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;
}
The expected type of the property
Whether the property is optional. Default: false
Default value if property is not provided
Minimum value for number types
Maximum value for number types
Minimum number of items for array and typed array types
Maximum number of items for array and typed array types
Minimum string length for string types
Maximum string length for string types
Allowed values for the property
Human-readable label for UI rendering
Description of the property
Step increment for number inputs
Format hint for specialized inputs
Regular expression pattern for string validation
Accepted file extensions for asset types
Group name for organizing properties in UI
Schema for array items (when type is ‘array’)
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
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
Schema to validate against. If not provided, props are returned unchanged.
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