decoders 2.3.0 → 2.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![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)
-[![Minified Size](https://badgen.net/bundlephobia/minzip/decoders)](https://bundlephobia.com/result?p=decoders)
+[![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/).

package/dist/index.cjs

@@ -66,7 +66,8 @@ function annotateArray(arr, text, seen) {
 function annotateObject(obj, text, seen) {
   seen.add(obj);
   const fields = /* @__PURE__ */ new Map();
-  for (const [key, value] of Object.entries(obj)) {
+  for (const key of Object.keys(obj)) {
+    const value = obj[key];
     fields.set(key, annotate(value, void 0, seen));
   }
   return makeObjectAnn(fields, text);
@@ -116,6 +117,10 @@ function indent(s, prefix = INDENT) {
     return `${prefix}${s}`;
   }
 }
+var quotePattern = /'/g;
+function quote(value) {
+  return typeof value === "string" ? "'" + value.replace(quotePattern, "\\'") + "'" : JSON.stringify(value);
+}
 
 // src/core/format.ts
 function summarize(ann, keypath = []) {
@@ -144,9 +149,9 @@ function summarize(ann, keypath = []) {
   if (keypath.length === 0) {
     prefix = "";
   } else if (keypath.length === 1) {
-    prefix = typeof keypath[0] === "number" ? `Value at index ${keypath[0]}: ` : `Value at key ${JSON.stringify(keypath[0])}: `;
+    prefix = typeof keypath[0] === "number" ? `Value at index ${keypath[0]}: ` : `Value at key ${quote(keypath[0])}: `;
   } else {
-    prefix = `Value at keypath ${keypath.map(String).join(".")}: `;
+    prefix = `Value at keypath ${quote(keypath.map(String).join("."))}: `;
   }
   return [...result, `${prefix}${text}`];
 }
@@ -202,7 +207,7 @@ function serializeValue(value) {
     return "undefined";
   } else {
     if (isDate(value)) {
-      return `new Date(${JSON.stringify(value.toISOString())})`;
+      return `new Date(${quote(value.toISOString())})`;
     } else if (value instanceof Date) {
       return "(Invalid Date)";
     } else {
@@ -311,10 +316,16 @@ function define(fn) {
   }
   function then(next) {
     return define((blob, ok2, err2) => {
-      const result = decode(blob);
-      return result.ok ? next(result.value, ok2, err2) : result;
+      const r1 = decode(blob);
+      if (!r1.ok)
+        return r1;
+      const r2 = isDecoder(next) ? next : next(r1.value, ok2, err2);
+      return isDecoder(r2) ? r2.decode(r1.value) : r2;
     });
   }
+  function pipe(next) {
+    return then(next);
+  }
   function reject(rejectFn) {
     return then((blob, ok2, err2) => {
       const errmsg = rejectFn(blob);
@@ -331,13 +342,7 @@ function define(fn) {
       }
     });
   }
-  function peek(next) {
-    return define((blob, ok2, err2) => {
-      const result = decode(blob);
-      return result.ok ? next([blob, result.value], ok2, err2) : result;
-    });
-  }
-  return Object.freeze({
+  return brand2({
     verify,
     value,
     decode,
@@ -346,9 +351,17 @@ function define(fn) {
     reject,
     describe,
     then,
-    peek
+    pipe
   });
 }
+var _register2 = /* @__PURE__ */ new WeakSet();
+function brand2(decoder) {
+  _register2.add(decoder);
+  return decoder;
+}
+function isDecoder(thing) {
+  return _register2.has(thing);
+}
 
 // src/arrays.ts
 var poja = define((blob, ok2, err2) => {
@@ -489,7 +502,7 @@ function object(decoders) {
         objAnn = merge(objAnn, errors);
       }
       if (missingKeys.size > 0) {
-        const errMsg = Array.from(missingKeys).map((key) => `"${key}"`).join(", ");
+        const errMsg = Array.from(missingKeys).map(quote).join(", ");
         const pluralized = missingKeys.size > 1 ? "keys" : "key";
         objAnn = updateText(objAnn, `Missing ${pluralized}: ${errMsg}`);
       }
@@ -503,17 +516,14 @@ function exact(decoders) {
   const checked = pojo.reject((plainObj) => {
     const actualKeys = new Set(Object.keys(plainObj));
     const extraKeys = difference(actualKeys, allowedKeys);
-    return extraKeys.size > 0 ? `Unexpected extra keys: ${Array.from(extraKeys).join(", ")}` : (
-      // Don't reject
-      null
-    );
+    return extraKeys.size > 0 ? `Unexpected extra keys: ${Array.from(extraKeys).map(quote).join(", ")}` : null;
   });
-  return checked.then(object(decoders).decode);
+  return checked.pipe(object(decoders));
 }
 function inexact(decoders) {
-  return pojo.then((plainObj) => {
+  return pojo.pipe((plainObj) => {
     const allkeys = new Set(Object.keys(plainObj));
-    const decoder = object(decoders).transform((safepart) => {
+    return object(decoders).transform((safepart) => {
       const safekeys = new Set(Object.keys(decoders));
       for (const k of safekeys)
         allkeys.add(k);
@@ -530,7 +540,6 @@ function inexact(decoders) {
       }
       return rv;
     });
-    return decoder.decode(plainObj);
   });
 }
 
@@ -566,9 +575,7 @@ function oneOf(constants) {
     if (winner !== void 0) {
       return ok2(winner);
     }
-    return err2(
-      `Must be one of ${constants.map((value) => JSON.stringify(value)).join(", ")}`
-    );
+    return err2(`Must be one of ${constants.map((value) => quote(value)).join(", ")}`);
   });
 }
 function enum_(enumObj) {
@@ -594,9 +601,9 @@ function taggedUnion(field, mapping2) {
   );
 }
 function select(scout, selectFn) {
-  return scout.peek(([blob, peekResult]) => {
-    const decoder = selectFn(peekResult);
-    return decoder.decode(blob);
+  return define((blob) => {
+    const result = scout.decode(blob);
+    return result.ok ? selectFn(result.value).decode(blob) : result;
   });
 }
 
@@ -627,9 +634,7 @@ function nullish(decoder, defaultValue) {
 }
 function constant(value) {
   return define(
-    (blob, ok2, err2) => blob === value ? ok2(value) : err2(
-      `Must be ${typeof value === "symbol" ? String(value) : JSON.stringify(value)}`
-    )
+    (blob, ok2, err2) => blob === value ? ok2(value) : err2(`Must be ${typeof value === "symbol" ? String(value) : quote(value)}`)
   );
 }
 function always(value) {
@@ -645,36 +650,11 @@ var hardcoded = always;
 var unknown = define((blob, ok2, _) => ok2(blob));
 var mixed = unknown;
 
-// src/numbers.ts
-var anyNumber = define(
-  (blob, ok2, err2) => isNumber(blob) ? ok2(blob) : err2("Must be number")
-);
-var number = anyNumber.refine(
-  (n) => Number.isFinite(n),
-  "Number must be finite"
-);
-var integer = number.refine(
-  (n) => Number.isInteger(n),
-  "Number must be an integer"
-);
-var positiveNumber = number.refine(
-  (n) => n >= 0 && !Object.is(n, -0),
-  "Number must be positive"
-);
-var positiveInteger = integer.refine(
-  (n) => n >= 0 && !Object.is(n, -0),
-  "Number must be positive"
-);
-var bigint = define(
-  (blob, ok2, err2) => isBigInt(blob) ? ok2(blob) : err2("Must be bigint")
-);
-
 // src/booleans.ts
 var boolean = define((blob, ok2, err2) => {
   return typeof blob === "boolean" ? ok2(blob) : err2("Must be boolean");
 });
 var truthy = define((blob, ok2, _) => ok2(!!blob));
-var numericBoolean = number.transform((n) => !!n);
 
 // src/collections.ts
 function record(fst, snd) {
@@ -683,14 +663,12 @@ function record(fst, snd) {
   return pojo.then((input, ok2, err2) => {
     let rv = {};
     const errors = /* @__PURE__ */ new Map();
-    for (const [key, value] of Object.entries(input)) {
+    for (const key of Object.keys(input)) {
+      const value = input[key];
       const keyResult = _optionalChain([keyDecoder, 'optionalAccess', _2 => _2.decode, 'call', _3 => _3(key)]);
       if (_optionalChain([keyResult, 'optionalAccess', _4 => _4.ok]) === false) {
         return err2(
-          public_annotate(
-            input,
-            `Invalid key ${JSON.stringify(key)}: ${formatShort(keyResult.error)}`
-          )
+          public_annotate(input, `Invalid key ${quote(key)}: ${formatShort(keyResult.error)}`)
         );
       }
       const k = _nullishCoalesce(_optionalChain([keyResult, 'optionalAccess', _5 => _5.value]), () => ( key));
@@ -720,6 +698,18 @@ function mapping(decoder) {
   return record(decoder).transform((obj) => new Map(Object.entries(obj)));
 }
 
+// src/lib/size-options.ts
+function bySizeOptions(options) {
+  const size = _optionalChain([options, 'optionalAccess', _6 => _6.size]);
+  const min = _nullishCoalesce(size, () => ( _optionalChain([options, 'optionalAccess', _7 => _7.min])));
+  const max = _nullishCoalesce(size, () => ( _optionalChain([options, 'optionalAccess', _8 => _8.max])));
+  const atLeast = min === max ? "" : "at least ";
+  const atMost = min === max ? "" : "at most ";
+  const tooShort = min !== void 0 && `Too short, must be ${atLeast}${min} chars`;
+  const tooLong = max !== void 0 && `Too long, must be ${atMost}${max} chars`;
+  return tooShort && tooLong ? (s) => s.length < min ? tooShort : s.length > max ? tooLong : null : tooShort ? (s) => s.length < min ? tooShort : null : tooLong ? (s) => s.length > max ? tooLong : null : () => null;
+}
+
 // src/strings.ts
 var url_re = /^([A-Za-z]{3,9}(?:[+][A-Za-z]{3,9})?):\/\/(?:([-;:&=+$,\w]+)@)?(?:([A-Za-z0-9.-]+)(?::([0-9]{2,5}))?)(\/(?:[-+~%/.,\w]*)?(?:\?[-+=&;%@.,/\w]*)?(?:#[.,!/\w]*)?)?$/;
 var string = define(
@@ -742,6 +732,15 @@ var httpsUrl = url.refine(
   (value) => value.protocol === "https:",
   "Must be an HTTPS URL"
 );
+var identifier = regex(
+  /^[a-z_][a-z0-9_]*$/i,
+  "Must be valid identifier"
+);
+function nanoid(options) {
+  return regex(/^[a-z0-9_-]+$/i, "Must be nano ID").reject(
+    bySizeOptions(_nullishCoalesce(options, () => ( { size: 21 })))
+  );
+}
 var uuid = regex(
   /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
   "Must be uuid"
@@ -781,6 +780,30 @@ var iso8601 = (
 );
 var datelike = either(date, iso8601).describe("Must be a Date or date string");
 
+// src/numbers.ts
+var anyNumber = define(
+  (blob, ok2, err2) => isNumber(blob) ? ok2(blob) : err2("Must be number")
+);
+var number = anyNumber.refine(
+  (n) => Number.isFinite(n),
+  "Number must be finite"
+);
+var integer = number.refine(
+  (n) => Number.isInteger(n),
+  "Number must be an integer"
+);
+var positiveNumber = number.refine(
+  (n) => n >= 0 && !Object.is(n, -0),
+  "Number must be positive"
+);
+var positiveInteger = integer.refine(
+  (n) => n >= 0 && !Object.is(n, -0),
+  "Number must be positive"
+);
+var bigint = define(
+  (blob, ok2, err2) => isBigInt(blob) ? ok2(blob) : err2("Must be bigint")
+);
+
 // src/json.ts
 var jsonObject = lazy(() => record(json));
 var jsonArray = lazy(() => array(json));
@@ -859,4 +882,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.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.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.never = never; exports.nonEmptyArray = nonEmptyArray; exports.nonEmptyString = nonEmptyString; exports.null_ = null_; exports.nullable = nullable; exports.nullish = nullish; exports.number = number; exports.numeric = numeric; exports.numericBoolean = numericBoolean; 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.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.datelike = datelike; exports.decimal = decimal; exports.define = define; exports.dict = dict; exports.either = either; exports.email = email; 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.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

@@ -59,7 +59,8 @@ type DecodeResult<T> = Result<T, Annotation>;
  * `ok()` and `err()` constructor functions are provided as the 2nd and 3rd
  * param. One of these should be called and its value returned.
  */
-type AcceptanceFn<T, InputT = unknown> = (blob: InputT, ok: (value: T) => DecodeResult<T>, err: (msg: string | Annotation) => DecodeResult<T>) => DecodeResult<T>;
+type AcceptanceFn<O, I = unknown> = (blob: I, ok: (value: O) => DecodeResult<O>, err: (msg: string | Annotation) => DecodeResult<O>) => DecodeResult<O>;
+type Next<O, I = unknown> = Decoder<O> | ((blob: I, ok: (value: O) => DecodeResult<O>, err: (msg: string | Annotation) => DecodeResult<O>) => DecodeResult<O> | Decoder<O>);
 interface Decoder<T> {
     /**
      * Verifies untrusted input. Either returns a value, or throws a decoding
@@ -96,23 +97,31 @@ interface Decoder<T> {
      */
     describe(message: string): Decoder<T>;
     /**
-     * Send the output of the current decoder into another acceptance function.
-     * The given acceptance function will receive the output of the current
-     * decoder as its input, making it partially trusted.
-     *
-     * This works similar to how you would `define()` a new decoder, except
-     * that the ``blob`` param will now be ``T`` (a known type), rather than
-     * ``unknown``. This will allow the function to make a stronger assumption
-     * about its input and avoid re-refining inputs.
+     * 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()` or `.refine()` instead._
+     * > be covered more elegantly by `.transform()`, `.refine()`, or `.pipe()`
+     * > instead._
+     */
+    then<V>(next: Next<V, T>): Decoder<V>;
+    /**
+     * Send the output of this decoder as input to another decoder.
+     *
+     * This can be useful to validate the results of a transform, i.e.:
      *
-     * If it helps, you can think of `define(...)` as equivalent to
-     * `unknown.then(...)`.
+     *   string
+     *     .transform((s) => s.split(','))
+     *     .pipe(array(nonEmptyString))
+     *
+     * You can also conditionally pipe:
+     *
+     *   string.pipe((s) => s.startsWith('@') ? username : email)
      */
-    then<V>(next: AcceptanceFn<V, T>): Decoder<V>;
+    pipe<V, D extends Decoder<V>>(next: D): Decoder<DecoderType<D>>;
+    pipe<V, D extends Decoder<V>>(next: (blob: T) => D): Decoder<DecoderType<D>>;
 }
 /**
  * Helper type to return the output type of a Decoder.
@@ -264,13 +273,6 @@ declare const boolean: Decoder<boolean>;
  * Accepts anything and will return its "truth" value. Will never reject.
  */
 declare const truthy: Decoder<boolean>;
-/**
- * Accepts numbers, but return their boolean representation.
- *
- * @deprecated This decoder will be removed in a future version. You can use
- * `truthy` to get almost the same effect.
- */
-declare const numericBoolean: Decoder<boolean>;
 
 /**
  * Accepts objects where all values match the given decoder, and returns the
@@ -358,6 +360,12 @@ declare const jsonArray: Decoder<JSONArray>;
  */
 declare const json: Decoder<JSONValue>;
 
+type SizeOptions = {
+    min?: number;
+    max?: number;
+    size?: number;
+};
+
 interface Klass<T> extends Function {
     new (...args: readonly any[]): T;
 }
@@ -490,6 +498,17 @@ declare const url: Decoder<URL>;
  * as a URL instance.
  */
 declare const httpsUrl: Decoder<URL>;
+/**
+ * Accepts and returns strings that are valid identifiers in most programming
+ * languages.
+ */
+declare const identifier: Decoder<string>;
+/**
+ * Accepts and returns [nanoid](https://zelark.github.io/nano-id-cc) string
+ * values. It assumes the default nanoid alphabet. If you're using a custom
+ * alphabet, use `regex()` instead.
+ */
+declare function nanoid(options?: SizeOptions): Decoder<string>;
 /**
  * Accepts strings that are valid
  * [UUIDs](https://en.wikipedia.org/wiki/universally_unique_identifier)
@@ -581,4 +600,4 @@ declare function taggedUnion<O extends Record<string, Decoder<unknown>>, T = Dec
  */
 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, always, anyNumber, array, bigint, boolean, constant, date, datelike, decimal, define, dict, either, email, enum_, err, exact, fail, formatInline, formatShort, hardcoded, hexadecimal, httpsUrl, inexact, instanceOf, integer, iso8601, json, jsonArray, jsonObject, lazy, mapping, maybe, mixed, never, nonEmptyArray, nonEmptyString, null_, nullable, nullish, number, numeric, numericBoolean, object, ok, oneOf, optional, poja, pojo, positiveInteger, positiveNumber, prep, record, regex, select, set, setFromArray, 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, datelike, decimal, define, dict, either, email, 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, string, taggedUnion, truthy, tuple, undefined_, unknown, url, uuid, uuidv1, uuidv4 };

package/dist/index.d.ts

@@ -59,7 +59,8 @@ type DecodeResult<T> = Result<T, Annotation>;
  * `ok()` and `err()` constructor functions are provided as the 2nd and 3rd
  * param. One of these should be called and its value returned.
  */
-type AcceptanceFn<T, InputT = unknown> = (blob: InputT, ok: (value: T) => DecodeResult<T>, err: (msg: string | Annotation) => DecodeResult<T>) => DecodeResult<T>;
+type AcceptanceFn<O, I = unknown> = (blob: I, ok: (value: O) => DecodeResult<O>, err: (msg: string | Annotation) => DecodeResult<O>) => DecodeResult<O>;
+type Next<O, I = unknown> = Decoder<O> | ((blob: I, ok: (value: O) => DecodeResult<O>, err: (msg: string | Annotation) => DecodeResult<O>) => DecodeResult<O> | Decoder<O>);
 interface Decoder<T> {
     /**
      * Verifies untrusted input. Either returns a value, or throws a decoding
@@ -96,23 +97,31 @@ interface Decoder<T> {
      */
     describe(message: string): Decoder<T>;
     /**
-     * Send the output of the current decoder into another acceptance function.
-     * The given acceptance function will receive the output of the current
-     * decoder as its input, making it partially trusted.
-     *
-     * This works similar to how you would `define()` a new decoder, except
-     * that the ``blob`` param will now be ``T`` (a known type), rather than
-     * ``unknown``. This will allow the function to make a stronger assumption
-     * about its input and avoid re-refining inputs.
+     * 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()` or `.refine()` instead._
+     * > be covered more elegantly by `.transform()`, `.refine()`, or `.pipe()`
+     * > instead._
+     */
+    then<V>(next: Next<V, T>): Decoder<V>;
+    /**
+     * Send the output of this decoder as input to another decoder.
+     *
+     * This can be useful to validate the results of a transform, i.e.:
      *
-     * If it helps, you can think of `define(...)` as equivalent to
-     * `unknown.then(...)`.
+     *   string
+     *     .transform((s) => s.split(','))
+     *     .pipe(array(nonEmptyString))
+     *
+     * You can also conditionally pipe:
+     *
+     *   string.pipe((s) => s.startsWith('@') ? username : email)
      */
-    then<V>(next: AcceptanceFn<V, T>): Decoder<V>;
+    pipe<V, D extends Decoder<V>>(next: D): Decoder<DecoderType<D>>;
+    pipe<V, D extends Decoder<V>>(next: (blob: T) => D): Decoder<DecoderType<D>>;
 }
 /**
  * Helper type to return the output type of a Decoder.
@@ -264,13 +273,6 @@ declare const boolean: Decoder<boolean>;
  * Accepts anything and will return its "truth" value. Will never reject.
  */
 declare const truthy: Decoder<boolean>;
-/**
- * Accepts numbers, but return their boolean representation.
- *
- * @deprecated This decoder will be removed in a future version. You can use
- * `truthy` to get almost the same effect.
- */
-declare const numericBoolean: Decoder<boolean>;
 
 /**
  * Accepts objects where all values match the given decoder, and returns the
@@ -358,6 +360,12 @@ declare const jsonArray: Decoder<JSONArray>;
  */
 declare const json: Decoder<JSONValue>;
 
+type SizeOptions = {
+    min?: number;
+    max?: number;
+    size?: number;
+};
+
 interface Klass<T> extends Function {
     new (...args: readonly any[]): T;
 }
@@ -490,6 +498,17 @@ declare const url: Decoder<URL>;
  * as a URL instance.
  */
 declare const httpsUrl: Decoder<URL>;
+/**
+ * Accepts and returns strings that are valid identifiers in most programming
+ * languages.
+ */
+declare const identifier: Decoder<string>;
+/**
+ * Accepts and returns [nanoid](https://zelark.github.io/nano-id-cc) string
+ * values. It assumes the default nanoid alphabet. If you're using a custom
+ * alphabet, use `regex()` instead.
+ */
+declare function nanoid(options?: SizeOptions): Decoder<string>;
 /**
  * Accepts strings that are valid
  * [UUIDs](https://en.wikipedia.org/wiki/universally_unique_identifier)
@@ -581,4 +600,4 @@ declare function taggedUnion<O extends Record<string, Decoder<unknown>>, T = Dec
  */
 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, always, anyNumber, array, bigint, boolean, constant, date, datelike, decimal, define, dict, either, email, enum_, err, exact, fail, formatInline, formatShort, hardcoded, hexadecimal, httpsUrl, inexact, instanceOf, integer, iso8601, json, jsonArray, jsonObject, lazy, mapping, maybe, mixed, never, nonEmptyArray, nonEmptyString, null_, nullable, nullish, number, numeric, numericBoolean, object, ok, oneOf, optional, poja, pojo, positiveInteger, positiveNumber, prep, record, regex, select, set, setFromArray, 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, datelike, decimal, define, dict, either, email, 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, string, taggedUnion, truthy, tuple, undefined_, unknown, url, uuid, uuidv1, uuidv4 };

package/dist/index.js

@@ -66,7 +66,8 @@ function annotateArray(arr, text, seen) {
 function annotateObject(obj, text, seen) {
   seen.add(obj);
   const fields = /* @__PURE__ */ new Map();
-  for (const [key, value] of Object.entries(obj)) {
+  for (const key of Object.keys(obj)) {
+    const value = obj[key];
     fields.set(key, annotate(value, void 0, seen));
   }
   return makeObjectAnn(fields, text);
@@ -116,6 +117,10 @@ function indent(s, prefix = INDENT) {
     return `${prefix}${s}`;
   }
 }
+var quotePattern = /'/g;
+function quote(value) {
+  return typeof value === "string" ? "'" + value.replace(quotePattern, "\\'") + "'" : JSON.stringify(value);
+}
 
 // src/core/format.ts
 function summarize(ann, keypath = []) {
@@ -144,9 +149,9 @@ function summarize(ann, keypath = []) {
   if (keypath.length === 0) {
     prefix = "";
   } else if (keypath.length === 1) {
-    prefix = typeof keypath[0] === "number" ? `Value at index ${keypath[0]}: ` : `Value at key ${JSON.stringify(keypath[0])}: `;
+    prefix = typeof keypath[0] === "number" ? `Value at index ${keypath[0]}: ` : `Value at key ${quote(keypath[0])}: `;
   } else {
-    prefix = `Value at keypath ${keypath.map(String).join(".")}: `;
+    prefix = `Value at keypath ${quote(keypath.map(String).join("."))}: `;
   }
   return [...result, `${prefix}${text}`];
 }
@@ -202,7 +207,7 @@ function serializeValue(value) {
     return "undefined";
   } else {
     if (isDate(value)) {
-      return `new Date(${JSON.stringify(value.toISOString())})`;
+      return `new Date(${quote(value.toISOString())})`;
     } else if (value instanceof Date) {
       return "(Invalid Date)";
     } else {
@@ -311,10 +316,16 @@ function define(fn) {
   }
   function then(next) {
     return define((blob, ok2, err2) => {
-      const result = decode(blob);
-      return result.ok ? next(result.value, ok2, err2) : result;
+      const r1 = decode(blob);
+      if (!r1.ok)
+        return r1;
+      const r2 = isDecoder(next) ? next : next(r1.value, ok2, err2);
+      return isDecoder(r2) ? r2.decode(r1.value) : r2;
     });
   }
+  function pipe(next) {
+    return then(next);
+  }
   function reject(rejectFn) {
     return then((blob, ok2, err2) => {
       const errmsg = rejectFn(blob);
@@ -331,13 +342,7 @@ function define(fn) {
       }
     });
   }
-  function peek(next) {
-    return define((blob, ok2, err2) => {
-      const result = decode(blob);
-      return result.ok ? next([blob, result.value], ok2, err2) : result;
-    });
-  }
-  return Object.freeze({
+  return brand2({
     verify,
     value,
     decode,
@@ -346,9 +351,17 @@ function define(fn) {
     reject,
     describe,
     then,
-    peek
+    pipe
   });
 }
+var _register2 = /* @__PURE__ */ new WeakSet();
+function brand2(decoder) {
+  _register2.add(decoder);
+  return decoder;
+}
+function isDecoder(thing) {
+  return _register2.has(thing);
+}
 
 // src/arrays.ts
 var poja = define((blob, ok2, err2) => {
@@ -489,7 +502,7 @@ function object(decoders) {
         objAnn = merge(objAnn, errors);
       }
       if (missingKeys.size > 0) {
-        const errMsg = Array.from(missingKeys).map((key) => `"${key}"`).join(", ");
+        const errMsg = Array.from(missingKeys).map(quote).join(", ");
         const pluralized = missingKeys.size > 1 ? "keys" : "key";
         objAnn = updateText(objAnn, `Missing ${pluralized}: ${errMsg}`);
       }
@@ -503,17 +516,14 @@ function exact(decoders) {
   const checked = pojo.reject((plainObj) => {
     const actualKeys = new Set(Object.keys(plainObj));
     const extraKeys = difference(actualKeys, allowedKeys);
-    return extraKeys.size > 0 ? `Unexpected extra keys: ${Array.from(extraKeys).join(", ")}` : (
-      // Don't reject
-      null
-    );
+    return extraKeys.size > 0 ? `Unexpected extra keys: ${Array.from(extraKeys).map(quote).join(", ")}` : null;
   });
-  return checked.then(object(decoders).decode);
+  return checked.pipe(object(decoders));
 }
 function inexact(decoders) {
-  return pojo.then((plainObj) => {
+  return pojo.pipe((plainObj) => {
     const allkeys = new Set(Object.keys(plainObj));
-    const decoder = object(decoders).transform((safepart) => {
+    return object(decoders).transform((safepart) => {
       const safekeys = new Set(Object.keys(decoders));
       for (const k of safekeys)
         allkeys.add(k);
@@ -530,7 +540,6 @@ function inexact(decoders) {
       }
       return rv;
     });
-    return decoder.decode(plainObj);
   });
 }
 
@@ -566,9 +575,7 @@ function oneOf(constants) {
     if (winner !== void 0) {
       return ok2(winner);
     }
-    return err2(
-      `Must be one of ${constants.map((value) => JSON.stringify(value)).join(", ")}`
-    );
+    return err2(`Must be one of ${constants.map((value) => quote(value)).join(", ")}`);
   });
 }
 function enum_(enumObj) {
@@ -594,9 +601,9 @@ function taggedUnion(field, mapping2) {
   );
 }
 function select(scout, selectFn) {
-  return scout.peek(([blob, peekResult]) => {
-    const decoder = selectFn(peekResult);
-    return decoder.decode(blob);
+  return define((blob) => {
+    const result = scout.decode(blob);
+    return result.ok ? selectFn(result.value).decode(blob) : result;
   });
 }
 
@@ -627,9 +634,7 @@ function nullish(decoder, defaultValue) {
 }
 function constant(value) {
   return define(
-    (blob, ok2, err2) => blob === value ? ok2(value) : err2(
-      `Must be ${typeof value === "symbol" ? String(value) : JSON.stringify(value)}`
-    )
+    (blob, ok2, err2) => blob === value ? ok2(value) : err2(`Must be ${typeof value === "symbol" ? String(value) : quote(value)}`)
   );
 }
 function always(value) {
@@ -645,36 +650,11 @@ var hardcoded = always;
 var unknown = define((blob, ok2, _) => ok2(blob));
 var mixed = unknown;
 
-// src/numbers.ts
-var anyNumber = define(
-  (blob, ok2, err2) => isNumber(blob) ? ok2(blob) : err2("Must be number")
-);
-var number = anyNumber.refine(
-  (n) => Number.isFinite(n),
-  "Number must be finite"
-);
-var integer = number.refine(
-  (n) => Number.isInteger(n),
-  "Number must be an integer"
-);
-var positiveNumber = number.refine(
-  (n) => n >= 0 && !Object.is(n, -0),
-  "Number must be positive"
-);
-var positiveInteger = integer.refine(
-  (n) => n >= 0 && !Object.is(n, -0),
-  "Number must be positive"
-);
-var bigint = define(
-  (blob, ok2, err2) => isBigInt(blob) ? ok2(blob) : err2("Must be bigint")
-);
-
 // src/booleans.ts
 var boolean = define((blob, ok2, err2) => {
   return typeof blob === "boolean" ? ok2(blob) : err2("Must be boolean");
 });
 var truthy = define((blob, ok2, _) => ok2(!!blob));
-var numericBoolean = number.transform((n) => !!n);
 
 // src/collections.ts
 function record(fst, snd) {
@@ -683,14 +663,12 @@ function record(fst, snd) {
   return pojo.then((input, ok2, err2) => {
     let rv = {};
     const errors = /* @__PURE__ */ new Map();
-    for (const [key, value] of Object.entries(input)) {
+    for (const key of Object.keys(input)) {
+      const value = input[key];
       const keyResult = keyDecoder?.decode(key);
       if (keyResult?.ok === false) {
         return err2(
-          public_annotate(
-            input,
-            `Invalid key ${JSON.stringify(key)}: ${formatShort(keyResult.error)}`
-          )
+          public_annotate(input, `Invalid key ${quote(key)}: ${formatShort(keyResult.error)}`)
         );
       }
       const k = keyResult?.value ?? key;
@@ -720,6 +698,18 @@ function mapping(decoder) {
   return record(decoder).transform((obj) => new Map(Object.entries(obj)));
 }
 
+// src/lib/size-options.ts
+function bySizeOptions(options) {
+  const size = options?.size;
+  const min = size ?? options?.min;
+  const max = size ?? options?.max;
+  const atLeast = min === max ? "" : "at least ";
+  const atMost = min === max ? "" : "at most ";
+  const tooShort = min !== void 0 && `Too short, must be ${atLeast}${min} chars`;
+  const tooLong = max !== void 0 && `Too long, must be ${atMost}${max} chars`;
+  return tooShort && tooLong ? (s) => s.length < min ? tooShort : s.length > max ? tooLong : null : tooShort ? (s) => s.length < min ? tooShort : null : tooLong ? (s) => s.length > max ? tooLong : null : () => null;
+}
+
 // src/strings.ts
 var url_re = /^([A-Za-z]{3,9}(?:[+][A-Za-z]{3,9})?):\/\/(?:([-;:&=+$,\w]+)@)?(?:([A-Za-z0-9.-]+)(?::([0-9]{2,5}))?)(\/(?:[-+~%/.,\w]*)?(?:\?[-+=&;%@.,/\w]*)?(?:#[.,!/\w]*)?)?$/;
 var string = define(
@@ -742,6 +732,15 @@ var httpsUrl = url.refine(
   (value) => value.protocol === "https:",
   "Must be an HTTPS URL"
 );
+var identifier = regex(
+  /^[a-z_][a-z0-9_]*$/i,
+  "Must be valid identifier"
+);
+function nanoid(options) {
+  return regex(/^[a-z0-9_-]+$/i, "Must be nano ID").reject(
+    bySizeOptions(options ?? { size: 21 })
+  );
+}
 var uuid = regex(
   /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
   "Must be uuid"
@@ -781,6 +780,30 @@ var iso8601 = (
 );
 var datelike = either(date, iso8601).describe("Must be a Date or date string");
 
+// src/numbers.ts
+var anyNumber = define(
+  (blob, ok2, err2) => isNumber(blob) ? ok2(blob) : err2("Must be number")
+);
+var number = anyNumber.refine(
+  (n) => Number.isFinite(n),
+  "Number must be finite"
+);
+var integer = number.refine(
+  (n) => Number.isInteger(n),
+  "Number must be an integer"
+);
+var positiveNumber = number.refine(
+  (n) => n >= 0 && !Object.is(n, -0),
+  "Number must be positive"
+);
+var positiveInteger = integer.refine(
+  (n) => n >= 0 && !Object.is(n, -0),
+  "Number must be positive"
+);
+var bigint = define(
+  (blob, ok2, err2) => isBigInt(blob) ? ok2(blob) : err2("Must be bigint")
+);
+
 // src/json.ts
 var jsonObject = lazy(() => record(json));
 var jsonArray = lazy(() => array(json));
@@ -815,6 +838,7 @@ export {
   hardcoded,
   hexadecimal,
   httpsUrl,
+  identifier,
   inexact,
   instanceOf,
   integer,
@@ -826,6 +850,7 @@ export {
   mapping,
   maybe,
   mixed,
+  nanoid,
   never,
   nonEmptyArray,
   nonEmptyString,
@@ -834,7 +859,6 @@ export {
   nullish,
   number,
   numeric,
-  numericBoolean,
   object,
   ok,
   oneOf,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "decoders",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Elegant and battle-tested validation library for type-safe input data for TypeScript",
   "license": "MIT",
   "repository": {
@@ -63,23 +63,23 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.13.5",
     "@release-it/keep-a-changelog": "^5.0.0",
-    "@typescript-eslint/eslint-plugin": "^6.18.1",
-    "@typescript-eslint/parser": "^6.18.1",
-    "@vitest/coverage-istanbul": "^1.1.3",
+    "@typescript-eslint/eslint-plugin": "^6.19.0",
+    "@typescript-eslint/parser": "^6.19.0",
+    "@vitest/coverage-istanbul": "^1.2.1",
     "eslint": "^8.56.0",
     "eslint-plugin-import": "^2.29.1",
     "eslint-plugin-simple-import-sort": "^10.0.0",
     "fast-check": "^3.15.0",
-    "itertools": "^2.2.1",
-    "prettier": "^3.1.1",
+    "itertools": "^2.2.3",
+    "prettier": "^3.2.4",
     "publint": "^0.2.7",
     "release-it": "^17.0.1",
     "ts-morph": "^21.0.1",
-    "tsd": "^0.30.3",
+    "tsd": "^0.30.4",
     "tsup": "^8.0.1",
     "typescript": "^5.3.3",
-    "vite-tsconfig-paths": "^4.2.3",
-    "vitest": "^1.1.3"
+    "vite-tsconfig-paths": "^4.3.1",
+    "vitest": "^1.2.1"
   },
   "githubUrl": "https://github.com/nvie/decoders",
   "sideEffects": false