Type

// Validate unknown values
const value: unknown = "hello";
const stringResult = String.fromUnknown(value);
if (!stringResult.ok) {
  // console.error(formatStringError(stringResult.error));
  return stringResult; // inside a function returning Result<string, _>
}
// Safe branch: value is now string
const upper = stringResult.value.toUpperCase();

// Type guard style
if (String.is(value)) {
  // narrowed to string
}

// Composing: arrays & objects
const Numbers = array(Number); // ReadonlyArray<number>
const Point = object({ x: Number, y: Number });

Numbers.from([1, 2, 3]); // ok
Point.from({ x: 1, y: 2 }); // ok
Point.from({ x: 1, y: "2" }); // err -> nested Number error

const CurrencyCode = brand("CurrencyCode", String, (value) =>
  /^[A-Z]{3}$/.test(value)
    ? ok(value)
    : err<CurrencyCodeError>({ type: "CurrencyCode", value }),
);
type CurrencyCode = typeof CurrencyCode.Type; // string & Brand<"CurrencyCode">

interface CurrencyCodeError extends TypeError<"CurrencyCode"> {}

const formatCurrencyCodeError = createTypeErrorFormatter<CurrencyCodeError>(
  (error) => `Invalid currency code: ${error.value}`,
);

const r = CurrencyCode.from("USD"); // ok("USD")
const e = CurrencyCode.from("usd"); // err(...)

const User = object({
  name: NonEmptyTrimmedString100,
  age: optional(PositiveInt),
});
type User = typeof User.Type;

User.from({ name: "Alice" }); // ok
User.from({ name: "Alice", age: -1 }); // err(PositiveInt)

const Person = object({
  name: NonEmptyString50,
  // Did you know that JSON.stringify converts NaN (a number) into null?
  // To prevent this, use FiniteNumber.
  age: FiniteNumber,
});
type Person = typeof Person.Type;

const [PersonJson, personToPersonJson, personJsonToPerson] = json(
  Person,
  "PersonJson",
);
// string & Brand<"PersonJson">
type PersonJson = typeof PersonJson.Type;

const person = Person.orThrow({
  name: "Alice",
  age: 30,
});

const personJson = personToPersonJson(person);
expect(personJsonToPerson(personJson)).toEqual(person);

const r = String.fromUnknown(42);
if (!r.ok) console.error(formatStringError(r.error));

// Override only what we care about; fall back to built-ins for the rest.
const formatTypeError = createFormatTypeError((error) => {
  if (error.type === "MinLength") return `Min length is ${error.min}`;
});

const User = object({ name: NonEmptyTrimmedString100 });
const resultUser = User.from({ name: "" });
if (!resultUser.ok) console.error(formatTypeError(resultUser.error));

const badPoint = object({ x: Number, y: Number }).from({
  x: 1,
  y: "foo",
});
if (!badPoint.ok) console.error(formatTypeError(badPoint.error));