@mostajs/net 1.0.0-alpha.1

package/dist/transports/mcp.transport.js

@@ -0,0 +1,188 @@
+// McpTransport — Model Context Protocol transport adapter
+// Exposes ORM entities as MCP tools and resources for AI agents (Claude, GPT, etc.)
+// Uses the official @modelcontextprotocol/sdk
+// Author: Dr Hamid MADANI drmdh@msn.com
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { z } from 'zod';
+export class McpTransport {
+    name = 'mcp';
+    config = null;
+    schemas = [];
+    middlewares = [];
+    ormHandler = null;
+    stats = { requests: 0, errors: 0, startedAt: 0 };
+    setHandler(handler) { this.ormHandler = handler; }
+    use(mw) { this.middlewares.push(mw); }
+    registerEntity(schema) { this.schemas.push(schema); }
+    async start(config) {
+        this.config = config;
+        this.stats.startedAt = Date.now();
+        // MCP server is created per-request in handleRequest() (stateless mode)
+    }
+    async stop() {
+        this.config = null;
+    }
+    getInfo() {
+        return {
+            name: this.name,
+            status: this.config ? 'running' : 'stopped',
+            url: this.config?.path || '/mcp',
+            entities: this.schemas.map(s => s.name),
+            stats: { ...this.stats },
+        };
+    }
+    getPath() {
+        return this.config?.path || '/mcp';
+    }
+    /**
+     * Handle an incoming MCP HTTP request.
+     * Called by the main Fastify server via route handler.
+     */
+    /**
+     * Handle an incoming MCP HTTP request.
+     * Creates a new McpServer + Transport per session for stateless mode.
+     */
+    async handleRequest(req, res, body) {
+        // Create a fresh MCP server per request (stateless mode)
+        const server = new McpServer({ name: '@mostajs/orm', version: '1.5.0' }, { capabilities: { tools: {}, resources: {} } });
+        // Register tools and resources
+        for (const schema of this.schemas) {
+            this.registerEntityToolsOn(server, schema);
+            this.registerEntityResourcesOn(server, schema);
+        }
+        // Create transport and connect
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined, // stateless
+        });
+        await server.connect(transport);
+        await transport.handleRequest(req, res, body);
+    }
+    // ============================================================
+    // Tool registration (CRUD operations per entity)
+    // ============================================================
+    registerEntityToolsOn(server, schema) {
+        const name = schema.name;
+        // Tool: {Entity}_findAll — query entities
+        server.registerTool(`${name}_findAll`, {
+            description: `Find all ${name} entities. Optionally filter, sort, limit.`,
+            inputSchema: {
+                filter: z.string().optional().describe('JSON filter object (MongoDB-style)'),
+                sort: z.string().optional().describe('JSON sort object, e.g. {"name":1}'),
+                limit: z.number().optional().describe('Max results to return'),
+                skip: z.number().optional().describe('Number of results to skip'),
+            },
+        }, async (params) => {
+            this.stats.requests++;
+            const res = await this.callOrm({
+                op: 'findAll',
+                entity: name,
+                filter: params.filter ? JSON.parse(params.filter) : {},
+                options: {
+                    sort: params.sort ? JSON.parse(params.sort) : undefined,
+                    limit: params.limit,
+                    skip: params.skip,
+                },
+            });
+            return { content: [{ type: 'text', text: JSON.stringify(res.data, null, 2) }] };
+        });
+        // Tool: {Entity}_findById — get one entity by ID
+        server.registerTool(`${name}_findById`, {
+            description: `Find a ${name} entity by its ID.`,
+            inputSchema: {
+                id: z.string().describe(`The ${name} ID`),
+            },
+        }, async (params) => {
+            this.stats.requests++;
+            const res = await this.callOrm({ op: 'findById', entity: name, id: params.id });
+            if (!res.data) {
+                return { content: [{ type: 'text', text: `${name} with id "${params.id}" not found` }], isError: true };
+            }
+            return { content: [{ type: 'text', text: JSON.stringify(res.data, null, 2) }] };
+        });
+        // Tool: {Entity}_create — create a new entity
+        server.registerTool(`${name}_create`, {
+            description: `Create a new ${name} entity.`,
+            inputSchema: {
+                data: z.string().describe(`JSON object with ${name} fields: ${Object.keys(schema.fields).join(', ')}`),
+            },
+        }, async (params) => {
+            this.stats.requests++;
+            const data = JSON.parse(params.data);
+            const res = await this.callOrm({ op: 'create', entity: name, data });
+            if (res.status === 'error') {
+                return { content: [{ type: 'text', text: `Error: ${res.error?.message}` }], isError: true };
+            }
+            return { content: [{ type: 'text', text: JSON.stringify(res.data, null, 2) }] };
+        });
+        // Tool: {Entity}_update — update an entity
+        server.registerTool(`${name}_update`, {
+            description: `Update a ${name} entity by ID.`,
+            inputSchema: {
+                id: z.string().describe(`The ${name} ID to update`),
+                data: z.string().describe('JSON object with fields to update'),
+            },
+        }, async (params) => {
+            this.stats.requests++;
+            const data = JSON.parse(params.data);
+            const res = await this.callOrm({ op: 'update', entity: name, id: params.id, data });
+            if (res.status === 'error') {
+                return { content: [{ type: 'text', text: `Error: ${res.error?.message}` }], isError: true };
+            }
+            return { content: [{ type: 'text', text: JSON.stringify(res.data, null, 2) }] };
+        });
+        // Tool: {Entity}_delete — delete an entity
+        server.registerTool(`${name}_delete`, {
+            description: `Delete a ${name} entity by ID.`,
+            inputSchema: {
+                id: z.string().describe(`The ${name} ID to delete`),
+            },
+        }, async (params) => {
+            this.stats.requests++;
+            const res = await this.callOrm({ op: 'delete', entity: name, id: params.id });
+            return { content: [{ type: 'text', text: res.data ? 'Deleted' : 'Not found' }] };
+        });
+        // Tool: {Entity}_count — count entities
+        server.registerTool(`${name}_count`, {
+            description: `Count ${name} entities. Optionally filter.`,
+            inputSchema: {
+                filter: z.string().optional().describe('JSON filter object'),
+            },
+        }, async (params) => {
+            this.stats.requests++;
+            const res = await this.callOrm({
+                op: 'count',
+                entity: name,
+                filter: params.filter ? JSON.parse(params.filter) : {},
+            });
+            return { content: [{ type: 'text', text: String(res.data) }] };
+        });
+    }
+    // ============================================================
+    // Resource registration (schema info per entity)
+    // ============================================================
+    registerEntityResourcesOn(server, schema) {
+        // Resource: entity schema definition
+        server.registerResource(`${schema.name} Schema`, `entity://${schema.name}/schema`, { description: `Schema definition for ${schema.name} entity`, mimeType: 'application/json' }, async () => ({
+            contents: [{
+                    uri: `entity://${schema.name}/schema`,
+                    text: JSON.stringify(schema, null, 2),
+                    mimeType: 'application/json',
+                }],
+        }));
+    }
+    // ============================================================
+    // ORM call helper
+    // ============================================================
+    async callOrm(req) {
+        if (!this.ormHandler) {
+            return { status: 'error', error: { code: 'NO_HANDLER', message: 'ORM handler not initialized' } };
+        }
+        const ctx = { transport: this.name };
+        return this.ormHandler(req, ctx);
+    }
+}
+/** Factory */
+export function createTransport() {
+    return new McpTransport();
+}

