awaitly 1.0.0

package/dist/tagged-error.d.cts

@@ -0,0 +1,252 @@
+/**
+ * awaitly/tagged-error
+ *
+ * Factory for creating tagged error types with exhaustive pattern matching.
+ * Enables TypeScript to enforce that all error variants are handled.
+ *
+ * @example
+ * ```typescript
+ * // Define error types (Props via generic)
+ * class NotFoundError extends TaggedError("NotFoundError")<{
+ *   id: string;
+ *   resource: string;
+ * }> {}
+ *
+ * // Define with type-safe message (Props inferred from callback annotation)
+ * class ValidationError extends TaggedError("ValidationError", {
+ *   message: (p: { field: string; reason: string }) => `Invalid ${p.field}: ${p.reason}`,
+ * }) {}
+ *
+ * // Create instances
+ * const error = new NotFoundError({ id: "123", resource: "User" });
+ *
+ * // Runtime type check: instanceof TaggedError works!
+ * console.log(error instanceof TaggedError); // true
+ *
+ * // Exhaustive matching
+ * type AppError = NotFoundError | ValidationError;
+ * const message = TaggedError.match(error as AppError, {
+ *   NotFoundError: (e) => `Missing: ${e.resource} ${e.id}`,
+ *   ValidationError: (e) => `Invalid ${e.field}: ${e.reason}`,
+ * });
+ * ```
+ */
+/**
+ * Options for Error constructor (compatible with ES2022 ErrorOptions).
+ */
+interface TaggedErrorOptions {
+    cause?: unknown;
+}
+/**
+ * Options for TaggedError factory with type-safe message callback.
+ */
+interface TaggedErrorCreateOptions<Props extends Record<string, unknown>> {
+    /** Custom message generator from props. Annotate parameter for type safety. */
+    message: (props: Props) => string;
+}
+/**
+ * Base interface for all tagged errors.
+ */
+interface TaggedErrorBase extends Error {
+    readonly _tag: string;
+}
+/**
+ * Instance type for factory-created TaggedErrors.
+ */
+type TaggedErrorInstance<Tag extends string, Props> = TaggedErrorBase & {
+    readonly _tag: Tag;
+} & Readonly<Props>;
+/**
+ * Constructor args type - conditionally optional based on whether Props has required fields.
+ * - If Props is empty or all properties are optional: props argument is optional
+ * - If Props has any required properties: props argument is required
+ * @internal
+ */
+type ConstructorArgs<Props extends Record<string, unknown>> = {} extends Props ? [props?: Props | void, options?: TaggedErrorOptions] : [props: Props, options?: TaggedErrorOptions];
+/**
+ * Constructor type returned by TaggedError factory.
+ */
+interface TaggedErrorConstructor<Tag extends string, Props extends Record<string, unknown>> {
+    new (...args: ConstructorArgs<Props>): TaggedErrorInstance<Tag, Props>;
+    readonly prototype: TaggedErrorInstance<Tag, Props>;
+}
+/**
+ * Generic class factory type that allows `<Props>` parameterization.
+ * This enables the Effect.js-style syntax: `class X extends TaggedError("X")<Props> {}`
+ * @internal
+ */
+interface TaggedErrorClassFactory<Tag extends string> {
+    new <Props extends Record<string, unknown> = Record<string, never>>(...args: ConstructorArgs<Props>): TaggedErrorInstance<Tag, Props>;
+}
+/**
+ * Helper type to extract return type from a function type.
+ * @internal
+ */
+type FnReturnType<T> = T extends (...args: any[]) => infer R ? R : never;
+/**
+ * Helper type to get union of return types from all handlers.
+ * @internal
+ */
+type HandlersReturnType<H> = {
+    [K in keyof H]: FnReturnType<H[K]>;
+}[keyof H];
+/**
+ * Helper type to extract keys whose values are definitely functions (not undefined).
+ * Only excludes a tag from the fallback type if its handler is guaranteed to be
+ * a function. Keys where the value type includes undefined are NOT excluded,
+ * ensuring type safety with dynamic/conditional handlers.
+ * @internal
+ */
+type DefinitelyHandledKeys<H> = {
+    [K in keyof H]-?: undefined extends H[K] ? never : K;
+}[keyof H];
+/**
+ * Factory function to create tagged error classes.
+ *
+ * Two usage patterns:
+ *
+ * 1. **Props via generic** (default message is tag name):
+ *    ```typescript
+ *    class NotFoundError extends TaggedError("NotFoundError")<{ id: string }> {}
+ *    ```
+ *
+ * 2. **Props inferred from message callback** (type-safe message):
+ *    ```typescript
+ *    class NotFoundError extends TaggedError("NotFoundError", {
+ *      message: (p: { id: string }) => `Not found: ${p.id}`,
+ *    }) {}
+ *    ```
+ *
+ * Both support `instanceof TaggedError` checks at runtime.
+ *
+ * @param tag - The unique tag string for this error type
+ * @param options - Optional configuration with message generator (annotate param for type safety)
+ * @returns A class constructor that can be extended
+ */
+declare function TaggedError<Tag extends string>(tag: Tag): TaggedErrorClassFactory<Tag>;
+declare function TaggedError<Tag extends string, Props extends Record<string, unknown>>(tag: Tag, options: TaggedErrorCreateOptions<Props>): TaggedErrorConstructor<Tag, Props>;
+/**
+ * Namespace for static methods on TaggedError.
+ */
+declare namespace TaggedError {
+    /**
+     * Type guard to check if a value is an Error instance.
+     */
+    function isError(value: unknown): value is Error;
+    /**
+     * Type guard to check if a value is a TaggedError instance.
+     * Uses the same check as `instanceof TaggedError` - only genuine
+     * TaggedError instances (created via the factory) pass this guard.
+     */
+    function isTaggedError(value: unknown): value is TaggedErrorBase;
+    /**
+     * Exhaustively matches on a tagged error, requiring handlers for all variants.
+     *
+     * TypeScript will error if any variant in the error union is not handled.
+     *
+     * @param error - The tagged error to match
+     * @param handlers - Object mapping _tag values to handler functions
+     * @returns The return value of the matched handler
+     *
+     * @example
+     * ```typescript
+     * type AppError = NotFoundError | ValidationError;
+     *
+     * const message = TaggedError.match(error, {
+     *   NotFoundError: (e) => `Not found: ${e.id}`,
+     *   ValidationError: (e) => `Invalid: ${e.field}`,
+     * });
+     * ```
+     */
+    function match<E extends TaggedErrorBase, H extends {
+        [K in E["_tag"]]: (e: Extract<E, {
+            _tag: K;
+        }>) => unknown;
+    }>(error: E, handlers: H): HandlersReturnType<H>;
+    /**
+     * Partially matches on a tagged error with a fallback for unhandled variants.
+     *
+     * The fallback receives variants that are NOT definitely handled. A tag is
+     * considered "definitely handled" only if its handler is a function (not
+     * `undefined`). This ensures type safety even with dynamic/conditional handlers:
+     *
+     * ```typescript
+     * const maybeHandle = featureFlag ? (e) => e.id : undefined;
+     * TaggedError.matchPartial(
+     *   error,
+     *   { NotFoundError: maybeHandle },  // maybeHandle might be undefined
+     *   (e) => e._tag  // e correctly includes NotFoundError
+     * );
+     * ```
+     *
+     * @param error - The tagged error to match
+     * @param handlers - Partial object mapping _tag values to handler functions
+     * @param otherwise - Fallback handler for unmatched variants
+     * @returns The return value of the matched handler or fallback
+     *
+     * @example
+     * ```typescript
+     * const message = TaggedError.matchPartial(
+     *   error,
+     *   { NotFoundError: (e) => `Not found: ${e.id}` },
+     *   (e) => `Other error: ${e.message}`
+     * );
+     * ```
+     */
+    function matchPartial<E extends TaggedErrorBase, H extends Partial<{
+        [K in E["_tag"]]: (e: Extract<E, {
+            _tag: K;
+        }>) => unknown;
+    }>, T>(error: E, handlers: H, otherwise: (e: Exclude<E, {
+        _tag: DefinitelyHandledKeys<H>;
+    }>) => T): HandlersReturnType<H> | T;
+}
+
+/**
+ * Helper type to extract the _tag literal type from a TaggedError.
+ *
+ * @example
+ * ```typescript
+ * class MyError extends TaggedError("MyError")<{ id: string }> {}
+ * type Tag = TagOf<MyError>; // "MyError"
+ * ```
+ */
+type TagOf<E extends TaggedErrorBase> = E["_tag"];
+/**
+ * Helper type to extract a specific variant from a TaggedError union by tag.
+ *
+ * @example
+ * ```typescript
+ * type AppError = NotFoundError | ValidationError;
+ * type NotFound = ErrorByTag<AppError, "NotFoundError">; // NotFoundError
+ * ```
+ */
+type ErrorByTag<E extends TaggedErrorBase, Tag extends E["_tag"]> = Extract<E, {
+    _tag: Tag;
+}>;
+/**
+ * Reserved keys that are stripped from user props at runtime.
+ * These keys cannot be used as user-defined properties:
+ * - _tag: discriminant for pattern matching
+ * - name, message, stack: Error internals (preserved for logging/debugging)
+ *
+ * Note: 'cause' is NOT reserved - it can be used as a user prop.
+ */
+type ReservedErrorKeys = "_tag" | "name" | "message" | "stack";
+/**
+ * Helper type to extract props from a TaggedError.
+ * Excludes reserved keys that are stripped at runtime.
+ *
+ * @example
+ * ```typescript
+ * class MyError extends TaggedError("MyError")<{ id: string }> {}
+ * type Props = PropsOf<MyError>; // { id: string }
+ *
+ * // 'cause' is allowed as a user prop
+ * class DomainError extends TaggedError("DomainError")<{ cause: { field: string } }> {}
+ * type DomainProps = PropsOf<DomainError>; // { cause: { field: string } }
+ * ```
+ */
+type PropsOf<E extends TaggedErrorBase> = Omit<E, ReservedErrorKeys>;
+
+export { type ErrorByTag, type PropsOf, type TagOf, TaggedError, type TaggedErrorBase, type TaggedErrorConstructor, type TaggedErrorCreateOptions, type TaggedErrorOptions };

