#stately

@statelyjs/schema - Stately Schema Runtime

This module provides the schema runtime that powers Stately's form generation and validation. It parses OpenAPI schemas into typed AST nodes and provides utilities for working with entity data.

#Overview

The schema runtime is created from two inputs:

1. OpenAPI document - The raw JSON/object for runtime introspection
2. Generated nodes - Pre-parsed schema nodes from codegen (PARSED_SCHEMAS)

Type safety comes from your generated TypeScript types, while the OpenAPI document enables runtime features like dynamic field rendering.

#Basic Usage

import { createStately } from '@statelyjs/schema';
import { PARSED_SCHEMAS } from './generated/schemas';
import openapiDoc from './openapi.json';

const schema = createStately<MySchemas>(openapiDoc, PARSED_SCHEMAS);

// Access schema nodes
const pipelineSchema = schema.schema.nodes['Pipeline'];

// Validate data
const result = schema.validate({
  data: { name: 'My Pipeline' },
  schema: pipelineSchema,
  path: 'Pipeline',
});

#With Plugins

Schema plugins extend the runtime with additional data, utilities, and validation:

import { corePlugin } from '@statelyjs/stately/core';

const schema = createStately<MySchemas>(openapiDoc, PARSED_SCHEMAS)
  .withPlugin(corePlugin());

// Access plugin utilities
schema.plugins.core.sortEntityProperties(...);

#Interfaces

#CreateStatelyOptions

Defined in: stately.ts:146

Options for creating a Stately schema runtime.

#Type Parameters

#S

S extends StatelySchemas<any, any>

#Properties

#runtimeSchemas?

optional runtimeSchemas: RuntimeSchemaLoader<S>

Defined in: stately.ts:160

Optional loader for code-split runtime schemas.

Provide this when using codegen with entry points to enable lazy loading of schemas that were split out (e.g., recursive schemas).

#Example

const schema = createStately<MySchemas>(openapiDoc, PARSED_SCHEMAS, {
  runtimeSchemas: () => import('./generated/schemas.runtime').then(m => m.RUNTIME_SCHEMAS),
});

#SchemaPluginConfig

Defined in: stately.ts:275

Configuration for creating a schema plugin.

#Type Parameters

#Plugin

Plugin extends AnySchemaPlugin

The plugin type (extends AnySchemaPlugin)

#Properties

#name

name: Plugin["name"]

Defined in: stately.ts:279

Unique plugin name. Must match the name in your DefinePlugin type.

#setup()?

optional setup: (ctx) => SchemaPluginResult<Plugin>

Defined in: stately.ts:296

Setup function called when the plugin is installed.

Receives a context object with access to the runtime. Returns only the parts the plugin is adding - no spreading required.

#Parameters

#ctx

SchemaPluginContext<StatelySchemas<any, any>>

Plugin context with runtime access

#Returns

SchemaPluginResult<Plugin>

The plugin's contributions (data, utils)

#utils?

optional utils: Plugin["utils"]

Defined in: stately.ts:285

Static utility functions provided by this plugin. These are merged into runtime.plugins[name].

#SchemaPluginContext

Defined in: stately.ts:322

Context provided to plugin setup functions.

Gives plugins access to the runtime for reading schema information and computing derived data.

#Type Parameters

#S

S extends StatelySchemas<any, any>

The application's schema type

#Properties

#data

readonly data: S["data"]

Defined in: stately.ts:334

Plugin-contributed data from previously registered plugins

#plugins

readonly plugins: S["utils"]

Defined in: stately.ts:337

Plugin-contributed utilities from previously registered plugins

#schema

readonly schema: object

Defined in: stately.ts:331

The schema document and parsed nodes

#document

document: any

Raw OpenAPI document for runtime introspection

#nodes

nodes: StatelySchemaConfig<S>["nodes"]

Pre-parsed schema nodes from codegen

#Methods

#getRuntime()

getRuntime<T>(): Stately<T>

Defined in: stately.ts:328

Get a typed view of the runtime.