package/dist/transports/rest.transport.d.ts

@@ -0,0 +1,29 @@
+import type { FastifyInstance } from 'fastify';
+import type { EntitySchema, OrmRequest, OrmResponse } from '@mostajs/orm';
+import type { ITransport, TransportConfig, TransportInfo, TransportMiddleware, TransportContext } from '../core/types.js';
+/** Handler function that executes OrmRequest (set by the server) */
+type OrmHandler = (req: OrmRequest, ctx: TransportContext) => Promise<OrmResponse>;
+export declare class RestTransport implements ITransport {
+    readonly name = "rest";
+    private app;
+    private config;
+    private schemas;
+    private middlewares;
+    private ormHandler;
+    private stats;
+    /** Set the ORM handler (called by the server after creating EntityService) */
+    setHandler(handler: OrmHandler): void;
+    use(middleware: TransportMiddleware): void;
+    registerEntity(schema: EntitySchema): void;
+    start(config: TransportConfig): Promise<void>;
+    stop(): Promise<void>;
+    getInfo(): TransportInfo;
+    /** Get the Fastify instance (for mounting in the shared server) */
+    getApp(): FastifyInstance | null;
+    private registerRoutes;
+    private handle;
+    private mapErrorToHttpStatus;
+}
+/** Factory function (used by transport loader) */
+export declare function createTransport(): ITransport;
+export {};

