@gravito/radiance 1.0.3 → 1.0.5

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

@@ -0,0 +1,135 @@
+/**
+ * FFI (Foreign Function Interface) 類型定義
+ * 支持 bun:ffi 的原生加速層
+ */
+/**
+ * CBOR 編碼/解碼加速器介面
+ * 可由原生 C 實現或 JavaScript 回退實現
+ */
+export interface CborAccelerator {
+    /**
+     * 將任意 JavaScript 物件編碼為 CBOR 二進制格式
+     * @param data - 要編碼的物件（支援：map、string、uint、float64、bytes、null、boolean）
+     * @returns CBOR 編碼的二進制資料
+     */
+    encode(data: Record<string, unknown>): Uint8Array;
+    /**
+     * 將 CBOR 二進制格式解碼為 JavaScript 物件
+     * @param bytes - CBOR 編碼的二進制資料
+     * @returns 解碼後的物件
+     */
+    decode(bytes: Uint8Array): Record<string, unknown>;
+}
+/**
+ * FFI 加速層狀態報告
+ */
+export interface NativeAcceleratorStatus {
+    /**
+     * 原生 FFI 加速是否可用
+     */
+    readonly available: boolean;
+    /**
+     * 當前使用的運行時實現
+     * - 'bun-ffi': Bun C 編譯器（bun:ffi 的 cc()）
+     * - 'js-fallback': 手寫 JavaScript CBOR 實現
+     * - 'cborg': npm 的 cborg 套件（已棄用，僅用於向後相容）
+     */
+    readonly runtime: 'bun-ffi' | 'js-fallback' | 'cborg';
+    /**
+     * 運行時版本或詳細資訊
+     */
+    readonly version: string;
+}
+/**
+ * FFI 層配置選項
+ */
+export interface FfiConfig {
+    /**
+     * 啟用調試日誌
+     * @default false
+     */
+    readonly debug?: boolean;
+    /**
+     * 最大 buffer 大小（位元組）
+     * @default 1048576 (1MB)
+     */
+    readonly maxBufferSize?: number;
+    /**
+     * 強制使用特定的加速器實現
+     * - undefined: 自動選擇（優先 bun-ffi，降級到 js-fallback）
+     * - 'bun-ffi': 只使用原生 C 實現
+     * - 'js-fallback': 只使用 JavaScript 實現
+     */
+    readonly forceImplementation?: 'bun-ffi' | 'js-fallback';
+}
+/**
+ * CBOR Major Type 常數
+ * 符合 RFC 7049 規範
+ */
+export declare const CBOR_MAJOR_TYPES: {
+    readonly UINT: 0;
+    readonly NEGINT: 1;
+    readonly BYTES: 2;
+    readonly TEXT: 3;
+    readonly ARRAY: 4;
+    readonly MAP: 5;
+    readonly TAG: 6;
+    readonly SIMPLE: 7;
+};
+/**
+ * CBOR 簡單值常數
+ */
+export declare const CBOR_SIMPLE_VALUES: {
+    readonly FALSE: 20;
+    readonly TRUE: 21;
+    readonly NULL: 22;
+    readonly UNDEFINED: 23;
+};
+/**
+ * CBOR 長度編碼的附加資訊
+ */
+export declare const CBOR_LENGTH_ENCODING: {
+    readonly SMALL_RANGE_END: 23;
+    readonly UINT8: 24;
+    readonly UINT16: 25;
+    readonly UINT32: 26;
+    readonly UINT64: 27;
+    readonly FLOAT16: 25;
+    readonly FLOAT32: 26;
+    readonly FLOAT64: 27;
+    readonly INDEFINITE: 31;
+};
+/**
+ * 雜湊加速器介面
+ * 可由 Bun 原生實現或 Node.js 回退實現
+ */
+export interface HashAccelerator {
+    /**
+     * SHA-256 雜湊計算
+     * @param input - 輸入（字串或二進制）
+     * @returns 十六進制編碼的 SHA-256 雜湊值（64 字元）
+     */
+    sha256(input: string | Uint8Array): string;
+    /**
+     * HMAC-SHA256 計算
+     * @param key - 密鑰
+     * @param data - 要雜湊的數據
+     * @returns 十六進制編碼的 HMAC-SHA256 值（64 字元）
+     */
+    hmacSha256(key: string, data: string): string;
+}
+/**
+ * 雜湊加速器狀態報告
+ */
+export interface NativeHasherStatus {
+    /**
+     * 雜湊加速層是否可用
+     */
+    readonly available: boolean;
+    /**
+     * 當前使用的運行時實現
+     * - 'bun-crypto-hasher': Bun 原生 CryptoHasher（C 實現，推薦）
+     * - 'node-crypto': node:crypto 回退實現
+     */
+    readonly runtime: 'bun-crypto-hasher' | 'node-crypto';
+}

