@xfcfam/xf-fs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Israel Sanjurjo and the XF contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# `@xfcfam/xf-fs`
+
+Filesystem Access Layer Generalization for the **XF Architecture
+Model** — encapsulates `node:fs` behind a coherent, XF-compliant API.
+
+`xf-fs` is the canonical wrapper that lets an XF artefact talk to
+the local filesystem without ever importing `node:fs` directly. It
+follows the same shape as `@xfcfam/xf-rest` (HTTP protocol) and
+`@xfcfam/xf-sql` (SQL protocol): one Generalization per protocol of
+access, with cross-cutting variants for caching and audit.
+
+## What it provides
+
+| Component | Purpose |
+| --- | --- |
+| `FileRepository` | Generalization. Wraps `node:fs`: read/write/append/delete/exists/stat, list/walk, mkdir/rmdir, streaming, watch, temp files. Concrete components extend it for their domain. |
+| `CachedFileRepository` | Same protocol; adds an in-memory cache for `read`/`readBytes` with write-through invalidation. |
+| `AuditedFileRepository` | Same protocol; adds overridable `onRead` / `onWrite` / `onDelete` / `onError` / … hooks for audit logs, metrics, tracing. |
+| `FileEntry`, `FileStat`, `WatchEvent`, `Watcher`, `TempFile` | Transfer objects modelling directory entries, metadata, change events, watch handles, and temp-file handles. |
+| `FileNotFoundException`, `FileAccessDeniedException`, `DirectoryNotEmptyException` | Typed Exceptions for the three modelled failure modes. Other failures propagate as native `Error`. |
+| `PathUtils`, `EncodingUtils` | Pure helpers — path manipulation (`join` / `normalize` / `relative` / …) and BOM-aware UTF-8 encoding. |
+
+## Install
+
+```bash
+pnpm add @xfcfam/xf-fs @xfcfam/xf
+```
+
+`@xfcfam/xf` is a peer dependency.
+
+## Quick start
+
+```ts
+import { FileRepository } from '@xfcfam/xf-fs'
+
+interface User { id: string; name: string }
+
+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))
+  }
+}
+```
+
+Inject it into the artefact's Access Layer injection `R`:
+
+```ts
+import { UsersFileRepository } from './repository/logic/UsersFileRepository.js'
+
+export class R {
+  private constructor() {}
+  static readonly usersFileRepository = new UsersFileRepository()
+  static async init()      { await R.usersFileRepository.init() }
+  static async terminate() { await R.usersFileRepository.terminate() }
+}
+```
+
+## Generalizations by protocol, not by feature
+
+xf-fs deliberately exposes **one** `FileRepository` covering the
+entire local-filesystem protocol (read, write, list, watch, stream,
+temp). Variants subclass `FileRepository` only when they add a
+**cross-cutting policy** over the same protocol:
+
+- `CachedFileRepository` adds *caching* (still the same protocol).
+- `AuditedFileRepository` adds *observability* (still the same
+  protocol).
+
+Other protocols of access (S3, FTP, in-memory virtual FS) would land
+in their own packages (`@xfcfam/xf-fs-s3`, `@xfcfam/xf-fs-memory`, …)
+exposing their own `FileRepository` subclass — the consumer picks
+the implementation that matches its environment, the API stays
+uniform.
+
+## Resource lifecycle
+
+`Watcher` and `TempFile` are Transfers that wrap an OS handle. The
+caller owns them and should call `.close()` when done. As a safety
+net, `FileRepository.terminate()` closes every still-active watcher
+and deletes every still-open temp file — so even a careless caller
+won't leak handles on shutdown.
+
+## Error model
+
+Three filesystem errors are translated into typed XF Exceptions
+because they have **clear domain meaning**:
+
+- `FileNotFoundException` ← `ENOENT`
+- `FileAccessDeniedException` ← `EACCES` / `EPERM`
+- `DirectoryNotEmptyException` ← `ENOTEMPTY`
+
+Anything else propagates as the native `Error` raised by `node:fs`.
+This is consistent with the XF doctrine: native runtime exceptions
+are well-formed transfer vehicles (like `String`, `Date`, `Promise`),
+and a custom Exception is justified only when it represents a
+concept of the artefact's domain.
+
+## License
+
+MIT.

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `@xfcfam/xf-fs` — local-filesystem Access Layer Generalization for
+ * the XF Architecture Model (CFAM).
+ *
+ * Exposes:
+ *
+ * - **{@link FileRepository}** — the canonical Generalization. Wraps
+ *   `node:fs` and exposes a single coherent API over the local
+ *   filesystem protocol: text & byte I/O, directory traversal,
+ *   streaming reads/writes, change watching, and temp-file allocation.
+ *   Concrete components extend it for their domain.
+ *
+ * - **{@link CachedFileRepository}** — same protocol; adds an
+ *   in-memory cache over `read`/`readBytes` with write-through
+ *   invalidation.
+ *
+ * - **{@link AuditedFileRepository}** — same protocol; adds
+ *   overridable `onRead` / `onWrite` / `onError` / … hooks for audit
+ *   logging, metrics, and tracing.
+ *
+ * - **Transfers**: {@link FileEntry}, {@link FileStat},
+ *   {@link WatchEvent}, {@link Watcher}, {@link TempFile}.
+ *
+ * - **Exceptions**: {@link FileNotFoundException},
+ *   {@link FileAccessDeniedException},
+ *   {@link DirectoryNotEmptyException}.
+ *
+ * - **Utilities**: {@link PathUtils}, {@link EncodingUtils}.
+ *
+ * See https://xfcfam.org for the full XF specification.
+ */
+export { FileRepository } from './src/repository/general/FileRepository.js';
+export type { FileOptions } from './src/repository/general/FileRepository.js';
+export { CachedFileRepository } from './src/repository/general/CachedFileRepository.js';
+export { AuditedFileRepository } from './src/repository/general/AuditedFileRepository.js';
+export type { FileOperation } from './src/repository/general/AuditedFileRepository.js';
+export type { FileEntry } from './src/repository/transfers/FileEntry.js';
+export type { FileStat } from './src/repository/transfers/FileStat.js';
+export type { WatchEvent, WatchEventKind } from './src/repository/transfers/WatchEvent.js';
+export type { Watcher } from './src/repository/transfers/Watcher.js';
+export type { TempFile } from './src/repository/transfers/TempFile.js';
+export { FileNotFoundException } from './src/repository/transfers/FileNotFoundException.js';
+export { FileAccessDeniedException } from './src/repository/transfers/FileAccessDeniedException.js';
+export { DirectoryNotEmptyException } from './src/repository/transfers/DirectoryNotEmptyException.js';
+export { PathUtils } from './src/repository/utils/PathUtils.js';
+export { EncodingUtils } from './src/repository/utils/EncodingUtils.js';
+export type { Encoding } from './src/repository/utils/EncodingUtils.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,4CAA4C,CAAA;AAC3E,YAAY,EAAE,WAAW,EAAE,MAAM,4CAA4C,CAAA;AAC7E,OAAO,EAAE,oBAAoB,EAAE,MAAM,kDAAkD,CAAA;AACvF,OAAO,EAAE,qBAAqB,EAAE,MAAM,mDAAmD,CAAA;AACzF,YAAY,EAAE,aAAa,EAAE,MAAM,mDAAmD,CAAA;AAGtF,YAAY,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AACxE,YAAY,EAAE,QAAQ,EAAE,MAAM,wCAAwC,CAAA;AACtE,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,0CAA0C,CAAA;AAC1F,YAAY,EAAE,OAAO,EAAE,MAAM,uCAAuC,CAAA;AACpE,YAAY,EAAE,QAAQ,EAAE,MAAM,wCAAwC,CAAA;AAGtE,OAAO,EAAE,qBAAqB,EAAE,MAAM,qDAAqD,CAAA;AAC3F,OAAO,EAAE,yBAAyB,EAAE,MAAM,yDAAyD,CAAA;AACnG,OAAO,EAAE,0BAA0B,EAAE,MAAM,0DAA0D,CAAA;AAGrG,OAAO,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAA;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAA;AACvE,YAAY,EAAE,QAAQ,EAAE,MAAM,yCAAyC,CAAA"}

