Merge pull request #791 from EltonLobo07/doc/add-variantAsync-with-sc…

…hema

add `variantAsync` & `VariantSchemaAsync` API refs

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<TKey, TOptions, TMessage>(key, options, message);
+```
+
+## Generics
+
+- `TKey` <Property {...properties.TKey} />
+- `TOptions` <Property {...properties.TOptions} />
+- `TMessage` <Property {...properties.TMessage} />
+
+## Parameters
+
+- `key` <Property {...properties.key} />
+- `options` <Property {...properties.options} />
+- `message` <Property {...properties.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` <Property {...properties.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
+
+<ApiList items={['looseObject', 'object', 'objectWithRest', 'strictObject']} />
+
+### Methods
+
+<ApiList items={['config', 'getDefault', 'getFallback']} />
+
+### Actions
+
+<ApiList
+ items={[
+ 'brand',
+ 'check',
+ 'description',
+ 'partialCheck',
+ 'rawCheck',
+ 'rawTransform',
+ 'readonly',
+ 'transform',
+ ]}
+/>
+
+### Utils
+
+<ApiList items={['entriesFromList', 'isOfKind', 'isOfType']} />
+
+### Async
+
+<ApiList
+ items={[
+ 'checkAsync',
+ 'fallbackAsync',
+ 'getDefaultsAsync',
+ 'getFallbacksAsync',
+ 'looseObjectAsync',
+ 'objectAsync',
+ 'objectWithRestAsync',
+ 'parseAsync',
+ 'parserAsync',
+ 'partialCheckAsync',
+ 'pipeAsync',
+ 'rawCheckAsync',
+ 'rawTransformAsync',
+ 'safeParseAsync',
+ 'safeParserAsync',
+ 'strictObjectAsync',
+ 'transformAsync',
+ ]}
+/>

website/src/routes/api/(async)/variantAsync/properties.ts

@@ -0,0 +1,82 @@
+import type { PropertyProps } from '~/components';
+
+export const properties: Record<string, PropertyProps> = {
+ 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',
+ },
+ ],
+ },
+ },
+};

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` <Property {...properties.TKey} />
+- `TOptions` <Property {...properties.TOptions} />
+- `TMessage` <Property {...properties.TMessage} />
+
+## Definition
+
+- `VariantSchemaAsync` <Property {...properties.BaseSchemaAsync} />
+ - `type` <Property {...properties.type} />
+ - `reference` <Property {...properties.reference} />
+ - `expects` <Property {...properties.expects} />
+ - `key` <Property {...properties.key} />
+ - `options` <Property {...properties.options} />
+ - `message` <Property {...properties.message} />