gem-hunter

Supazod

Quick Start

$ pnpm add --D supazod
$ supabase gen types typescript --local > types.ts

# Generate schemas with separate types file
$ pnpm supazod -i types.ts -o schemas.ts -t schemas.d.ts -s public,schema_a,schema_b

# Or generate everything in a single file with inline types
$ pnpm supazod -i types.ts -o schemas.ts --inline-types

PowerShell Users (Windows)

# Local database
supabase gen types typescript --local | Out-File -FilePath types.ts -Encoding utf8

# From supabase.com
supabase gen types typescript --project-id <project-id> | Out-File -FilePath types.ts -Encoding utf8

Generated Output

// ✅ Clean naming (v2.0+)
export const publicUsersInsertSchema = z.object({...});
export const publicUsersUpdateSchema = z.object({...});
export const publicUserStatusSchema = z.union([...]);
export const publicGetStatusArgsSchema = z.object({...});

// TypeScript types without "Schema" suffix
export type PublicUsersInsert = z.infer<typeof generated.publicUsersInsertSchema>;
export type PublicUserStatus = z.infer<typeof generated.publicUserStatusSchema>;

Inline Types

$ pnpm supazod -i types.ts -o schemas.ts --inline-types

// schemas.ts - single file output
import { z } from "zod";

export const publicUsersRowSchema = z.object({
  id: z.number(),
  username: z.string(),
  // ...
});

export const publicUserStatusSchema = z.union([
  z.literal("ONLINE"),
  z.literal("OFFLINE"),
]);

// Types are included directly in the same file
export type PublicUsersRow = z.infer<typeof publicUsersRowSchema>;
export type PublicUserStatus = z.infer<typeof publicUserStatusSchema>;

// supazod.config.ts
import { defineConfig } from 'supazod';

export default defineConfig({
  inlineTypes: true,
});

Configuration

TypeScript Configuration (Recommended)

import { defineConfig } from 'supazod';

export default defineConfig({
  namingConfig: {
    // TypeScript provides autocomplete for placeholders:
    // {schema}, {table}, {operation}, {function}, {name}
    tableOperationPattern: '{schema}_{table}_{operation}',
    tableSchemaPattern: '{schema}{table}{operation}',
    enumPattern: '{schema}_{name}_Enum',
    enumSchemaPattern: '{schema}{name}',
    functionArgsPattern: '{schema}_{function}_Args',
    functionArgsSchemaPattern: '{schema}{function}Args',
    functionReturnsPattern: '{schema}_{function}_Returns',
    functionReturnsSchemaPattern: '{schema}{function}Returns',

    // Capitalization and formatting
    capitalizeSchema: true,
    capitalizeNames: true,
    separator: '_',
  }
});

JSON Configuration

{
  "namingConfig": {
    "tableOperationPattern": "{schema}_{table}_{operation}",
    "tableSchemaPattern": "{schema}{table}{operation}",
    "enumPattern": "{schema}_{name}_Enum",
    "enumSchemaPattern": "{schema}{name}",
    "capitalizeSchema": true,
    "capitalizeNames": true,
    "separator": "_"
  }
}

CLI Options

supazod [options]

-i, --input <path>         Input TypeScript file
-o, --output <path>        Output Zod schemas file
-t, --types-output <path>  Output type definitions (optional)
-s, --schema <name>        Schema to process (optional, defaults to all)
-I, --inline-types         Include types in schema file (no separate .d.ts)
-v, --verbose              Enable debug logs

# Naming Configuration (overrides config file)
--table-operation-pattern <pattern>    Pattern for table operations
--table-schema-pattern <pattern>       Pattern for table schema constants
--enum-pattern <pattern>               Pattern for enums  
--enum-schema-pattern <pattern>        Pattern for enum schema constants  
--function-args-pattern <pattern>      Pattern for function arguments
--function-args-schema-pattern <pattern>  Pattern for function arg schema constants
--function-returns-pattern <pattern>   Pattern for function returns
--function-returns-schema-pattern <pattern> Pattern for function return schema constants
--config <path>                        Path to a Supazod config file
--capitalize-schema <boolean>          Capitalize schema names
--capitalize-names <boolean>           Capitalize type names
--separator <string>                   Separator between name parts

Example with Custom Naming

# Generate with custom naming patterns
$ pnpm supazod -i types.ts -o schemas.ts \
  --table-operation-pattern '{schema}_{table}_{operation}' \
  --table-schema-pattern '{schema}{table}{operation}' \
  --enum-pattern '{schema}_{name}_Enum' \
  --enum-schema-pattern '{schema}{name}' \
  --separator '_'

Separating Type and Schema Names

Available Placeholders

Features

MergeDeep Support

Supported Patterns

export type Database = MergeDeep<{ public: { Tables: { ... } } }, { /* overrides */ }>;

type DatabaseGenerated = { public: { Tables: { ... } } };  // same file
export type Database = MergeDeep<DatabaseGenerated, { /* overrides */ }>;

Known Limitations

import type { Database as DatabaseGenerated } from './database.gen';  // different file
export type Database = MergeDeep<DatabaseGenerated, { /* overrides */ }>;
// Error: Unable to extract type literal from MergeDeep first argument: TypeReference

Programmatic API

import { generateContent } from 'supazod';

const result = await generateContent({
  input: './types.ts',
  output: './schema.ts',
  schema: ['public'],
  inlineTypes: true, // Include types in schema file
  namingConfig: {
    tableOperationPattern: '{schema}_{table}_{operation}',
    enumPattern: '{schema}_{name}_Enum',
  }
});

Migration from v1.x

Credits