@daltonr/pathwrite-core 0.3.0 → 0.5.0

package/src/index.ts

@@ -1,5 +1,36 @@
 export type PathData = Record<string, unknown>;
 
+export interface SerializedPathState {
+  version: 1;
+  pathId: string;
+  currentStepIndex: number;
+  data: PathData;
+  visitedStepIds: string[];
+  subPathMeta?: Record<string, unknown>;
+  pathStack: Array<{
+    pathId: string;
+    currentStepIndex: number;
+    data: PathData;
+    visitedStepIds: string[];
+    subPathMeta?: Record<string, unknown>;
+  }>;
+  _isNavigating: boolean;
+}
+
+/**
+ * The interface every path state store must implement.
+ *
+ * `HttpStore` from `@daltonr/pathwrite-store-http` is the reference
+ * implementation. Any backend — MongoDB, Redis, localStorage, etc. —
+ * implements this interface and works with `httpPersistence` and
+ * `restoreOrStart` without any other changes.
+ */
+export interface PathStore {
+  save(key: string, state: SerializedPathState): Promise<void>;
+  load(key: string): Promise<SerializedPathState | null>;
+  delete(key: string): Promise<void>;
+}
+
 export interface PathStepContext<TData extends PathData = PathData> {
   readonly pathId: string;
   readonly stepId: string;
@@ -96,8 +127,21 @@ export interface PathSnapshot<TData extends PathData = PathData> {
   data: TData;
 }
 
+/**
+ * Identifies the public method that triggered a `stateChanged` event.
+ */
+export type StateChangeCause =
+  | "start"
+  | "next"
+  | "previous"
+  | "goToStep"
+  | "goToStepChecked"
+  | "setData"
+  | "cancel"
+  | "restart";
+
 export type PathEvent =
-  | { type: "stateChanged"; snapshot: PathSnapshot }
+  | { type: "stateChanged"; cause: StateChangeCause; snapshot: PathSnapshot }
   | { type: "completed"; pathId: string; data: PathData }
   | { type: "cancelled"; pathId: string; data: PathData }
   | {
@@ -107,6 +151,84 @@ export type PathEvent =
       snapshot: PathSnapshot;
     };
 
+/**
+ * A function called on every engine event. Observers are registered at
+ * construction time and receive every event for the lifetime of the engine.
+ *
+ * The second argument is the engine itself — useful when the observer needs to
+ * read current state (e.g. calling `engine.exportState()` for persistence).
+ *
+ * ```typescript
+ * const logger: PathObserver = (event) => console.log(event.type);
+ * const persist: PathObserver = (event, engine) => { ... };
+ * ```
+ */
+export type PathObserver = (event: PathEvent, engine: PathEngine) => void;
+
+/**
+ * Determines which engine events an observer should react to.
+ *
+ * | Strategy            | Triggers when                                              |
+ * |---------------------|------------------------------------------------------------|
+ * | `"onEveryChange"`   | Any settled `stateChanged` or `resumed`                    |
+ * | `"onNext"`          | `next()` completes navigation *(default)*                  |
+ * | `"onSubPathComplete"` | Sub-path finishes and the parent resumes                 |
+ * | `"onComplete"`      | The entire path completes                                  |
+ * | `"manual"`          | Never — caller decides when to act                        |
+ */
+export type ObserverStrategy =
+  | "onEveryChange"
+  | "onNext"
+  | "onSubPathComplete"
+  | "onComplete"
+  | "manual";
+
+/**
+ * Returns `true` when `event` matches the trigger condition for `strategy`.
+ *
+ * Use this in any `PathObserver` factory to centralise the
+ * "which events should I react to?" decision so every observer
+ * (HTTP, MongoDB, logger, analytics…) shares the same semantics.
+ *
+ * ```typescript
+ * const observer: PathObserver = (event, engine) => {
+ *   if (matchesStrategy(strategy, event)) doWork(engine);
+ * };
+ * ```
+ */
+export function matchesStrategy(strategy: ObserverStrategy, event: PathEvent): boolean {
+  switch (strategy) {
+    case "onEveryChange":
+      // Only react once navigation has settled — stateChanged fires twice per
+      // navigation (isNavigating:true then false).
+      return (event.type === "stateChanged" && !event.snapshot.isNavigating)
+        || event.type === "resumed";
+    case "onNext":
+      return event.type === "stateChanged"
+        && event.cause === "next"
+        && !event.snapshot.isNavigating;
+    case "onSubPathComplete":
+      return event.type === "resumed";
+    case "onComplete":
+      return event.type === "completed";
+    case "manual":
+      return false;
+  }
+}
+
+/**
+ * Options accepted by the `PathEngine` constructor and `PathEngine.fromState()`.
+ */
+export interface PathEngineOptions {
+  /**
+   * Zero or more observers to register before the first event fires.
+   * Each observer is called synchronously on every engine event for the
+   * lifetime of the engine. Observers cannot be removed; for removable
+   * listeners use `engine.subscribe()`.
+   */
+  observers?: PathObserver[];
+}
+
 interface ActivePath {
   definition: PathDefinition;
   currentStepIndex: number;
@@ -121,6 +243,81 @@ export class PathEngine {
   private readonly listeners = new Set<(event: PathEvent) => void>();
   private _isNavigating = false;
 
+  constructor(options?: PathEngineOptions) {
+    if (options?.observers) {
+      for (const observer of options.observers) {
+        // Wrap so observer receives the engine instance as the second argument
+        this.listeners.add((event) => observer(event, this));
+      }
+    }
+  }
+
+  /**
+   * Restores a PathEngine from previously exported state.
+   *
+   * **Important:** You must provide the same path definitions that were
+   * active when the state was exported. The path IDs in `state` are used
+   * to match against the provided definitions.
+   *
+   * @param state           The serialized state from `exportState()`.
+   * @param pathDefinitions A map of path ID → definition. Must include the
+   *                        active path and any paths in the stack.
+   * @returns A new PathEngine instance with the restored state.
+   * @throws If `state` references a path ID not present in `pathDefinitions`,
+   *         or if the state format is invalid.
+   */
+  public static fromState(
+    state: SerializedPathState,
+    pathDefinitions: Record<string, PathDefinition>,
+    options?: PathEngineOptions
+  ): PathEngine {
+    if (state.version !== 1) {
+      throw new Error(`Unsupported SerializedPathState version: ${state.version}`);
+    }
+
+    const engine = new PathEngine(options);
+
+    // Restore the path stack (sub-paths)
+    for (const stackItem of state.pathStack) {
+      const definition = pathDefinitions[stackItem.pathId];
+      if (!definition) {
+        throw new Error(
+          `Cannot restore state: path definition "${stackItem.pathId}" not found. ` +
+          `Provide all path definitions that were active when state was exported.`
+        );
+      }
+      engine.pathStack.push({
+        definition,
+        currentStepIndex: stackItem.currentStepIndex,
+        data: { ...stackItem.data },
+        visitedStepIds: new Set(stackItem.visitedStepIds),
+        subPathMeta: stackItem.subPathMeta ? { ...stackItem.subPathMeta } : undefined
+      });
+    }
+
+    // Restore the active path
+    const activeDefinition = pathDefinitions[state.pathId];
+    if (!activeDefinition) {
+      throw new Error(
+        `Cannot restore state: active path definition "${state.pathId}" not found.`
+      );
+    }
+
+    engine.activePath = {
+      definition: activeDefinition,
+      currentStepIndex: state.currentStepIndex,
+      data: { ...state.data },
+      visitedStepIds: new Set(state.visitedStepIds),
+      // Active path's subPathMeta is not serialized (it's transient metadata
+      // from the parent when this path was started). On restore, it's undefined.
+      subPathMeta: undefined
+    };
+
+    engine._isNavigating = state._isNavigating;
+
+    return engine;
+  }
+
   public subscribe(listener: (event: PathEvent) => void): () => void {
     this.listeners.add(listener);
     return () => this.listeners.delete(listener);
@@ -135,6 +332,26 @@ export class PathEngine {
     return this._startAsync(path, initialData);
   }
 
+  /**
+   * Tears down any active path (and the entire sub-path stack) without firing
+   * lifecycle hooks or emitting `cancelled`, then immediately starts the given
+   * path from scratch.
+   *
+   * Safe to call at any time — whether a path is running, already completed,
+   * or has never been started. Use this to implement a "Start over" button or
+   * to retry a path after completion without remounting the host component.
+   *
+   * @param path        The path definition to (re)start.
+   * @param initialData Data to seed the fresh path with. Defaults to `{}`.
+   */
+  public restart(path: PathDefinition<any>, initialData: PathData = {}): Promise<void> {
+    this.assertPathHasSteps(path);
+    this._isNavigating = false;
+    this.activePath = null;
+    this.pathStack.length = 0;
+    return this._startAsync(path, initialData);
+  }
+
   /**
    * Starts a sub-path on top of the currently active path. Throws if no path
    * is running.
@@ -171,9 +388,11 @@ export class PathEngine {
 
     const cancelledPathId = active.definition.id;
     const cancelledData = { ...active.data };
-    const cancelledMeta = active.subPathMeta;
 
     if (this.pathStack.length > 0) {
+      // Get meta from the parent in the stack
+      const parent = this.pathStack[this.pathStack.length - 1];
+      const cancelledMeta = parent.subPathMeta;
       return this._cancelSubPathAsync(cancelledPathId, cancelledData, cancelledMeta);
     }
 
@@ -185,7 +404,7 @@ export class PathEngine {
   public setData(key: string, value: unknown): Promise<void> {
     const active = this.requireActivePath();
     active.data[key] = value;
-    this.emitStateChanged();
+    this.emitStateChanged("setData");
     return Promise.resolve();
   }
 
@@ -258,6 +477,41 @@ export class PathEngine {
     };
   }
 
+  /**
+   * Exports the current engine state as a plain JSON-serializable object.
+   * Use with storage adapters (e.g. `@daltonr/pathwrite-store-http`) to
+   * persist and restore wizard progress.
+   *
+   * Returns `null` if no path is active.
+   *
+   * **Important:** This only exports the _state_ (data, step position, etc.),
+   * not the path definition. When restoring, you must provide the same
+   * `PathDefinition` to `fromState()`.
+   */
+  public exportState(): SerializedPathState | null {
+    if (this.activePath === null) {
+      return null;
+    }
+
+    const active = this.activePath;
+
+    return {
+      version: 1,
+      pathId: active.definition.id,
+      currentStepIndex: active.currentStepIndex,
+      data: { ...active.data },
+      visitedStepIds: Array.from(active.visitedStepIds),
+      pathStack: this.pathStack.map((p) => ({
+        pathId: p.definition.id,
+        currentStepIndex: p.currentStepIndex,
+        data: { ...p.data },
+        visitedStepIds: Array.from(p.visitedStepIds),
+        subPathMeta: p.subPathMeta ? { ...p.subPathMeta } : undefined
+      })),
+      _isNavigating: this._isNavigating
+    };
+  }
+
   // ---------------------------------------------------------------------------
   // Private async helpers
   // ---------------------------------------------------------------------------
@@ -266,7 +520,12 @@ export class PathEngine {
     if (this._isNavigating) return;
 
     if (this.activePath !== null) {
-      this.pathStack.push(this.activePath);
+      // Store the meta on the parent before pushing to stack
+      const parentWithMeta: ActivePath = {
+        ...this.activePath,
+        subPathMeta
+      };
+      this.pathStack.push(parentWithMeta);
     }
 
     this.activePath = {
@@ -274,7 +533,7 @@ export class PathEngine {
       currentStepIndex: 0,
       data: { ...initialData },
       visitedStepIds: new Set(),
-      subPathMeta
+      subPathMeta: undefined
     };
 
     this._isNavigating = true;
@@ -287,15 +546,15 @@ export class PathEngine {
       return;
     }
 
-    this.emitStateChanged();
+    this.emitStateChanged("start");
 
     try {
       this.applyPatch(await this.enterCurrentStep());
       this._isNavigating = false;
-      this.emitStateChanged();
+      this.emitStateChanged("start");
     } catch (err) {
       this._isNavigating = false;
-      this.emitStateChanged();
+      this.emitStateChanged("start");
       throw err;
     }
   }
@@ -304,7 +563,7 @@ export class PathEngine {
     if (this._isNavigating) return;
 
     this._isNavigating = true;
-    this.emitStateChanged();
+    this.emitStateChanged("next");
 
     try {
       const step = this.getCurrentStep(active);
@@ -324,10 +583,10 @@ export class PathEngine {
       }
 
       this._isNavigating = false;
-      this.emitStateChanged();
+      this.emitStateChanged("next");
     } catch (err) {
       this._isNavigating = false;
-      this.emitStateChanged();
+      this.emitStateChanged("next");
       throw err;
     }
   }
@@ -341,7 +600,7 @@ export class PathEngine {
     if (active.currentStepIndex === 0 && this.pathStack.length === 0) return;
 
     this._isNavigating = true;
-    this.emitStateChanged();
+    this.emitStateChanged("previous");
 
     try {
       const step = this.getCurrentStep(active);
@@ -361,10 +620,10 @@ export class PathEngine {
       }
 
       this._isNavigating = false;
-      this.emitStateChanged();
+      this.emitStateChanged("previous");
     } catch (err) {
       this._isNavigating = false;
-      this.emitStateChanged();
+      this.emitStateChanged("previous");
       throw err;
     }
   }
@@ -373,7 +632,7 @@ export class PathEngine {
     if (this._isNavigating) return;
 
     this._isNavigating = true;
-    this.emitStateChanged();
+    this.emitStateChanged("goToStep");
 
     try {
       const currentStep = this.getCurrentStep(active);
@@ -383,10 +642,10 @@ export class PathEngine {
 
       this.applyPatch(await this.enterCurrentStep());
       this._isNavigating = false;
-      this.emitStateChanged();
+      this.emitStateChanged("goToStep");
     } catch (err) {
       this._isNavigating = false;
-      this.emitStateChanged();
+      this.emitStateChanged("goToStep");
       throw err;
     }
   }
@@ -395,7 +654,7 @@ export class PathEngine {
     if (this._isNavigating) return;
 
     this._isNavigating = true;
-    this.emitStateChanged();
+    this.emitStateChanged("goToStepChecked");
 
     try {
       const currentStep = this.getCurrentStep(active);
@@ -411,10 +670,10 @@ export class PathEngine {
       }
 
       this._isNavigating = false;
-      this.emitStateChanged();
+      this.emitStateChanged("goToStepChecked");
     } catch (err) {
       this._isNavigating = false;
-      this.emitStateChanged();
+      this.emitStateChanged("goToStepChecked");
       throw err;
     }
   }
@@ -430,7 +689,7 @@ export class PathEngine {
     this.activePath = this.pathStack.pop() ?? null;
 
     this._isNavigating = true;
-    this.emitStateChanged();
+    this.emitStateChanged("cancel");
 
     try {
       const parent = this.activePath;
@@ -451,10 +710,10 @@ export class PathEngine {
       }
 
       this._isNavigating = false;
-      this.emitStateChanged();
+      this.emitStateChanged("cancel");
     } catch (err) {
       this._isNavigating = false;
-      this.emitStateChanged();
+      this.emitStateChanged("cancel");
       throw err;
     }
   }
@@ -463,11 +722,12 @@ export class PathEngine {
     const finished = this.requireActivePath();
     const finishedPathId = finished.definition.id;
     const finishedData = { ...finished.data };
-    const finishedMeta = finished.subPathMeta;
 
     if (this.pathStack.length > 0) {
-      this.activePath = this.pathStack.pop()!;
-      const parent = this.activePath;
+      const parent = this.pathStack.pop()!;
+      // The meta is stored on the parent, not the sub-path
+      const finishedMeta = parent.subPathMeta;
+      this.activePath = parent;
       const parentStep = this.getCurrentStep(parent);
 
       if (parentStep.onSubPathComplete) {
@@ -517,8 +777,8 @@ export class PathEngine {
     }
   }
 
-  private emitStateChanged(): void {
-    this.emit({ type: "stateChanged", snapshot: this.snapshot()! });
+  private emitStateChanged(cause: StateChangeCause): void {
+    this.emit({ type: "stateChanged", cause, snapshot: this.snapshot()! });
   }
 
   private getCurrentStep(active: ActivePath): PathStep {
@@ -620,6 +880,15 @@ export class PathEngine {
    * Evaluates a guard function synchronously for inclusion in the snapshot.
    * If the guard is absent, returns `true`.
    * If the guard returns a `Promise`, returns `true` (optimistic default).
+   *
+   * **Note:** Guards are evaluated on every snapshot, including the very first one
+   * emitted at the start of a path — _before_ `onEnter` has run on that step.
+   * This means `data` will still reflect the `initialData` passed to `start()`.
+   * Write guards defensively (e.g. `(data.name ?? "").trim().length > 0`) so they
+   * do not throw when optional fields are absent on first entry.
+   *
+   * If a guard throws, the error is caught, a `console.warn` is emitted, and the
+   * safe default (`true`) is returned so the UI remains operable.
    */
   private evaluateGuardSync(
     guard: ((ctx: PathStepContext) => boolean | Promise<boolean>) | undefined,
@@ -633,15 +902,41 @@ export class PathEngine {
       data: { ...active.data },
       isFirstEntry: !active.visitedStepIds.has(step.id)
     };
-    const result = guard(ctx);
-    if (typeof result === "boolean") return result;
-    return true;
+    try {
+      const result = guard(ctx);
+      if (typeof result === "boolean") return result;
+      // Async guard detected - warn and return optimistic default
+      if (result && typeof result.then === "function") {
+        console.warn(
+          `[pathwrite] Async guard detected on step "${step.id}". ` +
+          `Guards in snapshots must be synchronous. ` +
+          `Returning true (optimistic) as default. ` +
+          `The async guard will still be enforced during actual navigation.`
+        );
+      }
+      return true;
+    } catch (err) {
+      console.warn(
+        `[pathwrite] Guard on step "${step.id}" threw an error during snapshot evaluation. ` +
+        `Returning true (allow navigation) as a safe default. ` +
+        `Note: guards are evaluated before onEnter runs on first entry — ` +
+        `ensure guards handle missing/undefined data gracefully.`,
+        err
+      );
+      return true;
+    }
   }
 
   /**
    * Evaluates a validationMessages function synchronously for inclusion in the snapshot.
    * If the hook is absent, returns `[]`.
    * If the hook returns a `Promise`, returns `[]` (async hooks are not supported in snapshots).
+   *
+   * **Note:** Like guards, `validationMessages` is evaluated before `onEnter` runs on first
+   * entry. Write it defensively so it does not throw when fields are absent.
+   *
+   * If the function throws, the error is caught, a `console.warn` is emitted, and `[]`
+   * is returned so validation messages do not block the UI unexpectedly.
    */
   private evaluateValidationMessagesSync(
     fn: ((ctx: PathStepContext) => string[] | Promise<string[]>) | undefined,
@@ -655,9 +950,29 @@ export class PathEngine {
       data: { ...active.data },
       isFirstEntry: !active.visitedStepIds.has(step.id)
     };
-    const result = fn(ctx);
-    if (Array.isArray(result)) return result;
-    return [];
+    try {
+      const result = fn(ctx);
+      if (Array.isArray(result)) return result;
+      // Async validationMessages detected - warn and return empty array
+      if (result && typeof result.then === "function") {
+        console.warn(
+          `[pathwrite] Async validationMessages detected on step "${step.id}". ` +
+          `validationMessages in snapshots must be synchronous. ` +
+          `Returning [] as default. ` +
+          `Use synchronous validation or move async checks to canMoveNext.`
+        );
+      }
+      return [];
+    } catch (err) {
+      console.warn(
+        `[pathwrite] validationMessages on step "${step.id}" threw an error during snapshot evaluation. ` +
+        `Returning [] as a safe default. ` +
+        `Note: validationMessages is evaluated before onEnter runs on first entry — ` +
+        `ensure it handles missing/undefined data gracefully.`,
+        err
+      );
+      return [];
+    }
   }
 }