sqlite-zod-orm 3.0.0 → 3.2.0

package/README.md

@@ -1,314 +1,272 @@
-# SatiDB 🗄️
+# sqlite-zod-orm
 
-A modern, type-safe SQLite wrapper with **reactive editing**, **automatic relationships**, and **fluent APIs**. Built for TypeScript/JavaScript with Zod schema validation.
+Type-safe SQLite ORM for Bun. Define schemas with Zod, get a fully-typed database with automatic relationships, lazy navigation, and zero SQL.
 
-## ✨ Key Features
-
-- **🔄 Reactive Editing**: Change properties directly, auto-persists to database
-- **📊 Type-Safe Schemas**: Powered by Zod for runtime validation
-- **🔗 Automatic Relationships**: Belongs-to, one-to-many, many-to-many support
-- **📺 Event Subscriptions**: Listen to insert/update/delete events
-- **🏗️ Explicit Junction Tables**: Full control over many-to-many relationships
-- **🚀 Fluent API**: Intuitive, chainable operations
-- **⚡ Zero-Config**: Works with Bun SQLite out of the box
+```bash
+bun add sqlite-zod-orm
+```
 
-## 🚀 Quick Start
+## Quick Start
 
 ```typescript
-import { MyDatabase, z } from './satidb';
-
-// Define schemas with relationships
-const AuthorSchema = z.object({
-  name: z.string(),
-  posts: z.lazy(() => z.array(PostSchema)).optional(),
-});
-
-const PostSchema = z.object({
-  title: z.string(),
-  content: z.string(),
-  author: z.lazy(() => AuthorSchema).optional(),
-});
-
-// Create database
-const db = new MyDatabase(':memory:', {
-  authors: AuthorSchema,
-  posts: PostSchema,
+import { Database, z } from 'sqlite-zod-orm';
+
+const db = new Database(':memory:', {
+  users: z.object({
+    name: z.string(),
+    email: z.string().email(),
+    role: z.string().default('member'),
+  }),
 });
 
-// Use it!
-const author = db.authors.insert({ name: 'Jane Doe' });
-const post = author.posts.push({ title: 'Hello World', content: '...' });
-
-// Reactive editing - just change properties!
-post.title = 'Hello TypeScript'; // Automatically saved to DB
+const alice = db.users.insert({ name: 'Alice', email: 'alice@example.com', role: 'admin' });
+const admin = db.users.select().where({ role: 'admin' }).get();  // single row
+const all   = db.users.select().all();                           // all rows
 ```
 
-## 📖 Core Concepts
+---
 
-### Schemas & Relationships
+## Defining Relationships
 
-Define entities using Zod schemas with lazy relationships:
+FK columns go in your schema. The `relations` config declares which FK points to which table:
 
 ```typescript
-// One-to-many: Author has many Posts
-const AuthorSchema = z.object({
-  name: z.string(),
-  posts: z.lazy(() => z.array(PostSchema)).optional(), // one-to-many
-});
+const AuthorSchema = z.object({ name: z.string(), country: z.string() });
+const BookSchema   = z.object({ title: z.string(), year: z.number(), author_id: z.number().optional() });
 
-// Belongs-to: Post belongs to Author  
-const PostSchema = z.object({
-  title: z.string(),
-  author: z.lazy(() => AuthorSchema).optional(), // belongs-to
+const db = new Database(':memory:', {
+  authors: AuthorSchema,
+  books:   BookSchema,
+}, {
+  relations: {
+    books: { author_id: 'authors' },
+  },
 });
 ```
 
-### Explicit Junction Tables
+`books: { author_id: 'authors' }` tells the ORM that `books.author_id` is a foreign key referencing `authors.id`. The ORM automatically:
 
-For many-to-many relationships, define explicit junction entities with additional fields:
+- Adds `FOREIGN KEY (author_id) REFERENCES authors(id)` constraint
+- Infers the inverse one-to-many `authors → books`
+- Enables lazy navigation: `book.author()` and `author.books()`
+- Enables fluent joins: `db.books.select().join(db.authors).all()`
 
