@korajs/core 0.4.0 → 0.5.0

package/dist/index.js

@@ -1,6 +1,7 @@
 import {
   ClockDriftError,
   HybridLogicalClock,
+  KORA_ERROR_FIX_SUGGESTIONS,
   KoraError,
   MergeConflictError,
   OperationError,
@@ -8,10 +9,11 @@ import {
   StorageError,
   SyncError,
   createOperation,
+  getKoraErrorFix,
   isValidOperation,
   topologicalSort,
   verifyOperationIntegrity
-} from "./chunk-CFP5YFXC.js";
+} from "./chunk-H4FXU5OP.js";
 
 // src/types.ts
 var MERGE_STRATEGIES = [
@@ -23,6 +25,50 @@ var MERGE_STRATEGIES = [
 ];
 var CONNECTION_QUALITIES = ["excellent", "good", "fair", "poor", "offline"];
 
+// src/causal/causal-tracker.ts
+var CausalTracker = class {
+  lastOpIdByCollection = /* @__PURE__ */ new Map();
+  lastTransactionOpId = null;
+  /**
+   * Start a new transaction boundary. Clears in-transaction op ids.
+   */
+  beginTransaction() {
+    this.lastTransactionOpId = null;
+  }
+  /**
+   * Clear the transaction boundary without recording ops (after rollback).
+   */
+  clearTransaction() {
+    this.lastTransactionOpId = null;
+  }
+  /**
+   * Compute causal dependencies for the next operation in a collection.
+   * Uses direct parents only: collection head and the previous op in the open transaction.
+   */
+  nextCausalDeps(collection, inTransaction) {
+    const deps = [];
+    const lastInCollection = this.lastOpIdByCollection.get(collection);
+    if (lastInCollection !== void 0) {
+      deps.push(lastInCollection);
+    }
+    if (inTransaction && this.lastTransactionOpId !== null) {
+      if (!deps.includes(this.lastTransactionOpId)) {
+        deps.push(this.lastTransactionOpId);
+      }
+    }
+    return deps;
+  }
+  /**
+   * Record an operation after it has been created and assigned an id.
+   */
+  afterOperation(collection, operationId, inTransaction) {
+    this.lastOpIdByCollection.set(collection, operationId);
+    if (inTransaction) {
+      this.lastTransactionOpId = operationId;
+    }
+  }
+};
+
 // src/identifiers/uuid-v7.ts
 var defaultRandom = globalThis.crypto;
 function generateUUIDv7(timestamp = Date.now(), randomSource = defaultRandom) {
@@ -59,6 +105,37 @@ function formatUUID(bytes) {
   return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
 }
 
+// src/operations/apply-result.ts
+var APPLY_RESULTS = ["applied", "duplicate", "skipped", "rejected", "deferred"];
+var APPLY_FAILURE_CODES = {
+  APPLY_FAILED: "APPLY_FAILED",
+  APPLY_SKIPPED: "APPLY_SKIPPED",
+  APPLY_REJECTED: "APPLY_REJECTED",
+  APPLY_DEFERRED: "APPLY_DEFERRED",
+  CLOCK_DRIFT: "CLOCK_DRIFT",
+  REFERENTIAL_INTEGRITY: "REFERENTIAL_INTEGRITY",
+  SCHEMA_MISMATCH: "SCHEMA_MISMATCH"
+};
+function isApplyFailure(result) {
+  return result === "skipped" || result === "rejected" || result === "deferred";
+}
+function defaultApplyFailureReason(result, overrides) {
+  const base = result === "deferred" ? {
+    code: APPLY_FAILURE_CODES.APPLY_DEFERRED,
+    message: "Operation apply was deferred.",
+    retriable: true
+  } : result === "rejected" ? {
+    code: APPLY_FAILURE_CODES.APPLY_REJECTED,
+    message: "Operation apply was rejected.",
+    retriable: false
+  } : {
+    code: APPLY_FAILURE_CODES.APPLY_SKIPPED,
+    message: "Operation apply was skipped.",
+    retriable: false
+  };
+  return { ...base, ...overrides };
+}
+
 // src/operations/atomic-ops.ts
 var KORA_ATOMIC_OP = /* @__PURE__ */ Symbol.for("kora.atomic_op");
 function isAtomicOp(value) {
@@ -157,6 +234,69 @@ function toAtomicOp(sentinel) {
   return { type: sentinel.type, value: sentinel.value };
 }
 
+// src/scopes/sync-scope-bindings.ts
+function hasSchemaSyncRules(schema) {
+  return schema.sync !== void 0 && Object.keys(schema.sync).length > 0;
+}
+function getCollectionScopeBindings(schema, collectionName) {
+  const syncRule = schema.sync?.[collectionName];
+  if (syncRule && Object.keys(syncRule.where).length > 0) {
+    return { ...syncRule.where };
+  }
+  const scopeFields = schema.collections[collectionName]?.scope ?? [];
+  if (scopeFields.length === 0) {
+    return null;
+  }
+  const bindings = {};
+  for (const field of scopeFields) {
+    bindings[field] = field;
+  }
+  return bindings;
+}
+function isCollectionSyncScoped(schema, collectionName) {
+  if (hasSchemaSyncRules(schema)) {
+    if (schema.sync?.[collectionName]) {
+      return true;
+    }
+    const legacyScope = schema.collections[collectionName]?.scope ?? [];
+    return legacyScope.length > 0;
+  }
+  return getCollectionScopeBindings(schema, collectionName) !== null;
+}
+function collectSchemaScopeValueKeys(schema) {
+  const keys = /* @__PURE__ */ new Set();
+  for (const collection of Object.values(schema.collections)) {
+    for (const field of collection.scope) {
+      keys.add(field);
+    }
+  }
+  if (schema.sync) {
+    for (const rule of Object.values(schema.sync)) {
+      for (const scopeKey of Object.values(rule.where)) {
+        keys.add(scopeKey);
+      }
+    }
+  }
+  return [...keys];
+}
+function normalizeSyncRuleWhere(collectionName, where) {
+  const normalized = {};
+  for (const [field, scopeKey] of Object.entries(where)) {
+    if (scopeKey === true) {
+      normalized[field] = field;
+      continue;
+    }
+    if (typeof scopeKey === "string" && scopeKey.length > 0) {
+      normalized[field] = scopeKey;
+      continue;
+    }
+    throw new Error(
+      `Invalid sync rule for collection "${collectionName}": where.${field} must be true or a non-empty scope key string`
+    );
+  }
+  return normalized;
+}
+
 // src/state-machine/state-machine.ts
 function validateTransition(constraint, fromValue, toValue) {
   const from = String(fromValue);
@@ -246,7 +386,7 @@ function validateStateMachineDefinition(collectionName, sm, fields) {
 // src/schema/define.ts
 var COLLECTION_NAME_RE = /^[a-z][a-z0-9_]*$/;
 var FIELD_NAME_RE = /^[a-z][a-zA-Z0-9_]*$/;
-var RESERVED_FIELDS = /* @__PURE__ */ new Set(["id", "_created_at", "_updated_at", "_deleted"]);
+var RESERVED_FIELDS = /* @__PURE__ */ new Set(["id", "_created_at", "_updated_at", "_version", "_deleted"]);
 function defineSchema(input) {
   validateVersion(input.version);
   const collections = {};
@@ -289,7 +429,15 @@ function defineSchema(input) {
       migrations[version] = migration;
     }
   }
-  return { version: input.version, collections, relations, migrations };
+  const sync = buildSyncRules(input.sync, collections);
+  applySyncRulesToCollectionScope(collections, sync);
+  return {
+    version: input.version,
+    collections,
+    relations,
+    migrations,
+    ...sync ? { sync } : {}
+  };
 }
 function validateVersion(version) {
   if (typeof version !== "number" || !Number.isInteger(version) || version < 1) {
@@ -370,6 +518,63 @@ function buildCollection(name, input) {
   }
   return { fields, indexes, constraints, resolvers, scope, stateMachine };
 }
+function buildSyncRules(syncInput, collections) {
+  if (!syncInput) {
+    return void 0;
+  }
+  const sync = {};
+  for (const [collectionName, ruleInput] of Object.entries(syncInput)) {
+    if (!(collectionName in collections)) {
+      throw new SchemaValidationError(
+        `Sync rule references collection "${collectionName}" which does not exist. Available collections: ${Object.keys(collections).join(", ")}`,
+        { collection: collectionName }
+      );
+    }
+    if (!ruleInput.where || Object.keys(ruleInput.where).length === 0) {
+      throw new SchemaValidationError(
+        `Sync rule for collection "${collectionName}" must declare at least one where binding`,
+        { collection: collectionName }
+      );
+    }
+    const collection = collections[collectionName];
+    if (!collection) {
+      continue;
+    }
+    for (const fieldName of Object.keys(ruleInput.where)) {
+      if (!(fieldName in collection.fields)) {
+        throw new SchemaValidationError(
+          `Sync rule where field "${fieldName}" does not exist in collection "${collectionName}". Available fields: ${Object.keys(collection.fields).join(", ")}`,
+          { collection: collectionName, field: fieldName }
+        );
+      }
+    }
+    try {
+      sync[collectionName] = { where: normalizeSyncRuleWhere(collectionName, ruleInput.where) };
+    } catch (error) {
+      throw new SchemaValidationError(
+        error instanceof Error ? error.message : "Invalid sync rule",
+        { collection: collectionName }
+      );
+    }
+  }
+  return sync;
+}
+function applySyncRulesToCollectionScope(collections, sync) {
+  if (!sync) {
+    return;
+  }
+  for (const [collectionName, rule] of Object.entries(sync)) {
+    const collection = collections[collectionName];
+    if (!collection) {
+      continue;
+    }
+    for (const fieldName of Object.keys(rule.where)) {
+      if (!collection.scope.includes(fieldName)) {
+        collection.scope.push(fieldName);
+      }
+    }
+  }
+}
 function validateFieldName(collection, fieldName) {
   if (RESERVED_FIELDS.has(fieldName)) {
     throw new SchemaValidationError(
@@ -457,6 +662,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("_deleted INTEGER NOT NULL DEFAULT 0");
   statements.push(`CREATE TABLE IF NOT EXISTS ${collectionName} (
   ${columns.join(",\n  ")}
@@ -466,6 +672,10 @@ function generateSQL(collectionName, collection, relations) {
     statements.push(`--kora:safe-alter
 ALTER TABLE ${collectionName} ADD COLUMN ${colDef}`);
   }
+  statements.push(
+    `--kora:safe-alter
+ALTER TABLE ${collectionName} ADD COLUMN _version TEXT NOT NULL DEFAULT ''`
+  );
   for (const indexField of collection.indexes) {
     statements.push(
       `CREATE INDEX IF NOT EXISTS idx_${collectionName}_${indexField} ON ${collectionName} (${indexField})`
@@ -505,6 +715,18 @@ function generateFullDDL(schema) {
   statements.push(
     "CREATE TABLE IF NOT EXISTS _kora_sequences (\n  name TEXT NOT NULL,\n  scope TEXT NOT NULL DEFAULT '',\n  node_id TEXT NOT NULL,\n  counter INTEGER NOT NULL DEFAULT 0,\n  PRIMARY KEY (name, scope, node_id)\n)"
   );
+  statements.push(
+    "CREATE TABLE IF NOT EXISTS _kora_sync_queue (\n  id TEXT PRIMARY KEY NOT NULL,\n  payload TEXT NOT NULL\n)"
+  );
+  statements.push(
+    "CREATE TABLE IF NOT EXISTS _kora_audit_traces (\n  id TEXT PRIMARY KEY NOT NULL,\n  recorded_at INTEGER NOT NULL,\n  event_type TEXT NOT NULL,\n  collection TEXT NOT NULL,\n  record_id TEXT NOT NULL,\n  field TEXT NOT NULL,\n  strategy TEXT NOT NULL,\n  tier INTEGER NOT NULL,\n  constraint_name TEXT,\n  trace_json TEXT NOT NULL\n)"
+  );
+  statements.push(
+    "CREATE INDEX IF NOT EXISTS idx_kora_audit_traces_recorded_at ON _kora_audit_traces (recorded_at)"
+  );
+  statements.push(
+    "CREATE INDEX IF NOT EXISTS idx_kora_audit_traces_collection ON _kora_audit_traces (collection)"
+  );
   for (const [name, collection] of Object.entries(schema.collections)) {
     statements.push(...generateSQL(name, collection, schema.relations));
   }
@@ -633,10 +855,24 @@ var EnumFieldBuilder = class _EnumFieldBuilder extends FieldBuilder {
     );
   }
   default(value) {
-    return new _EnumFieldBuilder(this._enumValues, false, value, this._auto, this._mergeStrategy, this._transitions);
+    return new _EnumFieldBuilder(
+      this._enumValues,
+      false,
+      value,
+      this._auto,
+      this._mergeStrategy,
+      this._transitions
+    );
   }
   auto() {
-    return new _EnumFieldBuilder(this._enumValues, false, void 0, true, this._mergeStrategy, this._transitions);
+    return new _EnumFieldBuilder(
+      this._enumValues,
+      false,
+      void 0,
+      true,
+      this._mergeStrategy,
+      this._transitions
+    );
   }
   merge(strategy) {
     return new _EnumFieldBuilder(
@@ -1004,12 +1240,13 @@ function vectorsEqual(a, b) {
   }
   return true;
 }
-function computeDelta(localVector, remoteVector, operationLog) {
+async function computeDelta(localVector, remoteVector, operationLog) {
   const missing = [];
   for (const [nodeId, localSeq] of localVector) {
     const remoteSeq = remoteVector.get(nodeId) ?? 0;
     if (localSeq > remoteSeq) {
-      missing.push(...operationLog.getRange(nodeId, remoteSeq + 1, localSeq));
+      const ops = await operationLog.getRange(nodeId, remoteSeq + 1, localSeq);
+      missing.push(...ops);
     }
   }
   return topologicalSort(missing);
@@ -1026,12 +1263,17 @@ function deserializeVector(s) {
 // src/scopes/build-scope-map.ts
 function buildScopeMap(schema, scopeValues) {
   const result = {};
-  for (const [collName, collDef] of Object.entries(schema.collections)) {
-    if (collDef.scope.length > 0) {
+  const partialSync = hasSchemaSyncRules(schema);
+  for (const collName of Object.keys(schema.collections)) {
+    if (partialSync && !isCollectionSyncScoped(schema, collName)) {
+      continue;
+    }
+    const bindings = getCollectionScopeBindings(schema, collName);
+    if (bindings) {
       const collScope = {};
-      for (const field of collDef.scope) {
-        if (field in scopeValues) {
-          collScope[field] = scopeValues[field];
+      for (const [field, scopeKey] of Object.entries(bindings)) {
+        if (scopeKey in scopeValues) {
+          collScope[field] = scopeValues[scopeKey];
         }
       }
       result[collName] = collScope;
@@ -1042,6 +1284,34 @@ function buildScopeMap(schema, scopeValues) {
   return result;
 }
 
+// src/scopes/extract-scope-from-claims.ts
+function collectSchemaScopeFields(schema) {
+  return collectSchemaScopeValueKeys(schema);
+}
+function extractScopeValuesFromClaims(schema, claims) {
+  const scopeFields = collectSchemaScopeValueKeys(schema);
+  if (scopeFields.length === 0) {
+    return {};
+  }
+  const nestedScope = claims.scope;
+  const scopeObject = typeof nestedScope === "object" && nestedScope !== null && !Array.isArray(nestedScope) ? nestedScope : {};
+  const result = {};
+  for (const field of scopeFields) {
+    if (field in claims) {
+      result[field] = claims[field];
+      continue;
+    }
+    if (field in scopeObject) {
+      result[field] = scopeObject[field];
+      continue;
+    }
+    if (field === "userId" && typeof claims.sub === "string") {
+      result.userId = claims.sub;
+    }
+  }
+  return result;
+}
+
 // src/sequences/sequence-format.ts
 function formatSequenceValue(template, counter, nodeId, now) {
   const date = now ?? /* @__PURE__ */ new Date();
@@ -1068,6 +1338,29 @@ function defaultSequenceFormat(name) {
   return `${name}-{seq:4}`;
 }
 
+// src/migration/apply-operation-transforms.ts
+var MAX_TRANSFORM_STEPS = 32;
+function applyOperationTransforms(operation, targetSchemaVersion, transforms) {
+  let current = operation;
+  for (let step = 0; step < MAX_TRANSFORM_STEPS; step++) {
+    if (current.schemaVersion === targetSchemaVersion) {
+      return current;
+    }
+    const transform = transforms.find(
+      (candidate) => candidate.fromVersion === current.schemaVersion
+    );
+    if (!transform) {
+      return null;
+    }
+    const next = transform.transform(current);
+    if (next === null) {
+      return null;
+    }
+    current = next;
+  }
+  return null;
+}
+
 // src/migrations/migration-builder.ts
 var RollbackBuilder = class {
   _steps = [];
@@ -1611,12 +1904,16 @@ function generateProtoDefinitions(schema) {
   return { proto, typeMap, jsonDescriptor };
 }
 export {
+  APPLY_FAILURE_CODES,
+  APPLY_RESULTS,
   ArrayFieldBuilder,
   CONNECTION_QUALITIES,
+  CausalTracker,
   ClockDriftError,
   EnumFieldBuilder,
   FieldBuilder,
   HybridLogicalClock,
+  KORA_ERROR_FIX_SUGGESTIONS,
   KoraError,
   MERGE_STRATEGIES,
   MergeConflictError,
@@ -1628,17 +1925,22 @@ export {
   StorageError,
   SyncError,
   advanceVector,
+  applyOperationTransforms,
   buildScopeMap,
   buildStateMachineConstraints,
   canAutoRollback,
+  collectSchemaScopeFields,
+  collectSchemaScopeValueKeys,
   computeDelta,
   createOperation,
   createReversibleMigration,
   createVersionVector,
+  defaultApplyFailureReason,
   defaultSequenceFormat,
   defineSchema,
   deserializeVector,
   dominates,
+  extractScopeValuesFromClaims,
   extractTimestamp,
   formatSequenceValue,
   generateFullDDL,
@@ -1646,8 +1948,13 @@ export {
   generateRollbackSteps,
   generateSQL,
   generateUUIDv7,
+  getCollectionScopeBindings,
+  getKoraErrorFix,
   getTransitionMap,
+  hasSchemaSyncRules,
+  isApplyFailure,
   isAtomicOp,
+  isCollectionSyncScoped,
   isValidOperation,
   isValidUUIDv7,
   mergeVectors,