@objectstack/objectql 0.9.0 → 0.9.2

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @objectstack/objectql
 
+## 0.9.2
+
+### Patch Changes
+
+- Updated dependencies
+  - @objectstack/spec@0.9.2
+  - @objectstack/core@0.9.2
+  - @objectstack/types@0.9.2
+
+## 0.9.1
+
+### Patch Changes
+
+- Patch release for maintenance and stability improvements. All packages updated with unified versioning.
+- Updated dependencies
+  - @objectstack/spec@0.9.1
+  - @objectstack/core@0.9.1
+  - @objectstack/types@0.9.1
+
 ## 0.8.2
 
 ### Patch Changes

package/README.md

@@ -10,6 +10,19 @@
 - **Plugin System**: Load objects and logic via standard Manifests.
 - **Middleware**: (Planned) Support for Hooks and Validators.
 
+## 🤖 AI Development Context
+
+**Role**: Data Engine / Query Layer
+**Usage**:
+- Use this package to execute data operations (`find`, `insert`).
+- Do NOT bypass this layer to access drivers directly unless building a driver.
+- This is the "Backend Brain" for data.
+
+**Key Concepts**:
+- `SchemaRegistry`: Holds all object definitions.
+- `ObjectQL`: The main facade.
+- `Driver`: Interface for storage adapters.
+
 ## Usage
 
 ### 1. Standalone Usage
@@ -91,6 +104,279 @@ await kernel.bootstrap();
 - **QueryPlanner**: (Internal) Normalizes simplified queries into `QueryAST`.
 - **Executor**: Routes AST to the correct driver.
 
