@monlite/core 0.5.0 → 0.7.0

package/dist/index.js

@@ -19,17 +19,64 @@ function isObjectId(value) {
 
 // src/errors.ts
 var MonliteError = class extends Error {
-  constructor(message) {
+  constructor(message, options) {
     super(message);
     this.name = "MonliteError";
+    if (options?.cause !== void 0) this.cause = options.cause;
   }
 };
 var MonliteQueryError = class extends MonliteError {
-  constructor(message) {
-    super(message);
+  constructor(message, options) {
+    super(message, options);
     this.name = "MonliteQueryError";
   }
 };
+var MonliteConstraintError = class extends MonliteError {
+  collection;
+  constructor(message, options) {
+    super(message, options);
+    this.name = "MonliteConstraintError";
+    this.collection = options?.collection;
+  }
+};
+var MonliteUniqueConstraintError = class extends MonliteConstraintError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "MonliteUniqueConstraintError";
+  }
+};
+var MonliteNotNullError = class extends MonliteConstraintError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "MonliteNotNullError";
+  }
+};
+var MonliteForeignKeyError = class extends MonliteConstraintError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "MonliteForeignKeyError";
+  }
+};
+function normalizeDriverError(err, collection) {
+  if (err instanceof MonliteError) return err;
+  const code = err?.code ? String(err.code) : "";
+  const message = err instanceof Error ? err.message : String(err);
+  const blob = `${code} ${message}`;
+  const opts = { cause: err, collection };
+  if (/UNIQUE|PRIMARY KEY|constraint failed: .*\.(?:_id)\b/i.test(blob)) {
+    return new MonliteUniqueConstraintError(message, opts);
+  }
+  if (/NOT ?NULL/i.test(blob)) {
+    return new MonliteNotNullError(message, opts);
+  }
+  if (/FOREIGN ?KEY/i.test(blob)) {
+    return new MonliteForeignKeyError(message, opts);
+  }
+  if (/CONSTRAINT/i.test(blob)) {
+    return new MonliteConstraintError(message, opts);
+  }
+  return new MonliteError(message, { cause: err });
+}
 
 // src/query/sql.ts
 var RESERVED_FIELDS = /* @__PURE__ */ new Set(["_id", "created_at", "updated_at"]);
