Merge pull request #337 from sqmasep/docs/fallback

docs(api): Fallback related docs

library/src/methods/fallback/fallback.ts

@@ -19,7 +19,7 @@ export type SchemaWithFallback<
 };
 
 /**
- * Returns a fallback value when validating the passed schema failed.
+ * Returns a fallback output value when validating the passed schema failed.
  *
  * @param schema The schema to catch.
  * @param fallback The fallback value.

library/src/methods/fallback/fallbackAsync.ts

@@ -21,7 +21,7 @@ export type SchemaWithFallbackAsync<
 };
 
 /**
- * Returns a fallback value when validating the passed schema failed.
+ * Returns a fallback output value when validating the passed schema failed.
  *
  * @param schema The schema to catch.
  * @param fallback The fallback value.

website/src/routes/api/(methods)/fallback/index.mdx

@@ -1,11 +1,129 @@
 ---
 title: fallback
+description: Returns a fallback output value when validating the passed schema failed.
 source: /methods/fallback/fallback.ts
 contributors:
   - fabian-hiller
   - FlorianDevPhynix
+  - sqmasep
 ---
 
+import { Link } from '@builder.io/qwik-city';
+import { ApiList, Property } from '~/components';
+import { properties } from './properties';
+
 # fallback
 
-> 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/methods/fallback/fallback.ts) or take a look at [issue #287](https://github.com/fabian-hiller/valibot/issues/287) to help us extend the API reference.
+Returns a fallback output value when validating the passed schema failed.
+
+```ts
+const Schema = fallback<TSchema, TFallback>(schema, fallback);
+```
+
+## Generics
+
+- `TSchema` <Property {...properties.TSchema} />
+- `TFallback` <Property {...properties.TFallback} />
+
+## Parameters
+
+- `schema` <Property {...properties.schema} />
+- `fallback` <Property {...properties.fallback}/>
+
+### Explanation
+
+`fallback` allows you to define a fallback value for the output that will be used if the validation of the input fails. This means that no issues will be returned when using `fallback` and the schema will always return an output.
+
+> If you only want to set a default value for `null` or `undefined` inputs, you should use <Link href="../optional/">`optional`</Link>, <Link href="../nullable/">`nullable`</Link> or <Link href="../nullish/">`nullish`</Link> instead.
+
+> Warning: The fallback value is not validated. Make sure that the fallback value matches your schema.
+
+## Returns
+
+- `Schema` <Property {...properties.SchemaWithFallback} />
+
+## Examples
+
+The following examples show how `fallback` can be used.
+
+### Fallback string schema
+
+Schema that will always return a string output.
+
+```ts
+const FallbackStringSchema = fallback(string(), "I'm the fallback!");
+```
+
+### Fallback date schema
+
+Schema that will always return a `Date` output.
+
+> By using a function as the `fallback` parameter, the schema will return a new `Date` instance each time the input does not match the schema.
+
+```ts
+const FallbackDateSchema = fallback(date(), () => new Date());
+```
+
+## Related
+
+The following APIs can be combined with `fallback`.
+
+### Methods
+
+<ApiList
+  items={[
+    'brand',
+    'coerce',
+    'fallback',
+    'getDefault',
+    'getDefaults',
+    'getFallback',
+    'getFallbacks',
+    'is',
+    'parse',
+    'safeParse',
+    'transform',
+  ]}
+/>
+
+### Schemas
+
+<ApiList
+  items={[
+    'any',
+    'array',
+    'bigint',
+    'blob',
+    'boolean',
+    'date',
+    'enum_',
+    'instance',
+    'intersect',
+    'literal',
+    'map',
+    'nan',
+    'never',
+    'nonNullable',
+    'nonNullish',
+    'nonOptional',
+    'null_',
+    'nullable',
+    'nullish',
+    'number',
+    'object',
+    'optional',
+    'picklist',
+    'record',
+    'recursive',
+    'set',
+    'special',
+    'string',
+    'symbol',
+    'tuple',
+    'undefined_',
+    'union',
+    'unknown',
+    'variant',
+    'void_',
+  ]}
+/>

website/src/routes/api/(methods)/fallback/properties.ts

@@ -0,0 +1,78 @@
+import type { PropertyProps } from '~/components';
+
+export const properties: Record<string, PropertyProps> = {
+  TSchema: {
+    type: {
+      type: 'custom',
+      name: 'BaseSchema',
+      href: '../BaseSchema/',
+    },
+  },
+  TFallback: {
+    type: [
+      {
+        type: 'custom',
+        name: 'Output',
+        href: '../Output/',
+        generics: [
+          {
+            type: 'custom',
+            name: 'TSchema',
+          },
+        ],
+      },
+      {
+        type: 'function',
+        params: [
+          {
+            type: {
+              type: 'custom',
+              name: 'FallbackInfo',
+              href: '../FallbackInfo/',
+            },
+            name: 'info',
+            optional: true,
+          },
+        ],
+        return: [
+          {
+            type: 'custom',
+            name: 'Output',
+            href: '../Output/',
+            generics: [
+              {
+                type: 'custom',
+                name: 'TSchema',
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  },
+  schema: {
+    type: [
+      {
+        type: 'custom',
+        name: 'TSchema',
+      },
+    ],
+  },
+  fallback: {
+    type: [
+      {
+        type: 'custom',
+        name: 'TFallback',
+      },
+    ],
+  },
+  SchemaWithFallback: {
+    type: [
+      {
+        type: 'custom',
+        name: 'SchemaWithFallback',
+        href: '../SchemaWithFallback/',
+      },
+    ],
+  },
+};

website/src/routes/api/(types)/FallbackInfo/index.mdx

@@ -0,0 +1,20 @@
+---
+title: FallbackInfo
+description: Fallback info type.
+contributors:
+  - fabian-hiller
+  - sqmasep
+---
+
+import { Property } from '~/components';
+import { properties } from './properties';
+
+# FallbackInfo
+
+Fallback info type.
+
+## Definition
+
+- `FallbackInfo` <Property {...properties.FallbackInfo} />
+  - `input` <Property {...properties.input} />
+  - `issues` <Property {...properties.issues} />

website/src/routes/api/(types)/FallbackInfo/properties.ts

@@ -0,0 +1,17 @@
+import type { PropertyProps } from '~/components';
+
+export const properties: Record<string, PropertyProps> = {
+  FallbackInfo: {
+    type: 'object',
+  },
+  input: {
+    type: 'unknown',
+  },
+  issues: {
+    type: {
+      type: 'custom',
+      name: 'Issues',
+      href: '../Issues/',
+    },
+  },
+};

website/src/routes/api/(types)/SchemaWithFallback/index.mdx

@@ -0,0 +1,19 @@
+---
+title: SchemaWithFallback
+description: Schema with fallback type.
+contributors:
+  - fabian-hiller
+  - sqmasep
+---
+
+import { Property } from '~/components';
+import { properties } from './properties';
+
+# SchemaWithFallback
+
+Schema with fallback type.
+
+## Definition
+
+- `SchemaWithFallback` <Property {...properties.BaseSchema} />
+  - `fallback` <Property {...properties.fallback} />

website/src/routes/api/(types)/SchemaWithFallback/properties.ts

@@ -0,0 +1,18 @@
+import type { PropertyProps } from '~/components';
+
+export const properties: Record<string, PropertyProps> = {
+  BaseSchema: {
+    type: [
+      {
+        type: 'custom',
+        name: 'TSchema',
+      },
+    ],
+  },
+  fallback: {
+    type: {
+      type: 'custom',
+      name: 'TFallback',
+    },
+  },
+};

website/src/routes/api/menu.md

@@ -201,6 +201,7 @@
 - [Enum](/api/Enum/)
 - [EnumSchema](/api/EnumSchema/)
 - [ErrorMessage](/api/ErrorMessage/)
+- [FallbackInfo](/api/FallbackInfo/)
 - [Input](/api/Input/)
 - [InvalidActionResult](/api/InvalidActionResult/)
 - [Issue](/api/Issue/)
@@ -222,6 +223,7 @@
 - [PipeActionResult](/api/PipeActionResult/)
 - [RecordPathItem](/api/RecordPathItem/)
 - [SchemaResult](/api/SchemaResult/)
+- [SchemaWithFallback](/api/SchemaWithFallback/)
 - [SetPathItem](/api/SetPathItem/)
 - [StringSchema](/api/StringSchema/)
 - [SymbolSchema](/api/SymbolSchema/)