@onebun/core 0.1.7 → 0.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onebun/core",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Core package for OneBun framework - decorators, DI, modules, controllers",
   "license": "LGPL-3.0",
   "author": "RemRyahirev",

package/src/decorators/decorators.test.ts

@@ -481,7 +481,7 @@ describe('decorators', () => {
       expect(route?.params?.[0].type).toBe(ParamType.RESPONSE);
     });
 
-    test('should handle parameter options', () => {
+    test('should handle parameter with schema (optional by default for Query)', () => {
       @Controller()
       class TestController {
         @Get()
@@ -490,6 +490,37 @@ describe('decorators', () => {
         ) {}
       }
 
+      const metadata = getControllerMetadata(TestController);
+      const route = metadata?.routes[0];
+      const param = route?.params?.[0];
+      expect(param?.isRequired).toBe(false); // Query is optional by default
+      expect(param?.schema).toBeDefined();
+    });
+
+    test('should make Query required with { required: true } option', () => {
+      @Controller()
+      class TestController {
+        @Get()
+        test(
+          @Query('filter', { required: true }) filter: string,
+        ) {}
+      }
+
+      const metadata = getControllerMetadata(TestController);
+      const route = metadata?.routes[0];
+      const param = route?.params?.[0];
+      expect(param?.isRequired).toBe(true);
+    });
+
+    test('should make Query with schema required with { required: true } option', () => {
+      @Controller()
+      class TestController {
+        @Get()
+        test(
+          @Query('filter', type('string'), { required: true }) filter: string,
+        ) {}
+      }
+
       const metadata = getControllerMetadata(TestController);
       const route = metadata?.routes[0];
       const param = route?.params?.[0];
@@ -497,6 +528,102 @@ describe('decorators', () => {
       expect(param?.schema).toBeDefined();
     });
 
+    test('should make Header optional by default', () => {
+      @Controller()
+      class TestController {
+        @Get()
+        test(
+          @Header('X-Token') token: string,
+        ) {}
+      }
+
+      const metadata = getControllerMetadata(TestController);
+      const route = metadata?.routes[0];
+      const param = route?.params?.[0];
+      expect(param?.isRequired).toBe(false);
+    });
+
+    test('should make Header required with { required: true } option', () => {
+      @Controller()
+      class TestController {
+        @Get()
+        test(
+          @Header('Authorization', { required: true }) auth: string,
+        ) {}
+      }
+
+      const metadata = getControllerMetadata(TestController);
+      const route = metadata?.routes[0];
+      const param = route?.params?.[0];
+      expect(param?.isRequired).toBe(true);
+    });
+
+    test('should make Param always required (OpenAPI spec)', () => {
+      @Controller()
+      class TestController {
+        @Get(':id')
+        test(
+          @Param('id') id: string,
+        ) {}
+      }
+
+      const metadata = getControllerMetadata(TestController);
+      const route = metadata?.routes[0];
+      const param = route?.params?.[0];
+      expect(param?.isRequired).toBe(true);
+    });
+
+    test('should determine Body required from schema (not accepting undefined)', () => {
+      const bodySchema = type({ name: 'string' });
+
+      @Controller()
+      class TestController {
+        @Post()
+        test(
+          @Body(bodySchema) data: { name: string },
+        ) {}
+      }
+
+      const metadata = getControllerMetadata(TestController);
+      const route = metadata?.routes[0];
+      const param = route?.params?.[0];
+      expect(param?.isRequired).toBe(true); // Schema doesn't accept undefined
+    });
+
+    test('should determine Body optional from schema (accepting undefined)', () => {
+      const bodySchema = type({ name: 'string' }).or(type.undefined);
+
+      @Controller()
+      class TestController {
+        @Post()
+        test(
+          @Body(bodySchema) data: { name: string } | undefined,
+        ) {}
+      }
+
+      const metadata = getControllerMetadata(TestController);
+      const route = metadata?.routes[0];
+      const param = route?.params?.[0];
+      expect(param?.isRequired).toBe(false); // Schema accepts undefined
+    });
+
+    test('should allow explicit override of Body required', () => {
+      const bodySchema = type({ name: 'string' });
+
+      @Controller()
+      class TestController {
+        @Post()
+        test(
+          @Body(bodySchema, { required: false }) data: { name: string },
+        ) {}
+      }
+
+      const metadata = getControllerMetadata(TestController);
+      const route = metadata?.routes[0];
+      const param = route?.params?.[0];
+      expect(param?.isRequired).toBe(false); // Explicitly set to optional
+    });
+
     test('should handle multiple parameters', () => {
       @Controller()
       class TestController {

package/src/decorators/decorators.ts

@@ -1,9 +1,10 @@
 import './metadata'; // Import polyfill first
-import type { Type } from 'arktype';
+import { type, type Type } from 'arktype';
 
 import {
   type ControllerMetadata,
   HttpMethod,
+  type ParamDecoratorOptions,
   type ParamMetadata,
   ParamType,
 } from '../types';
@@ -193,7 +194,7 @@ export function controllerDecorator(basePath: string = '') {
  * Usage: constructor(\@Inject(CounterService) private counterService: CounterService)
  */
 // eslint-disable-next-line @typescript-eslint/naming-convention, @typescript-eslint/no-explicit-any
-export function Inject<T>(type: new (...args: any[]) => T) {
+export function Inject<T>(serviceType: new (...args: any[]) => T) {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/explicit-module-boundary-types
   return (target: any, propertyKey: string | symbol | undefined, parameterIndex: number): void => {
     // Get existing dependencies or create new array
@@ -206,7 +207,7 @@ export function Inject<T>(type: new (...args: any[]) => T) {
     }
 
     // Set the explicit type
-    existingDeps[parameterIndex] = type;
+    existingDeps[parameterIndex] = serviceType;
     META_CONSTRUCTOR_PARAMS.set(target, existingDeps);
   };
 }
@@ -301,62 +302,135 @@ function createRouteDecorator(method: HttpMethod) {
     };
 }
 
+/**
+ * Helper function to check if a schema accepts undefined
+ * Used to determine if @Body is required by default
+ */
+function schemaAcceptsUndefined(schema: Type<unknown>): boolean {
+  return !(schema(undefined) instanceof type.errors);
+}
+
+/**
+ * Helper function to check if value is an arktype schema
+ */
+function isArkTypeSchema(value: unknown): value is Type<unknown> {
+  if (!value) {
+    return false;
+  }
+
+  // ArkType schemas are functions with 'kind' property
+  return (
+    typeof value === 'function' &&
+    ('kind' in value || 'impl' in value || typeof (value as Type<unknown>)({}) !== 'undefined')
+  );
+}
+
+/**
+ * Helper function to check if value is options object
+ */
+function isOptions(value: unknown): value is ParamDecoratorOptions {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+  // Options object has 'required' property or is an empty object
+  const keys = Object.keys(value);
+
+  return keys.length === 0 || keys.every((k) => k === 'required');
+}
+
+/**
+ * Determine isRequired based on param type and options
+ * - PATH: always true (OpenAPI spec)
+ * - BODY: options?.required ?? !schemaAcceptsUndefined(schema) (determined from schema)
+ * - QUERY, HEADER: options?.required ?? false (optional by default)
+ */
+function determineIsRequired(
+  paramType: ParamType,
+  schema: Type<unknown> | undefined,
+  options: ParamDecoratorOptions | undefined,
+): boolean {
+  // PATH parameters are always required per OpenAPI spec
+  if (paramType === ParamType.PATH) {
+    return true;
+  }
+
+  // If options explicitly set required, use that
+  if (options?.required !== undefined) {
+    return options.required;
+  }
+
+  // For BODY, determine from schema
+  if (paramType === ParamType.BODY && schema) {
+    return !schemaAcceptsUndefined(schema);
+  }
+
+  // QUERY, HEADER are optional by default
+  return false;
+}
+
 /**
  * Create parameter decorator factory
- * Supports \@Body(schema), \@Query(schema), \@Param('id', schema) or \@Param('id') for simple cases
+ * Supports multiple signatures:
+ * - \@Param('id') - path parameter (always required)
+ * - \@Query('name') - optional by default
+ * - \@Query('name', { required: true }) - explicitly required
+ * - \@Query('name', schema) - with validation, optional by default
+ * - \@Query('name', schema, { required: true }) - with validation, explicitly required
+ * - \@Body(schema) - required determined from schema
+ * - \@Body(schema, { required: false }) - explicitly optional
+ * - \@Header('X-Token') - optional by default
+ * - \@Header('X-Token', { required: true }) - explicitly required
  */
 function createParamDecorator(paramType: ParamType) {
   return (
-    nameOrSchema?: string | Type<unknown>,
-    schema?: Type<unknown>,
+    nameOrSchema?: string | Type<unknown> | ParamDecoratorOptions,
+    schemaOrOptions?: Type<unknown> | ParamDecoratorOptions,
+    options?: ParamDecoratorOptions,
   ) =>
     (target: object, propertyKey: string, parameterIndex: number) => {
       const params: ParamMetadata[] =
         Reflect.getMetadata(PARAMS_METADATA, target, propertyKey) || [];
 
       let metadata: ParamMetadata;
+      let name = '';
+      let schema: Type<unknown> | undefined;
+      let opts: ParamDecoratorOptions | undefined;
 
-      // Helper function to check if value is an arktype schema
-      const isArkTypeSchema = (value: unknown): value is Type<unknown> => {
-        if (!value) {
-          return false;
+      // Parse arguments based on their types
+      // Case 1: @Body(schema) or @Body(schema, options)
+      if (isArkTypeSchema(nameOrSchema)) {
+        schema = nameOrSchema;
+        if (isOptions(schemaOrOptions)) {
+          opts = schemaOrOptions;
+        }
+      } else if (typeof nameOrSchema === 'string' && isOptions(schemaOrOptions)) {
+        // Case 2: @Query('name', options) - name + options, no schema
+        name = nameOrSchema;
+        opts = schemaOrOptions;
+      } else if (typeof nameOrSchema === 'string' && isArkTypeSchema(schemaOrOptions)) {
+        // Case 3: @Query('name', schema) or @Query('name', schema, options)
+        name = nameOrSchema;
+        schema = schemaOrOptions;
+        if (isOptions(options)) {
+          opts = options;
         }
+      } else if (typeof nameOrSchema === 'string') {
+        // Case 4: @Query('name') or @Body() - simple case
+        name = nameOrSchema;
+      } else if (isOptions(nameOrSchema)) {
+        // Case 5: @Query(options) - options only (edge case)
+        opts = nameOrSchema;
+      }
 
-        // ArkType schemas are functions with 'kind' property
-        return (
-          typeof value === 'function' &&
-          ('kind' in value || 'impl' in value || typeof (value as Type<unknown>)({}) !== 'undefined')
-        );
-      };
+      const isRequired = determineIsRequired(paramType, schema, opts);
 
-      // @Body(schema) or @Query(schema) - first argument is a schema
-      if (isArkTypeSchema(nameOrSchema)) {
-        const schemaValue = nameOrSchema as Type<unknown>;
-        metadata = {
-          type: paramType,
-          name: '',
-          index: parameterIndex,
-          schema: schemaValue,
-          isRequired: true,
-        };
-      } else if (typeof nameOrSchema === 'string' && isArkTypeSchema(schema)) {
-        // @Param('id', schema) or @Query('filter', schema)
-        metadata = {
-          type: paramType,
-          name: nameOrSchema,
-          index: parameterIndex,
-          schema: schema as Type<unknown>,
-          isRequired: true,
-        };
-      } else {
-        // Simple case: @Param('id') or @Query('filter') - no schema, no validation
-        const name = typeof nameOrSchema === 'string' ? nameOrSchema : '';
-        metadata = {
-          type: paramType,
-          name,
-          index: parameterIndex,
-        };
-      }
+      metadata = {
+        type: paramType,
+        name,
+        index: parameterIndex,
+        schema,
+        isRequired,
+      };
 
       params.push(metadata);
 
@@ -366,28 +440,42 @@ function createParamDecorator(paramType: ParamType) {
 
 /**
  * Path parameter decorator
+ * Path parameters are always required per OpenAPI spec
  * @example \@Param('id')
+ * @example \@Param('id', idSchema) - with validation
  */
 // eslint-disable-next-line @typescript-eslint/naming-convention
 export const Param = createParamDecorator(ParamType.PATH);
 
 /**
  * Query parameter decorator
- * @example \@Query('filter')
+ * Optional by default, use { required: true } for required parameters
+ * @example \@Query('filter') - optional
+ * @example \@Query('filter', { required: true }) - required
+ * @example \@Query('filter', schema) - optional with validation
+ * @example \@Query('filter', schema, { required: true }) - required with validation
  */
 // eslint-disable-next-line @typescript-eslint/naming-convention
 export const Query = createParamDecorator(ParamType.QUERY);
 
 /**
  * Body parameter decorator
- * @example \@Body()
+ * Required is determined from schema (accepts undefined = optional)
+ * @example \@Body(schema) - required if schema doesn't accept undefined
+ * @example \@Body(schema.or(type.undefined)) - optional (schema accepts undefined)
+ * @example \@Body(schema, { required: false }) - explicitly optional
+ * @example \@Body(schema, { required: true }) - explicitly required
  */
 // eslint-disable-next-line @typescript-eslint/naming-convention
 export const Body = createParamDecorator(ParamType.BODY);
 
 /**
  * Header parameter decorator
- * @example \@Header('Authorization')
+ * Optional by default, use { required: true } for required parameters
+ * @example \@Header('Authorization') - optional
+ * @example \@Header('Authorization', { required: true }) - required
+ * @example \@Header('Authorization', schema) - optional with validation
+ * @example \@Header('Authorization', schema, { required: true }) - required with validation
  */
 // eslint-disable-next-line @typescript-eslint/naming-convention
 export const Header = createParamDecorator(ParamType.HEADER);

package/src/index.ts

@@ -25,6 +25,7 @@ export {
   type ModuleInstance,
   type TypedEnvSchema,
   type ApplicationOptions,
+  type ParamDecoratorOptions,
   type ParamMetadata,
   type ResponseSchemaMetadata,
   type RouteMetadata,

package/src/types.ts

@@ -452,6 +452,19 @@ export enum ParamType {
   RESPONSE = 'response',
 }
 
+/**
+ * Options for parameter decorators (@Query, @Header, @Body, etc.)
+ */
+export interface ParamDecoratorOptions {
+  /**
+   * Whether the parameter is required
+   * - @Param: always true (OpenAPI spec requirement)
+   * - @Query, @Header: false by default
+   * - @Body: determined from schema (accepts undefined = optional)
+   */
+  required?: boolean;
+}
+
 /**
  * Parameter metadata
  */