package/dist/transports/rest.transport.js

@@ -0,0 +1,184 @@
+// RestTransport — REST API transport adapter
+// Generates CRUD routes from EntitySchema, translates HTTP → OrmRequest → OrmResponse → HTTP
+// Mirror of MongoDialect / PostgresDialect in @mostajs/orm
+// Author: Dr Hamid MADANI drmdh@msn.com
+import Fastify from 'fastify';
+import { composeMiddleware } from '../core/middleware.js';
+export class RestTransport {
+    name = 'rest';
+    app = null;
+    config = null;
+    schemas = [];
+    middlewares = [];
+    ormHandler = null;
+    stats = { requests: 0, errors: 0, startedAt: 0 };
+    /** Set the ORM handler (called by the server after creating EntityService) */
+    setHandler(handler) {
+        this.ormHandler = handler;
+    }
+    use(middleware) {
+        this.middlewares.push(middleware);
+    }
+    registerEntity(schema) {
+        this.schemas.push(schema);
+    }
+    async start(config) {
+        this.config = config;
+        this.stats.startedAt = Date.now();
+        // Fastify instance is created here but NOT listened —
+        // the main server.ts will inject it into the shared Fastify instance
+        this.app = Fastify({ logger: false });
+        // Register routes for each entity
+        for (const schema of this.schemas) {
+            this.registerRoutes(schema);
+        }
+    }
+    async stop() {
+        this.app = null;
+    }
+    getInfo() {
+        return {
+            name: this.name,
+            status: this.app ? 'running' : 'stopped',
+            url: this.config?.path || '/api/v1',
+            entities: this.schemas.map(s => s.name),
+            stats: { ...this.stats },
+        };
+    }
+    /** Get the Fastify instance (for mounting in the shared server) */
+    getApp() {
+        return this.app;
+    }
+    // ============================================================
+    // Route generation
+    // ============================================================
+    registerRoutes(schema) {
+        if (!this.app)
+            return;
+        const prefix = this.config?.path || '/api/v1';
+        const collection = schema.collection;
+        // GET /api/v1/{collection} → findAll
+        this.app.get(`${prefix}/${collection}`, async (req, reply) => {
+            const query = req.query;
+            const ormReq = {
+                op: 'findAll',
+                entity: schema.name,
+                filter: query.filter ? JSON.parse(query.filter) : {},
+                options: {
+                    sort: query.sort ? JSON.parse(query.sort) : undefined,
+                    limit: query.limit ? parseInt(query.limit, 10) : undefined,
+                    skip: query.skip ? parseInt(query.skip, 10) : undefined,
+                    select: query.select ? query.select.split(',') : undefined,
+                },
+            };
+            return this.handle(ormReq, reply);
+        });
+        // GET /api/v1/{collection}/:id → findById
+        this.app.get(`${prefix}/${collection}/:id`, async (req, reply) => {
+            const { id } = req.params;
+            const query = req.query;
+            const ormReq = {
+                op: 'findById',
+                entity: schema.name,
+                id,
+                relations: query.include ? query.include.split(',') : undefined,
+            };
+            return this.handle(ormReq, reply);
+        });
+        // POST /api/v1/{collection} → create
+        this.app.post(`${prefix}/${collection}`, async (req, reply) => {
+            const ormReq = {
+                op: 'create',
+                entity: schema.name,
+                data: req.body,
+            };
+            const res = await this.handle(ormReq, reply);
+            if (reply.statusCode < 400)
+                reply.status(201);
+            return res;
+        });
+        // PUT /api/v1/{collection}/:id → update
+        this.app.put(`${prefix}/${collection}/:id`, async (req, reply) => {
+            const { id } = req.params;
+            const ormReq = {
+                op: 'update',
+                entity: schema.name,
+                id,
+                data: req.body,
+            };
+            return this.handle(ormReq, reply);
+        });
+        // DELETE /api/v1/{collection}/:id → delete
+        this.app.delete(`${prefix}/${collection}/:id`, async (req, reply) => {
+            const { id } = req.params;
+            const ormReq = {
+                op: 'delete',
+                entity: schema.name,
+                id,
+            };
+            return this.handle(ormReq, reply);
+        });
+        // GET /api/v1/{collection}/count → count
+        this.app.get(`${prefix}/${collection}/count`, async (req, reply) => {
+            const query = req.query;
+            const ormReq = {
+                op: 'count',
+                entity: schema.name,
+                filter: query.filter ? JSON.parse(query.filter) : {},
+            };
+            return this.handle(ormReq, reply);
+        });
+        // POST /api/v1/{collection}/search → search
+        this.app.post(`${prefix}/${collection}/search`, async (req, reply) => {
+            const body = req.body;
+            const ormReq = {
+                op: 'search',
+                entity: schema.name,
+                query: body.query,
+                searchFields: body.fields,
+                options: body.options,
+            };
+            return this.handle(ormReq, reply);
+        });
+    }
+    // ============================================================
+    // Request handling (OrmRequest → middleware → OrmResponse → HTTP)
+    // ============================================================
+    async handle(ormReq, reply) {
+        this.stats.requests++;
+        if (!this.ormHandler) {
+            this.stats.errors++;
+            reply.status(503);
+            return { status: 'error', error: { code: 'NO_HANDLER', message: 'ORM handler not initialized' } };
+        }
+        const ctx = { transport: this.name };
+        // Compose middleware chain → final handler
+        const chain = composeMiddleware(this.middlewares, this.ormHandler);
+        const res = await chain(ormReq, ctx);
+        if (res.status === 'error') {
+            this.stats.errors++;
+            const code = this.mapErrorToHttpStatus(res.error?.code);
+            reply.status(code);
+        }
+        return res;
+    }
+    mapErrorToHttpStatus(code) {
+        switch (code) {
+            case 'ENTITY_NOT_FOUND': return 404;
+            case 'EntityNotFoundError': return 404;
+            case 'MISSING_ID': return 400;
+            case 'MISSING_DATA': return 400;
+            case 'MISSING_QUERY': return 400;
+            case 'MISSING_PARAMS': return 400;
+            case 'MISSING_STAGES': return 400;
+            case 'UNKNOWN_OP': return 400;
+            case 'ValidationError': return 422;
+            case 'ConnectionError': return 503;
+            default: return 500;
+        }
+    }
+}
+/** Factory function (used by transport loader) */
+export function createTransport() {
+    return new RestTransport();
+}

