route

CORE · function · Runtime value

Import

TypeScript

import { route } from '@jangts/agent-core/engine';

JavaScript

import { route } from '@jangts/agent-core/engine';

Other public entry points:@jangts/agent-core, @jangts/agent-core/engine, @jangts/agent-core/types.

Definition

Call

route(target: string, id?: string): { id: string; targetNodeId: string; }

Parameter	Type	Passing	Description
target	string	Required	—
id	string | undefined	Optional	—

Returns: { id: string; targetNodeId: string; }.

Return value structure

Field	Type	Required	Description
id	string	Required	See the type definition and usage context.
targetNodeId	string	Required	See the type definition and usage context.

Member index

Member	Purpose
to	See the overload below for full inputs and outputs.
toIfEqual	See the overload below for full inputs and outputs.
toIfEqualWith	See the overload below for full inputs and outputs.
toIfNotEmpty	See the overload below for full inputs and outputs.
toIfDefined	See the overload below for full inputs and outputs.
toIf	See the overload below for full inputs and outputs.
toIfError	See the overload below for full inputs and outputs.
deliver	See the overload below for full inputs and outputs.
deliverIfReady	See the overload below for full inputs and outputs.
deliverWhenComplete	See the overload below for full inputs and outputs.

Member details

to

route.to(target: string, id?: string): { id: string; targetNodeId: string; }

Parameter	Type	Passing	Description
target	string	Required	—
id	string | undefined	Optional	—

Returns: { id: string; targetNodeId: string; }.

Return value structure

Field	Type	Required	Description
id	string	Required	See the type definition and usage context.
targetNodeId	string	Required	See the type definition and usage context.

toIfEqual

route.toIfEqual<Key extends PropertyKey, Value>(target: string, path: Key, value: Value, options?: RouteOptions): { id: string | undefined; conditionId: string | undefined; when: (state: Partial<Record<PathRoot<Key>, unknown>>) => boolean; targetNodeId: string; description?: string; }

One conditional jump, using the same strict equality as a handwritten route.

A derived route id is only produced for symbol-free paths and primitive values, because those are the cases where String(value) is stable and unique enough to name the condition.

Type parameter	Constraint	Default type
Key	PropertyKey	—
Value	—	—

Parameter	Type	Passing	Description
target	string	Required	—
path	Key	Required	—
value	Value	Required	—
options	RouteOptions | undefined	Optional	—

Optional shapes of Parameter options: choose one shape; required fields for each branch are listed separately.

Branch 1

undefined

Branch 2

Field	Type	Required	Description
id	string | undefined	Optional	Read-only. Explicit route id; otherwise derived from the target so it stays stable.
conditionId	string | undefined	Optional	Read-only. Condition identity template; {nid} and {rid} are replaced when the node registers.
description	string | undefined	Optional	Read-only. Human-readable description surfaced by describe().

Returns: { id: string \| undefined; conditionId: string \| undefined; when: (state: Partial<Record<PathRoot<Key>, unknown>>) => boolean; targetNodeId: string; description?: string; }.

Return value structure

Field	Type	Required	Description
id	string | undefined	Required	See the type definition and usage context.
conditionId	string | undefined	Required	See the type definition and usage context.
when	(state: Partial<Record<PathRoot<Key>, unknown>>) => boolean	Required	See the type definition and usage context.
targetNodeId	string	Required	See the type definition and usage context.
description	string | undefined	Optional	Read-only. Human-readable description surfaced by describe().

toIfEqualWith

route.toIfEqualWith<Left extends PropertyKey, Right extends PropertyKey>(target: string, leftPath: Left, rightPath: Right, options?: RouteOptions): { id: string | undefined; conditionId: string | undefined; when: (state: Partial<Record<PathRoot<Left> | PathRoot<Right>, unknown>>) => boolean; targetNodeId: string; description?: string; }

Jump when two state paths resolve to strictly equal values.

No derived route id is produced for symbol paths, because a symbol cannot be embedded in a stable name.

Type parameter	Constraint	Default type
Left	PropertyKey	—
Right	PropertyKey	—

Parameter	Type	Passing	Description
target	string	Required	—
leftPath	Left	Required	—
rightPath	Right	Required	—
options	RouteOptions | undefined	Optional	—

Optional shapes of Parameter options: choose one shape; required fields for each branch are listed separately.

