@statewalker/webrun-files-composite 0.7.1 → 0.8.1

package/dist/composite-files-api.d.ts

@@ -1,16 +1,62 @@
 import type { FileInfo, FileStats, FilesApi, ListOptions, ReadOptions } from "@statewalker/webrun-files";
-import type { FileOperation } from "./types.js";
+/**
+ * Composite `FilesApi` that routes calls to one of several backends based
+ * on a path prefix. Mounts are matched by **longest prefix wins**, so a
+ * mount at `/a/b` takes precedence over a mount at `/a` for paths under
+ * `/a/b/...`. The mount point itself appears in listings as a synthetic
+ * directory and cannot be removed.
+ *
+ * Each backend can use a sub-directory of its own filesystem as the mount
+ * root via `fsPath` (constructor `rootPath` for the implicit root mount,
+ * `fsPath` argument for additional mounts). Cross-mount `move` is
+ * implemented as copy-then-delete; there is no atomicity guarantee.
+ *
+ * Access control and visibility filtering are intentionally **not** part of
+ * this class — wrap with {@link GuardedFilesApi} or {@link FilteredFilesApi}
+ * (or both) instead.
+ *
+ * @example
+ * ```ts
+ * const fs = new CompositeFilesApi(localFs, "/projects")
+ *   .mount("/docs", s3Fs, "/documentation")
+ *   .mount("/cache", memFs);
+ * await fs.write("/readme.md", data); // → localFs:/projects/readme.md
+ * await fs.write("/docs/api.md", data); // → s3Fs:/documentation/api.md
+ * ```
+ */
 export declare class CompositeFilesApi implements FilesApi {
     private mounts;
-    private guards;
+    /**
+     * @param root Default backend used for any path that does not match a
+     *   more specific mount. All paths are routed here unless `mount()`
+     *   intercepts them.
+     * @param rootPath Optional sub-directory of the root backend to use as
+     *   the composite filesystem's `/`. For example, `rootPath = "/projects"`
+     *   makes the composite path `/readme.md` resolve to `/projects/readme.md`
+     *   in the root backend. Defaults to `"/"` (no remapping).
+     */
     constructor(root: FilesApi, rootPath?: string);
+    /**
+     * Attaches a backend to handle every composite path under `path`. The
+     * mount prefix is normalized; paths under it are resolved against the
+     * mount's `fsPath` sub-directory (defaulting to `"/"`).
+     *
+     * @param path Composite-namespace prefix (e.g. `"/docs"`). Mounting at
+     *   `"/"` is forbidden — use the constructor `root` argument instead.
+     * @param api The backend `FilesApi` to delegate to for paths under
+     *   `path`. Wrap it in {@link FilteredFilesApi} / {@link GuardedFilesApi}
+     *   first if you want mount-local filtering or guards.
+     * @param fsPath Sub-directory of the mounted backend used as its mount
+     *   root, e.g. `mount("/docs", s3, "/documentation")` makes
+     *   `/docs/api.md` resolve to `/documentation/api.md` on `s3`.
+     * @returns `this`, for chaining.
+     * @throws If `path` normalizes to `"/"`.
+     */
     mount(path: string, api: FilesApi, fsPath?: string): this;
-    guard(operations: FileOperation[], check: (path: string) => boolean, message?: string): this;
     private resolve;
     private isMountPoint;
     /** Returns mount prefixes that are direct children of the given path. */
     private childMountPrefixes;
-    private checkGuard;
     read(path: string, options?: ReadOptions): AsyncIterable<Uint8Array>;
     write(path: string, content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>): Promise<void>;
     mkdir(path: string): Promise<void>;

package/dist/composite-files-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"composite-files-api.d.ts","sourceRoot":"","sources":["../src/composite-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAEnC,OAAO,KAAK,EAAa,aAAa,EAAE,MAAM,YAAY,CAAC;AAQ3D,qBAAa,iBAAkB,YAAW,QAAQ;IAChD,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,MAAM,CAAmB;gBAErB,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,MAAM;IAI7C,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAWzD,KAAK,CAAC,UAAU,EAAE,aAAa,EAAE,EAAE,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAO5F,OAAO,CAAC,OAAO;IAgBf,OAAO,CAAC,YAAY;IAKpB,yEAAyE;IACzE,OAAO,CAAC,kBAAkB;IAkB1B,OAAO,CAAC,UAAU;IAalB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC;IAM9D,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC;IAMV,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMjC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC;IA+CnE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IASnD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAStC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAUtC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAmBtD,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAiB5D,OAAO,CAAC,aAAa;YAOP,SAAS;IA4BvB,OAAO,CAAC,SAAS;IAejB,OAAO,CAAC,iBAAiB;CAQ1B"}
+{"version":3,"file":"composite-files-api.d.ts","sourceRoot":"","sources":["../src/composite-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AASnC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,iBAAkB,YAAW,QAAQ;IAChD,OAAO,CAAC,MAAM,CAAe;IAE7B;;;;;;;;OAQG;IACH,YAAY,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,MAAM,EAE5C;IAED;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CASxD;IAID,OAAO,CAAC,OAAO;IAgBf,OAAO,CAAC,YAAY;IAKpB,yEAAyE;IACzE,OAAO,CAAC,kBAAkB;IAkB1B,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC,CAGnE;IAEK,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC,CAGf;IAEK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGvC;IAEM,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC,CA4CxE;IAEK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAOxD;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO3C;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO3C;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAe3D;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAW3D;IAID,OAAO,CAAC,aAAa;YAOP,SAAS;IA4BvB,OAAO,CAAC,SAAS;IAejB,OAAO,CAAC,iBAAiB;CAQ1B"}

package/dist/cow-files-api.d.ts

@@ -0,0 +1,36 @@
+import type { FilesApi } from "@statewalker/webrun-files";
+/** Options for {@link cow}. */
+export interface CowOptions {
+    /**
+     * Filename prefix for per-path whiteout markers, stored in the writable
+     * layer. A whiteout for `/dir/name` lives at `/dir/<prefix>name`.
+     * Defaults to `".wh."`.
+     */
+    whiteoutPrefix?: string;
+    /**
+     * Filename for the opaque-directory marker, stored as a child of a
+     * directory whose base subtree has been deleted. Defaults to `".wh..opq"`.
+     */
+    opaqueName?: string;
+}
+/**
+ * Builds a copy-on-write `FilesApi`: a `writable` layer over a read-only
+ * `base`. Reads fall through to `base`; every write goes to `writable`;
+ * `base` is never mutated. Deletions are persisted as marker files in
+ * `writable` (a per-path whiteout for files, one opaque marker for a deleted
+ * base directory), so they survive over any backend and across restarts.
+ *
+ * @param base The read-only lower layer. Never mutated.
+ * @param writable The upper layer that captures all changes and markers.
+ * @param opts Marker naming overrides (see {@link CowOptions}).
+ * @returns A read/write `FilesApi` composing the two layers.
+ *
+ * @example
+ * ```ts
+ * const fs = cow(releaseFiles, new MemFilesApi());
+ * await fs.write("/a.txt", data); // captured in the writable layer
+ * await fs.remove("/base-only");  // whiteout marker; base untouched
+ * ```
+ */
+export declare function cow(base: FilesApi, writable: FilesApi, opts?: CowOptions): FilesApi;
+//# sourceMappingURL=cow-files-api.d.ts.map

package/dist/cow-files-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cow-files-api.d.ts","sourceRoot":"","sources":["../src/cow-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,QAAQ,EAGT,MAAM,2BAA2B,CAAC;AAGnC,+BAA+B;AAC/B,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAwMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,GAAG,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,QAAQ,CAEnF"}