@procedures/client 0.1.0 → 0.2.1

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

@@ -1,246 +0,0 @@
-/**
- * Synced Procedure Registry
- *
- * Wraps ProcedureRegistry with storage synchronization capabilities.
- * Enables procedure persistence and sync across backends.
- */
-import type { CollectionStorage } from "@mark1russell7/client-collections";
-import { ProcedureRegistry } from "../registry.js";
-import type { AnyProcedure, ProcedurePath, RegistrationOptions } from "../types.js";
-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/procedures/storage/synced-registry.d.ts.map

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