Schema

Schema validation utilities for component props in Helios

PropType

Supported property types for schema validation.

type PropType =
  | 'string'
  | 'number'
  | 'boolean'
  | 'object'
  | 'array'
  | 'color'
  | 'image'
  | 'video'
  | 'audio'
  | 'font'
  | 'model'
  | 'json'
  | 'shader'
  | 'int8array'
  | 'uint8array'
  | 'uint8clampedarray'
  | 'int16array'
  | 'uint16array'
  | 'int32array'
  | 'uint32array'
  | 'float32array'
  | 'float64array';

PropDefinition

Defines the schema for a single property.

interface PropDefinition {
  type: PropType;
  optional?: boolean;
  default?: any;
  minimum?: number;
  maximum?: number;
  minItems?: number;
  maxItems?: number;
  minLength?: number;
  maxLength?: number;
  enum?: (string | number)[];
  label?: string;
  description?: string;
  step?: number;
  format?: string;
  pattern?: string;
  accept?: string[];
  group?: string;
  items?: PropDefinition;
  properties?: HeliosSchema;
}

type · PropType · required

The expected type of the property

optional · boolean

Whether the property is optional. Default: false

default · any

Default value if property is not provided

minimum · number

Minimum value for number types

maximum · number

Maximum value for number types

minItems · number

Minimum number of items for array and typed array types

maxItems · number

Maximum number of items for array and typed array types

minLength · number

Minimum string length for string types

maxLength · number

Maximum string length for string types

enum · (string | number)[]

Allowed values for the property

label · string

Human-readable label for UI rendering

description · string

Description of the property

step · number

Step increment for number inputs

format · string

Format hint for specialized inputs

pattern · string

Regular expression pattern for string validation

accept · string[]

Accepted file extensions for asset types

group · string

Group name for organizing properties in UI

items · PropDefinition

Schema for array items (when type is ‘array’)

properties · HeliosSchema

Nested schema for object properties (when type is ‘object’)

HeliosSchema

A schema is a record mapping property names to their definitions.

type HeliosSchema = Record<string, PropDefinition>;

validateSchema

Validates that a schema definition is well-formed.

function validateSchema(schema: HeliosSchema | undefined, parentKey?: string): void

schema · HeliosSchema | undefined · required

Schema to validate

parentKey · string

Parent key for nested validation (used internally for error messages)

Example

import { validateSchema } from '@helios-project/core';

const schema = {
  title: {
    type: 'string',
    minLength: 1,
    maxLength: 100,
    default: 'Untitled'
  },
  color: {
    type: 'color',
    default: '#ff0000'
  },
  count: {
    type: 'number',
    minimum: 0,
    maximum: 100
  }
};

// Validates successfully
validateSchema(schema);

// Invalid schema - pattern on non-string
const invalid = {
  count: {
    type: 'number',
    pattern: '^\\d+$' // Error! pattern only valid for strings
  }
};

validateSchema(invalid); // Throws HeliosError

Errors

Throws HeliosError with code INVALID_SCHEMA if:

• Pattern is defined on non-string types
• Pattern regex is invalid
• Accept is defined on incompatible types
• minItems/maxItems is negative or inconsistent
• minLength/maxLength is negative or inconsistent
• Default value doesn’t match the schema constraints

validateProps

Validates component props against a schema.

function validateProps<T = Record<string, any>>(props: T, schema?: HeliosSchema): T

props · T · required

Props object to validate

schema · HeliosSchema

Schema to validate against. If not provided, props are returned unchanged.

return · T

Validated props object with defaults applied and extra props preserved

Example

import { validateProps } from '@helios-project/core';

const schema = {
  title: {
    type: 'string',
    minLength: 1,
    default: 'Untitled'
  },
  color: {
    type: 'color'
  },
  count: {
    type: 'number',
    minimum: 0,
    maximum: 100,
    optional: true
  }
};

// Valid props
const props = validateProps(
  { color: '#ff0000' },
  schema
);
console.log(props);
// { title: 'Untitled', color: '#ff0000' }

// Missing required prop
validateProps({}, schema);
// Throws HeliosError: Missing required prop: color

// Invalid type
validateProps({ color: 123 }, schema);
// Throws HeliosError: Invalid type for prop 'color'

// Out of range
validateProps({ color: '#ff0000', count: 150 }, schema);
// Throws HeliosError: Prop 'count' must be <= 100

// Nested object validation
const nestedSchema = {
  user: {
    type: 'object',
    properties: {
      name: { type: 'string' },
      age: { type: 'number', minimum: 0 }
    }
  }
};

const nested = validateProps(
  { user: { name: 'Alice', age: 30 } },
  nestedSchema
);

// Array validation
const arraySchema = {
  tags: {
    type: 'array',
    items: { type: 'string' },
    minItems: 1,
    maxItems: 5
  }
};

const withArray = validateProps(
  { tags: ['video', 'animation'] },
  arraySchema
);

Behavior

• Required props: Props without optional: true must be provided or have a default
• Defaults: Applied when prop is undefined
• Extra props: Props not in schema are preserved in the output
• Nested validation: Objects and arrays are validated recursively
• Type coercion: No automatic coercion; types must match exactly

Errors

Throws HeliosError with code INVALID_INPUT_PROPS if:

• Required prop is missing and has no default
• Prop type doesn’t match schema
• Number is outside minimum/maximum range
• String length is outside minLength/maxLength range
• Array length is outside minItems/maxItems range
• String doesn’t match pattern
• Value is not in enum
• Color string is invalid
• File extension doesn’t match accept list