@objectstack/rest 2.0.0 → 2.0.2

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/rest@2.0.0 build /home/runner/work/spec/spec/packages/rest
+> @objectstack/rest@2.0.2 build /home/runner/work/spec/spec/packages/rest
 > tsup --config ../../tsup.config.ts
 
 CLI Building entry: src/index.ts
@@ -10,13 +10,13 @@
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-ESM dist/index.js     20.70 KB
-ESM dist/index.js.map 50.10 KB
-ESM ⚡️ Build success in 50ms
 CJS dist/index.cjs     21.89 KB
 CJS dist/index.cjs.map 50.79 KB
-CJS ⚡️ Build success in 55ms
+CJS ⚡️ Build success in 67ms
+ESM dist/index.js     20.70 KB
+ESM dist/index.js.map 50.10 KB
+ESM ⚡️ Build success in 68ms
 DTS Build start
-DTS ⚡️ Build success in 10321ms
+DTS ⚡️ Build success in 7125ms
 DTS dist/index.d.ts  6.70 KB
 DTS dist/index.d.cts 6.70 KB

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @objectstack/rest
 
+## 2.0.2
+
+### Patch Changes
+
+- Updated dependencies [1db8559]
+  - @objectstack/spec@2.0.2
+  - @objectstack/core@2.0.2
+
+## 2.0.1
+
+### Patch Changes
+
+- Patch release for maintenance and stability improvements
+- Updated dependencies
+  - @objectstack/spec@2.0.1
+  - @objectstack/core@2.0.1
+
 ## 2.0.0
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/rest",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "license": "Apache-2.0",
   "description": "ObjectStack REST API Server - automatic REST endpoint generation from protocol",
   "type": "module",
