@korajs/core 0.1.0

package/dist/index.cjs

@@ -0,0 +1,1153 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ArrayFieldBuilder: () => ArrayFieldBuilder,
+  CONNECTION_QUALITIES: () => CONNECTION_QUALITIES,
+  ClockDriftError: () => ClockDriftError,
+  EnumFieldBuilder: () => EnumFieldBuilder,
+  FieldBuilder: () => FieldBuilder,
+  HybridLogicalClock: () => HybridLogicalClock,
+  KoraError: () => KoraError,
+  MERGE_STRATEGIES: () => MERGE_STRATEGIES,
+  MergeConflictError: () => MergeConflictError,
+  OperationError: () => OperationError,
+  SchemaValidationError: () => SchemaValidationError,
+  StorageError: () => StorageError,
+  SyncError: () => SyncError,
+  advanceVector: () => advanceVector,
+  computeDelta: () => computeDelta,
+  createOperation: () => createOperation,
+  createVersionVector: () => createVersionVector,
+  defineSchema: () => defineSchema,
+  deserializeVector: () => deserializeVector,
+  dominates: () => dominates,
+  extractTimestamp: () => extractTimestamp,
+  generateFullDDL: () => generateFullDDL,
+  generateSQL: () => generateSQL,
+  generateUUIDv7: () => generateUUIDv7,
+  isValidOperation: () => isValidOperation,
+  isValidUUIDv7: () => isValidUUIDv7,
+  mergeVectors: () => mergeVectors,
+  serializeVector: () => serializeVector,
+  t: () => t,
+  validateRecord: () => validateRecord,
+  vectorsEqual: () => vectorsEqual,
+  verifyOperationIntegrity: () => verifyOperationIntegrity
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/types.ts
+var MERGE_STRATEGIES = [
+  "auto-merge",
+  "lww",
+  "first-write-wins",
+  "server-decides",
+  "custom"
+];
+var CONNECTION_QUALITIES = ["excellent", "good", "fair", "poor", "offline"];
+
+// src/errors/errors.ts
+var KoraError = class extends Error {
+  constructor(message, code, context) {
+    super(message);
+    this.code = code;
+    this.context = context;
+    this.name = "KoraError";
+  }
+  code;
+  context;
+};
+var SchemaValidationError = class extends KoraError {
+  constructor(message, context) {
+    super(message, "SCHEMA_VALIDATION", context);
+    this.name = "SchemaValidationError";
+  }
+};
+var OperationError = class extends KoraError {
+  constructor(message, context) {
+    super(message, "OPERATION_ERROR", context);
+    this.name = "OperationError";
+  }
+};
+var MergeConflictError = class extends KoraError {
+  constructor(operationA, operationB, field) {
+    super(
+      `Merge conflict on field "${field}" in collection "${operationA.collection}"`,
+      "MERGE_CONFLICT",
+      { operationA: operationA.id, operationB: operationB.id, field }
+    );
+    this.operationA = operationA;
+    this.operationB = operationB;
+    this.field = field;
+    this.name = "MergeConflictError";
+  }
+  operationA;
+  operationB;
+  field;
+};
+var SyncError = class extends KoraError {
+  constructor(message, context) {
+    super(message, "SYNC_ERROR", context);
+    this.name = "SyncError";
+  }
+};
+var StorageError = class extends KoraError {
+  constructor(message, context) {
+    super(message, "STORAGE_ERROR", context);
+    this.name = "StorageError";
+  }
+};
+var ClockDriftError = class extends KoraError {
+  constructor(currentHlcTime, physicalTime) {
+    const driftSeconds = Math.round((currentHlcTime - physicalTime) / 1e3);
+    super(
+      `Clock drift of ${driftSeconds}s detected. Physical time is behind HLC by more than 5 minutes. This indicates a severe clock issue.`,
+      "CLOCK_DRIFT",
+      { currentHlcTime, physicalTime, driftSeconds }
+    );
+    this.currentHlcTime = currentHlcTime;
+    this.physicalTime = physicalTime;
+    this.name = "ClockDriftError";
+  }
+  currentHlcTime;
+  physicalTime;
+};
+
+// src/clock/hlc.ts
+var systemTimeSource = { now: () => Date.now() };
+var DRIFT_WARN_MS = 6e4;
+var DRIFT_ERROR_MS = 5 * 6e4;
+var HybridLogicalClock = class {
+  constructor(nodeId, timeSource = systemTimeSource, onDriftWarning) {
+    this.nodeId = nodeId;
+    this.timeSource = timeSource;
+    this.onDriftWarning = onDriftWarning;
+  }
+  nodeId;
+  timeSource;
+  onDriftWarning;
+  wallTime = 0;
+  logical = 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
+   */
+  now() {
+    const physicalTime = this.timeSource.now();
+    this.checkDrift(physicalTime);
+    if (physicalTime > this.wallTime) {
+      this.wallTime = physicalTime;
+      this.logical = 0;
+    } else {
+      this.logical++;
+    }
+    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
+   */
+  receive(remote) {
+    const physicalTime = this.timeSource.now();
+    if (physicalTime > this.wallTime && physicalTime > remote.wallTime) {
+      this.wallTime = physicalTime;
+      this.logical = 0;
+    } else if (remote.wallTime > this.wallTime) {
+      this.wallTime = remote.wallTime;
+      this.logical = remote.logical + 1;
+    } else if (this.wallTime === remote.wallTime) {
+      this.logical = Math.max(this.logical, remote.logical) + 1;
+    } else {
+      this.logical++;
+    }
+    this.checkDrift(physicalTime);
+    return { wallTime: this.wallTime, logical: this.logical, nodeId: this.nodeId };
+  }
+  /**
+   * Compare two timestamps. Returns negative if a < b, positive if a > b, zero if equal.
+   * Total order: wallTime first, then logical, then nodeId (lexicographic).
+   */
+  static compare(a, b) {
+    if (a.wallTime !== b.wallTime) return a.wallTime - b.wallTime;
+    if (a.logical !== b.logical) return a.logical - b.logical;
+    if (a.nodeId < b.nodeId) return -1;
+    if (a.nodeId > b.nodeId) return 1;
+    return 0;
+  }
+  /**
+   * Serialize an HLC timestamp to a string that sorts lexicographically.
+   * Format: zero-padded wallTime:logical:nodeId
+   */
+  static serialize(ts) {
+    const wall = ts.wallTime.toString().padStart(15, "0");
+    const log = ts.logical.toString().padStart(5, "0");
+    return `${wall}:${log}:${ts.nodeId}`;
+  }
+  /**
+   * Deserialize an HLC timestamp from its serialized string form.
+   */
+  static deserialize(s) {
+    const parts = s.split(":");
+    if (parts.length < 3) {
+      throw new Error(`Invalid HLC timestamp string: "${s}"`);
+    }
+    return {
+      wallTime: Number.parseInt(parts[0] ?? "0", 10),
+      logical: Number.parseInt(parts[1] ?? "0", 10),
+      // nodeId may contain colons, so rejoin remaining parts
+      nodeId: parts.slice(2).join(":")
+    };
+  }
+  checkDrift(physicalTime) {
+    const drift = this.wallTime - physicalTime;
+    if (drift > DRIFT_ERROR_MS) {
+      throw new ClockDriftError(this.wallTime, physicalTime);
+    }
+    if (drift > DRIFT_WARN_MS) {
+      this.onDriftWarning?.(drift);
+    }
+  }
+};
+
+// src/identifiers/uuid-v7.ts
+var defaultRandom = globalThis.crypto;
+function generateUUIDv7(timestamp = Date.now(), randomSource = defaultRandom) {
+  const bytes = new Uint8Array(16);
+  randomSource.getRandomValues(bytes);
+  const ms = Math.max(0, Math.floor(timestamp));
+  bytes[0] = ms / 2 ** 40 & 255;
+  bytes[1] = ms / 2 ** 32 & 255;
+  bytes[2] = ms / 2 ** 24 & 255;
+  bytes[3] = ms / 2 ** 16 & 255;
+  bytes[4] = ms / 2 ** 8 & 255;
+  bytes[5] = ms & 255;
+  bytes[6] = (bytes[6] ?? 0) & 15 | 112;
+  bytes[8] = (bytes[8] ?? 0) & 63 | 128;
+  return formatUUID(bytes);
+}
+function extractTimestamp(uuid) {
+  const hex = uuid.replace(/-/g, "");
+  const high = Number.parseInt(hex.slice(0, 8), 16);
+  const low = Number.parseInt(hex.slice(8, 12), 16);
+  return high * 2 ** 16 + low;
+}
+function isValidUUIDv7(uuid) {
+  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(uuid)) {
+    return false;
+  }
+  const hex = uuid.replace(/-/g, "");
+  if (hex[12] !== "7") return false;
+  const variantNibble = Number.parseInt(hex[16] ?? "0", 16);
+  return variantNibble >= 8 && variantNibble <= 11;
+}
+function formatUUID(bytes) {
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+
+// src/operations/content-hash.ts
+async function computeOperationId(input, timestamp) {
+  const canonical = canonicalize({
+    type: input.type,
+    collection: input.collection,
+    recordId: input.recordId,
+    data: input.data,
+    timestamp,
+    nodeId: input.nodeId
+  });
+  const encoded = new TextEncoder().encode(canonical);
+  const hashBuffer = await globalThis.crypto.subtle.digest("SHA-256", encoded);
+  return bufferToHex(hashBuffer);
+}
+function canonicalize(obj) {
+  if (obj === null || obj === void 0) {
+    return JSON.stringify(obj);
+  }
+  if (typeof obj !== "object") {
+    return JSON.stringify(obj);
+  }
+  if (Array.isArray(obj)) {
+    const items = obj.map((item) => canonicalize(item));
+    return `[${items.join(",")}]`;
+  }
+  const keys = Object.keys(obj).sort();
+  const pairs = keys.map((key) => {
+    const value = obj[key];
+    return `${JSON.stringify(key)}:${canonicalize(value)}`;
+  });
+  return `{${pairs.join(",")}}`;
+}
+function bufferToHex(buffer) {
+  const bytes = new Uint8Array(buffer);
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+// src/operations/operation.ts
+async function createOperation(input, clock) {
+  validateOperationParams(input);
+  const timestamp = clock.now();
+  const serializedTs = HybridLogicalClock.serialize(timestamp);
+  const id = await computeOperationId(input, serializedTs);
+  const operation = {
+    id,
+    nodeId: input.nodeId,
+    type: input.type,
+    collection: input.collection,
+    recordId: input.recordId,
+    data: input.data ? { ...input.data } : null,
+    previousData: input.previousData ? { ...input.previousData } : null,
+    timestamp,
+    sequenceNumber: input.sequenceNumber,
+    causalDeps: [...input.causalDeps],
+    schemaVersion: input.schemaVersion
+  };
+  return deepFreeze(operation);
+}
+function validateOperationParams(input) {
+  if (!input.nodeId || typeof input.nodeId !== "string") {
+    throw new OperationError("nodeId is required and must be a non-empty string", {
+      received: input.nodeId
+    });
+  }
+  if (!input.type || !["insert", "update", "delete"].includes(input.type)) {
+    throw new OperationError('type must be "insert", "update", or "delete"', {
+      received: input.type
+    });
+  }
+  if (!input.collection || typeof input.collection !== "string") {
+    throw new OperationError("collection is required and must be a non-empty string", {
+      received: input.collection
+    });
+  }
+  if (!input.recordId || typeof input.recordId !== "string") {
+    throw new OperationError("recordId is required and must be a non-empty string", {
+      received: input.recordId
+    });
+  }
+  if (input.type === "insert" && input.data === null) {
+    throw new OperationError("insert operations must include data", {
+      type: input.type,
+      collection: input.collection
+    });
+  }
+  if (input.type === "update" && input.data === null) {
+    throw new OperationError("update operations must include data with changed fields", {
+      type: input.type,
+      collection: input.collection
+    });
+  }
+  if (input.type === "update" && input.previousData === null) {
+    throw new OperationError(
+      "update operations must include previousData for 3-way merge support",
+      {
+        type: input.type,
+        collection: input.collection
+      }
+    );
+  }
+  if (input.type === "delete" && input.data !== null) {
+    throw new OperationError("delete operations must have null data", {
+      type: input.type,
+      collection: input.collection
+    });
+  }
+  if (typeof input.sequenceNumber !== "number" || input.sequenceNumber < 0) {
+    throw new OperationError("sequenceNumber must be a non-negative number", {
+      received: input.sequenceNumber
+    });
+  }
+  if (!Array.isArray(input.causalDeps)) {
+    throw new OperationError("causalDeps must be an array of operation IDs", {
+      received: typeof input.causalDeps
+    });
+  }
+  if (typeof input.schemaVersion !== "number" || input.schemaVersion < 1) {
+    throw new OperationError("schemaVersion must be a positive number", {
+      received: input.schemaVersion
+    });
+  }
+}
+async function verifyOperationIntegrity(op) {
+  const input = {
+    nodeId: op.nodeId,
+    type: op.type,
+    collection: op.collection,
+    recordId: op.recordId,
+    data: op.data,
+    previousData: op.previousData,
+    sequenceNumber: op.sequenceNumber,
+    causalDeps: op.causalDeps,
+    schemaVersion: op.schemaVersion
+  };
+  const serializedTs = HybridLogicalClock.serialize(op.timestamp);
+  const expectedId = await computeOperationId(input, serializedTs);
+  return op.id === expectedId;
+}
+function isValidOperation(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const op = value;
+  return typeof op.id === "string" && typeof op.nodeId === "string" && (op.type === "insert" || op.type === "update" || op.type === "delete") && typeof op.collection === "string" && typeof op.recordId === "string" && typeof op.sequenceNumber === "number" && Array.isArray(op.causalDeps) && typeof op.schemaVersion === "number" && typeof op.timestamp === "object" && op.timestamp !== null;
+}
+function deepFreeze(obj) {
+  if (typeof obj !== "object" || obj === null) return obj;
+  Object.freeze(obj);
+  for (const value of Object.values(obj)) {
+    if (typeof value === "object" && value !== null && !Object.isFrozen(value)) {
+      deepFreeze(value);
+    }
+  }
+  return obj;
+}
+
+// src/schema/define.ts
+var COLLECTION_NAME_RE = /^[a-z][a-z0-9_]*$/;
+var FIELD_NAME_RE = /^[a-z][a-z0-9_]*$/;
+var RESERVED_FIELDS = /* @__PURE__ */ new Set(["id", "_created_at", "_updated_at", "_deleted"]);
+function defineSchema(input) {
+  validateVersion(input.version);
+  const collections = {};
+  for (const [name, collectionInput] of Object.entries(input.collections)) {
+    validateCollectionName(name);
+    collections[name] = buildCollection(name, collectionInput);
+  }
+  if (Object.keys(collections).length === 0) {
+    throw new SchemaValidationError("Schema must define at least one collection");
+  }
+  const relations = {};
+  if (input.relations) {
+    for (const [name, relationInput] of Object.entries(input.relations)) {
+      validateRelation(name, relationInput, collections);
+      relations[name] = { ...relationInput };
+    }
+  }
+  return { version: input.version, collections, relations };
+}
+function validateVersion(version) {
+  if (typeof version !== "number" || !Number.isInteger(version) || version < 1) {
+    throw new SchemaValidationError("Schema version must be a positive integer", {
+      received: version
+    });
+  }
+}
+function validateCollectionName(name) {
+  if (!COLLECTION_NAME_RE.test(name)) {
+    throw new SchemaValidationError(
+      `Collection name "${name}" is invalid. Must be lowercase, start with a letter, and contain only letters, numbers, and underscores.`,
+      { collection: name }
+    );
+  }
+}
+function buildCollection(name, input) {
+  const fields = {};
+  if (!input.fields || Object.keys(input.fields).length === 0) {
+    throw new SchemaValidationError(`Collection "${name}" must define at least one field`, {
+      collection: name
+    });
+  }
+  for (const [fieldName, builder] of Object.entries(input.fields)) {
+    validateFieldName(name, fieldName);
+    fields[fieldName] = builder._build();
+  }
+  const indexes = input.indexes ?? [];
+  for (const indexField of indexes) {
+    if (!(indexField in fields)) {
+      throw new SchemaValidationError(
+        `Index field "${indexField}" does not exist in collection "${name}". Available fields: ${Object.keys(fields).join(", ")}`,
+        { collection: name, field: indexField }
+      );
+    }
+  }
+  const constraints = [];
+  if (input.constraints) {
+    for (const constraintInput of input.constraints) {
+      validateConstraint(name, constraintInput, fields);
+      constraints.push({ ...constraintInput });
+    }
+  }
+  const resolvers = {};
+  if (input.resolve) {
+    for (const [fieldName, resolver] of Object.entries(input.resolve)) {
+      if (!(fieldName in fields)) {
+        throw new SchemaValidationError(
+          `Resolver for field "${fieldName}" does not exist in collection "${name}". Available fields: ${Object.keys(fields).join(", ")}`,
+          { collection: name, field: fieldName }
+        );
+      }
+      if (typeof resolver !== "function") {
+        throw new SchemaValidationError(
+          `Resolver for field "${fieldName}" in collection "${name}" must be a function`,
+          { collection: name, field: fieldName }
+        );
+      }
+      resolvers[fieldName] = resolver;
+    }
+  }
+  return { fields, indexes, constraints, resolvers };
+}
+function validateFieldName(collection, fieldName) {
+  if (RESERVED_FIELDS.has(fieldName)) {
+    throw new SchemaValidationError(
+      `Field name "${fieldName}" is reserved in collection "${collection}". Reserved fields: ${[...RESERVED_FIELDS].join(", ")}`,
+      { collection, field: fieldName }
+    );
+  }
+  if (!FIELD_NAME_RE.test(fieldName)) {
+    throw new SchemaValidationError(
+      `Field name "${fieldName}" in collection "${collection}" is invalid. Must be lowercase, start with a letter, and contain only letters, numbers, and underscores.`,
+      { collection, field: fieldName }
+    );
+  }
+}
+function validateConstraint(collection, constraint, fields) {
+  for (const field of constraint.fields) {
+    if (!(field in fields)) {
+      throw new SchemaValidationError(
+        `Constraint references field "${field}" which does not exist in collection "${collection}". Available fields: ${Object.keys(fields).join(", ")}`,
+        { collection, field }
+      );
+    }
+  }
+  if (constraint.onConflict === "priority-field" && !constraint.priorityField) {
+    throw new SchemaValidationError(
+      `Constraint with "priority-field" onConflict strategy in collection "${collection}" requires a priorityField`,
+      { collection }
+    );
+  }
+  if (constraint.onConflict === "priority-field" && constraint.priorityField) {
+    if (!(constraint.priorityField in fields)) {
+      throw new SchemaValidationError(
+        `Constraint priorityField "${constraint.priorityField}" does not exist in collection "${collection}"`,
+        { collection, field: constraint.priorityField }
+      );
+    }
+  }
+  if (constraint.onConflict === "custom" && typeof constraint.resolve !== "function") {
+    throw new SchemaValidationError(
+      `Constraint with "custom" onConflict strategy in collection "${collection}" requires a resolve function`,
+      { collection }
+    );
+  }
+}
+function validateRelation(name, relation, collections) {
+  if (!(relation.from in collections)) {
+    throw new SchemaValidationError(
+      `Relation "${name}" references source collection "${relation.from}" which does not exist. Available collections: ${Object.keys(collections).join(", ")}`,
+      { relation: name, collection: relation.from }
+    );
+  }
+  if (!(relation.to in collections)) {
+    throw new SchemaValidationError(
+      `Relation "${name}" references target collection "${relation.to}" which does not exist. Available collections: ${Object.keys(collections).join(", ")}`,
+      { relation: name, collection: relation.to }
+    );
+  }
+  const fromCollection = collections[relation.from];
+  if (fromCollection && !(relation.field in fromCollection.fields)) {
+    throw new SchemaValidationError(
+      `Relation "${name}" references field "${relation.field}" which does not exist in collection "${relation.from}". Available fields: ${Object.keys(fromCollection.fields).join(", ")}`,
+      { relation: name, collection: relation.from, field: relation.field }
+    );
+  }
+}
+
+// src/schema/sql-gen.ts
+function generateSQL(collectionName, collection, relations) {
+  const statements = [];
+  const columns = ["id TEXT PRIMARY KEY NOT NULL"];
+  const indexedFields = new Set(collection.indexes);
+  const fkFields = [];
+  for (const [fieldName, descriptor] of Object.entries(collection.fields)) {
+    let colDef = columnDefinition(fieldName, descriptor);
+    if (relations) {
+      for (const rel of Object.values(relations)) {
+        if (rel.from === collectionName && rel.field === fieldName) {
+          colDef += ` REFERENCES ${rel.to}(id)`;
+          fkFields.push(fieldName);
+          break;
+        }
+      }
+    }
+    columns.push(colDef);
+  }
+  columns.push("_created_at INTEGER NOT NULL");
+  columns.push("_updated_at INTEGER NOT NULL");
+  columns.push("_deleted INTEGER NOT NULL DEFAULT 0");
+  statements.push(`CREATE TABLE IF NOT EXISTS ${collectionName} (
+  ${columns.join(",\n  ")}
+)`);
+  for (const indexField of collection.indexes) {
+    statements.push(
+      `CREATE INDEX IF NOT EXISTS idx_${collectionName}_${indexField} ON ${collectionName} (${indexField})`
+    );
+  }
+  for (const fkField of fkFields) {
+    if (!indexedFields.has(fkField)) {
+      statements.push(
+        `CREATE INDEX IF NOT EXISTS idx_${collectionName}_${fkField} ON ${collectionName} (${fkField})`
+      );
+    }
+  }
+  statements.push(
+    `CREATE TABLE IF NOT EXISTS _kora_ops_${collectionName} (
+  id TEXT PRIMARY KEY NOT NULL,
+  node_id TEXT NOT NULL,
+  type TEXT NOT NULL,
+  record_id TEXT NOT NULL,
+  data TEXT,
+  previous_data TEXT,
+  timestamp TEXT NOT NULL,
+  sequence_number INTEGER NOT NULL,
+  causal_deps TEXT NOT NULL,
+  schema_version INTEGER NOT NULL
+)`
+  );
+  return statements;
+}
+function generateFullDDL(schema) {
+  const statements = [];
+  statements.push(
+    "CREATE TABLE IF NOT EXISTS _kora_meta (\n  key TEXT PRIMARY KEY NOT NULL,\n  value TEXT NOT NULL\n)"
+  );
+  statements.push(
+    "CREATE TABLE IF NOT EXISTS _kora_version_vector (\n  node_id TEXT PRIMARY KEY NOT NULL,\n  sequence_number INTEGER NOT NULL\n)"
+  );
+  for (const [name, collection] of Object.entries(schema.collections)) {
+    statements.push(...generateSQL(name, collection, schema.relations));
+  }
+  return statements;
+}
+function columnDefinition(fieldName, descriptor) {
+  const sqlType = mapFieldType(descriptor);
+  const parts = [fieldName, sqlType];
+  if (descriptor.required && descriptor.defaultValue === void 0 && !descriptor.auto) {
+    parts.push("NOT NULL");
+  }
+  if (descriptor.defaultValue !== void 0) {
+    parts.push(`DEFAULT ${sqlDefault(descriptor.defaultValue)}`);
+  }
+  if (descriptor.kind === "enum" && descriptor.enumValues) {
+    const values = descriptor.enumValues.map((v) => `'${v}'`).join(", ");
+    parts.push(`CHECK (${fieldName} IN (${values}))`);
+  }
+  return parts.join(" ");
+}
+function mapFieldType(descriptor) {
+  switch (descriptor.kind) {
+    case "string":
+      return "TEXT";
+    case "number":
+      return "REAL";
+    case "boolean":
+      return "INTEGER";
+    case "enum":
+      return "TEXT";
+    case "timestamp":
+      return "INTEGER";
+    case "array":
+      return "TEXT";
+    // JSON-serialized
+    case "richtext":
+      return "BLOB";
+  }
+}
+function sqlDefault(value) {
+  if (value === null) return "NULL";
+  if (typeof value === "string") return `'${value}'`;
+  if (typeof value === "number") return String(value);
+  if (typeof value === "boolean") return value ? "1" : "0";
+  return `'${JSON.stringify(value)}'`;
+}
+
+// src/schema/types.ts
+var FieldBuilder = class _FieldBuilder {
+  _kind;
+  _required;
+  _defaultValue;
+  _auto;
+  constructor(kind, required = true, defaultValue = void 0, auto = false) {
+    this._kind = kind;
+    this._required = required;
+    this._defaultValue = defaultValue;
+    this._auto = auto;
+  }
+  /** Mark this field as optional (not required on insert) */
+  optional() {
+    return new _FieldBuilder(this._kind, false, this._defaultValue, this._auto);
+  }
+  /** Set a default value for this field. Implicitly makes the field optional. */
+  default(value) {
+    return new _FieldBuilder(this._kind, false, value, this._auto);
+  }
+  /** Mark this field as auto-populated (e.g., createdAt timestamps). Developers cannot set auto fields. */
+  auto() {
+    return new _FieldBuilder(this._kind, false, void 0, true);
+  }
+  /** @internal Build the final FieldDescriptor. Used by defineSchema(). */
+  _build() {
+    return {
+      kind: this._kind,
+      required: this._required,
+      defaultValue: this._defaultValue,
+      auto: this._auto,
+      enumValues: null,
+      itemKind: null
+    };
+  }
+};
+var EnumFieldBuilder = class _EnumFieldBuilder extends FieldBuilder {
+  _enumValues;
+  constructor(values, required = true, defaultValue = void 0, auto = false) {
+    super("enum", required, defaultValue, auto);
+    this._enumValues = values;
+  }
+  optional() {
+    return new _EnumFieldBuilder(this._enumValues, false, this._defaultValue, this._auto);
+  }
+  default(value) {
+    return new _EnumFieldBuilder(this._enumValues, false, value, this._auto);
+  }
+  auto() {
+    return new _EnumFieldBuilder(this._enumValues, false, void 0, true);
+  }
+  _build() {
+    return {
+      kind: "enum",
+      required: this._required,
+      defaultValue: this._defaultValue,
+      auto: this._auto,
+      enumValues: this._enumValues,
+      itemKind: null
+    };
+  }
+};
+var ArrayFieldBuilder = class _ArrayFieldBuilder extends FieldBuilder {
+  _itemKind;
+  constructor(itemBuilder, required = true, defaultValue = void 0, auto = false) {
+    super("array", required, defaultValue, auto);
+    this._itemKind = itemBuilder._build().kind;
+  }
+  optional() {
+    return new _ArrayFieldBuilder(
+      new FieldBuilder(this._itemKind),
+      false,
+      this._defaultValue,
+      this._auto
+    );
+  }
+  default(value) {
+    return new _ArrayFieldBuilder(new FieldBuilder(this._itemKind), false, value, this._auto);
+  }
+  auto() {
+    return new _ArrayFieldBuilder(new FieldBuilder(this._itemKind), false, void 0, true);
+  }
+  _build() {
+    return {
+      kind: "array",
+      required: this._required,
+      defaultValue: this._defaultValue,
+      auto: this._auto,
+      enumValues: null,
+      itemKind: this._itemKind
+    };
+  }
+};
+var t = {
+  string() {
+    return new FieldBuilder("string", true, void 0, false);
+  },
+  number() {
+    return new FieldBuilder("number", true, void 0, false);
+  },
+  boolean() {
+    return new FieldBuilder("boolean", true, void 0, false);
+  },
+  timestamp() {
+    return new FieldBuilder("timestamp", true, void 0, false);
+  },
+  richtext() {
+    return new FieldBuilder("richtext", true, void 0, false);
+  },
+  enum(values) {
+    return new EnumFieldBuilder(values, true, void 0, false);
+  },
+  array(itemBuilder) {
+    return new ArrayFieldBuilder(itemBuilder, true, void 0, false);
+  }
+};
+
+// src/schema/validation.ts
+function validateRecord(collection, collectionDef, data, operationType) {
+  if (operationType === "delete") {
+    return {};
+  }
+  const result = {};
+  const fieldNames = Object.keys(collectionDef.fields);
+  for (const key of Object.keys(data)) {
+    if (!(key in collectionDef.fields)) {
+      throw new SchemaValidationError(
+        `Unknown field "${key}" in collection "${collection}". Available fields: ${fieldNames.join(", ")}`,
+        { collection, field: key }
+      );
+    }
+  }
+  for (const [fieldName, descriptor] of Object.entries(collectionDef.fields)) {
+    const value = data[fieldName];
+    const hasValue = fieldName in data;
+    if (descriptor.auto && hasValue) {
+      throw new SchemaValidationError(
+        `Field "${fieldName}" in collection "${collection}" is auto-populated and cannot be set manually`,
+        { collection, field: fieldName }
+      );
+    }
+    if (operationType === "update") {
+      if (hasValue) {
+        if (value !== void 0 && value !== null) {
+          validateFieldValue(collection, fieldName, descriptor, value);
+        }
+        result[fieldName] = value;
+      }
+      continue;
+    }
+    if (descriptor.auto) {
+      continue;
+    }
+    if (!hasValue || value === void 0) {
+      if (descriptor.defaultValue !== void 0) {
+        result[fieldName] = typeof descriptor.defaultValue === "object" && descriptor.defaultValue !== null ? JSON.parse(JSON.stringify(descriptor.defaultValue)) : descriptor.defaultValue;
+        continue;
+      }
+      if (descriptor.required) {
+        throw new SchemaValidationError(
+          `Required field "${fieldName}" is missing in collection "${collection}"`,
+          { collection, field: fieldName }
+        );
+      }
+      continue;
+    }
+    validateFieldValue(collection, fieldName, descriptor, value);
+    result[fieldName] = value;
+  }
+  return result;
+}
+function validateFieldValue(collection, fieldName, descriptor, value) {
+  switch (descriptor.kind) {
+    case "string": {
+      if (typeof value !== "string") {
+        throw new SchemaValidationError(
+          `Field "${fieldName}" in collection "${collection}" must be a string, got ${typeof value}`,
+          { collection, field: fieldName, expectedType: "string", receivedType: typeof value }
+        );
+      }
+      break;
+    }
+    case "number": {
+      if (typeof value !== "number" || Number.isNaN(value)) {
+        throw new SchemaValidationError(
+          `Field "${fieldName}" in collection "${collection}" must be a number, got ${typeof value}`,
+          { collection, field: fieldName, expectedType: "number", receivedType: typeof value }
+        );
+      }
+      break;
+    }
+    case "boolean": {
+      if (typeof value !== "boolean") {
+        throw new SchemaValidationError(
+          `Field "${fieldName}" in collection "${collection}" must be a boolean, got ${typeof value}`,
+          { collection, field: fieldName, expectedType: "boolean", receivedType: typeof value }
+        );
+      }
+      break;
+    }
+    case "timestamp": {
+      if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new SchemaValidationError(
+          `Field "${fieldName}" in collection "${collection}" must be a timestamp (number), got ${typeof value}`,
+          {
+            collection,
+            field: fieldName,
+            expectedType: "timestamp",
+            receivedType: typeof value
+          }
+        );
+      }
+      break;
+    }
+    case "enum": {
+      if (typeof value !== "string") {
+        throw new SchemaValidationError(
+          `Field "${fieldName}" in collection "${collection}" must be a string (enum), got ${typeof value}`,
+          { collection, field: fieldName, expectedType: "enum", receivedType: typeof value }
+        );
+      }
+      if (descriptor.enumValues && !descriptor.enumValues.includes(value)) {
+        throw new SchemaValidationError(
+          `Field "${fieldName}" in collection "${collection}" must be one of: ${descriptor.enumValues.join(", ")}. Got "${value}"`,
+          {
+            collection,
+            field: fieldName,
+            allowedValues: [...descriptor.enumValues],
+            received: value
+          }
+        );
+      }
+      break;
+    }
+    case "array": {
+      if (!Array.isArray(value)) {
+        throw new SchemaValidationError(
+          `Field "${fieldName}" in collection "${collection}" must be an array, got ${typeof value}`,
+          { collection, field: fieldName, expectedType: "array", receivedType: typeof value }
+        );
+      }
+      if (descriptor.itemKind) {
+        const expectedType = jsTypeForKind(descriptor.itemKind);
+        for (let i = 0; i < value.length; i++) {
+          const item = value[i];
+          if (!matchesJsType(item, expectedType)) {
+            throw new SchemaValidationError(
+              `Field "${fieldName}[${i}]" in collection "${collection}" must be a ${descriptor.itemKind}, got ${typeof item}`,
+              {
+                collection,
+                field: `${fieldName}[${i}]`,
+                expectedType: descriptor.itemKind,
+                receivedType: typeof item
+              }
+            );
+          }
+        }
+      }
+      break;
+    }
+    case "richtext": {
+      if (!(value instanceof Uint8Array) && typeof value !== "string") {
+        throw new SchemaValidationError(
+          `Field "${fieldName}" in collection "${collection}" must be a Uint8Array or string for richtext, got ${typeof value}`,
+          {
+            collection,
+            field: fieldName,
+            expectedType: "richtext",
+            receivedType: typeof value
+          }
+        );
+      }
+      break;
+    }
+  }
+}
+function jsTypeForKind(kind) {
+  switch (kind) {
+    case "string":
+    case "enum":
+      return "string";
+    case "number":
+    case "timestamp":
+      return "number";
+    case "boolean":
+      return "boolean";
+    default:
+      return "object";
+  }
+}
+function matchesJsType(value, expected) {
+  switch (expected) {
+    case "string":
+      return typeof value === "string";
+    case "number":
+      return typeof value === "number";
+    case "boolean":
+      return typeof value === "boolean";
+    case "object":
+      return typeof value === "object";
+    default:
+      return false;
+  }
+}
+
+// src/version-vector/topological-sort.ts
+function topologicalSort(operations) {
+  if (operations.length <= 1) return [...operations];
+  const opMap = /* @__PURE__ */ new Map();
+  for (const op of operations) {
+    opMap.set(op.id, op);
+  }
+  const inDegree = /* @__PURE__ */ new Map();
+  const dependents = /* @__PURE__ */ new Map();
+  for (const op of operations) {
+    if (!inDegree.has(op.id)) {
+      inDegree.set(op.id, 0);
+    }
+    if (!dependents.has(op.id)) {
+      dependents.set(op.id, []);
+    }
+    for (const depId of op.causalDeps) {
+      if (opMap.has(depId)) {
+        inDegree.set(op.id, (inDegree.get(op.id) ?? 0) + 1);
+        const deps = dependents.get(depId);
+        if (deps) {
+          deps.push(op.id);
+        } else {
+          dependents.set(depId, [op.id]);
+        }
+      }
+    }
+  }
+  const queue = [];
+  for (const op of operations) {
+    if ((inDegree.get(op.id) ?? 0) === 0) {
+      queue.push(op);
+    }
+  }
+  queue.sort(compareByTimestamp);
+  const result = [];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (!current) break;
+    result.push(current);
+    const deps = dependents.get(current.id) ?? [];
+    const newlyReady = [];
+    for (const depId of deps) {
+      const deg = (inDegree.get(depId) ?? 0) - 1;
+      inDegree.set(depId, deg);
+      if (deg === 0) {
+        const op = opMap.get(depId);
+        if (op) newlyReady.push(op);
+      }
+    }
+    if (newlyReady.length > 0) {
+      newlyReady.sort(compareByTimestamp);
+      mergeIntoSorted(queue, newlyReady);
+    }
+  }
+  if (result.length !== operations.length) {
+    throw new OperationError(
+      `Cycle detected in operation dependency graph. Sorted ${result.length} of ${operations.length} operations.`,
+      {
+        sortedCount: result.length,
+        totalCount: operations.length
+      }
+    );
+  }
+  return result;
+}
+function compareByTimestamp(a, b) {
+  return HybridLogicalClock.compare(a.timestamp, b.timestamp);
+}
+function mergeIntoSorted(target, items) {
+  let insertIndex = 0;
+  for (const item of items) {
+    while (insertIndex < target.length) {
+      const existing = target[insertIndex];
+      if (existing && compareByTimestamp(item, existing) <= 0) break;
+      insertIndex++;
+    }
+    target.splice(insertIndex, 0, item);
+    insertIndex++;
+  }
+}
+
+// src/version-vector/version-vector.ts
+function createVersionVector() {
+  return /* @__PURE__ */ new Map();
+}
+function mergeVectors(a, b) {
+  const merged = new Map(a);
+  for (const [nodeId, seq] of b) {
+    merged.set(nodeId, Math.max(merged.get(nodeId) ?? 0, seq));
+  }
+  return merged;
+}
+function advanceVector(vector, nodeId, seq) {
+  const updated = new Map(vector);
+  updated.set(nodeId, Math.max(updated.get(nodeId) ?? 0, seq));
+  return updated;
+}
+function dominates(a, b) {
+  for (const [nodeId, bSeq] of b) {
+    if ((a.get(nodeId) ?? 0) < bSeq) return false;
+  }
+  return true;
+}
+function vectorsEqual(a, b) {
+  if (a.size !== b.size) return false;
+  for (const [nodeId, aSeq] of a) {
+    if (b.get(nodeId) !== aSeq) return false;
+  }
+  return true;
+}
+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));
+    }
+  }
+  return topologicalSort(missing);
+}
+function serializeVector(vector) {
+  const entries = [...vector.entries()].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+  return JSON.stringify(entries);
+}
+function deserializeVector(s) {
+  const entries = JSON.parse(s);
+  return new Map(entries);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ArrayFieldBuilder,
+  CONNECTION_QUALITIES,
+  ClockDriftError,
+  EnumFieldBuilder,
+  FieldBuilder,
+  HybridLogicalClock,
+  KoraError,
+  MERGE_STRATEGIES,
+  MergeConflictError,
+  OperationError,
+  SchemaValidationError,
+  StorageError,
+  SyncError,
+  advanceVector,
+  computeDelta,
+  createOperation,
+  createVersionVector,
+  defineSchema,
+  deserializeVector,
+  dominates,
+  extractTimestamp,
+  generateFullDDL,
+  generateSQL,
+  generateUUIDv7,
+  isValidOperation,
+  isValidUUIDv7,
+  mergeVectors,
+  serializeVector,
+  t,
+  validateRecord,
+  vectorsEqual,
+  verifyOperationIntegrity
+});
+//# sourceMappingURL=index.cjs.map