-```typescript
-// Many-to-many with rich junction table
-const PostTagSchema = z.object({
-  post: z.lazy(() => PostSchema).optional(),
-  tag: z.lazy(() => TagSchema).optional(),
-  appliedAt: z.date().default(() => new Date()),
-  appliedBy: z.string(),
-  priority: z.number().default(0),
-});
-
-// Usage
-const postTag = post.postTags.push({ 
-  tagId: tag.id, 
-  appliedBy: 'editor',
-  priority: 5 
-});
-```
+The nav method name is derived by stripping `_id` from the FK column: `author_id` → `author()`.
 
-**Why explicit junction tables?**
-- Full control over additional fields (timestamps, metadata, etc.)
-- Junction tables are queryable entities themselves
-- More flexible than auto-generated tables
-- Clearer data modeling
+---
 
-## 🎯 API Reference
+## Querying — `select()` is the only path
 
-### Creating & Querying
+All queries go through `select()`:
 
 ```typescript
-// Insert new entities
-const user = db.users.insert({ name: 'Alice', email: 'alice@example.com' });
-
-// Find multiple with conditions
-const activeUsers = db.users.find({ active: true, $limit: 10 });
-
-// Get single entity
-const user = db.users.get({ email: 'alice@example.com' });
-const userById = db.users.get('user-id-123');
+// Single row
+const user = db.users.select().where({ id: 1 }).get();
 
-// Update
-const updated = db.users.update('user-id', { name: 'Alice Smith' });
+// All matching rows
+const admins = db.users.select().where({ role: 'admin' }).all();
 
-// Upsert
-const user = db.users.upsert({ email: 'alice@example.com', name: 'Alice' });
+// All rows
+const everyone = db.users.select().all();
 
-// Delete
-db.users.delete('user-id');
+// Count
+const count = db.users.select().count();
 ```
 
-### Relationships
-
-```typescript
-// One-to-many: Add related entities
-const post = author.posts.push({ title: 'New Post', content: '...' });
-
-// Query related entities
-const authorPosts = author.posts(); // All posts
-const recentPosts = author.posts({ $limit: 5, $sortBy: 'createdAt:desc' });
+### Operators
 
-// Belongs-to: Navigate relationships
-const postAuthor = post.author();
+`$gt` `$gte` `$lt` `$lte` `$ne` `$in`
 
-// Get specific related entity
-const specificPost = author.post('post-id-123');
+```typescript
+const topScorers = db.users.select()
+  .where({ score: { $gt: 50 } })
+  .orderBy('score', 'desc')
+  .limit(10)
+  .all();
 ```
 
-### Reactive Editing
+### `$or`
 
 ```typescript
-const user = db.users.get('user-id');
+const results = db.users.select()
+  .where({ $or: [{ role: 'admin' }, { score: { $gt: 50 } }] })
+  .all();
+```
+
+### Fluent Join
 
-// Just change properties - automatically persists!
-user.name = 'New Name';
-user.email = 'new@email.com';
-user.active = false;
+Auto-infers foreign keys from relationships:
 
-// No need to call .save() or .update()
-// Changes are immediately persisted to database
+```typescript
+const rows = db.books.select('title', 'year')
+  .join(db.authors, ['name', 'country'])
+  .where({ year: { $gt: 1800 } })
+  .orderBy('year', 'asc')
+  .all();
+// → [{ title: 'War and Peace', year: 1869, authors_name: 'Leo Tolstoy', ... }]
 ```
 
-### Event Subscriptions
+### `db.query()` — Proxy Query (SQL-like)
+
+Full SQL-like control with destructured table aliases:
 
 ```typescript
