@rasputin-ai/elysia 0.5.0-alpha.13 → 0.5.0-alpha.14

package/README.md

@@ -81,7 +81,11 @@ The Elysia plugin scopes each HTTP request as an execution automatically. For ba
 
 ## Automatic instrumentation
 
-Build-time instrumentation is the production default. Transform compiled unbundled JavaScript after `tsc` so the running process never loads the TypeScript compiler:
+Rasputin wraps your functions so it can show what ran when an error happened.
+
+**Compiled JavaScript (use this in production)**
+
+Build as you already do, then run `rasputin-instrument` on the output. Start the process normally — no extra flags:
 
 ```json
 {
@@ -93,29 +97,56 @@ Build-time instrumentation is the production default. Transform compiled unbundl
 }
 ```
 
-Node `--import` and Bun `--preload` remain compatibility and development fallbacks. They transform application source as it loads, which pulls compiler infrastructure into the process and has materially higher RSS. Do not use those loader measurements in low-overhead comparisons. In `NODE_ENV=production` the loaders print a one-time warning recommending `rasputin-instrument`. Set `RASPUTIN_SUPPRESS_RUNTIME_TRANSFORM_WARNING=1` to hide it.
+Have TypeScript write `.js.map` files next to the output so recorded functions still point at your `.ts` sources. The instrumenter writes `.rasputin/instrumentation-manifest.json` beside `dist`, and `RasputinInit` loads it automatically.
+
+**Running TypeScript directly**
+
+`rasputin-instrument` rewrites compiled `.js` files on disk. It does not run when you start TypeScript with Bun (`bun src/app.ts`, `bun run src/app.ts`, and similar). Use `--preload` so Bun wraps files as they load:
 
 ```json
 {
   "scripts": {
-    "start:node": "node --import @rasputin-ai/elysia/instrument/node dist/app.js",
     "start:bun": "bun --preload @rasputin-ai/elysia/instrument/bun src/app.ts"
   }
 }
 ```
 
-Runtime state is retained only inside an active execution and attached when that execution throws.
+On Node you can wrap compiled files as they load instead of instrumenting at build time:
+
+```json
+{
+  "scripts": {
+    "start:node": "node --import @rasputin-ai/elysia/instrument/node dist/app.js"
+  }
+}
+```
+
+Use `--preload` / `--import` while you run TypeScript locally. In production, instrument at build time instead — wrapping files at startup is slower and uses more memory.
+
+Runtime state is kept only while a request or job is running, and is attached when that work throws.
 
 ## Manual capture
 
 For background jobs, scheduled tasks, or worker iterations, define an execution:
 
 ```ts
-await client.execution.run({ kind: 'job', name: 'sync-invoices' }, async () => {
-  await syncInvoices();
-});
+const scope = client.execution.createScope({
+  kind: 'job',
+  name: 'sync-invoices',
+})
+
+try {
+  return await scope.run(() => syncInvoices())
+} catch (error) {
+  scope.associateError(error)
+  throw error
+} finally {
+  scope.finish()
+}
 ```
 
