jotdb 0.1.4 → 0.1.6

package/README.md

@@ -1,203 +1,156 @@
 # JotDB
 
-## 🚀 Quick Start: Using JotDB in Your Cloudflare Worker
+[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/acoyfellow/jotdb)
 
-### 1. **Install 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.
 
-```bash
-bun add jotdb
-# or
-npm install jotdb
-```
-
-### 2. **Bind the Durable Object in your wrangler.toml or wrangler.json**
-
-```toml
-[[durable_objects.bindings]]
-name = "JOTDB"
-class_name = "JotDB"
-```
-
-### 3. **Register the Durable Object in your Worker**
-
-```ts
-import { JotDB } from 'jotdb';
-
-export interface Env {
-  JOTDB: DurableObjectNamespace<JotDB>;
-}
-
-export default {
-  async fetch(request: Request, env: Env) {
-    // Get a stub for your JotDB instance
-    const id = env.JOTDB.idFromName("my-db");
-    const db = env.JOTDB.get(id);
+> **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
 
-    // Use RPC (recommended, requires extends DurableObject)
-    await db.set("key", "value");
-    const value = await db.get("key");
+## Why JotDB?
 
-    return new Response(`Value: ${value}`);
-  }
-};
-```
+JotDB combines the best of both worlds: the simplicity of NoSQL with the safety of schema validation. Here's what makes it special:
 
-### 4. **Deploy or run locally**
+- **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
 
-```bash
-wrangler dev
-# or
-wrangler deploy
-```
+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
 
-## 📝 Notes
+JotDB uses Cloudflare Durable Objects under the hood, which means you can organize your data in several ways:
 
-- **RPC support:** JotDB uses Cloudflare's new JavaScript-native RPC. You can call methods directly on the stub (e.g., `db.set(...)`, `db.get(...)`).
-- **No fetch needed:** You do not need to use HTTP fetch to communicate with your Durable Object—just call methods!
-- **TypeScript:** Use `DurableObjectNamespace<JotDB>` for full type safety.
-- **See the API section below for all available methods.**
+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}`));
+   ```
 
-## 📚 Full Example
+3. **Per-Event Store**: Create temporary stores for events or sessions
+   ```typescript
+   const eventDb = env.JOTDB.get(env.JOTDB.idFromName(`event:${eventId}`));
+   ```
 
-```ts
-import { JotDB } from 'jotdb';
+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.
 
-export interface Env {
-  JOTDB: DurableObjectNamespace<JotDB>;
-}
-
-export default {
-  async fetch(request: Request, env: Env) {
-    const id = env.JOTDB.idFromName("my-db");
-    const db = env.JOTDB.get(id);
-
-    await db.setSchema({
-      name: "string",
-      age: "number",
-      email: "email"
-    });
+## Installation
 
-    await db.setAll({
-      name: "Alice",
-      age: 42,
-      email: "alice@example.com"
-    });
+```bash
+# Using npm
+npm install jotdb
 
-    const all = await db.getAll();
+# Using yarn
+yarn add jotdb
 
-    return new Response(JSON.stringify(all, null, 2), {
-      headers: { "Content-Type": "application/json" }
-    });
-  }
-};
+# Using pnpm
+pnpm add jotdb
 ```
 
----
-
-A lightweight, schema-validated key-value store built on Cloudflare Durable Objects.
-
-## Features
-
-- Schema validation using Zod
-- Automatic schema inference
-- Audit logging
-- TypeScript support
-- Read-only mode
-- Auto-strip mode for schema validation
-
-## Installation
-
-```bash
-npm install jotdb
-# or
-bun add jotdb
+### Configure wrangler.jsonc
+
+```jsonc
+{
+  "durable_objects": {
+    "bindings": [
+      {
+        "name": "JOTDB",
+        "class_name": "JotDB"
+      }
+    ]
+  }
+}
 ```
 
-## Usage
+## Full Example
 
 ```typescript
 import { JotDB } from 'jotdb';
 
-// In your Worker
 export interface Env {
   JOTDB: DurableObjectNamespace;
 }
 
 export default {
   async fetch(request: Request, env: Env) {
-    const id = env.JOTDB.idFromName("my-db");
-    const db = env.JOTDB.get(id);
-    
-    // Set a value
-    await db.set("key", "value");
-    
-    // Get a value
-    const value = await db.get("key");
-    
-    // Set schema
-    await db.setSchema({
-      name: "string",
-      age: "number",
-      email: "email"
-    });
-    
-    // Set multiple values
-    await db.setAll({
-      name: "John",
-      age: 30,
-      email: "john@example.com"
+    // 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
-
-### Methods
-
-- `get<T>(key: string): Promise<T | undefined>`
-- `set<T>(key: string, value: T): Promise<void>`
-- `getAll(): Promise<Record<string, unknown>>`
-- `setAll(obj: Record<string, unknown>): Promise<void>`
-- `delete(key: string): Promise<void>`
-- `clear(): Promise<void>`
-- `keys(): Promise<string[]>`
-- `has(key: string): Promise<boolean>`
-- `getSchema(): Promise<SchemaDefinition>`
-- `setSchema(schema: SchemaDefinition): Promise<void>`
-- `getOptions(): Promise<JotDBOptions>`
-- `setOptions(opts: Partial<JotDBOptions>): Promise<void>`
-- `getAuditLog(): Promise<AuditLogEntry[]>`
-- `clearAuditLog(): Promise<void>`
-
-### Types
+## API Reference
+
+| Method | Description | Parameters | Returns |
+|--------|-------------|------------|---------|
+| `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>` |
+| `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
-type SchemaType = "string" | "number" | "boolean" | "email" | "array" | "object" | "any";
-type SchemaDefinition = Record<string, SchemaType>;
-
 interface JotDBOptions {
-  autoStrip: boolean;
-  readOnly: boolean;
+  autoStrip: boolean;  // Automatically strip unknown fields
+  readOnly: boolean;   // Enable read-only mode
 }
+```
 
-interface AuditLogEntry {
-  timestamp: number;
-  action: string;
-  keys: string[];
-}
+### Schema Types
+
+```typescript
+type SchemaType = "string" | "number" | "boolean" | "email" | "array" | "object" | "any";
 ```
 
 ## License
 
-MIT
+MIT License - feel free to use this in your own projects!
 
 ## Contributing
 
+Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
+
 1. Fork the repository
 2. Create your feature branch (`git checkout -b feature/amazing-feature`)
 3. Commit your changes (`git commit -m 'Add some amazing feature'`)
@@ -206,6 +159,8 @@ MIT
 
 ## Testing
 
-```bash
-bun test
-```
+Currently, testing is done manually in production. We're working on adding a comprehensive test suite. For now, you can test the functionality by:
+
+1. Deploying to Cloudflare Workers
+2. Using the example endpoints
+3. Verifying data persistence

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jotdb",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "type": "module",
   "main": "dist/index.js",
   "exports": {