@fatagnus/dink-sync 1.0.0

package/dist/client/sync-engine.d.ts

@@ -0,0 +1,298 @@
+/**
+ * SyncEngine - NATS-based sync engine for offline-first document synchronization
+ *
+ * Implements per-document actors with:
+ * - Connection state tracking (online/offline/reconnecting)
+ * - Local change queuing with debounced batch sending
+ * - State vector exchange for CRDT convergence
+ * - Event emission for UI binding
+ * - Actual NATS transport for sync communication
+ */
+import { type Transport } from './transport.js';
+import { type CompressionConfig } from './compression.js';
+import { PendingQueue } from '../persistence/pending-queue.js';
+import type { PersistenceProvider } from '../persistence/types.js';
+import type { NetworkDetector } from './network-detector.js';
+export declare const ConnectionState: {
+    readonly Offline: "offline";
+    readonly Connecting: "connecting";
+    readonly Online: "online";
+    readonly Reconnecting: "reconnecting";
+};
+export type ConnectionState = typeof ConnectionState[keyof typeof ConnectionState];
+export declare const DEFAULT_DEBOUNCE_MS = 200;
+export declare const DEFAULT_MAX_RETRIES = 5;
+export declare const DEFAULT_MAX_BACKOFF_DELAY = 30000;
+export declare const DEFAULT_BATCH_SIZE = 50;
+/**
+ * Configuration for SyncEngine
+ */
+export interface SyncEngineConfig {
+    /** NATS server URL (e.g., 'nats://localhost:4222') */
+    readonly serverUrl: string;
+    /** API key for authentication */
+    readonly apiKey: string;
+    /** Application ID (optional, extracted from API key if not provided) */
+    readonly appId?: string;
+    /** Edge ID (optional, extracted from API key if not provided) */
+    readonly edgeId?: string;
+    /** Debounce time in ms before sending changes (default: 200) */
+    readonly debounceMs?: number;
+    /** Max retries for failed sync operations (default: 3) */
+    readonly maxRetries?: number;
+    /** Max batch size for sync operations (default: 50) */
+    readonly batchSize?: number;
+    /** Request timeout in ms (default: 10000) */
+    readonly requestTimeout?: number;
+    /** Custom transport (for testing or alternative implementations) */
+    readonly transport?: Transport;
+    /** Optional PendingQueue for persisting pending changes across crashes */
+    readonly pendingQueue?: PendingQueue;
+    /** Optional PersistenceProvider for storing state vectors */
+    readonly persistence?: PersistenceProvider;
+    /** Optional NetworkDetector for automatic network state detection */
+    readonly networkDetector?: NetworkDetector;
+    /** Optional compression configuration for large binary payloads */
+    readonly compression?: CompressionConfig;
+}
+/**
+ * Unsubscribe function type
+ */
+export type Unsubscribe = () => void;
+/**
+ * Document actor interface for per-document sync management
+ */
+export interface DocumentActor {
+    readonly documentId: string;
+    readonly collection: string;
+    queueChange(delta: Uint8Array): void;
+    hasPendingChanges(): boolean;
+    onPendingChange(callback: (pending: boolean) => void): Unsubscribe;
+    getStateVector(): Uint8Array;
+    setStateVector(vector: Uint8Array): void;
+    applyExternalUpdate(update: Uint8Array): void;
+    onExternalUpdate(callback: (update: Uint8Array) => void): Unsubscribe;
+}
+/**
+ * Sync event types
+ */
+export interface SyncStartedEvent {
+    readonly collection: string;
+    readonly documentId: string;
+}
+export interface SyncCompleteEvent {
+    readonly collection: string;
+    readonly documentId: string;
+}
+export interface SyncErrorEvent {
+    readonly collection: string;
+    readonly documentId: string;
+    readonly error: Error;
+}
+/**
+ * Event emitted when a retry is scheduled for a failed sync.
+ */
+export interface RetryScheduledEvent {
+    readonly collection: string;
+    readonly documentId: string;
+    /** The retry attempt number (1-based) */
+    readonly attempt: number;
+    /** The delay in milliseconds before the retry */
+    readonly delay: number;
+}
+/**
+ * Event emitted when sync has permanently failed after all retries.
+ */
+export interface SyncFailedEvent {
+    readonly collection: string;
+    readonly documentId: string;
+    readonly error: Error;
+    /** Total number of attempts made (initial + retries) */
+    readonly totalAttempts: number;
+}
+/**
+ * Error codes for sync rejection (server-side failures).
+ */
+export declare const SyncRejectionCode: {
+    readonly UniqueViolation: "UNIQUE_VIOLATION";
+    readonly ValidationError: "VALIDATION_ERROR";
+    readonly PermissionDenied: "PERMISSION_DENIED";
+    readonly NotFound: "NOT_FOUND";
+    readonly ServerError: "SERVER_ERROR";
+    readonly Unknown: "UNKNOWN";
+};
+export type SyncRejectionCode = typeof SyncRejectionCode[keyof typeof SyncRejectionCode];
+/**
+ * Detailed rejection information from server.
+ */
+export interface SyncRejectionError {
+    readonly code: SyncRejectionCode;
+    readonly field?: string;
+    readonly message: string;
+    readonly originalError?: unknown;
+}
+/**
+ * Event emitted when a sync is rejected by the server.
+ */
+export interface SyncRejectedEvent {
+    readonly collection: string;
+    readonly documentId: string;
+    readonly error: SyncRejectionError;
+}
+/**
+ * Event emitted when local changes are discarded.
+ */
+export interface LocalChangesDiscardedEvent {
+    readonly collection: string;
+    readonly documentId: string;
+    /** Number of changes that were discarded */
+    readonly discardedCount: number;
+}
+/**
+ * Event emitted when a force push operation is performed.
+ * Used for audit logging of force push operations.
+ */
+export interface ForcePushEvent {
+    readonly collection: string;
+    readonly documentId: string;
+    /** Timestamp when the force push was performed */
+    readonly timestamp: number;
+    /** Whether the force push succeeded */
+    readonly success: boolean;
+    /** Error details if force push failed */
+    readonly error?: {
+        readonly code: string;
+        readonly message: string;
+    };
+}
+/**
+ * Result of a force push operation.
+ */
+export interface ForcePushResult {
+    readonly success: boolean;
+    readonly error?: {
+        readonly code: string;
+        readonly message: string;
+    };
+}
+/**
+ * SyncEngine interface
+ */
+export interface SyncEngine {
+    getConnectionState(): ConnectionState;
+    onStateChange(callback: (state: ConnectionState) => void): Unsubscribe;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    destroy(): Promise<void>;
+    registerDocument(collection: string, documentId: string): Promise<DocumentActor>;
+    unregisterDocument(collection: string, documentId: string): Promise<void>;
+    onSyncStarted(callback: (event: SyncStartedEvent) => void): Unsubscribe;
+    onSyncComplete(callback: (event: SyncCompleteEvent) => void): Unsubscribe;
+    onSyncError(callback: (event: SyncErrorEvent) => void): Unsubscribe;
+    /**
+     * Subscribe to sync rejection events.
+     * Called when server rejects a sync due to validation errors, constraint violations, etc.
+     * @param callback - Function called with rejection details
+     * @returns Unsubscribe function
+     */
+    onSyncRejected(callback: (event: SyncRejectedEvent) => void): Unsubscribe;
+    /**
+     * Manually mark a document as rejected (for testing or external rejection handling).
+     * @param collection - Collection name
+     * @param documentId - Document ID
+     * @param error - Rejection error details
+     */
+    rejectDocument(collection: string, documentId: string, error: SyncRejectionError): void;
+    /**
+     * Subscribe to retry scheduled events.
+     * Called when a sync retry is scheduled after a retryable failure.
+     * @param callback - Function called with retry details
+     * @returns Unsubscribe function
+     */
+    onRetryScheduled(callback: (event: RetryScheduledEvent) => void): Unsubscribe;
+    /**
+     * Subscribe to sync failed events.
+     * Called when sync has permanently failed after all retries are exhausted.
+     * @param callback - Function called with failure details
+     * @returns Unsubscribe function
+     */
+    onSyncFailed(callback: (event: SyncFailedEvent) => void): Unsubscribe;
+    /**
+     * Reset retry count for a document and trigger a new sync attempt.
+     * Useful for manually retrying failed syncs after fixing the issue.
+     * @param collection - Collection name
+     * @param documentId - Document ID
+     */
+    resetRetries(collection: string, documentId: string): void;
+    /**
+     * Manually force offline mode.
+     * Prevents sync operations even when network is available.
+     * Useful for testing offline behavior or saving battery.
+     */
+    goOffline(): void;
+    /**
+     * Exit manual offline mode.
+     * Flushes any pending changes if transport and network are available.
+     */
+    goOnline(): void;
+    /**
+     * Check if the engine is in manual offline mode.
+     * @returns true if manually offline, false otherwise
+     */
+    isManuallyOffline(): boolean;
+    /**
+     * Discard local changes for a specific document.
+     * Removes pending changes from the queue and reverts to last synced state.
+     * @param collection - Collection name
+     * @param documentId - Document ID
+     */
+    discardLocalChanges(collection: string, documentId: string): Promise<void>;
+    /**
+     * Discard all local changes, optionally filtered by collection.
+     * @param collection - Optional collection name to filter by
+     */
+    discardAllLocalChanges(collection?: string): Promise<void>;
+    /**
+     * Subscribe to local changes discarded events.
+     * Called when local changes are discarded via discardLocalChanges or discardAllLocalChanges.
+     * @param callback - Function called with discard details
+     * @returns Unsubscribe function
+     */
+    onLocalChangesDiscarded(callback: (event: LocalChangesDiscardedEvent) => void): Unsubscribe;
+    /**
+     * Force push local state to server, overriding server state entirely.
+     * This is a last resort for conflict resolution and requires explicit user confirmation.
+     * @param collection - Collection name
+     * @param documentId - Document ID
+     * @returns Result of the force push operation
+     */
+    forcePush(collection: string, documentId: string): Promise<ForcePushResult>;
+    /**
+     * Subscribe to force push events for audit logging.
+     * Called when a force push operation is performed (success or failure).
+     * @param callback - Function called with force push details
+     * @returns Unsubscribe function
+     */
+    onForcePush(callback: (event: ForcePushEvent) => void): Unsubscribe;
+}
+/**
+ * Calculate exponential backoff delay.
+ * Delays: 1s, 2s, 4s, 8s, 16s, capped at maxDelay (default 30s).
+ * @param retryCount - The current retry attempt (0-indexed)
+ * @param maxDelay - Maximum delay in ms (default: 30000)
+ * @returns Delay in milliseconds
+ */
+export declare function calculateBackoffDelay(retryCount: number, maxDelay?: number): number;
+/**
+ * Determine if an error is retryable.
+ * Network errors, timeouts, and server errors are retryable.
+ * Validation, auth, and unique constraint errors are not.
+ * @param error - The error to check
+ * @returns true if the error is retryable, false otherwise
+ */
+export declare function isRetryableError(error: Error): boolean;
+/**
+ * Creates a SyncEngine instance
+ */
+export declare function createSyncEngine(config: SyncEngineConfig): SyncEngine;
+//# sourceMappingURL=sync-engine.d.ts.map

package/dist/client/sync-engine.d.ts.map

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