korajs 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -1,11 +1,12 @@
-import { KoraEventEmitter, SequenceConfig, Operation, SchemaDefinition, SchemaInput, FieldBuilder, InferRecord, InferInsertInput, InferUpdateInput } from '@korajs/core';
-export { AtomicOp, AtomicOpType, CollectionDefinition, ConnectionQuality, Constraint, FieldDescriptor, FieldKindToType, HLCTimestamp, HybridLogicalClock, InferFieldType, InferInsertInput, InferRecord, InferUpdateInput, KoraError, KoraEvent, KoraEventEmitter, KoraEventListener, KoraEventType, MergeStrategy, MergeTrace, MigrationDefinition, MigrationStep, Operation, SchemaDefinition, SchemaInput, SequenceConfig, TypedSchemaDefinition, VersionVector, createOperation, defineSchema, generateUUIDv7, migrate, op, t } from '@korajs/core';
-import * as _korajs_store from '@korajs/store';
-import { CollectionRecord, QueryBuilder, CollectionAccessor } from '@korajs/store';
-export { CollectionAccessor, CollectionRecord, SequenceManager, StorageAdapter, Store, StoreConfig, TransactionCollectionAccessor, TransactionContext, TransactionContextConfig } from '@korajs/store';
+import * as _korajs_core from '@korajs/core';
+import { KoraEventEmitter, SequenceConfig, Operation, SchemaDefinition, KoraEvent, SchemaInput, FieldBuilder, InferRecord, InferInsertInput, InferUpdateInput } from '@korajs/core';
+export { AtomicOp, AtomicOpType, CollectionDefinition, ConnectionQuality, Constraint, FieldDescriptor, FieldKindToType, HLCTimestamp, HybridLogicalClock, InferFieldType, InferInsertInput, InferRecord, InferUpdateInput, KoraError, KoraEvent, KoraEventEmitter, KoraEventListener, KoraEventType, MergeStrategy, MergeTrace, MigrationDefinition, MigrationStep, Operation, SchemaDefinition, SchemaInput, SequenceConfig, SyncRuleDefinition, TypedSchemaDefinition, VersionVector, createOperation, defineSchema, generateUUIDv7, migrate, op, t } from '@korajs/core';
 import * as _korajs_sync from '@korajs/sync';
 import { SyncStatusInfo, SyncEngine } from '@korajs/sync';
-export { SyncConfig, SyncDiagnostics, SyncEngine, SyncState, SyncStatus, SyncStatusInfo, SyncStore, WebSocketTransport } from '@korajs/sync';
+export { SyncConfig, SyncDiagnostics, SyncEncryptionConfig, SyncEngine, SyncState, SyncStatus, SyncStatusInfo, SyncStore, WebSocketTransport } from '@korajs/sync';
+import * as _korajs_store from '@korajs/store';
+import { CollectionRecord, BackupOptions, RestoreOptions, RestoreResult, ReplaySnapshot, AuditExportOptions, QueryBuilder, CollectionAccessor } from '@korajs/store';
+export { AuditExportManifest, AuditExportOptions, AuditExportPayload, BackupManifest, BackupOptions, BackupProgress, CollectionAccessor, CollectionRecord, PersistedAuditTrace, ReplaySnapshot, RestoreOptions, RestoreResult, SequenceManager, StorageAdapter, Store, StoreConfig, TransactionCollectionAccessor, TransactionContext, TransactionContextConfig, decodeAuditExport, exportBackup, readAuditExportManifest, readBackupManifest, restoreBackup, verifyAuditExportChecksum, verifyBackupChecksum } from '@korajs/store';
 export { MergeEngine, MergeInput, MergeResult } from '@korajs/merge';
 
 /**
@@ -24,8 +25,36 @@ interface StoreOptions {
     adapter?: AdapterType;
     /** Database name. Defaults to 'kora-db'. */
     name?: string;
+    /**
+     * `shared` (default): one sync node id per database.
+     * `per-tab`: unique node id per browser tab (sessionStorage).
+     */
+    isolation?: _korajs_store.StoreIsolation;
     /** URL to the SQLite WASM worker script. Required for browser adapters (sqlite-wasm, indexeddb). */
     workerUrl?: string | URL;
