@emdzej/csfs-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michał Jaskólski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+# @emdzej/csfs-core
+
+The contract every csfs backend implements, plus the pieces they all need:
+paths, two `CsFile` implementations, MIME lookup, and a tree walker.
+
+_Part of [csfs](https://github.com/emdzej/csfs) — a **c**lient **s**ide **f**ile **s**ystem: one read API over static HTTP, a picked directory,
+OPFS, and inside zip archives._
+
+You rarely install this alone — a backend package pulls it in. Install it
+directly when you are writing a backend, or when you want to accept "any csfs
+file system" as a parameter type.
+
+```ts
+import type { CsFileSystem } from "@emdzej/csfs-core";
+
+async function loadIndex(fs: CsFileSystem) {
+  const file = await fs.file("/pr/index.dat");
+  if (!file) return null; // absence is `null`, not a throw
+  return await file.slice(0, 4096).bytes(); // 4 KB, wherever it lives
+}
+```
+
+That function works unchanged against HTTP, a picked directory, OPFS, a zip
+archive, or `node:fs`.
+
+## The interface
+
+```ts
+interface CsFileSystem {
+  readonly kind: string; // "http", "fsa+zip", … — for diagnostics
+  file(path: string): Promise<CsFile | null>;
+  directory(path: string): Promise<CsDirectory | null>;
+  read(path: string): Promise<Uint8Array | null>;
+  stat(path: string): Promise<CsStat | null>;
+}
+```
+
+**A file is modelled on `Blob`** — `size`, `type`, `slice`, `bytes`,
+`arrayBuffer`, `stream`, `text`. Reading _part_ of a file is the operation that
+makes remote data usable: an archive is read from its end, a sorted index is
+binary-searched, a video is seeked. An interface whose only read is "give me the
+whole thing" forces a full download per lookup. Because `Blob` and `File`
+already have this shape, the local backends need no adapter at all.
+
+**Absence returns `null`.** Checking whether something exists needs no
+`try`/`catch`. Errors are for a caller asking something impossible, or a host
+misbehaving — which keeps the two apart at the call site.
+
+**Writing is a separate interface.** `WritableFileSystem` adds `write`,
+`makeDirectory`, and `remove`. Two of the backends cannot write; folding it into
+one interface would make every consumer check capabilities it never uses.
+
+## What is in here
+
+| Export                                                                               | Why                                                                                             |
+| ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
+| `BlobFile`                                                                           | a `CsFile` over anything `Blob`-shaped                                                          |
+| `RangeFile`                                                                          | a `CsFile` over a `(start, end) => Promise<Uint8Array>` reader; `slice` composes by arithmetic  |
+| `bytesFile`, `blobFile`, `toBlob`, `objectUrl`                                       | constructing files and getting a URL for an `<img>`                                             |
+| `parsePath`, `formatPath`, `normalizePath`                                           | `#` fragment addressing, and `..` resolved without escaping the root                            |
+| `dirname`, `basename`, `extname`, `joinPath`, `segments`                             | path arithmetic that does not import `node:path`                                                |
+| `mimeType`, `registerMimeType`                                                       | extension → type, so `file.type` is populated on backends that do not report one                |
+| `walk`, `walkFileSystem`, `resolveFile`, `resolveDirectory`, `statVia`               | depth-first iteration, and the shared implementations of "resolve a path one segment at a time" |
+| `NotDataError`, `RangeUnsupportedError`, `BackendError`, `UnsupportedOperationError` | the failures worth telling apart                                                                |
+
+`RangeFile` is the one to understand if you are writing a backend: give it a
+size and a range reader, and slicing is free — `slice(100, 200).slice(10, 20)`
+becomes a single read of bytes 110–120, with no request in between.
+
+## Paths
+
+Always `/`-rooted and `/`-separated, whatever the host uses. A `#` introduces a
+path _inside_ an archive, and nests:
+
+```ts
+parsePath("/a.zip#/b.zip#/deep.txt");
+// { base: "/a.zip", fragments: ["/b.zip", "/deep.txt"] }
+```
+
+`normalizePath` collapses `.` and `..` and cannot be walked above the root, so a
+path assembled from untrusted input stays inside the tree.
+
+## Licence
+
+**MIT** — see [LICENSE](https://github.com/emdzej/csfs/blob/main/LICENSE).

package/dist/errors.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Errors.
+ *
+ * Absence is *not* an error here: `file()` and `directory()` return `null`, so
+ * testing whether something exists needs no try/catch. These are for the cases
+ * where a caller asked for something impossible, or the store misbehaved —
+ * distinguishable types, because the two need opposite handling. "Not a data
+ * tree" means look somewhere else; "not found" is often expected.
+ */
+/** A backend cannot do what was asked — writing to HTTP, for instance. */
+export declare class UnsupportedOperationError extends Error {
+    constructor(operation: string, backend: string);
+}
+/** The store answered, but not with what was asked for. */
+export declare class BackendError extends Error {
+    readonly path?: string | undefined;
+    constructor(message: string, path?: string | undefined);
+}
+/**
+ * A remote host returned a web page where data was expected.
+ *
+ * Its own type because it needs the opposite handling from a 404: a 404 means
+ * *this file* is absent, which is normal, while HTML means the whole tree is
+ * somewhere else — a single-page app answers any unknown path with its own
+ * HTML and a 200, so a mistyped base URL otherwise looks like a working tree
+ * whose every file happens to be a document.
+ */
+export declare class NotDataError extends BackendError {
+    readonly url: string;
+    readonly contentType: string;
+    constructor(url: string, contentType: string);
+}
+/** A host that ignores `Range` would silently return the wrong bytes. */
+export declare class RangeUnsupportedError extends BackendError {
+    constructor(url: string, status: number);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,0EAA0E;AAC1E,qBAAa,yBAA0B,SAAQ,KAAK;gBACtC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAI/C;AAED,2DAA2D;AAC3D,qBAAa,YAAa,SAAQ,KAAK;IAGnC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM;gBADtB,OAAO,EAAE,MAAM,EACN,IAAI,CAAC,EAAE,MAAM,YAAA;CAKzB;AAED;;;;;;;;GAQG;AACH,qBAAa,YAAa,SAAQ,YAAY;IAE1C,QAAQ,CAAC,GAAG,EAAE,MAAM;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM;gBADnB,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM;CAK/B;AAED,yEAAyE;AACzE,qBAAa,qBAAsB,SAAQ,YAAY;gBACzC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAIxC"}

package/dist/errors.js

@@ -0,0 +1,52 @@
+/**
+ * Errors.
+ *
+ * Absence is *not* an error here: `file()` and `directory()` return `null`, so
+ * testing whether something exists needs no try/catch. These are for the cases
+ * where a caller asked for something impossible, or the store misbehaved —
+ * distinguishable types, because the two need opposite handling. "Not a data
+ * tree" means look somewhere else; "not found" is often expected.
+ */
+/** A backend cannot do what was asked — writing to HTTP, for instance. */
+export class UnsupportedOperationError extends Error {
+    constructor(operation, backend) {
+        super(`${backend} cannot ${operation}`);
+        this.name = "UnsupportedOperationError";
+    }
+}
+/** The store answered, but not with what was asked for. */
+export class BackendError extends Error {
+    path;
+    constructor(message, path) {
+        super(path ? `${path}: ${message}` : message);
+        this.path = path;
+        this.name = "BackendError";
+    }
+}
+/**
+ * A remote host returned a web page where data was expected.
+ *
+ * Its own type because it needs the opposite handling from a 404: a 404 means
+ * *this file* is absent, which is normal, while HTML means the whole tree is
+ * somewhere else — a single-page app answers any unknown path with its own
+ * HTML and a 200, so a mistyped base URL otherwise looks like a working tree
+ * whose every file happens to be a document.
+ */
+export class NotDataError extends BackendError {
+    url;
+    contentType;
+    constructor(url, contentType) {
+        super(`server returned ${contentType}, not data — is this really a data tree?`, url);
+        this.url = url;
+        this.contentType = contentType;
+        this.name = "NotDataError";
+    }
+}
+/** A host that ignores `Range` would silently return the wrong bytes. */
+export class RangeUnsupportedError extends BackendError {
+    constructor(url, status) {
+        super(`expected 206 for a Range request, got ${status} — the host ignores Range`, url);
+        this.name = "RangeUnsupportedError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,0EAA0E;AAC1E,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IAClD,YAAY,SAAiB,EAAE,OAAe;QAC5C,KAAK,CAAC,GAAG,OAAO,WAAW,SAAS,EAAE,CAAC,CAAC;QACxC,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;IAC1C,CAAC;CACF;AAED,2DAA2D;AAC3D,MAAM,OAAO,YAAa,SAAQ,KAAK;IAG1B;IAFX,YACE,OAAe,EACN,IAAa;QAEtB,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,OAAO,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;QAFrC,SAAI,GAAJ,IAAI,CAAS;QAGtB,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,OAAO,YAAa,SAAQ,YAAY;IAEjC;IACA;IAFX,YACW,GAAW,EACX,WAAmB;QAE5B,KAAK,CAAC,mBAAmB,WAAW,0CAA0C,EAAE,GAAG,CAAC,CAAC;QAH5E,QAAG,GAAH,GAAG,CAAQ;QACX,gBAAW,GAAX,WAAW,CAAQ;QAG5B,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAED,yEAAyE;AACzE,MAAM,OAAO,qBAAsB,SAAQ,YAAY;IACrD,YAAY,GAAW,EAAE,MAAc;QACrC,KAAK,CAAC,yCAAyC,MAAM,2BAA2B,EAAE,GAAG,CAAC,CAAC;QACvF,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF"}

package/dist/file.d.ts

@@ -0,0 +1,109 @@
+/**
+ * File implementations that every backend can share.
+ *
+ * `BlobFile` covers anything already `Blob`-shaped — a `File` from a picked
+ * directory, an OPFS file, a `Blob` built in memory — which is most of them.
+ * `RangeFile` covers the rest: a store that can answer "bytes m to n" but has
+ * no `Blob`, which is what HTTP is.
+ *
+ * Both exist so a backend supplies the one primitive it actually has and gets
+ * `slice`, `arrayBuffer`, `bytes`, `stream` and `text` for nothing.
+ */
+import type { CsFile } from "./types.js";
+/** Minimal `Blob` surface. `Blob` and `File` both satisfy it as they are. */
+export interface BlobLike {
+    readonly size: number;
+    readonly type?: string;
+    slice(start?: number, end?: number, contentType?: string): BlobLike;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    stream(): unknown;
+    text(): Promise<string>;
+}
+/** A `CsFile` over anything `Blob`-shaped. */
+export declare class BlobFile implements CsFile {
+    private readonly blob;
+    /** Overrides the blob's own type, which is often `""` from a file handle. */
+    private readonly mime?;
+    readonly path: string;
+    readonly name: string;
+    constructor(path: string, blob: BlobLike, 
+    /** Overrides the blob's own type, which is often `""` from a file handle. */
+    mime?: string | undefined);
+    get size(): number;
+    get type(): string;
+    slice(start?: number, end?: number): CsFile;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    bytes(): Promise<Uint8Array>;
+    stream(): ReadableStream<Uint8Array>;
+    text(): Promise<string>;
+}
+/**
+ * Reads a byte range. The one primitive a remote backend has to provide.
+ *
+ * `end` is exclusive. A backend may return fewer bytes than asked for only at
+ * the end of the file; anything else is a bug in the backend, not something
+ * callers should have to tolerate.
+ */
+export type RangeReader = (start: number, end: number) => Promise<Uint8Array>;
+/**
+ * A `CsFile` over a range reader — the HTTP case.
+ *
+ * Slicing composes by arithmetic rather than by fetching, so
+ * `file.slice(a, b).slice(c, d)` costs nothing until something is read. That
+ * matters for archives: a zip reader slices its way to a central directory
+ * through several layers before touching the network once.
+ */
+export declare class RangeFile implements CsFile {
+    private readonly total;
+    private readonly read;
+    private readonly mime;
+    /** Window into the underlying object: `[start, end)`. */
+    private readonly start;
+    private readonly end;
+    readonly path: string;
+    readonly name: string;
+    constructor(path: string, total: number, read: RangeReader, mime?: string, 
+    /** Window into the underlying object: `[start, end)`. */
+    start?: number, end?: number);
+    get size(): number;
+    get type(): string;
+    slice(start?: number, end?: number): CsFile;
+    bytes(): Promise<Uint8Array>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    stream(): ReadableStream<Uint8Array>;
+    text(): Promise<string>;
+}
+/** A `CsFile` over bytes already in memory. */
+export declare function bytesFile(path: string, data: Uint8Array, mime?: string): CsFile;
+/**
+ * A `CsFile` over a `Blob` or a `File`.
+ *
+ * The one-liner for the common case: a file the user picked, dropped, or chose
+ * with `<input type="file">`. The path defaults to the file's own name so a
+ * caller passing a `File` needs nothing else.
+ */
+export declare function blobFile(blob: BlobLike & {
+    name?: string;
+}, path?: string, mime?: string): CsFile;
+/**
+ * A `Blob` from bytes, with the type set.
+ *
+ * Here rather than in each caller because every consumer meets the same
+ * friction: TypeScript will not accept a `Uint8Array<ArrayBufferLike>` as a
+ * `BlobPart`, since the buffer *might* be a `SharedArrayBuffer`. It never is,
+ * for bytes that came out of a file, so the cast belongs at one boundary
+ * instead of being rediscovered at every call site.
+ *
+ * Setting the type matters: an `<img>` will sniff a typeless blob and cope,
+ * but an `<iframe>` handed a typeless PDF offers a download rather than
+ * rendering it.
+ */
+export declare function toBlob(bytes: Uint8Array, type?: string): Blob;
+/**
+ * An object URL for a file's contents.
+ *
+ * **The caller must revoke it.** A page that mints one per image and never
+ * revokes pins every image it has ever shown in memory.
+ */
+export declare function objectUrl(file: CsFile): Promise<string>;
+//# sourceMappingURL=file.d.ts.map

package/dist/file.d.ts.map

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

package/dist/file.js

@@ -0,0 +1,148 @@
+import { basename } from "./path.js";
+/** A `CsFile` over anything `Blob`-shaped. */
+export class BlobFile {
+    blob;
+    mime;
+    path;
+    name;
+    constructor(path, blob, 
+    /** Overrides the blob's own type, which is often `""` from a file handle. */
+    mime) {
+        this.blob = blob;
+        this.mime = mime;
+        this.path = path;
+        this.name = basename(path.split("#").at(-1) ?? path);
+    }
+    get size() {
+        return this.blob.size;
+    }
+    get type() {
+        return this.mime ?? this.blob.type ?? "";
+    }
+    slice(start, end) {
+        return new BlobFile(this.path, this.blob.slice(start, end), this.mime);
+    }
+    arrayBuffer() {
+        return this.blob.arrayBuffer();
+    }
+    async bytes() {
+        return new Uint8Array(await this.blob.arrayBuffer());
+    }
+    stream() {
+        return this.blob.stream();
+    }
+    text() {
+        return this.blob.text();
+    }
+}
+/**
+ * A `CsFile` over a range reader — the HTTP case.
+ *
+ * Slicing composes by arithmetic rather than by fetching, so
+ * `file.slice(a, b).slice(c, d)` costs nothing until something is read. That
+ * matters for archives: a zip reader slices its way to a central directory
+ * through several layers before touching the network once.
+ */
+export class RangeFile {
+    total;
+    read;
+    mime;
+    start;
+    end;
+    path;
+    name;
+    constructor(path, total, read, mime = "", 
+    /** Window into the underlying object: `[start, end)`. */
+    start = 0, end = total) {
+        this.total = total;
+        this.read = read;
+        this.mime = mime;
+        this.start = start;
+        this.end = end;
+        this.path = path;
+        this.name = basename(path.split("#").at(-1) ?? path);
+    }
+    get size() {
+        return Math.max(0, this.end - this.start);
+    }
+    get type() {
+        return this.mime;
+    }
+    slice(start = 0, end = this.size) {
+        // Clamp like `Blob.slice`: negative offsets count from the end, and
+        // over-long ranges truncate. A zip reader asking for the last 64 KB of a
+        // 20 KB file must get 20 KB rather than an error.
+        const size = this.size;
+        const from = start < 0 ? Math.max(0, size + start) : Math.min(start, size);
+        const to = end < 0 ? Math.max(0, size + end) : Math.min(end, size);
+        const lo = this.start + from;
+        const hi = this.start + Math.max(from, to);
+        return new RangeFile(this.path, this.total, this.read, this.mime, lo, hi);
+    }
+    async bytes() {
+        if (this.size === 0)
+            return new Uint8Array(0);
+        return await this.read(this.start, this.end);
+    }
+    async arrayBuffer() {
+        const bytes = await this.bytes();
+        // A fresh buffer: the view may be a window into a larger one, and handing
+        // that out would expose bytes the caller did not ask for.
+        return bytes.slice().buffer;
+    }
+    stream() {
+        // One chunk. A backend that can stream natively should override this by
+        // supplying its own `CsFile`; this is the correct-but-simple fallback.
+        const self = this;
+        return new ReadableStream({
+            async pull(controller) {
+                controller.enqueue(await self.bytes());
+                controller.close();
+            },
+        });
+    }
+    async text() {
+        return new TextDecoder().decode(await this.bytes());
+    }
+}
+/** A `CsFile` over bytes already in memory. */
+export function bytesFile(path, data, mime = "") {
+    return new RangeFile(path, data.byteLength, async (start, end) => data.subarray(start, end), mime);
+}
+/**
+ * A `CsFile` over a `Blob` or a `File`.
+ *
+ * The one-liner for the common case: a file the user picked, dropped, or chose
+ * with `<input type="file">`. The path defaults to the file's own name so a
+ * caller passing a `File` needs nothing else.
+ */
+export function blobFile(blob, path, mime) {
+    const resolved = path ?? `/${blob.name ?? "file"}`;
+    return new BlobFile(resolved, blob, mime);
+}
+/**
+ * A `Blob` from bytes, with the type set.
+ *
+ * Here rather than in each caller because every consumer meets the same
+ * friction: TypeScript will not accept a `Uint8Array<ArrayBufferLike>` as a
+ * `BlobPart`, since the buffer *might* be a `SharedArrayBuffer`. It never is,
+ * for bytes that came out of a file, so the cast belongs at one boundary
+ * instead of being rediscovered at every call site.
+ *
+ * Setting the type matters: an `<img>` will sniff a typeless blob and cope,
+ * but an `<iframe>` handed a typeless PDF offers a download rather than
+ * rendering it.
+ */
+export function toBlob(bytes, type = "application/octet-stream") {
+    return new Blob([bytes], { type });
+}
+/**
+ * An object URL for a file's contents.
+ *
+ * **The caller must revoke it.** A page that mints one per image and never
+ * revokes pins every image it has ever shown in memory.
+ */
+export async function objectUrl(file) {
+    return URL.createObjectURL(toBlob(await file.bytes(), file.type));
+}
+//# sourceMappingURL=file.js.map

package/dist/file.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./types.js";
+export * from "./path.js";
+export * from "./file.js";
+export * from "./mime.js";
+export * from "./errors.js";
+export * from "./walk.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from "./types.js";
+export * from "./path.js";
+export * from "./file.js";
+export * from "./mime.js";
+export * from "./errors.js";
+export * from "./walk.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC"}

package/dist/mime.d.ts

@@ -0,0 +1,5 @@
+/** The type for a path, or `"application/octet-stream"` when unknown. */
+export declare function mimeType(path: string): string;
+/** Register or override a type. For consumers with their own conventions. */
+export declare function registerMimeType(extension: string, type: string): void;
+//# sourceMappingURL=mime.d.ts.map

package/dist/mime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mime.d.ts","sourceRoot":"","sources":["../src/mime.ts"],"names":[],"mappings":"AA2CA,yEAAyE;AACzE,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAEtE"}

package/dist/mime.js

@@ -0,0 +1,50 @@
+/**
+ * MIME type by extension.
+ *
+ * Small and deliberate rather than a dependency: what a filesystem needs this
+ * for is handing a blob URL to an `<img>` or an `<iframe>`, and those care
+ * about a handful of types. An `<img>` will sniff a typeless blob and cope; an
+ * `<iframe>` handed a typeless PDF offers a download instead of rendering it,
+ * which is the failure this exists to prevent.
+ */
+const TYPES = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+    ".tif": "image/tiff",
+    ".tiff": "image/tiff",
+    ".bmp": "image/bmp",
+    ".ico": "image/x-icon",
+    ".pdf": "application/pdf",
+    ".json": "application/json",
+    ".xml": "application/xml",
+    ".html": "text/html",
+    ".htm": "text/html",
+    ".css": "text/css",
+    ".js": "text/javascript",
+    ".txt": "text/plain; charset=utf-8",
+    ".csv": "text/csv",
+    ".md": "text/markdown",
+    ".zip": "application/zip",
+    ".wasm": "application/wasm",
+    ".mp4": "video/mp4",
+    ".webm": "video/webm",
+    ".mp3": "audio/mpeg",
+    ".ogg": "audio/ogg",
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+    ".ttf": "font/ttf",
+};
+import { extname } from "./path.js";
+/** The type for a path, or `"application/octet-stream"` when unknown. */
+export function mimeType(path) {
+    return TYPES[extname(path)] ?? "application/octet-stream";
+}
+/** Register or override a type. For consumers with their own conventions. */
+export function registerMimeType(extension, type) {
+    TYPES[extension.toLowerCase()] = type;
+}
+//# sourceMappingURL=mime.js.map

package/dist/mime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mime.js","sourceRoot":"","sources":["../src/mime.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,KAAK,GAAqC;IAC9C,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,YAAY;IACpB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,WAAW;IACnB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,eAAe;IACvB,MAAM,EAAE,YAAY;IACpB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,cAAc;IACtB,MAAM,EAAE,iBAAiB;IACzB,OAAO,EAAE,kBAAkB;IAC3B,MAAM,EAAE,iBAAiB;IACzB,OAAO,EAAE,WAAW;IACpB,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,UAAU;IAClB,KAAK,EAAE,iBAAiB;IACxB,MAAM,EAAE,2BAA2B;IACnC,MAAM,EAAE,UAAU;IAClB,KAAK,EAAE,eAAe;IACtB,MAAM,EAAE,iBAAiB;IACzB,OAAO,EAAE,kBAAkB;IAC3B,MAAM,EAAE,WAAW;IACnB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,YAAY;IACpB,MAAM,EAAE,WAAW;IACnB,OAAO,EAAE,WAAW;IACpB,QAAQ,EAAE,YAAY;IACtB,MAAM,EAAE,UAAU;CACnB,CAAC;AAEF,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,yEAAyE;AACzE,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,0BAA0B,CAAC;AAC5D,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,gBAAgB,CAAC,SAAiB,EAAE,IAAY;IAC7D,KAAgC,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,GAAG,IAAI,CAAC;AACpE,CAAC"}

package/dist/path.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Paths, and the archive fragment.
+ *
+ * A csfs path is POSIX-style and rooted, with one extra piece of syntax: `#`
+ * separates a container from a path *inside* it.
+ *
+ *     /dessins/100.zip#/1132C000.png
+ *     /outer.zip#/inner.zip#/deep/file.txt
+ *
+ * `#` was chosen over a second argument or a `zip://` scheme because it keeps
+ * a location a single string. A path that survives being logged, stored in a
+ * manifest, put in a URL fragment or handed between a worker and a page is
+ * worth more than a tidier type — and every one of those places already
+ * accepts a string.
+ *
+ * Nesting is supported for the same reason: it costs one loop, and the
+ * alternative is a special case that someone eventually hits.
+ */
+/** A path split into its container chain and the final path inside it. */
+export interface ParsedPath {
+    /** The outermost path in the host filesystem. Never contains `#`. */
+    readonly base: string;
+    /**
+     * Paths inside each successive container, outermost first.
+     *
+     * Empty for an ordinary path. For `a.zip#/b.zip#/c.txt` this is
+     * `["/b.zip", "/c.txt"]` — note that the *second* element is inside the
+     * archive named by the first.
+     */
+    readonly fragments: readonly string[];
+}
+/**
+ * Normalise a path: single leading slash, no trailing slash, no `.` or `..`.
+ *
+ * `..` is resolved rather than rejected, and cannot escape the root — a path
+ * from a manifest or a URL is untrusted input, and `/a/../../etc` resolving to
+ * `/etc` inside someone's data directory is the whole reason to do this here
+ * rather than in each backend.
+ */
+export declare function normalizePath(path: string): string;
+/** Split a path on `#`, normalising each piece. */
+export declare function parsePath(path: string): ParsedPath;
+/** Rebuild a path from its pieces. The inverse of `parsePath`. */
+export declare function formatPath(parsed: ParsedPath): string;
+/** Everything before the last segment, or `"/"` at the root. */
+export declare function dirname(path: string): string;
+/** The last segment. `""` for the root. */
+export declare function basename(path: string): string;
+/** The extension including the dot, lower-cased, or `""`. */
+export declare function extname(path: string): string;
+/** Join segments into a normalised path. */
+export declare function joinPath(...parts: string[]): string;
+/** Split a normalised path into its segments, without empties. */
+export declare function segments(path: string): string[];
+//# sourceMappingURL=path.d.ts.map

package/dist/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,0EAA0E;AAC1E,MAAM,WAAW,UAAU;IACzB,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWlD;AAED,mDAAmD;AACnD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAKlD;AAED,kEAAkE;AAClE,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAErD;AAED,gEAAgE;AAChE,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI5C;AAED,2CAA2C;AAC3C,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG7C;AAED,6DAA6D;AAC7D,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI5C;AAED,4CAA4C;AAC5C,wBAAgB,QAAQ,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAEnD;AAED,kEAAkE;AAClE,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAE/C"}

package/dist/path.js

@@ -0,0 +1,76 @@
+/**
+ * Paths, and the archive fragment.
+ *
+ * A csfs path is POSIX-style and rooted, with one extra piece of syntax: `#`
+ * separates a container from a path *inside* it.
+ *
+ *     /dessins/100.zip#/1132C000.png
+ *     /outer.zip#/inner.zip#/deep/file.txt
+ *
+ * `#` was chosen over a second argument or a `zip://` scheme because it keeps
+ * a location a single string. A path that survives being logged, stored in a
+ * manifest, put in a URL fragment or handed between a worker and a page is
+ * worth more than a tidier type — and every one of those places already
+ * accepts a string.
+ *
+ * Nesting is supported for the same reason: it costs one loop, and the
+ * alternative is a special case that someone eventually hits.
+ */
+/**
+ * Normalise a path: single leading slash, no trailing slash, no `.` or `..`.
+ *
+ * `..` is resolved rather than rejected, and cannot escape the root — a path
+ * from a manifest or a URL is untrusted input, and `/a/../../etc` resolving to
+ * `/etc` inside someone's data directory is the whole reason to do this here
+ * rather than in each backend.
+ */
+export function normalizePath(path) {
+    const parts = [];
+    for (const segment of path.split("/")) {
+        if (segment === "" || segment === ".")
+            continue;
+        if (segment === "..") {
+            parts.pop();
+            continue;
+        }
+        parts.push(segment);
+    }
+    return `/${parts.join("/")}`;
+}
+/** Split a path on `#`, normalising each piece. */
+export function parsePath(path) {
+    const pieces = path.split("#");
+    const base = normalizePath(pieces[0] ?? "");
+    const fragments = pieces.slice(1).map((p) => normalizePath(p));
+    return { base, fragments };
+}
+/** Rebuild a path from its pieces. The inverse of `parsePath`. */
+export function formatPath(parsed) {
+    return [parsed.base, ...parsed.fragments].join("#");
+}
+/** Everything before the last segment, or `"/"` at the root. */
+export function dirname(path) {
+    const normalized = normalizePath(path);
+    const at = normalized.lastIndexOf("/");
+    return at <= 0 ? "/" : normalized.slice(0, at);
+}
+/** The last segment. `""` for the root. */
+export function basename(path) {
+    const normalized = normalizePath(path);
+    return normalized.slice(normalized.lastIndexOf("/") + 1);
+}
+/** The extension including the dot, lower-cased, or `""`. */
+export function extname(path) {
+    const name = basename(path);
+    const at = name.lastIndexOf(".");
+    return at <= 0 ? "" : name.slice(at).toLowerCase();
+}
+/** Join segments into a normalised path. */
+export function joinPath(...parts) {
+    return normalizePath(parts.join("/"));
+}
+/** Split a normalised path into its segments, without empties. */
+export function segments(path) {
+    return normalizePath(path).split("/").filter(Boolean);
+}
+//# sourceMappingURL=path.js.map

package/dist/path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.js","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAgBH;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACtC,IAAI,OAAO,KAAK,EAAE,IAAI,OAAO,KAAK,GAAG;YAAE,SAAS;QAChD,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACrB,KAAK,CAAC,GAAG,EAAE,CAAC;YACZ,SAAS;QACX,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACtB,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;AAC/B,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC/B,MAAM,IAAI,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAC5C,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/D,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AAC7B,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,UAAU,CAAC,MAAkB;IAC3C,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACtD,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,OAAO,CAAC,IAAY;IAClC,MAAM,UAAU,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IACvC,MAAM,EAAE,GAAG,UAAU,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACvC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACjD,CAAC;AAED,2CAA2C;AAC3C,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,MAAM,UAAU,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IACvC,OAAO,UAAU,CAAC,KAAK,CAAC,UAAU,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,OAAO,CAAC,IAAY;IAClC,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC5B,MAAM,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACjC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;AACrD,CAAC;AAED,4CAA4C;AAC5C,MAAM,UAAU,QAAQ,CAAC,GAAG,KAAe;IACzC,OAAO,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AACxC,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AACxD,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,133 @@
+/**
+ * The contract every backend implements.
+ *
+ * Two design decisions shape all of this, and both are worth stating because
+ * the obvious alternatives are worse.
+ *
+ * **A file is modelled on `Blob`, not on `readFile`.** `size`, `slice`,
+ * `arrayBuffer`, `stream`, `text` — the same five things a `Blob` gives you.
+ * That is not imitation for its own sake: reading *part* of a file is the
+ * operation that makes remote data usable at all. An archive is read from its
+ * end, a sorted index is binary-searched, a media file is seeked. An interface
+ * whose only read is "give me the whole thing" forces a download per lookup,
+ * and every backend then grows its own private range API. Because `Blob` and
+ * `File` already satisfy this shape, the local backends need no adapter at all.
+ *
+ * **Reads only.** Writing is a separate, optional interface
+ * (`WritableFileSystem`), because two of the three backends cannot write and a
+ * combined interface would make every consumer check capabilities it does not
+ * use. A read-only filesystem is the common case and should be the plain one.
+ */
+/** A file, or a slice of one. Deliberately `Blob`-shaped. */
+export interface CsFile {
+    /** Full path within its filesystem, including any archive fragment. */
+    readonly path: string;
+    /** Basename, in the case the backing store reports. */
+    readonly name: string;
+    readonly size: number;
+    /** MIME type when the backend knows one; `""` when it does not. */
+    readonly type: string;
+    /**
+     * A view of part of this file, without reading anything yet.
+     *
+     * `end` is exclusive, as in `Blob.slice`. Negative offsets and out-of-range
+     * values clamp rather than throw, again as `Blob.slice` does — a zip reader
+     * asking for the last 64 KB of a 20 KB file should get 20 KB, not an error.
+     */
+    slice(start?: number, end?: number): CsFile;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    bytes(): Promise<Uint8Array>;
+    stream(): ReadableStream<Uint8Array>;
+    text(): Promise<string>;
+}
+export type CsEntry = {
+    readonly kind: "file";
+    readonly name: string;
+    readonly size: number;
+} | {
+    readonly kind: "directory";
+    readonly name: string;
+};
+/** A directory listing. */
+export interface CsDirectory {
+    readonly path: string;
+    readonly name: string;
+    /** Direct children. */
+    entries(): Promise<CsEntry[]>;
+    /** A child file, or `null` if it is absent or is a directory. */
+    file(name: string): Promise<CsFile | null>;
+    /** A child directory, or `null` if it is absent or is a file. */
+    directory(name: string): Promise<CsDirectory | null>;
+}
+/**
+ * How names are matched.
+ *
+ * `"insensitive"` exists because real data sets are inconsistent about case —
+ * an index may say `MS43.IPO` where a reference says `ms43.ipo`. It is not the
+ * default, because it costs a full listing per lookup on backends that cannot
+ * index by name, and because two files differing only in case then become
+ * ambiguous.
+ */
+export type CaseSensitivity = "sensitive" | "insensitive";
+/** A read-only filesystem. */
+export interface CsFileSystem {
+    /** Short name of the backend, for diagnostics: `"http"`, `"fsa"`, `"opfs"`. */
+    readonly kind: string;
+    /**
+     * Resolve a path to a file.
+     *
+     * Paths are POSIX-style and rooted: `/pr/Planches.dat`. A leading slash is
+     * optional. `null` means "not there", which is the normal, non-exceptional
+     * answer — callers should not have to write a try/catch to test existence.
+     *
+     * A path may address inside an archive with `#`, e.g.
+     * `/dessins/100.zip#/1132C000.png`, when the filesystem was wrapped for it.
+     */
+    file(path: string): Promise<CsFile | null>;
+    /** Resolve a path to a directory. `"/"` is the root. */
+    directory(path: string): Promise<CsDirectory | null>;
+    /** Shorthand for `file(path)` then `bytes()`. `null` if absent. */
+    read(path: string): Promise<Uint8Array | null>;
+    /** Does this path exist, and as what? */
+    stat(path: string): Promise<CsStat | null>;
+    /**
+     * A URL the browser can load directly — an `<img>`, `<iframe>` or `<video>`
+     * source. Optional: only a backend whose bytes are already addressable can
+     * offer one, which in practice means HTTP.
+     *
+     * Worth asking for rather than always minting a blob. A blob URL requires
+     * downloading the whole file first, so a 40 MB PDF cannot show page one
+     * until all of it has arrived, and the browser cannot cache it between
+     * visits. A real URL lets the browser range-request and cache for itself.
+     *
+     * `null` when this path has no direct URL — it does not exist, or it lives
+     * inside an archive, where the bytes are not addressable on their own. A
+     * caller should then fall back to a blob.
+     */
+    directUrl?(path: string): Promise<string | null>;
+}
+export interface CsStat {
+    readonly kind: "file" | "directory";
+    readonly name: string;
+    /** Bytes; `0` for a directory, and for backends that cannot say cheaply. */
+    readonly size: number;
+}
+/**
+ * Writing, for the backends that can.
+ *
+ * Separate from `CsFileSystem` so a consumer that only reads never sees it,
+ * and so a function that needs to write says so in its signature.
+ */
+export interface WritableFileSystem extends CsFileSystem {
+    /** Create or replace a file, creating parent directories. */
+    write(path: string, data: Uint8Array | ReadableStream<Uint8Array>): Promise<void>;
+    /** Create a directory and its parents. Succeeds if it exists. */
+    makeDirectory(path: string): Promise<void>;
+    /** Remove a file or an empty directory. `recursive` removes a tree. */
+    remove(path: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+}
+/** True when a filesystem can be written to. */
+export declare function isWritable(fs: CsFileSystem): fs is WritableFileSystem;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,26 @@
+/**
+ * The contract every backend implements.
+ *
+ * Two design decisions shape all of this, and both are worth stating because
+ * the obvious alternatives are worse.
+ *
+ * **A file is modelled on `Blob`, not on `readFile`.** `size`, `slice`,
+ * `arrayBuffer`, `stream`, `text` — the same five things a `Blob` gives you.
+ * That is not imitation for its own sake: reading *part* of a file is the
+ * operation that makes remote data usable at all. An archive is read from its
+ * end, a sorted index is binary-searched, a media file is seeked. An interface
+ * whose only read is "give me the whole thing" forces a download per lookup,
+ * and every backend then grows its own private range API. Because `Blob` and
+ * `File` already satisfy this shape, the local backends need no adapter at all.
+ *
+ * **Reads only.** Writing is a separate, optional interface
+ * (`WritableFileSystem`), because two of the three backends cannot write and a
+ * combined interface would make every consumer check capabilities it does not
+ * use. A read-only filesystem is the common case and should be the plain one.
+ */
+/** True when a filesystem can be written to. */
+export function isWritable(fs) {
+    const candidate = fs;
+    return typeof candidate.write === "function" && typeof candidate.makeDirectory === "function";
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAwHH,gDAAgD;AAChD,MAAM,UAAU,UAAU,CAAC,EAAgB;IACzC,MAAM,SAAS,GAAG,EAAiC,CAAC;IACpD,OAAO,OAAO,SAAS,CAAC,KAAK,KAAK,UAAU,IAAI,OAAO,SAAS,CAAC,aAAa,KAAK,UAAU,CAAC;AAChG,CAAC"}

package/dist/walk.d.ts

@@ -0,0 +1,37 @@
+import type { CsDirectory, CsFile, CsFileSystem, CsStat } from "./types.js";
+/** Walk down from a directory to the one at `path`. `null` if absent. */
+export declare function resolveDirectory(root: CsDirectory, path: string): Promise<CsDirectory | null>;
+/** Walk down to the file at `path`. `null` if absent or a directory. */
+export declare function resolveFile(root: CsDirectory, path: string): Promise<CsFile | null>;
+/**
+ * `stat` built from `entries`.
+ *
+ * Asks the parent for its listing rather than trying the file and then the
+ * directory: one round trip instead of two, which matters on a backend where
+ * each is a network request.
+ */
+export declare function statVia(root: CsDirectory, path: string): Promise<CsStat | null>;
+export interface WalkEntry {
+    /** Path from the walk's root, with a leading slash. */
+    readonly path: string;
+    readonly name: string;
+    readonly kind: "file" | "directory";
+    /** `0` for directories, and for backends that do not report it in a listing. */
+    readonly size: number;
+}
+export interface WalkOptions {
+    /** Skip a subtree, or a file, by returning `false`. */
+    filter?: (entry: WalkEntry) => boolean;
+    /** Yield directories as well as files. Default: files only. */
+    includeDirectories?: boolean;
+}
+/**
+ * Every file under a directory, depth-first.
+ *
+ * A generator rather than an array: a tree can hold 228,000 files, and a
+ * caller that wants a count, or the first match, should not pay for the rest.
+ */
+export declare function walk(dir: CsDirectory, opts?: WalkOptions, prefix?: string): AsyncGenerator<WalkEntry>;
+/** `walk` from a filesystem's root. */
+export declare function walkFileSystem(fs: CsFileSystem, path?: string, opts?: WalkOptions): AsyncGenerator<WalkEntry>;
+//# sourceMappingURL=walk.d.ts.map

package/dist/walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,WAAW,EAAW,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAErF,yEAAyE;AACzE,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,WAAW,EACjB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAO7B;AAED,wEAAwE;AACxE,wBAAsB,WAAW,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAMzF;AAED;;;;;;GAMG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAUrF;AAED,MAAM,WAAW,SAAS;IACxB,uDAAuD;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IACpC,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,uDAAuD;IACvD,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,OAAO,CAAC;IACvC,+DAA+D;IAC/D,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;GAKG;AACH,wBAAuB,IAAI,CACzB,GAAG,EAAE,WAAW,EAChB,IAAI,GAAE,WAAgB,EACtB,MAAM,SAAK,GACV,cAAc,CAAC,SAAS,CAAC,CA2B3B;AAED,uCAAuC;AACvC,wBAAuB,cAAc,CACnC,EAAE,EAAE,YAAY,EAChB,IAAI,SAAM,EACV,IAAI,GAAE,WAAgB,GACrB,cAAc,CAAC,SAAS,CAAC,CAI3B"}

package/dist/walk.js

@@ -0,0 +1,93 @@
+/**
+ * Walking a tree, and resolving a path through it.
+ *
+ * Every backend needs the same two things: turn `/a/b/c.txt` into a sequence
+ * of lookups, and enumerate a tree depth-first. Both are written once here,
+ * against the interface, so a backend supplies only `entries`, `file` and
+ * `directory` on a single directory.
+ */
+import { basename, dirname, segments } from "./path.js";
+/** Walk down from a directory to the one at `path`. `null` if absent. */
+export async function resolveDirectory(root, path) {
+    let current = root;
+    for (const name of segments(path)) {
+        if (!current)
+            return null;
+        current = await current.directory(name);
+    }
+    return current;
+}
+/** Walk down to the file at `path`. `null` if absent or a directory. */
+export async function resolveFile(root, path) {
+    const parent = await resolveDirectory(root, dirname(path));
+    if (!parent)
+        return null;
+    const name = basename(path);
+    if (name === "")
+        return null;
+    return await parent.file(name);
+}
+/**
+ * `stat` built from `entries`.
+ *
+ * Asks the parent for its listing rather than trying the file and then the
+ * directory: one round trip instead of two, which matters on a backend where
+ * each is a network request.
+ */
+export async function statVia(root, path) {
+    const name = basename(path);
+    if (name === "")
+        return { kind: "directory", name: "", size: 0 };
+    const parent = await resolveDirectory(root, dirname(path));
+    if (!parent)
+        return null;
+    const found = (await parent.entries()).find((e) => e.name === name);
+    if (!found)
+        return null;
+    return found.kind === "file"
+        ? { kind: "file", name: found.name, size: found.size }
+        : { kind: "directory", name: found.name, size: 0 };
+}
+/**
+ * Every file under a directory, depth-first.
+ *
+ * A generator rather than an array: a tree can hold 228,000 files, and a
+ * caller that wants a count, or the first match, should not pay for the rest.
+ */
+export async function* walk(dir, opts = {}, prefix = "") {
+    let listing;
+    try {
+        listing = await dir.entries();
+    }
+    catch {
+        // An unreadable directory ends that branch rather than the whole walk:
+        // one permission-denied subtree should not lose the other 200,000 files.
+        return;
+    }
+    for (const child of listing) {
+        const path = `${prefix}/${child.name}`;
+        const entry = child.kind === "file"
+            ? { path, name: child.name, kind: "file", size: child.size }
+            : { path, name: child.name, kind: "directory", size: 0 };
+        if (opts.filter && !opts.filter(entry))
+            continue;
+        if (child.kind === "directory") {
+            if (opts.includeDirectories)
+                yield entry;
+            const sub = await dir.directory(child.name);
+            if (sub)
+                yield* walk(sub, opts, path);
+        }
+        else {
+            yield entry;
+        }
+    }
+}
+/** `walk` from a filesystem's root. */
+export async function* walkFileSystem(fs, path = "/", opts = {}) {
+    const dir = await fs.directory(path);
+    if (!dir)
+        return;
+    yield* walk(dir, opts, path === "/" ? "" : path.replace(/\/$/, ""));
+}
+//# sourceMappingURL=walk.js.map

package/dist/walk.js.map

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

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@emdzej/csfs-core",
+  "version": "0.1.0",
+  "description": "Client-side file system: the read contract, paths, and shared file implementations",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/emdzej/csfs.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/emdzej/csfs/tree/main/packages/core#readme",
+  "bugs": {
+    "url": "https://github.com/emdzej/csfs/issues"
+  },
+  "keywords": [
+    "filesystem",
+    "browser",
+    "zip",
+    "range-requests",
+    "opfs",
+    "file-system-access",
+    "http"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.1"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo *.tsbuildinfo"
+  }
+}