@@ -56,9 +103,12 @@ function pathLiteral(field) {
   return "'" + jsonPath(field).replace(/'/g, "''") + "'";
 }
 function fieldExpr(field, columns) {
-  if (isColumn(field, columns)) return `"${field}"`;
+  if (isColumn(field, columns)) return quoteIdent(field);
   return `json_extract(data, ${pathLiteral(field)})`;
 }
+function quoteIdent(name) {
+  return `"${name.replace(/"/g, '""')}"`;
+}
 function bindable(value) {
   if (value === void 0 || value === null) return null;
   if (typeof value === "boolean") return value ? 1 : 0;
@@ -109,10 +159,11 @@ function translateField(field, condition, ctx) {
     return eqExpr(expr, condition, ctx);
   }
   const filter = condition;
+  const ci = filter.mode === "insensitive";
   const clauses = [];
   for (const op of Object.keys(filter)) {
     const v = filter[op];
-    if (v === void 0) continue;
+    if (v === void 0 || op === "mode") continue;
     switch (op) {
       case "equals":
         clauses.push(eqExpr(expr, v, ctx));
@@ -139,16 +190,20 @@ function translateField(field, condition, ctx) {
         clauses.push(inExpr(expr, v, ctx, true));
         break;
       case "contains":
-        clauses.push(containsExpr(field, expr, v, ctx));
+        clauses.push(containsExpr(field, expr, v, ctx, ci));
         break;
       case "startsWith":
         ctx.params.push(bindable(v));
-        clauses.push(`instr(${expr}, ?) = 1`);
+        clauses.push(
+          ci ? `instr(lower(${expr}), lower(?)) = 1` : `instr(${expr}, ?) = 1`
+        );
         break;
       case "endsWith":
         ctx.params.push(bindable(v));
         ctx.params.push(bindable(v));
-        clauses.push(`substr(${expr}, -length(?)) = ?`);
+        clauses.push(
+          ci ? `substr(lower(${expr}), -length(?)) = lower(?)` : `substr(${expr}, -length(?)) = ?`
+        );
         break;
       case "has":
         clauses.push(hasExpr(field, expr, v, ctx));
@@ -181,9 +236,7 @@ function cmp(expr, op, v, ctx) {
 }
 function inExpr(expr, arr, ctx, negate) {
   if (!Array.isArray(arr)) {
-    throw new MonliteQueryError(
-      `${negate ? "notIn" : "in"} expects an array`
-    );
+    throw new MonliteQueryError(`${negate ? "notIn" : "in"} expects an array`);
   }
   if (arr.length === 0) return negate ? "1" : "0";
   const placeholders = arr.map((v) => {
@@ -192,15 +245,17 @@ function inExpr(expr, arr, ctx, negate) {
   }).join(", ");
   return negate ? `(${expr} IS NULL OR ${expr} NOT IN (${placeholders}))` : `${expr} IN (${placeholders})`;
 }
-function containsExpr(field, expr, v, ctx) {
+function containsExpr(field, expr, v, ctx, ci) {
+  const sub = ci ? `instr(lower(${expr}), lower(?)) > 0` : `instr(${expr}, ?) > 0`;
   if (isColumn(field, ctx.columns)) {
     ctx.params.push(bindable(v));
-    return `instr(${expr}, ?) > 0`;
+    return sub;
   }
   const path = pathLiteral(field);
+  const member = ci ? `lower(value) = lower(?)` : `value = ?`;
   ctx.params.push(bindable(v));
   ctx.params.push(bindable(v));
-  return `(CASE WHEN json_type(data, ${path}) = 'array' THEN EXISTS (SELECT 1 FROM json_each(data, ${path}) WHERE value = ?) ELSE instr(${expr}, ?) > 0 END)`;
+  return `(CASE WHEN json_type(data, ${path}) = 'array' THEN EXISTS (SELECT 1 FROM json_each(data, ${path}) WHERE ${member}) ELSE ${sub} END)`;
 }
 function hasExpr(field, expr, v, ctx) {
   ctx.params.push(bindable(v));
@@ -233,16 +288,26 @@ function buildOrderBy(orderBy, onPath, columns) {
 }
 
 // src/query/path.ts
+var FORBIDDEN = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
+function safeSegments(path) {
+  const segs = path.split(".");
+  for (const seg of segs) {
+    if (FORBIDDEN.has(seg)) {
+      throw new MonliteQueryError(`Illegal path segment "${seg}" in "${path}"`);
+    }
+  }
+  return segs;
+}
 function getPath(obj, path) {
   let cur = obj;
-  for (const seg of path.split(".")) {
+  for (const seg of safeSegments(path)) {
     if (cur == null) return void 0;
     cur = cur[seg];
   }
   return cur;
 }
 function setPath(obj, path, value) {
-  const segs = path.split(".");
+  const segs = safeSegments(path);
   let cur = obj;
   for (let i = 0; i < segs.length - 1; i++) {
     const seg = segs[i];
@@ -252,7 +317,7 @@ function setPath(obj, path, value) {
   cur[segs[segs.length - 1]] = value;
 }
 function unsetPath(obj, path) {
-  const segs = path.split(".");
+  const segs = safeSegments(path);
   let cur = obj;
   for (let i = 0; i < segs.length - 1; i++) {
     const seg = segs[i];
@@ -301,12 +366,18 @@ function applyUpdate(doc, data) {
   }
   const ops = data;
   if (ops.$set) {
-    for (const [path, value] of Object.entries(ops.$set)) setPath(next, path, value);
+    for (const [path, value] of Object.entries(ops.$set))
+      setPath(next, path, value);
   }
   if (ops.$inc) {
     for (const [path, by] of Object.entries(ops.$inc)) {
+      if (typeof by !== "number" || !Number.isFinite(by)) {
+        throw new MonliteQueryError(
+          `$inc on "${path}" requires a finite number, got ${JSON.stringify(by)}`
+        );
+      }
       const cur = getPath(next, path);
-      setPath(next, path, (typeof cur === "number" ? cur : 0) + Number(by));
+      setPath(next, path, (typeof cur === "number" ? cur : 0) + by);
     }
   }
   if (ops.$push) {
@@ -417,7 +488,11 @@ function buildHaving(having, params, columns) {
     if (!selection) continue;
     for (const field of Object.keys(selection)) {
       parts.push(
-        ...comparisonSql(`${fn}(${fieldExpr(field, columns)})`, selection[field], params)
+        ...comparisonSql(
+          `${fn}(${fieldExpr(field, columns)})`,
+          selection[field],
+          params
+        )
       );
     }
   }
@@ -425,7 +500,7 @@ function buildHaving(having, params, columns) {
 }
 function groupBy(ctx, args) {
   if (!Array.isArray(args.by) || args.by.length === 0) {
-    throw new Error("groupBy requires a non-empty `by` array");
+    throw new MonliteQueryError("groupBy requires a non-empty `by` array");
   }
   const params = [];
   const where = buildWhere(args.where, {
@@ -434,15 +509,22 @@ function groupBy(ctx, args) {
     columns: ctx.columns
   });
   const groupExprs = [];
+  const groupCols = [];
   const selects = [];
-  for (const field of args.by) {
+  args.by.forEach((field, gi) => {
     if (!isColumn(field, ctx.columns)) ctx.onPath(field);
     const expr = fieldExpr(field, ctx.columns);
+    const alias = `grp_${gi}`;
     groupExprs.push(expr);
-    selects.push(`${expr} AS "${field}"`);
-  }
+    selects.push(`${expr} AS ${alias}`);
+    groupCols.push({ alias, field });
+  });
   selects.push(`COUNT(*) AS agg_count`);
-  const { selects: accSelects, cols } = buildAccumulators(args, ctx.onPath, ctx.columns);
+  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) {
@@ -469,7 +551,7 @@ function groupBy(ctx, args) {
   const rows = ctx.db.prepare(sql).all(...params);
   return rows.map((row) => {
     const out = {};
-    for (const field of args.by) out[field] = row[field];
+    for (const { alias, field } of groupCols) out[field] = row[alias];
     if (args._count) out._count = row.agg_count;
     for (const col of cols) {
       (out[col.kind] ??= {})[col.field] = row[col.alias] ?? null;
@@ -508,6 +590,13 @@ var Collection = class {
           );
         }
         const normalized = typeof def === "string" ? { type: def } : def;
+        if (normalized.references && !/^[A-Za-z_][A-Za-z0-9_]*(\([A-Za-z_][A-Za-z0-9_]*\))?$/.test(
+          normalized.references
+        )) {
+          throw new MonliteError(
+            `Invalid references "${normalized.references}" on column "${field}"`
+          );
+        }
         this.columnDefs[field] = normalized;
         this.columnOrder.push(field);
         this.columns.add(field);
@@ -529,6 +618,14 @@ var Collection = class {
   get db() {
     return this.mon.driver;
   }
+  /** Run a DB operation, normalizing driver errors into typed MonliteErrors. */
+  guard(fn) {
+    try {
+      return fn();
+    } catch (err) {
+      throw normalizeDriverError(err, this.name);
+    }
+  }
   /** Native column names declared for this collection (structured mode). */
   get columnNames() {
     return [...this.columnOrder];
@@ -556,7 +653,8 @@ var Collection = class {
         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.default !== void 0)
+          line += ` DEFAULT ${formatDefault(def.default)}`;
         if (def.references) line += ` REFERENCES ${def.references}`;
         lines.push(line);
       }
@@ -581,7 +679,11 @@ var Collection = class {
     if (this.mode === "structured") {
       for (const field of this.columnOrder) {
         const value = row[field];
-        if (value === null || value === void 0) continue;
+        if (value === void 0) continue;
+        if (value === null) {
+          doc[field] = null;
+          continue;
+        }
         doc[field] = this.jsonColumns.has(field) ? JSON.parse(value) : value;
       }
     }
@@ -594,6 +696,11 @@ var Collection = class {
     if (this.jsonColumns.has(field)) {
       return value === void 0 ? null : JSON.stringify(value);
     }
+    if (value !== null && typeof value === "object" && !(value instanceof Date) && !Buffer.isBuffer(value)) {
+      throw new MonliteQueryError(
+        `Column "${field}" cannot store an object/array. Declare it as { type: "JSON" } to store structured values.`
+      );
+    }
     return bindable(value);
   }
   insertColumns() {
@@ -611,7 +718,12 @@ var Collection = class {
     const now = Date.now();
     const id = input._id != null ? String(input._id) : objectId();
     const doc = stripSystem(input);
-    const returned = { ...doc, _id: id, created_at: now, updated_at: now };
+    const returned = {
+      ...doc,
+      _id: id,
+      created_at: now,
+      updated_at: now
+    };
     if (this.mode === "document") {
       return {
         _id: id,
@@ -663,9 +775,65 @@ var Collection = class {
     ];
     return { setSql: setParts.join(", "), values };
   }
-  /** Sync store, but only for document collections (structured sync is future work). */
+  /** Sync store for recording local changes (both document and structured). */
   get recorder() {
-    return this.mode === "document" ? this.mon.$sync : void 0;
+    return this.mon.$sync;
+  }
+  /** @internal Read a full document by id (mode-aware), synchronously. */
+  getRaw(id) {
+    this.ensureTable();
+    const row = this.db.prepare(`SELECT * FROM "${this.name}" WHERE _id = ?`).get(id);
+    return row ? this.rowToDoc(row) : null;
+  }
+  /**
+   * @internal Apply a remote change to storage WITHOUT recording it to the
+   * change feed (the sync store records the `remote` feed row itself). Used by
+   * `@monlite/sync` so structured collections sync correctly through the same
+   * column/overflow split as local writes.
+   */
+  applyRemoteWrite(op, id, doc, ts) {
+    this.ensureTable();
+    if (op === "delete") {
+      this.db.prepare(`DELETE FROM "${this.name}" WHERE _id = ?`).run(id);
+      return;
+    }
+    const clean = stripSystem(doc ?? {});
+    const createdAt = typeof doc?.created_at === "number" ? doc.created_at : ts;
+    if (this.mode === "document") {
+      this.db.prepare(
+        `INSERT INTO "${this.name}" (_id, data, created_at, updated_at) VALUES (?, ?, ?, ?)
+           ON CONFLICT(_id) DO UPDATE SET data = excluded.data, updated_at = excluded.updated_at`
+      ).run(id, JSON.stringify(clean), createdAt, ts);
+      return;
+    }
+    const overflow = {};
+    const colValues = {};
+    for (const [k, v] of Object.entries(clean)) {
+      if (this.columns.has(k)) colValues[k] = v;
+      else overflow[k] = v;
+    }
+    const cols = [
+      "_id",
+      "created_at",
+      "updated_at",
+      "data",
+      ...this.columnOrder
+    ];
+    const values = [
+      id,
+      createdAt,
+      ts,
+      JSON.stringify(overflow),
+      ...this.columnOrder.map(
+        (c) => c in colValues ? this.encodeColumn(c, colValues[c]) : null
+      )
+    ];
+    const colList = cols.map((c) => `"${c}"`).join(", ");
+    const placeholders = cols.map(() => "?").join(", ");
+    const updateSet = cols.filter((c) => c !== "_id" && c !== "created_at").map((c) => `"${c}" = excluded."${c}"`).join(", ");
+    this.db.prepare(
+      `INSERT INTO "${this.name}" (${colList}) VALUES (${placeholders}) ON CONFLICT(_id) DO UPDATE SET ${updateSet}`
+    ).run(...values);
   }
   /* ----------------------------- create ----------------------------- */
   async create(args) {
@@ -676,21 +844,22 @@ var Collection = class {
       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();
+    this.guard(() => recorder ? this.db.transaction(write) : write());
     return row.returned;
   }
   async createMany(args) {
     this.ensureTable();
     const stmt = this.db.prepare(this.insertSql());
     const recorder = this.recorder;
-    this.db.transaction(() => {
-      for (const item of args.data) {
-        const row = this.buildInsert(item);
-        stmt.run(...row.values);
-        recorder?.recordLocal(this.name, row._id, "upsert", row.created_at);
-      }
-    });
+    this.guard(
+      () => this.db.transaction(() => {
+        for (const item of args.data) {
+          const row = this.buildInsert(item);
+          stmt.run(...row.values);
+          recorder?.recordLocal(this.name, row._id, "upsert", row.created_at);
+        }
+      })
+    );
     return { count: args.data.length };
   }
   /* ------------------------------ read ------------------------------ */
@@ -720,6 +889,28 @@ var Collection = class {
     const rows = await this.findMany({ ...args, take: 1 });
     return rows[0] ?? null;
   }
+  /** Alias of {@link findFirst} for Prisma familiarity. */
+  async findUnique(args = {}) {
+    return this.findFirst(args);
+  }
+  /** Like {@link findFirst} but throws if no document matches. */
+  async findFirstOrThrow(args = {}) {
+    const doc = await this.findFirst(args);
+    if (!doc) throw new MonliteError(`No document found in "${this.name}"`);
+    return doc;
+  }
+  /** True if at least one document matches. */
+  async exists(where) {
+    this.ensureTable();
+    const params = [];
+    const clause = buildWhere(where, {
+      params,
+      onPath: this.trackPath,
+      columns: this.columns
+    });
+    const row = this.db.prepare(`SELECT 1 FROM "${this.name}" WHERE ${clause} LIMIT 1`).get(...params);
+    return row != null;
+  }
   async findById(id) {
     this.ensureTable();
     const row = this.db.prepare(`SELECT * FROM "${this.name}" WHERE _id = ?`).get(id);
@@ -755,8 +946,10 @@ var Collection = class {
       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`;
     }
-    const rows = this.db.prepare(sql).all(...params);
-    return rows.map((r) => r.v);
+    return this.guard(() => {
+      const rows = this.db.prepare(sql).all(...params);
+      return rows.map((r) => r.v);
+    });
   }
   /* ----------------------------- update ----------------------------- */
   runUpdate(where, data, single) {
@@ -773,23 +966,25 @@ var Collection = class {
     if (!rows.length) return [];
     const now = Date.now();
     const recorder = this.recorder;
-    return this.db.transaction(() => {
-      const out = [];
-      for (const row of rows) {
-        const current = stripSystem(this.rowToDoc(row));
-        const updated = stripSystem(applyUpdate(current, data));
-        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,
-          created_at: row.created_at,
-          updated_at: now
-        });
-      }
-      return out;
-    });
+    return this.guard(
+      () => this.db.transaction(() => {
+        const out = [];
+        for (const row of rows) {
+          const current = stripSystem(this.rowToDoc(row));
+          const updated = stripSystem(applyUpdate(current, data));
+          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,
+            created_at: row.created_at,
+            updated_at: now
+          });
+        }
+        return out;
+      })
+    );
   }
   async update(args) {
     return this.runUpdate(args.where, args.data, true)[0] ?? null;
@@ -799,15 +994,36 @@ var Collection = class {
   }
   async upsert(args) {
     this.ensureTable();
-    const existing = await this.findFirst({ where: args.where });
-    if (existing) {
-      const updated = await this.update({
-        where: { _id: existing._id },
-        data: args.update
-      });
-      return updated;
-    }
-    return this.create({ data: args.create });
+    return this.guard(
+      () => this.db.transaction(() => {
+        const params = [];
+        const clause = buildWhere(args.where, {
+          params,
+          onPath: this.trackPath,
+          columns: this.columns
+        });
+        const row = this.db.prepare(`SELECT * FROM "${this.name}" WHERE ${clause} LIMIT 1`).get(...params);
+        const now = Date.now();
+        const recorder = this.recorder;
+        if (row) {
+          const current = stripSystem(this.rowToDoc(row));
+          const updated = stripSystem(applyUpdate(current, args.update));
+          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);
+          return {
+            ...updated,
+            _id: row._id,
+            created_at: row.created_at,
+            updated_at: now
+          };
+        }
+        const ins = this.buildInsert(args.create);
+        this.db.prepare(this.insertSql()).run(...ins.values);
+        recorder?.recordLocal(this.name, ins._id, "upsert", ins.created_at);
+        return ins.returned;
+      })
+    );
   }
   /* ----------------------------- delete ----------------------------- */
   runDelete(where, single) {
@@ -825,12 +1041,14 @@ var Collection = class {
     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);
-        recorder?.recordLocal(this.name, row._id, "delete", now);
-      }
-    });
+    this.guard(
+      () => this.db.transaction(() => {
+        for (const row of rows) {
+          stmt.run(row._id);
+          recorder?.recordLocal(this.name, row._id, "delete", now);
+        }
+      })
+    );
     return rows.map((r) => this.rowToDoc(r));
   }
   async delete(args) {
@@ -842,16 +1060,30 @@ var Collection = class {
   /* --------------------------- aggregation -------------------------- */
   async aggregate(args = {}) {
     this.ensureTable();
-    return aggregate(
-      { db: this.db, table: this.name, onPath: this.trackPath, columns: this.columns },
-      args
+    return this.guard(
+      () => aggregate(
+        {
+          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, columns: this.columns },
-      args
+    return this.guard(
+      () => groupBy(
+        {
+          db: this.db,
+          table: this.name,
+          onPath: this.trackPath,
+          columns: this.columns
+        },
+        args
+      )
     );
   }
 };
@@ -909,15 +1141,19 @@ var AutoIndexer = class {
 };
 
 // src/driver/better-sqlite3.ts
+var STMT_CACHE_MAX = 256;
 var BetterSqlite3Driver = class {
   name = "better-sqlite3";
   raw;
   verbose;
+  cache = /* @__PURE__ */ new Map();
   constructor(BetterSqlite3, filename, options) {
     this.verbose = options.verbose;
     this.raw = new BetterSqlite3(filename, {
       readonly: options.readonly ?? false
     });
+    this.raw.pragma("foreign_keys = ON");
+    this.raw.pragma(`busy_timeout = ${options.busyTimeout ?? 5e3}`);
     if (!options.readonly && (options.wal ?? true)) {
       this.raw.pragma("journal_mode = WAL");
     }
@@ -928,21 +1164,35 @@ var BetterSqlite3Driver = class {
   }
   prepare(sql) {
     this.verbose?.(sql);
-    return this.raw.prepare(sql);
+    const cached = this.cache.get(sql);
+    if (cached) return cached;
+    const stmt = this.raw.prepare(sql);
+    this.cacheStmt(sql, stmt);
+    return stmt;
+  }
+  cacheStmt(sql, stmt) {
+    if (this.cache.size >= STMT_CACHE_MAX) {
+      const oldest = this.cache.keys().next().value;
+      if (oldest !== void 0) this.cache.delete(oldest);
+    }
+    this.cache.set(sql, stmt);
   }
   transaction(fn) {
     return this.raw.transaction(fn)();
   }
   close() {
+    this.cache.clear();
     this.raw.close();
   }
 };
 
 // src/driver/node-sqlite.ts
+var STMT_CACHE_MAX2 = 256;
 var NodeSqliteDriver = class {
   name = "node:sqlite";
   raw;
   verbose;
+  cache = /* @__PURE__ */ new Map();
   depth = 0;
   constructor(nodeSqlite, filename, options) {
     this.verbose = options.verbose;
@@ -950,6 +1200,7 @@ var NodeSqliteDriver = class {
     this.raw = new DatabaseSync(filename, {
       readOnly: options.readonly ?? false
     });
+    this.raw.exec(`PRAGMA busy_timeout = ${options.busyTimeout ?? 5e3}`);
     if (!options.readonly && (options.wal ?? true)) {
       this.raw.exec("PRAGMA journal_mode = WAL");
     }
@@ -960,12 +1211,20 @@ var NodeSqliteDriver = class {
   }
   prepare(sql) {
     this.verbose?.(sql);
+    const cached = this.cache.get(sql);
+    if (cached) return cached;
     const stmt = this.raw.prepare(sql);
-    return {
+    const wrapped = {
       run: (...p) => stmt.run(...p),
       get: (...p) => stmt.get(...p),
       all: (...p) => stmt.all(...p)
     };
+    if (this.cache.size >= STMT_CACHE_MAX2) {
+      const oldest = this.cache.keys().next().value;
+      if (oldest !== void 0) this.cache.delete(oldest);
+    }
+    this.cache.set(sql, wrapped);
+    return wrapped;
   }
   transaction(fn) {
     const savepoint = `monlite_sp_${this.depth}`;
@@ -980,12 +1239,21 @@ var NodeSqliteDriver = class {
       return result;
     } catch (err) {
       this.depth--;
-      if (this.depth === 0) this.raw.exec("ROLLBACK");
-      else this.raw.exec(`ROLLBACK TO ${savepoint}; RELEASE ${savepoint}`);
+      try {
+        if (this.depth === 0) this.raw.exec("ROLLBACK");
+        else this.raw.exec(`ROLLBACK TO ${savepoint}; RELEASE ${savepoint}`);
+      } catch {
+        this.depth = 0;
+        try {
+          this.raw.exec("ROLLBACK");
+        } catch {
+        }
+      }
       throw err;
     }
   }
   close() {
+    this.cache.clear();
     this.raw.close();
   }
 };
@@ -1038,8 +1306,10 @@ function createDriver(filename, options = {}) {
 
 // src/sync/version.ts
 var TS_WIDTH = 15;
-function makeVersion(ts, nodeId) {
-  return String(ts).padStart(TS_WIDTH, "0") + ":" + nodeId;
+var SEQ_WIDTH = 12;
+function makeVersion(ts, nodeId, seq) {
+  const base = String(ts).padStart(TS_WIDTH, "0") + ":" + nodeId;
+  return seq === void 0 ? base : base + ":" + String(seq).padStart(SEQ_WIDTH, "0");
 }
 function compareVersions(a, b) {
   return a < b ? -1 : a > b ? 1 : 0;
@@ -1059,13 +1329,16 @@ function stripSystem2(obj) {
   return rest;
 }
 var SyncStore = class {
-  constructor(db, nodeId) {
+  constructor(db, nodeId, mon) {
     this.db = db;
+    this.mon = mon;
     this.init();
     this.nodeId = this.resolveNodeId(nodeId);
   }
   db;
+  mon;
   nodeId;
+  versionSeq = 0;
   init() {
     this.db.exec(`
       CREATE TABLE IF NOT EXISTS _monlite_changes (
@@ -1098,7 +1371,9 @@ var SyncStore = class {
   }
   resolveNodeId(explicit) {
     if (explicit) {
-      this.db.prepare(`INSERT OR REPLACE INTO _monlite_meta (key, value) VALUES ('nodeId', ?)`).run(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();
@@ -1114,7 +1389,7 @@ var SyncStore = class {
   /* ----------------------- 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);
+    const version = makeVersion(ts, this.nodeId, this.versionSeq++);
     this.db.prepare(
       `INSERT INTO _monlite_changes (coll, doc_id, op, version, ts, source, pushed)
          VALUES (?, ?, ?, ?, ?, 'local', 0)`
@@ -1131,13 +1406,18 @@ var SyncStore = class {
   }
   /* ----------------------------- push side ----------------------------- */
   /** Latest unpushed local change per document (the push queue). */
-  pending(collections) {
+  pending(collections, limit) {
     const params = [];
     let collFilter = "";
     if (collections && collections.length) {
       collFilter = ` AND coll IN (${collections.map(() => "?").join(", ")})`;
       params.push(...collections);
     }
+    let limitClause = "";
+    if (limit != null && limit > 0) {
+      limitClause = " LIMIT ?";
+      params.push(limit);
+    }
     const rows = this.db.prepare(
       `SELECT c.seq, c.coll, c.doc_id, c.op, c.version, c.ts
          FROM _monlite_changes c
@@ -1147,7 +1427,7 @@ var SyncStore = class {
            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`
+         ORDER BY c.seq${limitClause}`
     ).all(...params);
     return rows.map((r) => {
       const change = {
@@ -1185,31 +1465,34 @@ var SyncStore = class {
    */
   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(() => {
+    return this.db.transaction(() => {
+      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") {
+        if (localVersion !== null) {
+          this.recordLocal(change.collection, change._id, "upsert", Date.now());
+        }
+        return { applied: false, conflict: localVersion !== null, winner };
+      }
       this.applyData(change);
       this.db.prepare(
         `INSERT INTO _monlite_changes (coll, doc_id, op, version, ts, source, pushed)
@@ -1221,37 +1504,49 @@ var SyncStore = class {
         change.version,
         versionTs(change.version)
       );
+      return {
+        applied: true,
+        conflict: localVersion !== null,
+        winner: "remote"
+      };
     });
-    return { applied: true, conflict: localVersion !== null, winner: "remote" };
   }
   applyData(change) {
-    const { collection: coll, _id, op } = change;
+    const ts = versionTs(change.version);
+    if (this.mon) {
+      this.mon.collection(change.collection).applyRemoteWrite(change.op, change._id, change.doc, ts);
+      return;
+    }
+    const coll = change.collection;
     this.ensureCollTable(coll);
-    if (op === "delete") {
-      this.db.prepare(`DELETE FROM "${coll}" WHERE _id = ?`).run(_id);
+    if (change.op === "delete") {
+      this.db.prepare(`DELETE FROM "${coll}" WHERE _id = ?`).run(change._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);
+    ).run(change._id, JSON.stringify(stripSystem2(doc)), 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) {
+  changesSince(seq, collections, limit) {
     const params = [seq];
     let collFilter = "";
     if (collections && collections.length) {
       collFilter = ` AND coll IN (${collections.map(() => "?").join(", ")})`;
       params.push(...collections);
     }
+    let limitClause = "";
+    if (limit != null && limit > 0) {
+      limitClause = " LIMIT ?";
+      params.push(limit);
+    }
     const rows = this.db.prepare(
       `SELECT c.seq, c.coll, c.doc_id, c.op, c.version, c.ts
          FROM _monlite_changes c
@@ -1261,7 +1556,7 @@ var SyncStore = class {
            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`
+         ORDER BY c.seq${limitClause}`
     ).all(...params);
     const changes = rows.map((r) => {
       const change = {
@@ -1277,8 +1572,8 @@ var SyncStore = class {
       }
       return change;
     });
-    const maxRow = this.db.prepare(`SELECT MAX(seq) AS m FROM _monlite_changes`).get();
-    return { changes, maxSeq: maxRow?.m ?? seq };
+    const maxSeq = rows.length ? rows[rows.length - 1].seq : seq;
+    return { changes, maxSeq };
   }
   /* ------------------------------ bootstrap ----------------------------- */
   /**
@@ -1290,6 +1585,7 @@ var SyncStore = class {
     this.db.transaction(() => {
       for (const coll of collections) {
         assertName(coll);
+        if (!this.tableExists(coll)) continue;
         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;
@@ -1335,7 +1631,14 @@ var SyncStore = class {
     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));
+    ).run(
+      coll,
+      id,
+      localVersion,
+      remoteVersion,
+      winner,
+      versionTs(remoteVersion)
+    );
   }
   conflicts() {
     const rows = this.db.prepare(
@@ -1354,6 +1657,8 @@ var SyncStore = class {
   /* ------------------------------ helpers ------------------------------- */
   readDoc(coll, id) {
     assertName(coll);
+    if (this.mon) return this.mon.collection(coll).getRaw(id);
+    if (!this.tableExists(coll)) return null;
     const row = this.db.prepare(
       `SELECT _id, data, created_at, updated_at FROM "${coll}" WHERE _id = ?`
     ).get(id);
@@ -1364,6 +1669,9 @@ var SyncStore = class {
     doc.updated_at = row.updated_at;
     return doc;
   }
+  tableExists(name) {
+    return this.db.prepare(`SELECT 1 FROM sqlite_master WHERE type='table' AND name = ?`).get(name) != null;
+  }
   ensureCollTable(coll) {
     assertName(coll);
     this.db.exec(
@@ -1411,6 +1719,7 @@ var Monlite = class {
       driver: options.driver,
       readonly: options.readonly,
       wal: options.wal,
+      busyTimeout: options.busyTimeout,
       verbose: options.verbose
     });
     this.autoIndexer = new AutoIndexer(
@@ -1419,7 +1728,7 @@ var Monlite = class {
       options.autoIndexAfter ?? 10
     );
     if (options.sync) {
-      this.$sync = new SyncStore(this.driver, options.nodeId);
+      this.$sync = new SyncStore(this.driver, options.nodeId, this);
     }
   }
   /** Stable node id for LWW tie-breaking (only when sync is enabled). */
@@ -1446,6 +1755,15 @@ var Monlite = class {
     if (!col) {
       col = new Collection(this, name, options);
       this.collections.set(name, col);
+    } else if (options?.schema) {
+      const requested = Object.keys(options.schema);
+      const existing = new Set(col.columnNames);
+      const sameShape = col.mode === "structured" && requested.length === existing.size && requested.every((c) => existing.has(c));
+      if (!sameShape) {
+        throw new MonliteError(
+          `Collection "${name}" was already opened with a different schema/mode. A collection's storage mode is fixed on first access.`
+        );
+      }
     }
     return col;
   }
@@ -1480,7 +1798,11 @@ var Monlite = class {
   $executeRaw(strings, ...values) {
     this.assertOpen();
     const { sql, params } = buildTagged(strings, values);
-    return Promise.resolve(this.driver.prepare(sql).run(...params).changes);
+    try {
+      return Promise.resolve(this.driver.prepare(sql).run(...params).changes);
+    } catch (err) {
+      throw normalizeDriverError(err);
+    }
   }
   /** Like {@link $executeRaw} but takes a raw SQL string and positional params. */
   $executeRawUnsafe(sql, ...params) {
@@ -1538,6 +1860,6 @@ function createDb(filename, options) {
   return new Monlite(filename, options);
 }
 
-export { Collection, Monlite, MonliteError, MonliteQueryError, SyncStore, compareVersions, createDb, isObjectId, makeVersion, objectId, versionTs };
+export { Collection, Monlite, MonliteConstraintError, MonliteError, MonliteForeignKeyError, MonliteNotNullError, MonliteQueryError, MonliteUniqueConstraintError, SyncStore, compareVersions, createDb, isObjectId, makeVersion, normalizeDriverError, objectId, versionTs };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map