zen-fs-config 0.1.0 → 0.1.1

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import * as node_fs from 'node:fs';
-import { ConflictStrategy, SyncResult, SyncPairStatus } from 'zen-fs-sync';
+import { ConflictStrategy, SyncResult, SyncPairStatus, SyncableFS } from 'zen-fs-sync';
 export { SyncPairStatus, SyncResult } from 'zen-fs-sync';
+import * as node_fs from 'node:fs';
 
 /** A single backend in the topology. */
 interface BackendDescriptor {
@@ -143,15 +143,15 @@ interface IConfigRepo {
     /** Write a config value (auto-synced). */
     setConfig(path: string, data: unknown): void;
     /** Read node-local config. */
-    getNodeConfig<T = unknown>(nodeId: string, path: string): T;
+    getNodeConfig<T = unknown>(nodeId: string, path: string): Promise<T>;
     /** Write node-local config (no auto-sync). */
-    setNodeConfig(nodeId: string, path: string, data: unknown): void;
+    setNodeConfig(nodeId: string, path: string, data: unknown): Promise<void>;
     /** Publish node-local config to sync backends (one-time, for debugging). */
     publishNodeConfig(nodeId: string, options?: {
         paths?: string[];
     }): Promise<SyncResult>;
     /** Peek at another node's published config (read-only). */
-    peekNodeConfig<T = unknown>(nodeId: string, path: string): T;
+    peekNodeConfig<T = unknown>(nodeId: string, path: string): Promise<T>;
     /** Manually flush all pending sync operations. */
     flush(): Promise<SyncResult[]>;
     /** Get sync status for all registered sync pairs. */
@@ -164,4 +164,189 @@ interface IConfigRepo {
     dispose(): Promise<void>;
 }
 
-export type { BackendDescriptor, BackendsMeta, BootstrapData, CacheOptions, ConfigRepoOptions, ConfigSerializer, ConflictArchive, ConflictInfo, IConfigRepo, SyncRule, SyncRulesMeta, VersionMeta };
+/**
+ * zen-fs-config — Config Serializers
+ *
+ * Handles serialization/deserialization between JS values and file bytes.
+ * The default serializer handles .json, .txt, and unknown extensions.
+ * Users can provide a custom ConfigSerializer via ConfigRepoOptions.
+ */
+
+/**
+ * Extended serializer that also accepts an optional path hint for routing.
+ * The core ConfigSerializer interface only takes `data`, but internally
+ * we use the path to pick the right serializer.
+ */
+interface PathAwareSerializer extends ConfigSerializer {
+    serialize(data: unknown, path?: string): Uint8Array;
+    deserialize(raw: Uint8Array, path?: string): unknown;
+}
+/**
+ * Create a serializer chain from a user-provided serializer + defaults.
+ * The first serializer whose `canHandle()` returns true wins.
+ */
+declare function createSerializerChain(custom?: ConfigSerializer): PathAwareSerializer;
+
+/**
+ * Map a config key to a file path.
+ *
+ * - `/db/host` → `/db/host.json` (append .json if no extension)
+ * - `/readme.md` → `/readme.md` (preserve existing extension)
+ */
+declare function configKeyToFilePath(configPath: string): string;
+/**
+ * Extract the file extension (including the dot), or empty string.
+ */
+declare function getExtension(path: string): string;
+
+/**
+ * zen-fs-config — ConfigRepo Implementation
+ *
+ * Core implementation of IConfigRepo and the createConfigRepo factory.
+ */
+
+interface MinimalAsyncFS {
+    readFile(path: string, ...args: any[]): Promise<any>;
+    writeFile(path: string, data: any, options?: any): Promise<void>;
+    readdir(path: string): Promise<string[]>;
+    stat(path: string): Promise<any>;
+    exists(path: string): Promise<boolean>;
+    mkdir(path: string, options?: any): Promise<any>;
+    unlink(path: string): Promise<void>;
+    rmdir?(path: string): Promise<void>;
+    rename?(oldPath: string, newPath: string): Promise<void>;
+}
+declare class ConfigRepo implements IConfigRepo {
+    readonly appId: string;
+    readonly nodeId: string;
+    /** Chroot-isolated fs for app-facing API. Typed as `any` to match `typeof import('node:fs')` duck-typically. */
+    readonly fs: any;
+    private cachedFS;
+    private fullFS;
+    private serializer;
+    private syncEngine;
+    private replicaBackends;
+    private onConflictCallback?;
+    private disposed;
+    private configCache;
+    constructor(appId: string, nodeId: string, cachedFS: MinimalAsyncFS, serializer: PathAwareSerializer, onConflict?: (conflict: ConflictInfo) => Promise<unknown | null>);
+    load(rawConfig?: string): Promise<void>;
+    getConfig<T = unknown>(path: string): T;
+    setConfig(path: string, data: unknown): void;
+    getNodeConfig<T = unknown>(nodeId: string, path: string): Promise<T>;
+    setNodeConfig(nodeId: string, path: string, data: unknown): Promise<void>;
+    publishNodeConfig(nodeId: string, options?: {
+        paths?: string[];
+    }): Promise<SyncResult>;
+    peekNodeConfig<T = unknown>(nodeId: string, path: string): Promise<T>;
+    flush(): Promise<SyncResult[]>;
+    getSyncStatuses(): Map<string, SyncPairStatus>;
+    resolveConflict(conflictId: string, mergedContent: unknown): Promise<void>;
+    listConflicts(): Promise<ConflictArchive[]>;
+    dispose(): Promise<void>;
+    setupSync(rules: SyncRule[], backends: BackendDescriptor[], primaryBackendId: string): Promise<void>;
+    private persistConfig;
+    private reloadConfigCache;
+    private handleConflict;
+    private ensureDir;
+    private walkDir;
+    writeMetaFile(path: string, data: BackendsMeta | SyncRulesMeta): Promise<void>;
+    readMetaFile<T>(path: string): Promise<T | null>;
+    private tryParse;
+    private assertNotDisposed;
+}
+declare function createConfigRepo(appId: string, options: ConfigRepoOptions): Promise<IConfigRepo>;
+
+/**
+ * zen-fs-config — Backend Registry
+ *
+ * A pluggable registry that maps backend type names to factory functions.
+ * Built-in support for ZenFS backends (InMemory, IndexedDB, etc.)
+ * loaded from @zenfs/core.
+ *
+ * Users can register custom backends via `registerBackend()`.
+ */
+
+/**
+ * A factory function that creates a file system instance from options.
+ * The returned value must satisfy SyncableFS (and ideally CacheableFileSystem).
+ */
+type BackendFactory = (options: Record<string, unknown>) => Promise<BackendInstance>;
+/**
+ * The minimal interface a backend instance must satisfy.
+ * Combines SyncableFS (from zen-fs-sync) with the write signature
+ * needed by CachedFileSystem.
+ */
+interface BackendInstance {
+    readFile(path: string, ...args: any[]): Promise<any>;
+    writeFile(path: string, data: string | Uint8Array | ArrayBuffer, options?: any): Promise<void>;
+    readdir(path: string): Promise<string[]>;
+    stat(path: string, ...args: any[]): Promise<any>;
+    exists(path: string): Promise<boolean>;
+    mkdir(path: string, options?: any): Promise<any>;
+    unlink(path: string): Promise<void>;
+    rmdir?(path: string): Promise<void>;
+    rename?(oldPath: string, newPath: string): Promise<void>;
+    readFileMeta?(path: string, opts?: any): Promise<any>;
+    getRevision?(path: string): Promise<string | number | undefined>;
+}
+/**
+ * Register a backend factory by type name.
+ */
+declare function registerBackend(type: string, factory: BackendFactory): void;
+/**
+ * Create a backend instance from a descriptor.
+ */
+declare function createBackend(descriptor: Pick<BackendDescriptor, 'type' | 'options'>): Promise<BackendInstance>;
+/**
+ * Check if a backend type is registered.
+ */
+declare function hasBackend(type: string): boolean;
+/**
+ * List all registered backend type names.
+ */
+declare function listBackends(): string[];
+
+/**
+ * zen-fs-config — Sidecar Version File Management
+ *
+ * Each config file has a companion .version file for version-based change
+ * detection and conflict resolution.
+ *
+ * Config file:  /app-a/db.json
+ * Version file: /app-a/.db.json.version
+ */
+
+/**
+ * Compute the sidecar version file path from a config file path.
+ *
+ * /app-a/db.json        → /app-a/.db.json.version
+ * /shared/flags.json    → /shared/.flags.json.version
+ * /nodes/s1/env.json    → /nodes/s1/.env.json.version
+ */
+declare function versionPathFor(configFilePath: string): string;
+/**
+ * Compute SHA-256 hash of a Uint8Array.
+ * Returns "sha256:" prefix + hex digest.
+ */
+declare function sha256(data: Uint8Array): Promise<string>;
+/**
+ * Read and parse a version file. Returns null if it doesn't exist or is invalid.
+ */
+declare function readVersion(fs: SyncableFS, versionFilePath: string): Promise<VersionMeta | null>;
+/**
+ * Write a version file.
+ */
+declare function writeVersion(fs: SyncableFS, versionFilePath: string, meta: VersionMeta): Promise<void>;
+/**
+ * Increment version for a config file write.
+ */
+declare function incrementVersion(fs: SyncableFS, configFilePath: string, newContent: Uint8Array, author: string): Promise<VersionMeta>;
+/**
+ * Verify that the version file's hash matches the actual file content.
+ * If mismatch, auto-increment version and return updated meta.
+ * If version file doesn't exist, return null.
+ */
+declare function verifyOrRepairVersion(fs: SyncableFS, configFilePath: string, author: string): Promise<VersionMeta | null>;
+
+export { type BackendDescriptor, type BackendFactory, type BackendInstance, type BackendsMeta, type BootstrapData, type CacheOptions, ConfigRepo, type ConfigRepoOptions, type ConfigSerializer, type ConflictArchive, type ConflictInfo, type IConfigRepo, type SyncRule, type SyncRulesMeta, type VersionMeta, configKeyToFilePath, createBackend, createConfigRepo, createSerializerChain, getExtension, hasBackend, incrementVersion, listBackends, readVersion, registerBackend, sha256, verifyOrRepairVersion, versionPathFor, writeVersion };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import * as node_fs from 'node:fs';
-import { ConflictStrategy, SyncResult, SyncPairStatus } from 'zen-fs-sync';
+import { ConflictStrategy, SyncResult, SyncPairStatus, SyncableFS } from 'zen-fs-sync';
 export { SyncPairStatus, SyncResult } from 'zen-fs-sync';
+import * as node_fs from 'node:fs';
 
 /** A single backend in the topology. */
 interface BackendDescriptor {
@@ -143,15 +143,15 @@ interface IConfigRepo {
     /** Write a config value (auto-synced). */
     setConfig(path: string, data: unknown): void;
     /** Read node-local config. */
-    getNodeConfig<T = unknown>(nodeId: string, path: string): T;
+    getNodeConfig<T = unknown>(nodeId: string, path: string): Promise<T>;
     /** Write node-local config (no auto-sync). */
-    setNodeConfig(nodeId: string, path: string, data: unknown): void;
+    setNodeConfig(nodeId: string, path: string, data: unknown): Promise<void>;
     /** Publish node-local config to sync backends (one-time, for debugging). */
     publishNodeConfig(nodeId: string, options?: {
         paths?: string[];
     }): Promise<SyncResult>;
     /** Peek at another node's published config (read-only). */
-    peekNodeConfig<T = unknown>(nodeId: string, path: string): T;
+    peekNodeConfig<T = unknown>(nodeId: string, path: string): Promise<T>;
     /** Manually flush all pending sync operations. */
     flush(): Promise<SyncResult[]>;
     /** Get sync status for all registered sync pairs. */
@@ -164,4 +164,189 @@ interface IConfigRepo {
     dispose(): Promise<void>;
 }
 
-export type { BackendDescriptor, BackendsMeta, BootstrapData, CacheOptions, ConfigRepoOptions, ConfigSerializer, ConflictArchive, ConflictInfo, IConfigRepo, SyncRule, SyncRulesMeta, VersionMeta };
+/**
+ * zen-fs-config — Config Serializers
+ *
+ * Handles serialization/deserialization between JS values and file bytes.
+ * The default serializer handles .json, .txt, and unknown extensions.
+ * Users can provide a custom ConfigSerializer via ConfigRepoOptions.
+ */
+
+/**
+ * Extended serializer that also accepts an optional path hint for routing.
+ * The core ConfigSerializer interface only takes `data`, but internally
+ * we use the path to pick the right serializer.
+ */
+interface PathAwareSerializer extends ConfigSerializer {
+    serialize(data: unknown, path?: string): Uint8Array;
+    deserialize(raw: Uint8Array, path?: string): unknown;
+}
+/**
+ * Create a serializer chain from a user-provided serializer + defaults.
+ * The first serializer whose `canHandle()` returns true wins.
+ */
+declare function createSerializerChain(custom?: ConfigSerializer): PathAwareSerializer;
+
+/**
+ * Map a config key to a file path.
+ *
+ * - `/db/host` → `/db/host.json` (append .json if no extension)
+ * - `/readme.md` → `/readme.md` (preserve existing extension)
+ */
+declare function configKeyToFilePath(configPath: string): string;
+/**
+ * Extract the file extension (including the dot), or empty string.
+ */
+declare function getExtension(path: string): string;
+
+/**
+ * zen-fs-config — ConfigRepo Implementation
+ *
+ * Core implementation of IConfigRepo and the createConfigRepo factory.
+ */
+
+interface MinimalAsyncFS {
+    readFile(path: string, ...args: any[]): Promise<any>;
+    writeFile(path: string, data: any, options?: any): Promise<void>;
+    readdir(path: string): Promise<string[]>;
+    stat(path: string): Promise<any>;
+    exists(path: string): Promise<boolean>;
+    mkdir(path: string, options?: any): Promise<any>;
+    unlink(path: string): Promise<void>;
+    rmdir?(path: string): Promise<void>;
+    rename?(oldPath: string, newPath: string): Promise<void>;
+}
+declare class ConfigRepo implements IConfigRepo {
+    readonly appId: string;
+    readonly nodeId: string;
+    /** Chroot-isolated fs for app-facing API. Typed as `any` to match `typeof import('node:fs')` duck-typically. */
+    readonly fs: any;
+    private cachedFS;
+    private fullFS;
+    private serializer;
+    private syncEngine;
+    private replicaBackends;
+    private onConflictCallback?;
+    private disposed;
+    private configCache;
+    constructor(appId: string, nodeId: string, cachedFS: MinimalAsyncFS, serializer: PathAwareSerializer, onConflict?: (conflict: ConflictInfo) => Promise<unknown | null>);
+    load(rawConfig?: string): Promise<void>;
+    getConfig<T = unknown>(path: string): T;
+    setConfig(path: string, data: unknown): void;
+    getNodeConfig<T = unknown>(nodeId: string, path: string): Promise<T>;
+    setNodeConfig(nodeId: string, path: string, data: unknown): Promise<void>;
+    publishNodeConfig(nodeId: string, options?: {
+        paths?: string[];
+    }): Promise<SyncResult>;
+    peekNodeConfig<T = unknown>(nodeId: string, path: string): Promise<T>;
+    flush(): Promise<SyncResult[]>;
+    getSyncStatuses(): Map<string, SyncPairStatus>;
+    resolveConflict(conflictId: string, mergedContent: unknown): Promise<void>;
+    listConflicts(): Promise<ConflictArchive[]>;
+    dispose(): Promise<void>;
+    setupSync(rules: SyncRule[], backends: BackendDescriptor[], primaryBackendId: string): Promise<void>;
+    private persistConfig;
+    private reloadConfigCache;
+    private handleConflict;
+    private ensureDir;
+    private walkDir;
+    writeMetaFile(path: string, data: BackendsMeta | SyncRulesMeta): Promise<void>;
+    readMetaFile<T>(path: string): Promise<T | null>;
+    private tryParse;
+    private assertNotDisposed;
+}
+declare function createConfigRepo(appId: string, options: ConfigRepoOptions): Promise<IConfigRepo>;
+
+/**
+ * zen-fs-config — Backend Registry
+ *
+ * A pluggable registry that maps backend type names to factory functions.
+ * Built-in support for ZenFS backends (InMemory, IndexedDB, etc.)
+ * loaded from @zenfs/core.
+ *
+ * Users can register custom backends via `registerBackend()`.
+ */
+
+/**
+ * A factory function that creates a file system instance from options.
+ * The returned value must satisfy SyncableFS (and ideally CacheableFileSystem).
+ */
+type BackendFactory = (options: Record<string, unknown>) => Promise<BackendInstance>;
+/**
+ * The minimal interface a backend instance must satisfy.
+ * Combines SyncableFS (from zen-fs-sync) with the write signature
+ * needed by CachedFileSystem.
+ */
+interface BackendInstance {
+    readFile(path: string, ...args: any[]): Promise<any>;
+    writeFile(path: string, data: string | Uint8Array | ArrayBuffer, options?: any): Promise<void>;
+    readdir(path: string): Promise<string[]>;
+    stat(path: string, ...args: any[]): Promise<any>;
+    exists(path: string): Promise<boolean>;
+    mkdir(path: string, options?: any): Promise<any>;
+    unlink(path: string): Promise<void>;
+    rmdir?(path: string): Promise<void>;
+    rename?(oldPath: string, newPath: string): Promise<void>;
+    readFileMeta?(path: string, opts?: any): Promise<any>;
+    getRevision?(path: string): Promise<string | number | undefined>;
+}
+/**
+ * Register a backend factory by type name.
+ */
+declare function registerBackend(type: string, factory: BackendFactory): void;
+/**
+ * Create a backend instance from a descriptor.
+ */
+declare function createBackend(descriptor: Pick<BackendDescriptor, 'type' | 'options'>): Promise<BackendInstance>;
+/**
+ * Check if a backend type is registered.
+ */
+declare function hasBackend(type: string): boolean;
+/**
+ * List all registered backend type names.
+ */
+declare function listBackends(): string[];
+
+/**
+ * zen-fs-config — Sidecar Version File Management
+ *
+ * Each config file has a companion .version file for version-based change
+ * detection and conflict resolution.
+ *
+ * Config file:  /app-a/db.json
+ * Version file: /app-a/.db.json.version
+ */
+
+/**
+ * Compute the sidecar version file path from a config file path.
+ *
+ * /app-a/db.json        → /app-a/.db.json.version
+ * /shared/flags.json    → /shared/.flags.json.version
+ * /nodes/s1/env.json    → /nodes/s1/.env.json.version
+ */
+declare function versionPathFor(configFilePath: string): string;
+/**
+ * Compute SHA-256 hash of a Uint8Array.
+ * Returns "sha256:" prefix + hex digest.
+ */
+declare function sha256(data: Uint8Array): Promise<string>;
+/**
+ * Read and parse a version file. Returns null if it doesn't exist or is invalid.
+ */
+declare function readVersion(fs: SyncableFS, versionFilePath: string): Promise<VersionMeta | null>;
+/**
+ * Write a version file.
+ */
+declare function writeVersion(fs: SyncableFS, versionFilePath: string, meta: VersionMeta): Promise<void>;
+/**
+ * Increment version for a config file write.
+ */
+declare function incrementVersion(fs: SyncableFS, configFilePath: string, newContent: Uint8Array, author: string): Promise<VersionMeta>;
+/**
+ * Verify that the version file's hash matches the actual file content.
+ * If mismatch, auto-increment version and return updated meta.
+ * If version file doesn't exist, return null.
+ */
+declare function verifyOrRepairVersion(fs: SyncableFS, configFilePath: string, author: string): Promise<VersionMeta | null>;
+
+export { type BackendDescriptor, type BackendFactory, type BackendInstance, type BackendsMeta, type BootstrapData, type CacheOptions, ConfigRepo, type ConfigRepoOptions, type ConfigSerializer, type ConflictArchive, type ConflictInfo, type IConfigRepo, type SyncRule, type SyncRulesMeta, type VersionMeta, configKeyToFilePath, createBackend, createConfigRepo, createSerializerChain, getExtension, hasBackend, incrementVersion, listBackends, readVersion, registerBackend, sha256, verifyOrRepairVersion, versionPathFor, writeVersion };