decoders 2.10.1 → 2.12.0

package/dist/index.js

@@ -29,56 +29,87 @@ function isPlainObject(value) {
   // something is a pojo... ¯\_(ツ)_/¯
   Object.prototype.toString.call(value) === "[object Object]";
 }
+function assertNever(_value, msg = "Unhandled case") {
+  throw new Error(msg);
+}
 
 // src/core/annotate.ts
 var kAnnotationRegistry = /* @__PURE__ */ Symbol.for("decoders.kAnnotationRegistry");
-var _register = globalThis[kAnnotationRegistry] ??= /* @__PURE__ */ new WeakSet();
-function brand(ann) {
-  _register.add(ann);
+var _stamped = globalThis[kAnnotationRegistry] ??= /* @__PURE__ */ new WeakSet();
+function stamp(ann) {
+  _stamped.add(ann);
   return ann;
 }
-function makeObjectAnn(fields, text) {
-  return brand({ type: "object", fields, text });
+function makeObjectAnn(getFields, text) {
+  let fields;
+  return stamp({
+    type: "object",
+    get fields() {
+      return fields ??= getFields();
+    },
+    text
+  });
 }
-function makeArrayAnn(items, text) {
-  return brand({ type: "array", items, text });
+function makeArrayAnn(getItems, text) {
+  let items;
+  return stamp({
+    type: "array",
+    get items() {
+      return items ??= getItems();
+    },
+    text
+  });
 }
 function makeOpaqueAnn(value, text) {
-  return brand({ type: "opaque", value, text });
+  return stamp({ type: "opaque", value, text });
 }
 function makeScalarAnn(value, text) {
-  return brand({ type: "scalar", value, text });
+  return stamp({ type: "scalar", value, text });
 }
 function updateText(annotation, text) {
-  if (text !== void 0) {
-    return brand({ ...annotation, text });
-  } else {
+  if (text === void 0) {
     return annotation;
   }
+  switch (annotation.type) {
+    case "object":
+      return makeObjectAnn(() => annotation.fields, text);
+    case "array":
+      return makeArrayAnn(() => annotation.items, text);
+    case "scalar":
+      return makeScalarAnn(annotation.value, text);
+    case "opaque":
+      return makeOpaqueAnn(annotation.value, text);
+    // istanbul ignore next -- @preserve
+    default:
+      return assertNever(annotation, "Unknown annotation type");
+  }
 }
 function merge(objAnnotation, fields) {
-  const newFields = new Map([...objAnnotation.fields, ...fields]);
-  return makeObjectAnn(newFields, objAnnotation.text);
+  return makeObjectAnn(
+    () => new Map([...objAnnotation.fields, ...fields]),
+    objAnnotation.text
+  );
 }
 function isAnnotation(thing) {
-  return _register.has(thing);
+  return _stamped.has(thing);
 }
 function annotateArray(arr, text, seen) {
   seen.add(arr);
-  const items = [];
-  for (const value of arr) {
-    items.push(__annotate(value, void 0, seen));
-  }
-  return makeArrayAnn(items, text);
+  return makeArrayAnn(
+    () => Array.from(arr, (value) => __annotate(value, void 0, seen)),
+    text
+  );
 }
 function annotateObject(obj, text, seen) {
   seen.add(obj);
-  const fields = /* @__PURE__ */ new Map();
-  for (const key of Object.keys(obj)) {
-    const value = obj[key];
-    fields.set(key, __annotate(value, void 0, seen));
-  }
-  return makeObjectAnn(fields, text);
+  return makeObjectAnn(() => {
+    const fields = /* @__PURE__ */ new Map();
+    for (const key of Object.keys(obj)) {
+      const value = obj[key];
+      fields.set(key, __annotate(value, void 0, seen));
+    }
+    return fields;
+  }, text);
 }
 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") {
@@ -299,6 +330,9 @@ function* iterAnnotation(ann, stack) {
     case "opaque": {
       break;
     }
+    // istanbul ignore next -- @preserve
+    default:
+      assertNever(ann, "Unknown annotation type");
   }
 }
 function formatAsIssues(ann) {
@@ -337,29 +371,60 @@ ${formatted}`);
     return formatted;
   }
 }
-// @__NO_SIDE_EFFECTS__
-function define(fn) {
-  function decode(blob) {
-    const makeFlexErr = (msg) => err(isAnnotation(msg) ? msg : public_annotate(blob, msg));
-    return fn(blob, ok, makeFlexErr);
-  }
-  function verify(blob, formatter = formatInline) {
-    const result = decode(blob);
-    if (result.ok) {
-      return result.value;
-    } else {
-      throw format(result.error, formatter);
-    }
-  }
-  function value(blob) {
-    return decode(blob).value;
+var _standard = /* @__PURE__ */ new WeakMap();
+var DecoderImpl = class {
+  /**
+   * Verifies the untrusted/unknown input and either accepts or rejects it.
+   *
+   * Contrasted with `.verify()`, calls to `.decode()` will never fail and
+   * instead return a result type.
+   */
+  decode;
+  /**
+   * Verifies the untrusted/unknown input and either accepts or rejects it.
+   * When accepted, returns a value of type `T`. Otherwise fail with
+   * a runtime error.
+   */
+  verify;
+  /**
+   * Verifies the untrusted/unknown input and either accepts or rejects it.
+   * When accepted, returns the decoded `T` value directly. Otherwise returns
+   * `undefined`.
+   *
+   * Use this when you're not interested in programmatically handling the
+   * error message.
+   */
+  value;
+  constructor(fn) {
+    const decode = (blob) => {
+      const makeFlexErr = (msg) => err(isAnnotation(msg) ? msg : public_annotate(blob, msg));
+      return fn(blob, ok, makeFlexErr);
+    };
+    const verify = (blob, formatter = formatInline) => {
+      const result = decode(blob);
+      if (result.ok) {
+        return result.value;
+      } else {
+        throw format(result.error, formatter);
+      }
+    };
+    const value = (blob) => decode(blob).value;
+    this.decode = decode;
+    this.verify = verify;
+    this.value = value;
   }
-  function transform(transformFn) {
-    return chain(noThrow(transformFn));
+  /**
+   * Accepts any value the given decoder accepts, and on success, will call
+   * the given function **on the decoded result**. If the transformation
+   * function throws an error, the whole decoder will fail using the error
+   * message as the failure reason.
+   */
+  transform(transformFn) {
+    return this.chain(noThrow(transformFn));
   }
-  function refine(predicateFn, errmsg) {
-    return reject(
-      (value2) => predicateFn(value2) ? (
+  refine(predicateFn, errmsg) {
+    return this.reject(
+      (value) => predicateFn(value) ? (
         // Don't reject
         null
       ) : (
@@ -368,10 +433,25 @@ function define(fn) {
       )
     );
   }
-  function refineType() {
-    return self;
+  /**
+   * Cast the return type of this read-only decoder to a narrower type. This is
+   * useful to return "branded" types. This method has no runtime effect.
+   */
+  refineType() {
+    return this;
   }
-  function chain(next) {
+  /**
+   * Send the output of the current decoder into another decoder or acceptance
+   * function. The given acceptance function will receive the output of the
+   * current decoder as its input.
+   *
+   * > _**NOTE:** This is an advanced, low-level, API. It's not recommended
+   * > to reach for this construct unless there is no other way. Most cases can
+   * > be covered more elegantly by `.transform()`, `.refine()`, or `.pipe()`
+   * > instead._
+   */
+  chain(next) {
+    const decode = this.decode;
     return /* @__PURE__ */ define((blob, ok2, err2) => {
       const r1 = decode(blob);
       if (!r1.ok) return r1;
@@ -379,16 +459,46 @@ function define(fn) {
       return /* @__PURE__ */ isDecoder(r2) ? r2.decode(r1.value) : r2;
     });
   }
-  function pipe(next) {
-    return chain(next);
+  /**
+   * Send the output of this decoder as input to another decoder.
+   *
+   * This can be useful to validate the results of a transform, i.e.:
+   *
+   *   string
+   *     .transform((s) => s.split(','))
+   *     .pipe(array(nonEmptyString))
+   *
+   * You can also conditionally pipe:
+   *
+   *   string.pipe((s) => s.startsWith('@') ? username : email)
+   */
+  pipe(next) {
+    return this.chain(next);
   }
-  function reject(rejectFn) {
-    return chain((blob, ok2, err2) => {
+  /**
+   * Adds an extra predicate to a decoder. The new decoder is like the
+   * original decoder, but only accepts values that aren't rejected by the
+   * given function.
+   *
+   * The given function can return `null` to accept the decoded value, or
+   * return a specific error message to reject.
+   *
+   * Unlike `.refine()`, you can use this function to return a dynamic error
+   * message.
+   */
+  reject(rejectFn) {
+    return this.chain((blob, ok2, err2) => {
       const errmsg = rejectFn(blob);
       return errmsg === null ? ok2(blob) : err2(typeof errmsg === "string" ? public_annotate(blob, errmsg) : errmsg);
     });
   }
-  function describe(message) {
+  /**
+   * Uses the given decoder, but will use an alternative error message in
+   * case it rejects. This can be used to simplify or shorten otherwise
+   * long or low-level/technical errors.
+   */
+  describe(message) {
+    const decode = this.decode;
     return /* @__PURE__ */ define((blob, _, err2) => {
       const result = decode(blob);
       if (result.ok) {
@@ -398,18 +508,14 @@ function define(fn) {
       }
     });
   }
-  const unregistered = {
-    verify,
-    value,
-    decode,
-    transform,
-    refine,
-    refineType,
-    reject,
-    describe,
-    chain,
-    pipe,
-    "~standard": {
+  /**
+   * The Standard Schema interface for this decoder.
+   */
+  get "~standard"() {
+    const memo = _standard.get(this);
+    if (memo !== void 0) return memo;
+    const decode = this.decode;
+    const props = {
       version: 1,
       vendor: "decoders",
       validate: (blob) => {
@@ -421,82 +527,26 @@ function define(fn) {
           return { issues };
         }
       }
-    }
-  };
-  const self = brand2(unregistered);
-  return self;
+    };
+    _standard.set(this, props);
+    return props;
+  }
+};
+Object.defineProperty(DecoderImpl, "name", { value: "Decoder" });
+// @__NO_SIDE_EFFECTS__
+function define(fn) {
+  const decoder = new DecoderImpl(fn);
+  return stamp2(decoder);
 }
 var kDecoderRegistry = /* @__PURE__ */ Symbol.for("decoders.kDecoderRegistry");
-var _register2 = globalThis[kDecoderRegistry] ??= /* @__PURE__ */ new WeakSet();
-function brand2(decoder) {
-  _register2.add(decoder);
+var _stamped2 = globalThis[kDecoderRegistry] ??= /* @__PURE__ */ new WeakSet();
+function stamp2(decoder) {
+  _stamped2.add(decoder);
   return decoder;
 }
 // @__NO_SIDE_EFFECTS__
 function isDecoder(value) {
-  return _register2.has(value);
-}
-
-// src/arrays.ts
-var poja = define((blob, ok2, err2) => {
-  if (!Array.isArray(blob)) {
-    return err2("Must be an array");
-  }
-  return ok2(blob);
-});
-// @__NO_SIDE_EFFECTS__
-function array(decoder) {
-  const decodeFn = decoder.decode;
-  return poja.chain((inputs, ok2, err2) => {
-    const results = [];
-    for (let i = 0; i < inputs.length; ++i) {
-      const blob = inputs[i];
-      const result = decodeFn(blob);
-      if (result.ok) {
-        results.push(result.value);
-      } else {
-        results.length = 0;
-        const ann = result.error;
-        const clone = inputs.slice();
-        clone.splice(
-          i,
-          1,
-          public_annotate(ann, ann.text ? `${ann.text} (at index ${i})` : `index ${i}`)
-        );
-        return err2(public_annotate(clone));
-      }
-    }
-    return ok2(results);
-  });
-}
-function isNonEmpty(arr) {
-  return arr.length > 0;
-}
-// @__NO_SIDE_EFFECTS__
-function nonEmptyArray(decoder) {
-  return (/* @__PURE__ */ array(decoder)).refine(isNonEmpty, "Must have at least 1 item");
-}
-var ntuple = /* @__NO_SIDE_EFFECTS__ */ (n) => poja.refine((arr) => arr.length === n, `Must be a ${n}-tuple`);
-// @__NO_SIDE_EFFECTS__
-function tuple(...decoders) {
-  return (/* @__PURE__ */ ntuple(decoders.length)).chain((blobs, ok2, err2) => {
-    let allOk = true;
-    const rvs = decoders.map((decoder, i) => {
-      const blob = blobs[i];
-      const result = decoder.decode(blob);
-      if (result.ok) {
-        return result.value;
-      } else {
-        allOk = false;
-        return result.error;
-      }
-    });
-    if (allOk) {
-      return ok2(rvs);
-    } else {
-      return err2(public_annotate(rvs));
-    }
-  });
+  return _stamped2.has(value);
 }
 
 // src/lib/size-options.ts
@@ -561,6 +611,66 @@ function prep(mapperFn, decoder) {
   });
 }
 
+// src/arrays.ts
+var poja = define((blob, ok2, err2) => {
+  if (!Array.isArray(blob)) {
+    return err2("Must be an array");
+  }
+  return ok2(blob);
+});
+// @__NO_SIDE_EFFECTS__
+function array(decoder, options) {
+  const decodeFn = decoder.decode;
+  const base = options !== void 0 ? sized(poja, options) : poja;
+  return base.chain((inputs, ok2, err2) => {
+    const results = [];
+    for (let i = 0; i < inputs.length; ++i) {
+      const blob = inputs[i];
+      const result = decodeFn(blob);
+      if (result.ok) {
+        results.push(result.value);
+      } else {
+        results.length = 0;
+        const ann = result.error;
+        const clone = inputs.slice();
+        clone.splice(
+          i,
+          1,
+          public_annotate(ann, ann.text ? `${ann.text} (at index ${i})` : `index ${i}`)
+        );
+        return err2(public_annotate(clone));
+      }
+    }
+    return ok2(results);
+  });
+}
+// @__NO_SIDE_EFFECTS__
+function nonEmptyArray(decoder) {
+  return (/* @__PURE__ */ array(decoder, { min: 1 })).refineType();
+}
+var ntuple = /* @__NO_SIDE_EFFECTS__ */ (n) => poja.refine((arr) => arr.length === n, `Must be a ${n}-tuple`);
+// @__NO_SIDE_EFFECTS__
+function tuple(...decoders) {
+  return (/* @__PURE__ */ ntuple(decoders.length)).chain((blobs, ok2, err2) => {
+    let allOk = true;
+    const rvs = decoders.map((decoder, i) => {
+      const blob = blobs[i];
+      const result = decoder.decode(blob);
+      if (result.ok) {
+        return result.value;
+      } else {
+        allOk = false;
+        return result.error;
+      }
+    });
+    if (allOk) {
+      return ok2(rvs);
+    } else {
+      return err2(public_annotate(rvs));
+    }
+  });
+}
+
 // src/lib/set-methods.ts
 // @__NO_SIDE_EFFECTS__
 function difference(xs, ys) {
@@ -955,14 +1065,16 @@ var integer = /* @__PURE__ */ number.refine(
   (n) => Number.isInteger(n),
   "Number must be an integer"
 );
-var positiveNumber = /* @__PURE__ */ number.refine(
+var nonNegativeNumber = /* @__PURE__ */ number.refine(
   (n) => n >= 0 && !Object.is(n, -0),
   "Number must be positive"
 );
-var positiveInteger = /* @__PURE__ */ integer.refine(
+var natural = /* @__PURE__ */ integer.refine(
   (n) => n >= 0 && !Object.is(n, -0),
   "Number must be positive"
 );
+var positiveNumber = nonNegativeNumber;
+var positiveInteger = natural;
 // @__NO_SIDE_EFFECTS__
 function min(min2, decoder = number) {
   return decoder.reject(
@@ -1042,9 +1154,11 @@ export {
   max,
   min,
   nanoid,
+  natural,
   never,
   nonEmptyArray,
   nonEmptyString,
+  nonNegativeNumber,
   null_,
   nullable,
   nullish,
@@ -1077,4 +1191,5 @@ export {
   uuidv1,
   uuidv4
 };
+// istanbul ignore next -- @preserve
 // istanbul ignore else -- @preserve

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "decoders",
-  "version": "2.10.1",
+  "version": "2.12.0",
   "description": "Elegant and battle-tested validation library for type-safe input data for TypeScript",
   "license": "MIT",
   "repository": {
@@ -35,17 +35,17 @@
   ],
   "scripts": {
     "build": "tsup",
-    "docs": "npm run build && cp -r dist/ docs/decoders-latest-snapshot/ && cd docs && rm -rf .next && npm run dev",
+    "docs": "pnpm run build && cp -r dist/ docs/decoders-latest-snapshot/ && cd docs && rm -rf .next && pnpm run dev",
     "docs:update-sources": "node bin/update-source-lines.js",
     "docs:update-redirects": "node bin/update-decoder-redirects.js",
     "lint": "oxlint src/ test/ && prettier --list-different src/ test/ test-d/ && node bin/lint-side-effects.js",
     "lint:package": "publint --strict && attw --pack",
-    "format": "oxlint --fix src/ test/ ; prettier --write src/ test/ test-d/ docs/content/ ; npm run docs:update-sources ; npm run docs:update-redirects",
+    "format": "oxlint --fix src/ test/ ; prettier --write src/ test/ test-d/ docs/content/ ; pnpm run docs:update-sources ; pnpm run docs:update-redirects",
     "test": "vitest run --coverage",
-    "test:treeshake": "npm run build && node bin/test-treeshake.js",
+    "test:treeshake": "pnpm run build && node bin/test-treeshake.js",
     "test:completeness": "./bin/check.sh",
     "test:typescript": "tsc --noEmit",
-    "test:types": "npm run build && tsd --typings ./dist/index.d.ts",
+    "test:types": "pnpm run build && tsd --typings ./dist/index.d.ts",
     "test:watch": "vitest --coverage",
     "release": "release-it"
   },
@@ -66,11 +66,11 @@
     "@release-it/keep-a-changelog": "^8.0.1",
     "@standard-schema/spec": "^1.1.0",
     "@vitest/coverage-istanbul": "^4.1.11",
-    "fast-check": "^4.10.0",
+    "fast-check": "^4.10.2",
     "itertools": "^2.7.1",
     "oxlint": "^1.83.0",
     "pkg-pr-new": "^0.0.88",
-    "prettier": "^3.9.6",
+    "prettier": "^3.9.9",
     "publint": "^0.3.24",
     "release-it": "^21.0.3",
     "ts-morph": "^28.0.0",
@@ -80,5 +80,6 @@
     "vitest": "^4.1.11"
   },
   "githubUrl": "https://github.com/nvie/decoders",
-  "sideEffects": false
+  "sideEffects": false,
+  "packageManager": "pnpm@11.24.0"
 }