WithDefault

Use ft.WithDefault to substitute a default value in place of null or undefined when parsing. Unlike ft.Optional, the property is not treated as optional in the static TypeScript type or when serializing - by the time you have a parsed value, the default will already have been applied, so the field is always present.

import * as ft from "funtypes";

const UserCodec = ft.Object({
  id: ft.Number,
  role: ft.WithDefault(ft.String, "member"),
});
// => ft.Codec<{ id: number; role: string }>

type User = ft.Static<typeof UserCodec>;
// => { id: number; role: string }

assert.deepEqual(
  ft.showType(UserCodec),
  "{ id: number; role: string }",
);

// ✅ Missing property falls back to the default
assert.deepEqual(UserCodec.parse({ id: 1 }), {
  id: 1,
  role: "member",
});

// ✅ `null` also falls back to the default
assert.deepEqual(
  UserCodec.parse({ id: 1, role: null }),
  { id: 1, role: "member" },
);

// ✅ Any other value is validated normally
assert.deepEqual(
  UserCodec.parse({ id: 1, role: "admin" }),
  { id: 1, role: "admin" },
);

// 🚨 Invalid: `role` doesn't match the
//    underlying type
assert.throws(() => {
  UserCodec.parse({ id: 1, role: 42 });
});

Optional vs. Default

ft.Optional and ft.WithDefault solve related but different problems:

• ft.Optional(ft.String) means the property may be entirely absent, and if it's absent it's simply left out of the parsed value - the static type has an actual ?: string.
• ft.WithDefault(ft.String, "member") means the property may be absent (or null) on the way in, but it's always present and always a string once parsed.

import * as ft from "funtypes";

const UserCodec = ft.Object({
  nickname: ft.Optional(ft.String),
  role: ft.WithDefault(ft.String, "member"),
});
// => ft.Codec<{ nickname?: string; role: string }>

assert.deepEqual(UserCodec.parse({}), {
  role: "member",
});

import * as ft from "funtypes";

const RoleCodec = ft.WithDefault(
  ft.String,
  "member",
);

assert.deepEqual(RoleCodec.test(undefined), false);
assert.throws(() => RoleCodec.serialize(undefined as any));

Introspection

You can inspect the default value and underlying Codec via Codec.introspection:

import * as ft from "funtypes";

const RoleCodec = ft.WithDefault(
  ft.String,
  "member",
);

assert.deepEqual(RoleCodec.introspection, {
  tag: "default",
  underlying: ft.String,
  defaultValue: "member",
});