@onebun/core 0.1.23 → 0.2.0

package/src/decorators/decorators.test.ts

@@ -11,6 +11,7 @@ import {
   expect,
   beforeEach,
   afterEach,
+  mock,
 } from 'bun:test';
 
 import { OneBunApplication } from '../application';
@@ -817,50 +818,63 @@ describe('decorators', () => {
     });
 
     test('should properly inject module service into controller without @Inject', async () => {
-      @Service()
-      class TestService extends BaseService {
-        getValue() {
-          return 'injected-value';
+      // Mock Bun.serve to avoid starting a real server
+      const originalServe = Bun.serve;
+       
+      (Bun as any).serve = mock(() => ({
+        stop: mock(),
+        port: 3000,
+      }));
+
+      try {
+        @Service()
+        class TestService extends BaseService {
+          getValue() {
+            return 'injected-value';
+          }
         }
-      }
 
-      // No @Inject needed - automatic DI via emitDecoratorMetadata
-      @Controller('')
-      class TestController extends BaseController {
-        constructor(private service: TestService) {
-          super();
-        }
+        // No @Inject needed - automatic DI via emitDecoratorMetadata
+        @Controller('')
+        class TestController extends BaseController {
+          constructor(private service: TestService) {
+            super();
+          }
 
-        getServiceValue() {
-          return this.service.getValue();
+          getServiceValue() {
+            return this.service.getValue();
+          }
         }
-      }
 
-      @Module({
-        controllers: [TestController],
-        providers: [TestService],
-      })
-      class TestModule {}
+        @Module({
+          controllers: [TestController],
+          providers: [TestService],
+        })
+        class TestModule {}
 
-      const app = new OneBunApplication(TestModule, {
-        loggerLayer: makeMockLoggerLayer(),
-      });
+        const app = new OneBunApplication(TestModule, {
+          loggerLayer: makeMockLoggerLayer(),
+        });
 
-      // Access rootModule to setup and verify DI
-      const rootModule = (app as any).rootModule;
+        // start() creates rootModule and calls setup, triggering dependency injection
+        await app.start();
 
-      // Setup module to trigger dependency injection
-      const { Effect } = await import('effect');
-      await Effect.runPromise(rootModule.setup());
+        // Access rootModule after start to verify DI
+         
+        const rootModule = (app as any).rootModule;
 
-      // Get controller instance and verify service was injected
-      const controllerInstance = rootModule.getControllerInstance(TestController) as TestController;
+        // Get controller instance and verify service was injected
+        const controllerInstance = rootModule.getControllerInstance(TestController) as TestController;
 
-      expect(controllerInstance).toBeDefined();
-      expect(controllerInstance).toBeInstanceOf(TestController);
+        expect(controllerInstance).toBeDefined();
+        expect(controllerInstance).toBeInstanceOf(TestController);
 
-      // Verify the injected service works correctly
-      expect(controllerInstance.getServiceValue()).toBe('injected-value');
+        // Verify the injected service works correctly
+        expect(controllerInstance.getServiceValue()).toBe('injected-value');
+      } finally {
+         
+        (Bun as any).serve = originalServe;
+      }
     });
   });
 

package/src/decorators/decorators.ts

@@ -493,6 +493,18 @@ export const Body = createParamDecorator(ParamType.BODY);
 // eslint-disable-next-line @typescript-eslint/naming-convention
 export const Header = createParamDecorator(ParamType.HEADER);
 
