JSPM

@workkit/errors

1.0.3
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 31
  • Score
    100M100P100Q93558F
  • License MIT

Structured error types with retry classification for Cloudflare Workers

Package Exports

  • @workkit/errors

Readme

@workkit/errors

Structured, retryable error classes for Cloudflare Workers

npm bundle size

Install

bun add @workkit/errors

Usage

Before (raw errors)

// Unstructured, no retry info, no HTTP mapping
if (!env.MY_KV) throw new Error("KV not bound")

try {
  await doSomething()
} catch (e) {
  // Is this retryable? What status code? Who knows.
  return new Response("error", { status: 500 })
}

After (workkit errors)

import {
  NotFoundError,
  RateLimitError,
  ValidationError,
  errorToResponse,
  isRetryable,
} from "@workkit/errors"

// Typed errors with HTTP status codes and retry strategies
throw new NotFoundError("User not found") // 404, not retryable
throw new RateLimitError("Too many requests") // 429, retryable with backoff
throw new ValidationError("Invalid email", [
  { path: ["email"], message: "Must be a valid email" },
])

// Convert any WorkkitError to a proper HTTP Response
app.onError((err) => errorToResponse(err)) // { error: "...", code: "NOT_FOUND" }

// Check retryability and get delay
if (isRetryable(err)) {
  const delay = getRetryDelay(err, attempt) // respects error's retry strategy
}

API

Error Classes

Class Code Status Retryable
NotFoundError NOT_FOUND 404 No
ValidationError VALIDATION_ERROR 400 No
ConflictError CONFLICT 409 No
UnauthorizedError UNAUTHORIZED 401 No
ForbiddenError FORBIDDEN 403 No
TimeoutError TIMEOUT 504 Yes
RateLimitError RATE_LIMITED 429 Yes
ServiceUnavailableError SERVICE_UNAVAILABLE 503 Yes
BindingNotFoundError BINDING_NOT_FOUND 500 No
InternalError INTERNAL_ERROR 500 No
ConfigError CONFIG_ERROR 500 No

Utilities

  • errorToResponse(err) — Convert a WorkkitError to a JSON Response
  • fromHttpStatus(status, message) — Create a WorkkitError from an HTTP status code
  • isRetryable(err) — Check if an error should be retried
  • getRetryDelay(err, attempt) — Calculate retry delay with backoff
  • serializeError(err) — Serialize to JSON-safe object
  • wrapError(err) — Wrap unknown errors as InternalError
  • isWorkkitError(err) / isErrorCode(err, code) — Type guards

License

MIT