@gravito/ripple 4.0.1 → 5.0.0

package/dist/atlas/src/utils/CursorEncoding.d.ts

@@ -1,63 +0,0 @@
-/**
- * @gravito/atlas - Cursor Encoding Utility
- * @description Base64 encode/decode for cursor-based pagination cursors.
- *
- * Cursor format: base64(JSON({ id, sortValue, sortColumn, direction }))
- * This enables O(1) pagination using tuple comparison SQL:
- *   WHERE (sort_col, id) > (val, id_val)
- */
-export interface CursorPayload {
-    /**
-     * Primary key value of the last/first record in the current page
-     */
-    id: unknown;
-    /**
-     * Value of the sort column at the cursor boundary
-     */
-    sortValue: unknown;
-    /**
-     * Column name used for sorting
-     */
-    sortColumn: string;
-    /**
-     * Sort direction
-     */
-    direction: 'asc' | 'desc';
-}
-/**
- * Encode a cursor payload to an opaque base64 string.
- *
- * @param payload - Cursor data to encode
- * @returns Base64-encoded cursor string
- *
- * @example
- * const cursor = encodeCursor({ id: 42, sortValue: '2026-01-01', sortColumn: 'created_at', direction: 'asc' })
- */
-export declare function encodeCursor(payload: CursorPayload): string;
-/**
- * Decode a cursor string back to its payload.
- *
- * @param cursor - Base64 cursor string
- * @returns Decoded cursor payload
- * @throws {Error} If the cursor is malformed or tampered with
- *
- * @example
- * const payload = decodeCursor(cursor)
- * // payload.id, payload.sortValue, etc.
- */
-export declare function decodeCursor(cursor: string): CursorPayload;
-/**
- * Build the WHERE clause raw SQL and bindings for cursor pagination.
- *
- * For ascending sort: WHERE (sort_col, id) > (sort_val, id_val)
- * For descending sort: WHERE (sort_col, id) < (sort_val, id_val)
- *
- * Uses tuple comparison which is O(1) on indexed columns in Postgres & MySQL.
- *
- * @param payload - Decoded cursor payload
- * @returns { sql, bindings } ready for whereRaw()
- */
-export declare function buildCursorWhereClause(payload: CursorPayload, idColumn?: string): {
-    sql: string;
-    bindings: unknown[];
-};

package/dist/atlas/src/utils/levenshtein.d.ts

@@ -1,9 +0,0 @@
-/**
- * Calculate Levenshtein distance between two strings
- * Used for "Did you mean?" suggestions
- */
-export declare function levenshtein(a: string, b: string): number;
-/**
- * Find similar strings from a list
- */
-export declare function findSimilar(target: string, candidates: string[], maxDistance?: number, maxResults?: number): string[];

package/dist/core/src/adapters/PhotonAdapter.d.ts

