npm package: @schemashift/zod-superstruct
Description: Zod ↔ Superstruct transformer for SchemaShift
Author: Joseph May
Latest version: 0.14.0

# @schemashift/zod-superstruct

Zod ↔ Superstruct transformer for SchemaShift. Supports both forward (Zod → Superstruct) and backward (Superstruct → Zod) migrations.

[![npm version](https://img.shields.io/npm/v/@schemashift/zod-superstruct.svg)](https://www.npmjs.com/package/@schemashift/zod-superstruct)
[![npm downloads](https://img.shields.io/npm/dm/@schemashift/zod-superstruct.svg)](https://www.npmjs.com/package/@schemashift/zod-superstruct)
[![CI](https://github.com/jdmay2/schemashift/actions/workflows/ci.yml/badge.svg)](https://github.com/jdmay2/schemashift/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

**Tier:** Pro+

## Installation

```bash
npm install @schemashift/zod-superstruct
```

## Usage

```typescript
import { createZodToSuperstructHandler, createSuperstructToZodHandler } from '@schemashift/zod-superstruct';
import { TransformEngine } from '@schemashift/core';

const engine = new TransformEngine();
engine.registerHandler('zod', 'superstruct', createZodToSuperstructHandler());
engine.registerHandler('superstruct', 'zod', createSuperstructToZodHandler()); // Backward migration (Pro+)
```

## API Paradigm Difference

Zod uses a **namespaced chain** API:

```typescript
z.object({ name: z.string().email(), age: z.number().int() })
```

Superstruct uses **bare function** imports:

```typescript
object({ name: refine(string(), "email", ...), age: integer() })
```

## Transformation Mappings

### Imports

| Zod | Superstruct |
|-----|-------------|
| `import { z } from 'zod'` | `import { object, string, ... } from 'superstruct'` |

### Factory Methods

| Zod | Superstruct |
|-----|-------------|
| `z.string()` | `string()` |
| `z.number()` | `number()` |
| `z.boolean()` | `boolean()` |
| `z.date()` | `date()` |
| `z.bigint()` | `bigint()` |
| `z.any()` | `any()` |
| `z.unknown()` | `unknown()` |
| `z.never()` | `never()` |
| `z.object({...})` | `object({...})` |
| `z.array(s)` | `array(s)` |
| `z.enum(["a", "b"])` | `enums(["a", "b"])` |
| `z.literal(42)` | `literal(42)` |
| `z.union([a, b])` | `union([a, b])` |
| `z.record(k, v)` | `record(k, v)` |
| `z.tuple([a, b])` | `tuple([a, b])` |
| `z.number().int()` | `integer()` |

### Modifiers

| Zod | Superstruct |
|-----|-------------|
| `.optional()` | `optional(X)` |
| `.nullable()` | `nullable(X)` |

### Type Helpers

| Zod | Superstruct |
|-----|-------------|
| `z.infer<typeof s>` | `Infer<typeof s>` |

## Patterns Requiring Manual Review

### `.discriminatedUnion()`

Superstruct has no discriminatedUnion. Use `union()` with explicit struct variants.

### `.transform()` / `.preprocess()`

Superstruct uses `coerce()` for transforms:

```typescript
// Zod
z.string().transform((s) => s.toUpperCase());

// Superstruct
coerce(string(), string(), (s) => s.toUpperCase());
```

### `define()` (Custom Validators)

```typescript
// Superstruct
const Email = define('email', (v) => typeof v === 'string' && v.includes('@'));

// Zod
const Email = z.string().refine((v) => v.includes('@'));
```

### `.brand()`

Superstruct has no `.brand()` equivalent. Use `define()` with a branded type.

## Related Packages

- [schemashift-cli](https://www.npmjs.com/package/schemashift-cli) — CLI tool for running migrations
- [@schemashift/core](https://www.npmjs.com/package/@schemashift/core) — Core analysis engine
- [@schemashift/zod-valibot](https://www.npmjs.com/package/@schemashift/zod-valibot) — Zod ↔ Valibot transformer

## License

MIT