package/dist/transports/sse.transport.d.ts

@@ -0,0 +1,45 @@
+import type { EntitySchema } from '@mostajs/orm';
+import type { ITransport, TransportConfig, TransportInfo, TransportMiddleware } from '../core/types.js';
+import type { ServerResponse } from 'http';
+/**
+ * SSETransport streams entity change events to clients via Server-Sent Events.
+ *
+ * Clients connect to GET /events (or configured path) and receive:
+ *   event: entity.created
+ *   data: {"entity":"User","data":{...}}
+ *
+ *   event: entity.updated
+ *   data: {"entity":"User","id":"123","data":{...}}
+ *
+ *   event: entity.deleted
+ *   data: {"entity":"User","id":"123"}
+ */
+export declare class SSETransport implements ITransport {
+    readonly name = "sse";
+    private config;
+    private schemas;
+    private middlewares;
+    private clients;
+    private stats;
+    use(middleware: TransportMiddleware): void;
+    registerEntity(schema: EntitySchema): void;
+    start(config: TransportConfig): Promise<void>;
+    stop(): Promise<void>;
+    getInfo(): TransportInfo;
+    /** Get the SSE path for Fastify route registration */
+    getPath(): string;
+    /** Get connected client count */
+    getClientCount(): number;
+    /**
+     * Handle a new SSE client connection.
+     * Called by the server when a GET request arrives at the SSE path.
+     */
+    addClient(res: ServerResponse): void;
+    /**
+     * Broadcast an event to all connected SSE clients.
+     * Called by the server when EntityService emits change events.
+     */
+    broadcast(eventName: string, data: Record<string, unknown>): void;
+}
+/** Factory function */
+export declare function createTransport(): ITransport;

