@dbx-tools/shared-fs 0.6.10

package/README.md

@@ -0,0 +1,56 @@
+# `@dbx-tools/shared-fs`
+
+Browser-safe filesystem contract and abstract base for rooted storage backends.
+
+Key features:
+
+- Portable `FileSystem` interface (read/write/append/copy/move, mkdir/rmdir/readdir/stat/exists)
+- `BaseFileSystem` root accepts one or many segments (`"/path"`, objects →
+  FNV hash, `true`/`1` stringified); strings are split on `/` and only a
+  component that _cannot_ be a path component (separator, NUL / control
+  character, or `..`) is FNV-hashed, so real names like
+  `/Workspace/Users/me@corp.com/My Notes` survive intact
+- `BaseFileSystem` so a new backend mostly implements `*At` primitives: memoized `_init`, optional `createRoot`, `toBackendPath`, parent creation before write/append/copy/move, POSIX-only paths, encoding, recursive mkdir/rmdir/readdir, and append/copy/move fallbacks
+- Every primitive is invoked through a guard that routes failures to a
+  `mapError` hook, so an adapter writes no try/catch of its own and cannot
+  return an unnormalized error
+- `MemoryFileSystem` in-process adapter for tests and as a reference implementation
+- `baseFS.mapFileSystemError` / `baseFS.inferFileSystemErrorCode` on
+  `@dbx-tools/shared-core` `error` helpers
+- `posixPath` helpers that convert roots/joins to `/`-separated form
+  (`posixPath.toPosix`, `posixPath.join`, …)
+- Typed `FileSystemError` codes for portable failure handling
+
+## Why use this
+
+Use this when multiple backends (local disk, object storage, Databricks volumes, in-memory) should share one API. Node hosts implement concrete adapters such as `@dbx-tools/fs` (`LocalFileSystem`).
+
+## Quick start
+
+```ts
+import type { FileSystem } from "@dbx-tools/shared-fs";
+import { BaseFileSystem, FileSystemError, MemoryFileSystem, posixPath } from "@dbx-tools/shared-fs";
+
+const mem = new MemoryFileSystem();
+await mem.writeFile("note.txt", "hi");
+```
+
+## Module map
+
+| Export                                   | Role                                                       |
+| ---------------------------------------- | ---------------------------------------------------------- |
+| `FileSystem`                             | Portable filesystem contract                               |
+| `BaseFileSystem`                         | Abstract base over `*At` primitives; memoized `_init`      |
+| `baseFS.normalizeFileSystemRoot`         | Join root segments (stringify / FNV-hash)                  |
+| `FileSystemRootInput`                    | `root` option: one or many non-null segments               |
+| `MemoryFileSystem`                       | In-memory adapter (tests / reference)                      |
+| `baseFS.mapFileSystemError`              | Wrap backend failures into `FileSystemError`               |
+| `baseFS.inferFileSystemErrorCode`        | Infer a code from HTTP status / message tokens             |
+| `posixPath`                              | POSIX root/join/normalize helpers for namespace paths      |
+| `posixPath.isHomeRelativePath`           | `~` / `~/...` detection, shared by every adapter           |
+| `posixPath.expandHome`                   | Expand `~` against a home, with a pluggable join           |
+| `posixPath.toRelativeSegment`            | Strip leading `~` / separators so input joins UNDER a base |
+| `FileSystemError`                        | Typed filesystem failure                                   |
+| `FileEntry` / `FileStat` / options types | Shared wire shapes                                         |
+
+Adjacent: `@dbx-tools/fs` (local disk adapter).

package/index.ts

