brahma-firelight/index.d.ts

A blazing-fast, fire-and-forget orchestrator built with Rust and JavaScript, designed for ultra-low-latency task routing, message triggering, and heavyweight logic execution — all without blocking. A native Rust AddOn for NodeJS, BunJS and DenoJS.

/* auto-generated by NAPI-RS */
/* eslint-disable */
// _________last updated on 20-December-2025_____________//8:00 a.m. (IST)
export declare function registerJsCallback(callback: ((err: Error | null, arg0: string, arg1: string, arg2: string, arg3: string, arg4: string, arg5: Buffer, arg6: string, arg7: string) => string)): void

export declare function respond(reqId: string, status: number, headersJson: string | undefined | null, cookiesJson: string | undefined | null, body: Buffer): void

export declare function startServer(host?: string | undefined | null, port?: number | undefined | null, forceNewRuntime?: boolean | undefined | null): void

export declare function getJsResponseTimeout(): number

export declare function getMaxBodyBytes(): number

export declare function setJsResponseTimeout(secs: number): void

export declare function setMaxBodyBytes(bytes: number): void

export declare function clearRustHotpaths(): void

export declare function listRustHotpaths(): Array<string>

export declare function removeRustHotpath(method: string, path: string): boolean

export declare function registerRustHotpath(method: string, path: string, status?: number | undefined | null, headersJson?: string | undefined | null, body?: Buffer | undefined | null, includeRequest?: boolean | undefined | null): void


/**
 * Lightweight Express-like wrapper for Brahma native addon.
 *
 * - createApp() -> App
 * - App.use(path?, ...handlers)  // mount middleware or global middleware
 * - App.get/post/put/del/delete/patch/all
 * - App.listen(host?, port?, cb?) // if both host and port passed, native startServer(host, port) is called; otherwise startServer()
 * - Graceful shutdown via App.close(timeoutMs?)
 */

export type NextFunction = (err?: any) => void;

/**
 * Node-style request object (lightweight).
 */
export interface Request {
  /** Unique request id assigned by native layer (string or number) */
  reqId: string | number;
  /** Request path, e.g. '/user/42' */
  path: string;
  /** HTTP method, uppercase, e.g. 'GET' */
  method: string;
  /** Parsed headers (may be string values or arrays depending on native layer) */
  headers: Record<string, any>;
  /** Query parameters parsed from the raw query string (simple k -> v mapping) */
  query: Record<string, string>;
  /** Route parameters (populated for routes with `:param`) */
  params: Record<string, string>;
  /** Raw request body (string) — adapt in your handlers if you expect JSON */
  body: any;
}

/**
 * Lightweight response helpers.
 *
 * Notes:
 * - `send(status, headers, body)` sends a raw response object.
 * - `json`, `html`, `text` convenience helpers set Content-Type appropriately.
 * - `setHeader` / `appendHeader` allows middleware to set headers which will be merged
 *   into the final response.
 */
export interface Response {
  /** true when the response was already sent */
  _sent?: boolean;

  /** send arbitrary response */
  send(status?: number, headers?: Record<string, any>, body?: any): void;

  /** send plain text */
  text(text: string, status?: number): void;

  /** send HTML */
  html(html: string, status?: number): void;

  /** send JSON (object will be stringified) */
  json(obj: any, status?: number): void;

  /** redirect */
  redirect(location: string, status?: number): void;

  /** set or replace header value */
  setHeader(name: string, value: any): void;

  /**
   * appendHeader(name, value)
   * - If header already exists and is not array, it will be converted into an array.
   * - Useful for `Set-Cookie` multiple header support if native layer supports arrays.
   */
  appendHeader(name: string, value: any): void;

  /** Internal: may be present at runtime */
  _sendObj?: (obj: { status?: number; headers?: Record<string, any>; body?: any }) => void;
}

/** Standard middleware handler. Call next() to proceed. */
export type Handler = (req: Request, res: Response, next?: NextFunction) => any;

/** Error-handling middleware: (err, req, res, next) */
export type ErrorHandler = (err: any, req: Request, res: Response, next: NextFunction) => any;

export interface App {
  /**
   * Register middleware.
   * - app.use(fn)                 // global middleware
   * - app.use(path, fn1, fn2...)  // mount middleware on a prefix
   */
  use(pathOrFn: string | Handler, ...fns: Handler[]): App;

  /** Register GET route */
  get(path: string, ...handlers: (Handler | ErrorHandler)[]): App;

  /** Register POST route */
  post(path: string, ...handlers: (Handler | ErrorHandler)[]): App;

  /** Register PUT route */
  put(path: string, ...handlers: (Handler | ErrorHandler)[]): App;

  /** Register PATCH route */
  patch(path: string, ...handlers: (Handler | ErrorHandler)[]): App;

  /**
   * Register DELETE route (alias: `delete`)
   * Use `del` to avoid reserved-word ambiguities in some editors.
   */
  del(path: string, ...handlers: (Handler | ErrorHandler)[]): App;

  /** Alias for del */
  delete(path: string, ...handlers: (Handler | ErrorHandler)[]): App;

  /** Register any-method route */
  all(path: string, ...handlers: (Handler | ErrorHandler)[]): App;

  /**
   * Start the native server.
   *
   * Semantics:
   * - If both `host` and `port` are provided, the wrapper will call native startServer(host, port).
   * - Otherwise it calls native startServer() with no args.
   *
   * Examples:
   *   app.listen('0.0.0.0', 2025, () => {});
   *   app.listen(() => {}); // native picks defaults
   */
  listen(host?: string, port?: number | string, cb?: () => void, multicore?: boolean): App;

  /**
   * Close the server gracefully.
   * Resolves when shutdown completes or after `timeoutMs` milliseconds.
   * Default timeout: 10000 ms.
   */
  close(timeoutMs?: number): Promise<void>;

  /** For debugging / testing: internal state */
  _internal?: {
    middleware?: Array<{ path: string; fn: Handler }>;
    routes?: Array<{ method: string; path: string; /* handler hidden */ any: any }>;
  };
}

/**
 * Create a new app instance.
 * @returns {App}
 */
export function createApp(): App;

export default createApp;