Enable custom keyword overrides

[joemckie]

Currently, Kubb's output is not so easily overridable when custom code is required. Whilst it's possible to create new generators, if one wants to keep the bulk of the existing plugin functionality, the code must be copied and adjusted (unless there's another method of which I'm unaware).

For example, in the Zod plugin, it would be useful to be able to override the datetime keyword to return something other than z.iso, and in the Faker plugin, something other than faker.date.

The mapper option comes close, however, that only works on known keys rather than as a global override for all keys of a type.

[stijnvanhulle]

V4 of Kubb does not have support for this but we are planning v5 that will make it easier to do overrides. But to make that work, we need to refactor our generators.

[ghost]

Sounds great!

[timohausmann]

That would be super helpful! We have some fields in our API that share the same key but have different types.

[stijnvanhulle]

In v5 this is now possible without copying any plugin code. Every code-producing plugin (plugin-zod, plugin-faker, plugin-ts) ships a printer with a printer.nodes option: a map of schema node type → handler that globally overrides the built-in output for every node of that type — exactly the "all keys of a type" override mapper couldn't do (mapper is per-name).

import { pluginZod } from '@kubb/plugin-zod'
import { pluginFaker } from '@kubb/plugin-faker'

pluginZod({
  printer: {
    nodes: {
      datetime: () => 'z.string().datetime()', // default: z.iso.datetime()
      date: () => 'z.string().date()',         // default: z.iso.date()
    },
  },
}),
pluginFaker({
  printer: {
    nodes: {
      datetime: () => 'faker.date.past().toISOString()', // default: faker.date.anytime().toISOString()
    },
  },
}),

The override keys are the schema types: string, number, integer, bigint, boolean, date, datetime, time, uuid, email, url, ipv4, ipv6, blob, object, array, enum, union, ref, etc. Handlers receive the node and can use this.options and this.transform(node) to recurse, so you can branch on the node's own metadata rather than its property name.

Verified on 5.0.0-beta.35 with a spec containing format: date-time and format: date fields:

	default	with printer.nodes
zod datetime	z.iso.datetime()	z.string().datetime()
zod date	z.iso.date()	z.string().date()
faker datetime	faker.date.anytime().toISOString()	faker.date.past().toISOString()

Types you don't override keep their built-in handlers. For zod, with mini: true the overrides target the Zod Mini printer.

[stijnvanhulle]

https://kubb.dev/plugins/plugin-zod#printer

[timohausmann]

Amazing, thank you, will check it out!

[stijnvanhulle]

@timohausmann feel free to give feedback so we know that every use case can be covered