@martel/calyx 1.8.0 → 1.9.0

package/src/http/application.ts

@@ -11,6 +11,12 @@ import { cors, CorsOptions } from '../security/cors.middleware.ts';
 import { helmet, HelmetOptions } from '../security/helmet.middleware.ts';
 import { CronMatcher } from '../schedule/cron.matcher.ts';
 import { SerializationCompiler } from '../validation/compiler.ts';
+import { VersioningOptions, VersioningType, VersionExtractor, VERSION_METADATA_KEY } from '../versioning/versioning.ts';
+import { QueueManager, PROCESSOR_METADATA_KEY } from '../queue/queue.module.ts';
+import { parseCookies, formatCookie } from '../cookies/cookies.ts';
+import { StreamableFile } from '../streaming/streamable-file.ts';
+import { defaultRenderEngine, ViewEngine } from '../mvc/mvc.ts';
+import { join } from 'path';
 
 class ObjectPool<T> {
   private pool: T[] = [];
@@ -53,6 +59,13 @@ export class CalyxResponse {
     this.headers[name.toLowerCase()] = value;
     return this;
   }
+
+  cookiesList: string[] = [];
+
+  cookie(name: string, value: string, options?: any) {
+    this.cookiesList.push(formatCookie(name, value, options));
+    return this;
+  }
 }
 
 interface CompiledLifecycleItem {
@@ -85,6 +98,8 @@ interface HandlerConfig {
   interceptorsList: CompiledLifecycleItem[];
   filtersList: CompiledLifecycleItem[];
   middlewaresList: CompiledLifecycleItem[];
+  renderTemplate?: string;
+  isSse?: boolean;
 }
 
 export class CalyxApplication {
@@ -105,6 +120,32 @@ export class CalyxApplication {
   private serverPort = 3000;
   private graphqlSchema: any = null;
   private isInitialized = false;
+  private versioningOptions?: VersioningOptions;
+
+  enableVersioning(options: VersioningOptions) {
+    this.versioningOptions = options;
+    return this;
+  }
+
+  private compressionEnabled = false;
+
+  enableCompression() {
+    this.compressionEnabled = true;
+    return this;
+  }
+
+  private viewsDir = 'views';
+  private viewEngine: ViewEngine = defaultRenderEngine;
+
+  setViewsDir(dir: string) {
+    this.viewsDir = dir;
+    return this;
+  }
+
+  setViewEngine(engine: ViewEngine) {
+    this.viewEngine = engine;
+    return this;
+  }
 
   use(...middlewares: any[]) {
     this.globalMiddlewares.push(...middlewares);
@@ -155,6 +196,9 @@ export class CalyxApplication {
     // Register Event listeners
     this.registerEventListeners();
 
+    // Register Queue Processors
+    this.registerQueueProcessors();
+
     // Register Scheduled tasks
     this.registerScheduledTasks();
 
@@ -259,26 +303,64 @@ export class CalyxApplication {
             hasReqScopedPipe ||
             hasReqScopedMiddleware;
 
-          this.router.insert(routeMeta.method, fullPath, {
-            controllerClass,
-            moduleClass,
-            instance: singletonInstance,
-            methodName: method,
-            paramsConfig: compiledParamsConfig,
-            httpCode,
-            headers,
-            redirect,
-            hasBodyParam,
-            hasQueryParam,
-            hasResParam,
-            isPassthrough,
-            isRequestScoped: isRouteRequestScoped,
-            hasLifecycleMetadata,
-            guardsList,
-            interceptorsList,
-            filtersList,
-            middlewaresList,
-          });
+          const methodFn = controllerClass.prototype[method];
+          // Compile versions if versioning is enabled
+          let versions: string[] = [];
+          if (this.versioningOptions) {
+            const rawVersion = Reflect.getMetadata(VERSION_METADATA_KEY, controllerClass.prototype, method) ??
+                               Reflect.getMetadata(VERSION_METADATA_KEY, methodFn) ??
+                               Reflect.getMetadata(VERSION_METADATA_KEY, controllerClass);
+            if (rawVersion !== undefined && rawVersion !== null) {
+              versions = Array.isArray(rawVersion) ? rawVersion : [rawVersion];
+            } else if (this.versioningOptions.defaultVersion !== undefined && this.versioningOptions.defaultVersion !== null) {
+              const defaultV = this.versioningOptions.defaultVersion;
+              versions = Array.isArray(defaultV) ? defaultV : [defaultV];
+            }
+          }
+
+          const renderTemplate = Reflect.getMetadata('calyx:render_template', controllerClass.prototype, method) ??
+                                 Reflect.getMetadata('calyx:render_template', methodFn);
+          const isSse = Reflect.hasMetadata('calyx:sse', controllerClass.prototype, method) ||
+                        Reflect.hasMetadata('calyx:sse', methodFn);
+
+          const insertRoute = (methodStr: string, pathStr: string) => {
+            this.router.insert(methodStr, pathStr, {
+              controllerClass,
+              moduleClass,
+              instance: singletonInstance,
+              methodName: method,
+              paramsConfig: compiledParamsConfig,
+              httpCode,
+              headers,
+              redirect,
+              hasBodyParam,
+              hasQueryParam,
+              hasResParam,
+              isPassthrough,
+              isRequestScoped: isRouteRequestScoped,
+              hasLifecycleMetadata,
+              guardsList,
+              interceptorsList,
+              filtersList,
+              middlewaresList,
+              renderTemplate,
+              isSse,
+            });
+          };
+
+          if (this.versioningOptions && this.versioningOptions.type === VersioningType.URI && versions.length > 0) {
+            for (const version of versions) {
+              const versionPrefix = `/v${version}`;
+              const versionedPath = '/' + [versionPrefix.replace(/^\/|\/$/g, ''), normalizedPrefix, normalizedPath].filter(Boolean).join('/');
+              insertRoute(routeMeta.method, versionedPath);
+            }
+          } else if (this.versioningOptions && (this.versioningOptions.type === VersioningType.HEADER || this.versioningOptions.type === VersioningType.MEDIA_TYPE) && versions.length > 0) {
+            for (const version of versions) {
+              insertRoute(`${routeMeta.method}:v${version}`, fullPath);
+            }
+          } else {
+            insertRoute(routeMeta.method, fullPath);
+          }
         }
       }
     }
@@ -396,6 +478,10 @@ export class CalyxApplication {
   private handleRequest(req: Request): Response | Promise<Response> {
     try {
       const urlStr = req.url;
+      // Parse cookies
+      const cookieHeader = req.headers.get('cookie') || '';
+      (req as any).cookies = parseCookies(cookieHeader);
+
       // Fast path parsing
       let pathname = '/';
       let search = '';
@@ -416,7 +502,16 @@ export class CalyxApplication {
         return this.handleGraphQLRequest(req);
       }
 
-      const matched = this.router.match(req.method, pathname);
+      let matched = null;
+      if (this.versioningOptions && this.versioningOptions.type !== VersioningType.URI) {
+        const version = VersionExtractor.extract(req, this.versioningOptions.type, this.versioningOptions);
+        if (version) {
+          matched = this.router.match(`${req.method}:v${version}`.toUpperCase(), pathname);
+        }
+      }
+      if (!matched) {
+        matched = this.router.match(req.method, pathname);
+      }
       if (!matched) {
         if (this.globalMiddlewares.length > 0) {
           return this.handleGlobalMiddlewaresAnd404(req, pathname);
@@ -484,6 +579,8 @@ export class CalyxApplication {
         } catch {
           body = {};
         }
+      } else if (contentType.includes('multipart/form-data')) {
+        body = null;
       } else {
         try {
           body = await req.text();
@@ -576,39 +673,41 @@ export class CalyxApplication {
         query = {};
       }
 
-      // Execute pipes for each argument
-      const args: any[] = [];
-      for (const config of paramsConfig) {
-        let val: any;
-        switch (config.type) {
-          case 'req': val = req; break;
-          case 'res': val = resWrapper; break;
-          case 'param': val = config.name ? params[config.name] : params; break;
-          case 'query': val = config.name ? query?.[config.name] : query; break;
-          case 'body': val = config.name ? body?.[config.name] : body; break;
-          case 'headers': val = config.name ? req.headers.get(config.name) : Object.fromEntries(req.headers.entries()); break;
-          case 'custom': val = config.factory ? config.factory(config.name, context) : undefined; break;
-        }
+      const resolveArgs = async (): Promise<any[]> => {
+        const args: any[] = [];
+        for (const config of paramsConfig) {
+          let val: any;
+          switch (config.type) {
+            case 'req': val = req; break;
+            case 'res': val = resWrapper; break;
+            case 'param': val = config.name ? params[config.name] : params; break;
+            case 'query': val = config.name ? query?.[config.name] : query; break;
+            case 'body': val = config.name ? body?.[config.name] : body; break;
+            case 'headers': val = config.name ? req.headers.get(config.name) : Object.fromEntries(req.headers.entries()); break;
+            case 'custom': val = config.factory ? config.factory(config.name, context) : undefined; break;
+          }
 
-        // Apply pipes
-        for (const pipe of config.pipesList) {
-          const pipeInstance = pipe.isReqScoped
-            ? this.container.resolveTokenInModuleContext(moduleClass, pipe.token, requestContext)
-            : pipe.instance;
-          const transformed = pipeInstance.transform(val, {
-            type: config.type,
-            metatype: config.paramType,
-            data: config.name,
-          });
-          if (transformed instanceof Promise) {
-            val = await transformed;
-          } else {
-            val = transformed;
+          // Apply pipes
+          for (const pipe of config.pipesList) {
+            const pipeInstance = pipe.isReqScoped
+              ? this.container.resolveTokenInModuleContext(moduleClass, pipe.token, requestContext)
+              : pipe.instance;
+            const transformed = pipeInstance.transform(val, {
+              type: config.type,
+              metatype: config.paramType,
+              data: config.name,
+            });
+            if (transformed instanceof Promise) {
+              val = await transformed;
+            } else {
+              val = transformed;
+            }
           }
-        }
 
-        args[config.index] = val;
-      }
+          args[config.index] = val;
+        }
+        return args;
+      };
 
       let result: any;
       if (handler.interceptorsList.length > 0) {
@@ -621,21 +720,23 @@ export class CalyxApplication {
               : interceptor.instance;
             return interceptorInstance.intercept(context, { handle: () => executeHandler() });
           }
+          const args = await resolveArgs();
           return instance[methodName](...args);
         };
         result = await executeHandler();
       } else {
+        const args = await resolveArgs();
         result = instance[methodName](...args);
         if (result instanceof Promise) {
           result = await result;
         }
       }
 
-      if (this.isObservable(result)) {
+      if (this.isObservable(result) && !handler.isSse) {
         result = await this.resolveObservable(result);
       }
 
-      return this.processResult(req, result, resWrapper, httpCode, headers, redirect, handler.isPassthrough, handler.hasResParam);
+      return this.processResult(req, result, resWrapper, httpCode, headers, redirect, handler.isPassthrough, handler.hasResParam, handler.renderTemplate, handler.isSse);
     } catch (err: any) {
       return await this.handleLifecycleError(err, host, handler, requestContext);
     } finally {
@@ -775,6 +876,8 @@ export class CalyxApplication {
         } catch {
           body = {};
         }
+      } else if (contentType.includes('multipart/form-data')) {
+        body = null;
       } else {
         try {
           body = await req.text();
@@ -844,15 +947,54 @@ export class CalyxApplication {
 
     let result = instance[methodName](...args);
 
-    if (this.isObservable(result)) {
+    if (this.isObservable(result) && !handler.isSse) {
       result = this.resolveObservable(result);
     }
 
     if (result instanceof Promise) {
-      return result.then((resolvedResult) => this.processResult(req, resolvedResult, resWrapper, httpCode, headers, redirect, handler.isPassthrough, handler.hasResParam));
+      return result.then((resolvedResult) => this.processResult(req, resolvedResult, resWrapper, httpCode, headers, redirect, handler.isPassthrough, handler.hasResParam, handler.renderTemplate, handler.isSse));
     }
 
-    return this.processResult(req, result, resWrapper, httpCode, headers, redirect, handler.isPassthrough, handler.hasResParam);
+    return this.processResult(req, result, resWrapper, httpCode, headers, redirect, handler.isPassthrough, handler.hasResParam, handler.renderTemplate, handler.isSse);
+  }
+
+  private compressResponseIfNeeded(req: Request, body: any, headers: Headers, resWrapper: CalyxResponse | null): any {
+    const isEnabled = this.compressionEnabled || (resWrapper && (resWrapper as any).compressionEnabled);
+    if (!isEnabled) return body;
+
+    const acceptEncoding = req.headers.get('accept-encoding') || '';
+    if (!acceptEncoding.includes('gzip')) return body;
+
+    if (!body) return body;
+
+    const contentType = headers.get('content-type') || '';
+    const isCompressible = contentType.includes('text/') ||
+                          contentType.includes('json') ||
+                          contentType.includes('javascript') ||
+                          contentType.includes('xml') ||
+                          contentType === '';
+
+    if (!isCompressible) return body;
+
+    try {
+      let dataToCompress: Uint8Array;
+      if (typeof body === 'string') {
+        dataToCompress = new TextEncoder().encode(body);
+      } else if (body instanceof Uint8Array) {
+        dataToCompress = body;
+      } else if (body instanceof ArrayBuffer) {
+        dataToCompress = new Uint8Array(body);
+      } else {
+        dataToCompress = new TextEncoder().encode(JSON.stringify(body));
+      }
+
+      const compressed = Bun.gzipSync(dataToCompress);
+      headers.set('content-encoding', 'gzip');
+      headers.set('content-length', String(compressed.length));
+      return compressed;
+    } catch {
+      return body;
+    }
   }
 
   private processResult(
@@ -863,23 +1005,47 @@ export class CalyxApplication {
     headers: { name: string; value: string }[],
     redirect: { url: string; statusCode?: number } | undefined,
     isPassthrough = false,
-    hasResParam = false
-  ): Response {
+    hasResParam = false,
+    renderTemplate?: string,
+    isSse = false
+  ): Response | Promise<Response> {
     if (redirect) {
       return Response.redirect(redirect.url, redirect.statusCode || 302);
     }
 
     if (resWrapper) {
       if (resWrapper.sent && !isPassthrough) {
-        return new Response(resWrapper.body, {
+        const responseHeaders = new Headers();
+        for (const [k, v] of Object.entries(resWrapper.headers)) {
+          responseHeaders.set(k, v);
+        }
+        for (const c of resWrapper.cookiesList) {
+          responseHeaders.append('Set-Cookie', c);
+        }
+        if ((req as any).finalizeSession) {
+          (req as any).finalizeSession(responseHeaders);
+        }
+        const finalBody = this.compressResponseIfNeeded(req, resWrapper.body, responseHeaders, resWrapper);
+        return new Response(finalBody, {
           status: resWrapper.statusCode,
-          headers: resWrapper.headers,
+          headers: responseHeaders,
         });
       }
       if (hasResParam && !isPassthrough) {
-        return new Response(resWrapper.body, {
+        const responseHeaders = new Headers();
+        for (const [k, v] of Object.entries(resWrapper.headers)) {
+          responseHeaders.set(k, v);
+        }
+        for (const c of resWrapper.cookiesList) {
+          responseHeaders.append('Set-Cookie', c);
+        }
+        if ((req as any).finalizeSession) {
+          (req as any).finalizeSession(responseHeaders);
+        }
+        const finalBody = this.compressResponseIfNeeded(req, resWrapper.body, responseHeaders, resWrapper);
+        return new Response(finalBody, {
           status: resWrapper.statusCode,
-          headers: resWrapper.headers,
+          headers: responseHeaders,
         });
       }
     }
@@ -889,12 +1055,73 @@ export class CalyxApplication {
       : (httpCode ?? (req.method === 'POST' ? 201 : 200));
 
     // Build headers as a plain object Record<string, string>
-    const responseHeaders: Record<string, string> = resWrapper 
-      ? { ...resWrapper.headers } 
-      : {};
+    const responseHeaders = new Headers();
+    if (resWrapper) {
+      for (const [k, v] of Object.entries(resWrapper.headers)) {
+        responseHeaders.set(k, v);
+      }
+      for (const c of resWrapper.cookiesList) {
+        responseHeaders.append('Set-Cookie', c);
+      }
+    }
+
+    if ((req as any).finalizeSession) {
+      (req as any).finalizeSession(responseHeaders);
+    }
 
     for (const header of headers) {
-      responseHeaders[header.name.toLowerCase()] = header.value;
+      responseHeaders.set(header.name.toLowerCase(), header.value);
+    }
+
+    if (isSse) {
+      responseHeaders.set('content-type', 'text/event-stream');
+      responseHeaders.set('cache-control', 'no-cache');
+      responseHeaders.set('connection', 'keep-alive');
+
+      let subscription: any;
+      const stream = new ReadableStream({
+        start(controller) {
+          subscription = result.subscribe({
+            next(event: any) {
+              let msg = '';
+              if (event.id) msg += `id: ${event.id}\n`;
+              if (event.type) msg += `event: ${event.type}\n`;
+              if (event.retry) msg += `retry: ${event.retry}\n`;
+              const dataStr = typeof event.data === 'object' ? JSON.stringify(event.data) : String(event.data);
+              msg += `data: ${dataStr}\n\n`;
+              controller.enqueue(new TextEncoder().encode(msg));
+            },
+            error(err: any) {
+              controller.error(err);
+            },
+            complete() {
+              controller.close();
+            }
+          });
+        },
+        cancel() {
+          if (subscription) {
+            subscription.unsubscribe();
+          }
+        }
+      });
+
+      return new Response(stream, { status, headers: responseHeaders });
+    }
+
+    if (renderTemplate) {
+      const templatePath = join(this.viewsDir, renderTemplate + (renderTemplate.includes('.') ? '' : '.html'));
+      const renderResult = this.viewEngine(templatePath, result);
+      if (renderResult instanceof Promise) {
+        return renderResult.then((html) => {
+          responseHeaders.set('content-type', 'text/html');
+          const finalBody = this.compressResponseIfNeeded(req, html, responseHeaders, resWrapper);
+          return new Response(finalBody, { status, headers: responseHeaders });
+        });
+      }
+      responseHeaders.set('content-type', 'text/html');
+      const finalBody = this.compressResponseIfNeeded(req, renderResult, responseHeaders, resWrapper);
+      return new Response(finalBody, { status, headers: responseHeaders });
     }
 
     if (result === undefined || result === null) {
@@ -902,24 +1129,46 @@ export class CalyxApplication {
     }
 
     if (result instanceof Response) {
+      if (resWrapper && resWrapper.cookiesList.length > 0) {
+        for (const c of resWrapper.cookiesList) {
+          result.headers.append('Set-Cookie', c);
+        }
+      }
+      if ((req as any).finalizeSession) {
+        (req as any).finalizeSession(result.headers);
+      }
       return result;
     }
 
+    if (result instanceof StreamableFile) {
+      const fileHeaders = result.getHeaders();
+      for (const [k, v] of Object.entries(fileHeaders)) {
+        responseHeaders.set(k, v);
+      }
+      const finalBody = this.compressResponseIfNeeded(req, result.getStream(), responseHeaders, resWrapper);
+      return new Response(finalBody, { status, headers: responseHeaders });
+    }
+
     if (typeof result === 'object') {
-      responseHeaders['content-type'] = 'application/json';
+      responseHeaders.set('content-type', 'application/json');
       const constructor = result.constructor;
       if (constructor) {
         const hasRules = Reflect.hasMetadata('calyx:validation_rules', constructor);
         const hasExpose = Reflect.hasMetadata('calyx:expose_properties', constructor);
         if (hasRules || hasExpose) {
           const serialize = SerializationCompiler.compile(constructor);
-          return new Response(serialize(result), { status, headers: responseHeaders });
+          const serialized = serialize(result);
+          const finalBody = this.compressResponseIfNeeded(req, serialized, responseHeaders, resWrapper);
+          return new Response(finalBody, { status, headers: responseHeaders });
         }
       }
-      return new Response(JSON.stringify(result), { status, headers: responseHeaders });
+      const serialized = JSON.stringify(result);
+      const finalBody = this.compressResponseIfNeeded(req, serialized, responseHeaders, resWrapper);
+      return new Response(finalBody, { status, headers: responseHeaders });
     }
 
-    return new Response(String(result), { status, headers: responseHeaders });
+    const finalBody = this.compressResponseIfNeeded(req, String(result), responseHeaders, resWrapper);
+    return new Response(finalBody, { status, headers: responseHeaders });
   }
 
   private isObservable(obj: any): boolean {
@@ -1104,6 +1353,17 @@ export class CalyxApplication {
     }
   }
 
+  private registerQueueProcessors() {
+    const instances = this.container.getProviderAndControllerInstances();
+    for (const instance of instances) {
+      if (!instance || !instance.constructor) continue;
+      const queueName = Reflect.getMetadata(PROCESSOR_METADATA_KEY, instance.constructor);
+      if (queueName) {
+        QueueManager.registerProcessor(queueName, instance);
+      }
+    }
+  }
+
   private registerEventListeners() {
     let eventEmitter: EventEmitter;
     try {

package/src/http-client/http-client.module.ts

@@ -0,0 +1,124 @@
+import { Observable } from 'rxjs';
+import { Module, DynamicModule, Injectable } from '../core/decorators.ts';
+
+export interface AxiosResponse<T = any> {
+  data: T;
+  status: number;
+  statusText: string;
+  headers: any;
+  config: any;
+  request?: any;
+}
+
+@Injectable()
+export class HttpService {
+  request<T = any>(config: any): Observable<AxiosResponse<T>> {
+    return new Observable((subscriber) => {
+      const controller = new AbortController();
+      const { url, method = 'GET', data, headers, ...rest } = config;
+
+      const options: RequestInit = {
+        method,
+        headers,
+        signal: controller.signal,
+        ...rest,
+      };
+
+      if (data !== undefined) {
+        if (typeof data === 'object') {
+          options.body = JSON.stringify(data);
+          options.headers = { 'content-type': 'application/json', ...options.headers };
+        } else {
+          options.body = data;
+        }
+      }
+
+      fetch(url, options)
+        .then(async (res) => {
+          let responseData: any;
+          const contentType = res.headers.get('content-type') || '';
+          if (contentType.includes('application/json')) {
+            try {
+              responseData = await res.json();
+            } catch {
+              responseData = {};
+            }
+          } else {
+            try {
+              responseData = await res.text();
+            } catch {
+              responseData = '';
+            }
+          }
+
+          const headersObj: Record<string, string> = {};
+          res.headers.forEach((val, key) => {
+            headersObj[key] = val;
+          });
+
+          subscriber.next({
+            data: responseData,
+            status: res.status,
+            statusText: res.statusText,
+            headers: headersObj,
+            config,
+          });
+          subscriber.complete();
+        })
+        .catch((err) => {
+          subscriber.error(err);
+        });
+
+      return () => {
+        controller.abort();
+      };
+    });
+  }
+
+  get<T = any>(url: string, config?: any): Observable<AxiosResponse<T>> {
+    return this.request({ ...config, url, method: 'GET' });
+  }
+
+  post<T = any>(url: string, data?: any, config?: any): Observable<AxiosResponse<T>> {
+    return this.request({ ...config, url, data, method: 'POST' });
+  }
+
+  put<T = any>(url: string, data?: any, config?: any): Observable<AxiosResponse<T>> {
+    return this.request({ ...config, url, data, method: 'PUT' });
+  }
+
+  delete<T = any>(url: string, config?: any): Observable<AxiosResponse<T>> {
+    return this.request({ ...config, url, method: 'DELETE' });
+  }
+
+  patch<T = any>(url: string, data?: any, config?: any): Observable<AxiosResponse<T>> {
+    return this.request({ ...config, url, data, method: 'PATCH' });
+  }
+
+  head<T = any>(url: string, config?: any): Observable<AxiosResponse<T>> {
+    return this.request({ ...config, url, method: 'HEAD' });
+  }
+
+  options<T = any>(url: string, config?: any): Observable<AxiosResponse<T>> {
+    return this.request({ ...config, url, method: 'OPTIONS' });
+  }
+}
+
+@Module({
+  providers: [HttpService],
+  exports: [HttpService],
+})
+export class HttpModule {
+  static register(options: any = {}): DynamicModule {
+    return {
+      module: HttpModule,
+      providers: [
+        {
+          provide: HttpService,
+          useValue: new HttpService(),
+        },
+      ],
+      exports: [HttpService],
+    };
+  }
+}

package/src/http-client/index.ts

@@ -0,0 +1 @@
+export * from './http-client.module.ts';