jotdb 0.1.5 → 0.1.7

package/README.md

@@ -1,16 +1,56 @@
 # JotDB
 
-A lightweight, schema-less database built on Cloudflare Durable Objects. Perfect for quick prototyping and applications that need simple data storage without the complexity of traditional databases.
+[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/acoyfellow/jotdb)
+
+A lightweight, schema-less database built on Cloudflare Durable Objects. Think of it as Firestore's security rules, but with Zod validation built-in. Perfect for both internal and external APIs, with automatic type safety and validation.
+
+> **Cloudflare Products**: JotDB works with any Cloudflare product that supports Durable Objects:
+> - Cloudflare Workers
+> - Cloudflare Pages (with Functions)
+> - Cloudflare Workflows
+> - Cloudflare Queues
+> - Cloudflare Cron Triggers
 
 ## Why JotDB?
 
-I needed a quick way to save data without dealing with schemas, SQL, or complex database setup. While Firestore is great, it can be overkill for simple use cases. JotDB provides a simpler alternative by leveraging Cloudflare Durable Objects, making it perfect for:
+JotDB combines the best of both worlds: the simplicity of NoSQL with the safety of schema validation. Here's what makes it special:
+
+- **Built-in Type Safety**: Automatic Zod validation ensures your data is always in the right shape
+- **Edge-Native**: Runs directly on Cloudflare's edge network, with sub-millisecond latency
+- **RPC-First**: Direct method calls instead of HTTP endpoints (though you can easily wrap it in HTTP)
+- **Durable Storage**: Built on Durable Objects for reliable, consistent storage
+- **Zero Setup**: No database configuration, no connection strings, just instantiate and go
+- **Perfect for APIs**: Use it as an internal database or wrap it with auth for external APIs
+- **Real-time Ready**: Durable Objects provide strong consistency guarantees
+
+Perfect for:
+- Quick prototypes that need data validation
+- Small to medium applications that need reliable storage
+- Serverless environments where you want type safety
+- Real-time data storage with strong consistency
+- Collaborative applications that need data validation
+- APIs that need both flexibility and safety
+
+## Design Patterns
 
-- Quick prototypes
-- Small to medium applications
-- Serverless environments
-- Real-time data storage
-- Collaborative applications
+JotDB uses Cloudflare Durable Objects under the hood, which means you can organize your data in several ways:
+
+1. **Global Store**: Use a single instance for your entire application
+   ```typescript
+   const db = env.JOTDB.get(env.JOTDB.idFromName("global"));
+   ```
+
+2. **Per-User Store**: Create a separate instance for each user
+   ```typescript
+   const userDb = env.JOTDB.get(env.JOTDB.idFromName(`user:${userId}`));
+   ```
+
+3. **Per-Event Store**: Create temporary stores for events or sessions
+   ```typescript
+   const eventDb = env.JOTDB.get(env.JOTDB.idFromName(`event:${eventId}`));
+   ```
+
+Each instance is isolated and can have its own schema and options. This follows the Actor Model pattern, where each instance is an independent actor that manages its own state.
 
 ## Installation
 
@@ -25,24 +65,47 @@ yarn add jotdb
 pnpm add jotdb
 ```
 
+### Configure wrangler.jsonc
+
+```jsonc
+{
+  "durable_objects": {
+    "bindings": [
+      {
+        "name": "JOTDB",
+        "class_name": "JotDB"
+      }
+    ]
+  }
+}
+```
+
 ## Full Example
 
 ```typescript
 import { JotDB } from 'jotdb';
 
-// Initialize the database
-const jotId = env.JotDB.idFromName("my-db");
-const db = env.JotDB.get(jotId);
-
-// Set a value
-await db.set("user:123", { name: "John", age: 30 });
-
-// Get a value
-const user = await db.get("user:123");
-console.log(user); // { name: "John", age: 30 }
+export interface Env {
+  JOTDB: DurableObjectNamespace;
+}
 
