@rxova/journey-core 1.0.0-rc.3 → 1.0.1

package/README.md

@@ -1,282 +1,278 @@
 # @rxova/journey-core
 
-Typed state machine for multi-step UI flows.
+Typed, framework-independent state machines for multi-step product flows.
 
 <p>
   <a href="https://www.npmjs.com/package/@rxova/journey-core">
     <img src="https://img.shields.io/npm/v/@rxova/journey-core?color=0f8f6a" alt="npm" />
   </a>
-  <img src="https://img.shields.io/badge/7.58%20kB-brotli-0f8f6a" alt="size" />
-  <img src="https://img.shields.io/badge/zero%20dependencies-black" alt="zero deps" />
+  <img src="https://img.shields.io/badge/zero%20dependencies-black" alt="zero dependencies" />
   <img src="https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white" alt="TypeScript" />
 </p>
 
-`@rxova/journey-core` is approaching a `1.0.0-rc` contract freeze. The current public model is:
-
-- JSON-only runtime `context`
-- static step `meta`
-- transition-side state updates through `updateContext(...)`
-- documented lifecycle callbacks and events as the supported extension surface
+Journey owns current position, context, realized history, lifecycle status, terminal outcomes, and
+observable async transition state. Linear and graph definitions run on the same small runtime.
 
 ## Install
 
 ```bash
-npm i @rxova/journey-core
+npm install @rxova/journey-core
 ```
 
-## Quickstart
+## Linear quickstart
 
 ```ts
-import { createJourneyMachine } from "@rxova/journey-core";
-
-const machine = createJourneyMachine({
-  initial: "account",
-  context: { name: "" },
-  steps: { account: {}, details: {}, review: {} },
-  transitions: ["account", "details", "review"]
+import { createLinearJourney } from "@rxova/journey-core";
+
+type CheckoutStepId = "account" | "shipping" | "review";
+type CheckoutContext = {
+  email: string;
+  shippingId: string | null;
+};
+type CheckoutTerminationPayloads = {
+  complete: { orderId: string };
+  terminate: { reason: "cancelled" | "expired" };
+};
+
+const checkout = createLinearJourney<CheckoutStepId, CheckoutContext, CheckoutTerminationPayloads>({
+  steps: [
+    { id: "account", metadata: { title: "Account" } },
+    { id: "shipping", metadata: { title: "Shipping" } },
+    { id: "review", metadata: { title: "Review" } },
+  ],
+  context: {
+    email: "",
+    shippingId: null,
+  },
 });
 
-machine.startJourney();
-
-await machine.send({ type: "goToNextStep" }); // account → details
-await machine.send({ type: "goToNextStep" }); // details → review
-await machine.goToPreviousStep(); // review → details
+checkout.context.update((context) => ({
+  ...context,
+  email: "ada@example.com",
+}));
 
-const snap = machine.getSnapshot();
-console.log(snap.currentStepId); // "details"
-console.log(snap.history.timeline); // ["account", "details"]
-console.log(snap.status); // "running"
+await checkout.navigate.goToNextStep();
 ```
 
-## Three Transition Modes
-
-Reserved step ids: `*`, `global`, `COMPLETE`, and `TERMINATED`. They are used by the runtime and cannot be used as real step names.
-
-### Linear
-
-Array shorthand for sequential flows. Steps can carry synchronous `updateContext` transitions and timeouts.
+The first declared step is initial. String steps are shorthand when metadata and hooks are not
+needed:
 
 ```ts
-transitions: [
-  "account",
-  {
-    step: "details",
-    updateContext: ({ context }) => ({ ...context, step: 2 }),
-    timeoutMs: 5000
-  },
-  "payment",
-  "review"
-];
+createLinearJourney({
+  steps: ["account", "shipping", "review"],
+  context: {},
+});
 ```
 
-### Graph
+The optional third generic groups payloads passed to `controls.complete` and
+`controls.terminate`. It also types the corresponding `snapshot.machine.outcome`. Omit it when
+terminal payload typing is not needed.
 
