feat(zod-test): adds zxTest.fuzz for converting a Zod schemas into fast-check arbitraries

.changeset/mean-cats-float.md

@@ -0,0 +1,20 @@
+---
+"@traversable/zod-test": patch
+---
+
+feat(zod-test): adds `zxTest.fuzz` support for more string schema formats
+
+### formats
+
+- `z.cidr`
+- `z.cidr2`
+- `z.cuid`
+- `z.cuid2`
+- `z.e164`
+- `z.email`
+- `z.emoji`
+- `z.ksuid`
+- `z.nanoid`
+- `z.ulid`
+- `z.xid`
+

.changeset/tricky-eagles-fix.md

@@ -0,0 +1,7 @@
+---
+"@traversable/zod-types": patch
+"@traversable/zod-test": patch
+"@traversable/zod": patch
+---
+
+feat(zod-test): adds `zxTest.fuzz` for generating configurable, overridable fast-check arbitraries from a Zod schema (#544)

packages/zod-test/README.md

@@ -75,6 +75,7 @@ import { zxTest } from '@traversable/zod-test'
 
 ## Table of contents
 
+- [`zxTest.fuzz`](https://github.com/traversable/schema/tree/main/packages/zod-test#zxfuzz)
 - [`zxTest.seedToSchema`](https://github.com/traversable/schema/tree/main/packages/zod-test#zxtestseedtoschema)
 - [`zxTest.seedToValidData`](https://github.com/traversable/schema/tree/main/packages/zod-test#zxtestseedtovaliddata)
 - [`zxTest.seedToInvalidData`](https://github.com/traversable/schema/tree/main/packages/zod-test#zxtestseedtoinvaliddata)
@@ -85,6 +86,62 @@ import { zxTest } from '@traversable/zod-test'
 - [`zxTest.SeedInvalidDataGenerator`](https://github.com/traversable/schema/tree/main/packages/zod-test#zxseedinvaliddatagenerator)
 
 
+### `zxTest.fuzz`
+
+Convert a Zod schema into a [fast-check](https://github.com/dubzzz/fast-check) arbitrary.
+
+Configure how fuzzed values will be generated via the 2nd argument (`options`).
+
+Override individual arbitraries via the 3rd argument (`overrides`).
+
+> [!NOTE]
+>
+> `zxTest.fuzz` is the __only__ schema-to-generator function that has itself
+> been fuzz tested to ensure that no matter what schema you give it, the data-generator that `fuzz`
+> returns will always produce valid data.
+
+The only known exceptions are schemas that make it impossible to generate valid data. For example:
+
+- `z.never` 
+- `z.nonoptional(z.undefined())`
+- `z.enum([])`
+- `z.union([])`
+- `z.intersection(z.number(), z.string())`
+
+#### Example
+
+```typescript
+import * as vi from 'vitest'
+import * as fc from 'fast-check' * import { fuzz } from '@traversable/zod-test'
+
+const Schema = z.record(
+  z.string(), 
+  z.union(
+    z.number(),
+    z.string(),
+  )
+)
+
+const generator = fuzz(
+  Schema, 
+  { record: { minKeys: 1 }, number: { noDefaultInfinity: true } },
+  { string: () => fc.stringMatching(/[\S\s]+[\S]+/) },
+)
+
+vi.test('fuzz test example', () => {
+  fc.assert(
+    fc.property(generator, (data) => {
+      vi.assert.doesNotThrow(() => Schema.parse(data))
+    }),
+    { numRuns: 1_000 }
+  )
+})
+```
+
+#### See also
+- the [fast-check docs](https://fast-check.dev)
+
+
 ### `zxTest.seedToSchema`
 
 Use `zxTest.seedToSchema` to convert a seed generated by `zxTest.SeedGenerator` into a

packages/zod-test/package.json

@@ -45,22 +45,19 @@
   },
   "peerDependencies": {
     "@traversable/registry": "workspace:^",
+    "@traversable/zod-types": "workspace:^",
     "fast-check": "3 - 4",
     "zod": "4"
   },
   "peerDependenciesMeta": {
-    "@traversable/registry": {
-      "optional": false
-    },
-    "fast-check": {
-      "optional": false
-    },
-    "zod": {
-      "optional": false
-    }
+    "@traversable/registry": { "optional": false },
+    "@traversable/zod-types": { "optional": true },
+    "fast-check": { "optional": false },
+    "zod": { "optional": false }
   },
   "devDependencies": {
     "@traversable/registry": "workspace:^",
+    "@traversable/zod-types": "workspace:^",
     "fast-check": "catalog:",
     "zod": "catalog:"
   }

packages/zod-test/src/exports.ts

@@ -1,14 +1,11 @@
-export * from './version.js'
+export { VERSION } from './version.js'
 
 export type GeneratorOptions = import('./generator-options.js').Options<import('./generator.js').SeedMap>
-
 export type Seed<T = unknown> = import('./generator-seed.js').Seed<T>
 export * as Seed from './generator-seed.js'
 
-export type {
-  Config
-} from './generator-options.js'
-
+export { fuzz } from './fuzz.js'
+export type { Config } from './generator-options.js'
 export {
   SchemaGenerator,
   SeedGenerator,