@gravito/core 1.6.1 → 2.0.0

package/dist/Container/RequestScopeManager.d.ts

@@ -0,0 +1,62 @@
+import type { ServiceKey } from '../Container';
+import { RequestScopeMetrics, type RequestScopeObserver } from './RequestScopeMetrics';
+/**
+ * Manages request-scoped service instances within a single HTTP request.
+ *
+ * Each request gets its own RequestScopeManager instance with isolated state.
+ * Services are cached within the request and automatically cleaned up when
+ * the request ends.
+ *
+ * @example
+ * ```typescript
+ * const scope = new RequestScopeManager()
+ * const cache = scope.resolve('productCache', () => new ProductCache())
+ * // ... use cache ...
+ * await scope.cleanup() // Called automatically by Gravito engine
+ * ```
+ */
+export declare class RequestScopeManager {
+    private scoped;
+    private metadata;
+    private metrics;
+    private observer;
+    constructor(observer?: RequestScopeObserver);
+    /**
+     * Set observer for monitoring scope lifecycle
+     */
+    setObserver(observer: RequestScopeObserver): void;
+    /**
+     * Get metrics for this scope
+     */
+    getMetrics(): RequestScopeMetrics;
+    /**
+     * Resolve or retrieve a request-scoped service instance.
+     *
+     * If the service already exists in this scope, returns the cached instance.
+     * Otherwise, calls the factory function to create a new instance and caches it.
+     *
+     * Automatically detects and records services with cleanup methods.
+     *
+     * @template T - The type of the service.
+     * @param key - The service key (for caching).
+     * @param factory - Factory function to create the instance if not cached.
+     * @returns The cached or newly created instance.
+     */
+    resolve<T>(key: ServiceKey, factory: () => T): T;
+    /**
+     * Clean up all request-scoped instances.
+     *
+     * Calls the cleanup() method on each service that has one.
+     * Silently ignores cleanup errors to prevent cascading failures.
+     * Called automatically by the Gravito engine in the request finally block.
+     *
+     * @returns Promise that resolves when all cleanup is complete.
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Get the number of services in this scope (for monitoring).
+     *
+     * @returns The count of cached services.
+     */
+    size(): number;
+}

package/dist/Container/RequestScopeMetrics.d.ts

