jsxpression 0.1.0

package/src/render.test.ts

@@ -0,0 +1,425 @@
+import { describe, it, expect } from "vitest";
+import { render } from "./render";
+import { ParseError } from "./parse";
+import { AnalysisError } from "./analyze";
+import { EvaluationError } from "./evaluate";
+
+type TestNode = {
+  type: string;
+  props?: Record<string, unknown>;
+  children: unknown[];
+};
+
+describe("render", () => {
+  it("should render complete JSX pipeline successfully", () => {
+    const TestComponent = (props: { x: number; y: number }, ...children: any[]): TestNode => ({
+      type: "TestComponent",
+      props,
+      children,
+    });
+
+    const result = render(
+      "<Test x={data.x} y={Math.floor(data.y)}>Hello</Test>",
+      {
+        data: {
+          x: { type: "number" },
+          y: { type: "number" },
+        },
+        elements: {
+          Test: {
+            props: {
+              x: { type: "number" },
+              y: { type: "number" },
+            },
+          },
+        },
+      },
+      {
+        data: { x: 10, y: 3.7 },
+        components: { Test: TestComponent },
+      }
+    );
+
+    expect(result.type).toBe("TestComponent");
+    expect(result.props).toEqual({ x: 10, y: 3 });
+    expect(result.children).toEqual(["Hello"]);
+  });
+
+  it("should render complex expressions end-to-end", () => {
+    const TestComponent = (props: { values: string }): TestNode => ({
+      type: "TestComponent",
+      props,
+      children: [],
+    });
+
+    const result = render(
+      "<Test values={data.items.filter(x => x > 2).map(x => x * 2).join(', ')}>Text</Test>",
+      {
+        data: {
+          items: { type: "array", shape: { type: "number" } },
+        },
+        elements: {
+          Test: {
+            props: {
+              values: { type: "string" },
+            },
+          },
+        },
+      },
+      {
+        data: { items: [1, 2, 3, 4, 5] },
+        components: { Test: TestComponent },
+      }
+    );
+
+    expect(result.props.values).toBe("6, 8, 10");
+  });
+
+  it("should render nested JSX elements", () => {
+    const OuterComponent = (props: { x: number }, ...children: any[]): TestNode => ({
+      type: "OuterComponent",
+      props,
+      children,
+    });
+
+    const InnerComponent = (props: { y: number }): TestNode => ({
+      type: "InnerComponent",
+      props,
+      children: [],
+    });
+
+    const result = render(
+      "<Outer x={10}><Inner y={20}>Nested</Inner></Outer>",
+      {
+        elements: {
+          Outer: {
+            props: {
+              x: { type: "number" },
+            },
+          },
+          Inner: {
+            props: {
+              y: { type: "number" },
+            },
+          },
+        },
+      },
+      {
+        data: {},
+        components: {
+          Outer: OuterComponent,
+          Inner: InnerComponent,
+        },
+      }
+    );
+
+    expect(result.type).toBe("OuterComponent");
+    expect(result.props).toEqual({ x: 10 });
+    expect(result.children).toHaveLength(1);
+    expect(result.children[0].type).toBe("InnerComponent");
+  });
+
+  it("should render JSX fragments", () => {
+    const TestComponent = (): TestNode => ({
+      type: "Test",
+      props: {},
+      children: [],
+    });
+
+    const result = render(
+      "<><Test>A</Test><Test>B</Test></>",
+      {
+        elements: {
+          Test: {
+            props: {},
+          },
+        },
+      },
+      {
+        data: {},
+        components: { Test: TestComponent },
+      }
+    );
+
+    expect(result).toBeDefined();
+  });
+
+  it("should render bare expression containers", () => {
+    const result = render(
+      "{data.user.name}",
+      {
+        data: {
+          user: {
+            type: "object",
+            shape: {
+              name: { type: "string" },
+            },
+          },
+        },
+        elements: {},
+      },
+      {
+        data: { user: { name: "Alice" } },
+        components: {},
+      }
+    );
+
+    expect(result).toBe("Alice");
+  });
+
+  it("should render bare mathematical expressions", () => {
+    const result = render(
+      "{data.count * 2}",
+      {
+        data: {
+          count: { type: "number" },
+        },
+        elements: {},
+      },
+      {
+        data: { count: 42 },
+        components: {},
+      }
+    );
+
+    expect(result).toBe(84);
+  });
+
+  it("should render bare method calls", () => {
+    const result = render(
+      "{data.text.toUpperCase()}",
+      {
+        data: {
+          text: { type: "string" },
+        },
+        elements: {},
+      },
+      {
+        data: { text: "hello world" },
+        components: {},
+      }
+    );
+
+    expect(result).toBe("HELLO WORLD");
+  });
+
+  it("should render bare complex expressions", () => {
+    const result = render(
+      "{data.numbers.map(x => x * 2).join(', ')}",
+      {
+        data: {
+          numbers: {
+            type: "array",
+            shape: { type: "number" },
+          },
+        },
+        elements: {},
+      },
+      {
+        data: { numbers: [1, 2, 3, 4] },
+        components: {},
+      }
+    );
+
+    expect(result).toBe("2, 4, 6, 8");
+  });
+
+  it("should propagate ParseError for syntax errors", () => {
+    const TestComponent = (): TestNode => ({ type: "Test", props: {}, children: [] });
+
+    expect(() =>
+      render(
+        "<Text>Unclosed",
+        {
+          elements: {
+            Text: {
+              props: {},
+            },
+          },
+        },
+        {
+          components: { Text: TestComponent },
+        }
+      )
+    ).toThrow(ParseError);
+  });
+
+  it("should propagate AnalysisError for disallowed identifiers", () => {
+    const TestComponent = (): TestNode => ({ type: "Test", props: {}, children: [] });
+
+    expect(() =>
+      render(
+        "<Text>{window.location}</Text>",
+        {
+          elements: {
+            Text: {
+              props: {},
+            },
+          },
+        },
+        {
+          components: { Text: TestComponent },
+        }
+      )
+    ).toThrow(AnalysisError);
+  });
+
+  it("should propagate AnalysisError for unknown JSX elements", () => {
+    const TestComponent = (): TestNode => ({ type: "Test", props: {}, children: [] });
+
+    expect(() =>
+      render(
+        "<UnknownElement>Hello</UnknownElement>",
+        {
+          elements: {
+            Text: {
+              props: {},
+            },
+          },
+        },
+        {
+          components: { Text: TestComponent },
+        }
+      )
+    ).toThrow(AnalysisError);
+  });
+
+  it("should propagate AnalysisError for disallowed methods", () => {
+    const TestComponent = (): TestNode => ({ type: "Test", props: {}, children: [] });
+
+    expect(() =>
+      render(
+        "<Test>{data.items.push(1)}</Test>",
+        {
+          data: {
+            items: {
+              type: "array",
+              shape: { type: "number" },
+            },
+          },
+          elements: {
+            Test: {
+              props: {},
+            },
+          },
+        },
+        {
+          data: { items: [1, 2, 3] },
+          components: { Test: TestComponent },
+        }
+      )
+    ).toThrow(AnalysisError);
+  });
+
+  it("should propagate AnalysisError for unknown components", () => {
+    const TestComponent = (): TestNode => ({ type: "Test", props: {}, children: [] });
+
+    expect(() =>
+      render(
+        "<Test>Hello</Test>",
+        {
+          elements: {
+            Test: {
+              props: {},
+            },
+          },
+        },
+        {
+          data: {},
+          components: { Test: TestComponent },
+        }
+      )
+    ).not.toThrow();
+
+    expect(() =>
+      render("<Other>Hello</Other>", {
+        elements: {},
+      })
+    ).toThrow(AnalysisError);
+  });
+
+  it("should propagate EvaluationError for runtime errors", () => {
+    const TestComponent = (): TestNode => ({ type: "Test", props: {}, children: [] });
+
+    expect(() =>
+      render(
+        "<Test value={data.missing.nested}>Hello</Test>",
+        {
+          data: {
+            missing: {
+              type: "object",
+              shape: {
+                nested: { type: "number" },
+              },
+            },
+          },
+          elements: {
+            Test: {
+              props: {
+                value: { type: "number" },
+              },
+            },
+          },
+        },
+        {
+          data: {},
+          components: { Test: TestComponent },
+        }
+      )
+    ).toThrow(EvaluationError);
+  });
+
+  it("should handle empty options", () => {
+    expect(() => render("<Test>Hello</Test>", { elements: {} })).toThrow(AnalysisError);
+  });
+
+  it("should handle empty props", () => {
+    const TestComponent = (): TestNode => ({ type: "TestComponent", props: {}, children: [] });
+
+    const result = render(
+      "<Test>Hello</Test>",
+      {
+        elements: {
+          Test: {
+            props: {},
+          },
+        },
+      },
+      {
+        components: { Test: TestComponent },
+      }
+    );
+
+    expect(result.type).toBe("TestComponent");
+  });
+
+  it("should handle conditional rendering with props", () => {
+    const TestComponent = (props: { msg: string }): TestNode => ({
+      type: "Test",
+      props,
+      children: [],
+    });
+
+    const result = render(
+      "<Test msg={data.show ? 'visible' : 'hidden'}>Text</Test>",
+      {
+        data: {
+          show: { type: "boolean" },
+        },
+        elements: {
+          Test: {
+            props: {
+              msg: { type: "string" },
+            },
+          },
+        },
+      },
+      {
+        data: { show: false },
+        components: { Test: TestComponent },
+      }
+    );
+
+    expect(result.props!.msg).toBe("hidden");
+  });
+});

