Use Array Mutation on Convert

readme.md

@@ -1209,7 +1209,7 @@ const R = Value.Check(T, { x: 1 })                   // const R = true
 
 ### Convert
 
-Use the Convert function to convert a value into its target type if a reasonable conversion is possible. This function may return an invalid value and should be checked before use. Its return type is `unknown`.
+Use the Convert function to convert a value into its target type if a reasonable conversion is possible. This function may return an invalid value and should be checked before use. Its return type is `unknown`. Convert is a mutable operation. To avoid mutation, Clone the value first.
 
 ```typescript
 const T = Type.Object({ x: Type.Number() })

src/value/convert/convert.ts

@@ -164,7 +164,10 @@ function Default(value: any) {
 // ------------------------------------------------------------------
 function FromArray(schema: TArray, references: TSchema[], value: any): any {
   const elements = IsArray(value) ? value : [value]
-  return elements.map((element) => Visit(schema.items, references, element))
+  for(let i = 0; i < elements.length; i++) {
+    elements[i] = Visit(schema.items, references, elements[i])
+  }
+  return elements
 }
 function FromBigInt(schema: TBigInt, references: TSchema[], value: any): unknown {
   return TryConvertBigInt(value)
@@ -289,11 +292,11 @@ function Visit(schema: TSchema, references: TSchema[], value: any): unknown {
 // ------------------------------------------------------------------
 // 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. Convert is a mutable operation. To avoid mutation, Clone the value first. */
 export function Convert(schema: TSchema, references: 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. Convert is a mutable operation. To avoid mutation, Clone the value first. */
 export function Convert(schema: 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. Convert is a mutable operation. To avoid mutation, Clone the value first. */
 // prettier-ignore
 export function Convert(...args: any[]) {
   return args.length === 3 

src/value/value/value.ts

@@ -75,11 +75,11 @@ export function Clean(schema: TSchema, value: unknown): unknown
 export function Clean(...args: any[]) {
   return CleanValue.apply(CleanValue, args as any)
 }
-/** Converts any type mismatched values to their target type if a reasonable conversion is possible */
+/** `[Mutable]` Converts any type mismatched values to their target type if a reasonable conversion is possible. Convert is a mutable operation. To avoid mutation, Clone the value first. */
 export function Convert(schema: TSchema, references: TSchema[], value: unknown): unknown
-/** Converts any type mismatched values to their target type if a reasonable conversion is possibl. */
+/** `[Mutable]` Converts any type mismatched values to their target type if a reasonable conversion is possible. Convert is a mutable operation. To avoid mutation, Clone the value first. */
 export function Convert(schema: TSchema, value: unknown): unknown
-/** Converts any type mismatched values to their target type if a reasonable conversion is possible */
+/** `[Mutable]` Converts any type mismatched values to their target type if a reasonable conversion is possible. Convert is a mutable operation. To avoid mutation, Clone the value first. */
 export function Convert(...args: any[]) {
   return ConvertValue.apply(ConvertValue, args as any)
 }

test/runtime/value/convert/array.ts

@@ -53,4 +53,13 @@ describe('value/convert/Array', () => {
     const R = Value.Convert(T, { x: '1', y: true, z: null })
     Assert.IsEqual(R, [{ x: 1, y: 1, z: null }])
   })
+  // ----------------------------------------------------------------
+  // Array Mutation
+  // ----------------------------------------------------------------
+  it('Should mutate array on conversion', () => {
+    const T = Type.Array(Type.Number())
+    const V = ['1', '2', '3']
+    Value.Convert(T, V)
+    Assert.IsEqual(V, [1, 2, 3])
+  })
 })

test/runtime/value/convert/object.ts

@@ -21,13 +21,16 @@ describe('value/convert/Object', () => {
     const R = Value.Convert(T, { x: '42', y: 'true', z: 'hello' })
     Assert.IsEqual(R, { x: 42, y: true, z: 'hello' })
   })
+  // ----------------------------------------------------------------
+  // Object Mutation
+  // ----------------------------------------------------------------
   it('Should mutate object on conversion', () => {
     const T = Type.Object({
       x: Type.Number(),
       y: Type.Boolean()
     })
-    const value = { x: '42', y: 'true', z: 'hello' }
-    Value.Convert(T, value)
-    Assert.IsEqual(value, { x: 42, y: true, z: 'hello' })
+    const V = { x: '42', y: 'true' }
+    Value.Convert(T, V)
+    Assert.IsEqual(V, { x: 42, y: true })
   })
 })