@gravito/core 1.2.1 → 1.6.1

package/dist/compat-CI8hiulX.d.cts

@@ -0,0 +1,376 @@
+/**
+ * @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
+ */
+type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'options' | 'head';
+/**
+ * HTTP status codes
+ */
+type StatusCode = number;
+/**
+ * Content-bearing HTTP status codes (excludes 1xx, 204, 304)
+ */
+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
+ *   }
+ * }
+ * ```
+ */
+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;
+    /**
+     * Middleware scope tracking for Orbit isolation
+     * Tracks which Orbit/scope this request belongs to
+     * Used to prevent cross-Orbit middleware contamination
+     * @since 2.3.0
+     */
+    middlewareScope?: string;
+    /** @deprecated Use ctx.route() instead */
+    route?: unknown;
+    [key: string]: unknown;
+}
+/**
+ * Validated request data targets
+ */
+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>()
+ * ```
+ */
+interface GravitoRequest {
+    /** Full request URL */
+    readonly url: string;
+    /** HTTP method (uppercase) */
+    readonly method: string;
+    /** Request path without query string */
+    readonly path: string;
+    /**
+     * Route pattern (e.g., /users/:id) for the matched route
+     *
+     * This provides the parameterized route pattern instead of the concrete path,
+     * which is critical for preventing high cardinality issues in metrics systems.
+     *
+     * @example
+     * ```typescript
+     * // For request: GET /users/123
+     * ctx.req.path          // => "/users/123"
+     * ctx.req.routePattern  // => "/users/:id"
+     * ```
+     */
+    readonly routePattern?: 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)
+ */
+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 })
+ * }
+ * ```
+ */
+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;
+    /**
+     * Access the RequestScopeManager for this request
+     * Services resolved through this manager are scoped to the HTTP request lifetime.
+     */
+    requestScope(): any;
+    /**
+     * Resolve or create a request-scoped service
+     *
+     * @param key - Service key (string or symbol)
+     * @param factory - Factory function to create the service if not cached
+     * @returns The cached or newly created service instance
+     *
+     * @example
+     * ```typescript
+     * // Subsequent calls in the same request return the same instance
+     * const cache = ctx.scoped('product:cache', () => new RequestProductCache())
+     * ```
+     */
+    scoped<T>(key: string | symbol, factory: () => T): T;
+}
+/**
+ * Next function for middleware chain
+ */
+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!' })
+ * }
+ * ```
+ */
+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
+ * }
+ * ```
+ */
+type GravitoMiddleware<V extends GravitoVariables = GravitoVariables> = (ctx: GravitoContext<V>, next: GravitoNext) => Response | undefined | Promise<Response | undefined | undefined>;
+/**
+ * Error handler type
+ */
+type GravitoErrorHandler<V extends GravitoVariables = GravitoVariables> = (error: Error, ctx: GravitoContext<V>) => Response | Promise<Response>;
+/**
+ * Not found handler type
+ */
+type GravitoNotFoundHandler<V extends GravitoVariables = GravitoVariables> = (ctx: GravitoContext<V>) => Response | Promise<Response>;
+
+export type { ContentfulStatusCode as C, GravitoVariables as G, HttpMethod as H, ProxyOptions as P, StatusCode as S, ValidationTarget as V, GravitoHandler as a, GravitoMiddleware as b, GravitoErrorHandler as c, GravitoNotFoundHandler as d, GravitoContext as e, GravitoRequest as f, GravitoNext as g };