@zoijs/core 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -4,6 +4,39 @@ All notable changes to Zoijs are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/), and Zoijs follows
 [Semantic Versioning](https://semver.org/) (see `VERSIONING.md`).
 
+## [1.3.0] — 2026-06-26
+
+### Added
+- **`boundary(child, fallback)`.** A render-time error boundary: it renders
+  `child`, and if `child` throws **synchronously while building its markup** (a
+  setup/render error that would otherwise break the whole `mount`), it disposes the
+  partial work — so an `effect` created before the throw can't leak — and renders
+  `fallback` (a value, or `(error) => value`) instead. Catches synchronous
+  setup/render throws only; errors in reactive *updates* are already contained per
+  binding, and *async* errors belong to `@zoijs/resource` / `@zoijs/action`'s
+  `error()` state. Logs in dev, silent in production. The public surface is now
+  **nine** functions (additive MINOR). See [RFC 0004](docs/rfcs/0004-error-boundary.md).
+
+## [1.2.0] — 2026-06-26
+
+### Added
+- **`effect(fn)`.** A public reactive effect — runs a side effect immediately and
+  re-runs whenever a reactive value it reads changes (automatic dependency
+  tracking, microtask-batched). The function may return a cleanup that runs before
+  the next run and on dispose (same convention as a `ref`); `effect` auto-disposes
+  with its owner (component / list item) and returns `{ dispose }` for early
+  teardown. This is the public completion of the reactive trio (`createState` /
+  `computed` / `effect`) — the engine already used it internally for bindings. Use
+  it for side effects *outside* the view (persist on change, sync `document.title`,
+  drive a non-Zoijs widget); for on-screen content, keep using a binding
+  (`${() => …}`). The public surface is now **eight** functions (additive MINOR per
+  `VERSIONING.md`). See [RFC 0003](docs/rfcs/0003-effect-and-svg.md).
+
+### Notes
+- The **`svg`** helper considered alongside `effect` was **deferred**: templates
+  rooted at `<svg>` already render correctly, and only dynamic-SVG *composition* is
+  affected — a minority need. See [RFC 0003](docs/rfcs/0003-effect-and-svg.md) §6.
+
 ## [1.1.0] — 2026-06-25
 
 ### Added

package/README.md

@@ -54,7 +54,7 @@ No build step is required — the framework is plain ES modules.
 
 # run the counter example (serves the project root over http so ES modules resolve)
 npm run dev
-# then open: http://localhost:3000/examples/counter/   (keep the trailing slash)
+# then open: http://localhost:7310/examples/counter/   (keep the trailing slash)
 
 # run the tests (DOM tests run automatically via jsdom)
 npm test
@@ -81,7 +81,7 @@ npx playwright install chromium firefox webkit
 npm run test:browser
 ```
 
-Playwright starts a static server automatically (`npx serve` on port 3000) — still no build step.
+Playwright starts a static server automatically (`npx serve` on port 7310) — still no build step.
 
 ## Browser support
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zoijs/core",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Zoijs — a beginner-friendly, no-build, no-Virtual-DOM frontend framework. Plain HTML, CSS, and JavaScript.",
   "type": "module",
   "main": "src/index.js",
@@ -53,7 +53,7 @@
     "test:unit": "node --test",
     "test:types": "tsc --noEmit -p tsconfig.json",
     "test:browser": "playwright test",
-    "dev": "npx serve -l 3000 ."
+    "dev": "npx serve -l 7310 ."
   },
   "devDependencies": {
     "@playwright/test": "^1.61.1",

package/src/core/boundary.js

@@ -0,0 +1,34 @@
+// boundary.js — render-time error containment (RFC 0004).
+//
+// boundary(child, fallback) renders `child`; if it throws SYNCHRONOUSLY while
+// building its markup (a setup/render throw that would otherwise break the whole
+// mount), the partial work is torn down and `fallback(error)` is rendered instead.
+//
+// Errors in reactive UPDATES are already contained per-binding by the core; async
+// errors belong to @zoijs/resource / @zoijs/action. This catches the one
+// remaining case — the synchronous setup/render throw.
+
+import { createOwner, runWithOwner, disposeOwner } from "../reactivity/owner.js";
+import { isDev } from "../reactivity/env.js";
+
+/**
+ * @template C, F
+ * @param {(() => C) | C} child     a component (or value) to render
+ * @param {((error: unknown) => F) | F} fallback  a value, or (error) => value, shown if child throws
+ * @returns {C | F} the child's result, or the fallback's, for a template slot
+ */
+export function boundary(child, fallback) {
+  // Run setup in a child scope so anything it creates before a throw (notably an
+  // effect, which runs immediately) can be disposed — no zombies. On success the
+  // scope nests under the surrounding owner and is disposed with it.
+  const owner = createOwner();
+  try {
+    return runWithOwner(owner, () => (typeof child === "function" ? child() : child));
+  } catch (err) {
+    disposeOwner(owner);
+    if (isDev()) {
+      console.error("Zoijs: boundary caught an error during render; showing fallback.", err);
+    }
+    return typeof fallback === "function" ? fallback(err) : fallback;
+  }
+}

package/src/core/each.js

@@ -17,8 +17,8 @@
  * @param {Function|Array} items    a function returning the array, or an array
  * @param {Function} keyFn          item -> unique key
  * @param {Function} renderFn       item -> html() result
- * @returns {{ __easyEach: true, items: any, keyFn: Function, renderFn: Function }}
+ * @returns {{ __zoijsEach: true, items: any, keyFn: Function, renderFn: Function }}
  */
 export function each(items, keyFn, renderFn) {
-  return { __easyEach: true, items, keyFn, renderFn };
+  return { __zoijsEach: true, items, keyFn, renderFn };
 }

package/src/core/renderer.js

@@ -239,7 +239,7 @@ function renderChild(value) {
 // ---- keyed list binding ------------------------------------------------------
 
 function isEach(v) {
-  return v != null && typeof v === "object" && v.__easyEach === true;
+  return v != null && typeof v === "object" && v.__zoijsEach === true;
 }
 
 function setupKeyedList(anchor, marker) {

package/src/index.d.ts

@@ -91,6 +91,40 @@ export function createState<T>(initial: T, equals?: (a: T, b: T) => boolean): St
  */
 export function computed<T>(fn: () => T, equals?: (a: T, b: T) => boolean): Computed<T>;
 
+/** A disposable handle returned by {@link effect}. */
+export interface EffectHandle {
+  /** Dispose the effect now. It also auto-disposes with its owner (component/list item). */
+  dispose(): void;
+}
+
+/**
+ * Run a side effect that re-runs whenever a reactive value it reads changes.
+ * Runs once immediately, then again (batched on a microtask) on any change.
+ * Dependencies are tracked automatically — there is no dependency array.
+ *
+ * The function may return a cleanup function (same convention as a `ref`); it
+ * runs **before the next run** and **on dispose**. Use the return value for
+ * per-run teardown — `onCleanup` is component-scoped (fires on unmount), not
+ * per-run.
+ *
+ * Created inside a component or list item, it auto-disposes with that scope;
+ * created at module top level, it lives until you call `dispose()`.
+ *
+ * ```ts
+ * // persist on change
+ * effect(() => localStorage.setItem("theme", theme.get()));
+ *
+ * // per-run cleanup
+ * effect(() => {
+ *   const id = setInterval(() => poll(query.get()), 1000);
+ *   return () => clearInterval(id);
+ * });
+ * ```
+ *
+ * For reactive *content on screen*, use a binding (`${() => …}`), not an effect.
+ */
+export function effect(fn: () => void | (() => void)): EffectHandle;
+
 /**
  * Keyed list rendering. `items` may be a reactive function or a plain array;
  * `keyFn` returns a stable unique key; `renderFn` returns the template for one item.
@@ -110,6 +144,27 @@ export function each<T>(
   renderFn: (item: T) => TemplateResult
 ): EachResult;
 
+/**
+ * Render `child`; if it **throws synchronously while building its markup** (a
+ * setup/render error that would otherwise break the whole `mount`), tear down the
+ * partial work and render `fallback` instead. Place the call in a template slot.
+ *
+ * Catches synchronous setup/render throws only. Errors in reactive *updates* are
+ * already contained per binding by the core; *async* errors belong to
+ * `@zoijs/resource` / `@zoijs/action`'s `error()` state. It renders once (no reset
+ * — re-mount the subtree to retry), logs in dev, and is silent in production.
+ *
+ * ```ts
+ * html`<section>
+ *   ${boundary(() => RiskyWidget(), (err) => html`<p>Couldn't load this.</p>`)}
+ * </section>`
+ * ```
+ */
+export function boundary<C, F>(
+  child: (() => C) | C,
+  fallback: ((error: unknown) => F) | F
+): C | F;
+
 /** Toggle development warnings (default: `dev` is `true`). */
 export function configure(options: { dev?: boolean }): void;
 

package/src/index.js

@@ -8,7 +8,9 @@
 export { html } from "./core/html.js";
 export { mount } from "./core/mount.js";
 export { each } from "./core/each.js";
+export { boundary } from "./core/boundary.js";
 export { createState } from "./reactivity/state.js";
 export { computed } from "./reactivity/computed.js";
+export { effect } from "./reactivity/effect.js";
 export { configure } from "./reactivity/env.js";
 export { onCleanup } from "./reactivity/owner.js";

package/src/reactivity/core.js

@@ -105,6 +105,7 @@ function runComputation(node) {
     node.state = CLEAN;
     return;
   }
+  if (node.isEffect) runEffectCleanup(node); // per-run teardown before re-running
   cleanupSources(node);
   const previousObserver = currentObserver;
   currentObserver = node;
@@ -119,7 +120,13 @@ function runComputation(node) {
   } finally {
     currentObserver = previousObserver;
   }
-  if (threw || node.isEffect) return;
+  if (node.isEffect) {
+    // An effect may return a cleanup function (same convention as a ref): it runs
+    // before the next run and on dispose. Anything else is ignored.
+    if (!threw) node.cleanup = typeof result === "function" ? result : null;
+    return;
+  }
+  if (threw) return;
   if (!node.equals(node.value, result)) {
     node.value = result;
     // Value changed → promote observers (currently CHECK) to DIRTY so they update.
@@ -132,10 +139,23 @@ function cleanupSources(node) {
   node.sources.clear();
 }
 
+/** Run (and clear) an effect's returned cleanup — before a re-run and on dispose. */
+function runEffectCleanup(node) {
+  const cleanup = node.cleanup;
+  if (!cleanup) return;
+  node.cleanup = null;
+  try {
+    cleanup();
+  } catch (err) {
+    console.error("Zoijs: an effect cleanup threw (other bindings keep working):", err);
+  }
+}
+
 function disposeNode(node) {
   if (node.disposed) return;
   node.disposed = true;
   cleanupSources(node);
+  if (node.isEffect) runEffectCleanup(node); // final cleanup on dispose
 }
 
 const warned = new WeakSet();
@@ -186,6 +206,7 @@ export function effect(fn) {
     isEffect: true,
     disposed: false,
     equals: Object.is,
+    cleanup: null,
   };
   onCleanup(() => disposeNode(node)); // disposed with its owner scope
   runComputation(node);