@monlite/fts 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emad Jumaah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# 🌙 @monlite/fts
+
+> Full-text search for [`@monlite/core`](https://www.npmjs.com/package/@monlite/core),
+> powered by SQLite's built-in **FTS5**. Adds `collection.search()`.
+
+A monlite plugin — opt in by passing it to `createDb`, point it at the fields you
+want searchable, and it maintains an FTS5 index automatically (on every write,
+including changes applied by `@monlite/sync`).
+
+```ts
+import { createDb } from "@monlite/core";
+import { fts } from "@monlite/fts";
+
+const db = createDb("./app.db", {
+  plugins: [fts({ posts: ["title", "body"], users: ["name", "profile.bio"] })],
+});
+
+await db.collection("posts").create({
+  data: { title: "Hello world", body: "the quick brown fox" },
+});
+
+const results = await db.collection("posts").search("quick");
+// [ { _id, title, body, _score, … } ]  — ranked, full documents
+```
+
+## Install
+
+```bash
+npm install @monlite/core @monlite/fts
+```
+
+No native dependency — FTS5 ships inside SQLite, so this works on both monlite
+backends (`better-sqlite3` and the built-in `node:sqlite`).
+
+## API
+
+```ts
+fts(spec: Record<string, string[]>): MonlitePlugin
+```
+
+`spec` maps a collection name to the field paths to index (dot-notation for
+nested fields, e.g. `"profile.bio"`).
+
+```ts
+collection.search(query, {
+  limit?: number,           // default 50
+  where?: WhereInput<T>,    // also constrain with a normal monlite filter
+}): Promise<Array<WithId<T> & { _score: number }>>
+```
+
+- `query` uses FTS5 [MATCH syntax](https://www.sqlite.org/fts5.html#full_text_query_syntax)
+  (bare terms are AND-ed; `"a phrase"`; `term*` prefix; `a OR b`).
+- Results are ordered by relevance; `_score` is higher = better.
+- `where` is applied after matching, so you can combine search with structured filters.
+
+```ts
+import { reindex } from "@monlite/fts";
+reindex(db, "posts", ["title", "body"]); // rebuild a collection's index
+```
+
+## How it works
+
+For each configured collection, the plugin creates an FTS5 virtual table
+(`<collection>_fts`) keyed by the document `_id`. It indexes on `init` (backfilling
+existing documents when the index is empty) and keeps it current via the plugin
+`afterWrite` hook. Search runs `MATCH` against that table, then returns the live
+documents from the collection in rank order.
+
+## License
+
+MIT 🌙

package/dist/index.cjs

@@ -0,0 +1,95 @@
+'use strict';
+
+// src/index.ts
+var ftsTable = (coll) => `${coll}_fts`;
+var col = (i) => `f${i}`;
+function extractText(doc, path) {
+  let cur = doc;
+  for (const seg of path.split(".")) {
+    if (cur == null) return "";
+    cur = cur[seg];
+  }
+  if (cur == null) return "";
+  if (typeof cur === "string") return cur;
+  if (Array.isArray(cur))
+    return cur.filter((x) => x != null).map(String).join(" ");
+  if (typeof cur === "number" || typeof cur === "boolean") return String(cur);
+  return "";
+}
+function indexDoc(db, coll, fields, id) {
+  const sqlite = db.sqlite;
+  sqlite.prepare(`DELETE FROM "${ftsTable(coll)}" WHERE doc_id = ?`).run(id);
+  const doc = db.collection(coll).getRaw(id);
+  if (!doc) return;
+  const cols = fields.map((_, i) => `"${col(i)}"`).join(", ");
+  const placeholders = fields.map(() => "?").join(", ");
+  const values = fields.map((f) => extractText(doc, f));
+  sqlite.prepare(
+    `INSERT INTO "${ftsTable(coll)}"(doc_id, ${cols}) VALUES (?, ${placeholders})`
+  ).run(id, ...values);
+}
+function reindex(db, coll, fields) {
+  const sqlite = db.sqlite;
+  sqlite.exec(`DELETE FROM "${ftsTable(coll)}"`);
+  for (const doc of db.collection(coll).findManyCore({})) {
+    indexDoc(db, coll, fields, doc._id);
+  }
+}
+function search(db, coll, spec, query, opts) {
+  const fields = spec[coll.name];
+  if (!fields) {
+    throw new Error(
+      `Collection "${coll.name}" is not configured for full-text search`
+    );
+  }
+  const limit = opts?.limit ?? 50;
+  const rows = db.sqlite.prepare(
+    `SELECT doc_id, rank FROM "${ftsTable(coll.name)}" WHERE "${ftsTable(coll.name)}" MATCH ? ORDER BY rank LIMIT ?`
+  ).all(query, limit);
+  let allowed = null;
+  if (opts?.where) {
+    const ids = rows.map((r) => r.doc_id);
+    const idIn = { _id: { in: ids } };
+    const matching = coll.findManyCore({
+      where: { AND: [opts.where, idIn] }
+    });
+    allowed = new Set(matching.map((d) => d._id));
+  }
+  const out = [];
+  for (const r of rows) {
+    if (allowed && !allowed.has(r.doc_id)) continue;
+    const doc = coll.getRaw(r.doc_id);
+    if (doc) out.push({ ...doc, _score: -r.rank });
+  }
+  return Promise.resolve(out);
+}
+function fts(spec) {
+  let database;
+  return {
+    name: "fts",
+    init(db) {
+      database = db;
+      for (const [coll, fields] of Object.entries(spec)) {
+        const cols = fields.map((_, i) => `"${col(i)}"`).join(", ");
+        db.sqlite.exec(
+          `CREATE VIRTUAL TABLE IF NOT EXISTS "${ftsTable(coll)}" USING fts5(doc_id UNINDEXED, ${cols})`
+        );
+        const count = db.sqlite.prepare(`SELECT count(*) AS n FROM "${ftsTable(coll)}"`).get();
+        if (count.n === 0) reindex(db, coll, fields);
+      }
+    },
+    afterWrite(db, { collection, ids }) {
+      const fields = spec[collection];
+      if (!fields) return;
+      for (const id of ids) indexDoc(db, collection, fields, id);
+    },
+    collectionMethods: {
+      search: (collection, query, opts) => search(database, collection, spec, query, opts)
+    }
+  };
+}
+
+exports.fts = fts;
+exports.reindex = reindex;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["import type {\n  Collection,\n  Doc,\n  Monlite,\n  MonlitePlugin,\n  WhereInput,\n  WithId,\n} from \"@monlite/core\";\n\n/** Map of collection name → searchable field paths (dot-notation allowed). */\nexport type FtsSpec = Record<string, string[]>;\n\nexport interface SearchOptions<T = Doc> {\n  /** Max results (default 50). */\n  limit?: number;\n  /** Additionally constrain matches with a normal monlite where clause. */\n  where?: WhereInput<T>;\n}\n\nexport type SearchResult<T = Doc> = WithId<T> & { _score: number };\n\n// Make `collection.search()` typed wherever @monlite/fts is imported.\ndeclare module \"@monlite/core\" {\n  interface Collection<T> {\n    search(query: string, opts?: SearchOptions<T>): Promise<SearchResult<T>[]>;\n  }\n}\n\nconst ftsTable = (coll: string) => `${coll}_fts`;\nconst col = (i: number) => `f${i}`;\n\n/** Extract searchable text for a field path from a document. */\nfunction extractText(doc: Record<string, any>, path: string): string {\n  let cur: any = doc;\n  for (const seg of path.split(\".\")) {\n    if (cur == null) return \"\";\n    cur = cur[seg];\n  }\n  if (cur == null) return \"\";\n  if (typeof cur === \"string\") return cur;\n  if (Array.isArray(cur))\n    return cur\n      .filter((x) => x != null)\n      .map(String)\n      .join(\" \");\n  if (typeof cur === \"number\" || typeof cur === \"boolean\") return String(cur);\n  return \"\";\n}\n\nfunction indexDoc(\n  db: Monlite,\n  coll: string,\n  fields: string[],\n  id: string,\n): void {\n  const sqlite = db.sqlite;\n  sqlite.prepare(`DELETE FROM \"${ftsTable(coll)}\" WHERE doc_id = ?`).run(id);\n  const doc = db.collection(coll).getRaw(id);\n  if (!doc) return; // deleted\n  const cols = fields.map((_, i) => `\"${col(i)}\"`).join(\", \");\n  const placeholders = fields.map(() => \"?\").join(\", \");\n  const values = fields.map((f) => extractText(doc, f));\n  sqlite\n    .prepare(\n      `INSERT INTO \"${ftsTable(coll)}\"(doc_id, ${cols}) VALUES (?, ${placeholders})`,\n    )\n    .run(id, ...values);\n}\n\n/** Rebuild a collection's FTS index from scratch. */\nexport function reindex(db: Monlite, coll: string, fields: string[]): void {\n  const sqlite = db.sqlite;\n  sqlite.exec(`DELETE FROM \"${ftsTable(coll)}\"`);\n  for (const doc of db.collection(coll).findManyCore({})) {\n    indexDoc(db, coll, fields, (doc as WithId<Doc>)._id);\n  }\n}\n\nfunction search<T = Doc>(\n  db: Monlite,\n  coll: Collection<T>,\n  spec: FtsSpec,\n  query: string,\n  opts?: SearchOptions<T>,\n): Promise<SearchResult<T>[]> {\n  const fields = spec[coll.name];\n  if (!fields) {\n    throw new Error(\n      `Collection \"${coll.name}\" is not configured for full-text search`,\n    );\n  }\n  const limit = opts?.limit ?? 50;\n  const rows = db.sqlite\n    .prepare(\n      `SELECT doc_id, rank FROM \"${ftsTable(coll.name)}\" ` +\n        `WHERE \"${ftsTable(coll.name)}\" MATCH ? ORDER BY rank LIMIT ?`,\n    )\n    .all(query, limit) as Array<{ doc_id: string; rank: number }>;\n\n  let allowed: Set<string> | null = null;\n  if (opts?.where) {\n    const ids = rows.map((r) => r.doc_id);\n    const idIn = { _id: { in: ids } } as WhereInput<T>;\n    const matching = coll.findManyCore({\n      where: { AND: [opts.where, idIn] } as WhereInput<T>,\n    });\n    allowed = new Set(matching.map((d) => d._id));\n  }\n\n  const out: SearchResult<T>[] = [];\n  for (const r of rows) {\n    if (allowed && !allowed.has(r.doc_id)) continue;\n    const doc = coll.getRaw(r.doc_id);\n    if (doc) out.push({ ...doc, _score: -r.rank } as SearchResult<T>);\n  }\n  return Promise.resolve(out);\n}\n\n/**\n * Full-text search plugin (SQLite FTS5). Pass it to `createDb({ plugins: [...] })`\n * with a map of collection → searchable fields. Adds `collection.search()`, keeps\n * the index in sync on every write, and backfills existing documents on open.\n *\n * ```ts\n * const db = createDb(\"./app.db\", { plugins: [fts({ posts: [\"title\", \"body\"] })] });\n * await db.collection(\"posts\").search(\"hello world\");\n * ```\n */\nexport function fts(spec: FtsSpec): MonlitePlugin {\n  let database: Monlite;\n  return {\n    name: \"fts\",\n    init(db) {\n      database = db;\n      for (const [coll, fields] of Object.entries(spec)) {\n        const cols = fields.map((_, i) => `\"${col(i)}\"`).join(\", \");\n        db.sqlite.exec(\n          `CREATE VIRTUAL TABLE IF NOT EXISTS \"${ftsTable(coll)}\" ` +\n            `USING fts5(doc_id UNINDEXED, ${cols})`,\n        );\n        // Backfill when the index is empty (e.g. enabling FTS on an existing db).\n        const count = db.sqlite\n          .prepare(`SELECT count(*) AS n FROM \"${ftsTable(coll)}\"`)\n          .get() as { n: number };\n        if (count.n === 0) reindex(db, coll, fields);\n      }\n    },\n    afterWrite(db, { collection, ids }) {\n      const fields = spec[collection];\n      if (!fields) return;\n      for (const id of ids) indexDoc(db, collection, fields, id);\n    },\n    collectionMethods: {\n      search: (collection, query: string, opts?: SearchOptions) =>\n        search(database, collection, spec, query, opts),\n    },\n  };\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,33 @@
+import { Doc, WhereInput, WithId, MonlitePlugin, Monlite } from '@monlite/core';
+
+/** Map of collection name → searchable field paths (dot-notation allowed). */
+type FtsSpec = Record<string, string[]>;
+interface SearchOptions<T = Doc> {
+    /** Max results (default 50). */
+    limit?: number;
+    /** Additionally constrain matches with a normal monlite where clause. */
+    where?: WhereInput<T>;
+}
+type SearchResult<T = Doc> = WithId<T> & {
+    _score: number;
+};
+declare module "@monlite/core" {
+    interface Collection<T> {
+        search(query: string, opts?: SearchOptions<T>): Promise<SearchResult<T>[]>;
+    }
+}
+/** Rebuild a collection's FTS index from scratch. */
+declare function reindex(db: Monlite, coll: string, fields: string[]): void;
+/**
+ * Full-text search plugin (SQLite FTS5). Pass it to `createDb({ plugins: [...] })`
+ * with a map of collection → searchable fields. Adds `collection.search()`, keeps
+ * the index in sync on every write, and backfills existing documents on open.
+ *
+ * ```ts
+ * const db = createDb("./app.db", { plugins: [fts({ posts: ["title", "body"] })] });
+ * await db.collection("posts").search("hello world");
+ * ```
+ */
+declare function fts(spec: FtsSpec): MonlitePlugin;
+
+export { type FtsSpec, type SearchOptions, type SearchResult, fts, reindex };

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+import { Doc, WhereInput, WithId, MonlitePlugin, Monlite } from '@monlite/core';
+
+/** Map of collection name → searchable field paths (dot-notation allowed). */
+type FtsSpec = Record<string, string[]>;
+interface SearchOptions<T = Doc> {
+    /** Max results (default 50). */
+    limit?: number;
+    /** Additionally constrain matches with a normal monlite where clause. */
+    where?: WhereInput<T>;
+}
+type SearchResult<T = Doc> = WithId<T> & {
+    _score: number;
+};
+declare module "@monlite/core" {
+    interface Collection<T> {
+        search(query: string, opts?: SearchOptions<T>): Promise<SearchResult<T>[]>;
+    }
+}
+/** Rebuild a collection's FTS index from scratch. */
+declare function reindex(db: Monlite, coll: string, fields: string[]): void;
+/**
+ * Full-text search plugin (SQLite FTS5). Pass it to `createDb({ plugins: [...] })`
+ * with a map of collection → searchable fields. Adds `collection.search()`, keeps
+ * the index in sync on every write, and backfills existing documents on open.
+ *
+ * ```ts
+ * const db = createDb("./app.db", { plugins: [fts({ posts: ["title", "body"] })] });
+ * await db.collection("posts").search("hello world");
+ * ```
+ */
+declare function fts(spec: FtsSpec): MonlitePlugin;
+
+export { type FtsSpec, type SearchOptions, type SearchResult, fts, reindex };

package/dist/index.js

@@ -0,0 +1,92 @@
+// src/index.ts
+var ftsTable = (coll) => `${coll}_fts`;
+var col = (i) => `f${i}`;
+function extractText(doc, path) {
+  let cur = doc;
+  for (const seg of path.split(".")) {
+    if (cur == null) return "";
+    cur = cur[seg];
+  }
+  if (cur == null) return "";
+  if (typeof cur === "string") return cur;
+  if (Array.isArray(cur))
+    return cur.filter((x) => x != null).map(String).join(" ");
+  if (typeof cur === "number" || typeof cur === "boolean") return String(cur);
+  return "";
+}
+function indexDoc(db, coll, fields, id) {
+  const sqlite = db.sqlite;
+  sqlite.prepare(`DELETE FROM "${ftsTable(coll)}" WHERE doc_id = ?`).run(id);
+  const doc = db.collection(coll).getRaw(id);
+  if (!doc) return;
+  const cols = fields.map((_, i) => `"${col(i)}"`).join(", ");
+  const placeholders = fields.map(() => "?").join(", ");
+  const values = fields.map((f) => extractText(doc, f));
+  sqlite.prepare(
+    `INSERT INTO "${ftsTable(coll)}"(doc_id, ${cols}) VALUES (?, ${placeholders})`
+  ).run(id, ...values);
+}
+function reindex(db, coll, fields) {
+  const sqlite = db.sqlite;
+  sqlite.exec(`DELETE FROM "${ftsTable(coll)}"`);
+  for (const doc of db.collection(coll).findManyCore({})) {
+    indexDoc(db, coll, fields, doc._id);
+  }
+}
+function search(db, coll, spec, query, opts) {
+  const fields = spec[coll.name];
+  if (!fields) {
+    throw new Error(
+      `Collection "${coll.name}" is not configured for full-text search`
+    );
+  }
+  const limit = opts?.limit ?? 50;
+  const rows = db.sqlite.prepare(
+    `SELECT doc_id, rank FROM "${ftsTable(coll.name)}" WHERE "${ftsTable(coll.name)}" MATCH ? ORDER BY rank LIMIT ?`
+  ).all(query, limit);
+  let allowed = null;
+  if (opts?.where) {
+    const ids = rows.map((r) => r.doc_id);
+    const idIn = { _id: { in: ids } };
+    const matching = coll.findManyCore({
+      where: { AND: [opts.where, idIn] }
+    });
+    allowed = new Set(matching.map((d) => d._id));
+  }
+  const out = [];
+  for (const r of rows) {
+    if (allowed && !allowed.has(r.doc_id)) continue;
+    const doc = coll.getRaw(r.doc_id);
+    if (doc) out.push({ ...doc, _score: -r.rank });
+  }
+  return Promise.resolve(out);
+}
+function fts(spec) {
+  let database;
+  return {
+    name: "fts",
+    init(db) {
+      database = db;
+      for (const [coll, fields] of Object.entries(spec)) {
+        const cols = fields.map((_, i) => `"${col(i)}"`).join(", ");
+        db.sqlite.exec(
+          `CREATE VIRTUAL TABLE IF NOT EXISTS "${ftsTable(coll)}" USING fts5(doc_id UNINDEXED, ${cols})`
+        );
+        const count = db.sqlite.prepare(`SELECT count(*) AS n FROM "${ftsTable(coll)}"`).get();
+        if (count.n === 0) reindex(db, coll, fields);
+      }
+    },
+    afterWrite(db, { collection, ids }) {
+      const fields = spec[collection];
+      if (!fields) return;
+      for (const id of ids) indexDoc(db, collection, fields, id);
+    },
+    collectionMethods: {
+      search: (collection, query, opts) => search(database, collection, spec, query, opts)
+    }
+  };
+}
+
+export { fts, reindex };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";AA4BA,IAAM,QAAA,GAAW,CAAC,IAAA,KAAiB,CAAA,EAAG,IAAI,CAAA,IAAA,CAAA;AAC1C,IAAM,GAAA,GAAM,CAAC,CAAA,KAAc,CAAA,CAAA,EAAI,CAAC,CAAA,CAAA;AAGhC,SAAS,WAAA,CAAY,KAA0B,IAAA,EAAsB;AACnE,EAAA,IAAI,GAAA,GAAW,GAAA;AACf,EAAA,KAAA,MAAW,GAAA,IAAO,IAAA,CAAK,KAAA,CAAM,GAAG,CAAA,EAAG;AACjC,IAAA,IAAI,GAAA,IAAO,MAAM,OAAO,EAAA;AACxB,IAAA,GAAA,GAAM,IAAI,GAAG,CAAA;AAAA,EACf;AACA,EAAA,IAAI,GAAA,IAAO,MAAM,OAAO,EAAA;AACxB,EAAA,IAAI,OAAO,GAAA,KAAQ,QAAA,EAAU,OAAO,GAAA;AACpC,EAAA,IAAI,KAAA,CAAM,QAAQ,GAAG,CAAA;AACnB,IAAA,OAAO,GAAA,CACJ,MAAA,CAAO,CAAC,CAAA,KAAM,CAAA,IAAK,IAAI,CAAA,CACvB,GAAA,CAAI,MAAM,CAAA,CACV,IAAA,CAAK,GAAG,CAAA;AACb,EAAA,IAAI,OAAO,QAAQ,QAAA,IAAY,OAAO,QAAQ,SAAA,EAAW,OAAO,OAAO,GAAG,CAAA;AAC1E,EAAA,OAAO,EAAA;AACT;AAEA,SAAS,QAAA,CACP,EAAA,EACA,IAAA,EACA,MAAA,EACA,EAAA,EACM;AACN,EAAA,MAAM,SAAS,EAAA,CAAG,MAAA;AAClB,EAAA,MAAA,CAAO,OAAA,CAAQ,gBAAgB,QAAA,CAAS,IAAI,CAAC,CAAA,kBAAA,CAAoB,CAAA,CAAE,IAAI,EAAE,CAAA;AACzE,EAAA,MAAM,MAAM,EAAA,CAAG,UAAA,CAAW,IAAI,CAAA,CAAE,OAAO,EAAE,CAAA;AACzC,EAAA,IAAI,CAAC,GAAA,EAAK;AACV,EAAA,MAAM,IAAA,GAAO,MAAA,CAAO,GAAA,CAAI,CAAC,CAAA,EAAG,CAAA,KAAM,CAAA,CAAA,EAAI,GAAA,CAAI,CAAC,CAAC,CAAA,CAAA,CAAG,CAAA,CAAE,KAAK,IAAI,CAAA;AAC1D,EAAA,MAAM,eAAe,MAAA,CAAO,GAAA,CAAI,MAAM,GAAG,CAAA,CAAE,KAAK,IAAI,CAAA;AACpD,EAAA,MAAM,MAAA,GAAS,OAAO,GAAA,CAAI,CAAC,MAAM,WAAA,CAAY,GAAA,EAAK,CAAC,CAAC,CAAA;AACpD,EAAA,MAAA,CACG,OAAA;AAAA,IACC,gBAAgB,QAAA,CAAS,IAAI,CAAC,CAAA,UAAA,EAAa,IAAI,gBAAgB,YAAY,CAAA,CAAA;AAAA,GAC7E,CACC,GAAA,CAAI,EAAA,EAAI,GAAG,MAAM,CAAA;AACtB;AAGO,SAAS,OAAA,CAAQ,EAAA,EAAa,IAAA,EAAc,MAAA,EAAwB;AACzE,EAAA,MAAM,SAAS,EAAA,CAAG,MAAA;AAClB,EAAA,MAAA,CAAO,IAAA,CAAK,CAAA,aAAA,EAAgB,QAAA,CAAS,IAAI,CAAC,CAAA,CAAA,CAAG,CAAA;AAC7C,EAAA,KAAA,MAAW,GAAA,IAAO,GAAG,UAAA,CAAW,IAAI,EAAE,YAAA,CAAa,EAAE,CAAA,EAAG;AACtD,IAAA,QAAA,CAAS,EAAA,EAAI,IAAA,EAAM,MAAA,EAAS,GAAA,CAAoB,GAAG,CAAA;AAAA,EACrD;AACF;AAEA,SAAS,MAAA,CACP,EAAA,EACA,IAAA,EACA,IAAA,EACA,OACA,IAAA,EAC4B;AAC5B,EAAA,MAAM,MAAA,GAAS,IAAA,CAAK,IAAA,CAAK,IAAI,CAAA;AAC7B,EAAA,IAAI,CAAC,MAAA,EAAQ;AACX,IAAA,MAAM,IAAI,KAAA;AAAA,MACR,CAAA,YAAA,EAAe,KAAK,IAAI,CAAA,wCAAA;AAAA,KAC1B;AAAA,EACF;AACA,EAAA,MAAM,KAAA,GAAQ,MAAM,KAAA,IAAS,EAAA;AAC7B,EAAA,MAAM,IAAA,GAAO,GAAG,MAAA,CACb,OAAA;AAAA,IACC,CAAA,0BAAA,EAA6B,SAAS,IAAA,CAAK,IAAI,CAAC,CAAA,SAAA,EACpC,QAAA,CAAS,IAAA,CAAK,IAAI,CAAC,CAAA,+BAAA;AAAA,GACjC,CACC,GAAA,CAAI,KAAA,EAAO,KAAK,CAAA;AAEnB,EAAA,IAAI,OAAA,GAA8B,IAAA;AAClC,EAAA,IAAI,MAAM,KAAA,EAAO;AACf,IAAA,MAAM,MAAM,IAAA,CAAK,GAAA,CAAI,CAAC,CAAA,KAAM,EAAE,MAAM,CAAA;AACpC,IAAA,MAAM,OAAO,EAAE,GAAA,EAAK,EAAE,EAAA,EAAI,KAAI,EAAE;AAChC,IAAA,MAAM,QAAA,GAAW,KAAK,YAAA,CAAa;AAAA,MACjC,OAAO,EAAE,GAAA,EAAK,CAAC,IAAA,CAAK,KAAA,EAAO,IAAI,CAAA;AAAE,KAClC,CAAA;AACD,IAAA,OAAA,GAAU,IAAI,IAAI,QAAA,CAAS,GAAA,CAAI,CAAC,CAAA,KAAM,CAAA,CAAE,GAAG,CAAC,CAAA;AAAA,EAC9C;AAEA,EAAA,MAAM,MAAyB,EAAC;AAChC,EAAA,KAAA,MAAW,KAAK,IAAA,EAAM;AACpB,IAAA,IAAI,WAAW,CAAC,OAAA,CAAQ,GAAA,CAAI,CAAA,CAAE,MAAM,CAAA,EAAG;AACvC,IAAA,MAAM,GAAA,GAAM,IAAA,CAAK,MAAA,CAAO,CAAA,CAAE,MAAM,CAAA;AAChC,IAAA,IAAI,GAAA,EAAK,GAAA,CAAI,IAAA,CAAK,EAAE,GAAG,KAAK,MAAA,EAAQ,CAAC,CAAA,CAAE,IAAA,EAAyB,CAAA;AAAA,EAClE;AACA,EAAA,OAAO,OAAA,CAAQ,QAAQ,GAAG,CAAA;AAC5B;AAYO,SAAS,IAAI,IAAA,EAA8B;AAChD,EAAA,IAAI,QAAA;AACJ,EAAA,OAAO;AAAA,IACL,IAAA,EAAM,KAAA;AAAA,IACN,KAAK,EAAA,EAAI;AACP,MAAA,QAAA,GAAW,EAAA;AACX,MAAA,KAAA,MAAW,CAAC,IAAA,EAAM,MAAM,KAAK,MAAA,CAAO,OAAA,CAAQ,IAAI,CAAA,EAAG;AACjD,QAAA,MAAM,IAAA,GAAO,MAAA,CAAO,GAAA,CAAI,CAAC,CAAA,EAAG,CAAA,KAAM,CAAA,CAAA,EAAI,GAAA,CAAI,CAAC,CAAC,CAAA,CAAA,CAAG,CAAA,CAAE,KAAK,IAAI,CAAA;AAC1D,QAAA,EAAA,CAAG,MAAA,CAAO,IAAA;AAAA,UACR,CAAA,oCAAA,EAAuC,QAAA,CAAS,IAAI,CAAC,kCACnB,IAAI,CAAA,CAAA;AAAA,SACxC;AAEA,QAAA,MAAM,KAAA,GAAQ,EAAA,CAAG,MAAA,CACd,OAAA,CAAQ,CAAA,2BAAA,EAA8B,SAAS,IAAI,CAAC,CAAA,CAAA,CAAG,CAAA,CACvD,GAAA,EAAI;AACP,QAAA,IAAI,MAAM,CAAA,KAAM,CAAA,EAAG,OAAA,CAAQ,EAAA,EAAI,MAAM,MAAM,CAAA;AAAA,MAC7C;AAAA,IACF,CAAA;AAAA,IACA,UAAA,CAAW,EAAA,EAAI,EAAE,UAAA,EAAY,KAAI,EAAG;AAClC,MAAA,MAAM,MAAA,GAAS,KAAK,UAAU,CAAA;AAC9B,MAAA,IAAI,CAAC,MAAA,EAAQ;AACb,MAAA,KAAA,MAAW,MAAM,GAAA,EAAK,QAAA,CAAS,EAAA,EAAI,UAAA,EAAY,QAAQ,EAAE,CAAA;AAAA,IAC3D,CAAA;AAAA,IACA,iBAAA,EAAmB;AAAA,MACjB,MAAA,EAAQ,CAAC,UAAA,EAAY,KAAA,EAAe,IAAA,KAClC,OAAO,QAAA,EAAU,UAAA,EAAY,IAAA,EAAM,KAAA,EAAO,IAAI;AAAA;AAClD,GACF;AACF","file":"index.js","sourcesContent":["import type {\n  Collection,\n  Doc,\n  Monlite,\n  MonlitePlugin,\n  WhereInput,\n  WithId,\n} from \"@monlite/core\";\n\n/** Map of collection name → searchable field paths (dot-notation allowed). */\nexport type FtsSpec = Record<string, string[]>;\n\nexport interface SearchOptions<T = Doc> {\n  /** Max results (default 50). */\n  limit?: number;\n  /** Additionally constrain matches with a normal monlite where clause. */\n  where?: WhereInput<T>;\n}\n\nexport type SearchResult<T = Doc> = WithId<T> & { _score: number };\n\n// Make `collection.search()` typed wherever @monlite/fts is imported.\ndeclare module \"@monlite/core\" {\n  interface Collection<T> {\n    search(query: string, opts?: SearchOptions<T>): Promise<SearchResult<T>[]>;\n  }\n}\n\nconst ftsTable = (coll: string) => `${coll}_fts`;\nconst col = (i: number) => `f${i}`;\n\n/** Extract searchable text for a field path from a document. */\nfunction extractText(doc: Record<string, any>, path: string): string {\n  let cur: any = doc;\n  for (const seg of path.split(\".\")) {\n    if (cur == null) return \"\";\n    cur = cur[seg];\n  }\n  if (cur == null) return \"\";\n  if (typeof cur === \"string\") return cur;\n  if (Array.isArray(cur))\n    return cur\n      .filter((x) => x != null)\n      .map(String)\n      .join(\" \");\n  if (typeof cur === \"number\" || typeof cur === \"boolean\") return String(cur);\n  return \"\";\n}\n\nfunction indexDoc(\n  db: Monlite,\n  coll: string,\n  fields: string[],\n  id: string,\n): void {\n  const sqlite = db.sqlite;\n  sqlite.prepare(`DELETE FROM \"${ftsTable(coll)}\" WHERE doc_id = ?`).run(id);\n  const doc = db.collection(coll).getRaw(id);\n  if (!doc) return; // deleted\n  const cols = fields.map((_, i) => `\"${col(i)}\"`).join(\", \");\n  const placeholders = fields.map(() => \"?\").join(\", \");\n  const values = fields.map((f) => extractText(doc, f));\n  sqlite\n    .prepare(\n      `INSERT INTO \"${ftsTable(coll)}\"(doc_id, ${cols}) VALUES (?, ${placeholders})`,\n    )\n    .run(id, ...values);\n}\n\n/** Rebuild a collection's FTS index from scratch. */\nexport function reindex(db: Monlite, coll: string, fields: string[]): void {\n  const sqlite = db.sqlite;\n  sqlite.exec(`DELETE FROM \"${ftsTable(coll)}\"`);\n  for (const doc of db.collection(coll).findManyCore({})) {\n    indexDoc(db, coll, fields, (doc as WithId<Doc>)._id);\n  }\n}\n\nfunction search<T = Doc>(\n  db: Monlite,\n  coll: Collection<T>,\n  spec: FtsSpec,\n  query: string,\n  opts?: SearchOptions<T>,\n): Promise<SearchResult<T>[]> {\n  const fields = spec[coll.name];\n  if (!fields) {\n    throw new Error(\n      `Collection \"${coll.name}\" is not configured for full-text search`,\n    );\n  }\n  const limit = opts?.limit ?? 50;\n  const rows = db.sqlite\n    .prepare(\n      `SELECT doc_id, rank FROM \"${ftsTable(coll.name)}\" ` +\n        `WHERE \"${ftsTable(coll.name)}\" MATCH ? ORDER BY rank LIMIT ?`,\n    )\n    .all(query, limit) as Array<{ doc_id: string; rank: number }>;\n\n  let allowed: Set<string> | null = null;\n  if (opts?.where) {\n    const ids = rows.map((r) => r.doc_id);\n    const idIn = { _id: { in: ids } } as WhereInput<T>;\n    const matching = coll.findManyCore({\n      where: { AND: [opts.where, idIn] } as WhereInput<T>,\n    });\n    allowed = new Set(matching.map((d) => d._id));\n  }\n\n  const out: SearchResult<T>[] = [];\n  for (const r of rows) {\n    if (allowed && !allowed.has(r.doc_id)) continue;\n    const doc = coll.getRaw(r.doc_id);\n    if (doc) out.push({ ...doc, _score: -r.rank } as SearchResult<T>);\n  }\n  return Promise.resolve(out);\n}\n\n/**\n * Full-text search plugin (SQLite FTS5). Pass it to `createDb({ plugins: [...] })`\n * with a map of collection → searchable fields. Adds `collection.search()`, keeps\n * the index in sync on every write, and backfills existing documents on open.\n *\n * ```ts\n * const db = createDb(\"./app.db\", { plugins: [fts({ posts: [\"title\", \"body\"] })] });\n * await db.collection(\"posts\").search(\"hello world\");\n * ```\n */\nexport function fts(spec: FtsSpec): MonlitePlugin {\n  let database: Monlite;\n  return {\n    name: \"fts\",\n    init(db) {\n      database = db;\n      for (const [coll, fields] of Object.entries(spec)) {\n        const cols = fields.map((_, i) => `\"${col(i)}\"`).join(\", \");\n        db.sqlite.exec(\n          `CREATE VIRTUAL TABLE IF NOT EXISTS \"${ftsTable(coll)}\" ` +\n            `USING fts5(doc_id UNINDEXED, ${cols})`,\n        );\n        // Backfill when the index is empty (e.g. enabling FTS on an existing db).\n        const count = db.sqlite\n          .prepare(`SELECT count(*) AS n FROM \"${ftsTable(coll)}\"`)\n          .get() as { n: number };\n        if (count.n === 0) reindex(db, coll, fields);\n      }\n    },\n    afterWrite(db, { collection, ids }) {\n      const fields = spec[collection];\n      if (!fields) return;\n      for (const id of ids) indexDoc(db, collection, fields, id);\n    },\n    collectionMethods: {\n      search: (collection, query: string, opts?: SearchOptions) =>\n        search(database, collection, spec, query, opts),\n    },\n  };\n}\n"]}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@monlite/fts",
+  "version": "0.1.0",
+  "description": "Full-text search for @monlite/core, powered by SQLite FTS5. Adds collection.search().",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "monlite",
+    "fts",
+    "fts5",
+    "full-text-search",
+    "sqlite",
+    "search"
+  ],
+  "license": "MIT",
+  "author": "Emad Jumaah <emadjumaah@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/qataruts/monlite.git",
+    "directory": "packages/fts"
+  },
+  "homepage": "https://github.com/qataruts/monlite/tree/main/packages/fts#readme",
+  "bugs": {
+    "url": "https://github.com/qataruts/monlite/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@monlite/core": "^0.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "better-sqlite3": "^11.8.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}