@gravito/core 1.6.1 → 2.0.0

package/dist/helpers.d.ts

@@ -0,0 +1,338 @@
+import type { ContentfulStatusCode } from './http/types';
+import type { PlanetCore } from './PlanetCore';
+import type { Router } from './Router';
+export { Arr } from './helpers/Arr';
+export * from './helpers/data';
+export * from './helpers/errors';
+export * from './helpers/response';
+export { Str } from './helpers/Str';
+/**
+ * Error subclass used for dump and die functionality.
+ * @internal
+ */
+export declare class DumpDieError extends Error {
+    readonly values: unknown[];
+    name: string;
+    constructor(values: unknown[]);
+}
+/**
+ * Options for dump output
+ * @public
+ */
+export type DumpOptions = {
+    depth?: number | null;
+    colors?: boolean;
+};
+/**
+ * Dump data to console for debugging.
+ *
+ * Uses `console.dir` with configurable depth and colors to provide a
+ * readable representation of any value.
+ *
+ * @param values - One or more values to dump to the console.
+ *
+ * @example
+ * ```typescript
+ * dump(user, { meta: 'data' });
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
+export declare function dump(...values: unknown[]): void;
+/**
+ * Dump data to console and exit process (or throw in HTTP context).
+ *
+ * Short for "Dump and Die". In a CLI environment, it exits the process.
+ * In an HTTP context (like a web request), it throws a `DumpDieError`
+ * which is caught by the exception handler to display the debug output.
+ *
+ * @param values - One or more values to dump and then die.
+ * @throws {DumpDieError} Always throws this error to halt execution.
+ *
+ * @example
+ * ```typescript
+ * dd(user.permissions);
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
+export declare function dd(...values: unknown[]): never;
+/**
+ * Tap into a value, execute a callback, and return the value.
+ *
+ * This allows you to perform "side effects" on a value without breaking
+ * the chain of operations.
+ *
+ * @param value - The value to tap into.
+ * @param callback - A callback that receives the value.
+ * @returns The original value.
+ *
+ * @example
+ * ```typescript
+ * const user = tap(new User(), (u) => {
+ *   u.name = 'Alice';
+ *   u.save();
+ * });
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
+export declare function tap<T>(value: T, callback: (value: T) => unknown): T;
+/**
+ * Return the default value of the given value.
+ *
+ * If the value is a function, it will be executed with the provided arguments
+ * and its result will be returned. Otherwise, the value itself is returned.
+ * This is useful for handling optional lazy-loaded values.
+ *
+ * @param valueOrFactory - The value or a factory function.
+ * @param args - Arguments to pass to the factory function if it is a function.
+ * @returns The resolved value.
+ *
+ * @example
+ * ```typescript
+ * value(10); // 10
+ * value(() => 10); // 10
+ * value((name) => `Hello ${name}`, 'World'); // "Hello World"
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
+export declare function value<TArgs extends readonly unknown[], TResult>(valueOrFactory: TResult | ((...args: TArgs) => TResult), ...args: TArgs): TResult;
+/**
+ * Determine if the given value is "blank".
+ *
+ * A value is considered blank if it is:
+ * - `null` or `undefined`
+ * - An empty string or a string containing only whitespace
+ * - An empty array
+ * - An empty object
+ * - An empty Map or Set
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is blank, `false` otherwise.
+ *
+ * @example
+ * ```typescript
+ * blank(''); // true
+ * blank('  '); // true
+ * blank([]); // true
+ * blank({}); // true
+ * blank(0); // false
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
+export declare function blank(value: unknown): boolean;
+/**
+ * Determine if the given value is "filled" (not blank).
+ *
+ * This is the inverse of `blank()`.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is not blank, `false` otherwise.
+ *
+ * @example
+ * ```typescript
+ * filled('hello'); // true
+ * filled([1, 2, 3]); // true
+ * filled(''); // false
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
+export declare function filled(value: unknown): boolean;
+/**
+ * Throw an exception if the given condition is true.
+ *
+ * @param condition - The condition to evaluate.
+ * @param error - The exception to throw, a factory function, or an error message string.
+ * @throws {Error} If the condition evaluates to true.
+ *
+ * @example
+ * ```typescript
+ * throwIf(user.isBanned, 'User is banned from the system');
+ * throwIf(count > 100, () => new ValidationError('Too many items'));
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
+export declare function throwIf(condition: unknown, error?: Error | string | (() => Error)): void;
+/**
+ * Throw an exception unless the given condition is true.
+ *
+ * @param condition - The condition to evaluate.
+ * @param error - The exception to throw, a factory function, or an error message string.
+ * @throws {Error} If the condition evaluates to false.
+ *
+ * @example
+ * ```typescript
+ * throwUnless(user.isAdmin, 'Unauthorized access');
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
+export declare function throwUnless(condition: unknown, error?: Error | string | (() => Error)): void;
+/**
+ * Get the value of an environment variable.
+ *
+ * Automatically detects the runtime environment (Bun or Node.js) to retrieve
+ * the variable.
+ *
+ * @param key - The environment variable name.
+ * @param defaultValue - An optional default value to return if the variable is not defined.
+ * @returns The environment variable value or the default value.
+ *
+ * @example
+ * ```typescript
+ * const debug = env('DEBUG', 'false');
+ * const apiKey = env('API_KEY');
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
+export declare function env<TDefault = string | undefined>(key: string, defaultValue?: TDefault): string | TDefault;
+/**
+ * Set the global application instance.
+ *
+ * This is used internally during the bootstrap process to provide global
+ * access to the application instance via the `app()` helper.
+ *
+ * @param core - The PlanetCore instance to set as global.
+ * @internal
+ */
+export declare function setApp(core: PlanetCore | null): void;
+/**
+ * Check if the global application instance has been initialized and set.
+ *
+ * @returns `true` if the application instance is set, `false` otherwise.
+ *
+ * @public
+ * @since 3.0.0
+ */
+export declare function hasApp(): boolean;
+/**
+ * Get the global application instance.
+ *
+ * Provides access to the core application container, configuration, and services.
+ *
+ * @returns The initialized PlanetCore instance.
+ * @throws {Error} If the application has not been initialized.
+ *
+ * @example
+ * ```typescript
+ * const core = app();
+ * console.log(core.version);
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
+export declare function app(): PlanetCore;
+/**
+ * Get a configuration value from the application.
+ *
+ * Supports dot notation for accessing nested configuration properties.
+ *
+ * @param key - The configuration key in dot notation (e.g., 'app.name').
+ * @param defaultValue - An optional default value to return if the key is not found.
+ * @returns The configuration value or the default value.
+ *
+ * @example
+ * ```typescript
+ * const appName = config('app.name');
+ * const port = config('app.port', 3000);
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
+export declare function config<T = unknown>(key: string, defaultValue?: T): T;
+/**
+ * Get the global logger instance.
+ *
+ * Shortcut for `app().logger`.
+ *
+ * @returns The application's logger instance.
+ *
+ * @example
+ * ```typescript
+ * logger().info('Operation completed successfully');
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
+export declare function logger(): import("./Logger").Logger;
+/**
+ * Get the application's primary router instance.
+ *
+ * Shortcut for `app().router`.
+ *
+ * @returns The router instance.
+ *
+ * @public
+ * @since 3.0.0
+ */
+export declare function router(): Router;
+/**
+ * Abort the current request with an HTTP exception.
+ *
+ * Throws an `HttpException` with the specified status code and optional message.
+ *
+ * @param status - The HTTP status code to return.
+ * @param message - An optional custom error message.
+ * @throws {HttpException} Always throws this exception.
+ *
+ * @example
+ * ```typescript
+ * abort(403, 'You do not have permission to access this resource');
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
+export declare function abort(status: ContentfulStatusCode, message?: string): never;
+/**
+ * Abort the request if the given condition is true.
+ *
+ * @param condition - The condition to evaluate.
+ * @param status - The HTTP status code to return.
+ * @param message - An optional custom error message.
+ * @throws {HttpException} If the condition is true.
+ *
+ * @example
+ * ```typescript
+ * abortIf(!user.isActive, 403, 'Account is deactivated');
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
+export declare function abortIf(condition: unknown, status: ContentfulStatusCode, message?: string): void;
+/**
+ * Abort the request unless the given condition is true.
+ *
+ * @param condition - The condition to evaluate.
+ * @param status - The HTTP status code to return.
+ * @param message - An optional custom error message.
+ * @throws {HttpException} If the condition is false.
+ *
+ * @example
+ * ```typescript
+ * abortUnless(request.hasValidToken(), 401, 'Invalid authentication token');
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
+export declare function abortUnless(condition: unknown, status: ContentfulStatusCode, message?: string): void;

package/dist/hooks/ActionManager.d.ts

@@ -0,0 +1,132 @@
+import type { EventBackend } from '../events/EventBackend';
+import type { EventOptions } from '../events/EventOptions';
+import type { AsyncDetector } from './AsyncDetector';
+import type { MigrationWarner } from './MigrationWarner';
+import type { ActionCallback, HookManagerConfig, ListenerInfo, ListenerOptions } from './types';
+/**
+ * 管理 action hook 的登記與執行。
+ *
+ * Action hook 用於觸發副作用（例如發送 email、記錄日誌）。
+ * 支援同步和非同步執行模式，以及透過 EventPriorityQueue 的優先級佇列處理。
+ *
+ * @internal
+ */
+export declare class ActionManager {
+    /**
+     * 儲存所有已登記的 action callbacks。
+     */
+    private actions;
+    private backend;
+    private idempotencyCache;
+    private config;
+    private asyncDetector;
+    private migrationWarner;
+    private aggregationManager?;
+    constructor(backend: EventBackend, config: HookManagerConfig, asyncDetector: AsyncDetector, migrationWarner: MigrationWarner);
+    /**
+     * 更新設定。
+     */
+    updateConfig(config: HookManagerConfig): void;
+    /**
+     * 更新 backend。
+     */
+    setBackend(backend: EventBackend): void;
+    /**
+     * Register an action hook.
+     *
+     * Actions are used to trigger side effects (e.g., logging, sending emails)
+     * at specific points in the application lifecycle.
+     *
+     * @template TArgs - The type of arguments passed to the action.
+     * @param hook - The unique name of the hook.
+     * @param callback - The callback function to execute.
+     * @param options - Optional listener options (type override, circuit breaker).
+     *
+     * @example
+     * ```typescript
+     * actionManager.addAction('user_registered', async (user: User) => {
+     *   await sendWelcomeEmail(user)
+     * })
+     * ```
+     */
+    addAction<TArgs = unknown>(hook: string, callback: ActionCallback<TArgs>, options?: ListenerOptions): void;
+    /**
+     * 判斷是否需要使用非同步 dispatch，並在需要時發出遷移警告。
+     *
+     * 此方法僅判斷 dispatch 模式和發出警告，不執行實際的 dispatch。
+     * 實際執行由 HookManager.doAction 負責，以確保 ObservableHookManager 等子類別
+     * 的多型覆寫（override）能正確攔截 doActionSync / doActionAsync 呼叫。
+     *
+     * @param hook - Hook name
+     * @param args - Event args (unused here, kept for API consistency)
+     * @param options - Event options
+     * @returns 'async' if async dispatch should be used, 'sync' otherwise
+     */
+    resolveDispatchMode<TArgs = unknown>(hook: string, _args: TArgs, options?: EventOptions): 'async' | 'sync';
+    /**
+     * Run all registered actions synchronously (legacy mode).
+     *
+     * @template TArgs - The type of arguments passed to the action.
+     * @param hook - The name of the hook.
+     * @param args - The arguments to pass to the callbacks.
+     */
+    doActionSync<TArgs = unknown>(hook: string, args: TArgs): Promise<void>;
+    /**
+     * Run all registered actions asynchronously via priority queue.
+     *
+     * 透過 EventPriorityQueue 進行非同步 dispatch，支援：
+     * - 優先級處理（high > normal > low）
+     * - 超時處理
+     * - 順序保證（strict、partition、none）
+     * - 冪等性
+     *
+     * @template TArgs - The type of arguments passed to the action.
+     * @param hook - The name of the hook.
+     * @param args - The arguments to pass to the callbacks.
+     * @param options - Event options for async dispatch.
+     */
+    doActionAsync<TArgs = unknown>(hook: string, args: TArgs, options?: EventOptions): Promise<void>;
+    /**
+     * Determine if async dispatch should be used.
+     *
+     * @param callbacks - Callbacks to check
+     * @param options - Event options
+     * @returns True if async dispatch should be used
+     */
+    shouldUseAsyncDispatch(callbacks: ActionCallback[], options?: EventOptions): boolean;
+    /**
+     * Determine the dispatch mode for an event.
+     *
+     * @param hook - Hook name
+     * @param options - Optional event options
+     * @returns The dispatch mode: 'sync' or 'async'
+     */
+    detectMode(hook: string, options?: EventOptions): 'sync' | 'async';
+    /**
+     * Check if any listener for a hook is async (including type overrides).
+     *
+     * @param hook - Hook name
+     * @returns True if any listener is async
+     */
+    hasAsyncListeners(hook: string): boolean;
+    /**
+     * Get detailed information about all listeners for a hook.
+     *
+     * @param hook - Hook name
+     * @returns Array of listener info objects
+     */
+    getListenerInfo(hook: string): ListenerInfo[];
+    /**
+     * Get all registered listeners for a hook.
+     *
+     * @param hook - Hook name
+     * @returns Array of callbacks
+     */
+    getListeners(hook: string): ActionCallback[];
+    /**
+     * Remove all listeners for a specific action hook.
+     *
+     * @param hook - Hook name
+     */
+    removeAction(hook: string): void;
+}

