@constela/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,750 @@
+/**
+ * AST Type Definitions for Constela UI Framework
+ *
+ * This module defines the complete Abstract Syntax Tree (AST) types
+ * for representing Constela UI applications.
+ */
+declare const BINARY_OPERATORS: readonly ["+", "-", "*", "/", "==", "!=", "<", "<=", ">", ">=", "&&", "||"];
+type BinaryOperator = (typeof BINARY_OPERATORS)[number];
+declare const UPDATE_OPERATIONS: readonly ["increment", "decrement", "push", "pop", "remove"];
+type UpdateOperation = (typeof UPDATE_OPERATIONS)[number];
+declare const HTTP_METHODS: readonly ["GET", "POST", "PUT", "DELETE"];
+type HttpMethod = (typeof HTTP_METHODS)[number];
+/**
+ * Literal expression - represents a constant value
+ */
+interface LitExpr {
+    expr: 'lit';
+    value: string | number | boolean | null | unknown[];
+}
+/**
+ * State expression - references a state field
+ */
+interface StateExpr {
+    expr: 'state';
+    name: string;
+}
+/**
+ * Variable expression - references a loop variable or event data
+ */
+interface VarExpr {
+    expr: 'var';
+    name: string;
+    path?: string;
+}
+/**
+ * Binary expression - arithmetic, comparison, or logical operation
+ */
+interface BinExpr {
+    expr: 'bin';
+    op: BinaryOperator;
+    left: Expression;
+    right: Expression;
+}
+/**
+ * Not expression - logical negation
+ */
+interface NotExpr {
+    expr: 'not';
+    operand: Expression;
+}
+type Expression = LitExpr | StateExpr | VarExpr | BinExpr | NotExpr;
+/**
+ * Number state field
+ */
+interface NumberField {
+    type: 'number';
+    initial: number;
+}
+/**
+ * String state field
+ */
+interface StringField {
+    type: 'string';
+    initial: string;
+}
+/**
+ * List state field
+ */
+interface ListField {
+    type: 'list';
+    initial: unknown[];
+}
+type StateField = NumberField | StringField | ListField;
+/**
+ * Set step - sets a state field to a new value
+ */
+interface SetStep {
+    do: 'set';
+    target: string;
+    value: Expression;
+}
+/**
+ * Update step - performs an operation on a state field
+ */
+interface UpdateStep {
+    do: 'update';
+    target: string;
+    operation: UpdateOperation;
+    value?: Expression;
+}
+/**
+ * Fetch step - makes an HTTP request
+ */
+interface FetchStep {
+    do: 'fetch';
+    url: Expression;
+    method?: HttpMethod;
+    body?: Expression;
+    result?: string;
+    onSuccess?: ActionStep[];
+    onError?: ActionStep[];
+}
+type ActionStep = SetStep | UpdateStep | FetchStep;
+/**
+ * Event handler - binds an event to an action
+ */
+interface EventHandler {
+    event: string;
+    action: string;
+    payload?: Expression;
+}
+/**
+ * Action definition - a named sequence of steps
+ */
+interface ActionDefinition {
+    name: string;
+    steps: ActionStep[];
+}
+/**
+ * Element node - represents an HTML element
+ */
+interface ElementNode {
+    kind: 'element';
+    tag: string;
+    props?: Record<string, Expression | EventHandler>;
+    children?: ViewNode[];
+}
+/**
+ * Text node - represents text content
+ */
+interface TextNode {
+    kind: 'text';
+    value: Expression;
+}
+/**
+ * If node - conditional rendering
+ */
+interface IfNode {
+    kind: 'if';
+    condition: Expression;
+    then: ViewNode;
+    else?: ViewNode;
+}
+/**
+ * Each node - list rendering
+ */
+interface EachNode {
+    kind: 'each';
+    items: Expression;
+    as: string;
+    index?: string;
+    key?: Expression;
+    body: ViewNode;
+}
+type ViewNode = ElementNode | TextNode | IfNode | EachNode;
+/**
+ * Program - the root of a Constela AST
+ */
+interface Program {
+    version: '1.0';
+    state: Record<string, StateField>;
+    actions: ActionDefinition[];
+    view: ViewNode;
+}
+type ConstelaAst = Program;
+
+/**
+ * Type Guards for Constela AST Types
+ *
+ * This module provides runtime type checking functions for all AST types.
+ */
+
+/**
+ * Checks if value is a literal expression
+ */
+declare function isLitExpr(value: unknown): value is LitExpr;
+/**
+ * Checks if value is a state expression
+ */
+declare function isStateExpr(value: unknown): value is StateExpr;
+/**
+ * Checks if value is a variable expression
+ */
+declare function isVarExpr(value: unknown): value is VarExpr;
+/**
+ * Checks if value is a binary expression
+ *
+ * Note: This performs shallow validation only - it checks that `left` and `right`
+ * are objects but does not recursively validate they are valid Expressions.
+ * This is intentional for performance: deep validation would require traversing
+ * potentially deeply nested expression trees on every type guard call.
+ * Use the AST validator for full recursive validation instead.
+ */
+declare function isBinExpr(value: unknown): value is BinExpr;
+/**
+ * Checks if value is a not expression
+ *
+ * Note: This performs shallow validation only - it checks that `operand` is
+ * an object but does not recursively validate it is a valid Expression.
+ * This is intentional for performance: deep validation would require traversing
+ * potentially deeply nested expression trees on every type guard call.
+ * Use the AST validator for full recursive validation instead.
+ */
+declare function isNotExpr(value: unknown): value is NotExpr;
+/**
+ * Checks if value is any valid expression
+ */
+declare function isExpression(value: unknown): value is Expression;
+/**
+ * Checks if value is an element node
+ */
+declare function isElementNode(value: unknown): value is ElementNode;
+/**
+ * Checks if value is a text node
+ */
+declare function isTextNode(value: unknown): value is TextNode;
+/**
+ * Checks if value is an if node
+ */
+declare function isIfNode(value: unknown): value is IfNode;
+/**
+ * Checks if value is an each node
+ */
+declare function isEachNode(value: unknown): value is EachNode;
+/**
+ * Checks if value is any valid view node
+ */
+declare function isViewNode(value: unknown): value is ViewNode;
+/**
+ * Checks if value is a set step
+ */
+declare function isSetStep(value: unknown): value is SetStep;
+/**
+ * Checks if value is an update step
+ */
+declare function isUpdateStep(value: unknown): value is UpdateStep;
+/**
+ * Checks if value is a fetch step
+ */
+declare function isFetchStep(value: unknown): value is FetchStep;
+/**
+ * Checks if value is any valid action step
+ */
+declare function isActionStep(value: unknown): value is ActionStep;
+/**
+ * Checks if value is a number field
+ */
+declare function isNumberField(value: unknown): value is NumberField;
+/**
+ * Checks if value is a string field
+ */
+declare function isStringField(value: unknown): value is StringField;
+/**
+ * Checks if value is a list field
+ */
+declare function isListField(value: unknown): value is ListField;
+/**
+ * Checks if value is any valid state field
+ */
+declare function isStateField(value: unknown): value is StateField;
+/**
+ * Checks if value is an event handler
+ */
+declare function isEventHandler(value: unknown): value is EventHandler;
+
+/**
+ * Error Types for Constela
+ *
+ * This module defines error types, the ConstelaError class,
+ * and factory functions for creating specific errors.
+ */
+type ErrorCode = 'SCHEMA_INVALID' | 'UNDEFINED_STATE' | 'UNDEFINED_ACTION' | 'VAR_UNDEFINED' | 'DUPLICATE_ACTION' | 'UNSUPPORTED_VERSION';
+/**
+ * Custom error class for Constela validation errors
+ */
+declare class ConstelaError extends Error {
+    readonly code: ErrorCode;
+    readonly path: string | undefined;
+    constructor(code: ErrorCode, message: string, path?: string | undefined);
+    /**
+     * Converts the error to a JSON-serializable object
+     */
+    toJSON(): {
+        code: ErrorCode;
+        message: string;
+        path: string | undefined;
+    };
+}
+/**
+ * Checks if value is a ConstelaError instance
+ */
+declare function isConstelaError(value: unknown): value is ConstelaError;
+/**
+ * Creates a schema validation error
+ */
+declare function createSchemaError(message: string, path?: string): ConstelaError;
+/**
+ * Creates an undefined state reference error
+ */
+declare function createUndefinedStateError(stateName: string, path?: string): ConstelaError;
+/**
+ * Creates an undefined action reference error
+ */
+declare function createUndefinedActionError(actionName: string, path?: string): ConstelaError;
+/**
+ * Creates a duplicate action name error
+ */
+declare function createDuplicateActionError(actionName: string, path?: string): ConstelaError;
+/**
+ * Creates an undefined variable reference error
+ */
+declare function createUndefinedVarError(varName: string, path?: string): ConstelaError;
+/**
+ * Creates an unsupported version error
+ */
+declare function createUnsupportedVersionError(version: string): ConstelaError;
+
+/**
+ * AST Validator for Constela
+ *
+ * This module provides validation for Constela AST structures using
+ * JSON Schema validation (AJV) and semantic validation.
+ */
+
+interface ValidationSuccess {
+    ok: true;
+    ast: Program;
+}
+interface ValidationFailure {
+    ok: false;
+    error: ConstelaError;
+}
+type ValidationResult = ValidationSuccess | ValidationFailure;
+/**
+ * Validates a Constela AST
+ *
+ * @param input - The input to validate
+ * @returns A validation result with either the valid AST or an error
+ */
+declare function validateAst(input: unknown): ValidationResult;
+
+/**
+ * JSON Schema for Constela AST
+ *
+ * This module defines the JSON Schema for validating Constela AST structures.
+ */
+declare const astSchema: {
+    readonly $schema: "http://json-schema.org/draft-07/schema#";
+    readonly $id: "https://constela.dev/schemas/ast.json";
+    readonly title: "Constela AST";
+    readonly description: "Schema for Constela UI framework AST";
+    readonly type: "object";
+    readonly required: readonly ["version", "state", "actions", "view"];
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly version: {
+            readonly type: "string";
+            readonly const: "1.0";
+        };
+        readonly state: {
+            readonly type: "object";
+            readonly additionalProperties: {
+                readonly $ref: "#/$defs/StateField";
+            };
+        };
+        readonly actions: {
+            readonly type: "array";
+            readonly items: {
+                readonly $ref: "#/$defs/ActionDefinition";
+            };
+        };
+        readonly view: {
+            readonly $ref: "#/$defs/ViewNode";
+        };
+    };
+    readonly $defs: {
+        readonly Expression: {
+            readonly oneOf: readonly [{
+                readonly $ref: "#/$defs/LitExpr";
+            }, {
+                readonly $ref: "#/$defs/StateExpr";
+            }, {
+                readonly $ref: "#/$defs/VarExpr";
+            }, {
+                readonly $ref: "#/$defs/BinExpr";
+            }, {
+                readonly $ref: "#/$defs/NotExpr";
+            }];
+        };
+        readonly LitExpr: {
+            readonly type: "object";
+            readonly required: readonly ["expr", "value"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly expr: {
+                    readonly type: "string";
+                    readonly const: "lit";
+                };
+                readonly value: {
+                    readonly oneOf: readonly [{
+                        readonly type: "string";
+                    }, {
+                        readonly type: "number";
+                    }, {
+                        readonly type: "boolean";
+                    }, {
+                        readonly type: "null";
+                    }, {
+                        readonly type: "array";
+                    }];
+                };
+            };
+        };
+        readonly StateExpr: {
+            readonly type: "object";
+            readonly required: readonly ["expr", "name"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly expr: {
+                    readonly type: "string";
+                    readonly const: "state";
+                };
+                readonly name: {
+                    readonly type: "string";
+                };
+            };
+        };
+        readonly VarExpr: {
+            readonly type: "object";
+            readonly required: readonly ["expr", "name"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly expr: {
+                    readonly type: "string";
+                    readonly const: "var";
+                };
+                readonly name: {
+                    readonly type: "string";
+                };
+                readonly path: {
+                    readonly type: "string";
+                };
+            };
+        };
+        readonly BinExpr: {
+            readonly type: "object";
+            readonly required: readonly ["expr", "op", "left", "right"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly expr: {
+                    readonly type: "string";
+                    readonly const: "bin";
+                };
+                readonly op: {
+                    readonly type: "string";
+                    readonly enum: readonly ["+", "-", "*", "/", "==", "!=", "<", "<=", ">", ">=", "&&", "||"];
+                };
+                readonly left: {
+                    readonly $ref: "#/$defs/Expression";
+                };
+                readonly right: {
+                    readonly $ref: "#/$defs/Expression";
+                };
+            };
+        };
+        readonly NotExpr: {
+            readonly type: "object";
+            readonly required: readonly ["expr", "operand"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly expr: {
+                    readonly type: "string";
+                    readonly const: "not";
+                };
+                readonly operand: {
+                    readonly $ref: "#/$defs/Expression";
+                };
+            };
+        };
+        readonly StateField: {
+            readonly oneOf: readonly [{
+                readonly $ref: "#/$defs/NumberField";
+            }, {
+                readonly $ref: "#/$defs/StringField";
+            }, {
+                readonly $ref: "#/$defs/ListField";
+            }];
+        };
+        readonly NumberField: {
+            readonly type: "object";
+            readonly required: readonly ["type", "initial"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly type: {
+                    readonly type: "string";
+                    readonly const: "number";
+                };
+                readonly initial: {
+                    readonly type: "number";
+                };
+            };
+        };
+        readonly StringField: {
+            readonly type: "object";
+            readonly required: readonly ["type", "initial"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly type: {
+                    readonly type: "string";
+                    readonly const: "string";
+                };
+                readonly initial: {
+                    readonly type: "string";
+                };
+            };
+        };
+        readonly ListField: {
+            readonly type: "object";
+            readonly required: readonly ["type", "initial"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly type: {
+                    readonly type: "string";
+                    readonly const: "list";
+                };
+                readonly initial: {
+                    readonly type: "array";
+                };
+            };
+        };
+        readonly ActionStep: {
+            readonly oneOf: readonly [{
+                readonly $ref: "#/$defs/SetStep";
+            }, {
+                readonly $ref: "#/$defs/UpdateStep";
+            }, {
+                readonly $ref: "#/$defs/FetchStep";
+            }];
+        };
+        readonly SetStep: {
+            readonly type: "object";
+            readonly required: readonly ["do", "target", "value"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly do: {
+                    readonly type: "string";
+                    readonly const: "set";
+                };
+                readonly target: {
+                    readonly type: "string";
+                };
+                readonly value: {
+                    readonly $ref: "#/$defs/Expression";
+                };
+            };
+        };
+        readonly UpdateStep: {
+            readonly type: "object";
+            readonly required: readonly ["do", "target", "operation"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly do: {
+                    readonly type: "string";
+                    readonly const: "update";
+                };
+                readonly target: {
+                    readonly type: "string";
+                };
+                readonly operation: {
+                    readonly type: "string";
+                    readonly enum: readonly ["increment", "decrement", "push", "pop", "remove"];
+                };
+                readonly value: {
+                    readonly $ref: "#/$defs/Expression";
+                };
+            };
+        };
+        readonly FetchStep: {
+            readonly type: "object";
+            readonly required: readonly ["do", "url"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly do: {
+                    readonly type: "string";
+                    readonly const: "fetch";
+                };
+                readonly url: {
+                    readonly $ref: "#/$defs/Expression";
+                };
+                readonly method: {
+                    readonly type: "string";
+                    readonly enum: readonly ["GET", "POST", "PUT", "DELETE"];
+                };
+                readonly body: {
+                    readonly $ref: "#/$defs/Expression";
+                };
+                readonly result: {
+                    readonly type: "string";
+                };
+                readonly onSuccess: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly $ref: "#/$defs/ActionStep";
+                    };
+                };
+                readonly onError: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly $ref: "#/$defs/ActionStep";
+                    };
+                };
+            };
+        };
+        readonly EventHandler: {
+            readonly type: "object";
+            readonly required: readonly ["event", "action"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly event: {
+                    readonly type: "string";
+                };
+                readonly action: {
+                    readonly type: "string";
+                };
+                readonly payload: {
+                    readonly $ref: "#/$defs/Expression";
+                };
+            };
+        };
+        readonly ActionDefinition: {
+            readonly type: "object";
+            readonly required: readonly ["name", "steps"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly name: {
+                    readonly type: "string";
+                };
+                readonly steps: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly $ref: "#/$defs/ActionStep";
+                    };
+                };
+            };
+        };
+        readonly ViewNode: {
+            readonly oneOf: readonly [{
+                readonly $ref: "#/$defs/ElementNode";
+            }, {
+                readonly $ref: "#/$defs/TextNode";
+            }, {
+                readonly $ref: "#/$defs/IfNode";
+            }, {
+                readonly $ref: "#/$defs/EachNode";
+            }];
+        };
+        readonly ElementNode: {
+            readonly type: "object";
+            readonly required: readonly ["kind", "tag"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly kind: {
+                    readonly type: "string";
+                    readonly const: "element";
+                };
+                readonly tag: {
+                    readonly type: "string";
+                };
+                readonly props: {
+                    readonly type: "object";
+                    readonly additionalProperties: {
+                        readonly oneOf: readonly [{
+                            readonly $ref: "#/$defs/Expression";
+                        }, {
+                            readonly $ref: "#/$defs/EventHandler";
+                        }];
+                    };
+                };
+                readonly children: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly $ref: "#/$defs/ViewNode";
+                    };
+                };
+            };
+        };
+        readonly TextNode: {
+            readonly type: "object";
+            readonly required: readonly ["kind", "value"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly kind: {
+                    readonly type: "string";
+                    readonly const: "text";
+                };
+                readonly value: {
+                    readonly $ref: "#/$defs/Expression";
+                };
+            };
+        };
+        readonly IfNode: {
+            readonly type: "object";
+            readonly required: readonly ["kind", "condition", "then"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly kind: {
+                    readonly type: "string";
+                    readonly const: "if";
+                };
+                readonly condition: {
+                    readonly $ref: "#/$defs/Expression";
+                };
+                readonly then: {
+                    readonly $ref: "#/$defs/ViewNode";
+                };
+                readonly else: {
+                    readonly $ref: "#/$defs/ViewNode";
+                };
+            };
+        };
+        readonly EachNode: {
+            readonly type: "object";
+            readonly required: readonly ["kind", "items", "as", "body"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly kind: {
+                    readonly type: "string";
+                    readonly const: "each";
+                };
+                readonly items: {
+                    readonly $ref: "#/$defs/Expression";
+                };
+                readonly as: {
+                    readonly type: "string";
+                };
+                readonly index: {
+                    readonly type: "string";
+                };
+                readonly key: {
+                    readonly $ref: "#/$defs/Expression";
+                };
+                readonly body: {
+                    readonly $ref: "#/$defs/ViewNode";
+                };
+            };
+        };
+    };
+};
+
+export { type ActionDefinition, type ActionStep, BINARY_OPERATORS, type BinExpr, type BinaryOperator, type ConstelaAst, ConstelaError, type EachNode, type ElementNode, type ErrorCode, type EventHandler, type Expression, type FetchStep, HTTP_METHODS, type HttpMethod, type IfNode, type ListField, type LitExpr, type NotExpr, type NumberField, type Program, type SetStep, type StateExpr, type StateField, type StringField, type TextNode, UPDATE_OPERATIONS, type UpdateOperation, type UpdateStep, type ValidationFailure, type ValidationResult, type ValidationSuccess, type VarExpr, type ViewNode, astSchema, createDuplicateActionError, createSchemaError, createUndefinedActionError, createUndefinedStateError, createUndefinedVarError, createUnsupportedVersionError, isActionStep, isBinExpr, isConstelaError, isEachNode, isElementNode, isEventHandler, isExpression, isFetchStep, isIfNode, isListField, isLitExpr, isNotExpr, isNumberField, isSetStep, isStateExpr, isStateField, isStringField, isTextNode, isUpdateStep, isVarExpr, isViewNode, validateAst };