updates

examples/index.ts

@@ -5,11 +5,18 @@ import { Type, TypeGuard, Kind, Static, TSchema, KeyResolver, TObject } from '@s
 import { Run } from './benchmark'
 
 // Todo: Investigate Union Default (initialize interior types)
-// Todo: Implement Value.Clean() Tests
+// Todo: Implement Value.Clean() Tests - Done
+
+const A = Type.Union([
+  Type.Number({ default: 1 }),
+  Type.String({ default: 'hello' })
+])
+
+const X = Value.Default(A, undefined) // should pick the first?
+
+console.log(X)
+
+
+
 
-const X = Type.Object({ x: Type.Number() })
-const Y = Type.Object({ y: Type.Number() })
-const T = Type.Union([X, Y])
-const R = Value.Clean(T, { u: null, x: 1 })
 
-console.log(R)

src/value/cast.ts

@@ -230,11 +230,11 @@ function Visit(schema: Types.TSchema, references: Types.TSchema[], value: any):
 // --------------------------------------------------------------------------
 // Cast
 // --------------------------------------------------------------------------
-/** Casts a value into a given type. The return value will retain as much information of the original value as possible. */
+/** Casts a value into a given type, removing and generating default values if necessary. The return value will retain as much information from the original value as possible. */
 export function Cast<T extends Types.TSchema>(schema: T, references: Types.TSchema[], value: unknown): Types.Static<T>
-/** Casts a value into a given type. The return value will retain as much information of the original value as possible. */
+/** Casts a value into a given type, removing and generating default values if necessary. The return value will retain as much information from the original value as possible. */
 export function Cast<T extends Types.TSchema>(schema: T, value: unknown): Types.Static<T>
-/** Casts a value into a given type. The return value will retain as much information of the original value as possible. */
+/** Casts a value into a given type, removing and generating default values if necessary. The return value will retain as much information from the original value as possible. */
 export function Cast(...args: any[]) {
   return args.length === 3 ? Visit(args[0], args[1], args[2]) : Visit(args[0], [], args[1])
 }

src/value/clean.ts

