Errors

Plexis throws PlexisError for all runtime errors. It extends the native Error class and carries a typed code field so errors can be handled programmatically.

PlexisError

PlexisError extends Error.

Field	Type	Required	Description
code	string	Yes	One of the error codes below
domainId	string	No	Domain ID, when the error originated in a domain
pipelineId	string	No	Pipeline ID, when the error originated in a pipeline
nodeId	string	No	Node ID, when the error is node-specific
context	unknown	No	Snapshot of the context at the time of the error

Error codes

Code	Description
UNKNOWN_EVENT	follow() was called with an event that has no matching on handler and strict is true
PHASE_MISMATCH	followFrom() was called but the current phase does not match the expected phase
UNKNOWN_INITIAL_PHASE	The initial ID from the domain setup does not match any registered phase
UNKNOWN_INITIAL_NODE	The initial ID from the pipeline setup does not match any registered node
UNKNOWN_TARGET_PHASE	An event target does not match any registered phase
UNKNOWN_TARGET_NODE	A fork target does not match any registered node
UNKNOWN_NODE	inspectNode() was called with an ID that does not exist
BUILDER_CLOSED	A registration helper was called outside an active defineDomain or definePipeline setup function

Example

import { defineDomain, when, on, target, terminal } from '@tde.io/plexis';
import type { PlexisError } from '@tde.io/plexis';

const order = defineDomain('order', () => {
  when('pending', () => {
    on('submit', target('processing'));
  });
  when('processing', terminal());
  return { context: {}, initial: 'pending', strict: true };
});

try {
  await order.follow('cancel'); // no 'cancel' event + strict: true
} catch (err) {
  const e = err as PlexisError;
  if (e.code === 'UNKNOWN_EVENT') {
    console.log('No event handler:', e.message);
    console.log('Domain:', e.domainId);
  }
}

Example: handling PHASE_MISMATCH

try {
  await order.followFrom('processing', 'submit'); // domain is in 'pending'
} catch (err) {
  const e = err as PlexisError;
  if (e.code === 'PHASE_MISMATCH') {
    console.log('Expected phase mismatch:', e.message);
  }
}

Example: catching BUILDER_CLOSED

import { when } from '@tde.io/plexis';
import type { PlexisError } from '@tde.io/plexis';

try {
  when('orphan', () => {}); // called outside a setup function
} catch (err) {
  const e = err as PlexisError;
  console.log(e.code); // 'BUILDER_CLOSED'
}