@xfcfam/xf-fs 0.1.0

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

@@ -0,0 +1,382 @@
+import { Repository } from '@xfarch/xf';
+import { promises as fsp, createReadStream, createWriteStream, watch as fsWatch } from 'node:fs';
+import { Readable, Writable } from 'node:stream';
+import { tmpdir } from 'node:os';
+import { posix } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { FileNotFoundException } from '../structs/FileNotFoundException.js';
+import { FileAccessDeniedException } from '../structs/FileAccessDeniedException.js';
+import { DirectoryNotEmptyException } from '../structs/DirectoryNotEmptyException.js';
+import { PathUtils } from '../utils/PathUtils.js';
+/**
+ * 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 class FileRepository extends Repository {
+    constructor(options = {}) {
+        super({
+            rootPath: options.rootPath ?? process.cwd(),
+            openWatchers: new Set(),
+            openTempFiles: new Set(),
+        });
+    }
+    async init() { }
+    async terminate() {
+        // Close every still-active watcher.
+        for (const w of [...this.state.openWatchers]) {
+            try {
+                await w.close();
+            }
+            catch { /* swallow on shutdown */ }
+        }
+        // Delete every still-open temp file.
+        for (const t of [...this.state.openTempFiles]) {
+            try {
+                await t.close();
+            }
+            catch { /* swallow on shutdown */ }
+        }
+    }
+    // ─── Path resolution ──────────────────────────────────────
+    /**
+     * Resolve a path against `rootPath`. Absolute paths are returned
+     * unchanged (with separators normalised); relative paths are joined
+     * to the root.
+     */
+    resolve(path) {
+        const normalised = PathUtils.normalize(path);
+        if (PathUtils.isAbsolute(normalised))
+            return normalised;
+        return PathUtils.join(this.state.rootPath, normalised);
+    }
+    // ─── File operations ──────────────────────────────────────
+    /** Read a file as UTF-8 text. */
+    async read(path) {
+        const abs = this.resolve(path);
+        try {
+            return await fsp.readFile(abs, 'utf-8');
+        }
+        catch (err) {
+            throw this.translateError(err, abs);
+        }
+    }
+    /** Read a file as raw bytes. */
+    async readBytes(path) {
+        const abs = this.resolve(path);
+        try {
+            const buf = await fsp.readFile(abs);
+            return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+        }
+        catch (err) {
+            throw this.translateError(err, abs);
+        }
+    }
+    /**
+     * Write `content` to `path`, overwriting any existing file.
+     * Parent directories must already exist; use `mkdir` first if not.
+     */
+    async write(path, content) {
+        const abs = this.resolve(path);
+        try {
+            await fsp.writeFile(abs, content);
+        }
+        catch (err) {
+            throw this.translateError(err, abs);
+        }
+    }
+    /** Append `content` to the end of `path` (creating it if absent). */
+    async append(path, content) {
+        const abs = this.resolve(path);
+        try {
+            await fsp.appendFile(abs, content);
+        }
+        catch (err) {
+            throw this.translateError(err, abs);
+        }
+    }
+    /** Delete the file at `path`. Throws {@link FileNotFoundException} if absent. */
+    async delete(path) {
+        const abs = this.resolve(path);
+        try {
+            await fsp.unlink(abs);
+        }
+        catch (err) {
+            throw this.translateError(err, abs);
+        }
+    }
+    /** Whether the path exists (file, directory, link, anything). */
+    async exists(path) {
+        const abs = this.resolve(path);
+        try {
+            await fsp.access(abs);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Stat `path`. Throws {@link FileNotFoundException} if absent. */
+    async stat(path) {
+        const abs = this.resolve(path);
+        try {
+            const s = await fsp.lstat(abs);
+            return {
+                path: abs,
+                size: s.size,
+                modifiedAt: s.mtime,
+                createdAt: s.birthtime ?? s.mtime,
+                isFile: s.isFile(),
+                isDirectory: s.isDirectory(),
+                isSymlink: s.isSymbolicLink(),
+                mode: s.mode,
+            };
+        }
+        catch (err) {
+            throw this.translateError(err, abs);
+        }
+    }
+    // ─── Directory operations ─────────────────────────────────
+    /** List immediate entries of a directory (not recursive). */
+    async list(path) {
+        const abs = this.resolve(path);
+        try {
+            const entries = await fsp.readdir(abs, { withFileTypes: true });
+            const out = [];
+            for (const e of entries) {
+                const full = PathUtils.join(abs, e.name);
+                out.push({
+                    path: full,
+                    relativePath: e.name,
+                    name: e.name,
+                    isFile: e.isFile(),
+                    isDirectory: e.isDirectory(),
+                    isSymlink: e.isSymbolicLink(),
+                });
+            }
+            out.sort((a, b) => a.name.localeCompare(b.name));
+            return out;
+        }
+        catch (err) {
+            throw this.translateError(err, abs);
+        }
+    }
+    /**
+     * Walk a directory recursively. Returns every regular file and
+     * directory under `path`. `relativePath` is computed relative to
+     * the walk root.
+     */
+    async walk(path) {
+        const root = this.resolve(path);
+        const out = [];
+        await this.walkInto(root, root, out);
+        out.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+        return out;
+    }
+    async walkInto(current, root, out) {
+        let entries;
+        try {
+            entries = await fsp.readdir(current, { withFileTypes: true });
+        }
+        catch (err) {
+            throw this.translateError(err, current);
+        }
+        for (const e of entries) {
+            const full = PathUtils.join(current, e.name);
+            const rel = posix.relative(root, full);
+            out.push({
+                path: full,
+                relativePath: rel,
+                name: e.name,
+                isFile: e.isFile(),
+                isDirectory: e.isDirectory(),
+                isSymlink: e.isSymbolicLink(),
+            });
+            if (e.isDirectory())
+                await this.walkInto(full, root, out);
+        }
+    }
+    /** Create a directory. `recursive` creates intermediate parents. */
+    async mkdir(path, options = {}) {
+        const abs = this.resolve(path);
+        try {
+            await fsp.mkdir(abs, { recursive: options.recursive ?? false });
+        }
+        catch (err) {
+            throw this.translateError(err, abs);
+        }
+    }
+    /**
+     * Remove a directory. By default the directory must be empty;
+     * pass `{ recursive: true }` to delete contents too.
+     */
+    async rmdir(path, options = {}) {
+        const abs = this.resolve(path);
+        try {
+            if (options.recursive === true) {
+                await fsp.rm(abs, { recursive: true, force: true });
+            }
+            else {
+                await fsp.rmdir(abs);
+            }
+        }
+        catch (err) {
+            throw this.translateError(err, abs);
+        }
+    }
+    // ─── Streaming ────────────────────────────────────────────
+    /**
+     * 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) {
+        const abs = this.resolve(path);
+        const node = createReadStream(abs);
+        return Readable.toWeb(node);
+    }
+    /**
+     * Open a streaming writer for `path` as a Web `WritableStream`.
+     * Overwrites any existing content.
+     */
+    writeStream(path) {
+        const abs = this.resolve(path);
+        const node = createWriteStream(abs);
+        return Writable.toWeb(node);
+    }
+    // ─── Watching ─────────────────────────────────────────────
+    /**
+     * 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).
+     */
+    async watch(path, callback) {
+        const abs = this.resolve(path);
+        if (!(await this.exists(abs)))
+            throw new FileNotFoundException(abs);
+        const watcher = new WatcherImpl(abs, callback, this.state.openWatchers);
+        this.state.openWatchers.add(watcher);
+        return watcher;
+    }
+    // ─── Temp files ───────────────────────────────────────────
+    /**
+     * 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.
+     */
+    async tempFile(prefix = 'xf-fs-') {
+        const name = `${prefix}${randomBytes(8).toString('hex')}`;
+        const abs = posix.join(tmpdir().replace(/\\/g, '/'), name);
+        await fsp.writeFile(abs, '');
+        const handle = new TempFileImpl(abs, this.state.openTempFiles);
+        this.state.openTempFiles.add(handle);
+        return handle;
+    }
+    // ─── Error translation ────────────────────────────────────
+    /**
+     * 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.
+     */
+    translateError(err, path) {
+        if (typeof err !== 'object' || err === null)
+            return err;
+        const code = err.code;
+        if (code === 'ENOENT')
+            return new FileNotFoundException(path);
+        if (code === 'EACCES' || code === 'EPERM')
+            return new FileAccessDeniedException(path);
+        if (code === 'ENOTEMPTY')
+            return new DirectoryNotEmptyException(path);
+        return err;
+    }
+}
+// ─── Concrete Transfer implementations ───────────────────────
+class WatcherImpl {
+    path;
+    handle;
+    active = true;
+    registry;
+    constructor(path, callback, registry) {
+        this.path = path;
+        this.registry = registry;
+        this.handle = fsWatch(path, { recursive: process.platform !== 'linux' }, (eventType, filename) => {
+            const childPath = filename === null ? path : posix.join(path.replace(/\\/g, '/'), filename.toString());
+            const kind = eventType === 'rename' ? 'renamed' : 'modified';
+            callback({ path: childPath, kind });
+        });
+    }
+    get isActive() { return this.active; }
+    async close() {
+        if (!this.active)
+            return;
+        this.active = false;
+        this.registry.delete(this);
+        this.handle?.close();
+        this.handle = undefined;
+    }
+}
+class TempFileImpl {
+    path;
+    open = true;
+    registry;
+    constructor(path, registry) {
+        this.path = path;
+        this.registry = registry;
+    }
+    get isOpen() { return this.open; }
+    async close() {
+        if (!this.open)
+            return;
+        this.open = false;
+        this.registry.delete(this);
+        try {
+            await fsp.unlink(this.path);
+        }
+        catch { /* already gone */ }
+    }
+}
+//# sourceMappingURL=FileRepository.js.map

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

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

package/dist/src/repository/general/AuditedFileRepository.d.ts

@@ -0,0 +1,86 @@
+import { FileRepository } from './FileRepository.js';
+import type { FileEntry } from '../transfers/FileEntry.js';
+import type { FileStat } from '../transfers/FileStat.js';
+import type { Watcher } from '../transfers/Watcher.js';
+import type { TempFile } from '../transfers/TempFile.js';
+import type { WatchEvent } from '../transfers/WatchEvent.js';
+/**
+ * Canonical operations of a `FileRepository`, used as the discriminator
+ * passed to the {@link AuditedFileRepository.onError} hook so a single
+ * handler can branch on the operation that failed.
+ */
+export type FileOperation = 'read' | 'readBytes' | 'write' | 'append' | 'delete' | 'exists' | 'stat' | 'list' | 'walk' | 'mkdir' | 'rmdir' | 'readStream' | 'writeStream' | 'watch' | 'tempFile';
+/**
+ * Generalization for Access Layer components that need to observe
+ * every filesystem operation — for audit logs, metrics, security
+ * tracing, or invalidation of higher-level caches.
+ *
+ * Same protocol as {@link FileRepository}; this subclass adds a
+ * cross-cutting **observability policy**. Every public method is
+ * intercepted: on success the matching `onX` hook is invoked with
+ * the operation's path and result summary; on failure `onError` is
+ * invoked with the operation name, path, and the (possibly
+ * translated) error before it is re-thrown.
+ *
+ * Hooks default to no-ops. Subclasses override only the ones they
+ * care about. They may be async — the interceptor `await`s them, so
+ * a hook can hit a remote logger or block briefly without losing
+ * events.
+ *
+ * @example
+ * ```ts
+ * import { AuditedFileRepository } from '@xfcfam/xf-fs'
+ *
+ * export class AuditedConfigRepository extends AuditedFileRepository {
+ *   constructor() { super({ rootPath: '/etc/app' }) }
+ *
+ *   override async onWrite(path: string, sizeBytes: number) {
+ *     await this.appendAuditLog(`WRITE ${path} ${sizeBytes}B`)
+ *   }
+ *   override async onError(op: FileOperation, path: string, err: unknown) {
+ *     await this.appendAuditLog(`${op.toUpperCase()} FAIL ${path}: ${String(err)}`)
+ *   }
+ *
+ *   private async appendAuditLog(line: string) {  ... }
+ * }
+ * ```
+ */
+export declare abstract class AuditedFileRepository extends FileRepository {
+    protected onRead(_path: string, _sizeBytes: number): Promise<void>;
+    protected onReadBytes(_path: string, _sizeBytes: number): Promise<void>;
+    protected onWrite(_path: string, _sizeBytes: number): Promise<void>;
+    protected onAppend(_path: string, _sizeBytes: number): Promise<void>;
+    protected onDelete(_path: string): Promise<void>;
+    protected onExists(_path: string, _exists: boolean): Promise<void>;
+    protected onStat(_path: string, _stat: FileStat): Promise<void>;
+    protected onList(_path: string, _entries: readonly FileEntry[]): Promise<void>;
+    protected onWalk(_path: string, _entries: readonly FileEntry[]): Promise<void>;
+    protected onMkdir(_path: string, _recursive: boolean): Promise<void>;
+    protected onRmdir(_path: string, _recursive: boolean): Promise<void>;
+    protected onReadStream(_path: string): void;
+    protected onWriteStream(_path: string): void;
+    protected onWatch(_path: string, _watcher: Watcher): Promise<void>;
+    protected onTempFile(_tempFile: TempFile): Promise<void>;
+    protected onError(_operation: FileOperation, _path: string, _error: unknown): 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>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<FileStat>;
+    list(path: string): Promise<FileEntry[]>;
+    walk(path: string): Promise<FileEntry[]>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    rmdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    readStream(path: string): ReadableStream<Uint8Array>;
+    writeStream(path: string): WritableStream<Uint8Array>;
+    watch(path: string, callback: (event: WatchEvent) => void): Promise<Watcher>;
+    tempFile(prefix?: string): Promise<TempFile>;
+    private static sizeOf;
+}
+//# sourceMappingURL=AuditedFileRepository.d.ts.map

package/dist/src/repository/general/AuditedFileRepository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AuditedFileRepository.d.ts","sourceRoot":"","sources":["../../../../src/repository/general/AuditedFileRepository.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AAC1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAA;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAA;AAE5D;;;;GAIG;AACH,MAAM,MAAM,aAAa,GACrB,MAAM,GACN,WAAW,GACX,OAAO,GACP,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,MAAM,GACN,MAAM,GACN,OAAO,GACP,OAAO,GACP,YAAY,GACZ,aAAa,GACb,OAAO,GACP,UAAU,CAAA;AAEd;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,8BAAsB,qBAAsB,SAAQ,cAAc;cAGhD,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;cACxD,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;cAC7D,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;cACzD,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;cAC1D,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;cACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;cACxD,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;cACrD,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;cACpE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;cACpE,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;cAC1D,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAC1E,SAAS,CAAC,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAC3C,SAAS,CAAC,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;cAC5B,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;cACxD,UAAU,CAAC,SAAS,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;cAC9C,OAAO,CAAC,UAAU,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlF,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAanC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAa5C,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAYhE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAYjE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYnC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAMtC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAarC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAaxC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAaxC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAYzE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAY/E,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAAC,UAAU,CAAC;IAMpD,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAAC,UAAU,CAAC;IAM/C,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC;IAa5E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAa3D,OAAO,CAAC,MAAM,CAAC,MAAM;CAGtB"}