From 9d5a3b33ffeddd0827be1798cb9f116ab85e602e Mon Sep 17 00:00:00 2001 From: sinclair Date: Sat, 28 Oct 2023 04:29:51 +0900 Subject: [PATCH] updates --- examples/index.ts | 19 +++++++++---- src/value/cast.ts | 6 ++-- src/value/clean.ts | 6 ++-- src/value/convert.ts | 6 ++-- src/value/default.ts | 6 ++-- src/value/transmute.ts | 2 +- src/value/value.ts | 62 +++++++++++++++++++++--------------------- 7 files changed, 57 insertions(+), 50 deletions(-) diff --git a/examples/index.ts b/examples/index.ts index c660cbef8..90f6267da 100644 --- a/examples/index.ts +++ b/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) diff --git a/src/value/cast.ts b/src/value/cast.ts index 6f57df5cd..3aa626e38 100644 --- a/src/value/cast.ts +++ b/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(schema: T, references: Types.TSchema[], value: unknown): Types.Static -/** 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(schema: T, value: unknown): Types.Static -/** 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]) } diff --git a/src/value/clean.ts b/src/value/clean.ts index 43729bf69..e0bddd64f 100644 --- a/src/value/clean.ts +++ b/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(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(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]) } diff --git a/src/value/convert.ts b/src/value/convert.ts index f124e6d62..3cf2146c6 100644 --- a/src/value/convert.ts +++ b/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(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(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]) } diff --git a/src/value/default.ts b/src/value/default.ts index cb906b56c..1c35e812b 100644 --- a/src/value/default.ts +++ b/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(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(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]) } diff --git a/src/value/transmute.ts b/src/value/transmute.ts index fa626f89c..1d74c63d8 100644 --- a/src/value/transmute.ts +++ b/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(current: Transmutable, next: Next): Next { if (IsNonMutableValue(current) || IsNonMutableValue(next)) throw new ValueMutateInvalidRootMutationError() if (IsMismatchedValue(current, next)) throw new ValueMutateTypeMismatchError() diff --git a/src/value/value.ts b/src/value/value.ts index 4eb4c9fab..52e30872e 100644 --- a/src/value/value.ts +++ b/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(schema: T, references: Types.TSchema[], value: unknown): Types.Static - /** 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(schema: T, value: unknown): Types.Static - /** 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(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(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(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(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(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(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(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(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>(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(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(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>(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(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(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(current: ValueTransmute.Transmutable, next: Next): Next { + return ValueTransmute.Transmute(current, next) } }