package/dist/index.js

@@ -0,0 +1,43 @@
+/**
+ * `@xfcfam/xf-fs` — local-filesystem Access Layer Generalization for
+ * the XF Architecture Model (CFAM).
+ *
+ * Exposes:
+ *
+ * - **{@link FileRepository}** — the canonical Generalization. Wraps
+ *   `node:fs` and exposes a single coherent API over the local
+ *   filesystem protocol: text & byte I/O, directory traversal,
+ *   streaming reads/writes, change watching, and temp-file allocation.
+ *   Concrete components extend it for their domain.
+ *
+ * - **{@link CachedFileRepository}** — same protocol; adds an
+ *   in-memory cache over `read`/`readBytes` with write-through
+ *   invalidation.
+ *
+ * - **{@link AuditedFileRepository}** — same protocol; adds
+ *   overridable `onRead` / `onWrite` / `onError` / … hooks for audit
+ *   logging, metrics, and tracing.
+ *
+ * - **Transfers**: {@link FileEntry}, {@link FileStat},
+ *   {@link WatchEvent}, {@link Watcher}, {@link TempFile}.
+ *
+ * - **Exceptions**: {@link FileNotFoundException},
+ *   {@link FileAccessDeniedException},
+ *   {@link DirectoryNotEmptyException}.
+ *
+ * - **Utilities**: {@link PathUtils}, {@link EncodingUtils}.
+ *
+ * See https://xfcfam.org for the full XF specification.
+ */
+// ── Access ────────────────────────────────────────────────
+export { FileRepository } from './src/repository/general/FileRepository.js';
+export { CachedFileRepository } from './src/repository/general/CachedFileRepository.js';
+export { AuditedFileRepository } from './src/repository/general/AuditedFileRepository.js';
+// Exceptions
+export { FileNotFoundException } from './src/repository/transfers/FileNotFoundException.js';
+export { FileAccessDeniedException } from './src/repository/transfers/FileAccessDeniedException.js';
+export { DirectoryNotEmptyException } from './src/repository/transfers/DirectoryNotEmptyException.js';
+// Utilities
+export { PathUtils } from './src/repository/utils/PathUtils.js';
+export { EncodingUtils } from './src/repository/utils/EncodingUtils.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,6DAA6D;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,4CAA4C,CAAA;AAE3E,OAAO,EAAE,oBAAoB,EAAE,MAAM,kDAAkD,CAAA;AACvF,OAAO,EAAE,qBAAqB,EAAE,MAAM,mDAAmD,CAAA;AAUzF,aAAa;AACb,OAAO,EAAE,qBAAqB,EAAE,MAAM,qDAAqD,CAAA;AAC3F,OAAO,EAAE,yBAAyB,EAAE,MAAM,yDAAyD,CAAA;AACnG,OAAO,EAAE,0BAA0B,EAAE,MAAM,0DAA0D,CAAA;AAErG,YAAY;AACZ,OAAO,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAA;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAA"}

