IF Commons GitHub

watch

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-system FR-016

Files and folders watched (commons 0001-system FR-016), on node:fs's watch alone, so the same code runs on Bun and Node, on Linux, macOS and Windows. watchFs gives an async iterable of events (create, modify, remove, rename with both paths), stopped by close, an AbortSignal, using or leaving the loop.

What the platforms report differs (which of rename and change, how many, a name or none), so the raw reports only say where to look: they are joined over debounceMs, and then each path they name is compared with what the watcher last knew of it (kind, inode, size and times). One save is therefore one event, whether an editor writes the file in place or writes a new one and renames it over it (modify), a file created and removed within the window is no event, and a file moved within the watched tree is one rename where the platform gives inodes. A change that leaves the size and every time as they were (possible only on a file system with coarse times) is not seen.

A folder is watched recursively with recursive, by the platform's own recursive watch where it has one, and otherwise by one watch for each folder, kept as folders come and go (FR-018); a folder made inside it is read at once, so files made in it before its watch began are reported too. A file is watched through its folder, so a save that replaces it keeps being seen.

import { watchFs } from "./watch.ts";
using watcher = watchFs("works", { recursive: true, debounceMs: 300 });
for await (const e of watcher) console.log(e.kind, e.paths);

Source: commons/system/src/watch.ts

3 of 10 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

watchnamespace
namespace watch
watch.FsEventKindtypeno test imports it
type FsEventKind = "create" | "modify" | "remove" | "rename";

What happened to a path: made, changed, removed, or moved from the first path to the second.

watch.FsEventtypeno test imports it
type FsEvent =
  | { readonly kind: "create" | "modify" | "remove"; readonly paths: readonly [string] }
  | { readonly kind: "rename"; readonly paths: readonly [from: string, to: string] };

One event, after the join: a path made, changed or removed, or one moved (paths is then [from, to]). Paths are absolute.

watch.WatchOptionstypeno test imports it
type WatchOptions = { readonly recursive?: boolean; readonly debounceMs?: number; readonly signal?: AbortSignal };

How to watch: folders with everything under them (recursive), the window over which reports are joined (debounceMs, 100), and a signal that stops it.

watch.FsWatcherclassno test imports it
class FsWatcher implements AsyncIterableIterator<FsEvent>, Disposable, AsyncDisposable

A running watch: an async iterable of FsEvents, ended by close, the signal, using, await using or leaving a for await loop. A watch that fails (other than by its folder being removed) throws from the loop as an error of ./errors.ts. Made by watchFs.

MemberTypeWhat it is
next() => Promise<IteratorResult<FsEvent, any>>The next event, waiting for one; done once the watch is closed.
return() => Promise<IteratorResult<FsEvent, any>>The watch closed, as leaving a for await loop does.
__@asyncIterator@281474976747249() => FsWatcherThe watch itself, to iterate.
close() => voidThe watch stopped: no more events; a loop over it ends. Closing it again does nothing.
__@dispose@281474976713631() => voidClosed at the end of a using block.
__@asyncDispose@281474976747252() => Promise<void>Closed at the end of an await using block.
watch.watchFsfunctionno test imports it
function watchFs(paths: string | readonly (string | URL)[] | URL, options?: WatchOptions): FsWatcher

Files and folders watched, (see the module's documentation): each path a file, or a folder whose entries (with recursive, everything under it) are watched. NotFound where a path is not there.

FsEventKindtypeno test imports it
type FsEventKind = "create" | "modify" | "remove" | "rename";

What happened to a path: made, changed, removed, or moved from the first path to the second.

FsEventtype
type FsEvent =
  | { readonly kind: "create" | "modify" | "remove"; readonly paths: readonly [string] }
  | { readonly kind: "rename"; readonly paths: readonly [from: string, to: string] };

One event, after the join: a path made, changed or removed, or one moved (paths is then [from, to]). Paths are absolute.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

WatchOptionstypeno test imports it
type WatchOptions = { readonly recursive?: boolean; readonly debounceMs?: number; readonly signal?: AbortSignal };

How to watch: folders with everything under them (recursive), the window over which reports are joined (debounceMs, 100), and a signal that stops it.

FsWatcherclass
class FsWatcher implements AsyncIterableIterator<FsEvent>, Disposable, AsyncDisposable

A running watch: an async iterable of FsEvents, ended by close, the signal, using, await using or leaving a for await loop. A watch that fails (other than by its folder being removed) throws from the loop as an error of ./errors.ts. Made by watchFs.

MemberTypeWhat it is
next() => Promise<IteratorResult<FsEvent, any>>The next event, waiting for one; done once the watch is closed.
return() => Promise<IteratorResult<FsEvent, any>>The watch closed, as leaving a for await loop does.
__@asyncIterator@281474976747249() => FsWatcherThe watch itself, to iterate.
close() => voidThe watch stopped: no more events; a loop over it ends. Closing it again does nothing.
__@dispose@281474976713631() => voidClosed at the end of a using block.
__@asyncDispose@281474976747252() => Promise<void>Closed at the end of an await using block.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

watchFsfunction
function watchFs(paths: string | readonly (string | URL)[] | URL, options?: WatchOptions): FsWatcher

Files and folders watched, (see the module's documentation): each path a file, or a folder whose entries (with recursive, everything under it) are watched. NotFound where a path is not there.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.