package/dist/hooks/AsyncDetector.d.ts

@@ -0,0 +1,84 @@
+import type { ActionCallback } from './types';
+/**
+ * 負責偵測 callback 函數是否為非同步（async）。
+ *
+ * 提供靜態偵測（透過函數簽名）和運行時偵測（透過執行函數）兩種方式，
+ * 並包含快取機制以提升重複偵測的性能。
+ *
+ * @internal
+ */
+export declare class AsyncDetector {
+    /**
+     * 快取非同步偵測結果（WeakMap 以自動垃圾回收）。
+     */
+    private asyncDetectionCache;
+    /**
+     * 快取中的項目計數（供測試/偵錯使用）。
+     */
+    private asyncDetectionCacheCount;
+    /**
+     * 儲存 listener type override（callback -> type）。
+     */
+    private listenerTypeOverrides;
+    /**
+     * 設定 listener 的 type override。
+     *
+     * @param callback - 目標 callback
+     * @param type - Type override 值
+     */
+    setTypeOverride(callback: ActionCallback, type: 'sync' | 'async' | 'auto'): void;
+    /**
+     * 取得 listener 的 type override。
+     *
+     * @param callback - 目標 callback
+     * @returns Type override 或 undefined
+     */
+    getTypeOverride(callback: ActionCallback): 'sync' | 'async' | 'auto' | undefined;
+    /**
+     * Check if a callback is an async function (with caching).
+     *
+     * Detection methods:
+     * 1. Check cache first
+     * 2. Check type override
+     * 3. Check constructor.name === 'AsyncFunction'
+     * 4. Fallback: Check function string representation
+     *
+     * @param callback - The callback to check
+     * @returns True if the callback is async
+     * @public
+     */
+    isAsyncListener(callback: ActionCallback): boolean;
+    /**
+     * Check if a listener is effectively async (considering type override).
+     *
+     * @param callback - The callback to check
+     * @returns True if the listener should be treated as async
+     */
+    isEffectivelyAsync(callback: ActionCallback): boolean;
+    /**
+     * Runtime detection for functions that return Promises but aren't declared async.
+     *
+     * 此方法會實際執行 callback 來檢查是否回傳 Promise，請謹慎使用。
+     *
+     * @param callback - The callback to check
+     * @param testArgs - Arguments to pass to the callback for testing
+     * @returns True if the callback returns a Promise
+     * @public
+     */
+    isAsyncListenerRuntime<TArgs = unknown>(callback: ActionCallback<TArgs>, testArgs: TArgs): Promise<boolean>;
+    /**
+     * Get the size of the async detection cache (for testing/debugging).
+     *
+     * @returns Number of cached detection results
+     */
+    getCacheSize(): number;
+    /**
+     * Clear the async detection cache.
+     */
+    clearCache(): void;
+    /**
+     * 快取非同步偵測結果。
+     * @internal
+     */
+    private cacheResult;
+}

