Decompose monolithic readme into docs/ directory structure

docs/values/assert.md

@@ -0,0 +1,13 @@
+[Overview](../overview.md) | [Installation](../installation.md) | [Usage](../usage.md) | [Types](../types/) | **Values** | [Syntax](../syntax/) | [TypeRegistry](../type-registry.md) | [TypeCheck](../type-check.md)
+
+# Assert
+
+Use the Assert function to assert a value is valid.
+
+```typescript
+let value: unknown = 1;
+
+Value.Assert(Type.Number(), value); // throws AssertError if invalid
+```
+
+Back to [Home](../../readme.md)

docs/values/cast.md

@@ -0,0 +1,20 @@
+[Overview](../overview.md) | [Installation](../installation.md) | [Usage](../usage.md) | [Types](../types/) | **Values** | [Syntax](../syntax/) | [TypeRegistry](../type-registry.md) | [TypeCheck](../type-check.md)
+
+# Cast
+
+Use the Cast function to upcast a value into a target type. This function will retain as much information as possible from the original value. The Cast function is intended to be used in data migration scenarios where existing values need to be upgraded to match a modified type.
+
+```typescript
+const T = Type.Object(
+  { x: Type.Number(), y: Type.Number() },
+  { additionalProperties: false }
+);
+
+const X = Value.Cast(T, null); // const X = { x: 0, y: 0 }
+
+const Y = Value.Cast(T, { x: 1 }); // const Y = { x: 1, y: 0 }
+
+const Z = Value.Cast(T, { x: 1, y: 2, z: 3 }); // const Z = { x: 1, y: 2 }
+```
+
+Back to [Home](../../readme.md)

docs/values/check.md

@@ -0,0 +1,13 @@
+[Overview](../overview.md) | [Installation](../installation.md) | [Usage](../usage.md) | [Types](../types/) | **Values** | [Syntax](../syntax/) | [TypeRegistry](../type-registry.md) | [TypeCheck](../type-check.md)
+
+# Check
+
+Use the Check function to type check a value.
+
+```typescript
+const T = Type.Object({ x: Type.Number() });
+
+const R = Value.Check(T, { x: 1 }); // const R = true
+```
+
+Back to [Home](../../readme.md)

docs/values/clean.md

@@ -0,0 +1,20 @@
+[Overview](../overview.md) | [Installation](../installation.md) | [Usage](../usage.md) | [Types](../types/) | **Values** | [Syntax](../syntax/) | [TypeRegistry](../type-registry.md) | [TypeCheck](../type-check.md)
+
+# Clean
+
+Use Clean to remove excess properties from a value. This function does not check the value and returns an unknown type. You should Check the result before use. Clean is a mutable operation. To avoid mutation, Clone the value first.
+
+```typescript
+const T = Type.Object({
+  x: Type.Number(),
+  y: Type.Number(),
+});
+
+const X = Value.Clean(T, null); // const 'X = null
+
+const Y = Value.Clean(T, { x: 1 }); // const 'Y = { x: 1 }
+
+const Z = Value.Clean(T, { x: 1, y: 2, z: 3 }); // const 'Z = { x: 1, y: 2 }
+```
+
+Back to [Home](../../readme.md)

docs/values/clone.md

@@ -0,0 +1,11 @@
+[Overview](../overview.md) | [Installation](../installation.md) | [Usage](../usage.md) | [Types](../types/) | **Values** | [Syntax](../syntax/) | [TypeRegistry](../type-registry.md) | [TypeCheck](../type-check.md)
+
+# Clone
+
+Use the Clone function to deeply clone a value.
+
+```typescript
+const A = Value.Clone({ x: 1, y: 2, z: 3 }); // const A = { x: 1, y: 2, z: 3 }
+```
+
+Back to [Home](../../readme.md)

docs/values/convert.md

@@ -0,0 +1,15 @@
+[Overview](../overview.md) | [Installation](../installation.md) | [Usage](../usage.md) | [Types](../types/) | **Values** | [Syntax](../syntax/) | [TypeRegistry](../type-registry.md) | [TypeCheck](../type-check.md)
+
+# 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`.
+
+```typescript
+const T = Type.Object({ x: Type.Number() });
+
+const R1 = Value.Convert(T, { x: "3.14" }); // const R1 = { x: 3.14 }
+
+const R2 = Value.Convert(T, { x: "not a number" }); // const R2 = { x: 'not a number' }
+```
+
+Back to [Home](../../readme.md)

docs/values/create.md

