regor 1.4.8 → 1.5.0

package/README.md

@@ -152,11 +152,13 @@ pval.isBoolean
 pval.isClass(MyClass)
 pval.optional(pval.isString)
 pval.nullable(pval.isNumber)
+pval.or(pval.isString, pval.isNumber)
 pval.oneOf(['create', 'edit'] as const)
 pval.arrayOf(pval.isString)
 pval.shape({ title: pval.isString, count: pval.isNumber })
 pval.refOf(pval.isString)
-pval.fail('title', 'expected non-empty string')
+pval.describe('value')
+pval.fail('title', 'expected non-empty string, got string ("")')
 ```
 
 ### Dynamic bindings and refs
@@ -204,7 +206,7 @@ import { pval, type PropValidator } from 'regor'
 
 const isNonEmptyString: PropValidator<string> = (value, name) => {
   if (typeof value !== 'string' || value.trim() === '') {
-    pval.fail(name, 'expected non-empty string')
+    pval.fail(name, `expected non-empty string, ${pval.describe(value)}`)
   }
 }
 
@@ -219,7 +221,7 @@ Custom validators can also use the third `head` argument:
 const startsWithPrefix: PropValidator<string> = (value, name, head) => {
   const ctx = head.requireContext(AppServices)
   if (typeof value !== 'string' || !value.startsWith(ctx.prefix)) {
-    pval.fail(name, 'expected prefixed value')
+    pval.fail(name, `expected prefixed value, ${pval.describe(value)}`)
   }
 }
 ```

package/dist/regor.d.ts

@@ -13,6 +13,12 @@
  */
 export type PropValidator<TValue = unknown> = (value: unknown, name: string, head: ComponentHead<any>) => asserts value is TValue;
 export type ValidationSchemaLike = Record<string, PropValidator<any>>;
