@scalar/validation 0.6.4 → 0.6.6

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @scalar/validation
 
+## 0.6.6
+
+### Patch Changes
+
+- [#10417](https://github.com/scalar/scalar/pull/10417): Reduce union scoring overhead for literals, arrays, records, and missing optional values while preserving branch selection.
+
+## 0.6.5
+
+### Patch Changes
+
+- [#10315](https://github.com/scalar/scalar/pull/10315): Bound how deep union scoring looks into a value, so `coerce` no longer takes exponential time on recursive unions. `coerce` now also stops at a nesting depth of 1,000 calls instead of overflowing the stack. It leaves deeper values unchanged and logs a warning.
+
 ## 0.6.4
 
 ### Patch Changes

package/dist/coerce.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coerce.d.ts","sourceRoot":"","sources":["../src/coerce.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AACtC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAGrC;;;;;;;;;GASG;AACH,KAAK,SAAS,GAAG,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AA+SxC;;;;;;;;;;;;;GAaG;AACH,KAAK,UAAU,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,CAAA;AAE1E;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,SAAS,MAAM,EACrC,QAAQ,CAAC,EACT,OAAO,OAAO,EACd,QAAO,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAiB,EAC5D,YAAW,SAAyB,KACnC,UAAU,CAAC,CAAC,CAAkE,CAAA"}
+{"version":3,"file":"coerce.d.ts","sourceRoot":"","sources":["../src/coerce.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AACtC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AA6CrC;;;;;;;;;GASG;AACH,KAAK,SAAS,GAAG,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AA+WxC;;;;;;;;;;;;;GAaG;AACH,KAAK,UAAU,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,CAAA;AAE1E;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,SAAS,MAAM,EACrC,QAAQ,CAAC,EACT,OAAO,OAAO,EACd,QAAO,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAiB,EAC5D,YAAW,SAAyB,KACnC,UAAU,CAAC,CAAC,CAAyF,CAAA"}

package/dist/coerce.js

@@ -1,5 +1,44 @@
 import { isObject } from './helpers/is-object.js';
 import { validate } from './validate.js';
+/**
+ * How many object levels below a union node `scoreUnion` descends before it
+ * stops scoring child values. Picking a union branch is a local decision, so
+ * the shape near the union node is what matters. Scoring the whole subtree
+ * made the cost grow as 2^depth on recursive unions (a few hundred bytes of
+ * JSON could block the main thread for seconds). It also let a branch win
+ * just because the value under it happened to be deep.
+ *
+ * Three is a safety margin, not a derived minimum. The existing
+ * branch-selection tests only need the discriminator to be scored, which
+ * happens at any depth.
+ */
+const MAX_VALUE_DEPTH = 3;
+/**
+ * How many `lazy` nodes deep one scoring path may go before it returns a
+ * neutral score. `lazy` is the only way to build an infinite schema, so this
+ * stops schema cycles that never descend into a value, such as
+ * `T = lazy(() => union([T, string()]))` scored against `'s'`.
+ *
+ * It limits depth, not fan-out. The in-progress guard only tracks objects, so
+ * a schema cycle that branches over a primitive can still do a lot of work.
+ * Only a schema author can build one of those, and the OpenAPI and AsyncAPI
+ * schemas do not contain one.
+ */
+const MAX_LAZY_DEPTH = 64;
+/**
+ * How many nested `coerceInner` calls one `coerce` call makes before it
+ * stops and returns the remaining value unchanged. This has to fire before
+ * the JavaScript stack overflows, or it does nothing. Without it, a deeply
+ * nested document, or a schema cycle over a primitive such as
+ * `lazy(() => union([T, string()]))`, throws a `RangeError`.
+ *
+ * Measured against the real OpenAPI Schema Object in Node, the stack
+ * overflows at about 3,200 nested calls. That comes from 6 to 11 calls per
+ * document level, depending on shape. We stop at roughly a third of that,
+ * because browsers, web workers and the caller's own frames can leave less
+ * stack. Schema Objects nested 90 to 165 levels deep still coerce fully.
+ */
+const MAX_COERCE_DEPTH = 1000;
 const resolveLazy = (schema, lazyCache) => {
     const cached = lazyCache.get(schema);
     if (cached) {
@@ -45,15 +84,44 @@ const isDiscriminatorProperty = (schema) => {
  * Markers are removed in `finally` so sibling union branches that share a
  * schema reference are scored independently rather than inheriting a stale
  * "in cycle" marker.
+ *
+ * The marker only stops *nested* re-entry. It does not stop the same pair
+ * being scored again through a sibling path, so it cannot bound the work on
+ * its own. Two budgets do that, each checked in the branch that uses it:
+ * - `valueDepth` counts descents into object properties below the union node.
+ *   Past {@link MAX_VALUE_DEPTH}, non-discriminator properties score a flat `1`
+ *   and are not descended into.
+ * - `lazyDepth` counts `lazy` nodes on the current path, capped at {@link MAX_LAZY_DEPTH}.
+ *
+ * Every schema node still runs its own type check at the cap. So an `object`
+ * schema against a string still scores `0`, and the budgets only cut off
+ * descent into child values.
  */
-const scoreUnion = (schema, value, lazyCache, scoringCache = new WeakMap()) => {
+const scoreUnion = (schema, value, lazyCache, scoringCache = new WeakMap(), valueDepth = 0, lazyDepth = 0) => {
+    // These scores do not descend into the value, so they cannot encounter a cycle.
+    // In particular, literals are common in discriminator and enum unions and do
+    // not need a separate validation traversal or its cache allocation.
+    if (schema.type === 'literal') {
+        // Keep strict equality in sync with the literal branch of validateInner in validate.ts.
+        return value === schema.value ? 1 : 0;
+    }
+    if (schema.type === 'array') {
+        return Array.isArray(value) ? 1 : 0;
+    }
+    if (schema.type === 'record') {
+        // TODO: implement smarter scoring for records
+        return isObject(value) ? 1 : 0;
+    }
+    if (schema.type === 'optional' && value === undefined) {
+        return 1;
+    }
+    const trackable = isObject(value);
     // Short-circuit on cycles: this exact (value, schema) pair is already being
     // scored higher up the call stack. The enclosing call's score subsumes any
     // contribution we could compute here, so return a neutral positive score.
-    if (isObject(value) && scoringCache.get(value)?.has(schema)) {
+    if (trackable && scoringCache.get(value)?.has(schema)) {
         return 1;
     }
-    const trackable = isObject(value);
     if (trackable) {
         const schemas = scoringCache.get(value) ?? new Set();
         schemas.add(schema);
@@ -61,7 +129,7 @@ const scoreUnion = (schema, value, lazyCache, scoringCache = new WeakMap()) => {
     }
     try {
         if (schema.type === 'object') {
-            if (!isObject(value)) {
+            if (!trackable) {
                 return 0;
             }
             const keys = Object.keys(schema.properties);
@@ -81,41 +149,49 @@ const scoreUnion = (schema, value, lazyCache, scoringCache = new WeakMap()) => {
                 }
                 const propSchema = schema.properties[key];
                 const raw = value[key];
-                const base = scoreUnion(propSchema, raw, lazyCache, scoringCache);
-                if (isDiscriminatorProperty(propSchema)) {
+                const isDiscriminator = isDiscriminatorProperty(propSchema);
+                // Past the depth budget we stop descending into child values. Discriminators are still
+                // scored in full: they are finite trees of literals, optionals and unions (never `lazy`)
+                // that do not descend into the value, so this stays cheap. It also keeps a tag like
+                // `kind: literal('b')` deciding the branch when it sits below the budget.
+                const base = valueDepth >= MAX_VALUE_DEPTH
+                    ? isDiscriminator
+                        ? scoreUnion(propSchema, raw, lazyCache, scoringCache, valueDepth, lazyDepth)
+                        : 1
+                    : scoreUnion(propSchema, raw, lazyCache, scoringCache, valueDepth + 1, lazyDepth);
+                if (isDiscriminator) {
                     return acc + (base > 0 ? base * 10 : 0);
                 }
                 return acc + (base > 0 ? base : 1);
             }, 0);
         }
-        if (schema.type === 'array') {
-            // Score 1 if value is an array, otherwise 0
-            return Array.isArray(value) ? 1 : 0;
-        }
-        if (schema.type === 'record') {
-            // TODO: implement smarter scoring for records (just a placeholder for now)
-            return isObject(value) ? 1 : 0;
-        }
         if (schema.type === 'optional') {
-            return value === undefined ? 1 : scoreUnion(schema.schema, value, lazyCache, scoringCache);
+            return scoreUnion(schema.schema, value, lazyCache, scoringCache, valueDepth, lazyDepth);
         }
         if (schema.type === 'union') {
             // For a union, use the highest score among all sub-schemas
-            return Math.max(...schema.schemas.map((branch) => scoreUnion(branch, value, lazyCache, scoringCache)));
+            return Math.max(...schema.schemas.map((branch) => scoreUnion(branch, value, lazyCache, scoringCache, valueDepth, lazyDepth)));
         }
         if (schema.type === 'intersection') {
             if (schema.schemas.length === 0) {
                 return 1;
             }
-            return schema.schemas.reduce((acc, sub) => acc + scoreUnion(sub, value, lazyCache, scoringCache), 0);
+            return schema.schemas.reduce((acc, sub) => acc + scoreUnion(sub, value, lazyCache, scoringCache, valueDepth, lazyDepth), 0);
         }
         if (schema.type === 'lazy') {
+            // We cannot know the type without resolving, so a neutral score is the only option here.
+            if (lazyDepth >= MAX_LAZY_DEPTH) {
+                return 1;
+            }
             // For a lazy schema, evaluate the inner schema and recurse
-            return scoreUnion(resolveLazy(schema, lazyCache), value, lazyCache, scoringCache);
+            return scoreUnion(resolveLazy(schema, lazyCache), value, lazyCache, scoringCache, valueDepth, lazyDepth + 1);
         }
         if (schema.type === 'evaluate') {
-            // For an evaluate schema, evaluate the expression and recurse
-            return scoreUnion(schema.schema, schema.expression(value), lazyCache, scoringCache);
+            // For an evaluate schema, evaluate the expression and recurse. This spends no budget: the
+            // inner `object` branch still stops descending at the cap, and `lazy` still bounds cycles.
+            // Only a schema that points `evaluate` back at itself without a `lazy` in between could
+            // loop, and the builders in `schema.ts` cannot construct one.
+            return scoreUnion(schema.schema, schema.expression(value), lazyCache, scoringCache, valueDepth, lazyDepth);
         }
         // For primitives and any other type, return 1 if valid, otherwise 0
         return validate(schema, value) ? 1 : 0;
@@ -148,7 +224,17 @@ const trackCycle = (value, schema, result, cache) => {
  * can overflow the type checker now that `LazyStatic` resolves recursive schemas without a depth
  * cap. The public `coerce` wrapper preserves the typed surface.
  */
-const coerceInner = (schema, value, cache, lazyCache) => {
+const coerceInner = (schema, value, cache, lazyCache, depth, warningState) => {
+    // Stop before the stack overflows. Return the value unchanged, not a schema default: callers
+    // merge the result back into the document, so a default would overwrite real content. Leaving
+    // the subtree un-normalized loses nothing.
+    if (depth >= MAX_COERCE_DEPTH) {
+        if (!warningState.emitted) {
+            warningState.emitted = true;
+            console.warn(`[@scalar/validation] coerce stopped at nesting depth ${MAX_COERCE_DEPTH}; deeper values are left as-is.`);
+        }
+        return value;
+    }
     // Prevent infinite recursion by returning the in-progress result that was
     // staged by an enclosing call via trackCycle.
     if ((isObject(value) || Array.isArray(value)) && cache.get(value)?.has(schema)) {
@@ -195,7 +281,7 @@ const coerceInner = (schema, value, cache, lazyCache) => {
         if (value === undefined) {
             return undefined;
         }
-        return coerceInner(schema.schema, value, cache, lazyCache);
+        return coerceInner(schema.schema, value, cache, lazyCache, depth + 1, warningState);
     }
     if (schema.type === 'array') {
         if (!Array.isArray(value)) {
@@ -206,7 +292,7 @@ const coerceInner = (schema, value, cache, lazyCache) => {
         const result = new Array(value.length);
         trackCycle(value, schema, result, cache);
         for (let i = 0; i < value.length; i++) {
-            result[i] = coerceInner(schema.items, value[i], cache, lazyCache);
+            result[i] = coerceInner(schema.items, value[i], cache, lazyCache, depth + 1, warningState);
         }
         return result;
     }
@@ -219,7 +305,7 @@ const coerceInner = (schema, value, cache, lazyCache) => {
         const result = {};
         trackCycle(value, schema, result, cache);
         for (const key of Object.keys(value)) {
-            result[key] = coerceInner(schema.value, value[key], cache, lazyCache);
+            result[key] = coerceInner(schema.value, value[key], cache, lazyCache, depth + 1, warningState);
         }
         return result;
     }
@@ -236,7 +322,7 @@ const coerceInner = (schema, value, cache, lazyCache) => {
             if (propSchema.type === 'optional' && raw === undefined) {
                 continue;
             }
-            result[key] = coerceInner(propSchema, raw, cache, lazyCache);
+            result[key] = coerceInner(propSchema, raw, cache, lazyCache, depth + 1, warningState);
         }
         return result;
     }
@@ -246,19 +332,19 @@ const coerceInner = (schema, value, cache, lazyCache) => {
             return score > acc.score ? { schema: branchSchema, score } : acc;
         }, { schema: schema.schemas[0], score: 0 });
         // We need some way to pick one of the union values
-        return coerceInner(branch.schema, value, cache, lazyCache);
+        return coerceInner(branch.schema, value, cache, lazyCache, depth + 1, warningState);
     }
     if (schema.type === 'intersection') {
-        return schema.schemas.reduce((acc, subSchema) => Object.assign(acc, coerceInner(subSchema, value, cache, lazyCache)), {});
+        return schema.schemas.reduce((acc, subSchema) => Object.assign(acc, coerceInner(subSchema, value, cache, lazyCache, depth + 1, warningState)), {});
     }
     if (schema.type === 'literal') {
         return schema.value;
     }
     if (schema.type === 'lazy') {
-        return coerceInner(resolveLazy(schema, lazyCache), value, cache, lazyCache);
+        return coerceInner(resolveLazy(schema, lazyCache), value, cache, lazyCache, depth + 1, warningState);
     }
     if (schema.type === 'evaluate') {
-        return coerceInner(schema.schema, schema.expression(value), cache, lazyCache);
+        return coerceInner(schema.schema, schema.expression(value), cache, lazyCache, depth + 1, warningState);
     }
     // We need to assert here that schema has the type never so we know we handle all cases
     const _exhaustive = schema;
@@ -283,4 +369,4 @@ const coerceInner = (schema, value, cache, lazyCache) => {
  * The optional `cache` argument tracks visited object–schema pairs to stop infinite recursion
  * on cyclic graphs; callers normally omit it.
  */
-export const coerce = (schema, value, cache = new WeakMap(), lazyCache = new WeakMap()) => coerceInner(schema, value, cache, lazyCache);
+export const coerce = (schema, value, cache = new WeakMap(), lazyCache = new WeakMap()) => coerceInner(schema, value, cache, lazyCache, 0, { emitted: false });

package/package.json

@@ -15,7 +15,7 @@
     "coerce",
     "scalar"
   ],
-  "version": "0.6.4",
+  "version": "0.6.6",
   "engines": {
     "node": ">=20"
   },