jq79 0.6.4 → 0.6.6

package/src/reactive.ts

@@ -62,20 +62,69 @@ const walkLeaves = (obj: Record<string, any>, path: string, visit: (dotKey: stri
 //
 // Which of the two directions actually wakes an effect is the thing that makes
 // this fast, and it is not symmetric - see effectsFor and
-// TODOS/2026-08-23.narrow-the-wake-rule.md
+// RECORD/2026-08-23.narrow-the-wake-rule.md
 //
 // `children`/`own`/`deep` are allocated on first use and `parent`/`segment` let
 // a removal walk back up without re-splitting the path: a 10,000-row table is
 // ~40,000 nodes, and three eager allocations each (a Map and two Sets, almost
 // all of them staying empty) cost more than the index saves
+// The effects registered on one node, for one of the two channels. Almost every
+// dep has exactly ONE effect - `rows.7.label` is read by one text binding and
+// nothing else - so the first one lives in a slot of its own and a Set is
+// allocated only for the rest. It is the mirror of what indexEffect does one
+// layer up with soleDep/soleNode, and it is worth it because deleting an effect
+// from a one-entry Set was 60% of disposing it
+// (RECORD/2026-08-27.one-effect-per-node.md).
+//
+// TWO fields rather than one union, and that is the whole design: a field that
+// holds either an Effect or a Set makes every read of it polymorphic, and these
+// are read on the notify walk - the hot path of every write in the library. One
+// field of one shape each keeps both reads monomorphic.
+//
+// No invariant that `one` fills before `many`: an effect removed from `one`
+// leaves it null with `many` still populated, and nothing has to shuffle
 type TrieNode = {
   children: Map<string, TrieNode> | null
-  own: Set<Effect> | null
-  deep: Set<Effect> | null
+  own: Effect | null
+  ownMany: Set<Effect> | null
+  deep: Effect | null
+  deepMany: Set<Effect> | null
   parent: TrieNode | null
   segment: string
 }
 
+export const addOwn = (node: TrieNode, effect: Effect) => {
+  if (node.own === null) node.own = effect
+  else if (node.own !== effect) (node.ownMany ??= new Set()).add(effect)
+}
+
+export const addDeep = (node: TrieNode, effect: Effect) => {
+  if (node.deep === null) node.deep = effect
+  else if (node.deep !== effect) (node.deepMany ??= new Set()).add(effect)
+}
+
+// a node whose last effect leaves has to end up empty on both fields, or
+// isEmptyNode stops pruning it and the trie grows over the dead rows
+export const removeOwn = (node: TrieNode, effect: Effect) => {
+  if (node.own === effect) node.own = null
+  else if (node.ownMany?.delete(effect) && node.ownMany.size === 0) node.ownMany = null
+}
+
+export const removeDeep = (node: TrieNode, effect: Effect) => {
+  if (node.deep === effect) node.deep = null
+  else if (node.deepMany?.delete(effect) && node.deepMany.size === 0) node.deepMany = null
+}
+
+export const eachOwn = (node: TrieNode, visit: (effect: Effect) => void) => {
+  if (node.own !== null) visit(node.own)
+  node.ownMany?.forEach(visit)
+}
+
+export const eachDeep = (node: TrieNode, visit: (effect: Effect) => void) => {
+  if (node.deep !== null) visit(node.deep)
+  node.deepMany?.forEach(visit)
+}
+
 // the dep an `ownKeys` read records, as a reserved last segment on the
 // enumerated object's own path: an ordinary trie child that no walk for a real
 // key can reach, and that the subtree sweep still reaches when the whole object
@@ -92,10 +141,10 @@ const LENGTH_SUFFIX = ".length"
 
 
 const createTrieNode = (parent: TrieNode | null, segment: string): TrieNode =>
-  ({ children: null, own: null, deep: null, parent, segment })
+  ({ children: null, own: null, ownMany: null, deep: null, deepMany: null, parent, segment })
 
 const isEmptyNode = (node: TrieNode): boolean =>
-  !node.own?.size && !node.deep?.size && !node.children?.size
+  node.own === null && node.deep === null && !node.ownMany?.size && !node.deepMany?.size && !node.children?.size
 
 // reads the raw object behind a store proxy. Module-level (not per-store) so a
 // value that is already reactive - in this store or in another one - can be
@@ -144,7 +193,7 @@ export const untracked = <T>(fn: () => T): T => {
 // own, plus any it was attached to), each keeping that store's trie in step
 // with the deps of the last settled run. It lives on the effect rather than
 // in a per-store map because `run` has to reach it without a lookup
-type Effect = { deps: Set<string>; run: () => void; reindex: Set<(deps: Set<string>) => void>; deep: boolean; order: number }
+export type Effect = { deps: Set<string>; run: () => void; reindex: Set<(deps: Set<string>) => void>; deep: boolean; order: number }
 
 // creation order, module-wide. The flat `effects` set used to give this for
 // free - iterating it ran effects oldest-first, so a parent's bindings always
@@ -224,7 +273,8 @@ export const $reactive = <T extends Record<string, any>>(data: T): ReactiveDeepD
       }
       node = child
     })
