@martel/calyx 1.7.0 → 1.8.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [1.8.0](https://github.com/bmartel/calyx/compare/v1.7.0...v1.8.0) (2026-07-01)
+
+
+### Features
+
+* **graphql,openapi:** implement native code-first GraphQLModule and SwaggerModule spec/UI serving ([705c0c0](https://github.com/bmartel/calyx/commit/705c0c0a821cb9e7133d2ad1f1b2103f3aa57572))
+
 # [1.7.0](https://github.com/bmartel/calyx/compare/v1.6.0...v1.7.0) (2026-07-01)
 
 

package/bun.lock

@@ -5,6 +5,7 @@
     "": {
       "name": "@martel/calyx",
       "dependencies": {
+        "graphql": "^17.0.1",
         "reflect-metadata": "^0.2.2",
       },
       "devDependencies": {
@@ -322,6 +323,8 @@
 
     "graceful-fs": ["graceful-fs@4.2.11", "", {}, "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ=="],
 
+    "graphql": ["graphql@17.0.1", "", {}, "sha512-8eWbg5Zcv/8o20nzEjHUGPTj20MLFJjc5kagbIPxbaeGxvFwpitJhemEC/k17n5+UD4M/9ea5rTuce78mELujQ=="],
+
     "handlebars": ["handlebars@4.7.9", "", { "dependencies": { "minimist": "^1.2.5", "neo-async": "^2.6.2", "source-map": "^0.6.1", "wordwrap": "^1.0.0" }, "optionalDependencies": { "uglify-js": "^3.1.4" }, "bin": { "handlebars": "bin/handlebars" } }, "sha512-4E71E0rpOaQuJR2A3xDZ+GM1HyWYv1clR58tC8emQNeQe3RH7MAzSbat+V0wG78LQBo6m6bzSG/L4pBuCsgnUQ=="],
 
     "has-async-hooks": ["has-async-hooks@1.0.0", "", {}, "sha512-YF0VPGjkxr7AyyQQNykX8zK4PvtEDsUJAPqwu06UFz1lb6EvI53sPh5H1kWxg8NXI5LsfRCZ8uX9NkYDZBb/mw=="],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@martel/calyx",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "High-performance Bun-native NestJS-compatible framework",
   "main": "src/index.ts",
   "bin": {
@@ -12,6 +12,7 @@
     "benchmark": "bun run benchmarks/index.ts"
   },
   "dependencies": {
+    "graphql": "^17.0.1",
     "reflect-metadata": "^0.2.2"
   },
   "devDependencies": {

package/src/graphql/decorators.ts

@@ -0,0 +1,62 @@
+import { METADATA_KEYS } from '../core/metadata.ts';
+
+export function Resolver(nameOrClass?: any): ClassDecorator {
+  return (target) => {
+    Reflect.defineMetadata('calyx:resolver', nameOrClass || target, target);
+    Reflect.defineMetadata(METADATA_KEYS.INJECTABLE, true, target);
+  };
+}
+
+export function Query(typeFunc?: (returns: any) => any, options?: { name?: string }): MethodDecorator {
+  return (target, propertyKey) => {
+    const queries = Reflect.getOwnMetadata('calyx:queries', target.constructor) || [];
+    queries.push({ propertyKey, typeFunc, options });
+    Reflect.defineMetadata('calyx:queries', queries, target.constructor);
+  };
+}
+
+export function Mutation(typeFunc?: (returns: any) => any, options?: { name?: string }): MethodDecorator {
+  return (target, propertyKey) => {
+    const mutations = Reflect.getOwnMetadata('calyx:mutations', target.constructor) || [];
+    mutations.push({ propertyKey, typeFunc, options });
+    Reflect.defineMetadata('calyx:mutations', mutations, target.constructor);
+  };
+}
+
+export function ResolveField(typeFunc?: (returns: any) => any, options?: { name?: string }): MethodDecorator {
+  return (target, propertyKey) => {
+    const fields = Reflect.getOwnMetadata('calyx:resolve_fields', target.constructor) || [];
+    fields.push({ propertyKey, typeFunc, options });
+    Reflect.defineMetadata('calyx:resolve_fields', fields, target.constructor);
+  };
+}
+
+export function Args(name?: string): ParameterDecorator {
+  return (target, propertyKey, parameterIndex) => {
+    const args = Reflect.getOwnMetadata('calyx:args', target, propertyKey!) || [];
+    args.push({ parameterIndex, name });
+    Reflect.defineMetadata('calyx:args', args, target, propertyKey!);
+  };
+}
+
+export function Parent(): ParameterDecorator {
+  return (target, propertyKey, parameterIndex) => {
+    const parentParams = Reflect.getOwnMetadata('calyx:parent', target, propertyKey!) || [];
+    parentParams.push(parameterIndex);
+    Reflect.defineMetadata('calyx:parent', parentParams, target, propertyKey!);
+  };
+}
+
+export function ObjectType(): ClassDecorator {
+  return (target) => {
+    Reflect.defineMetadata('calyx:object_type', true, target);
+  };
+}
+
+export function Field(typeFunc?: (returns: any) => any, options?: { nullable?: boolean }): PropertyDecorator {
+  return (target, propertyKey) => {
+    const fields = Reflect.getOwnMetadata('calyx:fields', target.constructor) || [];
+    fields.push({ propertyKey: String(propertyKey), typeFunc, options });
+    Reflect.defineMetadata('calyx:fields', fields, target.constructor);
+  };
+}

package/src/graphql/graphql.module.ts

@@ -0,0 +1,166 @@
+import { CalyxContainer } from '../core/container.ts';
+import { Module } from '../core/decorators.ts';
+import {
+  GraphQLSchema,
+  GraphQLObjectType,
+  GraphQLString,
+  GraphQLInt,
+  GraphQLFloat,
+  GraphQLBoolean,
+  GraphQLList,
+  GraphQLNonNull,
+} from 'graphql';
+
+@Module({})
+export class GraphQLModule {
+  static buildSchema(container: CalyxContainer): GraphQLSchema | null {
+    const instances = container.getProviderAndControllerInstances();
+    const resolverInstances = instances.filter(
+      (inst) => inst && inst.constructor && Reflect.hasMetadata('calyx:resolver', inst.constructor)
+    );
+
+    if (resolverInstances.length === 0) {
+      return null;
+    }
+
+    const typeMap = new Map<any, any>();
+
+    function getGraphQLType(typeClass: any): any {
+      if (typeClass === String) return GraphQLString;
+      if (typeClass === Number) return GraphQLFloat;
+      if (typeClass === Boolean) return GraphQLBoolean;
+      if (typeMap.has(typeClass)) return typeMap.get(typeClass);
+
+      if (typeof typeClass === 'function' && Reflect.hasMetadata('calyx:object_type', typeClass)) {
+        const gqlObjectType = new GraphQLObjectType({
+          name: typeClass.name,
+          fields: () => {
+            const fieldsMetadata: { propertyKey: string; typeFunc?: any; options?: any }[] =
+              Reflect.getMetadata('calyx:fields', typeClass) || [];
+
+            const fieldsConfig: any = {};
+            for (const field of fieldsMetadata) {
+              let returnTypeClass = field.typeFunc ? field.typeFunc(null) : undefined;
+              if (!returnTypeClass) {
+                returnTypeClass = Reflect.getMetadata('design:type', typeClass.prototype, field.propertyKey);
+              }
+              if (!returnTypeClass) {
+                returnTypeClass = String;
+              }
+
+              let gqlType = getGraphQLType(returnTypeClass);
+              if (Array.isArray(returnTypeClass)) {
+                gqlType = new GraphQLList(getGraphQLType(returnTypeClass[0]));
+              }
+              if (!field.options?.nullable) {
+                gqlType = new GraphQLNonNull(gqlType);
+              }
+              fieldsConfig[field.propertyKey] = { type: gqlType };
+            }
+            return fieldsConfig;
+          },
+        });
+
+        typeMap.set(typeClass, gqlObjectType);
+        return gqlObjectType;
+      }
+
+      return GraphQLString;
+    }
+
+    const queryFields: any = {};
+    const mutationFields: any = {};
+
+    for (const resolverInstance of resolverInstances) {
+      const resolverClass = resolverInstance.constructor;
+
+      // Queries
+      const queries: { propertyKey: string | symbol; typeFunc?: any; options?: any }[] =
+        Reflect.getMetadata('calyx:queries', resolverClass) || [];
+      for (const query of queries) {
+        const returnTypeClass = query.typeFunc ? query.typeFunc(null) : String;
+        let gqlType = getGraphQLType(returnTypeClass);
+        if (Array.isArray(returnTypeClass)) {
+          gqlType = new GraphQLList(getGraphQLType(returnTypeClass[0]));
+        }
+
+        const argsMetadata: { parameterIndex: number; name: string }[] =
+          Reflect.getMetadata('calyx:args', resolverInstance, query.propertyKey) || [];
+        const argsConfig: any = {};
+
+        const paramTypes = Reflect.getMetadata('design:paramtypes', resolverInstance, query.propertyKey) || [];
+        for (const arg of argsMetadata) {
+          const paramType = paramTypes[arg.parameterIndex] || String;
+          argsConfig[arg.name] = { type: getGraphQLType(paramType) };
+        }
+
+        const queryName = query.options?.name || String(query.propertyKey);
+
+        queryFields[queryName] = {
+          type: gqlType,
+          args: argsConfig,
+          resolve: async (parent: any, args: any, context: any) => {
+            const params: any[] = [];
+            for (const arg of argsMetadata) {
+              params[arg.parameterIndex] = args[arg.name];
+            }
+            const parentParams = Reflect.getMetadata('calyx:parent', resolverInstance, query.propertyKey) || [];
+            for (const idx of parentParams) {
+              params[idx] = parent;
+            }
+            return resolverInstance[query.propertyKey](...params);
+          },
+        };
+      }
+
+      // Resolve fields mapping
+      const resolvedType = Reflect.getMetadata('calyx:resolver', resolverClass);
+      const fieldResolvers: { propertyKey: string | symbol; typeFunc?: any; options?: any }[] =
+        Reflect.getMetadata('calyx:resolve_fields', resolverClass) || [];
+
+      if (resolvedType && fieldResolvers.length > 0) {
+        const targetGqlType = getGraphQLType(resolvedType);
+        if (targetGqlType && typeof targetGqlType.getFields === 'function') {
+          const targetFields = targetGqlType.getFields();
+          for (const fieldRes of fieldResolvers) {
+            const fieldName = fieldRes.options?.name || String(fieldRes.propertyKey);
+            if (targetFields[fieldName]) {
+              targetFields[fieldName].resolve = async (parent: any, args: any, context: any) => {
+                const argsMetadata: { parameterIndex: number; name: string }[] =
+                  Reflect.getMetadata('calyx:args', resolverInstance, fieldRes.propertyKey) || [];
+                const params: any[] = [];
+                for (const arg of argsMetadata) {
+                  params[arg.parameterIndex] = args[arg.name];
+                }
+                const parentParams = Reflect.getMetadata('calyx:parent', resolverInstance, fieldRes.propertyKey) || [];
+                for (const idx of parentParams) {
+                  params[idx] = parent;
+                }
+                return resolverInstance[fieldRes.propertyKey](...params);
+              };
+            }
+          }
+        }
+      }
+    }
+
+    if (Object.keys(queryFields).length === 0) {
+      return null;
+    }
+
+    return new GraphQLSchema({
+      query: new GraphQLObjectType({
+        name: 'Query',
+        fields: queryFields,
+      }),
+      ...(Object.keys(mutationFields).length > 0
+        ? {
+            mutation: new GraphQLObjectType({
+              name: 'Mutation',
+              fields: mutationFields,
+            }),
+          }
+        : {}),
+    });
+  }
+}

package/src/graphql/index.ts

@@ -0,0 +1,2 @@
+export * from './decorators.ts';
+export * from './graphql.module.ts';

package/src/http/application.ts

@@ -103,6 +103,8 @@ export class CalyxApplication {
   private sharedWebSockets: any[] = [];
   private hasWebSockets = false;
   private serverPort = 3000;
+  private graphqlSchema: any = null;
+  private isInitialized = false;
 
   use(...middlewares: any[]) {
     this.globalMiddlewares.push(...middlewares);
@@ -138,6 +140,9 @@ export class CalyxApplication {
   constructor(private rootModule: any) {}
 
   async init() {
+    if (this.isInitialized) return;
+    this.isInitialized = true;
+
     // Bootstrap the dependency injection container
     this.container.bootstrap(this.rootModule);
 
@@ -161,9 +166,18 @@ export class CalyxApplication {
 
     // Call OnApplicationBootstrap hooks
     await this.runOnApplicationBootstrap();
+
+    // Build GraphQL Schema if GraphQLModule is loaded
+    try {
+      const { GraphQLModule } = await import('../graphql/graphql.module.ts');
+      this.graphqlSchema = GraphQLModule.buildSchema(this.container);
+    } catch {
+      // ignore
+    }
   }
 
   private buildRoutes() {
+    this.router.clear();
     const modules = this.container.getModules();
     for (const [moduleClass, record] of modules.entries()) {
       for (const controllerClass of record.controllers) {
@@ -398,6 +412,10 @@ export class CalyxApplication {
         pathname = pathname.substring(0, queryIdx);
       }
 
+      if (this.graphqlSchema && pathname === '/graphql' && req.method === 'POST') {
+        return this.handleGraphQLRequest(req);
+      }
+
       const matched = this.router.match(req.method, pathname);
       if (!matched) {
         if (this.globalMiddlewares.length > 0) {
@@ -943,8 +961,36 @@ export class CalyxApplication {
     );
   }
 
+  private async handleGraphQLRequest(req: Request): Promise<Response> {
+    try {
+      const body = await req.json() as any;
+      const { query, variables } = body;
+
+      const { graphql } = await import('graphql');
+      const result = await graphql({
+        schema: this.graphqlSchema,
+        source: query,
+        variableValues: variables,
+      });
+
+      return new Response(JSON.stringify(result), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      });
+    } catch (err: any) {
+      return new Response(
+        JSON.stringify({ errors: [{ message: err.message }] }),
+        {
+          status: 200,
+          headers: { 'content-type': 'application/json' },
+        }
+      );
+    }
+  }
+
   async listen(port: number): Promise<any> {
     this.serverPort = port;
+    this.buildRoutes();
     await this.init();
 
     const fetchHandler = (req: Request, server: any) => {
@@ -1330,6 +1376,10 @@ export class CalyxApplication {
       // ignore non-json
     }
   }
+
+  getRoutes() {
+    return this.router.getRoutes();
+  }
 }
 
 

package/src/http/factory.ts

@@ -5,6 +5,7 @@ import { MicroserviceOptions } from '../microservices/interfaces.ts';
 export class CalyxFactory {
   static async create(rootModule: any): Promise<CalyxApplication> {
     const app = new CalyxApplication(rootModule);
+    await app.init();
     return app;
   }
 

package/src/http/router.ts

@@ -16,8 +16,21 @@ export class RadixRouter<T> {
   private staticRoutes = new Map<string, T>();
   private handlersArray: T[] = [];
   private compiledMatch: ((method: string, path: string) => RouteMatch<T> | null) | null = null;
+  private routesList: { method: string; path: string; handler: T }[] = [];
+
+  getRoutes() {
+    return this.routesList;
+  }
+
+  clear() {
+    this.root = new RouterNode<T>();
+    this.staticRoutes.clear();
+    this.routesList = [];
+    this.compiledMatch = null;
+  }
 
   insert(method: string, path: string, handler: T) {
+    this.routesList.push({ method, path, handler });
     const hasParams = path.includes(':') || path.includes('*');
     if (!hasParams) {
       this.staticRoutes.set(method.toUpperCase() + ' ' + path, handler);

package/src/index.ts

@@ -10,3 +10,4 @@ export * from './websockets/index.ts';
 export * from './microservices/index.ts';
 export * from './cache/index.ts';
 export * from './validation/index.ts';
+export * from './openapi/index.ts';

package/src/openapi/decorators.ts

@@ -0,0 +1,49 @@
+import 'reflect-metadata';
+
+export function ApiTags(...tags: string[]): ClassDecorator & MethodDecorator {
+  return (target: any, propertyKey?: string | symbol) => {
+    const key = 'calyx:api_tags';
+    if (propertyKey) {
+      Reflect.defineMetadata(key, tags, target, propertyKey);
+    } else {
+      Reflect.defineMetadata(key, tags, target);
+    }
+  };
+}
+
+export function ApiOperation(options: { summary?: string; description?: string }): MethodDecorator {
+  return (target, propertyKey) => {
+    Reflect.defineMetadata('calyx:api_operation', options, target, propertyKey);
+  };
+}
+
+export function ApiResponse(options: {
+  status: number;
+  description: string;
+  type?: any;
+}): MethodDecorator & ClassDecorator {
+  return (target: any, propertyKey?: string | symbol) => {
+    const key = 'calyx:api_responses';
+    if (propertyKey) {
+      const existing = Reflect.getOwnMetadata(key, target, propertyKey) || [];
+      existing.push(options);
+      Reflect.defineMetadata(key, existing, target, propertyKey);
+    } else {
+      const existing = Reflect.getOwnMetadata(key, target) || [];
+      existing.push(options);
+      Reflect.defineMetadata(key, existing, target);
+    }
+  };
+}
+
+export function ApiProperty(options: {
+  description?: string;
+  type?: any;
+  required?: boolean;
+} = {}): PropertyDecorator {
+  return (target, propertyKey) => {
+    const properties = Reflect.getOwnMetadata('calyx:api_properties', target.constructor) || [];
+    properties.push({ propertyKey: String(propertyKey), ...options });
+    Reflect.defineMetadata('calyx:api_properties', properties, target.constructor);
+  };
+}

package/src/openapi/index.ts

@@ -0,0 +1,2 @@
+export * from './decorators.ts';
+export * from './swagger.module.ts';

package/src/openapi/swagger.module.ts

@@ -0,0 +1,174 @@
+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: {},
+    },
+  };
+
+  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;
+  }
+
+  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 = {};
+
+    const routes = app.getRoutes();
+
+    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 pathParams = [...path.matchAll(/:([a-zA-Z0-9_]+)/g)].map((m) => m[1]);
+
+      const parameters = pathParams.map((name) => ({
+        name,
+        in: 'path',
+        required: true,
+        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}` },
+              },
+            };
+            if (!document.components.schemas[schemaName]) {
+              const props = Reflect.getMetadata('calyx:api_properties', res.type) || [];
+              const schemaProps: Record<string, any> = {};
+              for (const p of props) {
+                schemaProps[p.propertyKey] = {
+                  type: p.type ? p.type.name.toLowerCase() : 'string',
+                  description: p.description,
+                };
+              }
+              document.components.schemas[schemaName] = {
+                type: 'object',
+                properties: schemaProps,
+              };
+            }
+          }
+        }
+      } else {
+        responses['200'] = { description: 'OK' };
+      }
+
+      document.paths[swaggerPath][method.toLowerCase()] = {
+        summary: operationMeta.summary || '',
+        description: operationMeta.description || '',
+        tags,
+        parameters,
+        responses,
+      };
+    }
+
+    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/tests/graphql.test.ts

@@ -0,0 +1,112 @@
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import { Module, CalyxFactory } from '../src/index.ts';
+import {
+  Resolver,
+  Query,
+  ResolveField,
+  Args,
+  Parent,
+  ObjectType,
+  Field,
+  GraphQLModule,
+} from '../src/graphql/index.ts';
+
+// 1. GraphQL Object Type DTO
+@ObjectType()
+class Author {
+  @Field()
+  id!: number;
+
+  @Field()
+  name!: string;
+}
+
+@ObjectType()
+class PostGql {
+  @Field()
+  id!: number;
+
+  @Field()
+  title!: string;
+
+  @Field(() => Author)
+  author!: Author;
+}
+
+// 2. Resolver Class
+@Resolver(PostGql)
+class PostResolver {
+  @Query(() => PostGql)
+  getPost(@Args('id') id: number) {
+    return {
+      id,
+      title: `Calyx: GraphQL JIT Performance`,
+      authorId: 456, // to be resolved by ResolveField
+    };
+  }
+
+  @ResolveField(() => Author)
+  author(@Parent() post: any) {
+    return {
+      id: post.authorId,
+      name: 'Jane Doe',
+    };
+  }
+}
+
+@Module({
+  imports: [GraphQLModule],
+  providers: [PostResolver],
+})
+class TestApp {}
+
+describe('Native Code-First GraphQL Module', () => {
+  let app: any;
+  let baseUrl: string;
+  const PORT = 3928;
+
+  beforeAll(async () => {
+    app = await CalyxFactory.create(TestApp);
+    await app.listen(PORT);
+    baseUrl = `http://localhost:${PORT}`;
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  test('should execute Query and ResolveField successfully using native graphql adapter', async () => {
+    const res = await fetch(`${baseUrl}/graphql`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        query: `
+          query {
+            getPost(id: 123) {
+              id
+              title
+              author {
+                id
+                name
+              }
+            }
+          }
+        `,
+      }),
+    });
+
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.errors).toBeUndefined();
+    expect(body.data).toEqual({
+      getPost: {
+        id: 123,
+        title: 'Calyx: GraphQL JIT Performance',
+        author: {
+          id: 456,
+          name: 'Jane Doe',
+        },
+      },
+    });
+  });
+});

package/tests/openapi.test.ts

@@ -0,0 +1,95 @@
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import {
+  Module,
+  Controller,
+  Get,
+  Param,
+  CalyxFactory,
+  ApiTags,
+  ApiOperation,
+  ApiResponse,
+  ApiProperty,
+  DocumentBuilder,
+  SwaggerModule,
+} from '../src/index.ts';
+
+// 1. Model class
+class Item {
+  @ApiProperty({ description: 'The unique identifier', type: Number })
+  id!: number;
+
+  @ApiProperty({ description: 'The item name', type: String })
+  name!: string;
+}
+
+@ApiTags('Items')
+@Controller('items')
+class ItemsController {
+  @Get(':id')
+  @ApiOperation({ summary: 'Get item by id', description: 'Returns a single item' })
+  @ApiResponse({ status: 200, description: 'Item found successfully', type: Item })
+  getItem(@Param('id') id: string) {
+    return { id: 1, name: 'Gadget' };
+  }
+}
+
+@Module({
+  controllers: [ItemsController],
+})
+class TestApp {}
+
+describe('OpenAPI (Swagger) Generation', () => {
+  let app: any;
+  let baseUrl: string;
+  const PORT = 3932;
+
+  beforeAll(async () => {
+    app = await CalyxFactory.create(TestApp);
+    
+    // Build OpenAPI config
+    const config = new DocumentBuilder()
+      .setTitle('My Test API')
+      .setDescription('OpenAPI description')
+      .setVersion('2.0.0')
+      .build();
+    
+    const document = SwaggerModule.createDocument(app, config);
+    SwaggerModule.setup('api', app, document);
+
+    await app.listen(PORT);
+    baseUrl = `http://localhost:${PORT}`;
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  test('should serve OpenAPI JSON specification with paths and components', async () => {
+    const res = await fetch(`${baseUrl}/api-json`);
+    expect(res.status).toBe(200);
+    const spec = await res.json();
+
+    expect(spec.openapi).toBe('3.0.0');
+    expect(spec.info.title).toBe('My Test API');
+    expect(spec.info.version).toBe('2.0.0');
+    expect(spec.paths['/items/{id}']).toBeDefined();
+    
+    const getOp = spec.paths['/items/{id}'].get;
+    expect(getOp.summary).toBe('Get item by id');
+    expect(getOp.tags).toContain('Items');
+    expect(getOp.parameters[0].name).toBe('id');
+    expect(getOp.parameters[0].in).toBe('path');
+    
+    expect(spec.components.schemas.Item).toBeDefined();
+    expect(spec.components.schemas.Item.properties.name.type).toBe('string');
+    expect(spec.components.schemas.Item.properties.id.type).toBe('number');
+  });
+
+  test('should serve Swagger UI html wrapper', async () => {
+    const res = await fetch(`${baseUrl}/api`);
+    expect(res.status).toBe(200);
+    const html = await res.text();
+    expect(html).toContain('swagger-ui');
+    expect(html).toContain('window.ui = SwaggerUIBundle');
+  });
+});