@@ -1,175 +0,0 @@
-/**
- * @fileoverview Photon Adapter Implementation
- *
- * This adapter wraps Photon to implement the Gravito HttpAdapter interface.
- * It serves as the default adapter and reference implementation for others.
- *
- * @module @gravito/core/adapters/photon
- * @since 2.0.0
- */
-import type { Context, Handler, MiddlewareHandler, Photon } from '@gravito/photon';
-import { RequestScopeManager } from '../Container/RequestScopeManager';
-import type { GravitoContext, GravitoErrorHandler, GravitoHandler, GravitoMiddleware, GravitoNotFoundHandler, GravitoRequest, GravitoVariables, HttpMethod, ProxyOptions, StatusCode } from '../http/types';
-import type { AdapterConfig, HttpAdapter, RouteDefinition } from './types';
-/**
- * Wraps Photon's request object to implement GravitoRequest
- */
-declare class PhotonRequestWrapper implements GravitoRequest {
-    photonCtx: Context;
-    /**
-     * Reset the wrapper for pooling
-     */
-    reset(photonCtx: Context): void;
-    /**
-     * Create a proxied instance to delegate to Photon's request
-     */
-    static create(photonCtx: Context): PhotonRequestWrapper;
-    /**
-     * Internal proxy wrapper
-     */
-    static wrap(instance: PhotonRequestWrapper): PhotonRequestWrapper;
-    get url(): string;
-    get method(): string;
-    get path(): string;
-    param(name: string): string | undefined;
-    params(): Record<string, string>;
-    query(name: string): string | undefined;
-    queries(): Record<string, string | string[]>;
-    header(name: string): string | undefined;
-    header(): Record<string, string>;
-    json<T = unknown>(): Promise<T>;
-    text(): Promise<string>;
-    formData(): Promise<FormData>;
-    arrayBuffer(): Promise<ArrayBuffer>;
-    parseBody<T = unknown>(): Promise<T>;
-    get raw(): Request;
-    valid<T = unknown>(target: string): T;
-}
-/**
- * Wraps Photon's context to implement GravitoContext
- */
-declare class PhotonContextWrapper<V extends GravitoVariables = GravitoVariables> implements GravitoContext<V> {
-    private _req;
-    private photonCtx;
-    private _requestScope;
-    route: (name: string, params?: Record<string, any>, query?: Record<string, any>) => string;
-    /**
-     * Reset the wrapper for pooling
-     */
-    reset(photonCtx: Context): void;
-    /**
-     * Create a proxied instance to enable object destructuring of context variables
-     */
-    static create<V extends GravitoVariables = GravitoVariables>(photonCtx: Context): GravitoContext<V>;
-    /**
-     * Internal proxy wrapper
-     */
-    static wrap<V extends GravitoVariables = GravitoVariables>(instance: PhotonContextWrapper<V>): GravitoContext<V>;
-    get req(): GravitoRequest;
-    get params(): Record<string, string>;
-    get query(): Record<string, string | string[]>;
-    get data(): unknown;
-    set data(value: unknown);
-    back(status?: 301 | 302 | 303 | 307 | 308): Response;
-    json<T>(data: T, status?: number): Response;
-    text(text: string, status?: number): Response;
-    html(html: string, status?: number): Response;
-    redirect(url: string, status?: 301 | 302 | 303 | 307 | 308): Response;
-    body(data: BodyInit | null, status?: number): Response;
-    stream(stream: ReadableStream, status?: number): Response;
-    notFound(message?: string): Response;
-    forbidden(message?: string): Response;
-    unauthorized(message?: string): Response;
-    badRequest(message?: string): Response;
-    header(name: string): string | undefined;
-    header(name: string, value: string, options?: {
-        append?: boolean;
-    }): void;
-    status(code: StatusCode): void;
-    get<K extends keyof V>(key: K): V[K];
-    set<K extends keyof V>(key: K, value: V[K]): void;
-    get executionCtx(): ExecutionContext | undefined;
-    get env(): Record<string, unknown> | undefined;
-    get native(): Context;
-    forward(target: string, options?: ProxyOptions): Promise<Response>;
-    requestScope(): RequestScopeManager;
-    scoped<T>(key: string | symbol, factory: () => T): T;
-}
-/**
- * Convert a GravitoHandler to a Photon Handler
- */
-declare function toPhotonHandler<V extends GravitoVariables>(handler: GravitoHandler<V>): Handler;
-/**
- * Convert a GravitoMiddleware to a Photon MiddlewareHandler
- */
-declare function toPhotonMiddleware<V extends GravitoVariables>(middleware: GravitoMiddleware<V>): MiddlewareHandler;
-/**
- * Default HTTP adapter using the optimized Gravito Core Engine.
- *
- * This adapter provides a consistent interface that can be
- * swapped out for other implementations without changing application code.
- *
- * @example
- * ```typescript
- * import { GravitoAdapter } from '@gravito/core'
- *
- * const adapter = new GravitoAdapter()
- *
- * // Register routes
- * adapter.route('get', '/hello', async (ctx) => {
- *   return ctx.json({ message: 'Hello, World!' })
- * })
- * ```
- */
-export declare class PhotonAdapter<V extends GravitoVariables = GravitoVariables> implements HttpAdapter<V> {
-    private config;
-    readonly name = "photon";
-    readonly version = "1.0.0";
-    private app;
-    constructor(config?: AdapterConfig, photonInstance?: unknown);
-    /**
-     * Get the underlying Photon app instance
-     */
-    get native(): Photon;
-    /**
-     * Set the underlying Photon app instance
-     * Used by PlanetCore during initialization
-     */
-    setNative(app: Photon): void;
-    route(method: HttpMethod, path: string, ...handlers: (GravitoHandler<V> | GravitoMiddleware<V>)[]): void;
-    routes(routes: RouteDefinition[]): void;
-    use(path: string, ...middleware: GravitoMiddleware<V>[]): void;
-    useGlobal(...middleware: GravitoMiddleware<V>[]): void;
-    useScoped(scope: string, path: string, ...middleware: GravitoMiddleware<V>[]): void;
-    mount(path: string, subAdapter: HttpAdapter<V>): void;
-    onError(handler: GravitoErrorHandler<V>): void;
-    onNotFound(handler: GravitoNotFoundHandler<V>): void;
-    /**
-     * Predictive Route Warming (JIT Optimization)
-     */
-    warmup(paths: string[]): Promise<void>;
-    fetch: (request: Request, server?: unknown) => Response | Promise<Response>;
-    createContext(_request: Request): GravitoContext<V>;
-    init(): Promise<void>;
-    shutdown(): Promise<void>;
-}
-/**
- * Create a new PhotonAdapter instance
- */
-export declare function createPhotonAdapter<V extends GravitoVariables = GravitoVariables>(config?: AdapterConfig): PhotonAdapter<V>;
-export { PhotonContextWrapper, PhotonRequestWrapper, toPhotonHandler, toPhotonMiddleware };
-/**
- * Rebranded alias for PhotonAdapter.
- * @category Rebranding
- */
-export declare const GravitoAdapter: typeof PhotonAdapter;
-/**
- * Rebranded alias for PhotonAdapter type.
- * @category Rebranding
- */
-export type GravitoAdapter<V extends GravitoVariables = GravitoVariables> = PhotonAdapter<V>;
-/**
- * Rebranded alias for createPhotonAdapter.
- * @category Rebranding
- */
-export declare const createGravitoAdapter: typeof createPhotonAdapter;

