jq79 0.5.4 → 0.5.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jq79",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "description": "Mini reactive component library: single-file components, Svelte-style setup scripts, fine-grained proxy reactivity. Single-file build, zero dependencies.",
   "keywords": [
     "reactive",

package/src/jq79.ts

@@ -127,6 +127,36 @@ const reportedExprErrors = new Set<string>()
 let pendingScripts = 0
 let flushScheduled = false
 
+// everything else an expression can throw - overwhelmingly a member access on
+// an undefined value, `{{ game.is.loaded }}` over a game with no `is`. There is
+// no pure question to ask about it the way there is for a missing name: `in`
+// answers "declared anywhere?" without evaluating, and nothing answers "would
+// this still throw?" without running the expression again, which is exactly
+// what mustn't happen (`@click="count++ + missing"` increments twice).
+//
+// What is pure is watching the evaluations that were going to happen anyway. An
+// expression whose value is merely late is re-evaluated when the value arrives -
+// the reads that did land registered as dependencies, so the write wakes the
+// effect - and it succeeds then. So transient means "succeeds later", and the
+// re-check is to clear the entry on the next successful evaluation and report
+// only what is still queued once the page has gone quiet.
+//
+// Quiet is a timer rather than the microtask the other queue flushes on,
+// because a value from fetch() arrives many tasks later and clearing on success
+// exists to let it. A second covers that and still lands the warning inside the
+// page load. It is a guess, and the cost is a slower fetch warning about correct
+// code with nothing to take it back - accepted because the silence it replaces
+// hid a render that was actively wrong
+const FAILED_EXPR_DELAY = 1000
+
+// keyed by expression text alone, not `message|expr`: the expression is what the
+// author edits, and one broken path throwing two messages is still one bug. The
+// entries hold no scope, only strings, so this queue cannot retain a live
+// component the way pendingReports can
+const failedExprs = new Map<string, string>()
+const reportedFailedExprs = new Set<string>()
+let failedFlushTimer: ReturnType<typeof setTimeout> | undefined
+
 const flushExprReports = () => {
   flushScheduled = false
   if (pendingScripts > 0) return // a script started meanwhile; its release re-schedules
@@ -149,6 +179,25 @@ const scheduleExprReportFlush = () => {
   queueMicrotask(flushExprReports)
 }
 
+const flushFailedExprs = () => {
+  failedFlushTimer = undefined
+  if (pendingScripts > 0) return // a script started meanwhile; its release re-schedules
+  failedExprs.forEach((message, expr) => {
+    reportedFailedExprs.add(expr)
+    console.warn(
+      `jq79: ${message} - evaluating "${expr}". It rendered as nothing and was ` +
+      `still failing a moment later, so the value is probably never coming: check ` +
+      `the path. If it does arrive asynchronously, guard it - "a?.b", or :if on the element.`
+    )
+  })
+  failedExprs.clear()
+}
+
+const scheduleFailedExprFlush = () => {
+  if (failedFlushTimer !== undefined || pendingScripts > 0 || !failedExprs.size) return
+  failedFlushTimer = setTimeout(flushFailedExprs, FAILED_EXPR_DELAY)
+}
+
 // scripts run before the template renders, so the counter is already up when
 // the first evaluation fails. Both script modes settle through a promise;
 // the factory's has to cover the merge, not just the module body
@@ -157,12 +206,20 @@ const trackScript = (settled: Promise<unknown>) => {
   const release = () => {
     pendingScripts--
     scheduleExprReportFlush()
+    scheduleFailedExprFlush()
   }
   settled.then(release, release)
 }
 
+const reportFailedExpr = (expr: string, error: unknown) => {
+  if (reportedFailedExprs.has(expr) || failedExprs.has(expr)) return
+  if (failedExprs.size >= MAX_PENDING_REPORTS) return
+  failedExprs.set(expr, (error as Error)?.message || String(error))
+  scheduleFailedExprFlush()
+}
+
 const reportExprError = (expr: string, scope: Record<string, any>, error: unknown) => {
-  if (!(error instanceof ReferenceError)) return
+  if (!(error instanceof ReferenceError)) return reportFailedExpr(expr, error)
   const match = MISSING_NAME_RE.exec(error.message)
   const name = match?.[1] ?? match?.[2]
   if (!name) return // an engine whose wording we don't know: stay quiet, as before
@@ -176,17 +233,52 @@ const reportExprError = (expr: string, scope: Record<string, any>, error: unknow
   scheduleExprReportFlush()
 }
 
-const evalExpr = (expr: string, scope: Record<string, any>, extras?: Record<string, any>): any => {
+const runExpr = (expr: string, scope: Record<string, any>, extras?: Record<string, any>): any => {
   const fn = compileExpr(expr, extras ? Object.keys(extras) : [])
-  if (!fn) return undefined
+  if (!fn) return undefined // a syntax error: compileExpr cached the failure, and it stays undefined
+  return fn(scope, ...(extras ? Object.values(extras) : []))
+}
+
+const evalExpr = (expr: string, scope: Record<string, any>, extras?: Record<string, any>): any => {
   try {
-    return fn(scope, ...(extras ? Object.values(extras) : []))
+    const value = runExpr(expr, scope, extras)
+    // the re-check for the failed-expression queue: this run is the proof that
+    // the earlier throw was a value arriving late. Guarded on size so the
+    // normal page - where nothing has ever thrown - pays one comparison
+    if (failedExprs.size) failedExprs.delete(expr)
+    return value
   } catch (error) {
     reportExprError(expr, scope, error)
     return undefined
   }
 }
 
+// the same evaluation for an @event attribute, which swallows far less. Every
+// word of the reason evalExpr catches is about rendering: an expression is
+// re-evaluated per effect run, per interpolation, per :each item, so a value
+// that is briefly undefined mid-render has to render empty rather than tear the
+// render down. A handler runs in an event listener - not in an effect, once,
+// when the user clicked - so there is no transient failure to absorb, only a
+// bug to report, and an exception belongs in the console with its stack. That
+// is what `@click="save"` has always done (the call happens outside the try,
+// on the returned function); this is what makes `@click="save()"` and
+// `@click="count++"` behave the same rather than the other way round.
+//
+// ReferenceError is the exception, for the reason it always is: it is not yet
+// decidable at throw time. A factory assigns its names to the store when it
+// returns, so a click while one is still in flight throws for a name that is
+// about to exist - reportExprError re-checks after the scripts settle and stays
+// quiet if it arrived, which throwing here would replace with a false alarm
+const evalHandler = (expr: string, scope: Record<string, any>, extras: Record<string, any>): any => {
+  try {
+    return runExpr(expr, scope, extras)
+  } catch (error) {
+    if (!(error instanceof ReferenceError)) throw error
+    reportExprError(expr, scope, error)
+    return undefined
+  }
+}
+
 // [\s\S] rather than `.` so an expression can span lines, like the ones in
 // directive attributes (which reach evalExpr wrapped in parens either way)
 const interpolate = (template: string, scope: Record<string, any>): string =>
@@ -225,7 +317,7 @@ const bindEvent = (el: Element, attr: string, expr: string, scope: Record<string
     if (mods.has("prevent")) event.preventDefault()
     if (mods.has("stop")) event.stopPropagation()
 
-    const handler = evalExpr(expr, scope, { $event: event })
+    const handler = evalHandler(expr, scope, { $event: event })
     if (typeof handler === "function") handler.call(el, event)
   }, { once: mods.has("once"), capture: mods.has("capture") })
 }
@@ -256,7 +348,7 @@ const wireTagEvent = (instance: Component79, attr: string, expr: string, scope:
     // and the creation effect's definition guard no-ops a spurious wake - but
     // "what a handler reads is nobody's dependency" shouldn't hinge on either
     untracked(() => {
-      const handler = evalExpr(expr, scope, { $event: event })
+      const handler = evalHandler(expr, scope, { $event: event })
       if (typeof handler === "function") handler(event)
     })
   }
@@ -1839,7 +1931,35 @@ const declareProps = (store: Record<string, any>, props: PropDecl[] | null) => {
 const setupSignature = (script: TagBlock): PropDecl[] | null => {
   const pattern = script.attrs[":setup"]
   if (pattern === undefined) return null
-  return pattern.trim() === "" ? [] : parsePropsPattern(pattern)
+  if (pattern.trim() === "") return []
+  const props = parsePropsPattern(pattern)
+  if (!props) warnUnreadableSignature(script, pattern)
+  return props
+}
+
+// script blocks already warned about, keyed by the block itself - parsed once
+// and shared by every instance of a definition, the same reason warnUndeclared
+// keys on the template node. It matters for a smaller reason here too:
+// setupSignature is called three times per render (both declared-name passes
+// and the script loop's declareProps), so even one mount would say it thrice
+const signatureWarned = new WeakSet<TagBlock>()
+
+// a value that isn't a props pattern reads as "declared no signature", which is
+// the most permissive mode there is - so a typo doesn't fail, it quietly opts
+// the component out of the contract it was trying to write. That is now the
+// only accidental route left to permissive: a bare :setup is closed and `_` is
+// the opt-out you have to ask for, so the mode nothing lands in by accident is
+// still reachable by getting it wrong. Both of parsePropsPattern's nulls count
+// - not-an-object (",{ a }", "props") and unbalanced ("{ a, b") - and only `_`
+// is exempt, because intent is the sole thing separating it from the typos
+const warnUnreadableSignature = (script: TagBlock, pattern: string) => {
+  if (pattern.trim() === "_" || signatureWarned.has(script)) return
+  signatureWarned.add(script)
+  console.warn(
+    `jq79: :setup="${pattern}" is not a props pattern, so this component declares no ` +
+    `signature and takes whatever a parent passes - write the props it takes ` +
+    `("{ a, b }"), a bare :setup for none, or "_" to stay open on purpose`
+  )
 }
 
 // every prop name a component's scripts declare, across both script modes.
@@ -2218,6 +2338,8 @@ export class Component79 {
     // a different key
     reportedExprErrors.clear()
     pendingReports.clear()
+    reportedFailedExprs.clear()
+    failedExprs.clear()
     const marker = this.startMarker
     const rendered = !!(marker && this.content)