@@ -14,9 +14,9 @@
     }
   },
   "dependencies": {
-    "zod": "^3.24.1",
-    "@objectstack/core": "2.0.0",
-    "@objectstack/spec": "2.0.0"
+    "zod": "^4.3.6",
+    "@objectstack/core": "2.0.2",
+    "@objectstack/spec": "2.0.2"
   },
   "devDependencies": {
     "typescript": "^5.0.0",

package/src/rest.test.ts

@@ -0,0 +1,531 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { RouteManager, RouteGroupBuilder } from './route-manager';
+import { RestServer } from './rest-server';
+import { createRestApiPlugin, createApiRegistryPlugin } from './rest-api-plugin';
+import type { RestApiPluginConfig } from './rest-api-plugin';
+
+// ---------------------------------------------------------------------------
+// Mocks & Helpers
+// ---------------------------------------------------------------------------
+
+/** Minimal IHttpServer mock */
+function createMockServer() {
+  return {
+    get: vi.fn(),
+    post: vi.fn(),
+    put: vi.fn(),
+    delete: vi.fn(),
+    patch: vi.fn(),
+    use: vi.fn(),
+    listen: vi.fn().mockResolvedValue(undefined),
+    close: vi.fn().mockResolvedValue(undefined),
+  };
+}
+
+/** Minimal ObjectStackProtocol mock */
+function createMockProtocol() {
+  return {
+    getDiscovery: vi.fn().mockResolvedValue({
+      version: 'v0',
+      endpoints: { data: '', metadata: '', ui: '', auth: '/auth' },
+    }),
+    getMetaTypes: vi.fn().mockResolvedValue([]),
+    getMetaItems: vi.fn().mockResolvedValue([]),
+    getMetaItem: vi.fn().mockResolvedValue({}),
+    getMetaItemCached: undefined as any,
+    saveMetaItem: undefined as any,
+    getUiView: undefined as any,
+    findData: vi.fn().mockResolvedValue([]),
+    getData: vi.fn().mockResolvedValue({}),
+    createData: vi.fn().mockResolvedValue({ id: '1' }),
+    updateData: vi.fn().mockResolvedValue({}),
+    deleteData: vi.fn().mockResolvedValue({ success: true }),
+    batchData: undefined as any,
+    createManyData: undefined as any,
+    updateManyData: undefined as any,
+    deleteManyData: undefined as any,
+  };
+}
+
+/** Minimal PluginContext mock */
+function createMockPluginContext(services: Record<string, any> = {}) {
+  return {
+    registerService: vi.fn(),
+    getService: vi.fn((name: string) => {
+      if (services[name]) return services[name];
+      throw new Error(`Service '${name}' not found`);
+    }),
+    getServices: vi.fn(() => new Map(Object.entries(services))),
+    hook: vi.fn(),
+    trigger: vi.fn().mockResolvedValue(undefined),
+    logger: {
+      debug: vi.fn(),
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+    },
+    getKernel: vi.fn(),
+  };
+}
+
+/** Dummy handler */
+const noop = vi.fn();
+
+// ---------------------------------------------------------------------------
+// RouteManager
+// ---------------------------------------------------------------------------
+
+describe('RouteManager', () => {
+  let server: ReturnType<typeof createMockServer>;
+  let manager: RouteManager;
+
+  beforeEach(() => {
+    server = createMockServer();
+    manager = new RouteManager(server as any);
+  });
+
+  // -- Registration --------------------------------------------------------
+
+  describe('register', () => {
+    it('should register a GET route and delegate to server.get', () => {
+      manager.register({ method: 'GET', path: '/users', handler: noop });
+      expect(server.get).toHaveBeenCalledWith('/users', noop);
+      expect(manager.count()).toBe(1);
+    });
+
+    it('should register POST, PUT, PATCH, DELETE routes', () => {
+      manager.register({ method: 'POST', path: '/a', handler: noop });
+      manager.register({ method: 'PUT', path: '/b', handler: noop });
+      manager.register({ method: 'PATCH', path: '/c', handler: noop });
+      manager.register({ method: 'DELETE', path: '/d', handler: noop });
+
+      expect(server.post).toHaveBeenCalledWith('/a', noop);
+      expect(server.put).toHaveBeenCalledWith('/b', noop);
+      expect(server.patch).toHaveBeenCalledWith('/c', noop);
+      expect(server.delete).toHaveBeenCalledWith('/d', noop);
+      expect(manager.count()).toBe(4);
+    });
+
+    it('should store metadata on the route entry', () => {
+      manager.register({
+        method: 'GET',
+        path: '/items',
+        handler: noop,
+        metadata: { summary: 'List items', tags: ['items'] },
+      });
+
+      const entry = manager.get('GET', '/items');
+      expect(entry).toBeDefined();
+      expect(entry!.metadata?.summary).toBe('List items');
+      expect(entry!.metadata?.tags).toContain('items');
+    });
+
+    it('should throw when a string handler is provided', () => {
+      expect(() =>
+        manager.register({ method: 'GET', path: '/x', handler: 'someHandler' }),
+      ).toThrow(/String-based route handlers/);
+    });
+  });
+
+  // -- registerMany --------------------------------------------------------
+
+  describe('registerMany', () => {
+    it('should register multiple routes at once', () => {
+      manager.registerMany([
+        { method: 'GET', path: '/a', handler: noop },
+        { method: 'POST', path: '/b', handler: noop },
+      ]);
+      expect(manager.count()).toBe(2);
+    });
+  });
+
+  // -- Lookup / query -------------------------------------------------------
+
+  describe('get', () => {
+    it('should return undefined for unregistered route', () => {
+      expect(manager.get('GET', '/nothing')).toBeUndefined();
+    });
+
+    it('should return the entry for a registered route', () => {
+      manager.register({ method: 'GET', path: '/users', handler: noop });
+      const entry = manager.get('GET', '/users');
+      expect(entry).toBeDefined();
+      expect(entry!.path).toBe('/users');
+    });
+  });
+
+  describe('getAll', () => {
+    it('should return all registered routes', () => {
+      manager.register({ method: 'GET', path: '/a', handler: noop });
+      manager.register({ method: 'POST', path: '/b', handler: noop });
+      expect(manager.getAll()).toHaveLength(2);
+    });
+  });
+
+  describe('getByMethod', () => {
+    it('should filter routes by HTTP method', () => {
+      manager.register({ method: 'GET', path: '/a', handler: noop });
+      manager.register({ method: 'GET', path: '/b', handler: noop });
+      manager.register({ method: 'POST', path: '/c', handler: noop });
+
+      expect(manager.getByMethod('GET')).toHaveLength(2);
+      expect(manager.getByMethod('POST')).toHaveLength(1);
+      expect(manager.getByMethod('DELETE')).toHaveLength(0);
+    });
+  });
+
+  describe('getByPrefix', () => {
+    it('should filter routes by path prefix', () => {
+      manager.register({ method: 'GET', path: '/api/users', handler: noop });
+      manager.register({ method: 'GET', path: '/api/items', handler: noop });
+      manager.register({ method: 'GET', path: '/other', handler: noop });
+
+      expect(manager.getByPrefix('/api')).toHaveLength(2);
+    });
+  });
+
+  describe('getByTag', () => {
+    it('should filter routes by metadata tag', () => {
+      manager.register({
+        method: 'GET', path: '/a', handler: noop,
+        metadata: { tags: ['users'] },
+      });
+      manager.register({
+        method: 'GET', path: '/b', handler: noop,
+        metadata: { tags: ['items'] },
+      });
+      manager.register({ method: 'GET', path: '/c', handler: noop });
+
+      expect(manager.getByTag('users')).toHaveLength(1);
+      expect(manager.getByTag('missing')).toHaveLength(0);
+    });
+  });
+
+  // -- Unregister -----------------------------------------------------------
+
+  describe('unregister', () => {
+    it('should remove a route from the registry', () => {
+      manager.register({ method: 'GET', path: '/x', handler: noop });
+      expect(manager.count()).toBe(1);
+
+      manager.unregister('GET', '/x');
+      expect(manager.count()).toBe(0);
+      expect(manager.get('GET', '/x')).toBeUndefined();
+    });
+  });
+
+  // -- Clear ----------------------------------------------------------------
+
+  describe('clear', () => {
+    it('should remove all routes', () => {
+      manager.registerMany([
+        { method: 'GET', path: '/a', handler: noop },
+        { method: 'POST', path: '/b', handler: noop },
+      ]);
+      manager.clear();
+      expect(manager.count()).toBe(0);
+    });
+  });
+
+  // -- Group ----------------------------------------------------------------
+
+  describe('group', () => {
+    it('should create routes with the prefix prepended', () => {
+      manager.group('/api/v1', (group) => {
+        group.get('/users', noop);
+        group.post('/users', noop);
+        group.put('/users/:id', noop);
+        group.patch('/users/:id', noop);
+        group.delete('/users/:id', noop);
+      });
+
+      expect(manager.count()).toBe(5);
+      expect(manager.get('GET', '/api/v1/users')).toBeDefined();
+      expect(manager.get('POST', '/api/v1/users')).toBeDefined();
+      expect(manager.get('PUT', '/api/v1/users/:id')).toBeDefined();
+      expect(manager.get('PATCH', '/api/v1/users/:id')).toBeDefined();
+      expect(manager.get('DELETE', '/api/v1/users/:id')).toBeDefined();
+    });
+
+    it('should normalize paths (strip trailing slash on prefix, ensure leading slash on path)', () => {
+      manager.group('/api/', (group) => {
+        group.get('items', noop);
+      });
+      expect(manager.get('GET', '/api/items')).toBeDefined();
+    });
+
+    it('should allow chaining on group builder methods', () => {
+      manager.group('/api', (group) => {
+        const result = group
+          .get('/a', noop)
+          .post('/b', noop);
+        expect(result).toBe(group);
+      });
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// RestServer
+// ---------------------------------------------------------------------------
+
+describe('RestServer', () => {
+  let server: ReturnType<typeof createMockServer>;
+  let protocol: ReturnType<typeof createMockProtocol>;
+
+  beforeEach(() => {
+    server = createMockServer();
+    protocol = createMockProtocol();
+  });
+
+  // -- Constructor & defaults -----------------------------------------------
+
+  describe('constructor', () => {
+    it('should create a RestServer with default config', () => {
+      const rest = new RestServer(server as any, protocol as any);
+      expect(rest).toBeDefined();
+      expect(rest.getRouteManager()).toBeInstanceOf(RouteManager);
+    });
+
+    it('should accept custom config', () => {
+      const rest = new RestServer(server as any, protocol as any, {
+        api: { version: 'v2', basePath: '/custom' },
+      } as any);
+      expect(rest).toBeDefined();
+    });
+  });
+
+  // -- registerRoutes -------------------------------------------------------
+
+  describe('registerRoutes', () => {
+    it('should register discovery, metadata, UI, CRUD, and batch routes by default', () => {
+      const rest = new RestServer(server as any, protocol as any);
+      rest.registerRoutes();
+
+      const routes = rest.getRoutes();
+      expect(routes.length).toBeGreaterThan(0);
+
+      // Expect at least discovery + metadata + CRUD routes
+      const paths = routes.map((r) => r.path);
+      // Discovery
+      expect(paths).toContain('/api/v1');
+      // Metadata
+      expect(paths.some((p) => p.includes('/meta'))).toBe(true);
+      // CRUD
+      expect(paths.some((p) => p.includes('/data'))).toBe(true);
+    });
+
+    it('should use custom apiPath when specified', () => {
+      const rest = new RestServer(server as any, protocol as any, {
+        api: { apiPath: '/custom/path' },
+      } as any);
+      rest.registerRoutes();
+
+      const paths = rest.getRoutes().map((r) => r.path);
+      expect(paths.some((p) => p.startsWith('/custom/path'))).toBe(true);
+    });
+
+    it('should skip CRUD routes when enableCrud is false', () => {
+      const rest = new RestServer(server as any, protocol as any, {
+        api: { enableCrud: false },
+      } as any);
+      rest.registerRoutes();
+
+      const tags = rest.getRoutes().flatMap((r) => r.metadata?.tags ?? []);
+      expect(tags).not.toContain('crud');
+    });
+
+    it('should skip metadata routes when enableMetadata is false', () => {
+      const rest = new RestServer(server as any, protocol as any, {
+        api: { enableMetadata: false },
+      } as any);
+      rest.registerRoutes();
+
+      const routes = rest.getRoutes();
+      // Only the PUT /meta/:type/:name is always registered, but enableMetadata=false
+      // skips the entire registerMetadataEndpoints call
+      expect(routes.every((r) => !r.path.includes('/meta'))).toBe(true);
+    });
+
+    it('should skip discovery when enableDiscovery is false', () => {
+      const rest = new RestServer(server as any, protocol as any, {
+        api: { enableDiscovery: false },
+      } as any);
+      rest.registerRoutes();
+
+      const routes = rest.getRoutes();
+      // Discovery route is the basePath itself (e.g. /api/v1)
+      const discoveryRoutes = routes.filter((r) =>
+        r.metadata?.tags?.includes('discovery'),
+      );
+      expect(discoveryRoutes).toHaveLength(0);
+    });
+
+    it('should skip batch routes when enableBatch is false', () => {
+      const rest = new RestServer(server as any, protocol as any, {
+        api: { enableBatch: false },
+      } as any);
+      rest.registerRoutes();
+
+      const tags = rest.getRoutes().flatMap((r) => r.metadata?.tags ?? []);
+      expect(tags).not.toContain('batch');
+    });
+
+    it('should register batch endpoints when protocol implements batch methods', () => {
+      protocol.batchData = vi.fn().mockResolvedValue({});
+      protocol.createManyData = vi.fn().mockResolvedValue([]);
+      protocol.updateManyData = vi.fn().mockResolvedValue([]);
+      protocol.deleteManyData = vi.fn().mockResolvedValue([]);
+
+      const rest = new RestServer(server as any, protocol as any);
+      rest.registerRoutes();
+
+      const batchRoutes = rest.getRoutes().filter((r) =>
+        r.metadata?.tags?.includes('batch'),
+      );
+      expect(batchRoutes.length).toBeGreaterThan(0);
+    });
+
+    it('should register UI view endpoint when enableUi is true', () => {
+      const rest = new RestServer(server as any, protocol as any);
+      rest.registerRoutes();
+
+      const uiRoutes = rest.getRoutes().filter((r) =>
+        r.metadata?.tags?.includes('ui'),
+      );
+      expect(uiRoutes.length).toBeGreaterThan(0);
+    });
+  });
+
+  // -- getRouteManager / getRoutes ------------------------------------------
+
+  describe('getRouteManager', () => {
+    it('should return the internal RouteManager instance', () => {
+      const rest = new RestServer(server as any, protocol as any);
+      const rm = rest.getRouteManager();
+      expect(rm).toBeInstanceOf(RouteManager);
+    });
+  });
+
+  describe('getRoutes', () => {
+    it('should return an empty array before registerRoutes is called', () => {
+      const rest = new RestServer(server as any, protocol as any);
+      expect(rest.getRoutes()).toEqual([]);
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// createRestApiPlugin
+// ---------------------------------------------------------------------------
+
+describe('createRestApiPlugin', () => {
+  it('should return a plugin object with name and version', () => {
+    const plugin = createRestApiPlugin();
+    expect(plugin.name).toBe('com.objectstack.rest.api');
+    expect(plugin.version).toBe('1.0.0');
+    expect(typeof plugin.init).toBe('function');
+    expect(typeof plugin.start).toBe('function');
+  });
+
+  it('should accept custom config', () => {
+    const cfg: RestApiPluginConfig = {
+      serverServiceName: 'my.server',
+      protocolServiceName: 'my.protocol',
+    };
+    const plugin = createRestApiPlugin(cfg);
+    expect(plugin.name).toBe('com.objectstack.rest.api');
+  });
+
+  describe('init', () => {
+    it('should resolve without error', async () => {
+      const plugin = createRestApiPlugin();
+      const ctx = createMockPluginContext();
+      await expect(plugin.init(ctx as any)).resolves.toBeUndefined();
+    });
+  });
+
+  describe('start', () => {
+    it('should warn and skip when http server is not found', async () => {
+      const plugin = createRestApiPlugin();
+      const ctx = createMockPluginContext(); // no services
+      await plugin.start!(ctx as any);
+      expect(ctx.logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('HTTP Server'),
+      );
+    });
+
+    it('should warn and skip when protocol is not found', async () => {
+      const mockServer = createMockServer();
+      const ctx = createMockPluginContext({ 'http.server': mockServer });
+      const plugin = createRestApiPlugin();
+      await plugin.start!(ctx as any);
+      expect(ctx.logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('Protocol'),
+      );
+    });
+
+    it('should register REST routes when both services are present', async () => {
+      const mockServer = createMockServer();
+      const mockProtocol = createMockProtocol();
+      const ctx = createMockPluginContext({
+        'http.server': mockServer,
+        protocol: mockProtocol,
+      });
+
+      const plugin = createRestApiPlugin();
+      await plugin.start!(ctx as any);
+
+      expect(ctx.logger.info).toHaveBeenCalledWith(
+        expect.stringContaining('REST API successfully registered'),
+      );
+      // CRUD routes should have been mounted
+      expect(mockServer.get).toHaveBeenCalled();
+      expect(mockServer.post).toHaveBeenCalled();
+    });
+
+    it('should use custom service names from config', async () => {
+      const mockServer = createMockServer();
+      const mockProtocol = createMockProtocol();
+      const ctx = createMockPluginContext({
+        'my.server': mockServer,
+        'my.protocol': mockProtocol,
+      });
+
+      const plugin = createRestApiPlugin({
+        serverServiceName: 'my.server',
+        protocolServiceName: 'my.protocol',
+      });
+      await plugin.start!(ctx as any);
+
+      expect(ctx.logger.info).toHaveBeenCalledWith(
+        expect.stringContaining('REST API successfully registered'),
+      );
+    });
+
+    it('should throw and log error when RestServer construction fails', async () => {
+      const badServer = {}; // missing methods → will throw
+      const mockProtocol = createMockProtocol();
+      const ctx = createMockPluginContext({
+        'http.server': badServer,
+        protocol: mockProtocol,
+      });
+
+      const plugin = createRestApiPlugin();
+      await expect(plugin.start!(ctx as any)).rejects.toThrow();
+      expect(ctx.logger.error).toHaveBeenCalled();
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Backward-compatible aliases
+// ---------------------------------------------------------------------------
+
+describe('backward-compatible aliases', () => {
+  it('createApiRegistryPlugin should be the same function as createRestApiPlugin', () => {
+    expect(createApiRegistryPlugin).toBe(createRestApiPlugin);
+  });
+});

package/vitest.config.ts

@@ -0,0 +1,10 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+  },
+});