decoders 2.4.2 → 2.6.0

package/dist/index.cjs

@@ -242,6 +242,41 @@ ${annotation}`;
 function formatShort(ann) {
   return summarize(ann, []).join("\n");
 }
+function* iterAnnotation(ann, stack) {
+  if (ann.text) {
+    if (stack.length > 0) {
+      yield { message: ann.text, path: [...stack] };
+    } else {
+      yield { message: ann.text };
+    }
+  }
+  switch (ann.type) {
+    case "array": {
+      let index = 0;
+      for (const item of ann.items) {
+        stack.push(index++);
+        yield* iterAnnotation(item, stack);
+        stack.pop();
+      }
+      break;
+    }
+    case "object": {
+      for (const [key, value] of ann.fields) {
+        stack.push(key);
+        yield* iterAnnotation(value, stack);
+        stack.pop();
+      }
+      break;
+    }
+    case "scalar":
+    case "opaque": {
+      break;
+    }
+  }
+}
+function formatAsIssues(ann) {
+  return Array.from(iterAnnotation(ann, []));
+}
 
 // src/core/Result.ts
 function ok(value) {
@@ -342,7 +377,20 @@ function define(fn) {
     reject,
     describe,
     then,
-    pipe
+    pipe,
+    "~standard": {
+      version: 1,
+      vendor: "decoders",
+      validate: (blob) => {
+        const result = decode(blob);
+        if (result.ok) {
+          return { value: result.value };
+        } else {
+          const issues = formatAsIssues(result.error);
+          return { issues };
+        }
+      }
+    }
   });
 }
 var _register2 = /* @__PURE__ */ new WeakSet();
@@ -709,6 +757,18 @@ var nonEmptyString = regex(/\S/, "Must be non-empty string");
 function regex(regex2, msg) {
   return string.refine((s) => regex2.test(s), msg);
 }
+function startsWith(prefix) {
+  return string.refine(
+    (s) => s.startsWith(prefix),
+    `Must start with '${prefix}'`
+  );
+}
+function endsWith(suffix) {
+  return string.refine(
+    (s) => s.endsWith(suffix),
+    `Must end with '${suffix}'`
+  );
+}
 var email = regex(
   // The almost perfect email regex, taken from https://emailregex.com/
   /^(([^<>()[\]\\.,;:\s@"]+(\.[^<>()[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/,
@@ -873,4 +933,6 @@ 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.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;
+
+
+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;

package/dist/index.d.cts

@@ -45,6 +45,62 @@ declare function ok<T>(value: T): Ok<T>;
  */
 declare function err<E>(error: E): Err<E>;
 
+/** The Standard Schema interface. */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+    /** The Standard Schema properties. */
+    readonly '~standard': StandardSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1 {
+    /** The Standard Schema properties interface. */
+    interface Props<Input = unknown, Output = Input> {
+        /** The version number of the standard. */
+        readonly version: 1;
+        /** The vendor name of the schema library. */
+        readonly vendor: string;
+        /** Validates unknown input values. */
+        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+        /** Inferred types associated with the schema. */
+        readonly types?: Types<Input, Output> | undefined;
+    }
+    /** The result interface of the validate function. */
+    type Result<Output> = SuccessResult<Output> | FailureResult;
+    /** The result interface if validation succeeds. */
+    interface SuccessResult<Output> {
+        /** The typed output value. */
+        readonly value: Output;
+        /** The non-existent issues. */
+        readonly issues?: undefined;
+    }
+    /** The result interface if validation fails. */
+    interface FailureResult {
+        /** The issues of failed validation. */
+        readonly issues: ReadonlyArray<Issue>;
+    }
+    /** The issue interface of the failure output. */
+    interface Issue {
+        /** The error message of the issue. */
+        readonly message: string;
+        /** The path of the issue, if any. */
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+    }
+    /** The path segment interface of the issue. */
+    interface PathSegment {
+        /** The key representing a path segment. */
+        readonly key: PropertyKey;
+    }
+    /** The Standard Schema types interface. */
+    interface Types<Input = unknown, Output = Input> {
+        /** The input type of the schema. */
+        readonly input: Input;
+        /** The output type of the schema. */
+        readonly output: Output;
+    }
+    /** Infers the input type of a Standard Schema. */
+    type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['input'];
+    /** Infers the output type of a Standard Schema. */
+    type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output'];
+}
+
 type DecodeResult<T> = Result<T, Annotation>;
 /**
  * A function taking a untrusted input, and returning a DecodeResult<T>. The
@@ -114,6 +170,10 @@ interface Decoder<T> {
      */
     pipe<V, D extends Decoder<V>>(next: D): Decoder<DecoderType<D>>;
     pipe<V, D extends Decoder<V>>(next: (blob: T) => D): Decoder<DecoderType<D>>;
+    /**
+     * The Standard Schema interface for this decoder.
+     */
+    '~standard': StandardSchemaV1.Props<unknown, T>;
 }
 /**
  * Helper type to return the output type of a Decoder.
@@ -476,6 +536,14 @@ declare const nonEmptyString: Decoder<string>;
  * Accepts and returns strings that match the given regular expression.
  */
 declare function regex(regex: RegExp, msg: string): Decoder<string>;
+/**
+ * Accepts and returns strings that start with the given prefix.
+ */
+declare function startsWith<P extends string>(prefix: P): Decoder<`${P}${string}`>;
+/**
+ * Accepts and returns strings that end with the given suffix.
+ */
+declare function endsWith<S extends string>(suffix: S): Decoder<`${string}${S}`>;
 /**
  * Accepts and returns strings that are syntactically valid email addresses.
  * (This will not mean that the email address actually exist.)
@@ -592,4 +660,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, 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 };
+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 };

package/dist/index.d.ts

@@ -45,6 +45,62 @@ declare function ok<T>(value: T): Ok<T>;
  */
 declare function err<E>(error: E): Err<E>;
 
+/** The Standard Schema interface. */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+    /** The Standard Schema properties. */
+    readonly '~standard': StandardSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1 {
+    /** The Standard Schema properties interface. */
+    interface Props<Input = unknown, Output = Input> {
+        /** The version number of the standard. */
+        readonly version: 1;
+        /** The vendor name of the schema library. */
+        readonly vendor: string;
+        /** Validates unknown input values. */
+        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+        /** Inferred types associated with the schema. */
+        readonly types?: Types<Input, Output> | undefined;
+    }
+    /** The result interface of the validate function. */
+    type Result<Output> = SuccessResult<Output> | FailureResult;
+    /** The result interface if validation succeeds. */
+    interface SuccessResult<Output> {
+        /** The typed output value. */
+        readonly value: Output;
+        /** The non-existent issues. */
+        readonly issues?: undefined;
+    }
+    /** The result interface if validation fails. */
+    interface FailureResult {
+        /** The issues of failed validation. */
+        readonly issues: ReadonlyArray<Issue>;
+    }
+    /** The issue interface of the failure output. */
+    interface Issue {
+        /** The error message of the issue. */
+        readonly message: string;
+        /** The path of the issue, if any. */
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+    }
+    /** The path segment interface of the issue. */
+    interface PathSegment {
+        /** The key representing a path segment. */
+        readonly key: PropertyKey;
+    }
+    /** The Standard Schema types interface. */
+    interface Types<Input = unknown, Output = Input> {
+        /** The input type of the schema. */
+        readonly input: Input;
+        /** The output type of the schema. */
+        readonly output: Output;
+    }
+    /** Infers the input type of a Standard Schema. */
+    type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['input'];
+    /** Infers the output type of a Standard Schema. */
+    type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output'];
+}
+
 type DecodeResult<T> = Result<T, Annotation>;
 /**
  * A function taking a untrusted input, and returning a DecodeResult<T>. The
@@ -114,6 +170,10 @@ interface Decoder<T> {
      */
     pipe<V, D extends Decoder<V>>(next: D): Decoder<DecoderType<D>>;
     pipe<V, D extends Decoder<V>>(next: (blob: T) => D): Decoder<DecoderType<D>>;
+    /**
+     * The Standard Schema interface for this decoder.
+     */
+    '~standard': StandardSchemaV1.Props<unknown, T>;
 }
 /**
  * Helper type to return the output type of a Decoder.
@@ -476,6 +536,14 @@ declare const nonEmptyString: Decoder<string>;
  * Accepts and returns strings that match the given regular expression.
  */
 declare function regex(regex: RegExp, msg: string): Decoder<string>;
+/**
+ * Accepts and returns strings that start with the given prefix.
+ */
+declare function startsWith<P extends string>(prefix: P): Decoder<`${P}${string}`>;
+/**
+ * Accepts and returns strings that end with the given suffix.
+ */
+declare function endsWith<S extends string>(suffix: S): Decoder<`${string}${S}`>;
 /**
  * Accepts and returns strings that are syntactically valid email addresses.
  * (This will not mean that the email address actually exist.)
@@ -592,4 +660,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, 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 };
+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 };

package/dist/index.js

@@ -242,6 +242,41 @@ ${annotation}`;
 function formatShort(ann) {
   return summarize(ann, []).join("\n");
 }