package/dist/hooks/FilterManager.d.ts

@@ -0,0 +1,71 @@
+import type { FilterCallback } from './types';
+/**
+ * 管理 filter hook 的登記與執行。
+ *
+ * Filter hook 用於轉換數值：每個 callback 接收前一個 callback 的回傳值，
+ * 並返回新的轉換後數值。所有 callback 按登記順序依次執行。
+ *
+ * @internal
+ */
+export declare class FilterManager {
+    /**
+     * 儲存所有已登記的 filter callbacks。
+     * Map key 為 hook 名稱，value 為 callback 陣列。
+     */
+    private filters;
+    /**
+     * Register a filter hook.
+     *
+     * Filters are used to transform a value (input/output) through a chain of
+     * callbacks. Each callback must return the modified value.
+     *
+     * @template T - The type of value being filtered.
+     * @param hook - The unique name of the hook.
+     * @param callback - The callback function to execute.
+     *
+     * @example
+     * ```typescript
+     * filterManager.addFilter('content', async (content: string) => {
+     *   return content.toUpperCase()
+     * })
+     * ```
+     */
+    addFilter<T = unknown>(hook: string, callback: FilterCallback<T>): void;
+    /**
+     * Apply all registered filters sequentially.
+     *
+     * Each callback receives the previous callback's return value.
+     *
+     * @template T - The type of value being filtered.
+     * @param hook - The name of the hook.
+     * @param initialValue - The initial value to filter.
+     * @param args - Additional arguments to pass to the callbacks.
+     * @returns The final filtered value.
+     *
+     * @example
+     * ```typescript
+     * const content = await filterManager.applyFilters('content', 'hello world')
+     * ```
+     */
+    applyFilters<T = unknown>(hook: string, initialValue: T, ...args: unknown[]): Promise<T>;
+    /**
+     * Check if any filters are registered for a hook.
+     *
+     * @param hook - Hook name
+     * @returns True if at least one filter is registered
+     */
+    hasFilters(hook: string): boolean;
+    /**
+     * Get count of registered filters for a hook.
+     *
+     * @param hook - Hook name
+     * @returns Number of registered filters
+     */
+    getFilterCount(hook: string): number;
+    /**
+     * Remove all filters for a specific hook.
+     *
+     * @param hook - Hook name
+     */
+    removeFilters(hook: string): void;
+}

package/dist/hooks/MigrationWarner.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Migration warning manager for deprecation warnings.
+ *
+ * 管理遷移警告訊息，支援透過環境變數抑制特定事件的警告。
+ *
+ * @internal
+ */
+export declare class MigrationWarner {
+    private suppressedWarnings;
+    constructor();
+    /**
+     * 發出遷移警告訊息。
+     *
+     * @param eventName - 事件名稱
+     * @param message - 警告訊息
+     */
+    warn(eventName: string, message: string): void;
+    /**
+     * 抑制特定事件的遷移警告。
+     *
+     * @param eventName - 要抑制警告的事件名稱
+     */
+    suppress(eventName: string): void;
+}