@lahin31/debugcontext-core 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,332 @@
+/**
+ * @module types
+ * Core type definitions for DebugContext incidents.
+ */
+/** HTTP request context captured at the time of the error. */
+interface RequestContext {
+    /** HTTP method (GET, POST, …) */
+    method: string;
+    /** Full request URL including query string */
+    url: string;
+    /** Express-style named route params, e.g. { id: "42" } */
+    params: Record<string, string>;
+    /** Parsed query-string parameters */
+    query: Record<string, string | string[]>;
+    /** Request body — sensitive fields are redacted */
+    body: unknown;
+    /** Selected headers — auth / cookie values are redacted */
+    headers: Record<string, string>;
+    /** Client IP address */
+    ip: string;
+    /** User-Agent string */
+    userAgent: string;
+}
+/** Node.js runtime context at the time of the error. */
+interface RuntimeContext {
+    /** ISO-8601 timestamp */
+    timestamp: string;
+    /** NODE_ENV value, defaults to "development" */
+    environment: string;
+    /** process.version */
+    nodeVersion: string;
+    /** process.pid */
+    pid: number;
+    /** os.hostname() */
+    hostname: string;
+    /** process.uptime() in seconds */
+    uptimeSeconds: number;
+    /** process.cwd() */
+    workingDirectory: string;
+}
+/** Operating-system / process memory context. */
+interface SystemContext {
+    /** process.memoryUsage() */
+    memory: {
+        rss: number;
+        heapTotal: number;
+        heapUsed: number;
+        external: number;
+        arrayBuffers: number;
+    };
+    /** Heap usage as a percentage 0-100 */
+    heapUsagePercent: number;
+    /** os.loadavg() — [1m, 5m, 15m] */
+    cpuLoadAvg: [number, number, number];
+    /** os.platform() */
+    platform: string;
+    /** os.arch() */
+    arch: string;
+    /** Total system memory in bytes */
+    totalMemory: number;
+    /** Free system memory in bytes */
+    freeMemory: number;
+}
+/** Git / package metadata resolved at startup. */
+interface GitContext {
+    /** Short (8-char) commit hash, or "unknown" */
+    commitHash: string;
+    /** Current branch name, or "unknown" */
+    branch: string;
+    /** version field from the nearest package.json */
+    packageVersion: string;
+}
+/** Serialisable error context. */
+interface ErrorContext {
+    /** Error constructor name */
+    name: string;
+    /** Error message */
+    message: string;
+    /** Full stack trace */
+    stack: string | undefined;
+    /** Serialised error.cause if present */
+    cause: unknown;
+}
+/**
+ * A fully structured debugging snapshot produced whenever an unhandled error
+ * or a caught framework error occurs.
+ */
+interface Incident {
+    /** Unique ID for this incident (UUID v4) */
+    incidentId: string;
+    /** ISO-8601 timestamp — duplicated here for quick top-level access */
+    timestamp: string;
+    /** HTTP request that was in-flight when the error occurred (may be null) */
+    request: RequestContext | null;
+    /** Node.js runtime snapshot */
+    runtime: RuntimeContext;
+    /** System resource snapshot */
+    system: SystemContext;
+    /** Git / package metadata */
+    git: GitContext;
+    /** Serialised error */
+    error: ErrorContext;
+}
+/**
+ * Options accepted by `DebugContext.init()`.
+ * Everything is optional — the SDK works with zero configuration.
+ */
+interface DebugContextOptions {
+    /**
+     * Additional header names whose values should be redacted.
+     * Merged with the built-in sensitive header list.
+     */
+    sensitiveHeaders?: string[];
+    /**
+     * Additional body field names whose values should be redacted.
+     * Merged with the built-in sensitive field list.
+     */
+    sensitiveFields?: string[];
+    /**
+     * Called after each incident is captured.
+     * Use this hook to ship incidents to your own storage / alerting.
+     *
+     * @example
+     * DebugContext.init({
+     *   onIncident: (incident) => myStorage.save(incident),
+     * });
+     */
+    onIncident?: (incident: Incident) => void | Promise<void>;
+    /**
+     * When true, DebugContext attaches a global `uncaughtException` +
+     * `unhandledRejection` listener.  Defaults to `true`.
+     */
+    captureGlobalErrors?: boolean;
+}
+
+interface ToFileOptions {
+    /**
+     * Path to the output file.
+     * @default "incidents.ndjson"  (relative to process.cwd())
+     */
+    path?: string;
+    /**
+     * When `true`, creates parent directories if they don't exist.
+     * @default true
+     */
+    mkdirp?: boolean;
+}
+/**
+ * Appends an incident as a single JSON line to an NDJSON file.
+ *
+ * - Safe to call from multiple processes (append is atomic on most OSes).
+ * - Synchronous by design so it can be called inside `onIncident` without
+ *   worrying about buffering or unhandled promise rejections.
+ *
+ * @param incident - The incident to write.
+ * @param options  - Output options.
+ *
+ * @example
+ * ```ts
+ * // Write to the default path (incidents.ndjson)
+ * DebugContext.toFile(incident);
+ *
+ * // Write to a custom path
+ * DebugContext.toFile(incident, { path: 'logs/incidents.ndjson' });
+ * ```
+ */
+declare function toFile$1(incident: Incident, options?: ToFileOptions): void;
+
+/**
+ * Initialises DebugContext with optional configuration.
+ *
+ * Call once at application startup — before your Express app starts
+ * accepting requests.
+ *
+ * @example
+ * ```ts
+ * import DebugContext from '@debugcontext/core';
+ *
+ * DebugContext.init({ onIncident: (i) => console.log(i) });
+ * ```
+ */
+declare function init(userOptions?: DebugContextOptions): void;
+/**
+ * Captures an error (and an optional request context provided by a framework
+ * adapter) into a structured Incident.
+ *
+ * @param error   - The thrown value.
+ * @param request - Optional request context from a framework adapter.
+ * @returns The captured Incident.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   riskyOperation();
+ * } catch (err) {
+ *   const incident = DebugContext.capture(err);
+ *   DebugContext.toConsole(incident);
+ * }
+ * ```
+ */
+declare function capture(error: unknown, request?: RequestContext | null): Incident;
+/**
+ * Returns the most recently captured Incident as a JSON string.
+ *
+ * @param incident - Incident to serialise.  Defaults to the last captured one.
+ * @returns Pretty-printed JSON string, or `null` if no incident has been captured.
+ */
+declare function toJSON(incident?: Incident): string | null;
+/**
+ * Prints the incident to the console in a human-readable format.
+ *
+ * @param incident - Incident to print.  Defaults to the last captured one.
+ */
+declare function toConsole(incident?: Incident): void;
+/**
+ * Appends the incident to a newline-delimited JSON (NDJSON) file.
+ * Creates the file and parent directories if they don't exist.
+ *
+ * @param incident - Incident to write. Defaults to the last captured one.
+ * @param options  - `{ path?: string }` — defaults to `"incidents.ndjson"`.
+ *
+ * @example
+ * ```ts
+ * DebugContext.init({
+ *   onIncident: (i) => DebugContext.toFile(i, { path: 'logs/incidents.ndjson' }),
+ * });
+ * ```
+ */
+declare function toFile(incident?: Incident, options?: ToFileOptions): void;
+/**
+ * Returns a framework-agnostic capture function pre-bound to the current
+ * options. Useful when building custom adapters.
+ *
+ * For Express, use `@debugcontext/express` instead.
+ *
+ * @example
+ * ```ts
+ * // In a custom adapter:
+ * const mw = DebugContext.middleware();
+ * app.use((err, req, res, next) => {
+ *   const requestCtx = buildRequestCtx(req);
+ *   mw(err, requestCtx);
+ *   next(err);
+ * });
+ * ```
+ */
+declare function middleware(): (error: unknown, request?: RequestContext | null) => Incident;
+/**
+ * Returns the current SDK options (useful for adapters).
+ * @internal
+ */
+declare function getOptions(): Required<DebugContextOptions>;
+/**
+ * The DebugContext SDK.
+ *
+ * @example
+ * ```ts
+ * import DebugContext from '@debugcontext/core';
+ *
+ * DebugContext.init();
+ * ```
+ */
+declare const DebugContext: {
+    readonly init: typeof init;
+    readonly capture: typeof capture;
+    readonly toJSON: typeof toJSON;
+    readonly toConsole: typeof toConsole;
+    readonly toFile: typeof toFile;
+    readonly middleware: typeof middleware;
+    /** @internal used by framework adapters */
+    readonly getOptions: typeof getOptions;
+};
+
+/**
+ * @module collectors/error
+ * Serialises a thrown value into a structured ErrorContext.
+ */
+
+/**
+ * Converts any thrown value into a structured, serialisable ErrorContext.
+ *
+ * Handles:
+ * - Standard `Error` instances (including subclasses).
+ * - Errors with a `.cause` (ES2022 error chaining).
+ * - Non-Error throws (strings, objects, etc.).
+ */
+declare function collectError(thrown: unknown): ErrorContext;
+
+/**
+ * Returns the Git context.  Resolution runs once and is then cached for the
+ * lifetime of the process.
+ */
+declare function collectGit(): GitContext;
+
+/**
+ * Captures a snapshot of the current Node.js runtime environment.
+ */
+declare function collectRuntime(): RuntimeContext;
+
+/**
+ * Captures a snapshot of current system resource usage.
+ */
+declare function collectSystem(): SystemContext;
+
+/**
+ * @module redact
+ * Utilities for scrubbing sensitive data from headers and request bodies
+ * before they are included in an Incident.
+ */
+/** Header names that are always redacted (case-insensitive comparison). */
+declare const DEFAULT_SENSITIVE_HEADERS: readonly string[];
+/** Body / object field names that are always redacted (case-insensitive). */
+declare const DEFAULT_SENSITIVE_FIELDS: readonly string[];
+/**
+ * Returns a copy of `headers` where sensitive values are replaced with
+ * `"[REDACTED]"`.
+ *
+ * @param headers       - Raw header map (values may be string or string[]).
+ * @param extraFields   - Caller-supplied additional header names to redact.
+ */
+declare function redactHeaders(headers: Record<string, string | string[] | undefined>, extraFields?: string[]): Record<string, string>;
+/**
+ * Deeply walks `body` (plain objects / arrays) and replaces the *values* of
+ * sensitive keys with `"[REDACTED]"`.  Non-plain-object values are returned
+ * as-is (e.g. strings, numbers, Buffers).
+ *
+ * @param body        - The request body to sanitise.
+ * @param extraFields - Caller-supplied additional field names to redact.
+ */
+declare function redactBody(body: unknown, extraFields?: string[]): unknown;
+
+export { DEFAULT_SENSITIVE_FIELDS, DEFAULT_SENSITIVE_HEADERS, type DebugContextOptions, type ErrorContext, type GitContext, type Incident, type RequestContext, type RuntimeContext, type SystemContext, type ToFileOptions, capture, collectError, collectGit, collectRuntime, collectSystem, DebugContext as default, getOptions, init, middleware, redactBody, redactHeaders, toConsole, toFile, toJSON, toFile$1 as writeIncidentToFile };

