@constela/builder 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Constela Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,179 @@
+import { LitExpr, StateExpr, VarExpr, BinaryOperator, Expression, BinExpr, NotExpr, CondExpr, GetExpr, NumberField, StringField, ListField, BooleanField, ObjectField, ActionStep, ActionDefinition, SetStep, UpdateOperation, UpdateStep, HttpMethod, FetchStep, NavigateTarget, NavigateStep, EventHandler, ViewNode, ElementNode, TextNode, IfNode, EachNode, ComponentNode, SlotNode, RouteDefinition, StateField, ComponentDef, Program } from '@constela/core';
+export { ActionDefinition, ActionStep, BinExpr, BinaryOperator, BooleanField, ComponentNode, CondExpr, EachNode, ElementNode, EventHandler, Expression, FetchStep, GetExpr, HttpMethod, IfNode, ListField, LitExpr, NavigateStep, NavigateTarget, NotExpr, NumberField, ObjectField, Program, SetStep, SlotNode, StateExpr, StateField, StringField, TextNode, UpdateOperation, UpdateStep, VarExpr, ViewNode } from '@constela/core';
+
+/**
+ * @constela/builder - Type-safe builders for constructing Constela AST programmatically
+ *
+ * This package provides a functional composition API for building Constela AST nodes.
+ * All builders return strongly-typed AST structures from @constela/core.
+ */
+
+/**
+ * Creates a literal expression
+ */
+declare function lit(value: string | number | boolean | null | unknown[]): LitExpr;
+/**
+ * Creates a state expression
+ */
+declare function state(name: string, path?: string): StateExpr;
+/**
+ * Creates a variable expression
+ */
+declare function variable(name: string, path?: string): VarExpr;
+/**
+ * Creates a binary expression
+ */
+declare function bin(op: BinaryOperator, left: Expression, right: Expression): BinExpr;
+declare const add: (left: Expression, right: Expression) => BinExpr;
+declare const sub: (left: Expression, right: Expression) => BinExpr;
+declare const mul: (left: Expression, right: Expression) => BinExpr;
+declare const divide: (left: Expression, right: Expression) => BinExpr;
+declare const eq: (left: Expression, right: Expression) => BinExpr;
+declare const neq: (left: Expression, right: Expression) => BinExpr;
+declare const lt: (left: Expression, right: Expression) => BinExpr;
+declare const lte: (left: Expression, right: Expression) => BinExpr;
+declare const gt: (left: Expression, right: Expression) => BinExpr;
+declare const gte: (left: Expression, right: Expression) => BinExpr;
+declare const and: (left: Expression, right: Expression) => BinExpr;
+declare const or: (left: Expression, right: Expression) => BinExpr;
+/**
+ * Creates a not expression
+ */
+declare function not(operand: Expression): NotExpr;
+/**
+ * Creates a conditional expression
+ */
+declare function cond(condition: Expression, thenExpr: Expression, elseExpr: Expression): CondExpr;
+/**
+ * Creates a get expression for property access
+ */
+declare function get(base: Expression, path: string): GetExpr;
+/**
+ * Creates a number field
+ */
+declare function numberField(initial: number): NumberField;
+/**
+ * Creates a string field
+ */
+declare function stringField(initial: string): StringField;
+/**
+ * Creates a list field
+ */
+declare function listField<T>(initial?: T[]): ListField;
+/**
+ * Creates a boolean field
+ */
+declare function booleanField(initial: boolean): BooleanField;
+/**
+ * Creates an object field
+ */
+declare function objectField<T extends Record<string, unknown>>(initial: T): ObjectField;
+/**
+ * Creates an action definition
+ */
+declare function action(name: string, steps: ActionStep[]): ActionDefinition;
+/**
+ * Creates a set step
+ */
+declare function set(target: string, value: Expression): SetStep;
+/**
+ * Creates an update step
+ */
+declare function update(target: string, operation: UpdateOperation, value?: Expression): UpdateStep;
+declare const increment: (target: string, value?: Expression) => UpdateStep;
+declare const decrement: (target: string, value?: Expression) => UpdateStep;
+declare const push: (target: string, value: Expression) => UpdateStep;
+declare const pop: (target: string) => UpdateStep;
+declare const toggle: (target: string) => UpdateStep;
+/**
+ * Fetch step options
+ */
+interface FetchOptions {
+    method?: HttpMethod;
+    body?: Expression;
+    result?: string;
+    onSuccess?: ActionStep[];
+    onError?: ActionStep[];
+}
+/**
+ * Creates a fetch step
+ */
+declare function fetch(url: Expression, options?: FetchOptions): FetchStep;
+/**
+ * Navigate step options
+ */
+interface NavigateOptions {
+    target?: NavigateTarget;
+    replace?: boolean;
+}
+/**
+ * Creates a navigate step
+ */
+declare function navigate(url: Expression, options?: NavigateOptions): NavigateStep;
+/**
+ * Creates an element node
+ */
+declare function element(tag: string, props?: Record<string, Expression | EventHandler>, children?: ViewNode[]): ElementNode;
+declare const div: (props?: Record<string, Expression | EventHandler>, children?: ViewNode[]) => ElementNode;
+declare const span: (props?: Record<string, Expression | EventHandler>, children?: ViewNode[]) => ElementNode;
+declare const button: (props?: Record<string, Expression | EventHandler>, children?: ViewNode[]) => ElementNode;
+declare const input: (props?: Record<string, Expression | EventHandler>, children?: ViewNode[]) => ElementNode;
+/**
+ * Creates a text node
+ */
+declare function text(value: Expression): TextNode;
+/**
+ * Creates an if node for conditional rendering
+ */
+declare function ifNode(condition: Expression, then: ViewNode, elseNode?: ViewNode): IfNode;
+/**
+ * Each node options
+ */
+interface EachOptions {
+    index?: string;
+    key?: Expression;
+}
+/**
+ * Creates an each node for list rendering
+ */
+declare function each(items: Expression, as: string, body: ViewNode, options?: EachOptions): EachNode;
+/**
+ * Creates a component node
+ */
+declare function component(name: string, props?: Record<string, Expression>, children?: ViewNode[]): ComponentNode;
+/**
+ * Creates a slot node
+ */
+declare function slot(name?: string): SlotNode;
+/**
+ * Creates an onClick event handler
+ */
+declare function onClick(action: string, payload?: Expression): EventHandler;
+/**
+ * Creates an onInput event handler with default payload
+ */
+declare function onInput(action: string, payload?: Expression): EventHandler;
+/**
+ * Creates an onChange event handler with default payload
+ */
+declare function onChange(action: string, payload?: Expression): EventHandler;
+/**
+ * Creates an onSubmit event handler
+ */
+declare function onSubmit(action: string, payload?: Expression): EventHandler;
+/**
+ * Program builder options
+ */
+interface ProgramOptions {
+    route?: RouteDefinition;
+    state: Record<string, StateField>;
+    actions: ActionDefinition[];
+    view: ViewNode;
+    components?: Record<string, ComponentDef>;
+}
+/**
+ * Creates a program
+ */
+declare function createProgram(options: ProgramOptions): Program;
+
+export { type EachOptions, type FetchOptions, type NavigateOptions, type ProgramOptions, action, add, and, bin, booleanField, button, component, cond, createProgram, decrement, div, divide, each, element, eq, fetch, get, gt, gte, ifNode, increment, input, listField, lit, lt, lte, mul, navigate, neq, not, numberField, objectField, onChange, onClick, onInput, onSubmit, or, pop, push, set, slot, span, state, stringField, sub, text, toggle, update, variable };

