@gravito/spectrum 3.0.0 → 3.0.2

package/dist/index.d.cts

@@ -3,41 +3,98 @@ import { GravitoContext, GravitoOrbit, PlanetCore } from '@gravito/core';
 /**
  * @gravito/spectrum - Types
  */
+/**
+ * Represents a detailed snapshot of an HTTP request processed by the application.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface CapturedRequest {
+    /** Unique execution ID. */
     id: string;
+    /** HTTP Method (GET, POST, etc.). */
     method: string;
+    /** URL Path. */
     path: string;
+    /** Full URL. */
     url: string;
+    /** HTTP response status code. */
     status: number;
+    /** Processing duration in milliseconds. */
     duration: number;
+    /** Epoch timestamp of when the request started. */
     startTime: number;
+    /** Client IP address. */
     ip: string;
+    /** Client user agent string. */
     userAgent?: string;
+    /** Incoming request headers. */
     requestHeaders: Record<string, string>;
+    /** Outgoing response headers. */
     responseHeaders: Record<string, string>;
+    /** Parsed request body (if captured). */
     requestBody?: any;
+    /** Parsed response body (if captured). */
     responseBody?: any;
+    /** Request ID for correlation with logs and queries. */
+    requestId?: string;
 }
+/**
+ * Represents a log entry captured during application execution.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface CapturedLog {
+    /** Unique log entry ID. */
     id: string;
+    /** Log severity level. */
     level: 'debug' | 'info' | 'warn' | 'error';
+    /** The primary log message text. */
     message: string;
+    /** Additional arguments passed to the logger. */
     args: any[];
+    /** Epoch timestamp when the log was generated. */
     timestamp: number;
+    /** Request ID for correlation with the originating request. */
+    requestId?: string;
 }
+/**
+ * Represents a database query captured during application execution.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface CapturedQuery {
+    /** Unique query execution ID. */
     id: string;
+    /** The name of the database connection used. */
     connection: string;
+    /** The raw or prepared SQL statement. */
     sql: string;
+    /** Prepared statement bindings/parameters. */
     bindings: any[];
+    /** Query execution duration in milliseconds. */
     duration: number;
+    /** Epoch timestamp when the query was executed. */
     timestamp: number;
+    /** Request ID for correlation with the originating request. */
+    requestId?: string;
 }
 
 /**
  * @gravito/spectrum - Storage Contract
  */
 
+/**
+ * Interface for Spectrum storage backends.
+ *
+ * Implement this interface to provide custom storage for captured telemetry
+ * data (requests, logs, queries).
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface SpectrumStorage {
     /**
      * Initialize storage driver
@@ -85,17 +142,30 @@ interface SpectrumStorage {
  * @gravito/spectrum - SpectrumOrbit
  */
 
+/**
+ * Configuration options for the Spectrum observability orbit.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface SpectrumConfig {
+    /** The URL path where the dashboard UI will be served. @default '/gravito/spectrum' */
     path?: string;
+    /** Maximum number of records to keep in memory/disk per category. @default 100 */
     maxItems?: number;
+    /** Whether the spectrum capture is enabled. @default true */
     enabled?: boolean;
+    /** Custom storage backend for captured data. Defaults to MemoryStorage. */
     storage?: SpectrumStorage;
     /**
-     * Authorization gate. Return true to allow access.
+     * Authorization gate for accessing the dashboard and its API.
+     * Return true to allow access, false to block.
      */
     gate?: (c: GravitoContext) => boolean | Promise<boolean>;
     /**
-     * Sample rate (0.0 to 1.0). Default: 1.0 (100%)
+     * Probability sample rate (0.0 to 1.0).
+     * 1.0 captures everything, 0.0 captures nothing.
+     * @default 1.0
      */
     sampleRate?: number;
 }
@@ -111,21 +181,112 @@ interface SpectrumOrbitDeps {
         };
     } | null>;
 }
+/**
+ * SpectrumOrbit is the official observability and debug dashboard for Gravito.
+ *
+ * It automatically captures HTTP requests, application logs, and database queries,
+ * providing a real-time view of your application's internals. It includes a
+ * built-in web dashboard for exploring and replaying captured data.
+ *
+ * @example
+ * ```typescript
+ * import { SpectrumOrbit } from '@gravito/spectrum';
+ *
+ * const spectrum = new SpectrumOrbit({
+ *   gate: (ctx) => ctx.get('auth')?.user?.isAdmin
+ * });
+ * core.addOrbit(spectrum);
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
 declare class SpectrumOrbit implements GravitoOrbit {
+    /**
+     * Global instance of SpectrumOrbit.
+     *
+     * Used for internal access and singleton patterns within the framework.
+     */
     static instance: SpectrumOrbit | undefined;
     readonly name = "spectrum";
     private config;
     private listeners;