+`scope.run()` executes the callback under this recording's async context and returns exactly what the callback returned. It does not wrap, replace, or observe Promises.
+
 When automatic instrumentation is unavailable, mark individual functions explicitly:
 
 ```ts
@@ -131,14 +162,16 @@ const syncInvoices = client.execution.trace(
 
 | Environment | Support |
 | --- | --- |
-| TypeScript compiled to multiple JavaScript files | Preferred: `rasputin-instrument dist` after `tsc`, with adjacent source maps |
-| Elysia 1.4 or newer within 1.x on Bun 1.3.x | Supported for directly loaded JavaScript and TypeScript using `instrument/bun` as a compatibility fallback |
-| Elysia 1.4 or newer within 1.x on Node.js 22.15 or newer | Supported for unbundled ESM/CJS JavaScript using `instrument/node` as a compatibility fallback; Node 22 and 24 are the supported LTS lines |
-| Single-file bundles (esbuild, tsup, webpack, Vite SSR, Next.js) | Automatic instrumentation not supported |
-| `tsx`, custom Node loader stacks, and Node's native TypeScript execution | Automatic instrumentation not supported |
+| TypeScript compiled to multiple JavaScript files | Use `rasputin-instrument dist` after `tsc`, with adjacent source maps |
+| Elysia 1.4+ on Bun 1.3.x, running `.ts` or `.js` files directly | Use `--preload @rasputin-ai/elysia/instrument/bun` |
+| Elysia 1.4+ on Node.js 22.15 or newer, unbundled ESM/CJS | Use `rasputin-instrument`, or `--import @rasputin-ai/elysia/instrument/node`; Node 22 and 24 are the supported LTS lines |
+
+On Node.js 22, start the process with `--experimental-async-context-frame` (or set `NODE_OPTIONS`) so `AsyncLocalStorage` uses the faster implementation that Node.js 24 enables by default. Rasputin logs this once when the flag is missing; set `RASPUTIN_SUPPRESS_ASYNC_CONTEXT_FRAME_WARNING=1` to hide it.
+| Single-file bundles (esbuild, tsup, webpack, Vite SSR, Next.js) | Automatic instrumentation is not supported |
+| `tsx`, custom Node loader stacks, and Node's native TypeScript execution | Automatic instrumentation is not supported |
 | Deno and edge runtimes | Not supported |
 
-Tested on Bun 1.3.13, Node.js 24.19.0, and Elysia 1.4.28. Node.js 22.15.0 is the minimum for automatic instrumentation (synchronous module hooks). Use `execution.run()` and `execution.trace()` when automatic instrumentation is not available.
+Tested on Bun 1.3.13, Node.js 24.19.0, and Elysia 1.4.28. Node.js 22.15.0 is the minimum for automatic instrumentation. Use `execution.createScope()` and `execution.trace()` when automatic instrumentation is not available.
 
 ## Recorder configuration
 
@@ -155,7 +188,9 @@ Defaults work for most apps. Customize to exclude noisy sources, redact fields,
 | `maxArrayElements` | `20` | Maximum items retained from one array, map, or set |
 | `maxStringLength` | `500` | Maximum characters retained from one string |
 | `maxSerializedValueBytes` | `8 KiB` | Maximum retained size of one captured value |
-| `redactKeys` | `[]` | Additional case-insensitive property names to redact |
+| `runtimeStateTargetBytes` | `256 KiB` | Soft size goal for the snapshot sent with an error; extra reconstruction data is dropped first |
+| `maxRuntimeStateBytes` | `512 KiB` | Hard size limit for that snapshot; values are dropped before call history |
+| `redactKeys` | `[]` | Additional property names to redact (case- and separator-insensitive) |
 | `excludeSources` | `[]` | Source globs or function-name patterns to exclude |
 
 ```ts
