@nicolastoulemont/std 0.8.2 → 0.10.0

package/README.md

@@ -20,7 +20,7 @@ Install optional extras used by some modules and examples:
 pnpm add @nicolastoulemont/std zod multithreading
 ```
 
-- `zod` is optional. The ADT examples below use it, but `Adt` accepts any Standard Schema-compatible validator, including `zod`, `valibot`, `arktype`, and similar libraries.
+- `zod` is optional. The schema-backed tagged union examples below use it, but `Schema` accepts any Standard Schema-compatible validator, including `zod`, `valibot`, `arktype`, and similar libraries.
 - `multithreading` is optional. It is only required if you want to use the `Multithread` module.
 
 ## Quick Start
@@ -256,13 +256,16 @@ const canSearch = isSearchInput({ q: "books", limit: 20 })
 
 ### Schema
 
-Schema wraps Standard Schema-compatible validators for two production use cases:
-boundary parsing and sync-only refinement.
+Schema wraps Standard Schema-compatible validators for three production use cases:
+boundary parsing, sync-only refinement, and bidirectional codecs.
 
 Use `Schema.parse` at I/O boundaries when a broad external type hides smaller implicit subtypes.
 Use `Schema.is` for direct in-memory proof checks.
 Use `Schema.refine` when you need a reusable preserved-shape predicate, especially with higher-order APIs like `Array.filter`.
+Use `Schema.codec` when you need an explicit bidirectional boundary adapter with validated encoded and decoded sides.
+Use `Schema.codec.json` for JSON string encoding/decoding with explicit `JSON.stringify` options.
 Use `Schema.Refine<Base, typeof schema>` for a reusable preserved-shape narrowed type, and `Schema.Infer<typeof schema>` for the exact schema output type.
+Use `Schema.struct`, `Schema.tagged`, and `Schema.union` when you want schema-backed constructors that validate before returning typed data.
 Only use `Schema.is` and `Schema.refine` with sync proof schemas that validate the current value in place. Transforms, defaults, and coercions should continue to use `Schema.parse`.
 
 #### Boundary Parsing Example
@@ -376,26 +379,110 @@ const chatTickets = tickets.filter(isChatTicket)
 
 Use `Schema.Infer<typeof schema>` when you need the exact schema output, and use `Schema.parse` whenever the schema changes the output shape.
 
-### Adt
+#### Bidirectional Codec Example
 
-Adt builds tagged unions backed by any Standard Schema-compatible validator.
-The examples below use `zod`, but the same API works with `valibot`, `arktype`, and other libraries that implement the Standard Schema contract.
+```ts
+import { Result, Schema } from "@nicolastoulemont/std"
+import { z } from "zod"
 
-#### Abstract Example
+const Port = z.number().int().min(1).max(65535)
+
+const PortString = Schema.codec({
+  encoded: z.string(),
+  decoded: Port,
+  decode: (encoded) => Number(encoded),
+  encode: (decoded) => String(decoded),
+})
+
+const decoded = PortString.decode("3000")
+const encoded = PortString.encode(3000)
+
+if (Result.isOk(decoded)) {
+  decoded.value
+}
+
+if (Result.isOk(encoded)) {
+  encoded.value
+}
+```
+
+`Schema.codec` validates both sides:
+
+```txt
+decode: encoded input -> encoded validation -> decode transform -> decoded validation -> decoded output
+encode: decoded value -> decoded validation -> encode transform -> encoded validation -> encoded output
+```
+
+Codec errors are tagged errors under `Schema.Codec`:
+
+```ts
+type CodecError = Schema.Codec.Error
+```
+
+#### JSON Codec Example
+
+```ts
+import { Result, Schema } from "@nicolastoulemont/std"
+import { z } from "zod"
+
+const User = z.object({
+  id: z.string(),
+  name: z.string(),
+})
+
+const UserJson = Schema.codec.json(User, { space: 2 })
+
+const decoded = UserJson.decode('{"id":"u1","name":"Alice"}')
+const encoded = UserJson.encode({ id: "u1", name: "Alice" })
+
+if (Result.isOk(decoded)) {
+  decoded.value.name
+}
+
+if (Result.isOk(encoded)) {
+  encoded.value
+}
+```
+
+#### Schema-Backed Struct Example
+
+```ts
+import { Schema } from "@nicolastoulemont/std"
+import { z } from "zod"
+
+const Folder = Schema.struct(
+  z.object({
+    id: z.string(),
+    name: z.string(),
+    archived: z.boolean().default(false),
+  }),
+)
+
+const created = Folder({ id: "folder_1", name: "Inbox" })
+
+if (created._tag === "Ok") {
+  created.value.equals({ id: "folder_1", name: "Inbox", archived: false })
+}
+```
+
+#### Schema-Backed Tagged Union Example
+
+Schema builds tagged unions backed by any Standard Schema-compatible validator.
+The examples below use `zod`, but the same API works with `valibot`, `arktype`, and other libraries that implement the Standard Schema contract.
 
 ```ts