+/**
+ * Cookie parameter decorator.
+ * Extracts a cookie value by name using BunRequest.cookies (CookieMap).
+ * Optional by default, use { required: true } for required cookies.
+ * @example \@Cookie('session_id') - optional
+ * @example \@Cookie('session_id', { required: true }) - required
+ * @example \@Cookie('session_id', schema) - optional with validation
+ * @example \@Cookie('session_id', schema, { required: true }) - required with validation
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const Cookie = createParamDecorator(ParamType.COOKIE);
+
 /**
  * Request object decorator
  * @example \@Req()

package/src/docs-examples.test.ts

@@ -33,7 +33,12 @@ import type {
   BeforeApplicationDestroy,
   OnApplicationDestroy,
 } from './';
-import type { SseEvent, SseGenerator } from './types';
+import type {
+  SseEvent,
+  SseGenerator,
+  OneBunRequest,
+  OneBunResponse,
+} from './types';
 import type { ServerWebSocket } from 'bun';
 
 
@@ -3431,13 +3436,16 @@ import {
   Body,
   Header,
   Req,
+  Cookie,
   Module,
   Service,
   BaseService,
   BaseController,
   UseMiddleware,
   getServiceTag,
+  getControllerMetadata,
   HttpStatusCode,
+  ParamType,
   NotFoundError,
   InternalServerError,
   OneBunBaseError,
@@ -3829,3 +3837,294 @@ describe('SSE (Server-Sent Events) API Documentation (docs/api/controllers.md)',
     });
   });
 });
+
+// ============================================================================
+// Cookie, Headers, @Req with OneBunRequest
+// ============================================================================
+
+describe('@Cookie Decorator (docs/api/decorators.md)', () => {
+  /**
+   * @source docs/api/decorators.md#cookie
+   */
+  it('should define @Cookie decorator with optional parameter', () => {
+    // From docs: @Cookie('session_id') - optional
+    @Controller('/api')
+    class ApiController extends BaseController {
+      @Get('/me')
+      async getMe(@Cookie('session_id') sessionId?: string) {
+        return { sessionId };
+      }
+    }
+
+    expect(ApiController).toBeDefined();
+    const metadata = getControllerMetadata(ApiController);
+    expect(metadata).toBeDefined();
+    expect(metadata!.routes.length).toBe(1);
+    expect(metadata!.routes[0].params!.length).toBe(1);
+    expect(metadata!.routes[0].params![0].type).toBe(ParamType.COOKIE);
+    expect(metadata!.routes[0].params![0].name).toBe('session_id');
+    expect(metadata!.routes[0].params![0].isRequired).toBe(false);
+  });
+
+  /**
+   * @source docs/api/decorators.md#cookie-required
+   */
+  it('should define @Cookie decorator with required option', () => {
+    // From docs: @Cookie('session_id', { required: true }) - required
+    @Controller('/api')
+    class AuthController extends BaseController {
+      @Get('/protected')
+      async protectedRoute(@Cookie('session_id', { required: true }) sessionId: string) {
+        return { sessionId };
+      }
+    }
+
+    expect(AuthController).toBeDefined();
+    const metadata = getControllerMetadata(AuthController);
+    expect(metadata!.routes[0].params![0].isRequired).toBe(true);
+  });
+
+  /**
+   * @source docs/api/decorators.md#cookie-with-validation
+   */
+  it('should define @Cookie decorator with validation schema', () => {
+    // From docs: @Cookie('session_id', schema) - optional with validation
+    const uuidSchema = type('string');
+
+    @Controller('/api')
+    class ApiController extends BaseController {
+      @Get('/session')
+      async getSession(@Cookie('session_id', uuidSchema) sessionId?: string) {
+        return { sessionId };
+      }
+    }
+
+    expect(ApiController).toBeDefined();
+    const metadata = getControllerMetadata(ApiController);
+    expect(metadata!.routes[0].params![0].schema).toBeDefined();
+  });
+
+  /**
+   * @source docs/api/decorators.md#cookie-combined-example
+   */
+  it('should combine @Cookie with other parameter decorators', () => {
+    // From docs: combining @Cookie, @Param, @Header, @Query
+    @Controller('/api')
+    class CombinedController extends BaseController {
+      @Get('/users/:id')
+      async getUser(
+        @Param('id') id: string,
+        @Query('fields') fields?: string,
+        @Header('Authorization') auth?: string,
+        @Cookie('session') session?: string,
+      ) {
+        return {
+          id, fields, auth, session, 
+        };
+      }
+    }
+
+    expect(CombinedController).toBeDefined();
+    const metadata = getControllerMetadata(CombinedController);
+    expect(metadata!.routes[0].params!.length).toBe(4);
+  });
+});
+
+describe('@Req() with OneBunRequest (docs/api/decorators.md)', () => {
+  /**
+   * @source docs/api/decorators.md#req-onebunrequest
+   */
+  it('should define @Req() handler with OneBunRequest type', () => {
+    // From docs: @Req() with OneBunRequest type
+    // OneBunRequest extends Request with .cookies (CookieMap) and .params
+    @Controller('/api')
+    class ApiController extends BaseController {
+      @Get('/raw')
+      async handleRaw(@Req() req: OneBunRequest) {
+        const url = new URL(req.url);
+
+        // req.cookies is CookieMap, req.params is available from routes API
+        return { url: url.pathname };
+      }
+    }
+
+    expect(ApiController).toBeDefined();
+    const metadata = getControllerMetadata(ApiController);
+    expect(metadata!.routes[0].params![0].type).toBe(ParamType.REQUEST);
+  });
+
+  /**
+   * @source docs/api/decorators.md#req-cookies-access
+   */
+  it('should define handler accessing cookies via req.cookies', () => {
+    // From docs: reading cookies through @Req()
+    @Controller('/api')
+    class ApiController extends BaseController {
+      @Get('/session')
+      async session(@Req() req: OneBunRequest) {
+        // Access cookies via CookieMap
+        const session = req.cookies.get('session');
+
+        return { session };
+      }
+    }
+
+    expect(ApiController).toBeDefined();
+  });
+});
+
+describe('OneBunRequest and OneBunResponse Types (docs/api/decorators.md)', () => {
+  /**
+   * @source docs/api/decorators.md#onebunrequest-type
+   */
+  it('should use OneBunRequest as type alias for BunRequest', () => {
+    // OneBunRequest is an alias for BunRequest
+    // It extends standard Request with .cookies and .params
+    const _check: OneBunRequest extends Request ? true : false = true;
+    expect(_check).toBe(true);
+  });
+
+  /**
+   * @source docs/api/decorators.md#onebunresponse-type
+   */
+  it('should use OneBunResponse as type alias for Response', () => {
+    // OneBunResponse is an alias for Response
+    const response: OneBunResponse = new Response('ok');
+    expect(response).toBeInstanceOf(Response);
+  });
+});
+
+describe('Custom Response Headers (docs/api/controllers.md)', () => {
+  /**
+   * @source docs/api/controllers.md#custom-response-headers
+   */
+  it('should define handler returning Response with custom headers', () => {
+    // From docs: returning Response with custom headers
+    @Controller('/api')
+    class ApiController extends BaseController {
+      @Get('/download')
+      async download() {
+        return new Response(JSON.stringify({ data: 'file content' }), {
+          status: 200,
+          headers: {
+            // eslint-disable-next-line @typescript-eslint/naming-convention
+            'Content-Type': 'application/json',
+            // eslint-disable-next-line @typescript-eslint/naming-convention
+            'X-Custom-Header': 'custom-value',
+          },
+        });
+      }
+    }
+
+    expect(ApiController).toBeDefined();
+  });
+
+  /**
+   * @source docs/api/controllers.md#set-cookie-header
+   */
+  it('should define handler returning Response with Set-Cookie header', () => {
+    // From docs: setting cookies via Set-Cookie header
+    @Controller('/api')
+    class AuthController extends BaseController {
+      @Post('/login')
+       
+      async login(@Body() _body: unknown) {
+        const headers = new Headers();
+        headers.set('Content-Type', 'application/json');
+        headers.append('Set-Cookie', 'session=abc123; Path=/; HttpOnly');
+        headers.append('Set-Cookie', 'theme=dark; Path=/');
+
+        return new Response(JSON.stringify({ loggedIn: true }), {
+          status: 200,
+          headers,
+        });
+      }
+    }
+
+    expect(AuthController).toBeDefined();
+  });
+});
+
+describe('Working with Cookies (docs/api/controllers.md)', () => {
+  /**
+   * @source docs/api/controllers.md#reading-cookies-via-decorator
+   */
+  it('should define handler reading cookies via @Cookie decorator', () => {
+    // From docs: reading cookies via @Cookie('name')
+    @Controller('/api')
+    class PrefsController extends BaseController {
+      @Get('/preferences')
+      async getPrefs(
+        @Cookie('theme') theme?: string,
+        @Cookie('lang') lang?: string,
+      ) {
+        return {
+          theme: theme ?? 'light',
+          lang: lang ?? 'en',
+        };
+      }
+    }
+
+    expect(PrefsController).toBeDefined();
+  });
+
+  /**
+   * @source docs/api/controllers.md#reading-cookies-via-req
+   */
+  it('should define handler reading cookies via req.cookies', () => {
+    // From docs: reading cookies through @Req() with req.cookies.get()
+    @Controller('/api')
+    class ApiController extends BaseController {
+      @Get('/session')
+      async session(@Req() req: OneBunRequest) {
+        const session = req.cookies.get('session');
+
+        return { session };
+      }
+    }
+
+    expect(ApiController).toBeDefined();
+  });
+
+  /**
+   * @source docs/api/controllers.md#setting-cookies-via-req
+   */
+  it('should define handler setting cookies via req.cookies', () => {
+    // From docs: setting cookies using req.cookies.set()
+    @Controller('/api')
+    class AuthController extends BaseController {
+      @Post('/login')
+       
+      async login(@Req() req: OneBunRequest, @Body() _body: unknown) {
+        // Set cookie via CookieMap
+        req.cookies.set('session', 'new-session-id', {
+          httpOnly: true,
+          path: '/',
+          maxAge: 3600,
+        });
+
+        return { loggedIn: true };
+      }
+    }
+
+    expect(AuthController).toBeDefined();
+  });
+
+  /**
+   * @source docs/api/controllers.md#deleting-cookies-via-req
+   */
+  it('should define handler deleting cookies via req.cookies', () => {
+    // From docs: deleting cookies using req.cookies.delete()
+    @Controller('/api')
+    class AuthController extends BaseController {
+      @Post('/logout')
+      async logout(@Req() req: OneBunRequest) {
+        req.cookies.delete('session');
+
+        return { loggedOut: true };
+      }
+    }
+
+    expect(AuthController).toBeDefined();
+  });
+});