@@ -177,4 +212,4 @@ Runtime state can include application data. Use `redactKeys` for sensitive field
 const { recorder, transport } = client.getStats();
 ```
 
-Counters are local to the current process and reset on restart.
+These counters describe what this process has recorded and sent since it started. They reset on restart. Compare two snapshots if you want activity over a window, rather than dividing lifetime totals by one request.

package/dist/index.js

@@ -8,41 +8,58 @@ import {
   installAutomaticExecutionRuntime,
   installGlobalHandlers,
   scheduleInstrumentationManifestUpload
-} from "@rasputin-ai/node";
+} from "@rasputin-ai/node/internal";
 import { Elysia } from "elysia";
 
 // src/sdk-meta.ts
 var SDK_NAME = "@rasputin-ai/elysia";
-var SDK_VERSION = "0.5.0-alpha.13";
+var SDK_VERSION = "0.5.0-alpha.14";
 
 // src/rasputin-init.ts
-var withExecution = (client, execution, installRuntime, manifest) => {
-  const uninstallRuntime = installRuntime ? installAutomaticExecutionRuntime(execution) : () => {
+var publicExecution = (runtime) => ({
+  createScope: (metadata) => {
+    const scope = runtime.createScope(metadata);
+    return {
+      run: scope.run,
+      associateError: scope.associateError,
+      finish: scope.finish
+    };
+  },
+  trace: runtime.trace,
+  getStats: runtime.getStats
+});
+var withExecution = (client, runtime, installRuntime, manifest, uninstallHandlers = () => {
+}) => {
+  const uninstallRuntime = installRuntime ? installAutomaticExecutionRuntime(runtime) : () => {
   };
   const manifestUpload = scheduleInstrumentationManifestUpload(manifest);
+  const execution = publicExecution(runtime);
   return {
     ...client,
     execution,
     getStats: () => ({ ...client.getStats(), recorder: execution.getStats() }),
     verifyConfiguration: manifestUpload.verify,
     captureException: (error, context) => {
-      const runtimeState = context?.runtimeState ?? execution.getErrorState(
-        error,
-        context?.request ? { kind: "http", request: context.request } : void 0
-      );
-      const result = client.captureException(error, { ...context, runtimeState });
+      const result = client.captureException(error, context);
       manifestUpload.flushSoon();
       return result;
     },
     flush: async (timeoutMs) => {
+      const startedAt = Date.now();
       await client.flush(timeoutMs);
-      await manifestUpload.wait();
+      if (timeoutMs === void 0) {
+        await manifestUpload.wait();
+        return;
+      }
+      await manifestUpload.wait(Math.max(0, timeoutMs - (Date.now() - startedAt)));
     },
     close: async () => {
+      uninstallHandlers();
       uninstallRuntime();
       manifestUpload.disconnect();
+      const startedAt = Date.now();
       await client.close();
-      await manifestUpload.wait();
+      await manifestUpload.wait(Math.max(0, 2e3 - (Date.now() - startedAt)));
     }
   };
 };
@@ -54,8 +71,12 @@ var toStatus = (status) => {
   }
   return void 0;
 };
-var isPromiseLike = (value) => {
-  return Boolean(value) && typeof value.then === "function";
+var isNativeResponsePromise = (value) => {
+  try {
+    return Object.prototype.toString.call(value) === "[object Promise]";
+  } catch {
+    return false;
+  }
 };
 var finishExecution = (scope, metadata) => {
   try {
@@ -65,7 +86,7 @@ var finishExecution = (scope, metadata) => {
 };
 var rememberExecutionError = (scope, error) => {
   try {
-    scope.getErrorState(error);
+    scope.associateError(error);
   } catch {
   }
 };
@@ -78,18 +99,18 @@ var buildPlugin = (client, execution, recorderEnabled) => {
     return (request) => scope.run(() => {
       try {
         const response = handler(request);
-        if (isPromiseLike(response)) {
-          return Promise.resolve(response).then(
+        if (isNativeResponsePromise(response)) {
+          Promise.prototype.then.call(
+            response,
             (value) => {
               finishExecution(scope, { request: { status: value.status } });
-              return value;
             },
             (error) => {
               rememberExecutionError(scope, error);
               finishExecution(scope);
-              throw error;
             }
           );
+          return response;
         }
         finishExecution(scope, { request: { status: response.status } });
         return response;
@@ -109,11 +130,7 @@ var buildPlugin = (client, execution, recorderEnabled) => {
       status: toStatus(set.status)
     };
     try {
-      const runtimeState = execution.getErrorState(error, {
-        kind: "http",
-        request: requestContext
-      });
-      client.captureException(error, { request: requestContext, runtimeState });
+      client.captureException(error, { request: requestContext });
     } catch {
     }
     return;
@@ -122,45 +139,58 @@ var buildPlugin = (client, execution, recorderEnabled) => {
 function RasputinInit(options, hooks = {}) {
   try {
     const {
-      installGlobalHandlers: installProcessHandlers = true,
+      installGlobalHandlers: installProcessHandlers = options.installGlobalHandlers !== false,
       fetch,
       announceDeploy,
-      installTransportSignalHandlers
+      installTransportSignalHandlers = options.installTransportSignalHandlers
     } = hooks;
+    const enabled = isClientEnabled(options);
+    const recorderEnabled = enabled && options.executionRecorder?.enabled !== false;
+    const runtime = createExecutionRecorder({
+      ...options.executionRecorder,
+      enabled: recorderEnabled
+    });
     const client = createClient(options, {
       fetch,
       announceDeploy,
       installTransportSignalHandlers,
       sdkVersion: SDK_VERSION,
-      sdkName: SDK_NAME
-    });
-    const recorderEnabled = isClientEnabled(options) && options.executionRecorder?.enabled !== false;
-    const execution = createExecutionRecorder({
-      ...options.executionRecorder,
-      enabled: recorderEnabled
-    });
-    const wrappedClient = withExecution(client, execution, recorderEnabled, {
-      projectApiKey: options.projectApiKey,
-      release: options.release,
-      apiUrl: options.apiUrl,
-      fetch,
-      enabled: isClientEnabled(options),
-      sourceRoot: options.sourceRoot,
-      sourceRoots: options.sourceRoots,
-      logSuccess: options.logSuccess
+      sdkName: SDK_NAME,
+      resolveRuntimeState: (error, context) => runtime.getErrorState(
+        error,
+        context?.request ? { kind: "http", request: context.request } : void 0
+      )
     });
-    if (isClientEnabled(options) && installProcessHandlers) {
-      installGlobalHandlers(wrappedClient);
+    let uninstallHandlers = () => {
+    };
+    const wrappedClient = withExecution(
+      client,
+      runtime,
+      recorderEnabled,
+      {
+        projectApiKey: options.projectApiKey ?? "",
+        release: options.release,
+        apiUrl: options.apiUrl,
+        fetch,
+        enabled,
+        sourceRoot: options.sourceRoot,
+        sourceRoots: options.sourceRoots,
+        logSuccess: options.logSuccess
+      },
+      () => uninstallHandlers()
+    );
+    if (enabled && installProcessHandlers) {
+      uninstallHandlers = installGlobalHandlers(wrappedClient);
     }
     return {
       client: wrappedClient,
-      plugin: buildPlugin(wrappedClient, execution, recorderEnabled)
+      plugin: buildPlugin(wrappedClient, runtime, recorderEnabled)
     };
   } catch {
     const client = createClient({ ...options, enabled: false });
-    const execution = createExecutionRecorder({ enabled: false });
-    const wrappedClient = withExecution(client, execution, false, {
-      projectApiKey: options.projectApiKey,
+    const runtime = createExecutionRecorder({ enabled: false });
+    const wrappedClient = withExecution(client, runtime, false, {
+      projectApiKey: options.projectApiKey ?? "",
       release: options.release,
       apiUrl: options.apiUrl,
       enabled: false,
@@ -168,7 +198,7 @@ function RasputinInit(options, hooks = {}) {
       sourceRoots: options.sourceRoots,
       logSuccess: options.logSuccess
     });
-    return { client: wrappedClient, plugin: buildPlugin(wrappedClient, execution, false) };
+    return { client: wrappedClient, plugin: buildPlugin(wrappedClient, runtime, false) };
   }
 }
 export {

package/dist/rasputin-init.d.ts

@@ -5,18 +5,36 @@
  * the framework-neutral Node recorder.
  */
 import { type RasputinOptions } from '@rasputin-ai/core';
-import { type ExecutionRecorderOptions, type RasputinExecution, type RasputinNodeClient } from '@rasputin-ai/node';
+import type { ExecutionRecorderOptions, RasputinExecution, RasputinNodeClient } from '@rasputin-ai/node';
 import { Elysia } from 'elysia';
+/** Elysia plugin returned by `RasputinInit`. Register it with `.use(plugin)`. */
 export type RasputinElysiaPlugin = ReturnType<typeof buildPlugin>;
 export type RasputinElysia = {
+    /** Use this for `captureException`, `flush`, and wrapping background jobs. */
     client: RasputinNodeClient;
+    /** Register early with `.use(plugin)` so each HTTP request is recorded. */
     plugin: RasputinElysiaPlugin;
 };
 export type RasputinElysiaOptions = RasputinOptions & {
-    /** Bounded runtime-state capture. Enabled by default; successful executions are discarded. */
+    /**
+     * Limits and redaction for the runtime recorder. Recording is on unless you
+     * set `enabled: false`. Successful requests and jobs are not kept.
+     */
     executionRecorder?: ExecutionRecorderOptions;
+    /**
+     * Observe `uncaughtException` / nonfatal `unhandledRejection`. Default true.
+     * Rasputin does not become the host crash/recovery owner: it exits only when
+     * it is the sole `uncaughtException` listener. Set false when the host owns
+     * process diagnostics.
+     */
+    installGlobalHandlers?: boolean;
+    /**
+     * Install SIGINT / SIGTERM / beforeExit flush hooks. Default true.
+     * Set false when the host owns process shutdown.
+     */
+    installTransportSignalHandlers?: boolean;
 };
-declare const buildPlugin: (client: RasputinNodeClient, execution: RasputinExecution, recorderEnabled: boolean) => Elysia<"", {
+declare const buildPlugin: (client: RasputinNodeClient, execution: Pick<RasputinExecution, "createScope">, recorderEnabled: boolean) => Elysia<"", {
     decorator: {
         rasputin: RasputinNodeClient;
     };

package/dist/rasputin-init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rasputin-init.d.ts","sourceRoot":"","sources":["../src/rasputin-init.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAKN,KAAK,eAAe,EACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAEN,KAAK,wBAAwB,EAI7B,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EAEvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAIhC,MAAM,MAAM,oBAAoB,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;AAElE,MAAM,MAAM,cAAc,GAAG;IAC5B,MAAM,EAAE,kBAAkB,CAAC;IAC3B,MAAM,EAAE,oBAAoB,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG,eAAe,GAAG;IACrD,8FAA8F;IAC9F,iBAAiB,CAAC,EAAE,wBAAwB,CAAC;CAC7C,CAAC;AA4FF,QAAA,MAAM,WAAW,GAChB,QAAQ,kBAAkB,EAC1B,WAAW,iBAAiB,EAC5B,iBAAiB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0DxB,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,qBAAqB,GAAG,cAAc,CAAC"}
+{"version":3,"file":"rasputin-init.d.ts","sourceRoot":"","sources":["../src/rasputin-init.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAKN,KAAK,eAAe,EACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EACX,wBAAwB,EAExB,iBAAiB,EACjB,kBAAkB,EAClB,MAAM,mBAAmB,CAAC;AAQ3B,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAIhC,iFAAiF;AACjF,MAAM,MAAM,oBAAoB,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;AAElE,MAAM,MAAM,cAAc,GAAG;IAC5B,8EAA8E;IAC9E,MAAM,EAAE,kBAAkB,CAAC;IAC3B,2EAA2E;IAC3E,MAAM,EAAE,oBAAoB,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG,eAAe,GAAG;IACrD;;;OAGG;IACH,iBAAiB,CAAC,EAAE,wBAAwB,CAAC;IAC7C;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;OAGG;IACH,8BAA8B,CAAC,EAAE,OAAO,CAAC;CACzC,CAAC;AA+GF,QAAA,MAAM,WAAW,GAChB,QAAQ,kBAAkB,EAC1B,WAAW,IAAI,CAAC,iBAAiB,EAAE,aAAa,CAAC,EACjD,iBAAiB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAsDxB,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,qBAAqB,GAAG,cAAc,CAAC"}

package/dist/sdk-meta.d.ts

@@ -1,4 +1,4 @@
 /** Generated by scripts/generate-sdk-meta.ts — do not edit. */
 export declare const SDK_NAME = "@rasputin-ai/elysia";
-export declare const SDK_VERSION = "0.5.0-alpha.13";
+export declare const SDK_VERSION = "0.5.0-alpha.14";
 //# sourceMappingURL=sdk-meta.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rasputin-ai/elysia",
-	"version": "0.5.0-alpha.13",
+	"version": "0.5.0-alpha.14",
 	"description": "Official Rasputin AI SDK for Elysia.",
 	"type": "module",
 	"exports": {
@@ -35,8 +35,8 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"@rasputin-ai/core": "0.5.0-alpha.13",
-		"@rasputin-ai/node": "0.5.0-alpha.13"
+		"@rasputin-ai/core": "0.5.0-alpha.14",
+		"@rasputin-ai/node": "0.5.0-alpha.14"
 	},
 	"peerDependencies": {
 		"elysia": ">=1.4.0 <2"