From 436c965039a3d8956861a5c83a3415d42b2df6bb Mon Sep 17 00:00:00 2001 From: Elton Lobo Date: Wed, 21 Aug 2024 00:30:36 +0530 Subject: [PATCH] add `variantAsync` & `VariantSchemaAsync` API refs --- .../routes/api/(async)/variantAsync/index.mdx | 160 +++++++++++++++++- .../api/(async)/variantAsync/properties.ts | 82 +++++++++ .../api/(types)/VariantSchemaAsync/index.mdx | 30 ++++ .../(types)/VariantSchemaAsync/properties.ts | 136 +++++++++++++++ website/src/routes/api/menu.md | 1 + 5 files changed, 408 insertions(+), 1 deletion(-) create mode 100644 website/src/routes/api/(async)/variantAsync/properties.ts create mode 100644 website/src/routes/api/(types)/VariantSchemaAsync/index.mdx create mode 100644 website/src/routes/api/(types)/VariantSchemaAsync/properties.ts diff --git a/website/src/routes/api/(async)/variantAsync/index.mdx b/website/src/routes/api/(async)/variantAsync/index.mdx index d4d70dd6d..a775ad1f6 100644 --- a/website/src/routes/api/(async)/variantAsync/index.mdx +++ b/website/src/routes/api/(async)/variantAsync/index.mdx @@ -1,10 +1,168 @@ --- title: variantAsync +description: Creates a variant schema. source: /schemas/variant/variantAsync.ts contributors: - fabian-hiller + - EltonLobo07 --- +import { ApiList, Property } from '~/components'; +import { properties } from './properties'; + # variantAsync -> 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/variant/variantAsync.ts) or take a look at [issue #287](https://github.com/fabian-hiller/valibot/issues/287) to help us extend the API reference. +Creates a variant schema. + +```ts +const Schema = v.variantAsync(key, options, message); +``` + +## Generics + +- `TKey` +- `TOptions` +- `TMessage` + +## Parameters + +- `key` +- `options` +- `message` + +### Explanation + +With `variantAsync` you can validate if the input matches one of the given object `options`. The object schema to be used for the validation is determined by the discriminator `key`. If the input does not match a schema and cannot be clearly assigned to one of the options, you can use `message` to customize the error message. + +> It is allowed to specify the exact same or a similar discriminator multiple times. However, in such cases `variantAsync` will only return the output of the first untyped or typed variant option result. Typed results take precedence over untyped ones. + +## Returns + +- `Schema` + +## Examples + +The following examples show how `variantAsync` can be used. + +### Message schema + +Schema to validate a message object. + +```ts +import { isValidGroupReceiver, isValidUserReceiver } from '~/api'; + +const MessageSchema = v.objectAsync({ + message: v.pipe(v.string(), v.nonEmpty()), + receiver: v.variantAsync('type', [ + v.objectAsync({ + type: v.literal('group'), + groupId: v.pipeAsync( + v.string(), + v.uuid(), + v.checkAsync(isValidGroupReceiver, 'The group cannot receive messages.') + ), + }), + v.objectAsync({ + type: v.literal('user'), + email: v.pipeAsync( + v.string(), + v.email(), + v.checkAsync(isValidUserReceiver, 'The user cannot receive messages.') + ), + }), + ]), +}); +``` + +### User schema + +Schema to validate unique user details. + +```ts +import { isRegisteredEmail, isRegisteredUsername, isValidUserId } from '~/api'; + +const UserSchema = v.variantAsync('type', [ + // Assume this schema is from a different file and reused here. + v.variantAsync('type', [ + v.objectAsync({ + type: v.literal('email'), + email: v.pipeAsync( + v.string(), + v.email(), + v.checkAsync(isRegisteredEmail, 'The email is not registered.') + ), + }), + v.objectAsync({ + type: v.literal('username'), + username: v.pipeAsync( + v.string(), + v.nonEmpty(), + v.checkAsync(isRegisteredUsername, 'The username is not registered.') + ), + }), + ]), + v.objectAsync({ + type: v.literal('userId'), + userId: v.pipeAsync( + v.string(), + v.uuid(), + v.checkAsync(isValidUserId, 'The user id is not valid.') + ), + }), +]); +``` + +## Related + +The following APIs can be combined with `variantAsync`. + +### Schemas + + + +### Methods + + + +### Actions + + + +### Utils + + + +### Async + + diff --git a/website/src/routes/api/(async)/variantAsync/properties.ts b/website/src/routes/api/(async)/variantAsync/properties.ts new file mode 100644 index 000000000..27ae99fb2 --- /dev/null +++ b/website/src/routes/api/(async)/variantAsync/properties.ts @@ -0,0 +1,82 @@ +import type { PropertyProps } from '~/components'; + +export const properties: Record = { + TKey: { + modifier: 'extends', + type: 'string', + }, + TOptions: { + modifier: 'extends', + type: { + type: 'custom', + name: 'VariantOptionsAsync', + href: '../VariantOptionsAsync/', + generics: [ + { + type: 'custom', + name: 'TKey', + }, + ], + }, + }, + TMessage: { + modifier: 'extends', + type: { + type: 'union', + options: [ + { + type: 'custom', + name: 'ErrorMessage', + href: '../ErrorMessage/', + generics: [ + { + type: 'custom', + name: 'VariantIssue', + href: '../VariantIssue/', + }, + ], + }, + 'undefined', + ], + }, + }, + key: { + type: { + type: 'custom', + name: 'TKey', + }, + }, + options: { + type: { + type: 'custom', + name: 'TOptions', + }, + }, + message: { + type: { + type: 'custom', + name: 'TMessage', + }, + }, + Schema: { + type: { + type: 'custom', + name: 'VariantSchemaAsync', + href: '../VariantSchemaAsync/', + generics: [ + { + type: 'custom', + name: 'TKey', + }, + { + type: 'custom', + name: 'TOptions', + }, + { + type: 'custom', + name: 'TMessage', + }, + ], + }, + }, +}; diff --git a/website/src/routes/api/(types)/VariantSchemaAsync/index.mdx b/website/src/routes/api/(types)/VariantSchemaAsync/index.mdx new file mode 100644 index 000000000..a27e68cfe --- /dev/null +++ b/website/src/routes/api/(types)/VariantSchemaAsync/index.mdx @@ -0,0 +1,30 @@ +--- +title: VariantSchemaAsync +description: Variant schema async type. +contributors: + - EltonLobo07 + - fabian-hiller +--- + +import { Property } from '~/components'; +import { properties } from './properties'; + +# VariantSchemaAsync + +Variant schema async type. + +## Generics + +- `TKey` +- `TOptions` +- `TMessage` + +## Definition + +- `VariantSchemaAsync` + - `type` + - `reference` + - `expects` + - `key` + - `options` + - `message` diff --git a/website/src/routes/api/(types)/VariantSchemaAsync/properties.ts b/website/src/routes/api/(types)/VariantSchemaAsync/properties.ts new file mode 100644 index 000000000..cb9827f5a --- /dev/null +++ b/website/src/routes/api/(types)/VariantSchemaAsync/properties.ts @@ -0,0 +1,136 @@ +import type { PropertyProps } from '~/components'; + +export const properties: Record = { + TKey: { + modifier: 'extends', + type: 'string', + }, + TOptions: { + modifier: 'extends', + type: { + type: 'custom', + name: 'VariantOptionsAsync', + href: '../VariantOptionsAsync/', + generics: [ + { + type: 'custom', + name: 'TKey', + }, + ], + }, + }, + TMessage: { + modifier: 'extends', + type: { + type: 'union', + options: [ + { + type: 'custom', + name: 'ErrorMessage', + href: '../ErrorMessage/', + generics: [ + { + type: 'custom', + name: 'VariantIssue', + href: '../VariantIssue/', + }, + ], + }, + 'undefined', + ], + }, + }, + BaseSchemaAsync: { + modifier: 'extends', + type: { + type: 'custom', + name: 'BaseSchemaAsync', + href: '../BaseSchemaAsync/', + generics: [ + { + type: 'custom', + name: 'InferInput', + href: '../InferInput/', + generics: [ + { + type: 'custom', + name: 'TOptions', + indexes: ['number'], + }, + ], + }, + { + type: 'custom', + name: 'InferOutput', + href: '../InferOutput/', + generics: [ + { + type: 'custom', + name: 'TOptions', + indexes: ['number'], + }, + ], + }, + { + type: 'union', + options: [ + { + type: 'custom', + name: 'VariantIssue', + href: '../VariantIssue/', + }, + { + type: 'custom', + name: 'InferVariantIssue', + href: '../InferVariantIssue/', + generics: [ + { + type: 'custom', + name: 'TOptions', + }, + ], + }, + ], + }, + ], + }, + }, + type: { + type: { + type: 'string', + value: 'variant', + }, + }, + reference: { + type: { + type: 'custom', + modifier: 'typeof', + name: 'variantAsync', + href: '../variantAsync/', + }, + }, + expects: { + type: { + type: 'string', + value: 'Object', + }, + }, + key: { + type: { + type: 'custom', + name: 'TKey', + }, + }, + options: { + type: { + type: 'custom', + name: 'TOptions', + }, + }, + message: { + type: { + type: 'custom', + name: 'TMessage', + }, + }, +}; diff --git a/website/src/routes/api/menu.md b/website/src/routes/api/menu.md index be1185072..5552f318c 100644 --- a/website/src/routes/api/menu.md +++ b/website/src/routes/api/menu.md @@ -581,5 +581,6 @@ - [VariantOptions](/api/VariantOptions/) - [VariantOptionsAsync](/api/VariantOptionsAsync/) - [VariantSchema](/api/VariantSchema/) +- [VariantSchemaAsync](/api/VariantSchemaAsync/) - [VoidIssue](/api/VoidIssue/) - [VoidSchema](/api/VoidSchema/)