@gravito/echo 3.0.0 → 3.0.1

package/dist/core/src/http/types.d.ts

@@ -0,0 +1,334 @@
+/**
+ * @fileoverview Core HTTP Types for Gravito Framework
+ *
+ * These types provide a unified abstraction layer that decouples the framework
+ * from any specific HTTP engine (Photon, Express, custom, etc.).
+ *
+ * @module @gravito/core/http
+ * @since 2.0.0
+ */
+declare global {
+    interface ExecutionContext {
+        waitUntil(promise: Promise<unknown>): void;
+        passThroughOnException(): void;
+    }
+}
+/**
+ * Standard HTTP methods supported by Gravito
+ */
+export type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'options' | 'head';
+/**
+ * HTTP status codes
+ */
+export type StatusCode = number;
+/**
+ * Content-bearing HTTP status codes (excludes 1xx, 204, 304)
+ */
+export type ContentfulStatusCode = Exclude<StatusCode, 100 | 101 | 102 | 103 | 204 | 304>;
+/**
+ * Base context variables available in every request
+ * Orbits can extend this interface via module augmentation
+ *
+ * @example
+ * ```typescript
+ * // Extending variables in your orbit:
+ * declare module '@gravito/core' {
+ *   interface GravitoVariables {
+ *     myService: MyService
+ *   }
+ * }
+ * ```
+ */
+export interface GravitoVariables {
+    /**
+     * The PlanetCore instance
+     * @remarks Always available in PlanetCore-managed contexts
+     */
+    core?: unknown;
+    /**
+     * Logger instance
+     */
+    logger?: unknown;
+    /**
+     * Configuration manager
+     */
+    config?: unknown;
+    /**
+     * Cookie jar for managing response cookies
+     */
+    cookieJar?: unknown;
+    /** @deprecated Use ctx.route() instead */
+    route?: unknown;
+    [key: string]: unknown;
+}
+/**
+ * Validated request data targets
+ */
+export type ValidationTarget = 'json' | 'query' | 'param' | 'header' | 'form' | 'cookie';
+/**
+ * GravitoRequest - Unified request interface
+ *
+ * Provides a consistent API for accessing request data regardless of
+ * the underlying HTTP engine.
+ *
+ * @example
+ * ```typescript
+ * const userId = ctx.req.param('id')
+ * const search = ctx.req.query('q')
+ * const body = await ctx.req.json<CreateUserDto>()
+ * ```
+ */
+export interface GravitoRequest {
+    /** Full request URL */
+    readonly url: string;
+    /** HTTP method (uppercase) */
+    readonly method: string;
+    /** Request path without query string */
+    readonly path: string;
+    /**
+     * Get a route parameter value
+     * @param name - Parameter name (e.g., 'id' for route '/users/:id')
+     */
+    param(name: string): string | undefined;
+    /**
+     * Get all route parameters
+     */
+    params(): Record<string, string>;
+    /**
+     * Get a query string parameter
+     * @param name - Query parameter name
+     */
+    query(name: string): string | undefined;
+    /**
+     * Get all query parameters
+     */
+    queries(): Record<string, string | string[]>;
+    /**
+     * Get a request header value
+     * @param name - Header name (case-insensitive)
+     */
+    header(name: string): string | undefined;
+    /**
+     * Get all request headers
+     */
+    header(): Record<string, string>;
+    /**
+     * Parse request body as JSON
+     * @throws {Error} If body is not valid JSON
+     */
+    json<T = unknown>(): Promise<T>;
+    /**
+     * Parse request body as text
+     */
+    text(): Promise<string>;
+    /**
+     * Parse request body as FormData
+     */
+    formData(): Promise<FormData>;
+    /**
+     * Parse request body as ArrayBuffer
+     */
+    arrayBuffer(): Promise<ArrayBuffer>;
+    /**
+     * Parse form data (urlencoded or multipart)
+     */
+    parseBody<T = unknown>(): Promise<T>;
+    /**
+     * Get the raw Request object
+     */
+    readonly raw: Request;
+    /**
+     * Get validated data from a specific source
+     * @param target - The validation target
+     * @throws {Error} If validation was not performed for this target
+     */
+    valid<T = unknown>(target: ValidationTarget): T;
+}
+/**
+ * Options for request forwarding (Proxy)
+ */
+export interface ProxyOptions {
+    /** Override or add request headers */
+    headers?: Record<string, string>;
+    /** Whether to keep the original Host header (default: false) */
+    preserveHost?: boolean;
+    /** Whether to add X-Forwarded-* headers (default: true) */
+    addForwardedHeaders?: boolean;
+    /** Path rewriting logic */
+    rewritePath?: (path: string) => string;
+}
+/**
+ * GravitoContext - Unified request context
+ *
+ * This interface encapsulates all HTTP request/response operations,
+ * enabling seamless replacement of the underlying HTTP engine.
+ *
+ * @typeParam V - Context variables type
+ *
+ * @example
+ * ```typescript
+ * // In a controller
+ * async show(ctx: GravitoContext) {
+ *   const id = ctx.req.param('id')
+ *   const user = await User.find(id)
+ *   return ctx.json({ user })
+ * }
+ * ```
+ */
+export interface GravitoContext<V extends GravitoVariables = GravitoVariables> {
+    /** The incoming request */
+    readonly req: GravitoRequest;
+    /**
+     * Send a JSON response
+     * @param data - Data to serialize as JSON
+     * @param status - HTTP status code (default: 200)
+     */
+    json<T>(data: T, status?: ContentfulStatusCode): Response;
+    /**
+     * Send a plain text response
+     * @param text - Text content
+     * @param status - HTTP status code (default: 200)
+     */
+    text(text: string, status?: ContentfulStatusCode): Response;
+    /**
+     * Send an HTML response
+     * @param html - HTML content
+     * @param status - HTTP status code (default: 200)
+     */
+    html(html: string, status?: ContentfulStatusCode): Response;
+    /**
+     * Send a redirect response
+     * @param url - Target URL
+     * @param status - Redirect status code (default: 302)
+     */
+    redirect(url: string, status?: 301 | 302 | 303 | 307 | 308): Response;
+    /**
+     * Create a Response with no body
+     * @param status - HTTP status code
+     */
+    body(data: BodyInit | null, status?: StatusCode): Response;
+    /**
+     * Stream a response
+     * @param stream - ReadableStream to send
+     * @param status - HTTP status code (default: 200)
+     */
+    stream(stream: ReadableStream, status?: ContentfulStatusCode): Response;
+    /**
+     * Send a 404 Not Found response
+     */
+    notFound(message?: string): Response;
+    /**
+     * Send a 403 Forbidden response
+     */
+    forbidden(message?: string): Response;
+    /**
+     * Send a 401 Unauthorized response
+     */
+    unauthorized(message?: string): Response;
+    /**
+     * Send a 400 Bad Request response
+     */
+    badRequest(message?: string): Response;
+    /**
+     * Forward the current request to another URL (Reverse Proxy)
+     * @param target - Target URL or base URL to forward to
+     * @param options - Optional proxy options
+     */
+    forward(target: string, options?: ProxyOptions): Promise<Response>;
+    /**
+     * Set a response header
+     * @param name - Header name
+     * @param value - Header value
+     * @param options - Options (append: true to add multiple values)
+     */
+    header(name: string, value: string, options?: {
+        append?: boolean;
+    }): void;
+    /**
+     * Get a request header
+     * @param name - Header name (case-insensitive)
+     */
+    header(name: string): string | undefined;
+    /**
+     * Set the response status code
+     * @param code - HTTP status code
+     */
+    status(code: StatusCode): void;
+    /**
+     * Get a context variable
+     * @param key - Variable key
+     */
+    get<K extends keyof V>(key: K): V[K];
+    /**
+     * Set a context variable
+     * @param key - Variable key
+     * @param value - Variable value
+     */
+    set<K extends keyof V>(key: K, value: V[K]): void;
+    /**
+     * Get the execution context (for Cloudflare Workers, etc.)
+     */
+    readonly executionCtx?: ExecutionContext;
+    /**
+     * Get environment bindings (for Cloudflare Workers, etc.)
+     */
+    readonly env?: Record<string, unknown>;
+    /**
+     * URL generator helper.
+     * Generates a URL for a named route.
+     */
+    route: (name: string, params?: Record<string, any>, query?: Record<string, any>) => string;
+    /**
+     * Access the native context object from the underlying HTTP engine.
+     *
+     * ⚠️ WARNING: Using this ties your code to a specific adapter.
+     * Prefer using the abstraction methods when possible.
+     *
+     * @example
+     * ```typescript
+     * // Only when absolutely necessary
+     * const photonCtx = ctx.native as Context // Photon Context
+     * ```
+     */
+    readonly native: unknown;
+}
+/**
+ * Next function for middleware chain
+ */
+export type GravitoNext = () => Promise<Response | undefined>;
+/**
+ * GravitoHandler - Standard route handler type
+ *
+ * @typeParam V - Context variables type
+ *
+ * @example
+ * ```typescript
+ * const handler: GravitoHandler = async (ctx) => {
+ *   return ctx.json({ message: 'Hello, World!' })
+ * }
+ * ```
+ */
+export type GravitoHandler<V extends GravitoVariables = GravitoVariables> = (ctx: GravitoContext<V>) => Response | Promise<Response>;
+/**
+ * GravitoMiddleware - Standard middleware type
+ *
+ * @typeParam V - Context variables type
+ *
+ * @example
+ * ```typescript
+ * const logger: GravitoMiddleware = async (ctx, next) => {
+ *   console.log(`${ctx.req.method} ${ctx.req.path}`)
+ *   await next()
+ *   return undefined
+ * }
+ * ```
+ */
+export type GravitoMiddleware<V extends GravitoVariables = GravitoVariables> = (ctx: GravitoContext<V>, next: GravitoNext) => Response | undefined | Promise<Response | undefined | undefined>;
+/**
+ * Error handler type
+ */
+export type GravitoErrorHandler<V extends GravitoVariables = GravitoVariables> = (error: Error, ctx: GravitoContext<V>) => Response | Promise<Response>;
+/**
+ * Not found handler type
+ */
+export type GravitoNotFoundHandler<V extends GravitoVariables = GravitoVariables> = (ctx: GravitoContext<V>) => Response | Promise<Response>;

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

