io-ts codec decode and encode: working versions (tested 2026-10-16)

{
  "name": "io-ts-codec-decode",
  "private": true,
  "type": "module",
  "scripts": {
    "test": "node --import tsx --test test/*.test.ts"
  },
  "dependencies": {
    "io-ts": "2.2.22",
    "fp-ts": "2.16.11"
  },
  "devDependencies": {
    "@types/node": "26.6.5",
    "tsx": "4.23.15"
  }
}

import * as t from "io-ts";
import { PathReporter } from "io-ts/PathReporter";
import type { Either } from "fp-ts/Either";

export interface PositiveIntBrand {
  readonly PositiveInt: unique symbol;
}

export const PositiveInt = t.brand(
  t.number,
  (n): n is t.Branded<number, PositiveIntBrand> =>
    Number.isInteger(n) && n > 0,
  "PositiveInt"
);

export type PositiveInt = t.BrandC<typeof t.number, PositiveIntBrand>;

export const Role = t.union([t.literal("admin"), t.literal("user")]);
export type Role = t.TypeOf<typeof Role>;

export const User = t.type({
  id: t.string,
  name: t.string,
  role: Role,
  tags: t.array(t.string),
  meta: t.partial({
    age: PositiveInt,
    nickname: t.string,
  }),
});

export type User = t.TypeOf<typeof User>;

export function decodeUser(input: unknown): Either<t.Errors, User> {
  return User.decode(input);
}

export function encodeUser(user: User): unknown {
  return User.encode(user);
}

export function explain(input: unknown): string[] {
  return PathReporter.report(User.decode(input));
}

import { test } from "node:test";
import assert from "node:assert/strict";
import { isLeft, isRight } from "fp-ts/Either";
import { decodeUser, encodeUser, explain, type User } from "../src/codec.ts";

const valid: User = {
  id: "u1",
  name: "Ada",
  role: "admin",
  tags: ["beta", "early"],
  meta: { age: 36 },
};

test("decodes valid unknown input", () => {
  const result = decodeUser(valid);
  assert.ok(isRight(result));
  if (isRight(result)) {
    assert.deepEqual(result.right, valid);
  }
});

test("treats partial fields as optional", () => {
  const result = decodeUser({ ...valid, meta: {} });
  assert.ok(isRight(result));
  if (isRight(result)) {
    assert.deepEqual(result.right.meta, {});
  }
});

test("rejects an unknown union member and reports the path", () => {
  const bad = { ...valid, role: "owner" };
  const result = decodeUser(bad);
  assert.ok(isLeft(result));
  assert.match(explain(bad).join("\n"), /role/);
});

test("rejects a non-positive branded age", () => {
  const bad = { ...valid, meta: { age: -1 } };
  const result = decodeUser(bad);
  assert.ok(isLeft(result));
  assert.match(explain(bad).join("\n"), /PositiveInt/);
});

test("rejects wrong element type inside an array", () => {
  const bad = { ...valid, tags: ["ok", 2] };
  const result = decodeUser(bad);
  assert.ok(isLeft(result));
  assert.match(explain(bad).join("\n"), /tags/);
});

test("encodes a valid value back to plain json", () => {
  assert.deepEqual(encodeUser(valid), valid);
});