@http-forge/core 0.4.5 → 0.4.7

package/dist/infrastructure/config/config-service.d.ts

@@ -66,6 +66,7 @@ export declare class ConfigService implements IConfigService {
     getSuitesPath(): string;
     getModulePaths(): string[];
     getScriptScope(): 'shared' | 'isolated';
+    getScriptTimeout(): number;
     getWorkspacePath(): string;
     reload(): void;
     configExists(): boolean;

package/dist/infrastructure/config/config.interface.d.ts

@@ -44,6 +44,12 @@ export interface ScriptsConfig {
      *   must pass through pm.variables / pm.environment / pm.globals.
      */
     scope?: 'shared' | 'isolated';
+    /**
+     * Per-script timeout in milliseconds (default 5000). Bounds both the synchronous
+     * script CPU guard and the async event-loop drain budget (pending setTimeout /
+     * un-awaited Promises) that the runner waits on before advancing to the next request.
+     */
+    timeout?: number;
 }
 /**
  * Runner configuration
@@ -212,6 +218,8 @@ export interface IConfigService {
     getModulePaths(): string[];
     /** Get the script scope mode ('shared' default, or 'isolated' for Postman parity) */
     getScriptScope(): 'shared' | 'isolated';
+    /** Get the per-script timeout in milliseconds (default 5000) */
+    getScriptTimeout(): number;
     /** Get the workspace root path */
     getWorkspacePath(): string;
     /** Reload configuration from disk */

package/dist/infrastructure/environment/environment-config-service.d.ts

@@ -113,7 +113,7 @@ export declare class EnvironmentConfigService implements IEnvironmentConfigServi
     private getEnvLocalConfigPath;
     private loadFolderConfigs;
     /**
-     * Create a VariableResolver pre-loaded with environment + session variables.
+     * Create a VariableResolver pre-loaded with environment variables.
      */
     private createResolver;
     private saveFolderSharedConfig;

package/dist/infrastructure/environment/environment-resolver.d.ts

@@ -77,6 +77,15 @@ export declare class EnvironmentResolver implements IEnvironmentStore {
      * Set a global variable
      */
     setGlobal(key: string, value: string): void;
+    /**
+     * Remove a session global variable. File-defined globals (globalVariables)
+     * are defaults and cannot be deleted here — only session overrides are removed.
+     */
+    unsetGlobal(key: string): void;
+    /**
+     * Clear all session global variables. File-defined globals are left intact.
+     */
+    clearGlobals(): void;
     /**
      * Resolve environment for execution
      */

package/dist/infrastructure/environment/forge-env.d.ts

@@ -30,8 +30,8 @@
  * env.get('token');  // 'abc'
  * ```
  */
-import { EnvironmentResolver } from './environment-resolver';
 import type { IEnvironmentStore, IVariableInterpolator } from '../../types/environment-config';
+import { EnvironmentResolver } from './environment-resolver';
 /**
  * ForgeEnv interface - the public API for environment management
  */
@@ -69,6 +69,22 @@ export interface IForgeEnv {
      * Get list of available environment names
      */
     getEnvironments(): string[];
+    /**
+     * Get all global variables (environment-agnostic variable layer)
+     */
+    getGlobals(): Record<string, string>;
+    /**
+     * Set a global variable value
+     */
+    setGlobal(key: string, value: string): void;
+    /**
+     * Remove a global variable
+     */
+    unsetGlobal(key: string): void;
+    /**
+     * Clear all (session) global variables
+     */
+    clearGlobals(): void;
     /**
      * Resolve {{variable}} placeholders in a string
      */
@@ -127,6 +143,23 @@ export declare class ForgeEnv implements IForgeEnv {
      * Get list of available environment names
      */
     getEnvironments(): string[];
+    /**
+     * Get all global variables. Globals are the lowest-priority, environment-agnostic
+     * variable layer — treated like environment variables with no environment scope.
+     */
+    getGlobals(): Record<string, string>;
+    /**
+     * Set a global variable value.
+     */
+    setGlobal(key: string, value: string): void;
+    /**
+     * Remove a (session) global variable.
+     */
+    unsetGlobal(key: string): void;
+    /**
+     * Clear all (session) global variables.
+     */
+    clearGlobals(): void;
     /**
      * Resolve {{variable}} placeholders
      */

package/dist/infrastructure/environment/variable-interpolator.d.ts

@@ -28,20 +28,28 @@ export interface VariableResolverConfig {
     globals: Record<string, string>;
     collectionVariables: Record<string, string>;
     environmentVariables: Record<string, string>;
-    sessionVariables: Record<string, string>;
     variables: Record<string, string>;
 }
 /**
  * Variable Resolver - Resolves {{varName}} patterns in strings and objects
  * Uses a 5-step pipeline: $dynamic → filter chains → simple lookup → JS expressions → passthrough
- * Variable precedence: globals > collection > environment > session > request > extra
+ * Variable precedence: globals > collection > environment > request > extra
  */
 export declare class VariableResolver {
     private readonly allVariables;
+    /**
+     * Maximum nesting depth for recursive {{var}} resolution.
+     * Postman-compatible cap that guards against reference cycles
+     * (e.g. a -> {{b}}, b -> {{a}}).
+     */
+    private static readonly MAX_RESOLUTION_DEPTH;
     constructor(config: VariableResolverConfig);
     /**
      * Resolve variables in a string ({{varName}} syntax)
-     * Uses the full 5-step pipeline with optional escaping for quoted strings
+     * Uses the full 5-step pipeline with optional escaping for quoted strings.
+     * Nested references — a variable whose value itself contains {{...}} — are
+     * resolved recursively (Postman-style) by repeating the substitution until
+     * the string stabilizes or the depth cap is reached.
      */
     resolveString(str: string, escape?: boolean): string;
     /**
@@ -49,6 +57,20 @@ export declare class VariableResolver {
      * Extra variables take highest precedence
      */
     resolveStringWithExtra(str: string, extraVariables: Record<string, string>, escape?: boolean): string;
+    /**
+     * Repeatedly apply a single substitution pass until the result stops changing
+     * (fixed point) or the nesting depth cap is hit. This resolves variable values
+     * that themselves contain {{...}} references. Undefined tokens are left as-is,
+     * so a pass that resolves nothing produces no change and terminates the loop;
+     * the depth cap guards against reference cycles (a -> {{b}}, b -> {{a}}).
+     */
+    private resolveUntilStable;
+    /**
+     * Single substitution pass over a string using the 5-step pipeline.
+     * With escaping enabled, resolved values are escaped for their surrounding
+     * quote context.
+     */
+    private resolveSinglePass;
     /**
      * Resolve variables in an object recursively
      */

package/dist/infrastructure/execution/request-executor.d.ts

@@ -62,6 +62,7 @@ export declare class RequestExecutor {
         forgeRoot?: string;
         scriptExecutor?: IScriptExecutor;
         scriptScope?: 'shared' | 'isolated';
+        scriptTimeout?: number;
     });
     /**
      * Execute a request with full pipeline

package/dist/infrastructure/script/async-drain.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Async Drain — Postman-compatible event-loop draining for script sandboxes
+ *
+ * Postman/Newman keep a script's sandbox alive after its synchronous body returns,
+ * pumping the event loop until all pending timers (`setTimeout`/`setInterval`) and
+ * microtasks (un-awaited Promises) have settled — bounded by a script timeout. Only
+ * then does the runner advance, committing any variable mutations made by those late
+ * callbacks so the next request can see them.
+ *
+ * This module provides an instrumented timer set plus a `drain()` loop that replicates
+ * that behavior. The timers wrap the real Node timers, track outstanding handles, and
+ * swallow errors thrown inside deferred callbacks (reporting them as non-fatal) so a
+ * late failure never rejects the surrounding request — matching Postman, where such
+ * callbacks run on a later tick outside the script's try/catch.
+ */
+/** Sandbox-facing timer functions, drop-in replacements for the Node globals. */
+export interface SandboxTimers {
+    setTimeout: (handler: (...args: any[]) => void, timeout?: number, ...args: any[]) => any;
+    clearTimeout: (handle: any) => void;
+    setInterval: (handler: (...args: any[]) => void, timeout?: number, ...args: any[]) => any;
+    clearInterval: (handle: any) => void;
+}
+/** Result of a drain operation. */
+export interface DrainResult {
+    /** True if the timeout cap was hit while timers were still pending. */
+    timedOut: boolean;
+    /** Approximate wall-clock time spent draining, in milliseconds. */
+    elapsedMs: number;
+}
+/**
+ * A registry of instrumented timers bound to a single script session.
+ */
+export interface TimerRegistry {
+    /** Timer functions to expose inside the VM sandbox. */
+    readonly timers: SandboxTimers;
+    /** Number of timers still pending (not yet fired or cleared, or active intervals). */
+    pendingCount(): number;
+    /** Cancel every outstanding timer. Used at the drain cap and on dispose. */
+    clearAll(): void;
+    /**
+     * Pump the event loop until no timers are pending (and a final microtask flush
+     * yields nothing new) or until `timeoutMs` of wall-clock time elapses, whichever
+     * comes first. On timeout, all remaining timers are force-cleared.
+     */
+    drain(timeoutMs: number): Promise<DrainResult>;
+}
+/**
+ * Create a timer registry whose deferred-callback errors are routed to `onTimerError`.
+ *
+ * @param onTimerError Invoked (never throws) when a timer callback throws. The error is
+ *                     swallowed relative to the request so the run continues.
+ */
+export declare function createTimerRegistry(onTimerError: (error: unknown) => void): TimerRegistry;

package/dist/infrastructure/script/interfaces.d.ts

@@ -61,7 +61,6 @@ export interface CommonScriptContext {
     variables: Record<string, string>;
     collectionVariables?: Record<string, string>;
     globals?: Record<string, string>;
-    sessionVariables?: Record<string, string>;
     environmentVariables?: Record<string, string>;
     environmentName?: string;
     sendRequest?: (options: any) => Promise<any>;
@@ -70,6 +69,7 @@ export interface CommonScriptContext {
     iterationCount?: number;
     iterationData?: Record<string, any>;
     onEnvironmentChange?: (action: 'set' | 'unset' | 'clear', key?: string, value?: string) => void;
+    onGlobalsChange?: (action: 'set' | 'unset' | 'clear', key?: string, value?: string) => void;
 }
 /**
  * Script execution context for pre-request scripts
@@ -95,7 +95,6 @@ export interface PreRequestScriptResult {
     modifiedVariables?: Record<string, string>;
     modifiedCollectionVariables?: Record<string, string>;
     modifiedGlobals?: Record<string, string>;
-    modifiedSessionVariables?: Record<string, string>;
     modifiedEnvironmentVariables?: Record<string, string>;
     consoleOutput?: string[];
     /** Postman-compatible: pm.execution.setNextRequest() value. null = stop runner. */
@@ -110,7 +109,8 @@ export interface PostResponseScriptResult {
     testResults: TestAssertion[];
     consoleOutput?: string[];
     modifiedEnvironmentVariables?: Record<string, string>;
-    modifiedSessionVariables?: Record<string, string>;
+    modifiedGlobals?: Record<string, string>;
+    modifiedCollectionVariables?: Record<string, string>;
     /** Postman-compatible: pm.execution.setNextRequest() value. null = stop runner. */
     nextRequest?: string | null;
     /** Postman-compatible: pm.visualizer.set(template, data) output */

package/dist/infrastructure/script/request-script-session.d.ts

@@ -8,16 +8,22 @@
  * This matches Postman's behavior for per-request script execution.
  */
 import * as vm from 'vm';
+import { SandboxTimers } from './async-drain';
 import { CommonScriptContext, IRequestScriptSession, PostResponseScriptResult, PreRequestScriptContext, PreRequestScriptResult, ResponseContext } from './interfaces';
 /**
  * Dependencies injected from ScriptExecutor
  * Interface Segregation: Only the methods needed by the session
  */
 export interface SessionDependencies {
-    createVM: (ctx: any, scriptConsole: any) => vm.Context;
+    createVM: (ctx: any, scriptConsole: any, timers?: SandboxTimers) => vm.Context;
     createCommonContext: (context: CommonScriptContext, eventName: 'prerequest' | 'test') => any;
     /** When true, each script level runs in its own scope (Postman-compatible). */
     isolateScripts?: boolean;
+    /**
+     * Per-script timeout in milliseconds. Bounds BOTH the synchronous VM CPU guard and
+     * the async event-loop drain budget (pending timers / un-awaited Promises).
+     */
+    scriptTimeoutMs?: number;
 }
 /**
  * Request Script Session Implementation
@@ -43,6 +49,7 @@ export declare class RequestScriptSession implements IRequestScriptSession {
     private _nextRequest;
     private _skipRequest;
     private _visualizerData;
+    private readonly timerRegistry;
     constructor(deps: SessionDependencies, initialContext: PreRequestScriptContext);
     /**
      * Initialize the shared VM context

package/dist/infrastructure/script/script-executor.d.ts

@@ -23,8 +23,9 @@ export declare class ScriptExecutor implements IScriptExecutor {
     private readonly httpService?;
     private readonly secretRegistry?;
     private readonly scopeMode;
+    private readonly scriptTimeoutMs;
     private readonly moduleLoader;
-    constructor(httpService?: IHttpRequestService | undefined, modulePaths?: string[], secretRegistry?: SecretResolverRegistry | undefined, scopeMode?: 'shared' | 'isolated');
+    constructor(httpService?: IHttpRequestService | undefined, modulePaths?: string[], secretRegistry?: SecretResolverRegistry | undefined, scopeMode?: 'shared' | 'isolated', scriptTimeoutMs?: number);
     /**
      * Create a request execution session
      * Factory method implementing IScriptExecutor
@@ -33,6 +34,10 @@ export declare class ScriptExecutor implements IScriptExecutor {
     /**
      * Create VM context with sandbox configuration
      * Returns a context object that can be used with vm.runInContext()
+     *
+     * @param timers Optional instrumented timer set. When provided, the sandbox uses
+     *               these instead of the Node globals so the session can track and
+     *               drain pending timers (Postman-compatible async behavior).
      */
     private createVM;
     /**
@@ -55,6 +60,13 @@ export declare class ScriptExecutor implements IScriptExecutor {
      * Create a basic variable scope with get/set/has/unset/clear/toObject
      */
     private createVariableScope;
+    /**
+     * Create the globals scope with change callbacks.
+     * Globals are a special, environment-agnostic variable layer, so they are
+     * persisted live through the same push-callback mechanism as environment
+     * variables (see createEnvironmentScope) rather than a post-hoc diff.
+     */
+    private createGlobalsScope;
     /**
      * Create merged variable scope (Postman-style cascading lookup)
      */

package/dist/infrastructure/test-suite/result-storage.d.ts

@@ -227,8 +227,6 @@ export interface FullResultDetails {
     modifiedEnvironmentVariables?: Record<string, string>;
     /** Collection variables modified by scripts */
     modifiedCollectionVariables?: Record<string, string>;
-    /** Session variables modified by scripts */
-    modifiedSessionVariables?: Record<string, string>;
     /** pm.execution.setNextRequest() value */
     nextRequest?: string | null;
     /** pm.visualizer.set() payload */

package/dist/types/types.d.ts

@@ -218,7 +218,6 @@ export interface ExecutionVariables {
     variables: Record<string, string>;
     collectionVariables?: Record<string, string>;
     globals?: Record<string, string>;
-    sessionVariables?: Record<string, string>;
     environmentVariables?: Record<string, string>;
 }
 /**
@@ -619,7 +618,6 @@ export interface ExecutionResult {
     modifiedVariables?: Record<string, string>;
     modifiedEnvironmentVariables?: Record<string, string>;
     modifiedCollectionVariables?: Record<string, string>;
-    modifiedSessionVariables?: Record<string, string>;
     error?: string;
     /** Folder path of the request within its collection (slash-separated; empty for root) */
     folderPath?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@http-forge/core",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "description": "Headless HTTP testing engine with Postman collection support, dynamic variables, and script-based automation.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",