package/dist/tagged-error.d.ts

@@ -0,0 +1,252 @@
+/**
+ * awaitly/tagged-error
+ *
+ * Factory for creating tagged error types with exhaustive pattern matching.
+ * Enables TypeScript to enforce that all error variants are handled.
+ *
+ * @example
+ * ```typescript
+ * // Define error types (Props via generic)
+ * class NotFoundError extends TaggedError("NotFoundError")<{
+ *   id: string;
+ *   resource: string;
+ * }> {}
+ *
+ * // Define with type-safe message (Props inferred from callback annotation)
+ * class ValidationError extends TaggedError("ValidationError", {
+ *   message: (p: { field: string; reason: string }) => `Invalid ${p.field}: ${p.reason}`,
+ * }) {}
+ *
+ * // Create instances
+ * const error = new NotFoundError({ id: "123", resource: "User" });
+ *
+ * // Runtime type check: instanceof TaggedError works!
+ * console.log(error instanceof TaggedError); // true
+ *
+ * // Exhaustive matching
+ * type AppError = NotFoundError | ValidationError;
+ * const message = TaggedError.match(error as AppError, {
+ *   NotFoundError: (e) => `Missing: ${e.resource} ${e.id}`,
+ *   ValidationError: (e) => `Invalid ${e.field}: ${e.reason}`,
+ * });
+ * ```
+ */
+/**
+ * Options for Error constructor (compatible with ES2022 ErrorOptions).
+ */
+interface TaggedErrorOptions {
+    cause?: unknown;
+}
+/**
+ * Options for TaggedError factory with type-safe message callback.
+ */
+interface TaggedErrorCreateOptions<Props extends Record<string, unknown>> {
+    /** Custom message generator from props. Annotate parameter for type safety. */
+    message: (props: Props) => string;
+}
+/**
+ * Base interface for all tagged errors.
+ */
+interface TaggedErrorBase extends Error {
+    readonly _tag: string;
+}
+/**
+ * Instance type for factory-created TaggedErrors.
+ */
+type TaggedErrorInstance<Tag extends string, Props> = TaggedErrorBase & {
+    readonly _tag: Tag;
+} & Readonly<Props>;
+/**
+ * Constructor args type - conditionally optional based on whether Props has required fields.
+ * - If Props is empty or all properties are optional: props argument is optional
+ * - If Props has any required properties: props argument is required
+ * @internal
+ */
+type ConstructorArgs<Props extends Record<string, unknown>> = {} extends Props ? [props?: Props | void, options?: TaggedErrorOptions] : [props: Props, options?: TaggedErrorOptions];
+/**
+ * Constructor type returned by TaggedError factory.
+ */
+interface TaggedErrorConstructor<Tag extends string, Props extends Record<string, unknown>> {
+    new (...args: ConstructorArgs<Props>): TaggedErrorInstance<Tag, Props>;
+    readonly prototype: TaggedErrorInstance<Tag, Props>;
+}
+/**
+ * Generic class factory type that allows `<Props>` parameterization.
+ * This enables the Effect.js-style syntax: `class X extends TaggedError("X")<Props> {}`
+ * @internal
+ */
+interface TaggedErrorClassFactory<Tag extends string> {
+    new <Props extends Record<string, unknown> = Record<string, never>>(...args: ConstructorArgs<Props>): TaggedErrorInstance<Tag, Props>;
+}
+/**
+ * Helper type to extract return type from a function type.
+ * @internal
+ */
+type FnReturnType<T> = T extends (...args: any[]) => infer R ? R : never;
+/**
+ * Helper type to get union of return types from all handlers.
+ * @internal
+ */
+type HandlersReturnType<H> = {
+    [K in keyof H]: FnReturnType<H[K]>;
+}[keyof H];
+/**
+ * Helper type to extract keys whose values are definitely functions (not undefined).
+ * Only excludes a tag from the fallback type if its handler is guaranteed to be
+ * a function. Keys where the value type includes undefined are NOT excluded,
+ * ensuring type safety with dynamic/conditional handlers.
+ * @internal
+ */
+type DefinitelyHandledKeys<H> = {
+    [K in keyof H]-?: undefined extends H[K] ? never : K;
+}[keyof H];
+/**
+ * Factory function to create tagged error classes.
+ *
+ * Two usage patterns:
+ *
+ * 1. **Props via generic** (default message is tag name):
+ *    ```typescript
+ *    class NotFoundError extends TaggedError("NotFoundError")<{ id: string }> {}
+ *    ```
+ *
+ * 2. **Props inferred from message callback** (type-safe message):
+ *    ```typescript
+ *    class NotFoundError extends TaggedError("NotFoundError", {
+ *      message: (p: { id: string }) => `Not found: ${p.id}`,
+ *    }) {}
+ *    ```
+ *
+ * Both support `instanceof TaggedError` checks at runtime.
+ *
+ * @param tag - The unique tag string for this error type
+ * @param options - Optional configuration with message generator (annotate param for type safety)
+ * @returns A class constructor that can be extended
+ */
+declare function TaggedError<Tag extends string>(tag: Tag): TaggedErrorClassFactory<Tag>;
+declare function TaggedError<Tag extends string, Props extends Record<string, unknown>>(tag: Tag, options: TaggedErrorCreateOptions<Props>): TaggedErrorConstructor<Tag, Props>;
+/**
+ * Namespace for static methods on TaggedError.
+ */
+declare namespace TaggedError {
+    /**
+     * Type guard to check if a value is an Error instance.
+     */
+    function isError(value: unknown): value is Error;
+    /**
+     * Type guard to check if a value is a TaggedError instance.
+     * Uses the same check as `instanceof TaggedError` - only genuine
+     * TaggedError instances (created via the factory) pass this guard.
+     */
+    function isTaggedError(value: unknown): value is TaggedErrorBase;
+    /**
+     * Exhaustively matches on a tagged error, requiring handlers for all variants.
+     *
+     * TypeScript will error if any variant in the error union is not handled.
+     *
+     * @param error - The tagged error to match
+     * @param handlers - Object mapping _tag values to handler functions
+     * @returns The return value of the matched handler
+     *
+     * @example
+     * ```typescript
+     * type AppError = NotFoundError | ValidationError;
+     *
+     * const message = TaggedError.match(error, {
+     *   NotFoundError: (e) => `Not found: ${e.id}`,
+     *   ValidationError: (e) => `Invalid: ${e.field}`,
+     * });
+     * ```
+     */
+    function match<E extends TaggedErrorBase, H extends {
+        [K in E["_tag"]]: (e: Extract<E, {
+            _tag: K;
+        }>) => unknown;
+    }>(error: E, handlers: H): HandlersReturnType<H>;
+    /**
+     * Partially matches on a tagged error with a fallback for unhandled variants.
+     *
+     * The fallback receives variants that are NOT definitely handled. A tag is
+     * considered "definitely handled" only if its handler is a function (not
+     * `undefined`). This ensures type safety even with dynamic/conditional handlers:
+     *
+     * ```typescript
+     * const maybeHandle = featureFlag ? (e) => e.id : undefined;
+     * TaggedError.matchPartial(
+     *   error,
+     *   { NotFoundError: maybeHandle },  // maybeHandle might be undefined
+     *   (e) => e._tag  // e correctly includes NotFoundError
+     * );
+     * ```
+     *
+     * @param error - The tagged error to match
+     * @param handlers - Partial object mapping _tag values to handler functions
+     * @param otherwise - Fallback handler for unmatched variants
+     * @returns The return value of the matched handler or fallback
+     *
+     * @example
+     * ```typescript
+     * const message = TaggedError.matchPartial(
+     *   error,
+     *   { NotFoundError: (e) => `Not found: ${e.id}` },
+     *   (e) => `Other error: ${e.message}`
+     * );
+     * ```
+     */
+    function matchPartial<E extends TaggedErrorBase, H extends Partial<{
+        [K in E["_tag"]]: (e: Extract<E, {
+            _tag: K;
+        }>) => unknown;
+    }>, T>(error: E, handlers: H, otherwise: (e: Exclude<E, {
+        _tag: DefinitelyHandledKeys<H>;
+    }>) => T): HandlersReturnType<H> | T;
+}
+
+/**
+ * Helper type to extract the _tag literal type from a TaggedError.
+ *
+ * @example
+ * ```typescript
+ * class MyError extends TaggedError("MyError")<{ id: string }> {}
+ * type Tag = TagOf<MyError>; // "MyError"
+ * ```
+ */
+type TagOf<E extends TaggedErrorBase> = E["_tag"];
+/**
+ * Helper type to extract a specific variant from a TaggedError union by tag.
+ *
+ * @example
+ * ```typescript
+ * type AppError = NotFoundError | ValidationError;
+ * type NotFound = ErrorByTag<AppError, "NotFoundError">; // NotFoundError
+ * ```
+ */
+type ErrorByTag<E extends TaggedErrorBase, Tag extends E["_tag"]> = Extract<E, {
+    _tag: Tag;
+}>;
+/**
+ * Reserved keys that are stripped from user props at runtime.
+ * These keys cannot be used as user-defined properties:
+ * - _tag: discriminant for pattern matching
+ * - name, message, stack: Error internals (preserved for logging/debugging)
+ *
+ * Note: 'cause' is NOT reserved - it can be used as a user prop.
+ */
+type ReservedErrorKeys = "_tag" | "name" | "message" | "stack";
+/**
+ * Helper type to extract props from a TaggedError.
+ * Excludes reserved keys that are stripped at runtime.
+ *
+ * @example
+ * ```typescript
+ * class MyError extends TaggedError("MyError")<{ id: string }> {}
+ * type Props = PropsOf<MyError>; // { id: string }
+ *
+ * // 'cause' is allowed as a user prop
+ * class DomainError extends TaggedError("DomainError")<{ cause: { field: string } }> {}
+ * type DomainProps = PropsOf<DomainError>; // { cause: { field: string } }
+ * ```
+ */
+type PropsOf<E extends TaggedErrorBase> = Omit<E, ReservedErrorKeys>;
+
+export { type ErrorByTag, type PropsOf, type TagOf, TaggedError, type TaggedErrorBase, type TaggedErrorConstructor, type TaggedErrorCreateOptions, type TaggedErrorOptions };

