docs(examples)!: give the order-processing domain real error classes

The example used `expected: Error` at every `qualifyFailure` site, which
matches essentially every throw — the pre-v8 catch-all spelled differently.
It was accurate (the domain only threw plain `Error`s) but it neutralized the
feature the flagship example is meant to teach, and a reader landing on one of
the bare sites had nothing to go on.

Adds `domain/errors.ts` with one class per port under a shared
`OrderProcessingError` base, and throws those from the use cases and the
payment adapter. Each activity now names the failure it actually anticipates
(`expected: ShippingError`, `expected: PaymentError`, ...), so the triage is
visible: a provider fault is a modeled activity failure, a `TypeError` from a
bug stays a defect and re-throws at the edge with its original stack.

Author: btravers

examples/order-processing-worker/src/application/activities.ts

@@ -11,6 +11,13 @@ import {
   createShipmentUseCase,
   refundPaymentUseCase,
 } from "../dependencies.js";
+import {
+  InventoryError,
+  NotificationError,
+  OrderRepositoryError,
+  PaymentError,
+  ShippingError,
+} from "../domain/errors.js";
 
 /**
  * Activity implementations using unthrown's `AsyncResult` pattern.
@@ -53,18 +60,25 @@ export const activities = declareActivitiesHandler({
       fromPromise(
         sendNotificationUseCase.execute(customerId, subject, message),
         qualifyFailure("NOTIFICATION_FAILED", {
-          // Anticipated failure shape: the domain layer signals technical
-          // faults by throwing plain `Error`s. Anything else (a TypeError
-          // from a bug, ...) stays a defect and re-throws at the edge.
-          expected: Error,
+          // `expected` names the failures this activity *anticipates*. The
+          // notification port signals its faults with `NotificationError`, so
+          // only those become the modeled `NOTIFICATION_FAILED` failure.
+          // Anything else — a `TypeError` from a bug, a null deref — is not a
+          // business failure: it rides unthrown's defect channel and re-throws
+          // at the activity edge with its original stack. Use
+          // `expected: "any"` if you deliberately want the old catch-all.
+          expected: NotificationError,
           message: "Failed to send notification",
         }),
       ),
 
     purgeExpiredOrders: ({ olderThanDays }) =>
       fromPromise(
         purgeExpiredOrdersUseCase.execute(olderThanDays),
-        qualifyFailure("ORDER_PURGE_FAILED", { expected: Error, message: "Order purge failed" }),
+        qualifyFailure("ORDER_PURGE_FAILED", {
+          expected: OrderRepositoryError,
+          message: "Order purge failed",
+        }),
       ).map((purgedCount) => ({ purgedCount })),
 
     processOrder: {
@@ -79,7 +93,7 @@ export const activities = declareActivitiesHandler({
         fromPromise(
           processPaymentUseCase.execute(customerId, amount),
           qualifyFailure("PAYMENT_GATEWAY_ERROR", {
-            expected: Error,
+            expected: PaymentError,
             message: "Payment gateway call failed",
           }),
         ).flatMap((outcome) => {
@@ -93,7 +107,7 @@ export const activities = declareActivitiesHandler({
         fromPromise(
           reserveInventoryUseCase.execute(items),
           qualifyFailure("INVENTORY_RESERVATION_FAILED", {
-            expected: Error,
+            expected: InventoryError,
             message: "Inventory reservation failed",
           }),
         ),
@@ -102,7 +116,7 @@ export const activities = declareActivitiesHandler({
         fromPromise(
           releaseInventoryUseCase.execute(reservationId),
           qualifyFailure("INVENTORY_RELEASE_FAILED", {
-            expected: Error,
+            expected: InventoryError,
             message: "Inventory release failed",
           }),
         ),
@@ -111,15 +125,15 @@ export const activities = declareActivitiesHandler({
         fromPromise(
           createShipmentUseCase.execute(orderId, customerId),
           qualifyFailure("SHIPMENT_CREATION_FAILED", {
-            expected: Error,
+            expected: ShippingError,
             message: "Shipment creation failed",
           }),
         ),
 
       refundPayment: (transactionId) =>
         fromPromise(
           refundPaymentUseCase.execute(transactionId),
-          qualifyFailure("REFUND_FAILED", { expected: Error, message: "Refund failed" }),
+          qualifyFailure("REFUND_FAILED", { expected: PaymentError, message: "Refund failed" }),
         ),
     },
   },

examples/order-processing-worker/src/domain/errors.ts

@@ -0,0 +1,44 @@
+/**
+ * Technical failure shapes for the order-processing domain.
+ *
+ * These exist so each activity boundary can *triage* rather than blanket-wrap.
+ * `qualifyFailure(type, { expected })` names the failures an activity
+ * anticipates: a matching cause becomes the modeled `ApplicationFailure`, and
+ * anything else — a `TypeError` from a bug, a null deref — rides unthrown's
+ * **defect** channel and re-throws at the activity edge with its original
+ * stack, instead of being mislabelled as a business failure.
+ *
+ * Naming one class per port is what makes that triage meaningful. A blanket
+ * `expected: Error` would match essentially every throw, which is the
+ * pre-v8 catch-all behavior spelled differently — if you genuinely want it,
+ * write `expected: "any"` so the intent is explicit and greppable.
+ *
+ * Distinct from the contract's **declared** `errors` (`PaymentDeclined`):
+ * those model expected *business* outcomes, are returned as
+ * `Err(errors.PaymentDeclined(...))` rather than thrown, and cross the wire
+ * as typed `ContractError`s. The classes here are plain technical faults.
+ */
+
+/** Base class for every technical fault raised by this example's domain. */
+export class OrderProcessingError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    // Keep `Error.name` the concrete subclass name for readable logs.
+    this.name = new.target.name;
+  }
+}
+
+/** The notification provider could not accept the message. */
+export class NotificationError extends OrderProcessingError {}
+
+/** The payment gateway could not process the charge or refund. */
+export class PaymentError extends OrderProcessingError {}
+
+/** The inventory service could not reserve or release stock. */
+export class InventoryError extends OrderProcessingError {}
+
+/** The shipping provider could not create the shipment. */
+export class ShippingError extends OrderProcessingError {}
+
+/** The order store could not complete the requested operation. */
+export class OrderRepositoryError extends OrderProcessingError {}

