dalila 1.1.1 → 1.2.0

package/README.md

@@ -10,6 +10,7 @@ Dalila is a **SPA**, **DOM-first**, **HTML natural** framework based on **signal
 - 🚀 **Signals-based reactivity** - Automatic dependency tracking
 - 🎯 **DOM-first rendering** - Direct DOM manipulation, no Virtual DOM
 - 🔄 **Scope-based lifecycle** - Automatic cleanup (best effort)
+- 🧿 **DOM lifecycle watchers** — `watch()` + helpers (`useEvent`, `useInterval`, `useTimeout`, `useFetch`) with scope-based cleanup
 - 🛣️ **SPA router** - Basic routing with loaders and AbortSignal
 - 📦 **Context system** - Reactive dependency injection
 - 🔧 **Scheduler & batching** - Group updates into a single frame
@@ -95,6 +96,80 @@ effectAsync(async (signal) => {
 });
 ```
 
+### Lifecycle / Cleanup (Scopes + DOM)
+
+Dalila is DOM-first. That means a lot of your "lifecycle" work is not React-like rendering —
+it's **attaching listeners, timers, and async work to real DOM nodes**.
+
+Dalila's rule is simple:
+
+- **Inside a scope** → cleanup is automatic on `scope.dispose()`
+- **Outside a scope** → you must call `dispose()` manually (Dalila warns once)
+
+#### `watch(node, fn)` — DOM lifecycle primitive
+
+`watch()` runs a reactive function while a DOM node is connected.
+When the node disconnects, the effect is disposed. If the node reconnects later, it starts again.
+It's the primitive that enables DOM lifecycle without a VDOM.
+
+```ts
+import { watch, signal } from "dalila";
+
+const count = signal(0);
+
+const dispose = watch(someNode, () => {
+  // Reactive while connected because watch() runs this inside an effect()
+  someNode.textContent = String(count());
+});
+
+// later (optional if inside a scope)
+dispose();
+```
+
+#### Lifecycle helpers
+
+Built on the same mental model, Dalila provides small helpers that always return an **idempotent** `dispose()`:
+`useEvent`, `useInterval`, `useTimeout`, `useFetch`.
+
+**Inside a scope (recommended)**
+
+```ts
+import { createScope, withScope, useEvent, useInterval, useFetch } from "dalila";
+
+const scope = createScope();
+
+withScope(scope, () => {
+  useEvent(button, "click", onClick);
+  useInterval(tick, 1000);
+
+  const user = useFetch("/api/user");
+
+  // Optional manual cleanup:
+  // user.dispose();
+});
+
+scope.dispose(); // stops listener, interval, and aborts fetch
+```
+
+Disposing the scope stops listeners/timers and aborts in-flight async work created inside the scope.
+
+**Outside a scope (manual cleanup)**
+
+```ts
+import { useInterval } from "dalila";
+
+const dispose = useInterval(() => console.log("tick"), 1000);
+
+// later...
+dispose(); // required
+```
+
+#### Why helpers vs native APIs?
+
+You *can* use `addEventListener` / `setTimeout` / `setInterval` directly, but then cleanup becomes "manual discipline".
+In a DOM-first app, listeners/timers are the #1 source of silent leaks when the UI changes.
+Scopes make cleanup a **default**, not a convention — so UI changes don't silently leak listeners, timers, or in-flight async work.
+
 ### Conditional Rendering
 
 Dalila provides two primitives for branching UI:

package/dist/core/index.d.ts

@@ -1,6 +1,6 @@
 export * from "./scope.js";
 export * from "./signal.js";
-export * from "./watch.js";
+export { watch, onMount, onCleanup, useEvent, useInterval, useTimeout, useFetch } from "./watch.js";
 export * from "./when.js";
 export * from "./match.js";
 export * from "./for.js";

package/dist/core/index.js

@@ -1,6 +1,6 @@
 export * from "./scope.js";
 export * from "./signal.js";
-export * from "./watch.js";
+export { watch, onMount, onCleanup, useEvent, useInterval, useTimeout, useFetch } from "./watch.js";
 export * from "./when.js";
 export * from "./match.js";
 export * from "./for.js";

package/dist/core/watch-testing.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Testing utilities for watch.ts
+ *
+ * This file is NOT exported in the public API (src/index.ts).
+ * It should only be imported directly by test files.
+ *
+ * @internal
+ */
+/**
+ * Reset all warning flags to their initial state.
+ * Use this in tests to ensure deterministic warning behavior.
+ */
+export declare function resetWarnings(): void;

package/dist/core/watch-testing.js

@@ -0,0 +1,16 @@
+/**
+ * Testing utilities for watch.ts
+ *
+ * This file is NOT exported in the public API (src/index.ts).
+ * It should only be imported directly by test files.
+ *
+ * @internal
+ */
+import { __resetWarningsForTests } from './watch.js';
+/**
+ * Reset all warning flags to their initial state.
+ * Use this in tests to ensure deterministic warning behavior.
+ */
+export function resetWarnings() {
+    __resetWarningsForTests();
+}

package/dist/core/watch.d.ts

@@ -1,19 +1,81 @@
 /**
- * Watch a DOM node and run an effect while it's connected.
+ * Reset warning flags (used by src/internal/watch-testing.ts for deterministic tests).
+ * @internal
+ */
+export declare function __resetWarningsForTests(): void;
+/**
+ * watch(node, fn)
+ *
+ * Runs `fn` inside a reactive effect while `node` is connected to the document.
+ * - Signal reads inside `fn` are tracked (because `fn` runs inside effect()).
+ * - When the node disconnects, the effect is disposed.
+ * - If the node reconnects later, the effect may start again (best-effort, based on DOM mutations).
  *
- * Fixes applied:
- * 1) Late-start effects now run inside the original scope (captured on watch()).
- * 2) watches uses WeakMap<Node,...> so we don't keep detached nodes alive.
- * 3) Observer disconnect uses ctx.watchCount (since WeakMap has no .size).
+ * Implementation notes / fixes:
+ * 1) Scope capture: the scope at watch() time is stored on the entry so effects that start later
+ *    still get created "inside" the original scope (fixes late-start effects created outside scope).
+ * 2) Memory safety: watches uses WeakMap<Node, ...> so detached nodes are not kept alive.
+ * 3) Observer lifecycle: we track ctx.watchCount (WeakMap has no .size) to know when to disconnect.
  */
 export declare function watch(node: Node, fn: () => void): () => void;
+/**
+ * onMount(fn)
+ *
+ * Executes fn immediately. Minimal semantic helper to document mount-time logic in DOM-first code.
+ * Unlike React, there's no deferred execution or batching — it runs synchronously.
+ */
 export declare function onMount(fn: () => void): void;
+/**
+ * onCleanup(fn)
+ *
+ * Registers fn to run when the current scope is disposed.
+ * If called outside a scope, fn is never called (no-op).
+ */
 export declare function onCleanup(fn: () => void): void;
+/**
+ * useEvent(target, type, handler, options?)
+ *
+ * Attaches an event listener and returns an idempotent dispose() function.
+ * - Inside a scope: listener is removed automatically on scope.dispose().
+ * - Outside a scope: you must call dispose() manually (warns once).
+ */
 export declare function useEvent<T extends EventTarget>(target: T, type: string, handler: (event: Event) => void, options?: AddEventListenerOptions): () => void;
+/**
+ * useInterval(fn, ms)
+ *
+ * Starts an interval and returns an idempotent dispose() function.
+ * - Inside a scope: interval is cleared automatically on scope.dispose().
+ * - Outside a scope: you must call dispose() manually (warns once).
+ */
 export declare function useInterval(fn: () => void, ms: number): () => void;
+/**
+ * useTimeout(fn, ms)
+ *
+ * Starts a timeout and returns an idempotent dispose() function.
+ * - Inside a scope: timeout is cleared automatically on scope.dispose().
+ * - Outside a scope: you must call dispose() manually (warns once).
+ */
 export declare function useTimeout(fn: () => void, ms: number): () => void;
+/**
+ * useFetch(url, options)
+ *
+ * Small convenience for "fetch + reactive state + abort" built on effectAsync().
+ * Returns { data, loading, error, dispose }.
+ *
+ * Behavior:
+ * - Runs the fetch inside effectAsync, which provides an AbortSignal.
+ * - If url is a function, it tracks signal reads (reactive).
+ * - Calling dispose() aborts the in-flight request (via effectAsync's signal).
+ * - Inside a scope: auto-disposed on scope.dispose().
+ * - Outside a scope: you must call dispose() manually (warns once).
+ *
+ * Limitations:
+ * - No refresh(), no caching, no invalidation.
+ * - For those features, use createResource / query().
+ */
 export declare function useFetch<T>(url: string | (() => string), options?: RequestInit): {
     data: () => T | null;
     loading: () => boolean;
     error: () => Error | null;
+    dispose: () => void;
 };

package/dist/core/watch.js

@@ -10,6 +10,14 @@ const documentWatchers = new WeakMap();
  */
 let hasWarnedNoScope = false;
 const warnedFunctions = new Set();
+/**
+ * Reset warning flags (used by src/internal/watch-testing.ts for deterministic tests).
+ * @internal
+ */
+export function __resetWarningsForTests() {
+    warnedFunctions.clear();
+    hasWarnedNoScope = false;
+}
 /**
  * Walk a subtree recursively, calling visitor for each node.
  * Supports any Node type (Element, Text, Comment, etc.) via childNodes.
@@ -23,8 +31,12 @@ function walkSubtree(root, visitor) {
     }
 }
 /**
- * Start a watch entry effect in the entry's captured scope (if any).
- * This fixes the critical bug where late-start effects were created outside scope.
+ * Start a watch entry effect inside the entry's captured scope (if any).
+ *
+ * Why:
+ * - `effect()` captures getCurrentScope() at creation time.
+ * - watch entries can start later (when a node becomes connected), so we must re-enter
+ *   the original scope to preserve cleanup semantics.
  */
 function startEntryEffect(entry) {
     if (entry.effectStarted || entry.cleanup)
@@ -105,12 +117,18 @@ function getDocumentWatchContext(doc) {
     return ctx;
 }
 /**
- * Watch a DOM node and run an effect while it's connected.
+ * watch(node, fn)
  *
- * Fixes applied:
- * 1) Late-start effects now run inside the original scope (captured on watch()).
- * 2) watches uses WeakMap<Node,...> so we don't keep detached nodes alive.
- * 3) Observer disconnect uses ctx.watchCount (since WeakMap has no .size).
+ * Runs `fn` inside a reactive effect while `node` is connected to the document.
+ * - Signal reads inside `fn` are tracked (because `fn` runs inside effect()).
+ * - When the node disconnects, the effect is disposed.
+ * - If the node reconnects later, the effect may start again (best-effort, based on DOM mutations).
+ *
+ * Implementation notes / fixes:
+ * 1) Scope capture: the scope at watch() time is stored on the entry so effects that start later
+ *    still get created "inside" the original scope (fixes late-start effects created outside scope).
+ * 2) Memory safety: watches uses WeakMap<Node, ...> so detached nodes are not kept alive.
+ * 3) Observer lifecycle: we track ctx.watchCount (WeakMap has no .size) to know when to disconnect.
  */
 export function watch(node, fn) {
     const currentScope = getCurrentScope();
@@ -160,9 +178,9 @@ export function watch(node, fn) {
         const entries = ctx.watches.get(node);
         if (entries) {
             entries.delete(entry);
-            // If empty, clear to drop strong refs to entries; key removal is handled by WeakMap GC.
+            // If empty, delete the entry from WeakMap to free the Set immediately
             if (entries.size === 0)
-                entries.clear();
+                ctx.watches.delete(node);
         }
         // Decrement active watch count and disconnect observer if none left
         ctx.watchCount--;
@@ -177,14 +195,33 @@ export function watch(node, fn) {
     }
     return dispose;
 }
+/**
+ * onMount(fn)
+ *
+ * Executes fn immediately. Minimal semantic helper to document mount-time logic in DOM-first code.
+ * Unlike React, there's no deferred execution or batching — it runs synchronously.
+ */
 export function onMount(fn) {
     fn();
 }
+/**
+ * onCleanup(fn)
+ *
+ * Registers fn to run when the current scope is disposed.
+ * If called outside a scope, fn is never called (no-op).
+ */
 export function onCleanup(fn) {
     const scope = getCurrentScope();
     if (scope)
         scope.onCleanup(fn);
 }
+/**
+ * useEvent(target, type, handler, options?)
+ *
+ * Attaches an event listener and returns an idempotent dispose() function.
+ * - Inside a scope: listener is removed automatically on scope.dispose().
+ * - Outside a scope: you must call dispose() manually (warns once).
+ */
 export function useEvent(target, type, handler, options) {
     const scope = getCurrentScope();
     if (!scope && !warnedFunctions.has('useEvent')) {
@@ -204,6 +241,13 @@ export function useEvent(target, type, handler, options) {
         scope.onCleanup(dispose);
     return dispose;
 }
+/**
+ * useInterval(fn, ms)
+ *
+ * Starts an interval and returns an idempotent dispose() function.
+ * - Inside a scope: interval is cleared automatically on scope.dispose().
+ * - Outside a scope: you must call dispose() manually (warns once).
+ */
 export function useInterval(fn, ms) {
     const scope = getCurrentScope();
     if (!scope && !warnedFunctions.has('useInterval')) {
@@ -223,6 +267,13 @@ export function useInterval(fn, ms) {
         scope.onCleanup(dispose);
     return dispose;
 }
+/**
+ * useTimeout(fn, ms)
+ *
+ * Starts a timeout and returns an idempotent dispose() function.
+ * - Inside a scope: timeout is cleared automatically on scope.dispose().
+ * - Outside a scope: you must call dispose() manually (warns once).
+ */
 export function useTimeout(fn, ms) {
     const scope = getCurrentScope();
     if (!scope && !warnedFunctions.has('useTimeout')) {
@@ -242,12 +293,34 @@ export function useTimeout(fn, ms) {
         scope.onCleanup(dispose);
     return dispose;
 }
-// Async effect with fetch support and automatic abort
+/**
+ * useFetch(url, options)
+ *
+ * Small convenience for "fetch + reactive state + abort" built on effectAsync().
+ * Returns { data, loading, error, dispose }.
+ *
+ * Behavior:
+ * - Runs the fetch inside effectAsync, which provides an AbortSignal.
+ * - If url is a function, it tracks signal reads (reactive).
+ * - Calling dispose() aborts the in-flight request (via effectAsync's signal).
+ * - Inside a scope: auto-disposed on scope.dispose().
+ * - Outside a scope: you must call dispose() manually (warns once).
+ *
+ * Limitations:
+ * - No refresh(), no caching, no invalidation.
+ * - For those features, use createResource / query().
+ */
 export function useFetch(url, options) {
+    const scope = getCurrentScope();
+    if (!scope && !warnedFunctions.has('useFetch')) {
+        warnedFunctions.add('useFetch');
+        console.warn('[Dalila] useFetch() called outside scope. ' +
+            'Request will not auto-cleanup. Call the returned dispose() function manually.');
+    }
     const data = signal(null);
     const loading = signal(false);
     const error = signal(null);
-    effectAsync(async (signal) => {
+    const dispose = effectAsync(async (signal) => {
         try {
             loading.set(true);
             error.set(null);
@@ -259,7 +332,7 @@ export function useFetch(url, options) {
             if (!response.ok) {
                 throw new Error(`HTTP error! status: ${response.status}`);
             }
-            const result = await response.json();
+            const result = (await response.json());
             data.set(result);
         }
         catch (err) {
@@ -273,5 +346,8 @@ export function useFetch(url, options) {
             }
         }
     });
-    return { data, loading, error };
+    // Match the other lifecycle helpers: if we are inside a scope, dispose automatically.
+    if (scope)
+        scope.onCleanup(dispose);
+    return { data, loading, error, dispose };
 }

package/dist/internal/watch-testing.d.ts

@@ -0,0 +1 @@
+export declare function resetWarnings(): void;

package/dist/internal/watch-testing.js

@@ -0,0 +1,8 @@
+/**
+ * Testing utilities for watch.ts
+ * @internal
+ */
+import { __resetWarningsForTests } from '../core/watch.js';
+export function resetWarnings() {
+    __resetWarningsForTests();
+}

package/package.json

@@ -1,10 +1,16 @@
 {
   "name": "dalila",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "DOM-first reactive framework based on signals",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",