package/dist/core/src/adapters/photon-types.d.ts

@@ -1,73 +0,0 @@
-/**
- * @fileoverview Photon Type Extensions
- *
- * Type definitions for Photon framework extensions and internal properties.
- * These types help maintain type safety when working with Photon's native APIs.
- *
- * @module @gravito/core/adapters/photon-types
- * @since 2.0.0
- */
-import type { Context } from '@gravito/photon';
-/**
- * Extended Photon Request with additional properties
- */
-export interface PhotonRequestExtended {
-    /**
-     * Validate request data against a schema
-     * This is typically added by validation middleware
-     */
-    valid<T = unknown>(target: string): T;
-    /**
-     * Allow dynamic property access for middleware extensions
-     */
-    [key: string]: unknown;
-}
-/**
- * Extended Photon Context with internal caching
- */
-export interface PhotonContextExtended extends Context {
-    /**
-     * Internal cache for parsed JSON body to avoid re-parsing
-     * @internal
-     */
-    _cachedJsonBody?: unknown;
-    /**
-     * Extended request object
-     */
-    req: Context['req'] & PhotonRequestExtended;
-}
-/**
- * Extended Response with flash message support
- * This is a partial interface since we're adding the method dynamically
- */
-export interface ResponseWithFlash {
-    /**
-     * Add flash message to session (for redirect responses)
-     * @param key - Flash message key
-     * @param value - Flash message value
-     * @returns The response for chaining
-     */
-    with(key: string, value: unknown): ResponseWithFlash;
-    [key: string]: unknown;
-}
-/**
- * Session interface with flash message support
- */
-export interface SessionWithFlash {
-    /**
-     * Store a flash message in the session
-     */
-    flash(key: string, value: unknown): void;
-    /**
-     * Allow other session properties
-     */
-    [key: string]: unknown;
-}
-/**
- * Type guard to check if context has cached JSON body
- */
-export declare function hasCachedJsonBody(ctx: Context): ctx is PhotonContextExtended;
-/**
- * Type guard to check if request has valid method
- */
-export declare function hasValidMethod(req: Context['req']): req is Context['req'] & PhotonRequestExtended;

