@gravito/radiance 1.0.4 → 1.0.5

package/dist/core/src/router/ControllerDispatcher.d.ts

@@ -0,0 +1,12 @@
+import type { GravitoHandler } from '../http/types';
+import type { PlanetCore } from '../PlanetCore';
+import type { ControllerClass } from '../Router';
+export declare class ControllerDispatcher {
+    private core;
+    private controllers;
+    constructor(core: PlanetCore);
+    /**
+     * Resolve Controller Instance and Method
+     */
+    resolve(CtrlClass: ControllerClass, methodName: string): GravitoHandler;
+}

package/dist/core/src/router/RequestValidator.d.ts

@@ -0,0 +1,20 @@
+import type { GravitoMiddleware } from '../http/types';
+import { type FormRequestClass } from '../Router';
+/**
+ * Handles validation of incoming requests using FormRequest classes.
+ * Provides mechanisms to detect and convert FormRequest classes into Gravito middleware.
+ */
+export declare class RequestValidator {
+    /**
+     * Check if a value is a FormRequest class.
+     * Optimized with Symbol check, prototype check, and caching.
+     * @internal
+     */
+    static isFormRequestClass(value: unknown): value is FormRequestClass;
+    /**
+     * Convert a FormRequest class to middleware.
+     * Uses instance caching to avoid re-instantiation on every request.
+     * @internal
+     */
+    static formRequestToMiddleware(RequestClass: FormRequestClass): GravitoMiddleware;
+}

package/dist/core/src/runtime/adapter-bun.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Bun runtime adapter implementation.
+ *
+ * @module runtime/adapter-bun
+ * @since 3.2.0
+ */
+import type { RuntimeAdapter } from './types';
+/**
+ * Create a RuntimeAdapter for the Bun runtime.
+ * @internal
+ */
+export declare function createBunAdapter(): RuntimeAdapter;

package/dist/core/src/runtime/adapter-deno.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Deno runtime adapter implementation.
+ *
+ * @module runtime/adapter-deno
+ * @since 3.2.0
+ */
+import type { RuntimeAdapter } from './types';
+/**
+ * Create a RuntimeAdapter for the Deno runtime.
+ * @internal
+ */
+export declare function createDenoAdapter(): RuntimeAdapter;

package/dist/core/src/runtime/adapter-node.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Node.js runtime adapter implementation.
+ *
+ * @module runtime/adapter-node
+ * @since 3.2.0
+ */
+import type { RuntimeAdapter } from './types';
+/**
+ * Create a RuntimeAdapter for the Node.js runtime.
+ * @internal
+ */
+export declare function createNodeAdapter(): RuntimeAdapter;

package/dist/core/src/runtime/adapter-unknown.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Unknown runtime adapter implementation (fallback).
+ *
+ * @module runtime/adapter-unknown
+ * @since 3.2.0
+ */
+import type { RuntimeAdapter } from './types';
+/**
+ * Create a RuntimeAdapter for unsupported runtimes.
+ * All methods throw with descriptive error messages.
+ * @internal
+ */
+export declare function createUnknownAdapter(): RuntimeAdapter;

package/dist/core/src/runtime/archive.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Runtime archive adapter implementations.
+ *
+ * @module runtime/archive
+ * @since 3.2.0
+ */
+import type { ArchiveFromDirectoryOptions, RuntimeArchiveAdapter } from './types';
+/**
+ * 取得封裝操作 adapter
+ * @public
+ */
+export declare function getArchiveAdapter(): RuntimeArchiveAdapter;
+/**
+ * 將目錄封裝為歸檔檔案
+ * @public
+ */
+export declare function archiveFromDirectory(dirPath: string, archivePath: string, options?: ArchiveFromDirectoryOptions): Promise<Uint8Array>;

package/dist/core/src/runtime/compression.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Runtime compression adapter implementations.
+ *
+ * Provides unified gzip/deflate compression across Bun and Node.js runtimes.
+ * Bun uses native C++ implementations (Bun.gzipSync etc.) for 2-5x better performance.
+ * Node.js falls back to the standard node:zlib module.
+ *
+ * @module runtime/compression
+ * @since 3.2.0
+ */
+import type { RuntimeCompressionAdapter } from './types';
+/**
+ * 取得壓縮操作 adapter（依運行時自動選擇最佳實作）
+ *
+ * - Bun: 使用原生 C++ 壓縮（2-5x 更快）
+ * - Node.js: 使用 node:zlib
+ * - Deno/Unknown: 拋出錯誤
+ *
+ * @public
+ */
+export declare function getCompressionAdapter(): RuntimeCompressionAdapter;

