Migrate io-ts to Effect Schema

Quick Start

Convert your io-ts codecs to Effect Schema:

npx schemashift-cli migrate ./src --from io-ts --to effect

Before & After

// schemas/config.ts
import * as t from 'io-ts';
import { pipe } from 'fp-ts/function';
import { fold } from 'fp-ts/Either';

const DatabaseConfig = t.type({
  host: t.string,
  port: t.number,
  database: t.string,
  ssl: t.boolean,
});

const AppConfig = t.type({
  db: DatabaseConfig,
  env: t.union([
    t.literal('development'),
    t.literal('staging'),
    t.literal('production'),
  ]),
  features: t.array(t.string),
  limits: t.partial({
    maxConnections: t.number,
    timeout: t.number,
  }),
});

type AppConfig = t.TypeOf<typeof AppConfig>;

const ServerConfig = t.intersection([
  AppConfig,
  t.type({ port: t.number }),
]);

// Decoding
const parseConfig = (raw: unknown): AppConfig =>
  pipe(
    AppConfig.decode(raw),
    fold(
      (errors) => { throw new Error(String(errors)); },
      (config) => config
    )
  );

// schemas/config.ts
import * as S from '@effect/schema/Schema';
import { pipe } from 'effect/Function';

const DatabaseConfig = S.Struct({
  host: S.String,
  port: S.Number,
  database: S.String,
  ssl: S.Boolean,
});

const AppConfig = S.Struct({
  db: DatabaseConfig,
  env: S.Union(
    S.Literal('development'),
    S.Literal('staging'),
    S.Literal('production'),
  ),
  features: S.Array(S.String),
  limits: S.partial(S.Struct({
    maxConnections: S.Number,
    timeout: S.Number,
  })),
});

type AppConfig = S.Schema.Type<typeof AppConfig>;

const ServerConfig = pipe(
  AppConfig,
  S.extend(S.Struct({ port: S.Number })),
);

// Decoding
const parseConfig = (raw: unknown): AppConfig =>
  S.decodeUnknownSync(AppConfig)(raw);

Conversion Reference

Edge Cases & Gotchas

• decode/encode changes: io-ts uses codec.decode(input) returning Either. Effect Schema uses S.decodeUnknownSync(schema)(input) which throws on failure, or S.decodeUnknownEither(schema)(input) for Either-style. Unlike Zod, Effect Schema preserves bidirectional encoding via S.encodeSync().
• Branded types: io-ts t.brand() maps to Effect Schema's S.brand(). The API is similar: pipe(S.Number, S.brand('Positive'), S.filter(n => n > 0)). Effect Schema brands are type-level and compose well with the pipe pattern.
• Recursive types use S.suspend(): io-ts t.recursion('name', () => codec) becomes S.Struct({ children: S.Array(S.suspend(() => TreeSchema)) }). You must provide explicit type annotations for recursive schemas in both libraries.
• Union uses spread, not array: io-ts t.union([A, B, C]) passes an array. Effect Schema uses spread arguments: S.Union(A, B, C). Forgetting to remove the array brackets is a common migration error.
• Effect ecosystem integration: Effect Schema is part of the larger Effect ecosystem. After migration, you can leverage Effect.runPromise, Layer, and other Effect primitives for error handling and dependency injection. This is a benefit if you plan to adopt Effect more broadly.
• fp-ts pipe → effect/Function pipe: The pipe function works identically but comes from a different package. Replace import { pipe } from 'fp-ts/function' with import { pipe } from 'effect/Function'. SchemaShift handles this automatically.

Automated Migration with SchemaShift

# Preview changes with dry run
npx schemashift-cli migrate ./src --from io-ts --to effect --dry-run

# Run the migration
npx schemashift-cli migrate ./src --from io-ts --to effect

# With verbose output and report
npx schemashift-cli migrate ./src --from io-ts --to effect --verbose --report html

# Analyze behavioral differences first
npx schemashift-cli analyze ./src --behavioral io-ts:effect

Manual Migration Checklist

• Replace import * as t from 'io-ts' with import * as S from '@effect/schema/Schema'
• Replace import { pipe } from 'fp-ts/function' with import { pipe } from 'effect/Function'
• Convert t.type({}) to S.Struct({})
• Convert primitives: t.string → S.String, t.number → S.Number
• Convert t.array(X) to S.Array(X)
• Convert t.union([A, B]) to S.Union(A, B) (spread, not array)
• Convert t.intersection([A, B]) to pipe(A, S.extend(B))
• Replace t.TypeOf<typeof X> with S.Schema.Type<typeof X>
• Convert codec.decode(input) to S.decodeUnknownSync(schema)(input)
• Convert codec.encode(value) to S.encodeSync(schema)(value)
• Replace t.recursion() with S.suspend()
• Convert t.brand() to S.brand()
• Remove unused fp-ts imports (Either, fold)
• Update package.json: add @effect/schema and effect, remove io-ts and fp-ts (if unused)
• Run npx tsc --noEmit to verify type safety

Frequently Asked Questions

Related Guides