@onebun/core 0.1.1 → 0.1.3

package/src/redis/shared-redis.ts

@@ -0,0 +1,231 @@
+/**
+ * Shared Redis Provider
+ *
+ * Singleton provider for sharing Redis connection across multiple consumers
+ * (cache, websocket, etc.)
+ */
+
+import {
+  Context,
+  Effect,
+  Layer,
+} from 'effect';
+
+import { RedisClient, type RedisClientOptions } from './redis-client';
+
+/**
+ * Options for shared Redis connection
+ */
+export interface SharedRedisOptions {
+  /** Redis connection URL */
+  url: string;
+  /** Key prefix for all operations */
+  keyPrefix?: string;
+  /** Enable automatic reconnection */
+  reconnect?: boolean;
+  /** Enable TLS */
+  tls?: boolean;
+}
+
+/**
+ * Singleton provider for shared Redis connection
+ *
+ * @example
+ * ```typescript
+ * // Configure at app startup
+ * SharedRedisProvider.configure({
+ *   url: 'redis://localhost:6379',
+ *   keyPrefix: 'myapp:',
+ * });
+ *
+ * // Get shared client
+ * const client = await SharedRedisProvider.getClient();
+ *
+ * // Use in cache
+ * const cache = new RedisCache({ useSharedClient: true });
+ *
+ * // Use in WebSocket storage
+ * const wsStorage = new RedisWsStorage(await SharedRedisProvider.getClient());
+ * ```
+ */
+export class SharedRedisProvider {
+  private static instance: RedisClient | null = null;
+  private static options: SharedRedisOptions | null = null;
+  private static connecting: Promise<RedisClient> | null = null;
+
+  /**
+   * Configure the shared Redis connection
+   * Must be called before getClient()
+   */
+  static configure(options: SharedRedisOptions): void {
+    // Note: If already connected, configuration will apply to new connections only
+    SharedRedisProvider.options = options;
+  }
+
+  /**
+   * Get the shared Redis client (creates connection if needed)
+   */
+  static async getClient(): Promise<RedisClient> {
+    // Return existing instance
+    if (SharedRedisProvider.instance?.isConnected()) {
+      return SharedRedisProvider.instance;
+    }
+
+    // Wait for existing connection attempt
+    if (SharedRedisProvider.connecting) {
+      return await SharedRedisProvider.connecting;
+    }
+
+    // Check configuration
+    if (!SharedRedisProvider.options) {
+      throw new Error(
+        'SharedRedisProvider not configured. Call SharedRedisProvider.configure() first.',
+      );
+    }
+
+    // Create new connection
+    SharedRedisProvider.connecting = SharedRedisProvider.createConnection();
+
+    try {
+      SharedRedisProvider.instance = await SharedRedisProvider.connecting;
+
+      return SharedRedisProvider.instance;
+    } finally {
+      SharedRedisProvider.connecting = null;
+    }
+  }
+
+  /**
+   * Create a new Redis connection
+   */
+  private static async createConnection(): Promise<RedisClient> {
+    const options = SharedRedisProvider.options!;
+    const client = new RedisClient({
+      url: options.url,
+      keyPrefix: options.keyPrefix,
+      reconnect: options.reconnect,
+      tls: options.tls,
+    });
+
+    await client.connect();
+
+    return client;
+  }
+
+  /**
+   * Disconnect the shared client
+   */
+  static async disconnect(): Promise<void> {
+    if (SharedRedisProvider.instance) {
+      await SharedRedisProvider.instance.disconnect();
+      SharedRedisProvider.instance = null;
+    }
+  }
+
+  /**
+   * Check if shared client is connected
+   */
+  static isConnected(): boolean {
+    return SharedRedisProvider.instance?.isConnected() ?? false;
+  }
+
+  /**
+   * Check if shared Redis is configured
+   */
+  static isConfigured(): boolean {
+    return SharedRedisProvider.options !== null;
+  }
+
+  /**
+   * Create a standalone Redis client (not shared)
+   * Useful for isolated scenarios
+   */
+  static createClient(options?: Partial<SharedRedisOptions>): RedisClient {
+    const baseOptions: Partial<SharedRedisOptions> = SharedRedisProvider.options || {};
+    const finalOptions: RedisClientOptions = {
+      url: options?.url || baseOptions.url || '',
+      keyPrefix: options?.keyPrefix ?? baseOptions.keyPrefix,
+      reconnect: options?.reconnect ?? baseOptions.reconnect ?? true,
+      tls: options?.tls ?? baseOptions.tls,
+    };
+
+    if (!finalOptions.url) {
+      throw new Error('Redis URL is required');
+    }
+
+    return new RedisClient(finalOptions);
+  }
+
+  /**
+   * Reset provider state (mainly for testing)
+   */
+  static async reset(): Promise<void> {
+    await SharedRedisProvider.disconnect();
+    SharedRedisProvider.options = null;
+  }
+}
+
+// ============================================================================
+// Effect.js Integration
+// ============================================================================
+
+/**
+ * Effect.js Tag for shared Redis service
+ */
+export class SharedRedisService extends Context.Tag('SharedRedisService')<
+  SharedRedisService,
+  RedisClient
+>() {}
+
+/**
+ * Create Effect.js Layer for shared Redis
+ *
+ * @example
+ * ```typescript
+ * const redisLayer = makeSharedRedisLayer({
+ *   url: 'redis://localhost:6379',
+ *   keyPrefix: 'myapp:',
+ * });
+ *
+ * const program = pipe(
+ *   SharedRedisService,
+ *   Effect.flatMap(redis => redis.get('key')),
+ *   Effect.provide(redisLayer),
+ * );
+ * ```
+ */
+export function makeSharedRedisLayer(
+  options: SharedRedisOptions,
+): Layer.Layer<SharedRedisService> {
+  return Layer.scoped(
+    SharedRedisService,
+    Effect.gen(function* () {
+      // Configure shared provider
+      SharedRedisProvider.configure(options);
+
+      // Get client
+      const client = yield* Effect.promise(() => SharedRedisProvider.getClient());
+
+      // Return client with cleanup
+      yield* Effect.addFinalizer(() =>
+        Effect.promise(async () => {
+          // Note: We don't disconnect shared client on scope close
+          // because other consumers might still be using it
+        }),
+      );
+
+      return client;
+    }),
+  );
+}
+
+/**
+ * Get shared Redis client as Effect
+ */
+export const getSharedRedis = Effect.gen(function* () {
+  if (!SharedRedisProvider.isConfigured()) {
+    return yield* Effect.fail(new Error('SharedRedisProvider not configured'));
+  }
+
+  return yield* Effect.promise(() => SharedRedisProvider.getClient());
+});

