@gravito/ripple 4.0.1 → 4.0.3

package/dist/core/src/hooks/types.d.ts

@@ -0,0 +1,107 @@
+import type { CircuitBreakerOptions } from '../events/CircuitBreaker';
+import type { EventBackend } from '../events/EventBackend';
+import type { EventQueueConfig } from '../events/EventPriorityQueue';
+/**
+ * Callback function for filters (transforms values).
+ * @public
+ */
+export type FilterCallback<T = unknown> = (value: T, ...args: unknown[]) => Promise<T> | T;
+/**
+ * Callback function for actions (side effects).
+ * @public
+ */
+export type ActionCallback<TArgs = unknown> = (args: TArgs) => Promise<void> | void;
+/**
+ * Options for listener registration.
+ * @public
+ */
+export interface ListenerOptions {
+    /**
+     * Explicitly specify the listener type.
+     * - 'sync': Force synchronous dispatch for this listener
+     * - 'async': Force asynchronous dispatch for this listener
+     * - 'auto': Auto-detect based on function signature (default)
+     * @default 'auto'
+     */
+    type?: 'sync' | 'async' | 'auto';
+    /**
+     * Circuit breaker configuration for this listener.
+     */
+    circuitBreaker?: CircuitBreakerOptions;
+}
+/**
+ * Information about a registered listener.
+ * @public
+ */
+export interface ListenerInfo {
+    /**
+     * The callback function.
+     */
+    callback: ActionCallback;
+    /**
+     * Whether the listener is considered async.
+     */
+    isAsync: boolean;
+    /**
+     * The explicit type override, if any.
+     */
+    typeOverride?: 'sync' | 'async' | 'auto';
+}
+/**
+ * Configuration for HookManager.
+ * @public
+ */
+export interface HookManagerConfig {
+    /**
+     * Enable async event dispatch by default.
+     * When true, doAction() will automatically use async dispatch if any listener is async.
+     * @default false
+     */
+    asyncByDefault?: boolean;
+    /**
+     * Migration mode for backward compatibility.
+     * - 'sync': All events use synchronous dispatch (legacy mode)
+     * - 'hybrid': Auto-detect and use async for async listeners (recommended)
+     * - 'async': All events use async dispatch (future mode)
+     * @default 'sync'
+     */
+    migrationMode?: 'sync' | 'hybrid' | 'async';
+    /**
+     * Enable deprecation warnings for synchronous event dispatch.
+     * @default false
+     */
+    showDeprecationWarnings?: boolean;
+    /**
+     * Enable Dead Letter Queue for failed events.
+     * @default true
+     */
+    enableDLQ?: boolean;
+    /**
+     * Configuration for the event priority queue (Backpressure).
+     */
+    queue?: EventQueueConfig;
+    /**
+     * Custom event backend for distributed processing.
+     */
+    backend?: EventBackend;
+    /**
+     * Database connection for persistent DLQ (optional).
+     * If provided, failed events after max retries will be persisted to database.
+     */
+    db?: any;
+    /**
+     * Enable persistent DLQ for failed events (requires db).
+     * @default false
+     */
+    enablePersistentDLQ?: boolean;
+    /**
+     * Message Queue Bridge for distributed event processing via Bull Queue.
+     * When provided, enables dispatchQueued() method for routing events to Redis-backed queue.
+     */
+    messageQueueBridge?: any;
+    /**
+     * Event aggregation configuration (FS-102).
+     * Enables deduplication and micro-batching for improved throughput.
+     */
+    aggregation?: any;
+}

package/dist/core/src/http/CookieJar.d.ts

@@ -23,7 +23,7 @@ export declare class CookieJar {
     private queued;
     constructor(encrypter?: Encrypter | undefined);
     /**
-     * Parse cookies from a Cookie header string
+     * Parse cookies from a Cookie header string using Bun's native CookieMap
      * @param header - The Cookie header value
      * @returns Parsed cookies as key-value pairs
      */
@@ -41,7 +41,7 @@ export declare class CookieJar {
      */
     forget(name: string, options?: CookieOptions): void;
     /**
-     * Serialize a cookie to a Set-Cookie header value
+     * Serialize a cookie to a Set-Cookie header value using Bun's native Cookie API
      */
     private serializeCookie;
     /**

package/dist/core/src/http/types.d.ts

@@ -106,6 +106,11 @@ export interface GravitoRequest {
      * ```
      */
     readonly routePattern?: string;
+    /**
+     * Alias for routePattern (for Hono/Express compatibility)
+     * @deprecated Use `routePattern` instead
+     */
+    readonly routePath?: string;
     /**
      * Get a route parameter value
      * @param name - Parameter name (e.g., 'id' for route '/users/:id')
@@ -164,6 +169,12 @@ export interface GravitoRequest {
      * @throws {Error} If validation was not performed for this target
      */
     valid<T = unknown>(target: ValidationTarget): T;
+    /**
+     * Store validated data for a specific source
+     * @param target - The validation target
+     * @param data - The validated data to store
+     */
+    setValidated(target: ValidationTarget, data: unknown): void;
 }
 /**
  * Options for request forwarding (Proxy)
@@ -199,6 +210,17 @@ export interface ProxyOptions {
 export interface GravitoContext<V extends GravitoVariables = GravitoVariables> {
     /** The incoming request */
     readonly req: GravitoRequest;
+    /**
+     * The response object (for middleware introspection).
+     * Middleware can read response headers and status, or mutate the response.
+     *
+     * @remarks
+     * This property is mutable, allowing middleware to replace the response object.
+     * Example: `c.res = new Response(...)`
+     *
+     * May be undefined until a handler creates a response.
+     */
+    res?: Response;
     /**
      * Send a JSON response
      * @param data - Data to serialize as JSON
@@ -335,7 +357,7 @@ export interface GravitoContext<V extends GravitoVariables = GravitoVariables> {
 /**
  * Next function for middleware chain
  */
-export type GravitoNext = () => Promise<Response | undefined>;
+export type GravitoNext = () => Promise<void>;
 /**
  * GravitoHandler - Standard route handler type
  *
@@ -359,11 +381,10 @@ export type GravitoHandler<V extends GravitoVariables = GravitoVariables> = (ctx
  * const logger: GravitoMiddleware = async (ctx, next) => {
  *   console.log(`${ctx.req.method} ${ctx.req.path}`)
  *   await next()
- *   return undefined
  * }
  * ```
  */
-export type GravitoMiddleware<V extends GravitoVariables = GravitoVariables> = (ctx: GravitoContext<V>, next: GravitoNext) => Response | undefined | Promise<Response | undefined | undefined>;
+export type GravitoMiddleware<V extends GravitoVariables = GravitoVariables> = (ctx: GravitoContext<V>, next: GravitoNext) => Response | void | Promise<Response | void>;
 /**
  * Error handler type
  */