Skip to Content
📖 Guide DocumentsRandom Generator

typia.random — make up a value that satisfies the type

signatures
function random<T>(generator?: Partial<IRandomGenerator>): Resolved<T>;
function createRandom<T>(): (generator?: Partial<IRandomGenerator>) => Resolved<T>;

typia.random<T> returns a value that satisfies T. Use it for test fixtures, seeding databases, or building demos without writing factory functions by hand.

It honors every type tag you put on the type: tags.Format<"email"> will produce an email, tags.Minimum<0> & tags.Maximum<100> will pick a number in that range, tags.MaxLength<8> will cap a string’s length.

First example

hello-random.ts
import typia, { tags } from "typia";
 
interface User {
  id: string & tags.Format<"uuid">;
  email: string & tags.Format<"email">;
  age: number & tags.Type<"uint32"> & tags.Minimum<19> & tags.Maximum<99>;
  hobbies: string[];
}
 
const user = typia.random<User>();
// e.g.
// {
//   id: "b6e0…",
//   email: "abc@example.com",
//   age: 47,
//   hobbies: ["wzPwLvO", "u_a-mqQ"],
// }
examples/src/random/random.ts
import typia, { tags } from "typia";
 
const member: IMember = typia.random<IMember>();
console.log(member);
 
interface IMember {
  id: string & tags.Format<"uuid">;
  email: string & tags.Format<"email">;
  age: number &
    tags.Type<"uint32"> &
    tags.ExclusiveMinimum<19> &
    tags.Maximum<100>;
}

undefined

export function random<T>(g?: Partial<IRandomGenerator>): Resolved<T>;

Reusable factory

const randomUser = typia.createRandom<User>();
 
const a = randomUser();
const b = randomUser({ /* custom generator overrides */ });
export function createRandom<T>(): (g?: Partial<IRandomGenerator>) => Resolved<T>;

Tags in action

The constraints you’d normally use for runtime validation also pin down what random produces. Type tags and comment tags compile to the same code, so either style works:

examples/src/random/random-tag.ts
import typia, { tags } from "typia";
 
const data: TypeTag = typia.random<TypeTag>();
console.log(data);
 
interface TypeTag {
  type: number & tags.Type<"int32">;
  number?: number & tags.ExclusiveMinimum<19> & tags.Maximum<100>;
  string: string & tags.MinLength<3>;
  pattern: string & tags.Pattern<"^[a-z]+$">;
  format: (string & tags.Format<"date-time">) | null;
}

For long-running test suites and especially anything that goes into a real database, prefer type tags — typos in comment tags fall back to defaults silently. See Special Tags for the trade-off.

Custom tags — custom generators

Defining a custom type tag for validation also gives you a hook for random generation. When you write validate on the tag, typia uses it for assert/is/validate — and uses the tag’s kind to look up a generator on the runtime IRandomGenerator.

examples/src/random/random-custom.ts
import typia from "typia";
import { _randomNumber } from "typia/lib/internal/_randomNumber";
import { _randomString } from "typia/lib/internal/_randomString";
 
const data: TagCustom = typia.random<TagCustom>({
  string: (schema) => {
    if ((schema as any)["x-typia-monetary"] === "dollar")
      return "$" + Math.floor(Math.random() * 1_000);
    else if ((schema as any)["x-typia-postfix"] !== undefined)
      return _randomString(schema) + (schema as any)["x-typia-postfix"];
    return _randomString(schema);
  },
  number: (schema) => {
    if ((schema as any)["x-typia-powerOf"] !== undefined) {
      const powerOf = (schema as any)["x-typia-powerOf"];
      return Math.pow(powerOf, Math.floor(Math.random() * 10) + 1);
    }
    return _randomNumber(schema);
  },
});
console.log(data);
 
interface TagCustom {
  id: string & typia.tags.Format<"uuid">;
  dollar: string & Dollar;
  postfix: string & Postfix<"abcd">;
  powerOf: number & PowerOf<2>;
}
 
type Dollar = typia.tags.TagBase<{
  kind: "monetary";
  target: "string";
  value: "dollar";
  validate: `$input[0] === "$" && !isNaN(Number($input.substring(1).split(",").join("")))`;
  schema: {
    "x-typia-monetary": "dollar";
  };
}>;
 
type Postfix<Value extends string> = typia.tags.TagBase<{
  kind: "postfix";
  target: "string";
  value: Value;
  validate: `$input.endsWith("${Value}")`;
  schema: {
    "x-typia-postfix": Value;
  };
}>;
 
type PowerOf<Value extends number> = typia.tags.TagBase<{
  kind: "powerOf";
  target: "number";
  value: Value;
  validate: `(() => {
    const denominator: number = Math.log(${Value});
    const value: number = Math.log($input) / denominator;
    return Math.abs(value - Math.round(value)) < 0.00000001;
  })()`;
  schema: {
    "x-typia-powerOf": Value;
  };
}>;

A custom tag without a validate is fine for documentation purposes, but if you want random to actually produce values that satisfy it, define the validation logic. The same validate then doubles as the check used by typia.assert<T>.

Where to go next

Last updated on
decode() functionsMiscellaneous