Initial Commit

packages/foundation/flow/undo/src/errors/undo-error.ts

@@ -0,0 +1,65 @@
+import { defineCodes, SuaveplanError } from "@suaveplan/error";
+
+/**
+ * Stable error-code registry for `@suaveplan/undo`.
+ *
+ * Each code is scoped under the `UNDO` namespace via `defineCodes`, producing
+ * fully-qualified strings such as `"UNDO.EMPTY_STACK"` that are safe for
+ * `error.code`-based discrimination across module boundaries.
+ */
+export const UNDO_CODES = defineCodes("UNDO", [
+    "EMPTY_STACK",
+    "AT_BRANCH_ROOT",
+    "DEPENDENCY_CONFLICT",
+    "COMMAND_FAILED",
+    "TRANSACTION_ACTIVE",
+    "TRANSACTION_INACTIVE",
+] as const);
+
+export type UndoCode = (typeof UNDO_CODES)[keyof typeof UNDO_CODES];
+
+/**
+ * Context fields carried by an `UndoError`.
+ */
+export interface UndoErrorContext {
+    /** ID of the command involved (if applicable). */
+    commandId?: string;
+    /** ID of the branch involved (if applicable). */
+    branchId?: string;
+    /** IDs of commands that conflict with a selective undo request. */
+    conflictIds?: string[];
+}
+
+/**
+ * Typed error for all `@suaveplan/undo` failures.
+ *
+ * Extends `SuaveplanError` so callers can discriminate via
+ * `error instanceof UndoError` or the stable `error.code` property.
+ *
+ * @example
+ * ```ts
+ * import { UndoError, UNDO_CODES } from "@suaveplan/undo/errors/undo-error";
+ *
+ * try {
+ *   stack.undo();
+ * } catch (err) {
+ *   if (err instanceof UndoError && err.code === UNDO_CODES.EMPTY_STACK) {
+ *     console.warn("Nothing to undo");
+ *   }
+ * }
+ * ```
+ */
+export class UndoError extends SuaveplanError<UndoCode> {
+    public constructor(
+        code: UndoCode,
+        message: string,
+        options?: { cause?: Error; context?: UndoErrorContext }
+    ) {
+        super(
+            code,
+            message,
+            options as { cause?: Error; context?: Record<string, unknown> }
+        );
+        this.name = "UndoError";
+    }
+}