package/dist/transports/sse.transport.js

@@ -0,0 +1,99 @@
+// SSETransport — Server-Sent Events transport adapter
+// Pushes entity change notifications (created, updated, deleted) to connected clients
+// Author: Dr Hamid MADANI drmdh@msn.com
+/**
+ * SSETransport streams entity change events to clients via Server-Sent Events.
+ *
+ * Clients connect to GET /events (or configured path) and receive:
+ *   event: entity.created
+ *   data: {"entity":"User","data":{...}}
+ *
+ *   event: entity.updated
+ *   data: {"entity":"User","id":"123","data":{...}}
+ *
+ *   event: entity.deleted
+ *   data: {"entity":"User","id":"123"}
+ */
+export class SSETransport {
+    name = 'sse';
+    config = null;
+    schemas = [];
+    middlewares = [];
+    clients = new Set();
+    stats = { requests: 0, errors: 0, startedAt: 0 };
+    use(middleware) {
+        this.middlewares.push(middleware);
+    }
+    registerEntity(schema) {
+        this.schemas.push(schema);
+    }
+    async start(config) {
+        this.config = config;
+        this.stats.startedAt = Date.now();
+    }
+    async stop() {
+        // Close all connected clients
+        for (const client of this.clients) {
+            client.end();
+        }
+        this.clients.clear();
+    }
+    getInfo() {
+        return {
+            name: this.name,
+            status: this.config ? 'running' : 'stopped',
+            url: this.config?.path || '/events',
+            entities: this.schemas.map(s => s.name),
+            stats: { ...this.stats },
+        };
+    }
+    /** Get the SSE path for Fastify route registration */
+    getPath() {
+        return this.config?.path || '/events';
+    }
+    /** Get connected client count */
+    getClientCount() {
+        return this.clients.size;
+    }
+    /**
+     * Handle a new SSE client connection.
+     * Called by the server when a GET request arrives at the SSE path.
+     */
+    addClient(res) {
+        this.stats.requests++;
+        // SSE headers
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            'Connection': 'keep-alive',
+            'X-Accel-Buffering': 'no', // Disable nginx buffering
+        });
+        // Send initial comment (keep-alive)
+        res.write(':ok\n\n');
+        // Send connected event with available entities
+        const connectData = JSON.stringify({
+            entities: this.schemas.map(s => s.name),
+            connectedAt: new Date().toISOString(),
+        });
+        res.write(`event: connected\ndata: ${connectData}\n\n`);
+        this.clients.add(res);
+        // Remove client on disconnect
+        res.on('close', () => {
+            this.clients.delete(res);
+        });
+    }
+    /**
+     * Broadcast an event to all connected SSE clients.
+     * Called by the server when EntityService emits change events.
+     */
+    broadcast(eventName, data) {
+        const payload = `event: ${eventName}\ndata: ${JSON.stringify(data)}\n\n`;
+        for (const client of this.clients) {
+            client.write(payload);
+        }
+    }
+}
+/** Factory function */
+export function createTransport() {
+    return new SSETransport();
+}

package/dist/transports/ws.transport.d.ts

