typescript-virtual-container 1.2.4 → 1.2.6

package/dist/VirtualFileSystem/index.d.ts

@@ -1,127 +1,154 @@
 import { EventEmitter } from "node:events";
-import type { RemoveOptions, VfsNodeStats, WriteFileOptions } from "../types/vfs";
+import type { RemoveOptions, VfsNodeStats, VfsSnapshot, WriteFileOptions } from "../types/vfs";
+/**
+ * "memory" — pure in-memory, no disk I/O (default).
+ *
+ * "fs"     — mirrors the VFS tree to a directory on the host filesystem.
+ *             `snapshotPath` must be set to the directory where the JSON
+ *             snapshot file will be read/written.
+ */
+export type VfsPersistenceMode = "memory" | "fs";
+export interface VfsOptions {
+    /**
+     * Persistence mode.
+     * - `"memory"` (default): no disk access, snapshot via `toSnapshot()`.
+     * - `"fs"`: auto-save JSON snapshot to `snapshotPath` on every
+     *   `flushMirror()` call, and restore from it on `restoreMirror()`.
+     */
+    mode?: VfsPersistenceMode;
+    /**
+     * Directory used by `"fs"` mode.
+     * The snapshot file will be written to `<snapshotPath>/vfs-snapshot.json`.
+     * Required when `mode` is `"fs"`.
+     */
+    snapshotPath?: string;
+}
+/**
+ * In-memory virtual filesystem with optional JSON-snapshot persistence.
+ *
+ * **Memory mode** (default) — all state lives in a fast recursive tree.
+ * Use `toSnapshot()` / `fromSnapshot()` / `importSnapshot()` for serialisation.
+ *
+ * **FS mode** — same in-memory tree, but `restoreMirror()` loads a JSON
+ * snapshot from disk and `flushMirror()` writes it back.  This gives you
+ * persistent VFS state across process restarts without any real POSIX filesystem
+ * semantics leaking through.
+ *
+ * @example
+ * ```ts
+ * // Pure in-memory (default)
+ * const vfs = new VirtualFileSystem();
+ *
+ * // With disk persistence
+ * const vfs = new VirtualFileSystem({ mode: "fs", snapshotPath: "./data" });
+ * await vfs.restoreMirror(); // load from disk (no-op if no snapshot yet)
+ * // ... use vfs ...
+ * await vfs.flushMirror();  // persist to disk
+ * ```
+ */
 declare class VirtualFileSystem extends EventEmitter {
-    private readonly mirrorRoot;
-    private ensureMirrorRoot;
-    private resolveFsPath;
-    private detectGzipFile;
-    private computeDiskUsageBytes;
-    private renderTreeLines;
-    /**
-     * Creates a virtual filesystem instance.
-     *
-     * @param baseDir Base directory used to resolve mirror archive location.
-     */
-    constructor(baseDir?: string);
+    private root;
+    private readonly mode;
+    private readonly snapshotFile;
+    constructor(options?: VfsOptions);
+    private makeDir;
+    private makeFile;
+    private mkdirRecursive;
     /**
-     * Restores filesystem state from mirror archive.
+     * In `"fs"` mode: reads the JSON snapshot from disk and hydrates the tree.
+     * Silently succeeds when the snapshot file does not exist yet.
      *
-     * If archive does not exist or cannot be read, creates fresh mirror file.
+     * In `"memory"` mode: no-op (kept for API compatibility).
      */
     restoreMirror(): Promise<void>;
     /**
-     * Persists current filesystem state to mirror archive.
+     * In `"fs"` mode: serialises the in-memory tree to a JSON snapshot on disk.
+     * The directory is created if it does not exist.
      *
-     * No-op when nothing changed and archive already exists.
+     * In `"memory"` mode: emits `"mirror:flush"` and returns (no disk write).
      */
     flushMirror(): Promise<void>;
-    /**
-     * Creates directory and any missing parent directories.
-     *
-     * @param targetPath Absolute or relative path to directory.
-     * @param mode POSIX-like mode bits for new directories.
-     */
+    /** Returns the current persistence mode. */
+    getMode(): VfsPersistenceMode;
+    /** Returns the snapshot file path used in `"fs"` mode, or `null`. */
+    getSnapshotPath(): string | null;
+    /** Creates a directory (and any missing parents). */
     mkdir(targetPath: string, mode?: number): void;
     /**
-     * Writes UTF-8 text or binary content into file.
-     *
+     * Writes UTF-8 text or binary content into a file.
      * Parent directories are created when missing.
-     *
-     * @param targetPath Destination file path.
-     * @param content File content as string or Buffer.
-     * @param options Optional write behavior (mode, compression).
      */
     writeFile(targetPath: string, content: string | Buffer, options?: WriteFileOptions): void;
     /**
-     * Reads file content as UTF-8 text.
-     *
-     * Compressed files are transparently decompressed.
-     *
-     * @param targetPath Path to file.
-     * @returns UTF-8 string content.
+     * Reads file content as a UTF-8 string.
+     * Gzip-compressed files are transparently decompressed.
      */
     readFile(targetPath: string): string;
-    /**
-     * Checks whether node exists at path.
-     *
-     * @param targetPath Node path.
-     * @returns True when file or directory exists.
-     */
+    /** Reads file content as a Buffer (decompresses if needed). */
+    readFileRaw(targetPath: string): Buffer;
+    /** Returns true when a file or directory exists at path. */
     exists(targetPath: string): boolean;
-    /**
-     * Updates mode bits for file or directory.
-     *
-     * @param targetPath Node path.
-     * @param mode New POSIX-like mode.
-     */
+    /** Updates mode bits on a node. */
     chmod(targetPath: string, mode: number): void;
-    /**
-     * Returns metadata for file or directory.
-     *
-     * @param targetPath Node path.
-     * @returns Typed stat object based on node type.
-     */
+    /** Returns metadata for a file or directory. */
     stat(targetPath: string): VfsNodeStats;
-    /**
-     * Lists direct children names of directory.
-     *
-     * @param dirPath Directory path, defaults to root.
-     * @returns Sorted child names.
-     */
+    /** Lists direct children names of a directory (sorted). */
     list(dirPath?: string): string[];
-    /**
-     * Renders ASCII tree view of directory hierarchy.
-     *
-     * @param dirPath Directory path, defaults to root.
-     * @returns Multi-line tree string.
-     */
+    /** Renders ASCII tree view of a directory hierarchy. */
     tree(dirPath?: string): string;
+    private renderTreeLines;
+    /** Computes total stored bytes under a path. */
+    getUsageBytes(targetPath?: string): number;
+    private computeUsage;
+    /** Compresses a file's content with gzip in place. */
+    compressFile(targetPath: string): void;
+    /** Decompresses a gzip-compressed file in place. */
+    decompressFile(targetPath: string): void;
     /**
-     * Computes total stored file bytes under a path.
-     *
-     * File usage is based on in-memory stored bytes, including compressed
-     * payload size when files are marked as compressed.
-     *
-     * @param targetPath File or directory path to measure, defaults to root.
-     * @returns Total byte usage for file content under target path.
+     * Creates a symbolic link.
+     * The link node is stored with mode `0o120777` (POSIX symlink convention).
      */
-    getUsageBytes(targetPath?: string): number;
+    symlink(targetPath: string, linkPath: string): void;
+    /** Returns true when the path is a symbolic link node. */
+    isSymlink(targetPath: string): boolean;
     /**
-     * Compresses file content with gzip and flags node as compressed.
-     *
-     * @param targetPath Path to file.
+     * Resolves a symlink chain up to `maxDepth` hops.
+     * Throws when the chain is too long (circular links).
      */
-    compressFile(targetPath: string): void;
+    resolveSymlink(linkPath: string, maxDepth?: number): string;
+    /** Removes a file or directory node. */
+    remove(targetPath: string, options?: RemoveOptions): void;
+    /** Moves or renames a node. */
+    move(fromPath: string, toPath: string): void;
     /**
-     * Decompresses gzip-compressed file content.
+     * Exports the entire filesystem as a JSON-serialisable snapshot.
      *
-     * @param targetPath Path to file.
+     * Works regardless of the persistence mode. Useful for test fixtures,
+     * manual backups, or passing VFS state between processes.
      */
-    decompressFile(targetPath: string): void;
+    toSnapshot(): VfsSnapshot;
+    private serializeDir;
+    private serializeFile;
     /**
-     * Removes file or directory node.
+     * Creates a new `VirtualFileSystem` instance (memory mode) from a snapshot.
      *
-     * @param targetPath Path to remove.
-     * @param options Removal options, including recursive delete.
+     * @example
+     * ```ts
+     * const vfs = VirtualFileSystem.fromSnapshot(savedSnapshot);
+     * ```
      */
-    remove(targetPath: string, options?: RemoveOptions): void;
+    static fromSnapshot(snapshot: VfsSnapshot): VirtualFileSystem;
     /**
-     * Moves or renames node to destination path.
+     * Replaces the current filesystem state with the content of a snapshot.
+     * The persistence mode is preserved.
      *
-     * @param fromPath Existing source path.
-     * @param toPath Destination path.
+     * @example
+     * ```ts
+     * vfs.importSnapshot(savedSnapshot);
+     * ```
      */
-    move(fromPath: string, toPath: string): void;
+    importSnapshot(snapshot: VfsSnapshot): void;
+    private deserializeDir;
 }
 export default VirtualFileSystem;
 //# sourceMappingURL=index.d.ts.map