package/dist/index.d.ts

@@ -0,0 +1,332 @@
+/**
+ * @module types
+ * Core type definitions for DebugContext incidents.
+ */
+/** HTTP request context captured at the time of the error. */
+interface RequestContext {
+    /** HTTP method (GET, POST, …) */
+    method: string;
+    /** Full request URL including query string */
+    url: string;
+    /** Express-style named route params, e.g. { id: "42" } */
+    params: Record<string, string>;
+    /** Parsed query-string parameters */
+    query: Record<string, string | string[]>;
+    /** Request body — sensitive fields are redacted */
+    body: unknown;
+    /** Selected headers — auth / cookie values are redacted */
+    headers: Record<string, string>;
+    /** Client IP address */
+    ip: string;
+    /** User-Agent string */
+    userAgent: string;
+}
+/** Node.js runtime context at the time of the error. */
+interface RuntimeContext {
+    /** ISO-8601 timestamp */
+    timestamp: string;
+    /** NODE_ENV value, defaults to "development" */
+    environment: string;
+    /** process.version */
+    nodeVersion: string;
+    /** process.pid */
+    pid: number;
+    /** os.hostname() */
+    hostname: string;
+    /** process.uptime() in seconds */
+    uptimeSeconds: number;
+    /** process.cwd() */
+    workingDirectory: string;
+}
+/** Operating-system / process memory context. */
+interface SystemContext {
+    /** process.memoryUsage() */
+    memory: {
+        rss: number;
+        heapTotal: number;
+        heapUsed: number;
+        external: number;
+        arrayBuffers: number;
+    };
+    /** Heap usage as a percentage 0-100 */
+    heapUsagePercent: number;
+    /** os.loadavg() — [1m, 5m, 15m] */
+    cpuLoadAvg: [number, number, number];
+    /** os.platform() */
+    platform: string;
+    /** os.arch() */
+    arch: string;
+    /** Total system memory in bytes */
+    totalMemory: number;
+    /** Free system memory in bytes */
+    freeMemory: number;
+}
+/** Git / package metadata resolved at startup. */
+interface GitContext {
+    /** Short (8-char) commit hash, or "unknown" */
+    commitHash: string;
+    /** Current branch name, or "unknown" */
+    branch: string;
+    /** version field from the nearest package.json */
+    packageVersion: string;
+}
+/** Serialisable error context. */
+interface ErrorContext {
+    /** Error constructor name */
+    name: string;
+    /** Error message */
+    message: string;
+    /** Full stack trace */
+    stack: string | undefined;
+    /** Serialised error.cause if present */
+    cause: unknown;
+}
+/**
+ * A fully structured debugging snapshot produced whenever an unhandled error
+ * or a caught framework error occurs.
+ */
+interface Incident {
+    /** Unique ID for this incident (UUID v4) */
+    incidentId: string;
+    /** ISO-8601 timestamp — duplicated here for quick top-level access */
+    timestamp: string;
+    /** HTTP request that was in-flight when the error occurred (may be null) */
+    request: RequestContext | null;
+    /** Node.js runtime snapshot */
+    runtime: RuntimeContext;
+    /** System resource snapshot */
+    system: SystemContext;
+    /** Git / package metadata */
+    git: GitContext;
+    /** Serialised error */
+    error: ErrorContext;
+}
+/**
+ * Options accepted by `DebugContext.init()`.
+ * Everything is optional — the SDK works with zero configuration.
+ */
+interface DebugContextOptions {
+    /**
+     * Additional header names whose values should be redacted.
+     * Merged with the built-in sensitive header list.
+     */
+    sensitiveHeaders?: string[];
+    /**
+     * Additional body field names whose values should be redacted.
+     * Merged with the built-in sensitive field list.
+     */
+    sensitiveFields?: string[];
+    /**
+     * Called after each incident is captured.
+     * Use this hook to ship incidents to your own storage / alerting.
+     *
+     * @example
+     * DebugContext.init({
+     *   onIncident: (incident) => myStorage.save(incident),
+     * });
+     */
+    onIncident?: (incident: Incident) => void | Promise<void>;
+    /**
+     * When true, DebugContext attaches a global `uncaughtException` +
+     * `unhandledRejection` listener.  Defaults to `true`.
+     */
+    captureGlobalErrors?: boolean;
+}
+
+interface ToFileOptions {
+    /**
+     * Path to the output file.
+     * @default "incidents.ndjson"  (relative to process.cwd())
+     */
+    path?: string;
+    /**
+     * When `true`, creates parent directories if they don't exist.
+     * @default true
+     */
+    mkdirp?: boolean;
+}
+/**
+ * Appends an incident as a single JSON line to an NDJSON file.
+ *
+ * - Safe to call from multiple processes (append is atomic on most OSes).
+ * - Synchronous by design so it can be called inside `onIncident` without
+ *   worrying about buffering or unhandled promise rejections.
+ *
+ * @param incident - The incident to write.
+ * @param options  - Output options.
+ *
+ * @example
+ * ```ts
+ * // Write to the default path (incidents.ndjson)
+ * DebugContext.toFile(incident);
+ *
+ * // Write to a custom path
+ * DebugContext.toFile(incident, { path: 'logs/incidents.ndjson' });
+ * ```
+ */
+declare function toFile$1(incident: Incident, options?: ToFileOptions): void;
+
+/**
+ * Initialises DebugContext with optional configuration.
+ *
+ * Call once at application startup — before your Express app starts
+ * accepting requests.
+ *
+ * @example
+ * ```ts
+ * import DebugContext from '@debugcontext/core';
+ *
+ * DebugContext.init({ onIncident: (i) => console.log(i) });
+ * ```
+ */
+declare function init(userOptions?: DebugContextOptions): void;
+/**
+ * Captures an error (and an optional request context provided by a framework
+ * adapter) into a structured Incident.
+ *
+ * @param error   - The thrown value.
+ * @param request - Optional request context from a framework adapter.
+ * @returns The captured Incident.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   riskyOperation();
+ * } catch (err) {
+ *   const incident = DebugContext.capture(err);
+ *   DebugContext.toConsole(incident);
+ * }
+ * ```
+ */
+declare function capture(error: unknown, request?: RequestContext | null): Incident;
+/**
+ * Returns the most recently captured Incident as a JSON string.
+ *
+ * @param incident - Incident to serialise.  Defaults to the last captured one.
+ * @returns Pretty-printed JSON string, or `null` if no incident has been captured.
+ */
+declare function toJSON(incident?: Incident): string | null;
+/**
+ * Prints the incident to the console in a human-readable format.
+ *
+ * @param incident - Incident to print.  Defaults to the last captured one.
+ */
+declare function toConsole(incident?: Incident): void;
+/**
+ * Appends the incident to a newline-delimited JSON (NDJSON) file.
+ * Creates the file and parent directories if they don't exist.
+ *
+ * @param incident - Incident to write. Defaults to the last captured one.
+ * @param options  - `{ path?: string }` — defaults to `"incidents.ndjson"`.
+ *
+ * @example
+ * ```ts
+ * DebugContext.init({
+ *   onIncident: (i) => DebugContext.toFile(i, { path: 'logs/incidents.ndjson' }),
+ * });
+ * ```
+ */
+declare function toFile(incident?: Incident, options?: ToFileOptions): void;
+/**
+ * Returns a framework-agnostic capture function pre-bound to the current
+ * options. Useful when building custom adapters.
+ *
+ * For Express, use `@debugcontext/express` instead.
+ *
+ * @example
+ * ```ts
+ * // In a custom adapter:
+ * const mw = DebugContext.middleware();
+ * app.use((err, req, res, next) => {
+ *   const requestCtx = buildRequestCtx(req);
+ *   mw(err, requestCtx);
+ *   next(err);
+ * });
+ * ```
+ */
+declare function middleware(): (error: unknown, request?: RequestContext | null) => Incident;
+/**
+ * Returns the current SDK options (useful for adapters).
+ * @internal
+ */
+declare function getOptions(): Required<DebugContextOptions>;
+/**
+ * The DebugContext SDK.
+ *
+ * @example
+ * ```ts
+ * import DebugContext from '@debugcontext/core';
+ *
+ * DebugContext.init();
+ * ```
+ */
+declare const DebugContext: {
+    readonly init: typeof init;
+    readonly capture: typeof capture;
+    readonly toJSON: typeof toJSON;
+    readonly toConsole: typeof toConsole;
+    readonly toFile: typeof toFile;
+    readonly middleware: typeof middleware;
+    /** @internal used by framework adapters */
+    readonly getOptions: typeof getOptions;
+};
+
+/**
+ * @module collectors/error
+ * Serialises a thrown value into a structured ErrorContext.
+ */
+
+/**
+ * Converts any thrown value into a structured, serialisable ErrorContext.
+ *
+ * Handles:
+ * - Standard `Error` instances (including subclasses).
+ * - Errors with a `.cause` (ES2022 error chaining).
+ * - Non-Error throws (strings, objects, etc.).
+ */
+declare function collectError(thrown: unknown): ErrorContext;
+
+/**
+ * Returns the Git context.  Resolution runs once and is then cached for the
+ * lifetime of the process.
+ */
+declare function collectGit(): GitContext;
+
+/**
+ * Captures a snapshot of the current Node.js runtime environment.
+ */
+declare function collectRuntime(): RuntimeContext;
+
+/**
+ * Captures a snapshot of current system resource usage.
+ */
+declare function collectSystem(): SystemContext;
+
+/**
+ * @module redact
+ * Utilities for scrubbing sensitive data from headers and request bodies
+ * before they are included in an Incident.
+ */
+/** Header names that are always redacted (case-insensitive comparison). */
+declare const DEFAULT_SENSITIVE_HEADERS: readonly string[];
+/** Body / object field names that are always redacted (case-insensitive). */
+declare const DEFAULT_SENSITIVE_FIELDS: readonly string[];
+/**
+ * Returns a copy of `headers` where sensitive values are replaced with
+ * `"[REDACTED]"`.
+ *
+ * @param headers       - Raw header map (values may be string or string[]).
+ * @param extraFields   - Caller-supplied additional header names to redact.
+ */
+declare function redactHeaders(headers: Record<string, string | string[] | undefined>, extraFields?: string[]): Record<string, string>;
+/**
+ * Deeply walks `body` (plain objects / arrays) and replaces the *values* of
+ * sensitive keys with `"[REDACTED]"`.  Non-plain-object values are returned
+ * as-is (e.g. strings, numbers, Buffers).
+ *
+ * @param body        - The request body to sanitise.
+ * @param extraFields - Caller-supplied additional field names to redact.
+ */
+declare function redactBody(body: unknown, extraFields?: string[]): unknown;
+
+export { DEFAULT_SENSITIVE_FIELDS, DEFAULT_SENSITIVE_HEADERS, type DebugContextOptions, type ErrorContext, type GitContext, type Incident, type RequestContext, type RuntimeContext, type SystemContext, type ToFileOptions, capture, collectError, collectGit, collectRuntime, collectSystem, DebugContext as default, getOptions, init, middleware, redactBody, redactHeaders, toConsole, toFile, toJSON, toFile$1 as writeIncidentToFile };