Skip to content

chore(deps): bump unthrown to 5.0.0-beta.5 #338

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
btravers merged 5 commits into from
Jul 27, 2026
Merged

chore(deps): bump unthrown to 5.0.0-beta.5 #338

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
7c707d8
chore(deps): bump unthrown to 5.0.0-beta.5
btravers Jul 27, 2026
d62fc4f
chore(deps): declare ts-pattern as a peerDependency
btravers Jul 27, 2026
ee223f8
refactor: enumerate every error case, remove P._ catch-all
btravers Jul 27, 2026
14932e9
refactor!: route TechnicalError and RuntimeClientError to the defect …
btravers Jul 27, 2026
e6ad37b
docs(client): fix the interceptor retry example to match the defect m…
btravers Jul 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions .changeset/bump-unthrown-beta-5.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
---
"@temporal-contract/contract": patch
"@temporal-contract/client": patch
"@temporal-contract/worker": patch
---

Bump `unthrown` to `5.0.0-beta.5`. This tracks two beta breaking changes:
`match`'s error handler key is renamed `err` → `errCases`, and the bare error
combinators gained the `*Cases` suffix (`flatMapErr` → `flatMapErrCases`,
`tapErr` → `tapErrCases`). `unthrown` also now declares `ts-pattern` as a peer
dependency, so `ts-pattern` (`^5`) is added alongside it. The peer range is
raised to `^5.0.0-beta.5`.
2 changes: 1 addition & 1 deletion docs/examples/basic-order-processing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ This example demonstrates the unthrown-based pattern:
- Activities return `AsyncResult<T, ApplicationFailure>` instead of throwing
- Child workflow calls return `Result<T, E>` for explicit error handling
- Errors are part of the type signature
- Enables railway-oriented programming via `.flatMap` / `.map` / `.mapErr`
- Enables railway-oriented programming via `.flatMap` / `.map` / `.mapErrCases`

### Worker Application

Expand Down
12 changes: 9 additions & 3 deletions docs/guide/activity-handlers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -341,9 +341,15 @@ import {
} from "@temporal-contract/worker/activity";

const logging: ActivityMiddleware = ({ activityName, workflowName }, next) =>
next().tapErr((error) => {
logger.warn({ activityName, workflowName, error }, "activity failed");
});
next().tapErrCases((matcher) =>
matcher.with(
P.instanceOf(ApplicationFailure),
tag("@temporal-contract/ContractError"),
(error) => {
logger.warn({ activityName, workflowName, error }, "activity failed");
},
),
);