@@ -0,0 +1,13 @@
+[Overview](../overview.md) | [Installation](../installation.md) | [Usage](../usage.md) | [Types](../types/) | **Values** | [Syntax](../syntax/) | [TypeRegistry](../type-registry.md) | [TypeCheck](../type-check.md)
+
+# Create
+
+Use the Create function to create a value from a type. TypeBox will use default values if specified.
+
+```typescript
+const T = Type.Object({ x: Type.Number(), y: Type.Number({ default: 42 }) });
+
+const A = Value.Create(T); // const A = { x: 0, y: 42 }
+```
+
+Back to [Home](../../readme.md)

docs/values/decode-encode.md

@@ -0,0 +1,25 @@
+[Overview](../overview.md) | [Installation](../installation.md) | [Usage](../usage.md) | [Types](../types/) | **Values** | [Syntax](../syntax/) | [TypeRegistry](../type-registry.md) | [TypeCheck](../type-check.md)
+
+# Decode / Encode
+
+## Decode
+
+Use the Decode function to decode a value from a type or throw if the value is invalid. The return value will infer as the decoded type. This function will run Transform codecs if available.
+
+```typescript
+const A = Value.Decode(Type.String(), "hello"); // const A = 'hello'
+
+const B = Value.Decode(Type.String(), 42); // throw
+```
+
+## Encode
+
+Use the Encode function to encode a value to a type or throw if the value is invalid. The return value will infer as the encoded type. This function will run Transform codecs if available.
+
+```typescript
+const A = Value.Encode(Type.String(), "hello"); // const A = 'hello'
+
+const B = Value.Encode(Type.String(), 42); // throw
+```
+
+Back to [Home](../../readme.md)

docs/values/default.md

@@ -0,0 +1,20 @@
+[Overview](../overview.md) | [Installation](../installation.md) | [Usage](../usage.md) | [Types](../types/) | **Values** | [Syntax](../syntax/) | [TypeRegistry](../type-registry.md) | [TypeCheck](../type-check.md)
+
+# Default
+
+Use Default to generate missing properties on a value using default schema annotations if available. This function does not check the value and returns an unknown type. You should Check the result before use. Default is a mutable operation. To avoid mutation, Clone the value first.
+
+```typescript
+const T = Type.Object({
+  x: Type.Number({ default: 0 }),
+  y: Type.Number({ default: 0 }),
+});
+
+const X = Value.Default(T, null); // const 'X = null - non-enumerable
+
+const Y = Value.Default(T, {}); // const 'Y = { x: 0, y: 0 }
+
+const Z = Value.Default(T, { x: 1 }); // const 'Z = { x: 1, y: 0 }
+```
+
+Back to [Home](../../readme.md)

docs/values/diff-patch.md

@@ -0,0 +1,36 @@
+[Overview](../overview.md) | [Installation](../installation.md) | [Usage](../usage.md) | [Types](../types/) | **Values** | [Syntax](../syntax/) | [TypeRegistry](../type-registry.md) | [TypeCheck](../type-check.md)
+
+# Diff / Patch
+
+## Diff
+
+Use the Diff function to generate a sequence of edits that will transform one value into another.
+
+```typescript
+const E = Value.Diff(
+  // const E = [
+  { x: 1, y: 2, z: 3 }, //   { type: 'update', path: '/y', value: 4 },
+  { y: 4, z: 5, w: 6 } //   { type: 'update', path: '/z', value: 5 },
+); //   { type: 'insert', path: '/w', value: 6 },
+//   { type: 'delete', path: '/x' }
+// ]
+```
+
+## Patch
+
+Use the Patch function to apply a sequence of edits.
+
+```typescript
+const A = { x: 1, y: 2 };
+
+const B = { x: 3 };
+
+const E = Value.Diff(A, B); // const E = [
+//   { type: 'update', path: '/x', value: 3 },
+//   { type: 'delete', path: '/y' }
+// ]
+
+const C = Value.Patch<typeof B>(A, E); // const C = { x: 3 }
+```
+
+Back to [Home](../../readme.md)

docs/values/equal.md

@@ -0,0 +1,15 @@
+[Overview](../overview.md) | [Installation](../installation.md) | [Usage](../usage.md) | [Types](../types/) | **Values** | [Syntax](../syntax/) | [TypeRegistry](../type-registry.md) | [TypeCheck](../type-check.md)
+
+# Equal
+
+Use the Equal function to deeply check for value equality.
+
+```typescript
+const R = Value.Equal(
+  // const R = true
+  { x: 1, y: 2, z: 3 },
+  { x: 1, y: 2, z: 3 }
+);
+```
+
+Back to [Home](../../readme.md)

docs/values/errors.md

