@mirk/store 0.4.2 → 0.6.1

package/dist/sql.js

@@ -0,0 +1,14 @@
+import {
+  buildLimitOffset,
+  buildOrderBy,
+  buildWhereClause,
+  hashName,
+  jsonPath
+} from "./chunk-DP4D7CJY.js";
+export {
+  buildLimitOffset,
+  buildOrderBy,
+  buildWhereClause,
+  hashName,
+  jsonPath
+};

package/dist/{types-BqSZEMAB.d.ts → types-B0XrD10b.d.ts}

@@ -32,6 +32,13 @@ interface VectorSearchOptions {
     topK?: number;
     /** Minimum cosine similarity; results below are excluded. Default: no floor. */
     minScore?: number;
+    /** Pre-KNN filter: only consider documents whose metadata satisfies ALL of these
+     *  exact-match conditions. Applied before scoring, so topK is out of the passing
+     *  set only. `where` and `whereNot` are independent — both may be provided. */
+    where?: Record<string, unknown>;
+    /** Pre-KNN filter: exclude documents whose metadata satisfies ANY of these
+     *  exact-match conditions. Applied before scoring. */
+    whereNot?: Record<string, unknown>;
 }
 /** A synchronous vector similarity store with per-collection documents.
  *
@@ -46,12 +53,31 @@ interface VectorStore {
     upsertMany<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, docs: ReadonlyArray<VectorDocument<M>>): void;
     /** Fetch a document by id, or null. */
     get<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, id: string): VectorDocument<M> | null;
+    /** Check whether a document exists by (collection, id). */
+    has(collection: string, id: string): boolean;
     /** Remove a document by id. Returns true if it existed. */
     remove(collection: string, id: string): boolean;
     /** Number of documents in a collection. */
     count(collection: string): number;
-    /** k-nearest-neighbour search by cosine similarity, highest score first. */
+    /** k-nearest-neighbour search by cosine similarity, highest score first.
+     *  Supports pre-KNN filtering via opts.where / opts.whereNot. */
     search<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, query: Vector, opts?: VectorSearchOptions): VectorSearchResult<M>[];
 }
+/** The async face of the same vector store. Remote backends (e.g. Qdrant) implement
+ *  this natively; sync backends reach it via {@link toAsyncVector}.
+ *
+ *  Hand-written rather than derived from VectorStore via a mapped type: per-method
+ *  generics (`get<M>`, `search<M>`, …) collapse to `unknown` under inference — same
+ *  constraint as the KV AsyncStore twin in src/types.ts. */
+interface AsyncVectorStore {
+    readonly meta: VectorStoreMeta;
+    upsert<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, doc: VectorDocument<M>): Promise<void>;
+    upsertMany<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, docs: ReadonlyArray<VectorDocument<M>>): Promise<void>;
+    get<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, id: string): Promise<VectorDocument<M> | null>;
+    has(collection: string, id: string): Promise<boolean>;
+    remove(collection: string, id: string): Promise<boolean>;
+    count(collection: string): Promise<number>;
+    search<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, query: Vector, opts?: VectorSearchOptions): Promise<VectorSearchResult<M>[]>;
+}
 
-export type { Vector as V, VectorDocument as a, VectorSearchOptions as b, VectorSearchResult as c, VectorStore as d, VectorStoreMeta as e };
+export type { AsyncVectorStore as A, Vector as V, VectorDocument as a, VectorSearchOptions as b, VectorSearchResult as c, VectorStore as d, VectorStoreMeta as e };

package/dist/types-BLZTMsQO.d.ts