const timing: ActivityMiddleware = async ({ activityName }, next) => {
const started = Date.now();
Expand Down
159 changes: 133 additions & 26 deletions docs/guide/client-usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,9 +63,19 @@ result.match({
ok: (output) => {
console.log("Order processed:", output.status); // TypeScript knows the shape!
},
err: (error) => {
console.error("Workflow failed:", error);
},
errCases: (matcher) =>
matcher.with(
tag("@temporal-contract/ContractError"),
tag("@temporal-contract/WorkflowNotFoundError"),
tag("@temporal-contract/WorkflowValidationError"),
tag("@temporal-contract/WorkflowAlreadyStartedError"),
tag("@temporal-contract/WorkflowFailedError"),
tag("@temporal-contract/WorkflowExecutionNotFoundError"),
tag("@temporal-contract/RuntimeClientError"),
Comment thread
btravers marked this conversation as resolved.
Outdated
(error) => {
console.error("Workflow failed:", error);
},
),
defect: (cause) => {
console.error("Unexpected failure:", cause);
},
Expand Down Expand Up @@ -94,13 +104,28 @@ handleResult.match({
const result = await handle.result();
result.match({
ok: (output) => console.log("Completed:", output),
err: (error) => console.error("Failed:", error),
errCases: (matcher) =>
matcher.with(
tag("@temporal-contract/ContractError"),
tag("@temporal-contract/WorkflowValidationError"),
tag("@temporal-contract/WorkflowFailedError"),
tag("@temporal-contract/WorkflowExecutionNotFoundError"),
tag("@temporal-contract/RuntimeClientError"),
(error) => console.error("Failed:", error),
),
defect: (cause) => console.error("Unexpected failure:", cause),
});
},
err: (error) => {
console.error("Failed to start workflow:", error);
},
errCases: (matcher) =>
matcher.with(
tag("@temporal-contract/WorkflowNotFoundError"),
tag("@temporal-contract/WorkflowValidationError"),
tag("@temporal-contract/WorkflowAlreadyStartedError"),
tag("@temporal-contract/RuntimeClientError"),
(error) => {
console.error("Failed to start workflow:", error);
},
),
defect: (cause) => {
console.error("Unexpected failure:", cause);
},
Expand Down Expand Up @@ -142,7 +167,7 @@ await client.executeWorkflow("invalidWorkflow", {
The client uses `unthrown` for explicit error handling:

```typescript
import { Result } from "unthrown";
import { Result, tag } from "unthrown";

const result = await client.executeWorkflow("processOrder", {
workflowId: "order-123",
Expand All @@ -154,9 +179,19 @@ result.match({
ok: (value) => {
console.log("Order processed:", value.transactionId);
},
err: (error) => {
console.error("Order failed:", error);
},
errCases: (matcher) =>
matcher.with(
tag("@temporal-contract/ContractError"),
tag("@temporal-contract/WorkflowNotFoundError"),
tag("@temporal-contract/WorkflowValidationError"),
tag("@temporal-contract/WorkflowAlreadyStartedError"),
tag("@temporal-contract/WorkflowFailedError"),
tag("@temporal-contract/WorkflowExecutionNotFoundError"),
tag("@temporal-contract/RuntimeClientError"),
(error) => {
console.error("Order failed:", error);
},
),
defect: (cause) => {
console.error("Unexpected failure:", cause);
},
Expand Down Expand Up @@ -200,27 +235,52 @@ handleResult.match({
const statusResult = await handle.queries.getStatus({});
statusResult.match({
ok: (status) => console.log("Status:", status),
err: (error) => console.error("Query failed:", error),
errCases: (matcher) =>
matcher.with(
tag("@temporal-contract/QueryValidationError"),
tag("@temporal-contract/WorkflowExecutionNotFoundError"),
tag("@temporal-contract/RuntimeClientError"),
(error) => console.error("Query failed:", error),
),
defect: (cause) => console.error("Unexpected failure:", cause),
});

// Signal the workflow
const signalResult = await handle.signals.cancelOrder({ reason: "Customer request" });
signalResult.match({
ok: () => console.log("Signal sent"),
err: (error) => console.error("Signal failed:", error),
errCases: (matcher) =>
matcher.with(
tag("@temporal-contract/SignalValidationError"),
tag("@temporal-contract/WorkflowExecutionNotFoundError"),
tag("@temporal-contract/RuntimeClientError"),
(error) => console.error("Signal failed:", error),
),
defect: (cause) => console.error("Unexpected failure:", cause),
});

// Get the result
const result = await handle.result();
result.match({
ok: (output) => console.log("Result:", output),
err: (error) => console.error("Workflow failed:", error),
errCases: (matcher) =>
matcher.with(
tag("@temporal-contract/ContractError"),
tag("@temporal-contract/WorkflowValidationError"),
tag("@temporal-contract/WorkflowFailedError"),
tag("@temporal-contract/WorkflowExecutionNotFoundError"),
tag("@temporal-contract/RuntimeClientError"),
(error) => console.error("Workflow failed:", error),
),
defect: (cause) => console.error("Unexpected failure:", cause),
});
},
err: (error) => console.error("Failed to get handle:", error),
errCases: (matcher) =>
matcher.with(
tag("@temporal-contract/WorkflowNotFoundError"),
tag("@temporal-contract/RuntimeClientError"),
(error) => console.error("Failed to get handle:", error),
),
defect: (cause) => console.error("Unexpected failure:", cause),
});
```
Expand Down Expand Up @@ -253,7 +313,17 @@ const result = await client.executeWorkflow("processOrder", {

result.match({
ok: (value) => console.log("Success:", value),
err: (error) => console.error("Workflow returned error:", error),
errCases: (matcher) =>
matcher.with(
tag("@temporal-contract/ContractError"),
tag("@temporal-contract/WorkflowNotFoundError"),
tag("@temporal-contract/WorkflowValidationError"),
tag("@temporal-contract/WorkflowAlreadyStartedError"),
tag("@temporal-contract/WorkflowFailedError"),
tag("@temporal-contract/WorkflowExecutionNotFoundError"),
tag("@temporal-contract/RuntimeClientError"),
(error) => console.error("Workflow returned error:", error),
),
defect: (cause) => console.error("Unexpected failure:", cause),
});
```
Expand Down Expand Up @@ -320,14 +390,41 @@ import type { ClientInterceptor } from "@temporal-contract/client";

// Observe every operation
const logging: ClientInterceptor = (args, next) =>
next().tapErr((error) => {
logger.warn({ operation: args.operation, workflowId: args.workflowId, error });
});
next().tapErrCases((matcher) =>
matcher.with(
tag("@temporal-contract/WorkflowNotFoundError"),
tag("@temporal-contract/WorkflowValidationError"),
tag("@temporal-contract/WorkflowAlreadyStartedError"),
tag("@temporal-contract/WorkflowFailedError"),
tag("@temporal-contract/WorkflowExecutionNotFoundError"),
tag("@temporal-contract/SignalValidationError"),
tag("@temporal-contract/QueryValidationError"),
tag("@temporal-contract/UpdateValidationError"),
tag("@temporal-contract/RuntimeClientError"),
tag("@temporal-contract/ContractError"),
(error) => {
logger.warn({ operation: args.operation, workflowId: args.workflowId, error });
},
),
);

// Retry a transient failure once
const retryOnce: ClientInterceptor = (args, next) =>
next().flatMapErr((error): ReturnType<typeof next> =>
error instanceof RuntimeClientError ? next() : Err(error).toAsync(),
next().flatMapErrCases((matcher) =>
matcher.with(
tag("@temporal-contract/WorkflowNotFoundError"),
tag("@temporal-contract/WorkflowValidationError"),
tag("@temporal-contract/WorkflowAlreadyStartedError"),
tag("@temporal-contract/WorkflowFailedError"),
tag("@temporal-contract/WorkflowExecutionNotFoundError"),
tag("@temporal-contract/SignalValidationError"),
tag("@temporal-contract/QueryValidationError"),
tag("@temporal-contract/UpdateValidationError"),
tag("@temporal-contract/RuntimeClientError"),
tag("@temporal-contract/ContractError"),
(error): ReturnType<typeof next> =>
error instanceof RuntimeClientError ? next() : Err(error).toAsync(),
),
);

const client = await TypedClient.create({
Expand Down Expand Up @@ -496,11 +593,21 @@ result.match({
// Handle success
updateDatabase(value);
},
err: (error) => {
// Handle error
logError(error);
notifySupport(error);
},
errCases: (matcher) =>
matcher.with(
tag("@temporal-contract/ContractError"),
tag("@temporal-contract/WorkflowNotFoundError"),
tag("@temporal-contract/WorkflowValidationError"),
tag("@temporal-contract/WorkflowAlreadyStartedError"),
tag("@temporal-contract/WorkflowFailedError"),
tag("@temporal-contract/WorkflowExecutionNotFoundError"),
tag("@temporal-contract/RuntimeClientError"),
(error) => {
// Handle error
logError(error);
notifySupport(error);
},
),
defect: (cause) => {
// Handle unexpected failure (bug)
logError(cause);
Expand Down
14 changes: 12 additions & 2 deletions docs/guide/core-concepts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -137,10 +137,20 @@ const result = await client.executeWorkflow("processOrder", {
args: { orderId: "ORD-123", amount: 100 },
});

// result is a Result — use .match({ ok, err, defect }) or isOk(result) to unwrap
// result is a Result — use .match({ ok, errCases, defect }) or isOk(result) to unwrap
result.match({
ok: (output) => console.log(output.transactionId),
err: (error) => console.error("Workflow failed:", error),
errCases: (matcher) =>
matcher.with(
tag("@temporal-contract/ContractError"),
tag("@temporal-contract/WorkflowNotFoundError"),
tag("@temporal-contract/WorkflowValidationError"),
tag("@temporal-contract/WorkflowAlreadyStartedError"),
tag("@temporal-contract/WorkflowFailedError"),
tag("@temporal-contract/WorkflowExecutionNotFoundError"),
tag("@temporal-contract/RuntimeClientError"),
(error) => console.error("Workflow failed:", error),
),
defect: (cause) => console.error("Unexpected failure:", cause),
});
```
Expand Down
19 changes: 17 additions & 2 deletions docs/guide/entry-points.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -233,11 +233,26 @@ handleResult.match({
const result = await handle.result();
result.match({
ok: (output) => console.log(output.success), // ✅ TypeScript knows the shape
err: (error) => console.error("Workflow failed:", error),
errCases: (matcher) =>
matcher.with(
tag("@temporal-contract/ContractError"),
tag("@temporal-contract/WorkflowValidationError"),
tag("@temporal-contract/WorkflowFailedError"),
tag("@temporal-contract/WorkflowExecutionNotFoundError"),
tag("@temporal-contract/RuntimeClientError"),
(error) => console.error("Workflow failed:", error),
),
defect: (cause) => console.error("Unexpected failure:", cause),
});
},
err: (error) => console.error("Failed to start workflow:", error),
errCases: (matcher) =>
matcher.with(
tag("@temporal-contract/WorkflowNotFoundError"),
tag("@temporal-contract/WorkflowValidationError"),
tag("@temporal-contract/WorkflowAlreadyStartedError"),
tag("@temporal-contract/RuntimeClientError"),
(error) => console.error("Failed to start workflow:", error),
),
defect: (cause) => console.error("Unexpected failure:", cause),
});
```
Expand Down
16 changes: 13 additions & 3 deletions docs/guide/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -232,9 +232,19 @@ result.match({
ok: (output) => {
console.log(output.status); // 'success' | 'failed' — fully typed!
},
err: (error) => {
console.error("Workflow failed:", error);
},
errCases: (matcher) =>
matcher.with(
tag("@temporal-contract/ContractError"),
tag("@temporal-contract/WorkflowNotFoundError"),
tag("@temporal-contract/WorkflowValidationError"),
tag("@temporal-contract/WorkflowAlreadyStartedError"),
tag("@temporal-contract/WorkflowFailedError"),
tag("@temporal-contract/WorkflowExecutionNotFoundError"),
tag("@temporal-contract/RuntimeClientError"),
(error) => {
console.error("Workflow failed:", error);
},
),
defect: (cause) => {
console.error("Unexpected failure:", cause);
},
Expand Down
Loading
Loading