@hypen-space/core 0.2.11 → 0.3.0

package/src/disposable.ts

@@ -0,0 +1,281 @@
+/**
+ * Disposable Pattern for Resource Management
+ *
+ * Provides a consistent way to manage and clean up resources like
+ * event listeners, timers, WebSocket connections, etc.
+ */
+
+/**
+ * Interface for objects that can be disposed
+ */
+export interface Disposable {
+  dispose(): void;
+}
+
+/**
+ * Check if an object is Disposable
+ */
+export function isDisposable(obj: unknown): obj is Disposable {
+  return (
+    obj !== null &&
+    typeof obj === 'object' &&
+    'dispose' in obj &&
+    typeof (obj as Disposable).dispose === 'function'
+  );
+}
+
+/**
+ * A stack of disposables that are disposed in LIFO order
+ */
+export class DisposableStack implements Disposable {
+  private stack: Disposable[] = [];
+  private disposed = false;
+
+  /**
+   * Add a disposable to the stack and return it
+   */
+  add<T extends Disposable>(disposable: T): T {
+    if (this.disposed) {
+      // If already disposed, immediately dispose the new item
+      disposable.dispose();
+      return disposable;
+    }
+    this.stack.push(disposable);
+    return disposable;
+  }
+
+  /**
+   * Add a cleanup callback to the stack
+   */
+  addCallback(callback: () => void): void {
+    this.add({ dispose: callback });
+  }
+
+  /**
+   * Add a value with a custom dispose function
+   */
+  addValue<T>(value: T, dispose: (value: T) => void): T {
+    this.add({ dispose: () => dispose(value) });
+    return value;
+  }
+
+  /**
+   * Dispose all items in reverse order (LIFO)
+   */
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+
+    while (this.stack.length > 0) {
+      const item = this.stack.pop()!;
+      try {
+        item.dispose();
+      } catch (error) {
+        // Log but continue disposing other items
+        console.error('[DisposableStack] Error during dispose:', error);
+      }
+    }
+  }
+
+  /**
+   * Check if this stack has been disposed
+   */
+  get isDisposed(): boolean {
+    return this.disposed;
+  }
+
+  /**
+   * Get the number of items in the stack
+   */
+  get size(): number {
+    return this.stack.length;
+  }
+}
+
+/**
+ * Create a disposable from an event listener
+ */
+export function disposableListener(
+  target: EventTarget,
+  event: string,
+  handler: EventListenerOrEventListenerObject,
+  options?: AddEventListenerOptions
+): Disposable {
+  target.addEventListener(event, handler, options);
+  return {
+    dispose: () => target.removeEventListener(event, handler, options),
+  };
+}
+
+/**
+ * Create a disposable from a timeout
+ */
+export function disposableTimeout(
+  callback: () => void,
+  ms: number
+): Disposable & { id: ReturnType<typeof setTimeout> } {
+  const id = setTimeout(callback, ms);
+  return {
+    id,
+    dispose: () => clearTimeout(id),
+  };
+}
+
+/**
+ * Create a disposable from an interval
+ */
+export function disposableInterval(
+  callback: () => void,
+  ms: number
+): Disposable & { id: ReturnType<typeof setInterval> } {
+  const id = setInterval(callback, ms);
+  return {
+    id,
+    dispose: () => clearInterval(id),
+  };
+}
+
+/**
+ * Create a disposable from a WebSocket
+ */
+export function disposableWebSocket(ws: WebSocket): Disposable {
+  return {
+    dispose: () => {
+      if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
+        ws.close();
+      }
+    },
+  };
+}
+
+/**
+ * Create a disposable from an AbortController
+ */
+export function disposableAbortController(): Disposable & { controller: AbortController; signal: AbortSignal } {
+  const controller = new AbortController();
+  return {
+    controller,
+    signal: controller.signal,
+    dispose: () => controller.abort(),
+  };
+}
+
+/**
+ * Create a disposable subscription (for event emitters, observables, etc.)
+ */
+export function disposableSubscription(unsubscribe: () => void): Disposable {
+  return { dispose: unsubscribe };
+}
+
+/**
+ * Symbol used to store disposables on DOM elements
+ */
+const ELEMENT_DISPOSABLES = Symbol('hypen.disposables');
+
+/**
+ * Get or create a DisposableStack for an HTML element
+ */
+export function getElementDisposables(element: HTMLElement): DisposableStack {
+  const existing = (element as any)[ELEMENT_DISPOSABLES];
+  if (existing instanceof DisposableStack) {
+    return existing;
+  }
+  const stack = new DisposableStack();
+  (element as any)[ELEMENT_DISPOSABLES] = stack;
+  return stack;
+}
+
+/**
+ * Dispose all disposables attached to an element
+ */
+export function disposeElement(element: HTMLElement): void {
+  const stack = (element as any)[ELEMENT_DISPOSABLES];
+  if (stack instanceof DisposableStack) {
+    stack.dispose();
+    delete (element as any)[ELEMENT_DISPOSABLES];
+  }
+}
+
+/**
+ * Check if an element has disposables
+ */
+export function hasElementDisposables(element: HTMLElement): boolean {
+  return (element as any)[ELEMENT_DISPOSABLES] instanceof DisposableStack;
+}
+
+/**
+ * Decorator/helper to make a class disposable
+ * Tracks all resources and disposes them when dispose() is called
+ */
+export class DisposableMixin {
+  protected disposables = new DisposableStack();
+
+  /**
+   * Register a disposable to be cleaned up
+   */
+  protected track<T extends Disposable>(disposable: T): T {
+    return this.disposables.add(disposable);
+  }
+
+  /**
+   * Register a cleanup callback
+   */
+  protected onDispose(callback: () => void): void {
+    this.disposables.addCallback(callback);
+  }
+
+  /**
+   * Dispose all tracked resources
+   */
+  dispose(): void {
+    this.disposables.dispose();
+  }
+}
+
+/**
+ * Create a composite disposable that disposes multiple items together
+ */
+export function compositeDisposable(...disposables: Disposable[]): Disposable {
+  return {
+    dispose: () => {
+      for (const d of disposables) {
+        try {
+          d.dispose();
+        } catch (error) {
+          console.error('[compositeDisposable] Error during dispose:', error);
+        }
+      }
+    },
+  };
+}
+
+/**
+ * Run a function with automatic cleanup on exit
+ * Similar to Python's context managers or C#'s using statement
+ */
+export async function using<T extends Disposable, R>(
+  resource: T | (() => T),
+  fn: (resource: T) => R | Promise<R>
+): Promise<R> {
+  const r = typeof resource === 'function' ? resource() : resource;
+  try {
+    return await fn(r);
+  } finally {
+    r.dispose();
+  }
+}
+
+/**
+ * Synchronous version of using()
+ */
+export function usingSync<T extends Disposable, R>(
+  resource: T | (() => T),
+  fn: (resource: T) => R
+): R {
+  const r = typeof resource === 'function' ? resource() : resource;
+  try {
+    return fn(r);
+  } finally {
+    r.dispose();
+  }
+}