Branch 1

undefined

Branch 2

Field	Type	Required	Description
id	string | undefined	Optional	Read-only. Explicit route id; otherwise derived from the target so it stays stable.
conditionId	string | undefined	Optional	Read-only. Condition identity template; {nid} and {rid} are replaced when the node registers.
description	string | undefined	Optional	Read-only. Human-readable description surfaced by describe().

Returns: { id: string \| undefined; conditionId: string \| undefined; when: (state: Partial<Record<PathRoot<Left> \| PathRoot<Right>, unknown>>) => boolean; targetNodeId: string; description?: string; }.

Return value structure

Field	Type	Required	Description
id	string | undefined	Required	See the type definition and usage context.
conditionId	string | undefined	Required	See the type definition and usage context.
when	(state: Partial<Record<PathRoot<Left> | PathRoot<Right>, unknown>>) => boolean	Required	See the type definition and usage context.
targetNodeId	string	Required	See the type definition and usage context.
description	string | undefined	Optional	Read-only. Human-readable description surfaced by describe().

toIfNotEmpty

route.toIfNotEmpty<Key extends PropertyKey>(target: string, key: Key, options?: RouteOptions): { conditionId: string; when: (state: Partial<Record<PathRoot<Key>, unknown>>) => boolean; id: string; targetNodeId: string; description?: string; }

Jump when a state array contains at least one entry.

A non-array value never matches, so a mistyped field cannot be treated as populated.

Type parameter	Constraint	Default type
Key	PropertyKey	—

Parameter	Type	Passing	Description
target	string	Required	—
key	Key	Required	—
options	RouteOptions | undefined	Optional	—

Optional shapes of Parameter options: choose one shape; required fields for each branch are listed separately.

Branch 1

undefined

Branch 2

Field	Type	Required	Description
id	string | undefined	Optional	Read-only. Explicit route id; otherwise derived from the target so it stays stable.
conditionId	string | undefined	Optional	Read-only. Condition identity template; {nid} and {rid} are replaced when the node registers.
description	string | undefined	Optional	Read-only. Human-readable description surfaced by describe().

Returns: { conditionId: string; when: (state: Partial<Record<PathRoot<Key>, unknown>>) => boolean; id: string; targetNodeId: string; description?: string; }.

Return value structure

Field	Type	Required	Description
conditionId	string	Required	See the type definition and usage context.
when	(state: Partial<Record<PathRoot<Key>, unknown>>) => boolean	Required	See the type definition and usage context.
id	string	Required	See the type definition and usage context.
targetNodeId	string	Required	See the type definition and usage context.
description	string | undefined	Optional	Read-only. Human-readable description surfaced by describe().

toIfDefined

route.toIfDefined<Key extends PropertyKey>(target: string, field: Key, options?: RouteOptions): { conditionId: string; when: (state: Partial<Record<PathRoot<Key>, unknown>>) => boolean; id: string; targetNodeId: string; description?: string; }

Jump once a state field has a value.

null counts as present: only undefined means the field is still unset.

Type parameter	Constraint	Default type
Key	PropertyKey	—

Parameter	Type	Passing	Description
target	string	Required	—
field	Key	Required	—
options	RouteOptions | undefined	Optional	—

Optional shapes of Parameter options: choose one shape; required fields for each branch are listed separately.

Branch 1

undefined

Branch 2

Field	Type	Required	Description
id	string | undefined	Optional	Read-only. Explicit route id; otherwise derived from the target so it stays stable.
conditionId	string | undefined	Optional	Read-only. Condition identity template; {nid} and {rid} are replaced when the node registers.
description	string | undefined	Optional	Read-only. Human-readable description surfaced by describe().

Returns: { conditionId: string; when: (state: Partial<Record<PathRoot<Key>, unknown>>) => boolean; id: string; targetNodeId: string; description?: string; }.

Return value structure

Field	Type	Required	Description
conditionId	string	Required	See the type definition and usage context.
when	(state: Partial<Record<PathRoot<Key>, unknown>>) => boolean	Required	See the type definition and usage context.
id	string	Required	See the type definition and usage context.
targetNodeId	string	Required	See the type definition and usage context.
description	string | undefined	Optional	Read-only. Human-readable description surfaced by describe().

toIf