+    private currentRequestId;
     private warnedSecurity;
     private deps;
+    /**
+     * Initializes a new instance of SpectrumOrbit.
+     *
+     * @param config - Configuration options for behavior and storage
+     * @param deps - Internal dependencies for integration with other orbits
+     *
+     * @example
+     * ```typescript
+     * const spectrum = new SpectrumOrbit({ path: '/debug' });
+     * ```
+     */
     constructor(config?: SpectrumConfig, deps?: SpectrumOrbitDeps);
+    /**
+     * Checks if the current operation should be captured based on sample rate.
+     *
+     * @returns True if capture is allowed
+     */
     private shouldCapture;
+    /**
+     * Broadcasts telemetry data to all connected SSE clients.
+     *
+     * @param type - The category of the data
+     * @param data - The telemetry payload
+     */
     private broadcast;
+    /**
+     * Installs the Spectrum orbit into the Gravito core.
+     *
+     * Sets up collection listeners, initializes storage, and registers API/UI routes.
+     *
+     * @param core - The planet core instance
+     * @returns Resolves when installation is complete
+     * @throws {Error} If storage initialization fails
+     *
+     * @example
+     * ```typescript
+     * await spectrum.install(core);
+     * ```
+     */
     install(core: PlanetCore): Promise<void>;
+    /**
+     * Configures collection of database queries from Atlas orbit.
+     *
+     * @param core - The planet core instance
+     */
     private setupDatabaseCollection;
+    /**
+     * Configures interception of HTTP requests and responses.
+     *
+     * @param core - The planet core instance
+     */
     private setupHttpCollection;
+    /**
+     * Configures interception of application logs.
+     *
+     * Wraps the core logger to capture all log calls.
+     *
+     * @param core - The planet core instance
+     */
     private setupLogCollection;
+    /**
+     * Processes and stores a captured log entry.
+     *
+     * @param level - Log severity level
+     * @param message - Primary message string
+     * @param args - Additional log arguments
+     */
     private captureLog;
+    /**
+     * Registers all API and UI routes for the Spectrum dashboard.
+     *
+     * @param core - The planet core instance
+     */
     private registerRoutes;
 }
 
@@ -135,28 +296,129 @@ declare class SpectrumOrbit implements GravitoOrbit {
  * Persistent storage using JSONL files.
  */
 
+/**
+ * Configuration for the `FileStorage` backend.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface FileStorageConfig {
+    /** The directory where captured telemetry data will be stored as JSONL files. */
     directory: string;
 }
+/**
+ * FileStorage persists Spectrum telemetry data to the local file system.
+ *
+ * It uses newline-delimited JSON (JSONL) files for efficient appends and
+ * maintains an in-memory cache for fast dashboard retrieval.
+ *
+ * @public
+ * @since 3.0.0
+ */
 declare class FileStorage implements SpectrumStorage {
     private config;
     private requestsPath;
     private logsPath;
     private queriesPath;
     private cache;
+    /**
+     * Initializes a new instance of FileStorage.
+     *
+     * @param config - Configuration including the target directory for JSONL files
+     *
+     * @example
+     * ```typescript
+     * const storage = new FileStorage({ directory: './storage' });
+     * ```
+     */
     constructor(config: FileStorageConfig);
+    /**
+     * Initializes the storage by creating the directory and loading existing files into memory.
+     *
+     * @returns Resolves when initialization is complete
+     * @throws {Error} If directory creation fails
+     */
     init(): Promise<void>;
+    /**
+     * Loads newline-delimited JSON data from a file into a target array.
+     *
+     * @param path - The absolute path to the JSONL file
+     * @param target - The array to populate with parsed objects
+     */
     private loadCache;
+    /**
+     * Internal helper to append data to both the in-memory cache and the JSONL file.
+     *
+     * @param path - File path to append to
+     * @param data - The telemetry object
+     * @param list - The cache array
+     */
     private append;
+    /**
+     * Persists a captured HTTP request.
+     *
+     * @param req - The request snapshot
+     */
     storeRequest(req: CapturedRequest): Promise<void>;
+    /**
+     * Persists a captured log entry.
+     *
+     * @param log - The log snapshot
+     */
     storeLog(log: CapturedLog): Promise<void>;
+    /**
+     * Persists a captured database query.
+     *
+     * @param query - The query snapshot
+     */
     storeQuery(query: CapturedQuery): Promise<void>;
+    /**
+     * Retrieves recent HTTP requests from storage.
+     *
+     * @param limit - Maximum number of items to return
+     * @param offset - Pagination offset
+     * @returns Array of requests
+     */
     getRequests(limit?: number, offset?: number): Promise<CapturedRequest[]>;
+    /**
+     * Retrieves a specific HTTP request by its unique ID.
+     *
+     * @param id - The snapshot ID
+     * @returns The request or null if not found
+     */
     getRequest(id: string): Promise<CapturedRequest | null>;
+    /**
+     * Retrieves recent logs from storage.
+     *
+     * @param limit - Maximum number of items to return
+     * @param offset - Pagination offset
+     * @returns Array of logs
+     */
     getLogs(limit?: number, offset?: number): Promise<CapturedLog[]>;
+    /**
+     * Retrieves recent database queries from storage.
+     *
+     * @param limit - Maximum number of items to return
+     * @param offset - Pagination offset
+     * @returns Array of queries
+     */
     getQueries(limit?: number, offset?: number): Promise<CapturedQuery[]>;
+    /**
+     * Wipes all data from both cache and files.
+     */
     clear(): Promise<void>;
+    /**
+     * Truncates the storage to stay within the specified limit.
+     *
+     * @param maxItems - The maximum allowed records per category
+     */
     prune(maxItems: number): Promise<void>;
+    /**
+     * Overwrites the file content with the current in-memory data.
+     *
+     * @param path - File path to overwrite
+     * @param data - The array of data objects
+     */
     private rewrite;
 }
 