package/dist/tagged-error.js

@@ -0,0 +1,2 @@
+var a=class extends Error{_tag};function c(r,i){return class extends a{_tag=r;constructor(t,s){let u=i?.message?i.message(t??{}):r;if(super(u),this.name=r,Object.setPrototypeOf(this,new.target.prototype),t&&typeof t=="object"){let{_tag:e,name:o,message:g,stack:d,...n}=t,p=Object.prototype.hasOwnProperty.call(n,"cause"),T=p?n.cause:void 0;p&&delete n.cause;let E=s?.cause!==void 0;if(p&&E)throw new TypeError("TaggedError: cannot provide 'cause' in props when also setting ErrorOptions.cause");Object.assign(this,n),p&&(this.cause=T),E&&(this.cause=s?.cause)}else s?.cause!==void 0&&(this.cause=s.cause)}}}Object.defineProperty(c,Symbol.hasInstance,{value:r=>r instanceof a});(u=>{function r(e){return e instanceof Error}u.isError=r;function i(e){return e instanceof a}u.isTaggedError=i;function t(e,o){let g=e._tag,d=o[g];return d(e)}u.match=t;function s(e,o,g){let d=e._tag,n=o[d];return n?n(e):g(e)}u.matchPartial=s})(c||={});export{c as TaggedError};
+//# sourceMappingURL=tagged-error.js.map

