@ny4n/durable 0.0.0-stage → 1.0.0

package/dist/env/index.js

@@ -0,0 +1,49 @@
+export function ok(value) {
+    return { ok: true, value };
+}
+export function err(error) {
+    return { ok: false, error };
+}
+export function getOrThrow(result) {
+    if (!result.ok)
+        throw result.error;
+    return result.value;
+}
+export function getOrUndefined(result) {
+    return result.ok ? result.value : undefined;
+}
+export function toError(error) {
+    if (error instanceof Error)
+        return error;
+    if (typeof error === "string")
+        return new Error(error);
+    try {
+        return new Error(JSON.stringify(error));
+    }
+    catch {
+        return new Error(String(error));
+    }
+}
+export class FileError extends Error {
+    code;
+    path;
+    constructor(code, message, path, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = "FileError";
+        this.code = code;
+        this.path = path;
+    }
+}
+export class ExecutionError extends Error {
+    code;
+    /** Spill file of a command that timed out or was aborted after its output crossed the spill thresholds. */
+    spillPath;
+    constructor(code, message, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = "ExecutionError";
+        this.code = code;
+    }
+}
+export { rangeDecoder, StreamDecoder, startsWithBom } from "./decode.js";
+export { LineScanner } from "./line-scan.js";
+//# sourceMappingURL=index.js.map

