@monlite/core 0.3.0 → 0.5.0

package/dist/index.cjs

@@ -39,6 +39,9 @@ var RESERVED_FIELDS = /* @__PURE__ */ new Set(["_id", "created_at", "updated_at"
 function isReserved(field) {
   return RESERVED_FIELDS.has(field);
 }
+function isColumn(field, columns) {
+  return isReserved(field) || (columns?.has(field) ?? false);
+}
 function jsonPath(field) {
   let path = "$";
   for (const seg of field.split(".")) {
@@ -55,8 +58,8 @@ function jsonPath(field) {
 function pathLiteral(field) {
   return "'" + jsonPath(field).replace(/'/g, "''") + "'";
 }
-function fieldExpr(field) {
-  if (isReserved(field)) return `"${field}"`;
+function fieldExpr(field, columns) {
+  if (isColumn(field, columns)) return `"${field}"`;
   return `json_extract(data, ${pathLiteral(field)})`;
 }
 function bindable(value) {
@@ -103,8 +106,8 @@ function isFilterObject(v) {
   return v !== null && typeof v === "object" && !Array.isArray(v) && !(v instanceof Date) && !Buffer.isBuffer(v) && (v.constructor === Object || v.constructor === void 0);
 }
 function translateField(field, condition, ctx) {
-  if (ctx.onPath && !isReserved(field)) ctx.onPath(field);
-  const expr = fieldExpr(field);
+  if (ctx.onPath && !isColumn(field, ctx.columns)) ctx.onPath(field);
+  const expr = fieldExpr(field, ctx.columns);
   if (!isFilterObject(condition)) {
     return eqExpr(expr, condition, ctx);
   }
@@ -154,7 +157,7 @@ function translateField(field, condition, ctx) {
         clauses.push(hasExpr(field, expr, v, ctx));
         break;
       case "exists":
-        clauses.push(existsExpr(field, expr, !!v));
+        clauses.push(existsExpr(field, expr, !!v, ctx.columns));
         break;
       default:
         throw new MonliteQueryError(
@@ -193,7 +196,7 @@ function inExpr(expr, arr, ctx, negate) {
   return negate ? `(${expr} IS NULL OR ${expr} NOT IN (${placeholders}))` : `${expr} IN (${placeholders})`;
 }
 function containsExpr(field, expr, v, ctx) {
-  if (isReserved(field)) {
+  if (isColumn(field, ctx.columns)) {
     ctx.params.push(bindable(v));
     return `instr(${expr}, ?) > 0`;
   }
@@ -204,11 +207,11 @@ function containsExpr(field, expr, v, ctx) {
 }
 function hasExpr(field, expr, v, ctx) {
   ctx.params.push(bindable(v));
-  if (isReserved(field)) return `${expr} = ?`;
+  if (isColumn(field, ctx.columns)) return `${expr} = ?`;
   return `EXISTS (SELECT 1 FROM json_each(data, ${pathLiteral(field)}) WHERE value = ?)`;
 }
-function existsExpr(field, expr, want) {
-  if (isReserved(field)) {
+function existsExpr(field, expr, want, columns) {
+  if (isColumn(field, columns)) {
     return want ? `${expr} IS NOT NULL` : `${expr} IS NULL`;
   }
   const path = pathLiteral(field);
@@ -216,7 +219,7 @@ function existsExpr(field, expr, want) {
 }
 
 // src/query/order.ts
-function buildOrderBy(orderBy, onPath) {
+function buildOrderBy(orderBy, onPath, columns) {
   if (!orderBy) return "";
   const list = Array.isArray(orderBy) ? orderBy : [orderBy];
   const parts = [];
@@ -224,9 +227,9 @@ function buildOrderBy(orderBy, onPath) {
     for (const field of Object.keys(obj)) {
       const dir = obj[field];
       if (dir === void 0) continue;
-      if (onPath && !isReserved(field)) onPath(field);
+      if (onPath && !isColumn(field, columns)) onPath(field);
       const d = String(dir).toLowerCase() === "desc" ? "DESC" : "ASC";
-      parts.push(`${fieldExpr(field)} ${d}`);
+      parts.push(`${fieldExpr(field, columns)} ${d}`);
     }
   }
   return parts.length ? "ORDER BY " + parts.join(", ") : "";
@@ -347,7 +350,7 @@ var SQL_FN = {
   _min: "MIN",
   _max: "MAX"
 };
-function buildAccumulators(args, onPath) {
+function buildAccumulators(args, onPath, columns) {
   const selects = [];
   const cols = [];
   let i = 0;
@@ -356,9 +359,9 @@ function buildAccumulators(args, onPath) {
     if (!selection) continue;
     for (const field of Object.keys(selection)) {
       if (!selection[field]) continue;
-      onPath(field);
+      if (!isColumn(field, columns)) onPath(field);
       const alias = `agg_${kind.slice(1)}_${i++}`;
-      selects.push(`${SQL_FN[kind]}(${fieldExpr(field)}) AS ${alias}`);
+      selects.push(`${SQL_FN[kind]}(${fieldExpr(field, columns)}) AS ${alias}`);
       cols.push({ alias, kind, field });
     }
   }
@@ -366,8 +369,12 @@ function buildAccumulators(args, onPath) {
 }
 function aggregate(ctx, args) {
   const params = [];
-  const where = buildWhere(args.where, { params, onPath: ctx.onPath });
-  const { selects, cols } = buildAccumulators(args, ctx.onPath);
+  const where = buildWhere(args.where, {
+    params,
+    onPath: ctx.onPath,
+    columns: ctx.columns
+  });
+  const { selects, cols } = buildAccumulators(args, ctx.onPath, ctx.columns);
   const allSelects = [`COUNT(*) AS agg_count`, ...selects];
   const sql = `SELECT ${allSelects.join(", ")} FROM "${ctx.table}" WHERE ${where}`;
   const row = ctx.db.prepare(sql).get(...params) ?? {};
@@ -403,7 +410,7 @@ function comparisonSql(expr, cmp2, params) {
   }
   return out;
 }
-function buildHaving(having, params) {
+function buildHaving(having, params, columns) {
   const parts = [];
   if (having._count) {
     parts.push(...comparisonSql("COUNT(*)", having._count, params));
@@ -412,7 +419,9 @@ function buildHaving(having, params) {
     const selection = having[kind];
     if (!selection) continue;
     for (const field of Object.keys(selection)) {
-      parts.push(...comparisonSql(`${fn}(${fieldExpr(field)})`, selection[field], params));
+      parts.push(
+        ...comparisonSql(`${fn}(${fieldExpr(field, columns)})`, selection[field], params)
+      );
     }
   }
   return parts.join(" AND ");
@@ -422,21 +431,25 @@ function groupBy(ctx, args) {
     throw new Error("groupBy requires a non-empty `by` array");
   }
   const params = [];
-  const where = buildWhere(args.where, { params, onPath: ctx.onPath });
+  const where = buildWhere(args.where, {
+    params,
+    onPath: ctx.onPath,
+    columns: ctx.columns
+  });
   const groupExprs = [];
   const selects = [];
   for (const field of args.by) {
-    ctx.onPath(field);
-    const expr = fieldExpr(field);
+    if (!isColumn(field, ctx.columns)) ctx.onPath(field);
+    const expr = fieldExpr(field, ctx.columns);
     groupExprs.push(expr);
     selects.push(`${expr} AS "${field}"`);
   }
   selects.push(`COUNT(*) AS agg_count`);
-  const { selects: accSelects, cols } = buildAccumulators(args, ctx.onPath);
+  const { selects: accSelects, cols } = buildAccumulators(args, ctx.onPath, ctx.columns);
   selects.push(...accSelects);
   let sql = `SELECT ${selects.join(", ")} FROM "${ctx.table}" WHERE ${where} GROUP BY ${groupExprs.join(", ")}`;
   if (args.having) {
-    const havingSql = buildHaving(args.having, params);
+    const havingSql = buildHaving(args.having, params, ctx.columns);
     if (havingSql) sql += ` HAVING ${havingSql}`;
   }
   if (args.orderBy) {
@@ -444,7 +457,7 @@ function groupBy(ctx, args) {
     for (const key of Object.keys(args.orderBy)) {
       const dir = String(args.orderBy[key]).toLowerCase() === "desc" ? "DESC" : "ASC";
       if (key === "_count") parts.push(`agg_count ${dir}`);
-      else parts.push(`${fieldExpr(key)} ${dir}`);
+      else parts.push(`${fieldExpr(key, ctx.columns)} ${dir}`);
     }
     if (parts.length) sql += ` ORDER BY ${parts.join(", ")}`;
   }
@@ -469,71 +482,216 @@ function groupBy(ctx, args) {
 }
 
 // src/collection.ts
-var SELECT_COLS = `_id, data, created_at, updated_at`;
 function stripSystem(obj) {
   const { _id, created_at, updated_at, ...rest } = obj;
   return rest;
 }
+var NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function sqliteType(type) {
+  return type === "JSON" ? "TEXT" : type;
+}
+function formatDefault(value) {
+  if (value === null) return "NULL";
+  if (typeof value === "number") return String(value);
+  return `'${String(value).replace(/'/g, "''")}'`;
+}
 var Collection = class {
-  constructor(mon, name) {
+  constructor(mon, name, options = {}) {
     this.mon = mon;
     this.name = name;
+    this.mode = options.schema ? "structured" : "document";
+    if (options.schema) {
+      for (const [field, def] of Object.entries(options.schema)) {
+        if (!NAME_RE.test(field)) {
+          throw new MonliteError(`Invalid column name "${field}"`);
+        }
+        if (RESERVED_FIELDS.has(field) || field === "data") {
+          throw new MonliteError(
+            `Column "${field}" is reserved by monlite and cannot be declared`
+          );
+        }
+        const normalized = typeof def === "string" ? { type: def } : def;
+        this.columnDefs[field] = normalized;
+        this.columnOrder.push(field);
+        this.columns.add(field);
+        if (normalized.type === "JSON") this.jsonColumns.add(field);
+      }
+    }
   }
   mon;
   name;
+  mode;
   initialized = false;
+  columnDefs = {};
+  columnOrder = [];
+  /** Declared native columns (empty in document mode). */
+  columns = /* @__PURE__ */ new Set();
+  jsonColumns = /* @__PURE__ */ new Set();
+  insertSqlCache;
   trackPath = (path) => this.mon.autoIndexer.track(this.name, path);
   get db() {
     return this.mon.driver;
   }
+  /** Native column names declared for this collection (structured mode). */
+  get columnNames() {
+    return [...this.columnOrder];
+  }
   ensureTable() {
     if (this.initialized) return;
-    this.db.exec(
-      `CREATE TABLE IF NOT EXISTS "${this.name}" (
-        _id        TEXT    PRIMARY KEY,
-        data       TEXT    NOT NULL,
-        created_at INTEGER NOT NULL,
-        updated_at INTEGER NOT NULL
-      )`
-    );
+    if (this.mode === "document") {
+      this.db.exec(
+        `CREATE TABLE IF NOT EXISTS "${this.name}" (
+          _id        TEXT    PRIMARY KEY,
+          data       TEXT    NOT NULL,
+          created_at INTEGER NOT NULL,
+          updated_at INTEGER NOT NULL
+        )`
+      );
+    } else {
+      const lines = [
+        `_id        TEXT    PRIMARY KEY`,
+        `created_at INTEGER NOT NULL`,
+        `updated_at INTEGER NOT NULL`,
+        `data       TEXT    NOT NULL DEFAULT '{}'`
+      ];
+      for (const field of this.columnOrder) {
+        const def = this.columnDefs[field];
+        let line = `"${field}" ${sqliteType(def.type)}`;
+        if (def.notNull) line += " NOT NULL";
+        if (def.unique) line += " UNIQUE";
+        if (def.default !== void 0) line += ` DEFAULT ${formatDefault(def.default)}`;
+        if (def.references) line += ` REFERENCES ${def.references}`;
+        lines.push(line);
+      }
+      this.db.exec(
+        `CREATE TABLE IF NOT EXISTS "${this.name}" (
+  ${lines.join(",\n  ")}
+)`
+      );
+      for (const field of this.columnOrder) {
+        if (this.columnDefs[field].index) {
+          this.db.exec(
+            `CREATE INDEX IF NOT EXISTS "idx_${this.name}_${field}" ON "${this.name}"("${field}")`
+          );
+        }
+      }
+    }
     this.initialized = true;
   }
+  /* --------------------------- row <-> doc -------------------------- */
   rowToDoc(row) {
-    const doc = JSON.parse(row.data);
+    const doc = this.mode === "document" ? JSON.parse(row.data) : JSON.parse(row.data ?? "{}");
+    if (this.mode === "structured") {
+      for (const field of this.columnOrder) {
+        const value = row[field];
+        if (value === null || value === void 0) continue;
+        doc[field] = this.jsonColumns.has(field) ? JSON.parse(value) : value;
+      }
+    }
     doc._id = row._id;
     doc.created_at = row.created_at;
     doc.updated_at = row.updated_at;
     return doc;
   }
-  prepareInsert(input) {
+  encodeColumn(field, value) {
+    if (this.jsonColumns.has(field)) {
+      return value === void 0 ? null : JSON.stringify(value);
+    }
+    return bindable(value);
+  }
+  insertColumns() {
+    return this.mode === "document" ? ["_id", "data", "created_at", "updated_at"] : ["_id", "created_at", "updated_at", "data", ...this.columnOrder];
+  }
+  insertSql() {
+    if (this.insertSqlCache) return this.insertSqlCache;
+    const cols = this.insertColumns();
+    const list = cols.map((c) => `"${c}"`).join(", ");
+    const placeholders = cols.map(() => "?").join(", ");
+    return this.insertSqlCache = `INSERT INTO "${this.name}" (${list}) VALUES (${placeholders})`;
+  }
+  /** Split an input document into a row aligned with `insertColumns()`. */
+  buildInsert(input) {
     const now = Date.now();
     const id = input._id != null ? String(input._id) : objectId();
     const doc = stripSystem(input);
-    return {
-      _id: id,
-      data: JSON.stringify(doc),
-      created_at: now,
-      updated_at: now
-    };
+    const returned = { ...doc, _id: id, created_at: now, updated_at: now };
+    if (this.mode === "document") {
+      return {
+        _id: id,
+        created_at: now,
+        updated_at: now,
+        values: [id, JSON.stringify(doc), now, now],
+        returned
+      };
+    }
+    const overflow = {};
+    const colValues = {};
+    for (const [k, v] of Object.entries(doc)) {
+      if (this.columns.has(k)) colValues[k] = v;
+      else overflow[k] = v;
+    }
+    const values = [
+      id,
+      now,
+      now,
+      JSON.stringify(overflow),
+      ...this.columnOrder.map(
+        (c) => c in colValues ? this.encodeColumn(c, colValues[c]) : null
+      )
+    ];
+    return { _id: id, created_at: now, updated_at: now, values, returned };
+  }
+  /** Build the `SET` clause + values to persist an updated document. */
+  buildUpdateSet(updatedDoc, now) {
+    if (this.mode === "document") {
+      return {
+        setSql: `data = ?, updated_at = ?`,
+        values: [JSON.stringify(updatedDoc), now]
+      };
+    }
+    const overflow = {};
+    const colValues = {};
+    for (const [k, v] of Object.entries(updatedDoc)) {
+      if (this.columns.has(k)) colValues[k] = v;
+      else overflow[k] = v;
+    }
+    const setParts = this.columnOrder.map((c) => `"${c}" = ?`);
+    setParts.push(`data = ?`, `updated_at = ?`);
+    const values = [
+      ...this.columnOrder.map(
+        (c) => c in colValues ? this.encodeColumn(c, colValues[c]) : null
+      ),
+      JSON.stringify(overflow),
+      now
+    ];
+    return { setSql: setParts.join(", "), values };
+  }
+  /** Sync store, but only for document collections (structured sync is future work). */
+  get recorder() {
+    return this.mode === "document" ? this.mon.$sync : void 0;
   }
   /* ----------------------------- create ----------------------------- */
   async create(args) {
     this.ensureTable();
-    const row = this.prepareInsert(args.data);
-    this.db.prepare(
-      `INSERT INTO "${this.name}" (_id, data, created_at, updated_at) VALUES (?, ?, ?, ?)`
-    ).run(row._id, row.data, row.created_at, row.updated_at);
-    return this.rowToDoc(row);
+    const row = this.buildInsert(args.data);
+    const recorder = this.recorder;
+    const write = () => {
+      this.db.prepare(this.insertSql()).run(...row.values);
+      recorder?.recordLocal(this.name, row._id, "upsert", row.created_at);
+    };
+    if (recorder) this.db.transaction(write);
+    else write();
+    return row.returned;
   }
   async createMany(args) {
     this.ensureTable();
-    const stmt = this.db.prepare(
-      `INSERT INTO "${this.name}" (_id, data, created_at, updated_at) VALUES (?, ?, ?, ?)`
-    );
+    const stmt = this.db.prepare(this.insertSql());
+    const recorder = this.recorder;
     this.db.transaction(() => {
       for (const item of args.data) {
-        const row = this.prepareInsert(item);
-        stmt.run(row._id, row.data, row.created_at, row.updated_at);
+        const row = this.buildInsert(item);
+        stmt.run(...row.values);
+        recorder?.recordLocal(this.name, row._id, "upsert", row.created_at);
       }
     });
     return { count: args.data.length };
@@ -542,9 +700,13 @@ var Collection = class {
   async findMany(args = {}) {
     this.ensureTable();
     const params = [];
-    const where = buildWhere(args.where, { params, onPath: this.trackPath });
-    let sql = `SELECT ${SELECT_COLS} FROM "${this.name}" WHERE ${where}`;
-    const order = buildOrderBy(args.orderBy, this.trackPath);
+    const where = buildWhere(args.where, {
+      params,
+      onPath: this.trackPath,
+      columns: this.columns
+    });
+    let sql = `SELECT * FROM "${this.name}" WHERE ${where}`;
+    const order = buildOrderBy(args.orderBy, this.trackPath, this.columns);
     if (order) sql += " " + order;
     if (args.take != null) {
       sql += " LIMIT ?";
@@ -555,9 +717,7 @@ var Collection = class {
       params.push(args.skip);
     }
     const rows = this.db.prepare(sql).all(...params);
-    return rows.map(
-      (r) => project(this.rowToDoc(r), args.select)
-    );
+    return rows.map((r) => project(this.rowToDoc(r), args.select));
   }
   async findFirst(args = {}) {
     const rows = await this.findMany({ ...args, take: 1 });
@@ -565,27 +725,35 @@ var Collection = class {
   }
   async findById(id) {
     this.ensureTable();
-    const row = this.db.prepare(`SELECT ${SELECT_COLS} FROM "${this.name}" WHERE _id = ?`).get(id);
+    const row = this.db.prepare(`SELECT * FROM "${this.name}" WHERE _id = ?`).get(id);
     return row ? this.rowToDoc(row) : null;
   }
   async count(args = {}) {
     this.ensureTable();
     const params = [];
-    const where = buildWhere(args.where, { params, onPath: this.trackPath });
+    const where = buildWhere(args.where, {
+      params,
+      onPath: this.trackPath,
+      columns: this.columns
+    });
     const row = this.db.prepare(`SELECT COUNT(*) AS n FROM "${this.name}" WHERE ${where}`).get(...params);
     return row.n;
   }
   /**
-   * Return the distinct values of a field across the collection. Array fields
-   * are unwound (each element counts as a value), matching MongoDB's `distinct`.
+   * Return the distinct values of a field. Array fields stored in JSON are
+   * unwound (each element counts as a value), matching MongoDB's `distinct`.
    */
   async distinct(field, where) {
     this.ensureTable();
     const params = [];
-    const clause = buildWhere(where, { params, onPath: this.trackPath });
+    const clause = buildWhere(where, {
+      params,
+      onPath: this.trackPath,
+      columns: this.columns
+    });
     let sql;
-    if (isReserved(field)) {
-      sql = `SELECT DISTINCT ${fieldExpr(field)} AS v FROM "${this.name}" WHERE ${clause} ORDER BY v`;
+    if (isColumn(field, this.columns)) {
+      sql = `SELECT DISTINCT ${fieldExpr(field, this.columns)} AS v FROM "${this.name}" WHERE ${clause} ORDER BY v`;
     } else {
       this.trackPath(field);
       sql = `SELECT DISTINCT je.value AS v FROM "${this.name}" CROSS JOIN json_each("${this.name}".data, ${pathLiteral(field)}) je WHERE ${clause} ORDER BY v`;
@@ -597,21 +765,25 @@ var Collection = class {
   runUpdate(where, data, single) {
     this.ensureTable();
     const params = [];
-    const clause = buildWhere(where, { params, onPath: this.trackPath });
-    let selectSql = `SELECT ${SELECT_COLS} FROM "${this.name}" WHERE ${clause}`;
+    const clause = buildWhere(where, {
+      params,
+      onPath: this.trackPath,
+      columns: this.columns
+    });
+    let selectSql = `SELECT * FROM "${this.name}" WHERE ${clause}`;
     if (single) selectSql += " LIMIT 1";
     const rows = this.db.prepare(selectSql).all(...params);
     if (!rows.length) return [];
     const now = Date.now();
-    const stmt = this.db.prepare(
-      `UPDATE "${this.name}" SET data = ?, updated_at = ? WHERE _id = ?`
-    );
+    const recorder = this.recorder;
     return this.db.transaction(() => {
       const out = [];
       for (const row of rows) {
-        const current = JSON.parse(row.data);
+        const current = stripSystem(this.rowToDoc(row));
         const updated = stripSystem(applyUpdate(current, data));
-        stmt.run(JSON.stringify(updated), now, row._id);
+        const { setSql, values } = this.buildUpdateSet(updated, now);
+        this.db.prepare(`UPDATE "${this.name}" SET ${setSql} WHERE _id = ?`).run(...values, row._id);
+        recorder?.recordLocal(this.name, row._id, "upsert", now);
         out.push({
           ...updated,
           _id: row._id,
@@ -644,14 +816,23 @@ var Collection = class {
   runDelete(where, single) {
     this.ensureTable();
     const params = [];
-    const clause = buildWhere(where, { params, onPath: this.trackPath });
-    let selectSql = `SELECT ${SELECT_COLS} FROM "${this.name}" WHERE ${clause}`;
+    const clause = buildWhere(where, {
+      params,
+      onPath: this.trackPath,
+      columns: this.columns
+    });
+    let selectSql = `SELECT * FROM "${this.name}" WHERE ${clause}`;
     if (single) selectSql += " LIMIT 1";
     const rows = this.db.prepare(selectSql).all(...params);
     if (!rows.length) return [];
     const stmt = this.db.prepare(`DELETE FROM "${this.name}" WHERE _id = ?`);
+    const recorder = this.recorder;
+    const now = Date.now();
     this.db.transaction(() => {
-      for (const row of rows) stmt.run(row._id);
+      for (const row of rows) {
+        stmt.run(row._id);
+        recorder?.recordLocal(this.name, row._id, "delete", now);
+      }
     });
     return rows.map((r) => this.rowToDoc(r));
   }
@@ -665,14 +846,14 @@ var Collection = class {
   async aggregate(args = {}) {
     this.ensureTable();
     return aggregate(
-      { db: this.db, table: this.name, onPath: this.trackPath },
+      { db: this.db, table: this.name, onPath: this.trackPath, columns: this.columns },
       args
     );
   }
   async groupBy(args) {
     this.ensureTable();
     return groupBy(
-      { db: this.db, table: this.name, onPath: this.trackPath },
+      { db: this.db, table: this.name, onPath: this.trackPath, columns: this.columns },
       args
     );
   }
@@ -858,6 +1039,347 @@ function createDriver(filename, options = {}) {
   );
 }
 
+// src/sync/version.ts
+var TS_WIDTH = 15;
+function makeVersion(ts, nodeId) {
+  return String(ts).padStart(TS_WIDTH, "0") + ":" + nodeId;
+}
+function compareVersions(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+function versionTs(v) {
+  const i = v.indexOf(":");
+  return Number(i === -1 ? v : v.slice(0, i));
+}
+
+// src/sync/store.ts
+var NAME_RE2 = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function assertName(name) {
+  if (!NAME_RE2.test(name)) throw new Error(`Invalid collection name "${name}"`);
+}
+function stripSystem2(obj) {
+  const { _id, created_at, updated_at, ...rest } = obj;
+  return rest;
+}
+var SyncStore = class {
+  constructor(db, nodeId) {
+    this.db = db;
+    this.init();
+    this.nodeId = this.resolveNodeId(nodeId);
+  }
+  db;
+  nodeId;
+  init() {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS _monlite_changes (
+        seq INTEGER PRIMARY KEY AUTOINCREMENT,
+        coll TEXT NOT NULL,
+        doc_id TEXT NOT NULL,
+        op TEXT NOT NULL,
+        version TEXT NOT NULL,
+        ts INTEGER NOT NULL,
+        source TEXT NOT NULL DEFAULT 'local',
+        pushed INTEGER NOT NULL DEFAULT 0
+      );
+      CREATE INDEX IF NOT EXISTS _idx_changes_doc ON _monlite_changes(coll, doc_id, seq);
+      CREATE INDEX IF NOT EXISTS _idx_changes_push ON _monlite_changes(source, pushed, seq);
+      CREATE TABLE IF NOT EXISTS _monlite_sync_state (
+        remote TEXT PRIMARY KEY,
+        cursor TEXT,
+        last_pull_at INTEGER,
+        last_push_seq INTEGER,
+        last_push_at INTEGER
+      );
+      CREATE TABLE IF NOT EXISTS _monlite_conflicts (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        coll TEXT, doc_id TEXT,
+        local_version TEXT, remote_version TEXT,
+        winner TEXT, ts INTEGER
+      );
+      CREATE TABLE IF NOT EXISTS _monlite_meta (key TEXT PRIMARY KEY, value TEXT);
+    `);
+  }
+  resolveNodeId(explicit) {
+    if (explicit) {
+      this.db.prepare(`INSERT OR REPLACE INTO _monlite_meta (key, value) VALUES ('nodeId', ?)`).run(explicit);
+      return explicit;
+    }
+    const row = this.db.prepare(`SELECT value FROM _monlite_meta WHERE key = 'nodeId'`).get();
+    if (row?.value) return row.value;
+    const generated = objectId();
+    this.db.prepare(`INSERT INTO _monlite_meta (key, value) VALUES ('nodeId', ?)`).run(generated);
+    return generated;
+  }
+  /** True if this database tracks sync metadata (always, once constructed). */
+  get enabled() {
+    return true;
+  }
+  /* ----------------------- local change recording ----------------------- */
+  /** Append a locally-originated change to the feed. Call inside a write txn. */
+  recordLocal(collection, id, op, ts) {
+    const version = makeVersion(ts, this.nodeId);
+    this.db.prepare(
+      `INSERT INTO _monlite_changes (coll, doc_id, op, version, ts, source, pushed)
+         VALUES (?, ?, ?, ?, ?, 'local', 0)`
+    ).run(collection, id, op, version, ts);
+    return version;
+  }
+  /** Current (latest) version of a document, or null if never recorded. */
+  currentVersion(collection, id) {
+    const row = this.db.prepare(
+      `SELECT version FROM _monlite_changes
+         WHERE coll = ? AND doc_id = ? ORDER BY seq DESC LIMIT 1`
+    ).get(collection, id);
+    return row?.version ?? null;
+  }
+  /* ----------------------------- push side ----------------------------- */
+  /** Latest unpushed local change per document (the push queue). */
+  pending(collections) {
+    const params = [];
+    let collFilter = "";
+    if (collections && collections.length) {
+      collFilter = ` AND coll IN (${collections.map(() => "?").join(", ")})`;
+      params.push(...collections);
+    }
+    const rows = this.db.prepare(
+      `SELECT c.seq, c.coll, c.doc_id, c.op, c.version, c.ts
+         FROM _monlite_changes c
+         JOIN (
+           SELECT coll, doc_id, MAX(seq) AS mseq
+           FROM _monlite_changes
+           WHERE source = 'local' AND pushed = 0${collFilter}
+           GROUP BY coll, doc_id
+         ) m ON c.coll = m.coll AND c.doc_id = m.doc_id AND c.seq = m.mseq
+         ORDER BY c.seq`
+    ).all(...params);
+    return rows.map((r) => {
+      const change = {
+        seq: r.seq,
+        collection: r.coll,
+        _id: r.doc_id,
+        op: r.op,
+        version: r.version,
+        ts: r.ts
+      };
+      if (r.op === "upsert") {
+        const doc = this.readDoc(r.coll, r.doc_id);
+        if (doc) change.doc = doc;
+        else change.op = "delete";
+      }
+      return change;
+    });
+  }
+  /** Mark the given changes (and any earlier local rows per doc) as pushed. */
+  markPushed(changes) {
+    if (!changes.length) return;
+    const stmt = this.db.prepare(
+      `UPDATE _monlite_changes SET pushed = 1
+       WHERE coll = ? AND doc_id = ? AND seq <= ? AND source = 'local'`
+    );
+    this.db.transaction(() => {
+      for (const c of changes) stmt.run(c.collection, c._id, c.seq);
+    });
+  }
+  /* ----------------------------- pull side ----------------------------- */
+  /**
+   * Apply a remote change, resolving conflicts against the local version.
+   * Remote-applied changes are recorded with `source='remote'` so they are
+   * never pushed back (echo prevention).
+   */
+  applyRemote(change, resolver) {
+    assertName(change.collection);
+    const localVersion = this.currentVersion(change.collection, change._id);
+    let winner;
+    if (localVersion === null) {
+      winner = "remote";
+    } else if (change.version === localVersion) {
+      return { applied: false, conflict: false, winner: "none" };
+    } else {
+      winner = resolver ? resolver({
+        collection: change.collection,
+        _id: change._id,
+        local: { version: localVersion },
+        remote: { version: change.version, doc: change.doc }
+      }) : compareVersions(change.version, localVersion) > 0 ? "remote" : "local";
+      this.recordConflict(
+        change.collection,
+        change._id,
+        localVersion,
+        change.version,
+        winner
+      );
+    }
+    if (winner !== "remote") {
+      return { applied: false, conflict: localVersion !== null, winner };
+    }
+    this.db.transaction(() => {
+      this.applyData(change);
+      this.db.prepare(
+        `INSERT INTO _monlite_changes (coll, doc_id, op, version, ts, source, pushed)
+           VALUES (?, ?, ?, ?, ?, 'remote', 1)`
+      ).run(
+        change.collection,
+        change._id,
+        change.op,
+        change.version,
+        versionTs(change.version)
+      );
+    });
+    return { applied: true, conflict: localVersion !== null, winner: "remote" };
+  }
+  applyData(change) {
+    const { collection: coll, _id, op } = change;
+    this.ensureCollTable(coll);
+    if (op === "delete") {
+      this.db.prepare(`DELETE FROM "${coll}" WHERE _id = ?`).run(_id);
+      return;
+    }
+    const doc = change.doc ?? {};
+    const data = JSON.stringify(stripSystem2(doc));
+    const ts = versionTs(change.version);
+    const createdAt = typeof doc.created_at === "number" ? doc.created_at : ts;
+    this.db.prepare(
+      `INSERT INTO "${coll}" (_id, data, created_at, updated_at) VALUES (?, ?, ?, ?)
+         ON CONFLICT(_id) DO UPDATE SET data = excluded.data, updated_at = excluded.updated_at`
+    ).run(_id, data, createdAt, ts);
+  }
+  /**
+   * Latest change per document with `seq` greater than the given watermark,
+   * as RemoteChanges (used when this database acts as a sync *source*, e.g. the
+   * monlite-as-remote adapter). Returns the new watermark to resume from.
+   */
+  changesSince(seq, collections) {
+    const params = [seq];
+    let collFilter = "";
+    if (collections && collections.length) {
+      collFilter = ` AND coll IN (${collections.map(() => "?").join(", ")})`;
+      params.push(...collections);
+    }
+    const rows = this.db.prepare(
+      `SELECT c.seq, c.coll, c.doc_id, c.op, c.version, c.ts
+         FROM _monlite_changes c
+         JOIN (
+           SELECT coll, doc_id, MAX(seq) AS mseq
+           FROM _monlite_changes
+           WHERE seq > ?${collFilter}
+           GROUP BY coll, doc_id
+         ) m ON c.coll = m.coll AND c.doc_id = m.doc_id AND c.seq = m.mseq
+         ORDER BY c.seq`
+    ).all(...params);
+    const changes = rows.map((r) => {
+      const change = {
+        collection: r.coll,
+        _id: r.doc_id,
+        op: r.op,
+        version: r.version
+      };
+      if (r.op === "upsert") {
+        const doc = this.readDoc(r.coll, r.doc_id);
+        if (doc) change.doc = doc;
+        else change.op = "delete";
+      }
+      return change;
+    });
+    const maxRow = this.db.prepare(`SELECT MAX(seq) AS m FROM _monlite_changes`).get();
+    return { changes, maxSeq: maxRow?.m ?? seq };
+  }
+  /* ------------------------------ bootstrap ----------------------------- */
+  /**
+   * Enqueue existing documents (created before sync was enabled, or never
+   * recorded) as local upserts so they can be pushed. Idempotent.
+   */
+  seed(collections) {
+    let count = 0;
+    this.db.transaction(() => {
+      for (const coll of collections) {
+        assertName(coll);
+        const docs = this.db.prepare(`SELECT _id, updated_at FROM "${coll}"`).all();
+        for (const d of docs) {
+          if (this.currentVersion(coll, d._id) !== null) continue;
+          this.recordLocal(coll, d._id, "upsert", d.updated_at);
+          count++;
+        }
+      }
+    });
+    return count;
+  }
+  /* ------------------------------- state -------------------------------- */
+  getState(remote) {
+    const row = this.db.prepare(`SELECT * FROM _monlite_sync_state WHERE remote = ?`).get(remote);
+    return {
+      remote,
+      cursor: row?.cursor ?? null,
+      lastPullAt: row?.last_pull_at ?? null,
+      lastPushSeq: row?.last_push_seq ?? null,
+      lastPushAt: row?.last_push_at ?? null
+    };
+  }
+  setState(remote, patch) {
+    const cur = this.getState(remote);
+    const next = { ...cur, ...patch };
+    this.db.prepare(
+      `INSERT INTO _monlite_sync_state (remote, cursor, last_pull_at, last_push_seq, last_push_at)
+         VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT(remote) DO UPDATE SET
+           cursor = excluded.cursor,
+           last_pull_at = excluded.last_pull_at,
+           last_push_seq = excluded.last_push_seq,
+           last_push_at = excluded.last_push_at`
+    ).run(
+      remote,
+      next.cursor,
+      next.lastPullAt,
+      next.lastPushSeq,
+      next.lastPushAt
+    );
+  }
+  /* ----------------------------- conflicts ------------------------------ */
+  recordConflict(coll, id, localVersion, remoteVersion, winner) {
+    this.db.prepare(
+      `INSERT INTO _monlite_conflicts (coll, doc_id, local_version, remote_version, winner, ts)
+         VALUES (?, ?, ?, ?, ?, ?)`
+    ).run(coll, id, localVersion, remoteVersion, winner, versionTs(remoteVersion));
+  }
+  conflicts() {
+    const rows = this.db.prepare(
+      `SELECT coll, doc_id, local_version, remote_version, winner, ts
+         FROM _monlite_conflicts ORDER BY id`
+    ).all();
+    return rows.map((r) => ({
+      collection: r.coll,
+      _id: r.doc_id,
+      localVersion: r.local_version,
+      remoteVersion: r.remote_version,
+      winner: r.winner,
+      ts: r.ts
+    }));
+  }
+  /* ------------------------------ helpers ------------------------------- */
+  readDoc(coll, id) {
+    assertName(coll);
+    const row = this.db.prepare(
+      `SELECT _id, data, created_at, updated_at FROM "${coll}" WHERE _id = ?`
+    ).get(id);
+    if (!row) return null;
+    const doc = JSON.parse(row.data);
+    doc._id = row._id;
+    doc.created_at = row.created_at;
+    doc.updated_at = row.updated_at;
+    return doc;
+  }
+  ensureCollTable(coll) {
+    assertName(coll);
+    this.db.exec(
+      `CREATE TABLE IF NOT EXISTS "${coll}" (
+        _id TEXT PRIMARY KEY,
+        data TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL
+      )`
+    );
+  }
+};
+
 // src/db.ts
 function validateName(name) {
   if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
@@ -883,6 +1405,8 @@ var Monlite = class {
   driver;
   /** @internal */
   autoIndexer;
+  /** @internal Sync metadata store; present only when `{ sync: true }`. */
+  $sync;
   collections = /* @__PURE__ */ new Map();
   closed = false;
   constructor(filename, options = {}) {
@@ -897,6 +1421,13 @@ var Monlite = class {
       options.autoIndex ?? true,
       options.autoIndexAfter ?? 10
     );
+    if (options.sync) {
+      this.$sync = new SyncStore(this.driver, options.nodeId);
+    }
+  }
+  /** Stable node id for LWW tie-breaking (only when sync is enabled). */
+  get nodeId() {
+    return this.$sync?.nodeId;
   }
   /** The underlying native database handle (escape hatch). */
   get sqlite() {
@@ -906,17 +1437,35 @@ var Monlite = class {
   get driverName() {
     return this.driver.name;
   }
-  /** Get (or lazily create) a typed collection handle. */
-  collection(name) {
+  /**
+   * Get (or lazily create) a typed collection handle. Pass `{ schema }` to make
+   * it a structured collection backed by native SQL columns; omit for the
+   * default schema-free document mode. Options apply only on first access.
+   */
+  collection(name, options) {
     this.assertOpen();
     validateName(name);
     let col = this.collections.get(name);
     if (!col) {
-      col = new Collection(this, name);
+      col = new Collection(this, name, options);
       this.collections.set(name, col);
     }
     return col;
   }
+  /** Inspect a collection's physical columns (PRAGMA table_info). */
+  $schema(name) {
+    this.assertOpen();
+    validateName(name);
+    const rows = this.driver.prepare(`PRAGMA table_info("${name}")`).all();
+    return Promise.resolve(
+      rows.map((r) => ({
+        name: r.name,
+        type: r.type,
+        notNull: !!r.notnull,
+        primaryKey: !!r.pk
+      }))
+    );
+  }
   /** Tagged-template SQL query returning rows. Values are safely parameterized. */
   $queryRaw(strings, ...values) {
     this.assertOpen();
@@ -956,7 +1505,9 @@ var Monlite = class {
     this.assertOpen();
     const rows = this.driver.prepare(
       `SELECT name FROM sqlite_master
-         WHERE type='table' AND name NOT LIKE 'sqlite_%'
+         WHERE type='table'
+           AND name NOT LIKE 'sqlite_%'
+           AND name NOT LIKE '\\_monlite\\_%' ESCAPE '\\'
          ORDER BY name`
     ).all();
     return Promise.resolve(rows.map((r) => r.name));
@@ -994,8 +1545,12 @@ exports.Collection = Collection;
 exports.Monlite = Monlite;
 exports.MonliteError = MonliteError;
 exports.MonliteQueryError = MonliteQueryError;
+exports.SyncStore = SyncStore;
+exports.compareVersions = compareVersions;
 exports.createDb = createDb;
 exports.isObjectId = isObjectId;
+exports.makeVersion = makeVersion;
 exports.objectId = objectId;
+exports.versionTs = versionTs;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map