@rxova/journey-core 0.6.3 → 0.7.0

package/dist/transitions.d.ts

@@ -1,20 +1,54 @@
 import type { JourneyEventPayloadMap } from "./types/journey.types";
-import type { EventBuilder, JourneyEventTransition, JourneyTransition, JourneyTransitionArgs, JourneyTransitionTarget, TransitionBranch, TransitionConfig } from "./types/transitions.types";
+import type { EventBuilder, JourneyTransition, JourneySelectedTransitionArgs, JourneyTransitionTarget, TransitionBranch, TransitionConfig } from "./types/transitions.types";
+type TransitionPayloadMap = Partial<Record<string, unknown>>;
+type SelectedPayloadMap<TEventType extends string, TPayloadMap extends TransitionPayloadMap> = TPayloadMap & JourneyEventPayloadMap<TEventType>;
 /**
  * Fluent helpers for building journey transitions with type-safe branches.
  */
 export declare const tx: {
-    from: <TStepId extends string, TContext = unknown>(from: TStepId) => {
-        on: <TEventType extends string>(event: TEventType) => EventBuilder<TContext, TStepId, TEventType, Record<never, never>>;
-        toComplete: (config?: TransitionConfig<TContext, TStepId, "completeJourney", Record<never, never>>) => JourneyEventTransition<TContext, TStepId, "completeJourney", Record<never, never>>;
-        toTerminate: (config?: TransitionConfig<TContext, TStepId, "terminateJourney", Record<never, never>>) => JourneyEventTransition<TContext, TStepId, "terminateJourney", Record<never, never>>;
+    from: <TStepId extends string, TContext = unknown, TPayloadMap extends TransitionPayloadMap = Record<never, never>>(from: TStepId) => {
+        on: <TEventType extends string>(event: TEventType) => EventBuilder<TContext, TStepId, TEventType, SelectedPayloadMap<TEventType, TPayloadMap>>;
+        toComplete: (config?: TransitionConfig<TContext, TStepId, "completeJourney", SelectedPayloadMap<"completeJourney", TPayloadMap>>) => {
+            id?: string;
+            from: "*" | TStepId;
+            when?: (args: JourneySelectedTransitionArgs<TContext, TStepId, "completeJourney", TPayloadMap & Partial<Record<"goToStepById" | "completeJourney", unknown>>>) => boolean | Promise<boolean>;
+            effect?: (args: JourneySelectedTransitionArgs<TContext, TStepId, "completeJourney", TPayloadMap & Partial<Record<"goToStepById" | "completeJourney", unknown>>>) => void | TContext | Promise<void | TContext>;
+        } & {
+            event: "completeJourney";
+            to?: never;
+        };
+        toTerminate: (config?: TransitionConfig<TContext, TStepId, "terminateJourney", SelectedPayloadMap<"terminateJourney", TPayloadMap>>) => {
+            id?: string;
+            from: "*" | TStepId;
+            when?: (args: JourneySelectedTransitionArgs<TContext, TStepId, "terminateJourney", TPayloadMap & Partial<Record<"goToStepById" | "terminateJourney", unknown>>>) => boolean | Promise<boolean>;
+            effect?: (args: JourneySelectedTransitionArgs<TContext, TStepId, "terminateJourney", TPayloadMap & Partial<Record<"goToStepById" | "terminateJourney", unknown>>>) => void | TContext | Promise<void | TContext>;
+        } & {
+            event: "terminateJourney";
+            to?: never;
+        };
     };
-    any: <TContext = unknown, TStepId extends string = string>() => {
-        on: <TEventType extends string>(event: TEventType) => EventBuilder<TContext, TStepId, TEventType, Record<never, never>>;
-        toComplete: (config?: TransitionConfig<TContext, TStepId, "completeJourney", Record<never, never>>) => JourneyEventTransition<TContext, TStepId, "completeJourney", Record<never, never>>;
-        toTerminate: (config?: TransitionConfig<TContext, TStepId, "terminateJourney", Record<never, never>>) => JourneyEventTransition<TContext, TStepId, "terminateJourney", Record<never, never>>;
+    any: <TContext = unknown, TStepId extends string = string, TPayloadMap extends TransitionPayloadMap = Record<never, never>>() => {
+        on: <TEventType extends string>(event: TEventType) => EventBuilder<TContext, TStepId, TEventType, SelectedPayloadMap<TEventType, TPayloadMap>>;
+        toComplete: (config?: TransitionConfig<TContext, TStepId, "completeJourney", SelectedPayloadMap<"completeJourney", TPayloadMap>>) => {
+            id?: string;
+            from: "*" | TStepId;
+            when?: (args: JourneySelectedTransitionArgs<TContext, TStepId, "completeJourney", TPayloadMap & Partial<Record<"goToStepById" | "completeJourney", unknown>>>) => boolean | Promise<boolean>;
+            effect?: (args: JourneySelectedTransitionArgs<TContext, TStepId, "completeJourney", TPayloadMap & Partial<Record<"goToStepById" | "completeJourney", unknown>>>) => void | TContext | Promise<void | TContext>;
+        } & {
+            event: "completeJourney";
+            to?: never;
+        };
+        toTerminate: (config?: TransitionConfig<TContext, TStepId, "terminateJourney", SelectedPayloadMap<"terminateJourney", TPayloadMap>>) => {
+            id?: string;
+            from: "*" | TStepId;
+            when?: (args: JourneySelectedTransitionArgs<TContext, TStepId, "terminateJourney", TPayloadMap & Partial<Record<"goToStepById" | "terminateJourney", unknown>>>) => boolean | Promise<boolean>;
+            effect?: (args: JourneySelectedTransitionArgs<TContext, TStepId, "terminateJourney", TPayloadMap & Partial<Record<"goToStepById" | "terminateJourney", unknown>>>) => void | TContext | Promise<void | TContext>;
+        } & {
+            event: "terminateJourney";
+            to?: never;
+        };
     };
-    when: <TContext, TStepId extends string, TEventType extends string, TPayloadMap extends JourneyEventPayloadMap<TEventType>>(predicate: (args: JourneyTransitionArgs<TContext, TStepId, TEventType, TPayloadMap>) => boolean | Promise<boolean>) => {
+    when: <TContext, TStepId extends string, TEventType extends string, TPayloadMap extends JourneyEventPayloadMap<TEventType>>(predicate: (args: JourneySelectedTransitionArgs<TContext, TStepId, TEventType, TPayloadMap>) => boolean | Promise<boolean>) => {
         to: (to: JourneyTransitionTarget<TStepId>, config?: TransitionConfig<TContext, TStepId, TEventType, TPayloadMap>) => TransitionBranch<TContext, TStepId, TEventType, TPayloadMap>;
     };
     otherwise: <TContext, TStepId extends string, TEventType extends string, TPayloadMap extends JourneyEventPayloadMap<TEventType>>() => {
@@ -25,3 +59,4 @@ export declare const tx: {
  * Flattens transition items and transition arrays into a single transition list.
  */
 export declare const createTransitions: <TContext, TStepId extends string, TEventType extends string, TPayloadMap extends JourneyEventPayloadMap<TEventType>>(...items: Array<JourneyTransition<TContext, TStepId, TEventType, TPayloadMap> | readonly JourneyTransition<TContext, TStepId, TEventType, TPayloadMap>[]>) => JourneyTransition<TContext, TStepId, TEventType, TPayloadMap>[];
+export {};

package/dist/types/index.d.ts

@@ -1,4 +1,4 @@
 export { JOURNEY_ASYNC_PHASE, JOURNEY_EVENT, JOURNEY_STATUS, JOURNEY_WILDCARD } from "./journey.types";
-export type { JourneyAsyncPhase, JourneyAsyncState, JourneyBaseEvent, JourneyBuiltInEvent, JourneyBuiltInFrom, JourneyDefaultEventType, JourneyDefinition, JourneyEvent, JourneyEventPayloadMap, JourneyGoToEvent, JourneyGoToStepByIdEventType, JourneyMachine, JourneyMachineEventType, JourneyMachinePayloadMap, JourneyMachineOptions, JourneyObservationEvent, JourneyPayloadFor, JourneySendEvent, JourneySendResult, JourneySnapshot, JourneyStatus, JourneyStepAsyncState, JourneyStepDefinition, JourneyTerminal } from "./journey.types";
+export type { JourneyAsyncPhase, JourneyAsyncState, JourneyBaseEvent, JourneyBuiltInEvent, JourneyBuiltInFrom, JourneyDefaultEventType, JourneyDefinition, JourneyEvent, JourneyEventPayloadMap, JourneyGoToEvent, JourneyGoToStepByIdEventType, JourneyMachine, JourneyMachineEventType, JourneyMachinePayloadMap, JourneyMachineOptions, JourneyObservationEvent, JourneySelector, JourneyEqualityFn, JourneyPayloadFor, JourneySendEvent, JourneySendResult, JourneySnapshot, JourneyStatus, JourneyStepAsyncState, JourneyStepDefinition, JourneyTerminal } from "./journey.types";
 export type { JourneyEventTransition, JourneyGoToStepTransition, JourneyTransition, JourneyTransitionArgs, JourneyTransitionTarget } from "./transitions.types";
 export type { JourneyPersistedSnapshot, JourneyPersistedState, JourneyPersistenceOptions, JourneyStorage } from "./persistence.types";

package/dist/types/journey.types.d.ts

@@ -106,6 +106,10 @@ export type JourneySnapshot<TContext, TStepId extends string, TStepMeta = unknow
     status: JourneyStatus;
     async: JourneyAsyncState<TStepId>;
 };
+/** Selector function that derives a value from a machine snapshot. */
+export type JourneySelector<TContext, TStepId extends string, TStepMeta = unknown, TSelected = unknown> = (snapshot: JourneySnapshot<TContext, TStepId, TStepMeta>) => TSelected;
+/** Equality function used to compare selected values between snapshot updates. */
+export type JourneyEqualityFn<TValue> = (previous: TValue, next: TValue) => boolean;
 /** Full machine definition used to create a journey machine instance. */
 export type JourneyDefinition<TContext, TStepId extends string = string, TEventType extends string = JourneyDefaultEventType, TPayloadMap extends JourneyEventPayloadMap<TEventType> = Record<never, never>, TStepMeta = unknown, TStepExtra extends object = Record<never, never>> = {
     initial: TStepId;
@@ -116,15 +120,21 @@ export type JourneyDefinition<TContext, TStepId extends string = string, TEventT
 /** Optional machine features (for example, persistence configuration). */
 export type JourneyMachineOptions<TContext, TStepId extends string, TStepMeta = unknown> = {
     persistence?: JourneyPersistenceOptions<TContext, TStepId, TStepMeta>;
+    completeOnNoNextStep?: boolean;
 };
 /** Result returned from send/navigation APIs. */
 export type JourneySendResult<TContext, TStepId extends string, TStepMeta = unknown> = {
     transitioned: boolean;
     transitionId?: string;
+    error?: unknown;
     snapshot: JourneySnapshot<TContext, TStepId, TStepMeta>;
 };
 /** Observation events emitted by the machine lifecycle/event stream. */
 export type JourneyObservationEvent<TStepId extends string, TEventType extends string, TPayloadMap extends JourneyEventPayloadMap<TEventType> = Record<never, never>, TStepMeta = unknown> = {
+    type: "journey.start";
+    stepId: TStepId;
+    timestamp: number;
+} | {
     type: "transition.start";
     from: TStepId;
     event: JourneySendEvent<TStepId, TEventType, TPayloadMap>;
@@ -191,7 +201,18 @@ export type JourneyMachine<TContext, TStepId extends string, TEventType extends
     updateStepMetadata: (stepId: TStepId, updater: (metadata: TStepMeta) => TStepMeta) => JourneySnapshot<TContext, TStepId, TStepMeta>;
     clearStepError: (stepId?: TStepId) => JourneySnapshot<TContext, TStepId, TStepMeta>;
     resetMachine: () => JourneySnapshot<TContext, TStepId, TStepMeta>;
+    dispose: () => void;
     subscribe: (listener: () => void) => () => void;
+    subscribeSelector: <TSelected>(selector: JourneySelector<TContext, TStepId, TStepMeta, TSelected>, listener: (next: TSelected, previous: TSelected) => void, equalityFn?: JourneyEqualityFn<TSelected>) => () => void;
     subscribeEvent: (listener: (event: JourneyObservationEvent<TStepId, TEventType, TPayloadMap, TStepMeta>) => void) => () => void;
+    subscribeStart: (listener: (event: Extract<JourneyObservationEvent<TStepId, TEventType, TPayloadMap, TStepMeta>, {
+        type: "journey.start";
+    }>) => void) => () => void;
+    subscribeComplete: (listener: (event: Extract<JourneyObservationEvent<TStepId, TEventType, TPayloadMap, TStepMeta>, {
+        type: "journey.complete";
+    }>) => void) => () => void;
+    subscribeTerminate: (listener: (event: Extract<JourneyObservationEvent<TStepId, TEventType, TPayloadMap, TStepMeta>, {
+        type: "journey.close";
+    }>) => void) => () => void;
 };
 export {};

package/dist/types/transitions.types.d.ts

@@ -7,24 +7,36 @@ export type JourneyTransitionArgs<TContext, TStepId extends string, TEventType e
     index: number;
     event: JourneyEvent<TStepId, TEventType, TPayloadMap>;
 };
+type JourneySelectedTransitionEvent<TStepId extends string, TEventType extends string, TPayloadMap extends JourneyEventPayloadMap<TEventType>> = Extract<JourneyEvent<TStepId, TEventType, TPayloadMap>, {
+    type: TEventType;
+}>;
+/** Arguments passed to fluent transition guards and effects for a selected event type. */
+export type JourneySelectedTransitionArgs<TContext, TStepId extends string, TEventType extends string, TPayloadMap extends JourneyEventPayloadMap<TEventType>> = Omit<JourneyTransitionArgs<TContext, TStepId, TEventType, TPayloadMap>, "event"> & {
+    event: JourneySelectedTransitionEvent<TStepId, TEventType, TPayloadMap>;
+};
+type JourneyTransitionPayloadMap<TEventType extends string, TPayloadMap extends Partial<Record<string, unknown>>> = TPayloadMap & JourneyEventPayloadMap<TEventType>;
 /** Transition destination, either another step or a terminal machine state. */
 export type JourneyTransitionTarget<TStepId extends string> = TStepId | JourneyTerminal;
-type JourneyTransitionConfig<TContext, TStepId extends string, TEventType extends string, TPayloadMap extends JourneyEventPayloadMap<TEventType> = Record<never, never>> = {
+type JourneyTransitionConfig<TContext, TStepId extends string, TEventType extends string, TPayloadMap extends Partial<Record<string, unknown>> = Record<never, never>> = {
     id?: string;
     from: TStepId | JourneyBuiltInFrom;
-    when?: (args: JourneyTransitionArgs<TContext, TStepId, TEventType, TPayloadMap>) => boolean | Promise<boolean>;
-    effect?: (args: JourneyTransitionArgs<TContext, TStepId, TEventType, TPayloadMap>) => TContext | void | Promise<TContext | void>;
+    when?: (args: JourneySelectedTransitionArgs<TContext, TStepId, TEventType, JourneyTransitionPayloadMap<TEventType, TPayloadMap>>) => boolean | Promise<boolean>;
+    effect?: (args: JourneySelectedTransitionArgs<TContext, TStepId, TEventType, JourneyTransitionPayloadMap<TEventType, TPayloadMap>>) => TContext | void | Promise<TContext | void>;
 };
 /** Transition declared for a standard event or terminal event. */
-export type JourneyEventTransition<TContext, TStepId extends string, TEventType extends string, TPayloadMap extends JourneyEventPayloadMap<TEventType> = Record<never, never>> = (JourneyTransitionConfig<TContext, TStepId, TEventType, TPayloadMap> & {
-    event: Exclude<TEventType, "completeJourney" | "terminateJourney">;
-    to: JourneyTransitionTarget<TStepId>;
-}) | (JourneyTransitionConfig<TContext, TStepId, TEventType, TPayloadMap> & {
-    event: Extract<TEventType, "completeJourney" | "terminateJourney">;
-    to?: never;
-});
+export type JourneyEventTransition<TContext, TStepId extends string, TEventType extends string, TPayloadMap extends JourneyEventPayloadMap<TEventType> = Record<never, never>> = {
+    [TSelectedEvent in Exclude<TEventType, "completeJourney" | "terminateJourney">]: JourneyTransitionConfig<TContext, TStepId, TSelectedEvent, TPayloadMap> & {
+        event: TSelectedEvent;
+        to: JourneyTransitionTarget<TStepId>;
+    };
+}[Exclude<TEventType, "completeJourney" | "terminateJourney">] | {
+    [TSelectedEvent in Extract<TEventType, "completeJourney" | "terminateJourney">]: JourneyTransitionConfig<TContext, TStepId, TSelectedEvent, TPayloadMap> & {
+        event: TSelectedEvent;
+        to?: never;
+    };
+}[Extract<TEventType, "completeJourney" | "terminateJourney">];
 /** Direct jump transition triggered by the built-in `goToStepById` event. */
-export type JourneyGoToStepTransition<TContext, TStepId extends string, TEventType extends string, TPayloadMap extends JourneyEventPayloadMap<TEventType> = Record<never, never>> = JourneyTransitionConfig<TContext, TStepId, TEventType, TPayloadMap> & {
+export type JourneyGoToStepTransition<TContext, TStepId extends string, TEventType extends string, TPayloadMap extends JourneyEventPayloadMap<TEventType> = Record<never, never>> = JourneyTransitionConfig<TContext, TStepId, JourneyGoToStepByIdEventType, TPayloadMap> & {
     event: JourneyGoToStepByIdEventType;
     to: TStepId;
 };
@@ -33,17 +45,23 @@ export type JourneyTransition<TContext, TStepId extends string, TEventType exten
 /** Optional transition behavior shared by direct and branch transitions. */
 export type TransitionConfig<TContext, TStepId extends string, TEventType extends string, TPayloadMap extends JourneyEventPayloadMap<TEventType>> = {
     id?: string;
-    effect?: (args: JourneyTransitionArgs<TContext, TStepId, TEventType, TPayloadMap>) => TContext | void | Promise<TContext | void>;
+    effect?: (args: JourneySelectedTransitionArgs<TContext, TStepId, TEventType, TPayloadMap>) => TContext | void | Promise<TContext | void>;
 };
 /** Branch definition used by `choose(...)`. */
 export type TransitionBranch<TContext, TStepId extends string, TEventType extends string, TPayloadMap extends JourneyEventPayloadMap<TEventType>> = TransitionConfig<TContext, TStepId, TEventType, TPayloadMap> & {
     to: JourneyTransitionTarget<TStepId>;
-    when?: (args: JourneyTransitionArgs<TContext, TStepId, TEventType, TPayloadMap>) => boolean | Promise<boolean>;
+    when?: (args: JourneySelectedTransitionArgs<TContext, TStepId, TEventType, TPayloadMap>) => boolean | Promise<boolean>;
+};
+/** Builder returned by fluent `when(...)` / `otherwise()` helpers for a selected event type. */
+export type TransitionBranchBuilder<TContext, TStepId extends string, TEventType extends string, TPayloadMap extends JourneyEventPayloadMap<TEventType>> = {
+    to: (to: JourneyTransitionTarget<TStepId>, config?: TransitionConfig<TContext, TStepId, TEventType, TPayloadMap>) => TransitionBranch<TContext, TStepId, TEventType, TPayloadMap>;
 };
 /** Builder returned by `tx.from(...).on(nonTerminalEvent)` and `tx.any().on(...)`. */
 export type StandardEventBuilder<TContext, TStepId extends string, TEventType extends string, TPayloadMap extends JourneyEventPayloadMap<TEventType>> = {
     to: (to: JourneyTransitionTarget<TStepId>, config?: TransitionConfig<TContext, TStepId, TEventType, TPayloadMap>) => JourneyTransition<TContext, TStepId, TEventType, TPayloadMap>;
     choose: (...branches: Array<TransitionBranch<TContext, TStepId, TEventType, TPayloadMap>>) => JourneyTransition<TContext, TStepId, TEventType, TPayloadMap>[];
+    when: (predicate: (args: JourneySelectedTransitionArgs<TContext, TStepId, TEventType, TPayloadMap>) => boolean | Promise<boolean>) => TransitionBranchBuilder<TContext, TStepId, TEventType, TPayloadMap>;
+    otherwise: () => TransitionBranchBuilder<TContext, TStepId, TEventType, TPayloadMap>;
 };
 /** Builder returned by `tx.from(...).on("completeJourney")`. */
 export type CompleteJourneyEventBuilder<TContext, TStepId extends string, TEventType extends string, TPayloadMap extends JourneyEventPayloadMap<TEventType>> = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rxova/journey-core",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "description": "Journey core state machine.",
   "keywords": [
     "journey",
@@ -52,12 +52,12 @@
       "name": "core/createJourneyMachine",
       "path": "dist/index.js",
       "import": "{ createJourneyMachine }",
-      "limit": "4 kB"
+      "limit": "5 kB"
     }
   ],
   "scripts": {
-    "build": "pnpm run clean && node ./scripts/build.mjs && tsc -p tsconfig.build.json && node ../../scripts/copy-types.mjs dist",
-    "clean": "node ../../scripts/clean-paths.mjs dist tsconfig.build.tsbuildinfo",
+    "build": "pnpm run clean && node --import tsx ./scripts/build.ts && tsc -p tsconfig.build.json && node --import tsx ../../scripts/copy-types.ts dist",
+    "clean": "node --import tsx ../../scripts/clean-paths.ts dist tsconfig.build.tsbuildinfo",
     "coverage": "pnpm --workspace-root vitest run --coverage --coverage.include=packages/core/src/** --coverage.reporter=text-summary",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "publint": "publint",