@@ -0,0 +1,144 @@
+/**
+ * RequestScopeMetrics - Observability for RequestScope lifecycle
+ *
+ * Tracks cleanup execution time, scope size, and service counts
+ * for performance monitoring and diagnostics.
+ *
+ * @example
+ * ```typescript
+ * const metrics = new RequestScopeMetrics()
+ * metrics.recordCleanupStart()
+ * await scope.cleanup()
+ * metrics.recordCleanupEnd()
+ *
+ * console.log(metrics.toJSON())
+ * // { cleanupDuration: 2.5, scopeSize: 3, servicesCleaned: 3 }
+ * ```
+ */
+export declare class RequestScopeMetrics {
+    private cleanupStartTime;
+    private cleanupDuration;
+    private scopeSize;
+    private servicesCleaned;
+    private errorsOccurred;
+    /**
+     * Record start of cleanup operation
+     */
+    recordCleanupStart(): void;
+    /**
+     * Record end of cleanup operation
+     *
+     * @param scopeSize - Number of services in the scope
+     * @param servicesCleaned - Number of services that had cleanup called
+     * @param errorsOccurred - Number of cleanup errors
+     */
+    recordCleanupEnd(scopeSize: number, servicesCleaned: number, errorsOccurred?: number): void;
+    /**
+     * Get cleanup duration in milliseconds
+     *
+     * @returns Duration in ms, or null if cleanup not completed
+     */
+    getCleanupDuration(): number | null;
+    /**
+     * Check if cleanup took longer than threshold (default 2ms)
+     * Useful for detecting slow cleanups
+     *
+     * @param thresholdMs - Threshold in milliseconds
+     * @returns True if cleanup exceeded threshold
+     */
+    isSlowCleanup(thresholdMs?: number): boolean;
+    /**
+     * Export metrics as JSON for logging/monitoring
+     */
+    toJSON(): {
+        cleanupDuration: number;
+        scopeSize: number;
+        servicesCleaned: number;
+        errorsOccurred: number;
+        hasErrors: boolean;
+        isSlowCleanup: boolean;
+    };
+    /**
+     * Export metrics as compact string for logging
+     */
+    toString(): string;
+}
+/**
+ * RequestScopeObserver - Hook for monitoring RequestScope lifecycle
+ *
+ * Implement this interface to receive callbacks during scope operations
+ */
+export interface RequestScopeObserver {
+    /**
+     * Called when a service is resolved in the scope
+     */
+    onServiceResolved?(key: string | symbol, isFromCache: boolean): void;
+    /**
+     * Called when cleanup starts
+     */
+    onCleanupStart?(): void;
+    /**
+     * Called when cleanup completes
+     */
+    onCleanupEnd?(metrics: RequestScopeMetrics): void;
+    /**
+     * Called when cleanup encounters an error
+     */
+    onCleanupError?(error: Error): void;
+}
+/**
+ * RequestScopeMetricsCollector - Aggregates metrics across multiple scopes
+ *
+ * Used for application-level monitoring and performance tracking
+ *
+ * @example
+ * ```typescript
+ * const collector = new RequestScopeMetricsCollector()
+ *
+ * // Record metrics from multiple requests
+ * collector.record(metrics1)
+ * collector.record(metrics2)
+ * collector.record(metrics3)
+ *
+ * // Get aggregated stats
+ * const stats = collector.getStats()
+ * console.log(stats.averageCleanupTime) // 3.5ms
+ * ```
+ */
+export declare class RequestScopeMetricsCollector {
+    private metrics;
+    /**
+     * Record metrics from a request scope
+     */
+    record(metrics: RequestScopeMetrics): void;
+    /**
+     * Get aggregated statistics
+     */
+    getStats(): {
+        count: number;
+        averageCleanupTime: number;
+        maxCleanupTime: number;
+        minCleanupTime: number;
+        totalErrorCount: number;
+        errorRate: number;
+    };
+    /**
+     * Clear collected metrics
+     */
+    clear(): void;
+    /**
+     * Get number of recorded metrics
+     */
+    size(): number;
+    /**
+     * Export metrics as JSON array
+     */
+    toJSON(): {
+        cleanupDuration: number;
+        scopeSize: number;
+        servicesCleaned: number;
+        errorsOccurred: number;
+        hasErrors: boolean;
+        isSlowCleanup: boolean;
+    }[];
+}

package/dist/Container.d.ts

