@forge-ops/tracker 0.1.0 → 0.1.1

package/README.md

@@ -1,9 +1,9 @@
 # @forge-ops/tracker
 
 Node.js error reporting client for a private, self-hosted [ForgeOps](../../) tracker instance.
-Requires Node 18+ (for global `fetch`). A from-scratch port of
-[`gems/forge_ops_tracker`](../../gems/forge_ops_tracker) (the Rails client) -- see that gem's
-README for the shared design rationale; this document only covers what's Node-specific.
+Requires Node 18+ (for global `fetch`). It captures uncaught exceptions, unhandled promise
+rejections, and explicitly reported errors, builds a backtrace, scrubs likely PII, and delivers
+events to ForgeOps over HTTP without blocking the request or process that raised them.
 
 ## Installation
 
@@ -76,8 +76,8 @@ try {
 }
 ```
 
-There's no Express/Fastify-wide equivalent to Rails' `Rails.error.handle` here -- report it
-explicitly instead, right at the catch site:
+There's no application-wide hook that reports an exception while still letting your own catch
+block handle it -- report it explicitly instead, right at the catch site:
 
 ```js
 } catch (err) {
@@ -108,35 +108,33 @@ dropped rather than thrown, so a broken or unreachable tracker can never take do
 
 ## Delivery: an async loop, not a thread
 
-`DeliveryQueue` here isn't a background *thread* the way the Ruby/.NET/Python clients' equivalent
-class is -- Node is single-threaded. But (unlike PHP-FPM) a Node process is long-running across many
-requests, so an async processing loop on the event loop is the natural substitute: `push()` returns
-immediately, and delivery happens via non-blocking `fetch()` calls without ever blocking the
-request that pushed it. The loop starts lazily, on first push, not at import time -- Node's
-`cluster` module can fork worker processes *after* the application has already loaded, the same
-hazard Puma/Gunicorn have for the Ruby/Python clients; starting fresh on first push means each
-forked worker gets its own live loop regardless of when it was forked relative to import.
+`DeliveryQueue` here isn't a background *thread* -- Node is single-threaded. But a Node process is
+long-running across many requests, so an async processing loop on the event loop is the natural
+substitute: `push()` returns immediately, and delivery happens via non-blocking `fetch()` calls
+without ever blocking the request that pushed it. The loop starts lazily, on first push, not at
+import time -- Node's `cluster` module can fork worker processes *after* the application has
+already loaded, and an eagerly-started loop would be left dead in every forked child; starting
+fresh on first push means each forked worker gets its own live loop regardless of when it was
+forked relative to import.
 
 ## `in_app` backtrace frames
 
-Like the Ruby gem (and unlike the .NET SDK, where a compiled assembly's file path never matches its
-original source location), Node runs interpreted directly from real `.js` files on disk, so
-file-path matching against `Configuration#appRoot` works the same way it does in the Ruby gem's
-`Rails.root` comparison. Defaults to the current working directory; set it explicitly if that
-doesn't match your app's actual layout. `node_modules` frames are never marked `in_app`, regardless
-of `appRoot`; Node's own internal modules (the `node:` scheme) never match a real `appRoot` prefix
-either, so they don't need special-casing.
-
-Backtrace parsing is a regex over `Error#stack` (a plain string in V8, unlike Python's structured
-`traceback` module or PHP's `Throwable::getTrace()`) -- verified directly against real captured
-stack traces, both synchronous and `async`, named and anonymous frames, before relying on it. A
-related quirk, shared with PHP but not Ruby/.NET/Python: V8 captures an Error's stack at
-*construction* time, not at `throw` time, so there's no "empty backtrace" case for an exception
-that's constructed but never thrown.
+Node runs interpreted directly from real `.js` files on disk, so file-path matching against
+`Configuration#appRoot` is a straightforward prefix comparison against those on-disk paths.
+Defaults to the current working directory; set it explicitly if that doesn't match your app's
+actual layout. `node_modules` frames are never marked `in_app`, regardless of `appRoot`; Node's own
+internal modules (the `node:` scheme) never match a real `appRoot` prefix either, so they don't
+need special-casing.
+
+Backtrace parsing is a regex over `Error#stack`, a plain string in V8 rather than a structured
+object -- verified directly against real captured stack traces, both synchronous and `async`,
+named and anonymous frames, before relying on it. One quirk worth knowing: V8 captures an Error's
+stack at *construction* time, not at `throw` time, so there's no "empty backtrace" case for an
+exception that's constructed but never thrown.
 
 ## PII scrubbing
 
-Same behavior as the Ruby gem: the message, backtrace, and any context/tags you attach are scanned
+By default, the message, backtrace, and any context/tags you attach are scanned
 for likely personal data -- email addresses, formatted SSNs/credit cards, known API key/token
 formats, and anything under a suspiciously-named key (`password`, `apiKey`, `ssn`, and similar) --
 and redacted before the payload ever leaves this process. ForgeOps itself scrubs again on arrival

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forge-ops/tracker",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "ForgeOps error tracking client: captures unhandled exceptions (Express/Fastify integration, plus explicit capture anywhere else) and delivers them to a ForgeOps instance over HTTP.",
   "type": "module",
   "main": "src/index.js",
@@ -31,8 +31,12 @@
     "fastify": ">=4"
   },
   "peerDependenciesMeta": {
-    "express": { "optional": true },
-    "fastify": { "optional": true }
+    "express": {
+      "optional": true
+    },
+    "fastify": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@eslint/js": "^10.0.0",