@korajs/sync 0.6.0 → 1.0.0-beta.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { S as SyncScopeMap, D as DeltaCursor, a as SyncMessage, b as SerializedOperation, W as WireFormat, c as SyncTransport, T as TransportOptions, d as TransportMessageHandler, e as TransportCloseHandler, f as TransportErrorHandler, g as SyncEncryptionConfig, V as VersionedKey, Y as YjsDocUpdateMessage, Q as QueueStorage, h as SyncState, i as SyncStatusInfo, j as SyncConfig, k as SyncStatePersistence, l as SyncQuerySubset } from './transport-BrdBj7rH.cjs';
-export { A as AcknowledgmentMessage, m as AwarenessStateWire, n as AwarenessUpdateMessage, E as EncryptedPayload, o as ErrorMessage, H as HandshakeMessage, p as HandshakeResponseMessage, I as InvalidScopeError, O as OperationBatchMessage, q as SYNC_STATES, r as SYNC_STATUSES, s as ScopeViolationError, t as SyncEncryptionAlgorithm, u as SyncScopeContext, v as SyncStatus, w as dedupeQuerySubsets, x as isAcknowledgmentMessage, y as isAwarenessUpdateMessage, z as isErrorMessage, B as isHandshakeMessage, C as isHandshakeResponseMessage, F as isOperationBatchMessage, G as isSyncMessage, J as isYjsDocUpdateMessage, K as operationMatchesQuerySubsets } from './transport-BrdBj7rH.cjs';
+import { S as SyncScopeMap, D as DeltaCursor, a as SyncMessage, b as SerializedOperation, W as WireFormat, c as SyncTransport, T as TransportOptions, d as TransportMessageHandler, e as TransportCloseHandler, f as TransportErrorHandler, g as SyncEncryptionConfig, V as VersionedKey, Y as YjsDocUpdateMessage, Q as QueueStorage, h as SyncState, i as SyncStatusInfo, j as SyncConfig, k as SyncStatePersistence, l as SyncQuerySubset } from './transport-BMesMB6s.cjs';
+export { A as AcknowledgmentMessage, m as AwarenessStateWire, n as AwarenessUpdateMessage, E as EncryptedPayload, o as ErrorMessage, H as HandshakeMessage, p as HandshakeResponseMessage, I as InvalidScopeError, O as OperationBatchMessage, q as SYNC_STATES, r as SYNC_STATUSES, s as ScopeViolationError, t as SyncEncryptionAlgorithm, u as SyncScopeContext, v as SyncStatus, w as dedupeQuerySubsets, x as isAcknowledgmentMessage, y as isAwarenessUpdateMessage, z as isErrorMessage, B as isHandshakeMessage, C as isHandshakeResponseMessage, F as isOperationBatchMessage, G as isSyncMessage, J as isYjsDocUpdateMessage, K as operationMatchesQuerySubsets } from './transport-BMesMB6s.cjs';
 import * as _korajs_core from '@korajs/core';
 import { Operation, VersionVector, ApplyResult, KoraEventEmitter, TimeSource, SyncError, ConnectionQuality } from '@korajs/core';
 export { ApplyFailureReason, ApplyResult } from '@korajs/core';
@@ -81,6 +81,20 @@ interface SyncStore {
      * @param toSeq - End sequence number (inclusive)
      */
     getOperationRange(nodeId: string, fromSeq: number, toSeq: number): Promise<Operation[]>;
+    /**
+     * Optional: re-stamp never-acknowledged local operations after a fast device
+     * clock was corrected (timestamp rebase). Optional so hand-rolled SyncStore
+     * implementations keep working; when absent the engine simply skips the
+     * rebase and falls back to the clock-block behavior.
+     *
+     * @param ids - Operation ids that are candidates for re-stamping
+     * @param correctedNowMs - Trusted "now" (server time at handshake) in ms
+     */
+    rebaseUnsyncedOperations?(ids: string[], correctedNowMs: number): Promise<{
+        operations: Operation[];
+        idMapping: Record<string, string>;
+        rebasedCount: number;
+    }>;
 }
 
 /** Prefix for handshake rejection when client schema version is unsupported. */