-// Listen to database events
-db.users.subscribe('insert', (user) => {
-  console.log(`New user: ${user.name}`);
+const rows = db.query(c => {
+  const { authors: a, books: b } = c;
+  return {
+    select: { author: a.name, book: b.title, year: b.year },
+    join: [[b.author_id, a.id]],
+    where: { [a.country]: 'Russia' },
+    orderBy: { [b.year]: 'asc' },
+  };
 });
+```
 
-db.posts.subscribe('update', (post) => {
-  console.log(`Post updated: ${post.title}`);
-});
+---
 
-db.users.subscribe('delete', (user) => {
-  console.log(`User deleted: ${user.name}`);
-});
-```
+## Lazy Navigation
 
-### Transactions
+Relationship fields become callable methods on entities. The method name is the FK column with `_id` stripped:
 
 ```typescript
-const result = db.transaction(() => {
-  const author = db.authors.insert({ name: 'Jane' });
-  const post1 = author.posts.push({ title: 'Post 1' });
-  const post2 = author.posts.push({ title: 'Post 2' });
-  return { author, posts: [post1, post2] };
-});
+// belongs-to: book.author_id → book.author()
+const book = db.books.select().where({ title: 'War and Peace' }).get()!;
+const author = book.author();       // → { name: 'Leo Tolstoy', ... }
+
+// one-to-many: author → books
+const books = tolstoy.books();      // → [{ title: 'War and Peace' }, ...]
+
+// Chain
+const allByAuthor = book.author().books();
 ```
 
-## 🔗 Relationship Types
+---
 
-### One-to-Many
+## CRUD
 
 ```typescript
-const PersonalitySchema = z.object({
-  name: z.string(),
-  chats: z.lazy(() => z.array(ChatSchema)).optional(),
-});
+// Insert (defaults fill in automatically)
+const user = db.users.insert({ name: 'Alice', role: 'admin' });
 
-const ChatSchema = z.object({
-  title: z.string(),
-  personality: z.lazy(() => PersonalitySchema).optional(),
-});
+// Insert with FK
+const book = db.books.insert({ title: 'War and Peace', year: 1869, author_id: tolstoy.id });
 
-// Usage
-const personality = db.personalities.insert({ name: 'Assistant' });
-const chat = personality.chats.push({ title: 'Help Session' });
-const chatPersonality = chat.personality(); // Navigate back
-```
+// Read
+const one   = db.users.select().where({ id: 1 }).get();
+const some  = db.users.select().where({ role: 'admin' }).all();
+const all   = db.users.select().all();
+const count = db.users.select().count();
 
-### Many-to-Many (Explicit Junction)
+// Entity-level update
+user.update({ role: 'superadmin' });
 
-```typescript
-// Define all three entities
-const UserSchema = z.object({
-  name: z.string(),
-  likes: z.lazy(() => z.array(LikeSchema)).optional(),
-});
+// Update by ID
+db.users.update(1, { role: 'superadmin' });
 
-const ProductSchema = z.object({
-  name: z.string(),
-  likes: z.lazy(() => z.array(LikeSchema)).optional(),
-});
+// Fluent update with WHERE
+db.users.update({ role: 'member' }).where({ role: 'guest' }).exec();
 
-// Junction table with additional fields
-const LikeSchema = z.object({
-  user: z.lazy(() => UserSchema).optional(),
-  product: z.lazy(() => ProductSchema).optional(),
-  rating: z.number().min(1).max(5),
-  likedAt: z.date().default(() => new Date()),
-});
+// Upsert
+db.users.upsert({ name: 'Alice' }, { name: 'Alice', role: 'admin' });
 
-// Usage
-const user = db.users.insert({ name: 'Alice' });
-const product = db.products.insert({ name: 'Laptop' });
+// Delete
+db.users.delete(1);
+```
 
-// Create relationship with metadata
-const like = user.likes.push({ 
-  productId: product.id, 
-  rating: 5 
-});
+### Auto-Persist Proxy
 
-// Query from both sides
-const userLikes = user.likes().map(l => l.product()); // Products Alice likes
-const productLikers = product.likes().map(l => l.user()); // Users who like laptop
+Setting a property on an entity auto-updates the DB:
 
-// Junction table is a full entity
-like.rating = 4; // Reactive update on junction table!
+```typescript
+const alice = db.users.select().where({ id: 1 }).get()!;
+alice.score = 200;    // → UPDATE users SET score = 200 WHERE id = 1
 ```
 
-## 📝 Advanced Usage
+---
 
-### Custom ID Generation
+## Schema Validation
 
-IDs are automatically generated based on entity data hash. For custom IDs:
+Zod validates every insert and update at runtime:
 
 ```typescript
-const entity = db.entities.insert({ 
-  id: 'custom-id-123', // Explicit ID
-  name: 'Custom Entity' 
-});
+db.users.insert({ name: '', email: 'bad', age: -1 });  // throws ZodError
 ```
 
-### Query Options
+---
+
+## Indexes
 
 ```typescript
-const results = db.posts.find({
-  published: true,
-  $limit: 10,
-  $offset: 20,
-  $sortBy: 'createdAt:desc'
+const db = new Database(':memory:', schemas, {
+  indexes: {
+    users: ['email', ['name', 'role']],
+    books: ['author_id', 'year'],
+  },
 });
 ```
 
-### Schema Validation
+---
 
-All data is validated against Zod schemas:
+## Change Tracking & Events
 
 ```typescript
-const UserSchema = z.object({
-  name: z.string().min(2),
-  email: z.string().email(),
-  age: z.number().optional(),
-});
+const db = new Database(':memory:', schemas, { changeTracking: true });
+db.getChangesSince(0);
 
-// Throws validation error if invalid
-const user = db.users.insert({ 
-  name: 'A', // Too short!
-  email: 'invalid-email' // Invalid format!
-});
+db.users.subscribe('insert', (user) => console.log('New:', user.name));
 ```
 
-## 🎯 Best Practices
-
-1. **Use Explicit Junction Tables**: Define junction entities with additional fields rather than relying on auto-generated tables
-2. **Leverage Reactive Editing**: Change properties directly instead of calling update methods
-3. **Subscribe to Events**: Use subscriptions for real-time updates and side effects
-4. **Validate with Zod**: Define comprehensive schemas with proper validation rules
-5. **Use Transactions**: Wrap related operations in transactions for data consistency
+---
 
-## 🔄 Migration from Traditional ORMs
+## Smart Polling
 
 ```typescript
-// Traditional ORM
-const user = await User.findById(id);
-user.name = 'New Name';
-await user.save(); // Explicit save
-
-// SatiDB
-const user = db.users.get(id);
-user.name = 'New Name'; // Automatically saved!
-```
+const unsub = db.users.select()
+  .where({ role: 'admin' })
+  .subscribe((admins) => {
+    console.log('Admin list changed:', admins);
+  }, { interval: 1000 });
 
-## 🛠️ Requirements
+unsub();
+```
 
-- Bun runtime with SQLite support
-- TypeScript (recommended) or JavaScript
-- Zod for schema validation
+---
 
-## 📄 License
+## Examples & Tests
 
-MIT License - feel free to use in your projects!
+```bash
+bun examples/example.ts    # comprehensive demo
+bun test                    # 91 tests
+```
 
 ---
 
-**SatiDB** - Reactive, type-safe database operations made simple. 🚀
+## API Reference
+
+| Method | Description |
+|---|---|
+| `new Database(path, schemas, options?)` | Create database with Zod schemas |
+| **Querying** | |
+| `db.table.select(...cols?).where(filter).get()` | Single row |
+| `db.table.select(...cols?).where(filter).all()` | Array of rows |
+| `db.table.select().count()` | Count rows |
+| `db.table.select().join(db.other, cols?).all()` | Fluent join (auto FK) |
+| `db.query(c => { ... })` | Proxy callback (SQL-like JOINs) |
+| **Writing** | |
+| `db.table.insert(data)` | Insert with validation |
+| `db.table.update(id, data)` | Update by ID |
+| `db.table.update(data).where(filter).exec()` | Fluent update |
+| `db.table.upsert(match, data)` | Insert or update |
+| `db.table.delete(id)` | Delete by ID |
+| **Navigation** | |
+| `entity.navMethod()` | Lazy navigation (FK name minus `_id`) |
+| `entity.update(data)` | Update entity in-place |
+| `entity.delete()` | Delete entity |
+| **Events** | |
+| `db.table.subscribe(event, callback)` | Listen for insert/update/delete |
+| `db.table.select().subscribe(cb, opts)` | Smart polling |
+| `db.getChangesSince(version, table?)` | Change tracking |
+
+## License
+
+MIT