@geekmidas/constructs 0.0.6 → 0.0.9

package/src/endpoints/__tests__/EndpointFactory.authorizers.spec.ts

@@ -0,0 +1,259 @@
+import { describe, expect, it } from 'vitest';
+import { EndpointFactory } from '../EndpointFactory';
+import { z } from 'zod';
+
+describe('EndpointFactory.authorizers', () => {
+  it('should create factory with available authorizers', () => {
+    const factory = new EndpointFactory().authorizers([
+      'iam',
+      'jwt-auth0',
+      'custom',
+    ] as const);
+
+    const endpoint = factory
+      .get('/users')
+      .authorizer('iam')
+      .handle(async () => ({ success: true }));
+
+    expect(endpoint.authorizer).toEqual({ name: 'iam' });
+  });
+
+  it('should allow setting authorizer on individual endpoints', () => {
+    const factory = new EndpointFactory().authorizers(['iam', 'jwt'] as const);
+
+    const endpoint1 = factory
+      .post('/admin/users')
+      .authorizer('iam')
+      .body(z.object({ name: z.string() }))
+      .handle(async () => ({ success: true }));
+
+    const endpoint2 = factory
+      .get('/api/users')
+      .authorizer('jwt')
+      .handle(async () => ({ users: [] }));
+
+    expect(endpoint1.authorizer).toEqual({ name: 'iam' });
+    expect(endpoint2.authorizer).toEqual({ name: 'jwt' });
+  });
+
+  it('should throw error when using non-existent authorizer', () => {
+    const factory = new EndpointFactory().authorizers(['iam', 'jwt'] as const);
+
+    expect(() => {
+      factory
+        .post('/users')
+        // @ts-expect-error - testing invalid authorizer
+        .authorizer('invalid')
+        .handle(async () => ({ success: true }));
+    }).toThrow('Authorizer "invalid" not found in available authorizers: iam, jwt');
+  });
+
+  it('should allow endpoints without authorizers', () => {
+    const factory = new EndpointFactory().authorizers(['iam', 'jwt'] as const);
+
+    const endpoint = factory.get('/public').handle(async () => ({ success: true }));
+
+    expect(endpoint.authorizer).toBeUndefined();
+  });
+
+  it('should preserve authorizers when chaining factory methods', () => {
+    const factory = new EndpointFactory()
+      .authorizers(['iam', 'jwt', 'api-key'] as const)
+      .route('/api/v1');
+
+    const endpoint = factory
+      .get('/protected')
+      .authorizer('jwt')
+      .handle(async () => ({ data: 'protected' }));
+
+    expect(endpoint.authorizer).toEqual({ name: 'jwt' });
+    expect(endpoint.route).toBe('/api/v1/protected');
+  });
+
+  it('should work with services and authorizers together', () => {
+    const dbService = {
+      serviceName: 'database' as const,
+      register: async () => ({ query: async () => [] }),
+    };
+
+    const factory = new EndpointFactory()
+      .services([dbService])
+      .authorizers(['iam'] as const);
+
+    const endpoint = factory
+      .post('/users')
+      .authorizer('iam')
+      .body(z.object({ name: z.string() }))
+      .handle(async ({ body, services }) => {
+        await services.database.query();
+        return { name: body.name };
+      });
+
+    expect(endpoint.authorizer).toEqual({ name: 'iam' });
+  });
+
+  it('should maintain type safety with authorizer names', () => {
+    const factory = new EndpointFactory().authorizers(['iam', 'jwt'] as const);
+
+    // This should compile with valid authorizer
+    factory.get('/test1').authorizer('iam').handle(async () => ({}));
+
+    // This should compile with valid authorizer
+    factory.get('/test2').authorizer('jwt').handle(async () => ({}));
+
+    // This should not compile with invalid authorizer (tested via TypeScript)
+    // factory.get('/test3').authorizer('invalid').handle(async () => ({}));
+  });
+
+  it('should allow creating endpoints without calling authorizer() method', () => {
+    const factory = new EndpointFactory().authorizers(['iam'] as const);
+
+    const endpoint1 = factory
+      .get('/public')
+      .handle(async () => ({ public: true }));
+
+    const endpoint2 = factory
+      .get('/protected')
+      .authorizer('iam')
+      .handle(async () => ({ protected: true }));
+
+    expect(endpoint1.authorizer).toBeUndefined();
+    expect(endpoint2.authorizer).toEqual({ name: 'iam' });
+  });
+
+  it('should work with nested routes', () => {
+    const apiFactory = new EndpointFactory()
+      .authorizers(['iam', 'jwt'] as const)
+      .route('/api');
+
+    const v1Factory = apiFactory.route('/v1');
+    const adminFactory = v1Factory.route('/admin');
+
+    const endpoint = adminFactory
+      .delete('/users/:id')
+      .authorizer('iam')
+      .params(z.object({ id: z.string() }))
+      .handle(async () => ({ deleted: true }));
+
+    expect(endpoint.route).toBe('/api/v1/admin/users/:id');
+    expect(endpoint.authorizer).toEqual({ name: 'iam' });
+  });
+
+  it('should work with all HTTP methods', () => {
+    const factory = new EndpointFactory().authorizers(['jwt'] as const);
+
+    const getEndpoint = factory.get('/users').authorizer('jwt').handle(async () => ({ users: [] }));
+    const postEndpoint = factory.post('/users').authorizer('jwt').handle(async () => ({ id: '1' }));
+    const putEndpoint = factory.put('/users/:id').authorizer('jwt').handle(async () => ({ updated: true }));
+    const patchEndpoint = factory.patch('/users/:id').authorizer('jwt').handle(async () => ({ patched: true }));
+    const deleteEndpoint = factory.delete('/users/:id').authorizer('jwt').handle(async () => ({ deleted: true }));
+    const optionsEndpoint = factory.options('/users').authorizer('jwt').handle(async () => ({}));
+
+    expect(getEndpoint.authorizer).toEqual({ name: 'jwt' });
+    expect(postEndpoint.authorizer).toEqual({ name: 'jwt' });
+    expect(putEndpoint.authorizer).toEqual({ name: 'jwt' });
+    expect(patchEndpoint.authorizer).toEqual({ name: 'jwt' });
+    expect(deleteEndpoint.authorizer).toEqual({ name: 'jwt' });
+    expect(optionsEndpoint.authorizer).toEqual({ name: 'jwt' });
+  });
+
+  it('should work with output schemas', () => {
+    const factory = new EndpointFactory().authorizers(['iam'] as const);
+
+    const outputSchema = z.object({
+      id: z.string(),
+      name: z.string(),
+    });
+
+    const endpoint = factory
+      .get('/user')
+      .authorizer('iam')
+      .output(outputSchema)
+      .handle(async () => ({
+        id: '123',
+        name: 'John Doe',
+      }));
+
+    expect(endpoint.authorizer).toEqual({ name: 'iam' });
+    expect(endpoint.outputSchema).toBe(outputSchema);
+  });
+
+  it('should not throw error when no authorizers are configured', () => {
+    const factory = new EndpointFactory();
+
+    const endpoint = factory
+      .get('/test')
+      .handle(async () => ({ success: true }));
+
+    expect(endpoint.authorizer).toBeUndefined();
+  });
+
+  it('should handle multiple authorizers with similar names', () => {
+    const factory = new EndpointFactory().authorizers([
+      'jwt-user',
+      'jwt-admin',
+      'jwt',
+    ] as const);
+
+    const endpoint1 = factory.get('/user').authorizer('jwt-user').handle(async () => ({}));
+    const endpoint2 = factory.get('/admin').authorizer('jwt-admin').handle(async () => ({}));
+    const endpoint3 = factory.get('/api').authorizer('jwt').handle(async () => ({}));
+
+    expect(endpoint1.authorizer).toEqual({ name: 'jwt-user' });
+    expect(endpoint2.authorizer).toEqual({ name: 'jwt-admin' });
+    expect(endpoint3.authorizer).toEqual({ name: 'jwt' });
+  });
+
+  it('should support "none" to explicitly mark endpoint as having no authorizer', () => {
+    const factory = new EndpointFactory().authorizers(['iam', 'jwt'] as const);
+
+    const endpoint = factory
+      .get('/public')
+      .authorizer('none')
+      .handle(async () => ({ public: true }));
+
+    expect(endpoint.authorizer).toBeUndefined();
+  });
+
+  it('should allow "none" to override default authorizer from factory', () => {
+    const factory = new EndpointFactory().authorizers(['iam', 'jwt'] as const);
+
+    // In the future, if we add default authorizer support at factory level,
+    // 'none' should override it
+    const endpoint = factory
+      .post('/public/signup')
+      .authorizer('none')
+      .body(z.object({ email: z.string() }))
+      .handle(async () => ({ success: true }));
+
+    expect(endpoint.authorizer).toBeUndefined();
+  });
+
+  it('should allow "none" even when no authorizers are configured', () => {
+    const factory = new EndpointFactory();
+
+    const endpoint = factory
+      .get('/test')
+      .authorizer('none')
+      .handle(async () => ({ test: true }));
+
+    expect(endpoint.authorizer).toBeUndefined();
+  });
+
+  it('should work with "none" in combination with other endpoint methods', () => {
+    const factory = new EndpointFactory().authorizers(['iam'] as const);
+
+    const endpoint = factory
+      .post('/public/contact')
+      .authorizer('none')
+      .body(z.object({ message: z.string() }))
+      .output(z.object({ sent: z.boolean() }))
+      .description('Public contact form')
+      .tags(['public', 'contact'])
+      .handle(async () => ({ sent: true }));
+
+    expect(endpoint.authorizer).toBeUndefined();
+    expect(endpoint.description).toBe('Public contact form');
+    expect(endpoint.tags).toEqual(['public', 'contact']);
+  });
+});