@@ -275,7 +289,7 @@ declare class ChaosTransport implements SyncTransport {
     private readonly random;
     private messageHandler;
     private reorderBuffer;
-    private timers;
+    private pending;
     constructor(inner: SyncTransport, config?: ChaosConfig);
     connect(url: string, options?: TransportOptions): Promise<void>;
     disconnect(): Promise<void>;
@@ -529,11 +543,13 @@ declare class SyncEncryptor {
      * @param config - Encryption configuration with passphrase
      * @param salt - Optional salt for deterministic key derivation (mainly for testing).
      *              If omitted, a random salt is generated.
+     * @param iterations - Optional PBKDF2 iteration count. Defaults to the
+     *              production-strength value. Lower it only in tests.
      * @returns A configured SyncEncryptor instance
      * @throws {EncryptionError} If configuration is invalid
      * @throws {KeyDerivationError} If key derivation fails
      */
-    static create(config: SyncEncryptionConfig, salt?: Uint8Array): Promise<SyncEncryptor>;
+    static create(config: SyncEncryptionConfig, salt?: Uint8Array, iterations?: number): Promise<SyncEncryptor>;
     /**
      * Creates a SyncEncryptor from pre-derived versioned keys.
      *
@@ -745,6 +761,20 @@ declare class OutboundQueue {
      * Peek at the first `count` operations without removing them.
      */
     peek(count: number): Operation[];
+    /**
+     * All queued operations (not counting in-flight), in causal order.
+     */
+    getAll(): Operation[];
+    /**
+     * Atomically replace the entire queue with a new set of operations.
+     *
+     * Used after a timestamp rebase rewrote the queued operations under new
+     * content-addressed ids: the old entries must vanish from memory AND from
+     * persistent storage in one step, or a page refresh could resurrect
+     * stale-stamped ops the server would reject. Resets the seen set to exactly
+     * the new ids so the rewritten ops are not treated as duplicates.
+     */
+    replaceAll(ops: Operation[]): Promise<void>;
     /**
      * Whether initialize() has been called.
      */
@@ -832,6 +862,8 @@ declare class SyncEngine {
     private currentBatch;
     private reconnecting;
     private schemaBlocked;
+    private clockBlocked;
+    private clockSkewMs;
     private deltaBatchesReceived;
     private deltaReceiveComplete;
     private deltaSendComplete;
@@ -885,6 +917,18 @@ declare class SyncEngine {
      * Sync stays blocked until the app schema is upgraded or sync config changes.
      */
     isSchemaBlocked(): boolean;
+    /**
+     * True when sync is blocked because this device's clock is too far ahead.
+     * Local writes continue to work and queue; only sync is paused.
+     */
+    isClockBlocked(): boolean;
+    /** serverTime - localTime measured at the last handshake, or null before first connect. */
+    getClockSkewMs(): number | null;
+    /**
+     * Clears the clock block after the user corrects the device clock.
+     * Moves the engine back to `disconnected` so `start()` can run again.
+     */
+    clearClockBlock(): void;
     /**
      * Clears schema-mismatch block after upgrading the local schema / sync config.
      * Moves the engine back to `disconnected` so `start()` can run again.
@@ -958,7 +1002,22 @@ declare class SyncEngine {
     private enqueueMessage;
     private handleMessageAsync;
     private handleMessageFailure;
+    /**
+     * Compares server wall-clock time from the handshake with local time.
+     * Negative skew = this device's clock is fast (dangerous for LWW and rejected
+     * by server ingest beyond 60s). Positive skew = slow (accepted but surfaced).
+     * Zero developer work required: the result flows into sync status and events.
+     */
+    private evaluateClockSkew;
     private handleHandshakeResponse;
+    /**
+     * Re-stamps queued (never-acknowledged) operations whose timestamps are far
+     * enough in the future that the server would reject them, using the server's
+     * own handshake time as the trusted "now". This is the automatic recovery
+     * path after a user corrects a fast device clock: the queue drains
+     * immediately instead of waiting for real time to catch up.
+     */
+    private maybeRebaseQueuedOperations;
     private sendDelta;
     private markDeltaSendCompleteIfReady;
     private collectDelta;
@@ -1164,6 +1223,9 @@ declare function generateSalt(): Uint8Array;
  *
  * @param passphrase - The user's passphrase (must be non-empty)
  * @param salt - Optional salt bytes. If omitted, a random 32-byte salt is generated.
+ * @param iterations - Optional PBKDF2 iteration count. Defaults to
+ *   {@link DEFAULT_PBKDF2_ITERATIONS}. Lower it only in tests; production must
+ *   keep the default so derived keys stay brute-force resistant.
  * @returns The derived CryptoKey and the salt used
  * @throws {KeyDerivationError} If the passphrase is empty, crypto is unavailable, or derivation fails
  *
@@ -1176,7 +1238,7 @@ declare function generateSalt(): Uint8Array;
  * const { key: sameKey } = await deriveKey('my-secure-passphrase', salt)
  * ```
  */
-declare function deriveKey(passphrase: string, salt?: Uint8Array): Promise<{
+declare function deriveKey(passphrase: string, salt?: Uint8Array, iterations?: number): Promise<{
     key: CryptoKey;
     salt: Uint8Array;
 }>;
@@ -1190,10 +1252,12 @@ declare function deriveKey(passphrase: string, salt?: Uint8Array): Promise<{
  * @param passphrase - The user's passphrase
  * @param version - Key version number (must be a positive integer)
  * @param salt - Optional salt bytes. If omitted, a random salt is generated.
+ * @param iterations - Optional PBKDF2 iteration count. Defaults to
+ *   {@link DEFAULT_PBKDF2_ITERATIONS}. Lower it only in tests.
  * @returns A {@link VersionedKey} containing the key, version, and salt
  * @throws {KeyDerivationError} If parameters are invalid or derivation fails
  */
-declare function deriveVersionedKey(passphrase: string, version: number, salt?: Uint8Array): Promise<VersionedKey>;
+declare function deriveVersionedKey(passphrase: string, version: number, salt?: Uint8Array, iterations?: number): Promise<VersionedKey>;
 
 /** Default status when sync is not configured or the engine is unavailable. */
 declare const OFFLINE_SYNC_STATUS: SyncStatusInfo;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { S as SyncScopeMap, D as DeltaCursor, a as SyncMessage, b as SerializedOperation, W as WireFormat, c as SyncTransport, T as TransportOptions, d as TransportMessageHandler, e as TransportCloseHandler, f as TransportErrorHandler, g as SyncEncryptionConfig, V as VersionedKey, Y as YjsDocUpdateMessage, Q as QueueStorage, h as SyncState, i as SyncStatusInfo, j as SyncConfig, k as SyncStatePersistence, l as SyncQuerySubset } from './transport-BrdBj7rH.js';
-export { A as AcknowledgmentMessage, m as AwarenessStateWire, n as AwarenessUpdateMessage, E as EncryptedPayload, o as ErrorMessage, H as HandshakeMessage, p as HandshakeResponseMessage, I as InvalidScopeError, O as OperationBatchMessage, q as SYNC_STATES, r as SYNC_STATUSES, s as ScopeViolationError, t as SyncEncryptionAlgorithm, u as SyncScopeContext, v as SyncStatus, w as dedupeQuerySubsets, x as isAcknowledgmentMessage, y as isAwarenessUpdateMessage, z as isErrorMessage, B as isHandshakeMessage, C as isHandshakeResponseMessage, F as isOperationBatchMessage, G as isSyncMessage, J as isYjsDocUpdateMessage, K as operationMatchesQuerySubsets } from './transport-BrdBj7rH.js';
+import { S as SyncScopeMap, D as DeltaCursor, a as SyncMessage, b as SerializedOperation, W as WireFormat, c as SyncTransport, T as TransportOptions, d as TransportMessageHandler, e as TransportCloseHandler, f as TransportErrorHandler, g as SyncEncryptionConfig, V as VersionedKey, Y as YjsDocUpdateMessage, Q as QueueStorage, h as SyncState, i as SyncStatusInfo, j as SyncConfig, k as SyncStatePersistence, l as SyncQuerySubset } from './transport-BMesMB6s.js';
+export { A as AcknowledgmentMessage, m as AwarenessStateWire, n as AwarenessUpdateMessage, E as EncryptedPayload, o as ErrorMessage, H as HandshakeMessage, p as HandshakeResponseMessage, I as InvalidScopeError, O as OperationBatchMessage, q as SYNC_STATES, r as SYNC_STATUSES, s as ScopeViolationError, t as SyncEncryptionAlgorithm, u as SyncScopeContext, v as SyncStatus, w as dedupeQuerySubsets, x as isAcknowledgmentMessage, y as isAwarenessUpdateMessage, z as isErrorMessage, B as isHandshakeMessage, C as isHandshakeResponseMessage, F as isOperationBatchMessage, G as isSyncMessage, J as isYjsDocUpdateMessage, K as operationMatchesQuerySubsets } from './transport-BMesMB6s.js';
 import * as _korajs_core from '@korajs/core';
 import { Operation, VersionVector, ApplyResult, KoraEventEmitter, TimeSource, SyncError, ConnectionQuality } from '@korajs/core';
 export { ApplyFailureReason, ApplyResult } from '@korajs/core';
@@ -81,6 +81,20 @@ interface SyncStore {
      * @param toSeq - End sequence number (inclusive)
      */
     getOperationRange(nodeId: string, fromSeq: number, toSeq: number): Promise<Operation[]>;
+    /**
+     * Optional: re-stamp never-acknowledged local operations after a fast device
+     * clock was corrected (timestamp rebase). Optional so hand-rolled SyncStore
+     * implementations keep working; when absent the engine simply skips the
+     * rebase and falls back to the clock-block behavior.
+     *
+     * @param ids - Operation ids that are candidates for re-stamping
+     * @param correctedNowMs - Trusted "now" (server time at handshake) in ms
+     */
+    rebaseUnsyncedOperations?(ids: string[], correctedNowMs: number): Promise<{
+        operations: Operation[];
+        idMapping: Record<string, string>;
+        rebasedCount: number;
+    }>;
 }
 
 /** Prefix for handshake rejection when client schema version is unsupported. */
@@ -275,7 +289,7 @@ declare class ChaosTransport implements SyncTransport {
     private readonly random;
     private messageHandler;
     private reorderBuffer;
-    private timers;
+    private pending;
     constructor(inner: SyncTransport, config?: ChaosConfig);
     connect(url: string, options?: TransportOptions): Promise<void>;
     disconnect(): Promise<void>;
@@ -529,11 +543,13 @@ declare class SyncEncryptor {
      * @param config - Encryption configuration with passphrase
      * @param salt - Optional salt for deterministic key derivation (mainly for testing).
      *              If omitted, a random salt is generated.
+     * @param iterations - Optional PBKDF2 iteration count. Defaults to the
+     *              production-strength value. Lower it only in tests.
      * @returns A configured SyncEncryptor instance
      * @throws {EncryptionError} If configuration is invalid
      * @throws {KeyDerivationError} If key derivation fails
      */
-    static create(config: SyncEncryptionConfig, salt?: Uint8Array): Promise<SyncEncryptor>;
+    static create(config: SyncEncryptionConfig, salt?: Uint8Array, iterations?: number): Promise<SyncEncryptor>;
     /**
      * Creates a SyncEncryptor from pre-derived versioned keys.
      *
@@ -745,6 +761,20 @@ declare class OutboundQueue {
      * Peek at the first `count` operations without removing them.
      */
     peek(count: number): Operation[];
+    /**
+     * All queued operations (not counting in-flight), in causal order.
+     */
+    getAll(): Operation[];
+    /**
+     * Atomically replace the entire queue with a new set of operations.
+     *
+     * Used after a timestamp rebase rewrote the queued operations under new
+     * content-addressed ids: the old entries must vanish from memory AND from
+     * persistent storage in one step, or a page refresh could resurrect
+     * stale-stamped ops the server would reject. Resets the seen set to exactly
+     * the new ids so the rewritten ops are not treated as duplicates.
+     */
+    replaceAll(ops: Operation[]): Promise<void>;
     /**
      * Whether initialize() has been called.
      */
@@ -832,6 +862,8 @@ declare class SyncEngine {
     private currentBatch;
     private reconnecting;
     private schemaBlocked;
+    private clockBlocked;
+    private clockSkewMs;
     private deltaBatchesReceived;
     private deltaReceiveComplete;
     private deltaSendComplete;
@@ -885,6 +917,18 @@ declare class SyncEngine {
      * Sync stays blocked until the app schema is upgraded or sync config changes.
      */
     isSchemaBlocked(): boolean;
+    /**
+     * True when sync is blocked because this device's clock is too far ahead.
+     * Local writes continue to work and queue; only sync is paused.
+     */
+    isClockBlocked(): boolean;
+    /** serverTime - localTime measured at the last handshake, or null before first connect. */
+    getClockSkewMs(): number | null;
+    /**
+     * Clears the clock block after the user corrects the device clock.
+     * Moves the engine back to `disconnected` so `start()` can run again.
+     */
+    clearClockBlock(): void;
     /**
      * Clears schema-mismatch block after upgrading the local schema / sync config.
      * Moves the engine back to `disconnected` so `start()` can run again.
@@ -958,7 +1002,22 @@ declare class SyncEngine {
     private enqueueMessage;
     private handleMessageAsync;
     private handleMessageFailure;
+    /**
+     * Compares server wall-clock time from the handshake with local time.
+     * Negative skew = this device's clock is fast (dangerous for LWW and rejected
+     * by server ingest beyond 60s). Positive skew = slow (accepted but surfaced).
+     * Zero developer work required: the result flows into sync status and events.
+     */
+    private evaluateClockSkew;
     private handleHandshakeResponse;
+    /**
+     * Re-stamps queued (never-acknowledged) operations whose timestamps are far
+     * enough in the future that the server would reject them, using the server's
+     * own handshake time as the trusted "now". This is the automatic recovery
+     * path after a user corrects a fast device clock: the queue drains
+     * immediately instead of waiting for real time to catch up.
+     */
+    private maybeRebaseQueuedOperations;
     private sendDelta;
     private markDeltaSendCompleteIfReady;
     private collectDelta;
@@ -1164,6 +1223,9 @@ declare function generateSalt(): Uint8Array;
  *
  * @param passphrase - The user's passphrase (must be non-empty)
  * @param salt - Optional salt bytes. If omitted, a random 32-byte salt is generated.
+ * @param iterations - Optional PBKDF2 iteration count. Defaults to
+ *   {@link DEFAULT_PBKDF2_ITERATIONS}. Lower it only in tests; production must
+ *   keep the default so derived keys stay brute-force resistant.
  * @returns The derived CryptoKey and the salt used
  * @throws {KeyDerivationError} If the passphrase is empty, crypto is unavailable, or derivation fails
  *
@@ -1176,7 +1238,7 @@ declare function generateSalt(): Uint8Array;
  * const { key: sameKey } = await deriveKey('my-secure-passphrase', salt)
  * ```
  */
-declare function deriveKey(passphrase: string, salt?: Uint8Array): Promise<{
+declare function deriveKey(passphrase: string, salt?: Uint8Array, iterations?: number): Promise<{
     key: CryptoKey;
     salt: Uint8Array;
 }>;
@@ -1190,10 +1252,12 @@ declare function deriveKey(passphrase: string, salt?: Uint8Array): Promise<{
  * @param passphrase - The user's passphrase
  * @param version - Key version number (must be a positive integer)
  * @param salt - Optional salt bytes. If omitted, a random salt is generated.
+ * @param iterations - Optional PBKDF2 iteration count. Defaults to
+ *   {@link DEFAULT_PBKDF2_ITERATIONS}. Lower it only in tests.
  * @returns A {@link VersionedKey} containing the key, version, and salt
  * @throws {KeyDerivationError} If parameters are invalid or derivation fails
  */
-declare function deriveVersionedKey(passphrase: string, version: number, salt?: Uint8Array): Promise<VersionedKey>;
+declare function deriveVersionedKey(passphrase: string, version: number, salt?: Uint8Array, iterations?: number): Promise<VersionedKey>;
 
 /** Default status when sync is not configured or the engine is unavailable. */
 declare const OFFLINE_SYNC_STATUS: SyncStatusInfo;