@procedures/store 0.0.0-stage → 0.2.0

package/dist/storage/synced-registry.d.ts

@@ -0,0 +1,246 @@
+/**
+ * Synced Procedure Registry
+ *
+ * Wraps ProcedureRegistry with storage synchronization capabilities.
+ * Enables procedure persistence and sync across backends.
+ */
+import type { CollectionStorage } from "@procedures/collections";
+import { ProcedureRegistry } from "@procedures/client";
+import type { AnyProcedure, ProcedurePath, RegistrationOptions } from "@procedures/client";
+import type { SerializedProcedure, SyncedRegistryOptions, SyncResult, SyncStatus, SyncDirection, HandlerLoader, HandlerReference } from "./types.js";
+import { ProcedureStorageAdapter } from "./adapter.js";
+/**
+ * Extended registration options with persistence flag.
+ */
+export interface SyncedRegistrationOptions extends RegistrationOptions {
+    /** Whether to persist this procedure to storage (default: true) */
+    persist?: boolean | undefined;
+    /**
+     * The module and export of the handler. The stored record keeps it, so another process can
+     * load the handler (with an allowlisted handler loader) when it pulls the record.
+     */
+    handlerRef?: HandlerReference | undefined;
+}
+/**
+ * The synced registry that wraps a registry, if one does. The `procedure.store`, `load`,
+ * `sync` and `remote` procedures use it.
+ *
+ * @param registry - A procedure registry
+ * @returns The synced registry of the newest wrapper that is not closed, or undefined
+ */
+export declare function getProcedureStore(registry: ProcedureRegistry): SyncedProcedureRegistry | undefined;
+/**
+ * Procedure registry with storage synchronization.
+ *
+ * Wraps an existing ProcedureRegistry and adds:
+ * - Automatic persistence on register (write-through/write-back)
+ * - Sync from storage on demand
+ * - Conflict resolution
+ * - Connection management for remote storage
+ *
+ * A pull compares the `storedAt` of each record with the one of the last sync, and a local
+ * change counter for each path. A change on one side only is not a conflict: the changed side
+ * wins. A change on both sides (or a path with no sync yet) is a conflict, and the
+ * `conflictResolution` option decides. A record with no handler never replaces a procedure
+ * that has one: the procedure keeps its handler and takes the record's metadata.
+ *
+ * @example
+ * ```typescript
+ * const registry = new SyncedProcedureRegistry(
+ *   PROCEDURE_REGISTRY,
+ *   storageAdapter,
+ *   {
+ *     writeStrategy: 'write-through',
+ *     conflictResolution: 'remote',
+ *   }
+ * );
+ *
+ * // Sync from storage on startup
+ * await registry.syncFromStorage();
+ *
+ * // Register with auto-persistence
+ * registry.register(myProcedure, { persist: true });
+ *
+ * // Manual sync
+ * const result = await registry.sync('both');
+ * ```
+ */
+export declare class SyncedProcedureRegistry {
+    private readonly baseRegistry;
+    private readonly adapter;
+    private readonly options;
+    /** Pending changes for write-back strategy */
+    private pendingChanges;
+    /** Pending deletes for write-back strategy (deep dive DATA-8: they were never deleted) */
+    private pendingDeletes;
+    /** The handler reference of each path, for the stored records */
+    private readonly handlerRefs;
+    /** The `storedAt` of the record of each path at its last push or pull */
+    private readonly syncedAt;
+    /** A counter of local changes for each path, and its value at the last push or pull */
+    private readonly localVersion;
+    private readonly syncedVersion;
+    /** Write-through stores that have not finished */
+    private readonly inFlight;
+    /** Whether currently connected to remote storage */
+    private connected;
+    /** Remote endpoint (if connected) */
+    private endpoint;
+    /** Last sync timestamp */
+    private lastSyncTime;
+    /** Whether currently syncing */
+    private syncing;
+    /** Auto-sync interval handle */
+    private syncIntervalHandle;
+    constructor(baseRegistry: ProcedureRegistry, storage: CollectionStorage<SerializedProcedure>, options?: Partial<SyncedRegistryOptions>);
+    /**
+     * Register a procedure with optional persistence.
+     *
+     * The record has the path where the procedure is registered: with a `pathPrefix`, the
+     * prefixed path. (Before, the record had the path without the prefix: deep dive CORE-8.)
+     *
+     * @param procedure - Procedure to register
+     * @param options - Registration options including persist flag
+     */
+    register(procedure: AnyProcedure, options?: SyncedRegistrationOptions): void;
+    /**
+     * Unregister a procedure. Its record is deleted from storage: now (write-through), or at the
+     * next flush (write-back).
+     *
+     * @param path - Procedure path
+     * @returns True if procedure was removed
+     */
+    unregister(path: ProcedurePath): boolean;
+    /**
+     * Get a procedure by path.
+     */
+    get(path: ProcedurePath): AnyProcedure | undefined;
+    /**
+     * Check if a procedure exists.
+     */
+    has(path: ProcedurePath): boolean;
+    /**
+     * Get all registered procedures.
+     */
+    getAll(): AnyProcedure[];
+    /**
+     * Get procedures by prefix.
+     */
+    getByPrefix(prefix: ProcedurePath): AnyProcedure[];
+    /**
+     * Get count of registered procedures.
+     */
+    get size(): number;
+    /**
+     * Sync from storage to registry.
+     * Loads procedures from storage and merges with registry.
+     *
+     * @param filter - Pull only the records for which this function gives true (default: all)
+     * @returns Sync result with counts and conflicts
+     */
+    syncFromStorage(filter?: (record: SerializedProcedure) => boolean): Promise<SyncResult>;
+    /**
+     * Sync from registry to storage.
+     * Persists all registered procedures to storage, each with its handler reference.
+     *
+     * @returns Sync result
+     */
+    syncToStorage(): Promise<SyncResult>;
+    /**
+     * Full bidirectional sync.
+     *
+     * @param direction - Sync direction (push/pull/both)
+     * @returns Sync result
+     */
+    sync(direction?: SyncDirection): Promise<SyncResult>;
+    /**
+     * Flush pending changes to storage: the queued writes and deletes of the write-back strategy.
+     *
+     * @returns The number of records written or deleted
+     */
+    flushPending(): Promise<number>;
+    /**
+     * Store the registered procedure at a path now, whatever the write strategy.
+     *
+     * @param path - Procedure path
+     * @param options - A handler reference for the record
+     * @returns The stored record, or undefined when no procedure is registered at the path
+     */
+    storeProcedure(path: ProcedurePath, options?: {
+        handlerRef?: HandlerReference | undefined;
+    }): Promise<SerializedProcedure | undefined>;
+    /**
+     * Wait for the write-through writes that have started.
+     */
+    flushWrites(): Promise<void>;
+    /**
+     * Record a remote endpoint, and optionally pull from storage. This method does not change the
+     * storage: give the registry an `ApiStorage` for the endpoint when you make it.
+     *
+     * @param endpoint - Remote endpoint URL
+     * @param options - Connection options
+     */
+    connect(endpoint: string, options?: {
+        syncOnConnect?: boolean;
+    }): Promise<void>;
+    /**
+     * Disconnect from remote storage.
+     */
+    disconnect(): void;
+    /**
+     * Get current sync status.
+     */
+    getStatus(): SyncStatus;
+    /**
+     * Start auto-sync at specified interval.
+     *
+     * @param intervalMs - Sync interval in milliseconds
+     */
+    startAutoSync(intervalMs: number): void;
+    /**
+     * Stop auto-sync.
+     */
+    stopAutoSync(): void;
+    /**
+     * Resolve a conflict between local and remote procedures.
+     *
+     * @param path - Procedure path
+     * @param local - Local procedure
+     * @param remote - Remote procedure
+     * @returns Conflict info if not automatically resolved
+     */
+    private resolveConflict;
+    /**
+     * The remote version of a procedure. When the remote record gives no handler (a stub), the
+     * local handler and schemas stay, and the remote metadata applies.
+     */
+    private keepHandler;
+    /** Record a local change of a path. */
+    private touch;
+    /** True when the path changed locally since its last push or pull. */
+    private isDirty;
+    /** Record that storage and the registry agree on a path. */
+    private markSynced;
+    /** Store records for procedures, each with its handler reference, and mark them synced. */
+    private storeRecords;
+    /** Delete records, and forget their sync state. */
+    private removeRecords;
+    private track;
+    /**
+     * Get the base registry.
+     */
+    getBaseRegistry(): ProcedureRegistry;
+    /**
+     * Get the storage adapter.
+     */
+    getAdapter(): ProcedureStorageAdapter;
+    /**
+     * Get the handler loader.
+     */
+    getHandlerLoader(): HandlerLoader | undefined;
+    /**
+     * Close the synced registry and cleanup resources.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=synced-registry.d.ts.map

package/dist/storage/synced-registry.d.ts.map

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