@evolu/common 8.9.0 → 8.10.0

package/dist/src/Config.js

@@ -0,0 +1,181 @@
+/**
+ * Strict configuration Types with explicit application policy.
+ *
+ * Decode configuration at startup, then pass validated values to constructors
+ * or Tasks. The application decides how to load configuration, combine sources,
+ * and apply defaults. Declare defaults with {@link withDefault}, or use `??`
+ * where a value is consumed. Invalid supplied values still fail decoding.
+ *
+ * Resolve source precedence before replacing absence with defaults. If a source
+ * Type already provides defaults and later composition needs to distinguish
+ * them from supplied values, use `strategy: "preserve"` and inspect
+ * `defaultUsed` explicitly. Preserving this evidence does not choose a merging
+ * policy: the application still decides which source wins.
+ *
+ * {@link env} creates a pure, reversible codec. It does not read global state,
+ * load files, merge sources, or introduce a Run dependency. Tests can pass
+ * ordinary objects; a Node.js entry point can pass `process.env`.
+ *
+ * @module
+ */
+import { assert } from "./Assert.js";
+import { createMutableRecord, filterObjectKeys, isPlainObject, } from "./Object.js";
+import { ok } from "./Result.js";
+import { CamelCaseIdentifier, camelCaseToConstantCase, ConstantCaseIdentifier, EvoluType, maxLength, object, objectKeys, String, transform, Unknown, } from "./Type.js";
+/**
+ * An environment variable name in Evolu's configuration convention.
+ *
+ * Names are {@link ConstantCaseIdentifier}s of at most 255 characters, including
+ * the application prefix. This is an Evolu convention, not an operating-system
+ * limit. Double underscores do not introduce nesting.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertErr, assertOk, EnvName } from "@evolu/common";
+ *
+ * assertOk(
+ *   EnvName.fromUnknown("APP_MAX_OWNER_BYTES"),
+ *   "APP_MAX_OWNER_BYTES",
+ * );
+ * assertErr(EnvName.fromUnknown("APP_maxOwnerBytes"));
+ * assertErr(EnvName.fromUnknown("APP_DB__PORT"));
+ * ```
+ */
+export const EnvName = /*#__PURE__*/ maxLength(255)(ConstantCaseIdentifier);
+/**
+ * Creates a reversible environment-variable codec with a flat decoded output.
+ *
+ * Declare camelCase fields directly, or put them in one-level CONSTANT_CASE
+ * namespace groups. A direct `port` field reads `PORT`; a `maxOwnerBytes` field
+ * in an `EVOLU_RELAY` group reads `EVOLU_RELAY_MAX_OWNER_BYTES`. Groups affect
+ * external names only. Duplicate decoded fields or encoded names are rejected
+ * during construction, even when their Types are identical.
+ *
+ * Selects exact declared unprefixed names and all keys within declared
+ * namespaces. Namespace selection ignores casing so incorrectly cased names
+ * fail validation instead of being ignored. Selected names must match their
+ * exact declared spelling. Unrelated variables are ignored; misspelled
+ * unprefixed names or namespace prefixes can therefore still look absent.
+ *
+ * Field Types must encode to strings. Optional fields may be absent, but
+ * explicit `undefined` values are rejected. Empty strings remain present and
+ * must satisfy the field Type. Compose {@link withDefault} to supply defaults.
+ * Encoding emits canonical external names and string values, preserving absence
+ * when the field codec does. Errors retain external names and nested paths.
+ *
+ * Reads own string properties from any non-null object, including
+ * `process.env`. Selected properties must be enumerable data properties;
+ * getters are never read. Prototypes and internal contents such as Map entries
+ * are ignored. Non-object inputs fail with standard object errors. Schema names
+ * must satisfy {@link EnvName}; groups cannot be nested. Loading and source
+ * precedence remain explicit application code.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertEqual,
+ *   assertErr,
+ *   assertOk,
+ *   assertType,
+ *   ByteSizeLiteral,
+ *   env,
+ *   optional,
+ *   Port,
+ *   PortFromString,
+ *   withDefault,
+ * } from "@evolu/common";
+ *
+ * const RelayEnv = env({
+ *   port: withDefault(optional(PortFromString), Port.orThrow(4000)),
+ *   EVOLU_RELAY: {
+ *     maxOwnerBytes: optional(ByteSizeLiteral),
+ *   },
+ * });
+ *
+ * const result = RelayEnv.fromUnknown({
+ *   PORT: "04000",
+ *   EVOLU_RELAY_MAX_OWNER_BYTES: "512KiB",
+ *   HOME: "/home/evolu",
+ * });
+ *
+ * assertOk(result, { port: 4000, maxOwnerBytes: "512KiB" });
+ * assertType<typeof result.value.port, Port>();
+ * assertEqual(RelayEnv.to(result.value), {
+ *   PORT: "4000",
+ *   EVOLU_RELAY_MAX_OWNER_BYTES: "512KiB",
+ * });
+ *
+ * assertOk(RelayEnv.fromUnknown({}), { port: 4000 });
+ * assertErr(RelayEnv.fromUnknown({ PORT: "" }));
+ * assertErr(RelayEnv.fromUnknown({ EVOLU_RELAY_MAX_OWENR_BYTES: "1MiB" }));
+ * assertErr(RelayEnv.fromUnknown({ evolu_relay_max_owner_bytes: "1MiB" }));
+ * ```
+ */
+export const env = (props, ..._validation) => {
+    assert(isPlainObject(props), "Environment properties must be a plain object.");
+    const flat = createMutableRecord();
+    const inputNameByOutputName = new Map();
+    const outputNameByInputName = new Map();
+    const prefixes = [];
+    const unprefixedNames = new Set();
+    for (const rootName of Reflect.ownKeys(props)) {
+        const descriptor = Object.getOwnPropertyDescriptor(props, rootName);
+        assert(typeof rootName === "string" &&
+            descriptor.enumerable &&
+            "value" in descriptor, "Environment properties must be enumerable string data properties.");
+        const grouped = ConstantCaseIdentifier.is(rootName);
+        assert(grouped || CamelCaseIdentifier.is(rootName), `Invalid environment schema name ${JSON.stringify(rootName)}. Expected a camelCase field or CONSTANT_CASE namespace.`);
+        const rootValue = descriptor.value;
+        const fields = grouped ? rootValue : { [rootName]: rootValue };
+        assert(isPlainObject(fields) && !EvoluType.is(fields), "Environment groups must be plain objects containing fields.");
+        if (grouped) {
+            assert(EnvName.is(rootName + "_A"), `Invalid environment namespace ${JSON.stringify(rootName)}. Names must fit within 255 characters.`);
+            prefixes.push(rootName + "_");
+        }
+        for (const name of Reflect.ownKeys(fields)) {
+            const field = Object.getOwnPropertyDescriptor(fields, name);
+            assert(typeof name === "string" && field.enumerable && "value" in field, "Environment fields must be enumerable string data properties.");
+            assert(CamelCaseIdentifier.is(name), `Invalid environment field ${JSON.stringify(name)}. Expected a camelCase identifier; groups cannot be nested.`);
+            assert(!inputNameByOutputName.has(name), `Duplicate environment field ${JSON.stringify(name)}.`);
+            const encoded = (grouped ? rootName + "_" : "") + camelCaseToConstantCase(name);
+            assert(EnvName.is(encoded), `Invalid environment schema name ${JSON.stringify(encoded)}. Expected a CONSTANT_CASE identifier of at most 255 characters.`);
+            assert(!outputNameByInputName.has(encoded), `Duplicate environment variable ${JSON.stringify(encoded)}.`);
+            const property = field.value;
+            const fieldType = EvoluType.is(property)
+                ? property
+                : isPlainObject(property)
+                    ? Object.getOwnPropertyDescriptor(property, "type")?.value
+                    : undefined;
+            assert(EvoluType.is(fieldType), `Invalid environment field ${JSON.stringify(name)}. Expected a Type or optional/defaulted property; groups must use CONSTANT_CASE names.`);
+            flat[name] = property;
+            inputNameByOutputName.set(name, encoded);
+            outputNameByInputName.set(encoded, name);
+            if (!grouped)
+                unprefixedNames.add(encoded);
+        }
+    }
+    // Runtime construction validates the flattened fields; the public signature
+    // checks their concrete Types and string encodings before flattening.
+    const output = object(flat);
+    const key = transform("EnvKey", String, CamelCaseIdentifier, {
+        // Identity fallback keeps this exposed codec round-trippable for other
+        // valid camelCase identifiers. objectKeys accepts only declared fields.
+        from: (value) => ok(outputNameByInputName.get(value) ?? value),
+        to: (value) => inputNameByOutputName.get(value) ?? value,
+    });
+    const withKeys = objectKeys(key)(output);
+    const type = transform("Env", Unknown, withKeys, {
+        from: (value) => {
+            if (typeof value !== "object" || value === null)
+                return ok(value);
+            return ok(filterObjectKeys(value, (key) => unprefixedNames.has(key) ||
+                prefixes.some((prefix) => key.toUpperCase().startsWith(prefix))));
+        },
+        to: (value) => value,
+    });
+    // The maps preserve each field's name and codec; only the static flattening
+    // cannot be expressed by the runtime loops above.
+    return type;
+};