@@ -0,0 +1,14 @@
+// GENERATED by projen watch - DO NOT EDIT.
+// Regenerated from the exporting modules in ./src.
+// Hand edits are overwritten on the next watch; this file is read-only.
+
+export * as baseFS from "./src/base-fs.ts";
+export * as fs from "./src/fs.ts";
+export * as memoryFS from "./src/memory-fs.ts";
+export * as posixPath from "./src/posix-path.ts";
+export { FileSystemError, BaseFileSystem } from "./src/base-fs.ts";
+export type { FileSystemRootSegment, FileSystemRootInput, FileSystemErrorCode, BaseFileSystemOptions } from "./src/base-fs.ts";
+export type { FileContent, FileEntryType, FileEntry, FileStat, ReadFileOptions, WriteFileOptions, RemoveOptions, CopyOptions, MakeDirectoryOptions, ListOptions, FileSystem } from "./src/fs.ts";
+export { MemoryFileSystem } from "./src/memory-fs.ts";
+export type { MemoryFileSystemOptions } from "./src/memory-fs.ts";
+export type { NormalizeResult } from "./src/posix-path.ts";

package/lib/index.d.ts

@@ -0,0 +1,10 @@
+export * as baseFS from "./src/base-fs.ts";
+export * as fs from "./src/fs.ts";
+export * as memoryFS from "./src/memory-fs.ts";
+export * as posixPath from "./src/posix-path.ts";
+export { FileSystemError, BaseFileSystem } from "./src/base-fs.ts";
+export type { FileSystemRootSegment, FileSystemRootInput, FileSystemErrorCode, BaseFileSystemOptions } from "./src/base-fs.ts";
+export type { FileContent, FileEntryType, FileEntry, FileStat, ReadFileOptions, WriteFileOptions, RemoveOptions, CopyOptions, MakeDirectoryOptions, ListOptions, FileSystem } from "./src/fs.ts";
+export { MemoryFileSystem } from "./src/memory-fs.ts";
+export type { MemoryFileSystemOptions } from "./src/memory-fs.ts";
+export type { NormalizeResult } from "./src/posix-path.ts";

package/lib/index.js

@@ -0,0 +1,10 @@
+// GENERATED by projen watch - DO NOT EDIT.
+// Regenerated from the exporting modules in ./src.
+// Hand edits are overwritten on the next watch; this file is read-only.
+export * as baseFS from "./src/base-fs.js";
+export * as fs from "./src/fs.js";
+export * as memoryFS from "./src/memory-fs.js";
+export * as posixPath from "./src/posix-path.js";
+export { FileSystemError, BaseFileSystem } from "./src/base-fs.js";
+export { MemoryFileSystem } from "./src/memory-fs.js";
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxPQUFPLEtBQUssTUFBTSxNQUFNLGtCQUFrQixDQUFDO0FBQzNDLE9BQU8sS0FBSyxFQUFFLE1BQU0sYUFBYSxDQUFDO0FBQ2xDLE9BQU8sS0FBSyxRQUFRLE1BQU0sb0JBQW9CLENBQUM7QUFDL0MsT0FBTyxLQUFLLFNBQVMsTUFBTSxxQkFBcUIsQ0FBQztBQUNqRCxPQUFPLEVBQUUsZUFBZSxFQUFFLGNBQWMsRUFBRSxNQUFNLGtCQUFrQixDQUFDO0FBR25FLE9BQU8sRUFBRSxnQkFBZ0IsRUFBRSxNQUFNLG9CQUFvQixDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLy8gR0VORVJBVEVEIGJ5IHByb2plbiB3YXRjaCAtIERPIE5PVCBFRElULlxuLy8gUmVnZW5lcmF0ZWQgZnJvbSB0aGUgZXhwb3J0aW5nIG1vZHVsZXMgaW4gLi9zcmMuXG4vLyBIYW5kIGVkaXRzIGFyZSBvdmVyd3JpdHRlbiBvbiB0aGUgbmV4dCB3YXRjaDsgdGhpcyBmaWxlIGlzIHJlYWQtb25seS5cblxuZXhwb3J0ICogYXMgYmFzZUZTIGZyb20gXCIuL3NyYy9iYXNlLWZzLnRzXCI7XG5leHBvcnQgKiBhcyBmcyBmcm9tIFwiLi9zcmMvZnMudHNcIjtcbmV4cG9ydCAqIGFzIG1lbW9yeUZTIGZyb20gXCIuL3NyYy9tZW1vcnktZnMudHNcIjtcbmV4cG9ydCAqIGFzIHBvc2l4UGF0aCBmcm9tIFwiLi9zcmMvcG9zaXgtcGF0aC50c1wiO1xuZXhwb3J0IHsgRmlsZVN5c3RlbUVycm9yLCBCYXNlRmlsZVN5c3RlbSB9IGZyb20gXCIuL3NyYy9iYXNlLWZzLnRzXCI7XG5leHBvcnQgdHlwZSB7IEZpbGVTeXN0ZW1Sb290U2VnbWVudCwgRmlsZVN5c3RlbVJvb3RJbnB1dCwgRmlsZVN5c3RlbUVycm9yQ29kZSwgQmFzZUZpbGVTeXN0ZW1PcHRpb25zIH0gZnJvbSBcIi4vc3JjL2Jhc2UtZnMudHNcIjtcbmV4cG9ydCB0eXBlIHsgRmlsZUNvbnRlbnQsIEZpbGVFbnRyeVR5cGUsIEZpbGVFbnRyeSwgRmlsZVN0YXQsIFJlYWRGaWxlT3B0aW9ucywgV3JpdGVGaWxlT3B0aW9ucywgUmVtb3ZlT3B0aW9ucywgQ29weU9wdGlvbnMsIE1ha2VEaXJlY3RvcnlPcHRpb25zLCBMaXN0T3B0aW9ucywgRmlsZVN5c3RlbSB9IGZyb20gXCIuL3NyYy9mcy50c1wiO1xuZXhwb3J0IHsgTWVtb3J5RmlsZVN5c3RlbSB9IGZyb20gXCIuL3NyYy9tZW1vcnktZnMudHNcIjtcbmV4cG9ydCB0eXBlIHsgTWVtb3J5RmlsZVN5c3RlbU9wdGlvbnMgfSBmcm9tIFwiLi9zcmMvbWVtb3J5LWZzLnRzXCI7XG5leHBvcnQgdHlwZSB7IE5vcm1hbGl6ZVJlc3VsdCB9IGZyb20gXCIuL3NyYy9wb3NpeC1wYXRoLnRzXCI7XG4iXX0=

