@gravito/echo 2.0.0 → 3.0.1

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

@@ -0,0 +1,138 @@
+/**
+ * @fileoverview Gravito Core Engine Types
+ *
+ * Minimal, high-performance types for the standalone engine.
+ * These are intentionally simpler than the full framework types.
+ *
+ * @module @gravito/core/engine
+ */
+import type { HttpMethod } from '../http/types';
+/**
+ * FastContext - The pooled request context
+ */
+export interface FastContext {
+    /** Request accessor */
+    readonly req: FastRequest;
+    /** Response helpers */
+    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;
+    forward(target: string, options?: any): Promise<Response>;
+    /** Header management */
+    header(name: string): string | undefined;
+    header(name: string, value: string): void;
+    status(code: number): void;
+    /** Context Variables */
+    get<T>(key: string): T;
+    set(key: string, value: any): void;
+    /** Lifecycle helpers */
+    route: (name: string, params?: any, query?: any) => string;
+    readonly native: any;
+    /** Internal initialization for pooling */
+    init(request: Request, params?: Record<string, string>, path?: string): this;
+    /** Internal cleanup for pooling */
+    reset(): void;
+}
+/**
+ * FastRequest - Minimal request interface
+ */
+export interface FastRequest {
+    /** Full URL */
+    readonly url: string;
+    /** HTTP method */
+    readonly method: string;
+    /** Path without query */
+    readonly path: string;
+    /** Get route parameter */
+    param(name: string): string | undefined;
+    /** Get all route parameters */
+    params(): Record<string, string>;
+    /** Get query parameter */
+    query(name: string): string | undefined;
+    /** Get all query parameters */
+    queries(): Record<string, string | string[]>;
+    /** Get header */
+    header(name: string): string | undefined;
+    /** Get all headers */
+    headers(): Record<string, string>;
+    /** Parse JSON body */
+    json<T = unknown>(): Promise<T>;
+    /** Parse text body */
+    text(): Promise<string>;
+    /** Parse form data */
+    formData(): Promise<FormData>;
+    /** Raw Request object */
+    readonly raw: Request;
+}
+/**
+ * Route handler function
+ */
+export type Handler = (ctx: FastContext) => Response | Promise<Response>;
+/**
+ * Middleware function
+ */
+export type Middleware = (ctx: FastContext, next: () => Promise<Response | undefined>) => Response | undefined | Promise<Response | undefined>;
+/**
+ * Error handler function
+ */
+export type ErrorHandler = (error: Error, ctx: FastContext) => Response | Promise<Response>;
+/**
+ * Not found handler function
+ */
+export type NotFoundHandler = (ctx: FastContext) => Response | Promise<Response>;
+/**
+ * Route metadata for middleware management
+ */
+export interface RouteMetadata {
+    handler: Handler;
+    middleware: Middleware[];
+    compiled?: CompiledHandler;
+    useMinimal?: boolean;
+    compiledVersion?: number;
+}
+/**
+ * Compiled handler function
+ */
+export type CompiledHandler = (ctx: FastContext) => Promise<Response>;
+/**
+ * Route match result from router
+ */
+export interface RouteMatch {
+    /** Matched handler */
+    handler: Handler | null;
+    /** Extracted route parameters */
+    params: Record<string, string>;
+    /** Middleware to execute */
+    middleware: Middleware[];
+    /** Optional stable route pattern for caching */
+    routePattern?: string;
+}
+/**
+ * Internal route node
+ */
+export interface RouteNode {
+    method: HttpMethod;
+    path: string;
+    handler: Handler;
+    middleware: Middleware[];
+}
+/**
+ * Engine configuration options
+ */
+export interface EngineOptions {
+    /** Context pool size (default: 256) */
+    poolSize?: number;
+    /** Enable route compilation optimization (default: true) */
+    enableAOT?: boolean;
+    /** Custom error handler */
+    onError?: ErrorHandler;
+    /** Custom 404 handler */
+    onNotFound?: NotFoundHandler;
+}

package/dist/core/src/exceptions/AuthenticationException.d.ts

@@ -0,0 +1,8 @@
+import { GravitoException } from './GravitoException';
+/**
+ * Exception thrown when authentication fails.
+ * @public
+ */
+export declare class AuthenticationException extends GravitoException {
+    constructor(message?: string);
+}

package/dist/core/src/exceptions/AuthorizationException.d.ts

@@ -0,0 +1,8 @@
+import { GravitoException } from './GravitoException';
+/**
+ * Exception thrown when user is not authorized to perform an action.
+ * @public
+ */
+export declare class AuthorizationException extends GravitoException {
+    constructor(message?: string);
+}

package/dist/core/src/exceptions/GravitoException.d.ts

@@ -0,0 +1,23 @@
+import type { ContentfulStatusCode } from '../http/types';
+/**
+ * Options for creating a GravitoException
+ * @public
+ */
+export interface ExceptionOptions {
+    message?: string;
+    cause?: unknown;
+    i18nKey?: string;
+    i18nParams?: Record<string, string | number>;
+}
+/**
+ * Base exception class for consistent error handling.
+ * @public
+ */
+export 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;
+}

package/dist/core/src/exceptions/HttpException.d.ts