@@ -146,11 +146,11 @@ function Visit(schema: Types.TSchema, references: Types.TSchema[], value: unknow
 // --------------------------------------------------------------------------
 // Clean
 // --------------------------------------------------------------------------
-/** `[Mutable]` Removes excess properties from the input value and returns the result. This function is mutable and will modify the input value. To avoid mutation, clone the input value before passing to this function. In addition, this function does not type check the input value and will return invalid results for invalid inputs. You should type check the result before use. */
+/** Removes excess properties from the input value and returns the result. This function does not type check the input value and may return invalid results for invalid inputs. You should type check the result before use. */
 export function Clean<T extends Types.TSchema>(schema: T, references: Types.TSchema[], value: unknown): unknown
-/** `[Mutable]` Removes excess properties from the input value and returns the result. This function is mutable and will modify the input value. To avoid mutation, clone the input value before passing to this function. In addition, this function does not type check the input value and will return invalid results for invalid inputs. You should type check the result before use. */
+/** Removes excess properties from the input value and returns the result. This function does not type check the input value and may return invalid results for invalid inputs. You should type check the result before use. */
 export function Clean<T extends Types.TSchema>(schema: T): unknown
-/** `[Mutable]` Removes excess properties from the input value and returns the result. This function is mutable and will modify the input value. To avoid mutation, clone the input value before passing to this function. In addition, this function does not type check the input value and will return invalid results for invalid inputs. You should type check the result before use. */
+/** Removes excess properties from the input value and returns the result. This function does not type check the input value and may return invalid results for invalid inputs. You should type check the result before use. */
 export function Clean(...args: any[]) {
   return args.length === 3 ? Visit(args[0], args[1], args[2]) : Visit(args[0], [], args[1])
 }

src/value/convert.ts

@@ -289,11 +289,11 @@ function Visit(schema: Types.TSchema, references: Types.TSchema[], value: any):
 // --------------------------------------------------------------------------
 // Convert
 // --------------------------------------------------------------------------
-/** Converts any type mismatched values to their target type if a reasonable conversion is possible */
+/** Converts any type mismatched values to their target type if a reasonable conversion is possible. This function does not type check the input value and may return invalid results for invalid inputs. You should type check the result before use. */
 export function Convert<T extends Types.TSchema>(schema: T, references: Types.TSchema[], value: unknown): unknown
-/** Converts any type mismatched values to their target type if a reasonable conversion is possible */
+/** Converts any type mismatched values to their target type if a reasonable conversion is possible. This function does not type check the input value and may return invalid results for invalid inputs. You should type check the result before use. */
 export function Convert<T extends Types.TSchema>(schema: T, value: unknown): unknown
-/** Converts any type mismatched values to their target type if a reasonable conversion is possible */
+/** Converts any type mismatched values to their target type if a reasonable conversion is possible. This function does not type check the input value and may return invalid results for invalid inputs. You should type check the result before use. */
 export function Convert(...args: any[]) {
   return args.length === 3 ? Visit(args[0], args[1], args[2]) : Visit(args[0], [], args[1])
 }

src/value/default.ts

@@ -139,11 +139,11 @@ function Visit(schema: Types.TSchema, references: Types.TSchema[], value: unknow
 // --------------------------------------------------------------------------
 // Default
 // --------------------------------------------------------------------------
-/** `[Mutable]` Patches a given value with defaults derived from default schema annotations. This function is mutable and will modify the input value. To avoid mutation, clone the input value prior to calling this function. This function may return an incomplete or invalid result and should be checked before use. */
+/** Applies default annotations to missing values and returns the result. This function does not type check the input value and may return invalid results for invalid inputs. You should type check the result before use. */
 export function Default<T extends Types.TSchema>(schema: T, references: Types.TSchema[], value: unknown): unknown
-/** `[Mutable]` Patches a given value with defaults derived from default schema annotations. This function is mutable and will modify the input value. To avoid mutation, clone the input value prior to calling this function. This function may return an incomplete or invalid result and should be checked before use. */
+/** Applies default annotations to missing values and returns the result. This function does not type check the input value and may return invalid results for invalid inputs. You should type check the result before use. */
 export function Default<T extends Types.TSchema>(schema: T, value: unknown): unknown
-/** `[Mutable]` Patches a given value with defaults derived from default schema annotations. This function is mutable and will modify the input value. To avoid mutation, clone the input value prior to calling this function. This function may return an incomplete or invalid result and should be checked before use. */
+/** Applies default annotations to missing values and returns the result. This function does not type check the input value and may return invalid results for invalid inputs. You should type check the result before use. */
 export function Default(...args: any[]) {
   return args.length === 3 ? Visit(args[0], args[1], args[2]) : Visit(args[0], [], args[1])
 }

src/value/transmute.ts

@@ -115,7 +115,7 @@ function IsMismatchedValue(current: unknown, next: unknown) {
 // --------------------------------------------------------------------------
 // Transmute
 // --------------------------------------------------------------------------
-/** `[Mutable]` Transforms the current value into the next value and returns the result. This function performs mutable operations on the current value. To avoid mutation, clone the current value before passing to this function. */
+/** Transforms the current value into the next value and returns the result. This function performs mutable operations on the input value. To avoid mutation, clone the input value before passing to this function. */
 export function Transmute<Next extends Transmutable>(current: Transmutable, next: Next): Next {
   if (IsNonMutableValue(current) || IsNonMutableValue(next)) throw new ValueMutateInvalidRootMutationError()
   if (IsMismatchedValue(current, next)) throw new ValueMutateTypeMismatchError()

src/value/value.ts

@@ -26,28 +26,28 @@ THE SOFTWARE.
 
 ---------------------------------------------------------------------------*/
 
-import * as ValueErrors from '../errors/index'
-import * as ValueMutate from './transmute'
-import * as ValueHash from './hash'
-import * as ValueEqual from './equal'
 import * as ValueCast from './cast'
+import * as ValueClean from './clean'
 import * as ValueClone from './clone'
 import * as ValueConvert from './convert'
 import * as ValueCreate from './create'
 import * as ValueCheck from './check'
 import * as ValueDefault from './default'
 import * as ValueDelta from './delta'
-import * as ValueStrict from './clean'
+import * as ValueEqual from './equal'
+import * as ValueErrors from '../errors'
+import * as ValueHash from './hash'
 import * as ValueTransform from './transform'
+import * as ValueTransmute from './transmute'
 import * as Types from '../typebox'
 
 /** Functions to perform structural operations on JavaScript values */
 export namespace Value {
-  /** Casts a value into a given type. The return value will retain as much information of the original value as possible. */
+  /** Casts a value into a given type. The return value will retain as much information from the original value as possible. */
   export function Cast<T extends Types.TSchema>(schema: T, references: Types.TSchema[], value: unknown): Types.Static<T>
-  /** Casts a value into a given type. The return value will retain as much information of the original value as possible. */
+  /** Casts a value into a given type. The return value will retain as much information from the original value as possible. */
   export function Cast<T extends Types.TSchema>(schema: T, value: unknown): Types.Static<T>
-  /** Casts a value into a given type. The return value will retain as much information of the original value as possible. */
+  /** Casts a value into a given type. The return value will retain as much information from the original value as possible. */
   export function Cast(...args: any[]) {
     return ValueCast.Cast.apply(ValueCast, args as any)
   }
@@ -59,23 +59,23 @@ export namespace Value {
   export function Check(...args: any[]) {
     return ValueCheck.Check.apply(ValueCheck, args as any)
   }
-  /** Returns a structural clone of the given value */
-  export function Clone<T>(value: T): T {
-    return ValueClone.Clone(value)
-  }
-  /** `[Mutable]` Removes excess properties from the input value and returns the result. This function is mutable and will modify the input value. To avoid mutation, clone the input value before passing to this function. In addition, this function does not type check the input value and will return invalid results for invalid inputs. You should type check the result before use. */
+  /** Removes excess properties from the input value and returns the result. This function does not type check the input value and may return invalid results for invalid inputs. You should type check the result before use. */
   export function Clean<T extends Types.TSchema>(schema: T, references: Types.TSchema[], value: unknown): unknown
-  /** `[Mutable]` Removes excess properties from the input value and returns the result. This function is mutable and will modify the input value. To avoid mutation, clone the input value before passing to this function. In addition, this function does not type check the input value and will return invalid results for invalid inputs. You should type check the result before use. */
+  /** Removes excess properties from the input value and returns the result. This function does not type check the input value and may return invalid results for invalid inputs. You should type check the result before use. */
   export function Clean<T extends Types.TSchema>(schema: T, value: unknown): unknown
-  /** `[Mutable]` Removes excess properties from the input value and returns the result. This function is mutable and will modify the input value. To avoid mutation, clone the input value before passing to this function. In addition, this function does not type check the input value and will return invalid results for invalid inputs. You should type check the result before use. */
+  /** Removes excess properties from the input value and returns the result. This function does not type check the input value and may return invalid results for invalid inputs. You should type check the result before use. */
   export function Clean(...args: any[]) {
-    return ValueStrict.Clean.apply(ValueStrict, args as any)
+    return ValueClean.Clean.apply(ValueClean, args as any)
+  }
+  /** Returns a structural clone of the given value */
+  export function Clone<T>(value: T): T {
+    return ValueClone.Clone(value)
   }
-  /** Converts any type mismatched values to their target type if a reasonable conversion is possible. This function returns unknown, so it is essential to check the return value before use. */
+  /** Converts any type mismatched values to their target type if a reasonable conversion is possible. This function does not type check the input value and may return invalid results for invalid inputs. You should type check the result before use. */
   export function Convert<T extends Types.TSchema>(schema: T, references: Types.TSchema[], value: unknown): unknown
-  /** Converts any type mismatched values to their target type if a reasonable conversion is possible. This function returns unknown, so it is essential to check the return value before use. */
+  /** Converts any type mismatched values to their target type if a reasonable conversion is possible. This function does not type check the input value and may return invalid results for invalid inputs. You should type check the result before use. */
   export function Convert<T extends Types.TSchema>(schema: T, value: unknown): unknown
-  /** Converts any type mismatched values to their target type if a reasonable conversion is possible This function returns unknown, so it is essential to check the return value before use. */
+  /** Converts any type mismatched values to their target type if a reasonable conversion is possible. This function does not type check the input value and may return invalid results for invalid inputs. You should type check the result before use. */
   export function Convert(...args: any[]) {
     return ValueConvert.Convert.apply(ValueConvert, args as any)
   }
@@ -87,14 +87,6 @@ export namespace Value {
   export function Create(...args: any[]) {
     return ValueCreate.Create.apply(ValueCreate, args as any)
   }
-  /** `[Mutable]` Patches a given value with defaults derived from default schema annotations. This function is mutable and will modify the input value. To avoid mutation, clone the input value prior to calling this function. This function may return an incomplete or invalid result and should be checked before use. */
-  export function Default<T extends Types.TSchema>(schema: T, references: Types.TSchema[], value: unknown): unknown
-  /** `[Mutable]` Patches a given value with defaults derived from default schema annotations. This function is mutable and will modify the input value. To avoid mutation, clone the input value prior to calling this function. This function may return an incomplete or invalid result and should be checked before use. */
-  export function Default<T extends Types.TSchema>(schema: T, value: unknown): unknown
-  /** `[Mutable]` Patches a given value with defaults derived from default schema annotations. This function is mutable and will modify the input value. To avoid mutation, clone the input value prior to calling this function. This function may return an incomplete or invalid result and should be checked before use. */
-  export function Default(...args: any[]) {
-    return ValueDefault.Default.apply(ValueDefault, args as any)
-  }
   /** Decodes a value or throws if error */
   export function Decode<T extends Types.TSchema, D = Types.StaticDecode<T>>(schema: T, references: Types.TSchema[], value: unknown): D
   /** Decodes a value or throws if error */
@@ -105,6 +97,14 @@ export namespace Value {
     if (!Check(schema, references, value)) throw new ValueTransform.TransformDecodeCheckError(schema, value, Errors(schema, references, value).First()!)
     return ValueTransform.DecodeTransform.Decode(schema, references, value, ValueCheck.Check)
   }
+  /** Applies default annotations to missing values and returns the result. This function does not type check the input value and may return invalid results for invalid inputs. You should type check the result before use. */
+  export function Default<T extends Types.TSchema>(schema: T, references: Types.TSchema[], value: unknown): unknown
+  /** Applies default annotations to missing values and returns the result. This function does not type check the input value and may return invalid results for invalid inputs. You should type check the result before use. */
+  export function Default<T extends Types.TSchema>(schema: T, value: unknown): unknown
+  /** Applies default annotations to missing values and returns the result. This function does not type check the input value and may return invalid results for invalid inputs. You should type check the result before use. */
+  export function Default(...args: any[]) {
+    return ValueDefault.Default.apply(ValueDefault, args as any)
+  }
   /** Encodes a value or throws if error */
   export function Encode<T extends Types.TSchema, E = Types.StaticEncode<T>>(schema: T, references: Types.TSchema[], value: unknown): E
   /** Encodes a value or throws if error */
@@ -136,12 +136,12 @@ export namespace Value {
   export function Hash(value: unknown): bigint {
     return ValueHash.Hash(value)
   }
-  /** Returns a new value with edits applied to the given value */
+  /** Applies edits to the current value and returns the result */
   export function Patch<T = any>(current: unknown, edits: ValueDelta.Edit[]): T {
     return ValueDelta.Patch(current, edits) as T
   }
-  /** `[Mutable]` Transforms the current value into the next value and returns the result. This function performs mutable operations on the current value. To avoid mutation, clone the current value before passing to this function. */
-  export function Transmute<Next extends ValueMutate.Transmutable>(current: ValueMutate.Transmutable, next: Next): Next {
-    return ValueMutate.Transmute(current, next)
+  /** Transforms the current value into the next value and returns the result. This function performs mutable operations on the input value. To avoid mutation, clone the input value before passing to this function. */
+  export function Transmute<Next extends ValueTransmute.Transmutable>(current: ValueTransmute.Transmutable, next: Next): Next {
+    return ValueTransmute.Transmute(current, next)
   }
 }