From bb62ad6352734876732a4139df77b611f8b98247 Mon Sep 17 00:00:00 2001 From: unional Date: Sat, 10 Oct 2026 18:26:21 -0700 Subject: [PATCH] docs(website): give JSON its own API page Split "Type Sets and JSON": the JSON types move to api/json.md and required/requiredDeep move to the Object page. type-sets.md is now "Type Sets". The llms.txt generator maps each file under src/ root to its own page. Co-Authored-By: Claude Opus 5.5 --- apps/website/public/llms.txt | 5 +- apps/website/src/content/docs/api/json.md | 58 +++++++++++++ apps/website/src/content/docs/api/object.md | 38 +++++++- .../website/src/content/docs/api/type-sets.md | 86 ++----------------- packages/type-plus/llms.txt | 5 +- packages/type-plus/readme.md | 2 + .../type-plus/scripts/generate-llms-txt.mjs | 19 ++-- 7 files changed, 124 insertions(+), 89 deletions(-) create mode 100644 apps/website/src/content/docs/api/json.md diff --git a/apps/website/public/llms.txt b/apps/website/public/llms.txt index a9525f3ca8..cedc3034b3 100644 --- a/apps/website/public/llms.txt +++ b/apps/website/public/llms.txt @@ -34,11 +34,12 @@ 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. @@ -46,7 +47,7 @@ The authoritative, per-symbol detail is the TSDoc in the shipped `.d.ts` files, - [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. diff --git a/apps/website/src/content/docs/api/json.md b/apps/website/src/content/docs/api/json.md new file mode 100644 index 0000000000..96160bf266 --- /dev/null +++ b/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 +``` + +🧰 *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`, `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). diff --git a/apps/website/src/content/docs/api/object.md b/apps/website/src/content/docs/api/object.md index 971a579794..00df9b7100 100644 --- a/apps/website/src/content/docs/api/object.md +++ b/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( + source1: Partial, + source2: Partial | undefined | null, + source3?: Partial | null, +): T & R & S +function requiredDeep( + source1: Partial, + source2: Partial | undefined | null, + source3?: Partial | 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(defaults, { b: { x: 2 } }) // { a: 1, b: { x: 2 } } +const r2 = requiredDeep(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()(source, override)` | Returns `{ ...source, ...override }` typed as `A`. `override` must supply exactly the properties `ANotB`: those `source` is missing or declares with an incompatible type. | 🗑ïļ **removed in 8.0.0**: `reduceKey` — use `reduceByKey` instead. diff --git a/apps/website/src/content/docs/api/type-sets.md b/apps/website/src/content/docs/api/type-sets.md index 7f6230c0f8..6d0f7acf36 100644 --- a/apps/website/src/content/docs/api/type-sets.md +++ b/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,70 +72,7 @@ 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 -``` - -🧰 *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( - source1: Partial, - source2: Partial | undefined | null, - source3?: Partial | null, -): T & R & S -function requiredDeep( - source1: Partial, - source2: Partial | undefined | null, - source3?: Partial | 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(defaults, { b: { x: 2 } }) // { a: 1, b: { x: 2 } } -const r2 = requiredDeep(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 | | --- | --- | @@ -142,15 +80,7 @@ the earlier value where a later source has `undefined`. Both skip `null` and `un | `ComposableTypes` | the types that can carry custom properties | | `NonComposableTypes` | the types that cannot | | `UnionKeys` | 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` | -| `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). diff --git a/packages/type-plus/llms.txt b/packages/type-plus/llms.txt index a9525f3ca8..cedc3034b3 100644 --- a/packages/type-plus/llms.txt +++ b/packages/type-plus/llms.txt @@ -34,11 +34,12 @@ 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. @@ -46,7 +47,7 @@ The authoritative, per-symbol detail is the TSDoc in the shipped `.d.ts` files, - [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. diff --git a/packages/type-plus/readme.md b/packages/type-plus/readme.md index 4bfa734ca0..7753876d59 100644 --- a/packages/type-plus/readme.md +++ b/packages/type-plus/readme.md @@ -894,6 +894,8 @@ The older helpers that overlapped it were removed in 8.0.0: ## JSON Support +Full reference: [JSON](https://cyberuni.github.io/type-plus/api/json/). + > `JsonPrimitive` ðŸ‘― *alias*: primitive types valid in JSON diff --git a/packages/type-plus/scripts/generate-llms-txt.mjs b/packages/type-plus/scripts/generate-llms-txt.mjs index 1e947bd216..6683c15338 100644 --- a/packages/type-plus/scripts/generate-llms-txt.mjs +++ b/packages/type-plus/scripts/generate-llms-txt.mjs @@ -48,9 +48,17 @@ function write(stream, message) { * than hidden. A family missing from this map is a hard error: a new directory * under `src/` has to be pointed at a page or explicitly declared undocumented, * so the map cannot silently fall behind the source. + * + * A file directly under `src/` is a family of its own, keyed by its file name, + * because those files do not share a topic. */ const FAMILY_DOCS = { $type: { title: 'Type branching', page: 'api/type-branching' }, + 'composable-types.ts': { title: 'Type Sets', page: 'api/type-sets' }, + 'json.ts': { title: 'JSON', page: 'api/json' }, + 'primitive.ts': { title: 'Type Sets', page: 'api/type-sets' }, + 'union-keys.ts': { title: 'Type Sets', page: 'api/type-sets' }, + 'unpartial.ts': { title: 'Object', page: 'api/object' }, any: { title: 'Primitives', page: 'api/primitives' }, array: { title: 'Array', page: 'api/array' }, assertion: { title: 'Type Guards and Assertions', page: 'api/type-guards-and-assertions' }, @@ -73,7 +81,6 @@ const FAMILY_DOCS = { object: { title: 'Object', page: 'api/object' }, predicates: { title: 'Type Guards and Assertions', page: 'api/type-guards-and-assertions' }, promise: { title: 'Promise', page: 'api/promise' }, - root: { title: 'Type Sets and JSON', page: 'api/type-sets' }, string: { title: 'String', page: 'api/string' }, symbol: { title: 'Primitives', page: 'api/primitives' }, testing: { title: 'Testing', page: 'api/testing' }, @@ -141,7 +148,7 @@ function readEntry(program, checker, file, specifier) { return { name: symbol.name, specifier, - family: inPackage ? (path.includes('/') ? path.slice(0, path.indexOf('/')) : 'root') : EXTERNAL, + family: inPackage ? (path.includes('/') ? path.slice(0, path.indexOf('/')) : path) : EXTERNAL, documented: isDocumented(target, checker), members: inPackage ? namespaceMembers(target, checker) : [], } @@ -154,7 +161,7 @@ function groupByFamily(exports) { if (item.family === EXTERNAL) continue if (!(item.family in FAMILY_DOCS)) { throw new Error( - `src/${item.family}/ is not in FAMILY_DOCS. Point it at a docs page, or set it to \`null\` to declare it undocumented.`, + `${familyPath(item.family)} is not in FAMILY_DOCS. Point it at a docs page, or set it to \`null\` to declare it undocumented.`, ) } const bucket = families.get(item.family) ?? [] @@ -215,9 +222,9 @@ function coverageNote(documented, total, missing) { return `${documented} of the ${total} exports carry TSDoc; the rest have a name and a signature only.` } -/** `root` is the pseudo-family for the files directly under `src/`. */ +/** A family is a directory under `src/`, or a file directly under it. */ function familyPath(family) { - return `\`src/${family === 'root' ? '' : `${family}/`}\`` + return `\`src/${family.endsWith('.ts') ? family : `${family}/`}\`` } /** A section exported from an entry other than the root names its import path. */ @@ -350,7 +357,7 @@ function unmentionedOnPages(exports) { if (!doc) continue if (!pages.has(doc.page)) { const file = ['.md', '.mdx'].map((ext) => join(docsRoot, `${doc.page}${ext}`)).find((f) => existsSync(f)) - if (!file) throw new Error(`FAMILY_DOCS points src/${item.family}/ at ${doc.page}, which has no page.`) + if (!file) throw new Error(`FAMILY_DOCS points ${familyPath(item.family)} at ${doc.page}, which has no page.`) pages.set(doc.page, { file, text: readFileSync(file, 'utf8') }) } const { file, text } = pages.get(doc.page)