@gravito/cosmos 2.0.0 → 3.0.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @gravito/cosmos
 
+## 3.0.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @gravito/core@1.2.0
+
 ## 2.0.0
 
 ### Patch Changes

package/dist/core/src/Application.d.ts

@@ -0,0 +1,185 @@
+/**
+ * @fileoverview Application - Enterprise Application Container
+ *
+ * A high-level application class that orchestrates the entire framework.
+ * Provides a centralized entry point for enterprise applications with
+ * auto-discovery of providers, config loading, and lifecycle management.
+ *
+ * @module @gravito/core
+ * @since 2.0.0
+ */
+import { ConfigManager } from './ConfigManager';
+import { Container } from './Container';
+import type { EventManager } from './EventManager';
+import type { Logger } from './Logger';
+import { PlanetCore } from './PlanetCore';
+import type { ServiceProvider } from './ServiceProvider';
+export interface ApplicationConfig {
+    /**
+     * Base path of the application
+     */
+    basePath: string;
+    /**
+     * Path to the config directory (relative to basePath)
+     * @default 'config'
+     */
+    configPath?: string;
+    /**
+     * Path to the providers directory (relative to basePath)
+     * @default 'src/Providers'
+     */
+    providersPath?: string;
+    /**
+     * Environment (development, production, testing)
+     */
+    env?: 'development' | 'production' | 'testing';
+    /**
+     * Logger instance
+     */
+    logger?: Logger;
+    /**
+     * Initial configuration values
+     */
+    config?: Record<string, unknown>;
+    /**
+     * Service providers to register
+     */
+    providers?: ServiceProvider[];
+    /**
+     * Whether to auto-discover providers from providersPath
+     * @default true
+     */
+    autoDiscoverProviders?: boolean;
+}
+/**
+ * Application - Enterprise-grade application container.
+ *
+ * Provides a higher-level abstraction over PlanetCore for building
+ * enterprise applications with convention-over-configuration patterns.
+ *
+ * @example
+ * ```typescript
+ * // Create application
+ * const app = new Application({
+ *   basePath: import.meta.dir,
+ *   env: process.env.NODE_ENV as 'development' | 'production',
+ * });
+ *
+ * // Boot the application
+ * await app.boot();
+ *
+ * // Access core
+ * export default app.core.liftoff();
+ * ```
+ */
+export declare class Application {
+    /**
+     * The underlying PlanetCore instance.
+     */
+    readonly core: PlanetCore;
+    /**
+     * The IoC container.
+     */
+    readonly container: Container;
+    /**
+     * The configuration manager.
+     */
+    readonly config: ConfigManager;
+    /**
+     * The event manager.
+     */
+    readonly events: EventManager;
+    /**
+     * The logger instance.
+     */
+    readonly logger: Logger;
+    /**
+     * Application base path.
+     */
+    readonly basePath: string;
+    /**
+     * Environment mode.
+     */
+    readonly env: 'development' | 'production' | 'testing';
+    /**
+     * Configuration options.
+     */
+    private readonly options;
+    /**
+     * Whether the application has been booted.
+     */
+    private booted;
+    constructor(options: ApplicationConfig);
+    /**
+     * Boot the application.
+     *
+     * This will:
+     * 1. Load configuration files
+     * 2. Auto-discover providers (if enabled)
+     * 3. Register all providers
+     * 4. Bootstrap the core
+     *
+     * @returns Promise that resolves when boot is complete
+     */
+    boot(): Promise<this>;
+    /**
+     * Load configuration files from the config directory.
+     *
+     * @internal
+     */
+    private loadConfiguration;
+    /**
+     * Discover and register providers from the providers directory.
+     *
+     * @internal
+     */
+    private discoverProviders;
+    /**
+     * Get a service from the container.
+     *
+     * @param key - The service key
+     * @returns The resolved service
+     */
+    make<T>(key: string): T;
+    /**
+     * Check if a service is bound.
+     *
+     * @param key - The service key
+     * @returns True if bound
+     */
+    has(key: string): boolean;
+    /**
+     * Get a configuration value.
+     *
+     * @param key - The config key (supports dot notation)
+     * @param defaultValue - Default value if not found
+     * @returns The config value
+     */
+    getConfig<T>(key: string, defaultValue?: T): T;
+    /**
+     * Create application path helper.
+     *
+     * @param segments - Path segments relative to base path
+     * @returns Absolute path
+     */
+    path(...segments: string[]): string;
+    /**
+     * Get the config path.
+     *
+     * @param segments - Additional path segments
+     * @returns Absolute path to config directory
+     */
+    configPath(...segments: string[]): string;
+    /**
+     * Check if running in production.
+     */
+    isProduction(): boolean;
+    /**
+     * Check if running in development.
+     */
+    isDevelopment(): boolean;
+    /**
+     * Check if running in testing.
+     */
+    isTesting(): boolean;
+}

