jq79 0.7.3 → 0.7.4

package/dist/reactive.d.ts

@@ -53,4 +53,8 @@ export type EffectScope = {
     dispose: () => void;
 };
 export declare const createEffectScope: (scope: Record<string, any>, deep?: boolean) => EffectScope;
+export type Computed<T> = ReactiveDeepData<{
+    readonly value: T;
+}>;
+export declare const $computed: <T>(get: () => T) => Computed<T>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jq79",
-  "version": "0.7.3",
+  "version": "0.7.4",
   "description": "Mini reactive component library: single-file .html components, Svelte-style setup scripts, fine-grained proxy reactivity. No compiler, no bundler, no dependencies — works from any static host.",
   "keywords": [
     "reactive",

package/src/jq79.ts

@@ -1,7 +1,7 @@
 
 import { $, $$, $create, sanitizeHTML, allowedHosts } from "./dom"
 import type { AllowUrl, QueryAll, QueryOne } from "./dom"
-import { $reactive, $toRaw, untracked, createEffectScope, ALSO_WAKEN_BY, OWNER } from "./reactive"
+import { $reactive, $toRaw, $computed, untracked, createEffectScope, ALSO_WAKEN_BY, OWNER } from "./reactive"
 import type { ReactiveDeepData, EffectScope } from "./reactive"
 import { transformSetupScript, transformFactoryScript, parsePropsPattern, parseFactoryProps, type PropDecl } from "./transform"
 import {
@@ -14,7 +14,8 @@ import {
 
 export { $, $$, $create } from "./dom"
 export type { QueryOne, QueryAll } from "./dom"
-export { $reactive, $toRaw } from "./reactive"
+export { $reactive, $toRaw, $computed } from "./reactive"
+export type { Computed } from "./reactive"
 
 // the package version, substituted at build time (tsup/vitest `define`, read
 // from package.json - releases bump it there and nowhere else). The typeof
@@ -4054,6 +4055,17 @@ export class Component79 {
   // must not resolve on attach alone - a script awaiting it would wake to an
   // empty component and find nothing to query
   private renderDone = false
+  // what this render generation's scripts asked to run when it is torn down
+  // ($destroyed). Created on the first call, and taken by destroy() before
+  // anything else goes, so a hook still sees the DOM and the store
+  private destroyHooks: (() => void)[] | null = null
+  // this generation's $attached / $detached hooks, and whether it has been
+  // told it is on the page. Only an instance that registered one of them is
+  // in pageWatchers, which is what keeps a page that uses neither from paying
+  // for a walk on every mount (see settleAttached)
+  private attachHooks: (() => void)[] | null = null
+  private detachHooks: (() => void)[] | null = null
+  private onPage = false
   // instance-level listeners for $emit events, registered with on(). Kept
   // outside the render generation so they survive re-render and destroy()
   private emitListeners = new Map<string, Set<EmitListener>>()
@@ -4351,6 +4363,55 @@ export class Component79 {
     this.resolveMounted = resolveMounted
     this.renderDone = false
 
+    // $destroyed(fn) runs fn when this generation is torn down: destroy(), a
+    // re-render, a hot reload, or a parent's :if/:each removing it - never
+    // detach(), which keeps state for a mount() to resume. Registered after
+    // the generation is gone (a script that awaited past its own destroy), it
+    // runs at once: holding it for a destroy that already happened would leak
+    // exactly what it was written to stop. Returns the unregister
+    const $destroyed = (fn: () => void): (() => void) => {
+      if (typeof fn !== "function") throw new TypeError("jq79: $destroyed expects a function")
+      if (marker !== this.startMarker) {
+        runHook(fn, "$destroyed")
+        return () => {}
+      }
+      return addHook((this.destroyHooks ??= []), fn)
+    }
+    // $attached(fn) runs fn every time this generation goes onto the page -
+    // in the document, rendered - the first mount included; $detached(fn)
+    // every time it leaves, and only after an $attached it balances. A nested
+    // component hears its root's mount and detach (see settleAttached and
+    // notifyDetached). `immediate`, on by default, also runs fn now when the
+    // component is on the page already, so "while I'm on the page" holds
+    // wherever the line sits - above `await $mounted()` or below it. A late
+    // $detached runs at once, as a late $destroyed does; a late $attached has
+    // nothing left to attach
+    const $attached = (fn: () => void, { immediate = true }: { immediate?: boolean } = {}): (() => void) => {
+      if (typeof fn !== "function") throw new TypeError("jq79: $attached expects a function")
+      if (marker !== this.startMarker) return () => {}
+      this.watchPage()
+      const off = addHook((this.attachHooks ??= []), fn)
+      if (immediate && this.onPage) runHook(fn, "$attached")
+      return off
+    }
+    const $detached = (fn: () => void): (() => void) => {
+      if (typeof fn !== "function") throw new TypeError("jq79: $detached expects a function")
+      if (marker !== this.startMarker) {
+        runHook(fn, "$detached")
+        return () => {}
+      }
+      this.watchPage()
+      return addHook((this.detachHooks ??= []), fn)
+    }
+    // the library's $computed, disposed with this generation: one made over a
+    // shared store is otherwise held by that store, and kept recomputing, for
+    // as long as the store lives
+    const $instanceComputed = <T>(get: () => T) => {
+      const computed = $computed(get)
+      $destroyed(() => computed.$dispose())
+      return computed
+    }
+
     // $self / $$self mirror $ / $$ but only search this instance's own
     // output: the sibling nodes between its markers. They work detached too
     // (the holding fragment keeps markers and rendered nodes as siblings),
@@ -4451,7 +4512,7 @@ export class Component79 {
       // resolve to nothing at all. In setup mode this composes with `with` -
       // scriptScope's `has` declines any name that is a helper, so the
       // parameter is what the name resolves to
-      const instanceHelpers = { $mounted, $self, $$self, ...injected, ...siblingScope }
+      const instanceHelpers = { $mounted, $destroyed, $attached, $detached, $computed: $instanceComputed, $self, $$self, ...injected, ...siblingScope }
       const at: ScriptLocation = { filename: this.filename, index }
       const deferred = ":mounted" in script.attrs
       const factoryCode = transformFactoryScript(script.content)
@@ -4541,6 +4602,8 @@ export class Component79 {
         this.endMarker!.parentNode!.insertBefore(renderNodes(this.template, templateScope, fx, shadow), this.endMarker!)
         this.renderDone = true
         this.settleMounted()
+        // a held render that paints on the page is this component's attach
+        Component79.settleAttached()
       })
       warnIfStuck(this, gates)
     }
@@ -4603,9 +4666,87 @@ export class Component79 {
     root.appendChild(this.content!)
     this.mountRoot = root
     this.settleMounted()
+    Component79.settleAttached()
     return this
   }
 
+  // whether this generation's DOM is in the document, template built - the
+  // one meaning "on the page" has for $attached. Not "attach() was called": a
+  // nested component is mounted into a fragment its parent inserts later, and
+  // a root can be mounted into an element that isn't in the document
+  private isOnPage(): boolean {
+    return this.renderDone && this.startMarker?.isConnected === true
+  }
+
+  // joins pageWatchers on the first $attached/$detached of a generation, with
+  // the state as it is now: a hook registered while on the page must not fire
+  // for an attach that already happened. Off the page, a settle is queued: a
+  // component inserted by its parent's :if, :each or tag is built in a
+  // fragment and put on the page later on this same stack, with no attach()
+  // of its own to say so - one microtask late, never early
+  private watchPage() {
+    if (pageWatchers.has(this)) return
+    pageWatchers.add(this)
+    this.onPage = this.isOnPage()
+    if (!this.onPage) Component79.queueSettle()
+  }
+
+  private static queueSettle() {
+    if (settleQueued) return
+    settleQueued = true
+    queueMicrotask(() => {
+      settleQueued = false
+      Component79.settleAttached()
+    })
+  }
+
+  // tells every watcher that is on the page and hasn't been told, in document
+  // order - a parent before what it rendered, slot content included, because
+  // the DOM is what says where a component is
+  private static settleAttached() {
+    if (pageWatchers.size === 0) return
+    const due = [...pageWatchers].filter(component => !component.onPage && component.isOnPage())
+    Component79.inDocumentOrder(due).forEach(component => {
+      // a hook that ran before this one may have destroyed it
+      if (component.onPage || !pageWatchers.has(component)) return
+      component.onPage = true
+      component.attachHooks?.slice().forEach(fn => runHook(fn, "$attached"))
+    })
+  }
+
+  // tells this component and every watcher whose DOM is under its markers
+  // that they are leaving the page - before anything moves, so the hooks see
+  // the DOM where it was. One whose DOM already left without it (an :if
+  // removes its branch, then destroys what was in it) has only itself to tell
+  private notifyDetached() {
+    if (pageWatchers.size === 0) return
+    let due: Component79[] = []
+    if (this.startMarker?.isConnected) {
+      const top = new Set<Node>()
+      for (let node: Node | null = this.startMarker; node; node = node.nextSibling) {
+        top.add(node)
+        if (node === this.endMarker) break
+      }
+      const under = (node: Node | null): boolean => {
+        for (; node; node = node.parentNode) if (top.has(node)) return true
+        return false
+      }
+      due = Component79.inDocumentOrder([...pageWatchers].filter(component => component.onPage && under(component.startMarker)))
+    } else if (this.onPage) {
+      due = [this]
+    }
+    due.forEach(component => {
+      if (!component.onPage) return
+      component.onPage = false
+      component.detachHooks?.slice().forEach(fn => runHook(fn, "$detached"))
+    })
+  }
+
+  private static inDocumentOrder(components: Component79[]): Component79[] {
+    return components.sort((a, b) =>
+      a.startMarker!.compareDocumentPosition(b.startMarker!) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1)
+  }
+
   // where a shadow-rendered component's styles go: <style> elements ahead of
   // its content, as always - or, under safe mode, sheets adopted by the shadow
   // root. Built on first placement, since only then is there a root; one that
@@ -4640,6 +4781,7 @@ export class Component79 {
   // with any updates that happened while detached already applied
   detach(): this {
     if (!this.mountRoot || !this.content || !this.startMarker || !this.endMarker) return this
+    this.notifyDetached()
 
     // move everything between the markers (inclusive) back into the holding
     // fragment - including nodes :if/:each inserted after mounting
@@ -4656,6 +4798,18 @@ export class Component79 {
   }
 
   destroy(): this {
+    // first, while everything they might read is still there: leaving the
+    // page ($detached, for this component and what it rendered), then going
+    // ($destroyed). Taken before running, so a hook that destroys again (or
+    // re-renders) finds none
+    this.notifyDetached()
+    pageWatchers.delete(this)
+    this.attachHooks = null
+    this.detachHooks = null
+    this.onPage = false
+    const hooks = this.destroyHooks
+    this.destroyHooks = null
+    hooks?.forEach(fn => runHook(fn, "$destroyed"))
     this.detach()
     this.fx?.dispose()
     this.fx = null
@@ -4789,6 +4943,30 @@ export type Component<P = any, E extends string = never, S extends string = neve
 
 export const parseComponent = (component: string): Component79 => new Component79(component)
 
+// one broken hook must not leave the others' timers running, or the
+// teardown half done: reported, and the rest still run
+const runHook = (fn: () => void, name: string) => {
+  try {
+    fn()
+  } catch (error) {
+    console.error(`jq79: error in a ${name} hook`, error)
+  }
+}
+
+// registers fn on a generation's hook list; the returned function takes it off
+const addHook = (hooks: (() => void)[], fn: () => void): (() => void) => {
+  hooks.push(fn)
+  return () => {
+    const at = hooks.indexOf(fn)
+    if (at !== -1) hooks.splice(at, 1)
+  }
+}
+
+// the instances with an $attached or $detached hook, in this generation -
+// the only ones a mount or a detach has to look at (see settleAttached)
+const pageWatchers = new Set<Component79>()
+let settleQueued = false
+
 // library helpers injected into setup scripts. They behave like extra
 // globals: a same-named scope property (render data or a top-level
 // declaration) shadows them. Their names, in this order, are also

package/src/precompile.ts

@@ -175,9 +175,10 @@ const precompileComponent = (
 
   // the helper names a script is compiled with: renderWith's
   // { ...SETUP_HELPERS, ...instanceHelpers }, where instanceHelpers is
-  // { $mounted, $self, $$self, ...injected, ...siblingScope } - key order
-  // included, because the parameters are positional (built as objects, so a
-  // sibling named like a helper keeps the helper's place, as it does there)
+  // { $mounted, $destroyed, $attached, $detached, $computed, $self, $$self,
+  // ...injected, ...siblingScope } - key order included, because the
+  // parameters are positional (built as objects, so a sibling named like a
+  // helper keeps the helper's place, as it does there)
   //
   // Reading the signatures is also the first thing renderWith does, and where
   // it refuses a component - a factory destructuring a ctx name out of props

package/src/reactive.ts

@@ -1200,3 +1200,32 @@ class Scope implements EffectScope {
 }
 
 export const createEffectScope = (scope: Record<string, any>, deep = false): EffectScope => new Scope(scope, deep)
+
+// a derived value: `get`'s result on `.value`, recomputed whenever anything it
+// read changes - in any store, the way any effect is woken. What comes back is
+// a store, so it does everything one does (passed as a prop, held in another
+// store and bridged there, $on("value")), seen through a read-only view: a
+// write would be overwritten by the next recompute, so it is refused aloud
+// instead (see RECORD/2026-10-01.computed.md)
+export type Computed<T> = ReactiveDeepData<{ readonly value: T }>
+
+export const $computed = <T>(get: () => T): Computed<T> => {
+  const box = $reactive({ value: undefined as T })
+  box.$effect(() => {
+    let value: T
+    try {
+      value = get()
+    } catch (error) {
+      // left to propagate, it would throw out of whatever write woke it -
+      // `cart.items.push(x)` failing for code that has nothing to do with it
+      console.error("jq79: error in $computed, keeping its last value", error)
+      return
+    }
+    box.value = value
+  })
+  const refuse = (_target: object, key: string | symbol): boolean => {
+    console.warn(`jq79: a $computed is read-only - the write to ${String(key)} was ignored`)
+    return true
+  }
+  return new Proxy(box, { set: refuse, deleteProperty: refuse, defineProperty: refuse }) as Computed<T>
+}

package/src/source.ts

@@ -364,12 +364,13 @@ export const declaredPropNames = (scripts: TagBlock[], signature: (script: TagBl
 // the names every setup and factory script is compiled with, in the order
 // renderWith passes them: SETUP_HELPERS (whose values live in jq79.ts, beside
 // the functions they are) and then the per-instance ones it builds -
-// $mounted, $self and $$self, then the injected $emit, $updateModel and
-// $slots. They are positional parameters, so the order is part of what
+// $mounted, $destroyed, $attached, $detached, $computed, $self and $$self,
+// then the injected
+// $emit, $updateModel and $slots. They are positional parameters, so the order is part of what
 // precompile has to reproduce; change one side and precompiled scripts stop
 // matching, which tests/precompile.test.ts and `npm run check:precompile` catch
 export const SETUP_HELPER_NAMES = ["$", "$$", "$create", "$reactive", "$toRaw", "Component79"]
-export const INSTANCE_HELPER_NAMES = ["$mounted", "$self", "$$self", "$emit", "$updateModel", "$slots"]
+export const INSTANCE_HELPER_NAMES = ["$mounted", "$destroyed", "$attached", "$detached", "$computed", "$self", "$$self", "$emit", "$updateModel", "$slots"]
 
 // the global a precompiled script leaves its functions on, for the runtime to
 // drain: (self.__jq79precompiled = self.__jq79precompiled || []).push([params,

package/src/transform.ts

@@ -401,7 +401,7 @@ export const transformSetupScript = (src: string): SetupTransform => {
 // plain lexical module instead of a `with`-scoped setup script: no implicit
 // reactivity, no `$:` labels - standard JS that editors and type-checkers
 // understand. The default export is called with the instance context
-// ({ $data, $effect, $emit, $mounted, $self, $$self }) and a returned object
+// ({ $data, $effect, $emit, $mounted, $destroyed, $attached, $detached, $computed, $self, $$self }) and a returned object
 // is merged into the reactive store for the template to use.
 // Detection is backwards-safe: `export default` is a SyntaxError inside a
 // setup script, so no previously-working component can change behavior.