package/dist/src/api/A.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Interaction Layer Injection — placeholder.
+ *
+ * `A` is the canonical injection of the Interaction Layer. `@xfcfam/xf-fs`
+ * is a library that contributes Generalizations and Transfer objects;
+ * it does not own any Logical of this layer, so its own `A` declares
+ * no static slots. The class is kept structurally complete (private
+ * constructor + empty `init` / `terminate`) so the artefact passes XF
+ * validation. It is NOT exported from the package — consumers import
+ * `A` from their own artefact.
+ */
+export declare class A {
+    private constructor();
+    static init(): Promise<void>;
+    static terminate(): Promise<void>;
+}
+//# sourceMappingURL=A.d.ts.map

package/dist/src/api/A.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"A.d.ts","sourceRoot":"","sources":["../../../src/api/A.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,qBAAa,CAAC;IACZ,OAAO;WACM,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;WACrB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;CACxC"}

package/dist/src/api/A.js

@@ -0,0 +1,17 @@
+/**
+ * Interaction Layer Injection — placeholder.
+ *
+ * `A` is the canonical injection of the Interaction Layer. `@xfcfam/xf-fs`
+ * is a library that contributes Generalizations and Transfer objects;
+ * it does not own any Logical of this layer, so its own `A` declares
+ * no static slots. The class is kept structurally complete (private
+ * constructor + empty `init` / `terminate`) so the artefact passes XF
+ * validation. It is NOT exported from the package — consumers import
+ * `A` from their own artefact.
+ */
+export class A {
+    constructor() { }
+    static async init() { }
+    static async terminate() { }
+}
+//# sourceMappingURL=A.js.map

package/dist/src/api/A.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"A.js","sourceRoot":"","sources":["../../../src/api/A.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,OAAO,CAAC;IACZ,gBAAuB,CAAC;IACxB,MAAM,CAAC,KAAK,CAAC,IAAI,KAAmB,CAAC;IACrC,MAAM,CAAC,KAAK,CAAC,SAAS,KAAmB,CAAC;CAC3C"}