@@ -0,0 +1,9 @@
+import type { ContentfulStatusCode } from '../http/types';
+import { type ExceptionOptions, GravitoException } from './GravitoException';
+/**
+ * Generic HTTP Exception
+ * @public
+ */
+export declare class HttpException extends GravitoException {
+    constructor(status: ContentfulStatusCode, options?: ExceptionOptions);
+}

package/dist/core/src/exceptions/ModelNotFoundException.d.ts

@@ -0,0 +1,10 @@
+import { GravitoException } from './GravitoException';
+/**
+ * Exception thrown when a database model is not found.
+ * @public
+ */
+export declare class ModelNotFoundException extends GravitoException {
+    readonly model: string;
+    readonly id?: string | number;
+    constructor(model: string, id?: string | number);
+}

package/dist/core/src/exceptions/ValidationException.d.ts

@@ -0,0 +1,22 @@
+import { GravitoException } from './GravitoException';
+/**
+ * Structure of a validation error
+ * @public
+ */
+export interface ValidationError {
+    field: string;
+    message: string;
+    code?: string;
+}
+/**
+ * Exception thrown when data validation fails.
+ * @public
+ */
+export 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;
+}

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

@@ -0,0 +1,6 @@
+export * from './AuthenticationException';
+export * from './AuthorizationException';
+export * from './GravitoException';
+export * from './HttpException';
+export * from './ModelNotFoundException';
+export * from './ValidationException';

package/dist/core/src/helpers/Arr.d.ts

@@ -0,0 +1,19 @@
+import { type DataPath } from './data';
+/**
+ * Array and Collection Helpers.
+ * Provides utility methods for array manipulation and deep object access.
+ * @public
+ */
+export 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[];
+};

package/dist/core/src/helpers/Str.d.ts

@@ -0,0 +1,23 @@
+type StartsEndsNeedle = string | readonly string[];
+/**
+ * String Helper Utilities.
+ * Provides methods for string manipulation, case conversion, and UUID generation.
+ * @public
+ */
+export 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;
+};
+export {};

package/dist/core/src/helpers/data.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Path segment (key) in a data structure.
+ * @public
+ */
+export type PathSegment = string | number;
+/**
+ * Path to a value (dot notation or array of segments).
+ * @public
+ */
+export type DataPath = string | readonly PathSegment[];
+/**
+ * Retrieve a value from a deep object using dot notation.
+ * @public
+ */
+export declare function dataGet<TDefault = undefined>(target: unknown, path: DataPath | null | undefined, defaultValue?: TDefault): unknown | TDefault;
+/**
+ * Check if a key exists in a deep object using dot notation.
+ * @public
+ */
+export declare function dataHas(target: unknown, path: DataPath | null | undefined): boolean;
+/**
+ * Set a value in a deep object using dot notation.
+ * @public
+ */
+export declare function dataSet(target: unknown, path: DataPath, setValue: unknown, overwrite?: boolean): unknown;

package/dist/core/src/helpers/errors.d.ts

@@ -0,0 +1,34 @@
+import type { GravitoContext } from '../http/types';
+/**
+ * Interface for displaying validation errors in views.
+ * @public
+ */
+export interface ErrorBag {
+    /** Check if a field has errors */
+    has(field: string): boolean;
+    /** Get the first error message for a field (or any first error if no field specified) */
+    first(field?: string): string | undefined;
+    /** Get all error messages for a field */
+    get(field: string): string[];
+    /** Get all errors for all fields */
+    all(): Record<string, string[]>;
+    /** Check if there are any errors */
+    any(): boolean;
+    /** Get total number of error messages */
+    count(): number;
+}
+/**
+ * Create a new ErrorBag instance from raw errors.
+ * @public
+ */
+export declare function createErrorBag(errors: Record<string, string[]>): ErrorBag;
+/**
+ * Helper to retrieve the ErrorBag from session flash data.
+ * @public
+ */
+export declare function errors(c: GravitoContext): ErrorBag;
+/**
+ * Helper to retrieve old input value from session flash.
+ * @public
+ */
+export declare function old(c: GravitoContext, field: string, defaultValue?: unknown): unknown;

package/dist/core/src/helpers/response.d.ts

@@ -0,0 +1,41 @@
+import type { ContentfulStatusCode, GravitoContext } from '../http/types';
+/**
+ * Standard API Success Response Structure
+ * @public
+ */
+export type ApiSuccess<T> = {
+    success: true;
+    data: T;
+};
+/**
+ * Standard API Failure Response Structure
+ * @public
+ */
+export type ApiFailure = {
+    success: false;
+    error: {
+        message: string;
+        code?: string;
+        details?: unknown;
+    };
+};
+/**
+ * Create a success response object.
+ * @public
+ */
+export declare function ok<T>(data: T): ApiSuccess<T>;
+/**
+ * Create a failure response object.
+ * @public
+ */
+export declare function fail(message: string, code?: string, details?: unknown): ApiFailure;
+/**
+ * Return a JSON response with standard success structure.
+ * @public
+ */
+export declare function jsonSuccess<T>(c: GravitoContext, data: T, status?: ContentfulStatusCode): Response;
+/**
+ * Return a JSON response with standard failure structure.
+ * @public
+ */
+export declare function jsonFail(c: GravitoContext, message: string, status?: ContentfulStatusCode, code?: string, details?: unknown): Response;