taladb 0.6.0 → 0.7.3

package/dist/index.browser.mjs

@@ -22,6 +22,52 @@ async function loadConfig(_configPath) {
 }
 
 // src/index.ts
+var TalaDbValidationError = class extends Error {
+  constructor(cause, context) {
+    const label = context ? ` (${context})` : "";
+    const msg = cause instanceof Error ? cause.message : String(cause);
+    super(`TalaDB schema validation failed${label}: ${msg}`);
+    this.cause = cause;
+    this.name = "TalaDbValidationError";
+  }
+};
+function applySchema(col, options) {
+  const { schema, validateOnRead = false } = options;
+  if (!schema) return col;
+  function parseWrite(doc, label) {
+    try {
+      return schema.parse(doc);
+    } catch (err) {
+      throw new TalaDbValidationError(err, label);
+    }
+  }
+  function parseRead(doc) {
+    try {
+      return schema.parse(doc);
+    } catch (err) {
+      throw new TalaDbValidationError(err, "read");
+    }
+  }
+  return {
+    ...col,
+    insert: async (doc) => {
+      parseWrite(doc, "insert");
+      return col.insert(doc);
+    },
+    insertMany: async (docs) => {
+      docs.forEach((doc, i) => parseWrite(doc, `insertMany[${i}]`));
+      return col.insertMany(docs);
+    },
+    find: validateOnRead ? async (filter) => {
+      const docs = await col.find(filter);
+      return docs.map((d) => parseRead(d));
+    } : col.find.bind(col),
+    findOne: validateOnRead ? async (filter) => {
+      const doc = await col.findOne(filter);
+      return doc === null ? null : parseRead(doc);
+    } : col.findOne.bind(col)
+  };
+}
 function detectPlatform() {
   if (globalThis.nativeCallSyncHook !== void 0) {
     return "react-native";
@@ -92,9 +138,9 @@ async function createBrowserDB(dbName, config) {
       }
     };
   }