package/src/endpoints/__tests__/EndpointFactory.reference-audit.spec.ts

@@ -0,0 +1,190 @@
+import { describe, expect, it } from 'vitest';
+import { ConsoleLogger } from '@geekmidas/logger/console';
+import { EndpointFactory } from '../EndpointFactory';
+import type { Service } from '@geekmidas/services';
+
+const ServiceA = {
+  serviceName: 'a' as const,
+  async register() {
+    return { test: () => 'a' };
+  },
+} satisfies Service<'a', any>;
+
+const ServiceB = {
+  serviceName: 'b' as const,
+  async register() {
+    return { test: () => 'b' };
+  },
+} satisfies Service<'b', any>;
+
+describe('EndpointFactory - Reference Sharing Audit', () => {
+  describe('services array', () => {
+    it('should not share services array references between builders', () => {
+      const factory = new EndpointFactory().services([ServiceA, ServiceB]);
+
+      const builder1 = factory.post('/a');
+      const builder2 = factory.post('/b');
+
+      // Should not be the same reference
+      expect((builder1 as any)._services === (builder2 as any)._services).toBe(
+        false,
+      );
+
+      // But should have same content
+      expect((builder1 as any)._services).toEqual([ServiceA, ServiceB]);
+      expect((builder2 as any)._services).toEqual([ServiceA, ServiceB]);
+    });
+
+    it('should not mutate factory services when builder adds services', () => {
+      const factory = new EndpointFactory().services([ServiceA]);
+
+      const builder = factory.post('/test');
+      const originalServices = (factory as any).defaultServices;
+
+      // Builder adds more services
+      builder.services([ServiceB]);
+
+      // Factory's defaultServices should be unchanged
+      expect((factory as any).defaultServices).toEqual(originalServices);
+      expect((factory as any).defaultServices.length).toBe(1);
+    });
+  });
+
+  describe('events array', () => {
+    it('should not share events array references between builders', () => {
+      const factory = new EndpointFactory();
+
+      const builder1 = factory.post('/a');
+      const builder2 = factory.post('/b');
+
+      // Each builder should have its own events array
+      expect((builder1 as any)._events === (builder2 as any)._events).toBe(
+        false,
+      );
+      expect((builder1 as any)._events).toEqual([]);
+      expect((builder2 as any)._events).toEqual([]);
+    });
+
+    it('should not share events between builders even after adding events', () => {
+      const factory = new EndpointFactory();
+
+      const builder1 = factory.post('/a');
+      const builder2 = factory.post('/b');
+
+      // Add event to builder1
+      const mockEvent: any = { type: 'test', map: () => ({}) };
+      (builder1 as any)._events.push(mockEvent);
+
+      // builder2 should not have the event
+      expect((builder1 as any)._events.length).toBe(1);
+      expect((builder2 as any)._events.length).toBe(0);
+    });
+  });
+
+  describe('schemas object', () => {
+    it('should not share schemas object references between builders', () => {
+      const factory = new EndpointFactory();
+
+      const builder1 = factory.post('/a');
+      const builder2 = factory.post('/b');
+
+      // Each builder should have its own schemas object
+      expect((builder1 as any).schemas === (builder2 as any).schemas).toBe(
+        false,
+      );
+    });
+
+    it('should not share schemas between builders after setting schemas', () => {
+      const factory = new EndpointFactory();
+      const bodySchema: any = { '~standard': { validate: () => ({}) } };
+
+      const builder1 = factory.post('/a').body(bodySchema);
+      const builder2 = factory.post('/b');
+
+      // builder1 should have body schema, builder2 should not
+      expect((builder1 as any).schemas.body).toBeDefined();
+      expect((builder2 as any).schemas.body).toBeUndefined();
+    });
+  });
+
+  describe('logger (intentionally shared)', () => {
+    it('should share logger references between builders (by design)', () => {
+      const logger = new ConsoleLogger({ app: 'test' });
+      const factory = new EndpointFactory().logger(logger);
+
+      const builder1 = factory.post('/a');
+      const builder2 = factory.post('/b');
+
+      // Logger should be the same reference (it's a singleton service)
+      expect((builder1 as any)._logger === (builder2 as any)._logger).toBe(
+        true,
+      );
+      expect((builder1 as any)._logger).toBe(logger);
+    });
+  });
+
+  describe('authorize and session functions', () => {
+    it('should share authorize function reference (by design)', () => {
+      const authFn = async () => true;
+      const factory = new EndpointFactory().authorize(authFn);
+
+      const builder1 = factory.post('/a');
+      const builder2 = factory.post('/b');
+
+      // Function should be the same reference
+      expect((builder1 as any)._authorize === (builder2 as any)._authorize).toBe(
+        true,
+      );
+      expect((builder1 as any)._authorize).toBe(authFn);
+    });
+
+    it('should share session extractor function reference (by design)', () => {
+      const sessionFn = async () => ({ userId: '123' });
+      const factory = new EndpointFactory().session(sessionFn);
+
+      const builder1 = factory.post('/a');
+      const builder2 = factory.post('/b');
+
+      // Function should be the same reference
+      expect((builder1 as any)._getSession === (builder2 as any)._getSession).toBe(
+        true,
+      );
+      expect((builder1 as any)._getSession).toBe(sessionFn);
+    });
+  });
+
+  describe('complex nested factory chains', () => {
+    it('should maintain proper isolation through multiple factory layers', () => {
+      // Create base router
+      const base = new EndpointFactory().services([ServiceA]);
+
+      // Create auth router from base
+      const authRouter = base.authorize(async () => true);
+
+      // Create API v1 router from auth router
+      const v1Router = authRouter.route('/v1').services([ServiceB]);
+
+      // Create endpoints from different routers
+      const ep1 = base.get('/test').handle(() => ({}));
+      const ep2 = authRouter.get('/test').handle(() => ({}));
+      const ep3 = v1Router.get('/test').handle(() => ({}));
+
+      // Verify service isolation
+      expect(ep1.services.map((s) => s.serviceName)).toEqual(['a']);
+      expect(ep2.services.map((s) => s.serviceName)).toEqual(['a']);
+      expect(ep3.services.map((s) => s.serviceName)).toEqual(['b', 'a']);
+
+      // Verify they don't share internal arrays
+      const builder1 = base.get('/x');
+      const builder2 = authRouter.get('/x');
+      const builder3 = v1Router.get('/x');
+
+      expect((builder1 as any)._services === (builder2 as any)._services).toBe(
+        false,
+      );
+      expect((builder2 as any)._services === (builder3 as any)._services).toBe(
+        false,
+      );
+    });
+  });
+});