Use this when you need access to runtime properties with proper typing.

#Type Parameters

#T

T extends StatelySchemas<any, any>

#Returns

Stately<T>

#SchemaPluginResult

Defined in: stately.ts:307

The result returned from a plugin setup function.

Plugins only return what they're adding - no need to spread runtime or plugins. The framework handles merging automatically.

#Type Parameters

#Plugin

Plugin extends AnySchemaPlugin

The plugin type (extends AnySchemaPlugin)

#Properties

#data?

optional data: Plugin["data"]

Defined in: stately.ts:309

Runtime data contributed by this plugin

#utils?

optional utils: Plugin["utils"]

Defined in: stately.ts:311

Utility functions provided by this plugin (merged with static utils)

#Stately

Defined in: stately.ts:104

The Stately schema runtime.

Contains the parsed schema nodes, plugin data, and validation utilities. Created via createStately().

#Extended by

• StatelyBuilder

#Type Parameters

#S

S extends StatelySchemas<any, any>

The application's schema type

#Properties

#data

data: S["data"]

Defined in: stately.ts:113

Plugin-contributed data (entity caches, computed values, etc.)

#loadRuntimeSchemas?

optional loadRuntimeSchemas: RuntimeSchemaLoader<S>

Defined in: stately.ts:122

Optional loader for code-split runtime schemas. When provided, RecursiveRef nodes can resolve schemas that were split out during codegen.

#plugins

plugins: S["utils"]

Defined in: stately.ts:115

Plugin-contributed utilities and validation hooks

#schema

schema: object

Defined in: stately.ts:106

The schema document and parsed nodes

#document

document: any

Raw OpenAPI document for runtime introspection

#nodes

nodes: StatelySchemaConfig<S>["nodes"]

Pre-parsed schema nodes from codegen

#validate()

validate: (args) => ValidationResult

Defined in: stately.ts:117

Validate data against a schema node

#Parameters

#args

ValidateArgs<S>

#Returns

ValidationResult

#StatelyBuilder

Defined in: stately.ts:130

Builder interface for chaining plugin additions.

Extends Stately with withPlugin() for fluent plugin composition.

#Extends

• Stately<S>

#Type Parameters

#S

S extends StatelySchemas<any, any>

#Properties

#data

data: S["data"]

Defined in: stately.ts:113

Plugin-contributed data (entity caches, computed values, etc.)

#Inherited from

Stately.data

#loadRuntimeSchemas?

optional loadRuntimeSchemas: RuntimeSchemaLoader<S>

Defined in: stately.ts:122

Optional loader for code-split runtime schemas. When provided, RecursiveRef nodes can resolve schemas that were split out during codegen.

#Inherited from

Stately.loadRuntimeSchemas

#plugins

plugins: S["utils"]

Defined in: stately.ts:115

Plugin-contributed utilities and validation hooks

#Inherited from

Stately.plugins

#schema

schema: object

Defined in: stately.ts:106

The schema document and parsed nodes

#document

document: any

Raw OpenAPI document for runtime introspection

#nodes

nodes: StatelySchemaConfig<S>["nodes"]

Pre-parsed schema nodes from codegen

#Inherited from

Stately.schema

#validate()

validate: (args) => ValidationResult

Defined in: stately.ts:117

Validate data against a schema node

#Parameters

#args

ValidateArgs<S>

#Returns

ValidationResult

#Inherited from

Stately.validate

#Methods

#withPlugin()

withPlugin(plugin): StatelyBuilder<S>

Defined in: stately.ts:140

Add a plugin to the schema runtime.

Plugins can contribute data, utilities, and validation hooks. Returns a new builder for chaining.

#Parameters

#plugin

PluginFactory<S>

The plugin factory function

#Returns

StatelyBuilder<S>

A new builder with the plugin applied

#Type Aliases

#PluginFactory()

PluginFactory<S> = (runtime) => Stately<S>

Defined in: stately.ts:82

Factory function for creating schema plugins.