package/src/{env-resolver.ts → service-client/env-resolver.ts}

@@ -1,4 +1,4 @@
-import type { EnvOverrides, EnvOverrideValue } from './multi-service.types';
+import type { EnvOverrides, EnvOverrideValue } from '../application/multi-service.types';
 
 import {
   type EnvLoadOptions,

package/src/service-client/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Service Client Module
+ *
+ * Type-safe service definitions and clients for inter-service communication.
+ */
+
+export * from './service-client.types';
+export * from './service-definition';
+export * from './service-client';
+export * from './env-resolver';

package/src/{service-client.test.ts → service-client/service-client.test.ts}

@@ -15,10 +15,11 @@ import {
   Post,
   Body,
   Query,
-} from './decorators';
+} from '../decorators/decorators';
+import { HttpMethod } from '../types';
+
 import { createServiceClient, getServiceUrl } from './service-client';
 import { createServiceDefinition } from './service-definition';
-import { HttpMethod } from './types';
 
 // Test controller with various parameter types
 @Controller('/users')

package/src/{service-client.ts → service-client/service-client.ts}

@@ -7,7 +7,7 @@ import type {
 
 import { HttpClient, type HttpMethod as RequestsHttpMethod } from '@onebun/requests';
 
-import { ParamType } from './types';
+import { ParamType } from '../types';
 
 /**
  * Build request parameters from endpoint metadata and arguments

package/src/{service-definition.test.ts → service-client/service-definition.test.ts}

@@ -11,9 +11,10 @@ import {
   Param,
   Post,
   Body,
-} from './decorators';
+} from '../decorators/decorators';
+import { HttpMethod } from '../types';
+
 import { createServiceDefinition } from './service-definition';
-import { HttpMethod } from './types';
 
 // Test controller
 @Controller('/users')

package/src/{service-definition.ts → service-client/service-definition.ts}

@@ -1,5 +1,5 @@
-import { getControllerMetadata, getModuleMetadata } from './decorators';
-import { type HttpMethod, type ParamMetadata } from './types';
+import { getControllerMetadata, getModuleMetadata } from '../decorators/decorators';
+import { type HttpMethod, type ParamMetadata } from '../types';
 
 /**
  * Metadata for a single endpoint

package/src/testing/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Testing Utilities
+ *
+ * Helpers for testing OneBun applications.
+ */
+
+export * from './test-utils';

package/src/types.ts

@@ -6,7 +6,7 @@ import type { Logger } from '@onebun/logger';
 /**
  * Base interface for all OneBun services
  */
-export interface Service {
+export interface ServiceInterface {
   readonly [key: string]: unknown;
 }
 
@@ -17,7 +17,7 @@ export interface ModuleProviders {
   /**
    * Services to provide
    */
-  providers?: Service[];
+  providers?: ServiceInterface[];
 
   /**
    * Controllers to include
@@ -27,7 +27,7 @@ export interface ModuleProviders {
   /**
    * Modules to import
    */
-  imports?: Module[];
+  imports?: ModuleInstance[];
 
   /**
    * Services to export to parent modules
@@ -36,9 +36,9 @@ export interface ModuleProviders {
 }
 
 /**
- * Module interface
+ * Module instance interface
  */
-export interface Module {
+export interface ModuleInstance {
   /**
    * Setup the module
    */
@@ -266,6 +266,85 @@ export interface ApplicationOptions {
       batchTimeout?: number;
     };
   };
+
+  /**
+   * WebSocket configuration
+   */
+  websocket?: WebSocketApplicationOptions;
+
+  /**
+   * Queue configuration
+   */
+  queue?: QueueApplicationOptions;
+
+  /**
+   * Enable graceful shutdown on SIGTERM/SIGINT
+   * When enabled, the application will cleanly shutdown on process signals,
+   * including closing shared Redis connections.
+   * Set to false to disable automatic signal handling.
+   * @defaultValue true
+   */
+  gracefulShutdown?: boolean;
+}
+
+/**
+ * Queue adapter type for application configuration
+ */
+export type QueueAdapterType = 'memory' | 'redis';
+
+/**
+ * Queue configuration for OneBunApplication
+ */
+export interface QueueApplicationOptions {
+  /** Enable/disable queue (default: auto - enabled if handlers exist) */
+  enabled?: boolean;
+  /** Adapter type or custom adapter instance */
+  adapter?: QueueAdapterType;
+  /** Redis-specific options (only used when adapter is 'redis') */
+  redis?: {
+    /** Use shared Redis provider instead of dedicated connection */
+    useSharedProvider?: boolean;
+    /** Redis connection URL (required if not using shared provider) */
+    url?: string;
+    /** Key prefix for Redis keys */
+    prefix?: string;
+  };
+}
+
+/**
+ * WebSocket storage type
+ */
+export type WsStorageType = 'memory' | 'redis';
+
+/**
+ * WebSocket storage options
+ */
+export interface WsStorageOptions {
+  /** Storage type */
+  type: WsStorageType;
+  /** Redis-specific options */
+  redis?: {
+    /** Redis connection URL */
+    url: string;
+    /** Key prefix for Redis keys */
+    prefix?: string;
+  };
+}
+
+/**
+ * WebSocket configuration for OneBunApplication
+ */
+export interface WebSocketApplicationOptions {
+  /** Enable/disable WebSocket (default: auto - enabled if gateways exist) */
+  enabled?: boolean;
+  /** Storage options */
+  storage?: WsStorageOptions;
+  /** Ping interval in milliseconds for heartbeat (socket.io) */
+  pingInterval?: number;
+  /** Ping timeout in milliseconds (socket.io) */
+  pingTimeout?: number;
+  /** Maximum payload size in bytes */
+  maxPayload?: number;
 }
 
 /**

package/src/websocket/index.ts

@@ -0,0 +1,50 @@
+/**
+ * WebSocket Module
+ *
+ * WebSocket gateway system with Socket.IO protocol support.
+ */
+
+// Types (excluding duplicates that come from ws-client.types)
+// Note: WsServer type is exported from ws.types.ts but WsServer decorator is from ws-decorators.ts
+// We export the type as WsServerType to avoid conflict with the decorator
+export {
+  WsHandlerType,
+  WsParamType,
+  isWsMessage,
+  isWsHandlerResponse,
+  isWsClientData,
+  isWsRoom,
+  type WsClientData,
+  type WsAuthData,
+  type WsRoom,
+  type GatewayMetadata,
+  type WsHandlerMetadata,
+  type WsParamMetadata,
+  type WebSocketGatewayOptions,
+  type WsMessage,
+  type WsHandlerResponse,
+  type PatternMatch,
+  type WsExecutionContext,
+  type WsGuard,
+  // Export WsServer type as WsServerType to avoid conflict with WsServer decorator
+  type WsServer as WsServerType,
+} from './ws.types';
+
+export * from './ws-client.types';
+
+// Core
+export * from './ws-base-gateway';
+export * from './ws-handler';
+export * from './ws-decorators';
+export * from './ws-guards';
+export * from './ws-pattern-matcher';
+export * from './ws-socketio-protocol';
+
+// Storage
+export * from './ws-storage';
+export * from './ws-storage-memory';
+export * from './ws-storage-redis';
+
+// Service definition & client
+export * from './ws-service-definition';
+export * from './ws-client';