+function* iterAnnotation(ann, stack) {
+  if (ann.text) {
+    if (stack.length > 0) {
+      yield { message: ann.text, path: [...stack] };
+    } else {
+      yield { message: ann.text };
+    }
+  }
+  switch (ann.type) {
+    case "array": {
+      let index = 0;
+      for (const item of ann.items) {
+        stack.push(index++);
+        yield* iterAnnotation(item, stack);
+        stack.pop();
+      }
+      break;
+    }
+    case "object": {
+      for (const [key, value] of ann.fields) {
+        stack.push(key);
+        yield* iterAnnotation(value, stack);
+        stack.pop();
+      }
+      break;
+    }
+    case "scalar":
+    case "opaque": {
+      break;
+    }
+  }
+}
+function formatAsIssues(ann) {
+  return Array.from(iterAnnotation(ann, []));
+}
 
 // src/core/Result.ts
 function ok(value) {
@@ -342,7 +377,20 @@ function define(fn) {
     reject,
     describe,
     then,
-    pipe
+    pipe,
+    "~standard": {
+      version: 1,
+      vendor: "decoders",
+      validate: (blob) => {
+        const result = decode(blob);
+        if (result.ok) {
+          return { value: result.value };
+        } else {
+          const issues = formatAsIssues(result.error);
+          return { issues };
+        }
+      }
+    }
   });
 }
 var _register2 = /* @__PURE__ */ new WeakSet();
