libsql-search 0.11.0 → 0.11.1

package/dist/turso.cjs

@@ -1,8 +1,65 @@
 'use strict';
 
+const MAX_QUERY_STATEMENT_CACHE_SIZE = 32;
 function tursoAdapter(database) {
   assertTursoDatabase(database);
-  return {
+  const queryStatementsBySql = /* @__PURE__ */ new Map();
+  const liveQueryStatements = /* @__PURE__ */ new Set();
+  let disposed = false;
+  let disposePromise;
+  const assertUsable = () => {
+    if (disposed) {
+      throw new Error("This Turso adapter has been disposed");
+    }
+  };
+  const closeQueryStatement = (entry) => {
+    entry.closePromise ??= closeStatement(entry.statement).finally(() => {
+      liveQueryStatements.delete(entry);
+    });
+    return entry.closePromise;
+  };
+  const retireQueryStatement = (entry) => {
+    if (queryStatementsBySql.get(entry.sql) === entry) {
+      queryStatementsBySql.delete(entry.sql);
+    }
+    entry.retired = true;
+    if (entry.pending === 0) {
+      void closeQueryStatement(entry);
+    }
+  };
+  const acquireQueryStatement = (sql) => {
+    assertUsable();
+    let entry = queryStatementsBySql.get(sql);
+    if (entry === void 0) {
+      entry = {
+        sql,
+        statement: database.prepare(sql),
+        tail: Promise.resolve(),
+        pending: 0,
+        retired: false
+      };
+      queryStatementsBySql.set(sql, entry);
+      liveQueryStatements.add(entry);
+      if (queryStatementsBySql.size > MAX_QUERY_STATEMENT_CACHE_SIZE) {
+        const oldest = queryStatementsBySql.values().next().value;
+        if (oldest !== void 0) {
+          retireQueryStatement(oldest);
+        }
+      }
+    } else {
+      queryStatementsBySql.delete(sql);
+      queryStatementsBySql.set(sql, entry);
+    }
+    entry.pending += 1;
+    const turn = entry.tail;
+    let release;
+    const completion = new Promise((resolve) => {
+      release = resolve;
+    });
+    entry.tail = turn.then(() => completion);
+    return { entry, turn, release };
+  };
+  const adapter = {
     libsqlSearchAdapter: true,
     backend: "turso",
     /**
@@ -12,15 +69,24 @@ function tursoAdapter(database) {
      */
     supportsVectorIndex: false,
     async executeDdl(sql) {
+      assertUsable();
       await database.exec(sql);
     },
     async executeQuery(sql, args) {
-      const statement = database.prepare(sql);
+      const { entry, turn, release } = acquireQueryStatement(sql);
+      await turn;
       try {
-        const rows = await (args === void 0 ? statement.all() : statement.all(args));
+        const rows = await (args === void 0 ? entry.statement.all() : entry.statement.all(args));
         return rows;
+      } catch (error) {
+        retireQueryStatement(entry);
+        throw error;
       } finally {
-        closeStatement(statement);
+        entry.pending -= 1;
+        release();
+        if (entry.retired && entry.pending === 0) {
+          await closeQueryStatement(entry);
+        }
       }
     },
     /**
@@ -37,6 +103,7 @@ function tursoAdapter(database) {
      * this turns N+1 prepares into exactly 2 regardless of corpus size.
      */
     async executeAtomicWrite(statements) {
+      assertUsable();
       const preparedBySql = /* @__PURE__ */ new Map();
       const prepareOnce = (sql) => {
         let prepared = preparedBySql.get(sql);
@@ -62,16 +129,32 @@ function tursoAdapter(database) {
         throw error;
       } finally {
         for (const prepared of preparedBySql.values()) {
-          closeStatement(prepared);
+          await closeStatement(prepared);
         }
         preparedBySql.clear();
       }
+    },
+    dispose() {
+      disposePromise ??= (async () => {
+        disposed = true;
+        for (const entry of [...queryStatementsBySql.values()]) {
+          retireQueryStatement(entry);
+        }
+        await Promise.all(
+          [...liveQueryStatements].map(async (entry) => {
+            await entry.tail;
+            await closeQueryStatement(entry);
+          })
+        );
+      })();
+      return disposePromise;
     }
   };
+  return adapter;
 }
-function closeStatement(statement) {
+async function closeStatement(statement) {
   try {
-    statement.close?.();
+    await statement.close?.();
   } catch {
   }
 }

package/dist/turso.d.ts

@@ -86,11 +86,21 @@ interface DatabaseAdapter {
  * import { tursoAdapter } from 'libsql-search/turso';
  * import { createTable, indexContent, search } from 'libsql-search';
  *
- * const client = tursoAdapter(await connect('./local.db'));
+ * const database = await connect('./local.db');
+ * const client = tursoAdapter(database);
+ * const embeddingOptions = {
+ *   provider: 'openai-compatible' as const,
+ *   baseUrl: 'https://embeddings.example.com/v1',
+ *   model: 'bge-large-en-v1.5',
+ *   dimensions: 1024
+ * };
  *
- * await createTable(client);
- * await indexContent({ client, contentPath: './content' });
- * const results = await search({ client, query: 'vector search' });
+ * await createTable(client, 'articles', 1024);
+ * await indexContent({ client, contentPath: './content', embeddingOptions });
+ * const results = await search({ client, query: 'vector search', embeddingOptions });
+ *
+ * await client.dispose();
+ * await database.close();
  * ```
  *
  * @module libsql-search/turso
@@ -113,8 +123,9 @@ interface TursoStatement {
      *
      * Not closing leaks roughly 10 KB of native memory per prepare on
      * `@tursodatabase/database`, which the garbage collector does not reclaim
-     * because it is not JavaScript heap. A server calling `search()` per request
-     * grows without bound until the process is killed.
+     * because it is not JavaScript heap. The adapter therefore closes
+     * transaction-local statements immediately and query statements on safe LRU
+     * eviction or disposal.
      */
     close?(): unknown;
 }
@@ -130,6 +141,16 @@ interface TursoDatabase {
     exec(sql: string): unknown;
     prepare(sql: string): TursoStatement;
 }
+/**
+ * A Turso-backed adapter with an explicit prepared-statement disposal hook.
+ *
+ * `dispose()` is terminal: it waits for queued query calls, closes every
+ * cached query statement, and rejects later adapter operations. It does not
+ * close the caller-owned {@link TursoDatabase} handle.
+ */
+interface TursoAdapter extends DatabaseAdapter {
+    dispose(): Promise<void>;
+}
 /**
  * Wrap a `@tursodatabase/database` handle so this library's functions can use
  * it.
@@ -150,7 +171,7 @@ interface TursoDatabase {
  *   This preserves the guarantee that a failed rebuild leaves the previous
  *   index intact.
  */
-declare function tursoAdapter(database: TursoDatabase): DatabaseAdapter;
+declare function tursoAdapter(database: TursoDatabase): TursoAdapter;
 
 export { tursoAdapter };
-export type { DatabaseAdapter, TursoDatabase, TursoStatement };
+export type { DatabaseAdapter, TursoAdapter, TursoDatabase, TursoStatement };

package/dist/turso.esm.js

@@ -1,6 +1,63 @@
+const MAX_QUERY_STATEMENT_CACHE_SIZE = 32;
 function tursoAdapter(database) {
   assertTursoDatabase(database);
-  return {
+  const queryStatementsBySql = /* @__PURE__ */ new Map();
+  const liveQueryStatements = /* @__PURE__ */ new Set();
+  let disposed = false;
+  let disposePromise;
+  const assertUsable = () => {
+    if (disposed) {
+      throw new Error("This Turso adapter has been disposed");
+    }
+  };
+  const closeQueryStatement = (entry) => {
+    entry.closePromise ??= closeStatement(entry.statement).finally(() => {
+      liveQueryStatements.delete(entry);
+    });
+    return entry.closePromise;
+  };
+  const retireQueryStatement = (entry) => {
+    if (queryStatementsBySql.get(entry.sql) === entry) {
+      queryStatementsBySql.delete(entry.sql);
+    }
+    entry.retired = true;
+    if (entry.pending === 0) {
+      void closeQueryStatement(entry);
+    }
+  };
+  const acquireQueryStatement = (sql) => {
+    assertUsable();
+    let entry = queryStatementsBySql.get(sql);
+    if (entry === void 0) {
+      entry = {
+        sql,
+        statement: database.prepare(sql),
+        tail: Promise.resolve(),
+        pending: 0,
+        retired: false
+      };
+      queryStatementsBySql.set(sql, entry);
+      liveQueryStatements.add(entry);
+      if (queryStatementsBySql.size > MAX_QUERY_STATEMENT_CACHE_SIZE) {
+        const oldest = queryStatementsBySql.values().next().value;
+        if (oldest !== void 0) {
+          retireQueryStatement(oldest);
+        }
+      }
+    } else {
+      queryStatementsBySql.delete(sql);
+      queryStatementsBySql.set(sql, entry);
+    }
+    entry.pending += 1;
+    const turn = entry.tail;
+    let release;
+    const completion = new Promise((resolve) => {
+      release = resolve;
+    });
+    entry.tail = turn.then(() => completion);
+    return { entry, turn, release };
+  };
+  const adapter = {
     libsqlSearchAdapter: true,
     backend: "turso",
     /**
@@ -10,15 +67,24 @@ function tursoAdapter(database) {
      */
     supportsVectorIndex: false,
     async executeDdl(sql) {
+      assertUsable();
       await database.exec(sql);
     },
     async executeQuery(sql, args) {
-      const statement = database.prepare(sql);
+      const { entry, turn, release } = acquireQueryStatement(sql);
+      await turn;
       try {
-        const rows = await (args === void 0 ? statement.all() : statement.all(args));
+        const rows = await (args === void 0 ? entry.statement.all() : entry.statement.all(args));
         return rows;
+      } catch (error) {
+        retireQueryStatement(entry);
+        throw error;
       } finally {
-        closeStatement(statement);
+        entry.pending -= 1;
+        release();
+        if (entry.retired && entry.pending === 0) {
+          await closeQueryStatement(entry);
+        }
       }
     },
     /**
@@ -35,6 +101,7 @@ function tursoAdapter(database) {
      * this turns N+1 prepares into exactly 2 regardless of corpus size.
      */
     async executeAtomicWrite(statements) {
+      assertUsable();
       const preparedBySql = /* @__PURE__ */ new Map();
       const prepareOnce = (sql) => {
         let prepared = preparedBySql.get(sql);
@@ -60,16 +127,32 @@ function tursoAdapter(database) {
         throw error;
       } finally {
         for (const prepared of preparedBySql.values()) {
-          closeStatement(prepared);
+          await closeStatement(prepared);
         }
         preparedBySql.clear();
       }
+    },
+    dispose() {
+      disposePromise ??= (async () => {
+        disposed = true;
+        for (const entry of [...queryStatementsBySql.values()]) {
+          retireQueryStatement(entry);
+        }
+        await Promise.all(
+          [...liveQueryStatements].map(async (entry) => {
+            await entry.tail;
+            await closeQueryStatement(entry);
+          })
+        );
+      })();
+      return disposePromise;
     }
   };
+  return adapter;
 }
-function closeStatement(statement) {
+async function closeStatement(statement) {
   try {
-    statement.close?.();
+    await statement.close?.();
   } catch {
   }
 }

package/docs/TURSO.md

@@ -65,6 +65,11 @@ const results = await search({
   limit: 5,
   embeddingOptions,
 });
+
+// When this adapter's lifetime ends, drain and close its cached statements
+// before closing the caller-owned database handle.
+await client.dispose();
+await database.close();
 ```
 
 Use `":memory:"` instead of a file path for an ephemeral database.
@@ -74,6 +79,29 @@ Use `":memory:"` instead of a file path for an ephemeral database.
 result shapes — `SearchOptions`, `SearchResult`, `IndexerOptions`,
 `IndexResult` — are identical on both backends.
 
+### Adapter lifetime and disposal
+
+One adapter caches up to **32 query statements**, keyed by SQL and evicted in
+least-recently-used order. The bound matters because public `tableName` options
+are embedded in SQL: an unbounded cache would let a long-lived process retain a
+new native statement for every valid table name it sees. Statements that are
+currently running or queued are closed after they finish rather than being
+evicted out from under a call.
+
+Call `await client.dispose()` after all work using that adapter has settled.
+Disposal drains queued query calls and closes every cached statement, but does
+**not** close the database handle you supplied. It is terminal: later calls on
+that adapter reject. Close the database separately, after disposal. If you omit
+disposal, the reusable cache is still bounded at 32 entries and lives until the
+underlying handle or process exits; statements evicted while in flight live
+only until their queued calls finish.
+
+The adapter serializes concurrent calls that share one cached statement. This
+is required for correctness, not just memory use: the native statement mutates
+its current bindings, so overlapping `all()` calls with different arguments can
+otherwise return another caller's rows. Different cached SQL statements remain
+independent.
+
 ## What is different on Turso
 
 ### There is no ANN vector index, so search is a full scan
@@ -192,13 +220,14 @@ point is still type-checked by `deno task check` so the claim above stays true.
 unchanged, and the main entry point exports no new symbol and references no
 Turso type.
 
-`tursoAdapter()` returns a `DatabaseAdapter`, and that type is exported from
-`libsql-search/turso` so you can name it:
+`tursoAdapter()` returns a `TursoAdapter`, which extends `DatabaseAdapter` with
+the disposal hook. Both types are exported from `libsql-search/turso` so you can
+name them:
 
 ```ts
-import { tursoAdapter, type DatabaseAdapter } from "libsql-search/turso";
+import { tursoAdapter, type TursoAdapter } from "libsql-search/turso";
 
-let client: DatabaseAdapter;
+let client: TursoAdapter;
 ```
 
 It is exported from the subpath only. The main entry point does not export it,
@@ -217,15 +246,18 @@ to prove the two stay interchangeable, and runs as part of
 Three things in `src/turso.ts` look like noise and are not. Each has a
 regression test; none of them fails loudly at runtime if removed.
 
-**Prepared statements must be closed.** A statement holds native memory that the
-garbage collector cannot reclaim, because it is not JavaScript heap. Every
-`prepare()` is released with `close()` in a `finally`. Measured through the
-built bundle, 60 000 `executeQuery()` calls on one handle grow RSS by ~570 MB
-without the close and ~150 MB with it. `search()` issues exactly one query, so
-an SSR site calling it per request is the case that turns this from untidy into
-an OOM. Inside `executeAtomicWrite()` the cached statements are released only
-*after* `COMMIT` or `ROLLBACK` — a statement stays bound to the transaction
-while it is open.
+**Prepared statements are bounded, serialized, and explicitly disposed.** A
+statement holds native memory that the garbage collector cannot reclaim,
+because it is not JavaScript heap. The query path therefore reuses a 32-entry
+LRU instead of preparing on every request, serializes rebinds per entry, and
+closes evictions only after their queued calls finish. `TursoAdapter.dispose()`
+drains and closes the remaining cache. Measured through the built bundle,
+60 000 `executeQuery()` calls grew RSS by ~570 MB when statements were never
+closed, ~150 MB when each call prepared and closed, and ~7 MB when one statement
+was reused. `search()` issues exactly one query, so the SSR-per-request path is
+where reuse matters most. Inside `executeAtomicWrite()` the transaction-local
+statements are still released only *after* `COMMIT` or `ROLLBACK` — a statement
+stays bound to the transaction while it is open.
 
 **`BEGIN IMMEDIATE` sits outside the `try`.** If it were inside, a `BEGIN` that
 fails because another rebuild already holds the write lock would fall into the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libsql-search",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "description": "Semantic search for static sites using libSQL/Turso with multi-provider embeddings",
   "type": "module",
   "packageManager": "pnpm@10.34.5",