@gravito/core 1.6.0 → 2.0.0

package/dist/hooks/dlq-operations.d.ts

@@ -0,0 +1,60 @@
+import type { DeadLetterQueue } from '../events/DeadLetterQueue';
+import type { EventOptions } from '../events/EventOptions';
+import type { DeadLetterQueueManager } from '../reliability/DeadLetterQueueManager';
+/**
+ * DLQ 操作輔助函式模組。
+ *
+ * 提取自 HookManager 的 DLQ 管理邏輯，以降低 HookManager 複雜度。
+ * 這些函式接受所需依賴作為參數，便於測試與重用。
+ *
+ * @internal
+ */
+/**
+ * 重新加入單一 DLQ 項目到事件佇列。
+ *
+ * @param dlqEntryId - DLQ 項目 ID
+ * @param dlq - 記憶體內 DLQ 實例
+ * @param requeue - 重新加入佇列的回調函式
+ * @returns 是否成功重新加入
+ */
+export declare function requeueDLQEntry(dlqEntryId: string, dlq: DeadLetterQueue, requeue: (eventName: string, payload: unknown, options: EventOptions) => Promise<void>): Promise<boolean>;
+/**
+ * 批次重新加入指定事件名稱的所有 DLQ 項目。
+ *
+ * @param eventName - 事件名稱
+ * @param dlq - 記憶體內 DLQ 實例
+ * @param requeue - 重新加入佇列的回調函式
+ * @returns 成功重新加入的項目數
+ */
+export declare function requeueDLQBatch(eventName: string, dlq: DeadLetterQueue, requeue: (entryId: string) => Promise<boolean>): Promise<number>;
+/**
+ * 建立 EventPriorityQueue 持久化 DLQ 處理器。
+ *
+ * @param persistentDlqManager - 持久化 DLQ 管理器
+ * @returns 持久化 DLQ 處理器函式
+ */
+export declare function createPersistentDLQHandler(persistentDlqManager: DeadLetterQueueManager): (hook: string, args: unknown, options: EventOptions, error: Error, retryCount: number, _firstFailedAt: number) => Promise<void>;
+/**
+ * 重新加入持久化 DLQ 單一項目到事件佇列。
+ *
+ * @param dlqId - 持久化 DLQ 項目 UUID
+ * @param persistentDlqManager - 持久化 DLQ 管理器
+ * @param doActionAsync - 重新加入佇列的回調函式
+ * @returns 是否成功重新加入
+ */
+export declare function requeuePersistentDLQEntry(dlqId: string, persistentDlqManager: DeadLetterQueueManager, doActionAsync: (event: string, args: unknown, options: EventOptions) => Promise<void>): Promise<boolean>;
+/**
+ * 批次重新加入持久化 DLQ 項目。
+ *
+ * @param filter - 過濾條件
+ * @param persistentDlqManager - 持久化 DLQ 管理器
+ * @returns 批次操作結果統計
+ */
+export declare function requeuePersistentDLQBatch(filter: {
+    eventName?: string;
+    status?: 'pending' | 'requeued' | 'resolved' | 'abandoned';
+} | undefined, persistentDlqManager: DeadLetterQueueManager): Promise<{
+    total: number;
+    succeeded: number;
+    failed: number;
+}>;

package/dist/hooks/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Hook subsystem 的公開匯出。
+ *
+ * 此 barrel file 匯出 hook 系統所有的型別定義和子模組。
+ * HookManager facade 已在 ../HookManager.ts 中，對外繼續透過 index.ts 匯出。
+ */
+export { ActionManager } from './ActionManager';
+export { AsyncDetector } from './AsyncDetector';
+export { FilterManager } from './FilterManager';
+export { MigrationWarner } from './MigrationWarner';
+export type { ActionCallback, FilterCallback, HookManagerConfig, ListenerInfo, ListenerOptions, } from './types';

package/dist/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/http/CookieJar.d.ts

@@ -0,0 +1,51 @@
+import type { Encrypter } from '../security/Encrypter';
+import type { GravitoContext } from './types';
+/**
+ * Options for setting cookies
+ * @public
+ */
+export interface CookieOptions {
+    path?: string;
+    domain?: string;
+    secure?: boolean;
+    httpOnly?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+    maxAge?: number;
+    expires?: Date;
+    encrypt?: boolean;
+}
+/**
+ * Utility for managing cookies (request/response/encryption).
+ * @public
+ */
+export declare class CookieJar {
+    private encrypter?;
+    private queued;
+    constructor(encrypter?: Encrypter);
+    /**
+     * 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
+     */
+    static parseCookies(header: string): Record<string, string>;
+    /**
+     * Queue a cookie to be sent with the response
+     */
+    queue(name: string, value: string, minutes?: number, options?: CookieOptions): void;
+    /**
+     * Make a cookie that lasts "forever" (5 years)
+     */
+    forever(name: string, value: string, options?: CookieOptions): void;
+    /**
+     * Expire a cookie
+     */
+    forget(name: string, options?: CookieOptions): void;
+    /**
+     * Serialize a cookie to a Set-Cookie header value using Bun's native Cookie API
+     */
+    private serializeCookie;
+    /**
+     * Attach queued cookies to the context
+     */
+    attach(c: GravitoContext): void;
+}

