@watershed-labs/context

Shared AsyncLocalStorage context for the Watershed ecosystem.

Part of the Watershed testing ecosystem.

Overview

@watershed-labs/context is the single AsyncLocalStorage instance shared across the entire Watershed ecosystem. It exists as its own package for one reason: to prevent a circular dependency between @watershed-labs/world (which sets the context) and @watershed-labs/logger (which reads it).

Both packages import from here. Neither imports from the other.

This package has no dependencies and no logic beyond the AsyncLocalStorage instance itself. Keep it that way.

Installation

npm install @watershed-labs/context

Usage

You should not need to import this package directly in most cases. @watershed-labs/world sets the store at the start of every scenario, and @watershed-labs/logger reads it automatically. The context wiring is transparent.

The two cases where you would import it directly are:

1. Building a new @watershed-labs/* package that needs to read scenario-scoped state

import context from '@watershed-labs/context';

const store = context.getStore();

if (store?.attach) {
    await store.attach(data, 'application/json');
}

2. Writing tests that need to simulate an active scenario context

import context from '@watershed-labs/context';

context.run({ attach: mockAttach }, () => {
    // anything called here sees the store
    const store = context.getStore();
});

API

This package has a single default export — the AsyncLocalStorage instance.

import context from '@watershed-labs/context';

| Method | Description | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | context.getStore() | Returns the current store object, or undefined if called outside an active scenario. | | context.enterWith(store) | Sets the store for the current async context. Called once per scenario by WatershedWorld.init(). Do not call this outside of the World. | | context.run(store, fn) | Runs fn with the given store active. Use in tests to simulate a scenario context without a full World setup. |

What the Store Contains

The store is set by WatershedWorld.init() at the start of every scenario:

context.enterWith({
    attach: this.attach.bind(this)
});

| Key | Type | Description | | -------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | attach | Function | Cucumber's native attach method, bound to the current World instance. Used by @watershed-labs/logger to route log output to the Cucumber report rather than stdout. |

Why This Package Exists

Without it, the dependency graph has a cycle:

@watershed-labs/world  → imports → @watershed-labs/logger
@watershed-labs/logger → imports → @watershed-labs/world   ← cycle

Node.js resolves circular imports by returning whatever the module has exported so far. Since context is defined inside @watershed-labs/world, and @watershed-labs/world hasn't finished evaluating when @watershed-labs/logger first imports it, context arrives as undefined. No error is thrown — context.getStore() silently fails on the first log call inside a scenario.

With @watershed-labs/context as a standalone package:

@watershed-labs/context   (no dependencies)
      ↑         ↑
@watershed-labs/world   @watershed-labs/logger

Both packages import from the same anchor. No cycle. No undefined imports.

Rules

Do not add dependencies to this package. If you find yourself wanting to import something here, the logic belongs elsewhere — in @watershed-labs/world, @watershed-labs/logger, or @watershed-labs/hooks.

Do not add exports to this package beyond the AsyncLocalStorage instance. If you need to share additional scenario-scoped state, extend the store object that WatershedWorld.init() passes to enterWith().

Do not call enterWith() outside of WatershedWorld.init(). There is exactly one place the context is set per scenario. Calling it elsewhere overwrites the store mid-scenario and breaks log routing for everything that ran before the second call.

Parallel Safety

Safe by design. Each parallel worker is a separate Node.js process with its own module cache and its own AsyncLocalStorage instance. Worker contexts are fully isolated — there is no cross-worker shared memory. getStore() in worker 0 never sees the store set by worker 1.

Dependencies

None.

Licence

MIT — part of the Watershed ecosystem.