package/src/render.ts

@@ -0,0 +1,75 @@
+import { compile } from "./compile";
+import { evaluate, EvaluateOptions } from "./evaluate/evaluate";
+import { parse } from "./parse";
+import { Schema } from "./schema";
+import { analyze, AnalysisError } from "./analyze";
+
+/**
+ * Configuration options for rendering JSX expressions.
+ *
+ * Extends EvaluateOptions with render-specific functionality, including control over
+ * the minimum severity threshold that stops rendering.
+ *
+ * @template T - The return type of createElement function
+ */
+export interface RenderOptions<T = any> extends EvaluateOptions<T> {
+  /**
+   * Minimum severity level that counts as a failure: 1=info, 2=warning, 3=error.
+   */
+  minSeverity?: 1 | 2 | 3;
+}
+
+/**
+ * Renders a JSX expression with data validation and security constraints.
+ *
+ * Parses JSX source code, validates it against a schema for security and type safety,
+ * compiles it to executable code, and evaluates it with the provided data and components.
+ *
+ * @template T - The return type of the rendered JSX (e.g., ReactElement, VNode, string)
+ * @param source - JSX expression source code to render (e.g., `"<Text x={data.user.name}>Hello</Text>"`)
+ * @param schema - Schema defining allowed data properties, JSX elements, and hierarchy rules
+ * @param options - Rendering configuration
+ * @param options.data - Data object available as `data.*` in expressions
+ * @param options.components - Map of component names to component functions
+ * @param options.createElement - Function to create elements (e.g., React.createElement)
+ * @param options.minSeverity - Minimum severity (1=info, 2=warning, 3=error) required to abort rendering; defaults to `3`
+ * @returns The rendered JSX element of type T
+ *
+ * @throws {AnalysisError} When JSX contains security violations, invalid data access, or schema mismatches
+ *
+ * @example
+ * ```typescript
+ * const schema: Schema = {
+ *   data: {
+ *     user: { type: "object", shape: { name: { type: "string" } } }
+ *   },
+ *   elements: {
+ *     Text: { props: { children: { type: "string" } } }
+ *   }
+ * };
+ *
+ * const result = render(
+ *   "<Text>Hello {data.user.name}!</Text>",
+ *   schema,
+ *   {
+ *     data: { user: { name: "World" } },
+ *     components: { Text: ({ children }) => children },
+ *     createElement: (type, props, ...children) => ({ type, props, children })
+ *   }
+ * );
+ * ```
+ */
+export function render<T = any>(
+  source: string,
+  schema: Schema,
+  { minSeverity = 3, ...options }: RenderOptions<T> = {}
+): T {
+  const ast = parse(source);
+  const report = analyze(ast, schema);
+
+  if (report.hasIssues(minSeverity)) {
+    throw AnalysisError.fromReport(report);
+  }
+
+  return evaluate(compile(ast), options) as T;
+}

