@toonstore/torm 0.2.0 → 0.3.0

package/README.md

@@ -1,17 +1,32 @@
 # @toonstore/torm
 
-> ToonStore ORM Client for Node.js & TypeScript
+> ToonStoreDB ORM Client for Node.js & TypeScript
 
-A Mongoose-style ORM client for ToonStore, providing type-safe models, validation, and query building.
+A Mongoose-style ORM client for ToonStoreDB, providing type-safe models, validation, and query building.
+
+> **What is ToonStoreDB?** ToonStoreDB is a blazingly fast embedded database with a built-in caching layer. This SDK lets you work with ToonStoreDB using a familiar Mongoose-like API.
+
+## 🎯 Quick Summary
+
+**What is this?** A TypeScript/JavaScript ORM library (like Mongoose for MongoDB or Drizzle for PostgreSQL) that lets you easily work with ToonStoreDB.
+
+**What do I need?**
+- ✅ ToonStoreDB server running (the database)
+- ✅ This npm package (`@toonstore/torm`)
+- ✅ Node.js/TypeScript project
+
+**What is TORM Studio?** An optional visual management tool (like phpMyAdmin or MongoDB Compass) for managing your ToonStoreDB data - NOT required for the SDK to work.
 
 ## ✨ Features
 
-- ✅ **Type-Safe** - Full TypeScript support
-- ✅ **Validation** - Built-in validators (email, URL, min/max, patterns)
-- ✅ **Query Builder** - Fluent API for filtering and sorting
-- ✅ **Schema Definition** - Define your data models
-- ✅ **Async/Await** - Promise-based API
-- ✅ **Direct Redis Connection** - No server required, connects directly to Redis/ToonStore
+- ✅ **Type-Safe** - Full TypeScript support with generics
+- ✅ **Direct Database Connection** - Connects directly to ToonStoreDB
+- ✅ **Mongoose-Like API** - Familiar API for easy adoption
+- ✅ **Schema Validation** - Built-in validators (email, URL, min/max, patterns, custom)
+- ✅ **Query Builder** - Fluent API for filtering, sorting, and pagination
+- ✅ **Async/Await** - Modern promise-based API
+- ✅ **Auto-Generated IDs** - Automatic document ID generation with timestamps
+- ✅ **Zero Configuration** - Works out of the box with sensible defaults
 
 ## 📦 Installation
 
@@ -19,39 +34,52 @@ A Mongoose-style ORM client for ToonStore, providing type-safe models, validatio
 npm install @toonstore/torm
 # or
 yarn add @toonstore/torm
+# or
+pnpm add @toonstore/torm
 ```
 
 ## 🚀 Quick Start
 
 ### Prerequisites
 
-Make sure Redis is running:
+**ToonStoreDB must be running:**
+
 ```bash
-redis-server
+# Start ToonStoreDB
+./toonstoredb
 # Default: localhost:6379
+
+# Or using Docker
+docker run -d -p 6379:6379 toonstoredb/toonstoredb:latest
+
+# Or install from releases
+# Download from: https://github.com/toonstore/toonstoredb/releases
 ```
 
+> **Note:** ToonStoreDB is a high-performance database with Redis-compatible protocol. The SDK connects directly to your ToonStoreDB instance. No additional servers or middleware needed.
+
 ### Basic Usage
 
 ```typescript
 import { TormClient } from '@toonstore/torm';
 
-// 1. Create client (connects directly to Redis)
+// 1. Connect to ToonStoreDB
 const torm = new TormClient({
   host: 'localhost',
   port: 6379,
   // Or use connection URL:
-  // url: 'redis://localhost:6379'
+  // url: 'toonstoredb://localhost:6379'
 });
 
-// 2. Define model with schema
+// 2. Define your model interface
 interface User {
-  id: string;
   name: string;
   email: string;
   age: number;
+  website?: string;
 }
 