@@ -0,0 +1,153 @@
+import type { RequestScopeManager } from './Container/RequestScopeManager';
+/**
+ * Factory type for creating service instances
+ */
+export type Factory<T> = (container: Container) => T;
+/**
+ * ServiceMap interface for type-safe IoC resolution.
+ *
+ * Extend this interface via module augmentation to get type inference:
+ * @example
+ * ```typescript
+ * declare module '@gravito/core' {
+ *   interface ServiceMap {
+ *     logger: Logger
+ *     db: DatabaseConnection
+ *   }
+ * }
+ * ```
+ */
+export type ServiceMap = {};
+/**
+ * ServiceKey represents the allowed keys for service resolution.
+ * Includes keys from ServiceMap, generic strings, or symbols.
+ */
+export type ServiceKey = keyof ServiceMap | (string & {}) | symbol;
+/**
+ * Container - Simple Dependency Injection Container.
+ * Manages service bindings and singleton instances.
+ * @public
+ */
+export declare class Container {
+    private bindings;
+    private instances;
+    private resolutionStack;
+    /**
+     * Run a function within a request scope context.
+     *
+     * All service resolutions within the function will use the provided scope,
+     * enabling request-scoped service instances to be properly isolated.
+     *
+     * @template T - The return type of the function.
+     * @param scope - The RequestScopeManager for this request.
+     * @param fn - The function to execute within the scope.
+     * @returns The result of the function.
+     *
+     * @example
+     * ```typescript
+     * const scope = new RequestScopeManager()
+     * const result = await Container.runWithScope(scope, async () => {
+     *   const service = container.make('requestScoped')
+     *   return service.doSomething()
+     * })
+     * ```
+     */
+    static runWithScope<T>(scope: RequestScopeManager, fn: () => T | Promise<T>): T | Promise<T>;
+    /**
+     * Bind a service to the container.
+     *
+     * A new instance will be created by the factory function every time the
+     * service is resolved from the container.
+     *
+     * @template T - The type of the service being bound.
+     * @param key - The unique identifier for the service.
+     * @param factory - The factory function that creates the service instance.
+     *
+     * @example
+     * ```typescript
+     * container.bind('logger', (c) => new ConsoleLogger());
+     * ```
+     */
+    bind<T>(key: ServiceKey, factory: Factory<T>): void;
+    /**
+     * Bind a shared service to the container (Singleton).
+     *
+     * The factory function will be called only once, and the same instance
+     * will be returned on every subsequent resolution.
+     *
+     * @template T - The type of the service being bound.
+     * @param key - The unique identifier for the service.
+     * @param factory - The factory function that creates the service instance.
+     *
+     * @example
+     * ```typescript
+     * container.singleton('db', (c) => new DatabaseConnection());
+     * ```
+     */
+    singleton<T>(key: ServiceKey, factory: Factory<T>): void;
+    /**
+     * Bind a request-scoped service to the container.
+     *
+     * A new instance will be created for each request and cached within that request.
+     * The service is automatically cleaned up when the request ends.
+     *
+     * @template T - The type of the service being bound.
+     * @param key - The unique identifier for the service.
+     * @param factory - The factory function that creates the service instance.
+     *
+     * @example
+     * ```typescript
+     * container.scoped('requestCache', (c) => new RequestProductCache());
+     * ```
+     */
+    scoped<T>(key: ServiceKey, factory: Factory<T>): void;
+    /**
+     * Register an existing instance as a shared service.
+     *
+     * @param key - The unique identifier for the service.
+     * @param instance - The instance to register.
+     */
+    instance<T>(key: ServiceKey, instance: T): void;
+    /**
+     * Check if a service is request-scoped.
+     *
+     * @param key - The service key to check.
+     * @returns True if the service is request-scoped.
+     */
+    isRequestScoped(key: ServiceKey): boolean;
+    /**
+     * Resolve a service instance from the container.
+     *
+     * Automatically handles singleton caching and factory execution.
+     *
+     * @template T - The expected type of the service.
+     * @param key - The unique identifier for the service.
+     * @returns The resolved service instance.
+     * @throws Error if the service key is not found in the container.
+     *
+     * @example
+     * ```typescript
+     * const logger = container.make<Logger>('logger');
+     * ```
+     */
+    make<K extends keyof ServiceMap>(key: K): ServiceMap[K];
+    make<T>(key: ServiceKey): T;
+    /**
+     * Check if a service is bound or has an instance in the container.
+     *
+     * @param key - The service key to check.
+     * @returns True if the service exists.
+     */
+    has(key: ServiceKey): boolean;
+    /**
+     * Flush all instances and bindings from the container.
+     * Resets the container to an empty state.
+     */
+    flush(): void;
+    /**
+     * Forget a specific instance while keeping its binding.
+     *
+     * @param key - The service key to forget.
+     */
+    forget(key: ServiceKey): void;
+}