route.toIf<Key extends string>(target: Key, options?: RouteOptions): { when: (state: Partial<Record<Key, unknown>>) => boolean; conditionId: string; id: string; targetNodeId: string; description?: string; }

Jump to the node named by a truthy state field.

The same field is used as the condition and as the destination, which is the usual shape of a dispatcher that stored its own next node.

Type parameter	Constraint	Default type
Key	string	—

Parameter	Type	Passing	Description
target	Key	Required	—
options	RouteOptions | undefined	Optional	—

Optional shapes of Parameter options: choose one shape; required fields for each branch are listed separately.

Branch 1

undefined

Branch 2

Field	Type	Required	Description
id	string | undefined	Optional	Read-only. Explicit route id; otherwise derived from the target so it stays stable.
conditionId	string | undefined	Optional	Read-only. Condition identity template; {nid} and {rid} are replaced when the node registers.
description	string | undefined	Optional	Read-only. Human-readable description surfaced by describe().

Returns: { when: (state: Partial<Record<Key, unknown>>) => boolean; conditionId: string; id: string; targetNodeId: string; description?: string; }.

Return value structure

Field	Type	Required	Description
when	(state: Partial<Record<Key, unknown>>) => boolean	Required	See the type definition and usage context.
conditionId	string	Required	See the type definition and usage context.
id	string	Required	See the type definition and usage context.
targetNodeId	string	Required	See the type definition and usage context.
description	string | undefined	Optional	Read-only. Human-readable description surfaced by describe().

toIfError

route.toIfError<Key extends PropertyKey>(target: string, options: RouteOptions & { readonly errorKey: Key; }): ReturnType<typeof toIfDefined<Key>>

Route a recorded state error to its recovery node.

Defaults to the error field because that is the convention the engine relies on when reporting recoverable failures.

Type parameter	Constraint	Default type
Key	PropertyKey	—

Parameter	Type	Passing	Description
target	string	Required	—
options	RouteOptions & { readonly errorKey: Key; }	Required	—

Fields of options

Field	Type	Required	Description
id	string | undefined	Optional	Read-only. Explicit route id; otherwise derived from the target so it stays stable.
conditionId	string | undefined	Optional	Read-only. Condition identity template; {nid} and {rid} are replaced when the node registers.
description	string | undefined	Optional	Read-only. Human-readable description surfaced by describe().
errorKey	Key	Required	Read-only. See the type definition and usage context.

Returns: { conditionId: string; when: (state: Partial<Record<PathRoot<Key>, unknown>>) => boolean; id: string; targetNodeId: string; description?: string; }.

Return value structure

Field	Type	Required	Description
conditionId	string	Required	See the type definition and usage context.
when	(state: Partial<Record<PathRoot<Key>, unknown>>) => boolean	Required	See the type definition and usage context.
id	string	Required	See the type definition and usage context.
targetNodeId	string	Required	See the type definition and usage context.
description	string | undefined	Optional	Read-only. Human-readable description surfaced by describe().

route.toIfError(target: string, options?: RouteOptions & { readonly errorKey?: undefined; }): ReturnType<typeof toIfDefined<"error">>

Parameter	Type	Passing	Description
target	string	Required	—
options	(RouteOptions & { readonly errorKey?: undefined; }) | undefined	Optional	—

Optional shapes of Parameter options: choose one shape; required fields for each branch are listed separately.

Branch 1

undefined

Branch 2

Field	Type	Required	Description
id	string | undefined	Optional	Read-only. Explicit route id; otherwise derived from the target so it stays stable.
conditionId	string | undefined	Optional	Read-only. Condition identity template; {nid} and {rid} are replaced when the node registers.
description	string | undefined	Optional	Read-only. Human-readable description surfaced by describe().
errorKey	undefined	Optional	Read-only. See the type definition and usage context.

Returns: { conditionId: string; when: (state: Partial<Record<"error", unknown>>) => boolean; id: string; targetNodeId: string; description?: string; }.

Return value structure

Field	Type	Required	Description
conditionId	string	Required	See the type definition and usage context.
when	(state: Partial<Record<"error", unknown>>) => boolean	Required	See the type definition and usage context.
id	string	Required	See the type definition and usage context.
targetNodeId	string	Required	See the type definition and usage context.
description	string | undefined	Optional	Read-only. Human-readable description surfaced by describe().

deliver