package/dist/env/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/env/index.ts"],"names":[],"mappings":"AAKA,MAAM,UAAU,EAAE,CAAiB,KAAa;IAC/C,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,GAAG,CAAiB,KAAa;IAChD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,UAAU,CAAiB,MAA8B;IACxE,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,MAAM,MAAM,CAAC,KAAK,CAAC;IACnC,OAAO,MAAM,CAAC,KAAK,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,cAAc,CAAgC,MAA8B;IAC3F,OAAO,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,KAAc;IACrC,IAAI,KAAK,YAAY,KAAK;QAAE,OAAO,KAAK,CAAC;IACzC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC;IACvD,IAAI,CAAC;QACJ,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACjC,CAAC;AACF,CAAC;AAcD,MAAM,OAAO,SAAU,SAAQ,KAAK;IAC5B,IAAI,CAAgB;IACpB,IAAI,CAAU;IAErB,YAAY,IAAmB,EAAE,OAAe,EAAE,IAAa,EAAE,KAAa;QAC7E,KAAK,CAAC,OAAO,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5D,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IAClB,CAAC;CACD;AAUD,MAAM,OAAO,cAAe,SAAQ,KAAK;IACjC,IAAI,CAAqB;IAChC,2GAA2G;IACpG,SAAS,CAAU;IAE1B,YAAY,IAAwB,EAAE,OAAe,EAAE,KAAa;QACnE,KAAK,CAAC,OAAO,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5D,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IAClB,CAAC;CACD;AA2PD,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC","sourcesContent":["import type { Context } from \"@ny4n/chord\";\n\n/** Result of a fallible operation. Expected failures are returned instead of thrown. */\nexport type Result<TValue, TError> = { ok: true; value: TValue } | { ok: false; error: TError };\n\nexport function ok<TValue, TError>(value: TValue): Result<TValue, TError> {\n\treturn { ok: true, value };\n}\n\nexport function err<TValue, TError>(error: TError): Result<TValue, TError> {\n\treturn { ok: false, error };\n}\n\nexport function getOrThrow<TValue, TError>(result: Result<TValue, TError>): TValue {\n\tif (!result.ok) throw result.error;\n\treturn result.value;\n}\n\nexport function getOrUndefined<TValue extends object, TError>(result: Result<TValue, TError>): TValue | undefined {\n\treturn result.ok ? result.value : undefined;\n}\n\nexport function toError(error: unknown): Error {\n\tif (error instanceof Error) return error;\n\tif (typeof error === \"string\") return new Error(error);\n\ttry {\n\t\treturn new Error(JSON.stringify(error));\n\t} catch {\n\t\treturn new Error(String(error));\n\t}\n}\n\nexport type FileKind = \"file\" | \"directory\" | \"symlink\";\n\nexport type FileErrorCode =\n\t| \"aborted\"\n\t| \"not_found\"\n\t| \"permission_denied\"\n\t| \"not_directory\"\n\t| \"is_directory\"\n\t| \"invalid\"\n\t| \"not_supported\"\n\t| \"unknown\";\n\nexport class FileError extends Error {\n\tpublic code: FileErrorCode;\n\tpublic path?: string;\n\n\tconstructor(code: FileErrorCode, message: string, path?: string, cause?: Error) {\n\t\tsuper(message, cause === undefined ? undefined : { cause });\n\t\tthis.name = \"FileError\";\n\t\tthis.code = code;\n\t\tthis.path = path;\n\t}\n}\n\nexport type ExecutionErrorCode =\n\t| \"aborted\"\n\t| \"timeout\"\n\t| \"shell_unavailable\"\n\t| \"spawn_error\"\n\t| \"callback_error\"\n\t| \"unknown\";\n\nexport class ExecutionError extends Error {\n\tpublic code: ExecutionErrorCode;\n\t/** Spill file of a command that timed out or was aborted after its output crossed the spill thresholds. */\n\tpublic spillPath?: string;\n\n\tconstructor(code: ExecutionErrorCode, message: string, cause?: Error) {\n\t\tsuper(message, cause === undefined ? undefined : { cause });\n\t\tthis.name = \"ExecutionError\";\n\t\tthis.code = code;\n\t}\n}\n\nexport interface FileInfo {\n\tname: string;\n\tpath: string;\n\tkind: FileKind;\n\tsize: number;\n\tmtimeMs: number;\n}\n\nexport interface TextLine {\n\ttext: string;\n\tterminated: boolean;\n}\n\nexport interface TextLineReader {\n\treadLine(context: Context): Promise<Result<TextLine | undefined, FileError>>;\n\tclose(context: Context): Promise<void>;\n}\n\n/** Positional reads from one opened regular file; all calls see the same file even if its path is renamed. */\nexport interface BinaryReader {\n\t/** Metadata of the opened file, not of whatever its path names now. */\n\tinfo(context: Context): Promise<Result<FileInfo, FileError>>;\n\t/** Up to `length` bytes at `offset`; fewer only at end of file. */\n\tread(offset: number, length: number, context: Context): Promise<Result<Uint8Array, FileError>>;\n\t/**\n\t * One pass over the file that locates lines `[startLine, endLine)` (`endLine` absent: to the end), 0-based, where line\n\t * `k` starts after the `k`-th newline byte. Decoded sizes are those of the text `new TextDecoder().decode(file)` would\n\t * produce for that range, so a byte-order mark at the start of the file is not counted.\n\t */\n\tscanLines(options: { startLine: number; endLine?: number }, context: Context): Promise<Result<LineScan, FileError>>;\n\tclose(context: Context): Promise<void>;\n}\n\n/** A file or directory to watch. It may be missing; creating it is a change. */\nexport interface WatchTarget {\n\tpath: string;\n\t/** Watch everything below a directory, not only its entries. Symbolic links below it are not followed. */\n\trecursive?: boolean;\n\t/** Entries below `path` that are neither watched nor reported: names starting with `.`, or these names. */\n\texclude?: { hidden?: boolean; names?: readonly string[] };\n}\n\n/**\n * What changed:\n * - `paths`: something at or below each path may have changed (a directory path covers its whole subtree). Calls may be\n *   spurious; a change is never missed while the watcher is healthy.\n * - `overflow`: coverage was uncertain for a while (lost events, reconnect); rescan everything that is watched.\n * - `error`: the watcher stopped, for example because the watched tree grew past the environment's limit; no calls\n *   follow.\n */\nexport type WatchChange = { paths: string[] } | { overflow: true } | { error: FileError };\n\nexport interface FileWatcher {\n\t/**\n\t * `native`: changes are reported within about two seconds. `polling`: the environment compares snapshots, because\n\t * the file system does not report changes reliably (network and FUSE file systems); a change undone between two\n\t * snapshots can be missed.\n\t */\n\treadonly mode: \"native\" | \"polling\";\n\t/** Stop watching; no `onChange` call starts after this resolves. Idempotent. */\n\tclose(context: Context): Promise<void>;\n}\n\n/** Where lines of a file are, as `BinaryReader.scanLines` found them. */\nexport interface LineScan {\n\t/** Newline bytes in the whole file; it has `newlines + 1` lines. */\n\tnewlines: number;\n\t/**\n\t * Byte range of the selected lines: from the start of the first to the end of the last, without the newline that\n\t * ends it. A selection past the last line is empty at the end of the file.\n\t */\n\tstart: number;\n\tend: number;\n\t/** Where the first selected line ends: its newline, or the end of the file. */\n\tfirstLineEnd: number;\n\t/** Where the last selected line starts. */\n\tlastLineStart: number;\n\t/** UTF-8 byte length of the decoded selection and of its first line. */\n\tselectedBytes: number;\n\tfirstLineBytes: number;\n}\n\n/** Pages of one directory's entries. */\nexport interface DirReader {\n\t/**\n\t * Up to `maxEntries` entries in the order the file system returns them, continuing where the previous call stopped.\n\t * `done` marks the end; it may come with the last entries or with an empty page. An entry that disappears before its\n\t * metadata is read is skipped, as are entries of unsupported kinds. After a failed or aborted call, close the reader.\n\t */\n\tnext(maxEntries: number, context: Context): Promise<Result<{ entries: FileInfo[]; done: boolean }, FileError>>;\n\tclose(context: Context): Promise<void>;\n}\n\n/** Portable filesystem capability. Operations return failures rather than throwing. */\nexport interface FileSystem {\n\t/**\n\t * The file namespace: equal ids see the same files at the same paths, whatever their `cwd`. Every local Node\n\t * environment shares one id; each container or remote host has its own.\n\t */\n\treadonly id: string;\n\tcwd: string;\n\tabsolutePath(path: string, context: Context): Promise<Result<string, FileError>>;\n\tjoinPath(parts: string[], context: Context): Promise<Result<string, FileError>>;\n\treadTextFile(path: string, context: Context): Promise<Result<string, FileError>>;\n\topenTextLineReader(path: string, context: Context): Promise<Result<TextLineReader, FileError>>;\n\treadTextLines(\n\t\tpath: string,\n\t\toptions: { maxLines?: number } | undefined,\n\t\tcontext: Context,\n\t): Promise<Result<string[], FileError>>;\n\treadBinaryFile(path: string, context: Context): Promise<Result<Uint8Array, FileError>>;\n\t/**\n\t * Open a regular file for bounded positional reads. A directory fails with `is_directory`, other non-regular files\n\t * with `invalid`. With `noFollow`, a symbolic link as the final path component fails with `invalid` instead of being\n\t * followed; earlier components are still resolved.\n\t */\n\topenBinaryReader(\n\t\tpath: string,\n\t\toptions: { noFollow?: boolean } | undefined,\n\t\tcontext: Context,\n\t): Promise<Result<BinaryReader, FileError>>;\n\twriteFile(path: string, content: string | Uint8Array, context: Context): Promise<Result<void, FileError>>;\n\tappendFile(path: string, content: string | Uint8Array, context: Context): Promise<Result<void, FileError>>;\n\t/** Truncate or extend a file to exactly `size` bytes. */\n\ttruncateFile(path: string, size: number, context: Context): Promise<Result<void, FileError>>;\n\t/** Flush file contents and metadata needed to retrieve them from an open file handle. */\n\tflushFile(path: string, context: Context): Promise<Result<void, FileError>>;\n\trenameFile(sourcePath: string, destinationPath: string, context: Context): Promise<Result<void, FileError>>;\n\tfileInfo(path: string, context: Context): Promise<Result<FileInfo, FileError>>;\n\tlistDir(path: string, context: Context): Promise<Result<FileInfo[], FileError>>;\n\topenDirReader(path: string, context: Context): Promise<Result<DirReader, FileError>>;\n\t/**\n\t * Report changes to files and directories, for hosts that load resources from the environment. When the returned\n\t * watcher exists, coverage is established: a host that watches before it loads cannot miss a change made during the\n\t * load. See `WatchChange` for what is reported and `FileWatcher.mode` for how reliably.\n\t */\n\twatch(\n\t\ttargets: readonly WatchTarget[],\n\t\tonChange: (change: WatchChange) => void,\n\t\tcontext: Context,\n\t): Promise<Result<FileWatcher, FileError>>;\n\tcanonicalPath(path: string, context: Context): Promise<Result<string, FileError>>;\n\texists(path: string, context: Context): Promise<Result<boolean, FileError>>;\n\tcreateDir(\n\t\tpath: string,\n\t\toptions: { recursive?: boolean } | undefined,\n\t\tcontext: Context,\n\t): Promise<Result<void, FileError>>;\n\tremove(\n\t\tpath: string,\n\t\toptions: { recursive?: boolean; force?: boolean } | undefined,\n\t\tcontext: Context,\n\t): Promise<Result<void, FileError>>;\n\tcreateTempDir(prefix: string | undefined, context: Context): Promise<Result<string, FileError>>;\n\tcreateTempFile(\n\t\toptions: { prefix?: string; suffix?: string } | undefined,\n\t\tcontext: Context,\n\t): Promise<Result<string, FileError>>;\n\tcleanup(context: Context): Promise<void>;\n}\n\n/** Spill the complete output to a temporary file once it exceeds either threshold. */\nexport interface ShellSpillOptions {\n\tafterBytes: number;\n\t/** Complete or partial lines. */\n\tafterLines: number;\n}\n\nexport interface ShellExecResult {\n\texitCode: number;\n\t/** Temporary file holding the complete raw output, when the spill thresholds were exceeded. */\n\tspillPath?: string;\n}\n\nexport interface ShellExecOptions {\n\tcwd?: string;\n\tenv?: Record<string, string>;\n\tinheritEnv?: boolean;\n\ttimeout?: number;\n\t/**\n\t * Every decoded chunk of stdout and stderr as it arrives, in arrival order, with the stream it came from: raw,\n\t * unbounded, and unthrottled. Each stream is decoded separately, so a character split across chunks survives.\n\t */\n\tonOutput?: (text: string, context: Context, info: ShellOutputInfo) => void;\n\tspill?: ShellSpillOptions;\n\t/**\n\t * The caller keeps only this tail of the output, so the environment may omit output outside it and report the omission\n\t * as `info.skipped`. Without it, every chunk is delivered.\n\t */\n\twindow?: ShellOutputWindow;\n}\n\n/**\n * The tail of the combined output a caller keeps, and how often it samples it. An environment that transfers output\n * over a slow link uses it to omit what the caller would drop anyway and to send no faster than the caller commits.\n */\nexport interface ShellOutputWindow {\n\t/** UTF-8 bytes of decoded text kept at the end of the output. */\n\tmaxBytes: number;\n\t/** Lines kept at the end of the output. */\n\tmaxLines: number;\n\t/** Minimum pause between the caller's samples of the output. */\n\tminIntervalMs: number;\n\t/** Each sample also pauses the caller in proportion to its size at this rate. */\n\tbytesPerSecond: number;\n}\n\n/**\n * Output an environment omitted, measured on the decoded text `onOutput` would have received: every U+FFFD counts as\n * three bytes, and no sanitizing is applied.\n */\nexport interface ShellOutputSkip {\n\t/** UTF-8 byte length of the omitted text. */\n\tbytes: number;\n\t/** Newlines (U+000A) in the omitted text. */\n\tnewlines: number;\n\t/** Whether the omitted text ends with a newline. */\n\tendsWithNewline: boolean;\n}\n\nexport interface ShellOutputInfo {\n\tstream: \"stdout\" | \"stderr\";\n\t/**\n\t * Output omitted immediately before this chunk, only with `window`. The chunk then holds all output after the\n\t * omission up to its end, and that is more than the window by at least one byte or one line: more than\n\t * `window.maxBytes` bytes or more than `window.maxLines` newlines. So the omitted text can never be in the kept tail.\n\t * The omission and such a chunk may span both streams in arrival order; `stream` then names the chunk's last stream.\n\t * Callers that need the streams apart do not pass `window`.\n\t */\n\tskipped?: ShellOutputSkip;\n}\n\nexport interface Shell {\n\t/**\n\t * Run a command. A string runs through the environment's shell. An array runs `command[0]` directly with the rest\n\t * as its arguments, without a shell, so they reach the program unparsed. Aborting the context or a timeout kills\n\t * only this command's processes.\n\t */\n\texec(\n\t\tcommand: string | readonly string[],\n\t\toptions: ShellExecOptions | undefined,\n\t\tcontext: Context,\n\t): Promise<Result<ShellExecResult, ExecutionError>>;\n\t/** Kill every command this environment still runs; for its owner's shutdown, never for one request. */\n\tcleanup(context: Context): Promise<void>;\n}\n\nexport interface ExecutionEnv extends FileSystem, Shell {}\n\nexport { rangeDecoder, StreamDecoder, startsWithBom } from \"./decode.ts\";\nexport { LineScanner } from \"./line-scan.ts\";\n"]}

