@gravito/spectrum 3.0.1 → 3.0.2

package/dist/index.d.cts

@@ -36,6 +36,8 @@ interface CapturedRequest {
     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.
@@ -54,6 +56,8 @@ interface CapturedLog {
     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.
@@ -74,6 +78,8 @@ interface CapturedQuery {
     duration: number;
     /** Epoch timestamp when the query was executed. */
     timestamp: number;
+    /** Request ID for correlation with the originating request. */
+    requestId?: string;
 }
 
 /**
@@ -196,20 +202,91 @@ interface SpectrumOrbitDeps {
  * @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;
 }
 
@@ -244,19 +321,104 @@ declare class FileStorage implements SpectrumStorage {
     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;
 }
 
@@ -266,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;
 }
 

package/dist/index.d.ts

@@ -36,6 +36,8 @@ interface CapturedRequest {
     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.
@@ -54,6 +56,8 @@ interface CapturedLog {
     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.
@@ -74,6 +78,8 @@ interface CapturedQuery {
     duration: number;
     /** Epoch timestamp when the query was executed. */
     timestamp: number;
+    /** Request ID for correlation with the originating request. */
+    requestId?: string;
 }
 
 /**
@@ -196,20 +202,91 @@ interface SpectrumOrbitDeps {
  * @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;
 }
 
@@ -244,19 +321,104 @@ declare class FileStorage implements SpectrumStorage {
     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;
 }
 
@@ -266,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;
 }