API reference › @evolu/common › Type › json

function json<T, Name>(
  type: T,
  name: Name,
): [
  BrandType<
    Type<"String", string, string, StringError, string, StringError>,
    Name,
    JsonError | InferErrors<T>,
    StringError
  >,
  (value: InferType<T>) => string & Brand<Name>,
  (value: string & Brand<Name>) => InferType<T>,
];

Defined in: packages/common/src/Type.ts:4304

Creates a branded JSON string Type and type-safe conversion functions for a given Type.

This factory creates:

  1. A branded string Type that validates JSON parsing and structural conformity
  2. A serialization function (Type → branded JSON string)
  3. A parsing function (branded JSON string → Type, skipping validation)

Optimized for Evolu's SQLite workflow where we store typed JSON strings and need type-safe conversions without double parsing.

Example

const Person = object({
  name: NonEmptyString100,
  age: FiniteNumber,
});
interface Person extends InferType<typeof Person> {}

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

// Usage:
const person: Person = { name: "Alice", age: 30 };
const jsonString = personToPersonJson(person); // PersonJson
const backToPerson = personJsonToPerson(jsonString); // Person
Markdown for LLMs