Documentation

changelog/0.32.0.md

@@ -2,10 +2,50 @@
 
 ## Overview
 
-Revision 0.32.0 focuses primarily on enhancements to the Value module. It includes two new functions, Default and Clean which can be used for pre and post processing values before and after validation. It also includes a new namespace called ValueGuard which provides type safe guards for JavaScript primitive and object values.
+Revision 0.32.0 adds additional enhancements to the Value module. These enhancements are aimed at enabling more fine grained pre and post processing of JavaScript during validation stages.
+
+```typescript
+import { Type, Static, TSchema } from '@sinclair/typebox'
+import { Value } from '@sinclair/typebox/value'
+
+/** User defined parse function */
+export function Parse<T extends TSchema>(schema: T, value: unknown): Static<T> {
+  // pre-process
+  const converted = Value.Convert(schema, value)      // Convert Values
+  const defaulted = Value.Default(schema, converted)  // Add Defaults
+  // check
+  const checked = Value.Check(schema, defaulted)      // Check!
+  // post-process
+  return checked 
+    ? Value.Clean(schema, defaulted) as Static<T>     // Discard Unknown Properties
+    : (() => {
+      const first = Value.Errors(schema, defaulted).First()!
+      throw new Error(`${first.message} ${first.path}. Value is ${first.value}`)
+    })()
+}
+
+// Parses for these environment variables
+const environment = Parse(Type.Object({
+  PROCESSOR_ARCHITECTURE: Type.String(),
+  PROCESSOR_IDENTIFIER:  Type.String(),
+  PROCESSOR_LEVEL: Type.Number(),
+  PROCESSOR_REVISION: Type.Number(),
+  UNKNOWN: Type.String({ default: 'some default value' })
+}), process.env)
+
+console.log(environment) // outputs: {
+                         //   PROCESSOR_ARCHITECTURE: '...',
+                         //   PROCESSOR_IDENTIFIER:  '...',
+                         //   PROCESSOR_LEVEL: 32,
+                         //   PROCESSOR_REVISION: 9000,
+                         //   UNKNOWN: 'some default value'
+                         // }
+```
 
 This revision also carries out updates to existing Value functions, and relaxes some of the rules around Types requiring type registration (limiting this requirement to only operations that type check during processing). Other updates include general refactoring and maintaince of existing Value functions.
 
+
+
 This revision contains no breaking changes.
 
 - [Value.Default()](#Default)

examples/index.ts

@@ -1,45 +1,39 @@
 import { TypeSystem } from '@sinclair/typebox/system'
 import { TypeCompiler } from '@sinclair/typebox/compiler'
 import { Value, ValueGuard } from '@sinclair/typebox/value'
-import { Type, TypeGuard, Kind, Static, TSchema, KeyResolver } from '@sinclair/typebox'
+import { Type, TypeGuard, Kind, Static, TSchema, KeyResolver, TObject } from '@sinclair/typebox'
 import { Run } from './benchmark'
 
 // Todo: Investigate Union Default (initialize interior types)
 // Todo: Implement Value.Clean() Tests
 
-const T = Type.Intersect([Type.Number(), Type.Number()])
-const R = Value.Clean(T, { u: null, x: 1 })
-console.log(R)
-// const T = Type.Intersect([
-//   Type.Object({ x: Type.Number() }),
-//   Type.Object({ y: Type.Number() })
-// ], {
-//   unevaluatedProperties: Type.Union([
-//     Type.Number(),
-//     Type.Null()
-//   ])
-// })
-
-// const T = Type.Object(
-//   {
-//     number: Type.Number({ default: 1 }),
-//     negNumber: Type.Number({ default: 1 }),
-//     maxNumber: Type.Number({ default: 3 }),
-//     string: Type.String({ default: 5 }),
-//     longString: Type.String(),
-//     boolean: Type.Boolean(),
-//     deeplyNested: Type.Object({
-//       foo: Type.String({ default: 2 }),
-//       num: Type.Number(),
-//       bool: Type.Boolean(),
-//     }),
-//   },
-//   {
-//     additionalProperties: Type.Any(),
-//   },
-// )
+function ParseEnv<T extends TObject>(schema: T, value: unknown = process.env): Static<T> {
+  const converted = Value.Convert(schema, value)
+  const defaulted = Value.Default(schema, converted)
+  const checked = Value.Check(schema, defaulted)
+  return checked
+    ? (Value.Clean(schema, defaulted) as Static<T>)
+    : (() => {
+        const first = Value.Errors(schema, defaulted).First()!
+        throw new Error(`${first.message} ${first.path}. Value is ${first.value}`)
+      })()
+}
+console.log(process.env)
 
-// const A = Value.Default(T, {})
-// console.log(A)
+const R = Run(
+  () => {
+    const E = ParseEnv(
+      Type.Object({
+        PROCESSOR_ARCHITECTURE: Type.String(),
+        PROCESSOR_IDENTIFIER: Type.String(),
+        PROCESSOR_LEVEL: Type.Number(),
+        PROCESSOR_REVISION: Type.Number(),
+      }),
+    )
+  },
+  {
+    iterations: 2000,
+  },
+)
 
-// console.log(Value.Transmute({}, {}))
+console.log(R)

examples/parse/parse.ts

@@ -0,0 +1,23 @@
+import { Type, Static, TSchema } from '@sinclair/typebox'
+import { Value } from '@sinclair/typebox/value'
+
+/** User defined parse function */
+export function Parse<T extends TSchema>(schema: T, value: unknown): Static<T> {
+  const converted = Value.Convert(schema, value)
+  const defaulted = Value.Default(schema, converted)
+  const checked = Value.Check(schema, defaulted)
+  return checked ? Value.Clean(schema, defaulted) as Static<T> : (() => {
+    const first = Value.Errors(schema, defaulted).First()!
+    throw new Error(`${first.message} ${first.path}. Value is ${first.value}`)
+  })()
+}
+
+// Parse some environment variables
+const environment = Parse(Type.Object({
+  PROCESSOR_ARCHITECTURE: Type.String(),
+  PROCESSOR_IDENTIFIER:  Type.String(),
+  PROCESSOR_LEVEL: Type.Number(),
+  PROCESSOR_REVISION: Type.Number(),
+}), process.env)
+
+console.log(environment)