@gravito/core 1.0.0-beta.6

package/dist/index.d.cts

@@ -0,0 +1,2031 @@
+import { Variables as GravitoVariables, HttpMethod, Handler as GravitoHandler, MiddlewareHandler as GravitoMiddleware, GravitoErrorHandler, GravitoNotFoundHandler, Context as GravitoContext, ContentfulStatusCode, GravitoRequest, StatusCode } from './compat.cjs';
+export { Next as GravitoNext, ValidationTarget } from './compat.cjs';
+import { Photon, Context } from '@gravito/photon';
+
+/**
+ * @fileoverview HTTP Adapter Interface for Gravito Framework
+ *
+ * This module defines the contract that all HTTP adapters must implement.
+ * By programming to this interface, Gravito can swap out the underlying
+ * HTTP engine without changing application code.
+ *
+ * @module @gravito/core/adapters
+ * @since 2.0.0
+ */
+
+/**
+ * Configuration options for HTTP adapters
+ */
+interface AdapterConfig {
+    /**
+     * Base path prefix for all routes
+     * @default ''
+     */
+    basePath?: string;
+    /**
+     * Whether to enable strict routing (trailing slashes matter)
+     * @default false
+     */
+    strictRouting?: boolean;
+    /**
+     * Custom options passed to the underlying HTTP engine
+     */
+    engineOptions?: Record<string, unknown>;
+}
+/**
+ * Route definition structure
+ */
+interface RouteDefinition {
+    method: HttpMethod;
+    path: string;
+    handlers: (GravitoHandler | GravitoMiddleware)[];
+    name?: string;
+    middleware?: GravitoMiddleware[];
+}
+/**
+ * HttpAdapter - The core interface for HTTP engine abstraction
+ *
+ * Any HTTP engine (Photon, Express, Fastify, custom Bun implementation)
+ * must implement this interface to be usable with Gravito.
+ *
+ * @typeParam V - Context variables type
+ *
+ * @example
+ * ```typescript
+ * // Using the default Photon adapter
+ * import { PhotonAdapter } from '@gravito/core/adapters'
+ *
+ * const core = new PlanetCore({
+ *   adapter: new PhotonAdapter()
+ * })
+ *
+ * // Using a custom adapter
+ * import { BunNativeAdapter } from '@gravito/adapter-bun'
+ *
+ * const core = new PlanetCore({
+ *   adapter: new BunNativeAdapter()
+ * })
+ * ```
+ */
+interface HttpAdapter<V extends GravitoVariables = GravitoVariables> {
+    /**
+     * Adapter name for identification
+     * @example 'photon', 'bun-native', 'express'
+     */
+    readonly name: string;
+    /**
+     * Adapter version
+     */
+    readonly version: string;
+    /**
+     * Access the underlying native HTTP engine instance.
+     *
+     * ⚠️ WARNING: Using this ties your code to a specific adapter.
+     *
+     * @example
+     * ```typescript
+     * // For Photon adapter
+     * const photonApp = adapter.native as Photon
+     *
+     * // For custom Bun adapter
+     * const bunApp = adapter.native as BunApp
+     * ```
+     */
+    readonly native: unknown;
+    /**
+     * Register a route with the adapter
+     *
+     * @param method - HTTP method
+     * @param path - Route path (may include parameters like ':id')
+     * @param handlers - One or more handlers for this route (handlers or middleware)
+     */
+    route(method: HttpMethod, path: string, ...handlers: (GravitoHandler<V> | GravitoMiddleware<V>)[]): void;
+    /**
+     * Register multiple routes at once
+     *
+     * @param routes - Array of route definitions
+     */
+    routes(routes: RouteDefinition[]): void;
+    /**
+     * Register a middleware for a path
+     *
+     * @param path - Path pattern to match
+     * @param middleware - One or more middleware functions
+     */
+    use(path: string, ...middleware: GravitoMiddleware<V>[]): void;
+    /**
+     * Register a global middleware (applied to all routes)
+     *
+     * @param middleware - Middleware function
+     */
+    useGlobal(...middleware: GravitoMiddleware<V>[]): void;
+    /**
+     * Mount a sub-adapter at a path
+     *
+     * @param path - Mount path
+     * @param subAdapter - The adapter to mount
+     */
+    mount(path: string, subAdapter: HttpAdapter<V>): void;
+    /**
+     * Set the error handler
+     *
+     * @param handler - Error handler function
+     */
+    onError(handler: GravitoErrorHandler<V>): void;
+    /**
+     * Set the not-found handler
+     *
+     * @param handler - Not-found handler function
+     */
+    onNotFound(handler: GravitoNotFoundHandler<V>): void;
+    /**
+     * The main fetch handler for serving requests.
+     *
+     * This is compatible with `Bun.serve()`, Cloudflare Workers,
+     * and other fetch-based runtimes.
+     *
+     * @param request - Incoming HTTP request
+     * @param server - Optional server context (Bun.Server, etc.)
+     * @returns HTTP response
+     *
+     * @example
+     * ```typescript
+     * // With Bun.serve
+     * Bun.serve({
+     *   port: 3000,
+     *   fetch: adapter.fetch
+     * })
+     * ```
+     */
+    fetch(request: Request, server?: unknown): Response | Promise<Response>;
+    /**
+     * Initialize the adapter
+     *
+     * Called during PlanetCore.boot()
+     */
+    init?(): void | Promise<void>;
+    /**
+     * Cleanup resources
+     *
+     * Called during graceful shutdown
+     */
+    shutdown?(): void | Promise<void>;
+    /**
+     * Create a GravitoContext from a raw request.
+     *
+     * This is used internally for testing and advanced scenarios.
+     *
+     * @param request - Raw HTTP request
+     * @returns Gravito context
+     */
+    createContext(request: Request): GravitoContext<V>;
+}
+/**
+ * Factory function type for creating adapters
+ */
+type AdapterFactory<V extends GravitoVariables = GravitoVariables> = (config?: AdapterConfig) => HttpAdapter<V>;
+/**
+ * Check if a value is an HttpAdapter
+ */
+declare function isHttpAdapter(value: unknown): value is HttpAdapter;
+
+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;
+}
+
+/**
+ * Factory type for creating service instances
+ */
+type Factory<T> = (container: Container) => T;
+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;
+}
+
+/**
+ * Event system type definitions.
+ */
+/**
+ * Listener interface.
+ *
+ * All event listeners must implement this interface.
+ */
+interface Listener<TEvent extends Event = Event> {
+    /**
+     * Handle an event.
+     * @param event - Event instance
+     */
+    handle(event: TEvent): Promise<void> | void;
+}
+/**
+ * Marker interface for listeners that should be queued.
+ *
+ * Listeners implementing this interface can be dispatched asynchronously via a queue.
+ */
+interface ShouldQueue {
+    /**
+     * Queue name (optional).
+     */
+    queue?: string;
+    /**
+     * Connection name (optional).
+     */
+    connection?: string;
+    /**
+     * Delay before execution (seconds).
+     */
+    delay?: number;
+}
+/**
+ * Marker interface for events that should be broadcast.
+ *
+ * Events implementing this interface can be automatically broadcast to clients.
+ */
+interface ShouldBroadcast {
+    /**
+     * Define the broadcast channel.
+     * @returns Channel name or channel object
+     */
+    broadcastOn(): string | Channel;
+    /**
+     * Define broadcast payload (optional).
+     * If omitted, public event properties will be used.
+     * @returns Broadcast payload
+     */
+    broadcastWith?(): Record<string, unknown>;
+    /**
+     * Define the broadcast event name (optional).
+     * If omitted, the event class name will be used.
+     * @returns Event name
+     */
+    broadcastAs?(): string;
+}
+/**
+ * Channel interface.
+ */
+interface Channel {
+    /**
+     * Channel name.
+     */
+    name: string;
+    /**
+     * Channel type.
+     */
+    type: 'public' | 'private' | 'presence';
+}
+/**
+ * Base event class.
+ *
+ * All events should extend this class.
+ */
+declare abstract class Event {
+    /**
+     * Whether this event should be broadcast.
+     */
+    shouldBroadcast(): boolean;
+    /**
+     * Get broadcast channel.
+     */
+    getBroadcastChannel(): string | Channel | null;
+    /**
+     * Get broadcast payload.
+     */
+    getBroadcastData(): Record<string, unknown>;
+    /**
+     * Get broadcast event name.
+     */
+    getBroadcastEventName(): string;
+}
+
+/**
+ * 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))
+ * ```
+ */
+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;
+}
+
+/**
+ * Standard logger interface.
+ *
+ * PSR-3 inspired API for easy swapping (e.g., Winston, Pino).
+ */
+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.
+ */
+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;
+}
+
+type GlobalProcessErrorKind = 'unhandledRejection' | 'uncaughtException';
+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;
+};
+type GlobalErrorHandlersMode = 'log' | 'exit' | 'exitInProduction';
+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)
+ */
+declare function registerGlobalErrorHandlers(options?: RegisterGlobalErrorHandlersOptions): () => void;
+
+type FilterCallback<T = unknown> = (value: T, ...args: unknown[]) => Promise<T> | T;
+type ActionCallback<TArgs = unknown> = (args: TArgs) => Promise<void> | void;
+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>;
+}
+
+type ApiSuccess<T> = {
+    success: true;
+    data: T;
+};
+type ApiFailure = {
+    success: false;
+    error: {
+        message: string;
+        code?: string;
+        details?: unknown;
+    };
+};
+declare function ok<T>(data: T): ApiSuccess<T>;
+declare function fail(message: string, code?: string, details?: unknown): ApiFailure;
+declare function jsonSuccess<T>(c: GravitoContext, data: T, status?: ContentfulStatusCode): Response;
+declare function jsonFail(c: GravitoContext, message: string, status?: ContentfulStatusCode, code?: string, details?: unknown): Response;
+
+/**
+ * ServiceProvider - The foundation for modular service registration.
+ *
+ * Service providers are the central place to configure your application.
+ * They bind services to the container and bootstrap application features.
+ *
+ * Lifecycle:
+ * 1. register() - Called during registration phase (sync or async)
+ * 2. boot() - Called after ALL providers have registered
+ *
+ * @since 1.0.0
+ * @example
+ * ```typescript
+ * class DatabaseServiceProvider extends ServiceProvider {
+ *   register(container: Container) {
+ *     container.singleton('db', () => new DatabaseManager());
+ *   }
+ *
+ *   boot(core: PlanetCore) {
+ *     const db = core.container.make<DatabaseManager>('db');
+ *     db.setDefaultConnection(core.config.get('database.default'));
+ *   }
+ * }
+ * ```
+ */
+declare abstract class ServiceProvider {
+    /**
+     * Reference to the application core instance.
+     * Set during provider registration.
+     */
+    protected core?: PlanetCore;
+    /**
+     * Whether this provider should be deferred.
+     * Deferred providers are only registered when one of their
+     * provided services is actually requested from the container.
+     */
+    deferred: boolean;
+    /**
+     * Get the services provided by this provider.
+     * Used for deferred loading - provider is only loaded when
+     * one of these services is requested.
+     *
+     * @returns Array of service keys this provider offers
+     *
+     * @example
+     * ```typescript
+     * provides(): string[] {
+     *   return ['db', 'db.connection'];
+     * }
+     * ```
+     */
+    provides(): string[];
+    /**
+     * Register bindings in the container.
+     *
+     * This method is called during the registration phase.
+     * **Warning**: Do not resolve services from other providers here,
+     * as they may not be registered yet.
+     *
+     * Supports both synchronous and asynchronous registration.
+     *
+     * @param container - The IoC container instance
+     */
+    abstract register(container: Container): void | Promise<void>;
+    /**
+     * Bootstrap any application services.
+     *
+     * This method is called after ALL providers have registered.
+     * You can safely resolve services from the container here.
+     *
+     * @param core - The PlanetCore application instance
+     */
+    boot?(core: PlanetCore): void | Promise<void>;
+    /**
+     * Set the core instance reference.
+     * Called internally by the application during registration.
+     *
+     * @internal
+     */
+    setCore(core: PlanetCore): void;
+    /**
+     * Merge configuration from a file into the application config.
+     *
+     * @param config - The ConfigManager instance
+     * @param key - The configuration key to set
+     * @param value - The configuration value or object
+     *
+     * @example
+     * ```typescript
+     * this.mergeConfig(config, 'database', {
+     *   default: 'mysql',
+     *   connections: { ... }
+     * });
+     * ```
+     */
+    protected mergeConfig(config: ConfigManager, key: string, value: unknown): void;
+    /**
+     * Merge configuration from an async loader.
+     * Useful for loading config from .ts files dynamically.
+     *
+     * @param config - The ConfigManager instance
+     * @param key - The configuration key
+     * @param loader - Async function that returns config value
+     *
+     * @example
+     * ```typescript
+     * await this.mergeConfigFrom(config, 'database', async () => {
+     *   return (await import('./config/database')).default;
+     * });
+     * ```
+     */
+    protected mergeConfigFrom(config: ConfigManager, key: string, loader: () => Promise<unknown>): Promise<void>;
+    /**
+     * Paths that should be published by the CLI.
+     * Maps source paths to destination paths.
+     */
+    private static publishables;
+    /**
+     * Register paths to be published.
+     * Used by CLI commands like `gravito vendor:publish`.
+     *
+     * @param paths - Map of source to destination paths
+     * @param group - Optional group name for selective publishing
+     *
+     * @example
+     * ```typescript
+     * this.publishes({
+     *   './config/cache.ts': 'config/cache.ts',
+     *   './views/errors': 'resources/views/errors'
+     * }, 'config');
+     * ```
+     */
+    protected publishes(paths: Record<string, string>, group?: string): void;
+    /**
+     * Get all publishable paths for a group.
+     *
+     * @param group - The group name (defaults to provider class name)
+     * @returns Map of source to destination paths
+     */
+    static getPublishables(group?: string): Map<string, string>;
+    /**
+     * Get all publish groups.
+     *
+     * @returns Array of group names
+     */
+    static getPublishGroups(): string[];
+}
+
+declare class Route {
+    private router;
+    private method;
+    private path;
+    private options;
+    constructor(router: Router, method: string, path: string, options: RouteOptions);
+    /**
+     * Name the route
+     */
+    name(name: string): this;
+    static get(path: string, handler: RouteHandler): Route;
+    static get(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    static post(path: string, handler: RouteHandler): Route;
+    static post(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    static put(path: string, handler: RouteHandler): Route;
+    static put(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    static delete(path: string, handler: RouteHandler): Route;
+    static delete(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    static patch(path: string, handler: RouteHandler): Route;
+    static patch(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    static resource(name: string, controller: ControllerClass, options?: ResourceOptions): void;
+    static prefix(path: string): RouteGroup;
+    static middleware(...handlers: any[]): RouteGroup;
+}
+
+type ControllerClass = new (core: PlanetCore) => Record<string, unknown>;
+type RouteHandler = GravitoHandler | [ControllerClass, string];
+/**
+ * Interface for FormRequest classes (from @gravito/impulse).
+ * Used for duck-typing detection without hard dependency.
+ */
+interface FormRequestLike {
+    schema: unknown;
+    source?: string;
+    validate?(ctx: unknown): Promise<{
+        success: boolean;
+        data?: unknown;
+        error?: unknown;
+    }>;
+}
+/**
+ * Type for FormRequest class constructor
+ */
+type FormRequestClass = new () => FormRequestLike;
+interface RouteOptions {
+    prefix?: string;
+    domain?: string;
+    middleware?: GravitoMiddleware[];
+}
+/**
+ * RouteGroup
+ * Helper class for chained route configuration (prefix, domain, etc.)
+ */
+declare class RouteGroup {
+    private router;
+    private options;
+    constructor(router: Router, options: RouteOptions);
+    /**
+     * Add a prefix to the current group
+     */
+    prefix(path: string): RouteGroup;
+    /**
+     * Add middleware to the current group.
+     * Accepts individual handlers or arrays of handlers.
+     */
+    middleware(...handlers: (GravitoMiddleware | GravitoMiddleware[])[]): RouteGroup;
+    /**
+     * Define routes within this group
+     */
+    group(callback: (router: Router | RouteGroup) => void): void;
+    get(path: string, handler: RouteHandler): Route;
+    get(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    post(path: string, handler: RouteHandler): Route;
+    post(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    put(path: string, handler: RouteHandler): Route;
+    put(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    delete(path: string, handler: RouteHandler): Route;
+    delete(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    patch(path: string, handler: RouteHandler): Route;
+    patch(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    resource(name: string, controller: ControllerClass, options?: ResourceOptions): void;
+}
+/**
+ * Gravito Router
+ *
+ * Provides a Laravel-like fluent API for defining routes.
+ * Supports:
+ * - Controller-based routing: router.get('/', [HomeController, 'index'])
+ * - Route groups with prefixes: router.prefix('/api').group(...)
+ * - Domain-based routing: router.domain('api.app').group(...)
+ * - Middleware chaining: router.middleware(auth).group(...)
+ * - FormRequest validation: router.post('/users', StoreUserRequest, [UserController, 'store'])
+ */
+declare class Router {
+    private core;
+    routes: Array<{
+        method: string;
+        path: string;
+    }>;
+    private controllers;
+    private namedRoutes;
+    private bindings;
+    /**
+     * Compile all registered routes into a flat array for caching or manifest generation.
+     */
+    compile(): {
+        method: string;
+        path: string;
+        name?: string;
+        domain?: string | undefined;
+    }[];
+    /**
+     * Register a named route
+     */
+    registerName(name: string, method: string, path: string, options?: RouteOptions): void;
+    /**
+     * Generate a URL from a named route.
+     */
+    url(name: string, params?: Record<string, string | number>, query?: Record<string, string | number | boolean | null | undefined>): string;
+    /**
+     * Export named routes as a serializable manifest (for caching).
+     */
+    exportNamedRoutes(): Record<string, {
+        method: string;
+        path: string;
+        domain?: string;
+    }>;
+    /**
+     * Load named routes from a manifest (for caching).
+     */
+    loadNamedRoutes(manifest: Record<string, {
+        method: string;
+        path: string;
+        domain?: string;
+    }>): void;
+    /**
+     * Register a route model binding.
+     */
+    bind(param: string, resolver: (id: string) => Promise<unknown>): void;
+    /**
+     * Register a route model binding for a Model class.
+     */
+    model(param: string, modelClass: unknown): void;
+    constructor(core: PlanetCore);
+    /**
+     * Start a route group with a prefix
+     */
+    prefix(path: string): RouteGroup;
+    /**
+     * Start a route group with a domain constraint
+     */
+    domain(host: string): RouteGroup;
+    /**
+     * Start a route group with middleware.
+     * Accepts individual handlers or arrays of handlers.
+     */
+    middleware(...handlers: (GravitoMiddleware | GravitoMiddleware[])[]): RouteGroup;
+    /**
+     * Register a GET route.
+     *
+     * @param path - The URL path for the route.
+     * @param handler - The handler function or controller method.
+     * @returns The registered Route instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * router.get('/users', [UserController, 'index']);
+     * ```
+     */
+    get(path: string, handler: RouteHandler): Route;
+    /**
+     * Register a GET route with a FormRequest for validation.
+     *
+     * @param path - The URL path.
+     * @param request - The FormRequest class for validation.
+     * @param handler - The handler function or controller method.
+     *
+     * @example
+     * ```typescript
+     * router.get('/search', SearchRequest, [Controller, 'search']);
+     * ```
+     */
+    get(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    /**
+     * Register a POST route.
+     *
+     * @param path - The URL path.
+     * @param handler - The handler function or controller method.
+     * @returns The registered Route instance.
+     *
+     * @example
+     * ```typescript
+     * router.post('/users', [UserController, 'store']);
+     * ```
+     */
+    post(path: string, handler: RouteHandler): Route;
+    /**
+     * Register a POST route with validation.
+     *
+     * @param path - The URL path.
+     * @param request - The FormRequest class.
+     * @param handler - The handler.
+     *
+     * @example
+     * ```typescript
+     * router.post('/users', StoreUserRequest, [UserController, 'store']);
+     * ```
+     */
+    post(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    /**
+     * Register a PUT route.
+     *
+     * @param path - The URL path.
+     * @param handler - The handler function.
+     * @returns The registered Route instance.
+     */
+    put(path: string, handler: RouteHandler): Route;
+    put(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    /**
+     * Register a DELETE route.
+     *
+     * @param path - The URL path.
+     * @param handler - The handler function.
+     * @returns The registered Route instance.
+     */
+    delete(path: string, handler: RouteHandler): Route;
+    delete(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    /**
+     * Register a PATCH route.
+     *
+     * @param path - The URL path.
+     * @param handler - The handler function.
+     * @returns The registered Route instance.
+     */
+    patch(path: string, handler: RouteHandler): Route;
+    patch(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    /**
+     * Register a resource route (Laravel-style).
+     */
+    resource(name: string, controller: ControllerClass, options?: ResourceOptions): void;
+    /**
+     * Internal Request Registration
+     */
+    req(method: HttpMethod, path: string, requestOrHandler: FormRequestClass | RouteHandler, handler?: RouteHandler, options?: RouteOptions): Route;
+    /**
+     * Resolve Controller Instance and Method
+     */
+    private resolveControllerHandler;
+}
+type ResourceAction = 'index' | 'create' | 'store' | 'show' | 'edit' | 'update' | 'destroy';
+interface ResourceOptions {
+    only?: ResourceAction[];
+    except?: ResourceAction[];
+}
+
+interface EncrypterOptions {
+    key: string;
+    cipher?: string;
+}
+declare class Encrypter {
+    private algorithm;
+    private key;
+    constructor(options: EncrypterOptions);
+    /**
+     * Encrypt a value
+     */
+    encrypt(value: unknown, serialize?: boolean): string;
+    /**
+     * Decrypt a value
+     */
+    decrypt(payload: string, deserialize?: boolean): unknown;
+    private hash;
+    private validPayload;
+    private validMac;
+    /**
+     * Generate a new key
+     */
+    static generateKey(cipher?: string): string;
+}
+
+/**
+ * Hashing interface
+ */
+interface Hasher {
+    /**
+     * Hash the given value
+     */
+    make(value: string, options?: Record<string, unknown>): Promise<string>;
+    /**
+     * Check the given plain value against a hash
+     */
+    check(value: string, hashedValue: string): Promise<boolean>;
+    /**
+     * Check if the given hash has been hashed using the given options
+     */
+    needsRehash(hashedValue: string, options?: Record<string, unknown>): boolean;
+}
+/**
+ * Bun Hasher
+ * Uses Bun's native password hashing (bcrypt by default)
+ */
+declare class BunHasher implements Hasher {
+    make(value: string, options?: {
+        algorithm?: 'bcrypt' | 'argon2id';
+        cost?: number;
+    }): Promise<string>;
+    check(value: string, hashedValue: string): Promise<boolean>;
+    needsRehash(_hashedValue: string, _options?: Record<string, unknown>): boolean;
+}
+
+/**
+ * @fileoverview PlanetCore - The Heart of Gravito Framework
+ *
+ * The micro-kernel that orchestrates the entire Galaxy Architecture.
+ * Manages HTTP routing, middleware, error handling, and orbit integration.
+ *
+ * @module @gravito/core
+ * @since 1.0.0
+ */
+
+/**
+ * CacheService interface for orbit-injected cache
+ * Orbits implementing cache should conform to this interface
+ */
+interface CacheService {
+    get<T = unknown>(key: string): Promise<T | null>;
+    set(key: string, value: unknown, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    remember<T>(key: string, ttl: number, callback: () => Promise<T>): Promise<T>;
+}
+interface ViewService {
+    render(view: string, data?: Record<string, unknown>, options?: Record<string, unknown>): string;
+}
+type ErrorHandlerContext = {
+    core: PlanetCore;
+    c: GravitoContext;
+    error: unknown;
+    isProduction: boolean;
+    accept: string;
+    wantsHtml: boolean;
+    status: ContentfulStatusCode;
+    payload: ReturnType<typeof fail>;
+    logLevel?: 'error' | 'warn' | 'info' | 'none';
+    logMessage?: string;
+    html?: {
+        templates: string[];
+        data: Record<string, unknown>;
+    };
+};
+interface GravitoOrbit {
+    install(core: PlanetCore): void | Promise<void>;
+}
+type GravitoConfig = {
+    logger?: Logger;
+    config?: Record<string, unknown>;
+    orbits?: (new () => GravitoOrbit)[] | GravitoOrbit[];
+    /**
+     * HTTP Adapter to use. Defaults to PhotonAdapter.
+     * @since 2.0.0
+     */
+    adapter?: HttpAdapter;
+};
+
+declare class PlanetCore {
+    /**
+     * The HTTP adapter used by this core instance.
+     * @since 2.0.0
+     */
+    private _adapter;
+    /**
+     * Access the underlying Photon app instance.
+     * @deprecated Use adapter methods for new code. This property is kept for backward compatibility.
+     */
+    get app(): unknown;
+    /**
+     * Get the HTTP adapter instance.
+     * @since 2.0.0
+     */
+    get adapter(): HttpAdapter;
+    logger: Logger;
+    config: ConfigManager;
+    hooks: HookManager;
+    events: EventManager;
+    router: Router;
+    container: Container;
+    /** @deprecated Use core.container instead */
+    services: Map<string, unknown>;
+    encrypter?: Encrypter;
+    hasher: BunHasher;
+    private providers;
+    private deferredProviders;
+    private bootedProviders;
+    /**
+     * Register a service provider.
+     *
+     * @param provider - The ServiceProvider instance to register.
+     * @returns The PlanetCore instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * core.register(new DatabaseServiceProvider());
+     * ```
+     */
+    register(provider: ServiceProvider): this;
+    /**
+     * Bootstrap the application by registering and booting providers.
+     *
+     * This method must be called before the application starts handling requests.
+     * It calls `register()` on all providers first, then `boot()` on all providers.
+     *
+     * Supports async register() methods.
+     *
+     * @returns Promise that resolves when bootstrapping is complete.
+     */
+    bootstrap(): Promise<void>;
+    /**
+     * Setup deferred provider resolution.
+     * Wraps container.make to auto-register deferred providers on first request.
+     *
+     * @internal
+     */
+    private setupDeferredProviderResolution;
+    /**
+     * Register a deferred provider on-demand.
+     *
+     * @internal
+     */
+    private registerDeferredProvider;
+    /**
+     * Boot a single provider if not already booted.
+     *
+     * @internal
+     */
+    private bootProvider;
+    constructor(options?: {
+        logger?: Logger;
+        config?: Record<string, unknown>;
+        adapter?: HttpAdapter;
+    });
+    /**
+     * Programmatically register an infrastructure module (Orbit).
+     * @since 2.0.0
+     *
+     * @param orbit - The orbit class or instance to register.
+     * @returns The PlanetCore instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * await core.orbit(OrbitCache);
+     * ```
+     */
+    orbit(orbit: GravitoOrbit | (new () => GravitoOrbit)): Promise<this>;
+    /**
+     * Programmatically register a feature module (Satellite).
+     * Alias for register() with provider support.
+     * @since 2.0.0
+     *
+     * @param satellite - The provider or setup function.
+     * @returns The PlanetCore instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * await core.use(new AuthProvider());
+     * ```
+     */
+    use(satellite: ServiceProvider | ((core: PlanetCore) => void | Promise<void>)): Promise<this>;
+    registerGlobalErrorHandlers(options?: Omit<RegisterGlobalErrorHandlersOptions, 'core'>): () => void;
+    /**
+     * Boot the application with a configuration object (IoC style default entry)
+     *
+     * @param config - The Gravito configuration object.
+     * @returns A Promise resolving to the booted PlanetCore instance.
+     *
+     * @example
+     * ```typescript
+     * const core = await PlanetCore.boot(config);
+     * ```
+     */
+    static boot(config: GravitoConfig): Promise<PlanetCore>;
+    /**
+     * Mount an Orbit (a Photon app) to a path.
+     *
+     * @param path - The URL path to mount the orbit at.
+     * @param orbitApp - The Photon application instance.
+     */
+    mountOrbit(path: string, orbitApp: unknown): void;
+    /**
+     * Start the core (Liftoff).
+     *
+     * Returns a config object for `Bun.serve`.
+     *
+     * @param port - Optional port number (defaults to config or 3000).
+     * @returns An object compatible with Bun.serve({ ... }).
+     *
+     * @example
+     * ```typescript
+     * export default core.liftoff(3000);
+     * ```
+     */
+    liftoff(port?: number): {
+        port: number;
+        fetch: (request: Request, server?: unknown) => Response | Promise<Response>;
+        core: PlanetCore;
+    };
+}
+
+/**
+ * @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
+ */
+
+/**
+ * Wraps Photon's request object to implement GravitoRequest
+ */
+declare class PhotonRequestWrapper implements GravitoRequest {
+    private photonCtx;
+    constructor(photonCtx: Context);
+    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 photonCtx;
+    private _req;
+    constructor(photonCtx: Context);
+    /**
+     * Create a proxied instance to enable object destructuring of context variables
+     * This allows: async list({ userService }: Context)
+     */
+    static create<V extends GravitoVariables = GravitoVariables>(photonCtx: Context): GravitoContext<V>;
+    get req(): GravitoRequest;
+    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;
+}
+/**
+ * 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!' })
+ * })
+ * ```
+ */
+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;
+    mount(path: string, subAdapter: HttpAdapter<V>): void;
+    onError(handler: GravitoErrorHandler<V>): void;
+    onNotFound(handler: GravitoNotFoundHandler<V>): 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
+ */
+declare function createPhotonAdapter<V extends GravitoVariables = GravitoVariables>(config?: AdapterConfig): PhotonAdapter<V>;
+
+/**
+ * Rebranded alias for PhotonAdapter.
+ * @category Rebranding
+ */
+declare const GravitoAdapter: typeof PhotonAdapter;
+type GravitoAdapter<V extends GravitoVariables = GravitoVariables> = PhotonAdapter<V>;
+/**
+ * Rebranded alias for createPhotonAdapter.
+ * @category Rebranding
+ */
+declare const createGravitoAdapter: typeof createPhotonAdapter;
+
+/**
+ * @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
+ */
+
+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();
+ * ```
+ */
+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;
+}
+
+interface ExceptionOptions {
+    message?: string;
+    cause?: unknown;
+    i18nKey?: string;
+    i18nParams?: Record<string, string | number>;
+}
+declare abstract class GravitoException extends Error {
+    readonly status: ContentfulStatusCode;
+    readonly code: string;
+    readonly i18nKey?: string;
+    readonly i18nParams?: Record<string, string | number>;
+    constructor(status: number, code: string, options?: ExceptionOptions);
+    getLocalizedMessage(t: (key: string, params?: Record<string, string | number>) => string): string;
+}
+
+declare class AuthenticationException extends GravitoException {
+    constructor(message?: string);
+}
+
+declare class AuthorizationException extends GravitoException {
+    constructor(message?: string);
+}
+
+declare class HttpException extends GravitoException {
+    constructor(status: ContentfulStatusCode, options?: ExceptionOptions);
+}
+
+declare class ModelNotFoundException extends GravitoException {
+    readonly model: string;
+    readonly id?: string | number;
+    constructor(model: string, id?: string | number);
+}
+
+interface ValidationError {
+    field: string;
+    message: string;
+    code?: string;
+}
+declare class ValidationException extends GravitoException {
+    readonly errors: ValidationError[];
+    redirectTo?: string;
+    input?: unknown;
+    constructor(errors: ValidationError[], message?: string);
+    withRedirect(url: string): this;
+    withInput(input: unknown): this;
+}
+
+interface GravitoManifest {
+    name: string;
+    version?: string;
+    modules: string[];
+    config?: GravitoConfig;
+}
+type ModuleResolver = () => Promise<any>;
+/**
+ * Gravito 核心啟動引擎 (已解耦)
+ */
+declare class GravitoServer {
+    /**
+     * 一鍵建立並組裝伺服器
+     * @param manifest 站點描述清單
+     * @param resolvers 模組解析器字典
+     * @param baseOrbits 基礎軌道模組 (例如 OrbitMonolith)
+     */
+    static create(manifest: GravitoManifest, resolvers: Record<string, ModuleResolver>, baseOrbits?: any[]): Promise<PlanetCore>;
+}
+
+type PathSegment = string | number;
+type DataPath = string | readonly PathSegment[];
+declare function dataGet<TDefault = undefined>(target: unknown, path: DataPath | null | undefined, defaultValue?: TDefault): unknown | TDefault;
+declare function dataHas(target: unknown, path: DataPath | null | undefined): boolean;
+declare function dataSet(target: unknown, path: DataPath, setValue: unknown, overwrite?: boolean): unknown;
+
+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[];
+};
+
+interface ErrorBag {
+    has(field: string): boolean;
+    first(field?: string): string | undefined;
+    get(field: string): string[];
+    all(): Record<string, string[]>;
+    any(): boolean;
+    count(): number;
+}
+declare function createErrorBag(errors: Record<string, string[]>): ErrorBag;
+declare function errors(c: GravitoContext): ErrorBag;
+declare function old(c: GravitoContext, field: string, defaultValue?: unknown): unknown;
+
+type StartsEndsNeedle = string | readonly string[];
+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;
+    readonly random: (length?: number) => string;
+};
+
+declare class DumpDieError extends Error {
+    readonly values: unknown[];
+    name: string;
+    constructor(values: unknown[]);
+}
+type DumpOptions = {
+    depth?: number | null;
+    colors?: boolean;
+};
+declare function dump(...values: unknown[]): void;
+declare function dd(...values: unknown[]): never;
+declare function tap<T>(value: T, callback: (value: T) => unknown): T;
+declare function value<TArgs extends readonly unknown[], TResult>(value: (...args: TArgs) => TResult, ...args: TArgs): TResult;
+declare function value<TResult>(value: TResult): TResult;
+declare function value<TArgs extends readonly unknown[], TResult>(valueOrFactory: TResult | ((...args: TArgs) => TResult), ...args: TArgs): TResult;
+declare function blank(value: unknown): boolean;
+declare function filled(value: unknown): boolean;
+declare function throwIf(condition: unknown, error?: Error | string | (() => Error)): void;
+declare function throwUnless(condition: unknown, error?: Error | string | (() => Error)): void;
+declare function env<TDefault = string | undefined>(key: string, defaultValue?: TDefault): string | TDefault;
+declare function setApp(core: PlanetCore | null): void;
+declare function hasApp(): boolean;
+declare function app(): PlanetCore;
+declare function config<T = unknown>(key: string): T;
+declare function config<T>(key: string, defaultValue: T): T;
+declare function logger(): Logger;
+declare function router(): Router;
+declare function abort(status: ContentfulStatusCode, message?: string): never;
+declare function abortIf(condition: unknown, status: ContentfulStatusCode, message?: string): void;
+declare function abortUnless(condition: unknown, status: ContentfulStatusCode, message?: string): void;
+
+interface CookieOptions {
+    path?: string;
+    domain?: string;
+    secure?: boolean;
+    httpOnly?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+    maxAge?: number;
+    expires?: Date;
+    encrypt?: boolean;
+}
+declare class CookieJar {
+    private encrypter?;
+    private queued;
+    constructor(encrypter?: Encrypter | undefined);
+    /**
+     * Queue a cookie to be sent with the response
+     */
+    queue(name: string, value: string, minutes?: number, options?: CookieOptions): void;
+    /**
+     * Make a cookie that lasts "forever" (5 years)
+     */
+    forever(name: string, value: string, options?: CookieOptions): void;
+    /**
+     * Expire a cookie
+     */
+    forget(name: string, options?: CookieOptions): void;
+    /**
+     * Serialize a cookie to a Set-Cookie header value
+     */
+    private serializeCookie;
+    /**
+     * Attach queued cookies to the context
+     */
+    attach(c: GravitoContext): void;
+}
+
+type BodySizeLimitOptions = {
+    methods?: string[];
+    requireContentLength?: boolean;
+};
+declare function bodySizeLimit(maxBytes: number, options?: BodySizeLimitOptions): GravitoMiddleware;
+
+type CorsOrigin = string | string[] | ((origin: string | undefined) => string | false);
+type CorsOptions = {
+    origin?: CorsOrigin;
+    methods?: string[];
+    allowedHeaders?: string[];
+    exposedHeaders?: string[];
+    credentials?: boolean;
+    maxAge?: number;
+    optionsSuccessStatus?: number;
+};
+declare function cors(options?: CorsOptions): GravitoMiddleware;
+
+type CsrfOptions = {
+    cookieName?: string;
+    headerName?: string;
+    formFieldName?: string;
+    cookie?: CookieOptions;
+    safeMethods?: string[];
+};
+declare function getCsrfToken(c: GravitoContext, options?: CsrfOptions): string;
+declare function csrfProtection(options?: CsrfOptions): GravitoMiddleware;
+
+type HeaderTokenGateOptions = {
+    headerName?: string;
+    token?: string | ((c: GravitoContext) => string | undefined);
+};
+type RequireHeaderTokenOptions = HeaderTokenGateOptions & {
+    status?: number;
+    message?: string;
+};
+declare function createHeaderGate(options?: HeaderTokenGateOptions): (c: GravitoContext) => Promise<boolean>;
+declare function requireHeaderToken(options?: RequireHeaderTokenOptions): GravitoMiddleware;
+
+type HstsOptions = {
+    maxAge: number;
+    includeSubDomains?: boolean;
+    preload?: boolean;
+};
+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;
+};
+declare function securityHeaders(options?: SecurityHeadersOptions): GravitoMiddleware;
+
+declare class ThrottleRequests {
+    private core;
+    constructor(core: PlanetCore);
+    /**
+     * Create the middleware
+     * @param maxAttempts - Max requests allowed
+     * @param decaySeconds - Time window in seconds
+     */
+    handle(maxAttempts?: number, decaySeconds?: number): GravitoMiddleware;
+}
+
+/**
+ * TestResponse wraps a standard Fetch Response and provides fluent assertion methods
+ * inspired by Laravel's TestResponse.
+ */
+declare class TestResponse {
+    readonly response: Response;
+    private _jsonData;
+    private _textData;
+    constructor(response: Response);
+    /**
+     * Assert the response status code
+     */
+    assertStatus(status: number): this;
+    /**
+     * Assert that the response has a 200 status code
+     */
+    assertOk(): this;
+    /**
+     * Assert that the response has a 201 status code
+     */
+    assertCreated(): this;
+    /**
+     * Assert that the response has a 404 status code
+     */
+    assertNotFound(): this;
+    /**
+     * Assert that the response has a 403 status code
+     */
+    assertForbidden(): this;
+    /**
+     * Assert that the response has a 401 status code
+     */
+    assertUnauthorized(): this;
+    /**
+     * Assert the response is a redirect
+     */
+    assertRedirect(uri?: string): this;
+    /**
+     * Assert that the response contains the given JSON data.
+     */
+    assertJson(data: any): Promise<this>;
+    /**
+     * Assert that the response contains exactly the given JSON data.
+     */
+    assertExactJson(data: any): Promise<this>;
+    /**
+     * Assert the structure of the JSON response.
+     */
+    assertJsonStructure(structure: any): Promise<this>;
+    /**
+     * Assert that the response contains the given string.
+     */
+    assertSee(value: string): Promise<this>;
+    /**
+     * Assert that the response does not contain the given string.
+     */
+    assertDontSee(value: string): Promise<this>;
+    /**
+     * Assert a header exists and matches value
+     */
+    assertHeader(header: string, value: string): this;
+    /**
+     * Assert a header does not exist
+     */
+    assertHeaderMissing(header: string): this;
+    /**
+     * Get the JSON content
+     */
+    getJson(): Promise<any>;
+    /**
+     * Get the text content
+     */
+    getText(): Promise<string>;
+    /**
+     * Alias for getText for standard expectations if needed
+     */
+    get body(): Promise<string>;
+}
+
+/**
+ * HttpTester provides a way to simulate HTTP requests against a PlanetCore instance
+ * and returns a TestResponse for assertions.
+ */
+declare class HttpTester {
+    private core;
+    constructor(core: PlanetCore);
+    /**
+     * Make a GET request
+     */
+    get(uri: string, headers?: Record<string, string>): Promise<TestResponse>;
+    /**
+     * Make a POST request
+     */
+    post(uri: string, data?: any, headers?: Record<string, string>): Promise<TestResponse>;
+    /**
+     * Make a PUT request
+     */
+    put(uri: string, data?: any, headers?: Record<string, string>): Promise<TestResponse>;
+    /**
+     * Make a PATCH request
+     */
+    patch(uri: string, data?: any, headers?: Record<string, string>): Promise<TestResponse>;
+    /**
+     * Make a DELETE request
+     */
+    delete(uri: string, data?: any, headers?: Record<string, string>): Promise<TestResponse>;
+    /**
+     * Core call method
+     */
+    private call;
+}
+/**
+ * Helper to create an HttpTester for a PlanetCore instance
+ */
+declare function createHttpTester(core: PlanetCore): HttpTester;
+
+type RuntimeKind = 'bun' | 'node' | 'deno' | 'unknown';
+interface RuntimeSpawnOptions {
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    stdin?: 'pipe' | 'inherit' | 'ignore';
+    stdout?: 'pipe' | 'inherit' | 'ignore';
+    stderr?: 'pipe' | 'inherit' | 'ignore';
+}
+interface RuntimeProcess {
+    exited: Promise<number>;
+    stdout?: ReadableStream<Uint8Array> | null;
+    stderr?: ReadableStream<Uint8Array> | null;
+    kill?: (signal?: string | number) => void;
+}
+interface RuntimeFileStat {
+    size: number;
+}
+interface RuntimeServeConfig {
+    port?: number;
+    fetch: (req: Request, server?: unknown) => Response | Promise<Response>;
+    websocket?: unknown;
+}
+interface RuntimeServer {
+    stop?: () => void;
+}
+interface RuntimeAdapter {
+    kind: RuntimeKind;
+    spawn(command: string[], options?: RuntimeSpawnOptions): RuntimeProcess;
+    writeFile(path: string, data: Blob | Buffer | string | ArrayBuffer | Uint8Array): Promise<void>;
+    readFile(path: string): Promise<Uint8Array>;
+    readFileAsBlob(path: string): Promise<Blob>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<RuntimeFileStat>;
+    deleteFile(path: string): Promise<void>;
+    serve(config: RuntimeServeConfig): RuntimeServer;
+}
+interface RuntimePasswordAdapter {
+    hash(value: string, options: {
+        algorithm: 'bcrypt';
+        cost?: number;
+    } | {
+        algorithm: 'argon2id';
+        memoryCost?: number;
+        timeCost?: number;
+        parallelism?: number;
+    }): Promise<string>;
+    verify(value: string, hashed: string): Promise<boolean>;
+}
+interface RuntimeSqliteStatement {
+    run(params?: Record<string, unknown>): void;
+    get(params?: Record<string, unknown>): unknown;
+    all(params?: Record<string, unknown>): unknown[];
+}
+interface RuntimeSqliteDatabase {
+    run(sql: string): void;
+    prepare(sql: string): RuntimeSqliteStatement;
+    query(sql: string): RuntimeSqliteStatement;
+    close(): void;
+}
+declare const getRuntimeEnv: () => Record<string, string | undefined>;
+declare const getRuntimeAdapter: () => RuntimeAdapter;
+declare const getPasswordAdapter: () => RuntimePasswordAdapter;
+declare const createSqliteDatabase: (path: string) => Promise<RuntimeSqliteDatabase>;
+
+/**
+ * @gravito/core
+ *
+ * The core micro-kernel for the Galaxy Architecture.
+ *
+ * @packageDocumentation
+ */
+
+declare const VERSION: string;
+
+/**
+ * Configure your Gravito application
+ *
+ * @example
+ * ```typescript
+ * const config = defineConfig({
+ *   config: {
+ *     APP_NAME: 'My App',
+ *     PORT: 3000,
+ *   },
+ *   orbits: [], // Add your orbits here
+ * })
+ *
+ * const core = await PlanetCore.boot(config)
+ * ```
+ */
+declare function defineConfig(config: GravitoConfig): GravitoConfig;
+
+export { type ActionCallback, type AdapterConfig, type AdapterFactory, type ApiFailure, type ApiSuccess, Application, type ApplicationConfig, Arr, AuthenticationException, AuthorizationException, type BodySizeLimitOptions, type CacheService, type Channel, ConfigManager, ConsoleLogger, Container, ContentfulStatusCode, type ControllerClass, CookieJar, type CookieOptions, type CorsOptions, type CorsOrigin, type CsrfOptions, type DataPath, DumpDieError, type DumpOptions, Encrypter, type EncrypterOptions, type ErrorBag, type ErrorHandlerContext, Event, EventManager, type ExceptionOptions, type Factory, type FilterCallback, type FormRequestClass, type FormRequestLike, type GlobalErrorHandlersMode, type GlobalProcessErrorHandlerContext, type GlobalProcessErrorKind, GravitoAdapter, type GravitoConfig, GravitoContext, GravitoErrorHandler, GravitoException, GravitoHandler, type GravitoManifest, GravitoMiddleware, GravitoNotFoundHandler, type GravitoOrbit, GravitoRequest, GravitoServer, GravitoVariables, type HeaderTokenGateOptions, HookManager, type HstsOptions, type HttpAdapter, HttpException, HttpMethod, HttpTester, type Listener, type Logger, ModelNotFoundException, type PathSegment, PhotonAdapter, PhotonContextWrapper, PhotonRequestWrapper, PlanetCore, type RegisterGlobalErrorHandlersOptions, type RequireHeaderTokenOptions, Route, type RouteDefinition, type RouteHandler, type RouteOptions, Router, type RuntimeAdapter, type RuntimeFileStat, type RuntimeKind, type RuntimePasswordAdapter, type RuntimeProcess, type RuntimeServeConfig, type RuntimeServer, type RuntimeSpawnOptions, type RuntimeSqliteDatabase, type RuntimeSqliteStatement, type SecurityHeadersOptions, ServiceProvider, type ShouldBroadcast, type ShouldQueue, StatusCode, Str, TestResponse, ThrottleRequests, VERSION, type ValidationError, ValidationException, type ViewService, abort, abortIf, abortUnless, app, blank, bodySizeLimit, config, cors, createErrorBag, createGravitoAdapter, createHeaderGate, createHttpTester, createPhotonAdapter, createSqliteDatabase, csrfProtection, dataGet, dataHas, dataSet, dd, defineConfig, dump, env, errors, fail, filled, getCsrfToken, getPasswordAdapter, getRuntimeAdapter, getRuntimeEnv, hasApp, isHttpAdapter, jsonFail, jsonSuccess, logger, ok, old, registerGlobalErrorHandlers, requireHeaderToken, router, securityHeaders, setApp, tap, throwIf, throwUnless, value };