package/lib/src/base-fs.d.ts

@@ -0,0 +1,268 @@
+/**
+ * Abstract {@link FileSystem} base: lifecycle, rooted POSIX paths, encoding, and
+ * portable fallbacks so a concrete backend only implements low-level I/O.
+ *
+ * A new adapter typically overrides:
+ * - {@link onInit} / {@link onClose} (optional)
+ * - {@link createRootDirectory} when {@link BaseFileSystemOptions.createRoot} is set
+ * - {@link toBackendPath} when the backend needs non-POSIX separators
+ * - {@link preparePath} for post-resolve checks (e.g. symlink containment)
+ * - the `*At` primitives and {@link isNotFoundError}
+ * - optional `try*` hooks for native append / copy / move
+ *
+ * @module
+ */
+import { type OneOrMany } from "@dbx-tools/shared-core";
+import type { CopyOptions, FileContent, FileEntry, FileStat, FileSystem, ListOptions, MakeDirectoryOptions, ReadFileOptions, RemoveOptions, WriteFileOptions } from "./fs.ts";
+/**
+ * One root path segment. Strings are split on `/` and sanitized; numbers /
+ * booleans / bigints stringify then sanitize; objects and arrays are FNV-hashed
+ * as a single segment.
+ */
+export type FileSystemRootSegment = string | number | boolean | bigint | object;
+/**
+ * A single {@link FileSystemRootSegment} or a non-empty list of them. Nested
+ * arrays/objects inside the list are one hashed segment each (not flattened).
+ */
+export type FileSystemRootInput = FileSystemRootSegment | OneOrMany<FileSystemRootSegment>;
+/**
+ * Turn {@link root} into a POSIX filesystem root:
+ *
+ * 1. Expand one-or-many input segments
+ * 2. Strings split on `/` (and `\`); objects/arrays FNV-hash as one piece
+ * 3. Each resulting component that cannot be a path component - see
+ *    {@link UNSAFE_PATH_SEGMENT} - is replaced with {@link hash.fnvHash}
+ * 4. Join with `/` and run {@link posixPath.normalizeRoot}
+ *
+ * Defaults to `/`. A leading `/` on the first string segment is preserved.
+ *
+ * @example
+ * normalizeFileSystemRoot("/cool/wow"); // "/cool/wow"
+ * normalizeFileSystemRoot("/Users/me@corp.com/My Notes"); // unchanged
+ * normalizeFileSystemRoot(["/path", { user: 1 }, true]); // "/path/<hash>/true"
+ */
+export declare function normalizeFileSystemRoot(root?: FileSystemRootInput): string;
+export type FileSystemErrorCode = "NOT_FOUND" | "ALREADY_EXISTS" | "NOT_DIRECTORY" | "IS_DIRECTORY" | "DIRECTORY_NOT_EMPTY" | "PERMISSION_DENIED" | "READ_ONLY" | "INVALID_PATH" | "NOT_SUPPORTED" | "IO_ERROR";
+export declare class FileSystemError extends Error {
+    readonly code: FileSystemErrorCode;
+    readonly path?: string | undefined;
+    readonly name = "FileSystemError";
+    constructor(code: FileSystemErrorCode, message: string, path?: string | undefined, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Infer a {@link FileSystemErrorCode} from HTTP status / message tokens on an
+ * unknown thrown value (via {@link error.errorContext}).
+ *
+ * Covers common SDK / REST wording so adapters do not reimplement the same
+ * "not found" / "already exists" checks. Returns undefined when nothing matches.
+ */
+export declare function inferFileSystemErrorCode(err: unknown): FileSystemErrorCode | undefined;
+/**
+ * Map an unknown backend failure into a {@link FileSystemError}.
+ *
+ * Prefer a backend-specific {@link codeOf} classifier (errno, SDK code). When
+ * it returns undefined, falls back to {@link inferFileSystemErrorCode}. Message
+ * and cause always go through `@dbx-tools/shared-core` {@link error} helpers.
+ */
+export declare function mapFileSystemError(err: unknown, filePath: string, codeOf?: (err: unknown) => FileSystemErrorCode | undefined): FileSystemError;
+export interface BaseFileSystemOptions<TBackend extends string = string> {
+    id: string;
+    backend: TBackend;
+    /**
+     * Filesystem root. One segment or a list of segments ({@link FileSystemRootInput}):
+     * primitives stringify, objects/arrays are FNV-hashed, then joined with `/`
+     * and normalized via {@link posixPath.normalizeRoot}. Defaults to `/`.
+     */
+    root?: FileSystemRootInput;
+    readOnly?: boolean;
+    /**
+     * Ensure {@link root} exists during init by calling {@link createRootDirectory}.
+     * Defaults to false (remote roots usually already exist). Local disk adapters
+     * typically pass true and override {@link createRootDirectory}.
+     */
+    createRoot?: boolean;
+}
+/**
+ * Base implementation for local, remote, and virtual filesystems.
+ *
+ * Subclasses implement the low-level `*At` primitives. This class provides:
+ *
+ * - Memoized {@link _init} (so an explicit {@link init} call is optional)
+ * - Optional root creation via {@link createRootDirectory}
+ * - POSIX-only rooted path normalization and traversal protection
+ * - {@link toBackendPath} for host/separator conversion at the boundary
+ * - Text encoding and decoding
+ * - {@link exists}
+ * - Parent-directory creation on write / append / copy / move
+ * - Append / copy / move fallbacks (override `try*` for native ops)
+ * - Recursive mkdir, readdir, and rmdir
+ * - Extension filtering for {@link readdir}
+ *
+ * Namespace paths always use `/`. Host adapters convert with
+ * {@link posixPath.toPosix} / {@link posixPath.toHost} in {@link toBackendPath}.
+ */
+export declare abstract class BaseFileSystem<TBackend extends string = string> implements FileSystem<TBackend> {
+    readonly id: string;
+    readonly backend: TBackend;
+    /** POSIX-normalized root (see {@link posixPath.normalizeRoot}). */
+    readonly root: string;
+    readonly readOnly: boolean;
+    protected readonly createRoot: boolean;
+    /**
+     * Memoized initialization. Every operation that needs a ready backend awaits
+     * this, so callers (e.g. Mastra) may call {@link init} every time or never;
+     * both are fine.
+     */
+    protected _init: () => Promise<void>;
+    private initStarted;
+    protected constructor(options: BaseFileSystemOptions<TBackend>);
+    private createInit;
+    init(): Promise<void>;
+    close(): Promise<void>;
+    /**
+     * Ensure {@link root} exists when {@link createRoot} is true.
+     *
+     * Default is a no-op. Local adapters typically `mkdir -p`; remote adapters
+     * leave the default when the root is provisioned out of band.
+     */
+    protected createRootDirectory(): Promise<void>;
+    /** Override when the backend requires connection or validation work. */
+    protected onInit(): Promise<void>;
+    /** Override when the backend owns connections or other resources. */
+    protected onClose(): Promise<void>;
+    protected assertWritable(operation: string): void;
+    /**
+     * Normalize an input path into an absolute POSIX path inside the virtual
+     * filesystem namespace (`/a/b`). Backslashes are converted; `..` escaping
+     * the root throws {@link FileSystemError} `PERMISSION_DENIED`.
+     */
+    protected normalizePath(inputPath: string): string;
+    /**
+     * Convert a POSIX backend path (under {@link root}) into the form the
+     * underlying API expects.
+     *
+     * Default is identity. Local disk overrides with {@link posixPath.toHost}.
+     * Databricks / object-store adapters usually leave the default.
+     */
+    protected toBackendPath(posixBackendPath: string): string;
+    /**
+     * Convert a normalized namespace path (`/a/b`) into a backend path.
+     *
+     * Joins {@link root} with the namespace using POSIX `/`, then applies
+     * {@link toBackendPath}. Override {@link toBackendPath} instead of this
+     * method unless the join itself must change.
+     */
+    protected resolveBackendPath(namespacePath: string): string;
+    resolvePath(inputPath: string): string;
+    /**
+     * Resolve {@link inputPath}, ensure init, and run {@link preparePath}.
+     */
+    protected resolveFor(inputPath: string, options?: {
+        allowMissing?: boolean;
+    }): Promise<string>;
+    /**
+     * {@link resolveFor} for a path that is ALREADY a normalized namespace path
+     * (`/a/b`). The single spelling for "namespace path to prepared backend
+     * path", so no call site has to re-derive the chain by hand.
+     */
+    private resolveNamespaceFor;
+    /**
+     * Hook after lexical resolution. Override for realpath containment or
+     * similar backend-specific checks. Default is a no-op.
+     */
+    protected preparePath(resolvedPath: string, _options?: {
+        allowMissing?: boolean;
+    }): Promise<string>;
+    protected joinNamespace(parent: string, child: string): string;
+    /** Namespace path without a leading slash (`.` for the root). */
+    protected toRelativePath(namespacePath: string): string;
+    protected toBytes(content: FileContent): Uint8Array;
+    /** Create parent directories for {@link inputPath} when it is nested. */
+    protected ensureParentDirectory(inputPath: string): Promise<void>;
+    protected abstract readBytesAt(resolvedPath: string): Promise<Uint8Array>;
+    protected abstract writeBytesAt(resolvedPath: string, content: Uint8Array, options: Required<WriteFileOptions>): Promise<void>;
+    protected abstract deleteFileAt(resolvedPath: string): Promise<void>;
+    protected abstract createDirectoryAt(resolvedPath: string): Promise<void>;
+    /**
+     * Remove an empty directory.
+     *
+     * Recursive deletion is implemented by {@link BaseFileSystem}.
+     */
+    protected abstract removeDirectoryAt(resolvedPath: string): Promise<void>;
+    /** Return only the direct children of a directory (`name` is the basename). */
+    protected abstract listDirectoryAt(resolvedPath: string): Promise<FileEntry[]>;
+    protected abstract statAt(resolvedPath: string): Promise<Omit<FileStat, "path">>;
+    /**
+     * Recognize the backend's not-found error.
+     *
+     * Default accepts {@link FileSystemError} `NOT_FOUND` plus common SDK / HTTP
+     * "not found" shapes via {@link inferFileSystemErrorCode}. Override for
+     * backend-specific codes (e.g. Node `ENOENT`) that do not carry a message.
+     */
+    protected isNotFoundError(err: unknown): boolean;
+    /**
+     * Normalize a backend failure into a {@link FileSystemError}.
+     *
+     * Every `*At` / `try*` primitive is invoked through {@link guard}, so an
+     * adapter never writes its own try/catch and cannot forget to normalize.
+     * Override only to classify backend-specific codes (e.g. Node errno).
+     */
+    protected mapError(err: unknown, filePath: string): FileSystemError;
+    /** Run a backend primitive, routing any failure through {@link mapError}. */
+    private guard;
+    /**
+     * Override when the backend supports native append.
+     *
+     * Parent directories are already created by {@link appendFile}. Return true
+     * when the operation was performed. The default causes {@link BaseFileSystem}
+     * to use read-concatenate-write.
+     */
+    protected tryAppendFileAt(_resolvedPath: string, _content: Uint8Array): Promise<boolean>;
+    /**
+     * Override when the backend supports native server-side copying.
+     *
+     * Parent directories of the destination are already created by {@link copyFile}.
+     */
+    protected tryCopyFileAt(_sourcePath: string, _destinationPath: string, _options: Required<CopyOptions>): Promise<boolean>;
+    /**
+     * Override for native rename or move support.
+     *
+     * Parent directories of the destination are already created by {@link moveFile}.
+     */
+    protected tryMoveFileAt(_sourcePath: string, _destinationPath: string, _options: Required<CopyOptions>): Promise<boolean>;
+    readFile(inputPath: string): Promise<Uint8Array>;
+    readFile(inputPath: string, options: ReadFileOptions & {
+        encoding: string;
+    }): Promise<string>;
+    writeFile(inputPath: string, content: FileContent, options?: WriteFileOptions): Promise<void>;
+    appendFile(inputPath: string, content: FileContent): Promise<void>;
+    deleteFile(inputPath: string, options?: RemoveOptions): Promise<void>;
+    copyFile(sourcePath: string, destinationPath: string, options?: CopyOptions): Promise<void>;
+    moveFile(sourcePath: string, destinationPath: string, options?: CopyOptions): Promise<void>;
+    /**
+     * Resolve the effective `overwrite` flag, rejecting when the target exists
+     * and overwriting was refused. Shared by write / copy / move so the three
+     * cannot disagree about what `overwrite: false` means.
+     */
+    private resolveOverwrite;
+    /** Shared copy / move prologue: writability, overwrite policy, both ends resolved. */
+    private prepareTransfer;
+    /** Run a removal, swallowing a not-found failure when `force` is set. */
+    private ignoringMissing;
+    mkdir(inputPath: string, options?: MakeDirectoryOptions): Promise<void>;
+    rmdir(inputPath: string, options?: RemoveOptions): Promise<void>;
+    private removeDirectoryContents;
+    /** {@link createDirectoryAt} for a namespace path, resolved and guarded. */
+    private createDirectory;
+    /** {@link removeDirectoryAt} for a namespace path, resolved and guarded. */
+    private removeDirectory;
+    /** {@link listDirectoryAt} for a namespace path, resolved and guarded. */
+    private listDirectory;
+    readdir(inputPath: string, options?: ListOptions): Promise<FileEntry[]>;
+    private listDirectoryRecursive;
+    private filterEntries;
+    exists(inputPath: string): Promise<boolean>;
+    stat(inputPath: string): Promise<FileStat>;
+}