@@ -0,0 +1,23 @@
+[Overview](../overview.md) | [Installation](../installation.md) | [Usage](../usage.md) | [Types](../types/) | **Values** | [Syntax](../syntax/) | [TypeRegistry](../type-registry.md) | [TypeCheck](../type-check.md)
+
+# Errors
+
+Use the Errors function to enumerate validation errors.
+
+```typescript
+const T = Type.Object({ x: Type.Number(), y: Type.Number() });
+
+const R = [...Value.Errors(T, { x: "42" })]; // const R = [{
+//   schema: { type: 'number' },
+//   path: '/x',
+//   value: '42',
+//   message: 'Expected number'
+// }, {
+//   schema: { type: 'number' },
+//   path: '/y',
+//   value: undefined,
+//   message: 'Expected number'
+// }]
+```
+
+Back to [Home](../../readme.md)

docs/values/hash.md

@@ -0,0 +1,13 @@
+[Overview](../overview.md) | [Installation](../installation.md) | [Usage](../usage.md) | [Types](../types/) | **Values** | [Syntax](../syntax/) | [TypeRegistry](../type-registry.md) | [TypeCheck](../type-check.md)
+
+# Hash
+
+Use the Hash function to create a [FNV1A-64](https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function) non-cryptographic hash of a value.
+
+```typescript
+const A = Value.Hash({ x: 1, y: 2, z: 3 }); // const A = 2910466848807138541n
+
+const B = Value.Hash({ x: 1, y: 4, z: 3 }); // const B = 1418369778807423581n
+```
+
+Back to [Home](../../readme.md)

docs/values/mutate.md

@@ -0,0 +1,19 @@
+[Overview](../overview.md) | [Installation](../installation.md) | [Usage](../usage.md) | [Types](../types/) | **Values** | [Syntax](../syntax/) | [TypeRegistry](../type-registry.md) | [TypeCheck](../type-check.md)
+
+# Mutate
+
+Use the Mutate function to perform a deep mutable value assignment while retaining internal references.
+
+```typescript
+const Y = { z: 1 }; // const Y = { z: 1 }
+const X = { y: Y }; // const X = { y: { z: 1 } }
+const A = { x: X }; // const A = { x: { y: { z: 1 } } }
+
+Value.Mutate(A, { x: { y: { z: 2 } } }); // A' = { x: { y: { z: 2 } } }
+
+const R0 = A.x.y.z === 2; // const R0 = true
+const R1 = A.x.y === Y; // const R1 = true
+const R2 = A.x === X; // const R2 = true
+```
+
+Back to [Home](../../readme.md)

docs/values/parse.md

@@ -0,0 +1,29 @@
+[Overview](../overview.md) | [Installation](../installation.md) | [Usage](../usage.md) | [Types](../types/) | **Values** | [Syntax](../syntax/) | [TypeRegistry](../type-registry.md) | [TypeCheck](../type-check.md)
+
+# Parse
+
+Use the Parse function to parse a value. This function calls the `Clone` `Clean`, `Default`, `Convert`, `Assert` and `Decode` Value functions in this exact order to process a value.
+
+```typescript
+const R = Value.Parse(Type.String(), "hello"); // const R: string = "hello"
+
+const E = Value.Parse(Type.String(), undefined); // throws AssertError
+```
+
+You can override the order in which functions are run, or omit functions entirely using the following.
+
+```typescript
+// Runs no functions.
+
+const R = Value.Parse([], Type.String(), 12345);
+
+// Runs the Assert() function.
+
+const E = Value.Parse(["Assert"], Type.String(), 12345);
+
+// Runs the Convert() function followed by the Assert() function.
+
+const S = Value.Parse(["Convert", "Assert"], Type.String(), 12345);
+```
+
+Back to [Home](../../readme.md)

docs/values/pointer.md

@@ -0,0 +1,17 @@
+[Overview](../overview.md) | [Installation](../installation.md) | [Usage](../usage.md) | [Types](../types/) | **Values** | [Syntax](../syntax/) | [TypeRegistry](../type-registry.md) | [TypeCheck](../type-check.md)
+
+# Pointer
+
+Use ValuePointer to perform mutable updates on existing values using [RFC6901](https://www.rfc-editor.org/rfc/rfc6901) Json Pointers.
+
+```typescript
+import { ValuePointer } from "@alkdev/typebox/value";
+
+const A = { x: 0, y: 0, z: 0 };
+
+ValuePointer.Set(A, "/x", 1); // A' = { x: 1, y: 0, z: 0 }
+ValuePointer.Set(A, "/y", 1); // A' = { x: 1, y: 1, z: 0 }
+ValuePointer.Set(A, "/z", 1); // A' = { x: 1, y: 1, z: 1 }
+```
+
+Back to [Home](../../readme.md)