package/dist/tagged-error.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/tagged-error.ts"],"sourcesContent":["/**\n * awaitly/tagged-error\n *\n * Factory for creating tagged error types with exhaustive pattern matching.\n * Enables TypeScript to enforce that all error variants are handled.\n *\n * @example\n * ```typescript\n * // Define error types (Props via generic)\n * class NotFoundError extends TaggedError(\"NotFoundError\")<{\n *   id: string;\n *   resource: string;\n * }> {}\n *\n * // Define with type-safe message (Props inferred from callback annotation)\n * class ValidationError extends TaggedError(\"ValidationError\", {\n *   message: (p: { field: string; reason: string }) => `Invalid ${p.field}: ${p.reason}`,\n * }) {}\n *\n * // Create instances\n * const error = new NotFoundError({ id: \"123\", resource: \"User\" });\n *\n * // Runtime type check: instanceof TaggedError works!\n * console.log(error instanceof TaggedError); // true\n *\n * // Exhaustive matching\n * type AppError = NotFoundError | ValidationError;\n * const message = TaggedError.match(error as AppError, {\n *   NotFoundError: (e) => `Missing: ${e.resource} ${e.id}`,\n *   ValidationError: (e) => `Invalid ${e.field}: ${e.reason}`,\n * });\n * ```\n */\n\n/**\n * Options for Error constructor (compatible with ES2022 ErrorOptions).\n */\nexport interface TaggedErrorOptions {\n  cause?: unknown;\n}\n\n/**\n * Options for TaggedError factory with type-safe message callback.\n */\nexport interface TaggedErrorCreateOptions<Props extends Record<string, unknown>> {\n  /** Custom message generator from props. Annotate parameter for type safety. */\n  message: (props: Props) => string;\n}\n\n/**\n * Base interface for all tagged errors.\n */\nexport interface TaggedErrorBase extends Error {\n  readonly _tag: string;\n}\n\n/**\n * Internal base class for instanceof checks.\n * All TaggedError-created classes extend this.\n * @internal\n */\nclass InternalTaggedErrorBase extends Error implements TaggedErrorBase {\n  readonly _tag!: string;\n}\n\n/**\n * Instance type for factory-created TaggedErrors.\n */\ntype TaggedErrorInstance<Tag extends string, Props> = TaggedErrorBase & {\n  readonly _tag: Tag;\n} & Readonly<Props>;\n\n/**\n * Constructor args type - conditionally optional based on whether Props has required fields.\n * - If Props is empty or all properties are optional: props argument is optional\n * - If Props has any required properties: props argument is required\n * @internal\n */\n// eslint-disable-next-line @typescript-eslint/no-empty-object-type\ntype ConstructorArgs<Props extends Record<string, unknown>> = {} extends Props\n  ? [props?: Props | void, options?: TaggedErrorOptions]\n  : [props: Props, options?: TaggedErrorOptions];\n\n/**\n * Constructor type returned by TaggedError factory.\n */\nexport interface TaggedErrorConstructor<\n  Tag extends string,\n  Props extends Record<string, unknown>,\n> {\n  new (...args: ConstructorArgs<Props>): TaggedErrorInstance<Tag, Props>;\n  readonly prototype: TaggedErrorInstance<Tag, Props>;\n}\n\n/**\n * Generic class factory type that allows `<Props>` parameterization.\n * This enables the Effect.js-style syntax: `class X extends TaggedError(\"X\")<Props> {}`\n * @internal\n */\ninterface TaggedErrorClassFactory<Tag extends string> {\n  new <Props extends Record<string, unknown> = Record<string, never>>(\n    ...args: ConstructorArgs<Props>\n  ): TaggedErrorInstance<Tag, Props>;\n}\n\n/**\n * Helper type to extract return type from a function type.\n * @internal\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\ntype FnReturnType<T> = T extends (...args: any[]) => infer R ? R : never;\n\n/**\n * Helper type to get union of return types from all handlers.\n * @internal\n */\ntype HandlersReturnType<H> = { [K in keyof H]: FnReturnType<H[K]> }[keyof H];\n\n/**\n * Helper type to extract keys whose values are definitely functions (not undefined).\n * Only excludes a tag from the fallback type if its handler is guaranteed to be\n * a function. Keys where the value type includes undefined are NOT excluded,\n * ensuring type safety with dynamic/conditional handlers.\n * @internal\n */\ntype DefinitelyHandledKeys<H> = {\n  [K in keyof H]-?: undefined extends H[K] ? never : K;\n}[keyof H];\n\n/**\n * Factory function to create tagged error classes.\n *\n * Two usage patterns:\n *\n * 1. **Props via generic** (default message is tag name):\n *    ```typescript\n *    class NotFoundError extends TaggedError(\"NotFoundError\")<{ id: string }> {}\n *    ```\n *\n * 2. **Props inferred from message callback** (type-safe message):\n *    ```typescript\n *    class NotFoundError extends TaggedError(\"NotFoundError\", {\n *      message: (p: { id: string }) => `Not found: ${p.id}`,\n *    }) {}\n *    ```\n *\n * Both support `instanceof TaggedError` checks at runtime.\n *\n * @param tag - The unique tag string for this error type\n * @param options - Optional configuration with message generator (annotate param for type safety)\n * @returns A class constructor that can be extended\n */\n\n// Overload 1: No options - use <Props> generic syntax, default message is tag\nfunction TaggedError<Tag extends string>(\n  tag: Tag\n): TaggedErrorClassFactory<Tag>;\n\n// Overload 2: With message option - Props inferred from callback parameter annotation\nfunction TaggedError<Tag extends string, Props extends Record<string, unknown>>(\n  tag: Tag,\n  options: TaggedErrorCreateOptions<Props>\n): TaggedErrorConstructor<Tag, Props>;\n\n// Implementation\nfunction TaggedError<Tag extends string, Props extends Record<string, unknown>>(\n  tag: Tag,\n  options?: TaggedErrorCreateOptions<Props>\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n): any {\n  return class extends InternalTaggedErrorBase {\n    override readonly _tag: Tag = tag;\n\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    constructor(props?: any, errorOptions?: TaggedErrorOptions) {\n      // Generate message: call callback if provided (even for prop-less errors), else use tag\n      const message = options?.message ? options.message(props ?? {}) : tag;\n\n      super(message);\n      this.name = tag;\n\n      // Maintains proper prototype chain for instanceof checks\n      Object.setPrototypeOf(this, new.target.prototype);\n\n      // Assign props to instance, stripping reserved keys:\n      // - _tag: discriminant for pattern matching (cannot be forged)\n      // - name, message, stack: Error internals (preserve for logging/debugging)\n      // Note: 'cause' is allowed as a user prop (common for domain errors)\n      if (props && typeof props === \"object\") {\n        const {\n          _tag: _,\n          name: _n,\n          message: _m,\n          stack: _s,\n          ...safeProps\n        } = props;\n\n        const hasUserCause = Object.prototype.hasOwnProperty.call(\n          safeProps,\n          \"cause\"\n        );\n        const userCause = hasUserCause\n          ? (safeProps as { cause?: unknown }).cause\n          : undefined;\n        if (hasUserCause) {\n          delete (safeProps as { cause?: unknown }).cause;\n        }\n\n        const hasOptionsCause = errorOptions?.cause !== undefined;\n        if (hasUserCause && hasOptionsCause) {\n          throw new TypeError(\n            \"TaggedError: cannot provide 'cause' in props when also setting ErrorOptions.cause\"\n          );\n        }\n\n        Object.assign(this, safeProps);\n\n        if (hasUserCause) {\n          (this as { cause?: unknown }).cause = userCause;\n        }\n        if (hasOptionsCause) {\n          (this as { cause?: unknown }).cause = errorOptions?.cause;\n        }\n      } else if (errorOptions?.cause !== undefined) {\n        (this as { cause?: unknown }).cause = errorOptions.cause;\n      }\n    }\n  };\n}\n\n// Add Symbol.hasInstance so `instanceof TaggedError` works\nObject.defineProperty(TaggedError, Symbol.hasInstance, {\n  value: (instance: unknown): boolean => instance instanceof InternalTaggedErrorBase,\n});\n\n/**\n * Namespace for static methods on TaggedError.\n */\n// eslint-disable-next-line @typescript-eslint/no-namespace\nnamespace TaggedError {\n  /**\n   * Type guard to check if a value is an Error instance.\n   */\n  export function isError(value: unknown): value is Error {\n    return value instanceof Error;\n  }\n\n  /**\n   * Type guard to check if a value is a TaggedError instance.\n   * Uses the same check as `instanceof TaggedError` - only genuine\n   * TaggedError instances (created via the factory) pass this guard.\n   */\n  export function isTaggedError(value: unknown): value is TaggedErrorBase {\n    return value instanceof InternalTaggedErrorBase;\n  }\n\n  /**\n   * Exhaustively matches on a tagged error, requiring handlers for all variants.\n   *\n   * TypeScript will error if any variant in the error union is not handled.\n   *\n   * @param error - The tagged error to match\n   * @param handlers - Object mapping _tag values to handler functions\n   * @returns The return value of the matched handler\n   *\n   * @example\n   * ```typescript\n   * type AppError = NotFoundError | ValidationError;\n   *\n   * const message = TaggedError.match(error, {\n   *   NotFoundError: (e) => `Not found: ${e.id}`,\n   *   ValidationError: (e) => `Invalid: ${e.field}`,\n   * });\n   * ```\n   */\n  export function match<\n    E extends TaggedErrorBase,\n    H extends { [K in E[\"_tag\"]]: (e: Extract<E, { _tag: K }>) => unknown },\n  >(error: E, handlers: H): HandlersReturnType<H> {\n    const tag = error._tag as E[\"_tag\"];\n    const handler = handlers[tag];\n    return handler(\n      error as Extract<E, { _tag: typeof tag }>\n    ) as HandlersReturnType<H>;\n  }\n\n  /**\n   * Partially matches on a tagged error with a fallback for unhandled variants.\n   *\n   * The fallback receives variants that are NOT definitely handled. A tag is\n   * considered \"definitely handled\" only if its handler is a function (not\n   * `undefined`). This ensures type safety even with dynamic/conditional handlers:\n   *\n   * ```typescript\n   * const maybeHandle = featureFlag ? (e) => e.id : undefined;\n   * TaggedError.matchPartial(\n   *   error,\n   *   { NotFoundError: maybeHandle },  // maybeHandle might be undefined\n   *   (e) => e._tag  // e correctly includes NotFoundError\n   * );\n   * ```\n   *\n   * @param error - The tagged error to match\n   * @param handlers - Partial object mapping _tag values to handler functions\n   * @param otherwise - Fallback handler for unmatched variants\n   * @returns The return value of the matched handler or fallback\n   *\n   * @example\n   * ```typescript\n   * const message = TaggedError.matchPartial(\n   *   error,\n   *   { NotFoundError: (e) => `Not found: ${e.id}` },\n   *   (e) => `Other error: ${e.message}`\n   * );\n   * ```\n   */\n  export function matchPartial<\n    E extends TaggedErrorBase,\n    H extends Partial<{\n      [K in E[\"_tag\"]]: (e: Extract<E, { _tag: K }>) => unknown;\n    }>,\n    T,\n  >(\n    error: E,\n    handlers: H,\n    otherwise: (e: Exclude<E, { _tag: DefinitelyHandledKeys<H> }>) => T\n  ): HandlersReturnType<H> | T {\n    const tag = error._tag as E[\"_tag\"];\n    const handler = handlers[tag];\n    if (handler) {\n      return handler(\n        error as Extract<E, { _tag: typeof tag }>\n      ) as HandlersReturnType<H>;\n    }\n    return otherwise(error as Exclude<E, { _tag: DefinitelyHandledKeys<H> }>);\n  }\n}\n\nexport { TaggedError };\n\n/**\n * Helper type to extract the _tag literal type from a TaggedError.\n *\n * @example\n * ```typescript\n * class MyError extends TaggedError(\"MyError\")<{ id: string }> {}\n * type Tag = TagOf<MyError>; // \"MyError\"\n * ```\n */\nexport type TagOf<E extends TaggedErrorBase> = E[\"_tag\"];\n\n/**\n * Helper type to extract a specific variant from a TaggedError union by tag.\n *\n * @example\n * ```typescript\n * type AppError = NotFoundError | ValidationError;\n * type NotFound = ErrorByTag<AppError, \"NotFoundError\">; // NotFoundError\n * ```\n */\nexport type ErrorByTag<\n  E extends TaggedErrorBase,\n  Tag extends E[\"_tag\"],\n> = Extract<E, { _tag: Tag }>;\n\n/**\n * Reserved keys that are stripped from user props at runtime.\n * These keys cannot be used as user-defined properties:\n * - _tag: discriminant for pattern matching\n * - name, message, stack: Error internals (preserved for logging/debugging)\n *\n * Note: 'cause' is NOT reserved - it can be used as a user prop.\n */\ntype ReservedErrorKeys = \"_tag\" | \"name\" | \"message\" | \"stack\";\n\n/**\n * Helper type to extract props from a TaggedError.\n * Excludes reserved keys that are stripped at runtime.\n *\n * @example\n * ```typescript\n * class MyError extends TaggedError(\"MyError\")<{ id: string }> {}\n * type Props = PropsOf<MyError>; // { id: string }\n *\n * // 'cause' is allowed as a user prop\n * class DomainError extends TaggedError(\"DomainError\")<{ cause: { field: string } }> {}\n * type DomainProps = PropsOf<DomainError>; // { cause: { field: string } }\n * ```\n */\nexport type PropsOf<E extends TaggedErrorBase> = Omit<E, ReservedErrorKeys>;\n"],"mappings":"AA6DA,IAAMA,EAAN,cAAsC,KAAiC,CAC5D,IACX,EAsGA,SAASC,EACPC,EACAC,EAEK,CACL,OAAO,cAAcH,CAAwB,CACzB,KAAYE,EAG9B,YAAYE,EAAaC,EAAmC,CAE1D,IAAMC,EAAUH,GAAS,QAAUA,EAAQ,QAAQC,GAAS,CAAC,CAAC,EAAIF,EAYlE,GAVA,MAAMI,CAAO,EACb,KAAK,KAAOJ,EAGZ,OAAO,eAAe,KAAM,WAAW,SAAS,EAM5CE,GAAS,OAAOA,GAAU,SAAU,CACtC,GAAM,CACJ,KAAMG,EACN,KAAMC,EACN,QAASC,EACT,MAAOC,EACP,GAAGC,CACL,EAAIP,EAEEQ,EAAe,OAAO,UAAU,eAAe,KACnDD,EACA,OACF,EACME,EAAYD,EACbD,EAAkC,MACnC,OACAC,GACF,OAAQD,EAAkC,MAG5C,IAAMG,EAAkBT,GAAc,QAAU,OAChD,GAAIO,GAAgBE,EAClB,MAAM,IAAI,UACR,mFACF,EAGF,OAAO,OAAO,KAAMH,CAAS,EAEzBC,IACD,KAA6B,MAAQC,GAEpCC,IACD,KAA6B,MAAQT,GAAc,MAExD,MAAWA,GAAc,QAAU,SAChC,KAA6B,MAAQA,EAAa,MAEvD,CACF,CACF,CAGA,OAAO,eAAeJ,EAAa,OAAO,YAAa,CACrD,MAAQc,GAA+BA,aAAoBf,CAC7D,CAAC,GAMSC,GAAV,CAIS,SAASe,EAAQC,EAAgC,CACtD,OAAOA,aAAiB,KAC1B,CAFOhB,EAAS,QAAAe,EAST,SAASE,EAAcD,EAA0C,CACtE,OAAOA,aAAiBjB,CAC1B,CAFOC,EAAS,cAAAiB,EAuBT,SAASC,EAGdC,EAAUC,EAAoC,CAC9C,IAAMnB,EAAMkB,EAAM,KACZE,EAAUD,EAASnB,CAAG,EAC5B,OAAOoB,EACLF,CACF,CACF,CATOnB,EAAS,MAAAkB,EAyCT,SAASI,EAOdH,EACAC,EACAG,EAC2B,CAC3B,IAAMtB,EAAMkB,EAAM,KACZE,EAAUD,EAASnB,CAAG,EAC5B,OAAIoB,EACKA,EACLF,CACF,EAEKI,EAAUJ,CAAuD,CAC1E,CAnBOnB,EAAS,aAAAsB,IA7ERtB,IAAA","names":["InternalTaggedErrorBase","TaggedError","tag","options","props","errorOptions","message","_","_n","_m","_s","safeProps","hasUserCause","userCause","hasOptionsCause","instance","isError","value","isTaggedError","match","error","handlers","handler","matchPartial","otherwise"]}