examples/order-processing-worker/src/domain/usecases/create-shipment.usecase.ts

@@ -1,4 +1,5 @@
 import type { ShippingResult } from "../entities/order.schema.js";
+import { ShippingError } from "../errors.js";
 import type { ShippingPort } from "../ports/shipping.port.js";
 
 /**
@@ -13,12 +14,12 @@ export class CreateShipmentUseCase {
     // Business validation
     if (!orderId || orderId.trim() === "") {
       // oxlint-disable-next-line unthrown/no-throw -- known-technical precondition throw in a plain (non-Result) domain helper, wrapped once at the activity boundary via fromPromise(..., qualifyFailure(...))
-      throw new Error("Order ID is required");
+      throw new ShippingError("Order ID is required");
     }
 
     if (!customerId || customerId.trim() === "") {
       // oxlint-disable-next-line unthrown/no-throw -- known-technical precondition throw in a plain (non-Result) domain helper, wrapped once at the activity boundary via fromPromise(..., qualifyFailure(...))
-      throw new Error("Customer ID is required");
+      throw new ShippingError("Customer ID is required");
     }
 
     // Delegate to shipping port

examples/order-processing-worker/src/domain/usecases/process-payment.usecase.ts

@@ -1,4 +1,5 @@
 import type { PaymentOutcome } from "../entities/order.schema.js";
+import { PaymentError } from "../errors.js";
 import type { PaymentPort } from "../ports/payment.port.js";
 
 /**
@@ -13,12 +14,12 @@ export class ProcessPaymentUseCase {
     // Business validation
     if (amount <= 0) {
       // oxlint-disable-next-line unthrown/no-throw -- known-technical precondition throw in a plain (non-Result) domain helper, wrapped once at the activity boundary via fromPromise(..., qualifyFailure(...))
-      throw new Error("Payment amount must be positive");
+      throw new PaymentError("Payment amount must be positive");
     }
 
     if (!customerId || customerId.trim() === "") {
       // oxlint-disable-next-line unthrown/no-throw -- known-technical precondition throw in a plain (non-Result) domain helper, wrapped once at the activity boundary via fromPromise(..., qualifyFailure(...))
-      throw new Error("Customer ID is required");
+      throw new PaymentError("Customer ID is required");
     }
 
     // Delegate to payment port

examples/order-processing-worker/src/domain/usecases/purge-expired-orders.usecase.ts

@@ -1,3 +1,4 @@
+import { OrderRepositoryError } from "../errors.js";
 import type { OrderRepositoryPort } from "../ports/order-repository.port.js";
 
 /**
@@ -12,7 +13,7 @@ export class PurgeExpiredOrdersUseCase {
     // Business validation
     if (!Number.isInteger(olderThanDays) || olderThanDays <= 0) {
       // oxlint-disable-next-line unthrown/no-throw -- known-technical precondition throw in a plain (non-Result) domain helper, wrapped once at the activity boundary via fromPromise(..., qualifyFailure(...))
-      throw new Error("olderThanDays must be a positive integer");
+      throw new OrderRepositoryError("olderThanDays must be a positive integer");
     }
 
     // Delegate to order repository port

examples/order-processing-worker/src/domain/usecases/refund-payment.usecase.ts

@@ -1,3 +1,4 @@
+import { PaymentError } from "../errors.js";
 import type { PaymentPort } from "../ports/payment.port.js";
 
 /**
@@ -12,7 +13,7 @@ export class RefundPaymentUseCase {
     // Business validation
     if (!transactionId || transactionId.trim() === "") {
       // oxlint-disable-next-line unthrown/no-throw -- known-technical precondition throw in a plain (non-Result) domain helper, wrapped once at the activity boundary via fromPromise(..., qualifyFailure(...))
-      throw new Error("Transaction ID is required");
+      throw new PaymentError("Transaction ID is required");
     }
 
     // Delegate to payment port

examples/order-processing-worker/src/domain/usecases/release-inventory.usecase.ts

@@ -1,3 +1,4 @@
+import { InventoryError } from "../errors.js";
 import type { InventoryPort } from "../ports/inventory.port.js";
 
 /**
@@ -12,7 +13,7 @@ export class ReleaseInventoryUseCase {
     // Business validation
     if (!reservationId || reservationId.trim() === "") {
       // oxlint-disable-next-line unthrown/no-throw -- known-technical precondition throw in a plain (non-Result) domain helper, wrapped once at the activity boundary via fromPromise(..., qualifyFailure(...))
-      throw new Error("Reservation ID is required");
+      throw new InventoryError("Reservation ID is required");
     }
 
     // Delegate to inventory port

examples/order-processing-worker/src/domain/usecases/reserve-inventory.usecase.ts

@@ -1,4 +1,5 @@
 import type { InventoryReservation, OrderItem } from "../entities/order.schema.js";
+import { InventoryError } from "../errors.js";
 import type { InventoryPort } from "../ports/inventory.port.js";
 
 /**
@@ -13,13 +14,13 @@ export class ReserveInventoryUseCase {
     // Business validation
     if (!items || items.length === 0) {
       // oxlint-disable-next-line unthrown/no-throw -- known-technical precondition throw in a plain (non-Result) domain helper, wrapped once at the activity boundary via fromPromise(..., qualifyFailure(...))
-      throw new Error("At least one item is required");
+      throw new InventoryError("At least one item is required");
     }
 
     for (const item of items) {
       if (item.quantity <= 0) {
         // oxlint-disable-next-line unthrown/no-throw -- known-technical precondition throw in a plain (non-Result) domain helper, wrapped once at the activity boundary via fromPromise(..., qualifyFailure(...))
-        throw new Error(`Invalid quantity for product ${item.productId}`);
+        throw new InventoryError(`Invalid quantity for product ${item.productId}`);
       }
     }
 

examples/order-processing-worker/src/domain/usecases/send-notification.usecase.ts

@@ -1,3 +1,4 @@
+import { NotificationError } from "../errors.js";
 import type { NotificationPort } from "../ports/notification.port.js";
 
 /**
@@ -12,17 +13,17 @@ export class SendNotificationUseCase {
     // Business validation
     if (!customerId || customerId.trim() === "") {
       // oxlint-disable-next-line unthrown/no-throw -- known-technical precondition throw in a plain (non-Result) domain helper, wrapped once at the activity boundary via fromPromise(..., qualifyFailure(...))
-      throw new Error("Customer ID is required");
+      throw new NotificationError("Customer ID is required");
     }
 
     if (!subject || subject.trim() === "") {
       // oxlint-disable-next-line unthrown/no-throw -- known-technical precondition throw in a plain (non-Result) domain helper, wrapped once at the activity boundary via fromPromise(..., qualifyFailure(...))
-      throw new Error("Subject is required");
+      throw new NotificationError("Subject is required");
     }
 
     if (!message || message.trim() === "") {
       // oxlint-disable-next-line unthrown/no-throw -- known-technical precondition throw in a plain (non-Result) domain helper, wrapped once at the activity boundary via fromPromise(..., qualifyFailure(...))
-      throw new Error("Message is required");
+      throw new NotificationError("Message is required");
     }
 
     // Delegate to notification port

examples/order-processing-worker/src/infrastructure/adapters/payment.adapter.ts

@@ -1,4 +1,5 @@
 import type { PaymentOutcome } from "../../domain/entities/order.schema.js";
+import { PaymentError } from "../../domain/errors.js";
 import type { PaymentPort } from "../../domain/ports/payment.port.js";
 import { logger } from "../../logger.js";
 
@@ -57,7 +58,7 @@ export class MockPaymentAdapter implements PaymentPort {
     } else {
       logger.error(`❌ Refund failed`);
       // oxlint-disable-next-line unthrown/no-throw -- known-technical precondition throw in a plain (non-Result) domain helper, wrapped once at the activity boundary via fromPromise(..., qualifyFailure(...))
-      throw new Error("Payment processor rejected refund request");
+      throw new PaymentError("Payment processor rejected refund request");
     }
   }
 }