@rxova/journey-core 0.6.0 → 0.6.2

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

@@ -1,57 +1,99 @@
 import type { JourneyPersistenceOptions } from "./persistence.types";
 import type { JourneyTransition } from "./transitions.types";
+/** Terminal outcomes reached when a journey completes or is explicitly terminated. */
 export type JourneyTerminal = "COMPLETE" | "TERMINATED";
+/** Runtime machine status constants. */
 export declare const JOURNEY_STATUS: {
     readonly RUNNING: "running";
     readonly COMPLETE: "complete";
     readonly TERMINATED: "terminated";
 };
+/** Union of possible runtime machine statuses. */
 export type JourneyStatus = (typeof JOURNEY_STATUS)[keyof typeof JOURNEY_STATUS];
+/** Wildcard step identifier used by transitions that match from any step. */
 export declare const JOURNEY_WILDCARD: "*";
+/** Built-in event constants that are part of core machine behavior. */
 export declare const JOURNEY_EVENT: {
     readonly GO_TO_STEP_BY_ID: "goToStepById";
 };
+/** Machine event types that are always recognized by core. */
 export type JourneyBuiltInEvent = (typeof JOURNEY_EVENT)[keyof typeof JOURNEY_EVENT];
+/** Event literal type for the built-in go-to-step command. */
+export type JourneyGoToStepByIdEventType = typeof JOURNEY_EVENT.GO_TO_STEP_BY_ID;
+/** Wildcard origin marker for transitions. */
 export type JourneyBuiltInFrom = typeof JOURNEY_WILDCARD;
+/** Default transition event names supported by machine convenience APIs. */
 export type JourneyDefaultEventType = "goToNextStep" | "goToPreviousStep" | "terminateJourney" | "completeJourney";
+/** Async lifecycle phases tracked per step while guards/effects run. */
 export declare const JOURNEY_ASYNC_PHASE: {
     readonly IDLE: "idle";
     readonly EVALUATING_WHEN: "evaluating-when";
     readonly RUNNING_EFFECT: "running-effect";
     readonly ERROR: "error";
 };
+/** Union of supported async lifecycle phases. */
 export type JourneyAsyncPhase = (typeof JOURNEY_ASYNC_PHASE)[keyof typeof JOURNEY_ASYNC_PHASE];
+/** Async execution state for a single step. */
 export type JourneyStepAsyncState = {
     phase: JourneyAsyncPhase;
     eventType: string | null;
     transitionId: string | null;
     error: unknown | null;
 };
+/** Aggregated async state for the machine, keyed by step id. */
 export type JourneyAsyncState<TStepId extends string> = {
     isLoading: boolean;
     byStep: Record<TStepId, JourneyStepAsyncState>;
 };
+/** Minimal event shape used across runtime boundaries. */
 export type JourneyBaseEvent = {
     type: string;
     payload?: unknown;
 };
+/** Optional event payload map by event type. */
 export type JourneyEventPayloadMap<TEventType extends string> = Partial<Record<TEventType | JourneyBuiltInEvent, unknown>>;
+/** Resolves payload type for a specific event type from the provided payload map. */
 export type JourneyPayloadFor<TEventType extends string, TPayloadMap extends JourneyEventPayloadMap<TEventType>, TEvent extends TEventType | JourneyBuiltInEvent> = TEvent extends keyof TPayloadMap ? TPayloadMap[TEvent] : unknown;
-type JourneyPayloadForDefaultEvent<TEventType extends string, TPayloadMap extends JourneyEventPayloadMap<TEventType>, TDefaultEvent extends JourneyDefaultEventType> = JourneyPayloadFor<TEventType | TDefaultEvent, TPayloadMap & JourneyEventPayloadMap<TDefaultEvent>, TDefaultEvent>;
+/** Event-type union accepted by machine `.send()`, including built-in convenience events. */
+export type JourneyMachineEventType<TEventType extends string> = TEventType | JourneyDefaultEventType;
+/** Payload map available to machine `.send()`, including built-in convenience events. */
+export type JourneyMachinePayloadMap<TEventType extends string, TPayloadMap extends JourneyEventPayloadMap<TEventType>> = TPayloadMap & JourneyEventPayloadMap<JourneyDefaultEventType>;
+type JourneyPayloadForDefaultEvent<TEventType extends string, TPayloadMap extends JourneyEventPayloadMap<TEventType>, TDefaultEvent extends JourneyDefaultEventType> = JourneyPayloadFor<JourneyMachineEventType<TEventType>, JourneyMachinePayloadMap<TEventType, TPayloadMap>, TDefaultEvent>;
+/** Built-in direct-navigation event that targets a specific step id. */
 export type JourneyGoToEvent<TStepId extends string, TPayload = unknown> = {
-    type: (typeof JOURNEY_EVENT)["GO_TO_STEP_BY_ID"];
+    type: JourneyGoToStepByIdEventType;
     stepId: TStepId;
     payload?: TPayload;
 };
