@geekmidas/constructs 0.0.1

package/src/endpoints/__tests__/TestEndpointAdaptor.spec.ts

@@ -0,0 +1,236 @@
+import { UnprocessableEntityError } from '@geekmidas/errors';
+import { ConsoleLogger } from '@geekmidas/logger/console';
+import { describe, expect, it, vi } from 'vitest';
+import { z } from 'zod';
+import { e } from '../EndpointFactory';
+import { TestEndpointAdaptor } from '../TestEndpointAdaptor';
+
+describe('TestEndpointAdaptor', () => {
+  const mockServices = {};
+  const logger = new ConsoleLogger();
+
+  describe('request', () => {
+    it('should handle simple endpoint without schemas', async () => {
+      const endpoint = e
+        .get('/test')
+        .output(z.object({ message: z.string() }))
+        .handle(() => ({ message: 'Hello World' }));
+
+      const adapter = new TestEndpointAdaptor(endpoint);
+
+      const result = await adapter.request({
+        services: mockServices,
+        headers: { host: 'example.com' },
+      });
+
+      expect(result).toEqual({ message: 'Hello World' });
+    });
+
+    it('should handle endpoint with body schema', async () => {
+      const endpoint = e
+        .post('/users')
+        .body(z.object({ name: z.string(), email: z.string().email() }))
+        .output(z.object({ id: z.string(), name: z.string() }))
+        .handle(async ({ body }) => ({
+          id: 'user-123',
+          name: body.name,
+        }));
+
+      const adapter = new TestEndpointAdaptor(endpoint);
+
+      const result = await adapter.request({
+        body: { name: 'John Doe', email: 'john@example.com' },
+        services: mockServices,
+        headers: { host: 'example.com', 'content-type': 'application/json' },
+      });
+
+      expect(result).toEqual({ id: 'user-123', name: 'John Doe' });
+    });
+
+    it('should handle endpoint with params schema', async () => {
+      const endpoint = e
+        .get('/users/:id')
+        .params(z.object({ id: z.string() }))
+        .output(z.object({ id: z.string(), found: z.boolean() }))
+        .handle(async ({ params }) => ({
+          id: params.id,
+          found: true,
+        }));
+
+      const adapter = new TestEndpointAdaptor(endpoint);
+
+      const result = await adapter.request({
+        params: { id: 'user-456' },
+        services: mockServices,
+        headers: { host: 'example.com' },
+      });
+
+      expect(result).toEqual({ id: 'user-456', found: true });
+    });
+
+    it('should handle endpoint with query schema', async () => {
+      const endpoint = e
+        .get('/search')
+        .query(z.object({ q: z.string(), page: z.coerce.number().default(1) }))
+        .output(z.object({ query: z.string(), page: z.number() }))
+        .handle(async ({ query }) => ({
+          query: query.q,
+          page: query.page,
+        }));
+
+      const adapter = new TestEndpointAdaptor(endpoint);
+
+      const result = await adapter.request({
+        query: { q: 'test search', page: 2 },
+        services: mockServices,
+        headers: { host: 'example.com' },
+      });
+
+      expect(result).toEqual({ query: 'test search', page: 2 });
+    });
+
+    it('should handle endpoint with all schemas', async () => {
+      const endpoint = e
+        .put('/users/:id')
+        .params(z.object({ id: z.string() }))
+        .body(z.object({ name: z.string(), email: z.string().email() }))
+        .query(z.object({ notify: z.coerce.boolean().default(false) }))
+        .output(
+          z.object({
+            id: z.string(),
+            updated: z.boolean(),
+            notified: z.boolean(),
+          }),
+        )
+        .handle(async ({ params, body, query }) => ({
+          id: params.id,
+          updated: true,
+          notified: query.notify,
+        }));
+
+      const adapter = new TestEndpointAdaptor(endpoint);
+
+      const result = await adapter.request({
+        body: { name: 'Jane Doe', email: 'jane@example.com' },
+        query: { notify: true },
+        params: { id: 'user-789' },
+        services: mockServices,
+        headers: { host: 'example.com' },
+      });
+
+      expect(result).toEqual({
+        id: 'user-789',
+        updated: true,
+        notified: true,
+      });
+    });
+
+    it('should throw validation error for invalid body', async () => {
+      const endpoint = e
+        .post('/users')
+        .body(z.object({ name: z.string(), age: z.number().min(18) }))
+        .handle(async ({ body }) => ({ id: '123' }));
+
+      const adapter = new TestEndpointAdaptor(endpoint);
+
+      await expect(
+        adapter.request({
+          body: { name: 'John', age: 15 },
+          services: mockServices,
+          headers: { host: 'example.com' },
+        }),
+      ).rejects.toThrow(UnprocessableEntityError);
+    });
+
+    it('should handle headers correctly', async () => {
+      const endpoint = e
+        .get('/headers')
+        .output(z.object({ auth: z.string().optional(), host: z.string() }))
+        .handle(async ({ header }) => ({
+          auth: header('authorization'),
+          host: header('host') || 'unknown',
+        }));
+
+      const adapter = new TestEndpointAdaptor(endpoint);
+
+      const result = await adapter.request({
+        services: mockServices,
+        headers: {
+          host: 'api.example.com',
+          authorization: 'Bearer token123',
+          'Content-Type': 'application/json',
+        },
+      });
+
+      expect(result).toEqual({
+        auth: 'Bearer token123',
+        host: 'api.example.com',
+      });
+    });
+
+    it('should handle session correctly', async () => {
+      const endpoint = e
+        .get('/profile')
+        .output(z.object({ userId: z.string() }))
+        .handle(async ({ session }) => ({
+          userId: (session as any).userId,
+        }));
+
+      // Mock getSession
+      endpoint.getSession = vi.fn().mockResolvedValue({ userId: 'user-123' });
+
+      const adapter = new TestEndpointAdaptor(endpoint);
+
+      const result = await adapter.request({
+        services: mockServices,
+        headers: { host: 'example.com' },
+      });
+
+      expect(result).toEqual({ userId: 'user-123' });
+      expect(endpoint.getSession).toHaveBeenCalledWith({
+        logger: expect.any(ConsoleLogger),
+        services: mockServices,
+        header: expect.any(Function),
+      });
+    });
+
+    it('should validate output schema', async () => {
+      const endpoint = e
+        .get('/invalid')
+        .output(z.object({ id: z.string(), count: z.number() }))
+        .handle(() => ({ id: '123', count: 'not-a-number' as any }));
+
+      const adapter = new TestEndpointAdaptor(endpoint);
+
+      await expect(
+        adapter.request({
+          services: mockServices,
+          headers: { host: 'example.com' },
+        }),
+      ).rejects.toThrow(UnprocessableEntityError);
+    });
+
+    it('should handle case-insensitive headers', async () => {
+      const endpoint = e
+        .get('/headers-case')
+        .output(z.object({ contentType: z.string().optional() }))
+        .handle(async ({ header }) => ({
+          contentType: header('CONTENT-TYPE'),
+        }));
+
+      const adapter = new TestEndpointAdaptor(endpoint);
+
+      const result = await adapter.request({
+        services: mockServices,
+        headers: {
+          host: 'example.com',
+          'content-type': 'application/json',
+        },
+      });
+
+      expect(result).toEqual({
+        contentType: 'application/json',
+      });
+    });
+  });
+});