package/dist/VirtualFileSystem/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/VirtualFileSystem/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAI3C,OAAO,KAAK,EACX,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,MAAM,cAAc,CAAC;AActB,cAAM,iBAAkB,SAAQ,YAAY;IAC3C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,OAAO,CAAC,gBAAgB;IAIxB,OAAO,CAAC,aAAa;IAarB,OAAO,CAAC,cAAc;IAWtB,OAAO,CAAC,qBAAqB;IAa7B,OAAO,CAAC,eAAe;IA4BvB;;;;OAIG;gBACS,OAAO,GAAE,MAAsB;IAM3C;;;;OAIG;IACU,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAK3C;;;;OAIG;IACU,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAMzC;;;;;OAKG;IACI,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,MAAc,GAAG,IAAI;IAa5D;;;;;;;;OAQG;IACI,SAAS,CACf,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,OAAO,GAAE,gBAAqB,GAC5B,IAAI;IAyBP;;;;;;;OAOG;IACI,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;IAe3C;;;;;OAKG;IACI,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAU1C;;;;;OAKG;IACI,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IASpD;;;;;OAKG;IACI,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY;IAsC7C;;;;;OAKG;IACI,IAAI,CAAC,OAAO,GAAE,MAAY,GAAG,MAAM,EAAE;IAU5C;;;;;OAKG;IACI,IAAI,CAAC,OAAO,GAAE,MAAY,GAAG,MAAM;IAY1C;;;;;;;;OAQG;IACI,aAAa,CAAC,UAAU,GAAE,MAAY,GAAG,MAAM;IAStD;;;;OAIG;IACI,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAa7C;;;;OAIG;IACI,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAa/C;;;;;OAKG;IACI,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,IAAI;IA6BpE;;;;;OAKG;IACI,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;CAuBnD;AAED,eAAe,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/VirtualFileSystem/index.ts"],"names":[],"mappings":"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"}