@korajs/store 0.6.0 → 1.0.0-beta.0

package/dist/index.d.cts

@@ -1,9 +1,9 @@
-import { C as CollectionRecord, S as StorageAdapter, Q as QueryDescriptor, c as SubscriptionCallback, W as WhereClause, d as OrderByDirection, L as LocalMutationHandler, e as StoreConfig, A as ApplyRemoteOptions, f as MaterializedRowSnapshot } from './types-DepnRDk_.cjs';
-export { M as MigrationPlan, g as OrderByClause, h as StoreIsolation, T as Transaction, i as TransactionBufferedEntry, j as TransactionCommitBatch, k as TransactionCommitResult, l as WhereOperators } from './types-DepnRDk_.cjs';
-import { Operation, KoraError, VersionVector, SchemaDefinition, MergeTrace, CollectionDefinition, SequenceConfig, HybridLogicalClock, CausalTracker, OperationLog, ApplyResult, StateMachineDefinition, KoraEvent } from '@korajs/core';
+import { C as CollectionRecord, S as StorageAdapter, Q as QueryDescriptor, c as SubscriptionCallback, W as WhereClause, d as OrderByDirection, L as LocalMutationHandler, e as StoreConfig, A as ApplyRemoteOptions, f as MaterializedRowSnapshot, g as RowVersionState } from './types-CJOVKxLw.cjs';
+export { M as MigrationPlan, h as OrderByClause, i as StoreIsolation, T as Transaction, j as TransactionBufferedEntry, k as TransactionCommitBatch, l as TransactionCommitResult, m as WhereOperators } from './types-CJOVKxLw.cjs';
+import { Operation, KoraError, VersionVector, SchemaDefinition, HLCTimestamp, MergeTrace, CollectionDefinition, SequenceConfig, HybridLogicalClock, CausalTracker, OperationLog, ApplyResult, StateMachineDefinition, KoraBytesValue, KoraEvent } from '@korajs/core';
 export { ApplyResult } from '@korajs/core';
-import { R as RelationEnforcer, L as LocalMutationContext } from './types-CTr00g_d.cjs';
-export { C as Collection } from './types-CTr00g_d.cjs';
+import { R as RelationEnforcer, L as LocalMutationContext } from './types-CyjXwrjW.cjs';
+export { C as Collection } from './types-CyjXwrjW.cjs';
 import * as yjs from 'yjs';
 
 /**
@@ -33,6 +33,18 @@ declare class QueryError extends KoraError {
 declare class RecordNotFoundError extends KoraError {
     constructor(collection: string, recordId: string);
 }
+/**
+ * Thrown inside `applyRemoteOperation` when the row's version state changed
+ * between the caller's snapshot read and the guarded write (a concurrent local
+ * mutation landed in the window). The transaction is rolled back with nothing
+ * written; the caller re-reads fresh state, recomputes its merge, and retries.
+ * This is the optimistic-concurrency guard that keeps merge-engine results
+ * (richtext, add-wins arrays, constraint resolutions) from clobbering newer
+ * local edits they never saw.
+ */
+declare class OptimisticLockError extends KoraError {
+    constructor(collection: string, recordId: string);
+}
 /**
  * Thrown when a storage adapter operation fails.
  */
@@ -101,6 +113,20 @@ declare function computeAckCompactionWatermark(serverVector: VersionVector): Ver
  */
 declare function compactOperationLog(adapter: StorageAdapter, schema: SchemaDefinition, strategy: CompactionStrategy, serverVector: VersionVector): Promise<CompactionResult>;
 
+/**
+ * Result of re-stamping unsynced operations after a clock correction.
+ */
+interface ClockRebaseResult {
+    /** The rewritten operations, in causal order (original HLC total order preserved). */
+    operations: Operation[];
+    /** Maps each old (pre-rebase) operation id to its new content-addressed id. */
+    idMapping: Record<string, string>;
+    /** Number of operations that were re-stamped. */
+    rebasedCount: number;
+    /** Highest timestamp assigned during the rebase, or null when nothing was rebased. */
+    newMaxTimestamp: HLCTimestamp | null;
+}
+
 declare const LAST_ACKED_SERVER_VECTOR_META_KEY = "last_acked_server_vector";
 /**
  * Serialize a version vector for `_kora_meta` storage.
@@ -715,6 +741,12 @@ declare class Store implements OperationLog {
     /**
      * Get the node ID for this store instance.
      */