package/dist/index.js

@@ -0,0 +1,237 @@
+// src/index.ts
+function lit(value) {
+  return { expr: "lit", value };
+}
+function state(name, path) {
+  const result = { expr: "state", name };
+  if (path !== void 0) {
+    result.path = path;
+  }
+  return result;
+}
+function variable(name, path) {
+  const result = { expr: "var", name };
+  if (path !== void 0) {
+    result.path = path;
+  }
+  return result;
+}
+function bin(op, left, right) {
+  return { expr: "bin", op, left, right };
+}
+var add = (left, right) => bin("+", left, right);
+var sub = (left, right) => bin("-", left, right);
+var mul = (left, right) => bin("*", left, right);
+var divide = (left, right) => bin("/", left, right);
+var eq = (left, right) => bin("==", left, right);
+var neq = (left, right) => bin("!=", left, right);
+var lt = (left, right) => bin("<", left, right);
+var lte = (left, right) => bin("<=", left, right);
+var gt = (left, right) => bin(">", left, right);
+var gte = (left, right) => bin(">=", left, right);
+var and = (left, right) => bin("&&", left, right);
+var or = (left, right) => bin("||", left, right);
+function not(operand) {
+  return { expr: "not", operand };
+}
+function cond(condition, thenExpr, elseExpr) {
+  return { expr: "cond", if: condition, then: thenExpr, else: elseExpr };
+}
+function get(base, path) {
+  return { expr: "get", base, path };
+}
+function numberField(initial) {
+  return { type: "number", initial };
+}
+function stringField(initial) {
+  return { type: "string", initial };
+}
+function listField(initial = []) {
+  return { type: "list", initial };
+}
+function booleanField(initial) {
+  return { type: "boolean", initial };
+}
+function objectField(initial) {
+  return { type: "object", initial };
+}
+function action(name, steps) {
+  return { name, steps };
+}
+function set(target, value) {
+  return { do: "set", target, value };
+}
+function update(target, operation, value) {
+  const result = { do: "update", target, operation };
+  if (value !== void 0) {
+    result.value = value;
+  }
+  return result;
+}
+var increment = (target, value) => value !== void 0 ? { do: "update", target, operation: "increment", value } : { do: "update", target, operation: "increment" };
+var decrement = (target, value) => value !== void 0 ? { do: "update", target, operation: "decrement", value } : { do: "update", target, operation: "decrement" };
+var push = (target, value) => ({ do: "update", target, operation: "push", value });
+var pop = (target) => ({ do: "update", target, operation: "pop" });
+var toggle = (target) => ({ do: "update", target, operation: "toggle" });
+function fetch(url, options) {
+  const result = { do: "fetch", url };
+  if (options) {
+    if (options.method !== void 0) result.method = options.method;
+    if (options.body !== void 0) result.body = options.body;
+    if (options.result !== void 0) result.result = options.result;
+    if (options.onSuccess !== void 0) result.onSuccess = options.onSuccess;
+    if (options.onError !== void 0) result.onError = options.onError;
+  }
+  return result;
+}
+function navigate(url, options) {
+  const result = { do: "navigate", url };
+  if (options) {
+    if (options.target !== void 0) result.target = options.target;
+    if (options.replace !== void 0) result.replace = options.replace;
+  }
+  return result;
+}
+function element(tag, props, children) {
+  const result = { kind: "element", tag };
+  if (props !== void 0 && Object.keys(props).length > 0) {
+    result.props = props;
+  }
+  if (children !== void 0 && children.length > 0) {
+    result.children = children;
+  }
+  return result;
+}
+var div = (props, children) => element("div", props, children);
+var span = (props, children) => element("span", props, children);
+var button = (props, children) => element("button", props, children);
+var input = (props, children) => element("input", props, children);
+function text(value) {
+  return { kind: "text", value };
+}
+function ifNode(condition, then, elseNode) {
+  const result = { kind: "if", condition, then };
+  if (elseNode !== void 0) {
+    result.else = elseNode;
+  }
+  return result;
+}
+function each(items, as, body, options) {
+  const result = { kind: "each", items, as, body };
+  if (options) {
+    if (options.index !== void 0) result.index = options.index;
+    if (options.key !== void 0) result.key = options.key;
+  }
+  return result;
+}
+function component(name, props, children) {
+  const result = { kind: "component", name };
+  if (props !== void 0 && Object.keys(props).length > 0) {
+    result.props = props;
+  }
+  if (children !== void 0 && children.length > 0) {
+    result.children = children;
+  }
+  return result;
+}
+function slot(name) {
+  const result = { kind: "slot" };
+  if (name !== void 0) {
+    result.name = name;
+  }
+  return result;
+}
+function onClick(action2, payload) {
+  const result = { event: "click", action: action2 };
+  if (payload !== void 0) {
+    result.payload = payload;
+  }
+  return result;
+}
+function onInput(action2, payload) {
+  return {
+    event: "input",
+    action: action2,
+    payload: payload ?? { expr: "var", name: "event", path: "target.value" }
+  };
+}
+function onChange(action2, payload) {
+  return {
+    event: "change",
+    action: action2,
+    payload: payload ?? { expr: "var", name: "event", path: "target.value" }
+  };
+}
+function onSubmit(action2, payload) {
+  const result = { event: "submit", action: action2 };
+  if (payload !== void 0) {
+    result.payload = payload;
+  }
+  return result;
+}
+function createProgram(options) {
+  const result = {
+    version: "1.0",
+    state: options.state,
+    actions: options.actions,
+    view: options.view
+  };
+  if (options.route !== void 0) {
+    result.route = options.route;
+  }
+  if (options.components !== void 0) {
+    result.components = options.components;
+  }
+  return result;
+}
+export {
+  action,
+  add,
+  and,
+  bin,
+  booleanField,
+  button,
+  component,
+  cond,
+  createProgram,
+  decrement,
+  div,
+  divide,
+  each,
+  element,
+  eq,
+  fetch,
+  get,
+  gt,
+  gte,
+  ifNode,
+  increment,
+  input,
+  listField,
+  lit,
+  lt,
+  lte,
+  mul,
+  navigate,
+  neq,
+  not,
+  numberField,
+  objectField,
+  onChange,
+  onClick,
+  onInput,
+  onSubmit,
+  or,
+  pop,
+  push,
+  set,
+  slot,
+  span,
+  state,
+  stringField,
+  sub,
+  text,
+  toggle,
+  update,
+  variable
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@constela/builder",
+  "version": "0.2.0",
+  "description": "Type-safe builders for constructing Constela AST programmatically",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@constela/core": "0.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^2.0.0"
+  },
+  "peerDependencies": {},
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
+  }
+}