@korajs/store 1.0.0-beta.11 → 1.0.0-beta.13

package/dist/chunk-HZTDBLDB.js

@@ -0,0 +1,607 @@
+import {
+  EMPTY_ROW_VERSION,
+  buildInsertQuery,
+  buildSoftDeleteQuery,
+  buildUpdateQuery,
+  serializeRowVersion
+} from "./chunk-SJP2HTYZ.js";
+import {
+  deserializeRecord,
+  encodeRichtextFieldsForOpData,
+  serializeOperation,
+  serializeRecord,
+  toRichtextReadShape
+} from "./chunk-J5AGXF3D.js";
+import {
+  RecordNotFoundError
+} from "./chunk-DUKTWVZW.js";
+
+// src/mutations/write-context.ts
+import { KoraError } from "@korajs/core";
+var CausalScope = class {
+  constructor(tracker, chainOperations) {
+    this.tracker = tracker;
+    this.chainOperations = chainOperations;
+  }
+  tracker;
+  chainOperations;
+  lastByCollection = /* @__PURE__ */ new Map();
+  lastInScope = null;
+  recorded = [];
+  /**
+   * Direct causal parents for the next operation in `collection`.
+   *
+   * @param collection - Collection of the operation being built
+   * @param extra - Explicit parents (e.g. the delete that caused a cascade)
+   */
+  depsFor(collection, extra = []) {
+    const deps = [];
+    const add = (id) => {
+      if (id && !deps.includes(id)) deps.push(id);
+    };
+    for (const id of extra) add(id);
+    const local = this.lastByCollection.get(collection);
+    if (local !== void 0) {
+      add(local);
+    } else {
+      for (const id of this.tracker?.nextCausalDeps(collection, false) ?? []) add(id);
+    }
+    if (this.chainOperations) add(this.lastInScope);
+    return deps;
+  }
+  /** Record an operation built in this scope. */
+  record(collection, operationId) {
+    this.lastByCollection.set(collection, operationId);
+    this.lastInScope = operationId;
+    this.recorded.push({ collection, id: operationId });
+  }
+  /** Publish this scope's heads to the shared tracker. Call only after commit. */
+  publish() {
+    for (const { collection, id } of this.recorded) {
+      this.tracker?.afterOperation(collection, id, false);
+    }
+  }
+};
+var SequenceBlock = class {
+  constructor(tx, nodeId) {
+    this.tx = tx;
+    this.nodeId = nodeId;
+  }
+  tx;
+  nodeId;
+  last = null;
+  persisted = 0;
+  /** The next number of the block. */
+  async take() {
+    if (this.last === null) {
+      const rows = await this.tx.query(
+        `INSERT INTO _kora_version_vector (node_id, sequence_number) VALUES (?, 1)
+     ON CONFLICT(node_id) DO UPDATE SET sequence_number = sequence_number + 1
+     RETURNING sequence_number`,
+        [this.nodeId]
+      );
+      const first = rows[0]?.sequence_number;
+      if (first === void 0) {
+        throw new KoraError(
+          `Failed to reserve a sequence number for node "${this.nodeId}"`,
+          "SEQUENCE_RESERVATION_FAILED",
+          { nodeId: this.nodeId }
+        );
+      }
+      this.last = first;
+      this.persisted = first;
+      return first;
+    }
+    this.last += 1;
+    return this.last;
+  }
+  /** Persist the end of the block. Must run inside the transaction, before commit. */
+  async close() {
+    if (this.last === null || this.last === this.persisted) return;
+    await this.tx.execute(
+      "UPDATE _kora_version_vector SET sequence_number = MAX(sequence_number, ?) WHERE node_id = ?",
+      [this.last, this.nodeId]
+    );
+    this.persisted = this.last;
+  }
+};
+async function withWriteScope(tx, nodeId, causal, write) {
+  const scope = { tx, sequence: new SequenceBlock(tx, nodeId), causal };
+  const result = await write(scope);
+  await scope.sequence.close();
+  return result;
+}
+function isStorageFullError(error) {
+  if (error === null || typeof error !== "object") return false;
+  const candidate = error;
+  if (candidate.name === "QuotaExceededError") return true;
+  if (candidate.code === "SQLITE_FULL" || candidate.code === "QUOTA_EXCEEDED") return true;
+  const message = typeof candidate.message === "string" ? candidate.message : "";
+  if (/SQLITE_FULL|database or disk is full|quota ?exceeded/i.test(message)) return true;
+  return candidate.cause !== void 0 && candidate.cause !== error ? isStorageFullError(candidate.cause) : false;
+}
+
+// src/lww/field-versions.ts
+function parseFieldVersions(raw) {
+  if (typeof raw !== "string" || raw.length === 0) {
+    return {};
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return {};
+    }
+    const result = {};
+    for (const [key, value] of Object.entries(parsed)) {
+      if (typeof value === "string") {
+        result[key] = value;
+      }
+    }
+    return result;
+  } catch {
+    return {};
+  }
+}
+function serializeFieldVersions(versions) {
+  return JSON.stringify(versions);
+}
+function fieldVersionsForFields(fieldNames, version) {
+  const versions = {};
+  for (const field of fieldNames) {
+    versions[field] = version;
+  }
+  return versions;
+}
+function effectiveFieldVersion(current, field, rowVersion) {
+  const own = current[field];
+  if (own !== void 0) {
+    return own;
+  }
+  return rowVersion ?? EMPTY_ROW_VERSION;
+}
+function resolvePerFieldLww(current, incomingFields, incomingVersion, rowVersion) {
+  const winners = [];
+  const merged = { ...current };
+  for (const field of incomingFields) {
+    const stored = effectiveFieldVersion(current, field, rowVersion);
+    if (incomingVersion > stored) {
+      winners.push(field);
+      merged[field] = incomingVersion;
+    }
+  }
+  return { winners, merged };
+}
+function stampFieldVersions(currentRaw, fields, version) {
+  const versions = parseFieldVersions(currentRaw);
+  for (const field of fields) {
+    const existing = versions[field];
+    if (existing === void 0 || existing < version) {
+      versions[field] = version;
+    }
+  }
+  return serializeFieldVersions(versions);
+}
+
+// src/state-machine/state-validator.ts
+import { KoraError as KoraError2, validateTransition } from "@korajs/core";
+var InvalidStateTransitionError = class extends KoraError2 {
+  constructor(collection, recordId, field, fromState, toState, allowedStates) {
+    super(
+      `Invalid state transition in collection "${collection}": cannot transition field "${field}" from "${fromState}" to "${toState}". Allowed transitions from "${fromState}": ${allowedStates.length > 0 ? allowedStates.join(", ") : "(none -- terminal state)"}`,
+      "INVALID_STATE_TRANSITION",
+      { collection, recordId, field, fromState, toState, allowedStates }
+    );
+    this.collection = collection;
+    this.recordId = recordId;
+    this.field = field;
+    this.fromState = fromState;
+    this.toState = toState;
+    this.allowedStates = allowedStates;
+    this.name = "InvalidStateTransitionError";
+  }
+  collection;
+  recordId;
+  field;
+  fromState;
+  toState;
+  allowedStates;
+};
+function validateStateTransition(collectionName, recordId, stateMachine, currentState, newState) {
+  if (currentState === null) {
+    return { valid: true, allowedStates: [] };
+  }
+  if (currentState === newState) {
+    return { valid: true, allowedStates: stateMachine.transitions[currentState] ?? [] };
+  }
+  const constraint = {
+    field: stateMachine.field,
+    collection: collectionName,
+    transitions: stateMachine.transitions
+  };
+  const transitionResult = validateTransition(constraint, currentState, newState);
+  if (transitionResult.valid) {
+    return { valid: true, allowedStates: transitionResult.allowedTargets };
+  }
+  const allowedStates = transitionResult.allowedTargets;
+  if (stateMachine.onInvalidTransition === "reject") {
+    throw new InvalidStateTransitionError(
+      collectionName,
+      recordId,
+      stateMachine.field,
+      currentState,
+      newState,
+      allowedStates
+    );
+  }
+  return { valid: false, allowedStates };
+}
+function validateUpdateStateMachine(collectionName, recordId, collectionDef, currentRecord, updateData) {
+  let result = updateData;
+  const stateMachine = collectionDef.stateMachine;
+  if (stateMachine !== void 0) {
+    result = applyStateMachine(collectionName, recordId, stateMachine, currentRecord, result);
+  }
+  for (const [field, descriptor] of Object.entries(collectionDef.fields)) {
+    if (descriptor.kind !== "enum" || !descriptor.transitions) continue;
+    if (stateMachine?.field === field) continue;
+    result = applyStateMachine(
+      collectionName,
+      recordId,
+      { field, transitions: descriptor.transitions, onInvalidTransition: "reject" },
+      currentRecord,
+      result
+    );
+  }
+  return result;
+}
+function applyStateMachine(collectionName, recordId, stateMachine, currentRecord, updateData) {
+  const stateField = stateMachine.field;
+  if (!(stateField in updateData)) {
+    return updateData;
+  }
+  const currentState = currentRecord[stateField];
+  const newState = updateData[stateField];
+  if (typeof currentState !== "string" || typeof newState !== "string") {
+    return updateData;
+  }
+  const result = validateStateTransition(
+    collectionName,
+    recordId,
+    stateMachine,
+    currentState,
+    newState
+  );
+  if (result.valid) {
+    return updateData;
+  }
+  const filtered = { ...updateData };
+  delete filtered[stateField];
+  return filtered;
+}
+
+// src/mutations/run-local-write.ts
+import { KoraError as KoraError3 } from "@korajs/core";
+async function runLocalWrite(ctx, write) {
+  const causal = new CausalScope(ctx.causalTracker, false);
+  let result;
+  try {
+    await ctx.adapter.transaction(async (tx) => {
+      result = await withWriteScope(tx, ctx.nodeId, causal, write);
+    });
+  } catch (error) {
+    ctx.onStorageError?.(error);
+    throw error;
+  }
+  if (!result) {
+    throw new KoraError3("Local write transaction completed without a result", "WRITE_INCOMPLETE", {
+      collection: ctx.collection
+    });
+  }
+  causal.publish();
+  publishOperations(ctx, result);
+  return result;
+}
+function publishOperations(ctx, result) {
+  const ops = [];
+  if (result.operation) ops.push(result.operation);
+  ops.push(...result.sideEffects);
+  for (const op of ops) {
+    ctx.onMutation(op.collection, op);
+  }
+}
+
+// src/mutations/write-ops.ts
+import {
+  DEFAULT_MAX_OPERATION_BYTES,
+  KoraError as KoraError4,
+  OperationTooLargeError,
+  assertResolvedFieldValue,
+  createOperation,
+  generateUUIDv7,
+  isAtomicOp,
+  measureOperationBytes,
+  quoteIdent,
+  resolveAtomicOp,
+  toAtomicOp,
+  validateRecord
+} from "@korajs/core";
+
+// src/mutations/secret-write.ts
+import { transformSecretFieldsForWrite } from "@korajs/core";
+function toAtRestWriteData(data, definition, secretKeyProvider) {
+  return transformSecretFieldsForWrite(data, definition, secretKeyProvider);
+}
+
+// src/mutations/write-ops.ts
+async function prepareInsert(env, collection, data) {
+  const definition = requireDefinition(env, collection);
+  const validated = validateRecord(collection, definition, data, "insert");
+  const now = Date.now();
+  for (const [fieldName, descriptor] of Object.entries(definition.fields)) {
+    if (descriptor.auto && descriptor.kind === "timestamp") {
+      validated[fieldName] = now;
+    }
+  }
+  const writeData = await toAtRestWriteData(validated, definition, env.secretKeyProvider);
+  return { collection, recordId: generateUUIDv7(), data: writeData };
+}
+async function writeInsertInTx(env, scope, insert, extraCausalDeps = []) {
+  const definition = requireDefinition(env, insert.collection);
+  const operation = await buildLocalOperation(env, scope, {
+    type: "insert",
+    collection: insert.collection,
+    recordId: insert.recordId,
+    // Binary richtext values are tagged as canonical JSON BEFORE hashing, so the
+    // hash input, persisted JSON and wire payload are the identical value.
+    data: encodeRichtextFieldsForOpData(insert.data, definition.fields),
+    previousData: null,
+    extraCausalDeps
+  });
+  if (env.fold) {
+    await appendOperationRow(scope, operation);
+    await env.fold.applyInTx(scope.tx, operation, "local");
+  } else {
+    const serialized = serializeRecord(insert.data, definition.fields);
+    const version = serializeRowVersion(operation.timestamp);
+    const row = {
+      id: insert.recordId,
+      ...serialized,
+      _created_at: operation.timestamp.wallTime,
+      _updated_at: operation.timestamp.wallTime,
+      _version: version,
+      // Every inserted field is stamped with this operation's version, so later
+      // per-field LWW compares against a real writer, not the row fallback.
+      _field_versions: stampFieldVersions(null, Object.keys(serialized), version)
+    };
+    const rowInsert = buildInsertQuery(insert.collection, row);
+    await scope.tx.execute(rowInsert.sql, rowInsert.params);
+    await appendOperationRow(scope, operation);
+  }
+  return {
+    operation,
+    record: {
+      id: insert.recordId,
+      // A richtext value written as a string returns as the bytes reads return.
+      ...toRichtextReadShape(insert.data, definition.fields),
+      createdAt: operation.timestamp.wallTime,
+      updatedAt: operation.timestamp.wallTime
+    },
+    sideEffects: []
+  };
+}
+async function writeUpdateInTx(env, scope, collection, id, data, extraCausalDeps = []) {
+  const definition = requireDefinition(env, collection);
+  const currentRow = await readLiveRow(scope, collection, id);
+  if (!currentRow) {
+    throw new RecordNotFoundError(collection, id);
+  }
+  const currentRecord = deserializeRecord(currentRow, definition.fields);
+  const allowed = validateUpdateStateMachine(collection, id, definition, currentRecord, data);
+  if (Object.keys(allowed).length === 0) {
+    return { operation: null, record: currentRecord, sideEffects: [] };
+  }
+  const previousData = {};
+  const resolved = {};
+  const atomicOps = {};
+  for (const [key, value] of Object.entries(allowed)) {
+    previousData[key] = currentRecord[key];
+    if (isAtomicOp(value)) {
+      resolved[key] = resolveAtomicOp(currentRecord[key], value);
+      const descriptor = definition.fields[key];
+      if (descriptor) assertResolvedFieldValue(collection, key, descriptor, resolved[key]);
+      atomicOps[key] = toAtomicOp(value);
+    } else {
+      resolved[key] = value;
+    }
+  }
+  const writeData = await toAtRestWriteData(resolved, definition, env.secretKeyProvider);
+  const operation = await buildLocalOperation(env, scope, {
+    type: "update",
+    collection,
+    recordId: id,
+    data: encodeRichtextFieldsForOpData(writeData, definition.fields),
+    previousData: encodeRichtextFieldsForOpData(previousData, definition.fields),
+    extraCausalDeps,
+    ...Object.keys(atomicOps).length > 0 ? { atomicOps } : {}
+  });
+  if (env.fold) {
+    await appendOperationRow(scope, operation);
+    await env.fold.applyInTx(scope.tx, operation, "local");
+  } else {
+    const serializedChanges = serializeRecord(writeData, definition.fields);
+    const version = serializeRowVersion(operation.timestamp);
+    const rowUpdate = buildUpdateQuery(collection, id, {
+      ...serializedChanges,
+      _updated_at: operation.timestamp.wallTime,
+      _version: version,
+      _field_versions: stampFieldVersions(
+        currentRow._field_versions,
+        Object.keys(serializedChanges),
+        version
+      )
+    });
+    await scope.tx.execute(rowUpdate.sql, rowUpdate.params);
+    await appendOperationRow(scope, operation);
+  }
+  const updatedRow = await readLiveRow(scope, collection, id);
+  if (!updatedRow) {
+    throw new RecordNotFoundError(collection, id);
+  }
+  return {
+    operation,
+    record: deserializeRecord(updatedRow, definition.fields),
+    sideEffects: []
+  };
+}
+async function writeDeleteInTx(env, scope, collection, id, options = {}) {
+  const definition = requireDefinition(env, collection);
+  const currentRow = await readLiveRow(scope, collection, id);
+  if (!currentRow) {
+    throw new RecordNotFoundError(collection, id);
+  }
+  const operation = await buildLocalOperation(env, scope, {
+    type: "delete",
+    collection,
+    recordId: id,
+    data: null,
+    previousData: null,
+    extraCausalDeps: options.extraCausalDeps ?? []
+  });
+  if (!options.skipReferentialEnforcement && env.beforeLocalDelete) {
+    await env.beforeLocalDelete(operation, scope.tx);
+  }
+  if (env.fold) {
+    await appendOperationRow(scope, operation);
+    await env.fold.applyInTx(scope.tx, operation, "local");
+  } else {
+    const version = serializeRowVersion(operation.timestamp);
+    const softDelete = buildSoftDeleteQuery(collection, id, operation.timestamp.wallTime, version);
+    await scope.tx.execute(softDelete.sql, softDelete.params);
+    await appendOperationRow(scope, operation);
+  }
+  const sideEffects = [];
+  if (!options.skipReferentialEnforcement && env.relationEnforcer) {
+    const result = await env.relationEnforcer.enforceDelete(
+      collection,
+      id,
+      scope,
+      env,
+      operation.id
+    );
+    sideEffects.push(...result.operations);
+  }
+  return {
+    operation,
+    record: deserializeRecord(currentRow, definition.fields),
+    sideEffects
+  };
+}
+async function buildLocalOperation(env, scope, input) {
+  const sequenceNumber = await scope.sequence.take();
+  const causalDeps = scope.causal.depsFor(input.collection, input.extraCausalDeps);
+  const operation = await createOperation(
+    {
+      nodeId: env.nodeId,
+      type: input.type,
+      collection: input.collection,
+      recordId: input.recordId,
+      data: input.data,
+      previousData: input.previousData,
+      sequenceNumber,
+      causalDeps,
+      schemaVersion: env.schema.version,
+      ...input.atomicOps !== void 0 ? { atomicOps: input.atomicOps } : {},
+      ...env.transactionId !== void 0 ? { transactionId: env.transactionId } : {},
+      ...env.mutationName !== void 0 ? { mutationName: env.mutationName } : {}
+    },
+    env.clock
+  );
+  const maxBytes = env.maxOperationBytes ?? DEFAULT_MAX_OPERATION_BYTES;
+  const bytes = measureOperationBytes(operation);
+  if (bytes > maxBytes) {
+    throw new OperationTooLargeError(input.collection, input.recordId, bytes, maxBytes);
+  }
+  scope.causal.record(input.collection, operation.id);
+  return operation;
+}
+async function appendOperationRow(scope, operation) {
+  const opInsert = buildInsertQuery(
+    `_kora_ops_${operation.collection}`,
+    serializeOperation(operation)
+  );
+  await scope.tx.execute(opInsert.sql, opInsert.params);
+}
+async function readLiveRow(scope, collection, id) {
+  const rows = await scope.tx.query(
+    `SELECT * FROM ${quoteIdent(collection)} WHERE id = ? AND _deleted = 0`,
+    [id]
+  );
+  return rows[0];
+}
+function requireDefinition(env, collection) {
+  const definition = env.schema.collections[collection];
+  if (!definition) {
+    throw new KoraError4(
+      `Unknown collection "${collection}". Available: ${Object.keys(env.schema.collections).join(", ")}`,
+      "UNKNOWN_COLLECTION",
+      { collection }
+    );
+  }
+  return definition;
+}
+
+// src/mutations/execute-delete.ts
+async function executeDelete(ctx, id, options) {
+  const result = await runLocalWrite(
+    ctx,
+    (scope) => writeDeleteInTx(ctx, scope, ctx.collection, id, {
+      skipReferentialEnforcement: options?.skipReferentialEnforcement ?? false,
+      extraCausalDeps: ctx.extraCausalDeps ?? []
+    })
+  );
+  return result.operation ? [result.operation, ...result.sideEffects] : result.sideEffects;
+}
+
+// src/mutations/execute-insert.ts
+async function executeInsert(ctx, data) {
+  const prepared = await prepareInsert(ctx, ctx.collection, data);
+  const result = await runLocalWrite(
+    ctx,
+    (scope) => writeInsertInTx(ctx, scope, prepared, ctx.extraCausalDeps ?? [])
+  );
+  return result.record;
+}
+
+// src/mutations/execute-update.ts
+import { validateRecord as validateRecord2 } from "@korajs/core";
+async function executeUpdate(ctx, id, data) {
+  const validated = validateRecord2(ctx.collection, ctx.definition, data, "update");
+  const result = await runLocalWrite(
+    ctx,
+    (scope) => writeUpdateInTx(ctx, scope, ctx.collection, id, validated, ctx.extraCausalDeps ?? [])
+  );
+  return result.record;
+}
+
+export {
+  CausalScope,
+  withWriteScope,
+  isStorageFullError,
+  parseFieldVersions,
+  serializeFieldVersions,
+  fieldVersionsForFields,
+  effectiveFieldVersion,
+  resolvePerFieldLww,
+  InvalidStateTransitionError,
+  validateStateTransition,
+  validateUpdateStateMachine,
+  toAtRestWriteData,
+  prepareInsert,
+  writeInsertInTx,
+  writeUpdateInTx,
+  writeDeleteInTx,
+  executeDelete,
+  executeInsert,
+  executeUpdate
+};
+//# sourceMappingURL=chunk-HZTDBLDB.js.map