package/dist/src/Fs.d.ts

@@ -0,0 +1,302 @@
+/**
+ * File system operations for {@link Task}s.
+ *
+ * {@link Fs} reads, writes, copies, and renames files; lists and manages
+ * directories; and provides metadata and existence checks. Each operation
+ * returns a Task.
+ *
+ * Tasks can sequence file operations without synchronous I/O. Node.js's
+ * synchronous methods are intentionally omitted to avoid accidentally blocking
+ * the event loop.
+ *
+ * Inject {@link @evolu/nodejs!createNodeFs | createNodeFs} through
+ * {@link @evolu/nodejs!runMain | runMain} or {@link createRun}. Tasks declare
+ * {@link FsDep} and access the file system through `run.deps.fs`.
+ *
+ * {@link FsError} includes the path, a diagnostic message, and a
+ * {@link FsErrorReason} such as `NotFound` or `PermissionDenied`.
+ * {@link Fs.exists} returns `false` for `NotFound` and preserves other errors.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertEqual,
+ *   ok,
+ *   type FsDep,
+ *   type FsError,
+ *   type Task,
+ * } from "@evolu/common";
+ * import { createNodeFs, runMain } from "@evolu/nodejs";
+ * import { join } from "node:path";
+ *
+ * const main: Task<void, FsError, FsDep> = async (run) => {
+ *   const { fs } = run.deps;
+ *   const temp = await run(
+ *     fs.createTempDirectory({ prefix: "evolu-fs-" }),
+ *   );
+ *   if (!temp.ok) return temp;
+ *
+ *   await using directory = temp.value;
+ *   const path = join(directory.path, "message.txt");
+ *
+ *   const result = await run(fs.writeFile(path, "hello"));
+ *   if (!result.ok) return result;
+ *
+ *   const text = await run(fs.readFile(path, "utf8"));
+ *   if (!text.ok) return text;
+ *   assertEqual(text.value, "hello");
+ *
+ *   return ok();
+ * };
+ *
+ * await runMain({ fs: createNodeFs() }, { mode: "command" })(main);
+ * ```
+ *
+ * @module
+ */
+import type { ByteLength } from "./Bytes.ts";
+import type { Task } from "./Task.ts";
+import type { Typed } from "./Type.ts";
+/** Asynchronous file system operations. */
+export interface Fs {
+    /**
+     * Reads a whole file, as bytes by default or as a string with an encoding. An
+     * abort requests cancellation; pending operating system reads may still
+     * finish.
+     */
+    readonly readFile: FsReadFile;
+    /**
+     * Writes a file, creating it or truncating an existing file by default. An
+     * abort requests cancellation and can leave the file partially written or
+     * truncated.
+     */
+    readonly writeFile: (path: FsPath, data: string | Uint8Array, options?: FsWriteFileOptions) => Task<void, FsError>;
+    /**
+     * Lists entry names relative to `path`, in unspecified order. With
+     * `recursive`, includes nested entries with their relative paths.
+     */
+    readonly readDirectory: (path: FsPath, options?: FsReadDirectoryOptions) => Task<ReadonlyArray<string>, FsError>;
+    /**
+     * Creates a directory. Without `recursive`, an existing directory fails with
+     * `AlreadyExists` and a missing parent with `NotFound`.
+     */
+    readonly createDirectory: (path: FsPath, options?: FsCreateDirectoryOptions) => Task<void, FsError>;
+    /**
+     * Copies a file or directory tree using Node's recursive `cp` semantics. By
+     * default, existing directories are merged and files are replaced. Symbolic
+     * links follow Node's rules: `force: false` and `errorOnExist` do not
+     * guarantee that destination links are preserved.
+     *
+     * Copying is neither exclusive nor atomic, and a failure can leave a partial
+     * copy. Use {@link Fs.copyFile} for exclusive creation of a single file.
+     */
+    readonly copy: (source: FsPath, destination: FsPath, options?: FsCopyOptions) => Task<void, FsError>;
+    /**
+     * Copies a single file. An existing destination fails with `AlreadyExists`
+     * unless `overwrite` is enabled. Without overwrite, destination creation is
+     * exclusive even when other copies run concurrently. File contents are not
+     * published atomically; a failure can leave a partial copy.
+     */
+    readonly copyFile: (source: FsPath, destination: FsPath, options?: FsCopyFileOptions) => Task<void, FsError>;
+    /**
+     * Renames or moves a file or directory using the platform's rename semantics.
+     * An existing destination file can be replaced.
+     */
+    readonly rename: (source: FsPath, destination: FsPath) => Task<void, FsError>;
+    /**
+     * Removes a file, or a directory with `recursive`. Removing a directory
+     * without `recursive` fails with `IsDirectory`. With `force`, a missing path
+     * succeeds.
+     */
+    readonly remove: (path: FsPath, options?: FsRemoveOptions) => Task<void, FsError>;
+    /** Reads file metadata, following symbolic links. */
+    readonly getMetadata: (path: FsPath) => Task<FsMetadata, FsError>;
+    /**
+     * Checks whether a path exists. `NotFound` produces `false`; other errors are
+     * returned. A `true` result does not establish read or write permission.
+     */
+    readonly exists: (path: FsPath) => Task<boolean, FsError>;
+    /**
+     * Creates a unique directory in the system temporary directory by default.
+     * Options can specify a parent directory and a name prefix. The returned
+     * resource removes the directory and its contents on disposal. Use `await
+     * using` for cleanup; disposal can throw if removal fails.
+     *
+     * Once started, this operation returns its result even if its Run aborts.
+     */
+    readonly createTempDirectory: (options?: FsCreateTempDirectoryOptions) => Task<FsTempDirectory, FsError>;
+}
+/** Dependency wrapper for {@link Fs}. */
+export interface FsDep {
+    readonly fs: Fs;
+}
+/** A file system path, or a `file:` URL. */
+export type FsPath = string | URL;
+/** Supported text encodings. */
+export type FsEncoding = "ascii" | "utf8" | "utf-8" | "utf16le" | "utf-16le" | "ucs2" | "ucs-2" | "base64" | "base64url" | "latin1" | "binary" | "hex";
+/** Supported file opening modes for {@link Fs.writeFile}. */
+export type FsOpenFlag = "a" | "ax" | "a+" | "ax+" | "as" | "as+" | "r" | "r+" | "rs+" | "w" | "wx" | "w+" | "wx+";
+/** Reads bytes by default, or text when an encoding is specified. */
+export interface FsReadFile {
+    (path: FsPath): Task<Uint8Array, FsError>;
+    (path: FsPath, encoding: FsEncoding | {
+        readonly encoding: FsEncoding;
+    }): Task<string, FsError>;
+}
+/** Options for {@link Fs.writeFile}. */
+export interface FsWriteFileOptions {
+    /** Encoding of string data. Defaults to `utf8`. */
+    readonly encoding?: FsEncoding;
+    /** File mode of a created file. Defaults to `0o666`. */
+    readonly mode?: number;
+    /** Open flag. Defaults to `w`; use `wx` to fail when the file exists. */
+    readonly flag?: FsOpenFlag;
+}
+/** Options for {@link Fs.readDirectory}. */
+export interface FsReadDirectoryOptions {
+    /** Includes entries from nested directories. Defaults to `false`. */
+    readonly recursive?: boolean;
+}
+/** Options for {@link Fs.createDirectory}. */
+export interface FsCreateDirectoryOptions {
+    /** Creates missing parents and accepts an existing directory. */
+    readonly recursive?: boolean;
+    /** Directory mode. Defaults to `0o777`. */
+    readonly mode?: number;
+}
+/** Options for {@link Fs.copy}. */
+export interface FsCopyOptions {
+    /**
+     * Node's `force` option. Replaces existing files; `false` skips them unless
+     * `errorOnExist` is enabled. Defaults to `true`. This does not protect
+     * destination symbolic links.
+     */
+    readonly force?: boolean;
+    /**
+     * Node's `errorOnExist` option. With `force: false`, existing files and
+     * directories fail with `AlreadyExists`. Defaults to `false`. Symbolic links
+     * retain Node's behavior and may still be replaced.
+     */
+    readonly errorOnExist?: boolean;
+    /** Preserves access and modification times. Defaults to `false`. */
+    readonly preserveTimestamps?: boolean;
+}
+/** Options for {@link Fs.copyFile}. */
+export interface FsCopyFileOptions {
+    /** Replaces an existing destination file. Defaults to `false`. */
+    readonly overwrite?: boolean;
+}
+/** Options for {@link Fs.remove}. */
+export interface FsRemoveOptions {
+    /** Removes directories and their contents. */
+    readonly recursive?: boolean;
+    /** Ignores a missing path. */
+    readonly force?: boolean;
+    /**
+     * Number of retries for `EBUSY`, `EMFILE`, `ENFILE`, `ENOTEMPTY`, or `EPERM`
+     * on Node.js. Applies only with `recursive: true`. Defaults to `0`.
+     */
+    readonly maxRetries?: number;
+    /**
+     * Base retry delay in milliseconds. Each retry waits one additional interval.
+     * Applies only with `recursive: true`. Defaults to `100`.
+     */
+    readonly retryDelay?: number;
+}
+/** File metadata as data, with Node's numeric and timestamp field names. */
+export interface FsMetadata {
+    readonly type: FsEntryType;
+    readonly dev: number;
+    readonly ino: number;
+    readonly mode: number;
+    readonly nlink: number;
+    readonly uid: number;
+    readonly gid: number;
+    readonly rdev: number;
+    readonly size: ByteLength;
+    readonly blksize: number;
+    readonly blocks: number;
+    readonly atimeMs: number;
+    readonly mtimeMs: number;
+    readonly ctimeMs: number;
+    readonly birthtimeMs: number;
+    readonly atime: Date;
+    readonly mtime: Date;
+    readonly ctime: Date;
+    readonly birthtime: Date;
+}
+/** The kind of file system entry described by {@link FsMetadata}. */
+export type FsEntryType = "File" | "Directory" | "SymbolicLink" | "BlockDevice" | "CharacterDevice" | "FIFO" | "Socket" | "Unknown";
+/** Options for {@link Fs.createTempDirectory}. */
+export interface FsCreateTempDirectoryOptions {
+    /** Existing parent directory. Defaults to the system temporary directory. */
+    readonly directory?: string;
+    /** Prefix for the directory name. Defaults to an empty string. */
+    readonly prefix?: string;
+}
+/** A temporary directory removed, with its contents, on asynchronous disposal. */
+export interface FsTempDirectory extends AsyncDisposable {
+    readonly path: string;
+}
+/** A failed file system operation. */
+export interface FsError extends Typed<"FsError"> {
+    readonly reason: FsErrorReason;
+    /**
+     * The operation's path, or source for copying and renaming. URL inputs use
+     * their `href`. Temporary directories use the supplied parent if its
+     * resolution fails, or the resolved parent combined with the name prefix if
+     * creation fails.
+     */
+    readonly path: string;
+    /**
+     * Destination for copying and renaming, with URL inputs represented by
+     * `href`.
+     */
+    readonly destination?: string;
+    /** The failing system call, or the method name when the platform reports none. */
+    readonly syscall: string;
+    /** The platform's diagnostic message. */
+    readonly message: string;
+}
+/** Why a file system operation failed, mapped from the platform's error code. */
+export type FsErrorReason = "NotFound" | "AlreadyExists" | "PermissionDenied" | "IsDirectory" | "NotDirectory" | "NotEmpty" | "Busy" | "Unknown";
+/**
+ * Creates a test {@link Fs} with the supplied operation overrides.
+ *
+ * Unconfigured operations throw a defect naming the method when their Task
+ * runs. Constructing a Task does not execute it. This helper performs no file
+ * system I/O; overrides provide the behavior needed by each test.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertEqual,
+ *   assertOk,
+ *   ok,
+ *   testCreateFs,
+ *   testCreateRun,
+ *   type FsDep,
+ *   type FsError,
+ *   type Task,
+ * } from "@evolu/common";
+ *
+ * const saveMessage: Task<void, FsError, FsDep> = (run) =>
+ *   run(run.deps.fs.writeFile("message.txt", "hello"));
+ *
+ * await using run = testCreateRun({
+ *   fs: testCreateFs({
+ *     writeFile: (path, data) => () => {
+ *       assertEqual(path, "message.txt");
+ *       assertEqual(data, "hello");
+ *       return ok();
+ *     },
+ *   }),
+ * });
+ *
+ * assertOk(await run(saveMessage));
+ * ```
+ */
+export declare const testCreateFs: (overrides?: Partial<Fs>) => Fs;
+//# sourceMappingURL=Fs.d.ts.map