@@ -0,0 +1,69 @@
+import { S as StoreFilter } from './types-DHLdLZ_W.js';
+
+/** A document to be full-text indexed. `meta` is an exact-match-filterable
+ *  payload persisted as JSON by disk-backed backends, so it must be JSON-
+ *  serializable; values JSON can't represent (`undefined`, functions) are dropped
+ *  on persistence — don't rely on them. */
+interface SearchTextDocument<M = Record<string, unknown>> {
+    /** Unique id within the collection. */
+    id: string;
+    /** Single-field text to tokenize and index. Back-compat shorthand for
+     *  `fields: { text }`. */
+    text: string;
+    /** Provide either `text` or `fields`, not both. */
+    fields?: never;
+    /** Typed context stored alongside the text. */
+    meta?: M;
+}
+interface SearchFieldDocument<M = Record<string, unknown>> {
+    /** Unique id within the collection. */
+    id: string;
+    /** Named text fields to tokenize and index with optional query-time weights
+     *  (for example `{ title, body }`). All documents in a collection must use the
+     *  same field names. */
+    fields: Record<string, string>;
+    /** Provide either `text` or `fields`, not both. */
+    text?: never;
+    /** Typed context stored alongside the text. */
+    meta?: M;
+}
+type SearchDocument<M = Record<string, unknown>> = SearchTextDocument<M> | SearchFieldDocument<M>;
+interface SearchOptions {
+    /** Maximum results to return. Default: 10. */
+    limit?: number;
+    /** Exact-match filter on document `meta` (uses `filter.where`, evaluated with
+     *  the shared `matchesWhere`). Applied before limit, after the FTS MATCH. */
+    filter?: StoreFilter;
+    /** Per-field bm25 weights. Fields not listed default to 1. Higher means more
+     *  important; e.g. `{ title: 4, body: 1 }` boosts title matches. */
+    fieldWeights?: Record<string, number>;
+}
+/** A ranked search hit. `score` is the bm25 relevance — higher is more relevant. */
+interface SearchResult<M = Record<string, unknown>> {
+    id: string;
+    /** bm25 relevance. Higher = more relevant. (sqlite exposes `-bm25(fts)`; the
+     *  in-memory reference computes the same quantity directly.) */
+    score: number;
+    /** The document's `meta`, or `{}` when none was indexed. */
+    meta: M;
+}
+/** A synchronous full-text search store with per-collection documents.
+ *
+ *  Ranking is bm25 with the FTS5 default parameters (k1 = 1.2, b = 0.75), plus
+ *  optional query-time per-field weights. The in-memory reference and the sqlite
+ *  `.search` facet produce the same RANKING on clear relevance differences;
+ *  exact float scores need not match across backends (the same parity caveat as
+ *  /vector). */
+interface SearchStore {
+    /** Insert or replace a document by (collection, id). */
+    index<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, doc: SearchDocument<M>): void;
+    /** Insert or replace many documents in one collection. */
+    indexMany<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, docs: ReadonlyArray<SearchDocument<M>>): void;
+    /** Remove a document by id. Returns true if it existed. */
+    remove(collection: string, id: string): boolean;
+    /** bm25-ranked keyword search, highest score first. Supports an exact-match
+     *  meta `filter`. An empty/whitespace query returns `[]`. */
+    search<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, query: string, opts?: SearchOptions): SearchResult<M>[];
+}
+
+export type { SearchDocument as S, SearchOptions as a, SearchResult as b, SearchStore as c, SearchFieldDocument as d, SearchTextDocument as e };

package/dist/{types-DyQLNtxa.d.ts → types-DHLdLZ_W.d.ts}

@@ -20,6 +20,17 @@ interface StoreFilter {
     /** Number of results to skip. */
     offset?: number;
 }