package/dist/testing.cjs

@@ -0,0 +1,2 @@
+"use strict";var G=Object.defineProperty;var we=Object.getOwnPropertyDescriptor;var Te=Object.getOwnPropertyNames;var de=Object.prototype.hasOwnProperty;var fe=(e,n)=>{for(var i in n)G(e,i,{get:n[i],enumerable:!0})},Re=(e,n,i,E)=>{if(n&&typeof n=="object"||typeof n=="function")for(let c of Te(n))!de.call(e,c)&&c!==i&&G(e,c,{get:()=>n[c],enumerable:!(E=we(n,c))||E.enumerable});return e};var Ce=e=>Re(G({},"__esModule",{value:!0}),e);var Oe={};fe(Oe,{compareSnapshots:()=>ce,createMockFn:()=>ie,createSnapshot:()=>pe,createTestClock:()=>le,createWorkflowHarness:()=>ae,errOutcome:()=>ye,okOutcome:()=>Ee,throwOutcome:()=>me});module.exports=Ce(Oe);var D=e=>({ok:!0,value:e}),b=(e,n)=>({ok:!1,error:e,...n?.cause!==void 0?{cause:n.cause}:{}});var xe=e=>typeof e=="object"&&e!==null&&e.type==="UNEXPECTED_ERROR",W=Symbol.for("step_timeout_marker");function te(e){return typeof e!="object"||e===null?!1:e.type==="STEP_TIMEOUT"?!0:W in e}function Se(e){if(!(typeof e!="object"||e===null)){if(e.type==="STEP_TIMEOUT"){let n=e;return{timeoutMs:n.timeoutMs,stepName:n.stepName,stepKey:n.stepKey,attempt:n.attempt}}if(W in e)return e[W]}}var oe=Symbol("early-exit");function ge(e,n){return{[oe]:!0,error:e,meta:n}}function he(e){return typeof e=="object"&&e!==null&&e[oe]===!0}var se=Symbol("mapper-exception");function ve(e){return{[se]:!0,thrown:e}}function Ae(e){return typeof e=="object"&&e!==null&&e[se]===!0}function be(e){return typeof e=="string"?{name:e}:e??{}}function z(e,n){let{backoff:i,initialDelay:E,maxDelay:c,jitter:v}=n,y;switch(i){case"fixed":y=E;break;case"linear":y=E*e;break;case"exponential":y=E*Math.pow(2,e-1);break}if(y=Math.min(y,c),v){let a=y*.25*Math.random();y=y+a}return Math.floor(y)}function Q(e){return new Promise(n=>setTimeout(n,e))}var ne=Symbol("timeout");async function Pe(e,n,i){let E=new AbortController,c=n.error??{type:"STEP_TIMEOUT",stepName:i.name,stepKey:i.key,timeoutMs:n.ms,attempt:i.attempt},v,y=new Promise((I,S)=>{v=setTimeout(()=>{E.abort(),S({[ne]:!0,error:c})},n.ms)}),a;n.signal?a=Promise.resolve(e(E.signal)):a=Promise.resolve(e());try{return await Promise.race([a,y])}catch(I){if(typeof I=="object"&&I!==null&&I[ne]===!0){let S=I.error;if(typeof S=="object"&&S!==null&&S.type!=="STEP_TIMEOUT"){let F={timeoutMs:n.ms,stepName:i.name,stepKey:i.key,attempt:i.attempt};W in S?S[W]=F:Object.defineProperty(S,W,{value:F,enumerable:!1,writable:!0,configurable:!1})}throw S}throw I}finally{clearTimeout(v)}}var V={backoff:"exponential",initialDelay:100,maxDelay:3e4,jitter:!0,retryOn:()=>!0,onRetry:()=>{}};async function re(e,n){let{onError:i,onEvent:E,catchUnexpected:c,workflowId:v,context:y}=n&&typeof n=="object"?n:{},a=v??crypto.randomUUID(),I=!i&&!c,S=[],F=0,N=p=>p??`step_${++F}`,w=p=>{let u=p.context!==void 0||y===void 0?p:{...p,context:y};if(u.type==="step_success"){let l=u.stepId;for(let m=S.length-1;m>=0;m--){let h=S[m];if(h.type==="race"&&!h.winnerId){h.winnerId=l;break}}}E?.(u,y)},U=ge,X=p=>he(p),$=(p,u)=>I?u?.origin==="result"?{type:"UNEXPECTED_ERROR",cause:{type:"STEP_FAILURE",origin:"result",error:p,...u.resultCause!==void 0?{cause:u.resultCause}:{}}}:u?.origin==="throw"?{type:"UNEXPECTED_ERROR",cause:{type:"STEP_FAILURE",origin:"throw",error:p,thrown:u.thrown}}:{type:"UNEXPECTED_ERROR",cause:{type:"STEP_FAILURE",origin:"result",error:p}}:p,H=p=>({type:"UNEXPECTED_ERROR",cause:p.meta.origin==="result"?{type:"STEP_FAILURE",origin:"result",error:p.error,...p.meta.resultCause!==void 0?{cause:p.meta.resultCause}:{}}:{type:"STEP_FAILURE",origin:"throw",error:p.error,thrown:p.meta.thrown}});try{let u=function(k,o){let r=`scope_${Date.now()}_${Math.random().toString(36).slice(2,8)}`;return(async()=>{let t=performance.now(),s=!1;S.push({scopeId:r,type:"parallel"});let g=()=>{if(s)return;s=!0;let d=S.findIndex(T=>T.scopeId===r);d!==-1&&S.splice(d,1),w({type:"scope_end",workflowId:a,scopeId:r,ts:Date.now(),durationMs:performance.now()-t})};w({type:"scope_start",workflowId:a,scopeId:r,scopeType:"parallel",name:k,ts:Date.now()});try{let d=await o();if(g(),!d.ok)throw i?.(d.error,k,y),U(d.error,{origin:"result",resultCause:d.cause});return d.value}catch(d){throw g(),d}})()},l=function(k,o){let r=Object.keys(k),t=o.name??`Parallel(${r.join(", ")})`,s=`scope_${Date.now()}_${Math.random().toString(36).slice(2,8)}`;return(async()=>{let g=performance.now(),d=!1;S.push({scopeId:s,type:"parallel"});let T=()=>{if(d)return;d=!0;let R=S.findIndex(x=>x.scopeId===s);R!==-1&&S.splice(R,1),w({type:"scope_end",workflowId:a,scopeId:s,ts:Date.now(),durationMs:performance.now()-g})};w({type:"scope_start",workflowId:a,scopeId:s,scopeType:"parallel",name:t,ts:Date.now()});try{let R=await new Promise(O=>{if(r.length===0){O([]);return}let M=!1,A=r.length,L=new Array(r.length);for(let _=0;_<r.length;_++){let j=r[_],Y=_;Promise.resolve(k[j]()).catch(C=>b({type:"PROMISE_REJECTED",cause:C},{cause:{type:"PROMISE_REJECTION",reason:C}})).then(C=>{if(!M){if(!C.ok){M=!0,O([{key:j,result:C}]);return}L[Y]={key:j,result:C},A--,A===0&&O(L)}})}});T();let x={};for(let{key:O,result:M}of R){if(!M.ok)throw i?.(M.error,O,y),U(M.error,{origin:"result",resultCause:M.cause});x[O]=M.value}return x}catch(R){throw T(),R}})()};var Z=u,ee=l;let p=(k,o)=>(async()=>{let r=be(o),{name:t,key:s,retry:g,timeout:d}=r,T=N(s),R=E,x=R?performance.now():0;if(!(typeof k=="function")){if(g&&g.attempts>1)throw new Error("step: retry options require a function operation. Direct Promise/Result values cannot be re-executed on retry. Wrap your operation in a function: step(() => yourOperation, { retry: {...} })");if(d)throw new Error("step: timeout options require a function operation. Direct Promise/Result values cannot be wrapped with timeout after they've started. Wrap your operation in a function: step(() => yourOperation, { timeout: {...} })")}let A={attempts:Math.max(1,g?.attempts??1),backoff:g?.backoff??V.backoff,initialDelay:g?.initialDelay??V.initialDelay,maxDelay:g?.maxDelay??V.maxDelay,jitter:g?.jitter??V.jitter,retryOn:g?.retryOn??V.retryOn,onRetry:g?.onRetry??V.onRetry};E&&w({type:"step_start",workflowId:a,stepId:T,stepKey:s,name:t,ts:Date.now()});let L;for(let C=1;C<=A.attempts;C++){let ke=R?performance.now():0;try{let f;if(typeof k=="function"?d?f=await Pe(k,d,{name:t,key:s,attempt:C}):f=await k():f=await k,f.ok){let K=performance.now()-x;return w({type:"step_success",workflowId:a,stepId:T,stepKey:s,name:t,ts:Date.now(),durationMs:K}),s&&w({type:"step_complete",workflowId:a,stepKey:s,name:t,ts:Date.now(),durationMs:K,result:f}),f.value}if(L=f,C<A.attempts&&A.retryOn(f.error,C)){let K=z(C,A);w({type:"step_retry",workflowId:a,stepId:T,stepKey:s,name:t,ts:Date.now(),attempt:C+1,maxAttempts:A.attempts,delayMs:K,error:f.error}),A.onRetry(f.error,C,K),await Q(K);continue}A.attempts>1&&w({type:"step_retries_exhausted",workflowId:a,stepId:T,stepKey:s,name:t,ts:Date.now(),durationMs:performance.now()-x,attempts:C,lastError:f.error});break}catch(f){let K=performance.now()-ke;if(X(f))throw w({type:"step_aborted",workflowId:a,stepId:T,stepKey:s,name:t,ts:Date.now(),durationMs:K}),f;if(te(f)){let P=Se(f),q=d?.ms??P?.timeoutMs??0;if(w({type:"step_timeout",workflowId:a,stepId:T,stepKey:s,name:t,ts:Date.now(),timeoutMs:q,attempt:C}),C<A.attempts&&A.retryOn(f,C)){let B=z(C,A);w({type:"step_retry",workflowId:a,stepId:T,stepKey:s,name:t,ts:Date.now(),attempt:C+1,maxAttempts:A.attempts,delayMs:B,error:f}),A.onRetry(f,C,B),await Q(B);continue}A.attempts>1&&w({type:"step_retries_exhausted",workflowId:a,stepId:T,stepKey:s,name:t,ts:Date.now(),durationMs:performance.now()-x,attempts:C,lastError:f})}if(C<A.attempts&&A.retryOn(f,C)){let P=z(C,A);w({type:"step_retry",workflowId:a,stepId:T,stepKey:s,name:t,ts:Date.now(),attempt:C+1,maxAttempts:A.attempts,delayMs:P,error:f}),A.onRetry(f,C,P),await Q(P);continue}A.attempts>1&&!te(f)&&w({type:"step_retries_exhausted",workflowId:a,stepId:T,stepKey:s,name:t,ts:Date.now(),durationMs:performance.now()-x,attempts:C,lastError:f});let J=performance.now()-x;if(c){let P;try{P=c(f)}catch(q){throw ve(q)}throw w({type:"step_error",workflowId:a,stepId:T,stepKey:s,name:t,ts:Date.now(),durationMs:J,error:P}),s&&w({type:"step_complete",workflowId:a,stepKey:s,name:t,ts:Date.now(),durationMs:J,result:b(P,{cause:f}),meta:{origin:"throw",thrown:f}}),i?.(P,t,y),U(P,{origin:"throw",thrown:f})}else{let P={type:"UNEXPECTED_ERROR",cause:{type:"UNCAUGHT_EXCEPTION",thrown:f}};throw w({type:"step_error",workflowId:a,stepId:T,stepKey:s,name:t,ts:Date.now(),durationMs:J,error:P}),s&&w({type:"step_complete",workflowId:a,stepKey:s,name:t,ts:Date.now(),durationMs:J,result:b(P,{cause:f}),meta:{origin:"throw",thrown:f}}),f}}}let _=L,j=performance.now()-x,Y=$(_.error,{origin:"result",resultCause:_.cause});throw w({type:"step_error",workflowId:a,stepId:T,stepKey:s,name:t,ts:Date.now(),durationMs:j,error:Y}),s&&w({type:"step_complete",workflowId:a,stepKey:s,name:t,ts:Date.now(),durationMs:j,result:_,meta:{origin:"result",resultCause:_.cause}}),i?.(_.error,t,y),U(_.error,{origin:"result",resultCause:_.cause})})();p.try=(k,o)=>{let r=o.name,t=o.key,s=N(t),g="error"in o?()=>o.error:o.onError,d=E;return(async()=>{let T=d?performance.now():0;E&&w({type:"step_start",workflowId:a,stepId:s,stepKey:t,name:r,ts:Date.now()});try{let R=await k(),x=performance.now()-T;return w({type:"step_success",workflowId:a,stepId:s,stepKey:t,name:r,ts:Date.now(),durationMs:x}),t&&w({type:"step_complete",workflowId:a,stepKey:t,name:r,ts:Date.now(),durationMs:x,result:D(R)}),R}catch(R){let x=g(R),O=performance.now()-T,M=$(x,{origin:"throw",thrown:R});throw w({type:"step_error",workflowId:a,stepId:s,stepKey:t,name:r,ts:Date.now(),durationMs:O,error:M}),t&&w({type:"step_complete",workflowId:a,stepKey:t,name:r,ts:Date.now(),durationMs:O,result:b(x,{cause:R}),meta:{origin:"throw",thrown:R}}),i?.(x,r,y),U(x,{origin:"throw",thrown:R})}})()},p.fromResult=(k,o)=>{let r=o.name,t=o.key,s=N(t),g="error"in o?()=>o.error:o.onError,d=E;return(async()=>{let T=d?performance.now():0;E&&w({type:"step_start",workflowId:a,stepId:s,stepKey:t,name:r,ts:Date.now()});let R=await k();if(R.ok){let x=performance.now()-T;return w({type:"step_success",workflowId:a,stepId:s,stepKey:t,name:r,ts:Date.now(),durationMs:x}),t&&w({type:"step_complete",workflowId:a,stepKey:t,name:r,ts:Date.now(),durationMs:x,result:D(R.value)}),R.value}else{let x=g(R.error),O=performance.now()-T,M=$(x,{origin:"result",resultCause:R.error});throw w({type:"step_error",workflowId:a,stepId:s,stepKey:t,name:r,ts:Date.now(),durationMs:O,error:M}),t&&w({type:"step_complete",workflowId:a,stepKey:t,name:r,ts:Date.now(),durationMs:O,result:b(x,{cause:R.error}),meta:{origin:"result",resultCause:R.error}}),i?.(x,r,y),U(x,{origin:"result",resultCause:R.error})}})()},p.retry=(k,o)=>p(k,{name:o.name,key:o.key,retry:{attempts:o.attempts,backoff:o.backoff,initialDelay:o.initialDelay,maxDelay:o.maxDelay,jitter:o.jitter,retryOn:o.retryOn,onRetry:o.onRetry},timeout:o.timeout}),p.withTimeout=(k,o)=>p(k,{name:o.name,key:o.key,timeout:o}),p.parallel=((...k)=>{if(typeof k[0]=="string"){let o=k[0],r=k[1];return u(o,r)}else{let o=k[0],r=k[1]??{};return l(o,r)}}),p.race=(k,o)=>{let r=`scope_${Date.now()}_${Math.random().toString(36).slice(2,8)}`;return(async()=>{let t=performance.now(),s=!1,g={scopeId:r,type:"race",winnerId:void 0};S.push(g);let d=()=>{if(s)return;s=!0;let T=S.findIndex(R=>R.scopeId===r);T!==-1&&S.splice(T,1),w({type:"scope_end",workflowId:a,scopeId:r,ts:Date.now(),durationMs:performance.now()-t,winnerId:g.winnerId})};w({type:"scope_start",workflowId:a,scopeId:r,scopeType:"race",name:k,ts:Date.now()});try{let T=await o();if(d(),!T.ok)throw i?.(T.error,k,y),U(T.error,{origin:"result",resultCause:T.cause});return T.value}catch(T){throw d(),T}})()},p.allSettled=(k,o)=>{let r=`scope_${Date.now()}_${Math.random().toString(36).slice(2,8)}`;return(async()=>{let t=performance.now(),s=!1;S.push({scopeId:r,type:"allSettled"});let g=()=>{if(s)return;s=!0;let d=S.findIndex(T=>T.scopeId===r);d!==-1&&S.splice(d,1),w({type:"scope_end",workflowId:a,scopeId:r,ts:Date.now(),durationMs:performance.now()-t})};w({type:"scope_start",workflowId:a,scopeId:r,scopeType:"allSettled",name:k,ts:Date.now()});try{let d=await o();if(g(),!d.ok)throw i?.(d.error,k,y),U(d.error,{origin:"result",resultCause:d.cause});return d.value}catch(d){throw g(),d}})()};let h=await e(p);return D(h)}catch(p){if(Ae(p))throw p.thrown;if(X(p)){let l=p.meta.origin==="throw"?p.meta.thrown:p.meta.resultCause;if(c||i)return b(p.error,{cause:l});if(xe(p.error))return b(p.error,{cause:l});let m=H(p);return b(m,{cause:l})}if(c){let l=c(p);return i?.(l,"unexpected",y),b(l,{cause:p})}let u={type:"UNEXPECTED_ERROR",cause:{type:"UNCAUGHT_EXCEPTION",thrown:p}};return i?.(u,"unexpected",y),b(u,{cause:p})}}re.strict=(e,n)=>re(e,n);function ue(e){return typeof e=="object"&&e!==null&&"__earlyExit"in e&&e.__earlyExit===!0}function ae(e,n={}){let{recordInvocations:i=!0,clock:E=Date.now}=n,c=[],v=new Map,y=0,a=[];function I(u){c=[...u],y=0,v.clear()}function S(u,l){v.set(u,l)}function F(u){if(u&&v.has(u))return v.get(u);if(y<c.length)return c[y++]}function N(){let u=async(l,m)=>{let h=typeof m=="string"?{name:m}:m??{},k=h.name??h.key,o=E(),r={name:h.name,key:h.key,order:a.length,timestamp:o};i&&a.push(r);let t=F(k);if(t)switch(r.durationMs=E()-o,t.type){case"ok":return r.result=D(t.value),t.value;case"err":throw r.result=b(t.error),{__earlyExit:!0,error:t.error};case"throw":throw t.error}let s=typeof l=="function"?await l():await l;if(r.durationMs=E()-o,r.result=s,!s.ok)throw{__earlyExit:!0,error:s.error};return s.value};return u.try=async(l,m)=>{let h=m.name??m.key,k=E(),o={name:m.name,key:m.key,order:a.length,timestamp:k};i&&a.push(o);let r=F(h);if(r)switch(o.durationMs=E()-k,r.type){case"ok":return o.result=D(r.value),r.value;case"err":throw o.result=b(r.error),{__earlyExit:!0,error:r.error};case"throw":throw r.error}try{let t=await l();return o.durationMs=E()-k,o.result=D(t),t}catch(t){o.durationMs=E()-k;let s="error"in m?m.error:m.onError(t);throw o.result=b(s),{__earlyExit:!0,error:s}}},u}async function w(u){let l=N();try{let m=await u(l,e);return D(m)}catch(m){return ue(m)?b(m.error):b({type:"UNEXPECTED_ERROR",cause:m})}}async function U(u,l){let m=N();try{let h=await l(m,e,u);return D(h)}catch(h){return ue(h)?b(h.error):b({type:"UNEXPECTED_ERROR",cause:h})}}function X(){return[...a]}function $(u){let l=a.map(h=>h.name??h.key??"unnamed").filter(h=>h!=="unnamed"),m=JSON.stringify(l)===JSON.stringify(u);return{passed:m,message:m?`Steps invoked in order: ${u.join(", ")}`:`Expected steps [${u.join(", ")}] but got [${l.join(", ")}]`,expected:u,actual:l}}function H(u){let l=a.some(m=>m.name===u||m.key===u);return{passed:l,message:l?`Step "${u}" was invoked`:`Step "${u}" was NOT invoked`,expected:u,actual:l}}function Z(u){let l=a.some(m=>m.name===u||m.key===u);return{passed:!l,message:l?`Step "${u}" was invoked but should not have been`:`Step "${u}" was correctly NOT invoked`,expected:"not called",actual:l?"called":"not called"}}function ee(u,l){let m=u.ok===l.ok&&(u.ok?JSON.stringify(u.value)===JSON.stringify(l.value):JSON.stringify(u.error)===JSON.stringify(l.error));return{passed:m,message:m?"Result matches expected":"Result does not match expected",expected:l,actual:u}}function p(){c=[],v.clear(),y=0,a=[]}return{script:I,scriptStep:S,run:w,runWithInput:U,getInvocations:X,assertSteps:$,assertStepCalled:H,assertStepNotCalled:Z,assertResult:ee,reset:p}}function ie(){let e,n=[],i=[],E=((...c)=>{if(i.push(c),n.length>0)return Promise.resolve(n.shift());if(e)return Promise.resolve(e);throw new Error("Mock function called without configured return value")});return E.returns=c=>(e=c,E),E.returnsOnce=c=>(n.push(c),E),E.getCalls=()=>[...i],E.getCallCount=()=>i.length,E.reset=()=>{e=void 0,n.length=0,i.length=0},E}function pe(e,n,i){let E=e.reduce((c,v)=>c+(v.durationMs??0),0);return{invocations:e.map(c=>({...c,timestamp:0})),result:n,events:i?.map(c=>({...c,ts:0})),durationMs:E}}function ce(e,n){let i=[];e.invocations.length!==n.invocations.length&&i.push(`Invocation count: ${e.invocations.length} vs ${n.invocations.length}`);let E=Math.max(e.invocations.length,n.invocations.length);for(let c=0;c<E;c++){let v=e.invocations[c],y=n.invocations[c];if(!v){i.push(`Step ${c}: missing in first snapshot`);continue}if(!y){i.push(`Step ${c}: missing in second snapshot`);continue}v.name!==y.name&&i.push(`Step ${c} name: "${v.name}" vs "${y.name}"`),v.key!==y.key&&i.push(`Step ${c} key: "${v.key}" vs "${y.key}"`),v.result?.ok!==y.result?.ok&&i.push(`Step ${c} result: ${v.result?.ok?"ok":"err"} vs ${y.result?.ok?"ok":"err"}`)}return e.result.ok!==n.result.ok&&i.push(`Final result: ${e.result.ok?"ok":"err"} vs ${n.result.ok?"ok":"err"}`),{equal:i.length===0,differences:i}}function le(e=0){let n=e;return{now:()=>n,advance:i=>{n+=i},set:i=>{n=i},reset:()=>{n=e}}}function Ee(e){return{type:"ok",value:e}}function ye(e){return{type:"err",error:e}}function me(e){return{type:"throw",error:e}}0&&(module.exports={compareSnapshots,createMockFn,createSnapshot,createTestClock,createWorkflowHarness,errOutcome,okOutcome,throwOutcome});
+//# sourceMappingURL=testing.cjs.map