package/src/endpoints/__tests__/__snapshots__/HonoEndpointAdaptor.spec.ts.snap

@@ -0,0 +1,54 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`HonoEndpointAdaptor > addRoute > should return 422 for invalid body 1`] = `
+[
+  {
+    "code": "too_small",
+    "inclusive": true,
+    "message": "Too small: expected string to have >=3 characters",
+    "minimum": 3,
+    "origin": "string",
+    "path": [
+      "name",
+    ],
+  },
+  {
+    "code": "invalid_type",
+    "expected": "number",
+    "message": "Invalid input: expected number, received string",
+    "path": [
+      "age",
+    ],
+  },
+]
+`;
+
+exports[`HonoEndpointAdaptor > addRoute > should return 422 for invalid path parameters 1`] = `
+[
+  {
+    "code": "invalid_format",
+    "format": "uuid",
+    "message": "Invalid UUID",
+    "origin": "string",
+    "path": [
+      "id",
+    ],
+    "pattern": "/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/",
+  },
+]
+`;
+
+exports[`HonoEndpointAdaptor > addRoute > should return 422 for invalid query parameters 1`] = `
+[
+  {
+    "code": "invalid_format",
+    "format": "regex",
+    "message": "Invalid string: must match pattern /^\\d+$/",
+    "origin": "string",
+    "path": [
+      "page",
+    ],
+    "pattern": "/^\\d+$/",
+  },
+]
+`;

package/src/endpoints/__tests__/endpoint-types.test.ts