-    ;((effect.deep ? (node.deep ??= new Set()) : (node.own ??= new Set()))).add(effect)
+    if (effect.deep) addDeep(node, effect)
+    else addOwn(node, effect)
     return node
   }
 
@@ -234,7 +284,8 @@ export const $reactive = <T extends Record<string, any>>(data: T): ReactiveDeepD
   // table is 30,000 of these, and splitting each path again to find a node the
   // caller was already holding is most of what that used to cost
   const removeDep = (node: TrieNode, effect: Effect) => {
-    ;(effect.deep ? node.deep : node.own)?.delete(effect)
+    if (effect.deep) removeDeep(node, effect)
+    else removeOwn(node, effect)
     let current: TrieNode | null = node
     while (current?.parent && isEmptyNode(current)) {
       current.parent.children!.delete(current.segment)
@@ -262,7 +313,7 @@ export const $reactive = <T extends Record<string, any>>(data: T): ReactiveDeepD
   //   `data[5].label = x`: an effect that read the array on its way to row
   //   7's label has no stake in row 5's, and waking all of them is what made
   //   100 row writes cost 100,000 effect runs - see
-  //   TODOS/2026-08-23.narrow-the-wake-rule.md
+  //   RECORD/2026-08-23.narrow-the-wake-rule.md
   //
   // Returned as a snapshot, so the effects it wakes can reindex themselves -
   // or dispose each other - while it drains
@@ -272,8 +323,8 @@ export const $reactive = <T extends Record<string, any>>(data: T): ReactiveDeepD
       const pending = from.children ? [...from.children.values()] : []
       while (pending.length) {
         const next = pending.pop()!
-        next.own?.forEach(effect => matched.add(effect))
-        next.deep?.forEach(effect => matched.add(effect))
+        eachOwn(next, effect => matched.add(effect))
+        eachDeep(next, effect => matched.add(effect))
         next.children?.forEach(child => pending.push(child))
       }
     }
@@ -285,21 +336,21 @@ export const $reactive = <T extends Record<string, any>>(data: T): ReactiveDeepD
       node = node.children?.get(segments[depth])
       if (!node) return matched
       path = path ? `${path}.${segments[depth]}` : segments[depth]
-      node.deep?.forEach(effect => matched.add(effect))
+      eachDeep(node, effect => matched.add(effect))
       // a nested store sits here: an effect that read through it holds this
       // path and nothing below it, so its own set is the whole channel
-      if (bridges.has(path)) node.own?.forEach(effect => matched.add(effect))
+      if (bridges.has(path)) eachOwn(node, effect => matched.add(effect))
       // ...whereas an array's length stands for the array: everything that
       // read an element has to hear a truncation, and those deps are below
       if (depth === segments.length - 2 && segments[depth + 1] === "length") {
-        node.own?.forEach(effect => matched.add(effect))
+        eachOwn(node, effect => matched.add(effect))
         sweep(node)
       }
     }
     node = node.children?.get(segments[segments.length - 1])
     if (!node) return matched