package/dist/core/src/runtime/deep-equals.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Deep equality comparison abstraction.
+ *
+ * Provides unified deep equality checking across Bun, Node.js, and Deno runtimes.
+ * Uses Bun.deepEquals() when available, falls back to recursive comparison.
+ *
+ * @module runtime/deep-equals
+ * @since 3.2.0
+ */
+/**
+ * Options for deep equality comparison.
+ * @public
+ */
+export interface DeepEqualsOptions {
+    /**
+     * When true, uses strict equality semantics:
+     * - NaN !== NaN
+     * - +0 !== -0
+     *
+     * When false (default), uses lenient semantics:
+     * - NaN === NaN
+     * - +0 === -0
+     */
+    strict?: boolean;
+}
+/**
+ * Function signature for deep equality comparison.
+ * @public
+ */
+export type DeepEqualsFn = (a: unknown, b: unknown, options?: DeepEqualsOptions) => boolean;
+/**
+ * Get the optimized deep equality comparison function for the current runtime.
+ *
+ * - **Bun**: Uses native Bun.deepEquals() for maximum performance (C++ optimized)
+ * - **Node.js/Deno/Unknown**: Uses fallback recursive implementation with cycle detection
+ *
+ * Results are cached after first invocation for efficiency.
+ *
+ * @returns A function that performs deep equality comparison
+ * @public
+ *
+ * @example
+ * ```typescript
+ * const deepEquals = getDeepEquals()
+ *
+ * const obj1 = { a: [1, 2], b: { c: 3 } }
+ * const obj2 = { a: [1, 2], b: { c: 3 } }
+ *
+ * console.log(deepEquals(obj1, obj2)) // true
+ *
+ * // Strict mode for +0 / -0 and NaN
+ * console.log(deepEquals(NaN, NaN)) // true (lenient)
+ * console.log(deepEquals(NaN, NaN, { strict: true })) // false
+ * ```
+ */
+export declare function getDeepEquals(): DeepEqualsFn;

package/dist/core/src/runtime/detection.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Runtime detection utilities.
+ *
+ * @module runtime/detection
+ * @since 3.2.0
+ */
+import type { RuntimeKind } from './types';
+/**
+ * Detect the current JavaScript runtime environment.
+ * @internal
+ */
+export declare function getRuntimeKind(): RuntimeKind;
+/**
+ * Get environment variables from the current runtime.
+ * @public
+ */
+export declare function getRuntimeEnv(): Record<string, string | undefined>;
+/**
+ * Convert various data types to Uint8Array.
+ * @internal
+ */
+export declare function toUint8Array(data: Blob | Buffer | string | ArrayBuffer | Uint8Array): Promise<Uint8Array>;

package/dist/core/src/runtime/escape.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Runtime HTML escape abstraction.
+ *
+ * Provides unified HTML escaping across Bun, Node.js, and Deno runtimes.
+ * Bun uses the native C++ `Bun.escapeHTML()` for 10-100x better performance.
+ * Node.js/Deno fall back to manual entity replacement.
+ *
+ * @module runtime/escape
+ * @since 3.4.0
+ */
+/**
+ * HTML escape function type.
+ * @public
+ */
+export type EscapeHtmlFn = (value: string) => string;
+/**
+ * Get the HTML escape function (auto-selects best implementation based on runtime).
+ *
+ * - Bun: Uses native C++ `Bun.escapeHTML()` (10-100x faster, SIMD accelerated)
+ * - Node.js/Deno/Unknown: Uses .replace() chain fallback with same behavior
+ *
+ * @returns HTML escape function
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { getEscapeHtml } from '@gravito/core'
+ *
+ * const escapeHtml = getEscapeHtml()
+ * const safe = escapeHtml('<script>alert("xss")</script>')
+ * // '&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;'
+ * ```
+ */
+export declare function getEscapeHtml(): EscapeHtmlFn;

