docs(website): give JSON its own API page

apps/website/public/llms.txt

@@ -34,19 +34,20 @@ The authoritative, per-symbol detail is the TSDoc in the shipped `.d.ts` files,
 - [Boolean and Logical](https://cyberuni.github.io/type-plus/api/boolean/): 11 exports from `src/binary/`, `src/boolean/`, `src/logical/` -- And, Bit, IsBoolean, IsFalse, IsNotBoolean, IsNotFalse, IsNotTrue, IsTrue, Not, Or, Xor.
 - [Equality](https://cyberuni.github.io/type-plus/api/equality/): 2 exports from `src/equal/` -- IsEqual, IsNotEqual.
 - [Function and Functional](https://cyberuni.github.io/type-plus/api/function/): 13 exports from `src/class/`, `src/function/`, `src/functional/` -- AnyConstructor, AnyFunction, ChainFn, ContextBaseShape, ContextBuilder, ContextExtender, EndoFn, ExtractFunction, IsFunction, IsNotFunction, compose, context, extractFunction.
+- [JSON](https://cyberuni.github.io/type-plus/api/json/): 8 exports from `src/json.ts` -- JSONArray, JSONObject, JSONPrimitive, JSONTypes, JsonArray, JsonObject, JsonPrimitive, JsonTypes.
 - [Math](https://cyberuni.github.io/type-plus/api/math/): 16 exports from `src/math/` -- Abs, Add, Decrement, Divide, GreaterThan, GreaterThanOrEqual, Increment, LessThan, LessThanOrEqual, MathPlus, Max, Min, Multiply, Quotient, Remainder, Subtract.
 - [Node.js](https://cyberuni.github.io/type-plus/api/nodejs/): 3 exports from `src/nodejs/` -- SystemErrorCodes, SystemErrors, isSystemError.
 - [Nominal Types](https://cyberuni.github.io/type-plus/api/nominal/): 8 exports from `src/nominal/` -- Brand, Branded, Flavor, Flavored, FlavoredUnit, brand, flavor, nominalMatch.
 - [Number and Numeric](https://cyberuni.github.io/type-plus/api/number/): 24 exports from `src/number/`, `src/numeric/` -- IsInteger, IsIntegerLiteral, IsNegative, IsNegativeLiteral, IsNotInteger, IsNotIntegerLiteral, IsNotNegative, IsNotNegativeLiteral, IsNotNumber, IsNotNumberLiteral, IsNotNumeric, IsNotPositive, IsNotPositiveLiteral, IsNumber, IsNumberLiteral, IsNumeric, IsPositive, IsPositiveLiteral, Numeric, NumericPlus, NumericToString, StringToNumber, StringToNumeric, Zero.
-- [Object](https://cyberuni.github.io/type-plus/api/object/): 54 exports from `src/object/` -- ANotB, AdjustExactOptionalProps, AnyRecord, BNotA, ExcludePropType, HasKey, HasNoKey, IsDisjoint, IsNotObject, IsNotOptionalKey, IsNotRecord, IsObject, IsOptionalKey, IsRecord, KeyTypes, KeysWithDiffType, KnownKeys, LeftJoin, ObjectPlus, OptionalKeys, OptionalProps, PartialOmit, PartialPick, Properties, RecordValue, RecursiveIntersect, RecursivePartial, RecursiveRequired, ReplaceProperty, RequiredExcept, RequiredKeys, RequiredOmit, RequiredPick, Split, SpreadRecord, ValueOf, everyKey, facade, filterKey, findKey, forEachKey, getField, hasKey, hasProperty, mapKey, mapProperties, omit, pick, record, reduceByKey, replaceProperty, someKey, split, typeOverrideIncompatible.
+- [Object](https://cyberuni.github.io/type-plus/api/object/): 56 exports from `src/object/`, `src/unpartial.ts` -- ANotB, AdjustExactOptionalProps, AnyRecord, BNotA, ExcludePropType, HasKey, HasNoKey, IsDisjoint, IsNotObject, IsNotOptionalKey, IsNotRecord, IsObject, IsOptionalKey, IsRecord, KeyTypes, KeysWithDiffType, KnownKeys, LeftJoin, ObjectPlus, OptionalKeys, OptionalProps, PartialOmit, PartialPick, Properties, RecordValue, RecursiveIntersect, RecursivePartial, RecursiveRequired, ReplaceProperty, RequiredExcept, RequiredKeys, RequiredOmit, RequiredPick, Split, SpreadRecord, ValueOf, everyKey, facade, filterKey, findKey, forEachKey, getField, hasKey, hasProperty, mapKey, mapProperties, omit, pick, record, reduceByKey, replaceProperty, required, requiredDeep, someKey, split, typeOverrideIncompatible.
 - [Primitives](https://cyberuni.github.io/type-plus/api/primitives/): 21 exports from `src/any/`, `src/never/`, `src/null/`, `src/symbol/`, `src/undefined/`, `src/unknown/`, `src/void/` -- HasNoNull, HasNoUndefined, HasNoVoid, HasNull, HasUndefined, HasVoid, IsAny, IsNever, IsNotAny, IsNotNever, IsNotNull, IsNotSymbol, IsNotUndefined, IsNotUnknown, IsNotVoid, IsNull, IsSymbol, IsUndefined, IsUnknown, IsVoid, NotUnknownOr.
 - [Promise](https://cyberuni.github.io/type-plus/api/promise/): 6 exports from `src/promise/` -- AwaitedProp, MaybePromise, PromiseValueMerge, isPromise, mapSeries, transformMaybePromise.
 - [String](https://cyberuni.github.io/type-plus/api/string/): 10 exports from `src/string/` -- ExtractManipulatedString, IsNotString, IsNotStringLiteral, IsNotTemplateLiteral, IsString, IsStringLiteral, IsTemplateLiteral, StringIncludes, StringPlus, StringSplit.
 - [Testing](https://cyberuni.github.io/type-plus/api/testing/): 2 exports from `src/testing/`, imported from `type-plus/testing` -- stub, testType.
 - [Tuple](https://cyberuni.github.io/type-plus/api/tuple/): 13 exports from `src/tuple/` -- CommonPropKeys, CreateTuple, DropFirst, DropLast, DropMatch, DropNull, DropNullable, DropUndefined, IsNotTuple, IsTuple, Tail, ToTuple, TuplePlus.
 - [Type branching](https://cyberuni.github.io/type-plus/api/type-branching/): 25 exports from `src/$type/` -- $Any, $Branch, $BranchOptions, $Distributive, $Else, $Error, $ErrorMessage, $Exact, $Fail, $Fn, $ForwardOptions, $InferError, $InputOptions, $MergeOptions, $Never, $NotNever, $ResolveBranch, $ResolveOptions, $Selection, $Special, $StrictOptions, $Then, $Type, $Unknown, $Void.
 - [Type Guards and Assertions](https://cyberuni.github.io/type-plus/api/type-guards-and-assertions/): 9 exports from `src/predicates/`, `src/type-guard/` -- Assignable, If, IsEmptyObject, IsLiteral, IsNotEmptyObject, IsNotLiteral, NotAssignable, assertType, isType.
-- [Type Sets and JSON](https://cyberuni.github.io/type-plus/api/type-sets/): 14 exports from `src/` -- ComposableTypes, JSONArray, JSONObject, JSONPrimitive, JSONTypes, JsonArray, JsonObject, JsonPrimitive, JsonTypes, NonComposableTypes, PrimitiveTypes, UnionKeys, required, requiredDeep.
+- [Type Sets](https://cyberuni.github.io/type-plus/api/type-sets/): 4 exports from `src/composable-types.ts`, `src/primitive.ts`, `src/union-keys.ts` -- ComposableTypes, NonComposableTypes, PrimitiveTypes, UnionKeys.
 - [Union and Mixed Types](https://cyberuni.github.io/type-plus/api/union/): 9 exports from `src/mix-types/`, `src/union/` -- Box, Exclude, IsAnyOrNever, IsNotAnyOrNever, IsNotUnion, IsUnion, Merge, SubUnion, merge.
 - [Utilities](https://cyberuni.github.io/type-plus/api/utilities/): 7 exports from `src/utils/` -- EitherOrBoth, TypePlusOptions, Widen, amend, as, asAny, inspect.
 

apps/website/src/content/docs/api/json.md

@@ -0,0 +1,58 @@
+---
+title: JSON
+description: The types of the values that survive a JSON round trip - JsonTypes and its primitive, object and array parts.
+sidebar:
+  order: 19
+---
+
+The JSON types name what `JSON.parse` can give back and what `JSON.stringify` keeps. Use them as the
+constraint on data that crosses a JSON boundary: a request or response body, a config file, a message
+on a queue.
+
+For the other named sets of types, such as `PrimitiveTypes`, see [Type Sets](/type-plus/api/type-sets/).
+
+## `JsonTypes`, `JsonPrimitive`, `JsonObject` and `JsonArray`
+
+```ts
+type JsonTypes = JsonPrimitive | JsonObject | JsonArray
+type JsonPrimitive = boolean | number | string | null
+type JsonObject = { [key in string]?: JsonTypes }
+type JsonArray = Array<JsonTypes>
+```
+
+🧰 *type util* — the values that survive a JSON round trip.
+
+```ts
+import type { JsonTypes } from 'type-plus'
+
+type R = { a: 1 } extends JsonTypes ? true : false // true
+type R = Date extends JsonTypes ? true : false // false
+type R = undefined extends JsonPrimitive ? true : false // false
+```
+
+Use `JsonTypes` as the constraint on data that has crossed a JSON boundary. It admits exactly what comes
+back, so a `Date`, a `Map`, a function or `undefined` is rejected where it is put in rather than silently
+lost on the way out.
+
+Two details follow from that. `undefined` is absent from `JsonPrimitive`, because JSON has no such value
+and `JSON.stringify` drops the properties holding it. And every property of `JsonObject` is optional, so
+reading one yields `JsonTypes | undefined` — the honest type for parsed data, where no key is guaranteed
+to be there.
+
+## Deprecated `JSON*` names
+
+💀 **deprecated since 8.0.0**: the names before 8.0, kept as aliases until 9.0 — use `JsonTypes`,
+`JsonPrimitive`, `JsonObject` and `JsonArray`. The new names title-case the acronym, as every type-plus
+name does. See [Migrating to v8](/type-plus/guides/migrating-to-v8/#deprecated-in-80).
+
+## Reference
+
+| Type | Description |
+| --- | --- |
+| `JsonTypes` | any value JSON can hold |
+| `JsonPrimitive` | `boolean \| number \| string \| null` |
+| `JsonObject` | string keys holding `JsonTypes`, all optional |
+| `JsonArray` | `Array<JsonTypes>` |
+| `JSONTypes`, `JSONPrimitive`, `JSONObject`, `JSONArray` | 💀 deprecated since 8.0.0, use the `Json*` names |
+
+Source: [`src/json.ts`](https://github.com/cyberuni/type-plus/blob/main/packages/type-plus/src/json.ts).

apps/website/src/content/docs/api/object.md

@@ -8,7 +8,8 @@ sidebar:
 The `object` category covers types for inspecting keys, adjusting optionality, and combining records,
 plus a set of runtime helpers that carry the matching type transformation.
 
-Sources: [`packages/type-plus/src/object`](https://github.com/cyberuni/type-plus/tree/main/packages/type-plus/src/object).
+Sources: [`packages/type-plus/src/object`](https://github.com/cyberuni/type-plus/tree/main/packages/type-plus/src/object) and
+[`packages/type-plus/src/unpartial.ts`](https://github.com/cyberuni/type-plus/blob/main/packages/type-plus/src/unpartial.ts).
 
 ## `IsObject` / `IsNotObject`
 
@@ -240,6 +241,39 @@ type M = ObjectPlus.Merge<{ a: 1 }, { b: 2 }> // { a: 1 } & { b: 2 }
 type G = ObjectPlus.Merge<{ get a(): 1 }, { b: 2 }> // { a: 1; b: 2 }
 ```
 
+## `required` and `requiredDeep`
+
+```ts
+function required<T, R = T, S = T & R>(
+  source1: Partial<T>,
+  source2: Partial<R> | undefined | null,
+  source3?: Partial<S> | null,
+): T & R & S
+function requiredDeep<T, R = T, S = T & R>(
+  source1: Partial<T>,
+  source2: Partial<R> | undefined | null,
+  source3?: Partial<S> | null,
+): T & R & S
+```
+
+🦴 *utilities* — merge up to three partial objects, left to right, into one value typed as the
+intersection of their full types. Both are re-exported from the
+[`unpartial`](https://github.com/unional/unpartial) package.
+
+```ts
+import { required, requiredDeep } from 'type-plus'
+
+type Options = { a: number; b: { x: number; y?: number } }
+const defaults: Options = { a: 1, b: { x: 1, y: 1 } }
+
+const r1 = required<Options>(defaults, { b: { x: 2 } }) // { a: 1, b: { x: 2 } }
+const r2 = requiredDeep<Options>(defaults, { b: { x: 2 } }) // { a: 1, b: { x: 2, y: 1 } }
+```
+
+`required` is shallow: a later source replaces a nested object, and a key it sets to `undefined`
+overwrites the earlier value. `requiredDeep` merges nested objects key by key, replaces arrays, and keeps
+the earlier value where a later source has `undefined`. Both skip `null` and `undefined` sources.
+
 ## `Split`
 
 ```ts
@@ -307,6 +341,8 @@ type R = AdjustExactOptionalProps<{ a: 1; b?: 2 }> // { b?: 2 | undefined } & {
 | `mapKey`, `filterKey`, `findKey`, `forEachKey`, `everyKey`, `someKey`, `reduceByKey` | Array-style iteration over the keys of a record. |
 | `mapProperties(subject, mapper)` | Maps every property value of a record. |
 | `replaceProperty(subject, key, value)` | Returns a copy with key `K` replaced, typed as `ReplaceProperty`. |
+| `required(source1, source2, source3?)` | Merges up to three partial objects shallowly into a full one. |
+| `requiredDeep(source1, source2, source3?)` | Merges up to three partial objects recursively into a full one. |
 | `typeOverrideIncompatible<A>()(source, override)` | Returns `{ ...source, ...override }` typed as `A`. `override` must supply exactly the properties `ANotB<A, typeof source>`: those `source` is missing or declares with an incompatible type. |
 
 🗑️ **removed in 8.0.0**: `reduceKey` — use `reduceByKey` instead.

apps/website/src/content/docs/api/type-sets.md

@@ -1,14 +1,15 @@
 ---
-title: Type Sets and JSON
-description: The named unions type-plus ships - TypeScript's primitive and composable type sets, the JSON value types, and UnionKeys.
+title: Type Sets
+description: The named unions type-plus ships - TypeScript's primitive and composable type sets, and UnionKeys.
 sidebar:
   order: 18
 ---
 
 A handful of exports sit at the root of `src/` rather than in a category. They have one thing in common:
 each names a set of types that TypeScript itself leaves unnamed, so a constraint can say "a primitive" or
-"anything JSON can hold" instead of spelling the union out again.
-Two runtime functions, `required` and `requiredDeep`, also sit at the root and are covered at the end.
+"anything that can carry a property" instead of spelling the union out again.
+
+For the set of values JSON can hold, see [JSON](/type-plus/api/json/).
 
 ## `PrimitiveTypes`
 
@@ -71,86 +72,15 @@ type R = keyof ({ a: 1 } | { b: 2 }) // never
 `UnionKeys` distributes first, so it gives the keys any member has. That is the constraint `ObjectPlus.Omit` and
 `omit` use, which is why they work on a union where the built-in `Omit` does not.
 
-## The JSON types
-
-```ts
-type JsonTypes = JsonPrimitive | JsonObject | JsonArray
-type JsonPrimitive = boolean | number | string | null
-type JsonObject = { [key in string]?: JsonTypes }
-type JsonArray = Array<JsonTypes>
-```
-
-🧰 *type util* — the values that survive a JSON round trip.
-
-```ts
-import type { JsonTypes } from 'type-plus'
-
-type R = { a: 1 } extends JsonTypes ? true : false // true
-type R = Date extends JsonTypes ? true : false // false
-type R = undefined extends JsonPrimitive ? true : false // false
-```
-
-Use `JsonTypes` as the constraint on data that has crossed a JSON boundary. It admits exactly what comes
-back, so a `Date`, a `Map`, a function or `undefined` is rejected where it is put in rather than silently
-lost on the way out.
-
-Two details follow from that. `undefined` is absent from `JsonPrimitive`, because JSON has no such value
-and `JSON.stringify` drops the properties holding it. And every property of `JsonObject` is optional, so
-reading one yields `JsonTypes | undefined` — the honest type for parsed data, where no key is guaranteed
-to be there.
-
-Before 8.0 these were `JSONTypes`, `JSONPrimitive`, `JSONObject` and `JSONArray`. The old names remain
-as deprecated aliases and go in 9.0.
-
-## `required` and `requiredDeep`
-
-```ts
-function required<T, R = T, S = T & R>(
-  source1: Partial<T>,
-  source2: Partial<R> | undefined | null,
-  source3?: Partial<S> | null,
-): T & R & S
-function requiredDeep<T, R = T, S = T & R>(
-  source1: Partial<T>,
-  source2: Partial<R> | undefined | null,
-  source3?: Partial<S> | null,
-): T & R & S
-```
-
-🦴 *utilities* — merge up to three partial objects, left to right, into one value typed as the
-intersection of their full types. Both are re-exported from the
-[`unpartial`](https://github.com/unional/unpartial) package.
-
-```ts
-import { required, requiredDeep } from 'type-plus'
-
-type Options = { a: number; b: { x: number; y?: number } }
-const defaults: Options = { a: 1, b: { x: 1, y: 1 } }
-
-const r1 = required<Options>(defaults, { b: { x: 2 } }) // { a: 1, b: { x: 2 } }
-const r2 = requiredDeep<Options>(defaults, { b: { x: 2 } }) // { a: 1, b: { x: 2, y: 1 } }
-```
-
-`required` is shallow: a later source replaces a nested object, and a key it sets to `undefined`
-overwrites the earlier value. `requiredDeep` merges nested objects key by key, replaces arrays, and keeps
-the earlier value where a later source has `undefined`. Both skip `null` and `undefined` sources.
-
+## Reference
 
 | Type | Description |
 | --- | --- |
 | `PrimitiveTypes` | every built-in type |
 | `ComposableTypes` | the types that can carry custom properties |
 | `NonComposableTypes` | the types that cannot |
 | `UnionKeys<T>` | keys of `T`, collected across a union |
-| `JsonTypes` | any value JSON can hold |
-| `JsonPrimitive` | `boolean \| number \| string \| null` |
-| `JsonObject` | string keys holding `JsonTypes`, all optional |
-| `JsonArray` | `Array<JsonTypes>` |
-| `required` | shallow merge of partial objects into a full one |
-| `requiredDeep` | deep merge of partial objects into a full one |
 
 Source: [`src/composable-types.ts`](https://github.com/cyberuni/type-plus/blob/main/packages/type-plus/src/composable-types.ts),
-[`src/primitive.ts`](https://github.com/cyberuni/type-plus/blob/main/packages/type-plus/src/primitive.ts),
-[`src/union-keys.ts`](https://github.com/cyberuni/type-plus/blob/main/packages/type-plus/src/union-keys.ts),
-[`src/json.ts`](https://github.com/cyberuni/type-plus/blob/main/packages/type-plus/src/json.ts) and
-[`src/unpartial.ts`](https://github.com/cyberuni/type-plus/blob/main/packages/type-plus/src/unpartial.ts).
+[`src/primitive.ts`](https://github.com/cyberuni/type-plus/blob/main/packages/type-plus/src/primitive.ts) and
+[`src/union-keys.ts`](https://github.com/cyberuni/type-plus/blob/main/packages/type-plus/src/union-keys.ts).