decoders 2.6.1 → 2.7.1

package/README.md

@@ -1,7 +1,7 @@
 <img alt="Decoders logo" src="./docs/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)
-[![Build Status](https://github.com/nvie/decoders/workflows/test/badge.svg)](https://github.com/nvie/decoders/actions)
+[![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

package/dist/index.cjs

@@ -114,7 +114,7 @@ function indent(s, prefix = INDENT) {
 }
 var quotePattern = /'/g;
 function quote(value) {
-  return typeof value === "string" ? "'" + value.replace(quotePattern, "\\'") + "'" : JSON.stringify(value);
+  return typeof value === "string" ? "'" + value.replace(quotePattern, "\\'") + "'" : value === void 0 ? "undefined" : JSON.stringify(value);
 }
 
 // src/core/format.ts
@@ -311,11 +311,8 @@ ${formatted}`);
 }
 function define(fn) {
   function decode(blob) {
-    return fn(
-      blob,
-      ok,
-      (msg) => err(isAnnotation(msg) ? msg : public_annotate(blob, msg))
-    );
+    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);
@@ -342,6 +339,9 @@ function define(fn) {
       )
     );
   }
+  function refineType() {
+    return self;
+  }
   function then(next) {
     return define((blob, ok2, err2) => {
       const r1 = decode(blob);
@@ -369,12 +369,13 @@ function define(fn) {
       }
     });
   }
-  return brand2({
+  const unregistered = {
     verify,
     value,
     decode,
     transform,
     refine,
+    refineType,
     reject,
     describe,
     then,
@@ -392,7 +393,9 @@ function define(fn) {
         }
       }
     }
-  });
+  };
+  const self = brand2(unregistered);
+  return self;
 }
 var kDecoderRegistry = Symbol.for("decoders.kDecoderRegistry");
 var _register2 = globalThis[kDecoderRegistry] ??= /* @__PURE__ */ new WeakSet();
@@ -411,30 +414,28 @@ var poja = define((blob, ok2, err2) => {
   }
   return ok2(blob);
 });
-function all(items, blobs, ok2, err2) {
-  const results = [];
-  for (let index = 0; index < items.length; ++index) {
-    const result = items[index];
-    if (result.ok) {
-      results.push(result.value);
-    } else {
-      const ann = result.error;
-      const clone = blobs.slice();
-      clone.splice(
-        index,
-        1,
-        public_annotate(ann, ann.text ? `${ann.text} (at index ${index})` : `index ${index}`)
-      );
-      return err2(public_annotate(clone));
-    }
-  }
-  return ok2(results);
-}
 function array(decoder) {
   const decodeFn = decoder.decode;
-  return poja.then((blobs, ok2, err2) => {
-    const results = blobs.map(decodeFn);
-    return all(results, blobs, ok2, err2);
+  return poja.then((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) {
@@ -533,9 +534,7 @@ function object(decoders) {
         if (rawValue === void 0) {
           missingKeys.add(key);
         } else {
-          if (errors === null) {
-            errors = /* @__PURE__ */ new Map();
-          }
+          errors ??= /* @__PURE__ */ new Map();
           errors.set(key, ann);
         }
       }
@@ -614,9 +613,9 @@ function either(...decoders) {
 }
 function oneOf(constants) {
   return define((blob, ok2, err2) => {
-    const winner = constants.find((c) => c === blob);
-    if (winner !== void 0) {
-      return ok2(winner);
+    const index = constants.indexOf(blob);
+    if (index !== -1) {
+      return ok2(constants[index]);
     }
     return err2(`Must be one of ${constants.map((value) => quote(value)).join(", ")}`);
   });
@@ -820,19 +819,14 @@ var iso8601_re = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:[.]\d+)?(?:Z|[+-]\d{2}:
 var date = define((blob, ok2, err2) => {
   return isDate(blob) ? ok2(blob) : err2("Must be a Date");
 });
-var iso8601 = (
-  // Input itself needs to match the ISO8601 regex...
-  regex(iso8601_re, "Must be ISO8601 format").transform(
-    // Make sure it is a _valid_ date
-    (value) => {
-      const date2 = new Date(value);
-      if (isNaN(date2.getTime())) {
-        throw new Error("Must be valid date/time value");
-      }
-      return date2;
-    }
-  )
+var dateString = regex(
+  iso8601_re,
+  "Must be ISO8601 format"
+).refine(
+  (value) => !isNaN(new Date(value).getTime()),
+  "Must be valid date/time value"
 );
+var iso8601 = dateString.transform((value) => new Date(value));
 var datelike = either(date, iso8601).describe("Must be a Date or date string");
 
 // src/numbers.ts
@@ -940,4 +934,5 @@ var json = either(
 
 
 
-exports.always = always; exports.anyNumber = anyNumber; exports.array = array; exports.bigint = bigint; exports.boolean = boolean; exports.constant = constant; exports.date = date; exports.datelike = datelike; exports.decimal = decimal; exports.define = define; exports.dict = dict; exports.either = either; exports.email = email; exports.endsWith = endsWith; exports.enum_ = enum_; exports.err = err; exports.exact = exact; exports.fail = fail; exports.formatInline = formatInline; exports.formatShort = formatShort; exports.hardcoded = hardcoded; exports.hexadecimal = hexadecimal; exports.httpsUrl = httpsUrl; exports.identifier = identifier; exports.inexact = inexact; exports.instanceOf = instanceOf; exports.integer = integer; exports.iso8601 = iso8601; exports.json = json; exports.jsonArray = jsonArray; exports.jsonObject = jsonObject; exports.lazy = lazy; exports.mapping = mapping; exports.maybe = maybe; exports.mixed = mixed; exports.nanoid = nanoid; exports.never = never; exports.nonEmptyArray = nonEmptyArray; exports.nonEmptyString = nonEmptyString; exports.null_ = null_; exports.nullable = nullable; exports.nullish = nullish; exports.number = number; exports.numeric = numeric; exports.object = object; exports.ok = ok; exports.oneOf = oneOf; exports.optional = optional; exports.poja = poja; exports.pojo = pojo; exports.positiveInteger = positiveInteger; exports.positiveNumber = positiveNumber; exports.prep = prep; exports.record = record; exports.regex = regex; exports.select = select; exports.set = set; exports.setFromArray = setFromArray; exports.startsWith = startsWith; exports.string = string; exports.taggedUnion = taggedUnion; exports.truthy = truthy; exports.tuple = tuple; exports.undefined_ = undefined_; exports.unknown = unknown; exports.url = url; exports.uuid = uuid; exports.uuidv1 = uuidv1; exports.uuidv4 = uuidv4;
+
+exports.always = always; exports.anyNumber = anyNumber; exports.array = array; exports.bigint = bigint; exports.boolean = boolean; exports.constant = constant; exports.date = date; exports.dateString = dateString; exports.datelike = datelike; exports.decimal = decimal; exports.define = define; exports.dict = dict; exports.either = either; exports.email = email; exports.endsWith = endsWith; exports.enum_ = enum_; exports.err = err; exports.exact = exact; exports.fail = fail; exports.formatInline = formatInline; exports.formatShort = formatShort; exports.hardcoded = hardcoded; exports.hexadecimal = hexadecimal; exports.httpsUrl = httpsUrl; exports.identifier = identifier; exports.inexact = inexact; exports.instanceOf = instanceOf; exports.integer = integer; exports.iso8601 = iso8601; exports.json = json; exports.jsonArray = jsonArray; exports.jsonObject = jsonObject; exports.lazy = lazy; exports.mapping = mapping; exports.maybe = maybe; exports.mixed = mixed; exports.nanoid = nanoid; exports.never = never; exports.nonEmptyArray = nonEmptyArray; exports.nonEmptyString = nonEmptyString; exports.null_ = null_; exports.nullable = nullable; exports.nullish = nullish; exports.number = number; exports.numeric = numeric; exports.object = object; exports.ok = ok; exports.oneOf = oneOf; exports.optional = optional; exports.poja = poja; exports.pojo = pojo; exports.positiveInteger = positiveInteger; exports.positiveNumber = positiveNumber; exports.prep = prep; exports.record = record; exports.regex = regex; exports.select = select; exports.set = set; exports.setFromArray = setFromArray; exports.startsWith = startsWith; exports.string = string; exports.taggedUnion = taggedUnion; exports.truthy = truthy; exports.tuple = tuple; exports.undefined_ = undefined_; exports.unknown = unknown; exports.url = url; exports.uuid = uuid; exports.uuidv1 = uuidv1; exports.uuidv4 = uuidv4;

package/dist/index.d.cts

@@ -130,6 +130,11 @@ interface Decoder<T> {
      */
     refine<N extends T>(predicate: (value: T) => value is N, msg: string): Decoder<N>;
     refine(predicate: (value: T) => boolean, msg: string): Decoder<T>;
+    /**
+     * 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<SubT extends T>(): Decoder<SubT>;
     /**
      * Build a new decoder from the current one, with an extra rejection
      * criterium.
@@ -365,6 +370,10 @@ declare function mapping<T>(decoder: Decoder<T>): Decoder<Map<string, T>>;
  * Accepts and returns `Date` instances.
  */
 declare const date: Decoder<Date>;
+/**
+ * Accepts and returns [ISO8601](https://en.wikipedia.org/wiki/ISO_8601)-formatted strings.
+ */
+declare const dateString: Decoder<string>;
 /**
  * Accepts [ISO8601](https://en.wikipedia.org/wiki/ISO_8601)-formatted strings,
  * returns them as `Date` instances.
@@ -659,4 +668,4 @@ declare function taggedUnion<O extends Record<string, Decoder<unknown>>>(field:
  */
 declare function select<T, D extends Decoder<unknown>>(scout: Decoder<T>, selectFn: (result: T) => D): Decoder<DecoderType<D>>;
 
-export { type DecodeResult, type Decoder, type DecoderType, type Err, type Formatter, type JSONArray, type JSONObject, type JSONValue, type Ok, type Result, type Scalar, type SizeOptions, always, anyNumber, array, bigint, boolean, constant, date, datelike, decimal, define, dict, either, email, endsWith, enum_, err, exact, fail, formatInline, formatShort, hardcoded, hexadecimal, httpsUrl, identifier, inexact, instanceOf, integer, iso8601, json, jsonArray, jsonObject, lazy, mapping, maybe, mixed, nanoid, never, nonEmptyArray, nonEmptyString, null_, nullable, nullish, number, numeric, object, ok, oneOf, optional, poja, pojo, positiveInteger, positiveNumber, prep, record, regex, select, set, setFromArray, startsWith, string, taggedUnion, truthy, tuple, undefined_, unknown, url, uuid, uuidv1, uuidv4 };
+export { type DecodeResult, type Decoder, type DecoderType, type Err, type Formatter, type JSONArray, type JSONObject, type JSONValue, type Ok, type Result, type Scalar, type SizeOptions, always, anyNumber, array, bigint, boolean, constant, date, dateString, datelike, decimal, define, dict, either, email, endsWith, enum_, err, exact, fail, formatInline, formatShort, hardcoded, hexadecimal, httpsUrl, identifier, inexact, instanceOf, integer, iso8601, json, jsonArray, jsonObject, lazy, mapping, maybe, mixed, nanoid, never, nonEmptyArray, nonEmptyString, null_, nullable, nullish, number, numeric, object, ok, oneOf, optional, poja, pojo, positiveInteger, positiveNumber, prep, record, regex, select, set, setFromArray, startsWith, string, taggedUnion, truthy, tuple, undefined_, unknown, url, uuid, uuidv1, uuidv4 };

package/dist/index.d.ts

@@ -130,6 +130,11 @@ interface Decoder<T> {
      */
     refine<N extends T>(predicate: (value: T) => value is N, msg: string): Decoder<N>;
     refine(predicate: (value: T) => boolean, msg: string): Decoder<T>;
+    /**
+     * 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<SubT extends T>(): Decoder<SubT>;
     /**
      * Build a new decoder from the current one, with an extra rejection
      * criterium.
@@ -365,6 +370,10 @@ declare function mapping<T>(decoder: Decoder<T>): Decoder<Map<string, T>>;
  * Accepts and returns `Date` instances.
  */
 declare const date: Decoder<Date>;
+/**
+ * Accepts and returns [ISO8601](https://en.wikipedia.org/wiki/ISO_8601)-formatted strings.
+ */
+declare const dateString: Decoder<string>;
 /**
  * Accepts [ISO8601](https://en.wikipedia.org/wiki/ISO_8601)-formatted strings,
  * returns them as `Date` instances.
@@ -659,4 +668,4 @@ declare function taggedUnion<O extends Record<string, Decoder<unknown>>>(field:
  */
 declare function select<T, D extends Decoder<unknown>>(scout: Decoder<T>, selectFn: (result: T) => D): Decoder<DecoderType<D>>;
 
-export { type DecodeResult, type Decoder, type DecoderType, type Err, type Formatter, type JSONArray, type JSONObject, type JSONValue, type Ok, type Result, type Scalar, type SizeOptions, always, anyNumber, array, bigint, boolean, constant, date, datelike, decimal, define, dict, either, email, endsWith, enum_, err, exact, fail, formatInline, formatShort, hardcoded, hexadecimal, httpsUrl, identifier, inexact, instanceOf, integer, iso8601, json, jsonArray, jsonObject, lazy, mapping, maybe, mixed, nanoid, never, nonEmptyArray, nonEmptyString, null_, nullable, nullish, number, numeric, object, ok, oneOf, optional, poja, pojo, positiveInteger, positiveNumber, prep, record, regex, select, set, setFromArray, startsWith, string, taggedUnion, truthy, tuple, undefined_, unknown, url, uuid, uuidv1, uuidv4 };
+export { type DecodeResult, type Decoder, type DecoderType, type Err, type Formatter, type JSONArray, type JSONObject, type JSONValue, type Ok, type Result, type Scalar, type SizeOptions, always, anyNumber, array, bigint, boolean, constant, date, dateString, datelike, decimal, define, dict, either, email, endsWith, enum_, err, exact, fail, formatInline, formatShort, hardcoded, hexadecimal, httpsUrl, identifier, inexact, instanceOf, integer, iso8601, json, jsonArray, jsonObject, lazy, mapping, maybe, mixed, nanoid, never, nonEmptyArray, nonEmptyString, null_, nullable, nullish, number, numeric, object, ok, oneOf, optional, poja, pojo, positiveInteger, positiveNumber, prep, record, regex, select, set, setFromArray, startsWith, string, taggedUnion, truthy, tuple, undefined_, unknown, url, uuid, uuidv1, uuidv4 };

package/dist/index.js

@@ -114,7 +114,7 @@ function indent(s, prefix = INDENT) {
 }
 var quotePattern = /'/g;
 function quote(value) {
-  return typeof value === "string" ? "'" + value.replace(quotePattern, "\\'") + "'" : JSON.stringify(value);
+  return typeof value === "string" ? "'" + value.replace(quotePattern, "\\'") + "'" : value === void 0 ? "undefined" : JSON.stringify(value);
 }
 
 // src/core/format.ts
@@ -311,11 +311,8 @@ ${formatted}`);
 }
 function define(fn) {
   function decode(blob) {
-    return fn(
-      blob,
-      ok,
-      (msg) => err(isAnnotation(msg) ? msg : public_annotate(blob, msg))
-    );
+    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);
@@ -342,6 +339,9 @@ function define(fn) {
       )
     );
   }
+  function refineType() {
+    return self;
+  }
   function then(next) {
     return define((blob, ok2, err2) => {
       const r1 = decode(blob);
@@ -369,12 +369,13 @@ function define(fn) {
       }
     });
   }
-  return brand2({
+  const unregistered = {
     verify,
     value,
     decode,
     transform,
     refine,
+    refineType,
     reject,
     describe,
     then,
@@ -392,7 +393,9 @@ function define(fn) {
         }
       }
     }
-  });
+  };
+  const self = brand2(unregistered);
+  return self;
 }
 var kDecoderRegistry = Symbol.for("decoders.kDecoderRegistry");
 var _register2 = globalThis[kDecoderRegistry] ??= /* @__PURE__ */ new WeakSet();