+/** Optional collection capability for adapters that can push `field IN (...)`
+ *  down to the backing store while preserving the normal StoreFilter semantics.
+ *  Graph frontier traversal uses this when present and falls back to plain
+ *  `list()` when absent. */
+interface SyncStoreInQuery {
+    listWhereIn<T>(collection: string, field: string, values: readonly unknown[], filter?: StoreFilter): T[];
+}
+/** Async twin of SyncStoreInQuery for remote-capable stores. */
+interface AsyncStoreInQuery {
+    listWhereIn<T>(collection: string, field: string, values: readonly unknown[], filter?: StoreFilter): Promise<T[]>;
+}
 /**
  * A typed key-value + collection store. **Synchronous.**
  *
@@ -80,4 +91,4 @@ interface AsyncStore {
     count(collection: string, filter?: StoreFilter): Promise<number>;
 }
 
-export type { AsyncStore as A, StoreFilter as S, StoreMeta as a, SyncStore as b };
+export type { AsyncStore as A, StoreFilter as S, AsyncStoreInQuery as a, StoreMeta as b, SyncStore as c, SyncStoreInQuery as d };

package/dist/vector.d.ts

@@ -1,4 +1,5 @@
-import { V as Vector, d as VectorStore, e as VectorStoreMeta, a as VectorDocument, b as VectorSearchOptions, c as VectorSearchResult } from './types-BqSZEMAB.js';
+import { V as Vector, d as VectorStore, e as VectorStoreMeta, a as VectorDocument, b as VectorSearchOptions, c as VectorSearchResult, A as AsyncVectorStore } from './types-B0XrD10b.js';
+export { m as matchesWhere } from './filter-B9hP-TKF.js';
 
 /** Cosine similarity in [-1, 1]. Exact. Shared by the in-memory backend and the
  *  sqlite backend's search path. Returns 0 for length mismatch or a zero vector
@@ -32,10 +33,15 @@ declare class InMemoryVectorStore implements VectorStore {
     upsert<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, doc: VectorDocument<M>): void;
     upsertMany<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, docs: ReadonlyArray<VectorDocument<M>>): void;
     get<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, id: string): VectorDocument<M> | null;
+    has(collection: string, id: string): boolean;
     remove(collection: string, id: string): boolean;
     count(collection: string): number;
     search<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, query: Vector, opts?: VectorSearchOptions): VectorSearchResult<M>[];
     private collectionFor;
 }
 
-export { InMemoryVectorStore, Vector, VectorDocument, VectorSearchOptions, VectorSearchResult, VectorStore, VectorStoreMeta, assertDimensions, bufferToVector, cosineSimilarity, isUsableVector, vectorToBuffer };
+/** Lift a synchronous VectorStore to the {@link AsyncVectorStore} interface. The
+ *  bridge only goes this direction — sync ⊂ async. */
+declare function toAsyncVector(store: VectorStore): AsyncVectorStore;
+
+export { AsyncVectorStore, InMemoryVectorStore, Vector, VectorDocument, VectorSearchOptions, VectorSearchResult, VectorStore, VectorStoreMeta, assertDimensions, bufferToVector, cosineSimilarity, isUsableVector, toAsyncVector, vectorToBuffer };

package/dist/vector.js

@@ -1,6 +1,7 @@
 import {
-  InMemoryVectorStore
-} from "./chunk-EDVHBRXG.js";
+  InMemoryVectorStore,
+  toAsyncVector
+} from "./chunk-OUY3D4RT.js";
 import {
   assertDimensions,
   bufferToVector,
@@ -8,11 +9,16 @@ import {
   isUsableVector,
   vectorToBuffer
 } from "./chunk-BXM3YDOC.js";
+import {
+  matchesWhere
+} from "./chunk-KPMRRYTL.js";
 export {
   InMemoryVectorStore,
   assertDimensions,
   bufferToVector,
   cosineSimilarity,
   isUsableVector,
+  matchesWhere,
+  toAsyncVector,
   vectorToBuffer
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mirk/store",
-  "version": "0.4.2",
+  "version": "0.6.1",
   "type": "module",
   "description": "Code-split storage ports + source adapters under one namespace. KV + collection store and vector similarity store as interface subpaths; the sqlite source-adapter implements both over one connection.",
   "license": "Apache-2.0",
@@ -25,6 +25,7 @@
   "homepage": "https://github.com/nightwork-dev/mirk/tree/main/packages/store#readme",
   "bugs": "https://github.com/nightwork-dev/mirk/issues",
   "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "import": "./dist/index.js",
@@ -38,6 +39,18 @@
       "import": "./dist/vector.js",
       "types": "./dist/vector.d.ts"
     },
+    "./search": {
+      "import": "./dist/search.js",
+      "types": "./dist/search.d.ts"
+    },
+    "./graph": {
+      "import": "./dist/graph.js",
+      "types": "./dist/graph.d.ts"
+    },
+    "./sql": {
+      "import": "./dist/sql.js",
+      "types": "./dist/sql.d.ts"
+    },
     "./sqlite": {
       "import": "./dist/adapters/sqlite.js",
       "types": "./dist/adapters/sqlite.d.ts"
@@ -74,7 +87,6 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
-    "build": "rm -rf dist && tsup src/index.ts src/kv.ts src/vector.ts src/adapters/sqlite.ts --format esm --dts --external better-sqlite3 --external sqlite-vec"
-  },
-  "types": "./dist/index.d.ts"
+    "build": "rm -rf dist && tsup src/index.ts src/kv.ts src/vector.ts src/search.ts src/graph.ts src/sql.ts src/adapters/sqlite.ts --format esm --dts --external better-sqlite3 --external sqlite-vec"
+  }
 }