taladb 0.2.3 → 0.2.5

package/dist/index.d.ts

@@ -0,0 +1,139 @@
+/** Similarity metric used for vector search. */
+type VectorMetric = 'cosine' | 'dot' | 'euclidean';
+interface VectorIndexOptions {
+    /** Number of dimensions in each stored vector. Enforced on insert and search. */
+    dimensions: number;
+    /** Similarity metric. Defaults to `"cosine"`. */
+    metric?: VectorMetric;
+}
+/** A single result returned by `Collection.findNearest`. */
+interface VectorSearchResult<T extends Document = Document> {
+    /** The matched document. */
+    document: T;
+    /**
+     * Similarity score — higher means more similar.
+     * Range depends on metric: cosine ∈ [-1,1], dot ∈ ℝ, euclidean ∈ (0,1].
+     */
+    score: number;
+}
+type Value = null | boolean | number | string | Uint8Array | Value[] | {
+    [key: string]: Value;
+};
+type Document = {
+    _id?: string;
+    [key: string]: Value | undefined;
+};
+type FieldOps<T> = T extends null | undefined ? {
+    $exists?: boolean;
+} : {
+    $eq?: T;
+    $ne?: T;
+    $gt?: T;
+    $gte?: T;
+    $lt?: T;
+    $lte?: T;
+    $in?: T[];
+    $nin?: T[];
+    $exists?: boolean;
+    /** Full-text search: matches documents where this string field contains the given token. */
+    $contains?: string;
+};
+type Filter<T extends Document = Document> = {
+    [K in keyof T]?: T[K] | FieldOps<T[K]>;
+} & {
+    $and?: Filter<T>[];
+    $or?: Filter<T>[];
+    $not?: Filter<T>;
+};
+type Update<T extends Document = Document> = {
+    $set?: Partial<T>;
+    $unset?: {
+        [K in keyof T]?: true;
+    };
+    $inc?: {
+        [K in keyof T]?: number;
+    };
+    $push?: {
+        [K in keyof T]?: Value;
+    };
+    $pull?: {
+        [K in keyof T]?: Value;
+    };
+};
+interface Collection<T extends Document = Document> {
+    insert(doc: Omit<T, '_id'>): Promise<string>;
+    insertMany(docs: Omit<T, '_id'>[]): Promise<string[]>;
+    find(filter?: Filter<T>): Promise<T[]>;
+    findOne(filter: Filter<T>): Promise<T | null>;
+    updateOne(filter: Filter<T>, update: Update<T>): Promise<boolean>;
+    updateMany(filter: Filter<T>, update: Update<T>): Promise<number>;
+    deleteOne(filter: Filter<T>): Promise<boolean>;
+    deleteMany(filter: Filter<T>): Promise<number>;
+    count(filter?: Filter<T>): Promise<number>;
+    createIndex(field: keyof Omit<T, '_id'> & string): Promise<void>;
+    dropIndex(field: keyof Omit<T, '_id'> & string): Promise<void>;
+    /**
+     * Create a vector index on a numeric-array field.
+     *
+     * After creation, `findNearest` can search this field and new inserts/updates
+     * automatically maintain the index. Existing documents are backfilled.
+     *
+     * @example
+     * await articles.createVectorIndex('embedding', { dimensions: 384 });
+     */
+    createVectorIndex(field: keyof Omit<T, '_id'> & string, options: VectorIndexOptions): Promise<void>;
+    /** Drop a vector index. */
+    dropVectorIndex(field: keyof Omit<T, '_id'> & string): Promise<void>;
+    /**
+     * Find the `topK` most similar documents to `vector` using a vector index.
+     *
+     * Optionally combine with a metadata `filter` to restrict the search space
+     * before ranking — e.g. find the 5 most similar english-language articles.
+     *
+     * Results are ordered by descending similarity score (highest first).
+     *
+     * @example
+     * const results = await articles.findNearest('embedding', queryVec, 5);
+     * // results: Array<{ document: Article, score: number }>
+     *
+     * @example with pre-filter
+     * const results = await articles.findNearest('embedding', queryVec, 5, {
+     *   locale: 'en',
+     * });
+     */
+    findNearest(field: keyof Omit<T, '_id'> & string, vector: number[], topK: number, filter?: Filter<T>): Promise<VectorSearchResult<T>[]>;
+    /**
+     * Subscribe to live query results. The callback receives a full snapshot of
+     * matching documents immediately and again after every write that could
+     * affect the result set.
+     *
+     * @returns An unsubscribe function. Call it to stop receiving updates.
+     *
+     * @example
+     * const unsub = users.subscribe({ active: true }, (docs) => {
+     *   console.log('active users:', docs);
+     * });
+     * // later…
+     * unsub();
+     */
+    subscribe(filter: Filter<T>, callback: (docs: T[]) => void): () => void;
+}
+interface TalaDB {
+    collection<T extends Document = Document>(name: string): Collection<T>;
+    close(): Promise<void>;
+}
+
+/**
+ * Open a TalaDB database.
+ *
+ * @param dbName  Name of the database file (used for OPFS and native file paths).
+ *                Ignored for in-memory databases.
+ *
+ * @example
+ * const db = await openDB('myapp.db');
+ * const users = db.collection<User>('users');
+ * const id = await users.insert({ name: 'Alice', age: 30 });
+ */
+declare function openDB(dbName?: string): Promise<TalaDB>;
+
+export { type Collection, type Document, type Filter, type TalaDB, type Update, type Value, type VectorIndexOptions, type VectorMetric, type VectorSearchResult, openDB };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taladb",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Local-first document and vector database for React, React Native, and Node.js",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -16,6 +16,13 @@
   "files": [
     "dist"
   ],
+  "scripts": {
+    "prepublishOnly": "npm run build",
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
   "keywords": [
     "database",
     "local-first",
@@ -48,13 +55,7 @@
     "vitest": "^3.2.0"
   },
   "optionalDependencies": {
-    "@taladb/web": "0.2.3",
-    "@taladb/node": "0.2.3"
-  },
-  "scripts": {
-    "build": "tsup",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest"
+    "@taladb/web": "workspace:*",
+    "@taladb/node": "workspace:*"
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 thinkgrid-labs
-
-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.