Add @objectql/server package with Node adapter

Introduces the @objectql/server package, including a generic HTTP server adapter for ObjectQL, Node.js handler, types, tests, and configuration files. Also updates pnpm-lock.yaml to register new dependencies and linkages for the server and example projects.

Author: hotlong

examples/express-server/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "esModuleInterop": true
+  },
+  "include": ["src/**/*"]
+}

packages/server/README.md

@@ -0,0 +1,58 @@
+# @objectql/server
+
+Generic HTTP Server Adapter for ObjectQL.
+Allows running ObjectQL on Node.js, Express, Next.js, etc.
+
+## Installation
+
+```bash
+pnpm add @objectql/server
+```
+
+## Usage
+
+### Node.js (Raw HTTP)
+
+```typescript
+import { createNodeHandler } from '@objectql/server';
+import { app } from './objectql'; // Your initialized ObjectQL instance
+import { createServer } from 'http';
+
+const handler = createNodeHandler(app);
+const server = createServer(handler);
+server.listen(3000);
+```
+
+### Express
+
+```typescript
+import express from 'express';
+import { createNodeHandler } from '@objectql/server';
+import { app } from './objectql';
+
+const server = express();
+
+// Optional: Mount express.json() if you want, but ObjectQL handles parsing too.
+// server.use(express.json());
+
+// Mount the handler
+server.all('/api/objectql', createNodeHandler(app));
+
+server.listen(3000);
+```
+
+### Next.js (API Routes)
+
+```typescript
+// pages/api/objectql.ts
+import { createNodeHandler } from '@objectql/server';
+import { app } from '../../lib/objectql';
+
+export const config = {
+  api: {
+    bodyParser: false, // ObjectQL handles body parsing
+  },
+};
+
+export default createNodeHandler(app);
+```

packages/server/jest.config.js

@@ -0,0 +1,8 @@
+module.exports = {
+    preset: 'ts-jest',
+    testEnvironment: 'node',
+    testMatch: ['**/*.test.ts'],
+    moduleNameMapper: {
+        '^@objectql/(.*)$': '<rootDir>/../$1/src'
+    }
+};

packages/server/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@objectql/server",
+  "version": "0.1.0",
+  "description": "HTTP Server Adapter for ObjectQL",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest"
+  },
+  "dependencies": {
+    "@objectql/core": "workspace:*",
+    "@objectql/types": "workspace:*"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "@types/node": "^20.10.0"
+  }
+}

packages/server/src/adapters/node.ts

@@ -0,0 +1,60 @@
+import { IObjectQL } from '@objectql/types';
+import { ObjectQLServer } from '../server';
+import { ObjectQLRequest } from '../types';
+import { IncomingMessage, ServerResponse } from 'http';
+
+/**
+ * Creates a standard Node.js HTTP request handler.
+ */
+export function createNodeHandler(app: IObjectQL) {
+    const server = new ObjectQLServer(app);
+
+
+    return async (req: IncomingMessage & { body?: any }, res: ServerResponse) => {
+        if (req.method !== 'POST') {
+            res.statusCode = 405;
+            res.end('Method Not Allowed');
+            return;
+        }
+
+        const handleRequest = async (json: any) => {
+             try {
+                // TODO: Parse user from header or request override
+                const qlReq: ObjectQLRequest = {
+                    op: json.op,
+                    object: json.object,
+                    args: json.args,
+                    user: json.user // For dev/testing, allowing user injection
+                };
+
+                const result = await server.handle(qlReq);
+                
+                res.setHeader('Content-Type', 'application/json');
+                res.statusCode = result.error ? 500 : 200;
+                res.end(JSON.stringify(result));
+            } catch (e) {
+                res.statusCode = 500;
+                res.end(JSON.stringify({ error: { code: 'INTERNAL_ERROR', message: 'Internal Server Error' }}));
+            }
+        };
+
+        // 1. Check if body is already parsed (e.g. by express.json())
+        if (req.body && typeof req.body === 'object') {
+            await handleRequest(req.body);
+            return;
+        }
+
+        // 2. Parse Body from stream
+        let body = '';
+        req.on('data', chunk => body += chunk);
+        req.on('end', async () => {
+            try {
+                const json = JSON.parse(body);
+                await handleRequest(json);
+            } catch (e) {
+                res.statusCode = 400;
+                res.end('Invalid JSON');
+            }
+        });
+    };
+}

packages/server/src/index.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './server';
+// We export createNodeHandler from root for convenience, 
+// but in the future we might encourage 'import ... from @objectql/server/node'
+export * from './adapters/node';

packages/server/src/server.ts