package/dist/http/cookie.d.ts

@@ -0,0 +1,29 @@
+import { type CookieOptions } from './CookieJar';
+import type { GravitoContext } from './types';
+/**
+ * Get a cookie value from the request
+ * @param c - Context object
+ * @param name - Cookie name
+ * @returns Cookie value or undefined
+ * @public
+ */
+export declare function getCookie(c: GravitoContext, name: string): string | undefined;
+/**
+ * Set a cookie in the response
+ * @param c - Context object
+ * @param name - Cookie name
+ * @param value - Cookie value
+ * @param options - Cookie options
+ * @public
+ */
+export declare function setCookie(c: GravitoContext, name: string, value: string, options?: CookieOptions & {
+    maxAge?: number;
+}): void;
+/**
+ * Delete a cookie (expire it)
+ * @param c - Context object
+ * @param name - Cookie name
+ * @param options - Cookie options (path, domain, etc.)
+ * @public
+ */
+export declare function deleteCookie(c: GravitoContext, name: string, options?: CookieOptions): void;

package/dist/http/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview HTTP Module
+ *
+ * Export all HTTP-related types, utilities, and components.
+ *
+ * @module @gravito/core/http
+ * @since 2.0.0
+ */
+export type { CookieOptions } from './CookieJar';
+export { CookieJar } from './CookieJar';
+export { deleteCookie, getCookie, setCookie } from './cookie';
+export type { ContentfulStatusCode, GravitoContext, GravitoErrorHandler, GravitoHandler, GravitoMiddleware, GravitoNext, GravitoNotFoundHandler, GravitoRequest, GravitoVariables, HttpMethod, StatusCode, ValidationTarget, } from './types';

package/dist/{compat-C4Src6NN.d.cts → http/types.d.ts}

