@korajs/core 0.5.0 → 1.0.0-beta.0

package/dist/index.cjs

@@ -22,6 +22,7 @@ var index_exports = {};
 __export(index_exports, {
   APPLY_FAILURE_CODES: () => APPLY_FAILURE_CODES,
   APPLY_RESULTS: () => APPLY_RESULTS,
+  AppNotReadyError: () => AppNotReadyError,
   ArrayFieldBuilder: () => ArrayFieldBuilder,
   CONNECTION_QUALITIES: () => CONNECTION_QUALITIES,
   CausalTracker: () => CausalTracker,
@@ -29,21 +30,26 @@ __export(index_exports, {
   EnumFieldBuilder: () => EnumFieldBuilder,
   FieldBuilder: () => FieldBuilder,
   HybridLogicalClock: () => HybridLogicalClock,
+  InvalidTimestampError: () => InvalidTimestampError,
   KORA_ERROR_FIX_SUGGESTIONS: () => KORA_ERROR_FIX_SUGGESTIONS,
   KoraError: () => KoraError,
+  MAX_LOGICAL: () => MAX_LOGICAL,
   MERGE_STRATEGIES: () => MERGE_STRATEGIES,
   MergeConflictError: () => MergeConflictError,
   MigrationBuilder: () => MigrationBuilder,
   MigrationRollbackError: () => MigrationRollbackError,
   OperationError: () => OperationError,
+  RemoteClockDriftError: () => RemoteClockDriftError,
   RollbackBuilder: () => RollbackBuilder,
   SchemaValidationError: () => SchemaValidationError,
   StorageError: () => StorageError,
   SyncError: () => SyncError,
   advanceVector: () => advanceVector,
   applyOperationTransforms: () => applyOperationTransforms,
+  base64ToBytes: () => base64ToBytes,
   buildScopeMap: () => buildScopeMap,
   buildStateMachineConstraints: () => buildStateMachineConstraints,
+  bytesToBase64: () => bytesToBase64,
   canAutoRollback: () => canAutoRollback,
   collectSchemaScopeFields: () => collectSchemaScopeFields,
   collectSchemaScopeValueKeys: () => collectSchemaScopeValueKeys,
@@ -51,11 +57,13 @@ __export(index_exports, {
   createOperation: () => createOperation,
   createReversibleMigration: () => createReversibleMigration,
   createVersionVector: () => createVersionVector,
+  decodeBytesFromOpData: () => decodeBytesFromOpData,
   defaultApplyFailureReason: () => defaultApplyFailureReason,
   defaultSequenceFormat: () => defaultSequenceFormat,
   defineSchema: () => defineSchema,
   deserializeVector: () => deserializeVector,
   dominates: () => dominates,
+  encodeBytesForOpData: () => encodeBytesForOpData,
   extractScopeValuesFromClaims: () => extractScopeValuesFromClaims,
   extractTimestamp: () => extractTimestamp,
   formatSequenceValue: () => formatSequenceValue,
@@ -71,6 +79,8 @@ __export(index_exports, {
   isApplyFailure: () => isApplyFailure,
   isAtomicOp: () => isAtomicOp,
   isCollectionSyncScoped: () => isCollectionSyncScoped,
+  isKoraBytesValue: () => isKoraBytesValue,
+  isLegacyNumericByteObject: () => isLegacyNumericByteObject,
   isValidOperation: () => isValidOperation,
   isValidUUIDv7: () => isValidUUIDv7,
   mergeVectors: () => mergeVectors,
@@ -107,6 +117,7 @@ var KORA_ERROR_FIX_SUGGESTIONS = {
   SYNC_ERROR: "Verify the sync server URL, auth token, and that the server accepts your schema version.",
   STORAGE_ERROR: "Confirm the storage adapter is supported in this environment and the database path is writable.",
   CLOCK_DRIFT: "Sync device wall-clock time (NTP). Kora refuses new timestamps when drift exceeds five minutes.",
+  INVALID_TIMESTAMP_FIELDS: "HLC timestamps need non-negative integer wallTime (< 10^15) and logical (<= 99999). Generate timestamps through HybridLogicalClock instead of building them by hand.",
   PERSISTENCE_ERROR: "IndexedDB persistence failed; check browser storage settings and available disk quota.",
   MISSING_WORKER_URL: "Pass store.workerUrl pointing to sqlite-wasm-worker.js (see create-kora-app templates).",
   INVALID_SYNC_URL: "Use ws:// or wss:// for WebSocket transport, or http(s):// for HTTP long-polling.",
@@ -177,6 +188,39 @@ var StorageError = class extends KoraError {
     this.name = "StorageError";
   }
 };
+var AppNotReadyError = class extends KoraError {
+  constructor(detail) {
+    super(detail, "APP_NOT_READY", {
+      fix: "Await app.ready, or wrap your UI in <KoraProvider app={app}> before calling useQuery()."
+    });
+    this.name = "AppNotReadyError";
+  }
+};
+var RemoteClockDriftError = class extends KoraError {
+  constructor(remoteWallTime, localReferenceTime) {
+    const aheadSeconds = Math.round((remoteWallTime - localReferenceTime) / 1e3);
+    super(
+      `Rejected remote timestamp ${aheadSeconds}s ahead of local reference time. The sending device's clock is set too far in the future.`,
+      "REMOTE_CLOCK_DRIFT",
+      { remoteWallTime, localReferenceTime, aheadSeconds }
+    );
+    this.remoteWallTime = remoteWallTime;
+    this.localReferenceTime = localReferenceTime;
+    this.name = "RemoteClockDriftError";
+  }
+  remoteWallTime;
+  localReferenceTime;
+};
+var InvalidTimestampError = class extends KoraError {
+  constructor(message, wallTime, logical) {
+    super(message, "INVALID_TIMESTAMP_FIELDS", { wallTime, logical });
+    this.wallTime = wallTime;
+    this.logical = logical;
+    this.name = "InvalidTimestampError";
+  }
+  wallTime;
+  logical;
+};
 var ClockDriftError = class extends KoraError {
   constructor(currentHlcTime, physicalTime) {
     const driftSeconds = Math.round((currentHlcTime - physicalTime) / 1e3);
@@ -195,24 +239,51 @@ var ClockDriftError = class extends KoraError {
 
 // src/clock/hlc.ts
 var systemTimeSource = { now: () => Date.now() };
+var MAX_LOGICAL = 99999;
+var LOGICAL_MODULUS = MAX_LOGICAL + 1;
+var WALL_TIME_LIMIT = 10 ** 15;
 var DRIFT_WARN_MS = 6e4;
 var DRIFT_ERROR_MS = 5 * 6e4;
-var HybridLogicalClock = class {
-  constructor(nodeId, timeSource = systemTimeSource, onDriftWarning) {
+var MAX_REMOTE_FUTURE_MS = 5 * 6e4;
+var HybridLogicalClock = class _HybridLogicalClock {
+  constructor(nodeId, timeSource = systemTimeSource, onDriftWarning, onDriftError) {
     this.nodeId = nodeId;
     this.timeSource = timeSource;
     this.onDriftWarning = onDriftWarning;
+    this.onDriftError = onDriftError;
   }
   nodeId;
   timeSource;
   onDriftWarning;
+  onDriftError;
   wallTime = 0;
   logical = 0;
+  referenceOffsetMs = null;
+  /**
+   * Records the known offset between an external time reference (usually the
+   * sync server, learned at handshake) and this device's physical clock:
+   * `referenceTime - localPhysicalTime`. Once set, drift evaluation and remote
+   * timestamp validation are performed against reference-corrected time, so a
+   * device with a wrong local clock still validates remote timestamps correctly.
+   */
+  setReferenceOffset(offsetMs) {
+    this.referenceOffsetMs = offsetMs;
+  }
+  getReferenceOffset() {
+    return this.referenceOffsetMs;
+  }
+  /** Physical time corrected by the known reference offset, when available. */
+  effectiveTime(physicalTime) {
+    return physicalTime + (this.referenceOffsetMs ?? 0);
+  }
   /**
    * Generate a new timestamp for a local event.
    * Guarantees monotonicity: each call returns a timestamp strictly greater than the previous.
    *
-   * @throws {ClockDriftError} If physical time is more than 5 minutes behind the HLC wallTime
+   * Never throws and never blocks a local write: if the physical clock has
+   * fallen behind the HLC (e.g. the user corrected a fast clock), the HLC
+   * freezes wallTime and advances the logical counter, and drift is reported
+   * through the onDriftWarning / onDriftError callbacks instead.
    */
   now() {
     const physicalTime = this.timeSource.now();
@@ -223,17 +294,40 @@ var HybridLogicalClock = class {
     } else {
       this.logical++;
     }
+    this.carryLogicalOverflow();
     return { wallTime: this.wallTime, logical: this.logical, nodeId: this.nodeId };
   }
   /**
    * Update clock on receiving a remote timestamp.
    * Merges the remote clock state with the local state to maintain causal ordering.
    *
-   * @throws {ClockDriftError} If physical time is more than 5 minutes behind the resulting wallTime
+   * @throws {InvalidTimestampError} If the remote timestamp has non-integer or
+   * negative wallTime/logical, or logical beyond {@link MAX_LOGICAL}. Checked
+   * BEFORE any state change, so malformed input cannot corrupt this clock.
+   * @throws {RemoteClockDriftError} If the remote timestamp is more than 5 minutes
+   * ahead of reference-corrected local time. Validation happens BEFORE any state
+   * is adopted, so a rejected timestamp cannot poison this clock. When no
+   * reference offset is known and this clock is uninitialized (cold start with
+   * a possibly-wrong local clock), validation is skipped, matching the previous
+   * cold-start behavior but now without a corrupting failure mode afterward.
    */
   receive(remote) {
     const physicalTime = this.timeSource.now();
     const wasColdStart = this.wallTime === 0;
+    if (!Number.isInteger(remote.wallTime) || remote.wallTime < 0 || !Number.isInteger(remote.logical) || remote.logical < 0 || remote.logical > MAX_LOGICAL) {
+      throw new InvalidTimestampError(
+        `Rejected remote HLC timestamp with invalid fields (wallTime=${remote.wallTime}, logical=${remote.logical}). wallTime and logical must be non-negative integers and logical must not exceed ${MAX_LOGICAL}.`,
+        remote.wallTime,
+        remote.logical
+      );
+    }
+    const canValidate = this.referenceOffsetMs !== null || !wasColdStart;
+    if (canValidate) {
+      const reference = this.effectiveTime(physicalTime);
+      if (remote.wallTime > reference + MAX_REMOTE_FUTURE_MS) {
+        throw new RemoteClockDriftError(remote.wallTime, reference);
+      }
+    }
     if (physicalTime > this.wallTime && physicalTime > remote.wallTime) {
       this.wallTime = physicalTime;
       this.logical = 0;
@@ -245,11 +339,54 @@ var HybridLogicalClock = class {
     } else {
       this.logical++;
     }
+    this.carryLogicalOverflow();
     if (!wasColdStart) {
       this.checkDrift(physicalTime);
     }
     return { wallTime: this.wallTime, logical: this.logical, nodeId: this.nodeId };
   }
+  /**
+   * Advance this clock to at least the given timestamp.
+   *
+   * Used after a timestamp rebase rewrites unsynced operations: future `now()`
+   * timestamps must sort after every rebased operation, otherwise a write issued
+   * immediately after the rebase could interleave with (or precede) rebased ops
+   * and break the log's total order. Never moves the clock backward — a
+   * timestamp at or before the current state is a no-op, preserving the
+   * monotonicity guarantee of `now()`.
+   *
+   * Inputs with logical > MAX_LOGICAL are normalized deterministically by
+   * carrying the excess into wallTime, so the adopted state always leaves room
+   * for the next increment inside the serializable range.
+   */
+  advanceTo(ts) {
+    const normalized = {
+      wallTime: ts.wallTime + Math.floor(ts.logical / LOGICAL_MODULUS),
+      logical: ts.logical % LOGICAL_MODULUS,
+      nodeId: ts.nodeId
+    };
+    const current = {
+      wallTime: this.wallTime,
+      logical: this.logical,
+      nodeId: this.nodeId
+    };
+    if (_HybridLogicalClock.compare(normalized, current) > 0) {
+      this.wallTime = normalized.wallTime;
+      this.logical = normalized.logical;
+    }
+  }
+  /**
+   * Carry the logical counter into wallTime when an increment pushed it past
+   * MAX_LOGICAL. Bumping wallTime by 1ms keeps the timestamp strictly greater
+   * than everything issued before (monotonicity) while keeping the logical
+   * counter inside the 5-digit slot the serialized form depends on.
+   */
+  carryLogicalOverflow() {
+    if (this.logical > MAX_LOGICAL) {
+      this.wallTime += 1;
+      this.logical = 0;
+    }
+  }
   /**
    * Compare two timestamps. Returns negative if a < b, positive if a > b, zero if equal.
    * Total order: wallTime first, then logical, then nodeId (lexicographic).
@@ -264,8 +401,23 @@ var HybridLogicalClock = class {
   /**
    * Serialize an HLC timestamp to a string that sorts lexicographically.
    * Format: zero-padded wallTime:logical:nodeId
+   *
+   * @throws {InvalidTimestampError} If wallTime does not fit 15 digits or
+   * logical does not fit 5 digits (or either is negative/non-integer). Such a
+   * value would overflow its zero-padded slot and the serialized string would
+   * no longer sort in the same order as {@link HybridLogicalClock.compare} —
+   * silently corrupting every LWW comparison on stored `_version` columns.
+   * Internal clocks can no longer produce such values (the logical counter
+   * carries into wallTime); this guards against hand-built timestamps.
    */
   static serialize(ts) {
+    if (!Number.isInteger(ts.wallTime) || ts.wallTime < 0 || ts.wallTime >= WALL_TIME_LIMIT || !Number.isInteger(ts.logical) || ts.logical < 0 || ts.logical > MAX_LOGICAL) {
+      throw new InvalidTimestampError(
+        `Cannot serialize HLC timestamp (wallTime=${ts.wallTime}, logical=${ts.logical}): wallTime must be an integer in [0, 10^15) and logical an integer in [0, ${MAX_LOGICAL}]. Values outside these ranges overflow the zero-padded serialized form, which must sort lexicographically identically to HybridLogicalClock.compare.`,
+        ts.wallTime,
+        ts.logical
+      );
+    }
     const wall = ts.wallTime.toString().padStart(15, "0");
     const log = ts.logical.toString().padStart(5, "0");
     return `${wall}:${log}:${ts.nodeId}`;
@@ -285,10 +437,16 @@ var HybridLogicalClock = class {
       nodeId: parts.slice(2).join(":")
     };
   }
+  /**
+   * Reports drift between the HLC and (reference-corrected) physical time.
+   * Reporting only: local timestamp generation is never blocked, because the
+   * user's data always outranks the quality of its timestamps.
+   */
   checkDrift(physicalTime) {
-    const drift = this.wallTime - physicalTime;
+    const drift = this.wallTime - this.effectiveTime(physicalTime);
     if (drift > DRIFT_ERROR_MS) {
-      throw new ClockDriftError(this.wallTime, physicalTime);
+      this.onDriftError?.(drift);
+      return;
     }
     if (drift > DRIFT_WARN_MS) {
       this.onDriftWarning?.(drift);
@@ -671,6 +829,106 @@ function toAtomicOp(sentinel) {
   return { type: sentinel.type, value: sentinel.value };
 }
 
+// src/operations/op-data-binary.ts
+function isKoraBytesValue(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const record = value;
+  return Object.keys(record).length === 1 && typeof record.$koraBytes === "string";
+}
+function isLegacyNumericByteObject(value) {
+  if (typeof value !== "object" || value === null || ArrayBuffer.isView(value)) {
+    return false;
+  }
+  const record = value;
+  const keys = Object.keys(record);
+  if (keys.length === 0) {
+    return false;
+  }
+  for (let i = 0; i < keys.length; i++) {
+    const byte = record[String(i)];
+    if (typeof byte !== "number" || !Number.isInteger(byte) || byte < 0 || byte > 255) {
+      return false;
+    }
+  }
+  return true;
+}
+var BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+var BASE64_REVERSE = new Map(
+  Array.from(BASE64_ALPHABET, (char, index) => [char, index])
+);
+function bytesToBase64(bytes) {
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const b0 = bytes[i] ?? 0;
+    const b1 = bytes[i + 1] ?? 0;
+    const b2 = bytes[i + 2] ?? 0;
+    const triple = b0 << 16 | b1 << 8 | b2;
+    out += BASE64_ALPHABET[triple >> 18 & 63] ?? "";
+    out += BASE64_ALPHABET[triple >> 12 & 63] ?? "";
+    out += i + 1 < bytes.length ? BASE64_ALPHABET[triple >> 6 & 63] ?? "" : "=";
+    out += i + 2 < bytes.length ? BASE64_ALPHABET[triple & 63] ?? "" : "=";
+  }
+  return out;
+}
+function base64ToBytes(base64) {
+  const cleaned = base64.replace(/=+$/, "");
+  const out = new Uint8Array(Math.floor(cleaned.length * 6 / 8));
+  let buffer = 0;
+  let bits = 0;
+  let index = 0;
+  for (const char of cleaned) {
+    const value = BASE64_REVERSE.get(char);
+    if (value === void 0) {
+      throw new OperationError(`Invalid base64 character "${char}" in tagged binary value.`, {
+        char
+      });
+    }
+    buffer = buffer << 6 | value;
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      out[index] = buffer >> bits & 255;
+      index += 1;
+    }
+  }
+  return out;
+}
+function encodeBytesForOpData(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+  const bytes = value instanceof Uint8Array ? value : new Uint8Array(value);
+  return { $koraBytes: bytesToBase64(bytes) };
+}
+function decodeBytesFromOpData(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (value instanceof Uint8Array) {
+    return value;
+  }
+  if (value instanceof ArrayBuffer) {
+    return new Uint8Array(value);
+  }
+  if (isKoraBytesValue(value)) {
+    return base64ToBytes(value.$koraBytes);
+  }
+  if (isLegacyNumericByteObject(value)) {
+    const keys = Object.keys(value);
+    const bytes = new Uint8Array(keys.length);
+    for (let i = 0; i < keys.length; i++) {
+      bytes[i] = value[String(i)] ?? 0;
+    }
+    return bytes;
+  }
+  throw new OperationError(
+    "Binary op-data value must be a string, Uint8Array, ArrayBuffer, tagged { $koraBytes } object, or legacy numeric-key byte object.",
+    { receivedType: typeof value }
+  );
+}
+
 // src/scopes/sync-scope-bindings.ts
 function hasSchemaSyncRules(schema) {
   return schema.sync !== void 0 && Object.keys(schema.sync).length > 0;
@@ -1100,6 +1358,7 @@ function generateSQL(collectionName, collection, relations) {
   columns.push("_created_at INTEGER NOT NULL");
   columns.push("_updated_at INTEGER NOT NULL");
   columns.push("_version TEXT NOT NULL DEFAULT ''");
+  columns.push("_field_versions TEXT NOT NULL DEFAULT '{}'");
   columns.push("_deleted INTEGER NOT NULL DEFAULT 0");
   statements.push(`CREATE TABLE IF NOT EXISTS ${collectionName} (
   ${columns.join(",\n  ")}
@@ -1112,6 +1371,10 @@ ALTER TABLE ${collectionName} ADD COLUMN ${colDef}`);
   statements.push(
     `--kora:safe-alter
 ALTER TABLE ${collectionName} ADD COLUMN _version TEXT NOT NULL DEFAULT ''`
+  );
+  statements.push(
+    `--kora:safe-alter
+ALTER TABLE ${collectionName} ADD COLUMN _field_versions TEXT NOT NULL DEFAULT '{}'`
   );
   for (const indexField of collection.indexes) {
     statements.push(
@@ -1139,6 +1402,9 @@ ALTER TABLE ${collectionName} ADD COLUMN _version TEXT NOT NULL DEFAULT ''`
   schema_version INTEGER NOT NULL
 )`
   );
+  statements.push(
+    `CREATE INDEX IF NOT EXISTS idx_kora_ops_${collectionName}_record_id ON _kora_ops_${collectionName} (record_id)`
+  );
   return statements;
 }
 function generateFullDDL(schema) {
@@ -1604,9 +1870,9 @@ function validateFieldValue(collection, fieldName, descriptor, value) {
       break;
     }
     case "richtext": {
-      if (!(value instanceof Uint8Array) && typeof value !== "string") {
+      if (!(value instanceof Uint8Array) && !(value instanceof ArrayBuffer) && typeof value !== "string") {
         throw new SchemaValidationError(
-          `Field "${fieldName}" in collection "${collection}" must be a Uint8Array or string for richtext, got ${typeof value}`,
+          `Field "${fieldName}" in collection "${collection}" must be a Uint8Array, ArrayBuffer, or string for richtext, got ${typeof value}`,
           {
             collection,
             field: fieldName,
@@ -2462,6 +2728,7 @@ function generateProtoDefinitions(schema) {
 0 && (module.exports = {
   APPLY_FAILURE_CODES,
   APPLY_RESULTS,
+  AppNotReadyError,
   ArrayFieldBuilder,
   CONNECTION_QUALITIES,
   CausalTracker,
@@ -2469,21 +2736,26 @@ function generateProtoDefinitions(schema) {
   EnumFieldBuilder,
   FieldBuilder,
   HybridLogicalClock,
+  InvalidTimestampError,
   KORA_ERROR_FIX_SUGGESTIONS,
   KoraError,
+  MAX_LOGICAL,
   MERGE_STRATEGIES,
   MergeConflictError,
   MigrationBuilder,
   MigrationRollbackError,
   OperationError,
+  RemoteClockDriftError,
   RollbackBuilder,
   SchemaValidationError,
   StorageError,
   SyncError,
   advanceVector,
   applyOperationTransforms,
+  base64ToBytes,
   buildScopeMap,
   buildStateMachineConstraints,
+  bytesToBase64,
   canAutoRollback,
   collectSchemaScopeFields,
   collectSchemaScopeValueKeys,
@@ -2491,11 +2763,13 @@ function generateProtoDefinitions(schema) {
   createOperation,
   createReversibleMigration,
   createVersionVector,
+  decodeBytesFromOpData,
   defaultApplyFailureReason,
   defaultSequenceFormat,
   defineSchema,
   deserializeVector,
   dominates,
+  encodeBytesForOpData,
   extractScopeValuesFromClaims,
   extractTimestamp,
   formatSequenceValue,
@@ -2511,6 +2785,8 @@ function generateProtoDefinitions(schema) {
   isApplyFailure,
   isAtomicOp,
   isCollectionSyncScoped,
+  isKoraBytesValue,
+  isLegacyNumericByteObject,
   isValidOperation,
   isValidUUIDv7,
   mergeVectors,