package/dist/core/src/health/HealthProvider.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview HealthProvider - Cloud-native health checks
+ *
+ * Provides liveness and readiness probes for Kubernetes and cloud deployments
+ *
+ * @module @gravito/core/health
+ * @since 2.2.0
+ */
+import type { Container } from '../Container';
+import type { PlanetCore } from '../PlanetCore';
+import { ServiceProvider } from '../ServiceProvider';
+/**
+ * Health check result
+ * @public
+ */
+export interface HealthCheckResult {
+    /** Health status */
+    status: 'healthy' | 'unhealthy';
+    /** Optional message */
+    message?: string;
+}
+/**
+ * Health check function interface
+ * @public
+ */
+export interface HealthCheck {
+    /** Unique name for this check */
+    name: string;
+    /** Check function that returns health status */
+    check(): Promise<HealthCheckResult>;
+}
+/**
+ * HealthProvider - Provides /health/liveness and /health/readiness endpoints
+ *
+ * - Liveness: Always returns 200 OK (just checks if server is running)
+ * - Readiness: Returns 200 if all checks are healthy, 503 otherwise
+ *
+ * @public
+ */
+export declare class HealthProvider extends ServiceProvider {
+    private checks;
+    register(container: Container): void;
+    /**
+     * Register a health check
+     *
+     * @param check - The health check to register
+     *
+     * @example
+     * ```typescript
+     * const health = core.container.make<HealthProvider>('health')
+     * health.registerCheck({
+     *   name: 'database',
+     *   check: async () => {
+     *     try {
+     *       await db.ping()
+     *       return { status: 'healthy' }
+     *     } catch {
+     *       return { status: 'unhealthy', message: 'DB unreachable' }
+     *     }
+     *   }
+     * })
+     * ```
+     */
+    registerCheck(check: HealthCheck): void;
+    boot(core: PlanetCore): void;
+}
+export default HealthProvider;

package/dist/core/src/helpers/Arr.d.ts

@@ -0,0 +1,19 @@
+import { type DataPath } from './data';
+/**
+ * Array and Collection Helpers.
+ * Provides utility methods for array manipulation and deep object access.
+ * @public
+ */
+export declare const Arr: {
+    readonly get: <TDefault = undefined>(target: unknown, path: DataPath | null | undefined, defaultValue?: TDefault) => unknown | TDefault;
+    readonly has: (target: unknown, path: DataPath | null | undefined) => boolean;
+    readonly set: (target: unknown, path: DataPath, value: unknown, overwrite?: boolean) => unknown;
+    readonly wrap: <T>(value: T | T[] | null | undefined) => T[];
+    readonly first: <T>(items: readonly T[], callback?: (value: T, index: number) => boolean) => T | undefined;
+    readonly last: <T>(items: readonly T[], callback?: (value: T, index: number) => boolean) => T | undefined;
+    readonly only: <T extends Record<string, unknown>>(target: T, keys: readonly string[]) => Partial<T>;
+    readonly except: <T extends Record<string, unknown>>(target: T, keys: readonly string[]) => Partial<T>;
+    readonly flatten: (items: unknown[], depth?: number) => unknown[];
+    readonly pluck: <TItem extends Record<string, unknown>>(items: readonly TItem[], valuePath: DataPath, keyPath?: DataPath) => unknown[] | Record<string, unknown>;
+    readonly where: <T>(items: readonly T[], callback: (value: T, index: number) => boolean) => T[];
+};

package/dist/core/src/helpers/Str.d.ts

