@stacksjs/stx
Version:
A performant UI Framework. Powered by Bun.
178 lines • 5.51 kB
TypeScript
/**
* Parse a TypeScript type annotation string into a TSType structure.
*
* @example
* parseTypeAnnotation('string') // { kind: 'primitive', value: 'string' }
* parseTypeAnnotation('string[]') // { kind: 'array', elementType: { kind: 'primitive', value: 'string' } }
* parseTypeAnnotation('{ name: string }') // { kind: 'object', properties: { name: { type: ..., optional: false } } }
*/
export declare function parseTypeAnnotation(typeStr: string): TSType;
/**
* Extract type definitions from a template's @types block.
*
* @example
* ```typescript
* const result = extractTypesFromTemplate(`
* @types
* interface PageContext {
* title: string
* }
* @endtypes
* <h1>{{ title }}</h1>
* `)
* // result.interfaces[0].name === 'PageContext'
* ```
*/
export declare function extractTypesFromTemplate(template: string): TypeExtractionResult;
/**
* Create a type context from extracted types and runtime context.
*/
export declare function createTypeContext(extracted: TypeExtractionResult, runtimeContext?: Record<string, unknown>): TemplateTypeContext;
/**
* Infer a TSType from a runtime value.
*/
export declare function inferTypeFromValue(value: unknown): TSType;
/**
* Type-check an expression against the type context.
*
* @returns The inferred type of the expression, or an error
*/
export declare function typeCheckExpression(expression: string, context: TemplateTypeContext): TSType | TypeCheckError;
/**
* Validate all expressions in a template.
*/
export declare function validateTemplateTypes(template: string, context: TemplateTypeContext): TypeCheckError[];
/**
* Generate TypeScript definition file for a template.
*
* This creates a .d.ts file that provides type information for IDE support.
*/
export declare function generateTypeDefinitions(templatePath: string, extracted: TypeExtractionResult): GeneratedTypes;
/**
* Convert a TSType back to a TypeScript string representation.
*/
export declare function typeToString(type: TSType): string;
/**
* Process @types directive - extracts and removes type definitions.
*/
export declare function processTypesDirective(template: string): {
template: string
types: TypeExtractionResult
};
/**
* Compile-time type check a template.
*
* @returns Array of errors/warnings, empty if valid
*/
export declare function compileTimeTypeCheck(template: string, runtimeContext?: Record<string, unknown>): { errors: TypeCheckError[], warnings: TypeCheckWarning[] };
/** TypeScript type representation */
export declare interface TSType {
kind: 'primitive' | 'array' | 'object' | 'union' | 'intersection' | 'literal' | 'function' | 'generic' | 'reference'
value?: TSPrimitiveType | string
elementType?: TSType
properties?: Record<string, TSTypeProperty>
types?: TSType[]
literalValue?: string | number | boolean
parameters?: TSFunctionParam[]
returnType?: TSType
typeArguments?: TSType[]
optional?: boolean
}
/** Object property with type */
export declare interface TSTypeProperty {
type: TSType
optional: boolean
readonly: boolean
description?: string
}
/** Function parameter */
export declare interface TSFunctionParam {
name: string
type: TSType
optional: boolean
rest: boolean
}
/** Interface definition */
export declare interface TSInterface {
name: string
properties: Record<string, TSTypeProperty>
extends?: string[]
description?: string
}
/** Type alias definition */
export declare interface TSTypeAlias {
name: string
type: TSType
description?: string
}
/** Template type context */
export declare interface TemplateTypeContext {
interfaces: Map<string, TSInterface>
typeAliases: Map<string, TSTypeAlias>
variables: Map<string, TSType>
errors: TypeCheckError[]
warnings: TypeCheckWarning[]
}
/** Type check error */
export declare interface TypeCheckError {
message: string
line?: number
column?: number
expression?: string
expectedType?: string
actualType?: string
}
/** Type check warning */
export declare interface TypeCheckWarning {
message: string
line?: number
column?: number
suggestion?: string
}
/** Type extraction result */
export declare interface TypeExtractionResult {
interfaces: TSInterface[]
typeAliases: TSTypeAlias[]
contextType?: TSInterface
errors: string[]
}
/** Generated type definition file content */
export declare interface GeneratedTypes {
content: string
filename: string
}
/**
* TypeScript-First Templates Module
*
* Provides compile-time type checking and TypeScript support for stx templates.
*
* ## Features
*
* 1. **Type-Safe Context** - Define typed interfaces for template context
* 2. **Compile-Time Checking** - Validate expressions against context types
* 3. **Type Inference** - Infer types from script blocks
* 4. **Type Generation** - Generate TypeScript definitions from templates
* 5. **IDE Support** - Enable autocomplete and type hints in editors
*
* ## Usage
*
* ```html
* <!-- Define context type at top of template -->
* @types
* interface PageContext {
* title: string
* items: Array<{ id: number; name: string }>
* user?: { name: string; role: 'admin' | 'user' }
* }
* @endtypes
*
* <h1>{{ title }}</h1>
* @foreach(items as item)
* <p>{{ item.name }}</p> <!-- Type-checked! -->
* @endforeach
* ```
*
* @module typescript-templates
*/
/** Supported TypeScript primitive types */
export type TSPrimitiveType = 'string' | 'number' | 'boolean' | 'null' | 'undefined' | 'any' | 'unknown' | 'never' | 'void'