-Step-keyed transitions with guards, `updateContext`, and branching.
+## Transactional navigation
+
+Pass work to next or previous navigation when an operation must succeed before movement:
 
 ```ts
-transitions: {
-  login: {
-    goToNextStep: [
-      { to: "admin", when: ({ context }) => context.role === "admin" },
-      { to: "dashboard" }
-    ]
+const result = await checkout.navigate.goToNextStep({
+  run: async ({ snapshot }) => submitShipping(snapshot.context),
+  commit: ({ result: shipping, updateContext }) => {
+    updateContext((context) => ({
+      ...context,
+      shippingId: shipping.id,
+    }));
   },
-  admin: { completeJourney: true },
-  dashboard: { completeJourney: true }
+});
+
+if (!result.ok) {
+  console.error(result.reason, result.error);
 }
 ```
 
-#### Graph Builder
+`run` is awaited while the source remains current. If it throws, rejects, or times out, neither
+position nor context changes. `commit` is synchronous; its context updates publish atomically with
+the destination.
 
-For larger flows, `createJourneyBuilder` lets each step declare its own transitions co-located with its component. It compiles to the same `JourneyDefinition` — no new runtime concepts.
+`goToPreviousStep()` accepts the same work contract.
 
-```ts
-// builder.ts — typed singleton
-const { createStep, to, build } = createJourneyBuilder<Context, StepId, EventMap>();
-
-// steps/login.step.ts — co-located with Login.tsx
-export const loginStep = createStep("login", {
-  on: {
-    submit: [to("admin").when(({ context }) => context.role === "admin"), to("dashboard")]
-  }
-});
+## Async state
 
-// journey.ts — one-screen assembly
-const definition = build({
-  initial: "login",
-  context: { role: "user" },
-  steps: [loginStep, adminStep, dashboardStep]
-});
-```
-
-Use the **factory form** when you need `event.payload` narrowed to the specific event type:
+Use `snapshot.transition.pending` as the normal UI-level loading flag:
 
 ```ts
-submit: ({ to }) => [to("admin").when(({ context, event }) => event.payload?.username !== "")];
+const snapshot = checkout.getSnapshot();
+continueButton.disabled = snapshot.transition.pending;
 ```
 
-Each transition modifier is single-use at the type level. Calling `.when()`, `.updateContext()`,
-`.onEnter()`, `.onLeave()`, `.label()`, or `.timeoutMs()` twice on the same builder is a TypeScript error. If you bypass the type system, runtime keeps the existing last-call-wins behavior.
+For diagnostics and richer feedback, `snapshot.transition` identifies the `working`, `leaving`, or
+`entering` phase, source, and destination. `snapshot.currentStep.async` records loading, success,
+and error state for the current entry.
+
+Only one navigation settles at a time. Concurrent calls resolve with
+`{ ok: false, reason: "transitioning" }`.
 
-### Headless
+## Lifecycle effects
 
-Omit `transitions` entirely. The machine holds state, history, and context, but the caller decides where to go. Useful for custom renderers, server-driven flows, or when the navigation logic lives outside the definition.
+`onLeave` and `onEnter` are awaited post-commit effects. They cannot cancel or roll back movement:
 
 ```ts
-const machine = createJourneyMachine({
-  initial: "start",
-  context: {},
-  steps: { start: {}, configure: {}, confirm: {} }
-  // no transitions — the caller drives the flow
+const machine = createLinearJourney({
+  context: { receiptId: null as string | null },
+  steps: [
+    {
+      id: "payment",
+      onLeave: ({ snapshot }) => analytics.track("payment_left", snapshot.context),
+    },
+    {
+      id: "receipt",
+      onEnter: async ({ snapshot, updateContext }) => {
+        const receipt = await loadReceipt(snapshot.context);
+        updateContext((context) => ({ ...context, receiptId: receipt.id }));
+      },
+    },
+  ],
 });
-
-machine.startJourney();
-await machine.goToStepById("configure");
-await machine.goToStepById("confirm");
-await machine.goToPreviousStep(); // back to configure
-await machine.completeJourney();
 ```
 
