-
-
Notifications
You must be signed in to change notification settings - Fork 217
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #969 from EltonLobo07/doc/add-undefinedableAsync
add `undefinedableAsync` API reference
- Loading branch information
Showing
2 changed files
with
319 additions
and
1 deletion.
There are no files selected for viewing
234 changes: 233 additions & 1 deletion
234
website/src/routes/api/(async)/undefinedableAsync/index.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,10 +1,242 @@ | ||
| --- | ||
| title: undefinedableAsync | ||
| description: Creates an undefinedable schema. | ||
| source: /schemas/undefinedable/undefinedableAsync.ts | ||
| contributors: | ||
| - fabian-hiller | ||
| - santoshyadavdev | ||
| - EltonLobo07 | ||
| --- | ||
|
|
||
| import { Link } from '@builder.io/qwik-city'; | ||
| import { ApiList, Property } from '~/components'; | ||
| import { properties } from './properties'; | ||
|
|
||
| # undefinedableAsync | ||
|
|
||
| > The content of this page is not yet ready. Until then, please use the [source code](https://github.com/fabian-hiller/valibot/blob/main/library/src/schemas/undefinedable/undefinedableAsync.ts) or take a look at [issue #287](https://github.com/fabian-hiller/valibot/issues/287) to help us extend the API reference. | ||
| Creates an undefinedable schema. | ||
|
|
||
| ```ts | ||
| const Schema = v.undefinedableAsync<TWrapped, TDefault>(wrapped, default_); | ||
| ``` | ||
|
|
||
| ## Generics | ||
|
|
||
| - `TWrapped` <Property {...properties.TWrapped} /> | ||
| - `TDefault` <Property {...properties.TDefault} /> | ||
|
|
||
| ## Parameters | ||
|
|
||
| - `wrapped` <Property {...properties.wrapped} /> | ||
| - `default_` {/* prettier-ignore */}<Property {...properties.default_} /> | ||
|
|
||
| ### Explanation | ||
|
|
||
| With `undefinedableAsync` the validation of your schema will pass `undefined` inputs, and if you specify a `default_` input value, the schema will use it if the input is `undefined`. For this reason, the output type may differ from the input type of the schema. | ||
|
|
||
| > `undefinedableAsync` behaves exactly the same as <Link href="../optionalAsync/">`optionalAsync`</Link> at runtime. The only difference is the input and output type when used for object entries. While <Link href="../optionalAsync/">`optionalAsync`</Link> adds a question mark to the key, `undefinedableAsync` does not. | ||
| > Note that `undefinedableAsync` does not accept `null` as an input. If you want to accept `null` inputs, use <Link href="../nullableAsync/">`nullableAsync`</Link>, and if you want to accept `null` and `undefined` inputs, use <Link href="../nullishAsync/">`nullishAsync`</Link> instead. Also, if you want to set a default output value for any invalid input, you should use <Link href="../fallbackAsync/">`fallbackAsync`</Link> instead. | ||
| ## Returns | ||
|
|
||
| - `Schema` <Property {...properties.Schema} /> | ||
|
|
||
| ## Examples | ||
|
|
||
| The following examples show how `undefinedableAsync` can be used. | ||
|
|
||
| ### Undefinedable username schema | ||
|
|
||
| Schema that accepts a unique username or `undefined`. | ||
|
|
||
| > By using a function as the `default_` parameter, the schema will return a unique username from the function call each time the input is `undefined`. | ||
| ```ts | ||
| import { getUniqueUsername, isUsernameUnique } from '~/api'; | ||
|
|
||
| const UndefinedableUsernameSchema = v.undefinedableAsync( | ||
| v.pipeAsync( | ||
| v.string(), | ||
| v.nonEmpty(), | ||
| v.checkAsync(isUsernameUnique, 'The username is not unique.') | ||
| ), | ||
| getUniqueUsername | ||
| ); | ||
| ``` | ||
|
|
||
| ### New user schema | ||
|
|
||
| Schema to validate new user details. | ||
|
|
||
| ```ts | ||
| import { isEmailUnique, isUsernameUnique } from '~/api'; | ||
|
|
||
| const NewUserSchema = v.objectAsync({ | ||
| email: v.pipeAsync( | ||
| v.string(), | ||
| v.email(), | ||
| v.checkAsync(isEmailUnique, 'The email is not unique.') | ||
| ), | ||
| username: v.undefinedableAsync( | ||
| v.pipeAsync( | ||
| v.string(), | ||
| v.nonEmpty(), | ||
| v.checkAsync(isUsernameUnique, 'The username is not unique.') | ||
| ) | ||
| ), | ||
| password: v.pipe(v.string(), v.minLength(8)), | ||
| }); | ||
|
|
||
| /* | ||
| The input and output types of the schema: | ||
| { | ||
| email: string; | ||
| password: string; | ||
| username: string | undefined; | ||
| } | ||
| */ | ||
| ``` | ||
|
|
||
| ### Username schema | ||
|
|
||
| Schema that accepts a unique username. | ||
|
|
||
| ```ts | ||
| import { isUsernameUnique } from '~/api'; | ||
|
|
||
| const UsernameSchema = v.unwrap( | ||
| // Assume this schema is from a different file and is reused here | ||
| v.undefinedableAsync( | ||
| v.pipeAsync( | ||
| v.string(), | ||
| v.nonEmpty(), | ||
| v.checkAsync(isUsernameUnique, 'The username is not unique.') | ||
| ) | ||
| ) | ||
| ); | ||
| ``` | ||
|
|
||
| ## Related | ||
|
|
||
| The following APIs can be combined with `undefinedableAsync`. | ||
|
|
||
| ### Schemas | ||
|
|
||
| <ApiList | ||
| items={[ | ||
| 'any', | ||
| 'array', | ||
| 'bigint', | ||
| 'blob', | ||
| 'boolean', | ||
| 'custom', | ||
| 'date', | ||
| 'enum', | ||
| 'file', | ||
| 'function', | ||
| 'instance', | ||
| 'intersect', | ||
| 'lazy', | ||
| 'literal', | ||
| 'looseObject', | ||
| 'looseTuple', | ||
| 'map', | ||
| 'nan', | ||
| 'never', | ||
| 'nonNullable', | ||
| 'nonNullish', | ||
| 'nonUndefinedable', | ||
| 'null', | ||
| 'nullable', | ||
| 'nullish', | ||
| 'number', | ||
| 'object', | ||
| 'objectWithRest', | ||
| 'optional', | ||
| 'picklist', | ||
| 'promise', | ||
| 'record', | ||
| 'set', | ||
| 'strictObject', | ||
| 'strictTuple', | ||
| 'string', | ||
| 'symbol', | ||
| 'tuple', | ||
| 'tupleWithRest', | ||
| 'undefined', | ||
| 'undefinedable', | ||
| 'union', | ||
| 'unknown', | ||
| 'variant', | ||
| 'void', | ||
| ]} | ||
| /> | ||
|
|
||
| ### Methods | ||
|
|
||
| <ApiList items={['config', 'getDefault', 'getFallback', 'unwrap']} /> | ||
|
|
||
| ### Actions | ||
|
|
||
| <ApiList | ||
| items={[ | ||
| 'brand', | ||
| 'check', | ||
| 'description', | ||
| 'metadata', | ||
| 'partialCheck', | ||
| 'rawCheck', | ||
| 'rawTransform', | ||
| 'readonly', | ||
| 'title', | ||
| 'transform', | ||
| ]} | ||
| /> | ||
|
|
||
| ### Utils | ||
|
|
||
| <ApiList items={['entriesFromList', 'isOfKind', 'isOfType']} /> | ||
|
|
||
| ### Async | ||
|
|
||
| <ApiList | ||
| items={[ | ||
| 'arrayAsync', | ||
| 'checkAsync', | ||
| 'customAsync', | ||
| 'fallbackAsync', | ||
| 'getDefaultsAsync', | ||
| 'getFallbacksAsync', | ||
| 'intersectAsync', | ||
| 'lazyAsync', | ||
| 'looseObjectAsync', | ||
| 'looseTupleAsync', | ||
| 'mapAsync', | ||
| 'nonNullableAsync', | ||
| 'nonNullishAsync', | ||
| 'nonOptionalAsync', | ||
| 'nullableAsync', | ||
| 'nullishAsync', | ||
| 'objectAsync', | ||
| 'objectWithRestAsync', | ||
| 'optionalAsync', | ||
| 'parseAsync', | ||
| 'parserAsync', | ||
| 'partialCheckAsync', | ||
| 'pipeAsync', | ||
| 'rawCheckAsync', | ||
| 'rawTransformAsync', | ||
| 'recordAsync', | ||
| 'safeParseAsync', | ||
| 'safeParserAsync', | ||
| 'setAsync', | ||
| 'strictObjectAsync', | ||
| 'strictTupleAsync', | ||
| 'transformAsync', | ||
| 'tupleAsync', | ||
| 'tupleWithRestAsync', | ||
| 'unionAsync', | ||
| 'variantAsync', | ||
| ]} | ||
| /> |
86 changes: 86 additions & 0 deletions
86
website/src/routes/api/(async)/undefinedableAsync/properties.ts
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,86 @@ | ||
| import type { PropertyProps } from '~/components'; | ||
|
|
||
| export const properties: Record<string, PropertyProps> = { | ||
| TWrapped: { | ||
| modifier: 'extends', | ||
| type: { | ||
| type: 'union', | ||
| options: [ | ||
| { | ||
| type: 'custom', | ||
| name: 'BaseSchema', | ||
| href: '../BaseSchema/', | ||
| generics: [ | ||
| 'unknown', | ||
| 'unknown', | ||
| { | ||
| type: 'custom', | ||
| name: 'BaseIssue', | ||
| href: '../BaseIssue/', | ||
| generics: ['unknown'], | ||
| }, | ||
| ], | ||
| }, | ||
| { | ||
| type: 'custom', | ||
| name: 'BaseSchemaAsync', | ||
| href: '../BaseSchemaAsync/', | ||
| generics: [ | ||
| 'unknown', | ||
| 'unknown', | ||
| { | ||
| type: 'custom', | ||
| name: 'BaseIssue', | ||
| href: '../BaseIssue/', | ||
| generics: ['unknown'], | ||
| }, | ||
| ], | ||
| }, | ||
| ], | ||
| }, | ||
| }, | ||
| TDefault: { | ||
| modifier: 'extends', | ||
| type: { | ||
| type: 'custom', | ||
| name: 'DefaultAsync', | ||
| href: '../DefaultAsync/', | ||
| generics: [ | ||
| { | ||
| type: 'custom', | ||
| name: 'TWrapped', | ||
| }, | ||
| 'undefined', | ||
| ], | ||
| }, | ||
| }, | ||
| wrapped: { | ||
| type: { | ||
| type: 'custom', | ||
| name: 'TWrapped', | ||
| }, | ||
| }, | ||
| default_: { | ||
| type: { | ||
| type: 'custom', | ||
| name: 'TDefault', | ||
| }, | ||
| }, | ||
| Schema: { | ||
| type: { | ||
| type: 'custom', | ||
| name: 'UndefinedableSchemaAsync', | ||
| href: '../UndefinedableSchemaAsync/', | ||
| generics: [ | ||
| { | ||
| type: 'custom', | ||
| name: 'TWrapped', | ||
| }, | ||
| { | ||
| type: 'custom', | ||
| name: 'TDefault', | ||
| }, | ||
| ], | ||
| }, | ||
| }, | ||
| }; |