package/dist/core/src/http/middleware/BodySizeLimit.d.ts

@@ -1,16 +0,0 @@
-import type { GravitoMiddleware } from '../types';
-/**
- * Options for body size limiting
- * @public
- */
-export type BodySizeLimitOptions = {
-    methods?: string[];
-    requireContentLength?: boolean;
-};
-/**
- * Middleware to limit request body size.
- * @param maxBytes - Maximum allowed size in bytes
- * @param options - Configuration options
- * @public
- */
-export declare function bodySizeLimit(maxBytes: number, options?: BodySizeLimitOptions): GravitoMiddleware;

package/dist/core/src/http/middleware/Cors.d.ts

@@ -1,24 +0,0 @@
-import type { GravitoMiddleware } from '../types';
-/**
- * Allowed origin(s) configuration.
- * @public
- */
-export type CorsOrigin = string | string[] | ((origin: string | undefined) => string | false);
-/**
- * Options for CORS middleware
- * @public
- */
-export type CorsOptions = {
-    origin?: CorsOrigin;
-    methods?: string[];
-    allowedHeaders?: string[];
-    exposedHeaders?: string[];
-    credentials?: boolean;
-    maxAge?: number;
-    optionsSuccessStatus?: number;
-};
-/**
- * Middleware handling Cross-Origin Resource Sharing (CORS).
- * @public
- */
-export declare function cors(options?: CorsOptions): GravitoMiddleware;

package/dist/core/src/http/middleware/Csrf.d.ts

@@ -1,23 +0,0 @@
-import { type CookieOptions } from '../CookieJar';
-import type { GravitoContext, GravitoMiddleware } from '../types';
-/**
- * Configuration for CSRF Protection
- * @public
- */
-export type CsrfOptions = {
-    cookieName?: string;
-    headerName?: string;
-    formFieldName?: string;
-    cookie?: CookieOptions;
-    safeMethods?: string[];
-};
-/**
- * Generate (or retrieve existing) CSRF token for the session.
- * @public
- */
-export declare function getCsrfToken(c: GravitoContext, options?: CsrfOptions): string;
-/**
- * Middleware that validates CSRF tokens on unsafe requests.
- * @public
- */
-export declare function csrfProtection(options?: CsrfOptions): GravitoMiddleware;

package/dist/core/src/http/middleware/HeaderTokenGate.d.ts

@@ -1,28 +0,0 @@
-import type { GravitoContext, GravitoMiddleware } from '../types';
-/**
- * Options for header token gate
- * @public
- */
-export type HeaderTokenGateOptions = {
-    headerName?: string;
-    token?: string | ((c: GravitoContext) => string | undefined);
-};
-/**
- * Options for requireHeaderToken middleware
- * @public
- */
-export type RequireHeaderTokenOptions = HeaderTokenGateOptions & {
-    status?: number;
-    message?: string;
-};
-/**
- * Create a simple gate function to check a header token.
- * @public
- */
-export declare function createHeaderGate(options?: HeaderTokenGateOptions): (c: GravitoContext) => Promise<boolean>;
-/**
- * Middleware that enforces a specific token in request headers.
- * Useful for internal API authentication.
- * @public
- */
-export declare function requireHeaderToken(options?: RequireHeaderTokenOptions): GravitoMiddleware;

package/dist/core/src/http/middleware/SecurityHeaders.d.ts

