diff --git a/packages/plugins/driver-memory/README.md b/packages/plugins/driver-memory/README.md new file mode 100644 index 000000000..8802d69d9 --- /dev/null +++ b/packages/plugins/driver-memory/README.md @@ -0,0 +1,227 @@ +# @objectstack/driver-memory + +In-Memory Driver for ObjectStack. A reference implementation of the DriverInterface that stores data in memory using JavaScript arrays. + +## Plugin Capabilities + +This driver implements the ObjectStack plugin capability protocol: +- **Type**: `driver` +- **Protocol**: `com.objectstack.protocol.storage.v1` (partial conformance) +- **Provides**: `DriverInterface` for data storage operations +- **Features**: + - ✅ Basic CRUD operations + - ✅ Pagination (limit/offset) + - ❌ Advanced query filters + - ❌ Aggregations + - ❌ Sorting + - ❌ Transactions + - ❌ Joins + +See [objectstack.config.ts](./objectstack.config.ts) for the complete capability manifest. + +## Features + +- 🚀 **Zero Dependencies**: Pure JavaScript implementation +- 🧪 **Perfect for Testing**: Volatile storage ideal for unit tests +- 📝 **TypeScript First**: Fully typed with TypeScript +- 🔍 **Reference Implementation**: Clean example of DriverInterface +- ⚡ **Fast**: In-memory operations are lightning fast + +## Installation + +```bash +pnpm add @objectstack/driver-memory +``` + +## Usage + +### With ObjectStack Runtime + +```typescript +import { InMemoryDriver } from '@objectstack/driver-memory'; +import { DriverPlugin } from '@objectstack/runtime'; +import { ObjectKernel } from '@objectstack/runtime'; + +const kernel = new ObjectKernel(); + +// Create and register the driver +const memoryDriver = new InMemoryDriver(); +kernel.use(new DriverPlugin(memoryDriver, 'memory')); + +await kernel.bootstrap(); +``` + +### Standalone Usage + +```typescript +import { InMemoryDriver } from '@objectstack/driver-memory'; + +const driver = new InMemoryDriver({ + seedData: true // Pre-populate with example data +}); + +// Initialize +await driver.connect(); + +// Create a record +const user = await driver.create('user', { + name: 'John Doe', + email: 'john@example.com' +}); + +// Find records +const users = await driver.find('user', { + limit: 10, + offset: 0 +}); + +// Get by ID +const foundUser = await driver.findOne('user', user.id); + +// Update +await driver.update('user', user.id, { + name: 'Jane Doe' +}); + +// Delete +await driver.delete('user', user.id); + +// Count +const count = await driver.count('user'); + +// Cleanup +await driver.disconnect(); +``` + +## API Reference + +### InMemoryDriver + +The main driver class that implements `DriverInterface`. + +#### Constructor Options + +```typescript +interface DriverOptions { + /** + * Pre-populate the database with example data on startup + * @default false + */ + seedData?: boolean; + + /** + * Logger instance + */ + logger?: Logger; +} +``` + +#### Methods + +- `connect()` - Initialize the driver (no-op for in-memory) +- `disconnect()` - Cleanup resources (clears all data) +- `create(object, data)` - Create a new record +- `find(object, query?)` - Query records with optional pagination +- `findOne(object, id)` - Get a single record by ID +- `update(object, id, data)` - Update a record +- `delete(object, id)` - Delete a record +- `count(object, query?)` - Count total records +- `getSchema(object)` - Get object schema definition +- `query(query)` - Execute a raw query (limited support) + +#### Capabilities + +The driver declares its capabilities via the `supports` property: + +```typescript +{ + transactions: false, + queryFilters: false, + queryAggregations: false, + querySorting: false, + queryPagination: true, // ✅ Supported via limit/offset + queryWindowFunctions: false, + querySubqueries: false, + joins: false, + fullTextSearch: false, + vectorSearch: false, + geoSpatial: false +} +``` + +## Data Storage + +The in-memory driver stores data in a simple Map structure: + +```typescript +private tables: Map>> = new Map(); +``` + +**Important**: All data is lost when the process exits or `disconnect()` is called. This driver is **not suitable for production use**. + +## Use Cases + +✅ **Good for:** +- Unit testing +- Integration testing +- Development/prototyping +- CI/CD pipelines +- Examples and tutorials +- Learning ObjectStack + +❌ **Not suitable for:** +- Production environments +- Data persistence requirements +- Large datasets (memory constraints) +- Multi-process scenarios +- Concurrent write operations + +## Testing Example + +```typescript +import { describe, it, expect, beforeEach, afterEach } from 'vitest'; +import { InMemoryDriver } from '@objectstack/driver-memory'; + +describe('User CRUD', () => { + let driver: InMemoryDriver; + + beforeEach(async () => { + driver = new InMemoryDriver(); + await driver.connect(); + }); + + afterEach(async () => { + await driver.disconnect(); + }); + + it('should create and retrieve a user', async () => { + const user = await driver.create('user', { + name: 'Test User', + email: 'test@example.com' + }); + + expect(user.id).toBeDefined(); + + const found = await driver.findOne('user', user.id); + expect(found.name).toBe('Test User'); + }); +}); +``` + +## Relationship to Other Drivers + +This driver serves as a reference implementation. For production use, consider: + +- **@objectstack/driver-postgres** - PostgreSQL driver with full SQL capabilities +- **@objectstack/driver-mongodb** - MongoDB driver for document storage +- **@objectstack/driver-redis** - Redis driver for caching and key-value storage + +## License + +Apache-2.0 + +## Related Packages + +- [@objectstack/runtime](../../runtime) - ObjectStack Runtime +- [@objectstack/spec](../../spec) - ObjectStack Specifications +- [@objectstack/core](../../core) - Core Interfaces and Types diff --git a/packages/plugins/driver-memory/objectstack.config.ts b/packages/plugins/driver-memory/objectstack.config.ts index 4d11f97dc..29eca9d2c 100644 --- a/packages/plugins/driver-memory/objectstack.config.ts +++ b/packages/plugins/driver-memory/objectstack.config.ts @@ -1,11 +1,17 @@ import { ObjectStackManifest } from '@objectstack/spec/system'; +/** + * In-Memory Driver Plugin Manifest + * + * Reference implementation of a storage driver that stores data in memory. + * Demonstrates the driver protocol implementation pattern. + */ const MemoryDriverPlugin: ObjectStackManifest = { id: 'com.objectstack.driver.memory', name: 'In-Memory Driver', version: '1.0.0', type: 'driver', - description: 'A reference specificiation implementation of the DriverInterface using in-memory arrays.', + description: 'A reference specification implementation of the DriverInterface using in-memory arrays. Suitable for testing and development.', configuration: { title: 'Memory Driver Settings', @@ -18,9 +24,234 @@ const MemoryDriverPlugin: ObjectStackManifest = { } }, + // Plugin Capability Declaration + capabilities: { + // Protocols This Driver Implements + implements: [ + { + protocol: { + id: 'com.objectstack.protocol.storage.v1', + label: 'Storage Protocol v1', + version: { major: 1, minor: 0, patch: 0 }, + description: 'Standard data storage and retrieval operations', + }, + conformance: 'partial', + implementedFeatures: [ + 'basic_crud', + 'pagination', + ], + features: [ + { + name: 'basic_crud', + enabled: true, + description: 'Create, read, update, delete operations', + }, + { + name: 'pagination', + enabled: true, + description: 'Basic pagination via limit/offset', + }, + { + name: 'query_filters', + enabled: false, + description: 'Advanced query filtering', + }, + { + name: 'aggregations', + enabled: false, + description: 'Count, sum, avg operations', + }, + { + name: 'sorting', + enabled: false, + description: 'Result set sorting', + }, + { + name: 'transactions', + enabled: false, + description: 'ACID transaction support', + }, + { + name: 'joins', + enabled: false, + description: 'Cross-object joins', + }, + ], + certified: false, + }, + ], + + // Interfaces This Driver Provides + provides: [ + { + id: 'com.objectstack.driver.memory.interface.driver', + name: 'DriverInterface', + description: 'Standard ObjectStack driver interface for data operations', + version: { major: 1, minor: 0, patch: 0 }, + stability: 'stable', + methods: [ + { + name: 'connect', + description: 'Initialize driver connection', + parameters: [], + returnType: 'Promise', + async: true, + }, + { + name: 'disconnect', + description: 'Close driver connection', + parameters: [], + returnType: 'Promise', + async: true, + }, + { + name: 'create', + description: 'Create a new record', + parameters: [ + { + name: 'object', + type: 'string', + required: true, + description: 'Object name', + }, + { + name: 'data', + type: 'Record', + required: true, + description: 'Record data', + }, + ], + returnType: 'Promise', + async: true, + }, + { + name: 'find', + description: 'Query records', + parameters: [ + { + name: 'object', + type: 'string', + required: true, + description: 'Object name', + }, + { + name: 'query', + type: 'QueryInput', + required: false, + description: 'Query parameters', + }, + ], + returnType: 'Promise', + async: true, + }, + { + name: 'findOne', + description: 'Find a single record by ID', + parameters: [ + { + name: 'object', + type: 'string', + required: true, + description: 'Object name', + }, + { + name: 'id', + type: 'string', + required: true, + description: 'Record ID', + }, + ], + returnType: 'Promise', + async: true, + }, + { + name: 'update', + description: 'Update a record', + parameters: [ + { + name: 'object', + type: 'string', + required: true, + description: 'Object name', + }, + { + name: 'id', + type: 'string', + required: true, + description: 'Record ID', + }, + { + name: 'data', + type: 'Record', + required: true, + description: 'Updated record data', + }, + ], + returnType: 'Promise', + async: true, + }, + { + name: 'delete', + description: 'Delete a record', + parameters: [ + { + name: 'object', + type: 'string', + required: true, + description: 'Object name', + }, + { + name: 'id', + type: 'string', + required: true, + description: 'Record ID', + }, + ], + returnType: 'Promise', + async: true, + }, + { + name: 'count', + description: 'Count records', + parameters: [ + { + name: 'object', + type: 'string', + required: true, + description: 'Object name', + }, + { + name: 'query', + type: 'QueryInput', + required: false, + description: 'Query parameters', + }, + ], + returnType: 'Promise', + async: true, + }, + ], + }, + ], + + // No external plugin dependencies (this is a core driver) + requires: [], + + // No extension points defined + extensionPoints: [], + + // No extensions contributed + extensions: [], + }, + contributes: { - // If there was a 'drivers' definition here, we would use it. - // For now, we register via code (src/index.ts) + drivers: [ + { + id: 'memory', + label: 'In-Memory Storage', + description: 'Stores data in memory (volatile, for testing/development)', + }, + ], } }; diff --git a/packages/plugins/plugin-hono-server/README.md b/packages/plugins/plugin-hono-server/README.md new file mode 100644 index 000000000..e5d60f56b --- /dev/null +++ b/packages/plugins/plugin-hono-server/README.md @@ -0,0 +1,324 @@ +# @objectstack/plugin-hono-server + +HTTP Server Adapter for ObjectStack Runtime using the [Hono](https://hono.dev/) framework. This plugin provides a production-ready REST API gateway for ObjectStack applications. + +## Plugin Capabilities + +This plugin implements the ObjectStack plugin capability protocol: +- **Type**: `adapter` +- **Protocol**: `com.objectstack.protocol.http.v1` (full conformance) +- **Protocol**: `com.objectstack.protocol.api.rest.v1` (full conformance) +- **Provides**: `IHttpServer` interface for HTTP server operations +- **Requires**: `com.objectstack.engine.objectql` (optional) for protocol implementation +- **Extension Points**: + - `middleware` - Register custom HTTP middleware + - `route` - Register custom API routes + +See [objectstack.config.ts](./objectstack.config.ts) for the complete capability manifest. + +## Features + +- 🚀 **High Performance**: Built on Hono, one of the fastest web frameworks +- 🌐 **Universal**: Works in Node.js, Deno, Bun, and edge runtimes +- 🔒 **Type Safe**: Fully typed with TypeScript +- 📡 **REST API**: Complete ObjectStack Runtime Protocol implementation +- 🎯 **Auto-Discovery**: Automatic endpoint registration +- 🔌 **Extensible**: Easy to add custom routes and middleware + +## Installation + +```bash +pnpm add @objectstack/plugin-hono-server hono @hono/node-server +``` + +## Usage + +### Basic Setup + +```typescript +import { HonoServerPlugin } from '@objectstack/plugin-hono-server'; +import { ObjectKernel } from '@objectstack/runtime'; + +const kernel = new ObjectKernel(); + +// Register the server plugin +kernel.use(new HonoServerPlugin({ + port: 3000, + staticRoot: './public' // Optional: serve static files +})); + +await kernel.bootstrap(); + +// Server starts automatically when kernel is ready +// API available at: http://localhost:3000/api/v1 +``` + +### With Custom Port + +```typescript +const plugin = new HonoServerPlugin({ + port: process.env.PORT || 8080 +}); + +kernel.use(plugin); +``` + +### Configuration Options + +```typescript +interface HonoPluginOptions { + /** + * HTTP server port + * @default 3000 + */ + port?: number; + + /** + * Path to static files directory (optional) + */ + staticRoot?: string; +} +``` + +## API Endpoints + +The plugin automatically exposes the following ObjectStack REST API endpoints: + +### Discovery + +```http +GET /api/v1 +``` + +Returns API discovery information including available endpoints and versions. + +### Metadata Protocol + +```http +GET /api/v1/meta +GET /api/v1/meta/:type +GET /api/v1/meta/:type/:name +``` + +Retrieve metadata about objects, views, and other system definitions. + +### Data Protocol (CRUD Operations) + +```http +GET /api/v1/data/:object # Find records +GET /api/v1/data/:object/:id # Get record by ID +POST /api/v1/data/:object # Create record +PATCH /api/v1/data/:object/:id # Update record +DELETE /api/v1/data/:object/:id # Delete record +``` + +Example requests: + +```bash +# Get all users +curl http://localhost:3000/api/v1/data/user + +# Get user by ID +curl http://localhost:3000/api/v1/data/user/123 + +# Create a user +curl -X POST http://localhost:3000/api/v1/data/user \ + -H "Content-Type: application/json" \ + -d '{"name":"John Doe","email":"john@example.com"}' + +# Update a user +curl -X PATCH http://localhost:3000/api/v1/data/user/123 \ + -H "Content-Type: application/json" \ + -d '{"name":"Jane Doe"}' + +# Delete a user +curl -X DELETE http://localhost:3000/api/v1/data/user/123 +``` + +### UI Protocol + +```http +GET /api/v1/ui/view/:object?type=list|form +``` + +Retrieve UI view configurations for objects. + +## Advanced Usage + +### Accessing the HTTP Server Instance + +The server instance is registered as a service and can be accessed by other plugins: + +```typescript +export class MyPlugin implements Plugin { + name = 'my-custom-plugin'; + + async start(ctx: PluginContext) { + const httpServer = ctx.getService('http-server'); + + // Add custom routes + httpServer.get('/api/custom', (req, res) => { + res.json({ message: 'Custom endpoint' }); + }); + } +} +``` + +### Extending with Middleware + +The plugin provides extension points for adding custom middleware: + +```typescript +// In another plugin's manifest +capabilities: { + extensions: [ + { + targetPluginId: 'com.objectstack.server.hono', + extensionPointId: 'com.objectstack.server.hono.extension.middleware', + implementation: './middleware/auth.ts', + priority: 10 + } + ] +} +``` + +### Custom Route Registration + +```typescript +// In another plugin's manifest +capabilities: { + extensions: [ + { + targetPluginId: 'com.objectstack.server.hono', + extensionPointId: 'com.objectstack.server.hono.extension.route', + implementation: './routes/webhooks.ts', + priority: 50 + } + ] +} +``` + +## Architecture + +The Hono Server Plugin follows a clean architecture: + +``` +┌─────────────────────────────────┐ +│ HonoServerPlugin │ +│ (Plugin Lifecycle) │ +└────────────┬────────────────────┘ + │ + ├─ init() → Register HTTP server service + ├─ start() → Bind routes, start server + └─ destroy() → Stop server + │ + ▼ + ┌─────────────────────┐ + │ HonoHttpServer │ + │ (Adapter) │ + └──────┬──────────────┘ + │ + ▼ + ┌─────────────────────┐ + │ Hono Framework │ + │ (Core Library) │ + └─────────────────────┘ +``` + +## Plugin Lifecycle + +1. **Init Phase**: + - Creates HonoHttpServer instance + - Registers as `http-server` service + +2. **Start Phase**: + - Retrieves protocol implementation service + - Registers all ObjectStack API routes + - Sets up lifecycle hooks + +3. **Ready Hook** (`kernel:ready`): + - Starts HTTP server on configured port + - Logs server URL + +4. **Destroy Phase**: + - Gracefully closes server + - Cleans up resources + +## Error Handling + +The plugin includes comprehensive error handling: + +```typescript +// 404 Not Found +GET /api/v1/data/user/999 +→ { "error": "Record not found" } + +// 400 Bad Request +POST /api/v1/data/user (invalid data) +→ { "error": "Validation failed: email is required" } +``` + +## Production Deployment + +### Environment Variables + +```bash +PORT=8080 +NODE_ENV=production +``` + +### Docker Example + +```dockerfile +FROM node:20-alpine +WORKDIR /app +COPY package.json pnpm-lock.yaml ./ +RUN npm install -g pnpm && pnpm install --frozen-lockfile +COPY . . +RUN pnpm build +EXPOSE 8080 +CMD ["node", "dist/index.js"] +``` + +### Serverless Deployment + +Hono works seamlessly with serverless platforms: + +```typescript +// Cloudflare Workers, Vercel Edge, etc. +export default { + async fetch(request: Request) { + const app = createHonoApp(); + return app.fetch(request); + } +} +``` + +## Performance + +Hono is designed for performance: +- ⚡ One of the fastest web frameworks for Node.js +- 🪶 Minimal overhead and memory footprint +- 🚀 Optimized routing with RegExpRouter +- 📦 Small bundle size (~12KB) + +## Comparison with Other Adapters + +| Feature | Hono | Express | Fastify | +|---------|------|---------|---------| +| Universal Runtime | ✅ | ❌ | ❌ | +| Edge Support | ✅ | ❌ | ❌ | +| TypeScript | ✅ | Partial | ✅ | +| Performance | Excellent | Good | Excellent | +| Bundle Size | 12KB | 208KB | 28KB | + +## License + +Apache-2.0 + +## Related Packages + +- [@objectstack/runtime](../../runtime) - ObjectStack Runtime +- [@objectstack/spec](../../spec) - ObjectStack Specifications +- [hono](https://hono.dev/) - Hono Web Framework +- [@hono/node-server](https://github.com/honojs/node-server) - Node.js adapter for Hono diff --git a/packages/plugins/plugin-hono-server/objectstack.config.ts b/packages/plugins/plugin-hono-server/objectstack.config.ts new file mode 100644 index 000000000..54ebd9aeb --- /dev/null +++ b/packages/plugins/plugin-hono-server/objectstack.config.ts @@ -0,0 +1,238 @@ +import { ObjectStackManifest } from '@objectstack/spec/system'; + +/** + * Hono Server Plugin Manifest + * + * HTTP server adapter plugin using the Hono framework. + * Provides northbound HTTP/REST API gateway capabilities. + */ +const HonoServerPlugin: ObjectStackManifest = { + id: 'com.objectstack.server.hono', + name: 'Hono Server Adapter', + version: '1.0.0', + type: 'adapter', + description: 'HTTP server adapter using Hono framework. Exposes ObjectStack Runtime Protocol via REST API endpoints.', + + configuration: { + title: 'Hono Server Configuration', + properties: { + port: { + type: 'number', + default: 3000, + description: 'HTTP server port', + }, + staticRoot: { + type: 'string', + description: 'Path to static files directory (optional)', + }, + }, + }, + + // Plugin Capability Declaration + capabilities: { + // Protocols This Plugin Implements + implements: [ + { + protocol: { + id: 'com.objectstack.protocol.http.v1', + label: 'HTTP Server Protocol v1', + version: { major: 1, minor: 0, patch: 0 }, + description: 'Standard HTTP server capabilities', + }, + conformance: 'full', + certified: false, + }, + { + protocol: { + id: 'com.objectstack.protocol.api.rest.v1', + label: 'REST API Protocol v1', + version: { major: 1, minor: 0, patch: 0 }, + description: 'RESTful API endpoint implementation', + }, + conformance: 'full', + features: [ + { + name: 'meta_protocol', + enabled: true, + description: 'Metadata discovery endpoints', + }, + { + name: 'data_protocol', + enabled: true, + description: 'CRUD data operations', + }, + { + name: 'ui_protocol', + enabled: true, + description: 'UI view metadata endpoints', + }, + ], + certified: false, + }, + ], + + // Interfaces This Plugin Provides + provides: [ + { + id: 'com.objectstack.server.hono.interface.http_server', + name: 'IHttpServer', + description: 'HTTP server service interface', + version: { major: 1, minor: 0, patch: 0 }, + stability: 'stable', + methods: [ + { + name: 'get', + description: 'Register GET route handler', + parameters: [ + { + name: 'path', + type: 'string', + required: true, + description: 'Route path pattern', + }, + { + name: 'handler', + type: 'Function', + required: true, + description: 'Route handler function', + }, + ], + returnType: 'void', + async: false, + }, + { + name: 'post', + description: 'Register POST route handler', + parameters: [ + { + name: 'path', + type: 'string', + required: true, + description: 'Route path pattern', + }, + { + name: 'handler', + type: 'Function', + required: true, + description: 'Route handler function', + }, + ], + returnType: 'void', + async: false, + }, + { + name: 'patch', + description: 'Register PATCH route handler', + parameters: [ + { + name: 'path', + type: 'string', + required: true, + description: 'Route path pattern', + }, + { + name: 'handler', + type: 'Function', + required: true, + description: 'Route handler function', + }, + ], + returnType: 'void', + async: false, + }, + { + name: 'delete', + description: 'Register DELETE route handler', + parameters: [ + { + name: 'path', + type: 'string', + required: true, + description: 'Route path pattern', + }, + { + name: 'handler', + type: 'Function', + required: true, + description: 'Route handler function', + }, + ], + returnType: 'void', + async: false, + }, + { + name: 'listen', + description: 'Start the HTTP server', + parameters: [ + { + name: 'port', + type: 'number', + required: true, + description: 'Port number', + }, + ], + returnType: 'Promise', + async: true, + }, + { + name: 'close', + description: 'Stop the HTTP server', + parameters: [], + returnType: 'void', + async: false, + }, + ], + }, + ], + + // Dependencies on Other Plugins/Services + requires: [ + { + pluginId: 'com.objectstack.engine.objectql', + version: '^0.6.0', + optional: true, + reason: 'ObjectStack Runtime Protocol implementation service', + requiredCapabilities: [ + 'com.objectstack.protocol.runtime.v1', + ], + }, + ], + + // Extension Points This Plugin Defines + extensionPoints: [ + { + id: 'com.objectstack.server.hono.extension.middleware', + name: 'HTTP Middleware', + description: 'Register custom HTTP middleware', + type: 'hook', + cardinality: 'multiple', + contract: { + signature: '(req: Request, res: Response, next: Function) => void | Promise', + }, + }, + { + id: 'com.objectstack.server.hono.extension.route', + name: 'Custom Routes', + description: 'Register custom API routes', + type: 'action', + cardinality: 'multiple', + contract: { + input: 'RouteDefinition', + signature: '(app: HonoApp) => void', + }, + }, + ], + + // No extensions contributed to other plugins + extensions: [], + }, + + contributes: { + // System Events + events: [ + 'kernel:ready', + ], + }, +}; + +export default HonoServerPlugin; diff --git a/packages/plugins/plugin-msw/README.md b/packages/plugins/plugin-msw/README.md index e0393edff..aa543160d 100644 --- a/packages/plugins/plugin-msw/README.md +++ b/packages/plugins/plugin-msw/README.md @@ -2,6 +2,16 @@ MSW (Mock Service Worker) Plugin for ObjectStack Runtime. This plugin enables seamless integration with [Mock Service Worker](https://mswjs.io/) for testing and development environments. +## Plugin Capabilities + +This plugin implements the ObjectStack plugin capability protocol: +- **Protocol**: `com.objectstack.protocol.testing.mock.v1` (full conformance) +- **Protocol**: `com.objectstack.protocol.api.rest.v1` (full conformance) +- **Provides**: `ObjectStackServer` interface for mock API operations +- **Requires**: `com.objectstack.engine.objectql` for data operations + +See [objectstack.config.ts](./objectstack.config.ts) for the complete capability manifest. + ## Features - 🎯 **Automatic API Mocking**: Automatically generates MSW handlers for all ObjectStack API endpoints diff --git a/packages/plugins/plugin-msw/objectstack.config.ts b/packages/plugins/plugin-msw/objectstack.config.ts new file mode 100644 index 000000000..2dab37859 --- /dev/null +++ b/packages/plugins/plugin-msw/objectstack.config.ts @@ -0,0 +1,273 @@ +import { ObjectStackManifest } from '@objectstack/spec/system'; + +/** + * MSW (Mock Service Worker) Plugin Manifest + * + * Browser-based mock server for testing and development. + * Intercepts HTTP requests and provides mock responses using ObjectStack runtime. + */ +const MSWPlugin: ObjectStackManifest = { + id: 'com.objectstack.plugin.msw', + name: 'Mock Service Worker Plugin', + version: '1.0.0', + type: 'plugin', + description: 'MSW (Mock Service Worker) integration for testing and development. Provides browser-based API mocking using ObjectStack runtime protocol.', + + configuration: { + title: 'MSW Plugin Configuration', + properties: { + enableBrowser: { + type: 'boolean', + default: true, + description: 'Enable MSW in browser environment', + }, + baseUrl: { + type: 'string', + default: '/api/v1', + description: 'Base URL for API endpoints', + }, + logRequests: { + type: 'boolean', + default: true, + description: 'Log all intercepted requests', + }, + }, + }, + + // Plugin Capability Declaration + capabilities: { + // Protocols This Plugin Implements + implements: [ + { + protocol: { + id: 'com.objectstack.protocol.testing.mock.v1', + label: 'Mock Service Protocol v1', + version: { major: 1, minor: 0, patch: 0 }, + description: 'HTTP request mocking for testing', + }, + conformance: 'full', + features: [ + { + name: 'browser_mocking', + enabled: true, + description: 'Browser-based request interception', + }, + { + name: 'api_simulation', + enabled: true, + description: 'Full ObjectStack API simulation', + }, + { + name: 'custom_handlers', + enabled: true, + description: 'Custom request handler registration', + }, + ], + certified: false, + }, + { + protocol: { + id: 'com.objectstack.protocol.api.rest.v1', + label: 'REST API Protocol v1', + version: { major: 1, minor: 0, patch: 0 }, + description: 'RESTful API endpoint mocking', + }, + conformance: 'full', + features: [ + { + name: 'meta_endpoints', + enabled: true, + description: 'Metadata discovery endpoints', + }, + { + name: 'data_endpoints', + enabled: true, + description: 'CRUD data operation endpoints', + }, + { + name: 'ui_endpoints', + enabled: true, + description: 'UI view metadata endpoints', + }, + ], + certified: false, + }, + ], + + // Interfaces This Plugin Provides + provides: [ + { + id: 'com.objectstack.plugin.msw.interface.mock_server', + name: 'ObjectStackServer', + description: 'Mock server interface for testing', + version: { major: 1, minor: 0, patch: 0 }, + stability: 'stable', + methods: [ + { + name: 'init', + description: 'Initialize mock server with protocol implementation', + parameters: [ + { + name: 'protocol', + type: 'IObjectStackProtocol', + required: true, + description: 'ObjectStack protocol implementation instance', + }, + { + name: 'logger', + type: 'Logger', + required: false, + description: 'Optional logger instance', + }, + ], + returnType: 'void', + async: false, + }, + { + name: 'findData', + description: 'Mock data find operation', + parameters: [ + { + name: 'object', + type: 'string', + required: true, + description: 'Object name', + }, + { + name: 'params', + type: 'any', + required: false, + description: 'Query parameters', + }, + ], + returnType: 'Promise<{ status: number; data: any }>', + async: true, + }, + { + name: 'getData', + description: 'Mock data get operation', + parameters: [ + { + name: 'object', + type: 'string', + required: true, + description: 'Object name', + }, + { + name: 'id', + type: 'string', + required: true, + description: 'Record ID', + }, + ], + returnType: 'Promise<{ status: number; data: any }>', + async: true, + }, + { + name: 'createData', + description: 'Mock data create operation', + parameters: [ + { + name: 'object', + type: 'string', + required: true, + description: 'Object name', + }, + { + name: 'data', + type: 'any', + required: true, + description: 'Record data', + }, + ], + returnType: 'Promise<{ status: number; data: any }>', + async: true, + }, + { + name: 'updateData', + description: 'Mock data update operation', + parameters: [ + { + name: 'object', + type: 'string', + required: true, + description: 'Object name', + }, + { + name: 'id', + type: 'string', + required: true, + description: 'Record ID', + }, + { + name: 'data', + type: 'any', + required: true, + description: 'Updated record data', + }, + ], + returnType: 'Promise<{ status: number; data: any }>', + async: true, + }, + { + name: 'deleteData', + description: 'Mock data delete operation', + parameters: [ + { + name: 'object', + type: 'string', + required: true, + description: 'Object name', + }, + { + name: 'id', + type: 'string', + required: true, + description: 'Record ID', + }, + ], + returnType: 'Promise<{ status: number; data: any }>', + async: true, + }, + ], + }, + ], + + // Dependencies on Other Plugins/Services + requires: [ + { + pluginId: 'com.objectstack.engine.objectql', + version: '^0.6.0', + optional: false, + reason: 'ObjectQL data engine for mock responses', + requiredCapabilities: [ + 'com.objectstack.protocol.storage.v1', + ], + }, + ], + + // Extension Points This Plugin Defines + extensionPoints: [ + { + id: 'com.objectstack.plugin.msw.extension.custom_handler', + name: 'Custom Request Handlers', + description: 'Register custom MSW request handlers', + type: 'action', + cardinality: 'multiple', + contract: { + input: 'MSWHandler', + description: 'MSW HTTP handler definition', + }, + }, + ], + + // No extensions contributed to other plugins + extensions: [], + }, + + contributes: { + // No specific contributions (runtime plugin) + }, +}; + +export default MSWPlugin;