-  function wrapCollection(name) {
+  function wrapCollection(name, opts) {
     const s = JSON.stringify;
-    return {
+    const wrapped = {
       insert: (doc) => proxy.send("insert", { collection: name, docJson: s(doc) }),
       insertMany: async (docs) => {
         const json = await proxy.send("insertMany", {
@@ -200,9 +246,11 @@ async function createBrowserDB(dbName, config) {
         };
       }
     };
+    return opts ? applySchema(wrapped, opts) : wrapped;
   }
   return {
-    collection: (name) => wrapCollection(name),
+    collection: (name, opts) => wrapCollection(name, opts),
+    compact: () => proxy.send("compact"),
     close: async () => {
       channel?.close();
       await proxy.send("close");
@@ -214,9 +262,9 @@ async function createNodeDB(dbName, config) {
   const { TalaDBNode } = await import("@taladb/node");
   const configJson = config !== void 0 ? JSON.stringify(config) : null;
   const db = TalaDBNode.open(dbName, configJson);
-  function wrapCollection(name) {
+  function wrapCollection(name, opts) {
     const col = db.collection(name);
-    return {
+    const wrapped = {
       insert: async (doc) => col.insert(doc),
       insertMany: async (docs) => col.insertMany(docs),
       find: async (filter) => col.find(filter ?? null),
@@ -243,9 +291,11 @@ async function createNodeDB(dbName, config) {
       },
       subscribe: (filter, callback) => makePoller(async () => col.find(filter ?? null), callback)
     };
+    return opts ? applySchema(wrapped, opts) : wrapped;
   }
   return {
-    collection: (name) => wrapCollection(name),
+    collection: (name, opts) => wrapCollection(name, opts),
+    compact: async () => db.compact(),
     close: async () => {
     }
   };
@@ -258,9 +308,9 @@ async function createNativeDB(_dbName) {
     );
   }
   const native = maybeNative;
-  function wrapCollection(name) {
+  function wrapCollection(name, opts) {
     const col = native.collection(name);
-    return {
+    const wrapped = {
       insert: async (doc) => col.insert(doc),
       insertMany: async (docs) => col.insertMany(docs),
       find: async (filter) => col.find(filter ?? {}),
@@ -284,9 +334,11 @@ async function createNativeDB(_dbName) {
       },
       subscribe: (filter, callback) => makePoller(async () => col.find(filter ?? {}), callback)
     };
+    return opts ? applySchema(wrapped, opts) : wrapped;
   }
   return {
-    collection: (name) => wrapCollection(name),
+    collection: (name, opts) => wrapCollection(name, opts),
+    compact: async () => native.compact(),
     close: async () => native.close()
   };
 }
@@ -309,5 +361,6 @@ async function openDB(dbName = "taladb.db", options) {
   }
 }
 export {
+  TalaDbValidationError,
   openDB
 };

package/dist/index.d.mts

@@ -80,6 +80,39 @@ type Update<T extends Document = Document> = {
         [K in keyof T]?: Value;
     };
 };
+/**
+ * A schema validator compatible with Zod, Valibot, and any library that
+ * exposes a `parse(data: unknown): T` method.
+ *
+ * @example with Zod
+ * const schema = z.object({ name: z.string(), age: z.number() });
+ * const users = db.collection<z.infer<typeof schema>>('users', { schema });
+ *
+ * @example with Valibot
+ * const schema = v.object({ name: v.string(), age: v.number() });
+ * const users = db.collection<v.InferOutput<typeof schema>>('users', { schema });
+ */
+interface Schema<T> {
+    parse(data: unknown): T;
+}
+/** Options passed to `db.collection()`. */
+interface CollectionOptions<T extends Document = Document> {
+    /**
+     * Schema validator. When provided, every document passed to `insert` and
+     * `insertMany` is run through `schema.parse()` before being stored. If
+     * validation fails, a `TalaDbValidationError` is thrown.
+     *
+     * Compatible with Zod (`z.object({...})`), Valibot (`v.object({...})`), or
+     * any object with a `parse(data: unknown): T` method.
+     */
+    schema?: Schema<T>;
+    /**
+     * When `true`, documents returned by `find` and `findOne` are also passed
+     * through `schema.parse()`. Useful for catching schema drift on old data.
+     * Defaults to `false`.
+     */
+    validateOnRead?: boolean;
+}
 interface Collection<T extends Document = Document> {
     insert(doc: Omit<T, '_id'>): Promise<string>;
     insertMany(docs: Omit<T, '_id'>[]): Promise<string[]>;
@@ -166,7 +199,18 @@ interface Collection<T extends Document = Document> {
     subscribe(filter: Filter<T>, callback: (docs: T[]) => void): () => void;
 }
 interface TalaDB {
-    collection<T extends Document = Document>(name: string): Collection<T>;
+    collection<T extends Document = Document>(name: string, options?: CollectionOptions<T>): Collection<T>;
+    /**
+     * Compact the underlying storage file, reclaiming space freed by deletes
+     * and updates.
+     *
+     * Call during idle periods — e.g. once on startup after `compactTombstones`.
+     * No-op on in-memory (IndexedDB-fallback) databases.
+     *
+     * @example
+     * await db.compact();
+     */
+    compact(): Promise<void>;
     close(): Promise<void>;
 }
 
@@ -208,6 +252,15 @@ interface TalaDbConfig {
     sync?: SyncConfig;
 }
 
+/**
+ * Thrown when a document fails schema validation on `insert` or `insertMany`.
+ * The `cause` property holds the original error thrown by the schema library.
+ */
+declare class TalaDbValidationError extends Error {
+    readonly cause: unknown;
+    constructor(cause: unknown, context?: string);
+}
+
 /** Options for `openDB`. */
 interface OpenDBOptions {
     /**
@@ -241,4 +294,4 @@ interface OpenDBOptions {
  */
 declare function openDB(dbName?: string, options?: OpenDBOptions): Promise<TalaDB>;
 
-export { type Collection, type CollectionIndexInfo, type Document, type Filter, type OpenDBOptions, type SyncConfig, type TalaDB, type TalaDbConfig, type Update, type Value, type VectorIndexOptions, type VectorMetric, type VectorSearchResult, openDB };
+export { type Collection, type CollectionIndexInfo, type CollectionOptions, type Document, type Filter, type OpenDBOptions, type Schema, type SyncConfig, type TalaDB, type TalaDbConfig, TalaDbValidationError, type Update, type Value, type VectorIndexOptions, type VectorMetric, type VectorSearchResult, openDB };

package/dist/index.d.ts

@@ -80,6 +80,39 @@ type Update<T extends Document = Document> = {
         [K in keyof T]?: Value;
     };
 };
+/**
+ * A schema validator compatible with Zod, Valibot, and any library that
+ * exposes a `parse(data: unknown): T` method.
+ *
+ * @example with Zod
+ * const schema = z.object({ name: z.string(), age: z.number() });
+ * const users = db.collection<z.infer<typeof schema>>('users', { schema });
+ *
+ * @example with Valibot
+ * const schema = v.object({ name: v.string(), age: v.number() });
+ * const users = db.collection<v.InferOutput<typeof schema>>('users', { schema });
+ */
+interface Schema<T> {
+    parse(data: unknown): T;
+}
+/** Options passed to `db.collection()`. */
+interface CollectionOptions<T extends Document = Document> {
+    /**
+     * Schema validator. When provided, every document passed to `insert` and
+     * `insertMany` is run through `schema.parse()` before being stored. If
+     * validation fails, a `TalaDbValidationError` is thrown.
+     *
+     * Compatible with Zod (`z.object({...})`), Valibot (`v.object({...})`), or
+     * any object with a `parse(data: unknown): T` method.
+     */
+    schema?: Schema<T>;
+    /**
+     * When `true`, documents returned by `find` and `findOne` are also passed
+     * through `schema.parse()`. Useful for catching schema drift on old data.
+     * Defaults to `false`.
+     */
+    validateOnRead?: boolean;
+}
 interface Collection<T extends Document = Document> {
     insert(doc: Omit<T, '_id'>): Promise<string>;
     insertMany(docs: Omit<T, '_id'>[]): Promise<string[]>;
@@ -166,7 +199,18 @@ interface Collection<T extends Document = Document> {
     subscribe(filter: Filter<T>, callback: (docs: T[]) => void): () => void;
 }
 interface TalaDB {
-    collection<T extends Document = Document>(name: string): Collection<T>;
+    collection<T extends Document = Document>(name: string, options?: CollectionOptions<T>): Collection<T>;
+    /**
+     * Compact the underlying storage file, reclaiming space freed by deletes
+     * and updates.
+     *
+     * Call during idle periods — e.g. once on startup after `compactTombstones`.
+     * No-op on in-memory (IndexedDB-fallback) databases.
+     *
+     * @example
+     * await db.compact();
+     */
+    compact(): Promise<void>;
     close(): Promise<void>;
 }
 
@@ -208,6 +252,15 @@ interface TalaDbConfig {
     sync?: SyncConfig;
 }
 
+/**
+ * Thrown when a document fails schema validation on `insert` or `insertMany`.
+ * The `cause` property holds the original error thrown by the schema library.
+ */
+declare class TalaDbValidationError extends Error {
+    readonly cause: unknown;
+    constructor(cause: unknown, context?: string);
+}
+
 /** Options for `openDB`. */
 interface OpenDBOptions {
     /**
@@ -241,4 +294,4 @@ interface OpenDBOptions {
  */
 declare function openDB(dbName?: string, options?: OpenDBOptions): Promise<TalaDB>;
 
-export { type Collection, type CollectionIndexInfo, type Document, type Filter, type OpenDBOptions, type SyncConfig, type TalaDB, type TalaDbConfig, type Update, type Value, type VectorIndexOptions, type VectorMetric, type VectorSearchResult, openDB };
+export { type Collection, type CollectionIndexInfo, type CollectionOptions, type Document, type Filter, type OpenDBOptions, type Schema, type SyncConfig, type TalaDB, type TalaDbConfig, TalaDbValidationError, type Update, type Value, type VectorIndexOptions, type VectorMetric, type VectorSearchResult, openDB };

package/dist/index.js

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  TalaDbValidationError: () => TalaDbValidationError,
   openDB: () => openDB
 });
 module.exports = __toCommonJS(index_exports);
@@ -103,6 +104,52 @@ async function loadConfig(configPath) {
 
 // src/index.ts
 var import_meta = {};
+var TalaDbValidationError = class extends Error {
+  constructor(cause, context) {
+    const label = context ? ` (${context})` : "";
+    const msg = cause instanceof Error ? cause.message : String(cause);
+    super(`TalaDB schema validation failed${label}: ${msg}`);
+    this.cause = cause;
+    this.name = "TalaDbValidationError";
+  }
+};
+function applySchema(col, options) {
+  const { schema, validateOnRead = false } = options;
+  if (!schema) return col;
+  function parseWrite(doc, label) {
+    try {
+      return schema.parse(doc);
+    } catch (err) {
+      throw new TalaDbValidationError(err, label);
+    }
+  }
+  function parseRead(doc) {
+    try {
+      return schema.parse(doc);
+    } catch (err) {
+      throw new TalaDbValidationError(err, "read");
+    }
+  }
+  return {
+    ...col,
+    insert: async (doc) => {
+      parseWrite(doc, "insert");
+      return col.insert(doc);
+    },
+    insertMany: async (docs) => {
+      docs.forEach((doc, i) => parseWrite(doc, `insertMany[${i}]`));
+      return col.insertMany(docs);
+    },
+    find: validateOnRead ? async (filter) => {
+      const docs = await col.find(filter);
+      return docs.map((d) => parseRead(d));
+    } : col.find.bind(col),
+    findOne: validateOnRead ? async (filter) => {
+      const doc = await col.findOne(filter);
+      return doc === null ? null : parseRead(doc);
+    } : col.findOne.bind(col)
+  };
+}
 function detectPlatform() {
   if (globalThis.nativeCallSyncHook !== void 0) {
     return "react-native";
@@ -173,9 +220,9 @@ async function createBrowserDB(dbName, config) {
       }
     };
   }
-  function wrapCollection(name) {
+  function wrapCollection(name, opts) {
     const s = JSON.stringify;
-    return {
+    const wrapped = {
       insert: (doc) => proxy.send("insert", { collection: name, docJson: s(doc) }),
       insertMany: async (docs) => {
         const json = await proxy.send("insertMany", {
@@ -281,9 +328,11 @@ async function createBrowserDB(dbName, config) {
         };
       }
     };
+    return opts ? applySchema(wrapped, opts) : wrapped;
   }
   return {
-    collection: (name) => wrapCollection(name),
+    collection: (name, opts) => wrapCollection(name, opts),
+    compact: () => proxy.send("compact"),
     close: async () => {
       channel?.close();
       await proxy.send("close");
@@ -295,9 +344,9 @@ async function createNodeDB(dbName, config) {
   const { TalaDBNode } = await import("@taladb/node");
   const configJson = config !== void 0 ? JSON.stringify(config) : null;
   const db = TalaDBNode.open(dbName, configJson);
-  function wrapCollection(name) {
+  function wrapCollection(name, opts) {
     const col = db.collection(name);
-    return {
+    const wrapped = {
       insert: async (doc) => col.insert(doc),
       insertMany: async (docs) => col.insertMany(docs),
       find: async (filter) => col.find(filter ?? null),
@@ -324,9 +373,11 @@ async function createNodeDB(dbName, config) {
       },
       subscribe: (filter, callback) => makePoller(async () => col.find(filter ?? null), callback)
     };
+    return opts ? applySchema(wrapped, opts) : wrapped;
   }
   return {
-    collection: (name) => wrapCollection(name),
+    collection: (name, opts) => wrapCollection(name, opts),
+    compact: async () => db.compact(),
     close: async () => {
     }
   };
@@ -339,9 +390,9 @@ async function createNativeDB(_dbName) {
     );
   }
   const native = maybeNative;
-  function wrapCollection(name) {
+  function wrapCollection(name, opts) {
     const col = native.collection(name);
-    return {
+    const wrapped = {
       insert: async (doc) => col.insert(doc),
       insertMany: async (docs) => col.insertMany(docs),
       find: async (filter) => col.find(filter ?? {}),
@@ -365,9 +416,11 @@ async function createNativeDB(_dbName) {
       },
       subscribe: (filter, callback) => makePoller(async () => col.find(filter ?? {}), callback)
     };
+    return opts ? applySchema(wrapped, opts) : wrapped;
   }
   return {
-    collection: (name) => wrapCollection(name),
+    collection: (name, opts) => wrapCollection(name, opts),
+    compact: async () => native.compact(),
     close: async () => native.close()
   };
 }
@@ -391,5 +444,6 @@ async function openDB(dbName = "taladb.db", options) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  TalaDbValidationError,
   openDB
 });

package/dist/index.mjs

@@ -66,6 +66,52 @@ async function loadConfig(configPath) {
 }
 
 // src/index.ts
+var TalaDbValidationError = class extends Error {
+  constructor(cause, context) {
+    const label = context ? ` (${context})` : "";
+    const msg = cause instanceof Error ? cause.message : String(cause);
+    super(`TalaDB schema validation failed${label}: ${msg}`);
+    this.cause = cause;
+    this.name = "TalaDbValidationError";
+  }
+};
+function applySchema(col, options) {
+  const { schema, validateOnRead = false } = options;
+  if (!schema) return col;
+  function parseWrite(doc, label) {
+    try {
+      return schema.parse(doc);
+    } catch (err) {
+      throw new TalaDbValidationError(err, label);
+    }
+  }
+  function parseRead(doc) {
+    try {
+      return schema.parse(doc);
+    } catch (err) {
+      throw new TalaDbValidationError(err, "read");
+    }
+  }
+  return {
+    ...col,
+    insert: async (doc) => {
+      parseWrite(doc, "insert");
+      return col.insert(doc);
+    },
+    insertMany: async (docs) => {
+      docs.forEach((doc, i) => parseWrite(doc, `insertMany[${i}]`));
+      return col.insertMany(docs);
+    },
+    find: validateOnRead ? async (filter) => {
+      const docs = await col.find(filter);
+      return docs.map((d) => parseRead(d));
+    } : col.find.bind(col),
+    findOne: validateOnRead ? async (filter) => {
+      const doc = await col.findOne(filter);
+      return doc === null ? null : parseRead(doc);
+    } : col.findOne.bind(col)
+  };
+}
 function detectPlatform() {
   if (globalThis.nativeCallSyncHook !== void 0) {
     return "react-native";
@@ -136,9 +182,9 @@ async function createBrowserDB(dbName, config) {
       }
     };
   }
-  function wrapCollection(name) {
+  function wrapCollection(name, opts) {
     const s = JSON.stringify;
-    return {
+    const wrapped = {
       insert: (doc) => proxy.send("insert", { collection: name, docJson: s(doc) }),
       insertMany: async (docs) => {
         const json = await proxy.send("insertMany", {
@@ -244,9 +290,11 @@ async function createBrowserDB(dbName, config) {
         };
       }
     };
+    return opts ? applySchema(wrapped, opts) : wrapped;
   }
   return {
-    collection: (name) => wrapCollection(name),
+    collection: (name, opts) => wrapCollection(name, opts),
+    compact: () => proxy.send("compact"),
     close: async () => {
       channel?.close();
       await proxy.send("close");
@@ -258,9 +306,9 @@ async function createNodeDB(dbName, config) {
   const { TalaDBNode } = await import("@taladb/node");
   const configJson = config !== void 0 ? JSON.stringify(config) : null;
   const db = TalaDBNode.open(dbName, configJson);
-  function wrapCollection(name) {
+  function wrapCollection(name, opts) {
     const col = db.collection(name);
-    return {
+    const wrapped = {
       insert: async (doc) => col.insert(doc),
       insertMany: async (docs) => col.insertMany(docs),
       find: async (filter) => col.find(filter ?? null),
@@ -287,9 +335,11 @@ async function createNodeDB(dbName, config) {
       },
       subscribe: (filter, callback) => makePoller(async () => col.find(filter ?? null), callback)
     };
+    return opts ? applySchema(wrapped, opts) : wrapped;
   }
   return {
-    collection: (name) => wrapCollection(name),
+    collection: (name, opts) => wrapCollection(name, opts),
+    compact: async () => db.compact(),
     close: async () => {
     }
   };
@@ -302,9 +352,9 @@ async function createNativeDB(_dbName) {
     );
   }
   const native = maybeNative;
-  function wrapCollection(name) {
+  function wrapCollection(name, opts) {
     const col = native.collection(name);
-    return {
+    const wrapped = {
       insert: async (doc) => col.insert(doc),
       insertMany: async (docs) => col.insertMany(docs),
       find: async (filter) => col.find(filter ?? {}),
@@ -328,9 +378,11 @@ async function createNativeDB(_dbName) {
       },
       subscribe: (filter, callback) => makePoller(async () => col.find(filter ?? {}), callback)
     };
+    return opts ? applySchema(wrapped, opts) : wrapped;
   }
   return {
-    collection: (name) => wrapCollection(name),
+    collection: (name, opts) => wrapCollection(name, opts),
+    compact: async () => native.compact(),
     close: async () => native.close()
   };
 }
@@ -353,5 +405,6 @@ async function openDB(dbName = "taladb.db", options) {
   }
 }
 export {
+  TalaDbValidationError,
   openDB
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taladb",
-  "version": "0.6.0",
+  "version": "0.7.3",
   "description": "Local-first document and vector database for React, React Native, and Node.js",
   "main": "dist/index.js",
   "module": "dist/index.mjs",