Date Handling in API Clients#

JSON does not natively distinguish between plain strings and date strings, so Hey API's generated clients require explicit configuration to serialize and deserialize Date objects. Three mechanisms are available, each targeting a different point in the pipeline:

Response Deserialization — Transformers Plugin#

The @hey-api/transformers plugin is the primary mechanism for turning date strings in API responses into native Date objects 1.

Enable it in your openapi-ts config:

// openapi-ts.config.ts
{
  plugins: [
    {
      dates: true,
      name: '@hey-api/transformers',
    },
  ],
}

1

With dates: true, the generator:

1. Changes TypeScript types from string to Date for all date/date-time fields.
2. Emits a transformers.gen.ts file with per-operation transformer functions that call new Date(value) at runtime 1.

Limitation: Only native JavaScript Date objects are supported. Third-party date libraries (e.g., dayjs, luxon) are not 1.

Wiring Transformers into the SDK#

Transformers are opt-in in the SDK layer. Set transformer: true on @hey-api/sdk to automatically apply responseTransformer to every generated SDK function 2:

{
  plugins: [
    '@hey-api/transformers',
    { name: '@hey-api/sdk', transformer: true },
  ],
}

Without this, generated transformers exist in the output but are not called automatically — you must invoke them manually.

Request Validation with Zod / Valibot#

Validator plugins handle request bodies and responses. They do not transform string → Date the way the transformers plugin does; instead they validate that the value matches the expected ISO format 2.

Zod exposes a dates object to tune z.iso.datetime() behavior 3:

• dates.offset: true — allows values with timezone offsets.
• dates.local: true — allows values without a timezone.

Enable a validator and wire it into the SDK:

{
  plugins: [
    { name: '@hey-api/sdk', validator: true },
    { name: 'zod', dates: { offset: true } },
  ],
}

2

You can also restrict validation to requests only, leaving response validation off — useful when you trust server output but not client input 2.

Pre-Generation Schema Patching#

When a spec contains incorrect or unwanted date representations, fix them before code generation using parser.patch.schemas. Patches run before any parsing, so all downstream plugins see the corrected schema 4.

Example — convert a date-time string field to a Unix timestamp (number):

// openapi-ts.config.ts
{
  parser: {
    patch: {
      schemas: {
        Foo: (schema) => {
          delete schema.properties.updatedAt.format;
          schema.properties.updatedAt.type = 'number';
        },
      },
    },
  },
}

4

Other common uses: add a missing format: 'date-time' annotation, or remove an erroneous date field entirely (delete schema.properties.internalDate).

Further Reading#

• Transformers plugin reference — full API, bigInt option, and generated code example
• SDK plugin — Transformers section — transformer and validator wiring options
• Parser configuration — patch, transforms, and filters
• Zod plugin — dates.offset / dates.local configuration
• Validators overview — Valibot, Zod, and other supported validators