General Maintenance (#489)

Author: sinclairzx81

example/collections/readme.md

@@ -0,0 +1,3 @@
+# Collections
+
+This example implements runtime type safe generic `Array`, `Map` and `Set` collection types using TypeBox types as the generic type arguments.

example/experimental/experimental.ts

@@ -1,6 +1,6 @@
 /*--------------------------------------------------------------------------
 
-@sinclair/typebox/extensions
+@sinclair/typebox/experimental
 
 The MIT License (MIT)
 
@@ -26,4 +26,6 @@ THE SOFTWARE.
 
 ---------------------------------------------------------------------------*/
 
-export * from './experimental'
+export * from './readonly-object'
+export * from './union-enum'
+export * from './union-oneof'

example/experimental/index.ts

@@ -1,30 +1,54 @@
-# ExperimentalTypeBuilder
+# Experimental Types
 
-An experimental TypeBox type builder with additional custom types.
+These examples are a set of experiemental candidate types that may introduced into TypeBox in future.
 
-## Overview
+## ReadonlyObject
 
-The TypeBox TypeBuilder classes are designed to be extended with user defined types. Instances where you may wish to do this are if your application is dependent on custom schematics and/or non-JSON serializable values (an example of which might be a Mongo's `ObjectId` or other such non-serializable value)
+Maps an object properties as `readonly`.
 
-## Application Type Builder
+```typescript
+import { ReadonlyObject } from './experimental'
+
+const T = ReadonlyObject(Type.Object({
+  x: Type.Number()
+}))
+
+type T = Static<typeof T>                           // type T = {
+                                                    //   readonly x: number
+                                                    // }
+```
+## UnionEnum
 
-The following shows creating a simple `ApplicationTypeBuilder` with additional types `Nullable` and `StringEnum`. These types are fairly common in OpenAPI implementations.
+Creates an `enum` union string schema representation.
 
 ```typescript
-import { StandardTypeBuilder, Static, TSchema } from '@sinclair/typebox'
-
-export class ApplicationTypeBuilder extends StandardTypeBuilder { // only JSON Schema types
-  public Nullable<T extends TSchema>(schema: T) {
-    return this.Unsafe<Static<T> | null>({ ...schema, nullable: true })
-  }
-  public StringEnum<T extends string[]>(values: [...T]) {
-    return this.Unsafe<T[number]>({ type: 'string', enum: values })
-  }
-}
-
-export const Type = new ApplicationTypeBuilder()    // re-export!
+import { UnionEnum } from './experimental'
+
+
+const T = UnionEnum(['A', 'B', 'C'])                // const T = {
+                                                    //   enum: ['A', 'B', 'C']
+                                                    // }
+
+type T = Static<typeof T>                           // type T = 'A' | 'B' | 'C'
+
 ```
+## UnionOneOf
+
+Creates a `oneOf` union representation.
+
+
+```typescript
+import { UnionOneOf } from './experimental'
+
+
+const T = UnionOneOf([                              // const T = {
+  Type.Literal('A'),                                //   oneOf: [
+  Type.Literal('B'),                                //     { const: 'A' },
+  Type.Literal('C')                                 //     { const: 'B' },
+])                                                  //     { const: 'C' },
+                                                    //   ]
+                                                    // }
 
-## Experimental Type Builder
+type T = Static<typeof T>                           // type T = 'A' | 'B' | 'C'
 
-The `experimental.ts` file provided with this example shows advanced usage by creating complex types for potential inclusion in the TypeBox library in later revisions. It is offered for reference, experimentation and is open to contributor submission.
+```

example/experimental/readme.md

@@ -0,0 +1,68 @@
+/*--------------------------------------------------------------------------
+
+@sinclair/typebox/experimental
+
+The MIT License (MIT)
+
+Copyright (c) 2017-2023 Haydn Paterson (sinclair) <[email protected]>
+
+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.
+
+---------------------------------------------------------------------------*/
+
+import * as Types from '@sinclair/typebox'
+
+// -------------------------------------------------------------------------------------
+// TReadonlyObject
+// -------------------------------------------------------------------------------------
+export type TReadonlyArray<T extends Types.TSchema[]> = Types.Assert<{ [K in keyof T]: TReadonlyObject<Types.Assert<T[K], Types.TSchema>> }, Types.TSchema[]>
+// prettier-ignore
+export type TReadonlyProperties<T extends Types.TProperties> = Types.Evaluate<Types.Assert<{
+  [K in keyof T]:
+  T[K] extends Types.TReadonlyOptional<infer U> ? Types.TReadonlyOptional<U> :
+  T[K] extends Types.TReadonly<infer U> ? Types.TReadonly<U> :
+  T[K] extends Types.TOptional<infer U> ? Types.TReadonlyOptional<U> :
+  Types.TReadonly<T[K]>
+}, Types.TProperties>>
+// prettier-ignore
+export type TReadonlyObject<T extends Types.TSchema> =
+  T extends Types.TIntersect<infer S> ? Types.TIntersect<TReadonlyArray<S>> :
+  T extends Types.TUnion<infer S> ? Types.TUnion<TReadonlyArray<S>> :
+  T extends Types.TObject<infer S> ? Types.TObject<TReadonlyProperties<S>> :
+  Types.TReadonly<T>
+
+/** `[Experimental]` Remaps a Intersect, Union or Object as readonly */
+export function ReadonlyObject<T extends Types.TSchema>(schema: T): TReadonlyObject<T> {
+  function Apply(property: Types.TSchema): any {
+    // prettier-ignore
+    switch (property[Types.Modifier]) {
+      case 'ReadonlyOptional': property[Types.Modifier] = 'ReadonlyOptional'; break
+      case 'Readonly': property[Types.Modifier] = 'Readonly'; break
+      case 'Optional': property[Types.Modifier] = 'ReadonlyOptional'; break
+      default: property[Types.Modifier] = 'Readonly'; break
+    }
+    return property
+  }
+  // prettier-ignore
+  return (Types.TypeGuard.TIntersect(schema) || Types.TypeGuard.TUnion(schema) || Types.TypeGuard.TObject(schema))
+    ? Types.ObjectMap.Map<TReadonlyObject<T>>(schema, (schema) => {
+      globalThis.Object.keys(schema.properties).forEach(key => Apply(schema.properties[key]))
+      return schema
+    }, {}) : Apply(schema)
+}

example/experimental/readonly-object.ts

@@ -1,6 +1,6 @@
 /*--------------------------------------------------------------------------
 
-@sinclair/typebox/typedef
+@sinclair/typebox/experimental
 
 The MIT License (MIT)
 
@@ -26,4 +26,22 @@ THE SOFTWARE.
 
 ---------------------------------------------------------------------------*/
 
-export * from './typedef'
+import * as Types from '@sinclair/typebox'
+
+// -------------------------------------------------------------------------------------
+// TUnionEnum
+// -------------------------------------------------------------------------------------
+export interface TUnionEnum<T extends (string | number)[]> extends Types.TSchema {
+  [Types.Kind]: 'UnionEnum'
+  static: T[number]
+  enum: T
+}
+
+/** `[Experimental]` Creates a Union type with a `enum` schema representation  */
+export function UnionEnum<T extends (string | number)[]>(values: [...T], options: Types.SchemaOptions = {}) {
+  function UnionEnumCheck(schema: TUnionEnum<(string | number)[]>, value: unknown) {
+    return (typeof value === 'string' || typeof value === 'number') && schema.enum.includes(value)
+  }
+  if (!Types.TypeRegistry.Has('UnionEnum')) Types.TypeRegistry.Set('UnionEnum', UnionEnumCheck)
+  return { ...options, [Types.Kind]: 'UnionEnum', enum: values } as TUnionEnum<T>
+}

example/typedef/index.ts renamed to example/experimental/union-enum.ts

@@ -1,6 +1,6 @@
 /*--------------------------------------------------------------------------
 
-@sinclair/typebox/legacy
+@sinclair/typebox/experimental
 
 The MIT License (MIT)
 
@@ -26,4 +26,19 @@ THE SOFTWARE.
 
 ---------------------------------------------------------------------------*/
 
-export * from './intersect'
+import * as Types from '@sinclair/typebox'
+import { Value } from '@sinclair/typebox/value'
+
+export interface TUnionOneOf<T extends Types.TSchema[]> extends Types.TSchema {
+  [Types.Kind]: 'UnionOneOf'
+  static: { [K in keyof T]: Types.Static<T[K]> }[number]
+  oneOf: T
+}
+/** `[Experimental]` Creates a Union type with a `oneOf` schema representation */
+export function UnionOneOf<T extends Types.TSchema[]>(oneOf: [...T], options: Types.SchemaOptions = {}) {
+  function UnionOneOfCheck(schema: TUnionOneOf<Types.TSchema[]>, value: unknown) {
+    return 1 === schema.oneOf.reduce((acc: number, schema: any) => (Value.Check(schema, value) ? acc + 1 : acc), 0)
+  }
+  if (!Types.TypeRegistry.Has('UnionOneOf')) Types.TypeRegistry.Set('UnionOneOf', UnionOneOfCheck)
+  return { ...options, [Types.Kind]: 'UnionOneOf', oneOf } as TUnionOneOf<T>
+}

example/legacy/index.ts renamed to example/experimental/union-oneof.ts

@@ -1,35 +1,11 @@
-# String Formats
+# Formats
 
-TypeBox does not implement any string formats by default. However it is possible to register user defined formats using the `FormatRegistry`. Once registered, the format becomes available to both `Value` and `TypeCompiler` modules.
+This example provides TypeCompiler supported versions of the `ajv-formats` package.
 
-## FormatRegistry
-
-The following shows basic usage of the format registry
-
-```typescript
-import { Type, FormatRegistry } from '@sinclair/typebox'
-import { Value } from '@sinclair/typebox/value'
-
-// Register the 'foo-only' format. The format checks for 'foo' only.
-FormatRegistry.Set('foo-only', value => value === 'foo')
-
-const T = Type.String({ format: 'foo-only' })
-
-// Validate
-Value.Check(T, 'foo') // true
-Value.Check(T, 'bar') // false
-```
-
-## Standard Formats
+## Standard
 
 The `standard.ts` file provided with this example implements several standard string formats. 
 
-```typescript
-import './standard'
-```
-
-The following formats are implemented by `standard.ts`
-
 | Format      | Description |
 | ---         | --- |
 | `email`     | Internet email address, see [RFC 5321, section 4.1.2.](http://tools.ietf.org/html/rfc5321#section-4.1.2) |