@@ -1,29 +0,0 @@
-import type { GravitoContext, GravitoMiddleware } from '../types';
-/**
- * HSTS Configuration
- * @public
- */
-export type HstsOptions = {
-    maxAge: number;
-    includeSubDomains?: boolean;
-    preload?: boolean;
-};
-/**
- * Options for Security Headers middleware
- * @public
- */
-export type SecurityHeadersOptions = {
-    contentSecurityPolicy?: string | false | ((c: GravitoContext) => string | false);
-    frameOptions?: string | false;
-    referrerPolicy?: string | false;
-    noSniff?: boolean;
-    hsts?: HstsOptions | false;
-    permissionsPolicy?: string | false;
-    crossOriginOpenerPolicy?: string | false;
-    crossOriginResourcePolicy?: string | false;
-};
-/**
- * Apply common security headers to responses (Helmet-style).
- * @public
- */
-export declare function securityHeaders(options?: SecurityHeadersOptions): GravitoMiddleware;

package/dist/core/src/http/middleware/ThrottleRequests.d.ts

@@ -1,18 +0,0 @@
-import type { GravitoMiddleware } from '../../http/types';
-import type { PlanetCore } from '../../PlanetCore';
-/**
- * Rate Limiting Middleware using Orbit Cache.
- * Requires an active CacheService implementation.
- * @public
- */
-export declare class ThrottleRequests {
-    private core;
-    private keyCache;
-    constructor(core: PlanetCore);
-    /**
-     * Create the middleware
-     * @param maxAttempts - Max requests allowed
-     * @param decaySeconds - Time window in seconds
-     */
-    handle(maxAttempts?: number, decaySeconds?: number): GravitoMiddleware;
-}

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

@@ -1,35 +0,0 @@
-/**
- * @gravito/core - Instrumentation Module
- *
- * 提供 OpenTelemetry SDK 集成功能，包括分佈式追蹤與指標收集。
- *
- * @example
- * ```typescript
- * import {
- *   setupOpenTelemetry,
- *   getOpenTelemetrySDK,
- *   getTracer,
- *   getMeter
- * } from '@gravito/core'
- *
- * // 初始化 SDK
- * await setupOpenTelemetry({
- *   serviceName: 'my-service',
- *   tracing: { enabled: true, exporter: 'jaeger' },
- *   metrics: { enabled: true, exporter: 'prometheus' }
- * })
- *
- * // 獲取 Tracer
- * const tracer = await getTracer('my-module')
- * const span = tracer.startSpan('my-operation')
- *
- * // 獲取 Meter
- * const meter = await getMeter('my-module')
- * const counter = meter.createCounter('request_count')
- * ```
- *
- * @packageDocumentation
- */
-export { getMeter, getOpenTelemetrySDK, getTracer, isOpenTelemetryInitialized, resetOpenTelemetry, setupOpenTelemetry, shutdownOpenTelemetry, } from './opentelemetry';
-export type { MetricsConfig, MetricsExporter, OpenTelemetryConfig, OpenTelemetrySDK, TracingConfig, TracingExporter, } from './types';
-export { DEFAULT_CONFIG, OTEL_ENV_VARS } from './types';

package/dist/core/src/instrumentation/opentelemetry.d.ts

