@maroonedog/luq 2.6.0 → 2.7.0

package/README.md

@@ -140,6 +140,7 @@ if (!result.valid) {
     // issue.code  "stringMin"   — which rule; the vocabulary is pinned
     // issue.message             — the text, overridable per call
     // issue.severity "error"    — only "error" makes the value invalid
+    // issue.causes              — present only on a composite: why it failed
   }
 }
 ```
@@ -155,6 +156,12 @@ missing field both report `required`. Codes a gate carries (`skip`,
 `validateIf`) sit in a separate list: they are accepted from a caller but no
 issue can ever carry one.
 
+A composite reports which applicator failed — `allOf`, `anyOf`, `oneOf` — and
+that code cannot say why. `issue.causes` carries the branch failures behind it,
+each a full issue with its own code, so `allOf` can be read down to the
+`stringMin` underneath it. The key is **absent** on an ordinary issue rather
+than present and undefined, so `"causes" in issue` is a question worth asking.
+
 `.v(path, chain)` declares rules for one field. A path you do not declare is
 not validated, not required and not read, so covering a type partly is a normal
 state rather than a half-finished one.
@@ -215,7 +222,11 @@ accounts.pickAll(["email"]); //             several fields, same plan
 
 `validate` and `parse` return the same discriminated union: `{ valid: true,
 data, issues }` or `{ valid: false, issues }`. `validate` hands back the object
-you passed, by identity, when nothing was written.
+you passed, by identity, when nothing was written. Only `parse` runs your
+transform functions, so only `parse` can throw what one of them throws: a throw
+from a transform is a programmer error, not a validation issue, and zod, valibot
+and yup all propagate it the same way. To reject a value instead, use a check
+such as [`custom`](https://luq.dev/docs/api/validator#transform-throws).
 
 ### Slots
 

package/dist/json-schema/declare-value-keywords.d.ts

@@ -20,8 +20,6 @@ export declare function permitsNull(schema: Draft07SchemaObject): boolean;
  * that fails all of them.
  */
 export declare function declareTypeRules(schema: Draft07SchemaObject, context: StructuralContext): readonly Rule[];
-/** `type: "integer"` is the only `type` member that adds a chain method. */
-export declare function declareIntegerRules(schema: Draft07SchemaObject, context: StructuralContext): readonly Rule[];
 export declare function declareConstRules(schema: Draft07SchemaObject, context: StructuralContext): readonly Rule[];
 /**
  * `enum` drives the `.oneOf()` METHOD, which is a different thing from the

package/dist/json-schema/declare-value-keywords.js

@@ -3,7 +3,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.readDeclaredTypes = readDeclaredTypes;
 exports.permitsNull = permitsNull;
 exports.declareTypeRules = declareTypeRules;
-exports.declareIntegerRules = declareIntegerRules;
 exports.declareConstRules = declareConstRules;
 exports.declareEnumRules = declareEnumRules;
 // ===========================================================================
@@ -41,6 +40,13 @@ const NO_RULES = Object.freeze([]);
 const JSON_TYPE_TESTS = {
     string: types_1.isString,
     number: (value) => typeof value === "number",
+    // The whole of `type: "integer"`. A second rule built from the numberInteger
+    // plugin used to run beside this one with its code overridden to `type`,
+    // which put two issues coded `type` at one path for one value — and (path,
+    // code) is the pair a machine consumer de-duplicates on, so one of them
+    // disappeared without trace. This test is the same predicate the plugin
+    // applies, so removing the second rule changed no verdict: the conformance
+    // corpus stayed at 929 / 929.
     integer: (value) => typeof value === "number" && Number.isInteger(value),
     boolean: (value) => typeof value === "boolean",
     array: types_1.isArray,
@@ -126,15 +132,6 @@ function declareTypeRules(schema, context) {
         }),
     ]);
 }
-/** `type: "integer"` is the only `type` member that adds a chain method. */
-function declareIntegerRules(schema, context) {
-    if (!readDeclaredTypes(schema).includes("integer"))
-        return NO_RULES;
-    const plugin = context.bag.numberInteger;
-    return Object.freeze([
-        plugin.build(context.ruleContextFor(plugin.name, "type")),
-    ]);
-}
 function declareConstRules(schema, context) {
     if (!Object.prototype.hasOwnProperty.call(schema, "const"))
         return NO_RULES;

package/dist/json-schema/declare-value-keywords.mjs

@@ -33,6 +33,13 @@ const NO_RULES = Object.freeze([]);
 const JSON_TYPE_TESTS = {
     string: isString,
     number: (value) => typeof value === "number",
+    // The whole of `type: "integer"`. A second rule built from the numberInteger
+    // plugin used to run beside this one with its code overridden to `type`,
+    // which put two issues coded `type` at one path for one value — and (path,
+    // code) is the pair a machine consumer de-duplicates on, so one of them
+    // disappeared without trace. This test is the same predicate the plugin
+    // applies, so removing the second rule changed no verdict: the conformance
+    // corpus stayed at 929 / 929.
     integer: (value) => typeof value === "number" && Number.isInteger(value),
     boolean: (value) => typeof value === "boolean",
     array: isArray,
@@ -118,15 +125,6 @@ export function declareTypeRules(schema, context) {
         }),
     ]);
 }
-/** `type: "integer"` is the only `type` member that adds a chain method. */
-export function declareIntegerRules(schema, context) {
-    if (!readDeclaredTypes(schema).includes("integer"))
-        return NO_RULES;
-    const plugin = context.bag.numberInteger;
-    return Object.freeze([
-        plugin.build(context.ruleContextFor(plugin.name, "type")),
-    ]);
-}
 export function declareConstRules(schema, context) {
     if (!Object.prototype.hasOwnProperty.call(schema, "const"))
         return NO_RULES;

package/dist/json-schema/extensions/json-schema-full-feature/bundle-coverage.js

@@ -44,7 +44,6 @@ exports.UNBOUND_BUNDLED_PLUGIN_NAMES = Object.freeze([
     "arrayContains",
     "arrayEach",
     "conditionalSchema",
-    "numberInteger",
     "objectAdditionalPropertiesSchema",
     "objectDependentRequired",
     "objectDependentSchemas",
@@ -53,6 +52,12 @@ exports.UNBOUND_BUNDLED_PLUGIN_NAMES = Object.freeze([
     "oneOf",
     // Reachable only from a hand-written chain; the converter never calls them.
     "compareField",
+    // numberInteger moved into this group when the converter stopped building a
+    // second rule from it for `type: "integer"`: the type table's own predicate
+    // is `Number.isInteger`, so the plugin's rule only ever duplicated it. It
+    // stays in the bag because `.integer()` is still a method a hand-written
+    // chain can call.
+    "numberInteger",
     "nullable",
     "optional",
     "tupleBuilder",

package/dist/json-schema/extensions/json-schema-full-feature/bundle-coverage.mjs

@@ -37,7 +37,6 @@ export const UNBOUND_BUNDLED_PLUGIN_NAMES = Object.freeze([
     "arrayContains",
     "arrayEach",
     "conditionalSchema",
-    "numberInteger",
     "objectAdditionalPropertiesSchema",
     "objectDependentRequired",
     "objectDependentSchemas",
@@ -46,6 +45,12 @@ export const UNBOUND_BUNDLED_PLUGIN_NAMES = Object.freeze([
     "oneOf",
     // Reachable only from a hand-written chain; the converter never calls them.
     "compareField",
+    // numberInteger moved into this group when the converter stopped building a
+    // second rule from it for `type: "integer"`: the type table's own predicate
+    // is `Number.isInteger`, so the plugin's rule only ever duplicated it. It
+    // stays in the bag because `.integer()` is still a method a hand-written
+    // chain can call.
+    "numberInteger",
     "nullable",
     "optional",
     "tupleBuilder",

package/dist/json-schema/schema-to-declarations.js

@@ -30,10 +30,7 @@ exports.STRUCTURAL_EXPANSIONS = {
     },
     type: {
         expandsTo: "rules",
-        toRules: (schema, context) => [
-            ...(0, declare_value_keywords_1.declareTypeRules)(schema, context),
-            ...(0, declare_value_keywords_1.declareIntegerRules)(schema, context),
-        ],
+        toRules: declare_value_keywords_1.declareTypeRules,
     },
     enum: { expandsTo: "rules", toRules: declare_value_keywords_1.declareEnumRules },
     allOf: { expandsTo: "rules", toRules: compose_keyword_1.composeAllOf },

package/dist/json-schema/schema-to-declarations.mjs

@@ -5,7 +5,7 @@ import { declareAdditionalPropertiesSchema } from "./declare-additional-properti
 import { declareDependencies, declareObjectRules, declarePatternProperties, declarePropertyNames, readPropertyChildren, } from "./declare-object-keywords.mjs";
 import { declareRequiredProperties } from "./declare-required-properties.mjs";
 import { declareFormatRules, declareNumberRules, declareStringRules, } from "./declare-scalar-keywords.mjs";
-import { declareConstRules, declareEnumRules, declareIntegerRules, declareTypeRules, } from "./declare-value-keywords.mjs";
+import { declareConstRules, declareEnumRules, declareTypeRules, } from "./declare-value-keywords.mjs";
 import { composeContains, composeTupleItems, declareArrayRules, readItemChildren, } from "./flatten-array-schema.mjs";
 import { NON_DRAFT07_KEYWORDS, findKeywordHandling } from "./keyword-map.mjs";
 import { readChildExpansion, readRuleExpansion, } from "./structural-expansion.types.mjs";
@@ -24,10 +24,7 @@ export const STRUCTURAL_EXPANSIONS = {
     },
     type: {
         expandsTo: "rules",
-        toRules: (schema, context) => [
-            ...declareTypeRules(schema, context),
-            ...declareIntegerRules(schema, context),
-        ],
+        toRules: declareTypeRules,
     },
     enum: { expandsTo: "rules", toRules: declareEnumRules },
     allOf: { expandsTo: "rules", toRules: composeAllOf },

package/dist/runtime/create-issue.d.ts

@@ -13,6 +13,15 @@ export interface IssueRequest {
      * sees one call shape and needs no rule kind to dispatch on.
      */
     render(context: MessageContext): string;
+    /**
+     * The branch failures behind a composite, when the rule that failed is one.
+     *
+     * Passed rather than read off the detail because this layer never sees a
+     * rule kind: a presence policy closes over nothing and a check closes over
+     * its own IssueDetail, and keeping that asymmetry out of here is what lets
+     * one call shape serve both.
+     */
+    readonly causes?: readonly ValidationIssue[] | undefined;
 }
 /**
  * A plugin whose message factory throws must not take the validation down

package/dist/runtime/create-issue.js

@@ -17,12 +17,19 @@ function createIssue(request) {
         value: request.value,
         code: request.code,
     };
-    return Object.freeze({
+    const issue = {
         path: request.path,
         code: request.code,
         message: renderMessageOrFallback(request, context),
         severity: request.severity,
-    });
+    };
+    // Spread CONDITIONALLY. Writing `causes: request.causes` unconditionally
+    // would put the key on every issue the library reports, with the value
+    // undefined — and `"causes" in issue` would then answer true for a plain
+    // stringMin failure, which is exactly the question a caller asks it.
+    return Object.freeze(request.causes === undefined || request.causes.length === 0
+        ? issue
+        : { ...issue, causes: request.causes });
 }
 function renderMessageOrFallback(request, context) {
     try {

package/dist/runtime/create-issue.mjs

@@ -13,12 +13,19 @@ export function createIssue(request) {
         value: request.value,
         code: request.code,
     };
-    return Object.freeze({
+    const issue = {
         path: request.path,
         code: request.code,
         message: renderMessageOrFallback(request, context),
         severity: request.severity,
-    });
+    };
+    // Spread CONDITIONALLY. Writing `causes: request.causes` unconditionally
+    // would put the key on every issue the library reports, with the value
+    // undefined — and `"causes" in issue` would then answer true for a plain
+    // stringMin failure, which is exactly the question a caller asks it.
+    return Object.freeze(request.causes === undefined || request.causes.length === 0
+        ? issue
+        : { ...issue, causes: request.causes });
 }
 function renderMessageOrFallback(request, context) {
     try {

package/dist/runtime/run-field.js

@@ -78,6 +78,7 @@ function reportCheckFailure(check, detail, value, ruleContext, context) {
         severity: check.severity,
         value,
         render: (ctx) => check.describe(detail, ctx),
+        causes: detail.causes,
     }));
 }
 function runChecks(field, value, ruleContext, context, mark) {

package/dist/runtime/run-field.mjs

@@ -74,6 +74,7 @@ function reportCheckFailure(check, detail, value, ruleContext, context) {
         severity: check.severity,
         value,
         render: (ctx) => check.describe(detail, ctx),
+        causes: detail.causes,
     }));
 }
 function runChecks(field, value, ruleContext, context, mark) {

package/dist/types/index.d.ts

@@ -26,6 +26,18 @@ export interface ValidationIssue {
     /** Never optional: the chain resolves it once at build time, so a reader
      *  never has to re-implement the "absent means error" fallback. */
     readonly severity: IssueSeverity;
+    /**
+     * Why a composite failed, when the failing rule is one.
+     *
+     * `allOf`, `anyOf` and `oneOf` report their own code, which says WHICH
+     * applicator failed and never why. The branch failures behind it land here,
+     * so a caller can reach "minLength" without re-running the sub-schemas.
+     *
+     * ABSENT, not undefined, on an ordinary issue. A key present everywhere
+     * would make `"causes" in issue` answer true for every issue the library
+     * reports, which is the opposite of what it is for.
+     */
+    readonly causes?: readonly ValidationIssue[];
 }
 /** branch / index / causes let a composite failure explain itself. */
 export interface IssueDetail {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@maroonedog/luq",
-  "version": "2.6.0",
-  "description": "Universal Model & API Definition Platform - TypeScript validation library evolving into cross-language code generation",
+  "version": "2.7.0",
+  "description": "Validate the TypeScript types you already have. Rules are declared against your own type's field paths, so a rule that does not apply to its field is a compile error.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -510,13 +510,22 @@
     "url": "https://github.com/maroonedog/luq/issues"
   },
   "keywords": [
-    "form",
-    "validation",
     "typescript",
+    "validation",
     "validator",
-    "library"
+    "schema",
+    "json-schema",
+    "draft-07",
+    "openapi",
+    "standard-schema",
+    "standardschema",
+    "type-safe",
+    "form-validation",
+    "runtime-validation",
+    "content-security-policy",
+    "zero-dependencies"
   ],
-  "author": "",
+  "author": "maroonedog (https://github.com/maroonedog)",
   "license": "MIT",
   "files": [
     "dist"