@willaimg/yatsp 4.3.6

package/src/v4/core/checks.ts

@@ -0,0 +1,1274 @@
+// import { $YatspType } from "./schemas.js";
+
+import * as core from "./core.js";
+import type * as errors from "./errors.js";
+import * as regexes from "./regexes.js";
+import type * as schemas from "./schemas.js";
+import * as util from "./util.js";
+
+//////////////////////////////   CHECKS   ///////////////////////////////////////
+
+export interface $YatspCheckDef {
+  check: string;
+  error?: errors.$YatspErrorMap<never> | undefined;
+  /** If true, no later checks will be executed if this check fails. Default `false`. */
+  abort?: boolean | undefined;
+  /** If provided, the check runs only when this returns `true`. By default, it is skipped if prior parsing produced aborting issues. */
+  when?: ((payload: schemas.ParsePayload) => boolean) | undefined;
+}
+
+export interface $YatspCheckInternals<T> {
+  def: $YatspCheckDef;
+  /** The set of issues this check might throw. */
+  issc?: errors.$YatspIssueBase;
+  check(payload: schemas.ParsePayload<T>): util.MaybeAsync<void>;
+  onattach: ((schema: schemas.$YatspType) => void)[];
+}
+
+export interface $YatspCheck<in T = never> {
+  _yatsp: $YatspCheckInternals<T>;
+}
+
+export const $YatspCheck: core.$constructor<$YatspCheck<any>> = /*@__PURE__*/ core.$constructor(
+  "$YatspCheck",
+  (inst, def) => {
+    inst._yatsp ??= {} as any;
+    inst._yatsp.def = def;
+    inst._yatsp.onattach ??= [];
+  }
+);
+
+/** Default `when` for size-based checks: run only on non-nullish values with a `size`. */
+const _whenHasSize = (payload: schemas.ParsePayload): boolean => {
+  const val = payload.value;
+  return !util.nullish(val) && (val as any).size !== undefined;
+};
+
+/** Default `when` for length-based checks: run only on non-nullish values with a `length`. */
+const _whenHasLength = (payload: schemas.ParsePayload): boolean => {
+  const val = payload.value;
+  return !util.nullish(val) && (val as any).length !== undefined;
+};
+
+///////////////////////////////////////
+/////      $YatspCheckLessThan      /////
+///////////////////////////////////////
+export interface $YatspCheckLessThanDef extends $YatspCheckDef {
+  check: "less_than";
+  value: util.Numeric;
+  inclusive: boolean;
+}
+
+export interface $YatspCheckLessThanInternals<T extends util.Numeric = util.Numeric> extends $YatspCheckInternals<T> {
+  def: $YatspCheckLessThanDef;
+  issc: errors.$YatspIssueTooBig<T>;
+}
+
+const numericOriginMap = {
+  number: "number",
+  bigint: "bigint",
+  object: "date",
+} as const;
+export interface $YatspCheckLessThan<T extends util.Numeric = util.Numeric> extends $YatspCheck<T> {
+  _yatsp: $YatspCheckLessThanInternals<T>;
+}
+
+export const $YatspCheckLessThan: core.$constructor<$YatspCheckLessThan> = /*@__PURE__*/ core.$constructor(
+  "$YatspCheckLessThan",
+  (inst, def) => {
+    $YatspCheck.init(inst, def);
+    const origin = numericOriginMap[typeof def.value as "number" | "bigint" | "object"];
+
+    inst._yatsp.check = (payload) => {
+      if (def.inclusive ? payload.value <= def.value : payload.value < def.value) {
+        return;
+      }
+
+      payload.issues.push({
+        origin: numericOriginMap[typeof payload.value as "number" | "bigint" | "object"] ?? origin,
+        code: "too_big",
+        maximum: typeof def.value === "object" ? def.value.getTime() : def.value,
+        input: payload.value,
+        inclusive: def.inclusive,
+        inst,
+        continue: !def.abort,
+      });
+    };
+  }
+);
+
+/////////////////////////////////////
+/////    $YatspCheckGreaterThan    /////
+/////////////////////////////////////
+export interface $YatspCheckGreaterThanDef extends $YatspCheckDef {
+  check: "greater_than";
+  value: util.Numeric;
+  inclusive: boolean;
+}
+
+export interface $YatspCheckGreaterThanInternals<T extends util.Numeric = util.Numeric>
+  extends $YatspCheckInternals<T> {
+  def: $YatspCheckGreaterThanDef;
+  issc: errors.$YatspIssueTooSmall<T>;
+}
+
+export interface $YatspCheckGreaterThan<T extends util.Numeric = util.Numeric> extends $YatspCheck<T> {
+  _yatsp: $YatspCheckGreaterThanInternals<T>;
+}
+
+export const $YatspCheckGreaterThan: core.$constructor<$YatspCheckGreaterThan> = /*@__PURE__*/ core.$constructor(
+  "$YatspCheckGreaterThan",
+  (inst, def) => {
+    $YatspCheck.init(inst, def);
+    const origin = numericOriginMap[typeof def.value as "number" | "bigint" | "object"];
+
+    inst._yatsp.check = (payload) => {
+      if (def.inclusive ? payload.value >= def.value : payload.value > def.value) {
+        return;
+      }
+
+      payload.issues.push({
+        origin: numericOriginMap[typeof payload.value as "number" | "bigint" | "object"] ?? origin,
+        code: "too_small",
+        minimum: typeof def.value === "object" ? def.value.getTime() : def.value,
+        input: payload.value,
+        inclusive: def.inclusive,
+        inst,
+        continue: !def.abort,
+      });
+    };
+  }
+);
+
+/////////////////////////////////////
+/////    $YatspCheckMultipleOf    /////
+/////////////////////////////////////
+// https://stackoverflow.com/questions/3966484/why-does-modulus-operator-return-fractional-number-in-javascript/31711034#31711034
+
+export interface $YatspCheckMultipleOfDef<T extends number | bigint = number | bigint> extends $YatspCheckDef {
+  check: "multiple_of";
+  value: T;
+}
+
+export interface $YatspCheckMultipleOfInternals<T extends number | bigint = number | bigint>
+  extends $YatspCheckInternals<T> {
+  def: $YatspCheckMultipleOfDef<T>;
+  issc: errors.$YatspIssueNotMultipleOf;
+}
+
+export interface $YatspCheckMultipleOf<T extends number | bigint = number | bigint> extends $YatspCheck<T> {
+  _yatsp: $YatspCheckMultipleOfInternals<T>;
+}
+
+export const $YatspCheckMultipleOf: core.$constructor<$YatspCheckMultipleOf<number | bigint>> =
+  /*@__PURE__*/ core.$constructor("$YatspCheckMultipleOf", (inst, def) => {
+    $YatspCheck.init(inst, def);
+
+    inst._yatsp.check = (payload) => {
+      if (typeof payload.value !== typeof def.value)
+        throw new Error("Cannot mix number and bigint in multiple_of check.");
+      const isMultiple =
+        typeof payload.value === "bigint"
+          ? // `value % 0n` throws, and nothing is a multiple of zero — the number branch already fails this way via NaN
+            (def.value as bigint) !== BigInt(0) && payload.value % (def.value as bigint) === BigInt(0)
+          : util.floatSafeRemainder(payload.value, def.value as number) === 0;
+
+      if (isMultiple) return;
+      payload.issues.push({
+        origin: typeof payload.value as "number",
+        code: "not_multiple_of",
+        divisor: def.value as number,
+        input: payload.value,
+        inst,
+        continue: !def.abort,
+      });
+    };
+  });
+
+/////////////////////////////////////
+/////    $YatspCheckFinite    /////
+/////////////////////////////////////
+// interface $YatspCheckFiniteDef extends $YatspCheckDef {
+//   check: "finite";
+// }
+
+// export interface $YatspCheckFinite extends $YatspCheckInternals<number> {
+//   _def: $YatspCheckFiniteDef;
+//   _issc:
+//     | errors.$YatspIssueTooBig<"number", number>
+//     | errors.$YatspIssueTooSmall<"number", number>;
+// }
+
+// export const $YatspCheckFinite: core.$constructor<$YatspCheckFinite> =
+//   core.$constructor("$YatspCheckFinite", (inst, def) => {
+//     $YatspCheck.init(inst, def);
+
+//     inst._yatsp.onattach = (inst) => {
+//       inst["_bag"].finite = true;
+//     };
+
+//     inst._yatsp.check = (payload) => {
+//       if (Number.isFinite(payload.value)) return;
+//       payload.issues.push({
+//         origin: "number",
+//         ...(payload.value === Number.POSITIVE_INFINITY
+//           ? {
+//               code: "too_big",
+//               maximum: Number.POSITIVE_INFINITY,
+//             }
+//           : {
+//               code: "too_small",
+//               minimum: Number.NEGATIVE_INFINITY,
+//             }),
+//         // code: payload.value === Number.POSITIVE_INFINITY ? "too_big" : "too_big",
+//         // maximum: Number.POSITIVE_INFINITY,
+//         inclusive: false,
+//         input: payload.value,
+//         inst,
+//       });
+//     };
+//   });
+
+///////////////////////////////////////
+/////    $YatspCheckNumberFormat    /////
+///////////////////////////////////////
+
+export type $YatspNumberFormats = "int32" | "uint32" | "float32" | "float64" | "safeint";
+
+export interface $YatspCheckNumberFormatDef<Format extends $YatspNumberFormats = $YatspNumberFormats>
+  extends $YatspCheckDef {
+  check: "number_format";
+  format: Format;
+  // abort?: boolean;
+}
+
+export interface $YatspCheckNumberFormatInternals<Format extends $YatspNumberFormats = $YatspNumberFormats>
+  extends $YatspCheckInternals<number> {
+  def: $YatspCheckNumberFormatDef<Format>;
+  issc: errors.$YatspIssueInvalidType | errors.$YatspIssueTooBig<"number"> | errors.$YatspIssueTooSmall<"number">;
+  // bag: util.LoosePartial<{
+  //   minimum?: number | undefined;
+  // }>;
+}
+
+export interface $YatspCheckNumberFormat<Format extends $YatspNumberFormats = $YatspNumberFormats>
+  extends $YatspCheck<number> {
+  _yatsp: $YatspCheckNumberFormatInternals<Format>;
+}
+
+export const $YatspCheckNumberFormat: core.$constructor<$YatspCheckNumberFormat> = /*@__PURE__*/ core.$constructor(
+  "$YatspCheckNumberFormat",
+  (inst, def) => {
+    $YatspCheck.init(inst, def); // no format checks
+    def.format = def.format || "float64";
+
+    const isInt = def.format?.includes("int");
+    const origin = isInt ? "int" : "number";
+    const [minimum, maximum] = util.NUMBER_FORMAT_RANGES[def.format];
+
+    inst._yatsp.check = (payload) => {
+      const input = payload.value;
+
+      if (isInt) {
+        if (!Number.isInteger(input)) {
+          // invalid_format issue
+          // payload.issues.push({
+          //   expected: def.format,
+          //   format: def.format,
+          //   code: "invalid_format",
+          //   input,
+          //   inst,
+          // });
+          // invalid_type issue
+          payload.issues.push({
+            expected: origin,
+            format: def.format,
+            code: "invalid_type",
+            continue: false,
+            input,
+            inst,
+          });
+
+          return;
+
+          // not_multiple_of issue
+          // payload.issues.push({
+          //   code: "not_multiple_of",
+          //   origin: "number",
+          //   input,
+          //   inst,
+          //   divisor: 1,
+          // });
+        }
+        if (!Number.isSafeInteger(input)) {
+          if (input > 0) {
+            // too_big
+            payload.issues.push({
+              input,
+              code: "too_big",
+              maximum: Number.MAX_SAFE_INTEGER,
+              note: "Integers must be within the safe integer range.",
+              inst,
+              origin,
+              inclusive: true,
+              continue: !def.abort,
+            });
+          } else {
+            // too_small
+            payload.issues.push({
+              input,
+              code: "too_small",
+              minimum: Number.MIN_SAFE_INTEGER,
+              note: "Integers must be within the safe integer range.",
+              inst,
+              origin,
+              inclusive: true,
+              continue: !def.abort,
+            });
+          }
+
+          return;
+        }
+      }
+
+      if (input < minimum) {
+        payload.issues.push({
+          origin: "number",
+          input,
+          code: "too_small",
+          minimum,
+          inclusive: true,
+          inst,
+          continue: !def.abort,
+        });
+      }
+
+      if (input > maximum) {
+        payload.issues.push({
+          origin: "number",
+          input,
+          code: "too_big",
+          maximum,
+          inclusive: true,
+          inst,
+          continue: !def.abort,
+        } as any);
+      }
+    };
+  }
+);
+
+/////////////////////////////////////
+/////    $YatspCheckBigIntFormat    /////
+/////////////////////////////////////
+
+export type $YatspBigIntFormats = "int64" | "uint64";
+
+export interface $YatspCheckBigIntFormatDef<Format extends $YatspBigIntFormats = $YatspBigIntFormats>
+  extends $YatspCheckDef {
+  check: "bigint_format";
+  format: Format;
+}
+
+export interface $YatspCheckBigIntFormatInternals<Format extends $YatspBigIntFormats = $YatspBigIntFormats>
+  extends $YatspCheckInternals<bigint> {
+  def: $YatspCheckBigIntFormatDef<Format>;
+  issc: errors.$YatspIssueTooBig<"bigint"> | errors.$YatspIssueTooSmall<"bigint">;
+}
+
+export interface $YatspCheckBigIntFormat<Format extends $YatspBigIntFormats = $YatspBigIntFormats>
+  extends $YatspCheck<bigint> {
+  _yatsp: $YatspCheckBigIntFormatInternals<Format>;
+}
+
+export const $YatspCheckBigIntFormat: core.$constructor<$YatspCheckBigIntFormat> = /*@__PURE__*/ core.$constructor(
+  "$YatspCheckBigIntFormat",
+  (inst, def) => {
+    $YatspCheck.init(inst, def); // no format checks
+
+    const [minimum, maximum] = util.BIGINT_FORMAT_RANGES[def.format];
+
+    inst._yatsp.check = (payload) => {
+      const input = payload.value;
+
+      if (input < minimum) {
+        payload.issues.push({
+          origin: "bigint",
+          input,
+          code: "too_small",
+          minimum: minimum as any,
+          inclusive: true,
+          inst,
+          continue: !def.abort,
+        });
+      }
+
+      if (input > maximum) {
+        payload.issues.push({
+          origin: "bigint",
+          input,
+          code: "too_big",
+          maximum,
+          inclusive: true,
+          inst,
+          continue: !def.abort,
+        } as any);
+      }
+    };
+  }
+);
+
+//////////////////////////////////
+/////    $YatspCheckMaxSize    /////
+//////////////////////////////////
+export interface $YatspCheckMaxSizeDef extends $YatspCheckDef {
+  check: "max_size";
+  maximum: number;
+}
+
+export interface $YatspCheckMaxSizeInternals<T extends util.HasSize = util.HasSize> extends $YatspCheckInternals<T> {
+  def: $YatspCheckMaxSizeDef;
+  issc: errors.$YatspIssueTooBig<T>;
+}
+
+export interface $YatspCheckMaxSize<T extends util.HasSize = util.HasSize> extends $YatspCheck<T> {
+  _yatsp: $YatspCheckMaxSizeInternals<T>;
+}
+
+export const $YatspCheckMaxSize: core.$constructor<$YatspCheckMaxSize> = /*@__PURE__*/ core.$constructor(
+  "$YatspCheckMaxSize",
+  (inst, def) => {
+    $YatspCheck.init(inst, def);
+
+    inst._yatsp.def.when ??= _whenHasSize;
+
+    inst._yatsp.check = (payload) => {
+      const input = payload.value;
+      const size = input.size;
+
+      if (size <= def.maximum) return;
+      payload.issues.push({
+        origin: util.getSizableOrigin(input),
+        code: "too_big",
+        maximum: def.maximum,
+        inclusive: true,
+        input,
+        inst,
+        continue: !def.abort,
+      });
+    };
+  }
+);
+
+//////////////////////////////////
+/////    $YatspCheckMinSize    /////
+//////////////////////////////////
+export interface $YatspCheckMinSizeDef extends $YatspCheckDef {
+  check: "min_size";
+  minimum: number;
+}
+
+export interface $YatspCheckMinSizeInternals<T extends util.HasSize = util.HasSize> extends $YatspCheckInternals<T> {
+  def: $YatspCheckMinSizeDef;
+  issc: errors.$YatspIssueTooSmall<T>;
+}
+
+export interface $YatspCheckMinSize<T extends util.HasSize = util.HasSize> extends $YatspCheck<T> {
+  _yatsp: $YatspCheckMinSizeInternals<T>;
+}
+
+export const $YatspCheckMinSize: core.$constructor<$YatspCheckMinSize> = /*@__PURE__*/ core.$constructor(
+  "$YatspCheckMinSize",
+  (inst, def) => {
+    $YatspCheck.init(inst, def);
+
+    inst._yatsp.def.when ??= _whenHasSize;
+
+    inst._yatsp.check = (payload) => {
+      const input = payload.value;
+      const size = input.size;
+
+      if (size >= def.minimum) return;
+      payload.issues.push({
+        origin: util.getSizableOrigin(input),
+        code: "too_small",
+        minimum: def.minimum,
+        inclusive: true,
+        input,
+        inst,
+        continue: !def.abort,
+      });
+    };
+  }
+);
+
+/////////////////////////////////////
+/////    $YatspCheckSizeEquals    /////
+/////////////////////////////////////
+export interface $YatspCheckSizeEqualsDef extends $YatspCheckDef {
+  check: "size_equals";
+  size: number;
+}
+
+export interface $YatspCheckSizeEqualsInternals<T extends util.HasSize = util.HasSize> extends $YatspCheckInternals<T> {
+  def: $YatspCheckSizeEqualsDef;
+  issc: errors.$YatspIssueTooBig<T> | errors.$YatspIssueTooSmall<T>;
+}
+
+export interface $YatspCheckSizeEquals<T extends util.HasSize = util.HasSize> extends $YatspCheck<T> {
+  _yatsp: $YatspCheckSizeEqualsInternals<T>;
+}
+
+export const $YatspCheckSizeEquals: core.$constructor<$YatspCheckSizeEquals> = /*@__PURE__*/ core.$constructor(
+  "$YatspCheckSizeEquals",
+  (inst, def) => {
+    $YatspCheck.init(inst, def);
+
+    inst._yatsp.def.when ??= _whenHasSize;
+
+    inst._yatsp.check = (payload) => {
+      const input = payload.value;
+      const size = input.size;
+      if (size === def.size) return;
+
+      const tooBig = size > def.size;
+      payload.issues.push({
+        origin: util.getSizableOrigin(input),
+        ...(tooBig ? { code: "too_big", maximum: def.size } : { code: "too_small", minimum: def.size }),
+        inclusive: true,
+        exact: true,
+        input: payload.value,
+        inst,
+        continue: !def.abort,
+      });
+    };
+  }
+);
+
+//////////////////////////////////
+/////    $YatspCheckMaxLength    /////
+//////////////////////////////////
+
+export interface $YatspCheckMaxLengthDef extends $YatspCheckDef {
+  check: "max_length";
+  maximum: number;
+}
+
+export interface $YatspCheckMaxLengthInternals<T extends util.HasLength = util.HasLength>
+  extends $YatspCheckInternals<T> {
+  def: $YatspCheckMaxLengthDef;
+  issc: errors.$YatspIssueTooBig<T>;
+}
+
+export interface $YatspCheckMaxLength<T extends util.HasLength = util.HasLength> extends $YatspCheck<T> {
+  _yatsp: $YatspCheckMaxLengthInternals<T>;
+}
+
+export const $YatspCheckMaxLength: core.$constructor<$YatspCheckMaxLength> = /*@__PURE__*/ core.$constructor(
+  "$YatspCheckMaxLength",
+  (inst, def) => {
+    $YatspCheck.init(inst, def);
+
+    inst._yatsp.def.when ??= _whenHasLength;
+
+    inst._yatsp.check = (payload) => {
+      const input = payload.value;
+      const units = input.length;
+      // Strings are measured in Unicode code points, not UTF-16 units. A code point is at most two units, so a string that already fits in units fits in code points; only an overflow has to be counted.
+      const length = typeof input === "string" && units > def.maximum ? util.codePointLength(input) : units;
+
+      if (length <= def.maximum) return;
+      const origin = util.getLengthableOrigin(input);
+      payload.issues.push({
+        origin,
+        code: "too_big",
+        maximum: def.maximum,
+        inclusive: true,
+        input,
+        inst,
+        continue: !def.abort,
+      });
+    };
+  }
+);
+
+//////////////////////////////////
+/////    $YatspCheckMinLength    /////
+//////////////////////////////////
+export interface $YatspCheckMinLengthDef extends $YatspCheckDef {
+  check: "min_length";
+  minimum: number;
+}
+
+export interface $YatspCheckMinLengthInternals<T extends util.HasLength = util.HasLength>
+  extends $YatspCheckInternals<T> {
+  def: $YatspCheckMinLengthDef;
+  issc: errors.$YatspIssueTooSmall<T>;
+}
+
+export interface $YatspCheckMinLength<T extends util.HasLength = util.HasLength> extends $YatspCheck<T> {
+  _yatsp: $YatspCheckMinLengthInternals<T>;
+}
+
+export const $YatspCheckMinLength: core.$constructor<$YatspCheckMinLength> = /*@__PURE__*/ core.$constructor(
+  "$YatspCheckMinLength",
+  (inst, def) => {
+    $YatspCheck.init(inst, def);
+
+    inst._yatsp.def.when ??= _whenHasLength;
+
+    inst._yatsp.check = (payload) => {
+      const input = payload.value;
+      const units = input.length;
+      // A code point is one or two UTF-16 units, so fewer units than the floor can never reach it and twice the floor always clears it. Only in between is the exact count in doubt.
+      const length =
+        typeof input === "string" && units >= def.minimum && units < def.minimum * 2
+          ? util.codePointLength(input)
+          : units;
+
+      if (length >= def.minimum) return;
+      const origin = util.getLengthableOrigin(input);
+      payload.issues.push({
+        origin,
+        code: "too_small",
+        minimum: def.minimum,
+        inclusive: true,
+        input,
+        inst,
+        continue: !def.abort,
+      });
+    };
+  }
+);
+
+/////////////////////////////////////
+/////    $YatspCheckLengthEquals    /////
+/////////////////////////////////////
+export interface $YatspCheckLengthEqualsDef extends $YatspCheckDef {
+  check: "length_equals";
+  length: number;
+}
+
+export interface $YatspCheckLengthEqualsInternals<T extends util.HasLength = util.HasLength>
+  extends $YatspCheckInternals<T> {
+  def: $YatspCheckLengthEqualsDef;
+  issc: errors.$YatspIssueTooBig<T> | errors.$YatspIssueTooSmall<T>;
+}
+
+export interface $YatspCheckLengthEquals<T extends util.HasLength = util.HasLength> extends $YatspCheck<T> {
+  _yatsp: $YatspCheckLengthEqualsInternals<T>;
+}
+
+export const $YatspCheckLengthEquals: core.$constructor<$YatspCheckLengthEquals> = /*@__PURE__*/ core.$constructor(
+  "$YatspCheckLengthEquals",
+  (inst, def) => {
+    $YatspCheck.init(inst, def);
+
+    inst._yatsp.def.when ??= _whenHasLength;
+
+    inst._yatsp.check = (payload) => {
+      const input = payload.value;
+      const units = input.length;
+      // A code point is one or two UTF-16 units, so outside `[length, length * 2]` units the target is missed either way — and missed in the same direction in both measures.
+      const length =
+        typeof input === "string" && units >= def.length && units <= def.length * 2
+          ? util.codePointLength(input)
+          : units;
+      if (length === def.length) return;
+      const origin = util.getLengthableOrigin(input);
+      const tooBig = length > def.length;
+      payload.issues.push({
+        origin,
+        ...(tooBig ? { code: "too_big", maximum: def.length } : { code: "too_small", minimum: def.length }),
+        inclusive: true,
+        exact: true,
+        input: payload.value,
+        inst,
+        continue: !def.abort,
+      });
+    };
+  }
+);
+
+/////////////////////////////////////////////
+/////    $YatspCheckStringFormatRegex    /////
+/////////////////////////////////////////////
+export type $YatspStringFormats =
+  | "email"
+  | "url"
+  | "emoji"
+  | "uuid"
+  | "guid"
+  | "nanoid"
+  | "cuid"
+  | "cuid2"
+  | "ulid"
+  | "xid"
+  | "ksuid"
+  | "datetime"
+  | "date"
+  | "time"
+  | "duration"
+  | "ipv4"
+  | "ipv6"
+  | "cidrv4"
+  | "cidrv6"
+  | "base64"
+  | "base64url"
+  | "json_string"
+  | "e164"
+  | "credit_card"
+  | "iban"
+  | "lowercase"
+  | "uppercase"
+  | "regex"
+  | "jwt"
+  | "starts_with"
+  | "ends_with"
+  | "includes";
+export interface $YatspCheckStringFormatDef<Format extends string = string> extends $YatspCheckDef {
+  check: "string_format";
+  format: Format;
+  pattern?: RegExp | undefined;
+}
+
+export interface $YatspCheckStringFormatInternals extends $YatspCheckInternals<string> {
+  def: $YatspCheckStringFormatDef;
+  issc: errors.$YatspIssueInvalidStringFormat;
+}
+
+export interface $YatspCheckStringFormat extends $YatspCheck<string> {
+  _yatsp: $YatspCheckStringFormatInternals;
+}
+
+export const $YatspCheckStringFormat: core.$constructor<$YatspCheckStringFormat> = /*@__PURE__*/ core.$constructor(
+  "$YatspCheckStringFormat",
+  (inst, def) => {
+    $YatspCheck.init(inst, def);
+
+    if (def.pattern)
+      inst._yatsp.check ??= (payload) => {
+        def.pattern!.lastIndex = 0;
+        if (def.pattern!.test(payload.value)) return;
+        payload.issues.push({
+          origin: "string",
+          code: "invalid_format",
+          format: def.format,
+          input: payload.value,
+          ...(def.pattern ? { pattern: def.pattern.toString() } : {}),
+          inst,
+          continue: !def.abort,
+        });
+      };
+    else inst._yatsp.check ??= () => {};
+  }
+);
+
+////////////////////////////////
+/////    $YatspCheckRegex    /////
+////////////////////////////////
+export interface $YatspCheckRegexDef extends $YatspCheckStringFormatDef {
+  format: "regex";
+  pattern: RegExp;
+}
+
+export interface $YatspCheckRegexInternals extends $YatspCheckInternals<string> {
+  def: $YatspCheckRegexDef;
+  issc: errors.$YatspIssueInvalidStringFormat;
+}
+
+export interface $YatspCheckRegex extends $YatspCheck<string> {
+  _yatsp: $YatspCheckRegexInternals;
+}
+
+export const $YatspCheckRegex: core.$constructor<$YatspCheckRegex> = /*@__PURE__*/ core.$constructor(
+  "$YatspCheckRegex",
+  (inst, def) => {
+    $YatspCheckStringFormat.init(inst, def);
+
+    inst._yatsp.check = (payload) => {
+      def.pattern.lastIndex = 0;
+      if (def.pattern.test(payload.value)) return;
+      payload.issues.push({
+        origin: "string",
+        code: "invalid_format",
+        format: "regex",
+        input: payload.value,
+        pattern: def.pattern.toString(),
+        inst,
+        continue: !def.abort,
+      });
+    };
+  }
+);
+
+///////////////////////////////////
+/////    $YatspCheckJSONString    /////
+///////////////////////////////////
+// interface $YatspCheckJSONStringDef extends $YatspCheckStringFormatDef<"json_string"> {
+//   // check: "string_format";
+//   // format: "json_string";
+//   // error?: errors.$YatspErrorMap<errors.$YatspIssueInvalidStringFormat> | undefined;
+// }
+
+// export interface $YatspCheckJSONString extends $YatspCheckStringFormat {
+//   _def: $YatspCheckJSONStringDef;
+// }
+
+// export const $YatspCheckJSONString: core.$constructor<$YatspCheckJSONString> = /*@__PURE__*/ core.$constructor(
+//   "$YatspCheckJSONString",
+//   (inst, def) => {
+//     $YatspCheck.init(inst, def);
+
+//     inst._yatsp.check = (payload) => {
+//       try {
+//         JSON.parse(payload.value);
+//         return;
+//       } catch (_) {
+//         payload.issues.push({
+//           origin: "string",
+//           code: "invalid_format",
+//           format: def.format,
+//           input: payload.value,
+//           inst,
+//           continue: !def.abort,
+//         });
+//       }
+//     };
+//   }
+// );
+
+//////////////////////////////////////
+/////    $YatspCheckLowerCase    /////
+//////////////////////////////////////
+export interface $YatspCheckLowerCaseDef extends $YatspCheckStringFormatDef<"lowercase"> {}
+
+export interface $YatspCheckLowerCaseInternals extends $YatspCheckInternals<string> {
+  def: $YatspCheckLowerCaseDef;
+  issc: errors.$YatspIssueInvalidStringFormat;
+}
+
+export interface $YatspCheckLowerCase extends $YatspCheck<string> {
+  _yatsp: $YatspCheckLowerCaseInternals;
+}
+
+export const $YatspCheckLowerCase: core.$constructor<$YatspCheckLowerCase> = /*@__PURE__*/ core.$constructor(
+  "$YatspCheckLowerCase",
+  (inst, def) => {
+    def.pattern ??= regexes.lowercase;
+    $YatspCheckStringFormat.init(inst, def);
+  }
+);
+
+//////////////////////////////////////
+/////    $YatspCheckUpperCase    /////
+//////////////////////////////////////
+export interface $YatspCheckUpperCaseDef extends $YatspCheckStringFormatDef<"uppercase"> {}
+
+export interface $YatspCheckUpperCaseInternals extends $YatspCheckInternals<string> {
+  def: $YatspCheckUpperCaseDef;
+  issc: errors.$YatspIssueInvalidStringFormat;
+}
+
+export interface $YatspCheckUpperCase extends $YatspCheck<string> {
+  _yatsp: $YatspCheckUpperCaseInternals;
+}
+
+export const $YatspCheckUpperCase: core.$constructor<$YatspCheckUpperCase> = /*@__PURE__*/ core.$constructor(
+  "$YatspCheckUpperCase",
+  (inst, def) => {
+    def.pattern ??= regexes.uppercase;
+    $YatspCheckStringFormat.init(inst, def);
+  }
+);
+
+///////////////////////////////////
+/////    $YatspCheckIncludes    /////
+///////////////////////////////////
+export interface $YatspCheckIncludesDef extends $YatspCheckStringFormatDef<"includes"> {
+  includes: string;
+  position?: number | undefined;
+}
+
+export interface $YatspCheckIncludesInternals extends $YatspCheckInternals<string> {
+  def: $YatspCheckIncludesDef;
+  issc: errors.$YatspIssueInvalidStringFormat;
+}
+
+export interface $YatspCheckIncludes extends $YatspCheck<string> {
+  _yatsp: $YatspCheckIncludesInternals;
+}
+
+export const $YatspCheckIncludes: core.$constructor<$YatspCheckIncludes> = /*@__PURE__*/ core.$constructor(
+  "$YatspCheckIncludes",
+  (inst, def) => {
+    $YatspCheck.init(inst, def);
+
+    const escapedRegex = util.escapeRegex(def.includes);
+    // `String.prototype.includes(sub, position)` matches `sub` at `position`
+    // OR LATER, so the pattern must allow at least `position` leading chars
+    // (`{N,}`), not exactly `position` chars (`{N}`).
+    const pattern = new RegExp(typeof def.position === "number" ? `^.{${def.position},}${escapedRegex}` : escapedRegex);
+    def.pattern = pattern;
+    inst._yatsp.check = (payload) => {
+      if (payload.value.includes(def.includes, def.position)) return;
+      payload.issues.push({
+        origin: "string",
+        code: "invalid_format",
+        format: "includes",
+        includes: def.includes,
+        input: payload.value,
+        inst,
+        continue: !def.abort,
+      });
+    };
+  }
+);
+
+/////////////////////////////////////
+/////    $YatspCheckStartsWith    /////
+/////////////////////////////////////
+export interface $YatspCheckStartsWithDef extends $YatspCheckStringFormatDef<"starts_with"> {
+  prefix: string;
+}
+
+export interface $YatspCheckStartsWithInternals extends $YatspCheckInternals<string> {
+  def: $YatspCheckStartsWithDef;
+  issc: errors.$YatspIssueInvalidStringFormat;
+}
+
+export interface $YatspCheckStartsWith extends $YatspCheck<string> {
+  _yatsp: $YatspCheckStartsWithInternals;
+}
+
+export const $YatspCheckStartsWith: core.$constructor<$YatspCheckStartsWith> = /*@__PURE__*/ core.$constructor(
+  "$YatspCheckStartsWith",
+  (inst, def) => {
+    $YatspCheck.init(inst, def);
+
+    const pattern = new RegExp(`^${util.escapeRegex(def.prefix)}.*`);
+    def.pattern ??= pattern;
+    inst._yatsp.check = (payload) => {
+      if (payload.value.startsWith(def.prefix)) return;
+      payload.issues.push({
+        origin: "string",
+        code: "invalid_format",
+        format: "starts_with",
+        prefix: def.prefix,
+        input: payload.value,
+        inst,
+        continue: !def.abort,
+      });
+    };
+  }
+);
+
+//////////////////////////////////
+/////   $YatspCheckEndsWith    /////
+//////////////////////////////////
+export interface $YatspCheckEndsWithDef extends $YatspCheckStringFormatDef<"ends_with"> {
+  suffix: string;
+}
+
+export interface $YatspCheckEndsWithInternals extends $YatspCheckInternals<string> {
+  def: $YatspCheckEndsWithDef;
+  issc: errors.$YatspIssueInvalidStringFormat;
+}
+
+export interface $YatspCheckEndsWith extends $YatspCheckInternals<string> {
+  _yatsp: $YatspCheckEndsWithInternals;
+}
+
+export const $YatspCheckEndsWith: core.$constructor<$YatspCheckEndsWith> = /*@__PURE__*/ core.$constructor(
+  "$YatspCheckEndsWith",
+  (inst, def) => {
+    $YatspCheck.init(inst, def);
+
+    const pattern = new RegExp(`.*${util.escapeRegex(def.suffix)}$`);
+    def.pattern ??= pattern;
+    inst._yatsp.check = (payload) => {
+      if (payload.value.endsWith(def.suffix)) return;
+      payload.issues.push({
+        origin: "string",
+        code: "invalid_format",
+        format: "ends_with",
+        suffix: def.suffix,
+        input: payload.value,
+        inst,
+        continue: !def.abort,
+      });
+    };
+  }
+);
+
+///////////////////////////////////
+/////    $YatspCheckProperty    /////
+///////////////////////////////////
+function handleCheckPropertyResult(
+  result: schemas.ParsePayload<unknown>,
+  payload: schemas.ParsePayload<unknown>,
+  property: string | symbol
+) {
+  if (result.issues.length) {
+    payload.issues.push(...util.prefixIssues(property, result.issues));
+  }
+}
+export interface $YatspCheckPropertyDef extends $YatspCheckDef {
+  check: "property";
+  property: string;
+  schema: schemas.$YatspType;
+}
+
+export interface $YatspCheckPropertyInternals<T extends object = object> extends $YatspCheckInternals<T> {
+  def: $YatspCheckPropertyDef;
+  issc: errors.$YatspIssue;
+}
+
+export interface $YatspCheckProperty<T extends object = object> extends $YatspCheck<T> {
+  _yatsp: $YatspCheckPropertyInternals<T>;
+}
+
+export const $YatspCheckProperty: core.$constructor<$YatspCheckProperty> = /*@__PURE__*/ core.$constructor(
+  "$YatspCheckProperty",
+  (inst, def) => {
+    $YatspCheck.init(inst, def);
+
+    inst._yatsp.check = (payload) => {
+      const result = def.schema._yatsp.run(
+        {
+          value: (payload.value as any)[def.property],
+          issues: [],
+        },
+        {}
+      );
+
+      if (result instanceof Promise) {
+        return result.then((result) => handleCheckPropertyResult(result, payload, def.property));
+      }
+
+      handleCheckPropertyResult(result, payload, def.property);
+      return;
+    };
+  }
+);
+
+/////////////////////////////////////
+/////    $YatspCheckProperties    /////
+/////////////////////////////////////
+export interface $YatspCheckPropertiesDef<Shape extends schemas.$YatspShape = schemas.$YatspShape>
+  extends $YatspCheckDef {
+  check: "properties";
+  shape: Shape;
+}
+
+// typed over the input side, since each child's result is discarded; a literal widens to its primitive so spreading over a `string` property still type-checks (#6520)
+export type $YatspCheckPropertiesInput<Shape extends schemas.$YatspShape = schemas.$YatspShape> = {
+  -readonly [k in keyof Shape]: util.Widen<core.input<Shape[k]>>;
+};
+
+export interface $YatspCheckPropertiesInternals<Shape extends schemas.$YatspShape = schemas.$YatspShape>
+  extends $YatspCheckInternals<$YatspCheckPropertiesInput<Shape>> {
+  def: $YatspCheckPropertiesDef<Shape>;
+  issc: errors.$YatspIssue;
+}
+
+export interface $YatspCheckProperties<Shape extends schemas.$YatspShape = schemas.$YatspShape>
+  extends $YatspCheck<$YatspCheckPropertiesInput<Shape>> {
+  _yatsp: $YatspCheckPropertiesInternals<Shape>;
+  // yields the check itself, so `.check(...z.properties(shape))` spread call sites keep working
+  [Symbol.iterator](): Iterator<this>;
+}
+
+export const $YatspCheckProperties: core.$constructor<$YatspCheckProperties> = /*@__PURE__*/ core.$constructor(
+  "$YatspCheckProperties",
+  (inst, def) => {
+    $YatspCheck.init(inst, def);
+    util.hide(inst, Symbol.iterator, function* () {
+      yield inst;
+    });
+
+    // key and schema snapshotted together: reading one live and the other cached lets a later mutation of the caller's shape object pair a stale key with a missing schema
+    let entries!: [string | symbol, schemas.$YatspType][];
+    inst._yatsp.check = (payload) => {
+      // the base schema already typed the value, so only a nullish one is rejected here: the properties read on a primitive too, matching z.property() on a string's length
+      if (payload.value == null) {
+        payload.issues.push({ expected: "object", code: "invalid_type", input: payload.value, inst });
+        return undefined;
+      }
+      entries ??= Reflect.ownKeys(def.shape).map((key) => [key, (def.shape as any)[key] as schemas.$YatspType]);
+      const input = payload.value as any;
+      let proms: Promise<any>[] | undefined;
+      for (const [key, schema] of entries) {
+        const result = schema._yatsp.run({ value: input[key], issues: [] }, {});
+        if (result instanceof Promise) {
+          proms ??= [];
+          proms.push(result.then((result) => handleCheckPropertyResult(result, payload, key)));
+        } else {
+          handleCheckPropertyResult(result, payload, key);
+        }
+      }
+      if (proms) return Promise.all(proms).then(() => undefined);
+      return undefined;
+    };
+  }
+);
+
+///////////////////////////////////
+/////    $YatspCheckMimeType    /////
+///////////////////////////////////
+export interface $YatspCheckMimeTypeDef extends $YatspCheckDef {
+  check: "mime_type";
+  mime: util.MimeTypes[];
+}
+
+export interface $YatspCheckMimeTypeInternals<T extends schemas.File = schemas.File> extends $YatspCheckInternals<T> {
+  def: $YatspCheckMimeTypeDef;
+  issc: errors.$YatspIssueInvalidValue;
+}
+
+export interface $YatspCheckMimeType<T extends schemas.File = schemas.File> extends $YatspCheck<T> {
+  _yatsp: $YatspCheckMimeTypeInternals<T>;
+}
+
+export const $YatspCheckMimeType: core.$constructor<$YatspCheckMimeType> = /*@__PURE__*/ core.$constructor(
+  "$YatspCheckMimeType",
+  (inst, def) => {
+    $YatspCheck.init(inst, def);
+    const mimeSet = new Set(def.mime);
+    inst._yatsp.check = (payload) => {
+      if (mimeSet.has(payload.value.type)) return;
+      payload.issues.push({
+        code: "invalid_value",
+        values: def.mime,
+        input: payload.value.type,
+        inst,
+        continue: !def.abort,
+      });
+    };
+  }
+);
+
+///////////////////////////////////
+/////    $YatspCheckFileName    /////
+///////////////////////////////////
+// interface $YatspCheckFileNameDef extends $YatspCheckDef {
+//   check: "file_name";
+//   fileName: string;
+//   error?: errors.$YatspErrorMap<errors.$YatspIssueInvalidType> | undefined;
+// }
+// export interface $YatspCheckFileName<T extends File = File>
+//   extends $YatspCheckInternals<T> {
+//   _def: $YatspCheckFileNameDef;
+// }
+
+// export const $YatspCheckFileName: core.$constructor<$YatspCheckFileName> =
+//   core.$constructor("$YatspCheckFileName", (inst, def) => {
+//     $YatspCheck.init(inst, def);
+
+//     inst._yatsp.check = (payload) => {
+//       if (def.fileName === payload.value.name) return;
+//       payload.issues.push({
+//         origin: "file",
+//         code: "invalid_value",
+//         options: [def.fileName],
+//         input: payload.value,
+//         path: ["name"],
+//         inst,
+//       });
+//     };
+//   });
+
+///////////////////////////////////
+/////    $YatspCheckOverwrite    /////
+///////////////////////////////////
+export interface $YatspCheckOverwriteDef<T = unknown> extends $YatspCheckDef {
+  check: "overwrite";
+  tx(value: T): T;
+}
+
+export interface $YatspCheckOverwriteInternals<T = unknown> extends $YatspCheckInternals<T> {
+  def: $YatspCheckOverwriteDef<T>;
+  issc: never;
+}
+
+export interface $YatspCheckOverwrite<T = unknown> extends $YatspCheck<T> {
+  _yatsp: $YatspCheckOverwriteInternals<T>;
+}
+
+export const $YatspCheckOverwrite: core.$constructor<$YatspCheckOverwrite> = /*@__PURE__*/ core.$constructor(
+  "$YatspCheckOverwrite",
+  (inst, def) => {
+    $YatspCheck.init(inst, def);
+
+    inst._yatsp.check = (payload) => {
+      payload.value = def.tx(payload.value);
+    };
+  }
+);
+
+// ///////////////////////////////
+// /////    $YatspCheckTrim    /////
+// ///////////////////////////////
+// export interface $YatspCheckTrimDef extends $YatspCheckDef {
+//   check: "trim";
+//   error?: errors.$YatspErrorMap<never> | undefined;
+// }
+// export interface $YatspCheckTrim extends $YatspCheckInternals<string> {
+//   _def: $YatspCheckTrimDef;
+// }
+
+// export const $YatspCheckTrim: core.$constructor<$YatspCheckTrim> =
+//   core.$constructor("$YatspCheckTrim", (inst, def) => {
+//     $YatspCheck.init(inst, def);
+
+//     inst._yatsp.check = (payload) => {
+//       payload.value = payload.value.trim();
+//     };
+//   });
+
+// //////////////////////////////////////
+// /////    $YatspCheckNormalize    /////
+// //////////////////////////////////////
+// interface $YatspCheckNormalizeDef extends $YatspCheckDef {
+//   check: "normalize";
+//   error?: errors.$YatspErrorMap<never> | undefined;
+// }
+
+// export interface $YatspCheckNormalize extends $YatspCheckInternals<string> {
+//   _def: $YatspCheckNormalizeDef;
+// }
+
+// export const $YatspCheckNormalize: core.$constructor<$YatspCheckNormalize> =
+//   core.$constructor("$YatspCheckNormalize", (inst, def) => {
+//     $YatspCheck.init(inst, def);
+
+//     inst._yatsp.check = (payload) => {
+//       payload.value = payload.value.normalize();
+//     };
+//   });
+
+export type $YatspChecks =
+  | $YatspCheckLessThan
+  | $YatspCheckGreaterThan
+  | $YatspCheckMultipleOf
+  | $YatspCheckNumberFormat
+  | $YatspCheckBigIntFormat
+  | $YatspCheckMaxSize
+  | $YatspCheckMinSize
+  | $YatspCheckSizeEquals
+  | $YatspCheckMaxLength
+  | $YatspCheckMinLength
+  | $YatspCheckLengthEquals
+  | $YatspCheckStringFormat
+  | $YatspCheckProperty
+  | $YatspCheckMimeType
+  | $YatspCheckOverwrite;
+
+export type $YatspStringFormatChecks =
+  | $YatspCheckRegex
+  | $YatspCheckLowerCase
+  | $YatspCheckUpperCase
+  | $YatspCheckIncludes
+  | $YatspCheckStartsWith
+  | $YatspCheckEndsWith
+  | schemas.$YatspStringFormatTypes; // union of string format schema types