@xfcfam/xf-fs 0.1.0

package/dist/src/repository/base/AuditedFileRepository.js.map

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

package/dist/src/repository/base/CachedFileRepository.d.ts

@@ -0,0 +1,53 @@
+import { FileRepository, type FileOptions } from './FileRepository.js';
+/**
+ * Generalization for Access Layer components that need an in-memory
+ * cache over the local filesystem.
+ *
+ * Same protocol as {@link FileRepository} — every public method
+ * preserves the parent's signature and semantics. This subclass adds
+ * a cross-cutting **caching policy**: results of `read()` and
+ * `readBytes()` are memoised in a per-instance map and served from
+ * memory until the path is mutated via this Repository.
+ *
+ * **Coherence model: write-through.** Mutations performed through
+ * this Repository (`write`, `append`, `delete`, `rmdir`) invalidate
+ * the cache entry for the affected path. Mutations performed by
+ * other processes (or by other `FileRepository` instances) are NOT
+ * detected — callers in those scenarios should invoke
+ * {@link clearCache} (or per-path {@link invalidateCache}) to force a
+ * fresh read.
+ *
+ * **What's not cached:** `stat`, `list`, `walk`, `exists`, streams,
+ * and `watch` always hit the filesystem. Caching directory listings
+ * across mutations is a separate design decision and out of scope
+ * for the v0 implementation.
+ *
+ * @example
+ * ```ts
+ * import { CachedFileRepository } from '@xfarch/xf-fs'
+ *
+ * export class TemplatesFileRepository extends CachedFileRepository {
+ *   constructor() { super({ rootPath: '/etc/app/templates' }) }
+ *   loadTemplate(name: string) { return this.read(`${name}.tpl`) }
+ * }
+ * ```
+ */
+export declare abstract class CachedFileRepository extends FileRepository {
+    private readonly textCache;
+    private readonly bytesCache;
+    constructor(options?: FileOptions);
+    terminate(): Promise<void>;
+    read(path: string): Promise<string>;
+    readBytes(path: string): Promise<Uint8Array>;
+    write(path: string, content: string | Uint8Array): Promise<void>;
+    append(path: string, content: string | Uint8Array): Promise<void>;
+    delete(path: string): Promise<void>;
+    rmdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    /** Drop the cache entry for a single path. */
+    protected invalidateCache(path: string): void;
+    /** Drop every cache entry. Use after external mutations. */
+    protected clearCache(): void;
+}
+//# sourceMappingURL=CachedFileRepository.d.ts.map

package/dist/src/repository/base/CachedFileRepository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CachedFileRepository.d.ts","sourceRoot":"","sources":["../../../../src/repository/base/CachedFileRepository.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,8BAAsB,oBAAqB,SAAQ,cAAc;IAC/D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyB;gBAExC,OAAO,GAAE,WAAgB;IAMtB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAM1B,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IASnC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAS5C,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAKhE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKnC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAaxF,8CAA8C;IAC9C,SAAS,CAAC,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAM7C,4DAA4D;IAC5D,SAAS,CAAC,UAAU,IAAI,IAAI;CAI7B"}

package/dist/src/repository/base/CachedFileRepository.js

