@equinor/fusion-framework-module-context

Context module for the Fusion Framework. Manages the active context (project, facility, contract, etc.) within Fusion-based applications and portals, providing query, validation, resolution, and parent–child synchronization out of the box.

When to use

Use this module when your application or portal needs to:

• set, read, or clear the active context (e.g. selecting a project)
• search and filter available context items from the Fusion context API
• validate whether a given context item matches the allowed context types
• resolve context across parent–child provider boundaries (portal → app)
• deep-link by extracting a context ID from the URL path

Application developers will typically use the higher-level @equinor/fusion-framework-react-app/context package, which wraps this module with React hooks and providers.

Portal developers will use @equinor/fusion-framework-react/context for the same purpose at the portal level.

How it fits together

A context module instance never lives in isolation. It depends on the @equinor/fusion-framework-module-services module for its default HTTP client, optionally uses @equinor/fusion-framework-module-event to dispatch and listen for context change events, and optionally reads the current URL through @equinor/fusion-framework-module-navigation to resolve a context from the path. None of these need manual setup — enableContext requires only services; event and navigation are picked up automatically when present.

The module is also hierarchy-aware by default: when a Portal and an App both enable context, the App's instance automatically connects to the Portal's and mirrors its context — no wiring required beyond enabling the module on both sides. See Lifecycle for exactly how that sync works, and when it can be overridden or disabled.

Documentation

Key concepts

Quick start

import { enableContext } from '@equinor/fusion-framework-module-context';

export const configure = (configurator) => {
  enableContext(configurator, (builder) => {
    // only accept ProjectMaster context items
    builder.setContextType(['ProjectMaster']);
  });
};

Once initialized, access the provider from the module instance:

// observe context changes
modules.context.currentContext$.subscribe((ctx) => {
  console.log('context changed', ctx);
});

// search for context items
const items = await modules.context.queryContextAsync('Johan');

// set context by item
await modules.context.setCurrentContextAsync(items[0]);

// set context by ID
await modules.context.setCurrentContextByIdAsync('7fd97952-...');

// clear the active context
modules.context.clearCurrentContext();

Operational telemetry

IContextProvider extends TelemetryConnectable. The provider uses telemetry.scope('context'), falling back to the lazily loaded factory for older custom providers, and closes the shared handle on disposal; selection/resolution observation remains in the context module.

When the host registers telemetry, each queued setCurrentContext task reports one fusion.context.select.duration outcome. Each resolution attempt reports fusion.context.resolve.duration, whether it comes from selection, a direct resolveContext/resolveContextAsync call or a configured resolver (by: 'item'), or from the lookup behind setCurrentContextById (by: 'id'):

• failure with reason validation when validation fails and resolution is disabled;
• cancelled with reason listener when an onSetContextResolve, onSetContextResolved or onCurrentContextChange listener calls preventDefault();
• cancelled when a newer task supersedes the task, the caller unsubscribes, or the provider is disposed (reason disposed).

Re-setting the current item without validation is skipped and reports nothing. Context ids, titles and values are never exported, and context behavior is unchanged. Synchronous resolver factory failures are recorded and rethrown synchronously without changing the error object. A final onCurrentContextChange veto records cancellation immediately, including on the existing detached-error path; telemetry does not change that path's caller behavior. See Operational telemetry.

Configuration

All configuration flows through enableContext → ContextModuleConfigurator:

enableContext(configurator, (builder) => {
  // restrict accepted context types
  builder.setContextType(['ProjectMaster', 'Facility']);

  // post-query filter
  builder.setContextFilter((items) => items.filter((i) => i.isActive));

  // custom parameter mapping for the search API
  builder.setContextParameterFn(({ search, type }) => ({
    search,
    filter: { type },
  }));

  // custom validation logic
  builder.setValidateContext(function (item) {
    return item !== null && this.validateContext(item);
  });

  // custom context resolution
  builder.setResolveContext(function (item) {
    return this.relatedContexts({ item, filter: { type: ['ProjectMaster'] } });
  });

  // connect (or disconnect) from parent context
  // when enabled (default), onParentContextChanged fires before mirroring the parent's context locally
  builder.connectParentContext(false);

  // path ↔ context integration
  // the default resolver uses extractContextIdFromPath to pull a GUID from the URL,
  // then fetches the matching context item — see resolveInitialContext in utils
  builder.setContextPathExtractor((path) => path.split('/')[2]);
  builder.setContextPathGenerator((ctx, path) =>
    path.replace(/\/context\/[^/]+/, `/context/${ctx.id}`),
  );

  // provide a fully custom context client
  builder.setContextClient({
    get: (args) => fetch(`/api/context/${args.id}`).then((r) => r.json()),
    query: (args) => fetch(`/api/context?q=${args.search}`).then((r) => r.json()),
  });
});

Configuration reference

Context Routing in the URL

The portal keeps the active context synchronized with the browser URL automatically via the @equinor/fusion-framework-plugin-context-navigation plugin. As an app developer, you control how context appears in your URL by declaring a routing strategy in your app manifest.

Declare a routing strategy

Set contextRouting in your manifest's build.options:

// app.manifest.config.ts
{
  "build": {
    "options": {
      "contextRouting": "query"
    }
  }
}

