@flareapp/node 0.7.0 → 0.9.0

package/dist/index.d.cts

@@ -32,22 +32,15 @@ declare class NodeScope extends Scope$1 {
  * Node.js-specific `Flare` singleton, exposed from `@flareapp/node` as `flare`.
  *
  * Subclasses core's `Flare` and wires the Node-only seams in its constructor:
- *
- * - `AsyncLocalStorageScopeProvider` so each `runWithContext(...)` callback
- *   gets its own `NodeScope` (glows, attributes, entry-point, request),
+ * - `AsyncLocalStorageScopeProvider` so each `runWithContext(...)` callback gets its own `NodeScope`,
  *   isolated from concurrent requests.
- * - `makeNodeContextCollector(...)` to project the current `NodeScope` and
- *   process info into report attributes (http.request.*, url.path, etc).
- * - `DiskFileReader` to read source files for stack-trace snippets via
- *   `node:fs/promises` instead of the browser's `fetch`.
- * - `ProcessHandlerManager` to attach/detach `uncaughtException` and
- *   `unhandledRejection` listeners based on the current `NodeOptions`.
+ * - `makeNodeContextCollector(...)` turns the current `NodeScope` + process info into report attributes.
+ * - `DiskFileReader` reads source for stack-trace snippets via `node:fs/promises`, not `fetch`.
+ * - `ProcessHandlerManager` attaches/detaches the fatal process listeners per `NodeOptions`.
  *
- * Also adds Node-only API surface on top of core: `configureNode(...)`,
- * `runWithContext(...)`, `mergeContext(...)`, `getContext()`,
- * `removeProcessListeners()`. Inherited core methods (`light`, `configure`,
- * `addContext`, `glow`, etc.) return `this`, so chaining keeps the
- * `NodeFlare` type and `configureNode(...)` stays callable mid-chain.
+ * Adds Node-only API on top of core: `configureNode`, `runWithContext`, `mergeContext`, `getContext`,
+ * `removeProcessListeners`. Inherited core methods return `this`, so chaining keeps the `NodeFlare`
+ * type and `configureNode(...)` stays callable mid-chain.
  */
 declare class NodeFlare extends Flare$1 {
   private nodeOptions;
@@ -55,66 +48,27 @@ declare class NodeFlare extends Flare$1 {
   private nodeScopeProvider;
   private handlerManager;
   constructor();
-  /**
-   * Set the API key (and optional debug flag), then reconcile process
-   * listeners with the current `nodeOptions`. Reconcile runs on EVERY call,
-   * not just the first, so `light()` is the right escape hatch to re-attach
-   * after `removeProcessListeners()`.
-   */
+  /** Reconcile runs on every call, so `light()` re-attaches after `removeProcessListeners()`. */
   light(key?: string, debug?: boolean): this;
   /**
-   * Merge Node-only options (fatal-handler modes, header/body redaction
-   * config, shutdown timeout) into the active configuration. Safe to call
-   * before or after `light()`:
-   *
-   * - Before `light()`: options are stored; listeners are attached when
-   *   `light()` runs.
-   * - After `light()`: options are stored AND listeners are reconciled
-   *   immediately, so flipping a mode to `'off'` detaches the handler and
-   *   flipping it back to `'report'`/`'report-and-exit'` re-attaches.
-   *
-   * Regex options (`headerAllowlist`, `bodyAllowedContentTypes`,
-   * `bodyKeyDenylist`) are passed through `sanitizeRegex` to strip stateful
-   * `g`/`y` flags; without that, `RegExp.prototype.test` would skip matches
-   * across keys.
+   * Safe before or after `light()`. Before, the listeners attach on `light()`; after, they reconcile
+   * immediately, so flipping a mode to `'off'` detaches and flipping it back re-attaches.
    */
   configureNode(partial: Partial<NodeOptions>): NodeFlare;
   /**
-   * Run `fn` inside a fresh `NodeScope` carrying the supplied request
-   * metadata. Inside `fn` (and any async work it awaits), `flare.glow(...)`,
-   * `flare.addContext(...)`, `flare.setUser(...)`, and `flare.report(...)`
-   * see a scope that is isolated from other concurrent requests.
-   *
-   * Mirrors a typical web-framework middleware: call once per request,
-   * wrapping the request handler, and the SDK will attribute any error
-   * reported inside the chain to the right request.
+   * Use as web-framework middleware, once per request around the handler. Inside `fn` and any async
+   * work it awaits, reports are attributed to that request rather than to a concurrent one.
    */
   runWithContext<T>(request: RequestContext, fn: () => T): T;
   /**
-   * Patch the request metadata on the active scope after `runWithContext(...)`
-   * has already started. Useful when fields become known partway through a
-   * request (e.g., the resolved absolute URL after proxy headers are parsed).
-   *
-   * Outside any `runWithContext(...)` callback, this writes to the fallback
-   * scope; the patch is visible to subsequent reports issued from outside a
-   * request scope but is NOT inherited by future `runWithContext(...)` calls.
+   * For fields that only become known partway through a request, such as the absolute URL once proxy
+   * headers are parsed. Outside `runWithContext(...)` this writes to the fallback scope, which future
+   * `runWithContext(...)` calls do not inherit.
    */
   mergeContext(partial: Partial<RequestContext>): void;
-  /**
-   * Returns the request scope when called inside `runWithContext(...)`, or
-   * `null` outside. Intentionally returns `null` (not the fallback scope)
-   * when no request is active, so callers can distinguish "we are inside a
-   * request" from "we are not". Primarily useful for debugging.
-   */
+  /** Null (not the fallback scope) outside a request, so callers can tell the two apart. Debugging aid. */
   getContext(): NodeScope | null;
-  /**
-   * Detach the `uncaughtException` and `unhandledRejection` listeners
-   * without changing `nodeOptions`. Intended for tests and for graceful
-   * shutdown paths where you want to take ownership of process exit
-   * yourself.
-   *
-   * Calling `light()` afterwards re-attaches based on the current options.
-   */
+  /** Leaves `nodeOptions` alone, so a later `light()` re-attaches. For tests and graceful shutdown. */
   removeProcessListeners(): void;
 }
 //#endregion

package/dist/index.d.mts

@@ -32,22 +32,15 @@ declare class NodeScope extends Scope$1 {
  * Node.js-specific `Flare` singleton, exposed from `@flareapp/node` as `flare`.
  *
  * Subclasses core's `Flare` and wires the Node-only seams in its constructor:
- *
- * - `AsyncLocalStorageScopeProvider` so each `runWithContext(...)` callback
- *   gets its own `NodeScope` (glows, attributes, entry-point, request),
+ * - `AsyncLocalStorageScopeProvider` so each `runWithContext(...)` callback gets its own `NodeScope`,
  *   isolated from concurrent requests.
- * - `makeNodeContextCollector(...)` to project the current `NodeScope` and
- *   process info into report attributes (http.request.*, url.path, etc).
- * - `DiskFileReader` to read source files for stack-trace snippets via
- *   `node:fs/promises` instead of the browser's `fetch`.
- * - `ProcessHandlerManager` to attach/detach `uncaughtException` and
- *   `unhandledRejection` listeners based on the current `NodeOptions`.
+ * - `makeNodeContextCollector(...)` turns the current `NodeScope` + process info into report attributes.
+ * - `DiskFileReader` reads source for stack-trace snippets via `node:fs/promises`, not `fetch`.
+ * - `ProcessHandlerManager` attaches/detaches the fatal process listeners per `NodeOptions`.
  *
- * Also adds Node-only API surface on top of core: `configureNode(...)`,
- * `runWithContext(...)`, `mergeContext(...)`, `getContext()`,
- * `removeProcessListeners()`. Inherited core methods (`light`, `configure`,
- * `addContext`, `glow`, etc.) return `this`, so chaining keeps the
- * `NodeFlare` type and `configureNode(...)` stays callable mid-chain.
+ * Adds Node-only API on top of core: `configureNode`, `runWithContext`, `mergeContext`, `getContext`,
+ * `removeProcessListeners`. Inherited core methods return `this`, so chaining keeps the `NodeFlare`
+ * type and `configureNode(...)` stays callable mid-chain.
  */
 declare class NodeFlare extends Flare$1 {
   private nodeOptions;
@@ -55,66 +48,27 @@ declare class NodeFlare extends Flare$1 {
   private nodeScopeProvider;
   private handlerManager;
   constructor();
-  /**
-   * Set the API key (and optional debug flag), then reconcile process
-   * listeners with the current `nodeOptions`. Reconcile runs on EVERY call,
-   * not just the first, so `light()` is the right escape hatch to re-attach
-   * after `removeProcessListeners()`.
-   */
+  /** Reconcile runs on every call, so `light()` re-attaches after `removeProcessListeners()`. */
   light(key?: string, debug?: boolean): this;
   /**
-   * Merge Node-only options (fatal-handler modes, header/body redaction
-   * config, shutdown timeout) into the active configuration. Safe to call
-   * before or after `light()`:
-   *
-   * - Before `light()`: options are stored; listeners are attached when
-   *   `light()` runs.
-   * - After `light()`: options are stored AND listeners are reconciled
-   *   immediately, so flipping a mode to `'off'` detaches the handler and
-   *   flipping it back to `'report'`/`'report-and-exit'` re-attaches.
-   *
-   * Regex options (`headerAllowlist`, `bodyAllowedContentTypes`,
-   * `bodyKeyDenylist`) are passed through `sanitizeRegex` to strip stateful
-   * `g`/`y` flags; without that, `RegExp.prototype.test` would skip matches
-   * across keys.
+   * Safe before or after `light()`. Before, the listeners attach on `light()`; after, they reconcile
+   * immediately, so flipping a mode to `'off'` detaches and flipping it back re-attaches.
    */
   configureNode(partial: Partial<NodeOptions>): NodeFlare;
   /**
-   * Run `fn` inside a fresh `NodeScope` carrying the supplied request
-   * metadata. Inside `fn` (and any async work it awaits), `flare.glow(...)`,
-   * `flare.addContext(...)`, `flare.setUser(...)`, and `flare.report(...)`
-   * see a scope that is isolated from other concurrent requests.
-   *
-   * Mirrors a typical web-framework middleware: call once per request,
-   * wrapping the request handler, and the SDK will attribute any error
-   * reported inside the chain to the right request.
+   * Use as web-framework middleware, once per request around the handler. Inside `fn` and any async
+   * work it awaits, reports are attributed to that request rather than to a concurrent one.
    */
   runWithContext<T>(request: RequestContext, fn: () => T): T;
   /**
-   * Patch the request metadata on the active scope after `runWithContext(...)`
-   * has already started. Useful when fields become known partway through a
-   * request (e.g., the resolved absolute URL after proxy headers are parsed).
-   *
-   * Outside any `runWithContext(...)` callback, this writes to the fallback
-   * scope; the patch is visible to subsequent reports issued from outside a
-   * request scope but is NOT inherited by future `runWithContext(...)` calls.
+   * For fields that only become known partway through a request, such as the absolute URL once proxy
+   * headers are parsed. Outside `runWithContext(...)` this writes to the fallback scope, which future
+   * `runWithContext(...)` calls do not inherit.
    */
   mergeContext(partial: Partial<RequestContext>): void;
-  /**
-   * Returns the request scope when called inside `runWithContext(...)`, or
-   * `null` outside. Intentionally returns `null` (not the fallback scope)
-   * when no request is active, so callers can distinguish "we are inside a
-   * request" from "we are not". Primarily useful for debugging.
-   */
+  /** Null (not the fallback scope) outside a request, so callers can tell the two apart. Debugging aid. */
   getContext(): NodeScope | null;
-  /**
-   * Detach the `uncaughtException` and `unhandledRejection` listeners
-   * without changing `nodeOptions`. Intended for tests and for graceful
-   * shutdown paths where you want to take ownership of process exit
-   * yourself.
-   *
-   * Calling `light()` afterwards re-attaches based on the current options.
-   */
+  /** Leaves `nodeOptions` alone, so a later `light()` re-attaches. For tests and graceful shutdown. */
   removeProcessListeners(): void;
 }
 //#endregion