Merge pull request #2493 from hey-api/docs/zod-datetimes

docs(zod): document iso datetimes

Author: mrlubos

docs/openapi-ts/configuration.md

@@ -67,7 +67,7 @@ export default defineConfig([
 
 You must provide an input so we can load your OpenAPI specification.
 
-The input can be a string path, URL, API registry shorthand, an object containing any of these, or an object representing an OpenAPI specification. Hey API supports all valid OpenAPI versions and file formats.
+The input can be a string path, URL, [API registry](/openapi-ts/configuration/input#api-registry) shorthand, an object containing any of these, or an object representing an OpenAPI specification. Hey API supports all valid OpenAPI versions and file formats.
 
 You can learn more on the [Input](/openapi-ts/configuration/input) page.
 

docs/openapi-ts/configuration/input.md

@@ -9,7 +9,7 @@ You must provide an input so we can load your OpenAPI specification.
 
 ## Input
 
-The input can be a string path, URL, API registry shorthand, an object containing any of these, or an object representing an OpenAPI specification. Hey API supports all valid OpenAPI versions and file formats.
+The input can be a string path, URL, [API registry](#api-registry), an object containing any of these, or an object representing an OpenAPI specification. Hey API supports all valid OpenAPI versions and file formats.
 
 ::: code-group
 

docs/openapi-ts/plugins/zod.md

@@ -175,6 +175,66 @@ export default {
 
 You can customize the naming and casing pattern for `definitions` schemas using the `.name` and `.case` options.
 
+## ISO Datetimes
+
+By default, values without a timezone or with a timezone offset are not allowed in the `z.iso.datetime()` method.
+
+### Timezone offsets
+
+You can allow values with timezone offsets by setting `dates.offset` to `true`.
+
+::: code-group
+
+```ts [example]
+export const zFoo = z.iso.datetime({ offset: true });
+```
+
+```js [config]
+export default {
+  input: 'hey-api/backend', // sign up at app.heyapi.dev
+  output: 'src/client',
+  plugins: [
+    // ...other plugins
+    {
+      name: 'zod',
+      dates: {
+        offset: true, // [!code ++]
+      },
+    },
+  ],
+};
+```
+
+:::
+
+### Local times
+
+You can allow values without a timezone by setting `dates.local` to `true`.
+
+::: code-group
+
+```ts [example]
+export const zFoo = z.iso.datetime({ local: true });
+```
+
+```js [config]
+export default {
+  input: 'hey-api/backend', // sign up at app.heyapi.dev
+  output: 'src/client',
+  plugins: [
+    // ...other plugins
+    {
+      name: 'zod',
+      dates: {
+        local: true, // [!code ++]
+      },
+    },
+  ],
+};
+```
+
+:::
+
 ## Metadata
 
 It's often useful to associate a schema with some additional [metadata](https://zod.dev/metadata) for documentation, code generation, AI structured outputs, form validation, and other purposes. If this is your use case, you can set `metadata` to `true` to generate additional metadata about schemas.

docs/openapi-ts/plugins/zod/mini.md

@@ -36,8 +36,8 @@ export default {
   plugins: [
     // ...other plugins
     {
-      compatibilityVersion: 'mini', // [!code ++]
       name: 'zod', // [!code ++]
+      compatibilityVersion: 'mini', // [!code ++]
     },
   ],
 };
@@ -53,7 +53,10 @@ export default {
   output: 'src/client',
   plugins: [
     // ...other plugins
-    'zod',
+    {
+      name: 'zod',
+      compatibilityVersion: 'mini',
+    },
     {
       name: '@hey-api/sdk', // [!code ++]
       validator: true, // [!code ++]
@@ -97,6 +100,7 @@ export default {
     // ...other plugins
     {
       name: 'zod',
+      compatibilityVersion: 'mini',
       requests: true, // [!code ++]
     },
   ],
@@ -136,6 +140,7 @@ export default {
     // ...other plugins
     {
       name: 'zod',
+      compatibilityVersion: 'mini',
       responses: true, // [!code ++]
     },
   ],
@@ -168,6 +173,7 @@ export default {
     // ...other plugins
     {
       name: 'zod',
+      compatibilityVersion: 'mini',
       definitions: true, // [!code ++]
     },
   ],
@@ -178,6 +184,68 @@ export default {
 
 You can customize the naming and casing pattern for `definitions` schemas using the `.name` and `.case` options.
 
+## ISO Datetimes
+
+By default, values without a timezone or with a timezone offset are not allowed in the `z.iso.datetime()` method.
+
+### Timezone offsets
+
+You can allow values with timezone offsets by setting `dates.offset` to `true`.
+
+::: code-group
+
+```ts [example]
+export const zFoo = z.iso.datetime({ offset: true });
+```
+
+```js [config]
+export default {
+  input: 'hey-api/backend', // sign up at app.heyapi.dev
+  output: 'src/client',
+  plugins: [
+    // ...other plugins
+    {
+      name: 'zod',
+      compatibilityVersion: 'mini',
+      dates: {
+        offset: true, // [!code ++]
+      },
+    },
+  ],
+};
+```
+
+:::
+
+### Local times
+
+You can allow values without a timezone by setting `dates.local` to `true`.
+
+::: code-group
+
+```ts [example]
+export const zFoo = z.iso.datetime({ local: true });
+```
+
+```js [config]
+export default {
+  input: 'hey-api/backend', // sign up at app.heyapi.dev
+  output: 'src/client',
+  plugins: [
+    // ...other plugins
+    {
+      name: 'zod',
+      compatibilityVersion: 'mini',
+      dates: {
+        local: true, // [!code ++]
+      },
+    },
+  ],
+};
+```
+
+:::
+
 ## Metadata
 
 It's often useful to associate a schema with some additional [metadata](https://zod.dev/metadata) for documentation, code generation, AI structured outputs, form validation, and other purposes. If this is your use case, you can set `metadata` to `true` to generate additional metadata about schemas.
@@ -198,6 +266,7 @@ export default {
     // ...other plugins
     {
       name: 'zod',
+      compatibilityVersion: 'mini',
       metadata: true, // [!code ++]
     },
   ],
@@ -224,6 +293,7 @@ export default {
     // ...other plugins
     {
       name: 'zod',
+      compatibilityVersion: 'mini',
       types: {
         infer: false, // by default, no `z.infer` types [!code ++]
       },

docs/openapi-ts/plugins/zod/v3.md

@@ -36,8 +36,8 @@ export default {
   plugins: [
     // ...other plugins
     {
-      compatibilityVersion: 3, // [!code ++]
       name: 'zod', // [!code ++]
+      compatibilityVersion: 3, // [!code ++]
     },
   ],
 };
@@ -53,7 +53,10 @@ export default {
   output: 'src/client',
   plugins: [
     // ...other plugins
-    'zod',
+    {
+      name: 'zod',
+      compatibilityVersion: 3,
+    },
     {
       name: '@hey-api/sdk', // [!code ++]
       validator: true, // [!code ++]
@@ -97,6 +100,7 @@ export default {
     // ...other plugins
     {
       name: 'zod',
+      compatibilityVersion: 3,
       requests: true, // [!code ++]
     },
   ],
@@ -136,6 +140,7 @@ export default {
     // ...other plugins
     {
       name: 'zod',
+      compatibilityVersion: 3,
       responses: true, // [!code ++]
     },
   ],
@@ -168,6 +173,7 @@ export default {
     // ...other plugins
     {
       name: 'zod',
+      compatibilityVersion: 3,
       definitions: true, // [!code ++]
     },
   ],
@@ -178,6 +184,68 @@ export default {
 
 You can customize the naming and casing pattern for `definitions` schemas using the `.name` and `.case` options.
 
+## ISO Datetimes
+
+By default, values without a timezone or with a timezone offset are not allowed in the `z.string().datetime()` method.
+
+### Timezone offsets
+
+You can allow values with timezone offsets by setting `dates.offset` to `true`.
+
+::: code-group
+
+```ts [example]
+export const zFoo = z.string().datetime({ offset: true });
+```
+
+```js [config]
+export default {
+  input: 'hey-api/backend', // sign up at app.heyapi.dev
+  output: 'src/client',
+  plugins: [
+    // ...other plugins
+    {
+      name: 'zod',
+      compatibilityVersion: 3,
+      dates: {
+        offset: true, // [!code ++]
+      },
+    },
+  ],
+};
+```
+
+:::
+
+### Local times
+
+You can allow values without a timezone by setting `dates.local` to `true`.
+
+::: code-group
+
+```ts [example]
+export const zFoo = z.string().datetime({ local: true });
+```
+
+```js [config]
+export default {
+  input: 'hey-api/backend', // sign up at app.heyapi.dev
+  output: 'src/client',
+  plugins: [
+    // ...other plugins
+    {
+      name: 'zod',
+      compatibilityVersion: 3,
+      dates: {
+        local: true, // [!code ++]
+      },
+    },
+  ],
+};
+```
+
+:::
+
 ## Metadata
 
 It's often useful to associate a schema with some additional [metadata](https://v3.zod.dev/?id=describe) for documentation, code generation, AI structured outputs, form validation, and other purposes. If this is your use case, you can set `metadata` to `true` to generate additional metadata about schemas.
@@ -196,6 +264,7 @@ export default {
     // ...other plugins
     {
       name: 'zod',
+      compatibilityVersion: 3,
       metadata: true, // [!code ++]
     },
   ],
@@ -222,6 +291,7 @@ export default {
     // ...other plugins
     {
       name: 'zod',
+      compatibilityVersion: 3,
       types: {
         infer: false, // by default, no `z.infer` types [!code ++]
       },

docs/package.json

@@ -16,7 +16,7 @@
   },
   "devDependencies": {
     "sharp": "0.33.5",
-    "vitepress": "2.0.0-alpha.11",
+    "vitepress": "2.0.0-alpha.12",
     "vitepress-plugin-llms": "1.7.3",
     "vue": "3.5.13"
   },