Skip to main content

@livon/schema

npm Package Size Security Scorecard CI

Install​

pnpm add @livon/schema

Purpose​

@livon/schema defines:

  • value schemas (string, number, object, array, or, union, ...)
  • operation schemas
  • subscription schemas
  • schema module (schemaModule)

Best for​

Use this package when you want a single schema source for validation, typing, and generated client APIs.

Schema API docs​

Each schema/combinator has its own usage page:

Type safety model​

LIVON schemas are both runtime validators and type sources. Primitive schema names are optional, so string() and number() are valid defaults.

  1. Define payload shape once in schema.
  2. Validate unknown input with parse().
  3. Reuse schema entrypoint with typed().
  4. Derive types with Infer instead of hand-written payload interfaces.
import {object, string, number, type Infer} from '@livon/schema';

const User = object({
  name: 'User',
  shape: {
    id: string(),
    age: number().int().min(0),
  },
});

type UserType = Infer<typeof User>;

const input: unknown = JSON.parse(raw);
const parsed = User.parse(input);
const typedInput: UserType = {id: 'u-1', age: 21};
const typed = User.typed(typedInput);

Parameters in this example​

object({...}):

  • name (string): schema node name.
  • shape (Record<string, Schema>): field schema map.

number().int().min(0):

  • min (number): minimum allowed numeric value.

User.parse(input):

  • input (unknown): runtime value to validate/parse.

User.typed(typedInput):

  • typedInput (UserType): pretyped value using same schema entrypoint.

Compose API schema​

import {api} from '@livon/schema';

const ApiSchema = api({
  type: User,
  operations: {
    sendMessage,
  },
  subscriptions: {
    onMessage,
  },
  fieldOperations: {
    greeting: userGreetingResolver,
  },
});

export const serverSchema = ApiSchema;

Use the api(...) (or composeApi(...)) result directly in schemaModule(...). No additional schema-module input factory is required.

Parameters in this example​

api({...}):

  • type (Schema, optional): entity schema for field operations.
  • operations (Record<string, Operation>, optional): request/response operations.
  • subscriptions (Record<string, Subscription | Schema>, optional): publish topic schemas.
  • fieldOperations (Record<string, FieldOperation>, optional): field-level resolvers.

For focused usage patterns:

Mount schema module into runtime​

import {runtime} from '@livon/runtime';
import {schemaModule} from '@livon/schema';

runtime(schemaModule(serverSchema, {explain: true}));

Parameters in this example​

schemaModule(serverSchema, options?):

  • serverSchema (Api | ComposedApi): fully composed schema from api(...) or composeApi(...).
  • options.explain (boolean, optional): enables $explain endpoint for AST/checksum metadata.

Explain endpoint​

If explain: true, schema module responds to $explain with AST/checksum metadata.