libsql-search 0.10.1 → 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/API.md

@@ -113,7 +113,7 @@ Indexes Markdown files from a directory on disk.
 interface IndexerOptions {
   client: Client | DatabaseAdapter;
   contentPath: string;
-  embeddingOptions?: EmbeddingOptions;
+  embeddingOptions: EmbeddingOptions;
   fileExtensions?: string[];
   exclude?: string[];
   tableName?: string;
@@ -187,7 +187,16 @@ class IndexingError extends Error {
 import { indexContent, IndexingError } from "libsql-search";
 
 try {
-  await indexContent({ client, contentPath: "./content" });
+  await indexContent({
+    client,
+    contentPath: "./content",
+    embeddingOptions: {
+      provider: "openai-compatible",
+      baseUrl: process.env.EMBEDDING_BASE_URL!,
+      model: "bge-large-en-v1.5",
+      dimensions: 1024,
+    },
+  });
 } catch (error) {
   if (error instanceof IndexingError) {
     console.error(error.phase, error.failures);
@@ -212,7 +221,7 @@ interface SearchOptions {
   query: string;
   limit?: number;
   tableName?: string;
-  embeddingOptions?: EmbeddingOptions;
+  embeddingOptions: EmbeddingOptions;
   candidates?: number;
   exact?: boolean;
 }
@@ -246,7 +255,7 @@ Controls how many rows the index returns for the exact re-rank. It must be an in
 
 ```ts
 // Trade query cost for recall on a large corpus
-const results = await search({ client, query, limit: 10, candidates: 200 });
+const results = await search({ client, query, embeddingOptions, limit: 10, candidates: 200 });
 ```
 
 `candidates` has no effect when `exact` is `true` — that path scans every row — but it is **still validated**. `search({ exact: true, limit: 10, candidates: 5 })` throws, exactly as it would on the index path. Validity does not depend on which path a call happens to take.
@@ -262,7 +271,7 @@ Related exported constants:
 Set `exact: true` to bypass the index and score every row in the table.
 
 ```ts
-const results = await search({ client, query, exact: true });
+const results = await search({ client, query, embeddingOptions, exact: true });
 ```
 
 This is the guaranteed-exact path: it computes `vector_distance_cos` for every row with a non-`NULL` embedding, sorts by `(distance, id)`, and trims to `limit`. Cost grows linearly with table size, so it is intended for small corpora, correctness checks against the index path, and tables that have no vector index.
@@ -330,8 +339,7 @@ All retrieval helpers validate `tableName` before executing SQL, and all of them
 
 ```ts
 interface EmbeddingOptions {
-  provider?:
-    | "local"
+  provider:
     | "cloudflare"
     | "mistral"
     | "gemini"
@@ -353,7 +361,7 @@ interface EmbeddingOptions {
 
 Important option rules:
 
-- `provider` defaults to `local`
+- `provider` is required; every provider is an external service
 - `maxLength` defaults to `8000`
 - `timeoutMs` defaults to `30000`
 - `model` is only used by `openai-compatible`
@@ -364,7 +372,6 @@ Important option rules:
 
 Dimension rules:
 
-- local: fixed `384`
 - Cloudflare: fixed `1024`
 - Mistral: fixed `1024`
 - Gemini: default `3072`, allowed integer range `128-3072`
@@ -373,7 +380,7 @@ Dimension rules:
 
 See [Provider matrix and credential rules](./PROVIDERS.md) for the canonical provider table.
 
-### `generateEmbedding(text, options?)`
+### `generateEmbedding(text, options)`
 
 Generates one embedding vector.
 
@@ -385,15 +392,15 @@ const embedding = await generateEmbedding("deploy docs", {
 });
 ```
 
-### `generateEmbeddings(texts, options?)`
+### `generateEmbeddings(texts, options)`
 
 Generates an ordered batch of embeddings.
 
-- empty batches return `[]` without loading the local model or making a hosted call
+- empty batches return `[]` without configuring credentials or making a provider call
 - OpenAI batches above `2048` inputs are rejected before network work
 - `openai-compatible` batches are chunked sequentially according to `batchSize`
 
-### `createEmbeddingProvider(options?)`
+### `createEmbeddingProvider(options)`
 
 Creates a provider client with immutable metadata and an `embed(texts, options?)` method.
 
@@ -413,7 +420,7 @@ Provider clients return a rich `EmbeddingBatchResult`; the compatibility helpers
 
 Hosted provider clients are scoped to their current options. The library does not reuse a Cloudflare, Mistral, Gemini, or OpenAI client across different credential sets or configurations.
 
-### `getEmbeddingProviderMetadata(options?)`
+### `getEmbeddingProviderMetadata(options)`
 
 Returns the same metadata exposed by `createEmbeddingProvider(options).metadata` without resolving hosted-provider credentials.
 
@@ -422,7 +429,6 @@ Metadata shape:
 ```ts
 interface EmbeddingProviderMetadata {
   name:
-    | "local"
     | "cloudflare"
     | "mistral"
     | "gemini"
@@ -451,7 +457,6 @@ Batch interpretation:
 interface EmbeddingBatchResult {
   embeddings: number[][];
   provider:
-    | "local"
     | "cloudflare"
     | "mistral"
     | "gemini"
@@ -474,7 +479,7 @@ Validates provider responses before they reach the database:
 
 ### `padEmbedding(embedding, targetDimensions)`
 
-Pads or truncates a vector to the target width. This is exported for compatibility and migration workflows, but the current local provider uses its native `384` dimensions rather than padding by default.
+Pads or truncates a vector to the target width. This is exported for compatibility and migration workflows; provider adapters otherwise validate and preserve the vectors returned by their external service.
 
 ### `prepareTextForEmbedding(fields)`
 

package/docs/INDEXING.md

@@ -18,13 +18,18 @@ The slug is derived from the file path relative to `contentPath`.
 `indexContent()` replaces the whole target table:
 
 ```ts
+const embeddingOptions = {
+  provider: "openai-compatible" as const,
+  baseUrl: process.env.EMBEDDING_BASE_URL!,
+  model: "bge-large-en-v1.5",
+  dimensions: 1024,
+};
+
 await indexContent({
   client,
   contentPath: "./content",
-  tableName: "articles_local_384",
-  embeddingOptions: {
-    provider: "local",
-  },
+  tableName: "articles_bge_1024",
+  embeddingOptions,
 });
 ```
 
@@ -69,7 +74,7 @@ Both are governed by `failurePolicy` like any other build failure, so they abort
 import { indexContent, IndexingError } from "libsql-search";
 
 try {
-  await indexContent({ client, contentPath: "./content" });
+  await indexContent({ client, contentPath: "./content", embeddingOptions });
 } catch (error) {
   if (error instanceof IndexingError) {
     for (const failure of error.failures) {
@@ -87,6 +92,7 @@ By default one bad file aborts the whole rebuild. To index everything that can b
 const result = await indexContent({
   client,
   contentPath: "./content",
+  embeddingOptions,
   failurePolicy: "skip",
 });
 
@@ -105,6 +111,7 @@ An empty source directory throws by default, because silently leaving stale rows
 await indexContent({
   client,
   contentPath: "./content",
+  embeddingOptions,
   allowEmptyIndex: true,
 });
 ```
@@ -173,7 +180,6 @@ Many projects wire indexing into a dedicated script and call it before their sit
 
 ## Runtime Notes
 
-- local embeddings may download and cache a model on the first run
 - Node users need `@libsql/client` installed alongside the package, at `^0.15.0 || ^0.17.0`; the packaged build is smoke-tested against both arms (`0.15.15` and `0.17.4`), which covers table and vector-index creation. `batch()` rollback behaves identically on both at the contract level, though its error text differs — see [Version differences](./TROUBLESHOOTING.md#libsqlclient-version-differences). Upgrading the client is not a prerequisite for upgrading this package. Deno/JSR users are not covered by that range and should pin the client themselves — see [Install](../README.md#install)
-- hosted providers send indexed or queried text to external services
+- all embedding providers send indexed or queried text to external services; this library never loads a model in-process
 - the repository validates package build and `deno check`, but indexing still depends on filesystem access

package/docs/INTEGRATIONS.md

@@ -55,13 +55,6 @@ These presets keep credentials out of the source file while making dimensions an
 
 ```ts
 const providerPresets = {
-  local: {
-    tableName: "articles_local_384",
-    dimensions: 384,
-    embeddingOptions: {
-      provider: "local" as const,
-    },
-  },
   cloudflare: {
     tableName: "articles_cf_bgem3_1024",
     dimensions: 1024,
@@ -137,9 +130,13 @@ export const POST: APIRoute = async ({ request }) => {
     client,
     query,
     limit,
-    tableName: "articles_local_384",
+    tableName: "articles_tei_1024",
     embeddingOptions: {
-      provider: "local",
+      provider: "openai-compatible",
+      baseUrl: process.env.EMBEDDING_BASE_URL!,
+      model: process.env.EMBEDDING_MODEL!,
+      dimensions: 1024,
+      apiKey: process.env.EMBEDDING_API_KEY,
       intent: "query",
     },
   });
@@ -162,14 +159,14 @@ const client = createClient({
 });
 
 export async function getStaticPaths() {
-  const articles = await getAllArticles(client, "articles_local_384");
+  const articles = await getAllArticles(client, "articles_tei_1024");
 
   return articles.map((article) => ({
     params: { slug: article.slug },
   }));
 }
 
-const article = await getArticleBySlug(client, "guides/getting-started", "articles_local_384");
+const article = await getArticleBySlug(client, "guides/getting-started", "articles_tei_1024");
 ```
 
 ## Next.js Route Handler
@@ -191,9 +188,13 @@ export async function POST(request: NextRequest) {
     client,
     query,
     limit,
-    tableName: "articles_local_384",
+    tableName: "articles_tei_1024",
     embeddingOptions: {
-      provider: "local",
+      provider: "openai-compatible",
+      baseUrl: process.env.EMBEDDING_BASE_URL!,
+      model: process.env.EMBEDDING_MODEL!,
+      dimensions: 1024,
+      apiKey: process.env.EMBEDDING_API_KEY,
       intent: "query",
     },
   });
@@ -214,7 +215,7 @@ const client = createClient({
 });
 
 export async function generateStaticParams() {
-  const articles = await getAllArticles(client, "articles_local_384");
+  const articles = await getAllArticles(client, "articles_tei_1024");
 
   return articles.map((article) => ({
     slug: article.slug,
@@ -223,7 +224,7 @@ export async function generateStaticParams() {
 
 export default async function Page({ params }: { params: Promise<{ slug: string }> }) {
   const { slug } = await params;
-  const article = await getArticleBySlug(client, slug, "articles_local_384");
+  const article = await getArticleBySlug(client, slug, "articles_tei_1024");
 
   return <article>{article?.title}</article>;
 }
@@ -241,13 +242,6 @@ const client = createClient({
 });
 
 const providerPresets = {
-  local: {
-    tableName: "articles_local_384",
-    dimensions: 384,
-    embeddingOptions: {
-      provider: "local" as const,
-    },
-  },
   cloudflare: {
     tableName: "articles_cf_bgem3_1024",
     dimensions: 1024,
@@ -299,7 +293,7 @@ const providerPresets = {
   },
 } as const;
 
-const provider = process.env.EMBEDDING_PROVIDER ?? "local";
+const provider = process.env.EMBEDDING_PROVIDER ?? "openai-compatible";
 
 if (!(provider in providerPresets)) {
   throw new Error(
@@ -349,4 +343,4 @@ await generateEmbeddings(["doc one", "doc two"], {
 });
 ```
 
-The repository test suite should not require real provider credentials. See [Testing guidance](./TESTING.md) for local model mocks, Gemini SDK mocks, and validation-before-network assertions.
+The repository test suite should not require real provider credentials. See [Testing guidance](./TESTING.md) for embedding-service mocks, Gemini SDK mocks, and validation-before-network assertions.