@objectstack/runtime 0.9.0 → 0.9.2

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @objectstack/runtime
 
+## 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

@@ -12,6 +12,16 @@ The runtime package provides the **Standard Library** for the ObjectStack Operat
 - **Core Integration**: Re-exports `ObjectKernel` for convenience
 - **Capability Contracts**: Abstract interfaces for HTTP server and data persistence
 
+## 🤖 AI Development Context
+
+**Role**: Server Runtime & REST API
+**Usage**:
+- Use `RestServer` to spawn HTTP endpoints.
+- Configures the HTTP layer.
+
+**Key Concepts**:
+- `RestServer`: Generates `/api/*` endpoints from ObjectQL schemas.
+
 ## Installation
 
 ```bash
@@ -268,6 +278,302 @@ See the `examples/` directory for complete examples:
 4. **Use hooks**: Decouple plugins with event system
 5. **Handle errors**: Implement proper error handling in lifecycle methods
 
+## Common Plugin Patterns
+
+### Service Provider Pattern
+
+```typescript
+import { Plugin, PluginContext } from '@objectstack/core';
+
+export class DatabasePlugin implements Plugin {
+  name = 'database';
+  private connection: any;
+  
+  async init(ctx: PluginContext) {
+    // Initialize connection
+    this.connection = await createConnection({
+      host: 'localhost',
+      database: 'myapp'
+    });
+    
+    // Register as service
+    ctx.registerService('database', this.connection);
+    
+    ctx.logger.info('Database connected');
+  }
+  
+  async destroy() {
+    // Cleanup
+    await this.connection.close();
+  }
+}
+```
+
+### Service Consumer Pattern
+
+```typescript
+import { Plugin, PluginContext } from '@objectstack/core';
+
+export class RepositoryPlugin implements Plugin {
+  name = 'repository';
+  dependencies = ['database']; // Ensure database loads first
+  
+  async init(ctx: PluginContext) {
+    // Get dependency
+    const db = ctx.getService('database');
+    
+    // Create and register repository
+    const repo = new UserRepository(db);
+    ctx.registerService('user-repository', repo);
+  }
+}
+```
+
+### Event-Driven Pattern
+
+```typescript
+import { Plugin, PluginContext } from '@objectstack/core';
+
+// Publisher
+export class DataPlugin implements Plugin {
+  name = 'data';
+  
+  async init(ctx: PluginContext) {
+    const service = {
+      async create(entity: string, data: any) {
+        const result = await db.insert(entity, data);
+        
+        // Trigger event
+        await ctx.trigger('data:created', { entity, data: result });
+        
+        return result;
+      }
+    };
+    
+    ctx.registerService('data', service);
+  }
+}
+
+// Subscriber
+export class AuditPlugin implements Plugin {
+  name = 'audit';
+  dependencies = ['data'];
+  
+  async init(ctx: PluginContext) {
+    // Listen to events
+    ctx.hook('data:created', async ({ entity, data }) => {
+      ctx.logger.info(`Audit: ${entity} created`, { id: data.id });
+      
+      await auditLog.write({
+        action: 'create',
+        entity,
+        entityId: data.id,
+        timestamp: new Date()
+      });
+    });
+  }
+}
+```
+
+### Configuration Pattern
+
+```typescript
+import { Plugin, PluginContext } from '@objectstack/core';
+import { z } from 'zod';
+
+const ConfigSchema = z.object({
+  apiKey: z.string(),
+  endpoint: z.string().url(),
+  timeout: z.number().default(5000)
+});
+
+export class ApiPlugin implements Plugin {
+  name = 'api-client';
+  
+  constructor(private config: z.infer<typeof ConfigSchema>) {
+    // Validate config
+    ConfigSchema.parse(config);
+  }
+  
+  async init(ctx: PluginContext) {
+    const client = new ApiClient({
+      apiKey: this.config.apiKey,
+      endpoint: this.config.endpoint,
+      timeout: this.config.timeout
+    });
+    
+    ctx.registerService('api-client', client);
+  }
+}
+
+// Usage
+kernel.use(new ApiPlugin({
+  apiKey: process.env.API_KEY,
+  endpoint: 'https://api.example.com',
+  timeout: 10000
+}));
+```
+
+### Factory Pattern
+
+```typescript
+import { Plugin, PluginContext } from '@objectstack/core';
+
+export class ConnectionPoolPlugin implements Plugin {
+  name = 'connection-pool';
+  private pool: any;
+  
+  async init(ctx: PluginContext) {
+    this.pool = {
+      connections: new Map(),
+      
+      getConnection(name: string) {
+        if (!this.connections.has(name)) {
+          this.connections.set(name, createConnection(name));
+        }
+        return this.connections.get(name);
+      },
+      
+      closeAll() {
+        for (const conn of this.connections.values()) {
+          conn.close();
+        }
+        this.connections.clear();
+      }
+    };
+    
+    ctx.registerService('connection-pool', this.pool);
+  }
+  
+  async destroy() {
+    // Use stored reference from init phase
+    if (this.pool) {
+      this.pool.closeAll();
+    }
+  }
+}
+```
+
+### Middleware Pattern
+
+```typescript
+import { Plugin, PluginContext } from '@objectstack/core';
+
+export class LoggingMiddleware implements Plugin {
+  name = 'logging-middleware';
+  dependencies = ['http-server'];
+  
+  async start(ctx: PluginContext) {
+    const server = ctx.getService('http-server');
+    
+    // Register middleware
+    server.use(async (req, res, next) => {
+      const start = Date.now();
+      
+      ctx.logger.info('Request', {
+        method: req.method,
+        path: req.path
+      });
+      
+      await next();
+      
+      const duration = Date.now() - start;
+      ctx.logger.info('Response', {
+        method: req.method,
+        path: req.path,
+        status: res.statusCode,
+        duration
+      });
+    });
+  }
+}
+```
+
+### Lazy Loading Pattern
+
+```typescript
+import { Plugin, PluginContext } from '@objectstack/core';
+
+export class HeavyServicePlugin implements Plugin {
+  name = 'heavy-service';
+  private instance: any = null;
+  
+  async init(ctx: PluginContext) {
+    // Register factory instead of instance
+    const factory = {
+      async getInstance() {
+        if (!this.instance) {
+          ctx.logger.info('Lazy loading heavy service...');
+          this.instance = await loadHeavyService();
+        }
+        return this.instance;
+      }
+    };
+    
+    ctx.registerService('heavy-service', factory);
+  }
+}
+
+// Usage
+const factory = kernel.getService('heavy-service');
+const service = await factory.getInstance(); // Loaded only when needed
+```
+
+### Health Check Pattern
+
+```typescript
+import { Plugin, PluginContext } from '@objectstack/core';
+
+export class HealthCheckPlugin implements Plugin {
+  name = 'health-check';
+  dependencies = ['http-server', 'database', 'cache'];
+  
+  async start(ctx: PluginContext) {
+    const server = ctx.getService('http-server');
+    
+    server.get('/health', async (req, res) => {
+      const checks = await Promise.all([
+        this.checkDatabase(ctx),
+        this.checkCache(ctx),
+        this.checkDiskSpace()
+      ]);
+      
+      const healthy = checks.every(c => c.healthy);
+      
+      res.status(healthy ? 200 : 503).json({
+        status: healthy ? 'healthy' : 'unhealthy',
+        checks
+      });
+    });
+  }
+  
+  private async checkDatabase(ctx: PluginContext) {
+    try {
+      const db = ctx.getService('database');
+      await db.ping();
+      return { name: 'database', healthy: true };
+    } catch (error) {
+      return { name: 'database', healthy: false, error: error.message };
+    }
+  }
+  
+  private async checkCache(ctx: PluginContext) {
+    try {
+      const cache = ctx.getService('cache');
+      await cache.ping();
+      return { name: 'cache', healthy: true };
+    } catch (error) {
+      return { name: 'cache', healthy: false, error: error.message };
+    }
+  }
+  
+  private async checkDiskSpace() {
+    // Implementation
+    return { name: 'disk', healthy: true };
+  }
+}
+```
+
 ## Documentation
 
 - [MiniKernel Guide](../../MINI_KERNEL_GUIDE.md) - Complete API documentation and patterns

package/dist/index.d.ts

@@ -4,5 +4,6 @@ export { AppPlugin } from './app-plugin.js';
 export { HttpServer } from './http-server.js';
 export { RestServer } from './rest-server.js';
 export { RouteManager, RouteGroupBuilder } from './route-manager.js';
+export type { RouteEntry } from './route-manager.js';
 export { MiddlewareManager } from './middleware.js';
 export * from '@objectstack/core';

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@objectstack/runtime",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "ObjectStack Core Runtime & Query Engine",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "dependencies": {
-    "@objectstack/core": "0.9.0",
-    "@objectstack/types": "0.9.0",
-    "@objectstack/spec": "0.9.0"
+    "@objectstack/core": "0.9.2",
+    "@objectstack/spec": "0.9.2",
+    "@objectstack/types": "0.9.2"
   },
   "devDependencies": {
     "typescript": "^5.0.0"

package/src/index.ts

@@ -9,6 +9,7 @@ export { AppPlugin } from './app-plugin.js';
 export { HttpServer } from './http-server.js';
 export { RestServer } from './rest-server.js';
 export { RouteManager, RouteGroupBuilder } from './route-manager.js';
+export type { RouteEntry } from './route-manager.js';
 export { MiddlewareManager } from './middleware.js';
 
 // Export Types