-    node.own?.forEach(effect => matched.add(effect))
-    node.deep?.forEach(effect => matched.add(effect))
+    eachOwn(node, effect => matched.add(effect))
+    eachDeep(node, effect => matched.add(effect))
     sweep(node)
     return matched
   }
@@ -458,7 +509,12 @@ export const $reactive = <T extends Record<string, any>>(data: T): ReactiveDeepD
   // holding the same elements (see notifyReplaced)
   const wakeExactly = (dep: string) => {
     const node = nodeAt(dep)
-    if (node) runMatched(new Set([...(node.own ?? []), ...(node.deep ?? [])]))
+    if (node) {
+      const matched = new Set<Effect>()
+      eachOwn(node, effect => matched.add(effect))
+      eachDeep(node, effect => matched.add(effect))
+      runMatched(matched)
+    }
   }
 
   // an object's key set changed. Effects only - a key set isn't a value, so
@@ -506,9 +562,6 @@ export const $reactive = <T extends Record<string, any>>(data: T): ReactiveDeepD
     isPlainData(previous) && isPlainData(next) &&
     Array.isArray(previous) === Array.isArray(next)
 
-  const keyCount = (container: any): number =>
-    Array.isArray(container) ? container.length : Object.keys(container).length
-
   // which keys hold a different value than they did, or null when so many do
   // that notifying them one at a time would cost more than sweeping the
   // container. Arrays - the case this exists for - are walked by index, so a
@@ -520,7 +573,12 @@ export const $reactive = <T extends Record<string, any>>(data: T): ReactiveDeepD
   // `exact` marks the keys as slots whose occupant *moved* rather than values
   // that changed: nothing under them is different, so the subtree each one
   // would otherwise sweep must be left alone (see splicedAt)
-  type Difference = { keys: string[]; exact: boolean }
+  // `keysChanged` answers the `@keys` dep - what an effect records when it reads
+  // Object.keys(container). It is not `keys.length > 0`: a replacement can
+  // change every value and no key name at all, and it used to be decided by
+  // comparing key COUNTS, which misses swapping one name for another
+  // (RECORD/2026-08-25.two-defects-a-review-found.md)
+  type Difference = { keys: string[]; exact: boolean; keysChanged: boolean }
 
   const NOT_SPLICED = -1
 
@@ -530,7 +588,7 @@ export const $reactive = <T extends Record<string, any>>(data: T): ReactiveDeepD
   // container differs" to the walk below, which gives up and has the whole
   // subtree swept; this recognises the shift for what it is. O(n), no
   // allocation, and O(1) to reject on any pair whose lengths differ by
-  // anything but one. See TODOS/2026-08-23.notify-a-splice.md
+  // anything but one. See RECORD/2026-08-23.notify-a-splice.md
   const splicedAt = (previous: any[], next: any[]): number => {
     const grew = next.length > previous.length
     const shorter = grew ? previous : next
@@ -547,6 +605,9 @@ export const $reactive = <T extends Record<string, any>>(data: T): ReactiveDeepD
     if (Array.isArray(next)) {
       const before = previous.length
       const after = next.length
+      // an array's keys are 0..length-1, so its length IS its key set - and
+      // nothing here walks the 10,000 elements a second time to learn that
+      const keysChanged = before !== after
       // nothing on one side means nothing to reuse on the other
       if (!before || !after) return GIVE_UP
       const span = Math.max(before, after)
@@ -555,7 +616,7 @@ export const $reactive = <T extends Record<string, any>>(data: T): ReactiveDeepD
         if (start !== NOT_SPLICED) {
           const slots: string[] = []
           for (let index = start; index < span; index++) slots.push(String(index))
-          return { keys: slots, exact: true }
+          return { keys: slots, exact: true, keysChanged }
         }
       }
       const changed: string[] = []
@@ -564,13 +625,22 @@ export const $reactive = <T extends Record<string, any>>(data: T): ReactiveDeepD
         changed.push(String(index))
         if (changed.length * 2 >= span) return GIVE_UP
       }