@@ -709,6 +757,18 @@ var nonEmptyString = regex(/\S/, "Must be non-empty string");
 function regex(regex2, msg) {
   return string.refine((s) => regex2.test(s), msg);
 }
+function startsWith(prefix) {
+  return string.refine(
+    (s) => s.startsWith(prefix),
+    `Must start with '${prefix}'`
+  );
+}
+function endsWith(suffix) {
+  return string.refine(
+    (s) => s.endsWith(suffix),
+    `Must end with '${suffix}'`
+  );
+}
 var email = regex(
   // The almost perfect email regex, taken from https://emailregex.com/
   /^(([^<>()[\]\\.,;:\s@"]+(\.[^<>()[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/,
@@ -819,6 +879,7 @@ export {
   dict,
   either,
   email,
+  endsWith,
   enum_,
   err,
   exact,
@@ -863,6 +924,7 @@ export {
   select,
   set,
   setFromArray,
+  startsWith,
   string,
   taggedUnion,
   truthy,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "decoders",
-  "version": "2.4.2",
+  "version": "2.6.0",
   "description": "Elegant and battle-tested validation library for type-safe input data for TypeScript",
   "license": "MIT",
   "repository": {
@@ -61,27 +61,28 @@
     "verify"
   ],
   "devDependencies": {
-    "@arethetypeswrong/cli": "^0.15.3",
-    "@release-it/keep-a-changelog": "^5.0.0",
+    "@arethetypeswrong/cli": "^0.17.3",
+    "@release-it/keep-a-changelog": "^6.0.0",
+    "@standard-schema/spec": "^1.0.0",
     "@types/eslint": "^8.56.10",
     "@typescript-eslint/eslint-plugin": "^7.14.1",
     "@typescript-eslint/parser": "^7.14.1",
-    "@vitest/coverage-istanbul": "^1.6.0",
+    "@vitest/coverage-istanbul": "^3.0.5",
     "eslint": "^8.57.0",
     "eslint-plugin-import": "^2.29.1",
     "eslint-plugin-simple-import-sort": "^12.1.0",
-    "fast-check": "^3.19.0",
+    "fast-check": "^3.23.2",
     "itertools": "^2.3.2",
-    "pkg-pr-new": "^0.0.9",
-    "prettier": "^3.3.2",
-    "publint": "^0.2.8",
-    "release-it": "^17.4.0",
-    "ts-morph": "^23.0.0",
-    "tsd": "^0.31.1",
-    "tsup": "^8.1.0",
-    "typescript": "^5.5.2",
-    "vite-tsconfig-paths": "^4.3.2",
-    "vitest": "^1.6.0"
+    "pkg-pr-new": "^0.0.39",
+    "prettier": "^3.4.2",
+    "publint": "^0.3.2",
+    "release-it": "^18.1.2",
+    "ts-morph": "^25.0.0",
+    "tsd": "^0.31.2",
+    "tsup": "^8.3.6",
+    "typescript": "^5.7.3",
+    "vite-tsconfig-paths": "^5.1.4",
+    "vitest": "^3.0.5"
   },
   "githubUrl": "https://github.com/nvie/decoders",
   "sideEffects": false