@@ -166,21 +428,100 @@ declare class FileStorage implements SpectrumStorage {
  * Non-persistent storage for development.
  */
 
+/**
+ * MemoryStorage provides a fast, non-persistent storage backend for Spectrum telemetry.
+ *
+ * This implementation is ideal for local development environments where data persistence
+ * across server restarts is not required. It maintains all captured data in memory
+ * and automatically prunes old records based on the configured limits.
+ *
+ * @public
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const storage = new MemoryStorage();
+ * ```
+ */
 declare class MemoryStorage implements SpectrumStorage {
     private requests;
     private logs;
     private queries;
     private maxItems;
+    /**
+     * Initializes the memory storage.
+     *
+     * As memory storage does not require external resources, this is a no-op.
+     *
+     * @returns Resolves immediately
+     */
     init(): Promise<void>;
+    /**
+     * Temporarily stores a captured HTTP request in memory.
+     *
+     * @param req - The request snapshot to store
+     */
     storeRequest(req: CapturedRequest): Promise<void>;
+    /**
+     * Temporarily stores a captured log entry in memory.
+     *
+     * @param log - The log entry to store
+     */
     storeLog(log: CapturedLog): Promise<void>;
+    /**
+     * Temporarily stores a captured database query in memory.
+     *
+     * @param query - The query information to store
+     */
     storeQuery(query: CapturedQuery): Promise<void>;
+    /**
+     * Retrieves a list of recent HTTP requests from memory.
+     *
+     * @param limit - Maximum number of requests to return
+     * @param offset - Number of requests to skip for pagination
+     * @returns A promise resolving to an array of captured requests
+     */
     getRequests(limit?: number, offset?: number): Promise<CapturedRequest[]>;
+    /**
+     * Finds a specific HTTP request by its unique identifier.
+     *
+     * @param id - The unique ID of the request to find
+     * @returns The found request or null if not present
+     */
     getRequest(id: string): Promise<CapturedRequest | null>;
+    /**
+     * Retrieves a list of recent application logs from memory.
+     *
+     * @param limit - Maximum number of logs to return
+     * @param offset - Number of logs to skip for pagination
+     * @returns A promise resolving to an array of captured logs
+     */
     getLogs(limit?: number, offset?: number): Promise<CapturedLog[]>;
+    /**
+     * Retrieves a list of recent database queries from memory.
+     *
+     * @param limit - Maximum number of queries to return
+     * @param offset - Number of queries to skip for pagination
+     * @returns A promise resolving to an array of captured queries
+     */
     getQueries(limit?: number, offset?: number): Promise<CapturedQuery[]>;
+    /**
+     * Wipes all captured telemetry data from memory.
+     *
+     * @returns Resolves when all collections are emptied
+     */
     clear(): Promise<void>;
+    /**
+     * Sets a new capacity limit and prunes existing data to fit.
+     *
+     * @param maxItems - The new maximum number of items to retain per category
+     */
     prune(maxItems: number): Promise<void>;
+    /**
+     * Truncates an array to ensure it does not exceed the maximum allowed capacity.
+     *
+     * @param arr - The target array to truncate
+     */
     private trim;
 }