package/dist/env/line-scan.d.ts

@@ -0,0 +1,13 @@
+import type { LineScan } from "./index.ts";
+/**
+ * Computes a `LineScan` from a file's bytes fed in order, so an environment can scan any size in bounded memory. Decoded
+ * sizes use the same streaming WHATWG decoder as decoding the whole file at once.
+ */
+export declare class LineScanner {
+    #private;
+    /** `startLine` and `endLine` must be non-negative integers with `endLine > startLine`; `endLine` absent: to the end. */
+    constructor(startLine: number, endLine?: number);
+    push(chunk: Uint8Array): void;
+    finish(): LineScan;
+}
+//# sourceMappingURL=line-scan.d.ts.map

package/dist/env/line-scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"line-scan.d.ts","sourceRoot":"","sources":["../../src/env/line-scan.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAU3C;;;GAGG;AACH,qBAAa,WAAW;;IAkBvB,wHAAwH;IACxH,YAAY,SAAS,EAAE,MAAM,EAAE,OAAO,SAA2B,EAShE;IAED,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAS5B;IA8BD,MAAM,IAAI,QAAQ,CA0BjB;CAkCD"}

package/dist/env/line-scan.js

@@ -0,0 +1,147 @@
+import { rangeDecoder, startsWithBom } from "./decode.js";
+const NEWLINE = 0x0a;
+const encoder = new TextEncoder();
+/** UTF-8 byte length of decoded text. */
+function decodedBytes(text) {
+    return text === "" ? 0 : encoder.encode(text).length;
+}
+/**
+ * Computes a `LineScan` from a file's bytes fed in order, so an environment can scan any size in bounded memory. Decoded
+ * sizes use the same streaming WHATWG decoder as decoding the whole file at once.
+ */
+export class LineScanner {
+    #startLine;
+    #endLine;
+    #position = 0;
+    #newlines = 0;
+    #lineStart = 0;
+    #start;
+    #end;
+    #firstLineEnd;
+    #lastLineStart;
+    #selectedBytes = 0;
+    #firstLineBytes = 0;
+    #selection;
+    #firstLine;
+    /** The first bytes, held until it is known whether they are a byte-order mark. */
+    #head = [];
+    #bom = false;
+    /** `startLine` and `endLine` must be non-negative integers with `endLine > startLine`; `endLine` absent: to the end. */
+    constructor(startLine, endLine = Number.POSITIVE_INFINITY) {
+        if (!Number.isSafeInteger(startLine) || startLine < 0 || !(endLine > startLine)) {
+            throw new RangeError("Invalid line range");
+        }
+        if (endLine !== Number.POSITIVE_INFINITY && !Number.isSafeInteger(endLine))
+            throw new RangeError("Invalid line range");
+        this.#startLine = startLine;
+        this.#endLine = endLine;
+        if (startLine === 0)
+            this.#begin(0);
+    }
+    push(chunk) {
+        if (this.#head !== undefined) {
+            const take = Math.min(3 - this.#head.length, chunk.length);
+            this.#head.push(...chunk.subarray(0, take));
+            if (this.#head.length < 3)
+                return;
+            this.#releaseHead();
+            chunk = chunk.subarray(take);
+        }
+        this.#process(chunk);
+    }
+    #releaseHead() {
+        const head = Uint8Array.from(this.#head ?? []);
+        this.#head = undefined;
+        this.#bom = startsWithBom(head);
+        this.#process(head);
+    }
+    #process(chunk) {
+        const base = this.#position;
+        let from = 0;
+        for (let index = chunk.indexOf(NEWLINE); index !== -1; index = chunk.indexOf(NEWLINE, index + 1)) {
+            // The newline ends line `this.#newlines`. It belongs to the selection between selected lines only.
+            this.#feed(chunk, base, from, index);
+            const line = this.#newlines;
+            const position = base + index;
+            if (line === this.#startLine)
+                this.#endFirstLine(position);
+            if (line === this.#endLine - 1)
+                this.#endSelection(position);
+            this.#feed(chunk, base, index, index + 1);
+            from = index + 1;
+            this.#newlines++;
+            this.#lineStart = position + 1;
+            if (this.#newlines === this.#startLine)
+                this.#begin(this.#lineStart);
+            if (this.#newlines === this.#endLine - 1)
+                this.#lastLineStart = this.#lineStart;
+        }
+        this.#feed(chunk, base, from, chunk.length);
+        this.#position += chunk.length;
+    }
+    finish() {
+        if (this.#head !== undefined)
+            this.#releaseHead();
+        const size = this.#position;
+        if (this.#start === undefined) {
+            return {
+                newlines: this.#newlines,
+                start: size,
+                end: size,
+                firstLineEnd: size,
+                lastLineStart: size,
+                selectedBytes: 0,
+                firstLineBytes: 0,
+            };
+        }
+        if (this.#firstLineEnd === undefined)
+            this.#endFirstLine(size);
+        if (this.#end === undefined)
+            this.#endSelection(size);
+        return {
+            newlines: this.#newlines,
+            start: this.#start,
+            end: this.#end ?? size,
+            firstLineEnd: this.#firstLineEnd ?? size,
+            // A selection that reaches past the last line ends with the last line.
+            lastLineStart: this.#lastLineStart ?? this.#lineStart,
+            selectedBytes: this.#selectedBytes,
+            firstLineBytes: this.#firstLineBytes,
+        };
+    }
+    #begin(start) {
+        this.#start = start;
+        if (this.#startLine === this.#endLine - 1)
+            this.#lastLineStart = start;
+        this.#selection = rangeDecoder();
+        this.#firstLine = rangeDecoder();
+    }
+    #endFirstLine(position) {
+        this.#firstLineEnd = position;
+        if (this.#firstLine !== undefined)
+            this.#firstLineBytes += decodedBytes(this.#firstLine.decode());
+        this.#firstLine = undefined;
+    }
+    #endSelection(position) {
+        this.#end = position;
+        if (this.#selection !== undefined)
+            this.#selectedBytes += decodedBytes(this.#selection.decode());
+        this.#selection = undefined;
+    }
+    /** Feed `chunk[from, to)`, which starts at file offset `base`, to the decoders of the ranges still open. */
+    #feed(chunk, base, from, to) {
+        // Decoding the whole file drops a leading byte-order mark.
+        if (this.#bom && base + from < 3)
+            from = Math.min(to, 3 - base);
+        if (to <= from)
+            return;
+        const bytes = chunk.subarray(from, to);
+        if (this.#selection !== undefined) {
+            this.#selectedBytes += decodedBytes(this.#selection.decode(bytes, { stream: true }));
+        }
+        if (this.#firstLine !== undefined) {
+            this.#firstLineBytes += decodedBytes(this.#firstLine.decode(bytes, { stream: true }));
+        }
+    }
+}
+//# sourceMappingURL=line-scan.js.map

package/dist/env/line-scan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"line-scan.js","sourceRoot":"","sources":["../../src/env/line-scan.ts"],"names":[],"mappings":"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","sourcesContent":["import { rangeDecoder, startsWithBom } from \"./decode.ts\";\nimport type { LineScan } from \"./index.ts\";\n\nconst NEWLINE = 0x0a;\nconst encoder = new TextEncoder();\n\n/** UTF-8 byte length of decoded text. */\nfunction decodedBytes(text: string): number {\n\treturn text === \"\" ? 0 : encoder.encode(text).length;\n}\n\n/**\n * Computes a `LineScan` from a file's bytes fed in order, so an environment can scan any size in bounded memory. Decoded\n * sizes use the same streaming WHATWG decoder as decoding the whole file at once.\n */\nexport class LineScanner {\n\treadonly #startLine: number;\n\treadonly #endLine: number;\n\t#position = 0;\n\t#newlines = 0;\n\t#lineStart = 0;\n\t#start: number | undefined;\n\t#end: number | undefined;\n\t#firstLineEnd: number | undefined;\n\t#lastLineStart: number | undefined;\n\t#selectedBytes = 0;\n\t#firstLineBytes = 0;\n\t#selection: InstanceType<typeof TextDecoder> | undefined;\n\t#firstLine: InstanceType<typeof TextDecoder> | undefined;\n\t/** The first bytes, held until it is known whether they are a byte-order mark. */\n\t#head: number[] | undefined = [];\n\t#bom = false;\n\n\t/** `startLine` and `endLine` must be non-negative integers with `endLine > startLine`; `endLine` absent: to the end. */\n\tconstructor(startLine: number, endLine = Number.POSITIVE_INFINITY) {\n\t\tif (!Number.isSafeInteger(startLine) || startLine < 0 || !(endLine > startLine)) {\n\t\t\tthrow new RangeError(\"Invalid line range\");\n\t\t}\n\t\tif (endLine !== Number.POSITIVE_INFINITY && !Number.isSafeInteger(endLine))\n\t\t\tthrow new RangeError(\"Invalid line range\");\n\t\tthis.#startLine = startLine;\n\t\tthis.#endLine = endLine;\n\t\tif (startLine === 0) this.#begin(0);\n\t}\n\n\tpush(chunk: Uint8Array): void {\n\t\tif (this.#head !== undefined) {\n\t\t\tconst take = Math.min(3 - this.#head.length, chunk.length);\n\t\t\tthis.#head.push(...chunk.subarray(0, take));\n\t\t\tif (this.#head.length < 3) return;\n\t\t\tthis.#releaseHead();\n\t\t\tchunk = chunk.subarray(take);\n\t\t}\n\t\tthis.#process(chunk);\n\t}\n\n\t#releaseHead(): void {\n\t\tconst head = Uint8Array.from(this.#head ?? []);\n\t\tthis.#head = undefined;\n\t\tthis.#bom = startsWithBom(head);\n\t\tthis.#process(head);\n\t}\n\n\t#process(chunk: Uint8Array): void {\n\t\tconst base = this.#position;\n\t\tlet from = 0;\n\t\tfor (let index = chunk.indexOf(NEWLINE); index !== -1; index = chunk.indexOf(NEWLINE, index + 1)) {\n\t\t\t// The newline ends line `this.#newlines`. It belongs to the selection between selected lines only.\n\t\t\tthis.#feed(chunk, base, from, index);\n\t\t\tconst line = this.#newlines;\n\t\t\tconst position = base + index;\n\t\t\tif (line === this.#startLine) this.#endFirstLine(position);\n\t\t\tif (line === this.#endLine - 1) this.#endSelection(position);\n\t\t\tthis.#feed(chunk, base, index, index + 1);\n\t\t\tfrom = index + 1;\n\t\t\tthis.#newlines++;\n\t\t\tthis.#lineStart = position + 1;\n\t\t\tif (this.#newlines === this.#startLine) this.#begin(this.#lineStart);\n\t\t\tif (this.#newlines === this.#endLine - 1) this.#lastLineStart = this.#lineStart;\n\t\t}\n\t\tthis.#feed(chunk, base, from, chunk.length);\n\t\tthis.#position += chunk.length;\n\t}\n\n\tfinish(): LineScan {\n\t\tif (this.#head !== undefined) this.#releaseHead();\n\t\tconst size = this.#position;\n\t\tif (this.#start === undefined) {\n\t\t\treturn {\n\t\t\t\tnewlines: this.#newlines,\n\t\t\t\tstart: size,\n\t\t\t\tend: size,\n\t\t\t\tfirstLineEnd: size,\n\t\t\t\tlastLineStart: size,\n\t\t\t\tselectedBytes: 0,\n\t\t\t\tfirstLineBytes: 0,\n\t\t\t};\n\t\t}\n\t\tif (this.#firstLineEnd === undefined) this.#endFirstLine(size);\n\t\tif (this.#end === undefined) this.#endSelection(size);\n\t\treturn {\n\t\t\tnewlines: this.#newlines,\n\t\t\tstart: this.#start,\n\t\t\tend: this.#end ?? size,\n\t\t\tfirstLineEnd: this.#firstLineEnd ?? size,\n\t\t\t// A selection that reaches past the last line ends with the last line.\n\t\t\tlastLineStart: this.#lastLineStart ?? this.#lineStart,\n\t\t\tselectedBytes: this.#selectedBytes,\n\t\t\tfirstLineBytes: this.#firstLineBytes,\n\t\t};\n\t}\n\n\t#begin(start: number): void {\n\t\tthis.#start = start;\n\t\tif (this.#startLine === this.#endLine - 1) this.#lastLineStart = start;\n\t\tthis.#selection = rangeDecoder();\n\t\tthis.#firstLine = rangeDecoder();\n\t}\n\n\t#endFirstLine(position: number): void {\n\t\tthis.#firstLineEnd = position;\n\t\tif (this.#firstLine !== undefined) this.#firstLineBytes += decodedBytes(this.#firstLine.decode());\n\t\tthis.#firstLine = undefined;\n\t}\n\n\t#endSelection(position: number): void {\n\t\tthis.#end = position;\n\t\tif (this.#selection !== undefined) this.#selectedBytes += decodedBytes(this.#selection.decode());\n\t\tthis.#selection = undefined;\n\t}\n\n\t/** Feed `chunk[from, to)`, which starts at file offset `base`, to the decoders of the ranges still open. */\n\t#feed(chunk: Uint8Array, base: number, from: number, to: number): void {\n\t\t// Decoding the whole file drops a leading byte-order mark.\n\t\tif (this.#bom && base + from < 3) from = Math.min(to, 3 - base);\n\t\tif (to <= from) return;\n\t\tconst bytes = chunk.subarray(from, to);\n\t\tif (this.#selection !== undefined) {\n\t\t\tthis.#selectedBytes += decodedBytes(this.#selection.decode(bytes, { stream: true }));\n\t\t}\n\t\tif (this.#firstLine !== undefined) {\n\t\t\tthis.#firstLineBytes += decodedBytes(this.#firstLine.decode(bytes, { stream: true }));\n\t\t}\n\t}\n}\n"]}

package/dist/env/node-watch.d.ts

@@ -0,0 +1,29 @@
+import type { Context } from "@ny4n/chord";
+import { type FileWatcher, type WatchChange, type WatchTarget } from "./index.ts";
+/** How `NodeExecutionEnv` watches. */
+export interface NodeWatchOptions {
+    /**
+     * Force a mode. By default `polling` is chosen on Windows, where native watchers keep directories open and so block
+     * renaming their parents, and for file systems that do not report remote changes.
+     */
+    mode?: "native" | "polling";
+    /** Interval between snapshots in `polling` mode; default 2000 ms. */
+    pollIntervalMs?: number;
+    /** Most directories one watcher covers; default 10,000. */
+    maxDirectories?: number;
+}
+/**
+ * Watches by snapshots: native events only trigger a debounced rescan, and changes are the difference between
+ * snapshots plus the event paths. A replaced file, a renamed or recreated ancestor, or a directory created with its
+ * contents therefore never depends on which events an operating system sends. New directories get their watchers
+ * before they are scanned again, so nothing written into them before the watcher existed is missed.
+ */
+export declare class NodeFileWatcher implements FileWatcher {
+    #private;
+    private constructor();
+    /** Establish coverage: watchers first, then the snapshot later changes are compared with. */
+    static open(targets: readonly WatchTarget[], resolvePath: (path: string) => string, onChange: (change: WatchChange) => void, options: NodeWatchOptions): Promise<NodeFileWatcher>;
+    get mode(): "native" | "polling";
+    close(_context: Context): Promise<void>;
+}
+//# sourceMappingURL=node-watch.d.ts.map

package/dist/env/node-watch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-watch.d.ts","sourceRoot":"","sources":["../../src/env/node-watch.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAa,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAE7F,sCAAsC;AACtC,MAAM,WAAW,gBAAgB;IAChC;;;OAGG;IACH,IAAI,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC5B,qEAAqE;IACrE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAkHD;;;;;GAKG;AACH,qBAAa,eAAgB,YAAW,WAAW;;IAelD,OAAO,eAWN;IAED,6FAA6F;IAC7F,OAAa,IAAI,CAChB,OAAO,EAAE,SAAS,WAAW,EAAE,EAC/B,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,EACrC,QAAQ,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,EACvC,OAAO,EAAE,gBAAgB,GACvB,OAAO,CAAC,eAAe,CAAC,CAwB1B;IAED,IAAI,IAAI,IAAI,QAAQ,GAAG,SAAS,CAE/B;IAEK,KAAK,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAI5C;CA6SD"}