-In headless mode, `goToStepById(...)` is the navigation primitive. `goToNextStep()` and custom events are explicit no-ops until you define transitions and move into linear or graph mode.
+Use navigation work for validation or submission that must prevent movement. Use hooks for cleanup,
+analytics, and destination setup after the move has committed.
 
-After `dispose()`, send-style APIs resolve with `transitioned: false` and `error: JourneyDisposedError`. Control APIs such as `startJourney()` and `updateContext()` stay no-op and emit a development warning.
+## Navigation and history
 
-`updateContext()` is the ordered context-write API. It runs through the same queue as `send()`, so it applies against the latest committed snapshot when it executes.
+```ts
+await checkout.navigate.goToNextStep();
+await checkout.navigate.goToPreviousStep();
+await checkout.navigate.goToPreviousStep(2);
+await checkout.navigate.goToLastVisitedStep();
+```
 
-## Step Lifecycle
+Linear history behaves like a browser timeline. Going back preserves the future; appending a new
+destination from an older position replaces the abandoned future.
 
-Run side effects when a step is entered or left by attaching `onEnter` / `onLeave` directly to the step definition. Both callbacks receive the current `context` and are observational. They do not change transition selection or mutate context. Use transition `updateContext` for synchronous state commits that belong to the transition itself.
+`goToStepById(id)` is an intentional escape hatch for occasional direct jumps in an otherwise
+ordered flow:
 
 ```ts
-const machine = createJourneyMachine({
-  context: { username: "" },
-  steps: {
-    login: {
-      onLeave: ({ context }) => analytics.track("login_left", { user: context.username })
-    },
-    dashboard: {
-      onEnter: ({ context }) => analytics.track("dashboard_entered"),
-      onLeave: ({ context }) => console.log("leaving dashboard")
-    }
-  },
-  transitions: ["login", "dashboard"]
-});
+await checkout.navigate.goToStepById("review");
 ```
 
-With the graph builder, callbacks sit alongside transitions on the step:
+It is ungated and can reach any declared linear step. When named jumps, branching, or guarded
+destinations become normal flow behavior, move the definition to graph mode.
 
-```ts
-const dashboardStep = createStep("dashboard", {
-  onEnter: ({ context }) => analytics.track("dashboard_entered"),
-  onLeave: ({ context }) => console.log("leaving dashboard"),
-  on: { submit: [to("review")] }
-});
-```
+## Completion and termination
 
-In React, use `useJourneyStepLifecycle` when the callback needs access to component state or React context:
+Reaching the last linear step does not complete the machine. A final screen is a position;
+completion is an explicit product outcome:
 
-```tsx
-const { useJourneyStepLifecycle } = createJourney(definition);
+```ts
+checkout.controls.complete({ orderId: "order-42" });
 