@@ -0,0 +1,107 @@
+import { FileRepository } from './FileRepository.js';
+/**
+ * Generalization for Access Layer components that need an in-memory
+ * cache over the local filesystem.
+ *
+ * Same protocol as {@link FileRepository} — every public method
+ * preserves the parent's signature and semantics. This subclass adds
+ * a cross-cutting **caching policy**: results of `read()` and
+ * `readBytes()` are memoised in a per-instance map and served from
+ * memory until the path is mutated via this Repository.
+ *
+ * **Coherence model: write-through.** Mutations performed through
+ * this Repository (`write`, `append`, `delete`, `rmdir`) invalidate
+ * the cache entry for the affected path. Mutations performed by
+ * other processes (or by other `FileRepository` instances) are NOT
+ * detected — callers in those scenarios should invoke
+ * {@link clearCache} (or per-path {@link invalidateCache}) to force a
+ * fresh read.
+ *
+ * **What's not cached:** `stat`, `list`, `walk`, `exists`, streams,
+ * and `watch` always hit the filesystem. Caching directory listings
+ * across mutations is a separate design decision and out of scope
+ * for the v0 implementation.
+ *
+ * @example
+ * ```ts
+ * import { CachedFileRepository } from '@xfarch/xf-fs'
+ *
+ * export class TemplatesFileRepository extends CachedFileRepository {
+ *   constructor() { super({ rootPath: '/etc/app/templates' }) }
+ *   loadTemplate(name: string) { return this.read(`${name}.tpl`) }
+ * }
+ * ```
+ */
+export class CachedFileRepository extends FileRepository {
+    textCache;
+    bytesCache;
+    constructor(options = {}) {
+        super(options);
+        this.textCache = new Map();
+        this.bytesCache = new Map();
+    }
+    async terminate() {
+        this.textCache.clear();
+        this.bytesCache.clear();
+        await super.terminate();
+    }
+    async read(path) {
+        const abs = this.resolve(path);
+        const cached = this.textCache.get(abs);
+        if (cached !== undefined)
+            return cached;
+        const content = await super.read(path);
+        this.textCache.set(abs, content);
+        return content;
+    }
+    async readBytes(path) {
+        const abs = this.resolve(path);
+        const cached = this.bytesCache.get(abs);
+        if (cached !== undefined)
+            return cached;
+        const content = await super.readBytes(path);
+        this.bytesCache.set(abs, content);
+        return content;
+    }
+    async write(path, content) {
+        await super.write(path, content);
+        this.invalidateCache(path);
+    }
+    async append(path, content) {
+        await super.append(path, content);
+        this.invalidateCache(path);
+    }
+    async delete(path) {
+        await super.delete(path);
+        this.invalidateCache(path);
+    }
+    async rmdir(path, options = {}) {
+        await super.rmdir(path, options);
+        if (options.recursive === true) {
+            // Recursive removal: drop every cache entry under this directory.
+            const abs = this.resolve(path);
+            const prefix = abs.endsWith('/') ? abs : `${abs}/`;
+            for (const k of this.textCache.keys())
+                if (k === abs || k.startsWith(prefix))
+                    this.textCache.delete(k);
+            for (const k of this.bytesCache.keys())
+                if (k === abs || k.startsWith(prefix))
+                    this.bytesCache.delete(k);
+        }
+        else {
+            this.invalidateCache(path);
+        }
+    }
+    /** Drop the cache entry for a single path. */
+    invalidateCache(path) {
+        const abs = this.resolve(path);
+        this.textCache.delete(abs);
+        this.bytesCache.delete(abs);
+    }
+    /** Drop every cache entry. Use after external mutations. */
+    clearCache() {
+        this.textCache.clear();
+        this.bytesCache.clear();
+    }
+}
+//# sourceMappingURL=CachedFileRepository.js.map

package/dist/src/repository/base/CachedFileRepository.js.map

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

package/dist/src/repository/base/FileRepository.d.ts

