@martel/calyx 1.7.0 → 1.9.0

package/src/openapi/swagger.module.ts

@@ -0,0 +1,326 @@
+import { CalyxApplication } from '../http/application.ts';
+
+export class DocumentBuilder {
+  private document: any = {
+    openapi: '3.0.0',
+    info: {
+      title: 'Calyx Application',
+      version: '1.0.0',
+      description: '',
+    },
+    paths: {},
+    components: {
+      schemas: {},
+      securitySchemes: {},
+    },
+  };
+
+  setTitle(title: string) {
+    this.document.info.title = title;
+    return this;
+  }
+
+  setVersion(version: string) {
+    this.document.info.version = version;
+    return this;
+  }
+
+  setDescription(description: string) {
+    this.document.info.description = description;
+    return this;
+  }
+
+  addBearerAuth(options: any = { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' }, name = 'bearer') {
+    this.document.components.securitySchemes[name] = options;
+    return this;
+  }
+
+  addBasicAuth(options: any = { type: 'http', scheme: 'basic' }, name = 'basic') {
+    this.document.components.securitySchemes[name] = options;
+    return this;
+  }
+
+  addOAuth2(options: any = { type: 'oauth2', flows: {} }, name = 'oauth2') {
+    this.document.components.securitySchemes[name] = options;
+    return this;
+  }
+
+  addSecurity(name: string, scheme: any) {
+    this.document.components.securitySchemes[name] = scheme;
+    return this;
+  }
+
+  build() {
+    return this.document;
+  }
+}
+
+export class SwaggerModule {
+  static createDocument(app: CalyxApplication, config: any): any {
+    const document = { ...config };
+    if (!document.paths) document.paths = {};
+    if (!document.components) document.components = {};
+    if (!document.components.schemas) document.components.schemas = {};
+    if (!document.components.securitySchemes) {
+      document.components.securitySchemes = config.components?.securitySchemes || {};
+    }
+
+    const routes = app.getRoutes();
+
+    function registerSchema(typeClass: any) {
+      if (!typeClass || typeof typeClass !== 'function') return;
+      const schemaName = typeClass.name;
+      if (document.components.schemas[schemaName]) return;
+
+      const props = Reflect.getMetadata('calyx:api_properties', typeClass) || [];
+      const schemaProps: Record<string, any> = {};
+      const requiredProps: string[] = [];
+
+      for (const p of props) {
+        let pType = 'string';
+        if (p.type) {
+          pType = p.type.name ? p.type.name.toLowerCase() : String(p.type).toLowerCase();
+        }
+        schemaProps[p.propertyKey] = {
+          type: pType === 'number' || pType === 'boolean' || pType === 'object' || pType === 'array' ? pType : 'string',
+          description: p.description,
+        };
+        if (p.required) {
+          requiredProps.push(p.propertyKey);
+        }
+      }
+
+      document.components.schemas[schemaName] = {
+        type: 'object',
+        properties: schemaProps,
+        ...(requiredProps.length > 0 ? { required: requiredProps } : {}),
+      };
+    }
+
+    for (const route of routes) {
+      const { method, path, handler } = route;
+
+      const swaggerPath = path.replace(/:([a-zA-Z0-9_]+)/g, '{$1}');
+
+      if (!document.paths[swaggerPath]) {
+        document.paths[swaggerPath] = {};
+      }
+
+      const operationMeta =
+        Reflect.getMetadata('calyx:api_operation', handler.controllerClass.prototype, handler.methodName) || {};
+      const tags =
+        Reflect.getMetadata('calyx:api_tags', handler.controllerClass.prototype, handler.methodName) ||
+        Reflect.getMetadata('calyx:api_tags', handler.controllerClass) ||
+        [];
+      const responsesMeta =
+        Reflect.getMetadata('calyx:api_responses', handler.controllerClass.prototype, handler.methodName) || [];
+      const securityMeta =
+        Reflect.getMetadata('calyx:api_security', handler.controllerClass.prototype, handler.methodName) ||
+        Reflect.getMetadata('calyx:api_security', handler.controllerClass) ||
+        [];
+
+      // Extra Models
+      const extraModels = Reflect.getMetadata('calyx:api_extra_models', handler.controllerClass) || [];
+      for (const model of extraModels) {
+        registerSchema(model);
+      }
+
+      const parameters: any[] = [];
+
+      // Parse Path Params (Regex match)
+      const pathParams = [...path.matchAll(/:([a-zA-Z0-9_]+)/g)].map((m) => m[1]);
+      const pathParamDecorators = Reflect.getMetadata('calyx:api_params', handler.controllerClass.prototype, handler.methodName) || [];
+
+      for (const name of pathParams) {
+        const dec = pathParamDecorators.find((d: any) => d.name === name) || {};
+        parameters.push({
+          name,
+          in: 'path',
+          required: true,
+          description: dec.description || '',
+          schema: {
+            type: dec.type ? dec.type.name.toLowerCase() : 'string',
+          },
+        });
+      }
+
+      // Parse Http Parameter Decorators (@Query, @Headers, etc.)
+      const httpParams: any[] = Reflect.getMetadata('calyx:http_params', handler.controllerClass.prototype, handler.methodName) || [];
+      const paramTypes = Reflect.getMetadata('design:paramtypes', handler.controllerClass.prototype, handler.methodName) || [];
+      const apiQueries = Reflect.getMetadata('calyx:api_queries', handler.controllerClass.prototype, handler.methodName) || [];
+      const apiHeaders = Reflect.getMetadata('calyx:api_headers', handler.controllerClass.prototype, handler.methodName) || [];
+      let requestBody: any = undefined;
+
+      for (const param of httpParams) {
+        const paramType = paramTypes[param.index];
+
+        if (param.type === 'query') {
+          const qName = param.name;
+          if (qName) {
+            const dec = apiQueries.find((q: any) => q.name === qName) || {};
+            parameters.push({
+              name: qName,
+              in: 'query',
+              required: dec.required ?? false,
+              description: dec.description || '',
+              schema: {
+                type: dec.type ? dec.type.name.toLowerCase() : (paramType ? paramType.name.toLowerCase() : 'string'),
+              },
+            });
+          }
+        } else if (param.type === 'headers') {
+          const hName = param.name;
+          if (hName) {
+            const dec = apiHeaders.find((h: any) => h.name === hName) || {};
+            parameters.push({
+              name: hName,
+              in: 'header',
+              required: dec.required ?? false,
+              description: dec.description || '',
+              schema: {
+                type: 'string',
+              },
+            });
+          }
+        } else if (param.type === 'body') {
+          const bodyDec = Reflect.getMetadata('calyx:api_body', handler.controllerClass.prototype, handler.methodName) || {};
+          const targetType = bodyDec.type || paramType;
+
+          if (targetType) {
+            registerSchema(targetType);
+            requestBody = {
+              description: bodyDec.description || '',
+              required: bodyDec.required ?? true,
+              content: {
+                'application/json': {
+                  schema: {
+                    $ref: `#/components/schemas/${targetType.name}`,
+                  },
+                },
+              },
+            };
+          }
+        }
+      }
+
+      // Add manual @ApiQuery annotations if they weren't matched to method params
+      for (const q of apiQueries) {
+        if (!parameters.some((p) => p.in === 'query' && p.name === q.name)) {
+          parameters.push({
+            name: q.name,
+            in: 'query',
+            required: q.required ?? false,
+            description: q.description || '',
+            schema: {
+              type: q.type ? q.type.name.toLowerCase() : 'string',
+            },
+          });
+        }
+      }
+
+      // Add manual @ApiHeader annotations if they weren't matched to method params
+      for (const h of apiHeaders) {
+        if (!parameters.some((p) => p.in === 'header' && p.name === h.name)) {
+          parameters.push({
+            name: h.name,
+            in: 'header',
+            required: h.required ?? false,
+            description: h.description || '',
+            schema: {
+              type: 'string',
+            },
+          });
+        }
+      }
+
+      const responses: Record<string, any> = {};
+      if (responsesMeta.length > 0) {
+        for (const res of responsesMeta) {
+          responses[String(res.status)] = {
+            description: res.description,
+          };
+          if (res.type) {
+            const schemaName = res.type.name;
+            responses[String(res.status)].content = {
+              'application/json': {
+                schema: { $ref: `#/components/schemas/${schemaName}` },
+              },
+            };
+            registerSchema(res.type);
+          }
+        }
+      } else {
+        responses['200'] = { description: 'OK' };
+      }
+
+      document.paths[swaggerPath][method.toLowerCase()] = {
+        summary: operationMeta.summary || '',
+        description: operationMeta.description || '',
+        tags,
+        parameters,
+        ...(requestBody ? { requestBody } : {}),
+        responses,
+        ...(securityMeta.length > 0 ? { security: securityMeta } : {}),
+      };
+    }
+
+    return document;
+  }
+
+  static setup(path: string, app: CalyxApplication, document: any) {
+    const jsonPath = `/${path}-json`.replace(/\/\/+/g, '/');
+    const uiPath = `/${path}`.replace(/\/\/+/g, '/');
+
+    app.use((req: any, res: any, next: any) => {
+      const url = new URL(req.url);
+      if (url.pathname === jsonPath && req.method === 'GET') {
+        res.status(200);
+        res.set('content-type', 'application/json');
+        res.send(JSON.stringify(document));
+        return;
+      }
+      next();
+    });
+
+    const html = `
+      <!DOCTYPE html>
+      <html lang="en">
+      <head>
+        <meta charset="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <title>Calyx Swagger UI</title>
+        <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.11.0/swagger-ui.css" />
+      </head>
+      <body>
+        <div id="swagger-ui"></div>
+        <script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.11.0/swagger-ui-bundle.js"></script>
+        <script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.11.0/swagger-ui-standalone-preset.js"></script>
+        <script>
+          window.onload = () => {
+            window.ui = SwaggerUIBundle({
+              url: '${jsonPath}',
+              dom_id: '#swagger-ui',
+              presets: [
+                SwaggerUIBundle.presets.apis,
+                SwaggerUIStandalonePreset
+              ],
+              layout: "BaseLayout"
+            });
+          };
+        </script>
+      </body>
+      </html>
+    `;
+
+    app.use((req: any, res: any, next: any) => {
+      const url = new URL(req.url);
+      if (url.pathname === uiPath && req.method === 'GET') {
+        res.status(200);
+        res.set('content-type', 'text/html');
+        res.send(html);
+        return;
+      }
+      next();
+    });
+  }
+}

package/src/queue/queue.module.ts

@@ -0,0 +1,174 @@
+import { Module, DynamicModule, Inject } from '../core/decorators.ts';
+import { METADATA_KEYS } from '../core/metadata.ts';
+
+export interface Job<T = any> {
+  id: string;
+  name: string;
+  data: T;
+  opts?: any;
+  status: 'waiting' | 'active' | 'completed' | 'failed';
+  result?: any;
+  error?: any;
+}
+
+export const PROCESSOR_METADATA_KEY = 'calyx:processor';
+export const PROCESS_METADATA_KEY = 'calyx:process';
+
+export function Processor(queueName?: string): ClassDecorator {
+  return (target) => {
+    Reflect.defineMetadata(PROCESSOR_METADATA_KEY, queueName ?? target.name, target);
+    Reflect.defineMetadata(METADATA_KEYS.INJECTABLE, true, target);
+  };
+}
+
+export interface ProcessOptions {
+  name?: string;
+}
+
+export function Process(options?: ProcessOptions | string): MethodDecorator {
+  return (target, propertyKey) => {
+    const name = typeof options === 'string' ? options : options?.name;
+    const existing = Reflect.getMetadata(PROCESS_METADATA_KEY, target.constructor) || [];
+    existing.push({ name: name ?? '', propertyKey });
+    Reflect.defineMetadata(PROCESS_METADATA_KEY, existing, target.constructor);
+  };
+}
+
+export function InjectQueue(name: string): ParameterDecorator & PropertyDecorator {
+  return Inject(`Queue_${name}`);
+}
+
+export class QueueManager {
+  private static processors = new Map<string, { instance: any; handlers: { name: string; propertyKey: string | symbol }[] }>();
+  private static queues = new Map<string, Queue>();
+
+  static registerProcessor(queueName: string, instance: any) {
+    const handlers = Reflect.getMetadata(PROCESS_METADATA_KEY, instance.constructor) || [];
+    this.processors.set(queueName, { instance, handlers });
+  }
+
+  static getOrCreateQueue(name: string): Queue {
+    let q = this.queues.get(name);
+    if (!q) {
+      q = new Queue(name);
+      this.queues.set(name, q);
+    }
+    return q;
+  }
+
+  static async dispatch(queueName: string, job: Job) {
+    const proc = this.processors.get(queueName);
+    if (!proc) {
+      // No processor registered yet, mark job as completed (dummy/mock queue mode)
+      job.status = 'completed';
+      return;
+    }
+
+    job.status = 'active';
+    const handler = proc.handlers.find((h) => h.name === job.name || (h.name === '' && !job.name));
+    if (handler) {
+      try {
+        const res = proc.instance[handler.propertyKey](job);
+        if (res instanceof Promise) {
+          job.result = await res;
+        } else {
+          job.result = res;
+        }
+        job.status = 'completed';
+      } catch (err: any) {
+        job.error = err;
+        job.status = 'failed';
+      }
+    } else {
+      // Fallback: match any handler or first one
+      const fallback = proc.handlers[0];
+      if (fallback) {
+        try {
+          const res = proc.instance[fallback.propertyKey](job);
+          if (res instanceof Promise) {
+            job.result = await res;
+          } else {
+            job.result = res;
+          }
+          job.status = 'completed';
+        } catch (err: any) {
+          job.error = err;
+          job.status = 'failed';
+        }
+      } else {
+        job.status = 'completed';
+      }
+    }
+  }
+}
+
+export class Queue {
+  private jobs: Job[] = [];
+  private jobCounter = 0;
+
+  constructor(public readonly name: string) {}
+
+  async add<T = any>(name: string, data: T, opts?: any): Promise<Job<T>>;
+  async add<T = any>(data: T, opts?: any): Promise<Job<T>>;
+  async add<T = any>(first: any, second?: any, third?: any): Promise<Job<T>> {
+    let name = '';
+    let data: T;
+    let opts: any;
+
+    if (typeof first === 'string') {
+      name = first;
+      data = second;
+      opts = third;
+    } else {
+      data = first;
+      opts = second;
+    }
+
+    this.jobCounter++;
+    const job: Job<T> = {
+      id: `${this.name}_job_${this.jobCounter}`,
+      name,
+      data,
+      opts,
+      status: 'waiting',
+    };
+
+    this.jobs.push(job);
+
+    // Run dispatch asynchronously in the background
+    queueMicrotask(() => {
+      QueueManager.dispatch(this.name, job);
+    });
+
+    return job;
+  }
+
+  async getJobs(): Promise<Job[]> {
+    return this.jobs;
+  }
+}
+
+@Module({})
+export class QueueModule {
+  static registerQueue(...configs: { name: string }[]): DynamicModule {
+    const providers = configs.map((c) => {
+      return {
+        provide: `Queue_${c.name}`,
+        useFactory: () => {
+          return QueueManager.getOrCreateQueue(c.name);
+        },
+      };
+    });
+
+    return {
+      module: QueueModule,
+      providers,
+      exports: configs.map((c) => `Queue_${c.name}`),
+    };
+  }
+
+  // Automatic processor registration on initialization
+  onApplicationBootstrap() {
+    // Handled in CalyxApplication initialization dynamically
+  }
+}

package/src/session/index.ts

@@ -0,0 +1 @@
+export * from './session.middleware.ts';

package/src/session/session.middleware.ts

@@ -0,0 +1,82 @@
+import { createParamDecorator } from '../http/decorators.ts';
+import { formatCookie } from '../cookies/cookies.ts';
+
+export interface SessionData {
+  id: string;
+  data: Record<string, any>;
+  expiresAt: number;
+}
+
+export class MemorySessionStore {
+  private store = new Map<string, SessionData>();
+
+  get(sid: string): SessionData | undefined {
+    const session = this.store.get(sid);
+    if (!session) return undefined;
+    if (session.expiresAt < Date.now()) {
+      this.store.delete(sid);
+      return undefined;
+    }
+    return session;
+  }
+
+  set(sid: string, data: Record<string, any>, ttlSeconds: number) {
+    this.store.set(sid, {
+      id: sid,
+      data,
+      expiresAt: Date.now() + ttlSeconds * 1000,
+    });
+  }
+
+  destroy(sid: string) {
+    this.store.delete(sid);
+  }
+}
+
+export const sessionStore = new MemorySessionStore();
+
+export interface SessionOptions {
+  secret?: string;
+  name?: string;
+  ttl?: number; // TTL in seconds, default 1 day
+}
+
+export function session(options: SessionOptions = {}) {
+  const cookieName = options.name ?? 'calyx_sid';
+  const ttl = options.ttl ?? 86400; // 1 day
+
+  return (req: any, res: any, next: any) => {
+    const cookies = req.cookies || {};
+    let sid = cookies[cookieName];
+    let sessionData = sid ? sessionStore.get(sid) : undefined;
+
+    if (!sessionData) {
+      sid = crypto.randomUUID();
+      sessionData = {
+        id: sid,
+        data: {},
+        expiresAt: Date.now() + ttl * 1000,
+      };
+      sessionStore.set(sid, sessionData.data, ttl);
+    }
+
+    req.session = sessionData.data;
+
+    // Attach finalizeSession hook to request
+    req.finalizeSession = (responseHeaders: Headers) => {
+      sessionStore.set(sid, req.session, ttl);
+      responseHeaders.append('Set-Cookie', formatCookie(cookieName, sid, {
+        maxAge: ttl,
+        httpOnly: true,
+        path: '/',
+      }));
+    };
+
+    next();
+  };
+}
+
+export const Session = createParamDecorator((data, ctx) => {
+  const req = ctx.switchToHttp().getRequest();
+  return (req as any).session;
+});

package/src/sse/index.ts

@@ -0,0 +1 @@
+export * from './sse.ts';

package/src/sse/sse.ts

@@ -0,0 +1,18 @@
+import 'reflect-metadata';
+import { METADATA_KEYS } from '../core/metadata.ts';
+
+export interface MessageEvent {
+  data: string | object;
+  id?: string;
+  type?: string;
+  retry?: number;
+}
+
+export function Sse(path = ''): MethodDecorator {
+  return (target: any, propertyKey: string | symbol, descriptor: any) => {
+    // SSE routes are GET requests
+    Reflect.defineMetadata(METADATA_KEYS.HTTP_METHOD, { method: 'GET', path }, target, propertyKey);
+    Reflect.defineMetadata('calyx:sse', true, target, propertyKey);
+    return descriptor;
+  };
+}

package/src/streaming/index.ts

@@ -0,0 +1 @@
+export * from './streamable-file.ts';

package/src/streaming/streamable-file.ts

@@ -0,0 +1,32 @@
+export interface StreamableFileOptions {
+  type?: string;
+  disposition?: string;
+  length?: number;
+}
+
+export class StreamableFile {
+  constructor(
+    public readonly streamOrBuffer: any,
+    public readonly options: StreamableFileOptions = {}
+  ) {}
+
+  getStream(): any {
+    return this.streamOrBuffer;
+  }
+
+  getHeaders(): Record<string, string> {
+    const headers: Record<string, string> = {};
+    if (this.options.type) {
+      headers['content-type'] = this.options.type;
+    } else {
+      headers['content-type'] = 'application/octet-stream';
+    }
+    if (this.options.disposition) {
+      headers['content-disposition'] = this.options.disposition;
+    }
+    if (this.options.length !== undefined) {
+      headers['content-length'] = String(this.options.length);
+    }
+    return headers;
+  }
+}