korajs 0.3.5 → 0.5.0

package/dist/index.d.ts

@@ -1,10 +1,12 @@
-import { KoraEventEmitter, SchemaDefinition, SchemaInput, FieldBuilder, InferRecord, InferInsertInput, InferUpdateInput } from '@korajs/core';
-export { CollectionDefinition, ConnectionQuality, Constraint, FieldDescriptor, FieldKindToType, HLCTimestamp, HybridLogicalClock, InferFieldType, InferInsertInput, InferRecord, InferUpdateInput, KoraError, KoraEvent, KoraEventEmitter, KoraEventListener, KoraEventType, MergeStrategy, MergeTrace, Operation, SchemaDefinition, SchemaInput, TypedSchemaDefinition, VersionVector, createOperation, defineSchema, generateUUIDv7, t } from '@korajs/core';
-import * as _korajs_store from '@korajs/store';
-import { QueryBuilder, CollectionAccessor } from '@korajs/store';
-export { CollectionAccessor, CollectionRecord, StorageAdapter, Store, StoreConfig } 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, 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';
 
 /**
@@ -23,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.
@@ -38,18 +68,50 @@ 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>>;
+    /**
+     * Flat scope values. Combined with schema scope declarations to build
+     * per-collection scope filters sent to the server during handshake.
+     *
+     * @example
+     * ```typescript
+     * createApp({
+     *   schema,
+     *   sync: {
+     *     url: 'wss://server/kora',
+     *     scope: { orgId: 'org-123', storeId: 'store-456' },
+     *   },
+     * })
+     * ```
+     */
+    scope?: Record<string, unknown>;
     /** Number of operations per batch. Defaults to 100. */
     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().
@@ -63,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.
  */
@@ -78,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.
@@ -87,8 +159,79 @@ 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;
+}
+/**
+ * A transaction collection accessor providing insert, update, delete, and findById.
+ */
+interface TransactionCollectionProxy {
+    insert(data: Record<string, unknown>): Promise<CollectionRecord>;
+    update(id: string, data: Record<string, unknown>): Promise<CollectionRecord>;
+    delete(id: string): Promise<void>;
+    findById(id: string): Promise<CollectionRecord | null>;
+}
+/**
+ * Transaction proxy passed to the transaction callback.
+ * Provides collection accessors as direct properties (e.g., tx.todos.insert(...)).
+ */
+interface TransactionProxy {
+    /** Dynamic collection accessors for transaction operations. */
+    [collection: string]: TransactionCollectionProxy;
+}
+/**
+ * Accessor for offline-safe sequences.
+ * Generates monotonically increasing, collision-free identifiers
+ * that work across offline devices.
+ */
+interface SequenceAccessor {
+    /**
+     * Get the next value in a sequence, atomically incrementing the counter.
+     *
+     * @param name - The sequence name (e.g., 'receipt', 'invoice')
+     * @param config - Optional configuration for scope, format, and starting value
+     * @returns The formatted sequence value
+     *
+     * @example
+     * ```typescript
+     * const receiptNo = await app.sequences.next('receipt', {
+     *   scope: storeId,
+     *   format: 'S-{date}-{node4}-{seq}',
+     * })
+     * // → "S-20260508-a1b2-0042"
+     * ```
+     */
+    next(name: string, config?: SequenceConfig): Promise<string>;
+    /**
+     * Get the current counter value without incrementing.
+     *
+     * @param name - The sequence name
+     * @param config - Optional scope
+     * @returns The current counter value, or 0 if never used
+     */
+    current(name: string, config?: {
+        scope?: string;
+    }): Promise<number>;
+    /**
+     * Reset a sequence counter.
+     *
+     * @param name - The sequence name
+     * @param config - Optional scope and target value
+     */
+    reset(name: string, config?: {
+        scope?: string;
+        to?: number;
+    }): Promise<void>;
 }
 /**
  * The main application object returned by createApp().
@@ -101,12 +244,70 @@ interface KoraApp {
     events: KoraEventEmitter;
     /** Sync control (connect/disconnect/status). Null if sync not configured. */
     sync: SyncControl | null;
+    /** Offline-safe sequence generation. */
+    sequences: SequenceAccessor;
     /** Get the underlying Store instance (for advanced use / React integration). */
     getStore(): _korajs_store.Store;
     /** Get the underlying SyncEngine instance. Null if sync not configured. */
     getSyncEngine(): SyncEngine | null;
     /** Gracefully close the app: stop sync, close store. */
     close(): Promise<void>;
+    /**
+     * Execute multiple mutations atomically within a transaction.
+     * All operations are committed together or rolled back on error.
+     * Subscription notifications are batched after commit.
+     *
+     * @example
+     * ```typescript
+     * await app.transaction(async (tx) => {
+     *   await tx.sales.update(saleId, { status: 'completed' })
+     *   await tx.payments.insert({ saleId, method: 'cash', amount: total })
+     * })
+     * ```
+     */
+    transaction(fn: (tx: TransactionProxy) => Promise<void>): Promise<Operation[]>;
+    /**
+     * Execute a named mutation — a transaction with a human-readable name.
+     * The mutation name is attached to all operations and visible in DevTools.
+     *
+     * @example
+     * ```typescript
+     * await app.mutation('complete-sale', async (tx) => {
+     *   await tx.sales.update(saleId, { status: 'completed' })
+     *   await tx.payments.insert({ saleId, method: 'cash', amount: total })
+     * })
+     * ```
+     */
+    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;
 }
@@ -137,12 +338,26 @@ type TypedKoraApp<S extends SchemaInput> = {
     events: KoraEventEmitter;
     /** Sync control (connect/disconnect/status). Null if sync not configured. */
     sync: SyncControl | null;
+    /** Offline-safe sequence generation. */
+    sequences: SequenceAccessor;
     /** Get the underlying Store instance (for advanced use / React integration). */
     getStore(): _korajs_store.Store;
     /** Get the underlying SyncEngine instance. Null if sync not configured. */
     getSyncEngine(): SyncEngine | null;
     /** 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>>;
@@ -190,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 StoreOptions, type SyncControl, type SyncOptions, 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 };