+    /** Optional SharedWorker host for multi-tab SQLite (see `@korajs/store/sqlite-wasm/shared-host`). */
+    sharedWorkerUrl?: string | URL;
+    /** Max wait for a worker RPC (e.g. `open`). Defaults to 30000ms. */
+    workerResponseTimeoutMs?: number;
+}
+/**
+ * Pre-built auth binding from `createKoraAuthSync()` in `@korajs/auth`.
+ * Wires token refresh, JWT scope maps, and device-bound sync node ids.
+ */
+interface AuthSyncBinding {
+    /** Returns the access token for sync handshake (empty string when signed out). */
+    auth: () => Promise<{
+        token: string;
+    }>;
+    /** Builds a scope map from the current token and schema. */
+    resolveScopeMap?: () => Promise<Record<string, Record<string, unknown>> | undefined>;
+    /**
+     * Returns the device-bound sync node id from the token `dev` claim.
+     * Separate from the user id (`sub`).
+     */
+    resolveNodeId?: () => Promise<string | undefined>;
+    /** Notifies when auth state changes so sync can refresh scope or reconnect. */
+    subscribe?: (listener: () => void) => () => void;
 }
 /**
  * Sync configuration within createApp.
@@ -39,6 +68,11 @@ interface SyncOptions {
     auth?: () => Promise<{
         token: string;
     }>;
+    /**
+     * Pre-built auth binding from `createKoraAuthSync({ authClient, schema })`.
+     * When set, overrides `auth`, auto-builds `scopeMap`, and binds store node id to `dev`.
+     */
+    authClient?: AuthSyncBinding;
     /** Sync scopes per collection. */
     scopes?: Record<string, (ctx: Record<string, unknown>) => Record<string, unknown>>;
     /**
@@ -61,12 +95,23 @@ interface SyncOptions {
     batchSize?: number;
     /** Schema version of this client. */
     schemaVersion?: number;
+    /** Connect to the sync server automatically after `app.ready`. Defaults to false. */
+    autoConnect?: boolean;
+    /** Wait for server ACK on each handshake delta batch before streaming. Defaults to false. */
+    strictHandshake?: boolean;
+    /** Rewrites legacy operations during sync when schema versions differ. */
+    operationTransforms?: _korajs_core.OperationTransform[];
     /** Enable auto-reconnection on unexpected disconnect. Defaults to true. */
     autoReconnect?: boolean;
     /** Initial reconnection delay in ms. Defaults to 1000. */
     reconnectInterval?: number;
     /** Maximum reconnection delay in ms. Defaults to 30000. */
     maxReconnectInterval?: number;
+    /**
+     * End-to-end encryption for operation payloads on the sync wire.
+     * When enabled, `data` and `previousData` are encrypted before send.
+     */
+    encryption?: _korajs_sync.SyncEncryptionConfig;
 }
 /**
  * Full configuration passed to createApp().
@@ -80,7 +125,15 @@ interface KoraConfig {
     sync?: SyncOptions;
     /** Enable DevTools instrumentation. Defaults to false. */
     devtools?: boolean;
+    /** Called for each sync-related framework event. */
+    onSyncEvent?: (event: Extract<KoraEvent, {
+        type: `sync:${string}`;
+    }>) => void;
 }
+/** Sync event types delivered to {@link KoraConfig.onSyncEvent}. */
+type KoraSyncEvent = Extract<KoraEvent, {
+    type: `sync:${string}`;
+}>;
 /**
  * Typed configuration passed to createApp() when using a TypedSchemaDefinition.
  */
@@ -95,6 +148,8 @@ interface TypedKoraConfig<S extends SchemaInput> {
     sync?: SyncOptions;
     /** Enable DevTools instrumentation. Defaults to false. */
     devtools?: boolean;
+    /** Called for each sync-related framework event. */
+    onSyncEvent?: (event: KoraSyncEvent) => void;
 }
 /**
  * Controls for the sync subsystem exposed on the KoraApp.
@@ -104,10 +159,16 @@ interface SyncControl {
     connect(): Promise<void>;
     /** Disconnect from the sync server. */
     disconnect(): Promise<void>;
