@gravito/spectrum 3.0.0 → 3.0.1

package/dist/index.d.cts

@@ -3,34 +3,76 @@ 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;
 }
+/**
+ * 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;
 }
+/**
+ * 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;
 }
 
@@ -38,6 +80,15 @@ interface CapturedQuery {
  * @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 +136,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,6 +175,26 @@ 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 {
     static instance: SpectrumOrbit | undefined;
     readonly name = "spectrum";
@@ -135,9 +219,25 @@ 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;

package/dist/index.d.ts

@@ -3,34 +3,76 @@ 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;
 }
+/**
+ * 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;
 }
+/**
+ * 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;
 }
 
@@ -38,6 +80,15 @@ interface CapturedQuery {
  * @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 +136,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,6 +175,26 @@ 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 {
     static instance: SpectrumOrbit | undefined;
     readonly name = "spectrum";
@@ -135,9 +219,25 @@ 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gravito/spectrum",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "publishConfig": {
     "access": "public"
   },