package/src/schema.ts

@@ -0,0 +1,195 @@
+export type StringPropertySchema = {
+  type: "string";
+  description?: string;
+  required?: boolean;
+  default?: string;
+  enum?: readonly string[];
+};
+
+export type NumberPropertySchema = {
+  type: "number";
+  description?: string;
+  required?: boolean;
+  default?: number;
+  enum?: readonly number[];
+};
+
+export type BooleanPropertySchema = {
+  type: "boolean";
+  description?: string;
+  required?: boolean;
+  default?: boolean;
+  enum?: readonly boolean[];
+};
+
+export type FunctionPropertySchema = {
+  type: "function";
+  description?: string;
+  required?: boolean;
+};
+
+export type ObjectPropertySchema = {
+  type: "object";
+  description?: string;
+  required?: boolean;
+  shape: Record<string, PropertySchema>;
+};
+
+export type ArrayPropertySchema = {
+  type: "array";
+  description?: string;
+  required?: boolean;
+  shape: PropertySchema;
+};
+
+export type PropertySchema =
+  | StringPropertySchema
+  | NumberPropertySchema
+  | BooleanPropertySchema
+  | FunctionPropertySchema
+  | ObjectPropertySchema
+  | ArrayPropertySchema;
+
+export type ElementSchema = {
+  description?: string;
+  props?: Record<string, PropertySchema>;
+  allowedChildren?: string[];
+};
+
+export interface Schema {
+  data?: Record<string, PropertySchema>;
+  elements?: Record<string, ElementSchema>;
+}
+
+export function isElementAllowed(schema: Schema, tagName: string): boolean {
+  return !!schema.elements?.[tagName];
+}
+
+export function getElementSchema(schema: Schema, tagName: string): ElementSchema | undefined {
+  return schema.elements?.[tagName];
+}
+
+export function getAllowedAttributes(schema: Schema, tagName: string): string[] {
+  const elementConfig = getElementSchema(schema, tagName);
+  return elementConfig?.props ? Object.keys(elementConfig.props) : [];
+}
+
+export function isAttributeAllowed(schema: Schema, tagName: string, attributeName: string): boolean {
+  const allowedAttributes = getAllowedAttributes(schema, tagName);
+  return allowedAttributes.includes(attributeName);
+}
+
+export function getAllowedChildren(schema: Schema, tagName: string): string[] | undefined {
+  const elementConfig = getElementSchema(schema, tagName);
+  return elementConfig?.allowedChildren;
+}
+
+export function canHaveChildren(schema: Schema, tagName: string): boolean {
+  const allowedChildren = getAllowedChildren(schema, tagName);
+  return allowedChildren === undefined || allowedChildren.length > 0;
+}
+
+export function isSelfClosing(schema: Schema, tagName: string): boolean {
+  const allowedChildren = getAllowedChildren(schema, tagName);
+  return allowedChildren !== undefined && allowedChildren.length === 0;
+}
+
+export function isChildAllowed(schema: Schema, parentTag: string, childTag: string): boolean {
+  const allowedChildren = getAllowedChildren(schema, parentTag);
+  return allowedChildren === undefined || allowedChildren.includes(childTag);
+}
+
+// New schema utilities for enhanced validation
+export function getAllElements(schema: Schema): string[] {
+  return schema.elements ? Object.keys(schema.elements) : [];
+}
+
+export function getElementConfig(schema: Schema, tagName: string): ElementSchema | undefined {
+  return getElementSchema(schema, tagName);
+}
+
+export function getAttributeSchema(schema: Schema, tagName: string, attributeName: string): PropertySchema | undefined {
+  const elementSchema = getElementSchema(schema, tagName);
+  return elementSchema?.props?.[attributeName];
+}
+
+export function getRequiredAttributes(schema: Schema, tagName: string): string[] {
+  const elementSchema = getElementSchema(schema, tagName);
+  if (!elementSchema?.props) {
+    return [];
+  }
+
+  const required: string[] = [];
+  for (const [attrName, attrSchema] of Object.entries(elementSchema.props)) {
+    if (attrSchema.required === true) {
+      required.push(attrName);
+    }
+  }
+
+  return required;
+}
+
+export function getOptionalAttributes(schema: Schema, tagName: string): string[] {
+  const allAttributes = getAllowedAttributes(schema, tagName);
+  const requiredAttributes = getRequiredAttributes(schema, tagName);
+  return allAttributes.filter((attr) => !requiredAttributes.includes(attr));
+}
+
+export function isAttributeRequired(schema: Schema, tagName: string, attributeName: string): boolean {
+  const requiredAttributes = getRequiredAttributes(schema, tagName);
+  return requiredAttributes.includes(attributeName);
+}
+
+export function getDataSchema(schema: Schema): Record<string, PropertySchema> | undefined {
+  return schema.data;
+}
+
+export function getPropertyAtPath(schema: Schema, path: string[]): PropertySchema | undefined {
+  if (!schema.data || path.length === 0) {
+    return undefined;
+  }
+
+  let current: PropertySchema | undefined = schema.data[path[0]];
+
+  for (let i = 1; i < path.length && current; i++) {
+    if (current.type === "object" && current.shape) {
+      current = current.shape[path[i]];
+    } else {
+      return undefined;
+    }
+  }
+
+  return current;
+}
+
+export function getAvailablePropertiesAtPath(schema: Schema, path: string[]): string[] {
+  if (!schema.data) {
+    return [];
+  }
+
+  if (path.length === 0) {
+    return Object.keys(schema.data);
+  }
+
+  const parentProperty = getPropertyAtPath(schema, path);
+  if (parentProperty?.type === "object" && parentProperty.shape) {
+    return Object.keys(parentProperty.shape);
+  }
+
+  return [];
+}
+
+export type PropertyEnumValue = string | number | boolean;
+
+export function getEnumValues(property: PropertySchema): readonly PropertyEnumValue[] | undefined {
+  switch (property.type) {
+    case "string":
+      return property.enum;
+    case "number":
+      return property.enum;
+    case "boolean":
+      return property.enum;
+    default:
+      return undefined;
+  }
+}