package/dist/ErrorHandler.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @fileoverview ErrorHandler - Centralized Error Handling for Gravito Framework
+ *
+ * Extracted from PlanetCore to follow Single Responsibility Principle.
+ * Handles HTTP errors, validation errors, and error rendering.
+ *
+ * @module @gravito/core
+ * @since 1.3.0
+ */
+import type { HookManager } from './HookManager';
+import type { GravitoContext } from './http/types';
+import type { Logger } from './Logger';
+/**
+ * HTTP Status Code to Error Code mapping
+ */
+export declare function codeFromStatus(status: number): string;
+/**
+ * HTTP Status Code to Message mapping
+ */
+export declare function messageFromStatus(status: number): string;
+/**
+ * Dependencies injected into ErrorHandler
+ * @public
+ */
+export interface ErrorHandlerDeps {
+    logger: Logger;
+    hooks: HookManager;
+    getCore: () => unknown;
+}
+/**
+ * ErrorHandler - Centralized error handling logic
+ *
+ * @example
+ * ```typescript
+ * const handler = new ErrorHandler({ logger, hooks, getCore: () => core })
+ * adapter.onError(handler.handleError.bind(handler))
+ * adapter.onNotFound(handler.handleNotFound.bind(handler))
+ * ```
+ */
+export declare class ErrorHandler {
+    private deps;
+    constructor(deps: ErrorHandlerDeps);
+    /**
+     * Handle application errors
+     *
+     * Integrates RequestScope cleanup to ensure proper resource management
+     * even when errors occur during request processing.
+     */
+    handleError(err: unknown, c: GravitoContext): Promise<Response>;
+    /**
+     * Handle 404 Not Found errors
+     */
+    handleNotFound(c: GravitoContext): Promise<Response>;
+    /**
+     * Handle validation error redirect for HTML requests
+     */
+    private handleValidationRedirect;
+    /**
+     * Log error based on context settings
+     */
+    private logError;
+    /**
+     * Render error response (HTML or JSON)
+     */
+    private renderErrorResponse;
+}

package/dist/Event.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Event base class and related types.
+ */
+export type { Channel, ShouldBroadcast } from './types/events';
+export { Event } from './types/events';

package/dist/EventManager.d.ts

@@ -0,0 +1,123 @@
+import { Event } from './Event';
+import type { Listener } from './Listener';
+import type { PlanetCore } from './PlanetCore';
+/**
+ * Listener registration metadata.
+ */
+interface ListenerRegistration<TEvent extends Event = Event> {
+    listener: Listener<TEvent> | (new () => Listener<TEvent>);
+    queue?: string;
+    connection?: string;
+    delay?: number;
+}
+/**
+ * Event manager.
+ *
+ * Provides type-safe event dispatching and listener registration.
+ * Supports both synchronous listeners and asynchronous (queued) listeners.
+ *
+ * @example
+ * ```typescript
+ * class UserRegistered extends Event {
+ *   constructor(public user: User) {
+ *     super()
+ *   }
+ * }
+ *
+ * class SendWelcomeEmail implements Listener<UserRegistered> {
+ *   async handle(event: UserRegistered): Promise<void> {
+ *     // send welcome email
+ *   }
+ * }
+ *
+ * // Register listener
+ * core.events.listen(UserRegistered, SendWelcomeEmail)
+ *
+ * // Dispatch event
+ * await core.events.dispatch(new UserRegistered(user))
+ * ```
+ */
+export declare class EventManager {
+    private core;
+    /**
+     * Listener registry.
+     * Key: event class or event name
+     * Value: listener registrations
+     */
+    private listeners;
+    /**
+     * Broadcast manager (optional, injected by `orbit-broadcasting`).
+     */
+    private broadcastManager;
+    /**
+     * Queue manager (optional, injected by `orbit-queue`).
+     */
+    private queueManager;
+    constructor(core: PlanetCore);
+    /**
+     * Register the broadcast manager (called by `orbit-broadcasting`).
+     */
+    setBroadcastManager(manager: EventManager['broadcastManager']): void;
+    /**
+     * Register the queue manager (called by `orbit-queue`).
+     */
+    setQueueManager(manager: EventManager['queueManager']): void;
+    /**
+     * Register an event listener.
+     *
+     * @param event - Event class or event name
+     * @param listener - Listener instance or listener class
+     * @param options - Optional queue options
+     *
+     * @example
+     * ```typescript
+     * // Synchronous listener
+     * core.events.listen(UserRegistered, SendWelcomeEmail)
+     *
+     * // Queued listener (async)
+     * core.events.listen(UserRegistered, SendWelcomeEmail, {
+     *   queue: 'emails',
+     *   delay: 60
+     * })
+     * ```
+     */
+    listen<TEvent extends Event>(event: string | (new (...args: unknown[]) => TEvent), listener: Listener<TEvent> | (new () => Listener<TEvent>), options?: {
+        queue?: string;
+        connection?: string;
+        delay?: number;
+    }): void;
+    /**
+     * Remove an event listener.
+     *
+     * @param event - Event class or event name
+     * @param listener - Listener to remove
+     */
+    unlisten<TEvent extends Event>(event: string | (new (...args: unknown[]) => TEvent), listener: Listener<TEvent> | (new () => Listener<TEvent>)): void;
+    /**
+     * Dispatch an event.
+     *
+     * Runs all registered listeners. If a listener implements `ShouldQueue` or
+     * has queue options, the listener will be pushed to the queue for async execution.
+     *
+     * @param event - Event instance
+     *
+     * @example
+     * ```typescript
+     * await core.events.dispatch(new UserRegistered(user))
+     * ```
+     */
+    dispatch<TEvent extends Event>(event: TEvent): Promise<void>;
+    /**
+     * Serialize an event (for queueing).
+     */
+    private serializeEvent;
+    /**
+     * Get all registered listeners.
+     */
+    getListeners(event?: string | (new () => Event)): ListenerRegistration[];
+    /**
+     * Clear all listeners.
+     */
+    clear(): void;
+}
+export {};

