zodbridge 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 typescriptmapper contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,361 @@
+# zodbridge
+
+[![CI](https://github.com/khanhx/zodmapper/actions/workflows/ci.yml/badge.svg)](https://github.com/khanhx/zodmapper/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/khanhx/zodmapper/branch/main/graph/badge.svg)](https://codecov.io/gh/khanhx/zodmapper)
+[![npm version](https://img.shields.io/npm/v/zodbridge.svg)](https://www.npmjs.com/package/zodbridge)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+Schema-first, **decorator-free**, **Zod 4**-driven mapping toolkit for the
+DB-entity ↔ response-DTO boundary. No `reflect-metadata`, no class decorators —
+your Zod schema is the single source of truth.
+
+Four composable pillars, each available as its own sub-export:
+
+1. **Two-way mapper** (`createMap`) — entity → DTO with auto-reversible renames.
+2. **Serialize / deserialize** — JSON-safe codec (Date ↔ ISO, BigInt ↔ string, Map ↔ entries).
+3. **Resolver graph** (`createResolver`) — dependency-aware, memoizing, cycle-guarded lazy field resolution over an injected fetch adapter.
+4. **Async mapping** (`forwardAsync`) — resolver-backed fields + a dynamic `select` set, validated with async Zod.
+
+```bash
+npm install zodbridge zod
+```
+
+> **Zod 4 required.** `zod` is a peer dependency pinned to `^4`. The codec
+> dispatches on Zod 4's internal `_zod.def.type`; **Zod 3 is not supported.**
+
+TypeScript ≥ 5.0 is required for the `const` type parameter `createMap` uses to
+preserve bare rule literals.
+
+## Contents
+
+- [1. Two-way mapper — `createMap`](#1-two-way-mapper--createmap)
+  - [Built-in key case conversion](#built-in-key-case-conversion)
+- [2. Serialize / deserialize](#2-serialize--deserialize)
+- [3. Resolver graph — `createResolver`](#3-resolver-graph--createresolver)
+  - [Schema-driven resolvers](#schema-driven-resolvers-validated-output)
+- [4. Async mapping — `forwardAsync`](#4-async-mapping--forwardasync)
+- [Map ops & resolver extras](#map-ops--resolver-extras)
+- [Security](#security)
+- [API surface](#api-surface)
+- [Examples](#examples)
+- [Contributing](#contributing)
+
+---
+
+## 1. Two-way mapper — `createMap`
+
+The dest Zod schema defines the DTO shape. Rules describe how each dest field is
+produced from the source entity:
+
+- `'sourceKey'` — string **rename** (auto-reversible, dot-paths supported).
+- `(source) => value` — **computed** function (one-way).
+- `{ to, from }` — explicit **both-directions** (reversible).
+
+```ts
+import { createMap } from "zodbridge";
+import { z } from "zod";
+
+const UserDto = z.object({
+  id: z.number(),
+  fullName: z.string(),
+  createdAt: z.string(),
+});
+
+const userMap = createMap(UserDto, {
+  fullName: (u: { first: string; last: string }) => `${u.first} ${u.last}`,
+  createdAt: "created_at", // rename
+});
+
+const dto = userMap.forward({ id: 1, first: "Ada", last: "Lovelace", created_at: "2024-01-01" });
+// → { id: 1, fullName: "Ada Lovelace", createdAt: "2024-01-01" }  (Zod-validated)
+
+userMap.reverse(dto);
+// → { created_at: "2024-01-01" }   (only reversible-mapped source fields)
+```
+
+`reverse` emits **only the mapped fields**; a one-way function rule throws
+`OneWayRuleError`. Use a `{ to, from }` pair to make a transform reversible.
+
+### Built-in key case conversion
+
+Every mapper instance also has `toSnakeCase` / `toCamelCase` — they recursively
+re-case **all** property keys of a value to the target case, no matter the input
+casing (snake, camel, Pascal, kebab, SCREAMING_SNAKE all normalize). Only keys
+change; values pass through. Mixed-casing objects are converted per key — a key
+that can't be tokenized is left as-is.
+
+```ts
+userMap.toSnakeCase({ firstName: 1, CreatedAt: 2, "kebab-key": 3 });
+// → { first_name: 1, created_at: 2, kebab_key: 3 }
+
+userMap.toCamelCase({ first_name: 1, post_tags: [{ tag_name: "x" }] });
+// → { firstName: 1, postTags: [{ tagName: "x" }] }   (recurses objects + arrays)
+```
+
+The same functions are exported standalone (and per-key variants too):
+
+```ts
+import { toSnakeCase, toCamelCase, toSnakeKey, toCamelKey } from "zodbridge";
+```
+
+Notes:
+- **Collisions:** if two source keys normalize to the same target (e.g. `userId`
+  and `userID` → `user_id`), the last one in iteration order wins.
+- **Safety:** a source key that normalizes to `constructor` or `prototype` is
+  dropped (never emitted) to prevent prototype pollution.
+- **Idempotency:** `toSnakeCase` is idempotent. `toCamelCase` is too, except for
+  keys that produce adjacent single-letter words (`a-b` → `aBCD` → `aBcd`) — an
+  unusual shape for real DTO keys.
+
+---
+
+## 2. Serialize / deserialize
+
+JSON-safe round-trip driven by the schema. `serialize` converts rich values to
+JSON-safe plain values; `deserialize` rebuilds them and validates with Zod.
+
+```ts
+import { serialize, deserialize } from "zodbridge/serialize";
+import { z } from "zod";
+
+const Event = z.object({ id: z.bigint(), at: z.date(), tally: z.map(z.string(), z.bigint()) });
+
+const wire = serialize({ id: 42n, at: new Date(), tally: new Map([["a", 1n]]) }, Event);
+JSON.stringify(wire); // safe — no Date/BigInt/Map left
+
+deserialize(wire, Event); // → original rich values, Zod-validated
+```
+
+`deserialize` is **sync-only**; a schema with async refinements throws
+`AsyncSchemaError`. Malformed wire input surfaces a typed `CodecError` (never a
+raw throw), and BigInt-string length / Map-entry count are bounded against DoS.
+
+---
+
+## 3. Resolver graph — `createResolver`
+
+Declarative, dependency-aware field resolution. Each field's resolver may read
+the seed, call the injected `adapter`, depend on other fields (`resolve`), or
+fall back to alternate sources (`fallback`). Results are **memoized** (one fetch
+per field, even under `Promise.all`), and cycles are guarded.
+
+```ts
+import { createResolver } from "zodbridge/resolver";
+
+interface Fields { orgId: string; org: { id: string; plan: string }; plan: string }
+interface Api { getOrg: (id: string) => Promise<{ id: string; plan: string }> }
+
+// your injected data source (DB client, HTTP API, etc.)
+const api: Api = {
+  getOrg: async (id) => ({ id, plan: "pro" }),
+};
+
+const ctx = createResolver<Fields, Api>({
+  adapter: api,
+  seed: { orgId: "o1" },
+  resolvers: {
+    org: (c) => c.adapter.getOrg(c.get("orgId") ?? ""),
+    plan: async (c) => (await c.resolve("org"))?.plan,
+  },
+});
+
+await ctx.resolve("plan");            // → "pro"  (fetches org once, derives plan)
+await ctx.resolveMany("org", "plan"); // { org, plan } — org NOT re-fetched
+```
+
+- `get(field)` — synchronous peek of seed + already-resolved values (no I/O).
+- `path(field, [..keys])` — pure nested peek (never resolves, never fetches).
+- `fallback([deps])` — resolve untouched deps, then retry the calling field.
+
+A resolver that **returns `undefined`** caches `undefined` (forgiving absence).
+A resolver that **throws** rejects and is **not cached** — auth/DB failures stay
+loud and a later retry can succeed.
+
+**Cycles never hang.** Mutually dependent fields are safe: if `conversation`'s
+resolver does `await ctx.resolve("reservation")` and `reservation`'s does
+`await ctx.resolve("conversation")`, a re-entry of a field already being resolved
+in the same chain returns `undefined` (so a `strategies` candidate falls through
+to its next route) — it never deadlocks. Concurrent
+`Promise.all` over a shared dependency is unaffected and still dedups to one fetch.
+
+### Schema-driven resolvers (validated output)
+
+Instead of a hand-written `Fields` type, derive the resolvable fields and their
+schemas from `createMap` instances. Each resolver's **output is validated** against
+its map's schema (unknown keys stripped) before caching — bad adapter data and
+over-exposure are caught at the boundary. Pass scalar dependency fields (with no
+DTO) via an optional `fields` object.
+
+```ts
+import { createResolver } from "zodbridge/resolver";
+import { createMap } from "zodbridge";
+import { z } from "zod";
+
+const userMap = createMap(z.object({ id: z.string(), name: z.string() }));
+const orgMap = createMap(z.object({ orgId: z.string(), tier: z.number() }));
+
+const api = {
+  getOrg: async (orgId: string) => ({ orgId, tier: 2 }),
+  getUser: async (orgId: string) => ({ id: `u-${orgId}`, name: "Ada" }),
+};
+
+const ctx = createResolver({
+  adapter: api,
+  maps: { user: userMap, org: orgMap },    // validated DTO fields
+  fields: z.object({ orgId: z.string() }), // scalar deps (no DTO)
+  seed: { orgId: "o1" },
+  resolvers: {
+    org: (c) => c.adapter.getOrg(c.get("orgId") ?? ""),  // typed as orgMap's DTO
+    user: async (c) => {
+      const org = await c.resolve("org");                // chaining
+      return c.adapter.getUser(org?.orgId ?? "");        // typed as userMap's DTO
+    },
+  },
+});
+
+await ctx.resolve("user"); // → { id: "u-o1", name: "Ada" }  (validated, or rejects)
+```
+
+- Resolver output is parsed; a value that fails its schema **rejects and evicts**
+  (same loud-failure policy as a thrown resolver).
+- **Seed is not validated** — it is trusted caller input (allows partial/scalar seed).
+- The hand-written `createResolver<Fields, Adapter>(...)` signature still works
+  unchanged (no runtime validation when no schema is attached).
+
+---
+
+## 4. Async mapping — `forwardAsync`
+
+Combine the mapper and the resolver. The `fromResolver` rule pulls a field from
+the resolver graph; an optional `select` set restricts which fields (and which
+resolver calls) run.
+
+```ts
+import { createMap, fromResolver } from "zodbridge";
+import { forwardAsync } from "zodbridge/async";
+import { createResolver } from "zodbridge/resolver";
+import { z } from "zod";
+
+const PostDto = z.object({
+  id: z.string(),
+  author: z.object({ id: z.string(), name: z.string() }),
+});
+
+const postMap = createMap(PostDto, { id: "post_id", author: fromResolver("author") });
+
+// the resolver that backs the `fromResolver("author")` rule
+const resolver = createResolver<{ author: { id: string; name: string } }, object>({
+  adapter: {},
+  resolvers: { author: async () => ({ id: "a1", name: "Ada" }) },
+});
+
+await forwardAsync(postMap, { post_id: "p1" }, { resolver });
+// → { id: "p1", author: { id: "a1", name: "Ada" } }  (author resolved + validated)
+
+await forwardAsync(postMap, { post_id: "p1" }, { resolver, select: ["id"] });
+// → { id: "p1" }  — author's resolver never fires
+```
+
+Validation uses `safeParseAsync`, so field-level async `.refine` runs. A partial
+`select` validates against a sub-schema derived from the raw `.shape` (Zod 4's
+`.pick()/.partial()` throw on refined schemas, so they are never called).
+Object-level cross-field refines run only on a **full** select. If any
+`fromResolver` resolver throws, the whole `forwardAsync` promise rejects.
+
+---
+
+## Security
+
+- **`select` is NOT an authorization boundary.** It is a performance/shape knob.
+  Enforce field-level authorization *before* passing any untrusted selection.
+- **Over-exposure.** Resolver-backed fields are parsed through their own dest
+  sub-schema, and Zod objects `.strip()` unknown keys by default — so extra
+  adapter-row columns (`passwordHash`, …) are dropped. **`z.any()`,
+  `.passthrough()`, and `z.record()` DISABLE this** and leak the value verbatim.
+  Use closed object schemas for response DTOs.
+- **Resolver errors propagate.** Your adapter must enforce authorization and
+  throw on denial; the resolver will not swallow it.
+- **Prototype pollution.** The dot-path helpers reject `__proto__`, `prototype`,
+  and `constructor` segments, so mapping untrusted data cannot poison
+  `Object.prototype`.
+- **DoS guards.** `deserialize` bounds BigInt-string length and Map-entry count
+  before transforming attacker-controlled input.
+
+---
+
+## API surface
+
+| Import path                 | Exports |
+|-----------------------------|---------|
+| `zodbridge`          | `createMap`, `fromResolver`, `withDefault`, `forwardMany`, `safeForward`, `pick`, `omit`, `compose`, `toSnakeCase`/`toCamelCase`/`toKebabCase`/`toPascalCase`/`toConstantCase` (+ per-key), `serialize`, `deserialize`, `deserializeAsync`, errors, `VERSION` |
+| `zodbridge/serialize`| `serialize`, `deserialize`, `deserializeAsync`, `CodecError`, `AsyncSchemaError`, leaf transforms (incl. `setToArray`) |
+| `zodbridge/resolver` | `createResolver`, `strategies`, `SKIP`, `GraphContext`, types |
+| `zodbridge/async`    | `forwardAsync`, `normalizeSelect`, `UnknownSelectKeyError` |
+
+### Map ops & resolver extras
+
+```ts
+import { createMap, compose, pick, withDefault } from "zodbridge";
+import { createResolver, strategies, SKIP } from "zodbridge/resolver";
+
+const UserDto = z.object({ id: z.number(), name: z.string(), role: z.string() });
+const userMap = createMap(UserDto, {
+  name: "full_name",
+  role: withDefault("member", "user_role"), // default when source missing
+});
+
+userMap.forwardMany([{ id: 1, full_name: "Ada" }]); // batch -> validated DTO[]
+userMap.safeForward({ id: "bad" });                 // { success: false, error }
+pick(userMap, ["id", "name"]);                      // sub-DTO view (new map)
+
+// resolver: try the fastest source first; first DEFINED value wins.
+// A candidate skips by returning `undefined` or the `SKIP` sentinel — `null`
+// is a winning value (return `SKIP` to skip when the value would be null).
+createResolver({
+  adapter,
+  resolvers: {
+    conversation: strategies(
+      (c) => c.adapter.byReservation(c.get("reservationId")),       // undefined -> skip
+      (c) => c.adapter.byConversationId(c.get("conversationId")) ?? SKIP, // skip even if null
+    ),
+  },
+});
+// force a fresh fetch (e.g. after a write):
+await ctx.refresh("org");
+
+// attach a resolver graph to the map itself:
+const m = createMap(schema, rules, { resolvers: { org: (c) => c.adapter.getOrg() } });
+const ctx = m.toResolver(adapter, seed); // validated against the map's schema
+```
+
+Ships dual ESM + CJS with `.d.ts` for every entry. Zero runtime dependencies.
+
+## Examples
+
+Runnable, self-contained use-cases live in [`examples/`](./examples):
+
+| # | Example | Shows |
+|---|---------|-------|
+| 01 | basic mapping | `forward`/`reverse`, rename + computed + pair rules |
+| 02 | case conversion | `toSnakeCase`/`toCamelCase`, value preservation |
+| 03 | serialize/deserialize | Date/BigInt/Map/Set JSON round-trip |
+| 04 | resolver graph | memoized resolution + `refresh` |
+| 05 | smart resolve | `strategies()` fastest-first multi-source |
+| 06 | async + select | `forwardAsync` with dynamic `select` |
+| 07 | map ops & views | batch/safe, `withDefault`, `pick`/`omit`/`compose`, `map.toResolver` |
+
+```bash
+npm run example examples/04-resolver-graph.ts  # run one (tsx)
+npm run verify:examples                         # typecheck them all
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md). In short: TDD, keep the **100% coverage
+gate** green, add a [changeset](https://github.com/changesets/changesets), and
+keep changes additive. Security issues → [SECURITY.md](./SECURITY.md) (private
+reporting, not public issues).
+
+## License
+
+[MIT](./LICENSE)

package/dist/async/index.cjs

@@ -0,0 +1,146 @@
+'use strict';
+
+var zod = require('zod');
+
+// src/async/forwardAsync.ts
+
+// src/map/rules.ts
+function isStringRule(rule) {
+  return typeof rule === "string";
+}
+function isFromResolverRule(rule) {
+  return typeof rule === "object" && rule !== null && rule.__kind === "fromResolver";
+}
+function isPairRule(rule) {
+  return typeof rule === "object" && rule !== null && typeof rule.to === "function" && typeof rule.from === "function";
+}
+function isDefaultRule(rule) {
+  return typeof rule === "object" && rule !== null && rule.__kind === "default";
+}
+function isFnRule(rule) {
+  return typeof rule === "function";
+}
+var FORBIDDEN_KEYS = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
+function isForbidden(key) {
+  return FORBIDDEN_KEYS.has(key);
+}
+function splitPath(path) {
+  return path.split(".");
+}
+function getPath(source, path) {
+  let current = source;
+  for (const segment of splitPath(path)) {
+    if (isForbidden(segment)) return void 0;
+    if (current === null || current === void 0) return void 0;
+    if (typeof current !== "object") return void 0;
+    if (!Object.prototype.hasOwnProperty.call(current, segment)) return void 0;
+    current = current[segment];
+  }
+  return current;
+}
+function setPath(target, path, value) {
+  const segments = splitPath(path);
+  let current = target;
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i];
+    if (isForbidden(segment)) return;
+    if (i === segments.length - 1) {
+      current[segment] = value;
+      return;
+    }
+    const next = current[segment];
+    if (typeof next !== "object" || next === null) {
+      const fresh = {};
+      current[segment] = fresh;
+      current = fresh;
+    } else {
+      current = next;
+    }
+  }
+}
+
+// src/map/createMap.ts
+function applyForwardRule(rule, destKey, source) {
+  if (rule === void 0) {
+    return getPath(source, destKey);
+  }
+  if (isStringRule(rule)) {
+    return getPath(source, rule);
+  }
+  if (isPairRule(rule)) {
+    return rule.to(source);
+  }
+  if (isDefaultRule(rule)) {
+    const read = getPath(source, rule.source ?? destKey);
+    return read === void 0 ? rule.value : read;
+  }
+  if (isFnRule(rule)) {
+    return rule(source);
+  }
+  return void 0;
+}
+
+// src/async/forwardAsync.ts
+var UnknownSelectKeyError = class extends Error {
+  keys;
+  constructor(keys) {
+    super(
+      `forwardAsync select contains key(s) not in the dest schema: ${keys.join(", ")}`
+    );
+    this.name = "UnknownSelectKeyError";
+    this.keys = keys;
+  }
+};
+function normalizeSelect(select, shape) {
+  if (select === void 0) return void 0;
+  const deduped = Array.from(new Set(select));
+  const unknown = deduped.filter(
+    (k) => !Object.prototype.hasOwnProperty.call(shape, k)
+  );
+  if (unknown.length > 0) throw new UnknownSelectKeyError(unknown);
+  return deduped;
+}
+async function stripField(value, fieldSchema) {
+  const result = await fieldSchema.safeParseAsync(value);
+  if (!result.success) return value;
+  return result.data;
+}
+async function forwardAsync(map, source, options) {
+  const { resolver, select } = options;
+  const { schema, rules, shape } = map;
+  const selected = normalizeSelect(select, shape);
+  const targetKeys = selected ?? Object.keys(shape);
+  const assembled = {};
+  for (const key of targetKeys) {
+    const rule = rules[key];
+    if (isFromResolverRule(rule)) {
+      const field = rule.field;
+      const raw = await resolver.resolve(field);
+      if (raw !== void 0) {
+        const value2 = await stripField(raw, shape[key]);
+        setPath(assembled, key, value2);
+      }
+      continue;
+    }
+    const produced = applyForwardRule(rule, key, source);
+    const value = produced instanceof Promise ? await produced : produced;
+    if (value !== void 0) setPath(assembled, key, value);
+  }
+  const validator = selected === void 0 ? schema : buildSubSchema(shape, selected);
+  const result = await validator.safeParseAsync(assembled);
+  if (!result.success) throw result.error;
+  return result.data;
+}
+function buildSubSchema(shape, selected) {
+  const picked = {};
+  for (const key of selected) {
+    picked[key] = shape[key];
+  }
+  return zod.z.object(picked);
+}
+
+exports.UnknownSelectKeyError = UnknownSelectKeyError;
+exports.forwardAsync = forwardAsync;
+exports.normalizeSelect = normalizeSelect;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/async/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/map/rules.ts","../../src/map/createMap.ts","../../src/async/forwardAsync.ts"],"names":["value","z"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Rule kinds for {@link createMap} and the dot-path get/set helpers they use.\n *\n * Rule kinds (by JS type):\n * - `string`            — rename: copy `source[ruleValue]` to the dest key. Auto-reversible.\n * - `(source) => value` — computed function, one-way (no reverse unless paired).\n * - `{ to, from }`      — explicit both-directions, reversible.\n * - `FromResolver`      — value pulled from a resolver graph (async path, Phase 5).\n */\n\n/** A function rule: derive a dest value from the whole source object. */\nexport type FnRule<S, V> = (source: S) => V;\n\n/** A reversible rule with explicit forward (`to`) and inverse (`from`) maps. */\nexport interface PairRule<S, V> {\n  to: (source: S) => V;\n  from: (value: V) => unknown;\n}\n\n/** Marker for a dest field resolved from a resolver graph (consumed by Phase 5). */\nexport interface FromResolver {\n  readonly __kind: \"fromResolver\";\n  readonly field: string;\n}\n\n/**\n * Default-value rule: read `source` (a source key, defaults to the dest key)\n * and fall back to `value` when the source is `undefined`. Reverse-safe: the\n * default is dropped on reverse and only the read key round-trips.\n */\nexport interface DefaultRule<V = unknown> {\n  readonly __kind: \"default\";\n  readonly value: V;\n  readonly source?: string;\n}\n\n/** Any rule a dest key may be configured with. */\nexport type Rule<S = any, V = any> =\n  | string\n  | FnRule<S, V>\n  | PairRule<S, V>\n  | FromResolver\n  | DefaultRule<V>;\n\n/** Build a {@link FromResolver} marker for `field` in the resolver graph. */\nexport function fromResolver(field: string): FromResolver {\n  return { __kind: \"fromResolver\", field };\n}\n\n/**\n * Build a {@link DefaultRule}: use `source` (or the dest key) from the entity,\n * falling back to `value` when absent.\n */\nexport function withDefault<V>(value: V, source?: string): DefaultRule<V> {\n  return { __kind: \"default\", value, source };\n}\n\n// --- type guards ---\n\nexport function isStringRule(rule: Rule): rule is string {\n  return typeof rule === \"string\";\n}\n\nexport function isFromResolverRule(rule: Rule): rule is FromResolver {\n  return (\n    typeof rule === \"object\" &&\n    rule !== null &&\n    (rule as FromResolver).__kind === \"fromResolver\"\n  );\n}\n\nexport function isPairRule(rule: Rule): rule is PairRule<any, any> {\n  return (\n    typeof rule === \"object\" &&\n    rule !== null &&\n    typeof (rule as PairRule<any, any>).to === \"function\" &&\n    typeof (rule as PairRule<any, any>).from === \"function\"\n  );\n}\n\nexport function isDefaultRule(rule: Rule): rule is DefaultRule {\n  return (\n    typeof rule === \"object\" &&\n    rule !== null &&\n    (rule as DefaultRule).__kind === \"default\"\n  );\n}\n\nexport function isFnRule(rule: Rule): rule is FnRule<any, any> {\n  return typeof rule === \"function\";\n}\n\n// --- prototype-pollution-safe dot-path helpers ---\n\n/** Path segments that, if written, could poison `Object.prototype`. */\nconst FORBIDDEN_KEYS = new Set([\"__proto__\", \"prototype\", \"constructor\"]);\n\nfunction isForbidden(key: string): boolean {\n  return FORBIDDEN_KEYS.has(key);\n}\n\n/** Split a dot-path into segments. A plain key (no dot) yields a single segment. */\nexport function splitPath(path: string): string[] {\n  return path.split(\".\");\n}\n\n/**\n * Read a nested value by dot-path. Returns `undefined` if any segment is\n * missing or if a segment is a forbidden prototype key (read is skipped, not\n * served from the prototype chain).\n */\nexport function getPath(source: unknown, path: string): unknown {\n  let current: unknown = source;\n  for (const segment of splitPath(path)) {\n    if (isForbidden(segment)) return undefined;\n    if (current === null || current === undefined) return undefined;\n    if (typeof current !== \"object\") return undefined;\n    if (!Object.prototype.hasOwnProperty.call(current, segment)) return undefined;\n    current = (current as Record<string, unknown>)[segment];\n  }\n  return current;\n}\n\n/**\n * Write a nested value by dot-path, auto-vivifying intermediate objects.\n * Forbidden prototype keys at any segment are skipped entirely, so a hostile\n * `__proto__.isAdmin` path can never mutate `Object.prototype`.\n */\nexport function setPath(target: Record<string, unknown>, path: string, value: unknown): void {\n  const segments = splitPath(path);\n  let current: Record<string, unknown> = target;\n  for (let i = 0; i < segments.length; i++) {\n    const segment = segments[i] as string;\n    if (isForbidden(segment)) return;\n    if (i === segments.length - 1) {\n      current[segment] = value;\n      return;\n    }\n    const next = current[segment];\n    if (typeof next !== \"object\" || next === null) {\n      const fresh: Record<string, unknown> = {};\n      current[segment] = fresh;\n      current = fresh;\n    } else {\n      current = next as Record<string, unknown>;\n    }\n  }\n}\n","/**\n * `createMap(destSchema, rules)` — synchronous, Zod-validated entity -> DTO\n * mapper. The dest Zod schema is the shape source of truth. Simple string\n * renames and `{ to, from }` pairs auto-reverse; computed function rules are\n * one-way unless paired.\n */\nimport type { z } from \"zod\";\nimport { createResolver } from \"../resolver/createResolver.js\";\nimport type { ResolverContext, ResolverRegistry } from \"../resolver/context.js\";\nimport {\n  type CamelCased,\n  type SnakeCased,\n  toCamelCase,\n  toSnakeCase,\n} from \"./case-convert.js\";\nimport {\n  type SafeResult,\n  forwardMany as forwardManyOp,\n  reverseMany as reverseManyOp,\n  safeForward as safeForwardOp,\n} from \"./map-ops.js\";\nimport {\n  type DefaultRule,\n  type FromResolver,\n  type Rule,\n  getPath,\n  isDefaultRule,\n  isFnRule,\n  isFromResolverRule,\n  isPairRule,\n  isStringRule,\n  setPath,\n} from \"./rules.js\";\n\n/**\n * Resolver graph declared on a map: each field of the dest DTO `Dest` may have\n * a resolver typed against `Dest` and the adapter `TAdapter`.\n */\nexport type MapResolvers<Dest = Record<string, unknown>, TAdapter = unknown> =\n  ResolverRegistry<Dest, TAdapter>;\n\n/** Options for {@link createMap}, parameterized by the dest DTO and adapter type. */\nexport interface CreateMapOptions<Dest = Record<string, unknown>, TAdapter = unknown> {\n  /**\n   * Resolver graph for this map's fields, against the map's own dest schema.\n   * Enables `map.toResolver(adapter)` and resolver-backed `forwardAsync` without\n   * a separate `createResolver` call. Each resolver's output is typed against the\n   * DTO field it produces. NOTE: `ctx.adapter` is typed as the concrete adapter\n   * only at the `toResolver(adapter)` call site — inside these declarations it is\n   * `unknown` (the adapter is not known at `createMap` time); cast it if needed.\n   */\n  resolvers?: MapResolvers<Dest, TAdapter>;\n}\n\n/** Thrown when `reverse` meets a one-way function rule that has no inverse. */\nexport class OneWayRuleError extends Error {\n  readonly key: string;\n  constructor(key: string) {\n    super(\n      `Cannot reverse dest key \"${key}\": it is mapped by a one-way function ` +\n        `rule. Use a { to, from } pair rule to make it reversible.`,\n    );\n    this.name = \"OneWayRuleError\";\n    this.key = key;\n  }\n}\n\n/** Thrown when `toResolver` is called on a map that declared no resolvers. */\nexport class MapHasNoResolversError extends Error {\n  constructor() {\n    super(\n      \"createMap.toResolver requires a resolver graph: pass \" +\n        \"`createMap(schema, rules, { resolvers })`.\",\n    );\n    this.name = \"MapHasNoResolversError\";\n  }\n}\n\n/** Thrown at build time when two rules reverse onto the same source key. */\nexport class ReverseKeyCollisionError extends Error {\n  constructor(sourceKey: string, a: string, b: string) {\n    super(\n      `Reverse-key collision: dest keys \"${a}\" and \"${b}\" both map back to ` +\n        `source key \"${sourceKey}\". Disambiguate one of them.`,\n    );\n    this.name = \"ReverseKeyCollisionError\";\n  }\n}\n\ntype AnyZodObject = z.ZodObject<any>;\n\n/** Rule map: each dest key may carry a rule; unmapped keys are copied by name. */\nexport type RuleMap<Dest> = Partial<Record<keyof Dest & string, Rule>>;\n\nexport interface TypeMapper<S extends AnyZodObject, R extends RuleMap<z.infer<S>>> {\n  /** Build a validated DTO from a source entity (sync path). */\n  forward(source: Record<string, unknown>): z.infer<S>;\n  /** Forward every item in a list, returning the validated DTO array. */\n  forwardMany(sources: Array<Record<string, unknown>>): Array<z.infer<S>>;\n  /** Forward without throwing: `{ success, data }` or `{ success: false, error }`. */\n  safeForward(source: Record<string, unknown>): SafeResult<z.infer<S>>;\n  /** Invert reversible rules; returns only mapped source fields. */\n  reverse(dto: z.infer<S>): Partial<Record<string, unknown>>;\n  /** Reverse every DTO in a list. */\n  reverseMany(dtos: Array<z.infer<S>>): Array<Partial<Record<string, unknown>>>;\n  /**\n   * Recursively re-case ALL property keys of `value` to `snake_case`,\n   * regardless of their original casing. Keys only; values pass through.\n   */\n  toSnakeCase<T>(value: T): SnakeCased<T>;\n  /**\n   * Recursively re-case ALL property keys of `value` to `camelCase`,\n   * regardless of their original casing. Keys only; values pass through.\n   */\n  toCamelCase<T>(value: T): CamelCased<T>;\n  /**\n   * Build a resolver graph from THIS map's schema fields plus the resolver\n   * graph declared in `createMap`'s options. The resolver validates each field's\n   * output against the matching dest sub-schema (over-exposure protection).\n   * Throws if no `resolvers` were declared on the map.\n   */\n  toResolver<TAdapter>(\n    adapter: TAdapter,\n    seed?: Partial<z.infer<S>>,\n  ): ResolverContext<z.infer<S>, TAdapter>;\n  /** The dest schema (shape source of truth). */\n  readonly schema: S;\n  /** Configured rules, frozen. */\n  readonly rules: R;\n  /** Raw `.shape` of the dest object — used by the async path (Phase 5). */\n  readonly shape: Record<string, z.ZodType>;\n  /** Resolver graph declared on this map (if any), for `toResolver`/forwardAsync. */\n  readonly resolvers?: MapResolvers<z.infer<S>>;\n}\n\n/** Apply a single forward rule for `destKey`, returning the mapped value. */\nexport function applyForwardRule(\n  rule: Rule | undefined,\n  destKey: string,\n  source: Record<string, unknown>,\n): unknown {\n  if (rule === undefined) {\n    // No rule: copy by matching dest key from source (dot-path aware).\n    return getPath(source, destKey);\n  }\n  if (isStringRule(rule)) {\n    return getPath(source, rule);\n  }\n  if (isPairRule(rule)) {\n    return rule.to(source);\n  }\n  if (isDefaultRule(rule)) {\n    const read = getPath(source, rule.source ?? destKey);\n    return read === undefined ? rule.value : read;\n  }\n  if (isFnRule(rule)) {\n    return rule(source);\n  }\n  // FromResolver markers are resolved only on the async path; sync forward\n  // treats them as absent (the field is filled by forwardAsync).\n  return undefined;\n}\n\n/**\n * Build a two-way mapper. The `const` type parameter on `R` preserves bare\n * object-literal rule values (string-literal renames) without the caller\n * writing `as const` (requires TypeScript >= 5.0).\n */\nexport function createMap<\n  S extends AnyZodObject,\n  const R extends RuleMap<z.infer<S>>,\n>(\n  schema: S,\n  rules: R = {} as R,\n  options: CreateMapOptions<z.infer<S>> = {},\n): TypeMapper<S, R> {\n  const shape = schema.shape as Record<string, z.ZodType>;\n  const destKeys = Object.keys(shape);\n  const mapResolvers = options.resolvers;\n\n  // Build-time reverse-collision detection: any two reversible rules whose\n  // inverse targets the same source key are a configuration error.\n  const reverseTargets = new Map<string, string>();\n  for (const destKey of Object.keys(rules) as Array<keyof R & string>) {\n    const rule = rules[destKey] as Rule | undefined;\n    if (rule !== undefined && isStringRule(rule)) {\n      const existing = reverseTargets.get(rule);\n      if (existing) throw new ReverseKeyCollisionError(rule, existing, destKey);\n      reverseTargets.set(rule, destKey);\n    }\n  }\n\n  function forward(source: Record<string, unknown>): z.infer<S> {\n    const out: Record<string, unknown> = {};\n    for (const destKey of destKeys) {\n      const rule = rules[destKey as keyof R & string] as Rule | undefined;\n      if (isFromResolverRule(rule as Rule)) continue; // async-only\n      const value = applyForwardRule(rule, destKey, source);\n      if (value !== undefined) setPath(out, destKey, value);\n    }\n    return schema.parse(out) as z.infer<S>;\n  }\n\n  function reverse(dto: z.infer<S>): Partial<Record<string, unknown>> {\n    const out: Record<string, unknown> = {};\n    const dtoObj = dto as Record<string, unknown>;\n    for (const destKey of Object.keys(rules) as Array<keyof R & string>) {\n      const rule = rules[destKey] as Rule | undefined;\n      if (rule === undefined) continue;\n      const destValue = getPath(dtoObj, destKey);\n      if (isStringRule(rule)) {\n        setPath(out, rule, destValue);\n      } else if (isPairRule(rule)) {\n        setPath(out, destKey, rule.from(destValue));\n      } else if (isDefaultRule(rule)) {\n        // Round-trip the read key; the default itself is forward-only.\n        setPath(out, (rule as DefaultRule).source ?? destKey, destValue);\n      } else if (isFromResolverRule(rule as Rule)) {\n        // Resolver-backed fields have no source inverse; skip.\n        continue;\n      } else {\n        // One-way function rule, no inverse.\n        throw new OneWayRuleError(destKey);\n      }\n    }\n    return out;\n  }\n\n  type Dest = z.infer<S>;\n\n  function toResolver<TAdapter>(\n    adapter: TAdapter,\n    seed?: Partial<Dest>,\n  ): ResolverContext<Dest, TAdapter> {\n    if (!mapResolvers) {\n      throw new MapHasNoResolversError();\n    }\n    // Per-field schemas from this map's own shape (over-exposure protection).\n    const schemas: Record<string, z.ZodType> = {};\n    for (const key of Object.keys(shape)) {\n      schemas[key] = shape[key] as z.ZodType;\n    }\n    return createResolver<Dest, TAdapter>({\n      adapter,\n      seed,\n      resolvers: mapResolvers as ResolverRegistry<Dest, TAdapter>,\n      schemas: schemas as Record<keyof Dest, z.ZodType>,\n    });\n  }\n\n  const mapper: TypeMapper<S, R> = {\n    forward,\n    reverse,\n    forwardMany: (sources) => forwardManyOp(mapper, sources) as Array<Dest>,\n    reverseMany: (dtos) => reverseManyOp(mapper, dtos),\n    safeForward: (source) => safeForwardOp(mapper, source) as SafeResult<Dest>,\n    toSnakeCase,\n    toCamelCase,\n    toResolver,\n    schema,\n    rules: Object.freeze({ ...rules }) as R,\n    shape,\n    resolvers: mapResolvers,\n  };\n  return mapper;\n}\n\nexport type { FromResolver };\n","/**\n * `forwardAsync` — the async mapping path. Consumes a resolver graph (Phase 4)\n * for `fromResolver` fields, honors a dynamic `select` set so only requested\n * fields (and their resolver deps) do I/O, and validates with Zod\n * `safeParseAsync` (so async `.refine` runs).\n *\n * Zod 4 constraint: `.pick()`/`.partial()` THROW on object schemas containing\n * refinements, which is exactly the async-refined shape this targets. So a\n * partial `select` is validated against a sub-schema built from the RAW\n * `.shape` (`z.object(pickedShape)`), never by calling `.pick()` on the refined\n * wrapper. Field-level refines on selected fields still run; object-level\n * cross-field refines run only on a full select (documented limitation).\n */\nimport { z } from \"zod\";\nimport { applyForwardRule } from \"../map/createMap.js\";\nimport {\n  type FromResolver,\n  type Rule,\n  isFromResolverRule,\n  setPath,\n} from \"../map/rules.js\";\nimport type { ResolverContext } from \"../resolver/context.js\";\n\n/** Thrown when `select` names a key absent from the dest schema. */\nexport class UnknownSelectKeyError extends Error {\n  readonly keys: string[];\n  constructor(keys: string[]) {\n    super(\n      `forwardAsync select contains key(s) not in the dest schema: ${keys.join(\", \")}`,\n    );\n    this.name = \"UnknownSelectKeyError\";\n    this.keys = keys;\n  }\n}\n\ntype AnyZodObject = z.ZodObject<any>;\n\ninterface ForwardAsyncMap<S extends AnyZodObject> {\n  readonly schema: S;\n  readonly rules: Record<string, Rule | undefined>;\n  readonly shape: Record<string, z.ZodType>;\n}\n\nexport interface ForwardAsyncOptions<Fields, TAdapter> {\n  resolver: ResolverContext<Fields, TAdapter>;\n  /** Only these dest keys are computed; unselected resolvers never fire. */\n  select?: string[];\n  /** Opaque extra passed to sync function rules via the source (unused hook). */\n  context?: unknown;\n}\n\n/**\n * Validate and de-duplicate a `select` list against the dest shape.\n * Unknown keys -> typed {@link UnknownSelectKeyError} (never a raw Zod trace).\n */\nexport function normalizeSelect(\n  select: string[] | undefined,\n  shape: Record<string, z.ZodType>,\n): string[] | undefined {\n  if (select === undefined) return undefined;\n  const deduped = Array.from(new Set(select));\n  const unknown = deduped.filter(\n    (k) => !Object.prototype.hasOwnProperty.call(shape, k),\n  );\n  if (unknown.length > 0) throw new UnknownSelectKeyError(unknown);\n  return deduped;\n}\n\n/**\n * Strip a resolver-produced value through its own dest field sub-schema so\n * unknown adapter-row keys (e.g. `passwordHash`) are dropped. NOTE: a field\n * typed `z.any()`/`.passthrough()`/`z.record()` disables this — those leak the\n * value verbatim by design (documented in the README security section).\n */\nasync function stripField(value: unknown, fieldSchema: z.ZodType): Promise<unknown> {\n  const result = await fieldSchema.safeParseAsync(value);\n  if (!result.success) return value; // let the full validation surface the error\n  return result.data;\n}\n\n/**\n * Build a validated DTO asynchronously. `fromResolver` fields pull from the\n * resolver; a resolver throw rejects the whole promise (fail-fast). Returns the\n * full DTO, or a `Partial<Dto>` when `select` is given.\n */\nexport async function forwardAsync<S extends AnyZodObject, Fields, TAdapter>(\n  map: ForwardAsyncMap<S>,\n  source: Record<string, unknown>,\n  options: ForwardAsyncOptions<Fields, TAdapter>,\n): Promise<Partial<z.infer<S>>> {\n  const { resolver, select } = options;\n  const { schema, rules, shape } = map;\n\n  const selected = normalizeSelect(select, shape);\n  const targetKeys = selected ?? Object.keys(shape);\n\n  // Fields resolve sequentially (await per key). The resolver's promise-cache\n  // (Phase 4) makes Promise.all safe too, but sequential keeps resolver\n  // invocations non-overlapping and is the documented default.\n  const assembled: Record<string, unknown> = {};\n  for (const key of targetKeys) {\n    const rule = rules[key];\n    if (isFromResolverRule(rule as Rule)) {\n      const field = (rule as FromResolver).field;\n      // A resolver throw propagates out of forwardAsync (fail-fast).\n      const raw = await resolver.resolve(field as keyof Fields);\n      if (raw !== undefined) {\n        // `key` is always a key of `shape` (it came from shape keys or a\n        // select list validated against shape), so its field schema exists.\n        const value = await stripField(raw, shape[key] as z.ZodType);\n        setPath(assembled, key, value);\n      }\n      continue;\n    }\n    // Sync/computed rules reuse the Phase 3 primitive; an async function rule\n    // returns a promise, which we await.\n    const produced = applyForwardRule(rule, key, source);\n    const value = produced instanceof Promise ? await produced : produced;\n    if (value !== undefined) setPath(assembled, key, value);\n  }\n\n  // Validate. Full select -> the original schema (all refines run). Partial\n  // select -> a sub-schema built from raw .shape (avoids .pick on refined).\n  const validator =\n    selected === undefined ? schema : buildSubSchema(shape, selected);\n  const result = await validator.safeParseAsync(assembled);\n  if (!result.success) throw result.error;\n  return result.data as Partial<z.infer<S>>;\n}\n\n/**\n * Construct a partial-select validator from the dest schema's raw `.shape`,\n * via `z.object(pickedShape)`. Refined wrappers are never `.pick()`-ed (which\n * throws in Zod 4); object-level cross-field refines are intentionally omitted\n * here and run only on a full select.\n */\nfunction buildSubSchema(\n  shape: Record<string, z.ZodType>,\n  selected: string[],\n): z.ZodType {\n  const picked: Record<string, z.ZodType> = {};\n  for (const key of selected) {\n    // `selected` was validated against `shape` by normalizeSelect, so each\n    // key is present.\n    picked[key] = shape[key] as z.ZodType;\n  }\n  return z.object(picked);\n}\n"]}

package/dist/async/index.d.cts

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+import { R as Rule } from '../rules-msHkZDR8.cjs';
+import { R as ResolverContext } from '../context-B0f9mQWu.cjs';
+
+/**
+ * `forwardAsync` — the async mapping path. Consumes a resolver graph (Phase 4)
+ * for `fromResolver` fields, honors a dynamic `select` set so only requested
+ * fields (and their resolver deps) do I/O, and validates with Zod
+ * `safeParseAsync` (so async `.refine` runs).
+ *
+ * Zod 4 constraint: `.pick()`/`.partial()` THROW on object schemas containing
+ * refinements, which is exactly the async-refined shape this targets. So a
+ * partial `select` is validated against a sub-schema built from the RAW
+ * `.shape` (`z.object(pickedShape)`), never by calling `.pick()` on the refined
+ * wrapper. Field-level refines on selected fields still run; object-level
+ * cross-field refines run only on a full select (documented limitation).
+ */
+
+/** Thrown when `select` names a key absent from the dest schema. */
+declare class UnknownSelectKeyError extends Error {
+    readonly keys: string[];
+    constructor(keys: string[]);
+}
+type AnyZodObject = z.ZodObject<any>;
+interface ForwardAsyncMap<S extends AnyZodObject> {
+    readonly schema: S;
+    readonly rules: Record<string, Rule | undefined>;
+    readonly shape: Record<string, z.ZodType>;
+}
+interface ForwardAsyncOptions<Fields, TAdapter> {
+    resolver: ResolverContext<Fields, TAdapter>;
+    /** Only these dest keys are computed; unselected resolvers never fire. */
+    select?: string[];
+    /** Opaque extra passed to sync function rules via the source (unused hook). */
+    context?: unknown;
+}
+/**
+ * Validate and de-duplicate a `select` list against the dest shape.
+ * Unknown keys -> typed {@link UnknownSelectKeyError} (never a raw Zod trace).
+ */
+declare function normalizeSelect(select: string[] | undefined, shape: Record<string, z.ZodType>): string[] | undefined;
+/**
+ * Build a validated DTO asynchronously. `fromResolver` fields pull from the
+ * resolver; a resolver throw rejects the whole promise (fail-fast). Returns the
+ * full DTO, or a `Partial<Dto>` when `select` is given.
+ */
+declare function forwardAsync<S extends AnyZodObject, Fields, TAdapter>(map: ForwardAsyncMap<S>, source: Record<string, unknown>, options: ForwardAsyncOptions<Fields, TAdapter>): Promise<Partial<z.infer<S>>>;
+
+export { type ForwardAsyncOptions, UnknownSelectKeyError, forwardAsync, normalizeSelect };