korajs 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -1,11 +1,14 @@
-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 { AppNotReadyError, 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';
+import { AuthSyncBinding } from '@korajs/core/bindings';
+export { AuthSyncBinding } from '@korajs/core/bindings';
 export { MergeEngine, MergeInput, MergeResult } from '@korajs/merge';
 
 /**
@@ -24,9 +27,19 @@ 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;
 }
+
 /**
  * Sync configuration within createApp.
  */
@@ -39,6 +52,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 +79,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 +109,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 +132,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 +143,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;
 }
@@ -189,6 +234,8 @@ interface KoraApp {
     getStore(): _korajs_store.Store;
     /** Get the underlying SyncEngine instance. Null if sync not configured. */
     getSyncEngine(): SyncEngine | null;
+    /** Per-app reference-counted cache for framework query subscriptions. */
+    getQueryStoreCache(): _korajs_store.QueryStoreCache;
     /** Gracefully close the app: stop sync, close store. */
     close(): Promise<void>;
     /**
@@ -218,6 +265,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;
 }
@@ -254,12 +330,22 @@ type TypedKoraApp<S extends SchemaInput> = {
     getStore(): _korajs_store.Store;
     /** Get the underlying SyncEngine instance. Null if sync not configured. */
     getSyncEngine(): SyncEngine | null;
+    /** Per-app reference-counted cache for framework query subscriptions. */
+    getQueryStoreCache(): _korajs_store.QueryStoreCache;
     /** Gracefully close the app: stop sync, close store. */
     close(): Promise<void>;
     /** Execute multiple mutations atomically within a transaction. */
     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>>;
@@ -272,39 +358,8 @@ type TypedKoraApp<S extends SchemaInput> = {
  * Wires together store, merge engine, event emitter, and optionally sync
  * into a single developer-facing `KoraApp` object. Collection accessors
  * (e.g. `app.todos`) are defined as properties for immediate use after `await app.ready`.
- *
- * @param config - Application configuration including schema and optional sync settings
- * @returns A KoraApp instance with reactive collections ready for use
- *
- * @example
- * ```typescript
- * const app = createApp({
- *   schema: defineSchema({
- *     version: 1,
- *     collections: {
- *       todos: {
- *         fields: {
- *           title: t.string(),
- *           completed: t.boolean().default(false)
- *         }
- *       }
- *     }
- *   })
- * })
- *
- * await app.ready
- * const todo = await app.todos.insert({ title: 'Hello' })
- * ```
- */
-/**
- * Creates a new typed Kora application instance.
- * When the schema is created with `defineSchema()`, full type inference flows through
- * to collection accessors, providing autocomplete and type checking for all CRUD operations.
  */
 declare function createApp<const S extends SchemaInput>(config: TypedKoraConfig<S>): TypedKoraApp<S>;
-/**
- * Creates a new Kora application instance (untyped fallback).
- */
 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 };