@korajs/store 0.1.0

package/dist/index.cjs

@@ -0,0 +1,1288 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AdapterError: () => AdapterError,
+  Collection: () => Collection,
+  PersistenceError: () => PersistenceError,
+  QueryBuilder: () => QueryBuilder,
+  QueryError: () => QueryError,
+  RecordNotFoundError: () => RecordNotFoundError,
+  Store: () => Store,
+  StoreNotOpenError: () => StoreNotOpenError,
+  SubscriptionManager: () => SubscriptionManager,
+  WorkerInitError: () => WorkerInitError,
+  WorkerTimeoutError: () => WorkerTimeoutError,
+  decodeRichtext: () => decodeRichtext,
+  encodeRichtext: () => encodeRichtext,
+  pluralize: () => pluralize,
+  richtextToPlainText: () => richtextToPlainText,
+  singularize: () => singularize
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var import_core = require("@korajs/core");
+var QueryError = class extends import_core.KoraError {
+  constructor(message, context) {
+    super(message, "QUERY_ERROR", context);
+    this.name = "QueryError";
+  }
+};
+var RecordNotFoundError = class extends import_core.KoraError {
+  constructor(collection, recordId) {
+    super(`Record "${recordId}" not found in collection "${collection}"`, "RECORD_NOT_FOUND", {
+      collection,
+      recordId
+    });
+    this.name = "RecordNotFoundError";
+  }
+};
+var AdapterError = class extends import_core.KoraError {
+  constructor(message, context) {
+    super(message, "ADAPTER_ERROR", context);
+    this.name = "AdapterError";
+  }
+};
+var StoreNotOpenError = class extends import_core.KoraError {
+  constructor() {
+    super("Store is not open. Call store.open() before performing operations.", "STORE_NOT_OPEN");
+    this.name = "StoreNotOpenError";
+  }
+};
+var WorkerInitError = class extends import_core.KoraError {
+  constructor(message, context) {
+    super(`Worker initialization failed: ${message}`, "WORKER_INIT_ERROR", context);
+    this.name = "WorkerInitError";
+  }
+};
+var WorkerTimeoutError = class extends import_core.KoraError {
+  constructor(operation, timeoutMs) {
+    super(
+      `Worker did not respond within ${timeoutMs}ms for operation "${operation}"`,
+      "WORKER_TIMEOUT",
+      { operation, timeoutMs }
+    );
+    this.name = "WorkerTimeoutError";
+  }
+};
+var PersistenceError = class extends import_core.KoraError {
+  constructor(message, context) {
+    super(`Persistence error: ${message}`, "PERSISTENCE_ERROR", context);
+    this.name = "PersistenceError";
+  }
+};
+
+// src/store/store.ts
+var import_core4 = require("@korajs/core");
+
+// src/collection/collection.ts
+var import_core3 = require("@korajs/core");
+
+// src/query/sql-builder.ts
+function buildSelectQuery(descriptor, fields) {
+  const params = [];
+  const parts = [`SELECT * FROM ${descriptor.collection}`];
+  const whereClause = buildWhereClauseParts(descriptor.where, fields, params);
+  const deletedFilter = "_deleted = 0";
+  if (whereClause) {
+    parts.push(`WHERE ${deletedFilter} AND ${whereClause}`);
+  } else {
+    parts.push(`WHERE ${deletedFilter}`);
+  }
+  if (descriptor.orderBy.length > 0) {
+    const orderParts = descriptor.orderBy.map((o) => {
+      validateFieldName(o.field, fields);
+      return `${o.field} ${o.direction.toUpperCase()}`;
+    });
+    parts.push(`ORDER BY ${orderParts.join(", ")}`);
+  }
+  if (descriptor.limit !== void 0) {
+    parts.push(`LIMIT ${descriptor.limit}`);
+  }
+  if (descriptor.offset !== void 0) {
+    parts.push(`OFFSET ${descriptor.offset}`);
+  }
+  return { sql: parts.join(" "), params };
+}
+function buildCountQuery(descriptor, fields) {
+  const params = [];
+  const parts = [`SELECT COUNT(*) as count FROM ${descriptor.collection}`];
+  const whereClause = buildWhereClauseParts(descriptor.where, fields, params);
+  const deletedFilter = "_deleted = 0";
+  if (whereClause) {
+    parts.push(`WHERE ${deletedFilter} AND ${whereClause}`);
+  } else {
+    parts.push(`WHERE ${deletedFilter}`);
+  }
+  return { sql: parts.join(" "), params };
+}
+function buildInsertQuery(collection, record) {
+  const columns = Object.keys(record);
+  const placeholders = columns.map(() => "?");
+  const params = Object.values(record);
+  const sql = `INSERT INTO ${collection} (${columns.join(", ")}) VALUES (${placeholders.join(", ")})`;
+  return { sql, params };
+}
+function buildUpdateQuery(collection, id, changes) {
+  const setClauses = Object.keys(changes).map((col) => `${col} = ?`);
+  const params = [...Object.values(changes), id];
+  const sql = `UPDATE ${collection} SET ${setClauses.join(", ")} WHERE id = ?`;
+  return { sql, params };
+}
+function buildSoftDeleteQuery(collection, id, updatedAt) {
+  return {
+    sql: `UPDATE ${collection} SET _deleted = 1, _updated_at = ? WHERE id = ?`,
+    params: [updatedAt, id]
+  };
+}
+var VALID_OPERATORS = /* @__PURE__ */ new Set(["$eq", "$ne", "$gt", "$gte", "$lt", "$lte", "$in"]);
+function buildWhereClauseParts(where, fields, params) {
+  const conditions = [];
+  for (const [fieldName, value] of Object.entries(where)) {
+    validateFieldName(fieldName, fields);
+    const descriptor = fields[fieldName];
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+      const ops = value;
+      for (const [op, opValue] of Object.entries(ops)) {
+        if (!VALID_OPERATORS.has(op)) {
+          throw new QueryError(`Unknown operator "${op}" on field "${fieldName}"`, {
+            field: fieldName,
+            operator: op,
+            validOperators: [...VALID_OPERATORS]
+          });
+        }
+        conditions.push(buildOperatorCondition(fieldName, op, opValue, descriptor, params));
+      }
+    } else {
+      conditions.push(buildOperatorCondition(fieldName, "$eq", value, descriptor, params));
+    }
+  }
+  if (conditions.length === 0) return null;
+  return conditions.join(" AND ");
+}
+function buildOperatorCondition(fieldName, operator, value, descriptor, params) {
+  const sqlValue = descriptor?.kind === "boolean" && typeof value === "boolean" ? value ? 1 : 0 : value;
+  switch (operator) {
+    case "$eq":
+      if (sqlValue === null) {
+        return `${fieldName} IS NULL`;
+      }
+      params.push(sqlValue);
+      return `${fieldName} = ?`;
+    case "$ne":
+      if (sqlValue === null) {
+        return `${fieldName} IS NOT NULL`;
+      }
+      params.push(sqlValue);
+      return `${fieldName} != ?`;
+    case "$gt":
+      params.push(sqlValue);
+      return `${fieldName} > ?`;
+    case "$gte":
+      params.push(sqlValue);
+      return `${fieldName} >= ?`;
+    case "$lt":
+      params.push(sqlValue);
+      return `${fieldName} < ?`;
+    case "$lte":
+      params.push(sqlValue);
+      return `${fieldName} <= ?`;
+    case "$in": {
+      if (!Array.isArray(sqlValue)) {
+        throw new QueryError(`$in operator requires an array value for field "${fieldName}"`, {
+          field: fieldName,
+          received: typeof sqlValue
+        });
+      }
+      const placeholders = sqlValue.map(() => "?");
+      for (const item of sqlValue) {
+        params.push(
+          descriptor?.kind === "boolean" && typeof item === "boolean" ? item ? 1 : 0 : item
+        );
+      }
+      return `${fieldName} IN (${placeholders.join(", ")})`;
+    }
+    default:
+      throw new QueryError(`Unknown operator "${operator}"`, { operator });
+  }
+}
+function validateFieldName(fieldName, fields) {
+  const allowedFields = /* @__PURE__ */ new Set([
+    ...Object.keys(fields),
+    "id",
+    "createdAt",
+    "updatedAt",
+    "_created_at",
+    "_updated_at"
+  ]);
+  if (!allowedFields.has(fieldName)) {
+    throw new QueryError(
+      `Unknown field "${fieldName}" in query. Available fields: ${[...allowedFields].join(", ")}`,
+      { field: fieldName }
+    );
+  }
+}
+
+// src/serialization/serializer.ts
+var import_core2 = require("@korajs/core");
+
+// src/serialization/richtext-serializer.ts
+var Y = __toESM(require("yjs"), 1);
+var TEXT_KEY = "content";
+function encodeRichtext(value) {
+  if (value === null || value === void 0) {
+    return null;
+  }
+  if (typeof value === "string") {
+    const doc = new Y.Doc();
+    doc.getText(TEXT_KEY).insert(0, value);
+    return Y.encodeStateAsUpdate(doc);
+  }
+  if (value instanceof Uint8Array) {
+    return value;
+  }
+  if (value instanceof ArrayBuffer) {
+    return new Uint8Array(value);
+  }
+  throw new Error("Richtext value must be a string, Uint8Array, ArrayBuffer, null, or undefined.");
+}
+function decodeRichtext(value) {
+  if (value === null || value === void 0) {
+    return null;
+  }
+  if (typeof Buffer !== "undefined" && Buffer.isBuffer(value)) {
+    return new Uint8Array(value);
+  }
+  if (value instanceof Uint8Array) {
+    return value;
+  }
+  if (value instanceof ArrayBuffer) {
+    return new Uint8Array(value);
+  }
+  throw new Error("Richtext storage value must be Uint8Array, ArrayBuffer, Buffer, null, or undefined.");
+}
+function richtextToPlainText(value) {
+  const encoded = encodeRichtext(value);
+  if (!encoded) return "";
+  const doc = new Y.Doc();
+  Y.applyUpdate(doc, encoded);
+  return doc.getText(TEXT_KEY).toString();
+}
+
+// src/serialization/serializer.ts
+function serializeRecord(data, fields) {
+  const result = {};
+  for (const [key, value] of Object.entries(data)) {
+    const descriptor = fields[key];
+    if (!descriptor) {
+      result[key] = value;
+      continue;
+    }
+    result[key] = serializeValue(value, descriptor);
+  }
+  return result;
+}
+function deserializeRecord(row, fields) {
+  const result = {
+    id: row.id,
+    createdAt: row._created_at,
+    updatedAt: row._updated_at
+  };
+  for (const [key, descriptor] of Object.entries(fields)) {
+    const rawValue = row[key];
+    if (rawValue === void 0 || rawValue === null) {
+      result[key] = rawValue ?? null;
+      continue;
+    }
+    result[key] = deserializeValue(rawValue, descriptor);
+  }
+  return result;
+}
+function serializeOperation(op) {
+  return {
+    id: op.id,
+    node_id: op.nodeId,
+    type: op.type,
+    record_id: op.recordId,
+    data: op.data ? JSON.stringify(op.data) : null,
+    previous_data: op.previousData ? JSON.stringify(op.previousData) : null,
+    timestamp: import_core2.HybridLogicalClock.serialize(op.timestamp),
+    sequence_number: op.sequenceNumber,
+    causal_deps: JSON.stringify(op.causalDeps),
+    schema_version: op.schemaVersion
+  };
+}
+function deserializeOperation(row) {
+  return {
+    id: row.id,
+    nodeId: row.node_id,
+    type: row.type,
+    collection: "",
+    // Collection name is derived from the table name by the caller
+    recordId: row.record_id,
+    data: row.data ? JSON.parse(row.data) : null,
+    previousData: row.previous_data ? JSON.parse(row.previous_data) : null,
+    timestamp: import_core2.HybridLogicalClock.deserialize(row.timestamp),
+    sequenceNumber: row.sequence_number,
+    causalDeps: JSON.parse(row.causal_deps),
+    schemaVersion: row.schema_version
+  };
+}
+function deserializeOperationWithCollection(row, collection) {
+  const op = deserializeOperation(row);
+  return { ...op, collection };
+}
+function serializeValue(value, descriptor) {
+  if (value === null || value === void 0) {
+    return null;
+  }
+  switch (descriptor.kind) {
+    case "boolean":
+      return value ? 1 : 0;
+    case "array":
+      return JSON.stringify(value);
+    case "richtext":
+      return encodeRichtext(value);
+    default:
+      return value;
+  }
+}
+function deserializeValue(value, descriptor) {
+  switch (descriptor.kind) {
+    case "boolean":
+      return value === 1 || value === true;
+    case "array":
+      if (typeof value === "string") {
+        return JSON.parse(value);
+      }
+      return value;
+    case "richtext":
+      return decodeRichtext(value);
+    default:
+      return value;
+  }
+}
+
+// src/collection/collection.ts
+var Collection = class {
+  constructor(name, definition, schema, adapter, clock, nodeId, getSequenceNumber, onMutation) {
+    this.name = name;
+    this.definition = definition;
+    this.schema = schema;
+    this.adapter = adapter;
+    this.clock = clock;
+    this.nodeId = nodeId;
+    this.getSequenceNumber = getSequenceNumber;
+    this.onMutation = onMutation;
+  }
+  name;
+  definition;
+  schema;
+  adapter;
+  clock;
+  nodeId;
+  getSequenceNumber;
+  onMutation;
+  /**
+   * Insert a new record into the collection.
+   * Generates a UUID v7 for the id, validates data, and persists atomically.
+   *
+   * @param data - The record data (auto fields and defaults are applied automatically)
+   * @returns The inserted record with id, createdAt, updatedAt
+   */
+  async insert(data) {
+    const validated = (0, import_core3.validateRecord)(this.name, this.definition, data, "insert");
+    const recordId = (0, import_core3.generateUUIDv7)();
+    const now = Date.now();
+    for (const [fieldName, descriptor] of Object.entries(this.definition.fields)) {
+      if (descriptor.auto && descriptor.kind === "timestamp") {
+        validated[fieldName] = now;
+      }
+    }
+    const sequenceNumber = this.getSequenceNumber();
+    const operation = await (0, import_core3.createOperation)(
+      {
+        nodeId: this.nodeId,
+        type: "insert",
+        collection: this.name,
+        recordId,
+        data: { ...validated },
+        previousData: null,
+        sequenceNumber,
+        causalDeps: [],
+        schemaVersion: this.schema.version
+      },
+      this.clock
+    );
+    const serializedData = serializeRecord(validated, this.definition.fields);
+    const record = {
+      id: recordId,
+      ...serializedData,
+      _created_at: now,
+      _updated_at: now
+    };
+    const insertQuery = buildInsertQuery(this.name, record);
+    const opRow = serializeOperation(operation);
+    const opInsert = buildInsertQuery(
+      `_kora_ops_${this.name}`,
+      opRow
+    );
+    await this.adapter.transaction(async (tx) => {
+      await tx.execute(insertQuery.sql, insertQuery.params);
+      await tx.execute(opInsert.sql, opInsert.params);
+      await tx.execute(
+        "INSERT OR REPLACE INTO _kora_version_vector (node_id, sequence_number) VALUES (?, ?)",
+        [this.nodeId, sequenceNumber]
+      );
+    });
+    this.onMutation(this.name, operation);
+    return {
+      id: recordId,
+      ...validated,
+      createdAt: now,
+      updatedAt: now
+    };
+  }
+  /**
+   * Find a record by its ID. Returns null if not found or soft-deleted.
+   */
+  async findById(id) {
+    const rows = await this.adapter.query(
+      `SELECT * FROM ${this.name} WHERE id = ? AND _deleted = 0`,
+      [id]
+    );
+    const row = rows[0];
+    if (!row) return null;
+    return deserializeRecord(row, this.definition.fields);
+  }
+  /**
+   * Update an existing record. Only the provided fields are changed.
+   *
+   * @param id - The record ID to update
+   * @param data - Partial data with only the fields to change
+   * @returns The updated record
+   * @throws {RecordNotFoundError} If the record doesn't exist or is deleted
+   */
+  async update(id, data) {
+    const currentRows = await this.adapter.query(
+      `SELECT * FROM ${this.name} WHERE id = ? AND _deleted = 0`,
+      [id]
+    );
+    const currentRow = currentRows[0];
+    if (!currentRow) {
+      throw new RecordNotFoundError(this.name, id);
+    }
+    const validated = (0, import_core3.validateRecord)(this.name, this.definition, data, "update");
+    const now = Date.now();
+    const previousData = {};
+    const currentRecord = deserializeRecord(currentRow, this.definition.fields);
+    for (const key of Object.keys(validated)) {
+      previousData[key] = currentRecord[key];
+    }
+    const sequenceNumber = this.getSequenceNumber();
+    const operation = await (0, import_core3.createOperation)(
+      {
+        nodeId: this.nodeId,
+        type: "update",
+        collection: this.name,
+        recordId: id,
+        data: { ...validated },
+        previousData,
+        sequenceNumber,
+        causalDeps: [],
+        schemaVersion: this.schema.version
+      },
+      this.clock
+    );
+    const serializedChanges = serializeRecord(validated, this.definition.fields);
+    const updateQuery = buildUpdateQuery(this.name, id, {
+      ...serializedChanges,
+      _updated_at: now
+    });
+    const opRow = serializeOperation(operation);
+    const opInsert = buildInsertQuery(
+      `_kora_ops_${this.name}`,
+      opRow
+    );
+    await this.adapter.transaction(async (tx) => {
+      await tx.execute(updateQuery.sql, updateQuery.params);
+      await tx.execute(opInsert.sql, opInsert.params);
+      await tx.execute(
+        "INSERT OR REPLACE INTO _kora_version_vector (node_id, sequence_number) VALUES (?, ?)",
+        [this.nodeId, sequenceNumber]
+      );
+    });
+    this.onMutation(this.name, operation);
+    const updatedRow = await this.findById(id);
+    if (!updatedRow) {
+      throw new RecordNotFoundError(this.name, id);
+    }
+    return updatedRow;
+  }
+  /**
+   * Soft-delete a record by its ID.
+   *
+   * @param id - The record ID to delete
+   * @throws {RecordNotFoundError} If the record doesn't exist or is already deleted
+   */
+  async delete(id) {
+    const currentRows = await this.adapter.query(
+      `SELECT * FROM ${this.name} WHERE id = ? AND _deleted = 0`,
+      [id]
+    );
+    if (!currentRows[0]) {
+      throw new RecordNotFoundError(this.name, id);
+    }
+    const now = Date.now();
+    const sequenceNumber = this.getSequenceNumber();
+    const operation = await (0, import_core3.createOperation)(
+      {
+        nodeId: this.nodeId,
+        type: "delete",
+        collection: this.name,
+        recordId: id,
+        data: null,
+        previousData: null,
+        sequenceNumber,
+        causalDeps: [],
+        schemaVersion: this.schema.version
+      },
+      this.clock
+    );
+    const deleteQuery = buildSoftDeleteQuery(this.name, id, now);
+    const opRow = serializeOperation(operation);
+    const opInsert = buildInsertQuery(
+      `_kora_ops_${this.name}`,
+      opRow
+    );
+    await this.adapter.transaction(async (tx) => {
+      await tx.execute(deleteQuery.sql, deleteQuery.params);
+      await tx.execute(opInsert.sql, opInsert.params);
+      await tx.execute(
+        "INSERT OR REPLACE INTO _kora_version_vector (node_id, sequence_number) VALUES (?, ?)",
+        [this.nodeId, sequenceNumber]
+      );
+    });
+    this.onMutation(this.name, operation);
+  }
+  /** Get the collection name */
+  getName() {
+    return this.name;
+  }
+  /** Get the collection definition */
+  getDefinition() {
+    return this.definition;
+  }
+};
+
+// src/query/pluralize.ts
+function isVowel(char) {
+  if (!char) return false;
+  return "aeiouAEIOU".includes(char);
+}
+function pluralize(word) {
+  if (word.endsWith("s")) return word;
+  if (word.endsWith("y") && !isVowel(word[word.length - 2])) {
+    return `${word.slice(0, -1)}ies`;
+  }
+  if (word.endsWith("sh") || word.endsWith("ch") || word.endsWith("x") || word.endsWith("z")) {
+    return `${word}es`;
+  }
+  return `${word}s`;
+}
+function singularize(word) {
+  if (word.endsWith("ies") && !isVowel(word[word.length - 4])) {
+    return `${word.slice(0, -3)}y`;
+  }
+  if (word.endsWith("shes") || word.endsWith("ches") || word.endsWith("xes") || word.endsWith("zes")) {
+    return word.slice(0, -2);
+  }
+  if (word.endsWith("ses")) {
+    return word.slice(0, -2);
+  }
+  if (word.endsWith("s") && !word.endsWith("ss")) {
+    return word.slice(0, -1);
+  }
+  return word;
+}
+
+// src/query/query-builder.ts
+var QueryBuilder = class _QueryBuilder {
+  constructor(collectionName, definition, adapter, subscriptionManager, initialWhere = {}, schema) {
+    this.collectionName = collectionName;
+    this.definition = definition;
+    this.adapter = adapter;
+    this.subscriptionManager = subscriptionManager;
+    this.schema = schema;
+    this.descriptor = {
+      collection: collectionName,
+      where: { ...initialWhere },
+      orderBy: []
+    };
+  }
+  collectionName;
+  definition;
+  adapter;
+  subscriptionManager;
+  schema;
+  descriptor;
+  /**
+   * Add WHERE conditions (AND semantics, merged with existing conditions).
+   */
+  where(conditions) {
+    const clone = this.clone();
+    clone.descriptor = {
+      ...clone.descriptor,
+      where: { ...clone.descriptor.where, ...conditions }
+    };
+    return clone;
+  }
+  /**
+   * Add ORDER BY clause.
+   */
+  orderBy(field, direction = "asc") {
+    const clone = this.clone();
+    clone.descriptor = {
+      ...clone.descriptor,
+      orderBy: [...clone.descriptor.orderBy, { field, direction }]
+    };
+    return clone;
+  }
+  /**
+   * Set result limit.
+   */
+  limit(n) {
+    const clone = this.clone();
+    clone.descriptor = { ...clone.descriptor, limit: n };
+    return clone;
+  }
+  /**
+   * Set result offset.
+   */
+  offset(n) {
+    const clone = this.clone();
+    clone.descriptor = { ...clone.descriptor, offset: n };
+    return clone;
+  }
+  /**
+   * Include related records in the query results.
+   * Follows relations defined in the schema to batch-fetch related data.
+   *
+   * @param targets - Relation target names (collection names or relation names)
+   * @returns A new QueryBuilder with include targets added
+   *
+   * @example
+   * ```typescript
+   * const todosWithProject = await app.todos
+   *   .where({ completed: false })
+   *   .include('project')
+   *   .exec()
+   * ```
+   */
+  include(...targets) {
+    const clone = this.clone();
+    const existing = clone.descriptor.include ?? [];
+    clone.descriptor = {
+      ...clone.descriptor,
+      include: [...existing, ...targets]
+    };
+    return clone;
+  }
+  /**
+   * Execute the query and return results.
+   */
+  async exec() {
+    const { sql, params } = buildSelectQuery(this.descriptor, this.definition.fields);
+    const rows = await this.adapter.query(sql, params);
+    const records = rows.map((row) => deserializeRecord(row, this.definition.fields));
+    if (this.descriptor.include && this.descriptor.include.length > 0 && this.schema) {
+      await this.resolveIncludes(records);
+    }
+    return records;
+  }
+  /**
+   * Execute a COUNT query and return the count.
+   */
+  async count() {
+    const { sql, params } = buildCountQuery(this.descriptor, this.definition.fields);
+    const rows = await this.adapter.query(sql, params);
+    return rows[0]?.count ?? 0;
+  }
+  /**
+   * Subscribe to query results. Callback is called immediately with current results,
+   * then again whenever the results change due to mutations.
+   *
+   * @returns An unsubscribe function
+   */
+  subscribe(callback) {
+    const executeFn = () => this.exec();
+    const descriptorCopy = { ...this.descriptor };
+    if (descriptorCopy.include && descriptorCopy.include.length > 0 && this.schema) {
+      descriptorCopy.includeCollections = this.resolveIncludeCollections(descriptorCopy.include);
+    }
+    return this.subscriptionManager.registerAndFetch(
+      descriptorCopy,
+      callback,
+      executeFn
+    );
+  }
+  /** Get the internal descriptor (for testing/debugging) */
+  getDescriptor() {
+    return { ...this.descriptor };
+  }
+  clone() {
+    const qb = new _QueryBuilder(
+      this.collectionName,
+      this.definition,
+      this.adapter,
+      this.subscriptionManager,
+      {},
+      this.schema
+    );
+    qb.descriptor = {
+      ...this.descriptor,
+      where: { ...this.descriptor.where },
+      orderBy: [...this.descriptor.orderBy],
+      include: this.descriptor.include ? [...this.descriptor.include] : void 0,
+      includeCollections: this.descriptor.includeCollections ? [...this.descriptor.includeCollections] : void 0
+    };
+    return qb;
+  }
+  /**
+   * Resolve include targets to their actual collection names for subscription tracking.
+   */
+  resolveIncludeCollections(targets) {
+    if (!this.schema) return [];
+    const collections = [];
+    for (const target of targets) {
+      const relation = this.findRelation(target);
+      if (relation) {
+        if (relation.from === this.collectionName) {
+          collections.push(relation.to);
+        } else {
+          collections.push(relation.from);
+        }
+      }
+    }
+    return collections;
+  }
+  /**
+   * Resolve includes after primary query, batch-fetching related records.
+   */
+  async resolveIncludes(records) {
+    if (!this.schema || !this.descriptor.include || records.length === 0) return;
+    for (const target of this.descriptor.include) {
+      const relation = this.findRelation(target);
+      if (!relation) {
+        throw new QueryError2(
+          `No relation found for include target "${target}" on collection "${this.collectionName}". Check that a relation is defined in your schema that connects "${this.collectionName}" to "${target}".`
+        );
+      }
+      if (relation.from === this.collectionName) {
+        await this.resolveManyToOneInclude(records, relation, target);
+      } else {
+        await this.resolveOneToManyInclude(records, relation, target);
+      }
+    }
+  }
+  /**
+   * Many-to-one: collect FK values from primary results, batch-fetch related, attach as singular.
+   */
+  async resolveManyToOneInclude(records, relation, target) {
+    const fkField = relation.field;
+    const fkValues = records.map((r) => r[fkField]).filter((v) => v !== null && v !== void 0 && typeof v === "string");
+    if (fkValues.length === 0) {
+      const propName2 = singularize(target);
+      for (const record of records) {
+        ;
+        record[propName2] = null;
+      }
+      return;
+    }
+    const uniqueFks = [...new Set(fkValues)];
+    const relatedCollection = relation.to;
+    const relatedDef = this.schema?.collections[relatedCollection];
+    if (!relatedDef) return;
+    const placeholders = uniqueFks.map(() => "?").join(", ");
+    const sql = `SELECT * FROM ${relatedCollection} WHERE id IN (${placeholders}) AND _deleted = 0`;
+    const rows = await this.adapter.query(sql, uniqueFks);
+    const relatedRecords = rows.map((row) => deserializeRecord(row, relatedDef.fields));
+    const lookup = /* @__PURE__ */ new Map();
+    for (const r of relatedRecords) {
+      lookup.set(r.id, r);
+    }
+    const propName = singularize(target);
+    for (const record of records) {
+      const fk = record[fkField];
+      record[propName] = fk ? lookup.get(fk) ?? null : null;
+    }
+  }
+  /**
+   * One-to-many: collect primary IDs, batch-fetch children, attach as array.
+   */
+  async resolveOneToManyInclude(records, relation, target) {
+    const primaryIds = records.map((r) => r.id);
+    const relatedCollection = relation.from;
+    const relatedDef = this.schema?.collections[relatedCollection];
+    if (!relatedDef) return;
+    const fkField = relation.field;
+    const placeholders = primaryIds.map(() => "?").join(", ");
+    const sql = `SELECT * FROM ${relatedCollection} WHERE ${fkField} IN (${placeholders}) AND _deleted = 0`;
+    const rows = await this.adapter.query(sql, primaryIds);
+    const relatedRecords = rows.map((row) => deserializeRecord(row, relatedDef.fields));
+    const grouped = /* @__PURE__ */ new Map();
+    for (const r of relatedRecords) {
+      const fk = r[fkField];
+      if (!grouped.has(fk)) {
+        grouped.set(fk, []);
+      }
+      grouped.get(fk)?.push(r);
+    }
+    const propName = pluralize(target);
+    for (const record of records) {
+      ;
+      record[propName] = grouped.get(record.id) ?? [];
+    }
+  }
+  /**
+   * Find a relation definition matching the include target.
+   * Searches by relation name, target collection name, and singularized/pluralized variants.
+   */
+  findRelation(target) {
+    if (!this.schema) return null;
+    for (const [_name, rel] of Object.entries(this.schema.relations)) {
+      if (rel.from === this.collectionName && rel.to === target) return rel;
+      if (rel.to === this.collectionName && rel.from === target) return rel;
+      if (rel.from === this.collectionName && rel.to === pluralize(target)) return rel;
+      if (rel.to === this.collectionName && rel.from === pluralize(target)) return rel;
+      if (rel.from === this.collectionName && rel.to === singularize(target)) return rel;
+      if (rel.to === this.collectionName && rel.from === singularize(target)) return rel;
+    }
+    return null;
+  }
+};
+var QueryError2 = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "QueryError";
+  }
+};
+
+// src/subscription/subscription-manager.ts
+var nextSubId = 0;
+var SubscriptionManager = class {
+  subscriptions = /* @__PURE__ */ new Map();
+  pendingCollections = /* @__PURE__ */ new Set();
+  flushScheduled = false;
+  /**
+   * Register a new subscription.
+   *
+   * @param descriptor - The query descriptor defining what this subscription watches
+   * @param callback - Called with results whenever they change
+   * @param executeFn - Function to re-execute the query and get current results
+   * @returns An unsubscribe function
+   */
+  register(descriptor, callback, executeFn) {
+    const id = `sub_${++nextSubId}`;
+    const subscription = {
+      id,
+      descriptor,
+      callback,
+      executeFn,
+      lastResults: []
+    };
+    this.subscriptions.set(id, subscription);
+    return () => {
+      this.subscriptions.delete(id);
+    };
+  }
+  /**
+   * Register a subscription and immediately execute the query.
+   * The initial results are stored as lastResults so subsequent flushes
+   * correctly diff against the initial state.
+   *
+   * @returns An unsubscribe function
+   */
+  registerAndFetch(descriptor, callback, executeFn) {
+    const id = `sub_${++nextSubId}`;
+    const subscription = {
+      id,
+      descriptor,
+      callback,
+      executeFn,
+      lastResults: []
+    };
+    this.subscriptions.set(id, subscription);
+    executeFn().then((results) => {
+      if (this.subscriptions.has(id)) {
+        subscription.lastResults = results;
+        callback(results);
+      }
+    });
+    return () => {
+      this.subscriptions.delete(id);
+    };
+  }
+  /**
+   * Notify the manager that a mutation occurred on a collection.
+   * Schedules a microtask flush to batch multiple mutations in the same tick.
+   */
+  notify(collection, _operation) {
+    this.pendingCollections.add(collection);
+    this.scheduleFlush();
+  }
+  /**
+   * Immediately flush all pending notifications.
+   * Useful for testing. In production, flushing happens via microtask.
+   */
+  async flush() {
+    if (this.pendingCollections.size === 0) return;
+    const collections = new Set(this.pendingCollections);
+    this.pendingCollections.clear();
+    this.flushScheduled = false;
+    const affected = [];
+    for (const sub of this.subscriptions.values()) {
+      if (collections.has(sub.descriptor.collection)) {
+        affected.push(sub);
+      } else if (sub.descriptor.includeCollections) {
+        for (const incCol of sub.descriptor.includeCollections) {
+          if (collections.has(incCol)) {
+            affected.push(sub);
+            break;
+          }
+        }
+      }
+    }
+    for (const sub of affected) {
+      try {
+        const newResults = await sub.executeFn();
+        if (!this.resultsEqual(sub.lastResults, newResults)) {
+          sub.lastResults = newResults;
+          sub.callback(newResults);
+        }
+      } catch {
+      }
+    }
+  }
+  /**
+   * Remove all subscriptions. Called on store close.
+   */
+  clear() {
+    this.subscriptions.clear();
+    this.pendingCollections.clear();
+    this.flushScheduled = false;
+  }
+  /** Number of active subscriptions (for testing/debugging) */
+  get size() {
+    return this.subscriptions.size;
+  }
+  scheduleFlush() {
+    if (this.flushScheduled) return;
+    this.flushScheduled = true;
+    queueMicrotask(() => {
+      this.flush();
+    });
+  }
+  /**
+   * Compare two result sets. Uses length check + JSON comparison as pragmatic approach.
+   * Sufficient for typical query results. Can be optimized to id-based diffing if profiling shows need.
+   */
+  resultsEqual(prev, next) {
+    if (prev.length !== next.length) return false;
+    if (prev.length === 0) return true;
+    return JSON.stringify(prev) === JSON.stringify(next);
+  }
+};
+
+// src/store/store.ts
+var Store = class {
+  opened = false;
+  nodeId = "";
+  sequenceNumber = 0;
+  versionVector = (0, import_core4.createVersionVector)();
+  clock = null;
+  collections = /* @__PURE__ */ new Map();
+  subscriptionManager = new SubscriptionManager();
+  schema;
+  adapter;
+  configNodeId;
+  emitter;
+  constructor(config) {
+    this.schema = config.schema;
+    this.adapter = config.adapter;
+    this.configNodeId = config.nodeId;
+    this.emitter = config.emitter ?? null;
+  }
+  /**
+   * Open the store: initialize the database, load or generate a node ID,
+   * restore the sequence number and version vector, and create Collection instances.
+   */
+  async open() {
+    await this.adapter.open(this.schema);
+    this.nodeId = await this.loadOrGenerateNodeId();
+    this.clock = new import_core4.HybridLogicalClock(this.nodeId);
+    this.sequenceNumber = await this.loadSequenceNumber();
+    this.versionVector = await this.loadVersionVector();
+    for (const [name, definition] of Object.entries(this.schema.collections)) {
+      const col = new Collection(
+        name,
+        definition,
+        this.schema,
+        this.adapter,
+        this.clock,
+        this.nodeId,
+        () => this.nextSequenceNumber(),
+        (collectionName, operation) => {
+          this.subscriptionManager.notify(collectionName, operation);
+          if (this.emitter) {
+            this.emitter.emit({ type: "operation:created", operation });
+          }
+        }
+      );
+      this.collections.set(name, col);
+    }
+    this.opened = true;
+  }
+  /**
+   * Close the store: clear subscriptions and close the adapter.
+   */
+  async close() {
+    this.subscriptionManager.clear();
+    this.collections.clear();
+    this.opened = false;
+    await this.adapter.close();
+  }
+  /**
+   * Get a Collection instance for CRUD operations.
+   * @throws {StoreNotOpenError} If the store is not open
+   * @throws {Error} If the collection name is not in the schema
+   */
+  collection(name) {
+    this.ensureOpen();
+    const col = this.collections.get(name);
+    if (!col) {
+      throw new Error(
+        `Unknown collection "${name}". Available: ${[...this.collections.keys()].join(", ")}`
+      );
+    }
+    const definition = this.schema.collections[name];
+    if (!definition) {
+      throw new Error(`Collection definition not found for "${name}"`);
+    }
+    return {
+      insert: (data) => col.insert(data),
+      findById: (id) => col.findById(id),
+      update: (id, data) => col.update(id, data),
+      delete: (id) => col.delete(id),
+      where: (conditions) => new QueryBuilder(name, definition, this.adapter, this.subscriptionManager, conditions, this.schema)
+    };
+  }
+  /**
+   * Get the current version vector.
+   */
+  getVersionVector() {
+    this.ensureOpen();
+    return new Map(this.versionVector);
+  }
+  /**
+   * Get the node ID for this store instance.
+   */
+  getNodeId() {
+    this.ensureOpen();
+    return this.nodeId;
+  }
+  /**
+   * Apply a remote operation received from sync.
+   * Checks for duplicates, applies to the data table, persists the operation,
+   * and updates the version vector.
+   */
+  async applyRemoteOperation(op) {
+    this.ensureOpen();
+    const collection = op.collection;
+    const definition = this.schema.collections[collection];
+    if (!definition) {
+      return "skipped";
+    }
+    const existing = await this.adapter.query(
+      `SELECT id FROM _kora_ops_${collection} WHERE id = ?`,
+      [op.id]
+    );
+    if (existing.length > 0) {
+      return "duplicate";
+    }
+    if (this.clock) {
+      this.clock.receive(op.timestamp);
+    }
+    await this.adapter.transaction(async (tx) => {
+      if (op.type === "insert" && op.data) {
+        const serializedData = serializeRecord(op.data, definition.fields);
+        const now = op.timestamp.wallTime;
+        const record = {
+          id: op.recordId,
+          ...serializedData,
+          _created_at: now,
+          _updated_at: now
+        };
+        const insertQuery = buildInsertQuery(collection, record);
+        await tx.execute(insertQuery.sql, insertQuery.params);
+      } else if (op.type === "update" && op.data) {
+        const serializedChanges = serializeRecord(op.data, definition.fields);
+        const updateQuery = buildUpdateQuery(collection, op.recordId, {
+          ...serializedChanges,
+          _updated_at: op.timestamp.wallTime
+        });
+        await tx.execute(updateQuery.sql, updateQuery.params);
+      } else if (op.type === "delete") {
+        const deleteQuery = buildSoftDeleteQuery(collection, op.recordId, op.timestamp.wallTime);
+        await tx.execute(deleteQuery.sql, deleteQuery.params);
+      }
+      const opRow = serializeOperation(op);
+      const opInsert = buildInsertQuery(
+        `_kora_ops_${collection}`,
+        opRow
+      );
+      await tx.execute(opInsert.sql, opInsert.params);
+      const currentSeq = this.versionVector.get(op.nodeId) ?? 0;
+      if (op.sequenceNumber > currentSeq) {
+        this.versionVector.set(op.nodeId, op.sequenceNumber);
+        await tx.execute(
+          "INSERT OR REPLACE INTO _kora_version_vector (node_id, sequence_number) VALUES (?, ?)",
+          [op.nodeId, op.sequenceNumber]
+        );
+      }
+    });
+    this.subscriptionManager.notify(collection, op);
+    return "applied";
+  }
+  /**
+   * Get operations from a node within a sequence number range.
+   * Implements the OperationLog interface for computeDelta.
+   */
+  getRange(nodeId, fromSeq, toSeq) {
+    return [];
+  }
+  /**
+   * Async version of getRange for use by the sync layer.
+   */
+  async getOperationRange(nodeId, fromSeq, toSeq) {
+    this.ensureOpen();
+    const allOps = [];
+    for (const collectionName of Object.keys(this.schema.collections)) {
+      const rows = await this.adapter.query(
+        `SELECT * FROM _kora_ops_${collectionName} WHERE node_id = ? AND sequence_number >= ? AND sequence_number <= ? ORDER BY sequence_number ASC`,
+        [nodeId, fromSeq, toSeq]
+      );
+      for (const row of rows) {
+        allOps.push(deserializeOperationWithCollection(row, collectionName));
+      }
+    }
+    allOps.sort((a, b) => a.sequenceNumber - b.sequenceNumber);
+    return allOps;
+  }
+  /**
+   * Get the schema definition.
+   */
+  getSchema() {
+    return this.schema;
+  }
+  /** Expose the subscription manager for direct access (e.g., by QueryBuilder) */
+  getSubscriptionManager() {
+    return this.subscriptionManager;
+  }
+  nextSequenceNumber() {
+    this.sequenceNumber++;
+    this.versionVector.set(this.nodeId, this.sequenceNumber);
+    return this.sequenceNumber;
+  }
+  async loadOrGenerateNodeId() {
+    if (this.configNodeId) {
+      await this.adapter.execute(
+        "INSERT OR REPLACE INTO _kora_meta (key, value) VALUES ('node_id', ?)",
+        [this.configNodeId]
+      );
+      return this.configNodeId;
+    }
+    const rows = await this.adapter.query(
+      "SELECT value FROM _kora_meta WHERE key = 'node_id'"
+    );
+    if (rows[0]) {
+      return rows[0].value;
+    }
+    const newNodeId = (0, import_core4.generateUUIDv7)();
+    await this.adapter.execute("INSERT INTO _kora_meta (key, value) VALUES ('node_id', ?)", [
+      newNodeId
+    ]);
+    return newNodeId;
+  }
+  async loadSequenceNumber() {
+    const rows = await this.adapter.query(
+      "SELECT sequence_number FROM _kora_version_vector WHERE node_id = ?",
+      [this.nodeId]
+    );
+    return rows[0]?.sequence_number ?? 0;
+  }
+  async loadVersionVector() {
+    const rows = await this.adapter.query(
+      "SELECT node_id, sequence_number FROM _kora_version_vector"
+    );
+    const vector = (0, import_core4.createVersionVector)();
+    for (const row of rows) {
+      vector.set(row.node_id, row.sequence_number);
+    }
+    return vector;
+  }
+  ensureOpen() {
+    if (!this.opened) {
+      throw new StoreNotOpenError();
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AdapterError,
+  Collection,
+  PersistenceError,
+  QueryBuilder,
+  QueryError,
+  RecordNotFoundError,
+  Store,
+  StoreNotOpenError,
+  SubscriptionManager,
+  WorkerInitError,
+  WorkerTimeoutError,
+  decodeRichtext,
+  encodeRichtext,
+  pluralize,
+  richtextToPlainText,
+  singularize
+});
+//# sourceMappingURL=index.cjs.map