@@ -0,0 +1,66 @@
+/**
+ * @gravito/core
+ *
+ * The core micro-kernel for the Galaxy Architecture.
+ *
+ * @packageDocumentation
+ */
+import type { GravitoConfig } from './PlanetCore';
+/**
+ * Current version of @gravito/core.
+ * @public
+ */
+export declare const VERSION: string;
+export { GravitoEngineAdapter } from './adapters/GravitoEngineAdapter';
+export { createGravitoAdapter, createPhotonAdapter, GravitoAdapter, PhotonAdapter, PhotonContextWrapper, PhotonRequestWrapper, } from './adapters/PhotonAdapter';
+export type { AdapterConfig, AdapterFactory, HttpAdapter, RouteDefinition } from './adapters/types';
+export { isHttpAdapter } from './adapters/types';
+export type { ContentfulStatusCode, GravitoContext, GravitoErrorHandler, GravitoHandler, GravitoMiddleware, GravitoNext, GravitoNotFoundHandler, GravitoRequest, GravitoVariables, HttpMethod, StatusCode, ValidationTarget, } from './http/types';
+export { Application, type ApplicationConfig } from './Application';
+export { ConfigManager } from './ConfigManager';
+export { Container, type Factory } from './Container';
+export { codeFromStatus, ErrorHandler, type ErrorHandlerDeps, messageFromStatus, } from './ErrorHandler';
+export { EventManager } from './EventManager';
+export * from './exceptions';
+export { type GlobalErrorHandlersMode, type GlobalProcessErrorHandlerContext, type GlobalProcessErrorKind, type RegisterGlobalErrorHandlersOptions, registerGlobalErrorHandlers, } from './GlobalErrorHandlers';
+export { type GravitoManifest, GravitoServer } from './GravitoServer';
+export type { ActionCallback, FilterCallback } from './HookManager';
+export { HookManager } from './HookManager';
+export * from './helpers';
+export { CookieJar, type CookieOptions } from './http/CookieJar';
+export { type BodySizeLimitOptions, bodySizeLimit } from './http/middleware/BodySizeLimit';
+export { type CorsOptions, type CorsOrigin, cors } from './http/middleware/Cors';
+export { type CsrfOptions, csrfProtection, getCsrfToken } from './http/middleware/Csrf';
+export { createHeaderGate, type HeaderTokenGateOptions, type RequireHeaderTokenOptions, requireHeaderToken, } from './http/middleware/HeaderTokenGate';
+export { type HstsOptions, type SecurityHeadersOptions, securityHeaders, } from './http/middleware/SecurityHeaders';
+export { ThrottleRequests } from './http/middleware/ThrottleRequests';
+export type { Listener, ShouldQueue } from './Listener';
+export type { Logger } from './Logger';
+export { ConsoleLogger } from './Logger';
+export { type CacheService, type ErrorHandlerContext, type GravitoConfig, type GravitoOrbit, PlanetCore, type ViewService, } from './PlanetCore';
+export { Route } from './Route';
+export { type ControllerClass, FORM_REQUEST_SYMBOL, type FormRequestClass, type FormRequestLike, RouteGroup, type RouteHandler, type RouteOptions, Router, } from './Router';
+export { ServiceProvider } from './ServiceProvider';
+export { Encrypter, type EncrypterOptions } from './security/Encrypter';
+export type { Channel, ShouldBroadcast } from './types/events';
+export { Event } from './types/events';
+export * from './testing';
+export { createSqliteDatabase, getPasswordAdapter, getRuntimeAdapter, getRuntimeEnv, type RuntimeAdapter, type RuntimeFileStat, type RuntimeKind, type RuntimePasswordAdapter, type RuntimeProcess, type RuntimeServeConfig, type RuntimeServer, type RuntimeSpawnOptions, type RuntimeSqliteDatabase, type RuntimeSqliteStatement, } from './runtime';
+export * as engine from './engine';
+/**
+ * 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)
+ * ```
+ */
+export declare function defineConfig(config: GravitoConfig): GravitoConfig;

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

