jq79 0.5.1 → 0.5.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jq79",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "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

@@ -94,12 +94,95 @@ const compileExpr = (expr: string, params: string[]): Function | null => {
   return fn
 }
 
+// a template expression is re-evaluated constantly - once per effect run, once
+// per interpolation, once per :each item - so a value that is briefly undefined
+// mid-render has to fail quietly, and the catch below stays. A ReferenceError
+// is the one failure worth a word: `with` resolves a name against the store and
+// then globalThis, so a name that resolves nowhere is declared nowhere - a
+// typo, a dropped prop, or the trap this was written for, a top-level
+// `function` declaration, which transformSetupScript leaves as an ordinary
+// lexical binding instead of a store property
+//
+// It is reported late rather than where it throws, because "declared nowhere"
+// is not yet decidable at that moment: a factory script assigns its bindings to
+// the store when it returns, so an async factory renders its whole template
+// before any of its names exist. Reporting waits until no script is still
+// running (pendingScripts), and then asks whether the name resolves *now*.
+//
+// The re-check is `name in scope` rather than a re-evaluation, because
+// re-evaluating is not pure: `@click="count++ + missing"` increments before it
+// throws, and running it again to see if it still throws would increment twice
+// and notify. `in` walks the same scope chain (:each scopes are
+// Object.create(scope), :with is a proxy over it) and evaluates nothing
+const MISSING_NAME_RE = /^(?:([\w$]+) is not defined|Can't find variable: ([\w$]+))/
+
+// the queue holds live scopes, so it is capped: a script that never settles
+// would otherwise let it grow for the life of the page
+const MAX_PENDING_REPORTS = 100
+
+type PendingReport = { name: string; expr: string; scope: Record<string, any> }
+
+const pendingReports = new Map<string, PendingReport>()
+const reportedExprErrors = new Set<string>()
+let pendingScripts = 0
+let flushScheduled = false
+
+const flushExprReports = () => {
+  flushScheduled = false
+  if (pendingScripts > 0) return // a script started meanwhile; its release re-schedules
+  pendingReports.forEach(({ name, expr, scope }, key) => {
+    if (name in scope) return // it arrived late - a factory's bindings, a prop
+    reportedExprErrors.add(key)
+    console.warn(
+      `jq79: ${name} is not defined - evaluating "${expr}". Template expressions ` +
+      `resolve against the component store: a top-level let/var/const in a :setup ` +
+      `script, a declared prop, or a global. Note a "function name() {}" declaration ` +
+      `is not on the store - write "const name = () => {}".`
+    )
+  })
+  pendingReports.clear()
+}
+
+const scheduleExprReportFlush = () => {
+  if (flushScheduled || pendingScripts > 0 || !pendingReports.size) return
+  flushScheduled = true
+  queueMicrotask(flushExprReports)
+}
+
+// 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
+const trackScript = (settled: Promise<unknown>) => {
+  pendingScripts++
+  const release = () => {
+    pendingScripts--
+    scheduleExprReportFlush()
+  }
+  settled.then(release, release)
+}
+
+const reportExprError = (expr: string, scope: Record<string, any>, error: unknown) => {
+  if (!(error instanceof ReferenceError)) return
+  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
+  // keyed on name and expression, not on the expression alone, so two missing
+  // names in one expression stay distinguishable - and so a :each of 1000 items
+  // enqueues one entry rather than 1000
+  const key = `${name}|${expr}`
+  if (reportedExprErrors.has(key) || pendingReports.has(key)) return
+  if (pendingReports.size >= MAX_PENDING_REPORTS) return
+  pendingReports.set(key, { name, expr, scope })
+  scheduleExprReportFlush()
+}
+
 const evalExpr = (expr: string, scope: Record<string, any>, extras?: Record<string, any>): any => {
   const fn = compileExpr(expr, extras ? Object.keys(extras) : [])
   if (!fn) return undefined
   try {
     return fn(scope, ...(extras ? Object.values(extras) : []))
-  } catch {
+  } catch (error) {
+    reportExprError(expr, scope, error)
     return undefined
   }
 }
@@ -1598,6 +1681,43 @@ const componentPartsFrom = (elements: Element[], hashSource: string): ComponentP
 const importResource = (url: string): Promise<any> =>
   /\.html?([?#]|$)/.test(url) ? fetchComponent(url) : import(url)
 
+// a relative specifier means "next to the file that wrote it", so it is
+// resolved against the component's own URL before importResource sees it -
+// neither of that function's two branches would otherwise land there. The
+// native import() inside it resolves against *this module* (dist/jq79.js), and
+// fetch() against the document; a component in a subdirectory gets a 404 from
+// the first and the page's directory from the second.
+//
+// Only `./` and `../` are resolved. A bare specifier ("lodash") belongs to the
+// import map or the native resolver, and resolving it would quietly turn it
+// into a path; anything already absolute means one thing under any base. That
+// keeps this the browser's rule rather than a third one of our own.
+//
+// The base is absolutized first, the way hotKey does and for the same reason:
+// the filename may itself be relative ("./card.html", from an import() in a
+// parent), and a relative URL cannot be a base.
+//
+// What comes back is a path whenever it lands on the page's own origin, and a
+// full URL only when it doesn't (a component served from a CDN resolves its
+// siblings on that CDN). Both are the same request, but the path keeps the
+// value the shape everything downstream already sees - what hotKey keys on,
+// what devtools shows as the script's name - so only the cross-origin case,
+// which has no path form, introduces a new one
+const resolveSpecifier = (spec: string, filename: string | undefined): string => {
+  if (!/^\.\.?\//.test(spec)) return spec
+  try {
+    const page = new URL(document.baseURI)
+    const url = new URL(spec, new URL(filename ?? "", page))
+    // "null" is what an opaque origin (file:, blob:) reports, for both sides
+    // and for anything else - it says the origins are unknown, not equal
+    return url.origin !== "null" && url.origin === page.origin
+      ? `${url.pathname}${url.search}${url.hash}`
+      : url.href
+  } catch {
+    return spec
+  }
+}
+
 // ---------------------------------------------------------------------------
 // naming scripts for devtools
 //
@@ -1682,6 +1802,7 @@ const runSetupScript = (code: string, scope: Record<string, any>, effect: (run:
     `return (async () => { with ($scope) { ${code} } })()${sourceUrlComment(at.filename, at.index ?? 0)}`
   )(scriptScope, effect, importer, ...Object.values(helpers))
   result.catch(error => console.error("jq79: error in :setup script", error))
+  trackScript(result)
 }
 
 // puts a component's declared props on the store, before any script runs and
@@ -1838,11 +1959,16 @@ const runFactoryScript = (code: string, scope: Record<string, any>, effect: (run
 
   const logError = (error: any) => console.error("jq79: error in factory script", error)
   let invoked = false
-  const invoke = () => {
-    if (invoked) return
+  // what invoke() is still waiting on, memoized: it is called from both paths
+  // below and does its work once, but the *second* caller is the one whose
+  // promise is tracked - without this it would see `undefined` and count the
+  // script as settled while an async factory's bindings are still on the way
+  let merging: Promise<void> | undefined
+  const invoke = (): Promise<void> | undefined => {
+    if (invoked) return merging
     invoked = true
     const factory = $__exports.default
-    if (typeof factory !== "function") return
+    if (typeof factory !== "function") return undefined
     const merge = (bindings: any) => {
       if (bindings && typeof bindings === "object") Object.assign(scope, bindings)
     }
@@ -1853,14 +1979,18 @@ const runFactoryScript = (code: string, scope: Record<string, any>, effect: (run
       // the props it declared (copying, as destructuring does - $props is the
       // live view for a primitive the parent reassigns later)
       const returned = factory(scope, { $data: scope, $props: scope, $effect: effect, ...instanceHelpers })
-      if (returned instanceof Promise) returned.then(merge).catch(logError)
+      if (returned instanceof Promise) merging = returned.then(merge).catch(logError)
       else merge(returned)
     } catch (error) {
       logError(error)
     }
+    return merging
   }
 
-  result.then(invoke, logError)
+  // tracked through the merge, not just the module body: a factory's names
+  // reach the store in `merge`, and a template expression that reads one before
+  // then is not an authoring mistake (see reportExprError)
+  trackScript(result.then(invoke, logError))
   if ($__exports.done) invoke() // fully-sync body: factory runs before first render
 }
 
@@ -2079,6 +2209,13 @@ export class Component79 {
   // while its markers sit where its DOM actually is
   hotReplace(src: string | ComponentParts): boolean {
     const parts = typeof src === "string" ? parseComponentString(src) : src
+    // the source just changed, so what was already said about it no longer
+    // applies: without this the author fixes the typo, saves, and the next typo
+    // in the same expression is deduped away against the old one. `compiled`
+    // needs no such reset - it is keyed by expression text, so edited source is
+    // a different key
+    reportedExprErrors.clear()
+    pendingReports.clear()
     const marker = this.startMarker
     const rendered = !!(marker && this.content)
 
@@ -2253,10 +2390,15 @@ export class Component79 {
 
     // import() calls whose specifier was pre-resolved by a bundler (the
     // modules map) get the bundled module; everything else falls back to the
-    // runtime importResource (fetch for .html, native import otherwise)
+    // runtime importResource (fetch for .html, native import otherwise),
+    // relative to this component's file. The map is keyed by the literal
+    // specifier the script wrote, so it is consulted *before* resolution -
+    // what the bundler hoisted and what the source says are the same string
     const modules = this.modules
     const $import = (url: string): Promise<any> =>
-      modules && url in modules ? Promise.resolve(modules[url]) : importResource(url)
+      modules && url in modules
+        ? Promise.resolve(modules[url])
+        : importResource(resolveSpecifier(url, this.filename))
 
     // the writeback half of :model, from the child's side: one argument is the
     // value for the default model (the bare :model), two are a name and a