package/dist/core/src/runtime/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Runtime abstraction module.
+ *
+ * Provides unified APIs for filesystem, process, archive, and compression
+ * operations across Bun, Node.js, and Deno runtimes.
+ *
+ * @module runtime
+ * @since 3.2.0
+ */
+import type { RuntimeAdapter, RuntimePasswordAdapter, RuntimeSqliteDatabase } from './types';
+export type { ArchiveCreateOptions, ArchiveEntry, ArchiveExtractOptions, ArchiveFileInfo, ArchiveFromDirectoryOptions, CompressionOptions, MarkdownRenderCallbacks, MarkdownRenderOptions, OptionalRuntimeResourceUsage, RuntimeAdapter, RuntimeArchiveAdapter, RuntimeCompressionAdapter, RuntimeFileSink, RuntimeFileStat, RuntimeKind, RuntimeMarkdownAdapter, RuntimePasswordAdapter, RuntimeProcess, RuntimeProcessOutput, RuntimeResourceUsage, RuntimeServeConfig, RuntimeServer, RuntimeSpawnOptions, RuntimeSpawnSyncResult, RuntimeSqliteDatabase, RuntimeSqliteStatement, } from './types';
+export { getRuntimeEnv, getRuntimeKind } from './detection';
+export { archiveFromDirectory, getArchiveAdapter, } from './archive';
+export { getCompressionAdapter } from './compression';
+export { createHtmlRenderCallbacks, getMarkdownAdapter } from './markdown';
+export type { DeepEqualsFn, DeepEqualsOptions } from './deep-equals';
+export { getDeepEquals } from './deep-equals';
+export type { EscapeHtmlFn } from './escape';
+export { getEscapeHtml } from './escape';
+/**
+ * Get the runtime abstraction adapter (Bun/Node/Deno).
+ * @public
+ */
+export declare function getRuntimeAdapter(): RuntimeAdapter;
+/**
+ * Reset the runtime adapter (mainly for testing).
+ * @internal
+ */
+export declare function resetRuntimeAdapter(): void;
+/**
+ * Get the password hashing adapter using native optimized implementations if available.
+ * @public
+ */
+export declare function getPasswordAdapter(): RuntimePasswordAdapter;
+/**
+ * Create a SQLite database connection using runtime-native drivers.
+ * @public
+ */
+export declare function createSqliteDatabase(path: string): Promise<RuntimeSqliteDatabase>;
+/**
+ * Convert various data types to Uint8Array.
+ * @internal
+ */
+export declare function toUint8Array(data: Blob | Buffer | string | ArrayBuffer | Uint8Array): Promise<Uint8Array>;

package/dist/core/src/runtime/markdown.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Runtime markdown adapter implementations.
+ *
+ * Provides unified Markdown -> HTML rendering across Bun and Node.js runtimes.
+ * Bun uses the native C++ Markdown parser (Bun.markdown) for 10-100x better performance.
+ * Node.js falls back to the `marked` library (lazy-loaded optional dependency).
+ *
+ * @module runtime/markdown
+ * @since 3.3.0
+ */
+import type { MarkdownRenderCallbacks, RuntimeMarkdownAdapter } from './types';
+/**
+ * 建立預設的 HTML 渲染回調集合。
+ *
+ * 提供完整的 HTML 元素生成回調，產生與 `html()` 相同的 HTML 輸出。
+ * 使用者可透過覆寫個別回調來自訂特定元素的渲染行為（例如 XSS 防護、
+ * 自訂 CSS class 等），同時保留其他元素的預設 HTML 渲染。
+ *
+ * @param overrides - 要覆寫的回調。未指定的回調使用預設 HTML 渲染。
+ * @returns 完整的 MarkdownRenderCallbacks 物件
+ *
+ * @example
+ * ```typescript
+ * // 自訂 link 和 html 渲染（XSS 防護）
+ * const callbacks = createHtmlRenderCallbacks({
+ *   html: (raw) => escapeHtml(raw),
+ *   link: (content, { href }) => `<a href="${href}" rel="noopener">${content}</a>`,
+ * })
+ * const result = adapter.render(markdown, callbacks)
+ * ```
+ *
+ * @public
+ */
+export declare function createHtmlRenderCallbacks(overrides?: Partial<MarkdownRenderCallbacks>): MarkdownRenderCallbacks;
+/**
+ * 取得 Markdown 操作 adapter（依運行時自動選擇最佳實作）
+ *
+ * - Bun: 使用原生 C++ Markdown 解析器（10-100x 更快）
+ * - Node.js: 使用 marked 函式庫（延遲載入 optional dependency）
+ * - Deno/Unknown: 拋出錯誤
+ *
+ * @public
+ */
+export declare function getMarkdownAdapter(): RuntimeMarkdownAdapter;