@zoijs/core 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -4,6 +4,26 @@ 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.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.2.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/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.

package/src/index.js

@@ -10,5 +10,6 @@ export { mount } from "./core/mount.js";
 export { each } from "./core/each.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);