@@ -0,0 +1,88 @@
+import { describe, expectTypeOf, it } from 'vitest';
+import { z } from 'zod';
+import { e } from '../EndpointFactory';
+
+describe('Endpoint type inference', () => {
+  it('should not include body/params/query when not defined', () => {
+    const endpoint = e.get('/test').handle((ctx) => {
+      expectTypeOf(ctx).toHaveProperty('services');
+      expectTypeOf(ctx).toHaveProperty('logger');
+      expectTypeOf(ctx).toHaveProperty('header');
+      expectTypeOf(ctx).toHaveProperty('session');
+
+      // These should NOT exist
+      expectTypeOf(ctx).not.toHaveProperty('body');
+      expectTypeOf(ctx).not.toHaveProperty('params');
+      expectTypeOf(ctx).not.toHaveProperty('query');
+
+      return { success: true };
+    });
+  });
+
+  it('should include body when defined', () => {
+    const endpoint = e
+      .post('/test')
+      .body(z.object({ name: z.string() }))
+      .handle((ctx) => {
+        expectTypeOf(ctx).toHaveProperty('body');
+        expectTypeOf(ctx.body).toEqualTypeOf<{ name: string }>();
+
+        // These should NOT exist
+        expectTypeOf(ctx).not.toHaveProperty('params');
+        expectTypeOf(ctx).not.toHaveProperty('query');
+
+        return { success: true };
+      });
+  });
+
+  it('should include params when defined', () => {
+    const endpoint = e
+      .get('/test/:id')
+      .params(z.object({ id: z.string() }))
+      .handle((ctx) => {
+        expectTypeOf(ctx).toHaveProperty('params');
+        expectTypeOf(ctx.params).toEqualTypeOf<{ id: string }>();
+
+        // These should NOT exist
+        expectTypeOf(ctx).not.toHaveProperty('body');
+        expectTypeOf(ctx).not.toHaveProperty('query');
+
+        return { success: true };
+      });
+  });
+
+  it('should include query when defined', () => {
+    const endpoint = e
+      .get('/test')
+      .query(z.object({ filter: z.string() }))
+      .handle((ctx) => {
+        expectTypeOf(ctx).toHaveProperty('query');
+        expectTypeOf(ctx.query).toEqualTypeOf<{ filter: string }>();
+
+        // These should NOT exist
+        expectTypeOf(ctx).not.toHaveProperty('body');
+        expectTypeOf(ctx).not.toHaveProperty('params');
+
+        return { success: true };
+      });
+  });
+
+  it('should include all properties when all are defined', () => {
+    const endpoint = e
+      .post('/test/:id')
+      .body(z.object({ name: z.string() }))
+      .params(z.object({ id: z.string() }))
+      .query(z.object({ filter: z.string() }))
+      .handle((ctx) => {
+        expectTypeOf(ctx).toHaveProperty('body');
+        expectTypeOf(ctx).toHaveProperty('params');
+        expectTypeOf(ctx).toHaveProperty('query');
+
+        expectTypeOf(ctx.body).toEqualTypeOf<{ name: string }>();
+        expectTypeOf(ctx.params).toEqualTypeOf<{ id: string }>();
+        expectTypeOf(ctx.query).toEqualTypeOf<{ filter: string }>();
+
+        return { success: true };
+      });
+  });
+});

package/src/endpoints/helpers.ts

@@ -0,0 +1,99 @@
+import path from 'node:path';
+import fg from 'fast-glob';
+import { Endpoint } from './Endpoint';
+
+import type { Service } from '@geekmidas/services';
+import type { HttpMethod } from '../types';
+
+// Re-export utility functions
+
+/**
+ * Recursively finds the project root directory by looking for lock files.
+ * Traverses up the directory tree until it finds a package manager lock file.
+ *
+ * @param cwd - The current working directory to start searching from
+ * @returns Promise resolving to the absolute path of the project root
+ *
+ * @example
+ * ```typescript
+ * const projectRoot = await getProjectRoot(process.cwd());
+ * console.log(`Project root: ${projectRoot}`);
+ * // Output: Project root: /Users/user/my-project
+ * ```
+ */
+export async function getProjectRoot(cwd: string): Promise<string> {
+  if (cwd === '/') {
+    return cwd;
+  }
+
+  const stream = fg.stream(
+    ['yarn.lock', 'pnpm-lock.yaml', 'package-lock.json', 'deno.lock'],
+    { dot: true, cwd },
+  );
+
+  let isRoot = false;
+
+  for await (const _ of stream) {
+    isRoot = true;
+    break;
+  }
+
+  if (isRoot) {
+    return cwd;
+  }
+
+  return getProjectRoot(path.resolve(cwd, '..'));
+}
+
+/**
+ * Discovers and imports all Endpoint instances from the specified route patterns.
+ * Uses fast-glob to find files matching the patterns and extracts exported Endpoints.
+ *
+ * @template TServices - Array of service types used by the endpoints
+ * @param routes - Array of glob patterns to match route files (e.g., ['src/routes/*.ts'])
+ * @param cwd - The current working directory to resolve paths from
+ * @returns Promise resolving to an array of Endpoint instances found in the matched files
+ *
+ * @example
+ * ```typescript
+ * // Find all endpoints in the routes directory
+ * const endpoints = await getEndpointsFromRoutes(
+ *   ['src/routes/**\/*.ts'],
+ *   process.cwd()
+ * );
+ *
+ * // Register endpoints with your server
+ * for (const endpoint of endpoints) {
+ *   server.register(endpoint);
+ * }
+ * ```
+ *
+ * @remarks
+ * - Only exports that are valid Endpoint instances are included
+ * - Files are imported dynamically, so they must be valid ES modules
+ * - The function filters out non-Endpoint exports automatically
+ */
+export async function getEndpointsFromRoutes<TServices extends Service[]>(
+  routes: string[],
+  cwd: string,
+): Promise<Endpoint<string, HttpMethod, any, any, TServices>[]> {
+  const stream = fg.stream(routes, { cwd });
+
+  const endpoints: Endpoint<string, HttpMethod, any, any, TServices>[] = [];
+
+  for await (const f of stream) {
+    // Resolve the absolute path for the route file
+    const routePath = path.resolve(cwd, f.toString());
+    // Dynamically import the route module
+    const route = await import(routePath);
+
+    // Filter exported values to find only Endpoint instances
+    const handlers = Object.values(route).filter((value) => {
+      return Endpoint.isEndpoint(value);
+    }) as unknown as Endpoint<string, HttpMethod, any, any, TServices>[];
+
+    endpoints.push(...handlers);
+  }
+
+  return endpoints;
+}