@@ -0,0 +1,38 @@
+type StartsEndsNeedle = string | readonly string[];
+/**
+ * String Helper Utilities.
+ * Provides methods for string manipulation, case conversion, and UUID generation.
+ * @public
+ */
+export declare const Str: {
+    readonly lower: (value: string) => string;
+    readonly upper: (value: string) => string;
+    readonly startsWith: (haystack: string, needles: StartsEndsNeedle) => boolean;
+    readonly endsWith: (haystack: string, needles: StartsEndsNeedle) => boolean;
+    readonly contains: (haystack: string, needles: StartsEndsNeedle) => boolean;
+    readonly snake: (value: string) => string;
+    readonly kebab: (value: string) => string;
+    readonly studly: (value: string) => string;
+    readonly camel: (value: string) => string;
+    readonly title: (value: string) => string;
+    readonly limit: (value: string, limit: number, end?: string) => string;
+    readonly slug: (value: string, separator?: string) => string;
+    readonly uuid: () => string;
+    /**
+     * 生成 UUID v7（單調遞增，內含時間戳）。
+     *
+     * Bun 環境使用原生 Bun.randomUUIDv7() (C++ 實作)。
+     * Node.js/Deno 環境使用 RFC 9562 的 JavaScript polyfill。
+     *
+     * UUID v7 的優勢：
+     * - 資料庫主鍵天然有序 → B-tree 索引性能提升 2-10x
+     * - 可從 UUID 提取毫秒級時間戳
+     * - 仍保持全域唯一性
+     *
+     * @returns UUID v7 字串
+     * @public
+     */
+    readonly uuidv7: () => string;
+    readonly random: (length?: number) => string;
+};
+export {};

package/dist/core/src/helpers/data.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Path segment (key) in a data structure.
+ * @public
+ */
+export type PathSegment = string | number;
+/**
+ * Path to a value (dot notation or array of segments).
+ * @public
+ */
+export type DataPath = string | readonly PathSegment[];
+/**
+ * Retrieve a value from a deep object using dot notation.
+ * @public
+ */
+export declare function dataGet<TDefault = undefined>(target: unknown, path: DataPath | null | undefined, defaultValue?: TDefault): unknown | TDefault;
+/**
+ * Check if a key exists in a deep object using dot notation.
+ * @public
+ */
+export declare function dataHas(target: unknown, path: DataPath | null | undefined): boolean;
+/**
+ * Set a value in a deep object using dot notation.
+ * @public
+ */
+export declare function dataSet(target: unknown, path: DataPath, setValue: unknown, overwrite?: boolean): unknown;

package/dist/core/src/helpers/errors.d.ts

@@ -0,0 +1,34 @@
+import type { GravitoContext } from '../http/types';
+/**
+ * Interface for displaying validation errors in views.
+ * @public
+ */
+export interface ErrorBag {
+    /** Check if a field has errors */
+    has(field: string): boolean;
+    /** Get the first error message for a field (or any first error if no field specified) */
+    first(field?: string): string | undefined;
+    /** Get all error messages for a field */
+    get(field: string): string[];
+    /** Get all errors for all fields */
+    all(): Record<string, string[]>;
+    /** Check if there are any errors */
+    any(): boolean;
+    /** Get total number of error messages */
+    count(): number;
+}
+/**
+ * Create a new ErrorBag instance from raw errors.
+ * @public
+ */
+export declare function createErrorBag(errors: Record<string, string[]>): ErrorBag;
+/**
+ * Helper to retrieve the ErrorBag from session flash data.
+ * @public
+ */
+export declare function errors(c: GravitoContext): ErrorBag;
+/**
+ * Helper to retrieve old input value from session flash.
+ * @public
+ */
+export declare function old(c: GravitoContext, field: string, defaultValue?: unknown): unknown;

package/dist/core/src/helpers/response.d.ts

@@ -0,0 +1,41 @@
+import type { ContentfulStatusCode, GravitoContext } from '../http/types';
+/**
+ * Standard API Success Response Structure
+ * @public
+ */
+export type ApiSuccess<T> = {
+    success: true;
+    data: T;
+};
+/**
+ * Standard API Failure Response Structure
+ * @public
+ */
+export type ApiFailure = {
+    success: false;
+    error: {
+        message: string;
+        code?: string;
+        details?: unknown;
+    };
+};
+/**
+ * Create a success response object.
+ * @public
+ */
+export declare function ok<T>(data: T): ApiSuccess<T>;
+/**
+ * Create a failure response object.
+ * @public
+ */
+export declare function fail(message: string, code?: string, details?: unknown): ApiFailure;
+/**
+ * Return a JSON response with standard success structure.
+ * @public
+ */
+export declare function jsonSuccess<T>(c: GravitoContext, data: T, status?: ContentfulStatusCode): Response;
+/**
+ * Return a JSON response with standard failure structure.
+ * @public
+ */
+export declare function jsonFail(c: GravitoContext, message: string, status?: ContentfulStatusCode, code?: string, details?: unknown): Response;

package/dist/core/src/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("@gravito/core").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;