@martel/calyx 1.12.0 → 1.13.0

package/src/core/testing-module.ts

@@ -15,6 +15,10 @@ export class TestingModule extends ModuleRef {
     return app;
   }
 
+  createNestApplication(options?: any): CalyxApplication {
+    return this.createCalyxApplication();
+  }
+
   get<T>(token: InjectionToken, options?: { strict: boolean }): T {
     const strict = options?.strict ?? false;
     if (strict) {

package/src/cqrs/cqrs.ts

@@ -1,6 +1,7 @@
 import { Module, Injectable } from '../core/decorators.ts';
 import { Type } from '../core/metadata.ts';
 import { ModuleRef } from '../core/module-ref.ts';
+import { Subject, Observable } from 'rxjs';
 
 export interface ICommand {}
 export interface ICommandHandler<TCommand extends ICommand = any, TResult = any> {
@@ -22,6 +23,7 @@ import { METADATA_KEYS } from '../core/metadata.ts';
 export const COMMAND_HANDLER_METADATA = 'cqrs:command_handler';
 export const QUERY_HANDLER_METADATA = 'cqrs:query_handler';
 export const EVENT_HANDLER_METADATA = 'cqrs:event_handler';
+export const SAGA_METADATA = 'cqrs:saga';
 
 export const CommandHandler = (command: Type<ICommand>): ClassDecorator => {
   return (target) => {
@@ -44,10 +46,24 @@ export const EventsHandler = (...events: Type<IEvent>[]): ClassDecorator => {
   };
 };
 
+export function Saga(): PropertyDecorator {
+  return (target: any, propertyKey: string | symbol) => {
+    const constructor = target.constructor;
+    const existing = Reflect.getOwnMetadata(SAGA_METADATA, constructor) || [];
+    existing.push(propertyKey);
+    Reflect.defineMetadata(SAGA_METADATA, existing, constructor);
+  };
+}
+
+@Injectable()
+export class UnhandledExceptionBus extends Subject<any> {}
+
 @Injectable()
 export class CommandBus {
   private handlers = new Map<any, ICommandHandler>();
 
+  constructor(private readonly exceptionBus: UnhandledExceptionBus) {}
+
   register(command: any, handler: ICommandHandler) {
     this.handlers.set(command, handler);
   }
@@ -58,7 +74,12 @@ export class CommandBus {
     if (!handler) {
       throw new Error(`CommandHandler not found for command: ${commandClass.name}`);
     }
-    return (await handler.execute(command)) as R;
+    try {
+      return (await handler.execute(command)) as R;
+    } catch (err) {
+      this.exceptionBus.next({ error: err, command });
+      throw err;
+    }
   }
 }
 
@@ -66,6 +87,8 @@ export class CommandBus {
 export class QueryBus {
   private handlers = new Map<any, IQueryHandler>();
 
+  constructor(private readonly exceptionBus: UnhandledExceptionBus) {}
+
   register(query: any, handler: IQueryHandler) {
     this.handlers.set(query, handler);
   }
@@ -76,12 +99,18 @@ export class QueryBus {
     if (!handler) {
       throw new Error(`QueryHandler not found for query: ${queryClass.name}`);
     }
-    return (await handler.execute(query)) as R;
+    try {
+      return (await handler.execute(query)) as R;
+    } catch (err) {
+      this.exceptionBus.next({ error: err, query });
+      throw err;
+    }
   }
 }
 
 @Injectable()
 export class EventBus {
+  public readonly subject$ = new Subject<any>();
   private handlers = new Map<any, IEventHandler[]>();
 
   register(event: any, handler: IEventHandler) {
@@ -100,6 +129,7 @@ export class EventBus {
         console.error(`Error in event handler:`, err);
       }
     }
+    this.subject$.next(event);
   }
 }
 
@@ -134,9 +164,47 @@ export class EventPublisher {
   }
 }
 
+export class AggregateRoot<EventBase extends IEvent = IEvent> {
+  private readonly _events: EventBase[] = [];
+  autoCommit = false;
+
+  publish(event: EventBase) {}
+  publishAll(events: EventBase[]) {}
+
+  commit() {
+    this.publishAll(this._events);
+    this._events.length = 0;
+  }
+
+  uncommit() {
+    this._events.length = 0;
+  }
+
+  getUncommittedEvents(): EventBase[] {
+    return this._events;
+  }
+
+  loadFromHistory(history: EventBase[]) {
+    history.forEach((event) => this.apply(event, true));
+  }
+
+  apply(event: EventBase, isFromHistory = false) {
+    if (!isFromHistory) {
+      this._events.push(event);
+    }
+    const handlerName = `on${event.constructor.name}`;
+    if ((this as any)[handlerName]) {
+      (this as any)[handlerName](event);
+    }
+    if (this.autoCommit) {
+      this.commit();
+    }
+  }
+}
+
 @Module({
-  providers: [CommandBus, QueryBus, EventBus, EventPublisher],
-  exports: [CommandBus, QueryBus, EventBus, EventPublisher],
+  providers: [CommandBus, QueryBus, EventBus, EventPublisher, UnhandledExceptionBus],
+  exports: [CommandBus, QueryBus, EventBus, EventPublisher, UnhandledExceptionBus],
 })
 export class CqrsModule {
   constructor(
@@ -170,6 +238,27 @@ export class CqrsModule {
           this.eventBus.register(event, inst);
         }
       }
+
+      // Check Sagas
+      const sagas: (string | symbol)[] = Reflect.getMetadata(SAGA_METADATA, inst.constructor) || [];
+      for (const sagaKey of sagas) {
+        const sagaFn = inst[sagaKey];
+        if (typeof sagaFn === 'function') {
+          const commands$ = sagaFn(this.eventBus.subject$);
+          if (commands$ && typeof commands$.subscribe === 'function') {
+            commands$.subscribe({
+              next: (cmd: any) => {
+                this.commandBus.execute(cmd).catch((err) => {
+                  console.error(`Saga error executing command:`, err);
+                });
+              },
+              error: (err: any) => {
+                console.error(`Saga stream error:`, err);
+              }
+            });
+          }
+        }
+      }
     }
   }
 }

package/src/database/sequelize.module.ts

@@ -0,0 +1,239 @@
+import { Database } from 'bun:sqlite';
+import { Module, DynamicModule, Inject } from '../core/decorators.ts';
+import { ConnectionManager } from './typeorm.module.ts';
+
+let isSequelizeAvailable = false;
+try {
+  require.resolve('sequelize');
+  isSequelizeAvailable = true;
+} catch {
+  // ignore
+}
+
+export class Model<T extends Record<string, any> = any> {
+  static tableName: string;
+  static db: Database;
+  static isNative = true;
+  static realModel: any = null;
+
+  constructor(values?: Partial<T>) {
+    if (values) {
+      Object.assign(this, values);
+    }
+  }
+
+  static async findAll(options?: any): Promise<any[]> {
+    if (!this.isNative && this.realModel) {
+      const results = await this.realModel.findAll(options);
+      return results.map((r: any) => {
+        const inst = new this();
+        Object.assign(inst, r.toJSON ? r.toJSON() : r);
+        return inst;
+      });
+    }
+    const tableName = this.tableName || this.name.toLowerCase();
+    const db = this.db || ConnectionManager.getOrCreate();
+    const rows = db.query(`SELECT id, data FROM ${tableName}`).all() as any[];
+    return rows.map((row) => {
+      const dataObj = JSON.parse(row.data);
+      dataObj.id = row.id;
+      const inst = new this();
+      Object.assign(inst, dataObj);
+      return inst;
+    });
+  }
+
+  static async findOne(options?: any): Promise<any | null> {
+    const list = await this.findAll(options);
+    return list.length > 0 ? list[0] : null;
+  }
+
+  static async findByPk(id: number | string): Promise<any | null> {
+    if (!this.isNative && this.realModel) {
+      const r = await this.realModel.findByPk(id);
+      if (!r) return null;
+      const inst = new this();
+      Object.assign(inst, r.toJSON ? r.toJSON() : r);
+      return inst;
+    }
+    const tableName = this.tableName || this.name.toLowerCase();
+    const db = this.db || ConnectionManager.getOrCreate();
+    const row = db.query(`SELECT id, data FROM ${tableName} WHERE id = $id`).get({ $id: Number(id) }) as any;
+    if (!row) return null;
+    const dataObj = JSON.parse(row.data);
+    dataObj.id = row.id;
+    const inst = new this();
+    Object.assign(inst, dataObj);
+    return inst;
+  }
+
+  static async create(values: any): Promise<any> {
+    if (!this.isNative && this.realModel) {
+      const r = await this.realModel.create(values);
+      const inst = new this();
+      Object.assign(inst, r.toJSON ? r.toJSON() : r);
+      return inst;
+    }
+    const tableName = this.tableName || this.name.toLowerCase();
+    const db = this.db || ConnectionManager.getOrCreate();
+    db.run(`
+      CREATE TABLE IF NOT EXISTS ${tableName} (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        data TEXT
+      )
+    `);
+    const dataCopy = { ...values };
+    delete dataCopy.id;
+    const result = db.query(`INSERT INTO ${tableName} (data) VALUES ($data) RETURNING id`).get({
+      $data: JSON.stringify(dataCopy)
+    }) as any;
+    const inst = new this();
+    Object.assign(inst, values, { id: result.id });
+    return inst;
+  }
+
+  async save(): Promise<this> {
+    const modelClass = this.constructor as any;
+    if (!modelClass.isNative && modelClass.realModel) {
+      const realInst = await modelClass.realModel.build(this);
+      await realInst.save();
+      Object.assign(this, realInst.toJSON());
+      return this;
+    }
+    const tableName = modelClass.tableName || modelClass.name.toLowerCase();
+    const db = modelClass.db || ConnectionManager.getOrCreate();
+    const self = this as any;
+    const dataCopy = { ...this };
+    const id = self.id;
+    delete (dataCopy as any).id;
+
+    if (id !== undefined && id !== null) {
+      db.query(`UPDATE ${tableName} SET data = $data WHERE id = $id`).run({
+        $data: JSON.stringify(dataCopy),
+        $id: id
+      });
+    } else {
+      const result = db.query(`INSERT INTO ${tableName} (data) VALUES ($data) RETURNING id`).get({
+        $data: JSON.stringify(dataCopy)
+      }) as any;
+      self.id = result.id;
+    }
+    return this;
+  }
+
+  async update(values: any): Promise<this> {
+    Object.assign(this, values);
+    return await this.save();
+  }
+
+  async destroy(): Promise<void> {
+    const modelClass = this.constructor as any;
+    if (!modelClass.isNative && modelClass.realModel) {
+      const realInst = await modelClass.realModel.findByPk((this as any).id);
+      if (realInst) await realInst.destroy();
+      return;
+    }
+    const tableName = modelClass.tableName || modelClass.name.toLowerCase();
+    const db = modelClass.db || ConnectionManager.getOrCreate();
+    const id = (this as any).id;
+    if (id !== undefined && id !== null) {
+      db.query(`DELETE FROM ${tableName} WHERE id = $id`).run({ $id: id });
+    }
+  }
+}
+
+export function InjectModel(model: any): ParameterDecorator & PropertyDecorator {
+  return Inject(`Sequelize_Model_${model.name}`);
+}
+
+export interface SequelizeModuleOptions {
+  dialect?: string;
+  storage?: string;
+  host?: string;
+  port?: number;
+  username?: string;
+  password?: string;
+  database?: string;
+  models?: any[];
+  autoLoadModels?: boolean;
+  synchronize?: boolean;
+  [key: string]: any;
+}
+
+@Module({})
+export class SequelizeModule {
+  static forRoot(options: SequelizeModuleOptions = {}): DynamicModule {
+    const isUsingSequelize = isSequelizeAvailable && options.dialect !== 'sqlite-native';
+
+    let seqPromise: Promise<any>;
+    if (isUsingSequelize) {
+      seqPromise = (async () => {
+        const { Sequelize } = await import('sequelize');
+        const sequelize = new Sequelize(options as any);
+        if (options.models) {
+          sequelize.addModels(options.models);
+        }
+        await sequelize.authenticate();
+        if (options.synchronize !== false) {
+          await sequelize.sync();
+        }
+        return sequelize;
+      })();
+    } else {
+      seqPromise = Promise.resolve(ConnectionManager.getOrCreate(options.storage));
+    }
+
+    return {
+      module: SequelizeModule,
+      providers: [
+        {
+          provide: 'Calyx_Sequelize_Instance',
+          useValue: seqPromise,
+        },
+        {
+          provide: 'Calyx_Sequelize_IsNative',
+          useValue: !isUsingSequelize,
+        },
+      ],
+      exports: ['Calyx_Sequelize_Instance', 'Calyx_Sequelize_IsNative'],
+      global: true,
+    };
+  }
+
+  static forFeature(models: any[] = []): DynamicModule {
+    const providers = models.map((model) => {
+      return {
+        provide: `Sequelize_Model_${model.name}`,
+        useFactory: (seqInstancePromise: Promise<any>, isNative: boolean) => {
+          if (isNative) {
+            const db = ConnectionManager.getOrCreate();
+            model.db = db;
+            model.tableName = model.name.toLowerCase();
+            model.isNative = true;
+            db.run(`
+              CREATE TABLE IF NOT EXISTS ${model.tableName} (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                data TEXT
+              )
+            `);
+            return model;
+          } else {
+            return seqInstancePromise.then((seq) => {
+              const realModel = seq.models[model.name];
+              model.realModel = realModel;
+              model.isNative = false;
+              return model;
+            });
+          }
+        },
+        inject: ['Calyx_Sequelize_Instance', 'Calyx_Sequelize_IsNative'],
+      };
+    });
+
+    return {
+      module: SequelizeModule,
+      providers,
+      exports: models.map((model) => `Sequelize_Model_${model.name}`),
+    };
+  }
+}

package/src/event-emitter/decorators.ts

@@ -1,10 +1,10 @@
 import 'reflect-metadata';
 
-export function OnEvent(event: string): MethodDecorator {
+export function OnEvent(event: string, options?: any): MethodDecorator {
   return (target, propertyKey) => {
     const constructor = target.constructor;
     const existing = Reflect.getOwnMetadata('calyx:on_event', constructor) || [];
-    existing.push({ event, propertyKey });
+    existing.push({ event, propertyKey, options });
     Reflect.defineMetadata('calyx:on_event', existing, constructor);
   };
 }

package/src/event-emitter/event-emitter.ts

@@ -59,3 +59,6 @@ export class EventEmitter {
     return Promise.all(promises);
   }
 }
+
+export const EventEmitter2 = EventEmitter;
+

package/src/http/application.ts

@@ -18,6 +18,8 @@ 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';
+import { CalyxMicroservice } from '../microservices/microservice.ts';
+
 
 class ObjectPool<T> {
   private pool: T[] = [];
@@ -158,12 +160,54 @@ export class CalyxApplication {
   private graphqlQueryCache = new Map<string, any>();
   private isInitialized = false;
   private versioningOptions?: VersioningOptions;
+  private globalPrefix?: string;
+  private globalPrefixOptions?: { exclude?: (string | { path: string; method: string })[] };
+  private connectedMicroservices: any[] = [];
+  private websocketAdapter: any = null;
 
   enableVersioning(options: VersioningOptions) {
     this.versioningOptions = options;
     return this;
   }
 
+  setGlobalPrefix(prefix: string, options?: { exclude?: (string | { path: string; method: string })[] }) {
+    this.globalPrefix = prefix;
+    this.globalPrefixOptions = options;
+    return this;
+  }
+
+  getHttpServer() {
+    return this.server;
+  }
+
+  getHttpAdapter() {
+    return {
+      getInstance: () => this.server,
+      getHttpServer: () => this.server,
+    };
+  }
+
+  async getUrl(): Promise<string> {
+    return `http://localhost:${this.serverPort}`;
+  }
+
+  useWebSocketAdapter(adapter: any) {
+    this.websocketAdapter = adapter;
+    return this;
+  }
+
+  connectMicroservice(options: any) {
+    const microservice = new CalyxMicroservice(this.rootModule, options);
+    this.connectedMicroservices.push(microservice);
+    return microservice;
+  }
+
+  async startAllMicroservices(): Promise<void> {
+    for (const ms of this.connectedMicroservices) {
+      await ms.listen();
+    }
+  }
+
   private compressionEnabled = false;
 
   enableCompression() {
@@ -268,6 +312,7 @@ export class CalyxApplication {
         const isControllerRequestScoped = controllerScope === Scope.REQUEST;
         const singletonInstance = isControllerRequestScoped ? null : record.instances.get(controllerClass);
 
+        const controllerHost = Reflect.getMetadata('calyx:controller_host', controllerClass);
         for (const method of methods) {
           const routeMeta = Reflect.getMetadata(METADATA_KEYS.HTTP_METHOD, controllerClass.prototype, method);
           if (!routeMeta) continue;
@@ -275,7 +320,13 @@ export class CalyxApplication {
           // Normalize prefix and path
           const normalizedPrefix = prefix.replace(/^\/|\/$/g, '');
           const normalizedPath = routeMeta.path.replace(/^\/|\/$/g, '');
-          const fullPath = '/' + [normalizedPrefix, normalizedPath].filter(Boolean).join('/');
+          const baseRoutePath = '/' + [normalizedPrefix, normalizedPath].filter(Boolean).join('/');
+          
+          let fullPath = baseRoutePath;
+          if (this.globalPrefix && !this.isRouteExcludedFromGlobalPrefix(baseRoutePath, routeMeta.method)) {
+            const cleanGlobal = this.globalPrefix.replace(/^\/|\/$/g, '');
+            fullPath = '/' + [cleanGlobal, normalizedPrefix, normalizedPath].filter(Boolean).join('/');
+          }
 
           const paramsConfig: ParameterConfig[] = Reflect.getMetadata(METADATA_KEYS.HTTP_PARAMS, controllerClass.prototype, method) || [];
           // Sort parameters by index ascending so they map correctly to function arguments
@@ -361,7 +412,14 @@ export class CalyxApplication {
                         Reflect.hasMetadata('calyx:sse', methodFn);
 
           const insertRoute = (methodStr: string, pathStr: string) => {
-            this.router.insert(methodStr, pathStr, {
+            let finalMethod = methodStr;
+            if (controllerHost) {
+              const hasParams = controllerHost.includes(':');
+              finalMethod = hasParams
+                ? `${methodStr}:host-dynamic:${controllerHost}`
+                : `${methodStr}:host:${controllerHost}`;
+            }
+            this.router.insert(finalMethod, pathStr, {
               controllerClass,
               moduleClass,
               instance: singletonInstance,
@@ -388,7 +446,11 @@ export class CalyxApplication {
           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('/');
+              let versionedPath = '/' + [versionPrefix.replace(/^\/|\/$/g, ''), normalizedPrefix, normalizedPath].filter(Boolean).join('/');
+              if (this.globalPrefix && !this.isRouteExcludedFromGlobalPrefix(versionedPath, routeMeta.method)) {
+                const cleanGlobal = this.globalPrefix.replace(/^\/|\/$/g, '');
+                versionedPath = '/' + [cleanGlobal, 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) {
@@ -540,12 +602,27 @@ export class CalyxApplication {
       }
 
       let matched = null;
+      const hostHeader = req.headers.get('host') || '';
+
       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);
+          const vMethod = `${req.method}:v${version}`.toUpperCase();
+          matched = this.router.match(`${vMethod}:host:${hostHeader}`.toUpperCase(), pathname);
+          if (!matched) {
+            matched = this.matchDynamicHost(vMethod, hostHeader, pathname);
+          }
+          if (!matched) {
+            matched = this.router.match(vMethod, pathname);
+          }
         }
       }
+      if (!matched) {
+        matched = this.router.match(`${req.method}:host:${hostHeader}`.toUpperCase(), pathname);
+      }
+      if (!matched) {
+        matched = this.matchDynamicHost(req.method.toUpperCase(), hostHeader, pathname);
+      }
       if (!matched) {
         matched = this.router.match(req.method, pathname);
       }
@@ -723,7 +800,7 @@ export class CalyxApplication {
             case 'headers': val = config.name ? req.headers.get(config.name) : Object.fromEntries(req.headers.entries()); break;
             case 'session': val = (req as any).session; break;
             case 'ip': val = this.server ? (this.server.requestIP(req)?.address ?? req.headers.get('x-forwarded-for') ?? '') : (req.headers.get('x-forwarded-for') ?? ''); break;
-            case 'hostparam': val = config.name ? req.headers.get('host') : req.headers.get('host'); break;
+            case 'hostparam': val = config.name ? params[config.name] : params; break;
             case 'next': val = next; break;
             case 'custom': val = config.factory ? config.factory(config.name, context) : undefined; break;
           }
@@ -986,7 +1063,7 @@ export class CalyxApplication {
           val = this.server ? (this.server.requestIP(req)?.address ?? req.headers.get('x-forwarded-for') ?? '') : (req.headers.get('x-forwarded-for') ?? '');
           break;
         case 'hostparam':
-          val = config.name ? req.headers.get('host') : req.headers.get('host');
+          val = config.name ? params[config.name] : params;
           break;
         case 'next':
           val = () => {};
@@ -1904,6 +1981,58 @@ export class CalyxApplication {
     }
   }
 
+  private isRouteExcludedFromGlobalPrefix(path: string, method: string): boolean {
+    if (!this.globalPrefixOptions?.exclude) return false;
+    const cleanPath = path.replace(/^\/|\/$/g, '');
+    for (const exclusion of this.globalPrefixOptions.exclude) {
+      if (typeof exclusion === 'string') {
+        if (exclusion.replace(/^\/|\/$/g, '') === cleanPath) return true;
+      } else {
+        const cleanExclPath = exclusion.path.replace(/^\/|\/$/g, '');
+        const exclMethod = String(exclusion.method).toUpperCase();
+        if (cleanExclPath === cleanPath && (exclMethod === 'ALL' || exclMethod === method.toUpperCase())) {
+          return true;
+        }
+      }
+    }
+    return false;
+  }
+
+  private matchDynamicHost(method: string, hostHeader: string, pathname: string): any {
+    const routes = this.router.getRoutes();
+    for (const route of routes) {
+      if (route.method.startsWith(method + ':host-dynamic:')) {
+        const hostPattern = route.method.substring((method + ':host-dynamic:').length);
+        const params = this.matchHostPattern(hostPattern, hostHeader);
+        if (params) {
+          const matched = this.router.match(route.method, pathname);
+          if (matched) {
+            matched.params = { ...matched.params, ...params };
+            return matched;
+          }
+        }
+      }
+    }
+    return null;
+  }
+
+  private matchHostPattern(pattern: string, host: string): Record<string, string> | null {
+    const patternSegments = pattern.split('.');
+    const hostSegments = host.split('.');
+    if (patternSegments.length !== hostSegments.length) return null;
+    const params: Record<string, string> = {};
+    for (let i = 0; i < patternSegments.length; i++) {
+      const pSeg = patternSegments[i];
+      const hSeg = hostSegments[i];
+      if (pSeg.startsWith(':')) {
+        params[pSeg.slice(1)] = hSeg;
+      } else if (pSeg !== hSeg) {
+        return null;
+      }
+    }
+    return params;
+  }
+
   getRoutes() {
     return this.router.getRoutes();
   }

package/src/http/decorators.ts

@@ -1,9 +1,29 @@
 import 'reflect-metadata';
 import { METADATA_KEYS } from '../core/metadata.ts';
 
-export function Controller(prefix = ''): ClassDecorator {
+export interface ControllerOptions {
+  path?: string;
+  host?: string;
+  scope?: any;
+}
+
+export function Controller(prefixOrOptions?: string | ControllerOptions): ClassDecorator {
   return (target) => {
+    let prefix = '';
+    let host: string | undefined = undefined;
+    if (typeof prefixOrOptions === 'string') {
+      prefix = prefixOrOptions;
+    } else if (prefixOrOptions && typeof prefixOrOptions === 'object') {
+      prefix = prefixOrOptions.path ?? '';
+      host = prefixOrOptions.host;
+      if (prefixOrOptions.scope) {
+        Reflect.defineMetadata(METADATA_KEYS.SCOPE, prefixOrOptions.scope, target);
+      }
+    }
     Reflect.defineMetadata(METADATA_KEYS.CONTROLLER, prefix, target);
+    if (host !== undefined) {
+      Reflect.defineMetadata('calyx:controller_host', host, target);
+    }
   };
 }