package/dist/src/business/B.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Business Layer Injection — placeholder.
+ *
+ * `B` is the canonical injection of the Business Layer. `@xfcfam/xf-fs`
+ * is a library that contributes Generalizations and Transfer objects;
+ * it does not own any Logical of this layer, so its own `B` declares
+ * no static slots. The class is kept structurally complete (private
+ * constructor + empty `init` / `terminate`) so the artefact passes XF
+ * validation. It is NOT exported from the package — consumers import
+ * `B` from their own artefact.
+ */
+export declare class B {
+    private constructor();
+    static init(): Promise<void>;
+    static terminate(): Promise<void>;
+}
+//# sourceMappingURL=B.d.ts.map

package/dist/src/business/B.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"B.d.ts","sourceRoot":"","sources":["../../../src/business/B.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,qBAAa,CAAC;IACZ,OAAO;WACM,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;WACrB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;CACxC"}

package/dist/src/business/B.js

@@ -0,0 +1,17 @@
+/**
+ * Business Layer Injection — placeholder.
+ *
+ * `B` is the canonical injection of the Business Layer. `@xfcfam/xf-fs`
+ * is a library that contributes Generalizations and Transfer objects;
+ * it does not own any Logical of this layer, so its own `B` declares
+ * no static slots. The class is kept structurally complete (private
+ * constructor + empty `init` / `terminate`) so the artefact passes XF
+ * validation. It is NOT exported from the package — consumers import
+ * `B` from their own artefact.
+ */
+export class B {
+    constructor() { }
+    static async init() { }
+    static async terminate() { }
+}
+//# sourceMappingURL=B.js.map

package/dist/src/business/B.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"B.js","sourceRoot":"","sources":["../../../src/business/B.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,OAAO,CAAC;IACZ,gBAAuB,CAAC;IACxB,MAAM,CAAC,KAAK,CAAC,IAAI,KAAmB,CAAC;IACrC,MAAM,CAAC,KAAK,CAAC,SAAS,KAAmB,CAAC;CAC3C"}

package/dist/src/repository/R.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Access Layer Injection — placeholder.
+ *
+ * `R` is the canonical injection of the Access Layer. `@xfcfam/xf-fs`
+ * is a library that contributes Generalizations and Transfer objects;
+ * it does not own any Logical of this layer, so its own `R` declares
+ * no static slots. The class is kept structurally complete (private
+ * constructor + empty `init` / `terminate`) so the artefact passes XF
+ * validation. It is NOT exported from the package — consumers import
+ * `R` from their own artefact.
+ */
+export declare class R {
+    private constructor();
+    static init(): Promise<void>;
+    static terminate(): Promise<void>;
+}
+//# sourceMappingURL=R.d.ts.map

package/dist/src/repository/R.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"R.d.ts","sourceRoot":"","sources":["../../../src/repository/R.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,qBAAa,CAAC;IACZ,OAAO;WACM,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;WACrB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;CACxC"}

package/dist/src/repository/R.js

@@ -0,0 +1,17 @@
+/**
+ * Access Layer Injection — placeholder.
+ *
+ * `R` is the canonical injection of the Access Layer. `@xfcfam/xf-fs`
+ * is a library that contributes Generalizations and Transfer objects;
+ * it does not own any Logical of this layer, so its own `R` declares
+ * no static slots. The class is kept structurally complete (private
+ * constructor + empty `init` / `terminate`) so the artefact passes XF
+ * validation. It is NOT exported from the package — consumers import
+ * `R` from their own artefact.
+ */
+export class R {
+    constructor() { }
+    static async init() { }
+    static async terminate() { }
+}
+//# sourceMappingURL=R.js.map

package/dist/src/repository/R.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"R.js","sourceRoot":"","sources":["../../../src/repository/R.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,OAAO,CAAC;IACZ,gBAAuB,CAAC;IACxB,MAAM,CAAC,KAAK,CAAC,IAAI,KAAmB,CAAC;IACrC,MAAM,CAAC,KAAK,CAAC,SAAS,KAAmB,CAAC;CAC3C"}

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