@@ -16,15 +16,15 @@ declare global {
 /**
  * Standard HTTP methods supported by Gravito
  */
-type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'options' | 'head';
+export type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'options' | 'head';
 /**
  * HTTP status codes
  */
-type StatusCode = number;
+export type StatusCode = number;
 /**
  * Content-bearing HTTP status codes (excludes 1xx, 204, 304)
  */
-type ContentfulStatusCode = Exclude<StatusCode, 100 | 101 | 102 | 103 | 204 | 304>;
+export type ContentfulStatusCode = Exclude<StatusCode, 100 | 101 | 102 | 103 | 204 | 304>;
 /**
  * Base context variables available in every request
  * Orbits can extend this interface via module augmentation
@@ -39,7 +39,7 @@ type ContentfulStatusCode = Exclude<StatusCode, 100 | 101 | 102 | 103 | 204 | 30
  * }
  * ```
  */
-interface GravitoVariables {
+export interface GravitoVariables {
     /**
      * The PlanetCore instance
      * @remarks Always available in PlanetCore-managed contexts
@@ -71,7 +71,7 @@ interface GravitoVariables {
 /**
  * Validated request data targets
  */
-type ValidationTarget = 'json' | 'query' | 'param' | 'header' | 'form' | 'cookie';
+export type ValidationTarget = 'json' | 'query' | 'param' | 'header' | 'form' | 'cookie';
 /**
  * GravitoRequest - Unified request interface
  *
@@ -85,7 +85,7 @@ type ValidationTarget = 'json' | 'query' | 'param' | 'header' | 'form' | 'cookie
  * const body = await ctx.req.json<CreateUserDto>()
  * ```
  */
-interface GravitoRequest {
+export interface GravitoRequest {
     /** Full request URL */
     readonly url: string;
     /** HTTP method (uppercase) */
@@ -106,6 +106,11 @@ 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')
@@ -168,7 +173,7 @@ interface GravitoRequest {
 /**
  * Options for request forwarding (Proxy)
  */
-interface ProxyOptions {
+export interface ProxyOptions {
     /** Override or add request headers */
     headers?: Record<string, string>;
     /** Whether to keep the original Host header (default: false) */
@@ -196,9 +201,20 @@ interface ProxyOptions {
  * }
  * ```
  */
-interface GravitoContext<V extends GravitoVariables = GravitoVariables> {
+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
@@ -312,11 +328,30 @@ interface GravitoContext<V extends GravitoVariables = GravitoVariables> {
      * ```
      */
     readonly native: unknown;
+    /**
+     * Access the RequestScopeManager for this request
+     * Services resolved through this manager are scoped to the HTTP request lifetime.
+     */
+    requestScope(): any;
+    /**
+     * Resolve or create a request-scoped service
+     *
+     * @param key - Service key (string or symbol)
+     * @param factory - Factory function to create the service if not cached
+     * @returns The cached or newly created service instance
+     *
+     * @example
+     * ```typescript
+     * // Subsequent calls in the same request return the same instance
+     * const cache = ctx.scoped('product:cache', () => new RequestProductCache())
+     * ```
+     */
+    scoped<T>(key: string | symbol, factory: () => T): T;
 }
 /**
  * Next function for middleware chain
  */
-type GravitoNext = () => Promise<Response | undefined>;
+export type GravitoNext = () => Promise<Response | void>;
 /**
  * GravitoHandler - Standard route handler type
  *
@@ -329,7 +364,7 @@ type GravitoNext = () => Promise<Response | undefined>;
  * }
  * ```
  */
-type GravitoHandler<V extends GravitoVariables = GravitoVariables> = (ctx: GravitoContext<V>) => Response | Promise<Response>;
+export type GravitoHandler<V extends GravitoVariables = GravitoVariables> = (ctx: GravitoContext<V>) => Response | Promise<Response>;
 /**
  * GravitoMiddleware - Standard middleware type
  *
@@ -340,18 +375,15 @@ type GravitoHandler<V extends GravitoVariables = GravitoVariables> = (ctx: Gravi
  * const logger: GravitoMiddleware = async (ctx, next) => {
  *   console.log(`${ctx.req.method} ${ctx.req.path}`)
  *   await next()
- *   return undefined
  * }
  * ```
  */
-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
  */
-type GravitoErrorHandler<V extends GravitoVariables = GravitoVariables> = (error: Error, ctx: GravitoContext<V>) => Response | Promise<Response>;
+export type GravitoErrorHandler<V extends GravitoVariables = GravitoVariables> = (error: Error, ctx: GravitoContext<V>) => Response | Promise<Response>;
 /**
  * Not found handler type
  */
-type GravitoNotFoundHandler<V extends GravitoVariables = GravitoVariables> = (ctx: GravitoContext<V>) => Response | Promise<Response>;
-
-export type { ContentfulStatusCode as C, GravitoVariables as G, HttpMethod as H, ProxyOptions as P, StatusCode as S, ValidationTarget as V, GravitoHandler as a, GravitoMiddleware as b, GravitoErrorHandler as c, GravitoNotFoundHandler as d, GravitoContext as e, GravitoRequest as f, GravitoNext as g };
+export type GravitoNotFoundHandler<V extends GravitoVariables = GravitoVariables> = (ctx: GravitoContext<V>) => Response | Promise<Response>;

package/dist/index.browser.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @gravito/core
+ *
+ * Browser-safe entry point for the core micro-kernel.
+ * Excludes Node.js specific modules like runtime adapters and FFI.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Current version of @gravito/core.
+ * @public
+ */
+export declare const VERSION: string;
+export { GravitoEngineAdapter } from './adapters/GravitoEngineAdapter';
+export type { AdapterConfig, AdapterFactory, HttpAdapter, RouteDefinition } from './adapters/types';
+export { isHttpAdapter } from './adapters/types';
+export type { ContentfulStatusCode, GravitoContext, GravitoErrorHandler, GravitoHandler, GravitoMiddleware, GravitoNext, GravitoNotFoundHandler, GravitoRequest, GravitoVariables, HttpMethod, ProxyOptions, StatusCode, ValidationTarget, } from './http/types';
+export { ConfigManager } from './ConfigManager';
+export { Container, type Factory, type ServiceKey, type ServiceMap } from './Container';
+export { registerQueueCommands } from './cli/queue-commands';
+export { codeFromStatus, ErrorHandler, type ErrorHandlerDeps, messageFromStatus, } from './ErrorHandler';
+export { EventManager } from './EventManager';
+export * from './events';
+export { HookManager, type HookManagerConfig } from './HookManager';
+export { HealthProvider } from './health/HealthProvider';
+export { Arr, abort, abortIf, abortUnless, app, blank, config, DumpDieError, dd, dump, env, filled, hasApp, logger, router, Str, setApp, tap, throwIf, throwUnless, value, } from './helpers';
+export * from './helpers/data';
+export * from './helpers/errors';
+export * from './helpers/response';
+export { CookieJar, type CookieOptions } from './http/CookieJar';
+export { deleteCookie, getCookie, setCookie } from './http/cookie';
+export { ServiceProvider } from './ServiceProvider';
+export * from './runtime/index.browser';
+export declare function defineConfig(config: any): any;