@bitfab/sdk 0.38.3 → 0.38.5

package/dist/node.cjs

@@ -88,7 +88,7 @@ var __version__, __packageName__;
 var init_version_generated = __esm({
   "src/version.generated.ts"() {
     "use strict";
-    __version__ = "0.38.3";
+    __version__ = "0.38.5";
     __packageName__ = "@bitfab/sdk";
   }
 });
@@ -2194,11 +2194,16 @@ function normalizeMockOverrides(mockOverride) {
   if (mockOverride === void 0) {
     return [];
   }
-  return Array.isArray(mockOverride) ? mockOverride : [mockOverride];
+  const overrides = Array.isArray(mockOverride) ? mockOverride : [mockOverride];
+  return overrides.map(
+    (override) => typeof override === "function" ? { match: () => true, value: override } : override
+  );
 }
+var NO_MOCK_OVERRIDE;
 var init_mockOverride = __esm({
   "src/mockOverride.ts"() {
     "use strict";
+    NO_MOCK_OVERRIDE = /* @__PURE__ */ Symbol("bitfab.noMockOverride");
   }
 });
 
@@ -3140,6 +3145,7 @@ __export(node_exports, {
   DEFAULT_SERVICE_URL: () => DEFAULT_SERVICE_URL,
   DbBranchReplayError: () => DbBranchReplayError,
   HttpClient: () => HttpClient,
+  NO_MOCK_OVERRIDE: () => NO_MOCK_OVERRIDE,
   ReplayError: () => ReplayError,
   SUPPORTED_PROVIDERS: () => SUPPORTED_PROVIDERS,
   __version__: () => __version__,
@@ -3802,6 +3808,29 @@ function runWithAutoTraceContext(context, fn, depth = 0) {
     autoTraceState.browserScope = previous;
   }
 }
+function runWithAutoTraceNodeConfiguration(nodeConfiguration, fn) {
+  const scope = currentAutoTraceScope();
+  if (!scope) {
+    return fn();
+  }
+  const configuredScope = { ...scope, nodeConfiguration };
+  let result;
+  if (autoTraceState.storage) {
+    result = autoTraceState.storage.run(configuredScope, fn);
+  } else {
+    const previous = autoTraceState.browserScope;
+    autoTraceState.browserScope = configuredScope;
+    try {
+      result = fn();
+    } finally {
+      autoTraceState.browserScope = previous;
+    }
+  }
+  if (isAutoTraceAsyncGenerator(result)) {
+    return wrapAutoTraceNodeAsyncGenerator(nodeConfiguration, result);
+  }
+  return result;
+}
 function runWithAutoTraceRootContext(context, fn) {
   autoTraceState.activeRoots += 1;
   let result;
@@ -3840,6 +3869,29 @@ function wrapAutoTraceAsyncGenerator(context, source) {
   };
   return wrapped;
 }
+function wrapAutoTraceNodeAsyncGenerator(nodeConfiguration, source) {
+  const step = (method, value) => runWithAutoTraceNodeConfiguration(
+    nodeConfiguration,
+    () => source[method](value)
+  );
+  const wrapped = {
+    next: (value) => step("next", value),
+    return: (value) => step("return", value),
+    throw: (error) => step("throw", error),
+    [Symbol.asyncIterator]: () => wrapped
+  };
+  return wrapped;
+}
+function __bitfabAutoTraceActive() {
+  if (autoTraceState.activeRoots === 0) {
+    return false;
+  }
+  return currentAutoTraceScope() !== void 0;
+}
+function currentAutoTraceScope() {
+  initializeAutoTraceStorage();
+  return autoTraceState.storage?.getStore() ?? autoTraceState.browserScope;
+}
 function __setBitfabAutoTraceCapturePolicy(client, traceFunctionKey, functionIds) {
   const policies = autoTraceState.capturePolicies.get(client) ?? /* @__PURE__ */ new Map();
   policies.set(traceFunctionKey, new Set(functionIds));
@@ -5692,6 +5744,102 @@ var Bitfab = class {
     const name = fn.name !== "" ? fn.name : traceFunctionKey;
     return this.createAutoTraceRoot(traceFunctionKey, name, options, fn);
   }
+  /**
+   * Configure a transformed class method when it is discovered beneath a
+   * {@link Bitfab.trace} root.
+   *
+   * The decorator creates no span or trace by itself. Beneath an active trace,
+   * it can rename or retype the discovered call, capture its contents, mark it
+   * for recorded-output replay, finalize its output, or omit it while leaving
+   * captured descendants attached to the nearest captured parent.
+   *
+   * @param options - Trace-owned call configuration.
+   * @experimental Automatic child-call instrumentation is experimental.
+   */
+  node(options = {}) {
+    const configuration = this.resolveNodeConfiguration(options);
+    const decorator = (...args) => {
+      if (args.length === 3) {
+        const descriptor = args[2];
+        if (!descriptor || typeof descriptor.value !== "function") {
+          throw new BitfabError("@bitfab.node can only decorate methods");
+        }
+        if (!this.explicitlyEnabled) {
+          return;
+        }
+        descriptor.value = this.createAutoTraceNode(
+          configuration,
+          descriptor.value,
+          String(args[1])
+        );
+        return;
+      }
+      const method = args[0];
+      const context = args[1];
+      if (typeof method !== "function" || context?.kind !== "method") {
+        throw new BitfabError("@bitfab.node can only decorate methods");
+      }
+      if (!this.explicitlyEnabled) {
+        return method;
+      }
+      return this.createAutoTraceNode(
+        configuration,
+        method,
+        String(context.name)
+      );
+    };
+    return decorator;
+  }
+  withNode(optionsOrFn, maybeFn, internalFunctionName) {
+    const options = typeof optionsOrFn === "function" ? {} : optionsOrFn;
+    const fn = typeof optionsOrFn === "function" ? optionsOrFn : maybeFn;
+    if (!fn) {
+      throw new BitfabError("bitfab.withNode requires a function");
+    }
+    const configuration = this.resolveNodeConfiguration(options);
+    if (!this.explicitlyEnabled) {
+      return fn;
+    }
+    const functionName = internalFunctionName ?? fn.name;
+    if (functionName === "") {
+      throw new BitfabError(
+        "bitfab.withNode requires a named function so the subtree transform can bind its configuration to the correct call."
+      );
+    }
+    return this.createAutoTraceNode(configuration, fn, functionName);
+  }
+  resolveNodeConfiguration(options) {
+    const capture = options.capture ?? true;
+    if (!capture && options.mockOnReplay === true) {
+      throw new BitfabError(
+        "bitfab.node({ capture: false }) cannot use mockOnReplay: true because an uncaptured node has no recorded output."
+      );
+    }
+    return {
+      capture,
+      type: options.type ?? "custom",
+      ...options.name !== void 0 && { name: options.name },
+      ...options.testRunId !== void 0 && {
+        testRunId: options.testRunId
+      },
+      ...options.mockOnReplay !== void 0 && {
+        mockOnReplay: options.mockOnReplay
+      },
+      ...options.finalize !== void 0 && { finalize: options.finalize }
+    };
+  }
+  createAutoTraceNode(configuration, fn, functionName) {
+    const nodeConfiguration = { ...configuration, functionName };
+    return function(...args) {
+      if (!__bitfabAutoTraceActive()) {
+        return fn.apply(this, args);
+      }
+      return runWithAutoTraceNodeConfiguration(
+        nodeConfiguration,
+        () => fn.apply(this, args)
+      );
+    };
+  }
   createAutoTraceRoot(traceFunctionKey, name, options, fn) {
     const self = this;
     const maxDepth = autoTraceLimit(
@@ -5730,29 +5878,51 @@ var Bitfab = class {
           );
         };
         const autoTraceContext = {
-          invoke(definition, inputs, invokeFn, depth) {
+          invoke(definition, inputs, invokeFn, depth, nodeConfiguration) {
             const nameParts = definition.name.split(".");
             const simpleName = nameParts[nameParts.length - 1];
-            if (excluded.has(definition.name) || simpleName !== void 0 && excluded.has(simpleName) || definition.wrapper === true && !includeWrappers) {
-              return invokeFn();
+            const invokeWithoutNode = () => nodeConfiguration === void 0 ? invokeFn() : runWithAutoTraceContext(autoTraceContext, invokeFn, depth);
+            if (excluded.has(definition.name) || simpleName !== void 0 && excluded.has(simpleName) || nodeConfiguration === void 0 && definition.wrapper === true && !includeWrappers) {
+              return invokeWithoutNode();
+            }
+            if (nodeConfiguration?.capture === false) {
+              return runWithAutoTraceContext(autoTraceContext, invokeFn, depth);
             }
             if (depth >= maxDepth || spansUsed >= maxSpans) {
               warnTruncated();
-              return invokeFn();
+              return invokeWithoutNode();
             }
             spansUsed += 1;
             const childOptions = {
-              name: definition.name,
-              type: "function",
+              name: nodeConfiguration?.name ?? definition.name,
+              type: nodeConfiguration?.type ?? "function",
               captureWhen: "nested",
               functionId: definition.id,
-              captureContent: capturePolicy.has(definition.id),
-              autoTraceDefinition: definition
+              captureContent: nodeConfiguration !== void 0 || capturePolicy.has(definition.id),
+              autoTraceDefinition: definition,
+              ...nodeConfiguration?.testRunId !== void 0 && {
+                testRunId: nodeConfiguration.testRunId
+              },
+              ...nodeConfiguration?.mockOnReplay !== void 0 && {
+                mockOnReplay: nodeConfiguration.mockOnReplay
+              },
+              ...nodeConfiguration?.finalize !== void 0 && {
+                finalize: nodeConfiguration.finalize
+              }
             };
+            const invokeWithAutoTraceContext = () => runWithAutoTraceContext(autoTraceContext, invokeFn, depth + 1);
+            if (definition.async === true) {
+              const tracedAsyncChild = self.withSpan(
+                traceFunctionKey,
+                childOptions,
+                async (..._inputs) => await invokeWithAutoTraceContext()
+              );
+              return tracedAsyncChild(...inputs);
+            }
             const tracedChild = self.withSpan(
               traceFunctionKey,
               childOptions,
-              (..._inputs) => runWithAutoTraceContext(autoTraceContext, invokeFn, depth + 1)
+              (..._inputs) => invokeWithAutoTraceContext()
             );
             return tracedChild(...inputs);
           }
@@ -6322,18 +6492,17 @@ var Bitfab = class {
         newStack = [...currentStack, newContext];
         const inputs = args;
         const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+        const replayCtxAtStart = getReplayContext();
+        const testRunId = replayCtxAtStart?.testRunId ?? options.testRunId;
         if (isRootSpan && !activeTraceStates.has(traceId)) {
-          const replayCtxAtRoot = getReplayContext();
           const dbSnapshotRef = buildSnapshotRef(self.dbSnapshot, startedAt);
           activeTraceStates.set(traceId, {
             traceId,
             startedAt,
             contexts: [],
-            ...replayCtxAtRoot?.testRunId && {
-              testRunId: replayCtxAtRoot.testRunId
-            },
-            ...replayCtxAtRoot?.inputSourceTraceId && {
-              inputSourceTraceId: replayCtxAtRoot.inputSourceTraceId
+            ...testRunId !== void 0 && { testRunId },
+            ...replayCtxAtStart?.inputSourceTraceId && {
+              inputSourceTraceId: replayCtxAtStart.inputSourceTraceId
             },
             dbSnapshotRef
           });
@@ -6366,9 +6535,7 @@ var Bitfab = class {
                 contexts: newContext.contexts,
                 prompt: newContext.prompt,
                 endedAt,
-                ...replayCtx?.testRunId && {
-                  testRunId: replayCtx.testRunId
-                },
+                ...testRunId !== void 0 && { testRunId },
                 ...replayCtx?.inputSourceSpanId && {
                   inputSourceSpanId: replayCtx.inputSourceSpanId
                 }
@@ -6408,6 +6575,49 @@ var Bitfab = class {
           } catch {
           }
         };
+        const recordSpan = (result) => {
+          if (options.finalize) {
+            void self.httpClient.trackDeferred(
+              Promise.resolve().then(() => options.finalize(result)).then((output) => sendSpan({ result: output })).catch(
+                (error) => sendSpan({
+                  result: void 0,
+                  error: error instanceof Error ? `finalize failed: ${error.message}` : `finalize failed: ${String(error)}`
+                })
+              )
+            );
+          } else {
+            void sendSpan({ result });
+          }
+        };
+        executeWithContext = () => {
+          let result;
+          try {
+            result = fn.apply(this, args);
+          } catch (error) {
+            void sendSpan({
+              result: void 0,
+              error: error instanceof Error ? error.message : String(error)
+            });
+            throw error;
+          }
+          if (result instanceof Promise) {
+            return result.then((resolvedResult) => {
+              recordSpan(resolvedResult);
+              return resolvedResult;
+            }).catch((error) => {
+              void sendSpan({
+                result: void 0,
+                error: error instanceof Error ? error.message : String(error)
+              });
+              throw error;
+            });
+          }
+          if (isAsyncGenerator(result)) {
+            return wrapAsyncGenerator(result, newStack, sendSpan);
+          }
+          recordSpan(result);
+          return result;
+        };
         const replayCtxForMock = getReplayContext();
         if (replayCtxForMock?.mockTree && !isRootSpan) {
           const counters = replayCtxForMock.callCounters;
@@ -6466,6 +6676,7 @@ var Bitfab = class {
             }
             return output;
           };
+          const shouldMockWithBaseStrategy = replayCtxForMock.mockStrategy === "all" || replayCtxForMock.mockStrategy === "marked" && options.mockOnReplay === true;
           if (replayCtxForMock.mockOverrides?.length) {
             const nodeMeta = {
               traceFunctionKey,
@@ -6473,28 +6684,75 @@ var Bitfab = class {
               type: options.type ?? "custom",
               originalSpanId: mockSpan?.sourceSpanId
             };
-            const override = replayCtxForMock.mockOverrides.find(
-              (o) => o.match(nodeMeta)
-            );
-            if (override) {
-              const injected = resolveMockValue(override.value, {
-                node: nodeMeta,
-                inputs: args,
-                getOriginalOutput: () => Promise.resolve(resolveRecordedOutput())
-              });
-              if (injected instanceof Promise) {
-                return emitMockAsync(injected, "override");
+            const overrideCtx = {
+              node: nodeMeta,
+              inputs: args,
+              getOriginalOutput: () => Promise.resolve(resolveRecordedOutput())
+            };
+            const resolveOverrideFrom = (startIndex) => {
+              for (let index = startIndex; index < replayCtxForMock.mockOverrides.length; index += 1) {
+                const override = replayCtxForMock.mockOverrides[index];
+                if (!override?.match(nodeMeta)) {
+                  continue;
+                }
+                const injected = resolveMockValue(override.value, overrideCtx);
+                if (injected instanceof Promise) {
+                  return injected.then(
+                    (output) => output === NO_MOCK_OVERRIDE ? resolveOverrideFrom(index + 1) : { matched: true, output }
+                  );
+                }
+                if (injected !== NO_MOCK_OVERRIDE) {
+                  return { matched: true, output: injected };
+                }
+              }
+              return { matched: false };
+            };
+            const resolution = resolveOverrideFrom(0);
+            if (resolution instanceof Promise) {
+              if (!fnReturnsPromise) {
+                throw new BitfabError(
+                  `Cannot resolve an asynchronous mock override for synchronous span "${traceFunctionKey}". Make the wrapped function async or return NO_MOCK_OVERRIDE synchronously.`
+                );
               }
-              return emitMock(injected, "override");
+              return runWithSpanStack(newStack, async () => {
+                const resolved = await resolution;
+                if (resolved.matched) {
+                  void sendSpan({
+                    result: resolved.output,
+                    mocked: true,
+                    mockTarget: "output",
+                    mockSource: "override"
+                  });
+                  return resolved.output;
+                }
+                if (shouldMockWithBaseStrategy && !mockSpan) {
+                  throw new BitfabError(
+                    `Replay selected span "${traceFunctionKey}:${baseSpanParams.spanName}" for mocking, but recorded occurrence ${callIndex + 1} is unavailable. The real span was not executed.`
+                  );
+                }
+                if (shouldMockWithBaseStrategy) {
+                  const output = await resolveRecordedOutput();
+                  void sendSpan({
+                    result: output,
+                    mocked: true,
+                    mockTarget: "output",
+                    mockSource: "recorded"
+                  });
+                  return output;
+                }
+                return executeWithContext();
+              });
+            }
+            if (resolution.matched) {
+              return emitMock(resolution.output, "override");
             }
           }
-          const shouldMock = replayCtxForMock.mockStrategy === "all" || replayCtxForMock.mockStrategy === "marked" && options.mockOnReplay === true;
-          if (shouldMock && !mockSpan) {
+          if (shouldMockWithBaseStrategy && !mockSpan) {
             throw new BitfabError(
               `Replay selected span "${traceFunctionKey}:${baseSpanParams.spanName}" for mocking, but recorded occurrence ${callIndex + 1} is unavailable. The real span was not executed.`
             );
           }
-          if (shouldMock) {
+          if (shouldMockWithBaseStrategy) {
             const recorded = resolveRecordedOutput();
             if (recorded instanceof Promise) {
               return emitMockAsync(recorded, "recorded");
@@ -6502,49 +6760,6 @@ var Bitfab = class {
             return emitMock(recorded, "recorded");
           }
         }
-        const recordSpan = (result) => {
-          if (options.finalize) {
-            void self.httpClient.trackDeferred(
-              Promise.resolve().then(() => options.finalize(result)).then((output) => sendSpan({ result: output })).catch(
-                (error) => sendSpan({
-                  result: void 0,
-                  error: error instanceof Error ? `finalize failed: ${error.message}` : `finalize failed: ${String(error)}`
-                })
-              )
-            );
-          } else {
-            void sendSpan({ result });
-          }
-        };
-        executeWithContext = () => {
-          let result;
-          try {
-            result = fn.apply(this, args);
-          } catch (error) {
-            void sendSpan({
-              result: void 0,
-              error: error instanceof Error ? error.message : String(error)
-            });
-            throw error;
-          }
-          if (result instanceof Promise) {
-            return result.then((resolvedResult) => {
-              recordSpan(resolvedResult);
-              return resolvedResult;
-            }).catch((error) => {
-              void sendSpan({
-                result: void 0,
-                error: error instanceof Error ? error.message : String(error)
-              });
-              throw error;
-            });
-          }
-          if (isAsyncGenerator(result)) {
-            return wrapAsyncGenerator(result, newStack, sendSpan);
-          }
-          recordSpan(result);
-          return result;
-        };
       } catch (setupError) {
         if (registeredTraceId) {
           activeTraceStates.delete(registeredTraceId);
@@ -6831,8 +7046,40 @@ var Bitfab = class {
       ...params.mockSource && { mockSource: params.mockSource }
     });
   }
-  registerMockOverride(overrideOrMatch, value) {
-    const override = typeof overrideOrMatch === "function" ? { match: overrideOrMatch, value } : overrideOrMatch;
+  registerMockOverride(overrideOrResolverOrMatch, ...values) {
+    let override;
+    if (typeof overrideOrResolverOrMatch === "string") {
+      const keyedOverride = values[0];
+      if (values.length !== 1 || keyedOverride === void 0) {
+        throw new BitfabError(
+          "registerMockOverride(traceFunctionKey, override) requires a resolver function or { match, value } override."
+        );
+      }
+      if (typeof keyedOverride === "function") {
+        override = {
+          match: (node) => node.traceFunctionKey === overrideOrResolverOrMatch,
+          value: keyedOverride
+        };
+      } else if (typeof keyedOverride === "object" && keyedOverride !== null && "match" in keyedOverride && "value" in keyedOverride) {
+        override = {
+          match: (node) => node.traceFunctionKey === overrideOrResolverOrMatch && keyedOverride.match(node),
+          value: keyedOverride.value
+        };
+      } else {
+        throw new BitfabError(
+          "registerMockOverride(traceFunctionKey, override) requires a resolver function or { match, value } override."
+        );
+      }
+    } else if (typeof overrideOrResolverOrMatch !== "function") {
+      override = overrideOrResolverOrMatch;
+    } else if (values.length === 0) {
+      override = { match: () => true, value: overrideOrResolverOrMatch };
+    } else {
+      override = {
+        match: overrideOrResolverOrMatch,
+        value: values[0]
+      };
+    }
     this.mockOverrides.push(override);
   }
   /** Remove all overrides registered via {@link registerMockOverride}. */
@@ -7082,6 +7329,7 @@ var finalizers = {
 
 // src/index.ts
 init_http();
+init_mockOverride();
 init_replay();
 
 // src/replayRegistry.ts
@@ -7109,6 +7357,7 @@ assertAsyncStorageRegistered();
   DEFAULT_SERVICE_URL,
   DbBranchReplayError,
   HttpClient,
+  NO_MOCK_OVERRIDE,
   ReplayError,
   SUPPORTED_PROVIDERS,
   __version__,