package/src/endpoints/__tests__/EndpointFactory.state-isolation.spec.ts

@@ -0,0 +1,155 @@
+import { describe, expect, it } from 'vitest';
+import { EndpointFactory } from '../EndpointFactory';
+import type { Service } from '@geekmidas/services';
+
+const CacheService = {
+  serviceName: 'cache' as const,
+  async register() {
+    return { get: () => 'cached' };
+  },
+} satisfies Service<'cache', any>;
+
+const DatabaseService = {
+  serviceName: 'database' as const,
+  async register() {
+    return { query: () => 'result' };
+  },
+} satisfies Service<'database', any>;
+
+describe('EndpointFactory - State Isolation', () => {
+  it('should create independent endpoints with sequential factory.services() calls', () => {
+    const factory = new EndpointFactory();
+
+    const endpoint1 = factory
+      .services([CacheService, DatabaseService])
+      .post('/user')
+      .handle(() => ({}));
+
+    const endpoint2 = factory.services([CacheService]).get('/user').handle(() => ({}));
+
+    expect(endpoint1.services.map((s) => s.serviceName)).toEqual([
+      'cache',
+      'database',
+    ]);
+    expect(endpoint2.services.map((s) => s.serviceName)).toEqual(['cache']);
+  });
+
+  it('should create independent builders from reused factory instance', () => {
+    const factory = new EndpointFactory().services([
+      CacheService,
+      DatabaseService,
+    ]);
+
+    const builder1 = factory.post('/users');
+    const builder2 = factory.get('/users');
+
+    // Both should have the factory's default services
+    expect((builder1 as any)._services.map((s: any) => s.serviceName)).toEqual([
+      'cache',
+      'database',
+    ]);
+    expect((builder2 as any)._services.map((s: any) => s.serviceName)).toEqual([
+      'cache',
+      'database',
+    ]);
+
+    // But they should not share the same array reference
+    expect((builder1 as any)._services === (builder2 as any)._services).toBe(
+      false,
+    );
+  });
+
+  it('should not leak services between independent builder chains', () => {
+    const factory = new EndpointFactory();
+
+    const builder1 = factory.post('/api1').services([CacheService]);
+    const builder2 = factory.post('/api2').services([DatabaseService]);
+
+    expect((builder1 as any)._services.map((s: any) => s.serviceName)).toEqual([
+      'cache',
+    ]);
+    expect((builder2 as any)._services.map((s: any) => s.serviceName)).toEqual([
+      'database',
+    ]);
+  });
+
+  it('should allow builder to add services without affecting other builders', () => {
+    const factory = new EndpointFactory().services([CacheService]);
+
+    const endpoint1 = factory
+      .post('/test')
+      .services([DatabaseService])
+      .handle(() => ({}));
+
+    const endpoint2 = factory.get('/test').handle(() => ({}));
+
+    expect(endpoint1.services.map((s) => s.serviceName)).toEqual([
+      'cache',
+      'database',
+    ]);
+    expect(endpoint2.services.map((s) => s.serviceName)).toEqual(['cache']);
+  });
+
+  it('should support base router pattern with extended services', () => {
+    // Create a base router with default services
+    const r = new EndpointFactory().services([
+      CacheService,
+      DatabaseService,
+    ]);
+
+    // Create endpoint with additional service
+    const getUsers = r.services([CacheService]).get('/users').handle(() => ({}));
+
+    // Create endpoint with just base services
+    const createUser = r.post('/users').handle(() => ({}));
+
+    // getUsers should have additional service (but deduplicated)
+    expect(getUsers.services.map((s) => s.serviceName)).toEqual([
+      'cache',
+      'database',
+    ]);
+
+    // createUser should only have base services
+    expect(createUser.services.map((s) => s.serviceName)).toEqual([
+      'cache',
+      'database',
+    ]);
+  });
+
+  it('should support base router pattern with truly additional services', () => {
+    const AdditionalService = {
+      serviceName: 'additional' as const,
+      async register() {
+        return { process: () => 'processed' };
+      },
+    } satisfies Service<'additional', any>;
+
+    // Create a base router with default services
+    const r = new EndpointFactory().services([
+      CacheService,
+      DatabaseService,
+    ]);
+
+    // Create endpoint with additional service
+    const getUsers = r
+      .services([AdditionalService])
+      .get('/users')
+      .handle(() => ({}));
+
+    // Create endpoint with just base services
+    const createUser = r.post('/users').handle(() => ({}));
+
+    // getUsers should have all three services
+    expect(getUsers.services.map((s) => s.serviceName)).toEqual([
+      'additional',
+      'cache',
+      'database',
+    ]);
+
+    // createUser should only have base services
+    expect(createUser.services.map((s) => s.serviceName)).toEqual([
+      'cache',
+      'database',
+    ]);
+  });
+});