-function Dashboard() {
-  useJourneyStepLifecycle("dashboard", {
-    onEnter: ({ context }) => analytics.track("dashboard_entered"),
-    onLeave: ({ context }) => console.log("leaving dashboard")
-  });
-  // ...
-}
+checkout.getSnapshot().machine.outcome;
+// { type: "completed", payload: { orderId: "order-42" } }
 ```
 
-The hook always calls the latest version of your callbacks without re-subscribing.
+Use `controls.terminate(payload?)` for an unsuccessful or cancelled terminal outcome. Navigation is
+rejected after either terminal state until `controls.restart()` begins a fresh run.
 
-## Features
+## Snapshot and subscriptions
 
-- **Async guards** — `when` can be async, with per-transition `timeoutMs` and `AbortSignal`-based cancellation. Step async state is tracked in `snapshot.async.byStep[stepId]` (`idle`, `evaluating-when`, `error`)
-- **Timeline history** — `goToPreviousStep()`, `goToLastVisitedStep()`, deterministic back/forward. Snapshot exposes `history.timeline` and `history.index` so you always know where the user has been
-- **Computed state** — `getComputed()` returns derived flags: `isFirstStep`, `isLastStep`, `isLoading`, `isComplete`, `isTerminated`, `activeStepIndex`, `stepCount`, `mode` (`linear` | `graph` | `headless`)
-- **Observability** — `subscribeEvent()` streams typed lifecycle events: `journey.start`, `transition.start`, `transition.success`, `step.enter`, `step.exit`, `journey.completed`, `journey.terminated`, and more
-- **Step metadata** — attach typed metadata per step and read it with `getStepMeta(stepId)`. Metadata is definition data, not mutable runtime state
-- **Terminal events** — `completeJourney()` and `terminateJourney()` with typed payloads. Once terminal, all navigation no-ops until `resetJourney()`
-- **Snapshot** — one object holds everything that changes at runtime: `currentStepId`, `context`, `history`, `visited`, `status` (`idled`, `running`, `completed`, `terminated`), and `async`
-- **Global transitions** — cross-cutting handlers via the `global` key, useful for close-confirmation or abort flows
+All changing state lives in one immutable snapshot:
 
-## Persistence
+```ts
+const snapshot = checkout.getSnapshot();
+
+snapshot.status; // "idle" | "running" | "paused" | "completed" | "terminated"
+snapshot.context;
+snapshot.currentStep?.id;
+snapshot.currentStep?.index;
+snapshot.history.timeline;
+snapshot.history.canGoBack;
+snapshot.transition.pending;
+snapshot.machine.outcome;
+```
+
+Subscribe to every committed snapshot, or to a named lifecycle event:
 
 ```ts
-import { createPersistencePlugin } from "@rxova/journey-core/persistence";
+const stop = checkout.subscriptions.subscribe(() => render(checkout.getSnapshot().currentStep?.id));
 
