@bquery/bquery 1.1.2 → 1.3.0

package/src/view/evaluate.ts

@@ -0,0 +1,274 @@
+import { isComputed, isSignal, type Signal } from '../reactive/index';
+import type { BindingContext } from './types';
+
+/** Maximum number of cached expression functions before LRU eviction */
+const MAX_CACHE_SIZE = 500;
+
+/** Compiled function type for expression evaluation */
+type CompiledFn = (ctx: BindingContext) => unknown;
+
+/**
+ * Simple LRU cache for compiled expression functions.
+ * Uses Map's insertion order to track recency - accessed items are re-inserted.
+ * @internal
+ */
+class LRUCache {
+  private cache = new Map<string, CompiledFn>();
+  private maxSize: number;
+
+  constructor(maxSize: number) {
+    this.maxSize = maxSize;
+  }
+
+  get(key: string): CompiledFn | undefined {
+    const value = this.cache.get(key);
+    if (value !== undefined) {
+      // Move to end (most recently used) by re-inserting
+      this.cache.delete(key);
+      this.cache.set(key, value);
+    }
+    return value;
+  }
+
+  set(key: string, value: CompiledFn): void {
+    // Delete first if exists to update insertion order
+    if (this.cache.has(key)) {
+      this.cache.delete(key);
+    } else if (this.cache.size >= this.maxSize) {
+      // Evict oldest (first) entry
+      const oldest = this.cache.keys().next().value;
+      if (oldest !== undefined) {
+        this.cache.delete(oldest);
+      }
+    }
+    this.cache.set(key, value);
+  }
+
+  clear(): void {
+    this.cache.clear();
+  }
+
+  get size(): number {
+    return this.cache.size;
+  }
+}
+
+/** LRU cache for compiled evaluate functions, keyed by expression string */
+const evaluateCache = new LRUCache(MAX_CACHE_SIZE);
+
+/** LRU cache for compiled evaluateRaw functions, keyed by expression string */
+const evaluateRawCache = new LRUCache(MAX_CACHE_SIZE);
+
+/**
+ * Clears all cached compiled expression functions.
+ * Call this when unmounting views or to free memory after heavy template usage.
+ *
+ * @example
+ * ```ts
+ * import { clearExpressionCache } from 'bquery/view';
+ *
+ * // After destroying a view or when cleaning up
+ * clearExpressionCache();
+ * ```
+ */
+export const clearExpressionCache = (): void => {
+  evaluateCache.clear();
+  evaluateRawCache.clear();
+};
+
+/**
+ * Creates a proxy that lazily unwraps signals/computed only when accessed.
+ * This avoids subscribing to signals that aren't referenced in the expression.
+ * @internal
+ */
+const createLazyContext = (context: BindingContext): BindingContext =>
+  new Proxy(context, {
+    get(target, prop: string | symbol) {
+      // Only handle string keys for BindingContext indexing
+      if (typeof prop !== 'string') {
+        return Reflect.get(target, prop);
+      }
+      const value = target[prop];
+      // Auto-unwrap signals/computed only when actually accessed
+      if (isSignal(value) || isComputed(value)) {
+        return (value as Signal<unknown>).value;
+      }
+      return value;
+    },
+    has(target, prop: string | symbol) {
+      // Required for `with` statement to resolve identifiers correctly
+      if (typeof prop !== 'string') {
+        return Reflect.has(target, prop);
+      }
+      return prop in target;
+    },
+  });
+
+/**
+ * Evaluates an expression in the given context using `new Function()`.
+ *
+ * Signals and computed values in the context are lazily unwrapped only when
+ * accessed by the expression, avoiding unnecessary subscriptions to unused values.
+ *
+ * @security **WARNING:** This function uses dynamic code execution via `new Function()`.
+ * - NEVER pass expressions derived from user input or untrusted sources
+ * - Expressions should only come from developer-controlled templates
+ * - Malicious expressions can access and exfiltrate context data
+ * - Consider this equivalent to `eval()` in terms of security implications
+ *
+ * @internal
+ */
+export const evaluate = <T = unknown>(expression: string, context: BindingContext): T => {
+  try {
+    // Create a proxy that lazily unwraps signals/computed on access
+    const lazyContext = createLazyContext(context);
+
+    // Use cached function or compile and cache a new one
+    let fn = evaluateCache.get(expression);
+    if (!fn) {
+      // Use `with` to enable direct property access from proxy scope.
+      // Note: `new Function()` runs in non-strict mode, so `with` is allowed.
+      fn = new Function('$ctx', `with($ctx) { return (${expression}); }`) as (
+        ctx: BindingContext
+      ) => unknown;
+      evaluateCache.set(expression, fn);
+    }
+    return fn(lazyContext) as T;
+  } catch (error) {
+    console.error(`bQuery view: Error evaluating "${expression}"`, error);
+    return undefined as T;
+  }
+};
+
+/**
+ * Evaluates an expression and returns the raw value (for signal access).
+ *
+ * @security **WARNING:** Uses dynamic code execution. See {@link evaluate} for security notes.
+ * @internal
+ */
+export const evaluateRaw = <T = unknown>(expression: string, context: BindingContext): T => {
+  try {
+    // Use cached function or compile and cache a new one
+    let fn = evaluateRawCache.get(expression);
+    if (!fn) {
+      // Use `with` to enable direct property access from context scope.
+      // Unlike `evaluate`, we don't use a lazy proxy - values are accessed directly.
+      fn = new Function('$ctx', `with($ctx) { return (${expression}); }`) as (
+        ctx: BindingContext
+      ) => unknown;
+      evaluateRawCache.set(expression, fn);
+    }
+    return fn(context) as T;
+  } catch (error) {
+    console.error(`bQuery view: Error evaluating "${expression}"`, error);
+    return undefined as T;
+  }
+};
+
+/**
+ * Parses object expression like "{ active: isActive, disabled: !enabled }".
+ * Handles nested structures like function calls, arrays, and template literals.
+ * @internal
+ */
+export const parseObjectExpression = (expression: string): Record<string, string> => {
+  const result: Record<string, string> = {};
+
+  // Remove outer braces and trim
+  const inner = expression
+    .trim()
+    .replace(/^\{|\}$/g, '')
+    .trim();
+  if (!inner) return result;
+
+  // Split by comma at depth 0, respecting strings and nesting
+  const parts: string[] = [];
+  let current = '';
+  let depth = 0;
+  let inString: string | null = null;
+
+  for (let i = 0; i < inner.length; i++) {
+    const char = inner[i];
+    const prevChar = i > 0 ? inner[i - 1] : '';
+
+    // Handle string literals (including escape sequences)
+    if ((char === '"' || char === "'" || char === '`') && prevChar !== '\\') {
+      if (inString === null) {
+        inString = char;
+      } else if (inString === char) {
+        inString = null;
+      }
+      current += char;
+      continue;
+    }
+
+    // Skip if inside string
+    if (inString !== null) {
+      current += char;
+      continue;
+    }
+
+    // Track nesting depth for parentheses, brackets, and braces
+    if (char === '(' || char === '[' || char === '{') {
+      depth++;
+      current += char;
+    } else if (char === ')' || char === ']' || char === '}') {
+      depth--;
+      current += char;
+    } else if (char === ',' && depth === 0) {
+      // Top-level comma - split point
+      parts.push(current.trim());
+      current = '';
+    } else {
+      current += char;
+    }
+  }
+
+  // Add the last part
+  if (current.trim()) {
+    parts.push(current.trim());
+  }
+
+  // Parse each part to extract key and value
+  for (const part of parts) {
+    // Find the first colon at depth 0 (to handle ternary operators in values)
+    let colonIndex = -1;
+    let partDepth = 0;
+    let partInString: string | null = null;
+
+    for (let i = 0; i < part.length; i++) {
+      const char = part[i];
+      const prevChar = i > 0 ? part[i - 1] : '';
+
+      if ((char === '"' || char === "'" || char === '`') && prevChar !== '\\') {
+        if (partInString === null) {
+          partInString = char;
+        } else if (partInString === char) {
+          partInString = null;
+        }
+        continue;
+      }
+
+      if (partInString !== null) continue;
+
+      if (char === '(' || char === '[' || char === '{') {
+        partDepth++;
+      } else if (char === ')' || char === ']' || char === '}') {
+        partDepth--;
+      } else if (char === ':' && partDepth === 0) {
+        colonIndex = i;
+        break;
+      }
+    }
+
+    if (colonIndex > -1) {
+      const key = part
+        .slice(0, colonIndex)
+        .trim()
+        .replace(/^['"]|['"]$/g, '');
+      const value = part.slice(colonIndex + 1).trim();
+      result[key] = value;
+    }
+  }
+
+  return result;
+};

package/src/view/index.ts

@@ -0,0 +1,112 @@
+/**
+ * Declarative DOM bindings via data attributes.
+ *
+ * This module provides Vue/Svelte-style template directives without
+ * requiring a compiler. Bindings are evaluated at runtime using
+ * bQuery's reactive system. Features include:
+ * - Conditional rendering (bq-if)
+ * - List rendering (bq-for)
+ * - Two-way binding (bq-model)
+ * - Class binding (bq-class)
+ * - Text/HTML binding (bq-text, bq-html)
+ * - Attribute binding (bq-bind)
+ * - Event binding (bq-on)
+ *
+ * ## Security Considerations
+ *
+ * **WARNING:** This module uses `new Function()` to evaluate expressions at runtime.
+ * This is similar to Vue/Alpine's approach but carries inherent security risks:
+ *
+ * - **NEVER** use expressions derived from user input or untrusted sources
+ * - Expressions should only come from developer-controlled templates
+ * - The context object should not contain sensitive data that could be exfiltrated
+ * - For user-generated content, use static bindings with sanitized values instead
+ *
+ * Since bQuery is runtime-only (no build-time compilation), expressions are evaluated
+ * dynamically. If your application loads templates from external sources (APIs, databases),
+ * ensure they are trusted and validated before mounting.
+ *
+ * ## Content Security Policy (CSP) Compatibility
+ *
+ * **IMPORTANT:** This module requires `'unsafe-eval'` in your CSP `script-src` directive.
+ * The `new Function()` constructor used for expression evaluation will be blocked by
+ * strict CSP policies that omit `'unsafe-eval'`.
+ *
+ * ### Required CSP Header
+ * ```
+ * Content-Security-Policy: script-src 'self' 'unsafe-eval';
+ * ```
+ *
+ * ### CSP-Strict Alternatives
+ *
+ * If your application requires a strict CSP without `'unsafe-eval'`, consider these alternatives:
+ *
+ * 1. **Use bQuery's core reactive system directly** - Bind signals to DOM elements manually
+ *    using `effect()` without the view module's template directives:
+ *    ```ts
+ *    import { signal, effect } from 'bquery/reactive';
+ *    import { $ } from 'bquery';
+ *
+ *    const count = signal(0);
+ *    effect(() => {
+ *      $('#counter').text(String(count.value));
+ *    });
+ *    ```
+ *
+ * 2. **Use bQuery's component module** - Web Components with typed props don't require
+ *    dynamic expression evaluation:
+ *    ```ts
+ *    import { component } from 'bquery/component';
+ *    component('my-counter', {
+ *      props: { count: { type: Number } },
+ *      render: ({ props }) => `<span>${props.count}</span>`,
+ *    });
+ *    ```
+ *
+ * 3. **Pre-compile templates at build time** - Use a build step to transform bq-* attributes
+ *    into static JavaScript (similar to Svelte/Vue SFC compilation). This is outside bQuery's
+ *    scope but can be achieved with custom Vite/Rollup plugins.
+ *
+ * The view module is designed for rapid prototyping and applications where CSP flexibility
+ * is acceptable. For security-critical applications requiring strict CSP, use the alternatives above.
+ *
+ * @module bquery/view
+ *
+ * @example
+ * ```html
+ * <div id="app">
+ *   <input bq-model="name" />
+ *   <p bq-text="greeting"></p>
+ *   <ul>
+ *     <li bq-for="item in items" bq-text="item.name"></li>
+ *   </ul>
+ *   <button bq-on:click="handleClick">Click me</button>
+ *   <div bq-if="showDetails" bq-class="{ active: isActive }">
+ *     Details here
+ *   </div>
+ * </div>
+ * ```
+ *
+ * ```ts
+ * import { mount } from 'bquery/view';
+ * import { signal } from 'bquery/reactive';
+ *
+ * mount('#app', {
+ *   name: signal('World'),
+ *   greeting: computed(() => `Hello, ${name.value}!`),
+ *   items: signal([{ name: 'Item 1' }, { name: 'Item 2' }]),
+ *   showDetails: signal(true),
+ *   isActive: signal(false),
+ *   handleClick: () => console.log('Clicked!'),
+ * });
+ * ```
+ */
+
+export { clearExpressionCache } from './evaluate';
+export { createTemplate, mount } from './mount';
+export type { BindingContext, MountOptions, View } from './types';
+
+/**
+ * Re-export reactive primitives for convenience.
+ */
+export { batch, computed, effect, signal } from '../reactive/index';

package/src/view/mount.ts

@@ -0,0 +1,200 @@
+import type { CleanupFn } from '../reactive/index';
+import {
+  createForHandler,
+  handleBind,
+  handleClass,
+  handleHtml,
+  handleIf,
+  handleModel,
+  handleOn,
+  handleRef,
+  handleShow,
+  handleStyle,
+  handleText,
+} from './directives/index';
+import { processChildren, processElement, type DirectiveHandlers } from './process';
+import type { BindingContext, MountOptions, View } from './types';
+
+/**
+ * Mounts a reactive view to an element.
+ *
+ * @param selector - CSS selector or Element
+ * @param context - Binding context with signals, computed, and functions
+ * @param options - Mount options
+ * @returns The mounted View instance
+ *
+ * @security **WARNING:** Directive expressions (bq-text, bq-if, bq-on, etc.) are evaluated
+ * using `new Function()` at runtime. This means:
+ * - Template attributes must come from trusted sources only
+ * - NEVER load templates containing bq-* attributes from user input or untrusted APIs
+ * - If you must use external templates, validate/sanitize attribute values first
+ *
+ * @example
+ * ```ts
+ * import { mount } from 'bquery/view';
+ * import { signal, computed } from 'bquery/reactive';
+ *
+ * const name = signal('World');
+ * const greeting = computed(() => `Hello, ${name.value}!`);
+ * const items = signal([
+ *   { id: 1, text: 'Item 1' },
+ *   { id: 2, text: 'Item 2' },
+ * ]);
+ *
+ * const view = mount('#app', {
+ *   name,
+ *   greeting,
+ *   items,
+ *   addItem: () => {
+ *     items.value = [...items.value, { id: Date.now(), text: 'New Item' }];
+ *   },
+ * });
+ *
+ * // Later, cleanup
+ * view.destroy();
+ * ```
+ */
+export const mount = (
+  selector: string | Element,
+  context: BindingContext,
+  options: MountOptions = {}
+): View => {
+  const { prefix = 'bq', sanitize = true } = options;
+
+  const el = typeof selector === 'string' ? document.querySelector(selector) : selector;
+
+  if (!el) {
+    throw new Error(`bQuery view: Element "${selector}" not found.`);
+  }
+
+  // Reject if root element has bq-for directive
+  // bq-for replaces the element with a placeholder comment, which would leave View.el detached
+  if (el.hasAttribute(`${prefix}-for`)) {
+    throw new Error(
+      `bQuery view: Cannot mount on element with ${prefix}-for directive. ` +
+        `Wrap the ${prefix}-for element in a container instead.`
+    );
+  }
+
+  const cleanups: CleanupFn[] = [];
+
+  const handlers: DirectiveHandlers = {
+    text: handleText,
+    html: handleHtml(sanitize),
+    if: handleIf,
+    show: handleShow,
+    class: handleClass,
+    style: handleStyle,
+    model: handleModel,
+    ref: handleRef,
+    for: createForHandler({
+      prefix,
+      processElement: (node, nodeContext, nodePrefix, nodeCleanups) =>
+        processElement(node, nodeContext, nodePrefix, nodeCleanups, handlers),
+      processChildren: (node, nodeContext, nodePrefix, nodeCleanups) =>
+        processChildren(node, nodeContext, nodePrefix, nodeCleanups, handlers),
+    }),
+    bind: handleBind,
+    on: handleOn,
+  };
+
+  const processWithHandlers = (
+    node: Element,
+    nodeContext: BindingContext,
+    nodeCleanups: CleanupFn[]
+  ) => {
+    // Check if element has bq-for before processing
+    // bq-for replaces the element and handles its children internally
+    const hasFor = node.hasAttribute(`${prefix}-for`);
+
+    processElement(node, nodeContext, prefix, nodeCleanups, handlers);
+
+    // Skip processChildren if bq-for was on this element - it handles children itself
+    if (!hasFor) {
+      processChildren(node, nodeContext, prefix, nodeCleanups, handlers);
+    }
+  };
+
+  // Process the root element and its children
+  processWithHandlers(el, context, cleanups);
+
+  return {
+    el,
+    context,
+
+    update: (newContext: Partial<BindingContext>) => {
+      Object.assign(context, newContext);
+    },
+
+    destroy: () => {
+      for (const cleanup of cleanups) {
+        cleanup();
+      }
+      cleanups.length = 0;
+    },
+  };
+};
+
+/**
+ * Creates a reactive template function.
+ *
+ * @param template - HTML template string
+ * @returns A function that creates a mounted element with the given context
+ *
+ * @example
+ * ```ts
+ * import { createTemplate } from 'bquery/view';
+ * import { signal } from 'bquery/reactive';
+ *
+ * const TodoItem = createTemplate(`
+ *   <li bq-class="{ completed: done }">
+ *     <input type="checkbox" bq-model="done" />
+ *     <span bq-text="text"></span>
+ *   </li>
+ * `);
+ *
+ * const item = TodoItem({
+ *   done: signal(false),
+ *   text: 'Buy groceries',
+ * });
+ *
+ * document.querySelector('#list').append(item.el);
+ * ```
+ */
+export const createTemplate = (
+  template: string,
+  options: MountOptions = {}
+): ((context: BindingContext) => View) => {
+  return (context: BindingContext) => {
+    const container = document.createElement('div');
+    container.innerHTML = template.trim();
+
+    const el = container.firstElementChild;
+    if (!el) {
+      throw new Error('bQuery view: Template must contain a single root element.');
+    }
+
+    // We know at least one element exists (firstElementChild is not null above)
+    // Reject if there are multiple root elements
+    if (container.childElementCount > 1) {
+      throw new Error(
+        `bQuery view: Template must contain exactly one root element, found ${container.childElementCount}.`
+      );
+    }
+
+    const { prefix = 'bq' } = options;
+    // Reject templates with bq-for or bq-if on the root element
+    // These directives replace the element with a placeholder comment, which would leave View.el detached
+    // Since processing happens while el is still in the temporary container, the placeholder
+    // would remain there while view.el is inserted elsewhere, causing desync on future toggles
+    if (el.hasAttribute(`${prefix}-for`) || el.hasAttribute(`${prefix}-if`)) {
+      const directive = el.hasAttribute(`${prefix}-for`) ? 'for' : 'if';
+      throw new Error(
+        `bQuery view: Template root element cannot have ${prefix}-${directive} directive. ` +
+          `Wrap the ${prefix}-${directive} element in a container instead.`
+      );
+    }
+
+    return mount(el, context, options);
+  };
+};

package/src/view/process.ts

@@ -0,0 +1,92 @@
+import type { CleanupFn } from '../reactive/index';
+import type { BindingContext, DirectiveHandler } from './types';
+
+export type DirectiveHandlers = {
+  text: DirectiveHandler;
+  html: DirectiveHandler;
+  if: DirectiveHandler;
+  show: DirectiveHandler;
+  class: DirectiveHandler;
+  style: DirectiveHandler;
+  model: DirectiveHandler;
+  ref: DirectiveHandler;
+  for: DirectiveHandler;
+  bind: (attrName: string) => DirectiveHandler;
+  on: (eventName: string) => DirectiveHandler;
+};
+
+/**
+ * Processes a single element for directives.
+ * @internal
+ */
+export const processElement = (
+  el: Element,
+  context: BindingContext,
+  prefix: string,
+  cleanups: CleanupFn[],
+  handlers: DirectiveHandlers
+): void => {
+  const attributes = Array.from(el.attributes);
+
+  for (const attr of attributes) {
+    const { name, value } = attr;
+
+    if (!name.startsWith(`${prefix}-`)) continue;
+
+    const directive = name.slice(prefix.length + 1); // Remove prefix and dash
+
+    // Handle bq-for specially (creates new scope)
+    if (directive === 'for') {
+      handlers.for(el, value, context, cleanups);
+      return; // Don't process children, bq-for handles it
+    }
+
+    // Handle other directives
+    if (directive === 'text') {
+      handlers.text(el, value, context, cleanups);
+    } else if (directive === 'html') {
+      handlers.html(el, value, context, cleanups);
+    } else if (directive === 'if') {
+      handlers.if(el, value, context, cleanups);
+    } else if (directive === 'show') {
+      handlers.show(el, value, context, cleanups);
+    } else if (directive === 'class') {
+      handlers.class(el, value, context, cleanups);
+    } else if (directive === 'style') {
+      handlers.style(el, value, context, cleanups);
+    } else if (directive === 'model') {
+      handlers.model(el, value, context, cleanups);
+    } else if (directive === 'ref') {
+      handlers.ref(el, value, context, cleanups);
+    } else if (directive.startsWith('bind:')) {
+      const attrName = directive.slice(5);
+      handlers.bind(attrName)(el, value, context, cleanups);
+    } else if (directive.startsWith('on:')) {
+      const eventName = directive.slice(3);
+      handlers.on(eventName)(el, value, context, cleanups);
+    }
+  }
+};
+
+/**
+ * Recursively processes children of an element.
+ * @internal
+ */
+export const processChildren = (
+  el: Element,
+  context: BindingContext,
+  prefix: string,
+  cleanups: CleanupFn[],
+  handlers: DirectiveHandlers
+): void => {
+  const children = Array.from(el.children);
+  for (const child of children) {
+    // Skip if element has bq-for (handled separately)
+    if (!child.hasAttribute(`${prefix}-for`)) {
+      processElement(child, context, prefix, cleanups, handlers);
+      processChildren(child, context, prefix, cleanups, handlers);
+    } else {
+      processElement(child, context, prefix, cleanups, handlers);
+    }
+  }
+};