-export type JourneyEvent<TStepId extends string, TEventType extends string, TPayloadMap extends JourneyEventPayloadMap<TEventType> = Record<never, never>> = JourneyGoToEvent<TStepId, JourneyPayloadFor<TEventType, TPayloadMap, (typeof JOURNEY_EVENT)["GO_TO_STEP_BY_ID"]>> | {
+/** Event union available to transitions and guards for the declared event type set. */
+export type JourneyEvent<TStepId extends string, TEventType extends string, TPayloadMap extends JourneyEventPayloadMap<TEventType> = Record<never, never>> = JourneyGoToEvent<TStepId, JourneyPayloadFor<TEventType, TPayloadMap, JourneyGoToStepByIdEventType>> | {
     [TType in TEventType]: {
         type: TType;
         payload?: JourneyPayloadFor<TEventType, TPayloadMap, TType>;
     };
 }[TEventType];
-export type JourneyStepDefinition<TStepMeta = unknown> = {
+type JourneyDefaultMachineEvent<TEventType extends string, TPayloadMap extends JourneyEventPayloadMap<TEventType>> = {
+    [TType in JourneyDefaultEventType]: {
+        type: TType;
+        payload?: JourneyPayloadFor<JourneyMachineEventType<TEventType>, JourneyMachinePayloadMap<TEventType, TPayloadMap>, TType>;
+    };
+}[JourneyDefaultEventType];
+type JourneyCustomMachineEvent<TEventType extends string, TPayloadMap extends JourneyEventPayloadMap<TEventType>> = {
+    [TType in TEventType]: {
+        type: TType;
+        payload?: JourneyPayloadFor<TEventType, TPayloadMap, TType>;
+    };
+}[TEventType];
+/** Event union accepted by `JourneyMachine.send`. */
+export type JourneySendEvent<TStepId extends string, TEventType extends string, TPayloadMap extends JourneyEventPayloadMap<TEventType> = Record<never, never>> = JourneyGoToEvent<TStepId, JourneyPayloadFor<JourneyMachineEventType<TEventType>, JourneyMachinePayloadMap<TEventType, TPayloadMap>, JourneyGoToStepByIdEventType>> | JourneyDefaultMachineEvent<TEventType, TPayloadMap> | JourneyCustomMachineEvent<TEventType, TPayloadMap>;
+/**
+ * Step definition with optional metadata and optional typed extension fields.
+ * Use `TStepExtra` to explicitly model additional per-step properties.
+ */
+export type JourneyStepDefinition<TStepMeta = unknown, TStepExtra extends object = Record<never, never>> = {
     meta?: TStepMeta;
-} & Record<string, unknown>;
+} & TStepExtra;
+/** Serializable runtime snapshot of the journey state. */
 export type JourneySnapshot<TContext, TStepId extends string, TStepMeta = unknown> = {
     currentStepId: TStepId;
     history: {
@@ -64,24 +106,28 @@ export type JourneySnapshot<TContext, TStepId extends string, TStepMeta = unknow
     status: JourneyStatus;
     async: JourneyAsyncState<TStepId>;
 };
-export type JourneyDefinition<TContext, TStepId extends string = string, TEventType extends string = JourneyDefaultEventType, TPayloadMap extends JourneyEventPayloadMap<TEventType> = Record<never, never>, TStepMeta = unknown> = {
+/** 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;
     context: TContext;
-    steps: Record<TStepId, JourneyStepDefinition<TStepMeta>>;
+    steps: Record<TStepId, JourneyStepDefinition<TStepMeta, TStepExtra>>;
     transitions: readonly JourneyTransition<TContext, TStepId, TEventType, TPayloadMap>[];
 };
+/** Optional machine features (for example, persistence configuration). */
 export type JourneyMachineOptions<TContext, TStepId extends string, TStepMeta = unknown> = {
     persistence?: JourneyPersistenceOptions<TContext, TStepId, TStepMeta>;
 };
+/** Result returned from send/navigation APIs. */
 export type JourneySendResult<TContext, TStepId extends string, TStepMeta = unknown> = {
     transitioned: boolean;
     transitionId?: string;
     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: "transition.start";
     from: TStepId;
-    event: JourneyEvent<TStepId, TEventType, TPayloadMap>;
+    event: JourneySendEvent<TStepId, TEventType, TPayloadMap>;
     timestamp: number;
 } | {
     type: "transition.success";
@@ -132,9 +178,10 @@ export type JourneyObservationEvent<TStepId extends string, TEventType extends s
     next: TStepMeta;
     timestamp: number;
 };
+/** Runtime machine API for reading snapshots, sending events, and controlling flow. */
 export type JourneyMachine<TContext, TStepId extends string, TEventType extends string, TPayloadMap extends JourneyEventPayloadMap<TEventType> = Record<never, never>, TStepMeta = unknown> = {
     getSnapshot: () => JourneySnapshot<TContext, TStepId, TStepMeta>;
-    send: (event: JourneyEvent<TStepId, TEventType, TPayloadMap>) => Promise<JourneySendResult<TContext, TStepId, TStepMeta>>;
+    send: (event: JourneySendEvent<TStepId, TEventType, TPayloadMap>) => Promise<JourneySendResult<TContext, TStepId, TStepMeta>>;
     goToNextStep: () => Promise<JourneySendResult<TContext, TStepId, TStepMeta>>;
     terminateJourney: (payload?: JourneyPayloadForDefaultEvent<TEventType, TPayloadMap, "terminateJourney">) => Promise<JourneySendResult<TContext, TStepId, TStepMeta>>;
     completeJourney: (payload?: JourneyPayloadForDefaultEvent<TEventType, TPayloadMap, "completeJourney">) => Promise<JourneySendResult<TContext, TStepId, TStepMeta>>;

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

@@ -1,4 +1,5 @@
-import type { JOURNEY_EVENT, JourneyBuiltInFrom, JourneyEvent, JourneyEventPayloadMap, JourneyTerminal } from "./journey.types";
+import type { JourneyBuiltInFrom, JourneyEvent, JourneyEventPayloadMap, JourneyGoToStepByIdEventType, JourneyTerminal } from "./journey.types";
+/** Arguments passed to transition guards and effects. */
 export type JourneyTransitionArgs<TContext, TStepId extends string, TEventType extends string, TPayloadMap extends JourneyEventPayloadMap<TEventType> = Record<never, never>> = {
     context: TContext;
     from: TStepId;
@@ -6,6 +7,7 @@ export type JourneyTransitionArgs<TContext, TStepId extends string, TEventType e
     index: number;
     event: JourneyEvent<TStepId, TEventType, TPayloadMap>;
 };
+/** 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>> = {
     id?: string;
@@ -13,6 +15,7 @@ type JourneyTransitionConfig<TContext, TStepId extends string, TEventType extend
     when?: (args: JourneyTransitionArgs<TContext, TStepId, TEventType, TPayloadMap>) => boolean | Promise<boolean>;
     effect?: (args: JourneyTransitionArgs<TContext, TStepId, 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>;
@@ -20,28 +23,39 @@ export type JourneyEventTransition<TContext, TStepId extends string, TEventType
     event: Extract<TEventType, "completeJourney" | "terminateJourney">;
     to?: never;
 });
+/** 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> & {
-    event: (typeof JOURNEY_EVENT)["GO_TO_STEP_BY_ID"];
+    event: JourneyGoToStepByIdEventType;
     to: TStepId;
 };
+/** Any transition shape accepted by `createJourneyMachine`. */
 export type JourneyTransition<TContext, TStepId extends string, TEventType extends string, TPayloadMap extends JourneyEventPayloadMap<TEventType> = Record<never, never>> = JourneyEventTransition<TContext, TStepId, TEventType, TPayloadMap> | JourneyGoToStepTransition<TContext, TStepId, TEventType, TPayloadMap>;
+/** 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>;
 };
+/** 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>;
 };
+/** 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>[];
 };
+/** Builder returned by `tx.from(...).on("completeJourney")`. */
 export type CompleteJourneyEventBuilder<TContext, TStepId extends string, TEventType extends string, TPayloadMap extends JourneyEventPayloadMap<TEventType>> = {
     complete: (config?: TransitionConfig<TContext, TStepId, TEventType, TPayloadMap>) => JourneyTransition<TContext, TStepId, TEventType, TPayloadMap>;
 };
+/** Builder returned by `tx.from(...).on("terminateJourney")`. */
 export type TerminateJourneyEventBuilder<TContext, TStepId extends string, TEventType extends string, TPayloadMap extends JourneyEventPayloadMap<TEventType>> = {
     terminate: (config?: TransitionConfig<TContext, TStepId, TEventType, TPayloadMap>) => JourneyTransition<TContext, TStepId, TEventType, TPayloadMap>;
 };
+/**
+ * Conditional transition builder returned by `tx.from(...).on(event)`:
+ * terminal events expose terminal-only helpers, other events expose `to/choose`.
+ */
 export type EventBuilder<TContext, TStepId extends string, TEventType extends string, TPayloadMap extends JourneyEventPayloadMap<TEventType>> = TEventType extends "completeJourney" ? CompleteJourneyEventBuilder<TContext, TStepId, TEventType, TPayloadMap> : TEventType extends "terminateJourney" ? TerminateJourneyEventBuilder<TContext, TStepId, TEventType, TPayloadMap> : StandardEventBuilder<TContext, TStepId, TEventType, TPayloadMap>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rxova/journey-core",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Journey core state machine.",
   "keywords": [
     "journey",
@@ -57,7 +57,7 @@
   ],
   "scripts": {
     "build": "pnpm run clean && node ./scripts/build.mjs && tsc -p tsconfig.build.json && node ../../scripts/copy-types.mjs dist",
-    "clean": "rm -rf dist tsconfig.build.tsbuildinfo",
+    "clean": "node ../../scripts/clean-paths.mjs 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",