route.deliver<Key extends PropertyKey>(field: Key, options?: Omit<RouteOptions, "conditionId">): { id: string; complete: <State extends Partial<Record<Key, unknown>>>(state: State) => Exclude<State[Key], undefined>; description?: string; }

At a terminal node, the result must already exist.

Completing reads the field with requireWorkflowValue, so a node that forgot to produce its result fails instead of returning undefined.

Type parameter	Constraint	Default type
Key	PropertyKey	—

Parameter	Type	Passing	Description
field	Key	Required	—
options	Omit<RouteOptions, "conditionId"> | undefined	Optional	—

Optional shapes of Parameter options: choose one shape; required fields for each branch are listed separately.

Branch 1

undefined

Branch 2

Field	Type	Required	Description
id	string | undefined	Optional	Read-only. Explicit route id; otherwise derived from the target so it stays stable.
description	string | undefined	Optional	Read-only. Human-readable description surfaced by describe().

Returns: { id: string; complete: <State extends Partial<Record<Key, unknown>>>(state: State) => Exclude<State[Key], undefined>; description?: string; }.

Return value structure

Field	Type	Required	Description
id	string	Required	See the type definition and usage context.
complete	<State extends Partial<Record<Key, unknown>>>(state: State) => Exclude<State[Key], undefined>	Required	See the type definition and usage context.
description	string | undefined	Optional	Read-only. Human-readable description surfaced by describe().

deliverIfReady

route.deliverIfReady<Key extends PropertyKey>(field: Key, options?: RouteOptions): { conditionId: string; when: (state: Partial<Record<Key, unknown>>) => boolean; id: string; complete: <State extends Partial<Record<Key, unknown>>>(state: State) => Exclude<State[Key], undefined>; description?: string; }

Deliver an available result, or let the next route decide.

Unlike deliver, this route carries a condition so a following route still has a chance to match when the field is still unset.

Type parameter	Constraint	Default type
Key	PropertyKey	—

Parameter	Type	Passing	Description
field	Key	Required	—
options	RouteOptions | undefined	Optional	—

Optional shapes of Parameter options: choose one shape; required fields for each branch are listed separately.

Branch 1

undefined

Branch 2

Field	Type	Required	Description
id	string | undefined	Optional	Read-only. Explicit route id; otherwise derived from the target so it stays stable.
conditionId	string | undefined	Optional	Read-only. Condition identity template; {nid} and {rid} are replaced when the node registers.
description	string | undefined	Optional	Read-only. Human-readable description surfaced by describe().

Returns: { conditionId: string; when: (state: Partial<Record<Key, unknown>>) => boolean; id: string; complete: <State extends Partial<Record<Key, unknown>>>(state: State) => Exclude<State[Key], undefined>; description?: string; }.

Return value structure

Field	Type	Required	Description
conditionId	string	Required	See the type definition and usage context.
when	(state: Partial<Record<Key, unknown>>) => boolean	Required	See the type definition and usage context.
id	string	Required	See the type definition and usage context.
complete	<State extends Partial<Record<Key, unknown>>>(state: State) => Exclude<State[Key], undefined>	Required	See the type definition and usage context.
description	string | undefined	Optional	Read-only. Human-readable description surfaced by describe().

deliverWhenComplete

route.deliverWhenComplete<Key extends PropertyKey>(field: Key, options?: RouteOptions): { id: string; conditionId: string; when: (state: Partial<Record<Key, StepOutcome<unknown>>>) => boolean; complete<Value>(state: Partial<Record<Key, StepOutcome<Value>>>): Value; description?: string; }

Apply the shared continue/complete outcome contract.

The field holds a StepOutcome; only the complete variant ends the workflow, and the completion asserts the variant instead of trusting the condition.

Type parameter	Constraint	Default type
Key	PropertyKey	—

Parameter	Type	Passing	Description
field	Key	Required	—
options	RouteOptions | undefined	Optional	—

Optional shapes of Parameter options: choose one shape; required fields for each branch are listed separately.

Branch 1

undefined

Branch 2

Field	Type	Required	Description
id	string | undefined	Optional	Read-only. Explicit route id; otherwise derived from the target so it stays stable.
conditionId	string | undefined	Optional	Read-only. Condition identity template; {nid} and {rid} are replaced when the node registers.
description	string | undefined	Optional	Read-only. Human-readable description surfaced by describe().