-const machine = createJourneyMachine(definition, {
-  plugins: [
-    createPersistencePlugin({
-      key: "checkout",
-      version: 2,
-      blockList: ["payment.cardNumber"]
-    })
-  ]
+checkout.subscriptions.subscribeEvent("navigationBlocked", ({ reason, error }) => {
+  reportNavigationFailure(reason, error);
 });
+
+stop();
 ```
 
-Versioned snapshot storage with migrations, context allow/block lists, and configurable reset behavior. Defaults to `localStorage` when available.
+## Graph mode
 
-If `migrate(...)` returns data that no longer matches a valid snapshot, Journey reports the error through `onError` (or a development warning when `onError` is omitted) and falls back to the initial snapshot.
+Use `createGraphJourney` when named events, guards, or branches choose destinations. Graph machines
+add typed `send(type, payload?)`, available events and targets in the snapshot, and transition-level
+post-commit effects.
 
-## Autosave
+Candidates take an optional `label`, which names the edge in timeout and error messages, in the
+`transition` argument every step hook receives, and in the structure view plugins read — several
+candidates on one event differ only by guard, so `event` and `to` do not tell them apart. They also
+take an optional `timeoutMs`, as does a declared work entry, overriding `defaultTimeoutMs` for that
+one edge so a single slow third-party call does not set the budget for the whole graph.
 
-```ts
-import { createAutosavePlugin } from "@rxova/journey-core/autosave";
+For larger graphs, `withGraphTypes<Bag>()` pins the types once and `GraphStep<Bag>` lets each step live in its own file, and
+`defineWork<Bag, "EVENT">()` reads a work entry's result type off its `run` instead of restating it
+in the bag. See the [Graph guide](https://rxova.dev/docs/core/usage/graph).
 
-const machine = createJourneyMachine(definition, {
-  plugins: [
-    createAutosavePlugin({
-      key: "checkout-draft",
-      debounceMs: 300,
-      allowList: ["profile", "shipping"]
-    })
-  ]
-});
+## Connectors
 
-await machine.flushAutosave();
+Connectors adapt optional third-party libraries to existing Core primitives without attaching a
+plugin to the machine. The Immer connector turns a synchronous producer into a context updater:
+
+```bash
+pnpm add immer
+```
+
+```ts
+import { immerConnector } from "@rxova/journey-core/connectors/immer";
+
+machine.context.update(
+  immerConnector<CheckoutContext>((draft) => {
+    draft.cart.items.push(item);
+    draft.cart.total += item.price;
+  }),
+);
 ```
 
-Autosave adds debounced draft persistence, hydration, `getAutosaveState()`, `flushAutosave()`, and `clearAutosave()` without requiring the persistence plugin as a separate public dependency.
+It also works with the `updateContext` passed to hooks and transactional commits. Immer remains an
+optional peer, so consumers that do not import this connector do not install or bundle it. See the
+[Immer connector guide](https://rxova.dev/docs/core/connectors/immer) for replacement recipes,
+freezing, draftability, and transactional behavior.
 
-## Analytics
+## Plugins
+
+Built-in plugins are separately imported and observe the machine through a read-only host:
 
 ```ts
-import { createAnalyticsPlugin } from "@rxova/journey-core/analytics";
+import { createLinearJourney } from "@rxova/journey-core";
+import { createAnalyticsPlugin } from "@rxova/journey-core/plugins";
 
-const machine = createJourneyMachine(definition, {
+const machine = createLinearJourney(definition, {
   plugins: [
     createAnalyticsPlugin({
-      machineId: "checkout",
-      track: (event) => analytics.track(event.name, event.payload)
-    })
-  ]
+      track: (event) => analytics.track(event.name, event.payload),
+    }),
+  ],
 });
 ```
 
-Analytics normalizes Journey lifecycle events into a stable event envelope and adds `trackAnalyticsEvent(...)` for custom markers.
-
-## DevTools
-
-```ts
-import { attachJourneyDevtools } from "@rxova/journey-devtools-bridge";
-
-const detach = attachJourneyDevtools(machine, { label: "Checkout" });
-```
+Persistence, analytics, replay, and execution paths each have dedicated export paths and
+documentation. `analyzeStructure(definition)` checks a graph for unreachable steps, shadowed
+transitions and cycles without creating a machine.
 
 ## Documentation
 
-- [Pre-1.0 Migration](https://rxova.org/docs/core/pre-1-0-migration)
-- [Stability Contract](https://rxova.org/docs/core/stability)
-- [Quickstart](https://rxova.org/docs/core/getting-started)
-- [Usage Modes](https://rxova.org/docs/core/usage)
-- [Async Lifecycle](https://rxova.org/docs/core/async)
-- [Persistence](https://rxova.org/docs/core/persistence)
-- [Autosave](https://rxova.org/docs/core/autosave)
-- [Analytics Plugin](https://rxova.org/docs/core/plugins/analytics-plugin)
-- [Plugins](https://rxova.org/docs/core/plugins/overview)
-- [API Reference](https://rxova.org/docs/core/api/overview)
+- [Quickstart](https://rxova.dev/docs/core/getting-started)
+- [Linear journeys](https://rxova.dev/docs/core/usage/linear)
+- [Async behavior](https://rxova.dev/docs/core/async)
+- [Machine API](https://rxova.dev/docs/core/api/machine-api)
+- [Snapshot](https://rxova.dev/docs/core/snapshot)
+- [Pre-1.0 migration](https://rxova.dev/docs/core/pre-1-0-migration)
+- [Stability contract](https://rxova.dev/docs/core/stability)
 
 ## License
 

package/dist/connectors/immer/immer.cjs

@@ -0,0 +1,2 @@
+"use strict";var m=Object.defineProperty;var i=Object.getOwnPropertyDescriptor;var x=Object.getOwnPropertyNames;var C=Object.prototype.hasOwnProperty;var c=(t,e)=>{for(var r in e)m(t,r,{get:e[r],enumerable:!0})},y=(t,e,r,p)=>{if(e&&typeof e=="object"||typeof e=="function")for(let o of x(e))!C.call(t,o)&&o!==r&&m(t,o,{get:()=>e[o],enumerable:!(p=i(e,o))||p.enumerable});return t};var f=t=>y(m({},"__esModule",{value:!0}),t);var s={};c(s,{immerConnector:()=>d});module.exports=f(s);var n=require("immer");function d(t){return e=>(0,n.produce)(e,t)}0&&(module.exports={immerConnector});
+//# sourceMappingURL=immer.cjs.map

package/dist/connectors/immer/immer.cjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/connectors/immer/immer.ts"],
+  "sourcesContent": ["import { produce } from \"immer\";\nimport type { ContextUpdater } from \"../../core/types\";\nimport type { ImmerContextRecipe } from \"./immer.types\";\n\nexport type { ImmerContextRecipe } from \"./immer.types\";\n\n/**\n * Converts a synchronous Immer recipe into a Journey context updater.\n *\n * Pass the result to `machine.context.update`, a hook's `updateContext`, or a\n * transactional work commit. Immer supplies structural sharing and applies its\n * normal draftability and auto-freezing behavior.\n */\nexport function immerConnector<TContext>(\n  recipe: ImmerContextRecipe<TContext>,\n): ContextUpdater<TContext> {\n  return (previous) => produce(previous, recipe);\n}\n"],
+  "mappings": "yaAAA,IAAAA,EAAA,GAAAC,EAAAD,EAAA,oBAAAE,IAAA,eAAAC,EAAAH,GAAA,IAAAI,EAAwB,iBAajB,SAASF,EACdG,EAC0B,CAC1B,OAAQC,MAAa,WAAQA,EAAUD,CAAM,CAC/C",
+  "names": ["immer_exports", "__export", "immerConnector", "__toCommonJS", "import_immer", "recipe", "previous"]
+}

package/dist/connectors/immer/immer.d.cts

@@ -0,0 +1,11 @@
+import type { ContextUpdater } from "../../core/types.js";
+import type { ImmerContextRecipe } from "./immer.types.js";
+export type { ImmerContextRecipe } from "./immer.types.js";
+/**
+ * Converts a synchronous Immer recipe into a Journey context updater.
+ *
+ * Pass the result to `machine.context.update`, a hook's `updateContext`, or a
+ * transactional work commit. Immer supplies structural sharing and applies its
+ * normal draftability and auto-freezing behavior.
+ */
+export declare function immerConnector<TContext>(recipe: ImmerContextRecipe<TContext>): ContextUpdater<TContext>;

package/dist/connectors/immer/immer.d.ts

@@ -0,0 +1,11 @@
+import type { ContextUpdater } from "../../core/types.js";
+import type { ImmerContextRecipe } from "./immer.types.js";
+export type { ImmerContextRecipe } from "./immer.types.js";
+/**
+ * Converts a synchronous Immer recipe into a Journey context updater.
+ *
+ * Pass the result to `machine.context.update`, a hook's `updateContext`, or a
+ * transactional work commit. Immer supplies structural sharing and applies its
+ * normal draftability and auto-freezing behavior.
+ */
+export declare function immerConnector<TContext>(recipe: ImmerContextRecipe<TContext>): ContextUpdater<TContext>;

package/dist/connectors/immer/immer.js

@@ -0,0 +1,2 @@
+import{produce as o}from"immer";function m(e){return t=>o(t,e)}export{m as immerConnector};
+//# sourceMappingURL=immer.js.map

package/dist/connectors/immer/immer.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/connectors/immer/immer.ts"],
+  "sourcesContent": ["import { produce } from \"immer\";\nimport type { ContextUpdater } from \"../../core/types\";\nimport type { ImmerContextRecipe } from \"./immer.types\";\n\nexport type { ImmerContextRecipe } from \"./immer.types\";\n\n/**\n * Converts a synchronous Immer recipe into a Journey context updater.\n *\n * Pass the result to `machine.context.update`, a hook's `updateContext`, or a\n * transactional work commit. Immer supplies structural sharing and applies its\n * normal draftability and auto-freezing behavior.\n */\nexport function immerConnector<TContext>(\n  recipe: ImmerContextRecipe<TContext>,\n): ContextUpdater<TContext> {\n  return (previous) => produce(previous, recipe);\n}\n"],
+  "mappings": "AAAA,OAAS,WAAAA,MAAe,QAajB,SAASC,EACdC,EAC0B,CAC1B,OAAQC,GAAaH,EAAQG,EAAUD,CAAM,CAC/C",
+  "names": ["produce", "immerConnector", "recipe", "previous"]
+}

package/dist/connectors/immer/immer.types.d.cts

@@ -0,0 +1,9 @@
+import type { Producer } from "immer";
+/**
+ * Synchronous Immer recipe adapted into a Journey context updater.
+ *
+ * A recipe may mutate its draft or return a replacement context, following
+ * Immer's producer rules. Returning `undefined` without draft mutations is a
+ * no-op; use Immer's `nothing` sentinel when an undefined context is intended.
+ */
+export type ImmerContextRecipe<TContext> = Producer<TContext>;

package/dist/connectors/immer/immer.types.d.ts

@@ -0,0 +1,9 @@
+import type { Producer } from "immer";
+/**
+ * Synchronous Immer recipe adapted into a Journey context updater.
+ *
+ * A recipe may mutate its draft or return a replacement context, following
+ * Immer's producer rules. Returning `undefined` without draft mutations is a
+ * no-op; use Immer's `nothing` sentinel when an undefined context is intended.
+ */
+export type ImmerContextRecipe<TContext> = Producer<TContext>;

package/dist/core/errors.d.cts

@@ -0,0 +1,57 @@
+/**
+ * Machine-readable reasons a journey can refuse to build or operate.
+ *
+ * Closed on purpose: consumers should be able to `switch` over it exhaustively.
+ * Adding a member is a minor change; removing or repurposing one is not done
+ * within a major.
+ */
+export type JourneyErrorCode = 
+/** A definition declared no steps. */
+"empty-definition"
+/** The same step id was declared twice. */
+ | "duplicate-step-id"
+/** A step id was referenced that the definition does not declare. */
+ | "unknown-step"
+/** `initial` names a step the definition does not declare. */
+ | "unknown-initial-step"
+/** A transition's `from` or `to` names a step that does not exist. */
+ | "dangling-transition"
+/** Two plugins claimed the same `name`. */
+ | "duplicate-plugin-name"
+/** Persistence was requested but no usable storage could be resolved. */
+ | "storage-unavailable"
+/** Navigation work's `commit` returned a promise; it must be synchronous. */
+ | "async-commit"
+/** A transition or work entry declared `label` as something other than a non-empty string. */
+ | "invalid-label"
+/** A transition or work entry declared `timeoutMs` as something other than a positive finite number. */
+ | "invalid-timeout";
+export type JourneyErrorDetails = {
+    /** The offending step id, where one caused the failure. */
+    readonly stepId?: string;
+    /** The offending event name, for transition failures. */
+    readonly event?: string;
+    /** The offending plugin name, for plugin failures. */
+    readonly pluginName?: string;
+};
+/**
+ * Every error core throws itself.
+ *
+ * Before this existed, distinguishing "duplicate plugin name" from "unknown step
+ * in transition" meant matching on the message text — which quietly made every
+ * message a compatibility promise. `code` is the stable contract; `message` is
+ * for humans and may be reworded in any release.
+ *
+ * Errors surfaced through `NavigationResult.error` and the `error` subscription
+ * event stay `unknown`: those carry whatever the caller's own work threw, which
+ * core cannot constrain.
+ */
+export declare class JourneyError extends Error {
+    readonly code: JourneyErrorCode;
+    readonly stepId: string | undefined;
+    readonly event: string | undefined;
+    readonly pluginName: string | undefined;
+    constructor(code: JourneyErrorCode, message: string, details?: JourneyErrorDetails, cause?: unknown);
+}
+/** Narrowing helper, so consumers need not import the class to test for it. */
+export declare const isJourneyError: (value: unknown) => value is JourneyError;