decoders 2.11.0 → 2.12.1

package/dist/index.cjs

@@ -371,29 +371,63 @@ ${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 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.
+   */
+  
+  /**
+   * 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.
+   */
+  
+  /**
+   * 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.
+   */
+  
+  /**
+   * Memoized `~standard` props, built on first access.
+   */
+  #standard;
+  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
       ) : (
@@ -402,10 +436,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;
@@ -413,16 +462,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) {
@@ -432,18 +511,12 @@ function define(fn) {
       }
     });
   }
-  const newDecoder = {
-    verify,
-    value,
-    decode,
-    transform,
-    refine,
-    refineType,
-    reject,
-    describe,
-    chain,
-    pipe,
-    "~standard": {
+  /**
+   * The Standard Schema interface for this decoder.
+   */
+  get "~standard"() {
+    const decode = this.decode;
+    return this.#standard ??= {
       version: 1,
       vendor: "decoders",
       validate: (blob) => {
@@ -455,10 +528,14 @@ function define(fn) {
           return { issues };
         }
       }
-    }
-  };
-  const self = stamp2(newDecoder);
-  return self;
+    };
+  }
+};
+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 _stamped2 = globalThis[kDecoderRegistry] ??= /* @__PURE__ */ new WeakSet();

package/dist/index.d.cts

@@ -179,7 +179,7 @@ interface Decoder<T> {
     /**
      * The Standard Schema interface for this decoder.
      */
-    '~standard': StandardSchemaV1.Props<unknown, T>;
+    readonly '~standard': StandardSchemaV1.Props<unknown, T>;
 }
 /**
  * Helper type to return the output type of a Decoder.
@@ -673,9 +673,10 @@ declare function either<TDecoders extends readonly Decoder<unknown>[]>(...decode
  * Accepts any value that is strictly-equal (using `===`) to one of the
  * specified values.
  */
-declare function oneOf<C extends Scalar>(constants: readonly C[]): Decoder<C>;
+declare function oneOf<const C extends Scalar>(constants: readonly C[]): Decoder<C>;
 /**
- * Accepts and return an enum value.
+ * Accepts and return an enum value. Works with TypeScript enums, as well as
+ * with `as const` objects.
  */
 declare function enum_<TEnum extends Record<string, string | number>>(enumObj: TEnum): Decoder<TEnum[keyof TEnum]>;
 /**

package/dist/index.d.ts

@@ -179,7 +179,7 @@ interface Decoder<T> {
     /**
      * The Standard Schema interface for this decoder.
      */
-    '~standard': StandardSchemaV1.Props<unknown, T>;
+    readonly '~standard': StandardSchemaV1.Props<unknown, T>;
 }
 /**
  * Helper type to return the output type of a Decoder.
@@ -673,9 +673,10 @@ declare function either<TDecoders extends readonly Decoder<unknown>[]>(...decode
  * Accepts any value that is strictly-equal (using `===`) to one of the
  * specified values.
  */
-declare function oneOf<C extends Scalar>(constants: readonly C[]): Decoder<C>;
+declare function oneOf<const C extends Scalar>(constants: readonly C[]): Decoder<C>;
 /**
- * Accepts and return an enum value.
+ * Accepts and return an enum value. Works with TypeScript enums, as well as
+ * with `as const` objects.
  */
 declare function enum_<TEnum extends Record<string, string | number>>(enumObj: TEnum): Decoder<TEnum[keyof TEnum]>;
 /**

package/dist/index.js

@@ -371,29 +371,63 @@ ${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 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;
+  /**
+   * Memoized `~standard` props, built on first access.
+   */
+  #standard;
+  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
       ) : (
@@ -402,10 +436,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;
@@ -413,16 +462,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) {
@@ -432,18 +511,12 @@ function define(fn) {
       }
     });
   }
-  const newDecoder = {
-    verify,
-    value,
-    decode,
-    transform,
-    refine,
-    refineType,
-    reject,
-    describe,
-    chain,
-    pipe,
-    "~standard": {
+  /**
+   * The Standard Schema interface for this decoder.
+   */
+  get "~standard"() {
+    const decode = this.decode;
+    return this.#standard ??= {
       version: 1,
       vendor: "decoders",
       validate: (blob) => {
@@ -455,10 +528,14 @@ function define(fn) {
           return { issues };
         }
       }
-    }
-  };
-  const self = stamp2(newDecoder);
-  return self;
+    };
+  }
+};
+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 _stamped2 = globalThis[kDecoderRegistry] ??= /* @__PURE__ */ new WeakSet();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "decoders",
-  "version": "2.11.0",
+  "version": "2.12.1",
   "description": "Elegant and battle-tested validation library for type-safe input data for TypeScript",
   "license": "MIT",
   "repository": {
@@ -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",