Version 1.1.20 (#1568)

* Union Priority Sort

* ChangeLog

* Version

Author: sinclairzx81

changelog/1.1.0.md

@@ -3,6 +3,8 @@
 ---
 
 ### Version Updates
+- [Revision 1.1.20](https://github.com/sinclairzx81/typebox/pull/1568)
+  - Union Priority Sort for Clean, Encode and Decode
 - [Revision 1.1.19](https://github.com/sinclairzx81/typebox/pull/1566)
   - Improved Intersect Encode and Decode Handling
 - [Revision 1.1.18](https://github.com/sinclairzx81/typebox/pull/1565)

src/value/clean/from-union.ts

@@ -33,8 +33,10 @@ import { Check } from '../check/index.ts'
 import { Clone } from '../clone/index.ts'
 import { FromType } from './from-type.ts'
 
+import { UnionPrioritySort } from '../shared/union-priority-sort.ts'
+
 export function FromUnion(context: TProperties, type: TUnion, value: unknown): unknown {
-  for (const schema of type.anyOf) {
+  for (const schema of UnionPrioritySort(type.anyOf)) {
     const clean = FromType(context, schema, Clone(value))
     if(Check(context, schema, clean)) return clean
   }

src/value/codec/from-object.ts

@@ -33,7 +33,8 @@ import { Guard } from '../../guard/index.ts'
 import { type TObject, type TProperties } from '../../type/index.ts'
 import { FromType } from './from-type.ts'
 import { Callback } from './callback.ts'
-import { IsOptionalUndefined } from '../shared/index.ts'
+
+import { IsOptionalUndefined } from '../shared/optional-undefined.ts'
 
 // ------------------------------------------------------------------
 // Decode

src/value/codec/from-union.ts

@@ -28,34 +28,32 @@ THE SOFTWARE.
 
 // deno-fmt-ignore-file
 
-import { Unreachable } from '../../system/unreachable/index.ts'
 import { Guard } from '../../guard/index.ts'
 import { type TProperties, type TUnion } from '../../type/index.ts'
 import { Callback } from './callback.ts'
 import { FromType } from './from-type.ts'
 import { Clone } from '../clone/index.ts'
 import { Check } from '../check/index.ts'
 
+import { UnionPrioritySort } from '../shared/union-priority-sort.ts'
+
 // ------------------------------------------------------------------
 // Decode
 // ------------------------------------------------------------------
-// deno-coverage-ignore-start - unreachable | checked
 function Decode(direction: string, context: TProperties, type: TUnion, value: unknown): unknown {
-  for (const schema of type.anyOf) {
+  for (const schema of UnionPrioritySort(type.anyOf, 1)) {
     if(!Check(context, schema, value)) continue
     const variant = FromType(direction, context, schema, value)
     return Callback(direction, context, type, variant)
   }
-  return Unreachable()
+  return value
 }
-// deno-coverage-ignore-stop
-
 // ------------------------------------------------------------------
 // Encode
 // ------------------------------------------------------------------
 function Encode(direction: string, context: TProperties, type: TUnion, value: unknown): unknown {
   let exterior = Callback(direction, context, type, value)
-  for (const schema of type.anyOf) {
+  for (const schema of UnionPrioritySort(type.anyOf, -1)) {
     const variant = FromType(direction, context, schema, Clone(exterior))
     if(!Check(context, schema, variant)) continue
     return variant

src/value/convert/from-object.ts

@@ -32,7 +32,8 @@ import { type TSchema, type TObject, type TProperties } from '../../type/index.t
 import { Guard } from '../../guard/index.ts'
 import { FromType } from './from-type.ts'
 import { FromAdditionalProperties } from './from-additional.ts'
-import { IsOptionalUndefined } from '../shared/index.ts'
+
+import { IsOptionalUndefined } from '../shared/optional-undefined.ts'
 
 // ------------------------------------------------------------------
 // FromProperties

src/value/index.ts

@@ -46,7 +46,10 @@ export * from './delta/index.ts'
 export * from './pipeline/index.ts'
 export * from './pointer/index.ts'
 export * from './repair/index.ts'
-
+// ------------------------------------------------------------------
+// Shared
+// ------------------------------------------------------------------
+export * from './shared/index.ts'
 // ------------------------------------------------------------------
 // Default
 // ------------------------------------------------------------------

src/value/repair/from-union.ts

@@ -30,71 +30,23 @@ THE SOFTWARE.
 
 import { IsDefault } from '../../schema/types/index.ts'
 
-import { type TProperties, type TSchema, type TUnion, Union, IsLiteral, IsObject, IsRef } from '../../type/index.ts'
+import { type TProperties, type TUnion, Union } from '../../type/index.ts'
 import { Flatten } from '../../type/engine/evaluate/index.ts'
-import { Guard } from '../../guard/index.ts'
 import { Check } from '../check/index.ts'
 import { Clone } from '../clone/index.ts'
 import { Create } from '../create/index.ts'
-import { RepairError } from './error.ts'
 import { FromType } from './from-type.ts'
 
-// ------------------------------------------------------------------
-// Deref
-// ------------------------------------------------------------------
-function Deref(context: TProperties, type: TSchema, value: unknown): TSchema {
-  return IsRef(type)
-    ? Guard.HasPropertyKey(context, type.$ref)
-      ? Deref(context, context[type.$ref], value)
-      : (() => { throw new RepairError(context, type, value, 'Unable to Deref target on Union repair') })()
-    : type
-}
+import { UnionScoreSelect } from '../shared/union-score-select.ts'
 
-// ------------------------------------------------------------------
-// The following will score a schema against a value. For objects,
-// the score is the tally of points awarded for each property of
-// the value. Property points are (1.0 / propertyCount) to prevent
-// large property counts biasing results. Properties that match
-// literal values are maximally awarded as literals are typically
-// used as union discriminator fields.
-// ------------------------------------------------------------------
-function ScoreVariant(context: TProperties, type: TSchema, value: unknown): number {
-  // scoring is only possible for object types.
-  if(!(IsObject(type) && Guard.IsObject(value))) return 0
-  
-  const keys = Guard.Keys(value)
-  const entries = Guard.Entries(type.properties)
-  return entries.reduce((result, [key, schema]) => {
-    const literal = IsLiteral(schema) && Guard.IsEqual(schema.const, value[key]) ? 100 : 0
-    const checks = Check(context, schema, value[key]) ? 10 : 0
-    const exists = keys.includes(key) ? 1 : 0
-    return result + (literal + checks + exists)
-  }, 0)
-}
-// ------------------------------------------------------------------
-// SelectVariant
-// ------------------------------------------------------------------
-function SelectVariant(context: TProperties, type: TUnion, value: unknown): TSchema {
-  const schemas = type.anyOf.map((schema) => Deref(context, schema, value))
-  let [select, best] = [schemas[0], 0]
-  for (const schema of schemas) {
-    const score = ScoreVariant(context, schema, value)
-    if (score > best) {
-      select = schema
-      best = score
-    }
-  }
-  return select
-}
 // ------------------------------------------------------------------
 // RepairUnion
 // ------------------------------------------------------------------
 function RepairUnion(context: TProperties, type: TUnion, value: unknown): unknown {
   const union = Union(Flatten(type.anyOf))
-  const schema = SelectVariant(context, union, value)
+  const schema = UnionScoreSelect(context, union, value)
   return FromType(context, schema, value)
 }
-
 export function FromUnion(context: TProperties, type: TUnion, value: unknown): unknown {
   if (Check(context, type, value)) return Clone(value)
   if (IsDefault(type)) return Create(context, type)

src/value/shared/index.ts

@@ -28,4 +28,6 @@ THE SOFTWARE.
 
 // deno-fmt-ignore-file
 
-export * from './optional-undefined.ts'
+export * from './optional-undefined.ts'
+export * from './union-priority-sort.ts'
+export * from './union-score-select.ts'

src/value/shared/optional-undefined.ts

@@ -31,7 +31,6 @@ THE SOFTWARE.
 import { Guard } from '../../guard/index.ts'
 import { type TSchema, IsOptional } from '../../type/index.ts'
 
-
 // ------------------------------------------------------------------
 // IsOptionalUndefined
 //

src/value/shared/union-priority-sort.ts

@@ -0,0 +1,69 @@
+/*--------------------------------------------------------------------------
+
+TypeBox
+
+The MIT License (MIT)
+
+Copyright (c) 2017-2026 Haydn Paterson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+---------------------------------------------------------------------------*/
+
+// deno-fmt-ignore-file
+
+import { Guard } from '../../guard/index.ts'
+import { Compare, type TSchema } from '../../type/index.ts'
+
+// ------------------------------------------------------------------
+// DeterministicCompare
+//
+// Provides a deterministic tie-break for schemas. This is used when
+// schemas are structurally disjoint or mutually inclusive. While
+// JSON serialization incurs a performance overhead, it serves as a
+// reliable mechanism to ensure stable ordering and preserves the
+// alphabetical alignment of named constants.
+//
+// ------------------------------------------------------------------
+function DeterministicCompare(left: TSchema, right: TSchema): number {
+  return JSON.stringify(left).localeCompare(JSON.stringify(right))
+}
+// ------------------------------------------------------------------
+// UnionPrioritySort
+//
+// Performs a deterministic sort on Union members. By default, this
+// function ensures that narrow (more specific) types precede broader
+// types in the resulting array. The order can be reversed by setting
+// the order property to -1 which will reverse unions from broader
+// to more narrow.
+//
+// ------------------------------------------------------------------
+
+/** Deterministically sorts schemas by structural relationship (narrow to broad) */
+export function UnionPrioritySort(types: TSchema[], order: number = 1): TSchema[] {
+  return types.sort((left, right) => {
+    const result = Compare(left, right) as string
+    return (
+      Guard.IsEqual(result, 'disjoint') ? DeterministicCompare(left, right) : 
+      Guard.IsEqual(result, 'right-inside') ? 1 : 
+      Guard.IsEqual(result, 'left-inside') ? -1 : 
+      DeterministicCompare(left, right)
+    ) * order
+  })
+}