@@ -411,30 +414,28 @@ var poja = define((blob, ok2, err2) => {
   }
   return ok2(blob);
 });
-function all(items, blobs, ok2, err2) {
-  const results = [];
-  for (let index = 0; index < items.length; ++index) {
-    const result = items[index];
-    if (result.ok) {
-      results.push(result.value);
-    } else {
-      const ann = result.error;
-      const clone = blobs.slice();
-      clone.splice(
-        index,
-        1,
-        public_annotate(ann, ann.text ? `${ann.text} (at index ${index})` : `index ${index}`)
-      );
-      return err2(public_annotate(clone));
-    }
-  }
-  return ok2(results);
-}
 function array(decoder) {
   const decodeFn = decoder.decode;
-  return poja.then((blobs, ok2, err2) => {
-    const results = blobs.map(decodeFn);
-    return all(results, blobs, ok2, err2);
+  return poja.then((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) {
@@ -533,9 +534,7 @@ function object(decoders) {
         if (rawValue === void 0) {
           missingKeys.add(key);
         } else {
-          if (errors === null) {
-            errors = /* @__PURE__ */ new Map();
-          }
+          errors ??= /* @__PURE__ */ new Map();
           errors.set(key, ann);
         }
       }
@@ -614,9 +613,9 @@ function either(...decoders) {
 }
 function oneOf(constants) {
   return define((blob, ok2, err2) => {
-    const winner = constants.find((c) => c === blob);
-    if (winner !== void 0) {
-      return ok2(winner);
+    const index = constants.indexOf(blob);
+    if (index !== -1) {
+      return ok2(constants[index]);
     }
     return err2(`Must be one of ${constants.map((value) => quote(value)).join(", ")}`);
   });
@@ -820,19 +819,14 @@ var iso8601_re = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:[.]\d+)?(?:Z|[+-]\d{2}:
 var date = define((blob, ok2, err2) => {
   return isDate(blob) ? ok2(blob) : err2("Must be a Date");
 });
-var iso8601 = (
-  // Input itself needs to match the ISO8601 regex...
-  regex(iso8601_re, "Must be ISO8601 format").transform(
-    // Make sure it is a _valid_ date
-    (value) => {
-      const date2 = new Date(value);
-      if (isNaN(date2.getTime())) {
-        throw new Error("Must be valid date/time value");
-      }
-      return date2;
-    }
-  )
+var dateString = regex(
+  iso8601_re,
+  "Must be ISO8601 format"
+).refine(
+  (value) => !isNaN(new Date(value).getTime()),
+  "Must be valid date/time value"
 );
+var iso8601 = dateString.transform((value) => new Date(value));
 var datelike = either(date, iso8601).describe("Must be a Date or date string");
 
 // src/numbers.ts
@@ -878,6 +872,7 @@ export {
   boolean,
   constant,
   date,
+  dateString,
   datelike,
   decimal,
   define,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "decoders",
-  "version": "2.6.1",
+  "version": "2.7.1",
   "description": "Elegant and battle-tested validation library for type-safe input data for TypeScript",
   "license": "MIT",
   "repository": {
@@ -61,26 +61,26 @@
   ],
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.17.4",
-    "@eslint/js": "^9.21.0",
+    "@eslint/js": "^9.23.0",
     "@release-it/keep-a-changelog": "^6.0.0",
     "@standard-schema/spec": "^1.0.0",
-    "@vitest/coverage-istanbul": "^3.0.7",
-    "eslint": "^9.21.0",
+    "@vitest/coverage-istanbul": "^3.0.9",
+    "eslint": "^9.23.0",
     "eslint-plugin-import": "^2.31.0",
     "eslint-plugin-simple-import-sort": "^12.1.1",
-    "fast-check": "^3.23.2",
+    "fast-check": "^4.0.0",
     "itertools": "^2.4.1",
-    "pkg-pr-new": "^0.0.39",
-    "prettier": "^3.5.2",
-    "publint": "^0.3.6",
+    "pkg-pr-new": "^0.0.41",
+    "prettier": "^3.5.3",
+    "publint": "^0.3.9",
     "release-it": "^18.1.2",
     "ts-morph": "^25.0.1",
     "tsd": "^0.31.2",
-    "tsup": "^8.3.6",
-    "typescript": "^5.7.3",
-    "typescript-eslint": "^8.25.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.2",
+    "typescript-eslint": "^8.28.0",
     "vite-tsconfig-paths": "^5.1.4",
-    "vitest": "^3.0.7"
+    "vitest": "^3.0.9"
   },
   "githubUrl": "https://github.com/nvie/decoders",
   "sideEffects": false