+    /**
+     * Records the offset between server time and this device's clock
+     * (serverTime - localTime), learned at sync handshake. Lets the store's HLC
+     * validate remote timestamps correctly even when the local clock is wrong.
+     */
+    setClockReferenceOffset(offsetMs: number): void;
     getNodeId(): string;
     /**
      * Apply a remote operation received from sync.
@@ -722,6 +754,18 @@ declare class Store implements OperationLog {
      * and updates the version vector.
      */
     applyRemoteOperation(op: Operation, options?: ApplyRemoteOptions): Promise<ApplyResult>;
+    /**
+     * Materialize update/delete operations that were logged for a record BEFORE
+     * its insert arrived (reordered delivery). Runs inside the insert's write
+     * transaction, folding each orphan in timestamp order through the exact
+     * per-field LWW / LWW-delete rules the normal apply paths use, so the final
+     * row state equals what a device that received the operations in causal
+     * order computed. Called only when the insert created a previously-absent
+     * row — in that case every logged update/delete for the record is
+     * necessarily an orphan (rows are soft-deleted, never removed, so a row
+     * that is absent now was never materialized).
+     */
+    private foldOrphanedOperations;
     /**
      * Get operations from a node within a sequence number range.
      * Implements the OperationLog interface for computeDelta.
@@ -775,6 +819,14 @@ declare class Store implements OperationLog {
      * Load a materialized row by ID, including soft-deleted tombstones.
      */
     findMaterializedRow(collection: string, recordId: string): Promise<MaterializedRowSnapshot | null>;
+    /**
+     * Raw version state of a materialized row, for optimistic-concurrency guarded
+     * applies: capture this snapshot before computing a merge, pass it as
+     * `guardRowState`, and the apply refuses to write if the row changed since.
+     * Returns null when no row exists (which is itself a valid guard state — the
+     * apply then requires the row to still be absent).
+     */
+    getRowVersionState(collection: string, recordId: string): Promise<RowVersionState | null>;
     /**
      * Latest operation from this device for a record (used for delete-vs-update merge on sync).
      */