@@ -0,0 +1,33 @@
+import type { EntitySchema, OrmRequest, OrmResponse } from '@mostajs/orm';
+import type { ITransport, TransportConfig, TransportInfo, TransportMiddleware, TransportContext } from '../core/types.js';
+type OrmHandler = (req: OrmRequest, ctx: TransportContext) => Promise<OrmResponse>;
+export declare class WebSocketTransport implements ITransport {
+    readonly name = "ws";
+    private wss;
+    private config;
+    private schemas;
+    private middlewares;
+    private ormHandler;
+    private stats;
+    setHandler(handler: OrmHandler): void;
+    use(mw: TransportMiddleware): void;
+    registerEntity(schema: EntitySchema): void;
+    start(config: TransportConfig): Promise<void>;
+    stop(): Promise<void>;
+    getInfo(): TransportInfo;
+    /** Get connected client count */
+    getClientCount(): number;
+    /**
+     * Attach WebSocket server to an existing HTTP server.
+     * Called by server.ts after Fastify starts listening.
+     */
+    attachToServer(httpServer: import('http').Server): void;
+    /**
+     * Broadcast an entity change event to all connected WebSocket clients.
+     */
+    broadcast(eventName: string, data: Record<string, unknown>): void;
+    private handleRequest;
+}
+/** Factory */
+export declare function createTransport(): ITransport;
+export {};

package/dist/transports/ws.transport.js

@@ -0,0 +1,100 @@
+// WebSocketTransport — Bidirectional WebSocket transport
+// Clients send OrmRequest as JSON, receive OrmResponse + entity change events
+// Author: Dr Hamid MADANI drmdh@msn.com
+import { WebSocketServer, WebSocket } from 'ws';
+export class WebSocketTransport {
+    name = 'ws';
+    wss = null;
+    config = null;
+    schemas = [];
+    middlewares = [];
+    ormHandler = null;
+    stats = { requests: 0, errors: 0, startedAt: 0 };
+    setHandler(handler) { this.ormHandler = handler; }
+    use(mw) { this.middlewares.push(mw); }
+    registerEntity(schema) { this.schemas.push(schema); }
+    async start(config) {
+        this.config = config;
+        this.stats.startedAt = Date.now();
+        // WSS is created later when the HTTP server is available (see attachToServer)
+    }
+    async stop() {
+        if (this.wss) {
+            for (const client of this.wss.clients) {
+                client.close(1000, 'Server shutting down');
+            }
+            this.wss.close();
+            this.wss = null;
+        }
+    }
+    getInfo() {
+        return {
+            name: this.name,
+            status: this.wss ? 'running' : 'stopped',
+            url: this.config?.path || '/ws',
+            entities: this.schemas.map(s => s.name),
+            stats: { ...this.stats },
+        };
+    }
+    /** Get connected client count */
+    getClientCount() {
+        return this.wss?.clients.size || 0;
+    }
+    /**
+     * Attach WebSocket server to an existing HTTP server.
+     * Called by server.ts after Fastify starts listening.
+     */
+    attachToServer(httpServer) {
+        const path = this.config?.path || '/ws';
+        this.wss = new WebSocketServer({ server: httpServer, path });
+        this.wss.on('connection', (socket) => {
+            // Send welcome message
+            socket.send(JSON.stringify({
+                type: 'connected',
+                entities: this.schemas.map(s => s.name),
+                connectedAt: new Date().toISOString(),
+            }));
+            // Handle incoming messages (OrmRequest)
+            socket.on('message', async (raw) => {
+                this.stats.requests++;
+                try {
+                    const req = JSON.parse(raw.toString());
+                    const res = await this.handleRequest(req);
+                    socket.send(JSON.stringify({ type: 'response', ...res }));
+                }
+                catch (err) {
+                    this.stats.errors++;
+                    socket.send(JSON.stringify({
+                        type: 'response',
+                        status: 'error',
+                        error: { code: 'PARSE_ERROR', message: err.message },
+                    }));
+                }
+            });
+        });
+    }
+    /**
+     * Broadcast an entity change event to all connected WebSocket clients.
+     */
+    broadcast(eventName, data) {
+        if (!this.wss)
+            return;
+        const payload = JSON.stringify({ type: 'event', event: eventName, ...data });
+        for (const client of this.wss.clients) {
+            if (client.readyState === WebSocket.OPEN) {
+                client.send(payload);
+            }
+        }
+    }
+    async handleRequest(req) {
+        if (!this.ormHandler) {
+            return { status: 'error', error: { code: 'NO_HANDLER', message: 'ORM handler not initialized' } };
+        }
+        const ctx = { transport: this.name };
+        return this.ormHandler(req, ctx);
+    }
+}
+/** Factory */
+export function createTransport() {
+    return new WebSocketTransport();
+}