package/src/index.ts

@@ -26,6 +26,8 @@ export { Effect, Layer } from 'effect';
 export {
   HttpMethod,
   ParamType,
+  type OneBunRequest,
+  type OneBunResponse,
   type ServiceInterface,
   type ModuleProviders,
   type ModuleInstance,

package/src/module/controller.ts

@@ -1,5 +1,9 @@
 import type { IConfig, OneBunAppConfig } from './config.interface';
-import type { SseEvent, SseOptions } from '../types';
+import type {
+  OneBunRequest,
+  SseEvent,
+  SseOptions,
+} from '../types';
 import type { Context } from 'effect';
 
 import type { SyncLogger } from '@onebun/logger';
@@ -101,14 +105,14 @@ export class Controller {
   /**
    * Check if request has JSON content type
    */
-  protected isJson(req: Request): boolean {
+  protected isJson(req: OneBunRequest | Request): boolean {
     return req.headers.get('content-type')?.includes('application/json') ?? false;
   }
 
   /**
    * Parse JSON from request body
    */
-  protected async parseJson<T = unknown>(req: Request): Promise<T> {
+  protected async parseJson<T = unknown>(req: OneBunRequest | Request): Promise<T> {
     return (await req.json()) as T;
   }
 

package/src/queue/docs-examples.test.ts

@@ -50,6 +50,65 @@ import {
   hasQueueDecorators,
 } from './index';
 
+/**
+ * @source docs/api/queue.md#setup
+ */
+describe('Setup Section Examples (docs/api/queue.md)', () => {
+  it('should register controller with queue decorators in module controllers', () => {
+    // From docs/api/queue.md: Registering Controllers with Queue Decorators
+    class OrderProcessor {
+      @Subscribe('orders.created')
+      async handleOrderCreated(message: Message<{ orderId: string }>) {
+        expect(message.data.orderId).toBeDefined();
+      }
+
+      @Cron(CronExpression.EVERY_HOUR, { pattern: 'cleanup.expired' })
+      getCleanupData() {
+        return { timestamp: Date.now() };
+      }
+    }
+
+    // Verify decorators are registered and auto-discoverable
+    expect(hasQueueDecorators(OrderProcessor)).toBe(true);
+
+    const subscriptions = getSubscribeMetadata(OrderProcessor);
+    expect(subscriptions.length).toBe(1);
+    expect(subscriptions[0].pattern).toBe('orders.created');
+
+    const cronJobs = getCronMetadata(OrderProcessor);
+    expect(cronJobs.length).toBe(1);
+  });
+
+  it('should support error handling with manual ack mode', () => {
+    // From docs/api/queue.md: Error Handling in Handlers
+    class ErrorHandlingProcessor {
+      @Subscribe('orders.created', {
+        ackMode: 'manual',
+        retry: { attempts: 3, backoff: 'exponential', delay: 1000 },
+      })
+      async handleOrder(message: Message<{ orderId: string }>) {
+        try {
+          // process order
+          await message.ack();
+        } catch {
+          if (message.attempt && message.attempt >= (message.maxAttempts || 3)) {
+            await message.ack();
+          } else {
+            await message.nack(true);
+          }
+        }
+      }
+    }
+
+    const subscriptions = getSubscribeMetadata(ErrorHandlingProcessor);
+    expect(subscriptions.length).toBe(1);
+    expect(subscriptions[0].options?.ackMode).toBe('manual');
+    expect(subscriptions[0].options?.retry?.attempts).toBe(3);
+    expect(subscriptions[0].options?.retry?.backoff).toBe('exponential');
+    expect(subscriptions[0].options?.retry?.delay).toBe(1000);
+  });
+});
+
 /**
  * @source docs/api/queue.md#quick-start
  */
@@ -86,6 +145,33 @@ describe('Quick Start Example (docs/api/queue.md)', () => {
     expect(cronJobs[0].expression).toBe(CronExpression.EVERY_HOUR);
     expect(cronJobs[0].options.pattern).toBe('cleanup.expired');
   });
+
+  it('should define service with interval decorator', () => {
+    // From docs/api/queue.md: Quick Start - Interval example
+    class EventProcessor {
+      @Subscribe('orders.created')
+      async handleOrderCreated(message: Message<{ orderId: number }>) {
+        expect(message.data.orderId).toBeDefined();
+      }
+
+      @Cron(CronExpression.EVERY_HOUR, { pattern: 'cleanup.expired' })
+      getCleanupData() {
+        return { timestamp: Date.now() };
+      }
+
+      @Interval(30000, { pattern: 'metrics.collect' })
+      getMetricsData() {
+        return { cpu: process.cpuUsage() };
+      }
+    }
+
+    expect(hasQueueDecorators(EventProcessor)).toBe(true);
+
+    const intervals = getIntervalMetadata(EventProcessor);
+    expect(intervals.length).toBe(1);
+    expect(intervals[0].milliseconds).toBe(30000);
+    expect(intervals[0].options.pattern).toBe('metrics.collect');
+  });
 });
 
 /**

package/src/service-client/service-client.test.ts

@@ -138,7 +138,7 @@ describe('createServiceClient', () => {
           }),
         ),
       );
-      globalThis.fetch = mockFetch;
+      globalThis.fetch = mockFetch as unknown as typeof fetch;
     });
 
     afterEach(() => {

package/src/types.ts

@@ -3,6 +3,21 @@ import type { Effect, Layer } from 'effect';
 
 import type { Logger, LoggerOptions } from '@onebun/logger';
 
+/**
+ * HTTP Request type used in OneBun controllers.
+ * Extends standard Web API Request with:
+ * - `.cookies` (CookieMap) for reading/setting cookies
+ * - `.params` for accessing route parameters
+ * @see https://bun.sh/docs/api/http#bunsrequest
+ */
+export type OneBunRequest = import('bun').BunRequest;
+
+/**
+ * HTTP Response type used in OneBun controllers.
+ * Standard Web API Response.
+ */
+export type OneBunResponse = Response;
+
 /**
  * Base interface for all OneBun services
  */
@@ -505,18 +520,19 @@ export enum ParamType {
   QUERY = 'query',
   BODY = 'body',
   HEADER = 'header',
+  COOKIE = 'cookie',
   REQUEST = 'request',
   RESPONSE = 'response',
 }
 
 /**
- * Options for parameter decorators (@Query, @Header, @Body, etc.)
+ * Options for parameter decorators (@Query, @Header, @Cookie, @Body, etc.)
  */
 export interface ParamDecoratorOptions {
   /**
    * Whether the parameter is required
    * - @Param: always true (OpenAPI spec requirement)
-   * - @Query, @Header: false by default
+   * - @Query, @Header, @Cookie: false by default
    * - @Body: determined from schema (accepts undefined = optional)
    */
   required?: boolean;

package/src/validation/schemas.test.ts

@@ -47,7 +47,6 @@ describe('Validation Schemas', () => {
     test('should create an optional schema that accepts undefined', () => {
       const schema = optionalSchema(stringSchema());
       expect(schema('test')).toBe('test');
-      // @ts-expect-error - Testing that optional schema accepts undefined
       expect(schema(undefined)).toBe(undefined);
       const invalidResult = schema(123);
       expect(invalidResult instanceof type.errors).toBe(true);
@@ -56,7 +55,6 @@ describe('Validation Schemas', () => {
     test('should work with number schema', () => {
       const schema = optionalSchema(numberSchema());
       expect(schema(42)).toBe(42);
-      // @ts-expect-error - Testing that optional schema accepts undefined
       expect(schema(undefined)).toBe(undefined);
       const invalidResult = schema('test');
       expect(invalidResult instanceof type.errors).toBe(true);

package/src/websocket/ws-base-gateway.ts

@@ -49,7 +49,7 @@ export abstract class BaseWebSocketGateway {
   protected storage: WsStorageAdapter | null = null;
 
   /** Bun server reference */
-  protected server: Server | null = null;
+  protected server: Server<WsClientData> | null = null;
 
   /** Unique instance ID (for multi-instance setups) */
   protected instanceId: string = crypto.randomUUID();
@@ -63,7 +63,7 @@ export abstract class BaseWebSocketGateway {
    * Called internally by the framework
    * @internal
    */
-  _initialize(storage: WsStorageAdapter, server: Server): void {
+  _initialize(storage: WsStorageAdapter, server: Server<WsClientData>): void {
     this.storage = storage;
     this.server = server;