package/dist/src/Fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Fs.d.ts","sourceRoot":"","sources":["../../src/Fs.ts"],"names":[],"mappings":"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"}

package/dist/src/Fs.js

@@ -0,0 +1,111 @@
+/**
+ * File system operations for {@link Task}s.
+ *
+ * {@link Fs} reads, writes, copies, and renames files; lists and manages
+ * directories; and provides metadata and existence checks. Each operation
+ * returns a Task.
+ *
+ * Tasks can sequence file operations without synchronous I/O. Node.js's
+ * synchronous methods are intentionally omitted to avoid accidentally blocking
+ * the event loop.
+ *
+ * Inject {@link @evolu/nodejs!createNodeFs | createNodeFs} through
+ * {@link @evolu/nodejs!runMain | runMain} or {@link createRun}. Tasks declare
+ * {@link FsDep} and access the file system through `run.deps.fs`.
+ *
+ * {@link FsError} includes the path, a diagnostic message, and a
+ * {@link FsErrorReason} such as `NotFound` or `PermissionDenied`.
+ * {@link Fs.exists} returns `false` for `NotFound` and preserves other errors.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertEqual,
+ *   ok,
+ *   type FsDep,
+ *   type FsError,
+ *   type Task,
+ * } from "@evolu/common";
+ * import { createNodeFs, runMain } from "@evolu/nodejs";
+ * import { join } from "node:path";
+ *
+ * const main: Task<void, FsError, FsDep> = async (run) => {
+ *   const { fs } = run.deps;
+ *   const temp = await run(
+ *     fs.createTempDirectory({ prefix: "evolu-fs-" }),
+ *   );
+ *   if (!temp.ok) return temp;
+ *
+ *   await using directory = temp.value;
+ *   const path = join(directory.path, "message.txt");
+ *
+ *   const result = await run(fs.writeFile(path, "hello"));
+ *   if (!result.ok) return result;
+ *
+ *   const text = await run(fs.readFile(path, "utf8"));
+ *   if (!text.ok) return text;
+ *   assertEqual(text.value, "hello");
+ *
+ *   return ok();
+ * };
+ *
+ * await runMain({ fs: createNodeFs() }, { mode: "command" })(main);
+ * ```
+ *
+ * @module
+ */
+/**
+ * Creates a test {@link Fs} with the supplied operation overrides.
+ *
+ * Unconfigured operations throw a defect naming the method when their Task
+ * runs. Constructing a Task does not execute it. This helper performs no file
+ * system I/O; overrides provide the behavior needed by each test.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertEqual,
+ *   assertOk,
+ *   ok,
+ *   testCreateFs,
+ *   testCreateRun,
+ *   type FsDep,
+ *   type FsError,
+ *   type Task,
+ * } from "@evolu/common";
+ *
+ * const saveMessage: Task<void, FsError, FsDep> = (run) =>
+ *   run(run.deps.fs.writeFile("message.txt", "hello"));
+ *
+ * await using run = testCreateRun({
+ *   fs: testCreateFs({
+ *     writeFile: (path, data) => () => {
+ *       assertEqual(path, "message.txt");
+ *       assertEqual(data, "hello");
+ *       return ok();
+ *     },
+ *   }),
+ * });
+ *
+ * assertOk(await run(saveMessage));
+ * ```
+ */
+export const testCreateFs = (overrides = {}) => ({
+    readFile: createUnexpectedFsOperation("readFile"),
+    writeFile: createUnexpectedFsOperation("writeFile"),
+    readDirectory: createUnexpectedFsOperation("readDirectory"),
+    createDirectory: createUnexpectedFsOperation("createDirectory"),
+    copy: createUnexpectedFsOperation("copy"),
+    copyFile: createUnexpectedFsOperation("copyFile"),
+    rename: createUnexpectedFsOperation("rename"),
+    remove: createUnexpectedFsOperation("remove"),
+    getMetadata: createUnexpectedFsOperation("getMetadata"),
+    exists: createUnexpectedFsOperation("exists"),
+    createTempDirectory: createUnexpectedFsOperation("createTempDirectory"),
+    ...overrides,
+});
+const createUnexpectedFsOperation = (method) => () => () => {
+    throw new Error(`Unexpected Fs.${method} call`);
+};