-import { Adt } from "@nicolastoulemont/std"
+import { Data, Schema } from "@nicolastoulemont/std"
 import { z } from "zod"
 
-const Shape = Adt.union("Shape", {
+const Shape = Schema.union("Shape", {
   Circle: z.object({ radius: z.number() }),
   Square: z.object({ side: z.number() }),
 })
 
-type Shape = Adt.Infer<typeof Shape>
+type Shape = Schema.Union.Infer<typeof Shape>
 
 const describeShape = (shape: Shape) =>
-  Adt.match(shape, {
+  Data.match(shape, {
     Circle: (value) => `circle(${value.radius})`,
     Square: (value) => `square(${value.side})`,
   })
@@ -404,19 +491,19 @@ const describeShape = (shape: Shape) =>
 #### Real-World Example
 
 ```ts
-import { Adt } from "@nicolastoulemont/std"
+import { Data, Schema } from "@nicolastoulemont/std"
 import { z } from "zod"
 
-const OrderState = Adt.union("OrderState", {
+const OrderState = Schema.union("OrderState", {
   Draft: z.object({ id: z.string() }),
   Confirmed: z.object({ id: z.string(), paymentId: z.string() }),
   Shipped: z.object({ id: z.string(), trackingId: z.string() }),
 })
 
-type OrderState = Adt.Infer<typeof OrderState>
+type OrderState = Schema.Union.Infer<typeof OrderState>
 
 const badgeLabel = (state: OrderState) =>
-  Adt.match(state, {
+  Data.match(state, {
     Draft: () => "Waiting for payment",
     Confirmed: () => "Preparing shipment",
     Shipped: (value) => `Shipped: ${value.trackingId}`,
@@ -426,7 +513,7 @@ const badgeLabel = (state: OrderState) =>
 ### Data
 
 Data creates immutable structural value objects with stable equality and hashing semantics.
-Use it when you want value semantics for tuples, arrays, tagged records, or custom error types.
+Use it when you want value semantics for structs, tuples, arrays, tagged records, custom error types, or pattern matching over tagged data.
 
 #### Abstract Example
 
@@ -439,6 +526,8 @@ const b = Data.struct({ env: "prod", retries: 3 })
 const same = a.equals(b) // true
 ```
 
+`Schema.struct` is the validated counterpart to `Data.struct`: it validates through a sync Standard Schema, then wraps the validated object as a structural value.
+
 #### Real-World Example
 
 ```ts
@@ -648,6 +737,8 @@ const readPort = Fx.gen(function* () {
 const exit = Fx.run(Provide.service(Port, 3000)(readPort))
 ```
 
+Use `Provide.layers(...)` when you want the ergonomics of `Provide.layer(Layer.merge(...))` without the extra nesting.
+
 #### Real-World Example
 
 ```ts
@@ -711,7 +802,7 @@ const ApiLive = Layer.ok(Api, {
 
 class InvalidQuantityError extends Data.TaggedError("InvalidQuantityError")<{ qty: number }> {}
 
-const submitOrder = Fx.gen(function* (payload: { sku?: string; qty: number }) {
+const submitOrder = Fx.gen(async function* (payload: { sku?: string; qty: number }) {
   const api = yield* Api
   const sku = yield* Fx.option(payload.sku)
   const validQty = yield* Result.filter(
@@ -719,10 +810,161 @@ const submitOrder = Fx.gen(function* (payload: { sku?: string; qty: number }) {
     (qty) => qty > 0,
     (qty) => new InvalidQuantityError({ qty }),
   )
-  return yield* Fx.try(() => api.postOrder({ sku, qty: validQty }))
+  const created = await Fx.try(() => api.postOrder({ sku, qty: validQty }))
+  return yield* created
+})
+
+const exit = await Fx.run(pipe(submitOrder({ sku: "book-1", qty: 2 }), Provide.layer(ApiLive)))
+```
+
+### Fiber
+
+Fiber exposes handles for running `Fx` computations.
+Use `Fx.runFork` to start a root fiber outside a program, and use `Fx.forkChild` or `Fx.forkDetach` inside `Fx.gen`.
+
+Child fibers are owned by the current fiber and are interrupted when the parent exits.
+Detached fibers snapshot the current runtime state but are not parent-owned.
+Interruption is cooperative: long-running programs should yield with `Fx.yieldNow()` or wait on interruptible runtime operations.
+
+#### Abstract Example
+
+```ts
+import { Fx } from "@nicolastoulemont/std"
+
+const fiber = Fx.runFork(
+  Fx.gen(async function* () {
+    yield* Fx.yieldNow()
+    return 42
+  }),
+)
+
+const exit = await fiber.await()
+// => { _tag: "Ok", value: 42 }
+```
+
+#### Real-World Example
+
+```ts
+import { Fiber, Fx } from "@nicolastoulemont/std"
+
+const program = Fx.gen(async function* () {
+  const child = yield* Fx.forkChild(
+    Fx.gen(async function* () {
+      yield* Fx.yieldNow()
+      return "child-ready"
+    }),
+  )
+
+  const value = yield* Fiber.join(child)
+  const statusAfterJoin = yield* Fiber.status(child)
+
+  return { value, statusAfterJoin }
 })
 
-const exit = Fx.run(pipe(submitOrder({ sku: "book-1", qty: 2 }), Provide.layer(ApiLive)))
+const exit = await Fx.run(program)
+// => { _tag: "Ok", value: { value: "child-ready", statusAfterJoin: "Done" } }
+```
+
+### Log
+
+Log stores contextual fields in the `Fx` runtime state and sends log events to installed logger backends.
+Log events include merged fields, active log spans, trace metadata when a span exists, and the current fiber id.
+Logger failures are ignored so logging cannot fail the user program.
+
+#### Abstract Example
+
+```ts
+import { Fx, Log, Provide } from "@nicolastoulemont/std"
+
+const events: Log.Event[] = []
+
+const program = Provide.layer(Log.layer({ log: (event) => events.push(event) }))(
+  Fx.gen(function* () {
+    const logger = yield* Log.context({ requestId: "req_1" })
+    yield* logger.info("request received", { route: "/orders" })
+    return "ok"
+  }),
+)
+
+const exit = Fx.run(program)
+// => { _tag: "Ok", value: "ok" }
+```
+
+#### Real-World Example
+
+```ts
+import { Fx, Log, Provide } from "@nicolastoulemont/std"
+
+const logger = Log.json()
+
+const program = Provide.layer(Log.layer(logger))(
+  Log.withFields({ service: "checkout" })(
+    Fx.gen(function* () {
+      const log = yield* Log.context({ requestId: "req_42" }, { logSpan: "checkout" })
+      yield* log.info("charging card", { amountCents: 4600 })
+      return "paid"
+    }),
+  ),
+)
+
+const exit = Fx.run(program)
+// => { _tag: "Ok", value: "paid" }
+```
+
+Use `Log.withSpan` for log timing decoration. Use `Trace.span` when you need a real tracing span.
+
+### Trace
+
+Trace stores span context in the `Fx` runtime state.
+Use `Trace.span` to wrap an effect in a tracing span, `Trace.annotate` or `Trace.attribute` to attach attributes, and `Trace.event` to add events.
+`Trace.layer` installs a tracer backend; `Trace.native()` provides a lightweight in-memory-compatible tracer implementation for local use and tests.
+
+#### Abstract Example
+
+```ts
+import { Fx, Trace } from "@nicolastoulemont/std"
+
+const program = Trace.span(
+  "checkout",
+  Fx.gen(function* () {
+    yield* Trace.attribute("order.id", "ord_42")
+    yield* Trace.event("charged")
+    const context = yield* Trace.currentContext()
+    return context === undefined ? "missing" : "traced"
+  }),
+)
+
+const exit = Fx.run(program)
+// => { _tag: "Ok", value: "traced" }
+```
+
+#### Real-World Example
+
+```ts
+import { Fx, Log, Provide, Trace } from "@nicolastoulemont/std"
+
+const logger = Log.console()
+const tracer = Trace.native()
+
+const program = Provide.layers(
+  Log.layer(logger),
+  Trace.layer(tracer),
+)(
+  Trace.span(
+    "POST /orders",
+    Fx.gen(function* () {
+      const log = yield* Log.context({ requestId: "req_42" })
+      yield* Trace.annotate({ "http.method": "POST", "http.route": "/orders" })
+      yield* log.info("request started")
+      yield* Trace.event("order.created", { orderId: "ord_42" })
+      return "ord_42"
+    }),
+    { kind: "server" },
+  ),
+)
+
+const exit = Fx.run(program)
+// => { _tag: "Ok", value: "ord_42" }
 ```
 
 ### Duration
@@ -898,7 +1140,98 @@ await imageQueue.shutdown({ mode: "drain" })
 Multithread runs self-contained callbacks in worker threads using a Result-first API while remaining yieldable in `Fx.gen`.
 It requires the optional `multithreading` dependency at runtime.
 
-#### Abstract Example
+Use it for independent CPU-heavy work that should not block the main thread, such as parsing large payloads, validating batches, compression, or expensive transforms.
+Callbacks are serialized into workers, so they must be self-contained: define helper functions inside the callback or pass data as arguments.
+
+#### Lifecycle
+
+Configure the worker pool before the first multithread operation starts:
+
+```ts
+import { Multithread } from "@nicolastoulemont/std"
+
+const configured = Multithread.configure({ maxWorkers: 4 })
+// => { _tag: "Ok", value: undefined }
+```
+
+`maxWorkers` is the maximum number of worker threads in the shared runtime pool.
+Per-operation `parallelism` controls how many jobs an operation tries to keep in flight, but the runtime can only execute up to `maxWorkers` worker jobs at the same time.
+
+For `Fx` programs, prefer the scoped layer so the worker runtime is shut down with the scope:
+
+```ts
+import { Fx, Multithread, Provide } from "@nicolastoulemont/std"
+
+const program = Provide.layer(Multithread.layer({ maxWorkers: 4 }))(
+  Fx.gen(async function* () {
+    return yield* Multithread.fx(() => 42)
+  }),
+)
+
+const exit = await Fx.run(program)
+// => { _tag: "Ok", value: 42 }
+```
+
+#### Inside `Fx.gen`
+
+Use `Multithread.fx` inside reusable `Fx.gen` programs. It creates a fresh worker operation for each `Fx` execution, so separate runs do not accidentally share cancellation or memoized state.
+
+```ts
+import { Fx, Multithread, Provide } from "@nicolastoulemont/std"
+
+type PurchaseEvent = {
+  readonly id: string
+  readonly accountId: string
+  readonly cents: number
+}
+
+const ndjsonLines = [
+  '{"id":"evt_1","accountId":"acct_1","cents":1200}',
+  '{"id":"evt_2","accountId":"acct_2","cents":3400}',
+]
+
+const program = Provide.layer(Multithread.layer({ maxWorkers: 4 }))(
+  Fx.gen(async function* () {
+    const events = yield* Multithread.fx((lines, ctx) => {
+      const parsed: PurchaseEvent[] = []
+
+      for (const line of lines) {
+        ctx.throwIfCancelled()
+
+        let value: Partial<PurchaseEvent>
+        try {
+          value = JSON.parse(line) as Partial<PurchaseEvent>
+        } catch {
+          return { _tag: "Err" as const, error: { _tag: "InvalidPurchaseEvent" as const, line } }
+        }
+
+        if (typeof value.id !== "string" || typeof value.accountId !== "string" || typeof value.cents !== "number") {
+          return { _tag: "Err" as const, error: { _tag: "InvalidPurchaseEvent" as const, line } }
+        }
+
+        parsed.push({
+          id: value.id,
+          accountId: value.accountId,
+          cents: value.cents,
+        })
+      }
+
+      return parsed
+    }, ndjsonLines)
+
+    return events.reduce((sum, event) => sum + event.cents, 0)
+  }),
+)
+
+const exit = await Fx.run(program)
+// => { _tag: "Ok", value: 4600 }
+```
+
+Fiber interruption aborts the worker operation. Worker cancellation is cooperative, so long-running callbacks should call `ctx.throwIfCancelled()` inside loops.
+
+#### Direct Operation API
+
+Use `Multithread.run` when you need the lower-level operation handle for direct Result-first usage, manual cancellation, explicit sharing, or composition with `race` and `firstSuccess`.
 
 ```ts
 import { Multithread } from "@nicolastoulemont/std"
@@ -909,36 +1242,54 @@ const op = Multithread.run((input: string, ctx) => {
 }, "hello")
 
 const result = await op.result()
+// => { _tag: "Ok", value: "HELLO" }
 ```
 
-#### Real-World Example
+`MultithreadOp` is cold and memoized. Once started, repeated `result()` calls observe the same worker result.
+If you share one operation between multiple fibers or callers, cancellation is also shared: `abort()` cancels it for all current and future waiters.
 
 ```ts
-import { Fx, Multithread } from "@nicolastoulemont/std"
+const op = Multithread.run((ctx) => {
+  while (true) {
+    ctx.throwIfCancelled()
+  }
+})
 
-const program = Fx.gen(async function* () {
-  const records = yield* Multithread.map(
-    ['{"id":"1","email":"a@example.com"}', '{"id":"2","email":"b@example.com"}'],
-    (line, _index, ctx) => {
-      ctx.throwIfCancelled()
-      try {
-        return JSON.parse(line) as { id: string; email: string }
-      } catch {
-        return { _tag: "Err" as const, error: { _tag: "ParseError" as const, line } }
-      }
-    },
-    { parallelism: 4 },
-  )
+op.abort()
+
+const result = await op.result()
+// => { _tag: "Err", error: { _tag: "MultithreadCancelledError", ... } }
+```
 
-  const preferred = yield* Multithread.firstSuccess([Multithread.run(() => "cache"), Multithread.run(() => "database")])
+#### Collection Work
 
-  return { records, preferred }
-})
+Use `map`, `forEach`, `filter`, and `flatMap` for independent collection work.
+Each worker receives `(value, index, ctx)`.
 
-const exit = await Fx.run(program)
+```ts
+import { Multithread } from "@nicolastoulemont/std"
+
+const result = await Multithread.map(
+  [35, 36, 37],
+  (n, _index, ctx) => {
+    const fib = (value: number): number => (value <= 1 ? value : fib(value - 1) + fib(value - 2))
+
+    ctx.throwIfCancelled()
+    return fib(n)
+  },
+  { parallelism: 3 },
+).result()
+// => { _tag: "Ok", value: [9227465, 14930352, 24157817] }
 ```
 
-Multithread cancellation is cooperative. `abort()` always cancels logically, and worker code can stop early by calling `ctx.throwIfCancelled()`.
+`race` returns the first settled operation and aborts the rest.
+`firstSuccess` returns the first successful operation and aggregates failures if all operations fail.
+
+Performance depends on worker startup, callback serialization, payload transfer, and task size. Small jobs can be slower in workers. There is an opt-in probe for local measurement:
+
+```bash
+RUN_MULTITHREAD_PERFORMANCE=1 pnpm --filter @nicolastoulemont/std test src/multithread/tests/multithreading.performance.test.ts
+```
 
 ### pipe / flow
 

package/dist/brand/index.d.mts

@@ -1,2 +1,2 @@
-import { t as brand_d_exports } from "../index-BA0EsFxS.mjs";
+import { t as brand_d_exports } from "../index-BDUhDs4D.mjs";
 export { brand_d_exports as Brand };

package/dist/brand/index.mjs

@@ -1 +1 @@
-import{t as e}from"../brand-DZgGDrAe.mjs";export{e as Brand};
+import{t as e}from"../brand-DP-C92GS.mjs";export{e as Brand};

package/dist/{brand-DZgGDrAe.mjs → brand-DP-C92GS.mjs}

@@ -1,2 +1,2 @@
-import{t as e}from"./chunk-oQKkju2G.mjs";import{i as t,t as n}from"./result-D3VY0qBG.mjs";var r=e({is:()=>o,make:()=>i,refine:()=>s,unsafeMake:()=>a});const i=e=>e,a=e=>e,o=e=>t=>e(t),s=(e,r)=>i=>e(i)?t(i):n({_tag:`BrandError`,value:i,message:typeof r==`function`?r(i):r??`Brand validation failed`});export{i as n,r as t};
-//# sourceMappingURL=brand-DZgGDrAe.mjs.map
+import{t as e}from"./chunk-6rpU2rUb.mjs";import{i as t,t as n}from"./result-C74pRN2x.mjs";var r=e({is:()=>o,make:()=>i,refine:()=>s,unsafeMake:()=>a});const i=e=>e,a=e=>e,o=e=>t=>e(t),s=(e,r)=>i=>e(i)?t(i):n({_tag:`BrandError`,value:i,message:typeof r==`function`?r(i):r??`Brand validation failed`});export{i as n,r as t};
+//# sourceMappingURL=brand-DP-C92GS.mjs.map

package/dist/{brand-DZgGDrAe.mjs.map → brand-DP-C92GS.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"brand-DZgGDrAe.mjs","names":["Result.err","Result.ok"],"sources":["../src/brand/brand.ts"],"sourcesContent":["/**\n * Nominal branding utilities for lightweight domain types.\n *\n * **Mental model**\n * - Brands let you distinguish semantically different values with the same runtime shape.\n * - `Brand.refine` validates and returns `Result`, while `Brand.make` is unchecked.\n *\n * **Common tasks**\n * - Create branded values with `Brand.make`.\n * - Add runtime validation with `Brand.refine`.\n * - Build guards with `Brand.is`.\n *\n * **Gotchas**\n * - Branding is a type-level operation and does not change runtime representation.\n * - `unsafeMake` should be reserved for trusted sources.\n *\n * **Quickstart**\n *\n * @example\n * ```ts\n * import { Brand } from \"@nicolastoulemont/std\"\n *\n * type UserId = Brand.Branded<string, \"UserId\">\n * const raw = \"user_123\" as UserId\n * const userId = Brand.make<UserId>(raw)\n * // => brand-preserving cast\n * ```\n *\n * @module\n */\nimport { Result } from \"../result\"\nimport type { Result as ResultType } from \"../result/result.types\"\nimport type { BrandError as BrandErrorType, Branded as BrandedType, Unbrand, Validator } from \"./brand.types\"\n\n/**\n * Re-exported nominal brand helper type.\n *\n * @example\n * ```ts\n * import { Brand } from \"@nicolastoulemont/std\"\n *\n * type Example = typeof Brand\n * ```\n */\nexport type Branded<T, K extends string> = BrandedType<T, K>\n\n/**\n * Re-exported brand validation error type.\n *\n * @example\n * ```ts\n * import { Brand } from \"@nicolastoulemont/std\"\n *\n * type Example = typeof Brand\n * ```\n */\nexport type BrandError<T> = BrandErrorType<T>\n\n/* oxlint-disable no-unsafe-type-assertion -- Branding is a deliberate nominal cast at the type level and requires explicit assertions. */\n\n/**\n * Create a branded value without validation.\n * This is a type-level cast with zero runtime cost.\n *\n * Use this when you trust the value source (e.g., from a database)\n * or when validation happens elsewhere.\n *\n * @template B - The branded type\n * @param value - The value to brand\n * @returns The value as a branded type\n *\n * @example\n * ```ts\n * import { Brand } from \"@nicolastoulemont/std\"\n *\n * type UserId = Brand.Branded<string, \"UserId\">\n * const raw = \"user_123\" as UserId\n * const userId = Brand.make<UserId>(raw)\n * // => brand-preserving cast\n * ```\n */\nexport const make = <B extends Branded<unknown, string>>(value: Unbrand<B>): B => {\n  return value as B\n}\n\n/**\n * Alias for make() - explicitly indicates no validation occurs.\n * Prefer this when readability about the lack of validation is important.\n *\n * @template B - The branded type\n * @param value - The value to brand (unchecked)\n * @returns The value as a branded type\n *\n * @example\n * ```ts\n * import { Brand } from \"@nicolastoulemont/std\"\n *\n * type UserId = Brand.Branded<string, \"UserId\">\n * const raw = \"user_123\" as UserId\n * const userId = Brand.unsafeMake<UserId>(raw)\n * // => unchecked brand cast\n * ```\n */\nexport const unsafeMake = <B extends Branded<unknown, string>>(value: Unbrand<B>): B => {\n  return value as B\n}\n\n/**\n * Create a type guard with validation for a branded type.\n * Returns a refinement predicate that narrows to the branded type.\n *\n * @template T - The base type\n * @template K - The brand key (string literal)\n * @param validator - A function that validates the base value\n * @returns A type guard that returns true if validation passes\n *\n * @example\n * ```ts\n * import { Brand } from \"@nicolastoulemont/std\"\n *\n * type UserId = Brand.Branded<string, \"UserId\">\n * const isUserId = Brand.is<string, \"UserId\">((value) => value.startsWith(\"user_\"))\n * const valid = isUserId(\"user_123\")\n * // => true\n * ```\n */\nexport const is = <T, K extends string>(validator: Validator<T>): ((value: T) => value is Branded<T, K>) => {\n  return (value: T): value is Branded<T, K> => validator(value)\n}\n\n/**\n * Create a validated branded value wrapped in a Result.\n * Returns `Result.ok(brandedValue)` on success, `Result.err(BrandError)` on failure.\n *\n * The returned Result is yieldable in Fx.gen computations via `yield*`.\n *\n * @template B - The branded type\n * @param validator - A function that validates the base value\n * @param errorMessage - Optional custom error message (or function)\n * @returns A function that takes a value and returns a Result\n *\n * @example\n * ```ts\n * import { Brand } from \"@nicolastoulemont/std\"\n *\n * type UserId = Brand.Branded<string, \"UserId\">\n * const toUserId = Brand.refine<UserId>((value) => value.startsWith(\"user_\"), \"Invalid user id\")\n * const parsed = toUserId(\"user_123\")\n * // => { _tag: \"Ok\", value: \"user_123\" }\n * ```\n */\nexport const refine = <B extends Branded<unknown, string>>(\n  validator: Validator<Unbrand<B>>,\n  errorMessage?: string | ((value: Unbrand<B>) => string),\n): ((value: Unbrand<B>) => ResultType<B, BrandError<Unbrand<B>>>) => {\n  return (value: Unbrand<B>) => {\n    if (!validator(value)) {\n      const msg = typeof errorMessage === \"function\" ? errorMessage(value) : (errorMessage ?? \"Brand validation failed\")\n      return Result.err({ _tag: \"BrandError\" as const, value, message: msg })\n    }\n    return Result.ok(value as B)\n  }\n}\n\n/* oxlint-enable no-unsafe-type-assertion */\n"],"mappings":"uJAiFA,MAAa,EAA4C,GAChD,EAqBI,EAAkD,GACtD,EAsBI,EAA2B,GAC9B,GAAqC,EAAU,EAAM,CAwBlD,GACX,EACA,IAEQ,GACD,EAAU,EAAM,CAIdC,EAAU,EAAW,CAFnBD,EAAW,CAAE,KAAM,aAAuB,QAAO,QAD5C,OAAO,GAAiB,WAAa,EAAa,EAAM,CAAI,GAAgB,0BAClB,CAAC"}
+{"version":3,"file":"brand-DP-C92GS.mjs","names":["Result.err","Result.ok"],"sources":["../src/brand/brand.ts"],"sourcesContent":["/**\n * Nominal branding utilities for lightweight domain types.\n *\n * **Mental model**\n * - Brands let you distinguish semantically different values with the same runtime shape.\n * - `Brand.refine` validates and returns `Result`, while `Brand.make` is unchecked.\n *\n * **Common tasks**\n * - Create branded values with `Brand.make`.\n * - Add runtime validation with `Brand.refine`.\n * - Build guards with `Brand.is`.\n *\n * **Gotchas**\n * - Branding is a type-level operation and does not change runtime representation.\n * - `unsafeMake` should be reserved for trusted sources.\n *\n * **Quickstart**\n *\n * @example\n * ```ts\n * import { Brand } from \"@nicolastoulemont/std\"\n *\n * type UserId = Brand.Branded<string, \"UserId\">\n * const raw = \"user_123\" as UserId\n * const userId = Brand.make<UserId>(raw)\n * // => brand-preserving cast\n * ```\n *\n * @module\n */\nimport { Result } from \"../result\"\nimport type { Result as ResultType } from \"../result/result.types\"\nimport type { BrandError as BrandErrorType, Branded as BrandedType, Unbrand, Validator } from \"./brand.types\"\n\n/**\n * Re-exported nominal brand helper type.\n *\n * @example\n * ```ts\n * import { Brand } from \"@nicolastoulemont/std\"\n *\n * type Example = typeof Brand\n * ```\n */\nexport type Branded<T, K extends string> = BrandedType<T, K>\n\n/**\n * Re-exported brand validation error type.\n *\n * @example\n * ```ts\n * import { Brand } from \"@nicolastoulemont/std\"\n *\n * type Example = typeof Brand\n * ```\n */\nexport type BrandError<T> = BrandErrorType<T>\n\n/* oxlint-disable no-unsafe-type-assertion -- Branding is a deliberate nominal cast at the type level and requires explicit assertions. */\n\n/**\n * Create a branded value without validation.\n * This is a type-level cast with zero runtime cost.\n *\n * Use this when you trust the value source (e.g., from a database)\n * or when validation happens elsewhere.\n *\n * @template B - The branded type\n * @param value - The value to brand\n * @returns The value as a branded type\n *\n * @example\n * ```ts\n * import { Brand } from \"@nicolastoulemont/std\"\n *\n * type UserId = Brand.Branded<string, \"UserId\">\n * const raw = \"user_123\" as UserId\n * const userId = Brand.make<UserId>(raw)\n * // => brand-preserving cast\n * ```\n */\nexport const make = <B extends Branded<unknown, string>>(value: Unbrand<B>): B => {\n  return value as B\n}\n\n/**\n * Alias for make() - explicitly indicates no validation occurs.\n * Prefer this when readability about the lack of validation is important.\n *\n * @template B - The branded type\n * @param value - The value to brand (unchecked)\n * @returns The value as a branded type\n *\n * @example\n * ```ts\n * import { Brand } from \"@nicolastoulemont/std\"\n *\n * type UserId = Brand.Branded<string, \"UserId\">\n * const raw = \"user_123\" as UserId\n * const userId = Brand.unsafeMake<UserId>(raw)\n * // => unchecked brand cast\n * ```\n */\nexport const unsafeMake = <B extends Branded<unknown, string>>(value: Unbrand<B>): B => {\n  return value as B\n}\n\n/**\n * Create a type guard with validation for a branded type.\n * Returns a refinement predicate that narrows to the branded type.\n *\n * @template T - The base type\n * @template K - The brand key (string literal)\n * @param validator - A function that validates the base value\n * @returns A type guard that returns true if validation passes\n *\n * @example\n * ```ts\n * import { Brand } from \"@nicolastoulemont/std\"\n *\n * type UserId = Brand.Branded<string, \"UserId\">\n * const isUserId = Brand.is<string, \"UserId\">((value) => value.startsWith(\"user_\"))\n * const valid = isUserId(\"user_123\")\n * // => true\n * ```\n */\nexport const is = <T, K extends string>(validator: Validator<T>): ((value: T) => value is Branded<T, K>) => {\n  return (value: T): value is Branded<T, K> => validator(value)\n}\n\n/**\n * Create a validated branded value wrapped in a Result.\n * Returns `Result.ok(brandedValue)` on success, `Result.err(BrandError)` on failure.\n *\n * The returned Result is yieldable in Fx.gen computations via `yield*`.\n *\n * @template B - The branded type\n * @param validator - A function that validates the base value\n * @param errorMessage - Optional custom error message (or function)\n * @returns A function that takes a value and returns a Result\n *\n * @example\n * ```ts\n * import { Brand } from \"@nicolastoulemont/std\"\n *\n * type UserId = Brand.Branded<string, \"UserId\">\n * const toUserId = Brand.refine<UserId>((value) => value.startsWith(\"user_\"), \"Invalid user id\")\n * const parsed = toUserId(\"user_123\")\n * // => { _tag: \"Ok\", value: \"user_123\" }\n * ```\n */\nexport const refine = <B extends Branded<unknown, string>>(\n  validator: Validator<Unbrand<B>>,\n  errorMessage?: string | ((value: Unbrand<B>) => string),\n): ((value: Unbrand<B>) => ResultType<B, BrandError<Unbrand<B>>>) => {\n  return (value: Unbrand<B>) => {\n    if (!validator(value)) {\n      const msg = typeof errorMessage === \"function\" ? errorMessage(value) : (errorMessage ?? \"Brand validation failed\")\n      return Result.err({ _tag: \"BrandError\" as const, value, message: msg })\n    }\n    return Result.ok(value as B)\n  }\n}\n\n/* oxlint-enable no-unsafe-type-assertion */\n"],"mappings":"uJAiFA,MAAa,EAA4C,GAChD,EAqBI,EAAkD,GACtD,EAsBI,EAA2B,GAC9B,GAAqC,EAAU,EAAM,CAwBlD,GACX,EACA,IAEQ,GACD,EAAU,EAAM,CAIdC,EAAU,EAAW,CAFnBD,EAAW,CAAE,KAAM,aAAuB,QAAO,QAD5C,OAAO,GAAiB,WAAa,EAAa,EAAM,CAAI,GAAgB,0BAClB,CAAC"}

package/dist/{brand.types-B3NDX1vo.d.mts → brand.types-C_7QgCA4.d.mts}

@@ -59,4 +59,4 @@ type BrandError<T = unknown> = {
 };
 //#endregion
 export { Validator as i, Branded as n, Unbrand as r, BrandError as t };
-//# sourceMappingURL=brand.types-B3NDX1vo.d.mts.map
+//# sourceMappingURL=brand.types-C_7QgCA4.d.mts.map

package/dist/{brand.types-B3NDX1vo.d.mts.map → brand.types-C_7QgCA4.d.mts.map}

@@ -1 +1 @@
-{"version":3,"file":"brand.types-B3NDX1vo.d.mts","names":[],"sources":["../src/brand/brand.types.ts"],"sourcesContent":[],"mappings":";;;AAIwC;AA8BxC;cA9Bc,WA8B6B,EAAA,OAAA,MAAA;;;;AAQ3C;;;KA9BK,KA8B6D,CAAA,UAAA,MAAA,CAAA,GAAA;EAAC,UA7BvD,WAAA,CA6BuD,EA7BzC,CA6ByC;AAQnE,CAAA;AAQA;;;;;;;;;;;;;;;;;;KAxBY,+BAA+B,IAAI,MAAM;;;;;;;KAQzC,aAAa,UAAU,+BAA+B;;;;;;;KAQtD,uBAAuB;;;;;;;KAQvB;;kBAEM"}
+{"version":3,"file":"brand.types-C_7QgCA4.d.mts","names":[],"sources":["../src/brand/brand.types.ts"],"sourcesContent":[],"mappings":";;;AAIwC;AA8BxC;cA9Bc,WA8B6B,EAAA,OAAA,MAAA;;;;AAQ3C;;;KA9BK,KA8B6D,CAAA,UAAA,MAAA,CAAA,GAAA;EAAC,UA7BvD,WAAA,CA6BuD,EA7BzC,CA6ByC;AAQnE,CAAA;AAQA;;;;;;;;;;;;;;;;;;KAxBY,+BAA+B,IAAI,MAAM;;;;;;;KAQzC,aAAa,UAAU,+BAA+B;;;;;;;KAQtD,uBAAuB;;;;;;;KAQvB;;kBAEM"}

package/dist/context/index.d.mts

@@ -1,2 +1,2 @@
-import { n as context_d_exports } from "../context-B2dWloPl.mjs";
+import { n as context_d_exports } from "../context-B9oWzbwF.mjs";
 export { context_d_exports as Context };

package/dist/context/index.mjs

@@ -1 +1 @@
-import{t as e}from"../context-0xDbwtpx.mjs";export{e as Context};
+import{t as e}from"../context-7oKePrBY.mjs";export{e as Context};

package/dist/{context-0xDbwtpx.mjs → context-7oKePrBY.mjs}

@@ -1,2 +1,2 @@
-import{t as e}from"./chunk-oQKkju2G.mjs";var t=e({add:()=>i,empty:()=>n,get:()=>o,has:()=>s,make:()=>r,merge:()=>a,size:()=>c});const n=()=>({_tag:`Context`,_services:new Map,_Services:void 0}),r=(e,t)=>({_tag:`Context`,_services:new Map([[e.key,t]]),_Services:void 0}),i=(e,t)=>n=>({_tag:`Context`,_services:new Map([...n._services,[e.key,t]]),_Services:void 0}),a=(e,t)=>({_tag:`Context`,_services:new Map([...e._services,...t._services]),_Services:void 0});function o(e,t){if(t===void 0){let t=e;return e=>{let n=e._services.get(t.key);if(n===void 0)throw Error(`Service "${t.key}" not found in context. Available services: [${[...e._services.keys()].join(`, `)}]`);return n}}let n=e,r=t,i=n._services.get(r.key);if(i===void 0)throw Error(`Service "${r.key}" not found in context. Available services: [${[...n._services.keys()].join(`, `)}]`);return i}const s=(e,t)=>e._services.has(t.key),c=e=>e._services.size;export{a as i,n,r,t};
-//# sourceMappingURL=context-0xDbwtpx.mjs.map
+import{t as e}from"./chunk-6rpU2rUb.mjs";var t=e({add:()=>i,empty:()=>n,get:()=>o,has:()=>s,make:()=>r,merge:()=>a,size:()=>c});const n=()=>({_tag:`Context`,_services:new Map,_Services:void 0}),r=(e,t)=>({_tag:`Context`,_services:new Map([[e.key,t]]),_Services:void 0}),i=(e,t)=>n=>({_tag:`Context`,_services:new Map([...n._services,[e.key,t]]),_Services:void 0}),a=(e,t)=>({_tag:`Context`,_services:new Map([...e._services,...t._services]),_Services:void 0});function o(e,t){if(t===void 0){let t=e;return e=>{let n=e._services.get(t.key);if(n===void 0)throw Error(`Service "${t.key}" not found in context. Available services: [${[...e._services.keys()].join(`, `)}]`);return n}}let n=e,r=t,i=n._services.get(r.key);if(i===void 0)throw Error(`Service "${r.key}" not found in context. Available services: [${[...n._services.keys()].join(`, `)}]`);return i}const s=(e,t)=>e._services.has(t.key),c=e=>e._services.size;export{a as i,n,r,t};
+//# sourceMappingURL=context-7oKePrBY.mjs.map