decoders 2.8.0 → 2.9.0-pre.0

package/README.md

@@ -1,31 +1,22 @@
-<img alt="Decoders logo" src="./docs/assets/logo@2x.png" style="width: 100%; max-width: 830px; max-height: 248px" width="830" /><br />
+<img alt="Decoders logo" src="./assets/logo@2x.png" style="width: 100%; max-width: 830px; max-height: 248px" width="830" /><br />
 
 [![npm](https://img.shields.io/npm/v/decoders.svg)](https://www.npmjs.com/package/decoders)
 [![Test Status](https://github.com/nvie/decoders/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/nvie/decoders/actions)
 [![Bundle size for decoders](https://pkg-size.dev/badge/bundle/4200)](https://pkg-size.dev/decoders)
 
-Elegant and battle-tested validation library for type-safe input data for
-[TypeScript](https://www.typescriptlang.org/).
-
-## Introduction
-
-Data entering your application from the outside world should not be trusted without
-validation and often is of the `any` type, effectively disabling your type checker around
-input values. It's an industry good practice to validate your expectations right at your
-program's boundaries. This has two benefits: (1) your inputs are getting validated, and
-(2) you can now statically know for sure the shape of the incoming data. **Decoders help
-solve both of these problems at once.**
+Elegant and battle-tested validation library for type-safe input data for TypeScript.
 
 ## Basic example
 
 ```typescript
 import { array, iso8601, number, object, optional, string } from 'decoders';
 
-// Incoming data at runtime
+// Incoming data at runtime, e.g. the request body
+// The point is that this data is untrusted and its type unknown
 const externalData = {
   id: 123,
   name: 'Alison Roberts',
-  createdAt: '1994-01-11T12:26:37.024Z',
+  createdAt: '2026-01-11T12:26:37.024Z',
   tags: ['foo', 'bar'],
 };
 
@@ -40,7 +31,7 @@ const userDecoder = object({
 // Call .verify() on the incoming data
 const user = userDecoder.verify(externalData);
 //    ^^^^
-//    TypeScript automatically infers this type as:
+//    TypeScript will infer this type as:
 //    {
 //      id: number;
 //      name: string;
@@ -71,82 +62,7 @@ correctly!
 
 ## Documentation
 
-<div id="$DecoderType"></div>
-<div id="DecodeResult"></div>
-<div id="Decoder"></div>
-<div id="DecoderType"></div>
-<div id="Guard"></div>
-<div id="JSONArray"></div>
-<div id="JSONObject"></div>
-<div id="JSONValue"></div>
-<div id="Scalar"></div>
-<div id="adding-predicates"></div>
-<div id="always"></div>
-<div id="anyNumber"></div>
-<div id="array"></div>
-<div id="boolean"></div>
-<div id="building-custom-decoders"></div>
-<div id="compose"></div>
-<div id="compositions"></div>
-<div id="constant"></div>
-<div id="date"></div>
-<div id="define"></div>
-<div id="describe"></div>
-<div id="dict"></div>
-<div id="either"></div>
-<div id="email"></div>
-<div id="exact"></div>
-<div id="fail"></div>
-<div id="guard"></div>
-<div id="hardcoded"></div>
-<div id="httpsUrl"></div>
-<div id="inexact"></div>
-<div id="instanceOf"></div>
-<div id="integer"></div>
-<div id="iso8601"></div>
-<div id="json"></div>
-<div id="jsonArray"></div>
-<div id="jsonObject"></div>
-<div id="lazy"></div>
-<div id="mapping"></div>
-<div id="maybe"></div>
-<div id="mixed"></div>
-<div id="never"></div>
-<div id="nonEmptyArray"></div>
-<div id="nonEmptyString"></div>
-<div id="null_"></div>
-<div id="nullable"></div>
-<div id="number"></div>
-<div id="numericBoolean"></div>
-<div id="object"></div>
-<div id="oneOf"></div>
-<div id="optional"></div>
-<div id="poja"></div>
-<div id="pojo"></div>
-<div id="positiveInteger"></div>
-<div id="positiveNumber"></div>
-<div id="predicate"></div>
-<div id="prep"></div>
-<div id="primitives"></div>
-<div id="regex"></div>
-<div id="set"></div>
-<div id="string"></div>
-<div id="taggedUnion"></div>
-<div id="the-difference-between-object-exact-and-inexact"></div>
-<div id="transform"></div>
-<div id="transformation"></div>
-<div id="truthy"></div>
-<div id="tuple"></div>
-<div id="undefined_"></div>
-<div id="unknown"></div>
-<div id="url"></div>
-<div id="uuid"></div>
-<div id="uuidv1"></div>
-<div id="uuidv4"></div>
-
-Documentation can be found on [https://decoders.cc](https://decoders.cc).
-
-## Building your own decoders
+Documentation can be found on [decoders.cc](https://decoders.cc).
 
-There is a dedicated page in the docs that explains how to
-[build your own decoders](https://decoders.cc/building-your-own.html) — it’s fun!
+There is a dedicated page that explains how to
+[build your own decoders](https://decoders.cc/docs/building-your-own).

package/dist/index.cjs

@@ -21,7 +21,7 @@ function isPlainObject(value) {
 }
 
 // src/core/annotate.ts
-var kAnnotationRegistry = Symbol.for("decoders.kAnnotationRegistry");
+var kAnnotationRegistry = /* @__PURE__ */ Symbol.for("decoders.kAnnotationRegistry");
 var _register = globalThis[kAnnotationRegistry] ??= /* @__PURE__ */ new WeakSet();
 function brand(ann) {
   _register.add(ann);
@@ -57,7 +57,7 @@ function annotateArray(arr, text, seen) {
   seen.add(arr);
   const items = [];
   for (const value of arr) {
-    items.push(annotate(value, void 0, seen));
+    items.push(__annotate(value, void 0, seen));
   }
   return makeArrayAnn(items, text);
 }
@@ -66,11 +66,11 @@ function annotateObject(obj, text, seen) {
   const fields = /* @__PURE__ */ new Map();
   for (const key of Object.keys(obj)) {
     const value = obj[key];
-    fields.set(key, annotate(value, void 0, seen));
+    fields.set(key, __annotate(value, void 0, seen));
   }
   return makeObjectAnn(fields, text);
 }
-function annotate(value, text, seen) {
+function __annotate(value, text, seen) {
   if (value === null || value === void 0 || typeof value === "string" || typeof value === "number" || typeof value === "boolean" || typeof value === "symbol" || typeof value === "bigint" || typeof value.getMonth === "function") {
     return makeScalarAnn(value, text);
   }
@@ -104,7 +104,7 @@ function annotate(value, text, seen) {
   }
 }
 function public_annotate(value, text) {
-  return annotate(value, text, /* @__PURE__ */ new WeakSet());
+  return __annotate(value, text, /* @__PURE__ */ new WeakSet());
 }
 function public_annotateObject(obj, text) {
   return annotateObject(obj, text, /* @__PURE__ */ new WeakSet());
@@ -338,7 +338,7 @@ function define(fn) {
     return decode(blob).value;
   }
   function transform(transformFn) {
-    return then(noThrow(transformFn));
+    return chain(noThrow(transformFn));
   }
   function refine(predicateFn, errmsg) {
     return reject(
@@ -354,7 +354,7 @@ function define(fn) {
   function refineType() {
     return self;
   }
-  function then(next) {
+  function chain(next) {
     return define((blob, ok2, err2) => {
       const r1 = decode(blob);
       if (!r1.ok) return r1;
@@ -363,10 +363,10 @@ function define(fn) {
     });
   }
   function pipe(next) {
-    return then(next);
+    return chain(next);
   }
   function reject(rejectFn) {
-    return then((blob, ok2, err2) => {
+    return chain((blob, ok2, err2) => {
       const errmsg = rejectFn(blob);
       return errmsg === null ? ok2(blob) : err2(typeof errmsg === "string" ? public_annotate(blob, errmsg) : errmsg);
     });
@@ -390,7 +390,7 @@ function define(fn) {
     refineType,
     reject,
     describe,
-    then,
+    chain,
     pipe,
     "~standard": {
       version: 1,
@@ -409,7 +409,7 @@ function define(fn) {
   const self = brand2(unregistered);
   return self;
 }
-var kDecoderRegistry = Symbol.for("decoders.kDecoderRegistry");
+var kDecoderRegistry = /* @__PURE__ */ Symbol.for("decoders.kDecoderRegistry");
 var _register2 = globalThis[kDecoderRegistry] ??= /* @__PURE__ */ new WeakSet();
 function brand2(decoder) {
   _register2.add(decoder);
@@ -428,7 +428,7 @@ var poja = define((blob, ok2, err2) => {
 });
 function array(decoder) {
   const decodeFn = decoder.decode;
-  return poja.then((inputs, ok2, err2) => {
+  return poja.chain((inputs, ok2, err2) => {
     const results = [];
     for (let i = 0; i < inputs.length; ++i) {
       const blob = inputs[i];
@@ -458,7 +458,7 @@ function nonEmptyArray(decoder) {
 }
 var ntuple = (n) => poja.refine((arr) => arr.length === n, `Must be a ${n}-tuple`);
 function tuple(...decoders) {
-  return ntuple(decoders.length).then((blobs, ok2, err2) => {
+  return ntuple(decoders.length).chain((blobs, ok2, err2) => {
     let allOk = true;
     const rvs = decoders.map((decoder, i) => {
       const blob = blobs[i];
@@ -526,7 +526,7 @@ var pojo = define(
 );
 function object(decoders) {
   const knownKeys = new Set(Object.keys(decoders));
-  return pojo.then((plainObj, ok2, err2) => {
+  return pojo.chain((plainObj, ok2, err2) => {
     const actualKeys = new Set(Object.keys(plainObj));
     const missingKeys = difference(knownKeys, actualKeys);
     const record2 = {};
@@ -712,7 +712,7 @@ var truthy = define((blob, ok2, _) => ok2(!!blob));
 function record(fst, snd) {
   const keyDecoder = snd !== void 0 ? fst : void 0;
   const valueDecoder = _nullishCoalesce(snd, () => ( fst));
-  return pojo.then((input, ok2, err2) => {
+  return pojo.chain((input, ok2, err2) => {
     let rv = {};
     const errors = /* @__PURE__ */ new Map();
     for (const key of Object.keys(input)) {

package/dist/index.d.cts

@@ -160,7 +160,7 @@ interface Decoder<T> {
      * > be covered more elegantly by `.transform()`, `.refine()`, or `.pipe()`
      * > instead._
      */
-    then<V>(next: Next<V, T>): Decoder<V>;
+    chain<V>(next: Next<V, T>): Decoder<V>;
     /**
      * Send the output of this decoder as input to another decoder.
      *

package/dist/index.d.ts

@@ -160,7 +160,7 @@ interface Decoder<T> {
      * > be covered more elegantly by `.transform()`, `.refine()`, or `.pipe()`
      * > instead._
      */
-    then<V>(next: Next<V, T>): Decoder<V>;
+    chain<V>(next: Next<V, T>): Decoder<V>;
     /**
      * Send the output of this decoder as input to another decoder.
      *

package/dist/index.js

@@ -21,7 +21,7 @@ function isPlainObject(value) {
 }
 
 // src/core/annotate.ts
-var kAnnotationRegistry = Symbol.for("decoders.kAnnotationRegistry");
+var kAnnotationRegistry = /* @__PURE__ */ Symbol.for("decoders.kAnnotationRegistry");
 var _register = globalThis[kAnnotationRegistry] ??= /* @__PURE__ */ new WeakSet();
 function brand(ann) {
   _register.add(ann);
@@ -57,7 +57,7 @@ function annotateArray(arr, text, seen) {
   seen.add(arr);
   const items = [];
   for (const value of arr) {
-    items.push(annotate(value, void 0, seen));
+    items.push(__annotate(value, void 0, seen));
   }
   return makeArrayAnn(items, text);
 }
@@ -66,11 +66,11 @@ function annotateObject(obj, text, seen) {
   const fields = /* @__PURE__ */ new Map();
   for (const key of Object.keys(obj)) {
     const value = obj[key];
-    fields.set(key, annotate(value, void 0, seen));
+    fields.set(key, __annotate(value, void 0, seen));
   }
   return makeObjectAnn(fields, text);
 }
-function annotate(value, text, seen) {
+function __annotate(value, text, seen) {
   if (value === null || value === void 0 || typeof value === "string" || typeof value === "number" || typeof value === "boolean" || typeof value === "symbol" || typeof value === "bigint" || typeof value.getMonth === "function") {
     return makeScalarAnn(value, text);
   }
@@ -104,7 +104,7 @@ function annotate(value, text, seen) {
   }
 }
 function public_annotate(value, text) {
-  return annotate(value, text, /* @__PURE__ */ new WeakSet());
+  return __annotate(value, text, /* @__PURE__ */ new WeakSet());
 }
 function public_annotateObject(obj, text) {
   return annotateObject(obj, text, /* @__PURE__ */ new WeakSet());
@@ -338,7 +338,7 @@ function define(fn) {
     return decode(blob).value;
   }
   function transform(transformFn) {
-    return then(noThrow(transformFn));
+    return chain(noThrow(transformFn));
   }
   function refine(predicateFn, errmsg) {
     return reject(
@@ -354,7 +354,7 @@ function define(fn) {
   function refineType() {
     return self;
   }
-  function then(next) {
+  function chain(next) {
     return define((blob, ok2, err2) => {
       const r1 = decode(blob);
       if (!r1.ok) return r1;
@@ -363,10 +363,10 @@ function define(fn) {
     });
   }
   function pipe(next) {
-    return then(next);
+    return chain(next);
   }
   function reject(rejectFn) {
-    return then((blob, ok2, err2) => {
+    return chain((blob, ok2, err2) => {
       const errmsg = rejectFn(blob);
       return errmsg === null ? ok2(blob) : err2(typeof errmsg === "string" ? public_annotate(blob, errmsg) : errmsg);
     });
@@ -390,7 +390,7 @@ function define(fn) {
     refineType,
     reject,
     describe,
-    then,
+    chain,
     pipe,
     "~standard": {
       version: 1,
@@ -409,7 +409,7 @@ function define(fn) {
   const self = brand2(unregistered);
   return self;
 }
-var kDecoderRegistry = Symbol.for("decoders.kDecoderRegistry");
+var kDecoderRegistry = /* @__PURE__ */ Symbol.for("decoders.kDecoderRegistry");
 var _register2 = globalThis[kDecoderRegistry] ??= /* @__PURE__ */ new WeakSet();
 function brand2(decoder) {
   _register2.add(decoder);
@@ -428,7 +428,7 @@ var poja = define((blob, ok2, err2) => {
 });
 function array(decoder) {
   const decodeFn = decoder.decode;
-  return poja.then((inputs, ok2, err2) => {
+  return poja.chain((inputs, ok2, err2) => {
     const results = [];
     for (let i = 0; i < inputs.length; ++i) {
       const blob = inputs[i];
@@ -458,7 +458,7 @@ function nonEmptyArray(decoder) {
 }
 var ntuple = (n) => poja.refine((arr) => arr.length === n, `Must be a ${n}-tuple`);
 function tuple(...decoders) {
-  return ntuple(decoders.length).then((blobs, ok2, err2) => {
+  return ntuple(decoders.length).chain((blobs, ok2, err2) => {
     let allOk = true;
     const rvs = decoders.map((decoder, i) => {
       const blob = blobs[i];
@@ -526,7 +526,7 @@ var pojo = define(
 );
 function object(decoders) {
   const knownKeys = new Set(Object.keys(decoders));
-  return pojo.then((plainObj, ok2, err2) => {
+  return pojo.chain((plainObj, ok2, err2) => {
     const actualKeys = new Set(Object.keys(plainObj));
     const missingKeys = difference(knownKeys, actualKeys);
     const record2 = {};
@@ -712,7 +712,7 @@ var truthy = define((blob, ok2, _) => ok2(!!blob));
 function record(fst, snd) {
   const keyDecoder = snd !== void 0 ? fst : void 0;
   const valueDecoder = snd ?? fst;
-  return pojo.then((input, ok2, err2) => {
+  return pojo.chain((input, ok2, err2) => {
     let rv = {};
     const errors = /* @__PURE__ */ new Map();
     for (const key of Object.keys(input)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "decoders",
-  "version": "2.8.0",
+  "version": "2.9.0-pre.0",
   "description": "Elegant and battle-tested validation library for type-safe input data for TypeScript",
   "license": "MIT",
   "repository": {
@@ -34,19 +34,19 @@
     "README.md"
   ],
   "scripts": {
-    "actually-prepublish": "echo \"\\n\\nPlease run \\`bin/publish.sh <options>\\` instead.\\n\\n\" && exit 2",
     "build": "tsup",
-    "docs": "cog -cr docs/*.md",
-    "lint": "eslint --color --report-unused-disable-directives src/ test/ && prettier --list-different src/ test/ test-d/",
-    "lint:docs": "cog -c --check docs/*.md || (npm run docs; git diff; echo 'Error: docs not up-to-date, please re-run \"npm docs\" to update them.' && exit 1)",
+    "docs:dev": "cd docs && npm run dev",
+    "docs:build": "cd docs && npm run build",
+    "docs:update-sources": "node bin/update-source-lines.js",
+    "lint": "oxlint src/ test/ && prettier --list-different src/ test/ test-d/",
     "lint:package": "publint --strict && attw --pack",
-    "format": "eslint --color --report-unused-disable-directives --fix src/ test/ ; prettier --write src/ test/ test-d/",
+    "format": "oxlint --fix src/ test/ ; prettier --write src/ test/ test-d/",
     "test": "vitest run --coverage",
     "test:completeness": "./bin/check.sh",
     "test:typescript": "tsc --noEmit",
     "test:types": "npm run build && tsd --typings ./dist/index.d.ts",
     "test:watch": "vitest --coverage",
-    "release": "npm run test && npm run lint && npm run lint:docs && npm run build && npm run lint:package && release-it"
+    "release": "release-it"
   },
   "keywords": [
     "Decoder",
@@ -62,26 +62,22 @@
   ],
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.2",
-    "@eslint/js": "^9.35.0",
-    "@release-it/keep-a-changelog": "^7.0.0",
-    "@standard-schema/spec": "^1.0.0",
-    "@vitest/coverage-istanbul": "^3.2.4",
-    "eslint": "^9.35.0",
-    "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-simple-import-sort": "^12.1.1",
-    "fast-check": "^4.3.0",
-    "itertools": "^2.5.0",
-    "pkg-pr-new": "^0.0.60",
-    "prettier": "^3.6.2",
-    "publint": "^0.3.13",
-    "release-it": "^19.0.5",
-    "ts-morph": "^27.0.0",
+    "@release-it/keep-a-changelog": "^7.0.1",
+    "@standard-schema/spec": "^1.1.0",
+    "@vitest/coverage-istanbul": "^4.0.18",
+    "fast-check": "^4.5.3",
+    "itertools": "^2.6.0",
+    "oxlint": "^1.50.0",
+    "pkg-pr-new": "^0.0.65",
+    "prettier": "^3.8.1",
+    "publint": "^0.3.18",
+    "release-it": "^19.2.4",
+    "ts-morph": "^27.0.2",
     "tsd": "^0.33.0",
-    "tsup": "^8.5.0",
-    "typescript": "^5.9.2",
-    "typescript-eslint": "^8.44.0",
-    "vite-tsconfig-paths": "^5.1.4",
-    "vitest": "^3.2.4"
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vite-tsconfig-paths": "^6.1.1",
+    "vitest": "^4.0.18"
   },
   "githubUrl": "https://github.com/nvie/decoders",
   "sideEffects": false