A plugin factory receives the current runtime and returns an augmented runtime. Plugins can add data to runtime.data, utilities to runtime.plugins, and validation hooks.

#Type Parameters

#S

S extends StatelySchemas<any, any>

The application's schema type

#Parameters

#runtime

Stately<S>

#Returns

Stately<S>

#Example

const myPlugin: PluginFactory<MySchemas> = (runtime) => ({
  ...runtime,
  data: { ...runtime.data, myData: computeMyData(runtime) },
  plugins: { ...runtime.plugins, myPlugin: { utils: myUtils } },
});

#RuntimeSchemaLoader()

RuntimeSchemaLoader<S> = () => Promise<Partial<S["config"]["nodes"]>>

Defined in: stately.ts:92

Loader function for code-split runtime schemas.

When using codegen with entry points, some schemas may be split into a separate bundle for lazy loading. This function loads those schemas on demand.

#Type Parameters

#S

S extends StatelySchemas<any, any>

#Returns

Promise<Partial<S["config"]["nodes"]>>

A promise resolving to the additional schema nodes

#Functions

#createSchemaPlugin()

createSchemaPlugin<Plugin>(config): <S>() => PluginFactory<S>

Defined in: stately.ts:387

Create a schema plugin with ergonomic API.

This helper wraps the low-level plugin pattern with:

• No manual spreading - Return only what you're adding
• Automatic merging - Data and utils are merged automatically
• Single type parameter - Derive everything from your DefinePlugin type

#Example

#Type Parameters

#Plugin

Plugin extends AnySchemaPlugin

The plugin type created with DefinePlugin

#Parameters

#config

SchemaPluginConfig<Plugin>

Plugin configuration

#Returns

A factory function that returns a PluginFactory

<S>(): PluginFactory<S>

#Type Parameters

#S

S extends StatelySchemas<any, any>

#Returns

PluginFactory<S>

#Example

import { createSchemaPlugin, type DefinePlugin } from '@statelyjs/schema';

// Define the plugin type
export type FilesPlugin = DefinePlugin<
  'files',
  FilesNodeMap,
  FilesTypes,
  FilesData,
  FilesUtils
>;

// Create the plugin factory
export const filesPlugin = createSchemaPlugin<FilesPlugin>({
  name: 'files',
  utils: filesUtils,

  setup: (ctx) => {
    // Compute any runtime data
    const data = computeFilesData(ctx.schema);

    // Return only what you're adding - no spreading
    return { data };
  },
});

// Usage
const schema = createStately<MySchemas>(openapiDoc, PARSED_SCHEMAS)
  .withPlugin(filesPlugin());

#createStately()

createStately<S>(openapi, generatedNodes, options?): StatelyBuilder<S>

Defined in: stately.ts:204

Create a Stately schema runtime.

This is the main entry point for creating a schema runtime. The returned builder can be extended with plugins via withPlugin().

#Type Parameters

#S

S extends StatelySchemas<any, any>

Your application's schema type (from Schemas<DefineConfig<...>>)

#Parameters

#openapi

any

The raw OpenAPI document (JSON object)

#generatedNodes

S["config"]["nodes"]

Pre-parsed schema nodes from codegen (PARSED_SCHEMAS)

#options?

CreateStatelyOptions<S>

Optional configuration (runtime schema loader, etc.)

#Returns

StatelyBuilder<S>

A schema builder that can be extended with plugins

#Examples

import { createStately } from '@statelyjs/schema';
import { PARSED_SCHEMAS } from './generated/schemas';
import openapiDoc from './openapi.json';

const schema = createStately<MySchemas>(openapiDoc, PARSED_SCHEMAS);

const schema = createStately<MySchemas>(openapiDoc, PARSED_SCHEMAS)
  .withPlugin(corePlugin())
  .withPlugin(filesPlugin());

const schema = createStately<MySchemas>(openapiDoc, PARSED_SCHEMAS, {
  runtimeSchemas: () => import('./generated/schemas.runtime').then(m => m.RUNTIME_SCHEMAS),
});