@intellectual-frontiers/system 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +8 -2
- package/dist/compile.d.ts +94 -0
- package/dist/compile.js +130 -0
- package/dist/dirs.d.ts +19 -0
- package/dist/dirs.js +64 -0
- package/dist/discover.d.ts +43 -0
- package/dist/discover.js +118 -0
- package/dist/errors.d.ts +130 -0
- package/dist/errors.js +189 -0
- package/dist/fs.d.ts +263 -0
- package/dist/fs.js +826 -0
- package/dist/git.d.ts +63 -0
- package/dist/git.js +144 -0
- package/dist/job-plan.d.ts +207 -0
- package/dist/job-plan.js +563 -0
- package/dist/lock.d.ts +41 -0
- package/dist/lock.js +130 -0
- package/dist/mod.d.ts +28 -0
- package/dist/mod.js +29 -0
- package/dist/path.d.ts +47 -0
- package/dist/path.js +55 -0
- package/dist/proc.d.ts +257 -0
- package/dist/proc.js +589 -0
- package/dist/schedule.d.ts +99 -0
- package/dist/schedule.js +131 -0
- package/dist/stdio.d.ts +31 -0
- package/dist/stdio.js +170 -0
- package/dist/tty.d.ts +34 -0
- package/dist/tty.js +71 -0
- package/dist/watch.d.ts +42 -0
- package/dist/watch.js +342 -0
- package/package.json +113 -4
- package/src/compile.ts +178 -0
- package/src/dirs.ts +87 -0
- package/src/discover.ts +144 -0
- package/src/errors.ts +176 -0
- package/src/fs.ts +967 -0
- package/src/git.ts +163 -0
- package/src/job-plan.ts +660 -0
- package/src/lock.ts +149 -0
- package/src/mod.ts +29 -0
- package/src/path.ts +59 -0
- package/src/proc.ts +786 -0
- package/src/schedule.ts +173 -0
- package/src/stdio.ts +204 -0
- package/src/tty.ts +94 -0
- package/src/watch.ts +338 -0
package/src/watch.ts
ADDED
|
@@ -0,0 +1,338 @@
|
|
|
1
|
+
// Spec: 0001-system FR-016
|
|
2
|
+
/**
|
|
3
|
+
* Files and folders watched (commons 0005-typescript-runtime FR-051), on `node:fs`'s `watch` alone, so the same code runs on Bun and
|
|
4
|
+
* Node, on Linux, macOS and Windows. `watchFs` gives an async iterable of events (`create`, `modify`, `remove`,
|
|
5
|
+
* `rename` with both paths), stopped by `close`, an `AbortSignal`, `using` or leaving the loop.
|
|
6
|
+
*
|
|
7
|
+
* 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:
|
|
8
|
+
* 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
|
|
9
|
+
* 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`),
|
|
10
|
+
* 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
|
|
11
|
+
* 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.
|
|
12
|
+
*
|
|
13
|
+
* A folder is watched recursively with `recursive`, by the platform's own recursive watch where it has one, and otherwise by one watch for
|
|
14
|
+
* 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
|
|
15
|
+
* reported too. A file is watched through its folder, so a save that replaces it keeps being seen.
|
|
16
|
+
*
|
|
17
|
+
* @example
|
|
18
|
+
* ```ts
|
|
19
|
+
* import { watchFs } from "./watch.ts";
|
|
20
|
+
* using watcher = watchFs("works", { recursive: true, debounceMs: 300 });
|
|
21
|
+
* for await (const e of watcher) console.log(e.kind, e.paths);
|
|
22
|
+
* ```
|
|
23
|
+
*
|
|
24
|
+
* @module
|
|
25
|
+
*/
|
|
26
|
+
import * as nfs from "node:fs";
|
|
27
|
+
import { dirname, isAbsolute, join, resolve, sep } from "node:path";
|
|
28
|
+
import { fileURLToPath } from "node:url";
|
|
29
|
+
import { hostCallSync, mapError } from "./errors.ts";
|
|
30
|
+
|
|
31
|
+
/** What happened to a path: made, changed, removed, or moved from the first path to the second. */
|
|
32
|
+
export type FsEventKind = "create" | "modify" | "remove" | "rename";
|
|
33
|
+
|
|
34
|
+
/** One event, after the join: a path made, changed or removed, or one moved (`paths` is then `[from, to]`). Paths are absolute. */
|
|
35
|
+
export type FsEvent =
|
|
36
|
+
| { readonly kind: "create" | "modify" | "remove"; readonly paths: readonly [string] }
|
|
37
|
+
| { readonly kind: "rename"; readonly paths: readonly [from: string, to: string] };
|
|
38
|
+
|
|
39
|
+
/** How to watch: folders with everything under them (`recursive`), the window over which reports are joined (`debounceMs`, 100), and a signal that stops it. */
|
|
40
|
+
export type WatchOptions = { readonly recursive?: boolean; readonly debounceMs?: number; readonly signal?: AbortSignal };
|
|
41
|
+
|
|
42
|
+
type Snap = {
|
|
43
|
+
readonly dir: boolean;
|
|
44
|
+
readonly dev: number;
|
|
45
|
+
readonly ino: number;
|
|
46
|
+
readonly size: number;
|
|
47
|
+
readonly mtimeMs: number;
|
|
48
|
+
readonly ctimeMs: number;
|
|
49
|
+
};
|
|
50
|
+
|
|
51
|
+
type Target = { readonly path: string; readonly real: string; readonly dir: boolean; readonly recursive: boolean };
|
|
52
|
+
|
|
53
|
+
const under = (path: string, root: string): boolean => path.startsWith(root.endsWith(sep) ? root : `${root}${sep}`);
|
|
54
|
+
|
|
55
|
+
function snapOf(path: string): Snap | undefined {
|
|
56
|
+
try {
|
|
57
|
+
const s = nfs.lstatSync(path);
|
|
58
|
+
return { dir: s.isDirectory(), dev: s.dev, ino: s.ino, size: s.size, mtimeMs: s.mtimeMs, ctimeMs: s.ctimeMs };
|
|
59
|
+
} catch {
|
|
60
|
+
return undefined;
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
function namesIn(dir: string): string[] {
|
|
65
|
+
try {
|
|
66
|
+
return nfs.readdirSync(dir);
|
|
67
|
+
} catch {
|
|
68
|
+
return [];
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
const changed = (a: Snap, b: Snap): boolean =>
|
|
73
|
+
a.dir !== b.dir || a.ino !== b.ino || a.size !== b.size || a.mtimeMs !== b.mtimeMs || a.ctimeMs !== b.ctimeMs;
|
|
74
|
+
|
|
75
|
+
const byPath = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
|
|
76
|
+
|
|
77
|
+
/**
|
|
78
|
+
* A running watch: an async iterable of {@link FsEvent}s, ended by `close`, the signal, `using`, `await using` or leaving a `for await`
|
|
79
|
+
* loop. A watch that fails (other than by its folder being removed) throws from the loop as an error of `./errors.ts`. Made by {@link watchFs}.
|
|
80
|
+
*/
|
|
81
|
+
export class FsWatcher implements AsyncIterableIterator<FsEvent>, Disposable, AsyncDisposable {
|
|
82
|
+
readonly #targets: readonly Target[];
|
|
83
|
+
readonly #debounceMs: number;
|
|
84
|
+
readonly #signal: AbortSignal | undefined;
|
|
85
|
+
readonly #known = new Map<string, Snap>();
|
|
86
|
+
readonly #pending = new Set<string>();
|
|
87
|
+
readonly #dirty = new Set<string>();
|
|
88
|
+
readonly #handles = new Map<string, nfs.FSWatcher>();
|
|
89
|
+
readonly #perFolder = new Set<string>();
|
|
90
|
+
readonly #queue: FsEvent[] = [];
|
|
91
|
+
readonly #waiting: { readonly resolve: (r: IteratorResult<FsEvent>) => void; readonly reject: (e: Error) => void }[] = [];
|
|
92
|
+
#error: Error | undefined;
|
|
93
|
+
#closed = false;
|
|
94
|
+
#timer: ReturnType<typeof setTimeout> | undefined;
|
|
95
|
+
#firstAt = 0;
|
|
96
|
+
readonly #onAbort = (): void => this.close();
|
|
97
|
+
|
|
98
|
+
/** A watch of the paths; use {@link watchFs}. */
|
|
99
|
+
constructor(paths: readonly string[], options: WatchOptions) {
|
|
100
|
+
this.#debounceMs = Math.max(0, options.debounceMs ?? 100);
|
|
101
|
+
this.#signal = options.signal;
|
|
102
|
+
this.#targets = paths.map((path) => {
|
|
103
|
+
const s = hostCallSync(path, () => nfs.statSync(path));
|
|
104
|
+
return { path, real: hostCallSync(path, () => nfs.realpathSync(path)), dir: s.isDirectory(), recursive: options.recursive === true };
|
|
105
|
+
});
|
|
106
|
+
for (const t of this.#targets) this.#scan(t.path, t.dir ? (t.recursive ? "all" : "children") : "self");
|
|
107
|
+
try {
|
|
108
|
+
for (const t of this.#targets) this.#start(t);
|
|
109
|
+
} catch (e) {
|
|
110
|
+
this.close();
|
|
111
|
+
throw mapError(e);
|
|
112
|
+
}
|
|
113
|
+
if (this.#signal?.aborted === true) this.close();
|
|
114
|
+
else this.#signal?.addEventListener("abort", this.#onAbort, { once: true });
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
#start(t: Target): void {
|
|
118
|
+
if (!t.dir) return this.#listen(dirname(t.path), false);
|
|
119
|
+
if (!t.recursive) return this.#listen(t.path, false);
|
|
120
|
+
try {
|
|
121
|
+
this.#listen(t.path, true);
|
|
122
|
+
} catch {
|
|
123
|
+
// No recursive watch on this platform and runtime (FR-018): one watch for each folder, kept up to date in #flush.
|
|
124
|
+
this.#perFolder.add(t.path);
|
|
125
|
+
for (const [path, s] of this.#known) if (s.dir && (path === t.path || under(path, t.path))) this.#listen(path, false);
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
#listen(dir: string, recursive: boolean): void {
|
|
130
|
+
if (this.#handles.has(dir)) return;
|
|
131
|
+
const w = nfs.watch(dir, { recursive, persistent: true }, (_type, name) => this.#raw(dir, name));
|
|
132
|
+
w.on("error", (e: unknown) => this.#failed(dir, e));
|
|
133
|
+
this.#handles.set(dir, w);
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
#unlisten(dir: string): void {
|
|
137
|
+
this.#handles.get(dir)?.close();
|
|
138
|
+
this.#handles.delete(dir);
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
#failed(dir: string, e: unknown): void {
|
|
142
|
+
this.#unlisten(dir);
|
|
143
|
+
if (snapOf(dir) === undefined) {
|
|
144
|
+
// The folder was removed (Windows reports it as an error): what was in it is removed, and the watch of it is over.
|
|
145
|
+
this.#dirty.add(dir);
|
|
146
|
+
this.#schedule();
|
|
147
|
+
return;
|
|
148
|
+
}
|
|
149
|
+
this.#error = mapError(e, dir);
|
|
150
|
+
for (const w of this.#waiting.splice(0)) w.reject(this.#error);
|
|
151
|
+
this.close();
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
/** A raw report: a name in a watched folder, or none (the folder is then read again). */
|
|
155
|
+
#raw(dir: string, name: string | null): void {
|
|
156
|
+
if (this.#closed) return;
|
|
157
|
+
if (name === null || name === "") this.#dirty.add(dir);
|
|
158
|
+
else if (isAbsolute(name)) this.#pending.add(this.#unreal(name));
|
|
159
|
+
else this.#pending.add(join(dir, name));
|
|
160
|
+
this.#schedule();
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
/** A path a platform gave absolute, by its real path (`/private/var` for `/var` on macOS), put back under the target's path. */
|
|
164
|
+
#unreal(path: string): string {
|
|
165
|
+
for (const t of this.#targets) {
|
|
166
|
+
if (path === t.real) return t.path;
|
|
167
|
+
if (under(path, t.real)) return join(t.path, path.slice(t.real.length));
|
|
168
|
+
}
|
|
169
|
+
return path;
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
#schedule(): void {
|
|
173
|
+
const now = Date.now();
|
|
174
|
+
if (this.#timer === undefined) this.#firstAt = now;
|
|
175
|
+
else clearTimeout(this.#timer);
|
|
176
|
+
// Reports that never stop are still flushed, at least once in ten windows (and once a second).
|
|
177
|
+
const late = now - this.#firstAt >= Math.max(1000, 10 * this.#debounceMs);
|
|
178
|
+
this.#timer = setTimeout(() => this.#flush(), late ? 0 : this.#debounceMs);
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
#inScope(path: string): boolean {
|
|
182
|
+
return this.#targets.some((t) =>
|
|
183
|
+
!t.dir ? path === t.path : path === t.path || (t.recursive ? under(path, t.path) : dirname(path) === t.path),
|
|
184
|
+
);
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
#deep(path: string): boolean {
|
|
188
|
+
return this.#targets.some((t) => t.dir && t.recursive && (path === t.path || under(path, t.path)));
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
/** What is at `path` now, recorded as known: the path itself, its children, or everything under it. */
|
|
192
|
+
#scan(path: string, how: "self" | "children" | "all"): void {
|
|
193
|
+
const s = snapOf(path);
|
|
194
|
+
if (s === undefined) return;
|
|
195
|
+
this.#known.set(path, s);
|
|
196
|
+
if (!s.dir || how === "self") return;
|
|
197
|
+
for (const name of namesIn(path)) {
|
|
198
|
+
const child = join(path, name);
|
|
199
|
+
if (how === "all") this.#scan(child, "all");
|
|
200
|
+
else {
|
|
201
|
+
const c = snapOf(child);
|
|
202
|
+
if (c !== undefined) this.#known.set(child, c);
|
|
203
|
+
}
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
/** Every path under `dir` as it is now. */
|
|
208
|
+
#present(dir: string, into: Set<string>): void {
|
|
209
|
+
for (const name of namesIn(dir)) {
|
|
210
|
+
const child = join(dir, name);
|
|
211
|
+
into.add(child);
|
|
212
|
+
if (snapOf(child)?.dir === true) this.#present(child, into);
|
|
213
|
+
}
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
#flush(): void {
|
|
217
|
+
this.#timer = undefined;
|
|
218
|
+
if (this.#closed) return;
|
|
219
|
+
const look = new Set(this.#pending);
|
|
220
|
+
this.#pending.clear();
|
|
221
|
+
for (const dir of this.#dirty) {
|
|
222
|
+
look.add(dir);
|
|
223
|
+
for (const k of this.#known.keys()) if (dirname(k) === dir) look.add(k);
|
|
224
|
+
for (const name of namesIn(dir)) look.add(join(dir, name));
|
|
225
|
+
}
|
|
226
|
+
this.#dirty.clear();
|
|
227
|
+
// A folder removed takes what was in it; a folder made (or moved in) brings what is in it now.
|
|
228
|
+
for (const path of [...look]) {
|
|
229
|
+
const before = this.#known.get(path);
|
|
230
|
+
const now = snapOf(path);
|
|
231
|
+
if (before?.dir === true && now?.dir !== true) for (const k of this.#known.keys()) if (under(k, path)) look.add(k);
|
|
232
|
+
if (now?.dir === true && before?.dir !== true && this.#deep(path)) this.#present(path, look);
|
|
233
|
+
}
|
|
234
|
+
const created: string[] = [];
|
|
235
|
+
const removed: { readonly path: string; readonly snap: Snap }[] = [];
|
|
236
|
+
const events: FsEvent[] = [];
|
|
237
|
+
for (const path of [...look].filter((x) => this.#inScope(x)).sort(byPath)) {
|
|
238
|
+
const before = this.#known.get(path);
|
|
239
|
+
const now = snapOf(path);
|
|
240
|
+
if (before === undefined && now === undefined) continue;
|
|
241
|
+
if (now === undefined) {
|
|
242
|
+
if (before !== undefined) removed.push({ path, snap: before });
|
|
243
|
+
this.#known.delete(path);
|
|
244
|
+
} else {
|
|
245
|
+
this.#known.set(path, now);
|
|
246
|
+
if (before === undefined) created.push(path);
|
|
247
|
+
else if (changed(before, now) && !(before.dir && now.dir)) events.push({ kind: "modify", paths: [path] });
|
|
248
|
+
}
|
|
249
|
+
}
|
|
250
|
+
// A path removed and one made with the same inode, in the same window, is a move; what was under a moved folder moved with it.
|
|
251
|
+
const moved = new Set<string>();
|
|
252
|
+
for (const r of removed) {
|
|
253
|
+
if (r.snap.ino === 0 || [...moved].some((m) => under(r.path, m))) continue;
|
|
254
|
+
const to = created.find((c) => !moved.has(c) && this.#known.get(c)?.ino === r.snap.ino && this.#known.get(c)?.dev === r.snap.dev);
|
|
255
|
+
if (to === undefined) continue;
|
|
256
|
+
moved.add(r.path).add(to);
|
|
257
|
+
events.push({ kind: "rename", paths: [r.path, to] });
|
|
258
|
+
}
|
|
259
|
+
const inMoved = (path: string): boolean => [...moved].some((m) => path === m || under(path, m));
|
|
260
|
+
for (const r of removed) if (!inMoved(r.path)) events.push({ kind: "remove", paths: [r.path] });
|
|
261
|
+
for (const c of created) if (!inMoved(c)) events.push({ kind: "create", paths: [c] });
|
|
262
|
+
// Per-folder watches follow the folders.
|
|
263
|
+
if (this.#perFolder.size > 0) {
|
|
264
|
+
for (const r of removed) if (this.#handles.has(r.path)) this.#unlisten(r.path);
|
|
265
|
+
for (const c of created) {
|
|
266
|
+
if (this.#known.get(c)?.dir === true && [...this.#perFolder].some((root) => under(c, root))) {
|
|
267
|
+
try {
|
|
268
|
+
this.#listen(c, false);
|
|
269
|
+
} catch {
|
|
270
|
+
// The folder went again before its watch began; the next report of its parent says so.
|
|
271
|
+
}
|
|
272
|
+
}
|
|
273
|
+
}
|
|
274
|
+
}
|
|
275
|
+
const first = (e: FsEvent): string => (e.kind === "rename" ? e.paths[1] : e.paths[0]);
|
|
276
|
+
events.sort((a, b) => byPath(first(a), first(b)));
|
|
277
|
+
for (const e of events) {
|
|
278
|
+
const w = this.#waiting.shift();
|
|
279
|
+
if (w === undefined) this.#queue.push(e);
|
|
280
|
+
else w.resolve({ value: e, done: false });
|
|
281
|
+
}
|
|
282
|
+
}
|
|
283
|
+
|
|
284
|
+
/** The next event, waiting for one; done once the watch is closed. */
|
|
285
|
+
next(): Promise<IteratorResult<FsEvent>> {
|
|
286
|
+
const e = this.#queue.shift();
|
|
287
|
+
if (e !== undefined) return Promise.resolve({ value: e, done: false });
|
|
288
|
+
if (this.#error !== undefined) return Promise.reject(this.#error);
|
|
289
|
+
if (this.#closed) return Promise.resolve({ value: undefined, done: true });
|
|
290
|
+
return new Promise((resolve, reject) => this.#waiting.push({ resolve, reject }));
|
|
291
|
+
}
|
|
292
|
+
|
|
293
|
+
/** The watch closed, as leaving a `for await` loop does. */
|
|
294
|
+
return(): Promise<IteratorResult<FsEvent>> {
|
|
295
|
+
this.close();
|
|
296
|
+
return Promise.resolve({ value: undefined, done: true });
|
|
297
|
+
}
|
|
298
|
+
|
|
299
|
+
/** The watch itself, to iterate. */
|
|
300
|
+
[Symbol.asyncIterator](): FsWatcher {
|
|
301
|
+
return this;
|
|
302
|
+
}
|
|
303
|
+
|
|
304
|
+
/** The watch stopped: no more events; a loop over it ends. Closing it again does nothing. */
|
|
305
|
+
close(): void {
|
|
306
|
+
if (this.#closed) return;
|
|
307
|
+
this.#closed = true;
|
|
308
|
+
if (this.#timer !== undefined) clearTimeout(this.#timer);
|
|
309
|
+
this.#timer = undefined;
|
|
310
|
+
this.#signal?.removeEventListener("abort", this.#onAbort);
|
|
311
|
+
for (const dir of [...this.#handles.keys()]) this.#unlisten(dir);
|
|
312
|
+
this.#queue.length = 0;
|
|
313
|
+
for (const w of this.#waiting.splice(0)) w.resolve({ value: undefined, done: true });
|
|
314
|
+
}
|
|
315
|
+
|
|
316
|
+
/** Closed at the end of a `using` block. */
|
|
317
|
+
[Symbol.dispose](): void {
|
|
318
|
+
this.close();
|
|
319
|
+
}
|
|
320
|
+
|
|
321
|
+
/** Closed at the end of an `await using` block. */
|
|
322
|
+
[Symbol.asyncDispose](): Promise<void> {
|
|
323
|
+
this.close();
|
|
324
|
+
return Promise.resolve();
|
|
325
|
+
}
|
|
326
|
+
}
|
|
327
|
+
|
|
328
|
+
/**
|
|
329
|
+
* Files and folders watched, (see the module's documentation): each path a file, or a folder whose entries
|
|
330
|
+
* (with `recursive`, everything under it) are watched. `NotFound` where a path is not there.
|
|
331
|
+
*/
|
|
332
|
+
export function watchFs(paths: string | URL | readonly (string | URL)[], options: WatchOptions = {}): FsWatcher {
|
|
333
|
+
const list = typeof paths === "string" || paths instanceof URL ? [paths] : paths;
|
|
334
|
+
return new FsWatcher(
|
|
335
|
+
list.map((x) => resolve(typeof x === "string" ? x : fileURLToPath(x))),
|
|
336
|
+
options,
|
|
337
|
+
);
|
|
338
|
+
}
|