@@ -798,6 +850,18 @@ declare class Store implements OperationLog {
      * Local operations not yet reflected on the server version vector.
      */
     getUnsyncedOperations(serverVector: VersionVector): Promise<Operation[]>;
+    /**
+     * Re-stamp never-acknowledged local operations after a fast device clock was
+     * corrected, so sync can resume immediately. Safe because unacknowledged
+     * operations are private to this device (like unpushed git commits);
+     * acknowledged/shared operations are immutable and never touched.
+     *
+     * After the rewrite the store's HLC is advanced past the highest new
+     * timestamp so subsequent local writes keep sorting after the rebased ops.
+     * No data-change notifications are emitted: materialized values are
+     * unchanged, only version stamps move.
+     */
+    rebaseUnsyncedOperations(unsyncedOpIds: string[], correctedNowMs: number): Promise<ClockRebaseResult>;
     /**
      * Count of local operations ahead of the server version vector.
      */
@@ -1185,8 +1249,14 @@ declare function asRichTextSyncEngine(engine: unknown): RichTextSyncEngine | nul
 type RichtextInput = string | Uint8Array | ArrayBuffer | null | undefined;
 /**
  * Encodes richtext values into Yjs document updates.
+ *
+ * Also accepts the tagged `{ $koraBytes }` form that binary richtext values
+ * take inside `op.data` (and, for old dev databases, the pre-fix numeric-key
+ * object shape), so every consumer that writes op-data values to columns
+ * inherits the decoding. Plain strings keep their exact historical behavior:
+ * encoded as a fresh Yjs document containing the string.
  */
-declare function encodeRichtext(value: RichtextInput): Uint8Array | null;
+declare function encodeRichtext(value: RichtextInput | KoraBytesValue): Uint8Array | null;
 /**
  * Decodes driver-provided richtext values into Uint8Array.
  */
@@ -1287,4 +1357,4 @@ declare function readAuditExportManifest(data: Uint8Array): AuditExportManifest;
  */
 declare function verifyAuditExportChecksum(data: Uint8Array): Promise<boolean>;
 
-export { AdapterError, ApplyRemoteOptions, type AuditExportManifest, type AuditExportOptions, type AuditExportPayload, type AuditExportProgress, type AuditTraceQuery, type BackupManifest, type BackupOptions, type BackupProgress, COMPACTION_BASELINE_META_KEY, type CollectionAccessor, CollectionRecord, type CompactionResult, type CompactionStrategy, type CreateRichTextControllerOptions, InvalidStateTransitionError, LAST_ACKED_SERVER_VECTOR_META_KEY, LocalMutationHandler, MaterializedRowSnapshot, OrderByDirection, type PersistedAuditTrace, PersistenceError, QueryBuilder, QueryDescriptor, QueryError, QueryStore, QueryStoreCache, RecordNotFoundError, type ReplaySnapshot, type RestoreOptions, type RestoreResult, type RichTextAwarenessUser, type RichTextController, type RichTextControllerSnapshot, type RichTextCursorInfo, type RichTextSyncEngine, SequenceManager, StorageAdapter, Store, StoreConfig, StoreNotOpenError, SubscriptionBloomFilter, SubscriptionCallback, SubscriptionManager, type SubscriptionManagerOptions, type SubscriptionStats, type TransactionCollectionAccessor, TransactionContext, type TransactionContextConfig, WhereClause, WorkerInitError, WorkerTimeoutError, asRichTextSyncEngine, assertQueryReady, collectOperationsAheadOfServer, compactOperationLog, computeAckCompactionWatermark, createRichTextController, decodeAuditExport, decodeRichtext, deserializeVersionVectorFromMeta, encodeRichtext, exportBackup, getSharedQueryStoreCache, mergeVersionVectors, persistedAuditTraceFromEvent, pluralize, readAuditExportManifest, readBackupManifest, restoreBackup, richtextStatesEqual, richtextToPlainText, serializeVersionVectorToMeta, singularize, validateStateTransition, validateUpdateStateMachine, verifyAuditExportChecksum, verifyBackupChecksum };
+export { AdapterError, ApplyRemoteOptions, type AuditExportManifest, type AuditExportOptions, type AuditExportPayload, type AuditExportProgress, type AuditTraceQuery, type BackupManifest, type BackupOptions, type BackupProgress, COMPACTION_BASELINE_META_KEY, type ClockRebaseResult, type CollectionAccessor, CollectionRecord, type CompactionResult, type CompactionStrategy, type CreateRichTextControllerOptions, InvalidStateTransitionError, LAST_ACKED_SERVER_VECTOR_META_KEY, LocalMutationHandler, MaterializedRowSnapshot, OptimisticLockError, OrderByDirection, type PersistedAuditTrace, PersistenceError, QueryBuilder, QueryDescriptor, QueryError, QueryStore, QueryStoreCache, RecordNotFoundError, type ReplaySnapshot, type RestoreOptions, type RestoreResult, type RichTextAwarenessUser, type RichTextController, type RichTextControllerSnapshot, type RichTextCursorInfo, type RichTextSyncEngine, RowVersionState, SequenceManager, StorageAdapter, Store, StoreConfig, StoreNotOpenError, SubscriptionBloomFilter, SubscriptionCallback, SubscriptionManager, type SubscriptionManagerOptions, type SubscriptionStats, type TransactionCollectionAccessor, TransactionContext, type TransactionContextConfig, WhereClause, WorkerInitError, WorkerTimeoutError, asRichTextSyncEngine, assertQueryReady, collectOperationsAheadOfServer, compactOperationLog, computeAckCompactionWatermark, createRichTextController, decodeAuditExport, decodeRichtext, deserializeVersionVectorFromMeta, encodeRichtext, exportBackup, getSharedQueryStoreCache, mergeVersionVectors, persistedAuditTraceFromEvent, pluralize, readAuditExportManifest, readBackupManifest, restoreBackup, richtextStatesEqual, richtextToPlainText, serializeVersionVectorToMeta, singularize, validateStateTransition, validateUpdateStateMachine, verifyAuditExportChecksum, verifyBackupChecksum };

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-import { C as CollectionRecord, S as StorageAdapter, Q as QueryDescriptor, c as SubscriptionCallback, W as WhereClause, d as OrderByDirection, L as LocalMutationHandler, e as StoreConfig, A as ApplyRemoteOptions, f as MaterializedRowSnapshot } from './types-DepnRDk_.js';
-export { M as MigrationPlan, g as OrderByClause, h as StoreIsolation, T as Transaction, i as TransactionBufferedEntry, j as TransactionCommitBatch, k as TransactionCommitResult, l as WhereOperators } from './types-DepnRDk_.js';
-import { Operation, KoraError, VersionVector, SchemaDefinition, MergeTrace, CollectionDefinition, SequenceConfig, HybridLogicalClock, CausalTracker, OperationLog, ApplyResult, StateMachineDefinition, KoraEvent } from '@korajs/core';
+import { C as CollectionRecord, S as StorageAdapter, Q as QueryDescriptor, c as SubscriptionCallback, W as WhereClause, d as OrderByDirection, L as LocalMutationHandler, e as StoreConfig, A as ApplyRemoteOptions, f as MaterializedRowSnapshot, g as RowVersionState } from './types-CJOVKxLw.js';
+export { M as MigrationPlan, h as OrderByClause, i as StoreIsolation, T as Transaction, j as TransactionBufferedEntry, k as TransactionCommitBatch, l as TransactionCommitResult, m as WhereOperators } from './types-CJOVKxLw.js';
+import { Operation, KoraError, VersionVector, SchemaDefinition, HLCTimestamp, MergeTrace, CollectionDefinition, SequenceConfig, HybridLogicalClock, CausalTracker, OperationLog, ApplyResult, StateMachineDefinition, KoraBytesValue, KoraEvent } from '@korajs/core';
 export { ApplyResult } from '@korajs/core';
-import { R as RelationEnforcer, L as LocalMutationContext } from './types-BMyHmwvn.js';
-export { C as Collection } from './types-BMyHmwvn.js';
+import { R as RelationEnforcer, L as LocalMutationContext } from './types-DAxCladl.js';
+export { C as Collection } from './types-DAxCladl.js';
 import * as yjs from 'yjs';
 
 /**
@@ -33,6 +33,18 @@ declare class QueryError extends KoraError {
 declare class RecordNotFoundError extends KoraError {
     constructor(collection: string, recordId: string);
 }
+/**
+ * Thrown inside `applyRemoteOperation` when the row's version state changed
+ * between the caller's snapshot read and the guarded write (a concurrent local
+ * mutation landed in the window). The transaction is rolled back with nothing
+ * written; the caller re-reads fresh state, recomputes its merge, and retries.
+ * This is the optimistic-concurrency guard that keeps merge-engine results
+ * (richtext, add-wins arrays, constraint resolutions) from clobbering newer
+ * local edits they never saw.
+ */
+declare class OptimisticLockError extends KoraError {
+    constructor(collection: string, recordId: string);
+}
 /**
  * Thrown when a storage adapter operation fails.
  */
@@ -101,6 +113,20 @@ declare function computeAckCompactionWatermark(serverVector: VersionVector): Ver
  */
 declare function compactOperationLog(adapter: StorageAdapter, schema: SchemaDefinition, strategy: CompactionStrategy, serverVector: VersionVector): Promise<CompactionResult>;
 
+/**
+ * Result of re-stamping unsynced operations after a clock correction.
+ */
+interface ClockRebaseResult {
+    /** The rewritten operations, in causal order (original HLC total order preserved). */
+    operations: Operation[];
+    /** Maps each old (pre-rebase) operation id to its new content-addressed id. */
+    idMapping: Record<string, string>;
+    /** Number of operations that were re-stamped. */
+    rebasedCount: number;
+    /** Highest timestamp assigned during the rebase, or null when nothing was rebased. */
+    newMaxTimestamp: HLCTimestamp | null;
+}
+
 declare const LAST_ACKED_SERVER_VECTOR_META_KEY = "last_acked_server_vector";
 /**
  * Serialize a version vector for `_kora_meta` storage.
@@ -715,6 +741,12 @@ declare class Store implements OperationLog {
     /**
      * Get the node ID for this store instance.
      */
+    /**
+     * Records the offset between server time and this device's clock
+     * (serverTime - localTime), learned at sync handshake. Lets the store's HLC
+     * validate remote timestamps correctly even when the local clock is wrong.
+     */
+    setClockReferenceOffset(offsetMs: number): void;
     getNodeId(): string;
     /**
      * Apply a remote operation received from sync.
@@ -722,6 +754,18 @@ declare class Store implements OperationLog {
      * and updates the version vector.
      */
     applyRemoteOperation(op: Operation, options?: ApplyRemoteOptions): Promise<ApplyResult>;
+    /**
+     * Materialize update/delete operations that were logged for a record BEFORE
+     * its insert arrived (reordered delivery). Runs inside the insert's write
+     * transaction, folding each orphan in timestamp order through the exact
+     * per-field LWW / LWW-delete rules the normal apply paths use, so the final
+     * row state equals what a device that received the operations in causal
+     * order computed. Called only when the insert created a previously-absent
+     * row — in that case every logged update/delete for the record is
+     * necessarily an orphan (rows are soft-deleted, never removed, so a row
+     * that is absent now was never materialized).
+     */
+    private foldOrphanedOperations;
     /**
      * Get operations from a node within a sequence number range.
      * Implements the OperationLog interface for computeDelta.
@@ -775,6 +819,14 @@ declare class Store implements OperationLog {
      * Load a materialized row by ID, including soft-deleted tombstones.
      */
     findMaterializedRow(collection: string, recordId: string): Promise<MaterializedRowSnapshot | null>;
+    /**
+     * Raw version state of a materialized row, for optimistic-concurrency guarded
+     * applies: capture this snapshot before computing a merge, pass it as
+     * `guardRowState`, and the apply refuses to write if the row changed since.
+     * Returns null when no row exists (which is itself a valid guard state — the
+     * apply then requires the row to still be absent).
+     */
+    getRowVersionState(collection: string, recordId: string): Promise<RowVersionState | null>;
     /**
      * Latest operation from this device for a record (used for delete-vs-update merge on sync).
      */
@@ -798,6 +850,18 @@ declare class Store implements OperationLog {
      * Local operations not yet reflected on the server version vector.
      */
     getUnsyncedOperations(serverVector: VersionVector): Promise<Operation[]>;
+    /**
+     * Re-stamp never-acknowledged local operations after a fast device clock was
+     * corrected, so sync can resume immediately. Safe because unacknowledged
+     * operations are private to this device (like unpushed git commits);
+     * acknowledged/shared operations are immutable and never touched.
+     *
+     * After the rewrite the store's HLC is advanced past the highest new
+     * timestamp so subsequent local writes keep sorting after the rebased ops.
+     * No data-change notifications are emitted: materialized values are
+     * unchanged, only version stamps move.
+     */
+    rebaseUnsyncedOperations(unsyncedOpIds: string[], correctedNowMs: number): Promise<ClockRebaseResult>;
     /**
      * Count of local operations ahead of the server version vector.
      */
@@ -1185,8 +1249,14 @@ declare function asRichTextSyncEngine(engine: unknown): RichTextSyncEngine | nul
 type RichtextInput = string | Uint8Array | ArrayBuffer | null | undefined;
 /**
  * Encodes richtext values into Yjs document updates.
+ *
+ * Also accepts the tagged `{ $koraBytes }` form that binary richtext values
+ * take inside `op.data` (and, for old dev databases, the pre-fix numeric-key
+ * object shape), so every consumer that writes op-data values to columns
+ * inherits the decoding. Plain strings keep their exact historical behavior:
+ * encoded as a fresh Yjs document containing the string.
  */
-declare function encodeRichtext(value: RichtextInput): Uint8Array | null;
+declare function encodeRichtext(value: RichtextInput | KoraBytesValue): Uint8Array | null;
 /**
  * Decodes driver-provided richtext values into Uint8Array.
  */
@@ -1287,4 +1357,4 @@ declare function readAuditExportManifest(data: Uint8Array): AuditExportManifest;
  */
 declare function verifyAuditExportChecksum(data: Uint8Array): Promise<boolean>;
 
-export { AdapterError, ApplyRemoteOptions, type AuditExportManifest, type AuditExportOptions, type AuditExportPayload, type AuditExportProgress, type AuditTraceQuery, type BackupManifest, type BackupOptions, type BackupProgress, COMPACTION_BASELINE_META_KEY, type CollectionAccessor, CollectionRecord, type CompactionResult, type CompactionStrategy, type CreateRichTextControllerOptions, InvalidStateTransitionError, LAST_ACKED_SERVER_VECTOR_META_KEY, LocalMutationHandler, MaterializedRowSnapshot, OrderByDirection, type PersistedAuditTrace, PersistenceError, QueryBuilder, QueryDescriptor, QueryError, QueryStore, QueryStoreCache, RecordNotFoundError, type ReplaySnapshot, type RestoreOptions, type RestoreResult, type RichTextAwarenessUser, type RichTextController, type RichTextControllerSnapshot, type RichTextCursorInfo, type RichTextSyncEngine, SequenceManager, StorageAdapter, Store, StoreConfig, StoreNotOpenError, SubscriptionBloomFilter, SubscriptionCallback, SubscriptionManager, type SubscriptionManagerOptions, type SubscriptionStats, type TransactionCollectionAccessor, TransactionContext, type TransactionContextConfig, WhereClause, WorkerInitError, WorkerTimeoutError, asRichTextSyncEngine, assertQueryReady, collectOperationsAheadOfServer, compactOperationLog, computeAckCompactionWatermark, createRichTextController, decodeAuditExport, decodeRichtext, deserializeVersionVectorFromMeta, encodeRichtext, exportBackup, getSharedQueryStoreCache, mergeVersionVectors, persistedAuditTraceFromEvent, pluralize, readAuditExportManifest, readBackupManifest, restoreBackup, richtextStatesEqual, richtextToPlainText, serializeVersionVectorToMeta, singularize, validateStateTransition, validateUpdateStateMachine, verifyAuditExportChecksum, verifyBackupChecksum };
+export { AdapterError, ApplyRemoteOptions, type AuditExportManifest, type AuditExportOptions, type AuditExportPayload, type AuditExportProgress, type AuditTraceQuery, type BackupManifest, type BackupOptions, type BackupProgress, COMPACTION_BASELINE_META_KEY, type ClockRebaseResult, type CollectionAccessor, CollectionRecord, type CompactionResult, type CompactionStrategy, type CreateRichTextControllerOptions, InvalidStateTransitionError, LAST_ACKED_SERVER_VECTOR_META_KEY, LocalMutationHandler, MaterializedRowSnapshot, OptimisticLockError, OrderByDirection, type PersistedAuditTrace, PersistenceError, QueryBuilder, QueryDescriptor, QueryError, QueryStore, QueryStoreCache, RecordNotFoundError, type ReplaySnapshot, type RestoreOptions, type RestoreResult, type RichTextAwarenessUser, type RichTextController, type RichTextControllerSnapshot, type RichTextCursorInfo, type RichTextSyncEngine, RowVersionState, SequenceManager, StorageAdapter, Store, StoreConfig, StoreNotOpenError, SubscriptionBloomFilter, SubscriptionCallback, SubscriptionManager, type SubscriptionManagerOptions, type SubscriptionStats, type TransactionCollectionAccessor, TransactionContext, type TransactionContextConfig, WhereClause, WorkerInitError, WorkerTimeoutError, asRichTextSyncEngine, assertQueryReady, collectOperationsAheadOfServer, compactOperationLog, computeAckCompactionWatermark, createRichTextController, decodeAuditExport, decodeRichtext, deserializeVersionVectorFromMeta, encodeRichtext, exportBackup, getSharedQueryStoreCache, mergeVersionVectors, persistedAuditTraceFromEvent, pluralize, readAuditExportManifest, readBackupManifest, restoreBackup, richtextStatesEqual, richtextToPlainText, serializeVersionVectorToMeta, singularize, validateStateTransition, validateUpdateStateMachine, verifyAuditExportChecksum, verifyBackupChecksum };