Facade methods replace direct workflowObject access

r00gm

·Apr 7, 2026·#27556refactor(editor): Add workflowObject facade methods + ESLint guards (no-changelog)

New composables in the editor give developers structured APIs for graph traversal and expression resolution, with ESLint blocking direct access to the deprecated workflowObject.

Direct access to internal workflow state has been a maintenance liability — consumers reaching into workflowsStore.workflowObject created hidden dependencies that made refactoring risky. A new pair of composables now provides structured alternatives: useWorkflowDocumentGraph exposes graph traversal methods like parent/child node lookup and connection analysis, while useWorkflowDocumentExpression wraps expression resolution behind a clean interface.

An ESLint rule blocks new code from bypassing these composables and accessing workflowsStore.workflowObject directly. The existing property carries a @deprecated tag, signaling that direct access will eventually disappear entirely. This approach protects consumers from breaking changes while the underlying implementation migrates from the old store to the new architecture.

In the @n8n/editor-ui package, the facade is wired into workflowDocumentStore itself, so code using that store automatically gains access to the new methods. A type-level guard (AssertNoOverlap) prevents composables from accidentally exporting overlapping keys, which would silently overwrite each other when spread together.

View Original GitHub Description

Summary

Foundational PR for CAT-2691: Creates the facade methods that will allow consumers to stop accessing workflowsStore.workflowObject directly.

useWorkflowDocumentGraph — graph traversal: getParentNodes, getChildNodes, getParentNodesByDepth, getConnectionsBetweenNodes, getNodeByName, getStartNode (delegates to workflowObject internally)
useWorkflowDocumentExpression — expression resolution: resolveParameterValue, resolveSimpleParameterValue, convertExpressionValueToString (delegates to workflowObject.expression internally)
Compile-time collision detection — AssertNoOverlap type guard catches key collisions between composables at typecheck time (with SharedKeys exclusion for intentionally shared keys like onStateDirty)
ESLint guard — prevents new direct workflowsStore.workflowObject access
@deprecated tag on workflowObject in workflows.store.ts
Contract tests for both composables verifying delegation behavior

This is the foundation PR — subsequent PRs will migrate ~35 consumer usages across ~20 files to use these facade methods.

Related Linear ticket(s)

https://linear.app/n8n/issue/CAT-2691

Review / Merge checklist

Contract tests pass
Typecheck passes
ESLint guard blocks new direct access

Test plan

Unit tests for useWorkflowDocumentGraph (graph traversal delegation)
Unit tests for useWorkflowDocumentExpression (expression resolution delegation)
Typecheck passes (collision detection works)
ESLint guard triggers on workflowsStore.workflowObject access