Version 1.0.51 (#1447)

* Add Required Clone function to Base

* ChangeLog

* Version

Author: sinclairzx81

changelog/1.0.0.md

@@ -3,6 +3,8 @@
 ---
 
 ### Version Updates
+- [Revision 1.0.51](https://github.com/sinclairzx81/typebox/pull/1447)
+  - Add Required Clone function to Base
 - [Revision 1.0.50](https://github.com/sinclairzx81/typebox/pull/1443)
   - Escape Known Property Keys on Additional Properties Checks
 - [Revision 1.0.49](https://github.com/sinclairzx81/typebox/pull/1436)

design/website/docs/type/base.md

@@ -4,18 +4,28 @@ Base class for building extended types.
 
 ## Definition
 
-The Base type is a class definition that includes methods which can be overridden. The two primary methods to override are Check and Errors, both of which are invoked by TypeBox validators. By convention, Base type definitions begin with a leading `T` and are paired with a factory function that creates instances of the type. The following example demonstrates how to define a DateType using Base. 
+The Base type is a class definition that includes methods which can be overridden. The primary methods to override are Check and Errors, which are called by TypeBox validators, and Clone, which is used by the TypeBox compositor to create new instances of Base when composing with other types.
+
+> ⚠️ Important: The Clone method must be overridden; otherwise, a `Clone not implemented` exception may be thrown. This method is used by the type compositor to generate new instances during type composition. Clone is typically required when the Base type is used within computed types such as Partial, Required, Pick, or Omit.
+
+By convention, Base type definitions start with a leading T and are paired with a factory function that creates instances of the type. The following example demonstrates how to define a DateType using Base, implementing the required Check, Errors, and Clone methods.
 
 ```typescript
 export class TDateType extends Type.Base<Date> {
+  // required: Used by validation
   public override Check(value: unknown): value is Date {
     return value instanceof Date
   }
+  // required: Used by validation
   public override Errors(value: unknown): object[] {
     return !this.Check(value) ? [{ message: 'not a Date'}] : []
   }
+  // required: Used by type compositor
+  public override Clone(): TDateType {
+    return new TDateType()
+  }
 }
-
+// factory
 export function DateType(): TDateType {
   return new TDateType()
 }

docs/docs/type/base.html

@@ -1,16 +1,26 @@
 <h1>Base</h1>
 <p>Base class for building extended types.</p>
 <h2>Definition</h2>
-<p>The Base type is a class definition that includes methods which can be overridden. The two primary methods to override are Check and Errors, both of which are invoked by TypeBox validators. By convention, Base type definitions begin with a leading <code>T</code> and are paired with a factory function that creates instances of the type. The following example demonstrates how to define a DateType using Base. </p>
+<p>The Base type is a class definition that includes methods which can be overridden. The primary methods to override are Check and Errors, which are called by TypeBox validators, and Clone, which is used by the TypeBox compositor to create new instances of Base when composing with other types.</p>
+<blockquote>
+<p>⚠️ Important: The Clone method must be overridden; otherwise, a <code>Clone not implemented</code> exception may be thrown. This method is used by the type compositor to generate new instances during type composition. Clone is typically required when the Base type is used within computed types such as Partial, Required, Pick, or Omit.</p>
+</blockquote>
+<p>By convention, Base type definitions start with a leading T and are paired with a factory function that creates instances of the type. The following example demonstrates how to define a DateType using Base, implementing the required Check, Errors, and Clone methods.</p>
 <pre><code class="language-typescript">export class TDateType extends Type.Base&lt;Date&gt; {
+  // required: Used by validation
   public override Check(value: unknown): value is Date {
     return value instanceof Date
   }
+  // required: Used by validation
   public override Errors(value: unknown): object[] {
     return !this.Check(value) ? [{ message: &#39;not a Date&#39;}] : []
   }
+  // required: Used by type compositor
+  public override Clone(): TDateType {
+    return new TDateType()
+  }
 }
-
+// factory
 export function DateType(): TDateType {
   return new TDateType()
 }

src/compile/validator.ts

@@ -28,53 +28,75 @@ THE SOFTWARE.
 
 // deno-fmt-ignore-file
 
+import { Arguments } from '../system/arguments/index.ts'
 import { Environment } from '../system/environment/index.ts'
 import { type TLocalizedValidationError } from '../error/index.ts'
 import { type StaticDecode, type StaticEncode, type TProperties, type TSchema, Base } from '../type/index.ts'
 import { Errors, Clean, Convert, Create, Default, Decode, Encode, HasCodec, Parser } from '../value/index.ts'
 import { Build } from '../schema/index.ts'
 
 // ------------------------------------------------------------------
-// ValidatorType<...>
+// Validator<...>
 // ------------------------------------------------------------------
 export class Validator<Context extends TProperties = TProperties, Type extends TSchema = TSchema> extends Base<StaticEncode<Type, Context>> {
+  private readonly context: Context
+  private readonly type: Type
   private readonly isEvaluated: boolean
   private readonly hasCodec: boolean
   private readonly code: string
   private readonly check: (value: unknown) => boolean
-  constructor(
-    private readonly context: Context,
-    private readonly type: Type,
-  ) {
+  /** Constructs a Validator with the given Context and Type. */
+  constructor(context: Context, type: Type)
+  /** Constructs a Validator with the given arguments. */
+  constructor(context: Context, type: Type, isEvaluated: boolean, hasCodec: boolean, code: string, check: (value: unknown) => boolean)
+  /** Constructs a Validator. */
+  constructor(...args: unknown[]) {
     super()
-    const result = Build(context, type).Evaluate()
-    this.hasCodec = HasCodec(context, type)
-    this.isEvaluated = result.IsEvaluated
-    this.code = result.Code
-    this.check = result.Check as never
+    const matched: [Context, Type, boolean, boolean, string, (value: unknown) => boolean] | [Context, Type] = Arguments.Match(args, {
+      6: (context, type, isEvalulated, hasCodec, code, check) => [context, type, isEvalulated, hasCodec, code, check],
+      2: (context, type) => [context, type]
+    })
+    if(matched.length === 6) {
+      const [context, type, isEvaluated, hasCodec, code, check] = matched
+      this.context = context
+      this.type = type
+      this.isEvaluated = isEvaluated
+      this.hasCodec = hasCodec
+      this.code = code
+      this.check = check
+    } else {
+      const [context, type] = matched as [Context, Type]
+      const result = Build(context, type).Evaluate()
+      this.hasCodec = HasCodec(context, type)
+      this.context = context
+      this.type = type
+      this.isEvaluated = result.IsEvaluated
+      this.code = result.Code
+      this.check = result.Check as never
+    }
   }
   // ----------------------------------------------------------------
-  // Evaluated
+  // IsEvaluated
   // ----------------------------------------------------------------
-  /** Returns true if this validator is using runtime eval optimizations */
+  /** Returns true if this validator is using runtime eval optimizations. */
   public IsEvaluated(): boolean {
     return this.isEvaluated
   }
   // ----------------------------------------------------------------
-  // Schema
+  // Context | Type
   // ----------------------------------------------------------------
-  /** Returns the Context for this validator */
+  /** Returns the Context for this validator. */
   public Context(): Context {
     return this.context
   }
-  /** Returns the Type for this validator */
+  /** Returns the Type for this validator. */
   public Type(): Type {
     return this.type
   }
   // ----------------------------------------------------------------
   // Code
   // ----------------------------------------------------------------
-  /** Returns the generated code for this validator */
+  /** Returns the generated code for this validator. */
   public Code(): string {
     return this.code
   }
@@ -106,6 +128,17 @@ export class Validator<Context extends TProperties = TProperties, Type extends T
   public override Default(value: unknown): unknown {
     return Default(this.context, this.type, value)
   }
+  /** Clones this validator. */
+  public override Clone(): Validator<Context, Type> {
+    return new Validator<Context, Type>(
+      this.context,
+      this.type, 
+      this.isEvaluated, 
+      this.hasCodec, 
+      this.code, 
+      this.check
+    )
+  }
   // ----------------------------------------------------------------
   // Parse | Decode | Encode
   // ----------------------------------------------------------------

src/type/engine/instantiate.ts

@@ -44,6 +44,7 @@ import { type TReadonly, IsReadonly, ReadonlyAdd, ReadonlyRemove, TReadonlyAdd,
 import { type TSchema, type TSchemaOptions, IsSchema } from '../types/schema.ts'
 import { type TArray, Array, IsArray, ArrayOptions } from '../types/array.ts'
 import { type TAsyncIterator, AsyncIterator, IsAsyncIterator, AsyncIteratorOptions } from '../types/async-iterator.ts'
+import { IsBase } from '../types/base.ts'
 import { type TConstructor, Constructor, IsConstructor, ConstructorOptions } from '../types/constructor.ts'
 import { type TDeferred, Deferred, IsDeferred } from '../types/deferred.ts'
 import { type TFunction, Function as _Function, IsFunction, FunctionOptions } from '../types/function.ts'
@@ -336,12 +337,14 @@ function InstantiateDeferred<Context extends TProperties, State extends TState,
 // InstantiateType
 // ------------------------------------------------------------------
 export type TInstantiateType<Context extends TProperties, State extends TState, Input extends TSchema,
-  IsImmutable extends boolean = Input extends TImmutable ? true : false,
-  ModifierState extends [TSchema, ModifierAction, ModifierAction] = TModifierActions<Input, 
-    Input extends TReadonly<Input> ? 'add' : 'none', 
-    Input extends TOptional<Input> ? 'add' : 'none'
-  >, 
-  Type extends TSchema = ModifierState[0],
+  Cloned extends TSchema = Input, // symmetry only
+  Immutable extends boolean = Cloned extends TImmutable ? true : false,
+  Modifiers extends [TSchema, ModifierAction, ModifierAction] = TModifierActions<Cloned, 
+    Cloned extends TReadonly<Cloned> ? 'add' : 'none', 
+    Cloned extends TOptional<Cloned> ? 'add' : 'none'
+  >,
+
+  Type extends TSchema = Modifiers[0],
   Instantiated extends TSchema = (
     Type extends TRef<infer Ref extends string> ? TRefInstantiate<Context, State, Ref> :
     Type extends TArray<infer Type extends TSchema> ? TArray<TInstantiateType<Context, State, Type>> :
@@ -360,16 +363,20 @@ export type TInstantiateType<Context extends TProperties, State extends TState,
     Type extends TUnion<infer Types extends TSchema[]> ? TUnion<TInstantiateTypes<Context, State, Types>> :
     Type
   ),
-  WithImmutable extends TSchema = IsImmutable extends true ? TImmutable<Instantiated> : Instantiated,
-  WithModifiers extends TSchema = TApplyReadonly<ModifierState[1], TApplyOptional<ModifierState[2], WithImmutable>>,
+  WithImmutable extends TSchema = Immutable extends true ? TImmutable<Instantiated> : Instantiated,
+  WithModifiers extends TSchema = TApplyReadonly<Modifiers[1], TApplyOptional<Modifiers[2], WithImmutable>>,
 > = WithModifiers
 
 export function InstantiateType<Context extends TProperties, State extends TState, Type extends TSchema>
   (context: Context, state: State, input: Type): 
     TInstantiateType<Context, State, Type> {
-  const isImmutable = IsImmutable(input)
-  const modifierActions = ModifierActions(input, IsReadonly(input) ? 'add' : 'none', IsOptional(input) ? 'add' : 'none')
-  const type = modifierActions[0]
+  const cloned = IsBase(input) ? input.Clone() : input
+  const immutable = IsImmutable(cloned)
+  const modifiers = ModifierActions(cloned, 
+    IsReadonly(cloned) ? 'add' : 'none', 
+    IsOptional(cloned) ? 'add' : 'none')
+
+  const type = modifiers[0]
   const instantiated = (
     IsRef(type) ? RefInstantiate(context, state, type.$ref) :
     IsArray(type) ? Array(InstantiateType(context, state, type.items), ArrayOptions(type)) :
@@ -388,8 +395,8 @@ export function InstantiateType<Context extends TProperties, State extends TStat
     IsUnion(type) ? Union(InstantiateTypes(context, state, type.anyOf), UnionOptions(type)) :
     type
   )
-  const withImmutable = isImmutable ? Immutable(instantiated) : instantiated
-  const withModifiers = ApplyReadonly(modifierActions[1], ApplyOptional(modifierActions[2], withImmutable))
+  const withImmutable = immutable ? Immutable(instantiated) : instantiated
+  const withModifiers = ApplyReadonly(modifiers[1], ApplyOptional(modifiers[2], withImmutable))
   return withModifiers as never
 }
 // ------------------------------------------------------------------

src/type/types/base.ts

@@ -40,27 +40,24 @@ export type StaticBase<Value extends unknown> = Value
 // ------------------------------------------------------------------
 // Type.Base<...>
 // ------------------------------------------------------------------
+function BaseProperty<Value>(value: Value): PropertyDescriptor {
+  return {
+    enumerable: Settings.Get().enumerableKind,
+    writable: false,
+    configurable: false,
+    value
+  }
+}
 /** Base class for creating extension types. */
 export class Base<Value extends unknown = unknown> implements TSchema, XGuard<Value> {
   public readonly '~kind': 'Base'
   public readonly '~guard': XGuardInterface<Value>
   constructor() {
-    const configuration = {
-      enumerable: Settings.Get().enumerableKind,
-      writable: false,
-      configurable: false,
-    }
-    globalThis.Object.defineProperty(this, '~kind', {       
-      ...configuration,
-      value: 'Base'
-    })
-    globalThis.Object.defineProperty(this, '~guard', {       
-      ...configuration,
-      value: {
-        check: (value): value is Value => this.Check(value),
-        errors: (value) => this.Errors(value)
-      } as XGuardInterface<Value>
-    })
+    globalThis.Object.defineProperty(this, '~kind', BaseProperty('Base'))
+    globalThis.Object.defineProperty(this, '~guard', BaseProperty<XGuardInterface<Value>>({
+      check: (value): value is Value => this.Check(value),
+      errors: (value) => this.Errors(value)
+    }))
   }
   /** Checks a value or returns false if invalid */
   public Check(value: unknown): value is Value {
@@ -86,6 +83,10 @@ export class Base<Value extends unknown = unknown> implements TSchema, XGuard<Va
   public Create(): Value {
     throw new Error('Create not implemented')
   }
+  /** Clones this type  */
+  public Clone(): Base {
+    throw Error('Clone not implemented')
+  }
 }
 // ------------------------------------------------------------------
 // Guard

tasks.ts

@@ -8,7 +8,7 @@ import { Range } from './task/range/index.ts'
 import { Metrics } from './task/metrics/index.ts'
 import { Task } from 'tasksmith'
 
-const Version = '1.0.50'
+const Version = '1.0.51'
 
 // ------------------------------------------------------------------
 // Build

test/typebox/runtime/type/types/base.ts

@@ -54,3 +54,69 @@ Test('Should Base 8', () => {
   const T: TStringBase = StringBase()
   Assert.IsEqual(T.Errors(1), [{ message: 'expected string' }])
 })
+// ------------------------------------------------------------------
+// Clone - Compositor
+// ------------------------------------------------------------------
+Test('Should Base 9', () => {
+  class Foo extends Type.Base {
+    public override Clone(): Type.Base {
+      return new Foo()
+    }
+  }
+  const T = new Foo()
+  // Non-Action
+  const A = Type.Object({ value: T })
+  Assert.IsFalse(Type.IsOptional(T))
+  Assert.IsFalse(Type.IsOptional(A.properties.value))
+  // Action
+  const B = Type.Partial(A)
+  Assert.IsFalse(Type.IsOptional(T))
+  Assert.IsFalse(Type.IsOptional(A.properties.value))
+  Assert.IsTrue(Type.IsOptional(B.properties.value))
+})
+Test('Should Base 10', () => {
+  class Foo extends Type.Base {}
+  const T = new Foo()
+  const A = Type.Object({ value: T })
+  Assert.IsFalse(Type.IsOptional(T))
+  Assert.IsFalse(Type.IsOptional(A.properties.value))
+  Assert.Throws(() => Type.Partial(A)) // action require Clone
+})
+// ------------------------------------------------------------------
+// https://github.com/sinclairzx81/typebox/issues/1444
+// ------------------------------------------------------------------
+Test('Should Base 11', () => {
+  class TDateType extends Type.Base<Date> {
+    public override Clone(): TDateType {
+      return new TDateType()
+    }
+  }
+  const DateType = () => new TDateType()
+  const A = Type.Object({
+    status: Type.String(),
+    updatedDate: DateType(),
+    createdDate: DateType()
+  })
+  const B = Type.Evaluate(Type.Intersect([A, Type.Object({ count: Type.Number() })]))
+  const C = Type.Object({ freeSchema: Type.Partial(B) })
+  const D = Type.Evaluate(Type.Intersect([A, Type.Object({ count: Type.Number() })]))
+  // A
+  Assert.IsFalse(Type.IsOptional(A.properties.status))
+  Assert.IsFalse(Type.IsOptional(A.properties.updatedDate))
+  Assert.IsFalse(Type.IsOptional(A.properties.createdDate))
+  // B
+  Assert.IsFalse(Type.IsOptional(B.properties.status))
+  Assert.IsFalse(Type.IsOptional(B.properties.updatedDate))
+  Assert.IsFalse(Type.IsOptional(B.properties.createdDate))
+  Assert.IsFalse(Type.IsOptional(B.properties.count))
+  // C
+  Assert.IsTrue(Type.IsOptional(C.properties.freeSchema.properties.status))
+  Assert.IsTrue(Type.IsOptional(C.properties.freeSchema.properties.updatedDate))
+  Assert.IsTrue(Type.IsOptional(C.properties.freeSchema.properties.createdDate))
+  Assert.IsTrue(Type.IsOptional(C.properties.freeSchema.properties.count))
+  // D
+  Assert.IsFalse(Type.IsOptional(D.properties.status))
+  Assert.IsFalse(Type.IsOptional(D.properties.updatedDate))
+  Assert.IsFalse(Type.IsOptional(D.properties.createdDate))
+  Assert.IsFalse(Type.IsOptional(D.properties.count))
+})