@geekmidas/constructs 0.0.7 → 0.0.10

package/src/endpoints/__tests__/Endpoint.manifest.spec.ts

@@ -0,0 +1,176 @@
+import { describe, expect, it } from 'vitest';
+import { Endpoint } from '../Endpoint';
+import { SuccessStatus } from '../Endpoint';
+import { z } from 'zod';
+
+describe('Endpoint manifest fields', () => {
+  it('should store timeout and memorySize', () => {
+    const endpoint = new Endpoint({
+      route: '/users/:id',
+      method: 'GET',
+      fn: async () => ({ id: '123' }),
+      authorize: undefined,
+      description: 'Get user by ID',
+      timeout: 30000,
+      memorySize: 512,
+      input: undefined,
+      output: undefined,
+      services: [],
+      logger: {} as any,
+      getSession: undefined,
+      rateLimit: undefined,
+      status: SuccessStatus.OK,
+    });
+
+    expect(endpoint.timeout).toBe(30000);
+    expect(endpoint.memorySize).toBe(512);
+  });
+
+  it('should store authorizer information', () => {
+    const endpoint = new Endpoint({
+      route: '/admin/users',
+      method: 'POST',
+      fn: async () => ({ success: true }),
+      authorize: undefined,
+      description: 'Create admin user',
+      timeout: undefined,
+      memorySize: undefined,
+      input: undefined,
+      output: undefined,
+      services: [],
+      logger: {} as any,
+      getSession: undefined,
+      rateLimit: undefined,
+      status: SuccessStatus.Created,
+      authorizer: {
+        name: 'iam',
+        type: 'AWS_IAM',
+        description: 'IAM-based authorizer',
+      },
+    });
+
+    expect(endpoint.authorizer).toEqual({
+      name: 'iam',
+      type: 'AWS_IAM',
+      description: 'IAM-based authorizer',
+    });
+  });
+
+  it('should have undefined authorizer when not provided', () => {
+    const endpoint = new Endpoint({
+      route: '/public',
+      method: 'GET',
+      fn: async () => ({ data: 'public' }),
+      authorize: undefined,
+      description: 'Public endpoint',
+      timeout: undefined,
+      memorySize: undefined,
+      input: undefined,
+      output: undefined,
+      services: [],
+      logger: {} as any,
+      getSession: undefined,
+      rateLimit: undefined,
+      status: SuccessStatus.OK,
+    });
+
+    expect(endpoint.authorizer).toBeUndefined();
+  });
+
+  it('should store all manifest fields together', () => {
+    const bodySchema = z.object({ name: z.string() });
+    const outputSchema = z.object({ id: z.string(), name: z.string() });
+
+    const endpoint = new Endpoint({
+      route: '/api/v1/users',
+      method: 'POST',
+      fn: async () => ({ id: '123', name: 'Test User' }),
+      authorize: undefined,
+      description: 'Create a new user',
+      tags: ['users', 'admin'],
+      timeout: 15000,
+      memorySize: 256,
+      input: { body: bodySchema },
+      output: outputSchema,
+      services: [],
+      logger: {} as any,
+      getSession: undefined,
+      rateLimit: undefined,
+      status: SuccessStatus.Created,
+      authorizer: {
+        name: 'jwt-auth0',
+        type: 'JWT',
+        description: 'Auth0 JWT authorizer',
+        metadata: {
+          audience: 'https://api.example.com',
+          issuer: 'https://example.auth0.com/',
+        },
+      },
+    });
+
+    expect(endpoint.route).toBe('/api/v1/users');
+    expect(endpoint.method).toBe('POST');
+    expect(endpoint.description).toBe('Create a new user');
+    expect(endpoint.tags).toEqual(['users', 'admin']);
+    expect(endpoint.timeout).toBe(15000);
+    expect(endpoint.memorySize).toBe(256);
+    expect(endpoint.status).toBe(SuccessStatus.Created);
+    expect(endpoint.authorizer).toEqual({
+      name: 'jwt-auth0',
+      type: 'JWT',
+      description: 'Auth0 JWT authorizer',
+      metadata: {
+        audience: 'https://api.example.com',
+        issuer: 'https://example.auth0.com/',
+      },
+    });
+  });
+
+  it('should preserve authorizer metadata with minimal fields', () => {
+    const endpoint = new Endpoint({
+      route: '/protected',
+      method: 'GET',
+      fn: async () => ({ data: 'secret' }),
+      authorize: undefined,
+      description: undefined,
+      timeout: undefined,
+      memorySize: undefined,
+      input: undefined,
+      output: undefined,
+      services: [],
+      logger: {} as any,
+      getSession: undefined,
+      rateLimit: undefined,
+      status: SuccessStatus.OK,
+      authorizer: {
+        name: 'custom',
+      },
+    });
+
+    expect(endpoint.authorizer).toEqual({ name: 'custom' });
+  });
+
+  it('should handle default timeout and memorySize values', () => {
+    const endpoint = new Endpoint({
+      route: '/default',
+      method: 'GET',
+      fn: async () => ({ data: 'default' }),
+      authorize: undefined,
+      description: undefined,
+      timeout: undefined,
+      memorySize: undefined,
+      input: undefined,
+      output: undefined,
+      services: [],
+      logger: {} as any,
+      getSession: undefined,
+      rateLimit: undefined,
+      status: SuccessStatus.OK,
+    });
+
+    // Default timeout is 30000ms (30 seconds)
+    expect(endpoint.timeout).toBe(30000);
+    // Default memorySize is undefined
+    expect(endpoint.memorySize).toBeUndefined();
+  });
+});

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,
+      );
+    });
+  });
+});