+export type ValidatorTuple = readonly [
+	PropValidator<any>,
+	PropValidator<any>,
+	...PropValidator<any>[]
+];
+export type InferValidatorValue<TValidator> = TValidator extends PropValidator<infer TValue> ? TValue : never;
 /**
  * Validation schema shape suggested by `ComponentHead<T>.props`.
  *
@@ -34,8 +40,8 @@ export type InferPropValidationSchema<TSchema extends Record<string, unknown>> =
  * Built-in prop-validator namespace used with `head.validateProps(...)`.
  *
  * This namespace includes both ready-made validators and composition helpers.
- * Custom validators can also use `pval.fail(...)` to produce the same
- * structured failure shape as Regor's built-in validators.
+ * Custom validators can also use `pval.fail(...)` and `pval.describe(...)`
+ * to produce messages in the same style as Regor's built-in validators.
  *
  * Example:
  * ```ts
@@ -50,12 +56,14 @@ export type InferPropValidationSchema<TSchema extends Record<string, unknown>> =
  */
 export declare const pval: {
 	readonly fail: (name: string, message: string) => never;
+	readonly describe: (value: unknown) => string;
 	readonly isString: PropValidator<string>;
 	readonly isNumber: PropValidator<number>;
 	readonly isBoolean: PropValidator<boolean>;
 	readonly isClass: <TValue extends object>(ctor: abstract new (...args: any[]) => TValue) => PropValidator<TValue>;
 	readonly optional: <TValue>(validator: PropValidator<TValue>) => PropValidator<TValue | undefined>;
 	readonly nullable: <TValue>(validator: PropValidator<TValue>) => PropValidator<TValue | null>;
+	readonly or: <TValidators extends ValidatorTuple>(...validators: TValidators) => PropValidator<InferValidatorValue<TValidators[number]>>;
 	readonly oneOf: <const TValue extends readonly unknown[]>(values: TValue) => PropValidator<TValue[number]>;
 	readonly arrayOf: <TValue>(validator: PropValidator<TValue>) => PropValidator<TValue[]>;
 	readonly shape: <TSchema extends ValidationSchemaLike>(schema: TSchema) => PropValidator<InferPropValidationSchema<TSchema>>;

package/dist/regor.es2015.cjs.js

@@ -301,6 +301,9 @@ var describeValue = (value) => {
   var _a;
   if (value === null) return "null";
   if (value === void 0) return "undefined";
+  if (isRef(value)) {
+    return `ref<${describeValue(value())}>`;
+  }
   if (typeof value === "string") return "string";
   if (typeof value === "number") return "number";
   if (typeof value === "boolean") return "boolean";
@@ -315,6 +318,64 @@ var describeValue = (value) => {
   const ctorName = (_a = value == null ? void 0 : value.constructor) == null ? void 0 : _a.name;
   return ctorName && ctorName !== "Object" ? ctorName : "object";
 };
+var trimPreview = (value) => {
+  return value.length > 60 ? `${value.slice(0, 57)}...` : value;
+};
+var formatPreview = (value, depth = 0) => {
+  const maxPreviewDepth = 1;
+  const maxArrayItems = 5;
+  const maxObjectEntries = 5;
+  if (depth > maxPreviewDepth) return "unknown";
+  if (isRef(value)) {
+    const refValue = value();
+    return `ref(${formatPreview(refValue, depth + 1)})`;
+  }
+  if (typeof value === "string") return trimPreview(JSON.stringify(value));
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+    return String(value);
+  }
+  if (typeof value === "symbol") return String(value);
+  if (value === null) return "null";
+  if (value === void 0) return "undefined";
+  if (value instanceof Date) return value.toISOString();
+  if (value instanceof RegExp) return String(value);
+  if (isArray(value)) {
+    const items = value.slice(0, maxArrayItems).map((x) => formatPreview(x, depth + 1)).join(", ");
+    return value.length > maxArrayItems ? `[${items}, ...]` : `[${items}]`;
+  }
+  if (isObject(value)) {
+    const entries = Object.entries(value).slice(0, maxObjectEntries);
+    if (entries.length === 0) return "{}";
+    const text = entries.map(([key, entry]) => {
+      const preview = formatPreview(entry, depth + 1);
+      return `${key}: ${preview}`;
+    }).join(", ");
+    return Object.keys(value).length > maxObjectEntries ? `{ ${text}, ... }` : `{ ${text} }`;
+  }
+  return "unknown";
+};
+var describe = (value) => {
+  const type = describeValue(value);
+  const preview = formatPreview(value);
+  return `got ${type} (${preview})`;
+};
+var getErrorDetail = (error) => {
+  if (error instanceof PropValidationError) return error.detail;
+  if (error instanceof Error) return error.message;
+  return String(error);
+};
+var formatOrDetail = (errors2, value) => {
+  const received = `, ${describe(value)}.`;
+  const reasons = [];
+  for (const error of errors2) {
+    const detail = getErrorDetail(error);
+    const reason = detail.endsWith(received) ? detail.slice(0, -received.length) : detail;
+    if (!reasons.includes(reason)) reasons.push(reason);
+  }
+  if (reasons.length === 0) return describe(value);
+  if (reasons.length === 1) return `${reasons[0]}, ${describe(value)}`;
+  return `${reasons.join(" or ")}, ${describe(value)}`;
+};
 var formatLiteral = (value) => {
   if (typeof value === "string") return `"${value}"`;
   if (typeof value === "number" || typeof value === "boolean") {
@@ -325,18 +386,24 @@ var formatLiteral = (value) => {
   return describeValue(value);
 };
 var isString2 = (value, name) => {
-  if (typeof value !== "string") fail(name, "expected string");
+  if (typeof value !== "string")
+    fail(name, `expected string, ${describe(value)}`);
 };
 var isNumber = (value, name) => {
-  if (typeof value !== "number") fail(name, "expected number");
+  if (typeof value !== "number")
+    fail(name, `expected number, ${describe(value)}`);
 };
 var isBoolean = (value, name) => {
-  if (typeof value !== "boolean") fail(name, "expected boolean");
+  if (typeof value !== "boolean")
+    fail(name, `expected boolean, ${describe(value)}`);
 };
 var isClass = (ctor) => {
   return (value, name) => {
     if (!(value instanceof ctor)) {
-      fail(name, `expected instance of ${ctor.name || "provided class"}`);
+      fail(
+        name,
+        `expected instance of ${ctor.name || "provided class"}, ${describe(value)}`
+      );
     }
   };
 };
@@ -352,18 +419,32 @@ var nullable = (validator) => {
     validator(value, name, head);
   };
 };
+var or = (...validators) => {
+  return (value, name, head) => {
+    const errors2 = [];
+    for (const validator of validators) {
+      try {
+        validator(value, name, head);
+        return;
+      } catch (error) {
+        errors2.push(error);
+      }
+    }
+    fail(name, formatOrDetail(errors2, value));
+  };
+};
 var oneOf = (values) => {
   return (value, name) => {
     if (values.includes(value)) return;
     fail(
       name,
-      `expected one of ${values.map((x) => formatLiteral(x)).join(", ")}`
+      `expected one of ${values.map((x) => formatLiteral(x)).join(", ")}, ${describe(value)}`
     );
   };
 };
 var arrayOf = (validator) => {
   return (value, name, head) => {
-    if (!isArray(value)) fail(name, "expected array");
+    if (!isArray(value)) fail(name, `expected array, ${describe(value)}`);
     const items = value;
     for (let i = 0; i < items.length; ++i) {
       validator(items[i], `${name}[${i}]`, head);
@@ -372,7 +453,7 @@ var arrayOf = (validator) => {
 };
 var shape = (schema) => {
   return (value, name, head) => {
-    if (!isObject(value)) fail(name, "expected object");
+    if (!isObject(value)) fail(name, `expected object, ${describe(value)}`);
     const record = value;
     for (const key in schema) {
       const validator = schema[key];
@@ -382,19 +463,23 @@ var shape = (schema) => {
 };
 var refOf = (validator) => {
   return (value, name, head) => {
-    if (!isRef(value)) fail(name, "expected ref");
-    const refValue = value;
-    validator(refValue(), `${name}.value`, head);
+    if (isRef(value)) {
+      validator(value(), `${name}.value`, head);
+      return;
+    }
+    fail(name, `expected ref, ${describe(value)}`);
   };
 };
 var pval = {
   fail,
+  describe,
   isString: isString2,
   isNumber,
   isBoolean,
   isClass,
   optional,
   nullable,
+  or,
   oneOf,
   arrayOf,
   shape,