chore: update docs

skunkteam · Oct 23, 2024 · b39ed0f · b39ed0f
1 parent eede34b
commit b39ed0f
Show file tree

Hide file tree

Showing 14 changed files with 152 additions and 128 deletions.
diff --git a/README.md b/README.md
diff --git a/etc/types.api.md b/etc/types.api.md
@@ -32,6 +32,12 @@ export interface ArrayTypeConfig extends LengthChecksConfig {
 // @public
 export type ArrayViolation = LengthViolation;
 
+// @public
+export function autoCast<T extends BaseTypeImpl<unknown>>(type: T): T;
+
+// @public
+export function autoCastAll<T extends BaseTypeImpl<unknown>>(type: T): T;
+
 // @public
 export const autoCastFailure: unique symbol;
 
@@ -56,15 +62,13 @@ export abstract class BaseTypeImpl<ResultType, TypeConfig = unknown> implements
     abstract accept<R>(visitor: Visitor<R>): R;
     andThen<Return, RestArgs extends unknown[]>(fn: (value: ResultType, ...restArgs: RestArgs) => Return): (input: unknown, ...restArgs: RestArgs) => Return;
     assert(input: unknown): asserts input is ResultType;
-    get autoCast(): this;
-    get autoCastAll(): this;
     protected autoCaster?(this: BaseTypeImpl<ResultType, TypeConfig>, value: unknown): unknown;
     abstract readonly basicType: BasicType | 'mixed';
     get check(): (this: void, input: unknown) => ResultType;
     protected combineConfig(oldConfig: TypeConfig, newConfig: TypeConfig): TypeConfig;
     construct(input: unknown): ResultType;
     // (undocumented)
-    protected createAutoCastAllType(): this;
+    protected createAutoCastAllType(): Type<ResultType>;
     protected createResult(input: unknown, result: unknown, validatorResult: ValidationResult): Result<ResultType>;
     protected readonly customValidators: ReadonlyArray<Validator<unknown>>;
     readonly enumerableLiteralDomain?: Iterable<LiteralValue>;
@@ -617,17 +621,17 @@ export type ValidationDetails = {
 // @public
 export class ValidationError extends Error implements Failure {
     // (undocumented)
-    details: OneOrMore<FailureDetails>;
+    readonly details: OneOrMore<FailureDetails>;
     static fromFailure(failure: Failure): ValidationError;
     // (undocumented)
-    input: unknown;
+    readonly input: unknown;
     // (undocumented)
     readonly name = "ValidationError";
     // (undocumented)
     readonly ok = false;
     static try<Return>({ type, input }: Pick<Failure, 'type' | 'input'>, fn: () => Return): Result<Return>;
     // (undocumented)
-    type: BaseTypeImpl<unknown>;
+    readonly type: BaseTypeImpl<unknown>;
 }
 
 // @public

diff --git a/markdown/types.autocast.md b/markdown/types.autocast.md
@@ -0,0 +1,27 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@skunkteam/types](./types.md) &gt; [autoCast](./types.autocast.md)
+
+## autoCast() function
+
+Returns the same type, but with an auto-casting default parser installed.
+
+**Signature:**
+
+```typescript
+declare function autoCast<T extends BaseTypeImpl<unknown>>(type: T): T;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| type      | T    |             |
+
+**Returns:**
+
+T
+
+## Remarks
+
+Each type implementation provides its own auto-cast rules. See builtin types for examples of auto-cast rules.
diff --git a/markdown/types.autocastall.md b/markdown/types.autocastall.md
@@ -0,0 +1,27 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@skunkteam/types](./types.md) &gt; [autoCastAll](./types.autocastall.md)
+
+## autoCastAll() function
+
+Create a recursive autocasting version of the given type.
+
+**Signature:**
+
+```typescript
+declare function autoCastAll<T extends BaseTypeImpl<unknown>>(type: T): T;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| type      | T    |             |
+
+**Returns:**
+
+T
+
+## Remarks
+
+This will replace any parser in the nested structure with the appropriate autocaster when applicable.
diff --git a/markdown/types.basetypeimpl.autocast.md b/markdown/types.basetypeimpl.autocast.md
diff --git a/markdown/types.basetypeimpl.autocastall.md b/markdown/types.basetypeimpl.autocastall.md
diff --git a/markdown/types.basetypeimpl.createautocastalltype.md b/markdown/types.basetypeimpl.createautocastalltype.md
@@ -7,9 +7,9 @@
 **Signature:**
 
 ```typescript
-protected createAutoCastAllType(): this;
+protected createAutoCastAllType(): Type<ResultType>;
 ```
 
 **Returns:**
 
-this
+[Type](./types.type.md)<!-- -->&lt;ResultType&gt;
diff --git a/markdown/types.basetypeimpl.md b/markdown/types.basetypeimpl.md
@@ -22,8 +22,6 @@ All type-implementations must extend this base class. Use [createType()](./types
 
 | Property                                                                    | Modifiers                                                 | Type                                                                          | Description                                                                                                                                                            |
 | --------------------------------------------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [autoCast](./types.basetypeimpl.autocast.md)                                | <code>readonly</code>                                     | this                                                                          | The same type, but with an auto-casting default parser installed.                                                                                                      |
-| [autoCastAll](./types.basetypeimpl.autocastall.md)                          | <code>readonly</code>                                     | this                                                                          | Create a recursive autocasting version of the current type.                                                                                                            |
 | [basicType](./types.basetypeimpl.basictype.md)                              | <p><code>abstract</code></p><p><code>readonly</code></p>  | [BasicType](./types.basictype.md) \| 'mixed'                                  | The kind of values this type validates.                                                                                                                                |
 | [check](./types.basetypeimpl.check.md)                                      | <code>readonly</code>                                     | (this: void, input: unknown) =&gt; ResultType                                 | Asserts that a value conforms to this Type and returns the input as is, if it does.                                                                                    |
 | [customValidators](./types.basetypeimpl.customvalidators.md)                | <p><code>protected</code></p><p><code>readonly</code></p> | ReadonlyArray&lt;[Validator](./types.validator.md)<!-- -->&lt;unknown&gt;&gt; | Additional custom validation added using [withValidation](./types.basetypeimpl.withvalidation.md) or [withConstraint](./types.basetypeimpl.withconstraint.md)<!-- -->. |

diff --git a/markdown/types.interfacepickoptions.applyparser.md b/markdown/types.interfacepickoptions.applyparser.md
@@ -14,7 +14,7 @@ applyParser?: boolean;
 
 ## Remarks
 
-By default, custom parsers (i.e. parsers that are added to a type using [BaseTypeImpl.withParser()](./types.basetypeimpl.withparser.md) or [BaseTypeImpl.autoCast](./types.basetypeimpl.autocast.md)<!-- -->) are not reused when a new type is created using [InterfaceType.pick()](./types.interfacetype.pick.md) and [InterfaceType.omit()](./types.interfacetype.omit.md)<!-- -->.
+By default, custom parsers (i.e. parsers that are added to a type using [BaseTypeImpl.withParser()](./types.basetypeimpl.withparser.md) or [autoCast()](./types.autocast.md)<!-- -->) are not reused when a new type is created using [InterfaceType.pick()](./types.interfacetype.pick.md) and [InterfaceType.omit()](./types.interfacetype.omit.md)<!-- -->.
 
 However, it is possible to reuse a parser that is set on the base type. Parsers have a single input of type `unknown` and may produce anything (also with type `unknown`<!-- -->). The result of a parser will always be validated afterwards by the type it is applied to. Technically, any parser is applicable to any type, but it might not make sense to do so. Therefore, you can choose to apply it or not with this option.
 

diff --git a/markdown/types.md b/markdown/types.md
@@ -32,6 +32,8 @@ Runtime type-validation with derived TypeScript types.
 | Function                                                          | Description                                                                                                                                       |
 | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
 | [array(args)](./types.array.md)                                   | Create a type that checks whether the input is an array and all elements conform to the given <code>elementType</code>.                           |
+| [autoCast(type)](./types.autocast.md)                             | Returns the same type, but with an auto-casting default parser installed.                                                                         |
+| [autoCastAll(type)](./types.autocastall.md)                       | Create a recursive autocasting version of the given type.                                                                                         |
 | [booleanAutoCaster(input)](./types.booleanautocaster.md)          |                                                                                                                                                   |
 | [createType(impl, override)](./types.createtype.md)               | Create a Type from the given type-implementation.                                                                                                 |
 | [intersection(args)](./types.intersection.md)                     | Intersect the given types.                                                                                                                        |

diff --git a/markdown/types.validationerror.details.md b/markdown/types.validationerror.details.md
@@ -7,5 +7,5 @@
 **Signature:**
 
 ```typescript
-details: OneOrMore<FailureDetails>;
+readonly details: OneOrMore<FailureDetails>;
 ```
diff --git a/markdown/types.validationerror.input.md b/markdown/types.validationerror.input.md
@@ -7,5 +7,5 @@
 **Signature:**
 
 ```typescript
-input: unknown;
+readonly input: unknown;
 ```
diff --git a/markdown/types.validationerror.md b/markdown/types.validationerror.md
@@ -24,11 +24,11 @@ Is itself also a [Failure](./types.failure.md) and can be used as such in APIs.
 
 | Property                                      | Modifiers             | Type                                                                                                 | Description |
 | --------------------------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------- | ----------- |
-| [details](./types.validationerror.details.md) |                       | [OneOrMore](./types.oneormore.md)<!-- -->&lt;[FailureDetails](./types.failuredetails.md)<!-- -->&gt; |             |
-| [input](./types.validationerror.input.md)     |                       | unknown                                                                                              |             |
+| [details](./types.validationerror.details.md) | <code>readonly</code> | [OneOrMore](./types.oneormore.md)<!-- -->&lt;[FailureDetails](./types.failuredetails.md)<!-- -->&gt; |             |
+| [input](./types.validationerror.input.md)     | <code>readonly</code> | unknown                                                                                              |             |
 | [name](./types.validationerror.name.md)       | <code>readonly</code> | (not declared)                                                                                       |             |
 | [ok](./types.validationerror.ok.md)           | <code>readonly</code> | (not declared)                                                                                       |             |
-| [type](./types.validationerror.type.md)       |                       | [BaseTypeImpl](./types.basetypeimpl.md)<!-- -->&lt;unknown&gt;                                       |             |
+| [type](./types.validationerror.type.md)       | <code>readonly</code> | [BaseTypeImpl](./types.basetypeimpl.md)<!-- -->&lt;unknown&gt;                                       |             |
 
 ## Methods
 

diff --git a/markdown/types.validationerror.type.md b/markdown/types.validationerror.type.md
@@ -7,5 +7,5 @@
 **Signature:**
 
 ```typescript
-type: BaseTypeImpl<unknown>;
+readonly type: BaseTypeImpl<unknown>;
 ```