@onebun/core 0.1.24 → 0.2.1

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,23 +520,47 @@ export enum ParamType {
   QUERY = 'query',
   BODY = 'body',
   HEADER = 'header',
+  COOKIE = 'cookie',
   REQUEST = 'request',
   RESPONSE = 'response',
+  FILE = 'file',
+  FILES = 'files',
+  FORM_FIELD = 'formField',
 }
 
 /**
- * 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;
 }
 
+/**
+ * Options for file upload decorators (@UploadedFile, @UploadedFiles)
+ */
+export interface FileUploadOptions {
+  /** Maximum file size in bytes */
+  maxSize?: number;
+  /** Allowed MIME types, supports wildcards like 'image/*'. Use MimeType enum for convenience. */
+  mimeTypes?: string[];
+  /** Whether the file is required (default: true for @UploadedFile/@UploadedFiles) */
+  required?: boolean;
+}
+
+/**
+ * Options for multiple file upload decorator (@UploadedFiles)
+ */
+export interface FilesUploadOptions extends FileUploadOptions {
+  /** Maximum number of files allowed */
+  maxCount?: number;
+}
+
 /**
  * Parameter metadata
  */
@@ -534,6 +573,10 @@ export interface ParamMetadata {
    * ArkType schema for validation
    */
   schema?: Type<unknown>;
+  /**
+   * File upload options (only for FILE/FILES param types)
+   */
+  fileOptions?: FileUploadOptions & { maxCount?: number };
 }
 
 /**

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;
 

package/src/websocket/ws-handler.ts

@@ -14,6 +14,7 @@ import type {
   WebSocketApplicationOptions,
 } from './ws.types';
 import type { WsHandlerResponse } from './ws.types';
+import type { OneBunRequest } from '../types';
 import type { Server, ServerWebSocket } from 'bun';
 
 import type { SyncLogger } from '@onebun/logger';
@@ -121,7 +122,7 @@ export class WsHandler {
   /**
    * Initialize gateways with server
    */
-  initializeGateways(server: Server): void {
+  initializeGateways(server: Server<WsClientData>): void {
     for (const [_, gateway] of this.gateways) {
       gateway.instance._initialize(this.storage, server);
     }
@@ -182,8 +183,8 @@ export class WsHandler {
    * Handle WebSocket upgrade request
    */
   async handleUpgrade(
-    req: Request,
-    server: Server,
+    req: OneBunRequest | Request,
+    server: Server<WsClientData>,
   ): Promise<Response | undefined> {
     const url = new URL(req.url);
     const path = url.pathname;

package/src/websocket/ws.types.ts

@@ -294,7 +294,7 @@ export interface WsGuard {
  */
 export interface WsServer {
   /** Bun server instance */
-  server: Server;
+  server: Server<WsClientData>;
   /** Publish message to a topic */
   publish(topic: string, message: string | Buffer): void;
   /** Get subscriber count for a topic */