package/dist/GlobalErrorHandlers.d.ts

@@ -0,0 +1,47 @@
+import type { Logger } from './Logger';
+import type { PlanetCore } from './PlanetCore';
+/**
+ * Type of process-level error
+ * @public
+ */
+export type GlobalProcessErrorKind = 'unhandledRejection' | 'uncaughtException';
+/**
+ * Context payload for global error handler filters/actions
+ * @public
+ */
+export type GlobalProcessErrorHandlerContext = {
+    core?: PlanetCore;
+    kind: GlobalProcessErrorKind;
+    error: unknown;
+    isProduction: boolean;
+    timestamp: number;
+    logLevel?: 'error' | 'warn' | 'info' | 'none';
+    logMessage?: string;
+    exit?: boolean;
+    exitCode?: number;
+    gracePeriodMs?: number;
+};
+/**
+ * Error handling strategy
+ * @public
+ */
+export type GlobalErrorHandlersMode = 'log' | 'exit' | 'exitInProduction';
+/**
+ * Options for registering global handlers
+ * @public
+ */
+export type RegisterGlobalErrorHandlersOptions = {
+    core?: PlanetCore;
+    logger?: Logger;
+    mode?: GlobalErrorHandlersMode;
+    exitCode?: number;
+    gracePeriodMs?: number;
+};
+/**
+ * Register process-level error handlers (`unhandledRejection` / `uncaughtException`).
+ *
+ * - `mode: "log"`: only log/report
+ * - `mode: "exit"`: report then `process.exit(exitCode)`
+ * - `mode: "exitInProduction"`: exit only when `NODE_ENV=production` (default)
+ */
+export declare function registerGlobalErrorHandlers(options?: RegisterGlobalErrorHandlersOptions): () => void;

package/dist/GravitoServer.d.ts

@@ -0,0 +1,28 @@
+import { type GravitoConfig, PlanetCore } from './PlanetCore';
+/**
+ * Manifest describing a Gravito application structure.
+ * @public
+ */
+export interface GravitoManifest {
+    name: string;
+    version?: string;
+    modules: string[];
+    config?: GravitoConfig;
+}
+/**
+ * Function type for asynchronous module resolution.
+ * @public
+ */
+export type ModuleResolver = () => Promise<any>;
+/**
+ * Gravito 核心啟動引擎 (已解耦)
+ */
+export declare class GravitoServer {
+    /**
+     * 一鍵建立並組裝伺服器
+     * @param manifest 站點描述清單
+     * @param resolvers 模組解析器字典
+     * @param baseOrbits 基礎軌道模組 (例如 OrbitMonolith)
+     */
+    static create(manifest: GravitoManifest, resolvers: Record<string, ModuleResolver>, baseOrbits?: any[]): Promise<PlanetCore>;
+}