-      return { keys: changed, exact: false }
+      return { keys: changed, exact: false, keysChanged }
     }
-    const keys = new Set([...Object.keys(previous), ...Object.keys(next)])
+    const previousKeys = Object.keys(previous)
+    const nextKeys = Object.keys(next)
+    const keys = new Set([...previousKeys, ...nextKeys])
     if (!keys.size) return GIVE_UP
     const changed: string[] = []
     keys.forEach(key => { if (!Object.is($toRaw(previous[key]), $toRaw(next[key]))) changed.push(key) })
-    return changed.length * 2 >= keys.size ? GIVE_UP : { keys: changed, exact: false }
+    // Object.keys answers in insertion order, so the ORDER is part of the answer
+    // and a rebuild that sorts the same names - Object.fromEntries(entries.sort())
+    // - changes what an effect reading it sees. A union larger than either side
+    // would catch a swapped name; walking the two arrays catches that and the
+    // reorder both, off arrays this already had to build
+    const keysChanged =
+      previousKeys.length !== nextKeys.length || previousKeys.some((key, index) => key !== nextKeys[index])
+    return changed.length * 2 >= keys.size ? GIVE_UP : { keys: changed, exact: false, keysChanged }
   }
 
   // A container replaced by another container: notify the elements that
@@ -578,7 +648,7 @@ export const $reactive = <T extends Record<string, any>>(data: T): ReactiveDeepD
   // `data = [...data, ...more]` holds the very same row objects at every index
   // it had before, so waking all thirty thousand of their bindings to re-render
   // identical output is ~150ms of a 208ms append - see
-  // TODOS/2026-08-23.notify-the-difference.md
+  // RECORD/2026-08-23.notify-the-difference.md
   //
   // One level deep on purpose: an element that differs is a changed value, and
   // notifying it sweeps its own subtree, which is what a changed value deserves.
@@ -591,8 +661,10 @@ export const $reactive = <T extends Record<string, any>>(data: T): ReactiveDeepD
     const matched = new Set<Effect>()
     const collectExact = (dep: string) => {
       const node = nodeAt(dep)
-      node?.own?.forEach(effect => matched.add(effect))
-      node?.deep?.forEach(effect => matched.add(effect))
+      if (node) {
+        eachOwn(node, effect => matched.add(effect))
+        eachDeep(node, effect => matched.add(effect))
+      }
     }
 
     const difference = whatChanged(previous, next)
@@ -631,7 +703,9 @@ export const $reactive = <T extends Record<string, any>>(data: T): ReactiveDeepD
       if (difference.exact) collectExact(child)
       else effectsFor(child).forEach(effect => matched.add(effect))
     })
-    if (keyCount(previous) !== keyCount(next)) collectExact(keysPath(dotKey))
+    // the key SET, not the count: replacing { a, b, c, d } with { a, b, c, e }
+    // leaves both at four and changes what Object.keys answers
+    if (difference.keysChanged) collectExact(keysPath(dotKey))
     // an array's length is a real dep (a `:each` reads it on its way through
     // list.map) and is not one of the keys walked above. Collected exactly:
     // the sweep a length write normally carries is for a truncation, and the
