@livon/schema

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:

• Schema APIs overview
• Schema Type Safety
• Schema Context
• string
• number
• boolean
• date
• enumeration
• object
• array
• tuple
• literal
• union
• or
• binary
• before
• after
• and
• api
• operation
• subscription
• fieldResolver
• schemaFactory
• typeGuards

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:

• api
• operation
• subscription
• fieldResolver

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.

Related pages

• Validated by Default
• parse vs typed
• Schema APIs overview
• Runtime Design
• Architecture