@@ -0,0 +1,170 @@
+import { Repository } from '@xfarch/xf';
+import type { FileEntry } from '../structs/FileEntry.js';
+import type { FileStat } from '../structs/FileStat.js';
+import type { Watcher } from '../structs/Watcher.js';
+import type { TempFile } from '../structs/TempFile.js';
+import type { WatchEvent } from '../structs/WatchEvent.js';
+/**
+ * Configuration accepted by {@link FileRepository}'s constructor.
+ *
+ * `rootPath` becomes the implicit root for every relative path passed
+ * to a Repository method; absolute paths are accepted as-is. This
+ * mirrors the way `RestRepository.baseUrl` anchors REST requests.
+ */
+export interface FileOptions {
+    /**
+     * If set, every relative path passed to a method is resolved against
+     * this directory. Absolute paths bypass it. Defaults to the current
+     * working directory.
+     */
+    readonly rootPath?: string;
+}
+interface FileRepoState {
+    readonly rootPath: string;
+    readonly openWatchers: Set<WatcherImpl>;
+    readonly openTempFiles: Set<TempFileImpl>;
+}
+/**
+ * Generalization for Access Layer components that operate on the
+ * local filesystem.
+ *
+ * The protocol is "local filesystem" — every method on this class is
+ * a syscall (or a tight wrapper over one) translated into the XF
+ * Transfer projection: file content as `string` / `Uint8Array`,
+ * metadata as {@link FileStat}, directory entries as
+ * {@link FileEntry}, change events as {@link WatchEvent}, and active
+ * handles as {@link Watcher} / {@link TempFile}.
+ *
+ * Concrete components extend this class to expose business-meaningful
+ * methods that compose the base operations (e.g. `loadProfile()`
+ * calls `this.read('/users/profile.json')` then `JSON.parse`).
+ *
+ * Errors raised by `node:fs` are translated into typed Exception
+ * components ({@link FileNotFoundException},
+ * {@link FileAccessDeniedException},
+ * {@link DirectoryNotEmptyException}) so the Business Layer never
+ * inspects `errno` strings. Other failures propagate as native
+ * `Error` (consistent with the XF doctrine that runtime exceptions
+ * are well-formed transfer vehicles).
+ *
+ * `terminate()` releases every still-active {@link Watcher} and
+ * deletes every still-open {@link TempFile}: even careless callers
+ * won't leak OS handles.
+ *
+ * @example
+ * ```ts
+ * import { FileRepository } from '@xfarch/xf-fs'
+ * import type { User } from '../structs/User.js'
+ *
+ * export class UsersFileRepository extends FileRepository {
+ *   constructor() { super({ rootPath: '/var/data/users' }) }
+ *
+ *   async findById(id: string): Promise<User> {
+ *     const text = await this.read(`${id}.json`)
+ *     return JSON.parse(text) as User
+ *   }
+ *
+ *   async save(user: User): Promise<void> {
+ *     await this.write(`${user.id}.json`, JSON.stringify(user))
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class FileRepository extends Repository<FileRepoState> {
+    constructor(options?: FileOptions);
+    init(): Promise<void>;
+    terminate(): Promise<void>;
+    /**
+     * Resolve a path against `rootPath`. Absolute paths are returned
+     * unchanged (with separators normalised); relative paths are joined
+     * to the root.
+     */
+    protected resolve(path: string): string;
+    /** Read a file as UTF-8 text. */
+    read(path: string): Promise<string>;
+    /** Read a file as raw bytes. */
+    readBytes(path: string): Promise<Uint8Array>;
+    /**
+     * Write `content` to `path`, overwriting any existing file.
+     * Parent directories must already exist; use `mkdir` first if not.
+     */
+    write(path: string, content: string | Uint8Array): Promise<void>;
+    /** Append `content` to the end of `path` (creating it if absent). */
+    append(path: string, content: string | Uint8Array): Promise<void>;
+    /** Delete the file at `path`. Throws {@link FileNotFoundException} if absent. */
+    delete(path: string): Promise<void>;
+    /** Whether the path exists (file, directory, link, anything). */
+    exists(path: string): Promise<boolean>;
+    /** Stat `path`. Throws {@link FileNotFoundException} if absent. */
+    stat(path: string): Promise<FileStat>;
+    /** List immediate entries of a directory (not recursive). */
+    list(path: string): Promise<FileEntry[]>;
+    /**
+     * Walk a directory recursively. Returns every regular file and
+     * directory under `path`. `relativePath` is computed relative to
+     * the walk root.
+     */
+    walk(path: string): Promise<FileEntry[]>;
+    private walkInto;
+    /** Create a directory. `recursive` creates intermediate parents. */
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    /**
+     * Remove a directory. By default the directory must be empty;
+     * pass `{ recursive: true }` to delete contents too.
+     */
+    rmdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    /**
+     * Open a streaming reader for `path` as a Web `ReadableStream`.
+     * Useful for large files (> a few MB) where buffering the whole
+     * content in memory is wasteful.
+     */
+    readStream(path: string): ReadableStream<Uint8Array>;
+    /**
+     * Open a streaming writer for `path` as a Web `WritableStream`.
+     * Overwrites any existing content.
+     */
+    writeStream(path: string): WritableStream<Uint8Array>;
+    /**
+     * Watch a file or directory for changes. `callback` is invoked
+     * synchronously by the OS for each event. Recursive watches are
+     * supported only on macOS and Windows; on Linux, recursive emulation
+     * is not built in (callers can stack multiple watchers).
+     */
+    watch(path: string, callback: (event: WatchEvent) => void): Promise<Watcher>;
+    /**
+     * Create a unique temporary file under the OS temp directory. The
+     * file exists empty on disk; callers write/read it via `read()` /
+     * `write()` passing `tempFile.path`. Closing the returned handle
+     * deletes the file. `terminate()` closes all outstanding handles.
+     */
+    tempFile(prefix?: string): Promise<TempFile>;
+    /**
+     * Translate a `node:fs` error into a typed Exception component when
+     * the error code is one of the modelled cases; otherwise return the
+     * error unchanged for plain propagation.
+     */
+    protected translateError(err: unknown, path: string): unknown;
+}
+declare class WatcherImpl implements Watcher {
+    readonly path: string;
+    private handle;
+    private active;
+    private readonly registry;
+    constructor(path: string, callback: (event: WatchEvent) => void, registry: Set<WatcherImpl>);
+    get isActive(): boolean;
+    close(): Promise<void>;
+}
+declare class TempFileImpl implements TempFile {
+    readonly path: string;
+    private open;
+    private readonly registry;
+    constructor(path: string, registry: Set<TempFileImpl>);
+    get isOpen(): boolean;
+    close(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=FileRepository.d.ts.map

package/dist/src/repository/base/FileRepository.d.ts.map

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