Apps with custom URL shapes can omit contextRouting and register custom hooks instead (see below). An explicit contextRouting: 'query' always selects query routing, even when custom hooks are registered.

[!NOTE] When contextRouting is not set (or set to null), the portal defaults to the path adapter which encodes context as a path segment after the app key. If your app also registers custom hooks (setContextPathExtractor / setContextPathGenerator), the custom adapter takes priority over the path adapter for path routing or when no strategy is declared. An explicit contextRouting: 'query' selects the query adapter instead.

Custom URL shapes

If your app uses a non-standard URL layout for context (e.g. /route-a/{contextId}), register custom hooks instead of (or in addition to) declaring contextRouting:

enableContext(configurator, (builder) => {
  builder.setContextType(['ProjectMaster']);

  // Tell the portal how to find the context id in your URL
  builder.setContextPathExtractor((path) => {
    const segments = path.split('/').filter(Boolean);
    return segments[1]; // e.g. /route-a/{contextId}
  });

  // Tell the portal how to build a URL with context
  builder.setContextPathGenerator((context, path) => {
    const segments = path.split('/').filter(Boolean);
    const route = segments[0] ?? '';
    return `/${route}/${context.id}`;
  });
});

When these hooks are registered, the portal's custom adapter uses them automatically — no contextRouting declaration needed in the manifest.

How it works (for reference)

The portal's context-navigation plugin reads contextRouting from your app's manifest at runtime and selects the appropriate URL adapter. You don't install or configure the plugin yourself — the portal handles it. Your app only needs to declare its preference.

Events

The context module dispatches events via the @equinor/fusion-framework-module-event system. All events are scoped to the ContextProvider source.

modules.event.addEventListener('onCurrentContextChanged', (e) => {
  console.log('previous:', e.detail.previous);
  console.log('next:', e.detail.next);
});

Errors

The module exports FusionContextSearchError (from @equinor/fusion-framework-module-context/errors.js) for search-related failures:

import { FusionContextSearchError } from '@equinor/fusion-framework-module-context/errors.js';

try {
  await modules.context.queryContextAsync('...');
} catch (err) {
  if (err instanceof FusionContextSearchError) {
    console.error(err.title, err.description);
  }
}

Testing

@equinor/fusion-framework-module-context/mock provides enableContextMock, a purpose-built test double backed by an in-memory pool of seeded context items — no context API, no HTTP mock, and no service-discovery mock required. Real ContextProvider behaviour (validateContext, resolveContext, parent-context propagation) still runs against the seeded data; only the data source is substituted.

Defaults

• The context pool starts empty and no current context is selected.
• Querying the empty pool returns no items.
• Looking up an unseeded id throws an error that names the id and the seeding methods.
• Related-context lookup uses the seeded pool, excludes the source item, and filters by the requested type.
• setCurrentContext both seeds the item and selects it for initial app resolution; setContexts only seeds items.

import { enableContextMock } from '@equinor/fusion-framework-module-context/mock';

enableContextMock(configurator, (mock) => {
  mock.setCurrentContext({ id: 'my-ctx', type: { id: 'ProjectMaster' }, value: {} });
});

• Friendly layer — setCurrentContext, setContexts, addContext, setRelatedContexts — a context-domain vocabulary for the common case: seed a known item, get it back.
• Escape hatch — setResolver — a raw resolution function for a custom resolveContext strategy or a shape the friendly layer did not cover.

When used with @equinor/fusion-framework/mock, FrameworkMockConfigurator.context returns this same configurator, so seeding happens directly through configurator.context with no callback needed.

This is one of two ways to fake context data in tests. The other is mocking the context API's HTTP responses directly (with configurator.http.addMiddleware(...), optionally paired with @equinor/fusion-framework-module-http/mock's createOpenApiMockMiddleware for faker-generated data straight from context's OpenAPI spec) — which exercises the real ContextModuleConfigurator/services/HTTP pipeline instead of substituting it. Reach for enableContextMock to seed one known item with no transport involved; reach for the HTTP middleware when a test needs to cover that pipeline itself. Fixture generators for realistic seeded data (createContextItemFactory, createContextItems) are available from @equinor/fusion-framework-module-context/mock/fixtures.

Generate deterministic context fixtures

The optional /mock/fixtures entry point uses @faker-js/faker to produce realistic but repeatable titles and readable ids. Install Faker only when importing this entry point.

import { enableContextMock } from '@equinor/fusion-framework-module-context/mock';
import { createContextItems } from '@equinor/fusion-framework-module-context/mock/fixtures';

const [project, contract] = createContextItems([
  { type: 'ProjectMaster' },
  { type: 'Contract', parentTypeIds: ['ProjectMaster'] },
]);

enableContextMock(configurator, (mock) => {
  mock.setContexts([project, contract]);
  mock.setCurrentContext(project);
});

Use createContextItemFactory(prefix?) for sequential fixtures of one type. Use createContextItems for multiple types and parent/child type metadata. Generated values are deterministic per id; use setRelatedContexts when relations must differ per specific item.

Utilities

Additional helpers are available from @equinor/fusion-framework-module-context/utils:

Package exports