@@ -1,178 +0,0 @@
-/**
- * @gravito/core - OpenTelemetry SDK 集成
- *
- * 提供 OpenTelemetry 的初始化、配置與管理功能。
- * 支援動態導入以實現可選依賴的優雅降級。
- *
- * @example
- * ```typescript
- * import { setupOpenTelemetry } from '@gravito/core'
- *
- * const sdk = await setupOpenTelemetry({
- *   serviceName: 'my-service',
- *   serviceVersion: '1.0.0',
- *   tracing: {
- *     enabled: true,
- *     exporter: 'jaeger',
- *     samplingRate: 0.1
- *   },
- *   metrics: {
- *     enabled: true,
- *     exporter: 'prometheus',
- *     prometheusPort: 9090
- *   }
- * })
- * ```
- *
- * @packageDocumentation
- */
-import { type MetricsConfig, type OpenTelemetryConfig, type OpenTelemetrySDK, type TracingConfig } from './types';
-export type { MetricsConfig, OpenTelemetryConfig, OpenTelemetrySDK, TracingConfig };
-/**
- * 初始化 OpenTelemetry SDK
- *
- * @param userConfig - 用戶配置
- * @returns OpenTelemetry SDK 實例或 null（如果禁用或初始化失敗）
- *
- * @example
- * ```typescript
- * // 基本用法
- * const sdk = await setupOpenTelemetry({
- *   serviceName: 'my-service'
- * })
- *
- * // 完整配置
- * const sdk = await setupOpenTelemetry({
- *   serviceName: 'my-service',
- *   serviceVersion: '2.0.0',
- *   environment: 'production',
- *   tracing: {
- *     enabled: true,
- *     exporter: 'jaeger',
- *     jaegerEndpoint: 'http://jaeger:14268/api/traces',
- *     samplingRate: 0.1
- *   },
- *   metrics: {
- *     enabled: true,
- *     exporter: 'prometheus',
- *     prometheusPort: 9090
- *   }
- * })
- * ```
- *
- * @public
- */
-export declare function setupOpenTelemetry(userConfig?: OpenTelemetryConfig): Promise<OpenTelemetrySDK | null>;
-/**
- * 獲取全局 OpenTelemetry SDK 實例
- *
- * @returns SDK 實例或 null
- *
- * @example
- * ```typescript
- * const sdk = getOpenTelemetrySDK()
- * if (sdk) {
- *   console.log('Service:', sdk.serviceName)
- * }
- * ```
- *
- * @public
- */
-export declare function getOpenTelemetrySDK(): OpenTelemetrySDK | null;
-/**
- * 檢查 OpenTelemetry 是否已初始化
- *
- * @returns 初始化狀態
- *
- * @public
- */
-export declare function isOpenTelemetryInitialized(): boolean;
-/**
- * 關閉 OpenTelemetry SDK
- *
- * 應在應用程序關閉時調用，確保所有 spans 和 metrics 都被導出。
- *
- * @example
- * ```typescript
- * // 在應用程序退出前
- * process.on('SIGTERM', async () => {
- *   await shutdownOpenTelemetry()
- *   process.exit(0)
- * })
- * ```
- *
- * @public
- */
-export declare function shutdownOpenTelemetry(): Promise<void>;
-/**
- * 重置 OpenTelemetry SDK（主要用於測試）
- *
- * 關閉現有 SDK 並重置所有狀態，允許重新初始化。
- *
- * @internal
- */
-export declare function resetOpenTelemetry(): Promise<void>;
-/**
- * 獲取 Tracer 實例
- *
- * @param name - Tracer 名稱（預設：@gravito/core）
- * @param version - Tracer 版本
- * @returns Tracer 實例
- *
- * @example
- * ```typescript
- * const tracer = getTracer('my-module')
- * const span = tracer.startSpan('my-operation')
- * // ... 執行操作
- * span.end()
- * ```
- *
- * @public
- */
-export declare function getTracer(name?: string, version?: string): Promise<import("@opentelemetry/api").Tracer | {
-    startSpan: () => {
-        end: () => void;
-        setAttribute: () => void;
-        setStatus: () => void;
-        recordException: () => void;
-        addEvent: () => void;
-        isRecording: () => boolean;
-    };
-    startActiveSpan: (_name: string, fn: (span: any) => any) => any;
-}>;
-/**
- * 獲取 Meter 實例
- *
- * @param name - Meter 名稱（預設：@gravito/core）
- * @param version - Meter 版本
- * @returns Meter 實例
- *
- * @example
- * ```typescript
- * const meter = getMeter('my-module')
- * const counter = meter.createCounter('my_counter')
- * counter.add(1, { key: 'value' })
- * ```
- *
- * @public
- */
-export declare function getMeter(name?: string, version?: string): Promise<import("@opentelemetry/api").Meter | {
-    createCounter: () => {
-        add: () => void;
-    };
-    createHistogram: () => {
-        record: () => void;
-    };
-    createUpDownCounter: () => {
-        add: () => void;
-    };
-    createObservableCounter: () => {
-        addCallback: () => void;
-    };
-    createObservableGauge: () => {
-        addCallback: () => void;
-    };
-    createObservableUpDownCounter: () => {
-        addCallback: () => void;
-    };
-}>;