@martel/calyx 1.10.0 → 1.11.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [1.11.0](https://github.com/bmartel/calyx/compare/v1.10.1...v1.11.0) (2026-07-01)
+
+
+### Features
+
+* **graphql,openapi:** support schema-first compiling, custom context and validation schema auto-enrichment ([e8dcce7](https://github.com/bmartel/calyx/commit/e8dcce78d75097ac88a8a3a984b5834d4d7f1818))
+
+## [1.10.1](https://github.com/bmartel/calyx/compare/v1.10.0...v1.10.1) (2026-07-01)
+
+
+### Performance Improvements
+
+* **graphql,openapi:** implement query AST caching and swagger response caching ([8310045](https://github.com/bmartel/calyx/commit/8310045265512553214a0a4040bc02d5085c77fa))
+
 # [1.10.0](https://github.com/bmartel/calyx/compare/v1.9.0...v1.10.0) (2026-07-01)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@martel/calyx",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "High-performance Bun-native NestJS-compatible framework",
   "main": "src/index.ts",
   "bin": {

package/src/graphql/graphql.module.ts

@@ -1,4 +1,4 @@
-import { CalyxContainer } from '../core/container.ts';
+import { CalyxContainer, DynamicModule } from '../core/container.ts';
 import { Module } from '../core/decorators.ts';
 import {
   GraphQLSchema,
@@ -13,17 +13,42 @@ import {
   GraphQLBoolean,
   GraphQLList,
   GraphQLNonNull,
+  buildSchema as buildGqlSchema,
 } from 'graphql';
 
+export interface GraphQLOptions {
+  typeDefs?: string;
+  context?: (ctx: { req: any }) => any | Promise<any>;
+}
+
 @Module({})
 export class GraphQLModule {
+  static forRoot(options: GraphQLOptions): DynamicModule {
+    return {
+      module: GraphQLModule,
+      providers: [
+        {
+          provide: 'calyx:graphql_options',
+          useValue: options,
+        },
+      ],
+    };
+  }
+
   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) {
+    let options: GraphQLOptions | undefined;
+    try {
+      options = container.getGlobalOrAnyInstance('calyx:graphql_options');
+    } catch {
+      // Options provider not bound, fallback to default code-first
+    }
+
+    if (resolverInstances.length === 0 && !options?.typeDefs) {
       return null;
     }
 
@@ -98,7 +123,12 @@ export class GraphQLModule {
       // Custom Scalar
       if (typeof typeClass === 'function' && Reflect.hasMetadata('calyx:scalar', typeClass)) {
         const scalarMeta = Reflect.getMetadata('calyx:scalar', typeClass);
-        const inst = container.get(typeClass) || new typeClass();
+        let inst: any;
+        try {
+          inst = container.getGlobalOrAnyInstance(typeClass);
+        } catch {
+          inst = new typeClass();
+        }
         const gqlScalar = new GraphQLScalarType({
           name: scalarMeta.name,
           description: Reflect.getMetadata('calyx:description', typeClass),
@@ -480,6 +510,60 @@ export class GraphQLModule {
       }
     }
 
+    // Support Schema-First Approach if typeDefs is specified
+    if (options?.typeDefs) {
+      const schema = buildGqlSchema(options.typeDefs);
+
+      // Attach code-first resolver actions onto schema-first AST definitions
+      const queryType = schema.getQueryType();
+      if (queryType) {
+        const fields = queryType.getFields();
+        for (const [fieldName, field] of Object.entries(fields)) {
+          if (queryFields[fieldName]) {
+            field.resolve = queryFields[fieldName].resolve;
+          }
+        }
+      }
+      const mutationType = schema.getMutationType();
+      if (mutationType) {
+        const fields = mutationType.getFields();
+        for (const [fieldName, field] of Object.entries(fields)) {
+          if (mutationFields[fieldName]) {
+            field.resolve = mutationFields[fieldName].resolve;
+          }
+        }
+      }
+      const subscriptionType = schema.getSubscriptionType();
+      if (subscriptionType) {
+        const fields = subscriptionType.getFields();
+        for (const [fieldName, field] of Object.entries(fields)) {
+          if (subscriptionFields[fieldName]) {
+            field.subscribe = subscriptionFields[fieldName].subscribe;
+            field.resolve = subscriptionFields[fieldName].resolve;
+          }
+        }
+      }
+
+      // Map Custom ObjectType ResolveFields from code-first typeMap
+      for (const [typeClass, codeFirstType] of typeMap.entries()) {
+        if (codeFirstType instanceof GraphQLObjectType) {
+          const typeName = codeFirstType.name;
+          const schemaFirstType = schema.getType(typeName);
+          if (schemaFirstType instanceof GraphQLObjectType) {
+            const codeFirstFields = codeFirstType.getFields();
+            const schemaFirstFields = schemaFirstType.getFields();
+            for (const [fieldName, cfField] of Object.entries(codeFirstFields)) {
+              if (cfField.resolve && schemaFirstFields[fieldName]) {
+                schemaFirstFields[fieldName].resolve = cfField.resolve;
+              }
+            }
+          }
+        }
+      }
+
+      return schema;
+    }
+
     if (Object.keys(queryFields).length === 0) {
       return null;
     }

package/src/http/application.ts

@@ -119,6 +119,7 @@ export class CalyxApplication {
   private hasWebSockets = false;
   private serverPort = 3000;
   private graphqlSchema: any = null;
+  private graphqlQueryCache = new Map<string, any>();
   private isInitialized = false;
   private versioningOptions?: VersioningOptions;
 
@@ -1215,11 +1216,40 @@ export class CalyxApplication {
       const body = await req.json() as any;
       const { query, variables } = body;
 
-      const { graphql } = await import('graphql');
-      const result = await graphql({
+      const { parse, validate, execute } = await import('graphql');
+      
+      let document = this.graphqlQueryCache.get(query);
+      if (!document) {
+        document = parse(query);
+        const errors = validate(this.graphqlSchema, document);
+        if (errors.length > 0) {
+          return new Response(JSON.stringify({ errors }), {
+            status: 200,
+            headers: { 'content-type': 'application/json' },
+          });
+        }
+        this.graphqlQueryCache.set(query, document);
+      }
+
+      let options: any;
+      try {
+        options = this.container.get('calyx:graphql_options');
+      } catch {}
+
+      let contextValue: any = { req };
+      if (options?.context) {
+        contextValue = await options.context({ req });
+        if (contextValue && typeof contextValue === 'object') {
+          contextValue.req = req;
+        } else {
+          contextValue = { req, ...contextValue };
+        }
+      }
+
+      const result = await execute({
         schema: this.graphqlSchema,
-        source: query,
-        contextValue: { req },
+        document,
+        contextValue,
         variableValues: variables,
       });
 
@@ -1321,13 +1351,39 @@ export class CalyxApplication {
           const { id, payload } = data;
           const { query, variables } = payload;
           
-          const { subscribe, parse } = await import('graphql');
+          const { subscribe, parse, validate } = await import('graphql');
           
+          let document = this.graphqlQueryCache.get(query);
+          if (!document) {
+            document = parse(query);
+            const errors = validate(this.graphqlSchema, document);
+            if (errors.length > 0) {
+              ws.send(JSON.stringify({ type: 'error', id, payload: errors }));
+              break;
+            }
+            this.graphqlQueryCache.set(query, document);
+          }
+
+          let options: any;
+          try {
+            options = this.container.get('calyx:graphql_options');
+          } catch {}
+
+          let contextValue: any = { req: ws.data?.req };
+          if (options?.context) {
+            contextValue = await options.context({ req: ws.data?.req });
+            if (contextValue && typeof contextValue === 'object') {
+              contextValue.req = ws.data?.req;
+            } else {
+              contextValue = { req: ws.data?.req, ...contextValue };
+            }
+          }
+
           const subResult = await subscribe({
             schema: this.graphqlSchema,
-            document: parse(query),
+            document,
             variableValues: variables,
-            contextValue: { req: ws.data?.req },
+            contextValue,
           });
           
           if (subResult && Symbol.asyncIterator in subResult) {

package/src/openapi/swagger.module.ts

@@ -73,20 +73,41 @@ export class SwaggerModule {
       if (document.components.schemas[schemaName]) return;
 
       const props = Reflect.getMetadata('calyx:api_properties', typeClass) || [];
+      const rules = Reflect.getMetadata('calyx:validation_rules', 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();
+      const allKeys = new Set<string>();
+      for (const p of props) allKeys.add(p.propertyKey);
+      for (const r of rules) allKeys.add(r.propertyKey);
+
+      for (const key of allKeys) {
+        const p = props.find((x: any) => x.propertyKey === key) || {};
+        const propertyRules = rules.filter((r: any) => r.propertyKey === key);
+
+        let pType = p.type ? (p.type.name ? p.type.name.toLowerCase() : String(p.type).toLowerCase()) : 'string';
+        let format: string | undefined = undefined;
+
+        if (propertyRules.some((r: any) => r.type === 'number')) {
+          pType = 'number';
+        } else if (propertyRules.some((r: any) => r.type === 'string')) {
+          pType = 'string';
+        } else if (propertyRules.some((r: any) => r.type === 'email')) {
+          pType = 'string';
+          format = 'email';
         }
-        schemaProps[p.propertyKey] = {
+
+        schemaProps[key] = {
           type: pType === 'number' || pType === 'boolean' || pType === 'object' || pType === 'array' ? pType : 'string',
-          description: p.description,
+          description: p.description || '',
+          ...(format ? { format } : {}),
         };
-        if (p.required) {
-          requiredProps.push(p.propertyKey);
+
+        const isOptional = propertyRules.some((r: any) => r.type === 'optional');
+        const isRequired = p.required ?? !isOptional;
+
+        if (isRequired) {
+          requiredProps.push(key);
         }
       }
 
@@ -271,12 +292,14 @@ export class SwaggerModule {
     const jsonPath = `/${path}-json`.replace(/\/\/+/g, '/');
     const uiPath = `/${path}`.replace(/\/\/+/g, '/');
 
+    const jsonString = JSON.stringify(document);
+
     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));
+        res.send(jsonString);
         return;
       }
       next();

package/tests/graphql.test.ts

@@ -349,3 +349,104 @@ describe('Native Code-First GraphQL Module', () => {
     ws.close();
   });
 });
+
+describe('Schema-First GraphQL Module', () => {
+  let app: any;
+  let baseUrl: string;
+  const PORT = 3929;
+
+  const typeDefs = `
+    type Author {
+      id: Int!
+      name: String!
+    }
+
+    type PostGql {
+      id: Int!
+      title: String!
+      author: Author!
+    }
+
+    type Query {
+      getPost(id: Int!): PostGql
+    }
+  `;
+
+  @Resolver(PostGql)
+  class SchemaFirstResolver {
+    @Query()
+    getPost(@Args('id') id: number) {
+      return {
+        id,
+        title: 'Schema-First Works!',
+        authorId: 888,
+      };
+    }
+
+    @ResolveField()
+    author(@Parent() post: any) {
+      return {
+        id: post.authorId,
+        name: 'Bob',
+      };
+    }
+  }
+
+  @Module({
+    imports: [
+      GraphQLModule.forRoot({
+        typeDefs,
+        context: async ({ req }) => {
+          return { customVal: 'injected' };
+        },
+      }),
+    ],
+    providers: [SchemaFirstResolver],
+  })
+  class SchemaFirstApp {}
+
+  beforeAll(async () => {
+    app = await CalyxFactory.create(SchemaFirstApp);
+    await app.listen(PORT);
+    baseUrl = `http://baseUrl:${PORT}`;
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  test('should parse typeDefs and bind query/field resolver methods', async () => {
+    const res = await fetch(`http://localhost:${PORT}/graphql`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        query: `
+          query {
+            getPost(id: 42) {
+              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: 42,
+        title: 'Schema-First Works!',
+        author: {
+          id: 888,
+          name: 'Bob',
+        },
+      },
+    });
+  });
+});

package/tests/openapi.test.ts

@@ -19,6 +19,10 @@ import {
   DocumentBuilder,
   SwaggerModule,
   PartialType,
+  IsString,
+  IsNumber,
+  IsOptional,
+  IsEmail,
 } from '../src/index.ts';
 
 // 1. DTO Model
@@ -42,6 +46,22 @@ class CreateItemDto {
 // 3. Partial DTO using mapped type
 class UpdateItemDto extends PartialType(CreateItemDto) {}
 
+// 4. Validation-rich DTO (without explicit @ApiProperty)
+class ValidationRichDto {
+  @IsString()
+  title!: string;
+
+  @IsNumber()
+  amount!: number;
+
+  @IsOptional()
+  @IsString()
+  note?: string;
+
+  @IsEmail()
+  contactEmail!: string;
+}
+
 @ApiTags('Items')
 @ApiBearerAuth('jwt')
 @Controller('items')
@@ -66,6 +86,12 @@ class ItemsController {
   updateItem(@Body() body: UpdateItemDto) {
     return { id: 3, ...body };
   }
+
+  @Post('validate')
+  @ApiOperation({ summary: 'Validation endpoint' })
+  validateDto(@Body() body: ValidationRichDto) {
+    return body;
+  }
 }
 
 @Module({
@@ -150,6 +176,21 @@ describe('OpenAPI (Swagger) Generation', () => {
     expect(spec.components.schemas.UpdateItemDto).toBeDefined();
     expect(spec.components.schemas.UpdateItemDto.required).toBeUndefined(); // all optional
     expect(spec.components.schemas.UpdateItemDto.properties.name.type).toBe('string');
+
+    // 6. Validation Decorator Schema Auto-enrichment
+    expect(spec.components.schemas.ValidationRichDto).toBeDefined();
+    const richSchema = spec.components.schemas.ValidationRichDto;
+    expect(richSchema.properties.title.type).toBe('string');
+    expect(richSchema.properties.amount.type).toBe('number');
+    expect(richSchema.properties.note.type).toBe('string');
+    expect(richSchema.properties.contactEmail.type).toBe('string');
+    expect(richSchema.properties.contactEmail.format).toBe('email');
+
+    // Ensure note is optional, but others are required
+    expect(richSchema.required).toContain('title');
+    expect(richSchema.required).toContain('amount');
+    expect(richSchema.required).toContain('contactEmail');
+    expect(richSchema.required).not.toContain('note');
   });
 
   test('should serve Swagger UI html wrapper', async () => {