bimorph 0.0.1 → 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleksandr Zhuravlov
+
+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

@@ -1,57 +1,87 @@
 # bimorph
 
-A TypeScript library for **bidirectional data mapping**. Define a mapping **once**,
-get both directions for free:
+[![npm](https://img.shields.io/npm/v/bimorph)](https://www.npmjs.com/package/bimorph)
+[![license: MIT](https://img.shields.io/npm/l/bimorph)](LICENSE)
 
-- `decode` — external representation → domain value
-- `encode` — domain value → external representation
+**Bidirectional data mapping for TypeScript.** Define a mapping once and get both
+directions — `decode` (wire → domain) and `encode` (domain → wire) — with the reverses
+that *don't* invert cleanly surfaced in the type instead of failing silently.
 
-The interesting part is not the happy path (a `Record` already does that). It's
-that **most real mappings do not invert cleanly** — duplicate values, lossy
-transforms, missing keys, read-only fields, and reverses that need runtime context
-the value doesn't carry. bimorph's thesis: *embrace that reality, surface it early,
-and give the caller explicit, legible escape hatches* — rather than pretend every
-mapping is a clean isomorphism.
+```ts
+import { Enum } from 'bimorph';
 
-## Status
+const Status = Enum([
+    [1, 'active'],
+    [0, 'inactive'],
+]);
 
-Design phase + a **typechecked prototype** proving the load-bearing type machinery.
+Status.decode(1); // 'active'   — wire → domain
+Status.encode('active'); // 1   — domain → wire
+```
 
-Docs:
+One declaration, both directions — no hand-written reverse lookup drifting out of sync.
 
-- [`apps/docs/`](apps/docs) — the full documentation site (Fumadocs + Next.js App
-  Router). Every `ts twoslash` example is type-checked against `src/index.ts` at
-  build time. Run it with `npm run docs`, then open http://localhost:3411.
-- [`docs/DESIGN.md`](docs/DESIGN.md) — principles, contracts, and the API surface.
-- [`docs/SCENARIOS.md`](docs/SCENARIOS.md) — ~28 real-world scenarios gathered to test the design against.
-- [`docs/DOGFOOD.md`](docs/DOGFOOD.md) — the design written against those scenarios, and the gaps it exposed.
+## The problem it kills
+
+The happy path is easy; a lookup object already does that. The pain is the *reverse*:
+
+```ts
+const STATUSES = { 0: 'BAD', 1: 'OK' };
+const label = STATUSES[0]; // easy
+const value = Object.entries(STATUSES).find(([, v]) => v === 'OK')?.[0]; // ugh — and it drifts
+```
+
+And most real mappings *don't* invert cleanly: duplicate values, lossy transforms,
+missing keys, read-only fields, reverses that need runtime context the value doesn't
+carry. Most tools ignore that or hide it. bimorph's thesis: **surface non-invertibility
+in the type, and give explicit escape hatches** — instead of pretending every mapping is
+a clean isomorphism.
+
+That shows up as:
 
-Prototype:
+- **Fidelity tiers** — `iso` (exact round-trip), `lossy` (no round-trip promised),
+  `partial` (the inverse can fail). A `partial` codec doesn't even offer a throwing
+  `decode`; the type forces you through `safeDecode`.
+- **Doors, not flags** — `decode` throws with a path, `safeDecode` returns a `Result`,
+  `decodeOr` falls back, `validate` accumulates every error. The behavior is visible at
+  the call site, never a hidden config flag.
+- **Aliases** — several wire values decode to one domain value, but `encode` only ever
+  emits the canonical one (narrowed in the type), so a migration can't leak a legacy
+  spelling.
+- **Context** — a codec that needs a `region` or `locale` says so in its type; you can't
+  silently forget to pass it.
 
-- [`src/index.ts`](src/index.ts) — minimal runtime, but the **real** types: `iso` / `lossy` /
-  `partial` / `Enum` (with aliases) / `Struct` / `Field` / `bind`.
+## Install
 
 ```bash
-npm install
-npm run typecheck        # tsc --noEmit over src/
-npm run check:runtime    # runtime-behaviour regression gate over src/
-npm run docs             # run the documentation site (apps/docs) at http://localhost:3411
+npm install bimorph
 ```
 
-What the prototype proves compiles (see the MDX for the assertions):
+> **Early release — expect breaking changes before 1.0.** The API has just stabilized,
+> but the package currently ships TypeScript source (`src/index.ts`): it works in a
+> TypeScript project with a bundler, and a compiled `dist/` (`.js` + `.d.ts`) for plain
+> Node/JS is on the way. Pin the version.
 
-1. **Alias narrowing** — `Enum` decode accepts the *wide* union (primaries + aliases),
-   `encode` returns the *narrow* canonical-only union. A migration cannot emit a legacy spelling.
-2. **Contextual codecs** — a `Ctx` third param whose trailing argument is required
-   (`decode(b)` without it is a type error), `.bind(ctx)` erases it back to a plain codec,
-   and `Struct` **intersects** the contexts of its fields into one merged bag.
-3. **`Partial` removes the throwing decode door** at the type level — you're forced to `safeDecode`.
+## Documentation
 
-## The one-line motivation
+The full documentation site — Fumadocs, with every `ts twoslash` example type-checked
+against the real types at build time — lives in [`apps/docs/`](apps/docs). Run it with
+`npm run docs` and open http://localhost:3411.
 
-```ts
-// The problem this exists to kill:
-const STATUSES = { 0: "BAD", 1: "OK" };
-const label = STATUSES[0];                                 // easy
-const value = Object.entries(STATUSES).find(([, v]) => v === "OK")?.[0]; // ugh
+Design record:
+
+- [`docs/DESIGN.md`](docs/DESIGN.md) — principles, the codec contract, and the API surface.
+- [`docs/SCENARIOS.md`](docs/SCENARIOS.md) — ~28 real-world mappings the design was tested against.
+- [`docs/DOGFOOD.md`](docs/DOGFOOD.md) — the design written against those scenarios, and the gaps it exposed.
+
+## Development
+
+```bash
+npm run typecheck     # tsc --noEmit over src/
+npm run check:runtime # runtime-behaviour regression gate
+npm run docs          # the documentation site at http://localhost:3411
 ```
+
+## License
+
+[MIT](LICENSE) © 2026 Oleksandr Zhuravlov

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "bimorph",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "type": "module",
+  "license": "MIT",
   "description": "Bidirectional data mapping for TypeScript — define a mapping once, get decode and encode, with non-invertibility surfaced in the type.",
   "exports": {
     ".": "./src/index.ts"