@@ -0,0 +1,119 @@
+/**
+ * Detected Javascript Runtime Environment
+ * @public
+ */
+export type RuntimeKind = 'bun' | 'node' | 'deno' | 'unknown';
+/**
+ * Options for spawning subprocesses
+ * @public
+ */
+export interface RuntimeSpawnOptions {
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    stdin?: 'pipe' | 'inherit' | 'ignore';
+    stdout?: 'pipe' | 'inherit' | 'ignore';
+    stderr?: 'pipe' | 'inherit' | 'ignore';
+}
+/**
+ * Abstract subprocess interface
+ * @public
+ */
+export interface RuntimeProcess {
+    exited: Promise<number>;
+    stdout?: ReadableStream<Uint8Array> | null;
+    stderr?: ReadableStream<Uint8Array> | null;
+    kill?: (signal?: string | number) => void;
+}
+/**
+ * File statistics abstraction
+ * @public
+ */
+export interface RuntimeFileStat {
+    size: number;
+}
+/**
+ * HTTP Server configuration
+ * @public
+ */
+export interface RuntimeServeConfig {
+    port?: number;
+    fetch: (req: Request, server?: unknown) => Response | Promise<Response>;
+    websocket?: unknown;
+}
+/**
+ * HTTP Server interface
+ * @public
+ */
+export interface RuntimeServer {
+    stop?: () => void;
+}
+/**
+ * Abstraction layer for filesystem and process operations across runtimes.
+ * @public
+ */
+export 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;
+}
+/**
+ * Abstraction layer for password hashing
+ * @public
+ */
+export 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>;
+}
+/**
+ * SQLite Statement abstraction
+ * @public
+ */
+export interface RuntimeSqliteStatement {
+    run(params?: Record<string, unknown>): void;
+    get(params?: Record<string, unknown>): unknown;
+    all(params?: Record<string, unknown>): unknown[];
+}
+/**
+ * SQLite Database abstraction
+ * @public
+ */
+export interface RuntimeSqliteDatabase {
+    run(sql: string): void;
+    prepare(sql: string): RuntimeSqliteStatement;
+    query(sql: string): RuntimeSqliteStatement;
+    close(): void;
+}
+/**
+ * Get environment variables from the current runtime.
+ * @public
+ */
+export declare const getRuntimeEnv: () => Record<string, string | undefined>;
+/**
+ * Get the runtime abstraction adapter (Bun/Node/Deno).
+ * @public
+ */
+export declare const getRuntimeAdapter: () => RuntimeAdapter;
+/**
+ * Get the password hashing adapter using native optimized implementations if available.
+ * @public
+ */
+export declare const getPasswordAdapter: () => RuntimePasswordAdapter;
+/**
+ * Create a SQLite database connection using runtime-native drivers.
+ * @public
+ */
+export declare const createSqliteDatabase: (path: string) => Promise<RuntimeSqliteDatabase>;

package/dist/core/src/security/Encrypter.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Options for the Encrypter class.
+ * @public
+ */
+export interface EncrypterOptions {
+    key: string;
+    cipher?: string;
+}
+/**
+ * Service for OpenSSL encryption/decryption.
+ * Compatible with Laravel's encryption format.
+ * @public
+ */
+export 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;
+}

package/dist/core/src/security/Hasher.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Hashing interface
+ */
+export 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)
+ */
+export 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;
+}

package/dist/core/src/testing/HttpTester.d.ts

@@ -0,0 +1,39 @@
+import type { PlanetCore } from '../PlanetCore';
+import { TestResponse } from './TestResponse';
+/**
+ * HttpTester provides a way to simulate HTTP requests against a PlanetCore instance
+ * and returns a TestResponse for assertions.
+ */
+export declare class HttpTester {
+    private core;
+    private cookies;
+    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
+ */
+export declare function createHttpTester(core: PlanetCore): HttpTester;

package/dist/core/src/testing/TestResponse.d.ts

@@ -0,0 +1,78 @@
+/**
+ * TestResponse wraps a standard Fetch Response and provides fluent assertion methods
+ * inspired by Laravel's TestResponse.
+ */
+export 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>;
+}