Returns: { id: string; conditionId: string; when: (state: Partial<Record<Key, StepOutcome<unknown>>>) => boolean; complete<Value>(state: Partial<Record<Key, StepOutcome<Value>>>): Value; description?: string; }.

Return value structure

Field	Type	Required	Description
id	string	Required	See the type definition and usage context.
conditionId	string	Required	See the type definition and usage context.
when	(state: Partial<Record<Key, StepOutcome<unknown>>>) => boolean	Required	See the type definition and usage context.
complete	<Value>(state: Partial<Record<Key, StepOutcome<Value>>>) => Value	Required	See the type definition and usage context.
description	string | undefined	Optional	Read-only. Human-readable description surfaced by describe().

Examples

• route: generating complete configuration and capturing common checks: The route function group generates ordinary WorkflowRoute configuration; hand-written objects and generated configuration follow the same contract.

Minimal jump and end

Beginner · Node.js

TypeScript

import { route } from '@jangts/agent-core/engine';
const jump = route('reply');
const sameJump = route.to('reply');
const finish = route.deliver('answer');
console.log(jump, sameJump, finish);

JavaScript

import { route } from '@jangts/agent-core/engine';
const jump = route('reply');
const sameJump = route.to('reply');
const finish = route.deliver('answer');
console.log(jump, sameJump, finish);

Common branches for the same business

Configuration · Node.js

TypeScript

import { route } from '@jangts/agent-core/engine';
const reviewRoutes = [
  route.toIfError('failure'),
  route.toIf('recovered'),
  route.toIfNotEmpty('candidate', 'candidates'),
  route.toIfDefined('reply', 'answer'),
  route.toIfEqual('status', 'intent.id', 'status'),
  route.toIfEqualWith('reuse', 'cache.0.id', 'request.id'),
  route.to('fallback'),
];
const completionRoutes = [route.deliverIfReady('answer'), route.to('retry')];
const outcomeRoutes = [route.deliverWhenComplete('outcome'), route.to('retry')];
console.log(reviewRoutes, completionRoutes, outcomeRoutes);

JavaScript

import { route } from '@jangts/agent-core/engine';
const reviewRoutes = [
    route.toIfError('failure'),
    route.toIf('recovered'),
    route.toIfNotEmpty('candidate', 'candidates'),
    route.toIfDefined('reply', 'answer'),
    route.toIfEqual('status', 'intent.id', 'status'),
    route.toIfEqualWith('reuse', 'cache.0.id', 'request.id'),
    route.to('fallback'),
];
const completionRoutes = [route.deliverIfReady('answer'), route.to('retry')];
const outcomeRoutes = [route.deliverWhenComplete('outcome'), route.to('retry')];
console.log(reviewRoutes, completionRoutes, outcomeRoutes);

Override identity as the business requires; hand-written objects also support placeholders

Extension · Node.js

conditionId carries no authorization. It helps logs explain which condition matched.

TypeScript

import { defineWorkflow, route } from '@jangts/agent-core/engine';
type State = { answer?: string; reviewError?: string };
const workflow = defineWorkflow<State, string>({ id: 'review', nodes: [
  { id: 'check', description: '检查既有结果', startsRound: true, routes: [
    route.toIfError('failure', { errorKey: 'reviewError', id: 'review-error' }),
    { id: 'ready', conditionId: '{nid}.{rid}', when: state => state.answer !== undefined,
      complete: state => state.answer! },
    route.to('failure'),
  ] },
  { id: 'failure', description: '给出当前缺失信息',
    run: () => ({ answer: '当前没有可交付结果' }), routes: [route.deliver('answer')] },
] });
console.log(workflow.describe());

JavaScript

import { defineWorkflow, route } from '@jangts/agent-core/engine';
const workflow = defineWorkflow({ id: 'review', nodes: [
        { id: 'check', description: '检查既有结果', startsRound: true, routes: [
                route.toIfError('failure', { errorKey: 'reviewError', id: 'review-error' }),
                { id: 'ready', conditionId: '{nid}.{rid}', when: state => state.answer !== undefined,
                    complete: state => state.answer },
                route.to('failure'),
            ] },
        { id: 'failure', description: '给出当前缺失信息',
            run: () => ({ answer: '当前没有可交付结果' }), routes: [route.deliver('answer')] },
    ] });
console.log(workflow.describe());

Related policy source

• Default rules and check process of each route generator