@@ -939,7 +1013,7 @@ export type EffectScope = {
 // is 70,000 objects that exist to hold, on the common path, three disposers.
 // The prototype's methods are shared, and a row that registers nothing (a
 // static template) now allocates one object and no arrays at all.
-// See TODOS/2026-08-23.where-the-create-time-goes.md
+// See RECORD/2026-08-23.where-the-create-time-goes.md
 //
 // Prototype methods need their receiver: a caller that hands one on as a bare
 // function (`runSetupScript(..., fx.effect, ...)` did) must wrap it instead

package/src/transform.ts

@@ -752,3 +752,150 @@ export const transformFactoryScript = (src: string): string | null => {
   return isFactory ? out : null
 }
 
+
+// ---------------------------------------------------------------------------
+// free identifiers in a template expression
+//
+// What a compiled expression reads from the scope, so it can be resolved by
+// name instead of by `with ($scope)` - which is 60% of an evaluation over a
+// store proxy, because it resolves every mention through [[HasProperty]] (the
+// proxy's `has` trap as well as its `get`) and consults Symbol.unscopables
+// besides. See RECORD/2026-08-27.name-resolution-without-with.md
+//
+// This is a scanner, not a parser, and it is deliberately conservative: `null`
+// means "keep `with`", and every shape that binds a name, assigns to one or
+// resolves one dynamically returns it. The caller falls back rather than
+// guesses, so a name this misses costs a slower evaluation, never a wrong one.
+// ---------------------------------------------------------------------------
+
+// words that scan as an identifier and are never a free variable read
+const NOT_A_FREE_NAME = new Set([
+  "true", "false", "null", "undefined", "this", "typeof", "instanceof", "in", "new", "void",
+  "delete", "of", "await", "yield", "NaN", "Infinity", "arguments", "case", "do", "else", "return",
+])
+
+// anything that introduces a binding or reaches the scope by another route.
+// A dynamic `import(...)` is absent deliberately: naming it here would put the
+// word next to a quote in the bundle, which is what tests/no-bundle.test.ts
+// greps for. It needs no entry - `import` is collected as a free name, the
+// prologue's `const import = …` will not compile, and compileScoped falls back
+const BINDS_A_NAME = new Set(["function", "class", "let", "const", "var", "eval", "with"])
+
+// the compiled function's own parameters and temporary: an expression that
+// mentions one would be reading the codegen's variable, not the author's
+const CODEGEN_NAMES = new Set(["$scope", "$r", "$t"])
+
+// operators that write, or bind - any of them and the expression keeps `with`
+const WRITES_RE = /^(?:\+\+|--|=>|\*\*=|<<=|>>>=|>>=|&&=|\|\|=|\?\?=|[+\-*/%&|^]=(?!=))/
+// operators that merely read, longest first so `===` is never read as `==` + `=`
+const READS_RE = /^(?:>>>|===|!==|\*\*|<<|>>|==|!=|<=|>=|&&|\|\||\?\?|\?\.)/
+
+const isIdentifierStart = (ch: string): boolean => /[A-Za-z_$]/.test(ch)
+
+// a numeric literal, consumed whole so `1e5` does not scan as the name `e5`
+const NUMBER_RE = /^(?:0[xXbBoO][\da-fA-F_]+|\d[\d_]*(?:\.[\d_]*)?(?:[eE][+-]?\d+)?)n?/
+
+export const freeIdentifiers = (expr: string): string[] | null => {
+  const names = new Set<string>()
+  // one entry per open bracket, counting the `?`s waiting for their `:` at that
+  // depth - which is what tells `{ danger: x }`'s key from `a ? b : c`'s colon
+  const ternaries: number[] = [0]
+  const brackets: string[] = []
+  let shortCircuits = false
+  let prev = "" // the last meaningful token: "name", "value", "." or "?." or a punctuator
+  let i = 0
+
+  while (i < expr.length) {
+    const ch = expr[i]
+    if (/\s/.test(ch)) { i++; continue }
+    if (ch === "/" && expr[i + 1] === "/") { i = skipLineComment(expr, i); continue }
+    if (ch === "/" && expr[i + 1] === "*") { i = skipBlockComment(expr, i); continue }
+    if (ch === "/" && regexAllowed(expr, i)) { i = skipRegex(expr, i); prev = "value"; continue }
+    if (ch === '"' || ch === "'") { i = skipString(expr, i); prev = "value"; continue }
+
+    if (ch === "`") {
+      // a template literal reads names inside every ${...}, and nothing else
+      let j = i + 1
+      while (j < expr.length) {
+        if (expr[j] === "\\") { j += 2; continue }
+        if (expr[j] === "`") { j++; break }
+        if (expr[j] === "$" && expr[j + 1] === "{") {
+          let depth = 1
+          const start = (j += 2)
+          while (j < expr.length && depth > 0) {
+            if (expr[j] === "{") depth++
+            else if (expr[j] === "}") depth--
+            j++
+          }
+          const inner = freeIdentifiers(expr.slice(start, j - 1))
+          if (inner === null) return null
+          inner.forEach(name => names.add(name))
+          continue
+        }
+        j++
+      }
+      i = j
+      prev = "value"
+      continue
+    }
+
+    if (/\d/.test(ch) && prev !== "." && prev !== "?.") {
+      const match = NUMBER_RE.exec(expr.slice(i))
+      i += match ? match[0].length : 1
+      prev = "value"
+      continue
+    }
+
+    if (isIdentifierStart(ch)) {
+      let end = i
+      while (end < expr.length && /[\w$]/.test(expr[end])) end++
+      const word = expr.slice(i, end)
+      i = end
+      if (BINDS_A_NAME.has(word)) return null
+      if (prev === "." || prev === "?.") { prev = "value"; continue } // a property, not a name
+      if (NOT_A_FREE_NAME.has(word)) { prev = word === "this" ? "value" : "op"; continue }
+      if (CODEGEN_NAMES.has(word)) return null
+      let after = i
+      while (after < expr.length && /\s/.test(expr[after])) after++
+      // A free name that is CALLED is called with the with-object as its
+      // receiver: `add()` inside `with ($scope)` runs with `this === $scope`,
+      // and a factory component's `{ items: [], add() { this.items… } }`
+      // depends on it. A `const` cannot reproduce that - the call would get
+      // `undefined` - so a called name keeps `with`. Measured at 11 of this
+      // repository's 239 resolvable expressions, and 8 of those are handlers
+      if (expr[after] === "(") return null
+      // `{ danger: … }` names a key; `a ? b : c` names a value
+      const isKey = expr[after] === ":" && expr[after + 1] !== ":" &&
+        brackets[brackets.length - 1] === "{" && ternaries[ternaries.length - 1] === 0
+      if (!isKey) names.add(word)
+      prev = "value"
+      continue
+    }
+
+    const rest = expr.slice(i)
+    if (WRITES_RE.test(rest)) return null
+    const reads = READS_RE.exec(rest)
+    if (reads) {
+      if (reads[0] === "&&" || reads[0] === "||" || reads[0] === "??") shortCircuits = true
+      prev = reads[0] === "?." ? "?." : "op"
+      i += reads[0].length
+      continue
+    }
+    if (ch === "=") return null // a bare `=` left after READS_RE is an assignment
+
+    if (ch === "(" || ch === "[" || ch === "{") { brackets.push(ch); ternaries.push(0) }
+    else if (ch === ")" || ch === "]" || ch === "}") { brackets.pop(); if (ternaries.length > 1) ternaries.pop() }
+    else if (ch === "?") { ternaries[ternaries.length - 1]++; shortCircuits = true }
+    else if (ch === ":" && ternaries[ternaries.length - 1] > 0) ternaries[ternaries.length - 1]--
+
+    prev = ch
+    i++
+  }
+
+  // every name is resolved before the expression runs, so a branch that would
+  // not have been taken is read anyway: one more dep than `with` would track,
+  // and a ReferenceError for a name only the dead branch mentions. With one
+  // name there is no branch to be wrong about
+  if (shortCircuits && names.size > 1) return null
+  return [...names]
+}