-// Delete a value
-await db.delete("user:123");
+export default {
+  async fetch(request: Request, env: Env) {
+    // Initialize the database
+    const jotId = env.JOTDB.idFromName("my-db");
+    const db = env.JOTDB.get(jotId);
+
+    // Example operations
+    await db.set("user:123", { name: "John", age: 30 });
+    const user = await db.get("user:123");
+    await db.delete("user:123");
+
+    // Return the result
+    return new Response(JSON.stringify({ user }), {
+      headers: { 'Content-Type': 'application/json' }
+    });
+  }
+};
 ```
 
 ## API Reference
@@ -52,19 +115,34 @@ await db.delete("user:123");
 | `set(key, value)` | Store a value | `key: string`, `value: any` | `Promise<void>` |
 | `get(key)` | Retrieve a value | `key: string` | `Promise<any>` |
 | `delete(key)` | Remove a value | `key: string` | `Promise<void>` |
-| `list(prefix?)` | List all keys (optionally filtered by prefix) | `prefix?: string` | `Promise<string[]>` |
-
-## Types
+| `clear()` | Remove all values | none | `Promise<void>` |
+| `keys()` | Get all keys | none | `Promise<string[]>` |
+| `has(key)` | Check if key exists | `key: string` | `Promise<boolean>` |
+| `getAll()` | Get all data | none | `Promise<Record<string, unknown> \| unknown[]>` |
+| `setAll(objOrArr)` | Set all data at once | `objOrArr: Record<string, unknown> \| unknown[]` | `Promise<void>` |
+| `push(item)` | Add item to array | `item: unknown` | `Promise<void>` |
+| `getSchema()` | Get current schema | none | `Promise<SchemaDefinition>` |
+| `setSchema(schema)` | Set data schema | `schema: SchemaDefinition` | `Promise<void>` |
+| `getOptions()` | Get current options | none | `Promise<JotDBOptions>` |
+| `setOptions(opts)` | Set database options | `opts: Partial<JotDBOptions>` | `Promise<void>` |
+| `getAuditLog()` | Get audit log entries | none | `Promise<AuditLogEntry[]>` |
+| `clearAuditLog()` | Clear audit log | none | `Promise<void>` |
+
+### Options
 
 ```typescript
