wellcrafted 0.42.0 → 0.44.0

package/README.md

@@ -9,84 +9,141 @@
 
 Tagged errors and Result types as plain objects. < 2KB, zero dependencies.
 
-Most Result libraries hand you a container and leave the error type as an exercise. You get `Ok` and `Err` but nothing to help you define, compose, or serialize the errors themselves. So you end up with string literals, ad-hoc objects, or class hierarchies that break the moment you call `JSON.stringify`.
+`try/catch` throws away your error's type the moment you catch it. You get `catch (error: unknown)` and you're guessing again. And a thrown `Error` travels badly: `JSON.stringify(new Error("boom"))` is `{}`, so the message vanishes the moment it hits a log line, a Web Worker, or an IPC boundary, where `instanceof` stops working too.
 
-wellcrafted takes the opposite approach: start with the errors. `defineErrors` gives you typed, serializable, composable error variants inspired by Rust's [thiserror](https://docs.rs/thiserror). The Result type is just `{ data, error }` destructuring — the same shape you already know from Supabase, SvelteKit load functions, and TanStack Query. No `.isOk()` method chains, no `.map().andThen().orElse()` pipelines. Check `error`, use `data`. That's it.
+wellcrafted fixes both. Define your errors once as plain data, return them instead of throwing, and check them with the `{ data, error }` shape you already know from Supabase, SvelteKit load functions, and TanStack Query. No `.isOk()` method chains, no `.map().andThen().orElse()` pipelines. Check `error`, use `data`.
 
 ```typescript
-import { defineErrors, extractErrorMessage, type InferErrors } from "wellcrafted/error";
-import { tryAsync, Ok, type Result } from "wellcrafted/result";
+import { defineErrors } from "wellcrafted/error";
+import { trySync } from "wellcrafted/result";
+
+// The key becomes error.name. The fields you return are typed on the error.
+const { ParseError } = defineErrors({
+  ParseError: ({ path }: { path: string }) => ({
+    message: `Could not parse ${path}`,
+    path,
+  }),
+});
 
-// Define domain errors — all variants in one call
-const UserError = defineErrors({
-  AlreadyExists: ({ email }: { email: string }) => ({
-    message: `User ${email} already exists`,
-    email,
+const { data, error } = trySync({
+  try: () => JSON.parse(raw),
+  catch: () => ParseError({ path: "config.json" }),
+});
+
+if (error) {
+  // error is { name: "ParseError"; message: string; path: string }
+  console.error(error.message, error.path);
+} else {
+  // data is the parsed value, error is null
+  use(data);
+}
+```
+
+That's the whole idea: define an error, wrap the throwing call, destructure the result, check `error`. A *tagged error* is just an object with a `name` field you can `switch` on. Everything below is that pattern at scale.
+
+## Install
+
+```bash
+npm install wellcrafted
+```
+
+## A real service
+
+Here is the pattern in shipping code, lightly trimmed from [Whispering](https://github.com/EpicenterHQ/epicenter)'s transcription layer. Each service owns a small vocabulary of things that can go wrong, declared up front with `defineErrors`.
+
+```typescript
+import {
+  defineErrors,
+  extractErrorMessage,
+  type InferErrors,
+} from "wellcrafted/error";
+import { type Result, tryAsync } from "wellcrafted/result";
+
+export const ElevenLabsError = defineErrors({
+  MissingApiKey: () => ({ message: "ElevenLabs API key is required" }),
+  FileTooLarge: ({ sizeMb, maxMb }: { sizeMb: number; maxMb: number }) => ({
+    message: `File ${sizeMb.toFixed(1)}MB exceeds ${maxMb}MB limit`,
+    sizeMb,
+    maxMb,
   }),
-  CreateFailed: ({ email, cause }: { email: string; cause: unknown }) => ({
-    message: `Failed to create user ${email}: ${extractErrorMessage(cause)}`,
-    email,
+  Unexpected: ({ cause }: { cause: unknown }) => ({
+    message: extractErrorMessage(cause),
     cause,
   }),
 });
-type UserError = InferErrors<typeof UserError>;
-//   ^? { name: "AlreadyExists"; message: string; email: string }
-//    | { name: "CreateFailed"; message: string; email: string; cause: unknown }
+export type ElevenLabsError = InferErrors<typeof ElevenLabsError>;
 
-// Each factory returns Err<...> directly — no wrapping needed
-async function createUser(email: string): Promise<Result<User, UserError>> {
-  const existing = await db.findByEmail(email);
-  if (existing) return UserError.AlreadyExists({ email });
+async function transcribe(
+  audio: Blob,
+  apiKey: string,
+): Promise<Result<string, ElevenLabsError>> {
+  if (!apiKey) return ElevenLabsError.MissingApiKey(); // a factory already is an Err
+
+  const sizeMb = audio.size / (1024 * 1024);
+  if (sizeMb > 1000) return ElevenLabsError.FileTooLarge({ sizeMb, maxMb: 1000 });
 
   return tryAsync({
-    try: () => db.users.create({ email }),
-    catch: (error) => UserError.CreateFailed({ email, cause: error }),
+    try: () => callElevenLabs(apiKey, audio), // may throw
+    catch: (cause) => ElevenLabsError.Unexpected({ cause }),
   });
 }
+```
 
-// Discriminate with switch — TypeScript narrows automatically
-const { data, error } = await createUser("alice@example.com");
+The caller checks `error`, then `switch`es on `error.name` to handle each case with the right fields in scope:
+
+```typescript
+const { data, error } = await transcribe(audio, apiKey);
 if (error) {
   switch (error.name) {
-    case "AlreadyExists": console.log(error.email);   break;
-    case "CreateFailed":  console.log(error.email);   break;
-    //                           ^ TypeScript knows exactly which fields exist
+    case "MissingApiKey": return promptForKey();
+    case "FileTooLarge":  return warn(`Audio too large: ${error.sizeMb}MB`);
+    case "Unexpected":    return report(error.cause);
   }
 }
+showTranscript(data); // data is string, error is null
 ```
 
-## Install
+Three things are doing the work here, and the rest of this README is just those three things.
 
-```bash
-npm install wellcrafted
-```
+## Define your errors
 
-## Why define errors at all?
+You can put any value in `Ok` and `Err`. So why `defineErrors`?
 
-You can use `Ok` and `Err` with any value. So why bother with `defineErrors`?
+Because errors aren't random. A function fails in a handful of known ways, and a namespace is where you enumerate them up front: the closed set of what can go wrong. A user service fails with `AlreadyExists`, `CreateFailed`, or `InvalidEmail`, and nothing else. That set is exactly a Rust error enum: the namespace is the enum, each key is a variant, and `switch (error.name)` is the `match`. `defineErrors` brings the [thiserror](https://docs.rs/thiserror) pattern to TypeScript as plain objects instead of classes.
 
-Because in practice, errors aren't random. Every service has a handful of things that can go wrong, and you want to enumerate them upfront. A user service has `AlreadyExists`, `CreateFailed`, `InvalidEmail`. An HTTP client has `Connection`, `Timeout`, `Response`. These are logical groups — the error vocabulary for a domain. Rust codified this with [thiserror](https://docs.rs/thiserror). `defineErrors` brings the same pattern to TypeScript, but outputs plain objects instead of classes.
+Enumerating the set up front is what makes the rest pay off. The union flows into your `Result<T, E>` signature, so a caller sees every way the call can fail right in the type, and a `switch` with a [`never` guard](#exhaustiveness) turns a forgotten variant into a compile error.
 
-**Errors are data, not classes.** Plain frozen objects with no prototype chain. `JSON.stringify` just works — no `stack` property eating up your logs, no `instanceof` checks that break across package boundaries. This matters anywhere errors cross a serialization boundary: Web Workers, server actions, sync engines, IPC. The error you create is the error that arrives.
+Each key becomes a variant. Your constructor returns `{ message, ...fields }`; `defineErrors` stamps the key on as `name` and hands back a factory that returns `Err<...>` directly. `InferErrors` extracts the union of every variant for your `Result<T, E>` signatures.
 
-**Every factory returns `Err<...>` directly.** No wrapping step. Return it from a `tryAsync` catch handler or as a standalone early return — `if (existing) return UserError.AlreadyExists({ email })`. The Result type flows naturally.
+```typescript
+const UserError = defineErrors({
+  AlreadyExists: ({ email }: { email: string }) => ({
+    message: `User ${email} already exists`,
+    email,
+  }),
+  CreateFailed: ({ email, cause }: { email: string; cause: unknown }) => ({
+    message: `Failed to create user ${email}: ${extractErrorMessage(cause)}`,
+    email,
+    cause,
+  }),
+});
+type UserError = InferErrors<typeof UserError>;
+//   ^? { name: "AlreadyExists"; message: string; email: string }
+//    | { name: "CreateFailed";  message: string; email: string; cause: unknown }
+```
 
-**Discriminated unions for free.** `switch (error.name)` gives you full TypeScript narrowing. No `instanceof`, no type predicates, no manual union types. Add a new variant and every consumer that switches gets a compile error until they handle it.
+Two properties make this pay off:
 
-## Wrapping unsafe code
+**Errors are data, not classes.** Plain frozen objects, no prototype chain. The fields you put on them are plain own properties, so they survive `JSON.stringify`, a Web Worker, or an IPC hop with no `stack` noise and no `instanceof` that breaks across package boundaries. The error you create is the error that arrives.
 
-`trySync` and `tryAsync` turn throwing operations into `Result` types. The `catch` handler receives the raw error and returns an `Err<...>` from your `defineErrors` factories.
+**Every factory returns `Err<...>` directly.** No wrapping step. Return it from a `tryAsync` catch handler or as a standalone early return (`if (existing) return UserError.AlreadyExists({ email })`). The `Result` type flows out naturally.
 
-```typescript
-import { trySync, tryAsync } from "wellcrafted/result";
+## Wrap throwing code
 
-const JsonError = defineErrors({
-  ParseFailed: ({ input, cause }: { input: string; cause: unknown }) => ({
-    message: `Invalid JSON: ${extractErrorMessage(cause)}`,
-    input: input.slice(0, 100),
-    cause,
-  }),
-});
+`trySync` and `tryAsync` turn a throwing operation into a `Result`. The `catch` handler receives the raw error and returns one of your `defineErrors` variants. Anything you don't wrap keeps throwing exactly as before, so you can adopt this one function at a time.
+
+```typescript
+import { trySync, tryAsync, Ok } from "wellcrafted/result";
 
 // Synchronous
 const { data, error } = trySync({
@@ -101,135 +158,88 @@ const { data, error } = await tryAsync({
 });
 ```
 
-When `catch` returns `Ok(fallback)` instead of `Err`, the return type narrows to `Ok<T>` — no error checking needed:
+When `catch` returns `Ok(fallback)` instead of an error, there is no error branch left: the return type narrows to `Ok<T>`, so `error` is always `null` and you can skip the check.
 
 ```typescript
-const { data: parsed } = trySync({
-  try: (): unknown => JSON.parse(riskyJson),
-  catch: () => Ok([]),
+const { data: items } = trySync({
+  try: (): string[] => JSON.parse(riskyJson),
+  catch: () => Ok([] as string[]), // recovered; there is no error to check
 });
-// parsed is always defined — the catch recovered
 ```
 
-## Composing errors across layers
+## Compose across layers
 
-This is where the pattern pays off. Each layer defines its own error vocabulary; inner errors become `cause` fields, and `extractErrorMessage` formats them inside the factory so call sites stay clean.
+Each layer defines its own vocabulary and folds the layer below into a `cause` field. `extractErrorMessage` formats that cause inside the factory, so call sites stay clean. You propagate with a plain `if (error) return` (there is no `?` operator; see [what you give up](#what-you-give-up)).
 
 ```typescript
-// Service layer: domain errors wrap raw failures via cause
-const UserServiceError = defineErrors({
-  NotFound: ({ userId }: { userId: string }) => ({
-    message: `User ${userId} not found`,
-    userId,
-  }),
-  FetchFailed: ({ userId, cause }: { userId: string; cause: unknown }) => ({
-    message: `Failed to fetch user ${userId}: ${extractErrorMessage(cause)}`,
-    userId,
-    cause,
-  }),
-});
-type UserServiceError = InferErrors<typeof UserServiceError>;
-
 async function getUser(userId: string): Promise<Result<User, UserServiceError>> {
-  const response = await tryAsync({
+  const { data: response, error } = await tryAsync({
     try: () => fetch(`/api/users/${userId}`),
     catch: (cause) => UserServiceError.FetchFailed({ userId, cause }),
-    //                 raw fetch error becomes cause ^^^^^
-  });
-  if (response.error) return response;
-
-  if (response.data.status === 404) return UserServiceError.NotFound({ userId });
-
-  return tryAsync({
-    try: () => response.data.json() as Promise<User>,
-    catch: (cause) => UserServiceError.FetchFailed({ userId, cause }),
+    //                  raw fetch error becomes cause ^^^^^
   });
-}
+  if (error) return Err(error); // propagate as-is
 
-// API handler: maps domain errors to HTTP responses
-async function handleGetUser(request: Request, userId: string) {
-  const { data, error } = await getUser(userId);
-
-  if (error) {
-    switch (error.name) {
-      case "NotFound":
-        return Response.json({ error: error.message }, { status: 404 });
-      case "FetchFailed":
-        return Response.json({ error: error.message }, { status: 502 });
-    }
-  }
-
-  return Response.json(data);
+  if (response.status === 404) return UserServiceError.NotFound({ userId });
+  return Ok(await response.json());
 }
 ```
 
-The full error chain is JSON-serializable at every level. Log it, send it over the wire, display it in a toast. The structure survives.
+Your tagged fields are plain data, so the chain logs and crosses the wire cleanly. The raw `cause` is the exception: it serializes only as well as whatever you caught, which is why the factories above fold it through `extractErrorMessage` into the `message` string.
 
 ## The Result type
 
-The foundation is a simple discriminated union:
+The foundation is one discriminated union:
 
 ```typescript
-import { Ok, Err, trySync, tryAsync, type Result } from "wellcrafted/result";
-
-type Ok<T>      = { data: T; error: null };
-type Err<E>     = { error: E; data: null };
+type Ok<T>        = { data: T; error: null };
+type Err<E>       = { error: E; data: null };
 type Result<T, E> = Ok<T> | Err<E>;
 ```
 
-Check `error` first, and TypeScript narrows `data` automatically:
+Check `error` first and TypeScript narrows `data` for you:
 
 ```typescript
 const { data, error } = await someOperation();
-if (error) {
-  // error is E, data is null
-  return;
-}
+if (error) return; // error is E, data is null
 // data is T, error is null
 ```
 
-## Also in the box
+`if (error)` works because errors from `defineErrors` are always objects, and an object is truthy. The exact check is `error !== null` (or the `isErr` guard); reach for it if you ever put a falsy value like `0` or `""` in an `Err`.
 
-### Brand Types
+### Exhaustiveness
 
-Create distinct types from primitives so TypeScript catches mix-ups at compile time. Zero runtime footprint — purely a type utility.
+`switch (error.name)` narrows each case, and your editor autocompletes every variant. To make a *new* variant a compile error until it is handled, add a `never` check in `default`:
 
 ```typescript
-import type { Brand } from "wellcrafted/brand";
-
-type UserId = string & Brand<"UserId">;
-type OrderId = string & Brand<"OrderId">;
-
-function getUser(id: UserId) { /* ... */ }
-
-const userId = "abc" as UserId;
-const orderId = "xyz" as OrderId;
-getUser(userId);   // compiles
-getUser(orderId);  // type error
+switch (error.name) {
+  case "NotFound":    return notFound();
+  case "FetchFailed": return badGateway();
+  default:
+    error satisfies never; // add a variant and this line fails to compile
+}
 ```
 
-### Query Integration
+Plain TypeScript does not enforce exhaustive `switch` on its own; this one line is how you opt in.
 
-TanStack Query factories with `.options` for reactive components and explicit imperative helpers for event handlers.
+## What you give up
 
-```typescript
-import { createQueryFactories } from "wellcrafted/query";
+wellcrafted is not an effect system, and the honest cost is control flow. There is no `?` operator, so you propagate with an explicit `if (error) return` at each step. There is no dependency injection, no automatic short-circuiting, and no built-in concurrency. If you need those, reach for [Effect](https://effect.website); that is what it is for.
 
-const { defineQuery, defineMutation } = createQueryFactories(queryClient);
+In exchange, the whole API is `{ data, error }`, `async/await`, and `switch`: no new runtime, no generators, no pipe operators to learn.
 
-const userQuery = defineQuery({
-  queryKey: ["users", userId],
-  queryFn: () => getUser(userId), // returns Result<User, UserError>
-});
+## Also in the box
 
-// Reactive: pass to useQuery (React) or createQuery (Svelte)
-const query = createQuery(() => userQuery.options);
+Each lives behind its own subpath import, so you pay for only what you use.
 
-// Imperative: choose the query read policy explicitly
-const { data, error } = await userQuery.fetch();
-```
+- `wellcrafted/brand`: `Brand<T>` makes distinct types from primitives (`type UserId = string & Brand<"UserId">`) so the compiler catches mix-ups. Zero runtime.
+- `wellcrafted/logger`: a small DI-based structured logger keyed on log level, built to take your `defineErrors` types directly. No global singleton.
+- `wellcrafted/testing`: `expectOk` / `expectErr` unwrap a `Result` in a test, or throw with a readable message.
+- `wellcrafted/json`: `parseJson` is `JSON.parse` that returns a `Result` instead of throwing.
+- `wellcrafted/query`: TanStack Query adapters for Result-returning functions. Queries expose `.options`, `.fetch`, and `.ensure`; mutations are callable and expose `.options`.
+- `wellcrafted/standard-schema`: wrap a `Result` as a [Standard Schema](https://github.com/standard-schema/standard-schema) for validators that speak the spec.
 
-## Comparison
+## How it compares
 
 |  | wellcrafted | neverthrow | better-result | fp-ts | Effect |
 |---|---|---|---|---|---|
@@ -239,89 +249,33 @@ const { data, error } = await userQuery.fetch();
 | Bundle size | < 2KB | ~5KB | ~2KB | ~30KB | ~50KB |
 | Syntax | async/await | Method chains | Method chains + generators | Pipe operators | Generators |
 
-Every Result library gives you a container. wellcrafted gives you what goes inside it — then gets out of the way.
-
-## Philosophy
-
-wellcrafted is deliberately idiomatic to JavaScript. The `{ data, error }` shape isn't novel — it's the same pattern used by Supabase, SvelteKit load functions, and TanStack Query. We chose it because it's already familiar, already destructurable, and requires zero new mental models.
-
-The same principle applies throughout: async/await instead of generators, `switch` instead of `.match()`, plain objects instead of class hierarchies. The best abstractions are the ones your team already knows. wellcrafted adds type-safe error definition on top of patterns that JavaScript developers use every day — it doesn't ask you to learn a new programming paradigm to handle errors.
-
-## API Reference
-
-### Error functions
-
-- **`defineErrors(config)`** — define multiple error factories in a single call. Each key becomes a variant; the value is a factory returning `{ message, ...fields }`. Every factory returns `Err<...>` directly.
-- **`extractErrorMessage(error)`** — extract a readable string from any `unknown` error value.
-
-### Error types
-
-- **`InferErrors<T>`** — extract union of all error types from a `defineErrors` return value.
-- **`InferError<T>`** — extract a single variant's error type from one factory.
-
-### Result functions
+Every Result library hands you a container. wellcrafted hands you what goes inside it, then gets out of the way.
 
-- **`Ok(data)`** — create a success result
-- **`Err(error)`** — create a failure result
-- **`trySync({ try, catch })`** — wrap a synchronous throwing operation
-- **`tryAsync({ try, catch })`** — wrap an async throwing operation
-- **`isOk(result)` / `isErr(result)`** — type guards
-- **`unwrap(result)`** — extract data or throw error
-- **`resolve(value)`** — handle values that may or may not be Results
-- **`partitionResults(results)`** — split an array of Results into separate ok/err arrays
+## API at a glance
 
-### Query functions
+From `wellcrafted/result`:
 
-- **`createQueryFactories(client)`** — create query/mutation factories for TanStack Query
-- **`defineQuery(options)`**: define a query with `.options`, `.fetch()`, and `.ensure()`
-- **`defineMutation(options)`**: define a callable mutation with `.options` for hooks
+- `Ok(data)` / `Err(error)`: construct a success or failure
+- `trySync` / `tryAsync`: wrap a throwing operation, sync or async
+- `Result<T, E>`: the `Ok<T> | Err<E>` union
 
-### Standard Schema
+From `wellcrafted/error`:
 
-- **`ResultSchema(dataSchema, errorSchema)`** — [Standard Schema](https://github.com/standard-schema/standard-schema) wrapper for Result types, interoperable with any validator that supports the spec.
+- `defineErrors(config)`: define a namespace of error variant factories
+- `extractErrorMessage(value)`: pull a readable string out of any `unknown`
+- `InferErrors<typeof MyError>`: the union of all variants; `InferError<typeof MyError.Variant>`: one variant
 
-### Other types
+Less common but there when you need them: `isOk` / `isErr` type guards, `unwrap` (extract or throw), `partitionResults` (split an array of Results), and `resolve` (handle values that may or may not be Results).
 
-- **`Result<T, E>`** — union of `Ok<T> | Err<E>`
-- **`Brand<T, B>`** — branded type wrapper for distinct primitives
+## Teach your AI agent
 
-## AI Agent Skills
-
-If you use an AI coding agent (Claude Code, Cursor, etc.), teach it how to use wellcrafted correctly:
+If you use an AI coding agent, install the skills that teach it the patterns and anti-patterns directly:
 
 ```bash
 npx skills add wellcrafted-dev/wellcrafted
 ```
 
-This installs 5 skills that teach your agent the patterns, anti-patterns, and API conventions:
-
-| Skill | What it teaches |
-| --- | --- |
-| `define-errors` | `defineErrors` variants, `extractErrorMessage`, `InferErrors`/`InferError` type extraction |
-| `result-types` | `Ok`, `Err`, `trySync`/`tryAsync`, the `{ data, error }` destructuring pattern |
-| `query-factories` | `createQueryFactories`, `defineQuery`/`defineMutation`, reactive options, and imperative helpers |
-| `branded-types` | `Brand<T>`, brand constructor pattern, when to add runtime validation |
-| `patterns` | Architectural style guide: control flow, factory composition, service layers, error composition |
-
-Skills work with any agent that supports [`npx skills`](https://www.npmjs.com/package/skills). Install once, update with `npx skills update`.
-
-
-## Development Setup
-
-### AI Agent Skills
-
-AI agent skills are managed via [`npx skills`](https://www.npmjs.com/package/skills), sourced from [Epicenter](https://github.com/EpicenterHQ/epicenter). Only skills relevant to wellcrafted's domain are installed.
-
-```bash
-# Install skills (already committed, but can be refreshed)
-npx skills add EpicenterHQ/epicenter --skill error-handling --skill define-errors -a claude-code -y
-
-# Update all installed skills
-npx skills update
-
-# List installed skills
-npx skills list
-```
+This installs five skills: `define-errors`, `result-types`, `query-factories`, `branded-types`, and `patterns` (the architectural style guide). They work with any agent that supports [`npx skills`](https://www.npmjs.com/package/skills). Install once, update with `npx skills update`.
 
 ## License
 

package/dist/error/index.d.ts

@@ -1,4 +1,4 @@
-import "../result-DKwq9BCr.js";
-import { AnyTaggedError, DefineErrorsReturn, ErrorBody, ErrorsConfig, InferError, InferErrors, ValidatedConfig } from "../types-tXXk7K9Q.js";
-import { defineErrors, extractErrorMessage } from "../index-B9PnZCTt.js";
+import "../result-_socO0Ud.js";
+import { AnyTaggedError, DefineErrorsReturn, ErrorBody, ErrorsConfig, InferError, InferErrors, ValidatedConfig } from "../types-ojNaDB4n.js";
+import { defineErrors, extractErrorMessage } from "../index-ByVX3bXz.js";
 export { AnyTaggedError, DefineErrorsReturn, ErrorBody, ErrorsConfig, InferError, InferErrors, ValidatedConfig, defineErrors, extractErrorMessage };

package/dist/error/index.js

@@ -1,4 +1,4 @@
-import "../result-C5cJ1_WU.js";
-import { defineErrors, extractErrorMessage } from "../error-Dy9wXt5_.js";
+import "../result-C_ph_izC.js";
+import { defineErrors, extractErrorMessage } from "../error-BkeqDeUq.js";
 
 export { defineErrors, extractErrorMessage };

package/dist/{error-Dy9wXt5_.js → error-BkeqDeUq.js}

@@ -1,4 +1,4 @@
-import { Err } from "./result-C5cJ1_WU.js";
+import { Err } from "./result-C_ph_izC.js";
 
 //#region src/error/defineErrors.ts
 /**
@@ -104,4 +104,4 @@ function extractErrorMessage(error) {
 
 //#endregion
 export { defineErrors, extractErrorMessage };
-//# sourceMappingURL=error-Dy9wXt5_.js.map
+//# sourceMappingURL=error-BkeqDeUq.js.map

package/dist/{error-Dy9wXt5_.js.map → error-BkeqDeUq.js.map}

@@ -1 +1 @@
-{"version":3,"file":"error-Dy9wXt5_.js","names":["config: TConfig & ValidatedConfig<TConfig>","result: Record<string, unknown>","error: unknown"],"sources":["../src/error/defineErrors.ts","../src/error/extractErrorMessage.ts"],"sourcesContent":["import { Err } from \"../result/result.js\";\nimport type {\n\tDefineErrorsReturn,\n\tErrorsConfig,\n\tValidatedConfig,\n} from \"./types.js\";\n\n/**\n * Defines a set of typed error factories using Rust-style namespaced variants.\n *\n * Each key is a short variant name (the namespace provides context). Every\n * factory returns `Err<...>` directly — ready for `trySync`/`tryAsync` catch\n * handlers. The variant name is stamped as `name` on the error object.\n *\n * @example\n * ```ts\n * const HttpError = defineErrors({\n *   Connection: ({ cause }: { cause: unknown }) => ({\n *     message: `Failed to connect: ${extractErrorMessage(cause)}`,\n *     cause,\n *   }),\n *   Response: ({ status }: { status: number; bodyMessage?: string }) => ({\n *     message: `HTTP ${status}`,\n *     status,\n *   }),\n *   Parse: ({ cause }: { cause: unknown }) => ({\n *     message: `Failed to parse response body: ${extractErrorMessage(cause)}`,\n *     cause,\n *   }),\n * });\n *\n * type HttpError = InferErrors<typeof HttpError>;\n *\n * const result = HttpError.Connection({ cause: 'timeout' }); // Err<...>\n * ```\n *\n * Inspired by Rust's {@link https://docs.rs/thiserror | thiserror} crate. The\n * mapping is nearly 1:1:\n *\n * - `enum HttpError` → `const HttpError = defineErrors(...)`\n * - Variant `Connection { cause: String }` → key `Connection: ({ cause }: { cause: unknown }) => (...)`\n * - `#[error(\"Failed: {cause}\")]` → `` message: `Failed: ${extractErrorMessage(cause)}` ``\n * - `HttpError::Connection { ... }` → `HttpError.Connection({ ... })`\n * - `match error { Connection { .. } => }` → `switch (error.name) { case 'Connection': }`\n *\n * The equivalent Rust `thiserror` enum:\n * ```rust\n * #[derive(Error, Debug)]\n * enum HttpError {\n *     #[error(\"Failed to connect: {cause}\")]\n *     Connection { cause: String },\n *\n *     #[error(\"HTTP {status}\")]\n *     Response { status: u16, body_message: Option<String> },\n *\n *     #[error(\"Failed to parse response body: {cause}\")]\n *     Parse { cause: String },\n * }\n * ```\n */\nexport function defineErrors<const TConfig extends ErrorsConfig>(\n\tconfig: TConfig & ValidatedConfig<TConfig>,\n): DefineErrorsReturn<TConfig> {\n\tconst result: Record<string, unknown> = {};\n\n\tfor (const [name, ctor] of Object.entries(config)) {\n\t\tresult[name] = (...args: unknown[]) => {\n\t\t\tconst body = (ctor as (...a: unknown[]) => Record<string, unknown>)(\n\t\t\t\t...args,\n\t\t\t);\n\t\t\treturn Err(Object.freeze({ ...body, name }));\n\t\t};\n\t}\n\n\treturn result as DefineErrorsReturn<TConfig>;\n}\n","/**\n * Extracts a readable error message from an unknown error value\n *\n * @param error - The unknown error to extract a message from\n * @returns A string representation of the error\n */\nexport function extractErrorMessage(error: unknown): string {\n\t// Handle Error instances\n\tif (error instanceof Error) {\n\t\treturn error.message;\n\t}\n\n\t// Handle primitives\n\tif (typeof error === \"string\") return error;\n\tif (\n\t\ttypeof error === \"number\" ||\n\t\ttypeof error === \"boolean\" ||\n\t\ttypeof error === \"bigint\"\n\t)\n\t\treturn String(error);\n\tif (typeof error === \"symbol\") return error.toString();\n\tif (error === null) return \"null\";\n\tif (error === undefined) return \"undefined\";\n\n\t// Handle arrays\n\tif (Array.isArray(error)) return JSON.stringify(error);\n\n\t// Handle plain objects\n\tif (typeof error === \"object\") {\n\t\tconst errorObj = error as Record<string, unknown>;\n\n\t\t// Check common error properties\n\t\tconst messageProps = [\n\t\t\t\"message\",\n\t\t\t\"error\",\n\t\t\t\"description\",\n\t\t\t\"title\",\n\t\t\t\"reason\",\n\t\t\t\"details\",\n\t\t] as const;\n\t\tfor (const prop of messageProps) {\n\t\t\tif (prop in errorObj && typeof errorObj[prop] === \"string\") {\n\t\t\t\treturn errorObj[prop];\n\t\t\t}\n\t\t}\n\n\t\t// Fallback to JSON stringification\n\t\ttry {\n\t\t\treturn JSON.stringify(error);\n\t\t} catch {\n\t\t\treturn String(error);\n\t\t}\n\t}\n\n\t// Final fallback\n\treturn String(error);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4DA,SAAgB,aACfA,QAC8B;CAC9B,MAAMC,SAAkC,CAAE;AAE1C,MAAK,MAAM,CAAC,MAAM,KAAK,IAAI,OAAO,QAAQ,OAAO,CAChD,QAAO,QAAQ,CAAC,GAAG,SAAoB;EACtC,MAAM,OAAO,AAAC,KACb,GAAG,KACH;AACD,SAAO,IAAI,OAAO,OAAO;GAAE,GAAG;GAAM;EAAM,EAAC,CAAC;CAC5C;AAGF,QAAO;AACP;;;;;;;;;;ACrED,SAAgB,oBAAoBC,OAAwB;AAE3D,KAAI,iBAAiB,MACpB,QAAO,MAAM;AAId,YAAW,UAAU,SAAU,QAAO;AACtC,YACQ,UAAU,mBACV,UAAU,oBACV,UAAU,SAEjB,QAAO,OAAO,MAAM;AACrB,YAAW,UAAU,SAAU,QAAO,MAAM,UAAU;AACtD,KAAI,UAAU,KAAM,QAAO;AAC3B,KAAI,iBAAqB,QAAO;AAGhC,KAAI,MAAM,QAAQ,MAAM,CAAE,QAAO,KAAK,UAAU,MAAM;AAGtD,YAAW,UAAU,UAAU;EAC9B,MAAM,WAAW;EAGjB,MAAM,eAAe;GACpB;GACA;GACA;GACA;GACA;GACA;EACA;AACD,OAAK,MAAM,QAAQ,aAClB,KAAI,QAAQ,mBAAmB,SAAS,UAAU,SACjD,QAAO,SAAS;AAKlB,MAAI;AACH,UAAO,KAAK,UAAU,MAAM;EAC5B,QAAO;AACP,UAAO,OAAO,MAAM;EACpB;CACD;AAGD,QAAO,OAAO,MAAM;AACpB"}
+{"version":3,"file":"error-BkeqDeUq.js","names":["config: TConfig & ValidatedConfig<TConfig>","result: Record<string, unknown>","error: unknown"],"sources":["../src/error/defineErrors.ts","../src/error/extractErrorMessage.ts"],"sourcesContent":["import { Err } from \"../result/result.js\";\nimport type {\n\tDefineErrorsReturn,\n\tErrorsConfig,\n\tValidatedConfig,\n} from \"./types.js\";\n\n/**\n * Defines a set of typed error factories using Rust-style namespaced variants.\n *\n * Each key is a short variant name (the namespace provides context). Every\n * factory returns `Err<...>` directly — ready for `trySync`/`tryAsync` catch\n * handlers. The variant name is stamped as `name` on the error object.\n *\n * @example\n * ```ts\n * const HttpError = defineErrors({\n *   Connection: ({ cause }: { cause: unknown }) => ({\n *     message: `Failed to connect: ${extractErrorMessage(cause)}`,\n *     cause,\n *   }),\n *   Response: ({ status }: { status: number; bodyMessage?: string }) => ({\n *     message: `HTTP ${status}`,\n *     status,\n *   }),\n *   Parse: ({ cause }: { cause: unknown }) => ({\n *     message: `Failed to parse response body: ${extractErrorMessage(cause)}`,\n *     cause,\n *   }),\n * });\n *\n * type HttpError = InferErrors<typeof HttpError>;\n *\n * const result = HttpError.Connection({ cause: 'timeout' }); // Err<...>\n * ```\n *\n * Inspired by Rust's {@link https://docs.rs/thiserror | thiserror} crate. The\n * mapping is nearly 1:1:\n *\n * - `enum HttpError` → `const HttpError = defineErrors(...)`\n * - Variant `Connection { cause: String }` → key `Connection: ({ cause }: { cause: unknown }) => (...)`\n * - `#[error(\"Failed: {cause}\")]` → `` message: `Failed: ${extractErrorMessage(cause)}` ``\n * - `HttpError::Connection { ... }` → `HttpError.Connection({ ... })`\n * - `match error { Connection { .. } => }` → `switch (error.name) { case 'Connection': }`\n *\n * The equivalent Rust `thiserror` enum:\n * ```rust\n * #[derive(Error, Debug)]\n * enum HttpError {\n *     #[error(\"Failed to connect: {cause}\")]\n *     Connection { cause: String },\n *\n *     #[error(\"HTTP {status}\")]\n *     Response { status: u16, body_message: Option<String> },\n *\n *     #[error(\"Failed to parse response body: {cause}\")]\n *     Parse { cause: String },\n * }\n * ```\n */\nexport function defineErrors<const TConfig extends ErrorsConfig>(\n\tconfig: TConfig & ValidatedConfig<TConfig>,\n): DefineErrorsReturn<TConfig> {\n\tconst result: Record<string, unknown> = {};\n\n\tfor (const [name, ctor] of Object.entries(config)) {\n\t\tresult[name] = (...args: unknown[]) => {\n\t\t\tconst body = (ctor as (...a: unknown[]) => Record<string, unknown>)(\n\t\t\t\t...args,\n\t\t\t);\n\t\t\treturn Err(Object.freeze({ ...body, name }));\n\t\t};\n\t}\n\n\treturn result as DefineErrorsReturn<TConfig>;\n}\n","/**\n * Extracts a readable error message from an unknown error value\n *\n * @param error - The unknown error to extract a message from\n * @returns A string representation of the error\n */\nexport function extractErrorMessage(error: unknown): string {\n\t// Handle Error instances\n\tif (error instanceof Error) {\n\t\treturn error.message;\n\t}\n\n\t// Handle primitives\n\tif (typeof error === \"string\") return error;\n\tif (\n\t\ttypeof error === \"number\" ||\n\t\ttypeof error === \"boolean\" ||\n\t\ttypeof error === \"bigint\"\n\t)\n\t\treturn String(error);\n\tif (typeof error === \"symbol\") return error.toString();\n\tif (error === null) return \"null\";\n\tif (error === undefined) return \"undefined\";\n\n\t// Handle arrays\n\tif (Array.isArray(error)) return JSON.stringify(error);\n\n\t// Handle plain objects\n\tif (typeof error === \"object\") {\n\t\tconst errorObj = error as Record<string, unknown>;\n\n\t\t// Check common error properties\n\t\tconst messageProps = [\n\t\t\t\"message\",\n\t\t\t\"error\",\n\t\t\t\"description\",\n\t\t\t\"title\",\n\t\t\t\"reason\",\n\t\t\t\"details\",\n\t\t] as const;\n\t\tfor (const prop of messageProps) {\n\t\t\tif (prop in errorObj && typeof errorObj[prop] === \"string\") {\n\t\t\t\treturn errorObj[prop];\n\t\t\t}\n\t\t}\n\n\t\t// Fallback to JSON stringification\n\t\ttry {\n\t\t\treturn JSON.stringify(error);\n\t\t} catch {\n\t\t\treturn String(error);\n\t\t}\n\t}\n\n\t// Final fallback\n\treturn String(error);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4DA,SAAgB,aACfA,QAC8B;CAC9B,MAAMC,SAAkC,CAAE;AAE1C,MAAK,MAAM,CAAC,MAAM,KAAK,IAAI,OAAO,QAAQ,OAAO,CAChD,QAAO,QAAQ,CAAC,GAAG,SAAoB;EACtC,MAAM,OAAO,AAAC,KACb,GAAG,KACH;AACD,SAAO,IAAI,OAAO,OAAO;GAAE,GAAG;GAAM;EAAM,EAAC,CAAC;CAC5C;AAGF,QAAO;AACP;;;;;;;;;;ACrED,SAAgB,oBAAoBC,OAAwB;AAE3D,KAAI,iBAAiB,MACpB,QAAO,MAAM;AAId,YAAW,UAAU,SAAU,QAAO;AACtC,YACQ,UAAU,mBACV,UAAU,oBACV,UAAU,SAEjB,QAAO,OAAO,MAAM;AACrB,YAAW,UAAU,SAAU,QAAO,MAAM,UAAU;AACtD,KAAI,UAAU,KAAM,QAAO;AAC3B,KAAI,iBAAqB,QAAO;AAGhC,KAAI,MAAM,QAAQ,MAAM,CAAE,QAAO,KAAK,UAAU,MAAM;AAGtD,YAAW,UAAU,UAAU;EAC9B,MAAM,WAAW;EAGjB,MAAM,eAAe;GACpB;GACA;GACA;GACA;GACA;GACA;EACA;AACD,OAAK,MAAM,QAAQ,aAClB,KAAI,QAAQ,mBAAmB,SAAS,UAAU,SACjD,QAAO,SAAS;AAKlB,MAAI;AACH,UAAO,KAAK,UAAU,MAAM;EAC5B,QAAO;AACP,UAAO,OAAO,MAAM;EACpB;CACD;AAGD,QAAO,OAAO,MAAM;AACpB"}

package/dist/function.d.ts

@@ -0,0 +1,36 @@
+//#region src/function.d.ts
+/**
+ * Run-at-most-once wrapper. Wrap `fn` so the first call invokes it and caches the result;
+ * every later call is a no-op that returns that same cached result. Arguments passed after
+ * the first call are ignored.
+ *
+ * Canonical use: an idempotent `[Symbol.dispose]` whose teardown is reachable from more than
+ * one path and must not run twice. `once` makes that guarantee declarative instead of a
+ * hand-rolled `let disposed` flag.
+ *
+ * This is for the pure "this function body runs at most once" case. A boolean that is ALSO
+ * read by other methods to short-circuit a dead object is a liveness flag, not a once-guard;
+ * keep that boolean, `once` does not replace it.
+ *
+ * @example
+ * ```ts
+ * import { once } from "wellcrafted/function";
+ *
+ * const init = once(() => expensiveSetup());
+ * init(); // runs expensiveSetup()
+ * init(); // returns the cached result, does not run again
+ * ```
+ *
+ * @example Idempotent disposal
+ * ```ts
+ * import { once } from "wellcrafted/function";
+ *
+ * const dispose = once(() => closeConnection());
+ * // safe to call from multiple teardown paths; closeConnection() runs at most once
+ * ```
+ */
+declare function once<TArgs extends readonly unknown[], TReturn>(fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+//# sourceMappingURL=function.d.ts.map
+//#endregion
+export { once };
+//# sourceMappingURL=function.d.ts.map

package/dist/function.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"function.d.ts","names":[],"sources":["../src/function.ts"],"sourcesContent":[],"mappings":";;AA8BA;;;;;;AAE8B;;;;;;;;;;;;;;;;;;;;;;;iBAFd,8DACD,UAAU,oBACZ,UAAU"}

package/dist/function.js

@@ -0,0 +1,46 @@
+//#region src/function.ts
+/**
+* Run-at-most-once wrapper. Wrap `fn` so the first call invokes it and caches the result;
+* every later call is a no-op that returns that same cached result. Arguments passed after
+* the first call are ignored.
+*
+* Canonical use: an idempotent `[Symbol.dispose]` whose teardown is reachable from more than
+* one path and must not run twice. `once` makes that guarantee declarative instead of a
+* hand-rolled `let disposed` flag.
+*
+* This is for the pure "this function body runs at most once" case. A boolean that is ALSO
+* read by other methods to short-circuit a dead object is a liveness flag, not a once-guard;
+* keep that boolean, `once` does not replace it.
+*
+* @example
+* ```ts
+* import { once } from "wellcrafted/function";
+*
+* const init = once(() => expensiveSetup());
+* init(); // runs expensiveSetup()
+* init(); // returns the cached result, does not run again
+* ```
+*
+* @example Idempotent disposal
+* ```ts
+* import { once } from "wellcrafted/function";
+*
+* const dispose = once(() => closeConnection());
+* // safe to call from multiple teardown paths; closeConnection() runs at most once
+* ```
+*/
+function once(fn) {
+	let called = false;
+	let result;
+	return (...args) => {
+		if (!called) {
+			called = true;
+			result = fn(...args);
+		}
+		return result;
+	};
+}
+
+//#endregion
+export { once };
+//# sourceMappingURL=function.js.map

package/dist/function.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"function.js","names":["fn: (...args: TArgs) => TReturn","result: TReturn"],"sources":["../src/function.ts"],"sourcesContent":["/**\n * Run-at-most-once wrapper. Wrap `fn` so the first call invokes it and caches the result;\n * every later call is a no-op that returns that same cached result. Arguments passed after\n * the first call are ignored.\n *\n * Canonical use: an idempotent `[Symbol.dispose]` whose teardown is reachable from more than\n * one path and must not run twice. `once` makes that guarantee declarative instead of a\n * hand-rolled `let disposed` flag.\n *\n * This is for the pure \"this function body runs at most once\" case. A boolean that is ALSO\n * read by other methods to short-circuit a dead object is a liveness flag, not a once-guard;\n * keep that boolean, `once` does not replace it.\n *\n * @example\n * ```ts\n * import { once } from \"wellcrafted/function\";\n *\n * const init = once(() => expensiveSetup());\n * init(); // runs expensiveSetup()\n * init(); // returns the cached result, does not run again\n * ```\n *\n * @example Idempotent disposal\n * ```ts\n * import { once } from \"wellcrafted/function\";\n *\n * const dispose = once(() => closeConnection());\n * // safe to call from multiple teardown paths; closeConnection() runs at most once\n * ```\n */\nexport function once<TArgs extends readonly unknown[], TReturn>(\n\tfn: (...args: TArgs) => TReturn,\n): (...args: TArgs) => TReturn {\n\tlet called = false;\n\tlet result: TReturn;\n\treturn (...args: TArgs): TReturn => {\n\t\tif (!called) {\n\t\t\tcalled = true;\n\t\t\tresult = fn(...args);\n\t\t}\n\t\treturn result;\n\t};\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,SAAgB,KACfA,IAC8B;CAC9B,IAAI,SAAS;CACb,IAAIC;AACJ,QAAO,CAAC,GAAG,SAAyB;AACnC,OAAK,QAAQ;AACZ,YAAS;AACT,YAAS,GAAG,GAAG,KAAK;EACpB;AACD,SAAO;CACP;AACD"}