+// 3. Create model with validation schema
 const User = torm.model<User>('User', {
   name: {
     type: 'string',
@@ -70,35 +98,118 @@ const User = torm.model<User>('User', {
     min: 13,
     max: 120,
   },
+  website: {
+    type: 'string',
+    url: true,
+  },
 });
 
-// 3. Create document
+// 4. Create document (ID auto-generated)
 const user = await User.create({
-  id: 'user:1',
   name: 'Alice',
   email: 'alice@example.com',
   age: 30,
+  website: 'https://alice.dev',
 });
+console.log(user._id); // Auto-generated: "1736076000000-abc123xyz"
 
-// 4. Find documents
+// 5. Find documents
 const allUsers = await User.find();
-const specificUser = await User.findById('user:1');
+const specificUser = await User.findById(user._id);
+const foundUser = await User.findOne({ email: 'alice@example.com' });
 
-// 5. Query with filters
+// 6. Query with filters
 const adults = await User.query()
-  .filter('age', 'gte', 18)
+  .where('age', 'gte', 18)
   .sort('name', 'asc')
   .limit(10)
   .exec();
 
-// 6. Update document
-await User.update('user:1', { age: 31 });
+// 7. Update document
+const updated = await User.update(user._id, { age: 31 });
+
+// 8. Delete document
+await User.delete(user._id);
 
-// 7. Delete document
-await User.delete('user:1');
+// 9. Delete many documents
+await User.deleteMany({ age: { $lt: 18 } });
 
-// 8. Count documents
+// 10. Count documents
 const count = await User.count();
+
+// 11. Disconnect when done
+await torm.disconnect();
+```
+
+## 🛠️ CLI Commands
+
+TORM includes a powerful CLI for database management and development workflows:
+
+### TORM Studio
+
+Launch the visual database manager (bundled with the SDK):
+
+```bash
+# Start TORM Studio
+npx torm studio
+```
+
+**First Run:** If no `torm.config.ts` exists, it will be auto-generated. Edit it with your database credentials, then run `npx torm studio` again.
+
+**Access:** http://localhost:4983
+
+**Configuration:**
+Create or edit `torm.config.ts` in your project root:
+```typescript
+export default {
+  dbCredentials: {
+    host: 'localhost',  // or cloud host
+    port: 6379,
+    // For cloud/auth:
+    // password: 'your-password',
+    // url: 'redis://user:pass@host:port',
+  },
+  studio: {
+    port: 4983,  // default
+  },
+};
+```
+
+**Features:**
+- 📊 Visual database browser - browse collections and documents
+- ✏️ Create, read, update, delete records with UI
+- 🔍 Search and filter data
+- 📈 Real-time database statistics
+- 🎨 Modern dark-themed interface
+- ✅ No separate installation - fully bundled with npm package!
+- 🌐 Works with local or cloud-hosted ToonStoreDB
+
+**Custom Port:**
+```bash
+npx torm studio --port 8080
+```
+
+### Migrations (Coming Soon)
+
+```bash
+# Generate migration from schema changes
+npx torm generate
+
+# Run pending migrations
+npx torm migrate
+
+# Check migration status
+npx torm migrate:status
+```
+
+### Type Generation (Coming Soon)
+
+```bash
+# Generate TypeScript types from your schema
+npx torm generate
+
+# Watch mode for development
+npx torm generate --watch
 ```
 
 ## 📖 API Documentation
@@ -112,35 +223,45 @@ const torm = new TormClient(options?: TormClientOptions);
 ```
 
 **Options:**
-- `host` (string) - Redis host (default: `localhost`)
-- `port` (number) - Redis port (default: `6379`)
-- `url` (string) - Redis connection URL (e.g., `redis://localhost:6379`)
-- All standard `ioredis` options are supported
+- `host` (string) - ToonStoreDB host (default: `localhost`)
+- `port` (number) - ToonStoreDB port (default: `6379`)
+- `url` (string) - ToonStoreDB connection URL (e.g., `toonstoredb://localhost:6379`)
+- All standard connection options are supported
 
 #### Methods
 
 - `model<T>(name, schema?, options?)` - Create a model
-- `health()` - Check Redis connection health
-- `disconnect()` - Close Redis connection
-- `isConnected()` - Check if connected to Redis
+- `health()` - Check database connection health
+- `disconnect()` - Close database connection
+- `isConnected()` - Check if connected to database
+- `getClient()` - Get underlying database client instance
 
 ### Model
 
+All documents automatically include:
+- `_id` - Auto-generated unique ID
+- `_createdAt` - ISO timestamp of creation
+- `_updatedAt` - ISO timestamp of last update
+
 #### CRUD Operations
 
 ```typescript
-// Create
+// Create (ID auto-generated)
 const doc = await Model.create(data);
+// Returns: { ...data, _id, _createdAt, _updatedAt }
 
 // Read
 const all = await Model.find();
 const one = await Model.findById(id);
+const match = await Model.findOne({ email: 'user@example.com' });
 
 // Update
 const updated = await Model.update(id, data);
 
 // Delete
 const deleted = await Model.delete(id);
+await Model.deleteMany(); // Delete all
+await Model.deleteMany({ status: 'inactive' }); // Delete matching
 
 // Count
 const count = await Model.count();
@@ -150,16 +271,16 @@ const count = await Model.count();
 
 ```typescript
 const results = await Model.query()
-  .filter(field, operator, value)  // Add filter
-  .where(field, value)             // Shorthand for .filter(field, 'eq', value)
-  .sort(field, order)              // Sort results
+  .where(field, operator, value)   // Add filter
+  .equals(field, value)            // Shorthand for .where(field, 'eq', value)
+  .sort(field, order)              // Sort results ('asc' | 'desc')
   .limit(n)                        // Limit results
-  .skip(n)                         // Skip results
+  .skip(n)                         // Skip results (pagination)
   .exec();                         // Execute query
 
 // Count with filters
 const count = await Model.query()
-  .filter('status', 'eq', 'active')
+  .where('status', 'eq', 'active')
   .count();
 ```
 
@@ -219,16 +340,26 @@ age: { type: 'number', min: 0, max: 120 }
 // Pattern matching
 phone: { type: 'string', pattern: /^\d{10}$/ }
 
-// Custom validation
+// Custom validation (sync or async)
 username: {
   type: 'string',
   validate: (value) => /^[a-z0-9_]+$/.test(value),
 }
+
+// Async custom validation
+email: {
+  type: 'string',
+  validate: async (value) => {
+    // Check if email is already taken
+    const existing = await User.findOne({ email: value });
+    return !existing;
+  },
+}
 ```
 
 ## 📝 Examples
 
-### Example 1: User Management
+### Example 1: User Management System
 
 ```typescript
 import { TormClient } from '@toonstore/torm';
@@ -236,10 +367,10 @@ import { TormClient } from '@toonstore/torm';
 const torm = new TormClient();
 
 interface User {
-  id: string;
   username: string;
   email: string;
   age: number;
+  role: 'admin' | 'user';
 }
 
 const User = torm.model<User>('User', {
@@ -258,33 +389,43 @@ const User = torm.model<User>('User', {
     type: 'number',
     min: 18,
   },
+  role: {
+    type: 'string',
+    required: true,
+  },
 });
 
 // Create users
-await User.create({
-  id: 'user:1',
+const alice = await User.create({
   username: 'alice',
   email: 'alice@example.com',
   age: 30,
+  role: 'admin',
 });
 
-// Find adults
-const adults = await User.query()
-  .filter('age', 'gte', 18)
+// Find by role
+const admins = await User.query()
+  .where('role', 'eq', 'admin')
   .sort('username', 'asc')
   .exec();
+
+// Find adults sorted by age
+const adults = await User.query()
+  .where('age', 'gte', 18)
+  .sort('age', 'desc')
+  .exec();
 ```
 
-### Example 2: Blog Posts
+### Example 2: Blog Posts with Tags
 
 ```typescript
 interface Post {
-  id: string;
   title: string;
   content: string;
-  author_id: string;
+  authorId: string;
   published: boolean;
   tags: string[];
+  views: number;
 }
 
 const Post = torm.model<Post>('Post', {
@@ -299,7 +440,7 @@ const Post = torm.model<Post>('Post', {
     required: true,
     minLength: 10,
   },
-  author_id: {
+  authorId: {
     type: 'string',
     required: true,
   },
@@ -309,41 +450,48 @@ const Post = torm.model<Post>('Post', {
   tags: {
     type: 'array',
   },
+  views: {
+    type: 'number',
+    min: 0,
+  },
 });
 
 // Create post
-await Post.create({
-  id: 'post:1',
+const post = await Post.create({
   title: 'Getting Started with TORM',
-  content: 'TORM is an amazing ORM for ToonStore...',
-  author_id: 'user:1',
+  content: 'TORM is an amazing ORM for ToonStoreDB with type-safe models and validation...',
+  authorId: alice._id,
   published: true,
-  tags: ['orm', 'database', 'toonstore'],
+  tags: ['orm', 'database', 'toonstore', 'redis'],
+  views: 0,
 });
 
 // Find published posts
-const published = await Post.query()
-  .filter('published', 'eq', true)
-  .sort('created_at', 'desc')
+const publishedPosts = await Post.query()
+  .where('published', 'eq', true)
+  .sort('_createdAt', 'desc')
   .limit(10)
   .exec();
 
 // Find posts by author
-const authorPosts = await Post.query()
-  .filter('author_id', 'eq', 'user:1')
+const alicePosts = await Post.query()
+  .where('authorId', 'eq', alice._id)
   .exec();
+
+// Update view count
+await Post.update(post._id, { views: post.views + 1 });
 ```
 
-### Example 3: E-Commerce Products
+### Example 3: E-Commerce Product Catalog
 
 ```typescript
 interface Product {
-  id: string;
   name: string;
   price: number;
   stock: number;
   sku: string;
   category: string;
+  description?: string;
 }
 
 const Product = torm.model<Product>('Product', {
@@ -368,31 +516,82 @@ const Product = torm.model<Product>('Product', {
   },
 });
 
-// Create product
-await Product.create({
-  id: 'product:1',
-  name: 'Laptop',
-  price: 999.99,
-  stock: 50,
+// Create products
+const laptop = await Product.create({
+  name: 'Gaming Laptop',
+  price: 1299.99,
+  stock: 15,
   sku: 'LAP-12345',
   category: 'electronics',
+  description: 'High-performance gaming laptop with RTX 4070',
 });
 
 // Find products in stock
 const inStock = await Product.query()
-  .filter('stock', 'gt', 0)
+  .where('stock', 'gt', 0)
   .sort('price', 'asc')
   .exec();
 
+// Find by category with pagination
+const electronics = await Product.query()
+  .where('category', 'eq', 'electronics')
+  .sort('name', 'asc')
+  .skip(0)
+  .limit(20)
+  .exec();
+
 // Find expensive products
-const expensive = await Product.query()
-  .filter('price', 'gte', 1000)
+const premium = await Product.query()
+  .where('price', 'gte', 1000)
+  .sort('price', 'desc')
+  .exec();
+
+// Low stock alert
+const lowStock = await Product.query()
+  .where('stock', 'lt', 10)
   .exec();
 ```
 
+## 🔄 Migration from v0.1.x
+
+Version 0.2.0 introduces breaking changes:
+
+### What Changed
+- **No more HTTP server required** - SDK now connects directly to ToonStoreDB
+- **Auto-generated IDs** - No need to provide `id` field, use `_id` instead
+- **New connection options** - Use `host`, `port`, or `url` for ToonStoreDB connection
+
+### Migration Steps
+
+```typescript
+// v0.1.x (OLD - required TORM server via HTTP)
+const torm = new TormClient({
+  baseURL: 'http://localhost:3001',
+});
+
+const user = await User.create({
+  id: 'user:1',
+  name: 'Alice',
+});
+
+// v0.2.x (NEW - direct ToonStoreDB connection)
+const torm = new TormClient({
+  host: 'localhost',
+  port: 6379,
+});
+
+const user = await User.create({
+  name: 'Alice', // No id needed
+});
+console.log(user._id); // Auto-generated
+```
+
 ## 🧪 Running Examples
 
 ```bash
+# Make sure ToonStoreDB is running
+./toonstoredb
+
 # Install dependencies
 npm install
 
@@ -403,7 +602,7 @@ npm run build
 npm run example
 ```
 
-## 🛠️ Development
+## 🏗️ Development
 
 ```bash
 # Install dependencies
@@ -412,15 +611,93 @@ npm install
 # Build TypeScript
 npm run build
 
-# Watch mode (auto-rebuild)
+# Watch mode (auto-rebuild on changes)
 npm run dev
+
+# Run tests
+npm test
+```
+
+## 🌟 Why TORM?
+
+- **Standalone SDK** - No TORM server needed, just ToonStoreDB
+- **Type Safety** - Full TypeScript support with generics
+- **Familiar API** - If you know Mongoose, you know TORM
+- **High Performance** - Leverages ToonStoreDB's blazing fast speed (5.28M ops/sec)
+- **Validation Built-in** - Comprehensive validation without extra libraries
+- **Modern Async/Await** - Clean, readable promise-based code
+
+## 🏢 Architecture
+
 ```
+Your Node.js App → @toonstore/torm SDK → ToonStoreDB
+```
+
+**What you need to run:**
+- ✅ ToonStoreDB server (the database)
+- ✅ Your Node.js app with this SDK
+
+**What you DON'T need:**
+- ❌ TORM Server (that's only for TORM Studio UI - a separate optional visual management tool)
+- ❌ Any HTTP server or API layer
+- ❌ Redis installation (ToonStoreDB is the database, it just uses Redis-compatible protocol internally)
+
+## 🗺️ Roadmap
+
+**SDK Features:**
+- [ ] Relationships (references between models)
+- [ ] Hooks (pre/post save, update, delete)
+- [ ] Indexes and search optimization
+- [ ] Transactions support
+- [ ] Aggregation pipelines
+- [ ] Virtual fields
+- [ ] Plugins system
+
+**CLI Tools:**
+- [x] TORM Studio (bundled Node.js server) ✅
+- [ ] Schema migrations (`torm generate`, `torm migrate`)
+- [ ] Type generation from schemas
+- [ ] Database seeding
+- [ ] Schema validation and linting
+
+**Studio Enhancements:**
+- [ ] Custom domain (local.torm.studio via DNS) - no hosts file needed
+- [ ] Advanced query builder UI
+- [ ] Export/import data
+- [ ] Real-time collaboration
+- [ ] Schema visualization
+
+**Migration System (Planned):**
+```bash
+# Generate migration from model changes
+torm generate --name add_users_table
+
+# Run migrations
+torm migrate
+
+# Rollback
+torm migrate:rollback
+
+# Check status
+torm migrate:status
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
 
 ## 📄 License
 
 MIT
 
-## 🙏 Credits
+## 🔗 Links
+
+- [ToonStoreDB](https://github.com/toonstore/toonstoredb) - The blazingly fast database
+- [TORM](https://github.com/toonstore/torm) - Multi-language ORM with Studio
+- [TOON Format](https://github.com/toon-format/toon) - The data format specification
+- [NPM Package](https://www.npmjs.com/package/@toonstore/torm)
+- [TORM Studio Guide](https://github.com/toonstore/torm/blob/main/docs/STUDIO.md)
+
+## 💬 Support
 
-- Inspired by [Mongoose](https://mongoosejs.com/)
-- Built for [ToonStore](https://github.com/toon-format/toon)
+For questions and support, please open an issue on GitHub.

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * TORM CLI
+ * Command-line interface for ToonStoreDB ORM
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;;GAGG"}