package/dist/core/src/ConfigManager.d.ts

@@ -0,0 +1,21 @@
+export declare class ConfigManager {
+    private config;
+    constructor(initialConfig?: Record<string, unknown>);
+    /**
+     * Load all environment variables from the active runtime.
+     */
+    private loadEnv;
+    /**
+     * Get a configuration value (generic return type supported).
+     * Supports dot notation for deep access (e.g. 'app.name').
+     */
+    get<T = unknown>(key: string, defaultValue?: T): T;
+    /**
+     * Set a configuration value.
+     */
+    set(key: string, value: unknown): void;
+    /**
+     * Check whether a key exists.
+     */
+    has(key: string): boolean;
+}

package/dist/core/src/Container.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Factory type for creating service instances
+ */
+export type Factory<T> = (container: Container) => T;
+export declare class Container {
+    private bindings;
+    private instances;
+    /**
+     * Bind a service to the container.
+     * New instance will be created on each resolution.
+     */
+    bind<T>(key: string, factory: Factory<T>): void;
+    /**
+     * Bind a shared service to the container (Singleton).
+     * Same instance will be returned on each resolution.
+     */
+    singleton<T>(key: string, factory: Factory<T>): void;
+    /**
+     * Register an existing instance as shared service.
+     */
+    instance<T>(key: string, instance: T): void;
+    /**
+     * Resolve a service from the container.
+     */
+    make<T>(key: string): T;
+    /**
+     * Check if a service is bound.
+     */
+    has(key: string): boolean;
+    /**
+     * Flush all instances and bindings.
+     */
+    flush(): void;
+    /**
+     * Forget a specific instance (but keep binding)
+     */
+    forget(key: string): void;
+}

package/dist/core/src/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/core/src/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/core/src/GlobalErrorHandlers.d.ts

@@ -0,0 +1,31 @@
+import type { Logger } from './Logger';
+import type { PlanetCore } from './PlanetCore';
+export type GlobalProcessErrorKind = 'unhandledRejection' | 'uncaughtException';
+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;
+};
+export type GlobalErrorHandlersMode = 'log' | 'exit' | 'exitInProduction';
+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/core/src/GravitoServer.d.ts

@@ -0,0 +1,20 @@
+import { type GravitoConfig, PlanetCore } from './PlanetCore';
+export interface GravitoManifest {
+    name: string;
+    version?: string;
+    modules: string[];
+    config?: GravitoConfig;
+}
+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>;
+}

package/dist/core/src/HookManager.d.ts

@@ -0,0 +1,70 @@
+export type FilterCallback<T = unknown> = (value: T, ...args: unknown[]) => Promise<T> | T;
+export type ActionCallback<TArgs = unknown> = (args: TArgs) => Promise<void> | void;
+export declare class HookManager {
+    private filters;
+    private actions;
+    /**
+     * Register a filter hook.
+     *
+     * Filters are used to transform a value (input/output).
+     *
+     * @template T - The type of value being filtered.
+     * @param hook - The name of the hook.
+     * @param callback - The callback function to execute.
+     *
+     * @example
+     * ```typescript
+     * core.hooks.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 core.hooks.applyFilters('content', 'hello world');
+     * ```
+     */
+    applyFilters<T = unknown>(hook: string, initialValue: T, ...args: unknown[]): Promise<T>;
+    /**
+     * Register an action hook.
+     *
+     * Actions are for side effects (no return value).
+     *
+     * @template TArgs - The type of arguments passed to the action.
+     * @param hook - The name of the hook.
+     * @param callback - The callback function to execute.
+     *
+     * @example
+     * ```typescript
+     * core.hooks.addAction('user_registered', async (user: User) => {
+     *   await sendWelcomeEmail(user);
+     * });
+     * ```
+     */
+    addAction<TArgs = unknown>(hook: string, callback: ActionCallback<TArgs>): void;
+    /**
+     * Run all registered actions sequentially.
+     *
+     * @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.
+     *
+     * @example
+     * ```typescript
+     * await core.hooks.doAction('user_registered', user);
+     * ```
+     */
+    doAction<TArgs = unknown>(hook: string, args: TArgs): Promise<void>;
+}

package/dist/core/src/Listener.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Listener-related types and interfaces.
+ */
+export type { Listener, ShouldQueue } from './types/events';

package/dist/core/src/Logger.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Standard logger interface.
+ *
+ * PSR-3 inspired API for easy swapping (e.g., Winston, Pino).
+ */
+export interface Logger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * Default console logger implementation.
+ */
+export declare class ConsoleLogger implements Logger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}