@@ -0,0 +1,78 @@
+import { IObjectQL, ObjectQLContext } from '@objectql/types';
+import { ObjectQLRequest, ObjectQLResponse } from './types';
+
+export class ObjectQLServer {
+    constructor(private app: IObjectQL) {}
+
+    /**
+     * The core handler that processes a JSON request object and returns a result.
+     * This is framework-agnostic.
+     */
+    async handle(req: ObjectQLRequest): Promise<ObjectQLResponse> {
+        try {
+            // 1. Build Context
+            // TODO: integrate with real session/auth
+            const contextOptions = {
+                userId: req.user?.id,
+                roles: req.user?.roles || [],
+                // TODO: spaceId
+            };
+            
+            // Note: Currently IObjectQL.createContext implies we have access to it.
+            // But IObjectQL interface in @objectql/types usually doesn't expose createContext (it's on the class).
+            // We need to cast or fix the interface. Assuming 'app' behaves like ObjectQL class.
+            const app = this.app as any; 
+            if (typeof app.createContext !== 'function') {
+                throw new Error("The provided ObjectQL instance does not support createContext.");
+            }
+            
+            const ctx: ObjectQLContext = app.createContext(contextOptions);
+            const repo = ctx.object(req.object);
+
+            let result: any;
+            
+            switch (req.op) {
+                case 'find':
+                    result = await repo.find(req.args);
+                    break;
+                case 'findOne':
+                    result = await repo.findOne(req.args);
+                    break;
+                case 'create':
+                    result = await repo.create(req.args);
+                    break;
+                case 'update':
+                    result = await repo.update(req.args.id, req.args.data);
+                    break;
+                case 'delete':
+                    result = await repo.delete(req.args.id);
+                    break;
+                case 'count':
+                    result = await repo.count(req.args);
+                    break;
+                case 'action':
+                    // TODO: The repo interface might not expose 'executeAction' directly yet,
+                    // usually it's on the app level or via special method.
+                    // For now, let's assume app.executeAction
+                    result = await app.executeAction(req.object, req.args.action, {
+                         ...ctx, // Pass context with user info
+                         params: req.args.params
+                    });
+                    break;
+                default:
+                    throw new Error(`Unknown operation: ${req.op}`);
+            }
+
+            return { data: result };
+
+        } catch (e: any) {
+            console.error('[ObjectQL Server] Error:', e);
+            return {
+                error: {
+                    code: 'INTERNAL_ERROR',
+                    message: e.message || 'An error occurred'
+                }
+            };
+        }
+    }
+}

packages/server/src/types.ts

@@ -0,0 +1,24 @@
+// src/types.ts
+export interface ObjectQLRequest {
+    // Identity provided by the framework adapter (e.g. from session)
+    user?: {
+        id: string;
+        roles: string[];
+        [key: string]: any;
+    };
+    
+    // The actual operation
+    op: 'find' | 'findOne' | 'create' | 'update' | 'delete' | 'count' | 'action';
+    object: string;
+    
+    // Arguments
+    args: any;
+}
+
+export interface ObjectQLResponse {
+    data?: any;
+    error?: {
+        code: string;
+        message: string;
+    }
+}

packages/server/test/node.test.ts

@@ -0,0 +1,92 @@
+import request from 'supertest';
+import { createServer } from 'http';
+import { ObjectQL } from '@objectql/core';
+import { createNodeHandler } from '../src/adapters/node';
+import { IObjectQL, Driver } from '@objectql/types';
+
+// Simple Mock Driver
+class MockDriver implements Driver {
+    async init() {}
+    async find(objectName: string) {
+        if (objectName === 'user') {
+            return [{ id: 1, name: 'Alice' }];
+        }
+        return [];
+    }
+    async findOne() { return null; }
+    async create() { return { id: 2, name: 'Bob' }; }
+    async update() { return 1; }
+    async delete() { return 1; }
+    async count() { return 0; }
+    async execute() {}
+}
+
+describe('Node Adapter', () => {
+    let app: ObjectQL;
+    let server: any;
+
+    beforeAll(async () => {
+        app = new ObjectQL({
+            datasources: {
+                default: new MockDriver()
+            }
+        });
+        
+        // Manual schema registration
+        app.metadata.register('object', {
+            type: 'object',
+            id: 'user',
+            content: {
+                name: 'user',
+                fields: {
+                    name: { type: 'string' }
+                }
+            }
+        });
+    });
+
+    it('should handle find request', async () => {
+        const handler = createNodeHandler(app);
+        server = createServer(handler);
+
+        const response = await request(server)
+            .post('/')
+            .send({
+                op: 'find',
+                object: 'user',
+                args: {}
+            })
+            .set('Accept', 'application/json');
+
+        expect(response.status).toBe(200);
+        expect(response.body).toEqual({
+            data: [{ id: 1, name: 'Alice' }]
+        });
+    });
+
+    it('should handle create request', async () => {
+        const handler = createNodeHandler(app);
+        server = createServer(handler);
+
+        const response = await request(server)
+            .post('/')
+            .send({
+                op: 'create',
+                object: 'user',
+                args: { data: { name: 'Bob' } }
+            });
+
+        expect(response.status).toBe(200);
+        expect(response.body).toEqual({
+            data: { id: 2, name: 'Bob' }
+        });
+    });
+
+    it('should return 405 for GET', async () => {
+        const handler = createNodeHandler(app);
+        server = createServer(handler);
+
+        const response = await request(server).get('/');
+        expect(response.status).toBe(405);
+    });
+});

packages/server/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "composite": true
+  },
+  "include": ["src/**/*"]
+}