package/src/engine.browser.ts

@@ -94,7 +94,7 @@ export class Engine {
     if (this.initialized) return;
 
     // Default to CDN for zero-config experience
-    const cdnBase = "https://unpkg.com/@hypen-space/core@0.2.11/wasm-browser";
+    const cdnBase = "https://unpkg.com/@hypen-space/core@0.2.12/wasm-browser";
     const jsUrl = options.jsUrl ?? `${cdnBase}/hypen_engine.js`;
     const wasmUrl = options.wasmUrl ?? `${cdnBase}/hypen_engine_bg.wasm`;
 

package/src/engine.ts

@@ -6,6 +6,31 @@
 // WASM module types
 import { WasmEngine } from "../wasm-node/hypen_engine.js";
 
+/**
+ * Unwrap proxy objects to plain values for WASM serialization.
+ * Uses structuredClone when available (Node 17+, Bun, modern browsers),
+ * falls back to JSON round-trip for proxy objects or older environments.
+ */
+function unwrapForWasm<T>(value: T): T {
+  // Fast path: primitives don't need cloning
+  if (value === null || typeof value !== 'object') {
+    return value;
+  }
+
+  // Check if the object has a snapshot method (our proxy convention)
+  if (typeof (value as any).__getSnapshot === 'function') {
+    return (value as any).__getSnapshot() as T;
+  }
+
+  // Try structuredClone first (fastest for plain objects)
+  try {
+    return structuredClone(value);
+  } catch {
+    // Fallback for proxy objects or unsupported types
+    return JSON.parse(JSON.stringify(value));
+  }
+}
+
 export type Patch = {
   type: "create" | "setProp" | "setText" | "insert" | "move" | "remove" | "attachEvent" | "detachEvent";
   id?: string;
@@ -108,8 +133,7 @@ export class Engine {
    */
   renderInto(source: string, parentNodeId: string, state: Record<string, any>): void {
     const engine = this.ensureInitialized();
-    const safeState = JSON.parse(JSON.stringify(state));
-    engine.renderInto(source, parentNodeId, safeState);
+    engine.renderInto(source, parentNodeId, unwrapForWasm(state));
   }
 
   /**
@@ -122,9 +146,7 @@ export class Engine {
       return;
     }
 
-    // Clone values to prevent proxy objects from causing issues
-    const plainValues = JSON.parse(JSON.stringify(values));
-    engine.updateStateSparse(paths, plainValues);
+    engine.updateStateSparse(paths, unwrapForWasm(values));
     console.debug("[Hypen] State changed (sparse):", paths);
   }
 
@@ -134,9 +156,7 @@ export class Engine {
    */
   notifyStateChangeFull(paths: string[], currentState: Record<string, any>): void {
     const engine = this.ensureInitialized();
-
-    const plainObject = JSON.parse(JSON.stringify(currentState));
-    engine.updateState(plainObject);
+    engine.updateState(unwrapForWasm(currentState));
 
     if (paths.length > 0) {
       console.debug("[Hypen] State changed (full):", paths);
@@ -149,8 +169,7 @@ export class Engine {
    */
   updateState(statePatch: Record<string, any>): void {
     const engine = this.ensureInitialized();
-    const plainObject = JSON.parse(JSON.stringify(statePatch));
-    engine.updateState(plainObject);
+    engine.updateState(unwrapForWasm(statePatch));
   }
 
   /**

package/src/hypen.ts

@@ -0,0 +1,209 @@
+/**
+ * Hypen Tagged Template Literal
+ *
+ * Enables single-file components with inline UI templates.
+ *
+ * The `hypen` tagged template preserves ${state.x} and ${item.x} bindings
+ * instead of interpolating them, allowing you to write:
+ *
+ * @example
+ * ```typescript
+ * import { app, hypen, state } from "@hypen-space/core";
+ *
+ * export default app
+ *   .defineState({ count: 0 })
+ *   .onAction("increment", ({ state }) => {
+ *     state.count += 1;
+ *   })
+ *   .ui(hypen`
+ *     Column {
+ *       Text("Count: ${state.count}")
+ *       Button { Text("+") }
+ *         .onClick("@actions.increment")
+ *     }
+ *   `);
+ * ```
+ */
+
+/**
+ * Creates a proxy that captures property access as a binding path string.
+ *
+ * When used in a template literal, the proxy's toString() returns the
+ * full binding expression (e.g., "${state.user.name}").
+ *
+ * @example
+ * ```typescript
+ * const state = createBindingProxy('state');
+ * `${state.user.name}` // Returns: "${state.user.name}"
+ * ```
+ */
+function createBindingProxy(root: string): any {
+  const handler: ProxyHandler<object> = {
+    get(_, prop: string | symbol): any {
+      // Handle Symbol.toPrimitive, toString, and valueOf for string conversion
+      if (
+        prop === Symbol.toPrimitive ||
+        prop === "toString" ||
+        prop === "valueOf"
+      ) {
+        return () => `\${${root}}`;
+      }
+
+      // Handle other Symbol properties (e.g., Symbol.toStringTag)
+      if (typeof prop === "symbol") {
+        return undefined;
+      }
+
+      // Handle JSON.stringify
+      if (prop === "toJSON") {
+        return () => `\${${root}}`;
+      }
+
+      // Chain to nested property: state.user -> state.user.name
+      return createBindingProxy(`${root}.${prop}`);
+    },
+
+    // Support for `in` operator
+    has() {
+      return true;
+    },
+
+    // Support for Object.keys() - return empty to avoid enumeration issues
+    ownKeys() {
+      return [];
+    },
+
+    getOwnPropertyDescriptor() {
+      return {
+        configurable: true,
+        enumerable: true,
+      };
+    },
+  };
+
+  return new Proxy({} as any, handler);
+}
+
+/**
+ * Proxy for state bindings.
+ *
+ * Use in hypen templates to create reactive state bindings:
+ *
+ * @example
+ * ```typescript
+ * hypen`Text("Hello, ${state.user.name}")`
+ * // Produces: Text("Hello, ${state.user.name}")
+ * ```
+ */
+export const state: any = createBindingProxy("state");
+
+/**
+ * Proxy for item bindings in list iteration.
+ *
+ * Use inside List components to reference the current item:
+ *
+ * @example
+ * ```typescript
+ * hypen`
+ *   List(@state.items) {
+ *     Text("${item.name}: ${item.price}")
+ *   }
+ * `
+ * ```
+ */
+export const item: any = createBindingProxy("item");
+
+/**
+ * Proxy for index in list iteration.
+ *
+ * Use inside List components to reference the current index:
+ *
+ * @example
+ * ```typescript
+ * hypen`
+ *   List(@state.items) {
+ *     Text("Item #${index}: ${item.name}")
+ *   }
+ * `
+ * ```
+ */
+export const index: any = {
+  [Symbol.toPrimitive]: () => "${index}",
+  toString: () => "${index}",
+  valueOf: () => "${index}",
+  toJSON: () => "${index}",
+};
+
+/**
+ * Tagged template literal for Hypen DSL templates.
+ *
+ * Works with the `state`, `item`, and `index` binding proxies to preserve
+ * binding syntax in the output string.
+ *
+ * @example
+ * ```typescript
+ * import { hypen, state, item } from "@hypen-space/core";
+ *
+ * // Simple state binding
+ * const t1 = hypen`Text("Count: ${state.count}")`;
+ * // Result: 'Text("Count: ${state.count}")'
+ *
+ * // Nested state binding
+ * const t2 = hypen`Text("Hello, ${state.user.profile.name}")`;
+ * // Result: 'Text("Hello, ${state.user.profile.name}")'
+ *
+ * // List with item binding
+ * const t3 = hypen`
+ *   List(@state.products) {
+ *     Text("${item.name} - $${item.price}")
+ *   }
+ * `;
+ *
+ * // Complex expressions (use regular JS interpolation for static values)
+ * const title = "My App";
+ * const t4 = hypen`Text("${title}: ${state.count}")`;
+ * // Result: 'Text("My App: ${state.count}")'
+ * ```
+ *
+ * @param strings - Template literal string parts
+ * @param expressions - Interpolated expressions (proxies return binding strings)
+ * @returns The template string with bindings preserved
+ */
+export function hypen(
+  strings: TemplateStringsArray,
+  ...expressions: unknown[]
+): string {
+  let result = strings[0];
+
+  for (let i = 0; i < expressions.length; i++) {
+    const expr = expressions[i];
+
+    // Convert expression to string
+    // Binding proxies will return "${state.x}" via their toString()
+    result += String(expr);
+    result += strings[i + 1]!;
+  }
+
+  return result!.trim();
+}
+
+/**
+ * Type helper for defining state shape.
+ * Use with state proxy for better IDE support in complex scenarios.
+ *
+ * @example
+ * ```typescript
+ * type MyState = { user: { name: string; age: number } };
+ * const typedState = state as StateProxy<MyState>;
+ * ```
+ */
+export type StateProxy<T> = {
+  [K in keyof T]: T[K] extends object
+    ? StateProxy<T[K]> & { toString(): string }
+    : { toString(): string };
+} & { toString(): string };
+
+/**
+ * Type helper for item proxy in lists.
+ */
+export type ItemProxy<T> = StateProxy<T>;