+    /** Current sync status snapshot (updates on sync events). */
+    readonly status: SyncStatusInfo;
     /** Get the current developer-facing sync status. */
     getStatus(): SyncStatusInfo;
+    /** Subscribe to status changes (event-driven, no polling). */
+    subscribeStatus(listener: (status: SyncStatusInfo) => void): () => void;
     /** Force an immediate reconnection attempt. No-op if already connected. */
     retryNow(): Promise<void>;
+    /** Clear schema-mismatch block after upgrading schema; then call `connect()`. */
+    clearSchemaBlock(): void;
     /** Export a diagnostics snapshot for debugging and support tickets. */
     exportDiagnostics(): _korajs_sync.SyncDiagnostics;
 }
@@ -218,6 +279,35 @@ interface KoraApp {
      * ```
      */
     mutation(name: string, fn: (tx: TransactionProxy) => Promise<void>): Promise<Operation[]>;
+    /**
+     * Export all data as a portable backup binary.
+     * Delegates to the underlying store's exportBackup.
+     *
+     * @param options - Backup options (includeRecords, collections, onProgress)
+     * @returns Backup as a Uint8Array
+     */
+    exportBackup(options?: BackupOptions): Promise<Uint8Array>;
+    /**
+     * Restore data from a backup binary.
+     * Delegates to the underlying store's importBackup.
+     *
+     * @param data - The backup data
+     * @param options - Restore options (merge, collections, onProgress)
+     * @returns Result of the restore operation
+     */
+    importBackup(data: Uint8Array, options?: RestoreOptions): Promise<RestoreResult>;
+    /**
+     * Rebuild an in-memory snapshot at a causal cut in the operation log.
+     * Does not mutate live data — for DevTools time-travel and audit inspection.
+     *
+     * @param operationId - Content-addressed operation id to replay through (inclusive)
+     */
+    replayTo(operationId: string): Promise<ReplaySnapshot>;
+    /**
+     * Export the operation log and persisted merge traces as a portable audit bundle.
+     * Merge traces are recorded automatically when conflicts are resolved.
+     */
+    exportAudit(options?: AuditExportOptions): Promise<Uint8Array>;
     /** Dynamic collection accessors (e.g., app.todos). Typed via Object.defineProperty. */
     [collection: string]: unknown;
 }
@@ -260,6 +350,14 @@ type TypedKoraApp<S extends SchemaInput> = {
     transaction(fn: (tx: TransactionProxy) => Promise<void>): Promise<Operation[]>;
     /** Execute a named mutation — a transaction with a DevTools-visible name. */
     mutation(name: string, fn: (tx: TransactionProxy) => Promise<void>): Promise<Operation[]>;
+    /** Export all data as a portable backup binary. */
+    exportBackup(options?: BackupOptions): Promise<Uint8Array>;
+    /** Restore data from a backup binary. */
+    importBackup(data: Uint8Array, options?: RestoreOptions): Promise<RestoreResult>;
+    /** Rebuild an in-memory snapshot at a causal cut in the operation log. */
+    replayTo(operationId: string): Promise<ReplaySnapshot>;
+    /** Export the operation log and persisted merge traces as a portable audit bundle. */
+    exportAudit(options?: AuditExportOptions): Promise<Uint8Array>;
 } & {
     readonly [C in keyof S['collections'] & string]: S['collections'][C] extends {
         fields: infer F extends Record<string, FieldBuilder<any, any, any>>;
@@ -307,4 +405,4 @@ declare function createApp<const S extends SchemaInput>(config: TypedKoraConfig<
  */
 declare function createApp(config: KoraConfig): KoraApp;
 
-export { type AdapterType, type KoraApp, type KoraConfig, type SequenceAccessor, type StoreOptions, type SyncControl, type SyncOptions, type TransactionCollectionProxy, type TransactionProxy, type TypedCollectionAccessor, type TypedKoraApp, type TypedKoraConfig, createApp };
+export { type AdapterType, type AuthSyncBinding, type KoraApp, type KoraConfig, type SequenceAccessor, type StoreOptions, type SyncControl, type SyncOptions, type TransactionCollectionProxy, type TransactionProxy, type TypedCollectionAccessor, type TypedKoraApp, type TypedKoraConfig, createApp };