@bendyline/docblocks 1.1.2 → 2.0.0

package/dist/types-CsX6EN2t.d.ts

@@ -0,0 +1,301 @@
+import { a as WorkspacePath } from './workspace-path-CWVrcuPL.js';
+
+/** Stable error codes shared by every filesystem transport and backend. */
+type FsErrorCode = 'invalid-path' | 'path-escape' | 'not-found' | 'already-exists' | 'type-mismatch' | 'not-empty' | 'permission-denied' | 'conflict' | 'quota-exceeded' | 'not-supported' | 'busy' | 'disposed' | 'closed' | 'aborted' | 'io';
+type FsOperation = 'parse-path' | 'read' | 'stat' | 'list' | 'write' | 'create-directory' | 'remove' | 'move' | 'snapshot' | 'watch' | 'dispose';
+/** Plain-data form safe to send over IPC, postMessage, or JSON. */
+interface SerializedFsError {
+    readonly name: 'FsError';
+    readonly code: FsErrorCode;
+    readonly message: string;
+    readonly operation: FsOperation | null;
+    readonly path: string | null;
+    readonly destinationPath: string | null;
+    readonly retryable: boolean;
+}
+interface FsErrorContext {
+    readonly operation?: FsOperation;
+    readonly path?: string;
+    readonly destinationPath?: string;
+    readonly retryable?: boolean;
+    readonly defaultCode?: FsErrorCode;
+}
+/** Error with a stable code and a deliberately serializable public shape. */
+declare class FsError extends Error {
+    readonly code: FsErrorCode;
+    readonly operation: FsOperation | null;
+    readonly path: string | null;
+    readonly destinationPath: string | null;
+    readonly retryable: boolean;
+    constructor(code: FsErrorCode, message: string, context?: FsErrorContext);
+    toJSON(): SerializedFsError;
+}
+declare function mapDomExceptionToFsErrorCode(name: string): FsErrorCode;
+declare function mapNodeErrorCodeToFsErrorCode(code: string): FsErrorCode;
+declare function isSerializedFsError(value: unknown): value is SerializedFsError;
+declare function deserializeFsError(value: SerializedFsError): FsError;
+declare function fsErrorFromUnknown(error: unknown, context?: FsErrorContext): FsError;
+declare function serializeFsError(error: unknown, context?: FsErrorContext): SerializedFsError;
+/**
+ * True when a storage backend rejected an operation because the origin or
+ * device is out of space. Covers typed `FsError`s (`'quota-exceeded'`, from
+ * DOMException `QuotaExceededError` or Node `ENOSPC`/`EDQUOT`), serialized
+ * transport copies, and raw DOMExceptions from backends that do not wrap
+ * their errors (e.g. the File System Access API) — including cross-realm
+ * instances where `instanceof DOMException` would fail.
+ */
+declare function isQuotaExceededError(error: unknown): boolean;
+
+/**
+ * Opaque provider-issued token representing one observed entry/tree state.
+ * Tokens support equality only within the issuing provider; callers must not
+ * parse them or assume a move or byte-identical rewrite changes the token.
+ * A token need not be a content hash, but it must change whenever the issuing
+ * provider observes a potentially different kind, payload, or descendant
+ * state. Detection of non-cooperating external changes is bounded by the
+ * backend's declared capabilities and metadata precision.
+ */
+declare const fileSystemVersionBrand: unique symbol;
+type FileSystemVersion = string & {
+    readonly [fileSystemVersionBrand]: 'FileSystemVersion';
+};
+/** Validate/rebrand a version received from a provider transport. */
+declare function parseFileSystemVersion(value: unknown): FileSystemVersion;
+declare function tryParseFileSystemVersion(value: unknown): FileSystemVersion | null;
+/** `process` excludes this provider's local peers; `cross-context` also excludes cooperating tabs/processes. */
+type FileSystemAtomicity = 'none' | 'process' | 'cross-context';
+type FileSystemCaseSensitivity = 'sensitive' | 'insensitive' | 'platform';
+type FileSystemDurability = 'volatile' | 'best-effort' | 'durable';
+type FileSystemConditionalWriteStrength = 'none' | 'process' | 'cross-context' | 'storage-atomic';
+type FileSystemSymlinkPolicy = 'unsupported' | 'reject' | 'follow-contained' | 'preserve';
+/** Serializable feature declaration; consumers never need provider instanceof checks. */
+interface FileSystemProviderCapabilities {
+    /** Isolation of one successful file replacement from cooperating writers. */
+    readonly writeAtomicity: FileSystemAtomicity;
+    /** Isolation of one successful source-to-destination move. */
+    readonly moveAtomicity: FileSystemAtomicity;
+    /** Writers excluded while one complete snapshot is captured. */
+    readonly snapshotAtomicity: FileSystemAtomicity;
+    /** Strongest boundary at which expectedVersion is checked with mutation. */
+    readonly conditionalWrite: FileSystemConditionalWriteStrength;
+    readonly recursiveRemove: boolean;
+    /** True only when watch has a real ready barrier and sequenced events. */
+    readonly watch: boolean;
+    readonly caseSensitivity: FileSystemCaseSensitivity;
+    readonly symlinkPolicy: FileSystemSymlinkPolicy;
+    readonly durability: FileSystemDurability;
+}
+interface FileSystemEntrySnapshotBase {
+    readonly path: WorkspacePath;
+    readonly name: string;
+    readonly version: FileSystemVersion;
+    /** ISO-8601 timestamp supplied by the backend; versions remain authoritative. */
+    readonly lastModified: string;
+}
+interface FileSystemFileSnapshot extends FileSystemEntrySnapshotBase {
+    readonly kind: 'file';
+    readonly size: number;
+}
+interface FileSystemDirectorySnapshot extends FileSystemEntrySnapshotBase {
+    readonly kind: 'directory';
+    readonly size: null;
+}
+type FileSystemEntrySnapshot = FileSystemFileSnapshot | FileSystemDirectorySnapshot;
+/** A read always couples owned bytes to the exact metadata version they represent. */
+interface FileSystemFileRead {
+    readonly entry: FileSystemFileSnapshot;
+    readonly data: ArrayBuffer;
+}
+interface FileSystemSnapshotFile extends FileSystemFileSnapshot {
+    readonly data: ArrayBuffer;
+}
+type FileSystemSnapshotEntry = FileSystemSnapshotFile | FileSystemDirectorySnapshot;
+/**
+ * Complete best-available tree traversal. `snapshotAtomicity` declares
+ * whether concurrent local/cross-context mutations are excluded while it is
+ * captured. Implementations must never expose aliased buffers.
+ */
+interface FileSystemSnapshot {
+    readonly version: FileSystemVersion;
+    readonly entries: readonly FileSystemSnapshotEntry[];
+}
+type FileSystemWriteMode = 'upsert' | 'create' | 'replace';
+interface FileSystemWriteOptions {
+    /** Defaults to upsert. */
+    readonly mode?: FileSystemWriteMode;
+    /** Defaults to false so structure creation is never implicit. */
+    readonly createParents?: boolean;
+    /** null means the entry must not exist; a token requires an exact match. */
+    readonly expectedVersion?: FileSystemVersion | null;
+}
+type FileSystemCreateDirectoryMode = 'ensure' | 'create';
+interface FileSystemCreateDirectoryOptions {
+    /** Defaults to ensure (idempotently return an existing directory). */
+    readonly mode?: FileSystemCreateDirectoryMode;
+    /** Defaults to false. */
+    readonly createParents?: boolean;
+}
+interface FileSystemRemoveOptions {
+    /** Defaults to false; non-empty directories otherwise fail with not-empty. */
+    readonly recursive?: boolean;
+    /** Defaults to error. */
+    readonly missing?: 'ignore' | 'error';
+    readonly expectedVersion?: FileSystemVersion;
+}
+interface FileSystemRemoveResult {
+    readonly removed: boolean;
+    /** Version of the complete tree after the removal attempt. */
+    readonly version: FileSystemVersion;
+}
+interface FileSystemMoveOptions {
+    /** Defaults to false. Destinations are never overwritten. */
+    readonly createParents?: boolean;
+    readonly expectedVersion?: FileSystemVersion;
+}
+type FileSystemWatchEventType = 'created' | 'modified' | 'removed' | 'moved' | 'overflow';
+type FileSystemWatchEventOrigin = 'local' | 'external' | 'unknown';
+interface FileSystemWatchEventBase {
+    readonly sequence: number;
+    readonly origin: FileSystemWatchEventOrigin;
+    readonly path: WorkspacePath;
+}
+interface FileSystemEntryWatchEvent extends FileSystemWatchEventBase {
+    readonly type: Exclude<FileSystemWatchEventType, 'overflow'>;
+    readonly kind: 'file' | 'directory';
+    readonly destinationPath: WorkspacePath | null;
+    readonly version: FileSystemVersion | null;
+    readonly previousVersion: FileSystemVersion | null;
+}
+interface FileSystemOverflowWatchEvent extends FileSystemWatchEventBase {
+    readonly type: 'overflow';
+    readonly kind: null;
+    readonly destinationPath: null;
+    readonly version: null;
+    readonly previousVersion: null;
+}
+type FileSystemWatchEvent = FileSystemEntryWatchEvent | FileSystemOverflowWatchEvent;
+type FileSystemWatchListener = (event: FileSystemWatchEvent) => void;
+type FileSystemWatchErrorListener = (error: FsError) => void;
+interface FileSystemWatchOptions {
+    readonly onError?: FileSystemWatchErrorListener;
+}
+interface FileSystemWatchSubscription {
+    readonly closed: boolean;
+    /** Resolves after the backend watch is installed and no initial event can be missed. */
+    readonly ready: Promise<void>;
+    /** Idempotent and awaitable so resource release can join provider shutdown. */
+    dispose(): Promise<void>;
+}
+/**
+ * Correctness-first filesystem contract. Every logical path has exactly one
+ * kind and one byte payload; conditional writes and lifecycle disposal are
+ * mandatory rather than optional provider extensions.
+ */
+interface FileSystemProviderV2 {
+    readonly id: string;
+    readonly label: string;
+    readonly capabilities: FileSystemProviderCapabilities;
+    /** Absence is represented only by null; permission/I/O/wrong-kind errors throw FsError. */
+    stat(path: WorkspacePath): Promise<FileSystemEntrySnapshot | null>;
+    /** Absence is represented only by null; a directory at path is type-mismatch. */
+    readFile(path: WorkspacePath): Promise<FileSystemFileRead | null>;
+    /** Missing paths and file paths throw; results are canonical and deterministic. */
+    readDirectory(path: WorkspacePath): Promise<readonly FileSystemEntrySnapshot[]>;
+    writeFile(path: WorkspacePath, data: ArrayBuffer | Uint8Array, options?: FileSystemWriteOptions): Promise<FileSystemFileSnapshot>;
+    createDirectory(path: WorkspacePath, options?: FileSystemCreateDirectoryOptions): Promise<FileSystemDirectorySnapshot>;
+    remove(path: WorkspacePath, options?: FileSystemRemoveOptions): Promise<FileSystemRemoveResult>;
+    move(oldPath: WorkspacePath, newPath: WorkspacePath, options?: FileSystemMoveOptions): Promise<FileSystemEntrySnapshot>;
+    snapshot(): Promise<FileSystemSnapshot>;
+    /**
+     * Always returns a disposable subscription. When `capabilities.watch` is
+     * false, `ready` rejects with `FsError('not-supported')` and `onError`
+     * observes the same failure; callers can therefore use one cleanup path.
+     */
+    watch(listener: FileSystemWatchListener, options?: FileSystemWatchOptions): FileSystemWatchSubscription;
+    dispose(): Promise<void>;
+}
+
+/**
+ * FileSystemProvider — abstract interface for a virtual filesystem.
+ *
+ * Legacy text-oriented facade retained while consumers migrate to
+ * FileSystemProviderV2. New persistence code must use the provider's `v2`
+ * contract so paths, errors, operation modes, and capabilities are explicit.
+ */
+
+interface FileEntry {
+    kind: 'file';
+    name: string;
+    path: string;
+}
+interface FolderEntry {
+    kind: 'directory';
+    name: string;
+    path: string;
+}
+type FileSystemEntry = FileEntry | FolderEntry;
+interface FileMeta {
+    name: string;
+    path: string;
+    size: number;
+    lastModified: string;
+}
+type FileCommitResult = {
+    status: 'committed';
+    version: string | null;
+} | {
+    status: 'conflict';
+    content: string | null;
+    version: string | null;
+};
+/**
+ * @deprecated Compatibility facade for external providers and older callers.
+ * Implement new backends with `FileSystemProviderV2`; built-in facades expose
+ * their authoritative implementation through `v2`.
+ */
+interface FileSystemProvider {
+    /** Unique identifier for this provider instance. */
+    readonly id: string;
+    /** Human-readable label (e.g., folder name or "Browser Storage"). */
+    readonly label: string;
+    /** Optional correctness-first implementation exposed during the v1-to-v2 migration. */
+    readonly v2?: FileSystemProviderV2;
+    /** Read the text content of a file. Returns null if the file doesn't exist. */
+    readFile(path: string): Promise<string | null>;
+    /** Write text content to a file, creating it (and parent dirs) if needed. */
+    writeFile(path: string, content: string): Promise<void>;
+    /**
+     * Conditionally replace a text file when it still matches the caller's
+     * persisted baseline. Production providers implement this at their
+     * strongest available serialization boundary.
+     */
+    commitFile?(path: string, content: string, expectedContent: string | null): Promise<FileCommitResult>;
+    /**
+     * Legacy recursive removal of a file or directory subtree. Workspace root
+     * deletion is forbidden. Prefer v2 `remove({ recursive })`.
+     */
+    delete(path: string): Promise<void>;
+    /** Rename or move an entry. Rejects missing sources and existing destinations. */
+    rename(oldPath: string, newPath: string): Promise<void>;
+    /** List immediate children of a directory. */
+    readDirectory(path: string): Promise<FileSystemEntry[]>;
+    /** Check whether a path exists. */
+    exists(path: string): Promise<boolean>;
+    /** Create a directory (and parents if needed). */
+    createDirectory(path: string): Promise<void>;
+    /** Get metadata for a file. Returns null if not found. */
+    stat(path: string): Promise<FileMeta | null>;
+    /** Read raw binary content. Returns null if not found. */
+    readBinary(path: string): Promise<ArrayBuffer | null>;
+    /** Write raw binary content. */
+    writeBinary(path: string, data: ArrayBuffer | Uint8Array): Promise<void>;
+}
+type FileSystemProviderWithV2 = FileSystemProvider & {
+    readonly v2: FileSystemProviderV2;
+};
+/** Discover a provider-owned v2 implementation without coupling consumers to a concrete class. */
+declare function hasFileSystemProviderV2(provider: FileSystemProvider): provider is FileSystemProviderWithV2;
+/** Return the provider-owned v2 implementation when migration support is available. */
+declare function getFileSystemProviderV2(provider: FileSystemProvider): FileSystemProviderV2 | null;
+
+export { tryParseFileSystemVersion as $, type FileSystemVersion as A, type FileSystemWatchErrorListener as B, type FileSystemWatchEvent as C, type FileSystemWatchEventOrigin as D, type FileSystemWatchEventType as E, type FileCommitResult as F, type FileSystemWatchListener as G, type FileSystemWatchOptions as H, type FileSystemWatchSubscription as I, type FileSystemWriteMode as J, type FileSystemWriteOptions as K, type FolderEntry as L, FsError as M, type FsErrorCode as N, type FsErrorContext as O, type FsOperation as P, deserializeFsError as Q, fsErrorFromUnknown as R, type SerializedFsError as S, getFileSystemProviderV2 as T, hasFileSystemProviderV2 as U, isQuotaExceededError as V, isSerializedFsError as W, mapDomExceptionToFsErrorCode as X, mapNodeErrorCodeToFsErrorCode as Y, parseFileSystemVersion as Z, serializeFsError as _, type FileEntry as a, type FileMeta as b, type FileSystemAtomicity as c, type FileSystemCaseSensitivity as d, type FileSystemConditionalWriteStrength as e, type FileSystemCreateDirectoryMode as f, type FileSystemCreateDirectoryOptions as g, type FileSystemDirectorySnapshot as h, type FileSystemDurability as i, type FileSystemEntry as j, type FileSystemEntrySnapshot as k, type FileSystemEntryWatchEvent as l, type FileSystemFileRead as m, type FileSystemFileSnapshot as n, type FileSystemMoveOptions as o, type FileSystemOverflowWatchEvent as p, type FileSystemProvider as q, type FileSystemProviderCapabilities as r, type FileSystemProviderV2 as s, type FileSystemProviderWithV2 as t, type FileSystemRemoveOptions as u, type FileSystemRemoveResult as v, type FileSystemSnapshot as w, type FileSystemSnapshotEntry as x, type FileSystemSnapshotFile as y, type FileSystemSymlinkPolicy as z };