+## Advanced Examples
+
+### Complex Queries
+
+```typescript
+// Filtering with multiple conditions
+const activeTasks = await ql.find('todo_task', {
+  where: {
+    $and: [
+      { status: 'active' },
+      { priority: { $gte: 3 } },
+      { due_date: { $lte: new Date() } }
+    ]
+  },
+  orderBy: [
+    { field: 'priority', order: 'desc' },
+    { field: 'due_date', order: 'asc' }
+  ],
+  limit: 50
+});
+
+// Text search
+const searchResults = await ql.find('todo_task', {
+  where: {
+    $or: [
+      { title: { $contains: 'urgent' } },
+      { description: { $contains: 'urgent' } }
+    ]
+  }
+});
+
+// Nested conditions
+const complexQuery = await ql.find('project', {
+  where: {
+    $and: [
+      { status: { $in: ['active', 'planning'] } },
+      {
+        $or: [
+          { budget: { $gt: 100000 } },
+          { priority: { $eq: 1 } }
+        ]
+      }
+    ]
+  }
+});
+```
+
+### Batch Operations
+
+```typescript
+// Batch insert
+const newTasks = [
+  { title: 'Task 1', priority: 1 },
+  { title: 'Task 2', priority: 2 },
+  { title: 'Task 3', priority: 3 }
+];
+
+for (const task of newTasks) {
+  await ql.insert('todo_task', task);
+}
+
+// Batch update
+const tasksToUpdate = await ql.find('todo_task', {
+  where: { status: 'pending' }
+});
+
+for (const task of tasksToUpdate) {
+  await ql.update('todo_task', task.id, {
+    status: 'in_progress',
+    started_at: new Date()
+  });
+}
+```
+
+### Working with Relationships
+
+```typescript
+// One-to-Many: Get project with tasks
+const project = await ql.find('project', {
+  where: { id: 'proj_123' },
+  include: ['tasks'] // Assumes 'tasks' is a relation field
+});
+
+// Many-to-One: Get task with project details
+const task = await ql.find('todo_task', {
+  where: { id: 'task_456' },
+  include: ['project']
+});
+
+// Manual join (when driver doesn't support relations)
+const tasks = await ql.find('todo_task', {
+  where: { project_id: 'proj_123' }
+});
+
+const project = await ql.find('project', {
+  where: { id: 'proj_123' }
+});
+
+const projectWithTasks = {
+  ...project[0],
+  tasks: tasks
+};
+```
+
+### Aggregations
+
+```typescript
+// Count records
+const totalTasks = await ql.count('todo_task', {
+  where: { status: 'active' }
+});
+
+// Sum (if driver supports)
+const totalBudget = await ql.aggregate('project', {
+  operation: 'sum',
+  field: 'budget',
+  where: { status: 'active' }
+});
+
+// Group by (if driver supports)
+const tasksByStatus = await ql.aggregate('todo_task', {
+  operation: 'count',
+  groupBy: ['status']
+});
+```
+
+### Multi-Datasource Queries
+
+```typescript
+import { PostgresDriver } from '@objectstack/driver-postgres';
+import { MongoDBDriver } from '@objectstack/driver-mongodb';
+import { RedisDriver } from '@objectstack/driver-redis';
+
+const ql = new ObjectQL();
+
+// Register multiple drivers
+const pgDriver = new PostgresDriver({ connectionString: 'postgres://...' });
+const mongoDriver = new MongoDBDriver({ url: 'mongodb://...' });
+const redisDriver = new RedisDriver({ host: 'localhost' });
+
+ql.registerDriver(pgDriver, false, 'postgres');
+ql.registerDriver(mongoDriver, false, 'mongodb');
+ql.registerDriver(redisDriver, false, 'redis');
+
+// Configure objects to use different datasources
+await ql.use({
+  name: 'multi-db-app',
+  objects: [
+    {
+      name: 'user',
+      datasource: 'postgres', // Users in PostgreSQL
+      fields: { /* ... */ }
+    },
+    {
+      name: 'product',
+      datasource: 'mongodb', // Products in MongoDB
+      fields: { /* ... */ }
+    },
+    {
+      name: 'session',
+      datasource: 'redis', // Sessions in Redis
+      fields: { /* ... */ }
+    }
+  ]
+});
+
+await ql.init();
+
+// Query automatically routes to correct datasource
+const users = await ql.find('user');      // → PostgreSQL
+const products = await ql.find('product'); // → MongoDB
+const sessions = await ql.find('session'); // → Redis
+```
+
+### Custom Hooks and Middleware
+
+```typescript
+// Register hooks for data operations
+ql.registerHook('beforeInsert', async (ctx) => {
+  console.log(`Creating ${ctx.object}:`, ctx.data);
+  
+  // Add timestamps
+  ctx.data.created_at = new Date();
+  ctx.data.updated_at = new Date();
+  
+  // Validate
+  if (ctx.object === 'user' && !ctx.data.email) {
+    throw new Error('Email is required');
+  }
+});
+
+ql.registerHook('afterInsert', async (ctx) => {
+  console.log(`Created ${ctx.object}:`, ctx.result);
+  
+  // Trigger events - get event bus from kernel or context
+  // Note: eventBus should be injected or accessed from context
+  const eventBus = ctx.getService?.('event-bus');
+  if (eventBus) {
+    await eventBus.emit('data:created', {
+      object: ctx.object,
+      id: ctx.result.id
+    });
+  }
+});
+
+ql.registerHook('beforeUpdate', async (ctx) => {
+  // Update timestamp
+  ctx.data.updated_at = new Date();
+});
+
+ql.registerHook('beforeDelete', async (ctx) => {
+  // Soft delete
+  if (ctx.object === 'user') {
+    throw new Error('Cannot delete users, use deactivate instead');
+  }
+});
+```
+
+### Transaction Support
+
+```typescript
+// If driver supports transactions
+const driver = ql.getDriver('default');
+
+if (driver.supports.transactions) {
+  await driver.beginTransaction();
+  
+  try {
+    await ql.insert('order', {
+      customer_id: 'cust_123',
+      total: 100.00
+    });
+    
+    await ql.update('inventory', 'inv_456', {
+      quantity: { $decrement: 1 }
+    });
+    
+    await driver.commitTransaction();
+  } catch (error) {
+    await driver.rollbackTransaction();
+    throw error;
+  }
+}
+```
+
+### Schema Migration
+
+```typescript
+// Add new field to existing object
+const currentSchema = ql.getSchema('todo_task');
+
+const updatedSchema = {
+  ...currentSchema,
+  fields: {
+    ...currentSchema.fields,
+    assignee: {
+      type: 'lookup',
+      reference: 'user',
+      label: 'Assignee'
+    }
+  }
+};
+
+// Re-register schema
+ql.registerObject(updatedSchema);
+
+// Driver might need to sync schema
+const driver = ql.getDriver('default');
+if (driver.syncSchema) {
+  await driver.syncSchema('todo_task', updatedSchema);
+}
+```
+
 ## Roadmap
 
 - [x] Basic CRUD

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@objectstack/objectql",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Isomorphic ObjectQL Engine for ObjectStack",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "dependencies": {
-    "@objectstack/core": "0.9.0",
-    "@objectstack/spec": "0.9.0",
-    "@objectstack/types": "0.9.0"
+    "@objectstack/core": "0.9.2",
+    "@objectstack/spec": "0.9.2",
+    "@objectstack/types": "0.9.2"
   },
   "devDependencies": {
     "typescript": "^5.0.0",