gina 0.3.2 → 0.3.3

package/types/index.d.ts

@@ -0,0 +1,566 @@
+/**
+ * Gina Framework — TypeScript declarations
+ *
+ * Main module declaration for `require('gina')`.
+ * Also exports all public types for use in consumer projects.
+ *
+ * @packageDocumentation
+ */
+
+/// <reference types="node" />
+/// <reference path="./globals.d.ts" />
+
+import { EventEmitter } from 'events';
+import type { IncomingMessage, ServerResponse } from 'http';
+import type { Http2ServerRequest, Http2ServerResponse, ServerHttp2Stream } from 'http2';
+import type { PathObject, OnCompletable, UuidFunction, LocaleResult } from './globals';
+
+// ─── Request / Response aliases ──────────────────────────────────────────────
+
+export type GinaRequest = (IncomingMessage | Http2ServerRequest) & {
+    /** Parsed GET query-string params */
+    get?: Record<string, any>;
+    /** Parsed POST body */
+    post?: Record<string, any>;
+    /** Parsed PUT body */
+    put?: Record<string, any>;
+    /** Parsed PATCH body */
+    patch?: Record<string, any>;
+    /** Parsed DELETE body */
+    delete?: Record<string, any>;
+    /** Parsed HEAD query-string params */
+    head?: Record<string, any>;
+    /** Alias for the method-specific params (e.g. req.post on POST) */
+    body?: Record<string, any>;
+    /** URI params extracted by the router (`:id` segments, requirement captures) */
+    params?: Record<string, string>;
+    /** Routing metadata attached by the router */
+    routing?: {
+        rule: string;
+        method: string;
+        param: RouteParam;
+        [key: string]: any;
+    };
+    /** Get all merged params for the current HTTP method */
+    getParams(): Record<string, any>;
+    /** Get a single param by name */
+    getParam(name: string): any;
+};
+
+export type GinaResponse = (ServerResponse | Http2ServerResponse) & {
+    /** HTTP/2 stream when available */
+    stream?: ServerHttp2Stream;
+    status?: number;
+};
+
+export type NextFunction = (err?: any) => void;
+
+// ─── SuperController ─────────────────────────────────────────────────────────
+
+/**
+ * Base controller class. Every bundle controller inherits from SuperController.
+ * A fresh instance is created for each HTTP request.
+ */
+export class SuperController extends EventEmitter {
+    name: string;
+    engine: any;
+    isProcessingError: boolean;
+
+    /** Get the current request object */
+    getRequestObject(): GinaRequest;
+    /** Get the current response object */
+    getResponseObject(): GinaResponse;
+    /** Get the `next` middleware callback */
+    getNextCallback(): NextFunction | null;
+
+    /** True when running in dev mode */
+    isCacheless(): boolean;
+    /** True when scope is `'local'` */
+    isLocalScope(): boolean;
+    /** True when scope is `'production'` */
+    isProductionScope(): boolean;
+
+    /**
+     * Render an HTML template (Swig engine).
+     * @param userData - Template data merged into the view
+     * @param displayInspector - Show the Gina Inspector overlay
+     * @param errOptions - Error rendering options (internal)
+     */
+    render(userData?: object, displayInspector?: boolean, errOptions?: object): void;
+
+    /** Render without the layout wrapper */
+    renderWithoutLayout(data?: object, displayInspector?: boolean): void;
+
+    /**
+     * Send a JSON response.
+     * @param jsonObj - Data to serialise; parsed if passed as a string
+     */
+    renderJSON(jsonObj: any): void;
+
+    /**
+     * Stream an AsyncIterable as a chunked HTTP response.
+     * Defaults to `text/event-stream` (SSE) framing.
+     * @param asyncIterable - Source of chunks (strings or Buffers)
+     * @param contentType - Response Content-Type (default: `'text/event-stream'`)
+     */
+    renderStream(asyncIterable: AsyncIterable<any>, contentType?: string): void;
+
+    /** Send a plain-text response */
+    renderTEXT(content: string | any): void;
+
+    /**
+     * Send 103 Early Hints for preloading resources.
+     * @param links - Link header value(s)
+     * @returns `this` for chaining
+     */
+    setEarlyHints(links: string | string[]): this;
+
+    /** True when the request was made via XMLHttpRequest */
+    isXMLRequest(): boolean;
+    /** True when credentials (cookies/auth) were sent */
+    isWithCredentials(): boolean;
+    /** True when the request originated from a Gina popin */
+    isPopinContext(): boolean;
+
+    /** Override the HTTP method for the current request */
+    setRequestMethod(requestMethod: string, conf: object): string;
+    /** Get the (possibly overridden) HTTP method */
+    getRequestMethod(): string | null;
+    /** Override the parsed method params */
+    setRequestMethodParams(params: object): void;
+    /** Get the overridden method params */
+    getRequestMethodParams(): object | null;
+
+    /**
+     * Redirect to a route name, URL, or full request triplet.
+     *
+     * Overloads:
+     * - `redirect(url: string, ignoreWebRoot?: boolean)`
+     * - `redirect(routeName: string, ignoreWebRoot?: boolean)`
+     * - `redirect(req, res, next)`
+     */
+    redirect(target: string, ignoreWebRoot?: boolean): void;
+    redirect(req: GinaRequest, res: GinaResponse, next?: NextFunction): void;
+
+    /** Get a clone of the bundle configuration */
+    getConfig(name?: string): any;
+
+    /** Get locale utilities */
+    getLocales(shortCountryCode?: string): LocaleResult;
+
+    /** Get form validation rules for the current request */
+    getFormsRules(): object;
+
+    /**
+     * Make an outbound HTTP/HTTPS request.
+     * @param options - Request options (host, port, path, method, headers, critical, ...)
+     * @param data - Request body / query params
+     * @param callback - `callback(err, result)` -- omit for Promise
+     */
+    query(options: QueryOptions, data?: object, callback?: (err: Error | null, result: any) => void): void | Promise<any>;
+
+    /**
+     * Download a file from a remote URL and stream it to the client.
+     * @param url - Remote URL
+     * @param options - Download options (file, toLocalDir, contentType, ...)
+     * @param cb - Callback on completion
+     */
+    downloadFromURL(url: string, options?: DownloadOptions, cb?: (err: Error | null, files?: any[]) => void): Promise<void>;
+
+    /** Download a local file to the client */
+    downloadFromLocal(filename: string): void;
+
+    /**
+     * Store uploaded file(s) to a target directory.
+     * @param target - Destination directory path
+     * @param files - File(s) to store (defaults to all uploaded files)
+     * @param cb - Callback `(err, files)`
+     */
+    store(target: string, files?: any, cb?: (err: Error | null, files?: any[]) => void): Promise<void>;
+
+    /** Health check: responds with `{ status: 200, isAlive: true }` */
+    getBundleStatus(req: GinaRequest, res: GinaResponse, next: NextFunction): void;
+
+    /** Ping a sibling bundle's health endpoint */
+    checkBundleStatus(bundle: string, cb?: (err: Error | null, status: object) => void): Promise<object>;
+
+    /** Forward the request to another bundle */
+    forward(req: GinaRequest, res: GinaResponse, next: NextFunction): void;
+
+    /** Conditional 404: throw 404 unless `condition` is truthy */
+    forward404Unless(condition: any, req: GinaRequest, res: GinaResponse, next?: NextFunction): Error | boolean;
+
+    /** Push an SSE payload to connected clients */
+    push(payload: any, option?: object, callback?: (err: Error | null) => void): void;
+
+    /** Check if the session has a halted request */
+    isHaltedRequest(session?: object): boolean;
+    /** Snapshot and store the current request for later replay */
+    pauseRequest(data?: object, requestStorage?: object): object;
+    /** Replay a previously paused request */
+    resumeRequest(requestStorage?: object): void;
+
+    /** Render the custom error page */
+    renderCustomError(req: GinaRequest, res: GinaResponse, next: NextFunction): void;
+
+    /**
+     * Error handler. Polymorphic signatures:
+     * - `throwError(err: Error)`
+     * - `throwError(res, code, msg)`
+     * - `throwError(errorObj)` where errorObj has `.status`, `.error`, `.fields`
+     */
+    throwError(err: Error): void;
+    throwError(res: GinaResponse, code: number, msg?: string | Error): void;
+    throwError(errorObj: { status?: number; error?: string; message?: string; fields?: object; flash?: object }): void;
+
+    /** Inject per-request state (called by router -- not typically used in app code) */
+    setOptions(req: GinaRequest, res: GinaResponse, next: NextFunction, options: object): void;
+
+    /** Create an isolated test instance */
+    static createTestInstance(deps?: { config?: Function; connector?: object }): SuperController;
+}
+
+// ─── EntitySuper ─────────────────────────────────────────────────────────────
+
+export interface EntityInjected {
+    config?: (bundle: string, confName: string) => any;
+    connector?: any;
+}
+
+/**
+ * Base entity class. Each model entity inherits from EntitySuper.
+ * Entity methods return Promises with an `.onComplete(cb)` shim attached.
+ */
+export class EntitySuper extends EventEmitter {
+    initialized: boolean;
+    name: string;
+    bundle: string;
+    model: string;
+
+    /**
+     * @param conn - Database connection object from the connector
+     * @param caller - Name of calling context (debug)
+     * @param injected - Dependency overrides for unit testing
+     */
+    constructor(conn: any, caller?: string, injected?: EntityInjected);
+
+    /** Get the database connection object */
+    getConnection(scope?: string, collection?: string): any;
+
+    /** Get bundle config */
+    getConfig(bundle?: string, confName?: string): any;
+
+    /**
+     * Get a related entity by name.
+     * Supports short names: `'user'` resolves to `'user/user'`.
+     */
+    getEntity(entity: string): any;
+
+    /** Override the cached entity instance */
+    setInstance(instance: any): void;
+}
+
+// ─── Query / Download option shapes ──────────────────────────────────────────
+
+export interface QueryOptions {
+    host?: string;
+    hostname?: string;
+    port?: number;
+    path?: string;
+    method?: string;
+    headers?: Record<string, string>;
+    /** When `false`, HTTP/2 errors are swallowed (log-only) instead of propagating */
+    critical?: boolean;
+    rejectUnauthorized?: boolean;
+    [key: string]: any;
+}
+
+export interface DownloadOptions {
+    /** Override the downloaded file name */
+    file?: string | null;
+    fileSize?: number | null;
+    /** Store locally instead of streaming to client */
+    toLocalDir?: string | false;
+    contentDisposition?: string;
+    contentType?: string;
+    agent?: any;
+    rejectUnauthorized?: boolean;
+    port?: number;
+    method?: string;
+    keepAlive?: boolean;
+    headers?: Record<string, string>;
+}
+
+// ─── Config file shapes ──────────────────────────────────────────────────────
+
+/** A single route entry in `routing.json` */
+export interface RouteEntry {
+    url: string;
+    method: string;
+    param: RouteParam;
+    requirements?: Record<string, string>;
+    middleware?: string[];
+    middlewareIgnored?: string[];
+    bundle?: string;
+    hostname?: string;
+    scopes?: string[];
+    cache?: string | RouteCache;
+    namespace?: string;
+    _comment?: string;
+    _sample?: any;
+}
+
+export interface RouteParam {
+    control: string;
+    file?: string;
+    path?: string;
+    code?: number;
+    ignoreWebRoot?: boolean;
+    title?: string;
+}
+
+export interface RouteCache {
+    type?: string;
+    ttl?: number;
+    visibility?: string;
+    sliding?: boolean;
+    maxAge?: number;
+    invalidateOnEvents?: string[];
+}
+
+/** `routing.json` — keys are route names */
+export type RoutingConfig = Record<string, RouteEntry>;
+
+/** A single connector entry in `connectors.json` */
+export interface ConnectorEntry {
+    connector?: 'couchbase' | 'mysql' | 'postgresql' | 'sqlite' | 'redis' | 'ai';
+    protocol?: string;
+    host?: string;
+    port?: number;
+    database?: string;
+    username?: string;
+    password?: string;
+    scope?: string;
+    connectionLimit?: number;
+    ssl?: object;
+    /** SQLite: path to database file */
+    file?: string;
+    /** PostgreSQL: idle timeout in ms */
+    idleTimeout?: number;
+    /** PostgreSQL: connection timeout in ms */
+    connectionTimeout?: number;
+    /** Redis: database index */
+    db?: number;
+    /** Redis: TLS toggle */
+    tls?: boolean;
+    /** Redis: key prefix for sessions */
+    prefix?: string;
+    /** Redis: TTL in seconds */
+    ttl?: number;
+    /** Redis: cluster node list */
+    cluster?: Array<{ host: string; port: number }>;
+    /** Couchbase: keep connection alive */
+    keepAlive?: boolean;
+    /** Couchbase: ping interval (e.g. `"2m"`) */
+    pingInterval?: string;
+    /** Couchbase: use scopes and collections */
+    useScopeAndCollections?: boolean;
+    /** Couchbase: timeout overrides */
+    timeouts?: Record<string, number>;
+    /** AI: API key or env var reference */
+    apiKey?: string;
+    /** AI: model identifier */
+    model?: string;
+    /** AI: base URL override */
+    baseURL?: string;
+}
+
+/** `connectors.json` — keys are connector names */
+export type ConnectorsConfig = Record<string, ConnectorEntry>;
+
+/** `app.json` */
+export interface AppConfig {
+    name: string;
+    version: string;
+    greeting?: string;
+    proxy?: Record<string, {
+        ca?: string;
+        hostname?: string;
+        port?: number;
+        path?: string;
+        requestTimeout?: number;
+    }>;
+    apis?: Record<string, object>;
+}
+
+/** `settings.json` */
+export interface SettingsConfig {
+    region?: {
+        culture?: string;
+        isoShort?: string;
+        date?: string;
+        timeZone?: string;
+    };
+    server?: {
+        engine?: 'isaac' | 'express';
+        protocol?: string;
+        scheme?: string;
+        allowHTTP1?: boolean;
+        warmup?: number;
+    };
+    ioServer?: {
+        integrationMode?: string;
+        transports?: string[];
+        pingInterval?: number;
+        pingTimeout?: number;
+    };
+    upload?: {
+        maxFieldsSize?: number;
+    };
+    response?: {
+        header?: Record<string, string>;
+    };
+    http2Options?: {
+        maxConcurrentStreams?: number;
+        initialWindowSize?: number;
+    };
+}
+
+/** A single bundle entry in `manifest.json` */
+export interface ManifestBundle {
+    version: string;
+    tag?: string;
+    gina_version?: string;
+    src: string;
+    link?: Record<string, string>;
+    releases?: Record<string, string>;
+}
+
+/** `manifest.json` */
+export interface ManifestConfig {
+    name: string;
+    version: string;
+    scope: string;
+    rootDomain: string;
+    bundles: Record<string, ManifestBundle>;
+}
+
+/** A single watcher entry in `watchers.json` */
+export interface WatcherEntry {
+    event?: 'change' | 'rename';
+    persistent?: boolean;
+}
+
+/** `watchers.json` — keys are config file names */
+export type WatchersConfig = Record<string, WatcherEntry>;
+
+/** A single cron entry in `app.crons.json` */
+export interface CronEntry {
+    active: boolean;
+    interval: string;
+    task: string;
+    processingCores?: number;
+}
+
+/** `app.crons.json` — keys are cron names */
+export type CronsConfig = Record<string, CronEntry>;
+
+// ─── lib registry ────────────────────────────────────────────────────────────
+
+export interface GinaLib {
+    Config: any;
+    inherits: (ctor: Function, superCtor: Function) => void;
+    helpers: any;
+    Domain: any;
+    Model: any;
+    Collection: any;
+    merge: (source: object, target: object) => object;
+    generator: any;
+    Proc: any;
+    Shell: any;
+    logger: any;
+    math: any;
+    routing: {
+        getRoute(name: string): RouteEntry | undefined;
+        getRouteByUrl(url: string): RouteEntry | undefined;
+        [key: string]: any;
+    };
+    archiver: any;
+    cmd: any;
+    SessionStore: any;
+    SwigFilters: any;
+    Cache: any;
+    uuid: UuidFunction;
+    Watcher: any;
+    async: <T = any>(emitter: OnCompletable) => Promise<T>;
+    State: any;
+}
+
+// ─── Gna (main module export) ────────────────────────────────────────────────
+
+export interface Gna extends EventEmitter {
+    lib: GinaLib;
+    locales: any;
+    plugins: any;
+    initialized: boolean;
+    routed: boolean;
+    started: boolean;
+    env: string;
+    scope: string;
+    executionPath: string;
+    project: ManifestConfig;
+    watcher?: any;
+    isAborting: boolean;
+
+    /**
+     * Called after models are loaded and connectors are ready.
+     * @param callback - `(emitter, instance, middleware) => void`
+     */
+    onInitialize(callback: (emitter: EventEmitter, instance: any, middleware: any) => void): void;
+
+    /** Called when the HTTP server is listening */
+    onStarted(callback: () => void): void;
+
+    /**
+     * Called on every incoming request after routing resolves.
+     * @param callback - `(emitter, request, response, next, params) => void`
+     */
+    onRouting(callback: (emitter: EventEmitter, request: GinaRequest, response: GinaResponse, next: NextFunction, params: object) => void): void;
+
+    /** Called on framework-level errors */
+    onError(callback: (err: Error, request?: GinaRequest, response?: GinaResponse, next?: NextFunction) => void): void;
+
+    /** Get bundle config (available after onInitialize) */
+    getConfig(name?: string): any;
+
+    /** Get the parsed manifest as a project object */
+    getProjectConfiguration(callback: (err: Error | null, project: ManifestConfig) => void): void;
+
+    /** Mount a bundle via symlink */
+    mount(bundlesPath: string, source: string, target: string, type?: string, callback?: (err: Error | null) => void): void;
+
+    /** Read connector shutdown config (async) */
+    getShutdownConnector(callback: (err: Error | null, config: object) => void): void;
+    /** Read connector shutdown config (sync) */
+    getShutdownConnectorSync(): object | undefined;
+
+    /** List mounted bundles (async) */
+    getMountedBundles(callback: (err: Error | null, bundles: string[]) => void): void;
+    /** List mounted bundles (sync) */
+    getMountedBundlesSync(): string[] | string;
+
+    /** Get running bundle PIDs: `[bundlePids, ginaPids]` */
+    getRunningBundlesSync(): [string[], string[]];
+
+    /** Read bundle version from app.json */
+    getVersion(bundle?: string): string | Error | undefined;
+
+    /** Start the bundle server */
+    start(): void;
+    /** Stop the bundle process */
+    stop(pid: number, code?: number): void;
+    /** Check bundle status */
+    status(bundle: string): void;
+    /** Restart the bundle */
+    restart(): void;
+}

package/framework/v0.3.2/VERSION

@@ -1 +0,0 @@
-0.3.2