package/src/endpoints/index.ts

@@ -0,0 +1,5 @@
+import { EndpointFactory } from './EndpointFactory';
+
+export { Endpoint, type EndpointOutput } from './Endpoint';
+
+export const e = new EndpointFactory();

package/src/endpoints/parseHonoQuery.ts

@@ -0,0 +1,51 @@
+import type { Context } from 'hono';
+
+/**
+ * Parse Hono query parameters to handle arrays and nested objects
+ * Hono provides c.req.queries() for arrays, but we need to handle dot notation for objects
+ */
+export function parseHonoQuery(c: Context): Record<string, any> {
+  const allParams = c.req.query();
+  const result: Record<string, any> = {};
+
+  // First, handle all query parameters
+  for (const [key, value] of Object.entries(allParams)) {
+    if (key.includes('.')) {
+      // Handle dot notation for objects
+      const parts = key.split('.');
+      let current = result;
+
+      // Navigate/create the nested structure
+      for (let i = 0; i < parts.length - 1; i++) {
+        const part = parts[i];
+        if (
+          !current[part] ||
+          typeof current[part] !== 'object' ||
+          Array.isArray(current[part])
+        ) {
+          current[part] = {};
+        }
+        current = current[part];
+      }
+
+      // Set the final value, checking for arrays in nested keys
+      const lastPart = parts[parts.length - 1];
+      const multipleValues = c.req.queries(key);
+      if (multipleValues && multipleValues.length > 1) {
+        current[lastPart] = multipleValues;
+      } else {
+        current[lastPart] = value;
+      }
+    } else {
+      // For regular keys, check if there are multiple values
+      const multipleValues = c.req.queries(key);
+      if (multipleValues && multipleValues.length > 1) {
+        result[key] = multipleValues;
+      } else {
+        result[key] = value;
+      }
+    }
+  }
+
+  return result;
+}

package/src/endpoints/parseQueryParams.ts

@@ -0,0 +1,51 @@
+/**
+ * Parse query parameters from a flat object into a nested structure
+ * Handles arrays (multiple values with same key) and objects (dot notation)
+ *
+ * @example
+ * parseQueryParams({ 'tags': ['a', 'b'], 'filter.name': 'john' })
+ * // Returns: { tags: ['a', 'b'], filter: { name: 'john' } }
+ */
+export function parseQueryParams(
+  queryParams: Record<string, string | string[] | undefined> | null,
+): Record<string, any> {
+  if (!queryParams) {
+    return {};
+  }
+
+  const result: Record<string, any> = {};
+
+  for (const [key, value] of Object.entries(queryParams)) {
+    if (value === undefined) {
+      continue;
+    }
+
+    // Check if the key contains dot notation
+    if (key.includes('.')) {
+      const parts = key.split('.');
+      let current = result;
+
+      // Navigate/create the nested structure
+      for (let i = 0; i < parts.length - 1; i++) {
+        const part = parts[i];
+        if (
+          !current[part] ||
+          typeof current[part] !== 'object' ||
+          Array.isArray(current[part])
+        ) {
+          current[part] = {};
+        }
+        current = current[part];
+      }
+
+      // Set the final value
+      const lastPart = parts[parts.length - 1];
+      current[lastPart] = value;
+    } else {
+      // Simple key, just assign the value
+      result[key] = value;
+    }
+  }
+
+  return result;
+}