-interface JotDB {
-  set(key: string, value: any): Promise<void>;
-  get(key: string): Promise<any>;
-  delete(key: string): Promise<void>;
-  list(prefix?: string): Promise<string[]>;
+interface JotDBOptions {
+  autoStrip: boolean;  // Automatically strip unknown fields
+  readOnly: boolean;   // Enable read-only mode
 }
 ```
 
+### Schema Types
+
+```typescript
+type SchemaType = "string" | "number" | "boolean" | "email" | "array" | "object" | "any";
+```
+
 ## License
 
 MIT License - feel free to use this in your own projects!

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jotdb",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "type": "module",
   "main": "dist/index.js",
   "exports": {
@@ -13,7 +13,8 @@
   "scripts": {
     "dev": "wrangler dev --port 5173",
     "deploy": "wrangler deploy",
-    "patch": "npm version patch && npm publish --access public"
+    "patch": "npm version patch",
+    "publish": "npm publish --access public"
   },
   "devDependencies": {
     "typescript": "^5.8.3",

package/src/index.ts

@@ -1,4 +1,4 @@
-import { z, ZodTypeAny, ZodObject } from "zod";
+import { z, ZodTypeAny, ZodObject, ZodError } from "zod";
 import { Hono } from 'hono';
 import { cors } from 'hono/cors';
 import { prettyJSON } from 'hono/pretty-json';
@@ -6,7 +6,9 @@ import { DurableObject } from "cloudflare:workers";
 
 // Type definitions
 type SchemaType = "string" | "number" | "boolean" | "email" | "array" | "object" | "any";
-type SchemaDefinition = Record<string, SchemaType>;
+type ObjectSchema = Record<string, SchemaType>;
+type ArraySchema = { __arrayType: SchemaType | ObjectSchema };
+type SchemaDefinition = ObjectSchema | ArraySchema;
 
 interface JotDBOptions {
   autoStrip: boolean;
@@ -19,10 +21,39 @@ interface AuditLogEntry {
   keys: string[];
 }
 
+function isZodError(e: any): e is ZodError {
+  return e && typeof e === 'object' && Array.isArray(e.issues);
+}
+
+function handleZod<T>(fn: () => T): T {
+  try {
+    return fn();
+  } catch (e) {
+    if (isZodError(e)) {
+      throw new Error('Validation failed: ' + e.issues.map(issue => issue.message).join('; '));
+    }
+    throw e;
+  }
+}
+
+function isArraySchema(schema: SchemaDefinition): schema is ArraySchema {
+  return '__arrayType' in schema;
+}
+function isObjectSchema(schema: SchemaDefinition): schema is ObjectSchema {
+  return !('__arrayType' in schema);
+}
+
+function inferPrimitiveType(v: any): SchemaType {
+  if (typeof v === "string") return v.includes("@") ? "email" : "string";
+  if (typeof v === "number") return "number";
+  if (typeof v === "boolean") return "boolean";
+  return "any";
+}
+
 export class JotDB extends DurableObject {
   private data: Record<string, unknown> | unknown[] = {};
   private rawSchema: SchemaDefinition = {};
-  private zodSchema: ZodObject<any> | null = null;
+  private zodSchema: ZodTypeAny | null = null;
   private options: JotDBOptions = {
     autoStrip: false,
     readOnly: false,
@@ -56,11 +87,49 @@ export class JotDB extends DurableObject {
     return Array.isArray(this.data);
   }
 
+  private inferSchemaFromValue(value: any): SchemaDefinition {
+    if (Array.isArray(value)) {
+      if (value.length === 0) return { __arrayType: "any" };
+      const first = value[0];
+      if (typeof first === "object" && first !== null && !Array.isArray(first)) {
+        // Array of objects
+        return { __arrayType: this.inferSchemaFromValue(first) };
+      }
+      // Array of primitives
+      return { __arrayType: inferPrimitiveType(first) };
+    }
+    if (typeof value === "object" && value !== null) {
+      const schema: ObjectSchema = {};
+      for (const [k, v] of Object.entries(value)) {
+        if (Array.isArray(v)) {
+          schema[k] = "array";
+        } else if (typeof v === "object" && v !== null) {
+          schema[k] = "object";
+        } else {
+          schema[k] = inferPrimitiveType(v);
+        }
+      }
+      return schema;
+    }
+    // Top-level primitive (shouldn't happen for objects, but fallback)
+    return {};
+  }
+
   async push(item: unknown): Promise<void> {
     await this.load();
     if (!Array.isArray(this.data)) {
       this.data = [];
     }
+    if (!this.zodSchema) {
+      const schema = this.inferSchemaFromValue([item]);
+      await this.setSchema(schema);
+      console.info('[JotDB] Auto-inferred and set schema from first push:', schema);
+    }
+    if (isArraySchema(this.rawSchema)) {
+      handleZod(() => (this.zodSchema as any).parse([item]));
+    } else if (this.zodSchema && isObjectSchema(this.rawSchema)) {
+      handleZod(() => this.zodSchema!.parse(item));
+    }
     (this.data as unknown[]).push(item);
     await this.save();
     await this.logAudit("push", []);
@@ -68,8 +137,17 @@ export class JotDB extends DurableObject {
 
   async setAll(objOrArr: Record<string, unknown> | unknown[]): Promise<void> {
     await this.load();
-    if (!Array.isArray(objOrArr) && this.zodSchema) {
-      objOrArr = this.zodSchema.parse(objOrArr);
+    if (!this.zodSchema) {
+      const schema = this.inferSchemaFromValue(objOrArr);
+      await this.setSchema(schema);
+      console.info('[JotDB] Auto-inferred and set schema from first setAll:', schema);
+    }
+    if (Array.isArray(objOrArr) && isArraySchema(this.rawSchema)) {
+      handleZod(() => (this.zodSchema as any).parse(objOrArr));
+    } else if (!Array.isArray(objOrArr) && this.zodSchema && isObjectSchema(this.rawSchema)) {
+      objOrArr = handleZod(() => this.zodSchema!.parse(objOrArr));
+    } else if (Array.isArray(objOrArr) && this.zodSchema && isObjectSchema(this.rawSchema)) {
+      objOrArr.forEach(item => handleZod(() => this.zodSchema!.parse(item)));
     }
     this.data = objOrArr;
     await this.save();
@@ -183,30 +261,33 @@ export class JotDB extends DurableObject {
     await this.ctx.storage.put("__audit__", []);
   }
 
-  private buildZodSchema(schema: SchemaDefinition): ZodObject<any> {
+  private buildZodSchema(schema: SchemaDefinition): ZodTypeAny {
+    if (isArraySchema(schema)) {
+      const t = schema.__arrayType;
+      if (typeof t === "string") {
+        switch (t) {
+          case "string": return z.string().array();
+          case "number": return z.number().array();
+          case "boolean": return z.boolean().array();
+          case "email": return z.string().email().array();
+          default: return z.any().array();
+        }
+      } else {
+        // Array of objects
+        return this.buildZodSchema(t).array();
+      }
+    }
+    // Object schema
     const shape: Record<string, ZodTypeAny> = {};
     for (const [key, type] of Object.entries(schema)) {
       switch (type) {
-        case "string":
-          shape[key] = z.string();
-          break;
-        case "number":
-          shape[key] = z.number();
-          break;
-        case "boolean":
-          shape[key] = z.boolean();
-          break;
-        case "email":
-          shape[key] = z.string().email();
-          break;
-        case "array":
-          shape[key] = z.array(z.any());
-          break;
-        case "object":
-          shape[key] = z.record(z.any());
-          break;
-        default:
-          shape[key] = z.any();
+        case "string": shape[key] = z.string(); break;
+        case "number": shape[key] = z.number(); break;
+        case "boolean": shape[key] = z.boolean(); break;
+        case "email": shape[key] = z.string().email(); break;
+        case "array": shape[key] = z.array(z.any()); break;
+        case "object": shape[key] = z.record(z.any()); break;
+        default: shape[key] = z.any();
       }
     }
     return z.object(shape);
@@ -222,9 +303,15 @@ export class JotDB extends DurableObject {
       throw new Error("Database is in read-only mode");
     }
     if (!Array.isArray(this.data)) {
+      // Auto-infer schema if not set
+      if (!this.zodSchema) {
+        const schema = this.inferSchemaFromValue({ [key]: value });
+        await this.setSchema(schema);
+        console.info('[JotDB] Auto-inferred and set schema from first set:', schema);
+      }
       this.data[key] = value;
       if (this.zodSchema) {
-        this.zodSchema.parse(this.data);
+        handleZod(() => this.zodSchema!.parse(this.data));
       }
       await this.save();
       await this.logAudit("set", key);
@@ -246,7 +333,8 @@ app.use('*', prettyJSON());
 
 // Test endpoint
 app.get('/test', async (c) => {
-  const id = c.env.JOTDB.idFromName("test-db");
+  const JOB_ID = Date.now().toString();
+  const id = c.env.JOTDB.idFromName(JOB_ID);
   const db = c.env.JOTDB.get(id) as unknown as JotDB;
 
   const results = {
@@ -256,6 +344,7 @@ app.get('/test', async (c) => {
   };
 
   try {
+
     // Test 1: Basic set/get
     await db.set("test1", "hello");
     const value1 = await db.get("test1");
@@ -316,7 +405,7 @@ app.get('/test', async (c) => {
     });
 
     // Test 5: Array mode - setAll and getAll
-    const arrayId = c.env.JOTDB.idFromName("test-array");
+    const arrayId = c.env.JOTDB.idFromName(JOB_ID + "-test-array");
     const arrayDb = c.env.JOTDB.get(arrayId) as unknown as JotDB;
     await arrayDb.setAll([1, 2, 3]);
     const arr = await arrayDb.getAll();
@@ -335,6 +424,67 @@ app.get('/test', async (c) => {
       value: arr2
     });
 
+    // --- Schema inference tests-- -
+    //   Object mode
+    const objId = c.env.JOTDB.idFromName("schema-obj");
+    const objDb = c.env.JOTDB.get(objId) as unknown as JotDB;
+    await objDb.setAll({ foo: "bar", count: 1 });
+    const objSchema = await objDb.getSchema();
+    let objPassed = false;
+    if (!('__arrayType' in objSchema)) {
+      objPassed = (objSchema as any).foo === "string" && (objSchema as any).count === "number";
+    }
+    results.tests.push({
+      name: "Object mode: inferred schema",
+      passed: objPassed,
+      value: objSchema
+    });
+    let objError = null;
+    try {
+      await objDb.setAll({ foo: 123, count: "not a number" });
+    } catch (e) {
+      objError = e instanceof Error ? e.message : String(e);
+    }
+    results.tests.push({
+      name: "Object mode: invalid shape fails",
+      passed: !!objError,
+      error: objError
+    });
+
+    // Array mode
+    const arrId = c.env.JOTDB.idFromName("schema-arr");
+    const arrDb = c.env.JOTDB.get(arrId) as unknown as JotDB;
+    await arrDb.setAll([{ foo: "bar", count: 1 }]);
+    const arrSchema = await arrDb.getSchema();
+    let arrPassed = false;
+    if ('__arrayType' in arrSchema && typeof arrSchema.__arrayType === 'object') {
+      arrPassed = arrSchema.__arrayType.foo === "string" && arrSchema.__arrayType.count === "number";
+    }
+    results.tests.push({
+      name: "Array mode: inferred schema",
+      passed: arrPassed,
+      value: arrSchema
+    });
+    let arrError = null;
+    try {
+      await arrDb.push({ foo: 123, count: "not a number" });
+    } catch (e) {
+      arrError = e instanceof Error ? e.message : String(e);
+    }
+    results.tests.push({
+      name: "Array mode: invalid item fails",
+      passed: !!arrError,
+      error: arrError
+    });
+
+    // Test 0: Clear database, set options to read-only: false
+    await db.clear();
+    results.tests.push({
+      name: "Clear database",
+      passed: true,
+      value: await db.getAll()
+    });
+
     // Get audit log
     results.auditLog = await db.getAuditLog();
 
@@ -364,9 +514,15 @@ app.get('/test', async (c) => {
 
     return new Response(html, { headers: { 'Content-Type': 'text/html' } });
   } catch (error) {
+    console.error(error);
+    let errorMessage = error instanceof Error ? error.message : String(error);
+    if (isZodError(error)) {
+      console.error(error.issues);
+      errorMessage = error.issues.map(issue => issue.message).join('\n');
+    }
     let html = `<!DOCTYPE html><html><head><title>JotDB Test Error</title></head><body>` +
       `<h1 style="color:red">Error</h1>` +
-      `<pre>${error instanceof Error ? error.message : String(error)}</pre>` +
+      `<pre>${errorMessage}</pre>` +
       `<h2>Partial Results</h2>` +
       `<pre>${JSON.stringify(results.tests, null, 2)}</pre>` +
       `<h2>Audit Log</h2>` +