Fix and improve array API reference on website

fabian-hiller · Dec 30, 2023 · 6a4112e · 6a4112e
1 parent d3fe8b6
commit 6a4112e
Show file tree

Hide file tree

Showing 3 changed files with 55 additions and 40 deletions.
diff --git a/website/src/routes/api/(schemas)/array/index.mdx b/website/src/routes/api/(schemas)/array/index.mdx
@@ -1,29 +1,25 @@
 ---
 title: array
-source: /schemas/array/array.ts
 description: Creates an array schema.
+source: /schemas/array/array.ts
 contributors:
   - fabian-hiller
   - kazizi55
 ---
 
+import { Link } from '@builder.io/qwik-city';
 import { ApiList, Property } from '~/components';
 import { properties } from './properties';
 
 # array
 
 Creates an array schema.
 
-> If you want to use `tuple` schema, you can use [tuple](../tuple/).
-
 ```ts
 // Array schema with an optional pipe
-const Schema = array(item, pipe);
+const Schema = array<TItem>(item, pipe);
 
 // Array schema with an optional message and pipe
-const Schema = array(item, message, pipe);
-
-// Array schema with generics
 const Schema = array<TItem>(item, message, pipe);
 ```
 
@@ -41,6 +37,8 @@ const Schema = array<TItem>(item, message, pipe);
 
 With `array` you can validate the data type of the input and with `pipe` you can transform and validate the further details of the array. If the input is not an array, you can use `message` to customize the error message.
 
+> If your array has a fixed length, consider using <Link href="../tuple/">`tuple`</Link> for a more precise typing.
+
 ## Returns
 
 - `Schema` <Property {...properties.Schema} />
@@ -51,31 +49,34 @@ The following examples show how `array` can be used.
 
 ### String array schema
 
-Schema that accepts `array` which contains only `string`.
+Schema to validate an array of strings.
 
 ```ts
-const StringArraySchema = array(string());
+const StringArraySchema = array(string(), 'An array is required.');
 ```
 
-### Mixed array schema of string and number
+### Object array schema
 
-Schema that accepts `array` which contains only `string` and `number`.
+Schema to validate an array of objects.
 
 ```ts
-const StringNumberMixedArraySchema = array(union([string(), number()]));
+const ObjectArraySchema = array(object({ key: string() }));
 ```
 
-### User object array schema
+### Validate length
 
-Schema that accepts `array` which contains only user object.
+Schema that validates the length of an array.
 
 ```ts
-const UserSchema = object({
-  name: string(),
-  age: number(),
-});
+const ArrayLengthSchema = array(number(), [minLength(1), maxLength(3)]);
+```
+
+### Validate content
 
-const UserArraySchema = array(UserSchema);
+Schema that validates the content of an array.
+
+```ts
+const ArrayContentSchema = array(string(), [includes('foo'), excludes('bar')]);
 ```
 
 ## Related
@@ -108,6 +109,7 @@ The following APIs can be combined with `array`.
 
 <ApiList
   items={[
+    'custom',
     'excludes',
     'includes',
     'length',

diff --git a/website/src/routes/api/(types)/ArraySchema/properties.ts b/website/src/routes/api/(types)/ArraySchema/properties.ts
@@ -22,34 +22,32 @@ export const properties: Record<string, PropertyProps> = {
               ],
             },
           },
-
           {
-            type: 'array',
-            item: {
-              type: 'custom',
-              name: 'TOutput',
-              generics: [
-                {
-                  type: 'custom',
-                  name: 'TItem',
-                },
-              ],
-              default: {
+            type: 'custom',
+            name: 'TOutput',
+            default: {
+              type: 'array',
+              item: {
                 type: 'custom',
                 name: 'Output',
                 href: '../Output/',
+                generics: [
+                  {
+                    type: 'custom',
+                    name: 'TItem',
+                  },
+                ],
               },
             },
           },
         ],
       },
     ],
   },
-  message: {
+  type: {
     type: {
-      type: 'custom',
-      name: 'ErrorMessage',
-      href: '../ErrorMessage/',
+      type: 'string',
+      value: 'array',
     },
   },
   item: {
@@ -60,10 +58,11 @@ export const properties: Record<string, PropertyProps> = {
       },
     ],
   },
-  type: {
+  message: {
     type: {
-      type: 'string',
-      value: 'array',
+      type: 'custom',
+      name: 'ErrorMessage',
+      href: '../ErrorMessage/',
     },
   },
   pipe: {
@@ -72,7 +71,21 @@ export const properties: Record<string, PropertyProps> = {
         type: 'custom',
         name: 'Pipe',
         href: '../Pipe/',
-        generics: ['array'],
+        generics: [
+          {
+            type: 'array',
+            item: {
+              type: 'custom',
+              name: 'Output',
+              generics: [
+                {
+                  type: 'custom',
+                  name: 'TItem',
+                },
+              ],
+            },
+          },
+        ],
       },
       'undefined',
     ],

diff --git a/website/src/routes/api/menu.md b/website/src/routes/api/menu.md
@@ -190,8 +190,8 @@
 ## Types
 
 - [AnySchema](/api/AnySchema/)
-- [ArraySchema](/api/ArraySchema/)
 - [ArrayPathItem](/api/ArrayPathItem/)
+- [ArraySchema](/api/ArraySchema/)
 - [BaseSchema](/api/BaseSchema/)
 - [BaseTransformation](/api/BaseTransformation/)
 - [BaseValidation](/api/BaseValidation/)