@@ -0,0 +1,86 @@
+import { FileRepository } from './FileRepository.js';
+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';
+/**
+ * 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 '@xfarch/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/base/AuditedFileRepository.d.ts.map

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

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

@@ -0,0 +1,202 @@
+import { FileRepository } from './FileRepository.js';
+/**
+ * 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 '@xfarch/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 class AuditedFileRepository extends FileRepository {
+    // ─── Hooks (overridable; defaults are no-ops) ─────────────
+    async onRead(_path, _sizeBytes) { }
+    async onReadBytes(_path, _sizeBytes) { }
+    async onWrite(_path, _sizeBytes) { }
+    async onAppend(_path, _sizeBytes) { }
+    async onDelete(_path) { }
+    async onExists(_path, _exists) { }
+    async onStat(_path, _stat) { }
+    async onList(_path, _entries) { }
+    async onWalk(_path, _entries) { }
+    async onMkdir(_path, _recursive) { }
+    async onRmdir(_path, _recursive) { }
+    onReadStream(_path) { }
+    onWriteStream(_path) { }
+    async onWatch(_path, _watcher) { }
+    async onTempFile(_tempFile) { }
+    async onError(_operation, _path, _error) { }
+    // ─── Intercepted operations ───────────────────────────────
+    async read(path) {
+        try {
+            const content = await super.read(path);
+            await this.onRead(this.resolve(path), Buffer.byteLength(content, 'utf-8'));
+            return content;
+        }
+        catch (err) {
+            await this.onError('read', this.resolve(path), err);
+            throw err;
+        }
+    }
+    async readBytes(path) {
+        try {
+            const bytes = await super.readBytes(path);
+            await this.onReadBytes(this.resolve(path), bytes.byteLength);
+            return bytes;
+        }
+        catch (err) {
+            await this.onError('readBytes', this.resolve(path), err);
+            throw err;
+        }
+    }
+    async write(path, content) {
+        try {
+            await super.write(path, content);
+            await this.onWrite(this.resolve(path), AuditedFileRepository.sizeOf(content));
+        }
+        catch (err) {
+            await this.onError('write', this.resolve(path), err);
+            throw err;
+        }
+    }
+    async append(path, content) {
+        try {
+            await super.append(path, content);
+            await this.onAppend(this.resolve(path), AuditedFileRepository.sizeOf(content));
+        }
+        catch (err) {
+            await this.onError('append', this.resolve(path), err);
+            throw err;
+        }
+    }
+    async delete(path) {
+        try {
+            await super.delete(path);
+            await this.onDelete(this.resolve(path));
+        }
+        catch (err) {
+            await this.onError('delete', this.resolve(path), err);
+            throw err;
+        }
+    }
+    async exists(path) {
+        const result = await super.exists(path);
+        await this.onExists(this.resolve(path), result);
+        return result;
+    }
+    async stat(path) {
+        try {
+            const s = await super.stat(path);
+            await this.onStat(s.path, s);
+            return s;
+        }
+        catch (err) {
+            await this.onError('stat', this.resolve(path), err);
+            throw err;
+        }
+    }
+    async list(path) {
+        try {
+            const entries = await super.list(path);
+            await this.onList(this.resolve(path), entries);
+            return entries;
+        }
+        catch (err) {
+            await this.onError('list', this.resolve(path), err);
+            throw err;
+        }
+    }
+    async walk(path) {
+        try {
+            const entries = await super.walk(path);
+            await this.onWalk(this.resolve(path), entries);
+            return entries;
+        }
+        catch (err) {
+            await this.onError('walk', this.resolve(path), err);
+            throw err;
+        }
+    }
+    async mkdir(path, options = {}) {
+        try {
+            await super.mkdir(path, options);
+            await this.onMkdir(this.resolve(path), options.recursive ?? false);
+        }
+        catch (err) {
+            await this.onError('mkdir', this.resolve(path), err);
+            throw err;
+        }
+    }
+    async rmdir(path, options = {}) {
+        try {
+            await super.rmdir(path, options);
+            await this.onRmdir(this.resolve(path), options.recursive ?? false);
+        }
+        catch (err) {
+            await this.onError('rmdir', this.resolve(path), err);
+            throw err;
+        }
+    }
+    readStream(path) {
+        const stream = super.readStream(path);
+        this.onReadStream(this.resolve(path));
+        return stream;
+    }
+    writeStream(path) {
+        const stream = super.writeStream(path);
+        this.onWriteStream(this.resolve(path));
+        return stream;
+    }
+    async watch(path, callback) {
+        try {
+            const watcher = await super.watch(path, callback);
+            await this.onWatch(this.resolve(path), watcher);
+            return watcher;
+        }
+        catch (err) {
+            await this.onError('watch', this.resolve(path), err);
+            throw err;
+        }
+    }
+    async tempFile(prefix) {
+        try {
+            const handle = await super.tempFile(prefix);
+            await this.onTempFile(handle);
+            return handle;
+        }
+        catch (err) {
+            await this.onError('tempFile', '', err);
+            throw err;
+        }
+    }
+    static sizeOf(content) {
+        return typeof content === 'string' ? Buffer.byteLength(content, 'utf-8') : content.byteLength;
+    }
+}
+//# sourceMappingURL=AuditedFileRepository.js.map