[monarcode]

Summary

Release candidate 0.1.0-rc.2. It adds two features: typed errors chosen by response status (statusErrors), and an onExit plugin hook with a built-in consoleLogger plugin.

statusErrors: typed errors by status

Error responses can now be decoded into your own error types, chosen by status, instead of arriving as a generic HttpError.

const api = yield* Fetch.make({
  baseUrl: "https://api.example.com",
  statusErrors: { 401: SessionExpired, 429: RateLimited },
});

const assign = api.endpoint("POST /todos/:id/assignees", {
  input: Body,
  output: Todo,
  statusErrors: { 404: TodoNotFound, 400: [UnknownUser, AlreadyAssigned] },
});

• Where a map can go: on the client (make), an endpoint, or a single call. For a given status, the call's schemas are tried first, then the endpoint's, then the client's.
• How matching works: each schema tries to decode the body, and the first one that decodes wins. A list such as [UnknownUser, AlreadyAssigned] is tried in order, so literal fields like code can tell apart responses that share a status. A body that no schema decodes falls through to HttpError, defaultError and plugins as before.
• _tag handling: backends don't send a _tag, so effetch adds the schema's literal _tag to the body before decoding. Plain Schema.TaggedError classes work as they are. Schema.encodeKeys handles field renames.
• Types: the matched errors are added to the call's error channel, so catchTag and catchTags work on them.
  • Maps are copied and frozen where they're given.
  • A client or endpoint with a map can't be assigned to the type without one.
  • The per-call map is NoInfer, so generic wrappers still infer correctly.
• New exports:
  • Types: StatusErrorMap, StatusError, StatusErrorSchema, StatusErrorServices.
  • Properties: client.statusErrors, Endpoint.statusErrors.
• Known limitation: maps typed as interfaces aren't supported yet. This is documented.

Plugin onExit hook and consoleLogger

• onExit(exit, ctx): a new plugin hook that runs once per call with the call's Exit, the response (when there is one) and the duration. Its services are tracked by a new RExit type parameter on Plugin.Definition.
• consoleLogger: a new plugin in @monarcode/effetch/plugins that prints each call as a console group with headers, bodies and errors. It supports:
  • redaction of headers, query and bodies
  • colors
  • filters
  • per-call options

Docs and examples

• README: new "Status errors" and "Console logging" sections.
• CHANGELOG: rc.2 entry.
• Examples: new examples/status-errors.ts. examples/builtins.ts and examples/app/* are updated.
• Smoke and editor checks: updated for the new exports.

Testing

• pnpm run check passes. It covers lint, format, typecheck, the docs check (65 exports), 496 tests including type tests, build, publint, attw, and the tarball smoke and editor checks.
• New tests: test/statusErrors.test.ts, test/types/statusErrors.test-d.ts, and the consoleLogger tests.