kiru 1.2.0 → 1.3.0

package/src/error.ts

@@ -1,6 +1,5 @@
-import { $KIRU_ERROR } from "./constants.js"
+import { $DEV_FILE_LINK, $KIRU_ERROR } from "./constants.js"
 import { __DEV__ } from "./env.js"
-import { findParent, noop } from "./utils/index.js"
 
 type KiruErrorOptions =
   | string
@@ -16,8 +15,6 @@ export class KiruError extends Error {
   [$KIRU_ERROR] = true
   /** Indicates whether the error is fatal and should crash the application */
   fatal?: boolean
-  /** Present if vNode is provided */
-  customNodeStack?: string
   constructor(optionsOrMessage: KiruErrorOptions) {
     const message =
       typeof optionsOrMessage === "string"
@@ -26,18 +23,21 @@ export class KiruError extends Error {
     super(message)
     if (typeof optionsOrMessage !== "string") {
       if (__DEV__ && optionsOrMessage?.vNode) {
-        this.customNodeStack = captureErrorStack(optionsOrMessage.vNode)
+        const stack = createVNodeStack(optionsOrMessage.vNode)
+        this.message = `${message}
+${stack.map((item) => `    at ${item}`).join("\n")}
+`
       }
       this.fatal = optionsOrMessage?.fatal
     }
   }
 
   static isKiruError(error: unknown): error is KiruError {
-    return error instanceof Error && (error as KiruError)[$KIRU_ERROR] === true
+    return error instanceof Error && $KIRU_ERROR in error
   }
 }
 
-function captureErrorStack(vNode: Kiru.VNode) {
+function createVNodeStack(vNode: Kiru.VNode) {
   let n = vNode
   let componentFns: string[] = []
   while (n) {
@@ -45,24 +45,16 @@ function captureErrorStack(vNode: Kiru.VNode) {
     if (typeof n.type === "function") {
       componentFns.push(getComponentErrorDisplayText(n.type))
     } else if (typeof n.type === "string") {
-      componentFns.push(n.type)
+      componentFns.push(`<${n.type}>`)
     }
     n = n.parent
   }
-  const componentNode = (
-    typeof vNode.type === "function"
-      ? vNode
-      : findParent(vNode, (n) => typeof n.type === "function")
-  ) as (Kiru.VNode & { type: Function }) | null
-  return `The above error occurred in the <${getFunctionName(
-    componentNode?.type || noop
-  )}> component:
 
-${componentFns.map((x) => `   at ${x}`).join("\n")}\n`
+  return componentFns
 }
 
 function getComponentErrorDisplayText(fn: Function) {
-  let str = getFunctionName(fn)
+  let str = `<${getFunctionName(fn)}>`
   if (__DEV__) {
     const fileLink = getComponentFileLink(fn)
     if (fileLink) {
@@ -77,5 +69,5 @@ function getFunctionName(fn: Function) {
 }
 
 function getComponentFileLink(fn: Function) {
-  return fn.toString().match(/\/\/ \[kiru_devtools\]:(.*)/)?.[1] ?? null
+  return (fn as any)[$DEV_FILE_LINK] ?? null
 }

package/src/headlessRender.ts

@@ -7,8 +7,8 @@ import {
   assertValidElementProps,
   isPrimitiveChild,
   isValidTextChild,
+  isStreamDataThrowValue,
 } from "./utils/index.js"
-import { isStreamDataThrowValue } from "./statefulPromise.js"
 import { Signal } from "./signals/base.js"
 import { $ERROR_BOUNDARY, voidElements, $STREAM_DATA } from "./constants.js"
 import { __DEV__ } from "./env.js"
@@ -16,14 +16,14 @@ import type { ErrorBoundaryNode } from "./types.utils"
 
 export interface HeadlessRenderContext {
   write(chunk: string): void
-  onStreamData?: (data: Kiru.StatefulPromiseBase<unknown>[]) => void
+  onStreamData?: (data: Kiru.StatefulPromise<unknown>[]) => void
 }
 
 export function headlessRender(
   ctx: HeadlessRenderContext,
   el: unknown,
-  parent: Kiru.VNode | null,
-  idx: number
+  parent: Kiru.VNode | null = null,
+  idx: number = 0
 ): void {
   if (el === null) return
   if (el === undefined) return
@@ -66,7 +66,7 @@ export function headlessRender(
   if (isExoticType(type)) {
     if (type === $ERROR_BOUNDARY) {
       let boundaryBuffer = ""
-      const streamPromises = new Set<Kiru.StatefulPromiseBase<unknown>>()
+      const streamPromises = new Set<Kiru.StatefulPromise<unknown>>()
       const boundaryCtx: HeadlessRenderContext = {
         write(chunk) {
           boundaryBuffer += chunk

package/src/hmr.ts

@@ -98,6 +98,8 @@ export function createHmrContext() {
     if (currentModuleMemory === null)
       throw new Error("[kiru]: HMR could not register: No active module")
 
+    // TODO: we should call destroy() on unmatched old entries
+
     let dirtyNodes = new Set<Kiru.VNode>()
     for (const [name, newEntry] of Object.entries(hotVarRegistrationEntries)) {
       const oldEntry = currentModuleMemory.hotVars.get(name)
@@ -120,10 +122,10 @@ export function createHmrContext() {
         isGenericHmrAcceptor(oldEntry.value) &&
         isGenericHmrAcceptor(newEntry.value)
       ) {
-        newEntry.value[$HMR_ACCEPT].inject(
-          oldEntry.value[$HMR_ACCEPT].provide()
+        performHmrAccept(
+          oldEntry.value[$HMR_ACCEPT],
+          newEntry.value[$HMR_ACCEPT]
         )
-        oldEntry.value[$HMR_ACCEPT].destroy()
         continue
       }
       if (oldEntry.type === "component" && newEntry.type === "component") {
@@ -192,3 +194,11 @@ export function onHmr(callback: () => void): void {
     window.__kiru.HMRContext.onHmr(callback)
   }
 }
+
+export function performHmrAccept<T>(
+  oldThing: HMRAccept<T>,
+  newThing: HMRAccept<T>
+) {
+  newThing.inject(oldThing.provide())
+  oldThing.destroy()
+}

package/src/hooks/setup.ts

@@ -1,8 +1,12 @@
-import { computed, signal } from "../signals/index.js"
+import { signal, Signal } from "../signals/base.js"
 import { createVNodeId } from "../utils/vdom.js"
 import { __DEV__ } from "../env.js"
 import { node, setups } from "../globals.js"
-import type { Signal } from "../signals/base.js"
+import {
+  tracking,
+  type TrackingStackObservations,
+} from "../signals/tracking.js"
+import { registerVNodeCleanup } from "../utils/index.js"
 
 export interface Setup<Props extends {}> {
   readonly derive: <T>(
@@ -36,7 +40,6 @@ export function setup<Props extends {}>(): Setup<Props> {
   setups.set(vNode, setup)
   return setup
 }
-
 function createSetup<Props extends {}>(vNode: Kiru.VNode): Setup<Props> {
   let id: Signal<string>
 
@@ -45,12 +48,89 @@ function createSetup<Props extends {}>(vNode: Kiru.VNode): Setup<Props> {
 
   let prevIndex = -1
 
-  return {
-    derive(selector) {
-      const props = { ...vNode.props } as InferredProps
-      const sig = computed(() => selector(props))
-      propSyncs.push((p) => (sig.value = selector(p)))
-      return sig
+  // Always points at latest props (updated in propSync) so selector and subs see current props
+  const currentProps = { current: { ...vNode.props } as InferredProps }
+  const deriveCleanups: Array<() => void> = []
+
+  type DeriveEntry = { run: () => void; accessedPaths: Set<string> }
+  const deriveEntries: DeriveEntry[] = []
+
+  propSyncs.push((p) => {
+    const old = currentProps.current as Record<string, unknown>
+    const skip = new Set<DeriveEntry>()
+    for (const entry of deriveEntries) {
+      if (
+        entry.accessedPaths.size > 0 &&
+        propsUnchangedAtPaths(
+          old,
+          p as Record<string, unknown>,
+          entry.accessedPaths
+        )
+      ) {
+        skip.add(entry)
+      }
+    }
+    currentProps.current = p
+    for (const entry of deriveEntries) {
+      if (!skip.has(entry)) entry.run()
+    }
+  })
+
+  registerVNodeCleanup(vNode, "vnode:setup", () => {
+    for (const cleanup of deriveCleanups) cleanup()
+    setups.delete(vNode)
+  })
+
+  const setupResult: Setup<Props> = {
+    derive<T>(
+      selector: (props: Props extends Kiru.FC<infer P> ? P : Props) => T
+    ) {
+      const resultSig = signal(undefined!) as Signal<T>
+      const unsubs = new Map<string, () => void>()
+      const accessedPaths = new Set<string>()
+
+      function sync() {
+        accessedPaths.clear()
+        const propsProxy = createPropsProxy(
+          currentProps.current as Record<string, unknown>,
+          accessedPaths
+        ) as InferredProps
+        const observations: TrackingStackObservations = new Map()
+        tracking.stack.push(observations)
+        const value = selector(propsProxy)
+        tracking.stack.pop()
+        // Always assign and notify so the component re-renders when the derived value changes
+        // (e.g. when parent passes a different signal ref like toggle switching count/double).
+        resultSig.value = value
+
+        for (const [sid, unsub] of unsubs) {
+          if (!observations.has(sid)) {
+            unsub()
+            unsubs.delete(sid)
+          }
+        }
+        for (const [sid, observedSig] of observations) {
+          if (!unsubs.has(sid)) {
+            try {
+              unsubs.set(sid, observedSig.subscribe(sync))
+            } catch {
+              // Signal may be disposed after HMR; skip subscribing
+            }
+          }
+        }
+      }
+
+      sync()
+      const entry: DeriveEntry = { run: sync, accessedPaths }
+      deriveEntries.push(entry)
+      deriveCleanups.push(() => {
+        unsubs.forEach((u) => u())
+        unsubs.clear()
+        const i = deriveEntries.indexOf(entry)
+        if (i !== -1) deriveEntries.splice(i, 1)
+      })
+
+      return resultSig
     },
     get id() {
       if (!id) {
@@ -67,4 +147,58 @@ function createSetup<Props extends {}>(vNode: Kiru.VNode): Setup<Props> {
       return id
     },
   }
+  return setupResult
+}
+function propsUnchangedAtPaths(
+  oldProps: Record<string, unknown>,
+  newProps: Record<string, unknown>,
+  paths: Set<string>
+): boolean {
+  for (const path of paths) {
+    if (!Object.is(getAtPath(oldProps, path), getAtPath(newProps, path))) {
+      return false
+    }
+  }
+  return true
+}
+
+function getAtPath(obj: Record<string, unknown>, path: string): unknown {
+  let cur: unknown = obj
+  for (const key of path.split(".")) {
+    if (cur == null || typeof cur !== "object") return undefined
+    cur = (cur as Record<string, unknown>)[key]
+  }
+  return cur
+}
+
+/**
+ * Proxy that records paths and wraps signals. We only add to accessedPaths when
+ * we hit a signal (the leaf we subscribe to), so propSync skip only compares
+ * signal refs. Container objects (e.g. "data") are new every render and would
+ * always fail the skip.
+ */
+function createPropsProxy<P extends Record<string, unknown>>(
+  props: P,
+  accessedPaths: Set<string>,
+  pathPrefix?: string
+): P {
+  return new Proxy(props, {
+    get(holder, key: string) {
+      const path = pathPrefix ? `${pathPrefix}.${key}` : key
+      const v = holder[key]
+      if (Signal.isSignal(v)) {
+        accessedPaths.add(path) // only record path for signal leaves
+        return v
+      }
+      if (v !== null && typeof v === "object" && !Array.isArray(v)) {
+        return createPropsProxy(
+          v as Record<string, unknown>,
+          accessedPaths,
+          path
+        ) as P[keyof P]
+      }
+      accessedPaths.add(path) // primitive leaf
+      return v
+    },
+  }) as P
 }

package/src/index.ts

@@ -22,7 +22,7 @@ export {
   requestUpdate,
   useRequestUpdate,
 } from "./scheduler.js"
-export * from "./statefulPromise.js"
+export * from "./resource.js"
 export * from "./viewTransitions.js"
 
 if (isBrowser) {

package/src/renderToString.ts

@@ -11,7 +11,7 @@ export function renderToString(element: JSX.Element) {
       result += chunk
     },
   }
-  headlessRender(ctx, Fragment({ children: element }), null, 0)
+  headlessRender(ctx, Fragment({ children: element }))
   renderMode.current = prev
   return result
 }

package/src/resource.ts

@@ -0,0 +1,207 @@
+import { $HMR_ACCEPT, STREAMED_DATA_EVENT } from "./constants.js"
+import { hydrationMode, node, renderMode } from "./globals.js"
+import { Signal, signal } from "./signals/base.js"
+import { createVNodeId, registerVNodeCleanup } from "./utils/vdom.js"
+import { generateRandomID } from "./utils/generateId.js"
+import { __DEV__, isBrowser } from "./env.js"
+import { GenericHMRAcceptor, performHmrAccept } from "./hmr.js"
+
+/**
+ * Returns true if the value is a {@link Resource}
+ */
+export function isResource(thing: unknown): thing is Resource<unknown> {
+  return (
+    Signal.isSignal(thing) &&
+    "promise" in thing &&
+    thing["promise"] instanceof Promise
+  )
+}
+
+const resourceMeta = new WeakMap<Kiru.VNode, { id: string; index: number }>()
+
+interface ResourceState<T> {
+  error: Signal<Error | null>
+  isPending: Signal<boolean>
+  promise: Kiru.StatefulPromise<T>
+  refetch: () => void
+  dispose: () => void
+}
+
+export type Resource<T> = Kiru.Signal<T> & ResourceState<T>
+export interface ResourceLoaderContext {
+  signal: AbortSignal
+}
+
+export function resource<T, Source>(
+  source: Kiru.Signal<Source>,
+  callback: (source: Source, ctx: ResourceLoaderContext) => Promise<T>
+): Resource<T> {
+  const data = signal(void 0 as T)
+  const error = signal<Error | null>(null)
+  const isPending = signal(true)
+
+  let promiseId = ""
+  const vNode = node.current
+  if (!vNode) {
+    // todo: investigate streaming global resources via SSR
+    // likely cooked since we can't ensure modules are loaded in the same order,
+  } else if (
+    renderMode.current === "hydrate" ||
+    renderMode.current === "stream"
+  ) {
+    // hydrate or stream - create a deterministic id + index offset to use for promise hydration
+    const { id, index } = resourceMeta.get(vNode) ?? {
+      id: createVNodeId(vNode),
+      index: 0,
+    }
+    promiseId = `${id}:resource:${index}`
+    resourceMeta.set(vNode, { id, index: index + 1 })
+  } else {
+    // could be improved. For now, just use a random id to prevent collisions on the cleanups map.
+    // in future, we could implement a cached id based on the vNode for use across other modules too.
+    promiseId = generateRandomID()
+  }
+
+  const unsub = source.subscribe((src) => {
+    resource.promise = createPromise(src)
+    resource.notify()
+  })
+
+  let controller = new AbortController()
+  const dispose = () => {
+    if (!controller.signal.aborted) controller.abort()
+    Signal.dispose(data)
+    Signal.dispose(isPending)
+    unsub()
+  }
+
+  if (vNode) {
+    registerVNodeCleanup(vNode, promiseId, dispose)
+  }
+
+  const resource: Resource<T> = Object.assign(data, {
+    error,
+    isPending,
+    promise: undefined as unknown as Kiru.StatefulPromise<T>,
+    refetch() {
+      data.value = void 0 as T
+      this.promise = createPromise(source.peek())
+    },
+    dispose,
+  })
+
+  if (__DEV__) {
+    const { inject: baseInject, destroy: baseDestroy } = data[$HMR_ACCEPT]!
+
+    ;(resource as any as GenericHMRAcceptor<Resource<T>>)[$HMR_ACCEPT] = {
+      provide: () => {
+        return resource
+      },
+      destroy: () => {
+        baseDestroy()
+        controller.abort()
+      },
+      inject: (prev) => {
+        baseInject(prev)
+        const { isPending: prevPending, error: prevError } = prev
+        const { isPending, error } = resource
+        performHmrAccept(prevPending[$HMR_ACCEPT]!, isPending[$HMR_ACCEPT]!)
+        performHmrAccept(prevError[$HMR_ACCEPT]!, error[$HMR_ACCEPT]!)
+      },
+    }
+  }
+
+  if (__DEV__ && isBrowser && window.__kiru.HMRContext?.isReplacement()) {
+    queueMicrotask(() => {
+      resource.promise = createPromise(source.peek())
+    })
+  } else {
+    resource.promise = createPromise(source.peek())
+  }
+
+  function createPromise(source: Source): Kiru.StatefulPromise<T> {
+    controller.abort()
+    const ctrl = (controller = new AbortController())
+    isPending.value = true
+    let newPromise: Promise<T>
+    if (renderMode.current === "string") {
+      // if we're rendering to a string, there's no need to fire the callback
+      newPromise = Promise.resolve() as Promise<T>
+    } else if (
+      renderMode.current === "hydrate" &&
+      hydrationMode.current === "dynamic"
+    ) {
+      // if we're hydrating and the hydration mode is not static,
+      // we need to resolve the promise from cache/event
+      newPromise = resolveDeferredPromise<T>(promiseId, ctrl.signal)
+    } else {
+      // stream / dom / (hydrate + static)
+      newPromise = callback(source, { signal: ctrl.signal })
+    }
+
+    const statefulPromise: Kiru.StatefulPromise<T> = Object.assign(newPromise, {
+      id: promiseId,
+      state: "pending",
+    } satisfies Kiru.PromiseState<T>)
+
+    statefulPromise
+      .then((value) => {
+        statefulPromise.state = "fulfilled"
+        statefulPromise.value = value
+        data.value = value
+        isPending.value = false
+        error.value = null
+      })
+      .catch((e) => {
+        if (ctrl !== controller) return // prevent setting pending=false if new controller was recreated (new promise)
+        statefulPromise.state = "rejected"
+        statefulPromise.error = e instanceof Error ? e : new Error(e)
+        error.value = statefulPromise.error
+        isPending.value = false
+      })
+    return statefulPromise
+  }
+
+  return resource
+}
+
+interface DeferredPromiseEventDetail<T> {
+  id: string
+  data?: T
+  error?: string
+}
+
+function resolveDeferredPromise<T>(
+  id: string,
+  signal: AbortSignal
+): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const deferralCache: Map<string, { data?: T; error?: string }> = // @ts-ignore
+      (window[STREAMED_DATA_EVENT] ??= new Map())
+
+    const existing = deferralCache.get(id)
+    if (existing) {
+      const { data, error } = existing
+      deferralCache.delete(id)
+      if (error) return reject(error)
+      return resolve(data!)
+    }
+
+    const onDataEvent = (event: Event) => {
+      const { detail } = event as CustomEvent<DeferredPromiseEventDetail<T>>
+      if (detail.id === id) {
+        deferralCache.delete(id)
+        window.removeEventListener(STREAMED_DATA_EVENT, onDataEvent)
+        const { data, error } = detail
+        if (error) return reject(error)
+        resolve(data!)
+      }
+    }
+
+    window.addEventListener(STREAMED_DATA_EVENT, onDataEvent)
+    signal.addEventListener("abort", () => {
+      window.removeEventListener(STREAMED_DATA_EVENT, onDataEvent)
+      reject()
+    })
+  })
+}

package/src/scheduler.ts

@@ -22,6 +22,7 @@ import {
   findParentErrorBoundary,
   call,
   propsChanged,
+  depthSort,
 } from "./utils/index.js"
 import { __DEV__ } from "./env.js"
 import { KiruError } from "./error.js"
@@ -129,8 +130,6 @@ function queueDelete(vNode: VNode): void {
   deletions.push(vNode)
 }
 
-const depthSort = (a: VNode, b: VNode): number => b.depth - a.depth
-
 let currentWorkRoot: VNode | null = null
 
 function doWork(): void {
@@ -281,11 +280,6 @@ function updateVNode(vNode: VNode): VNode | null {
     }
 
     if (KiruError.isKiruError(error)) {
-      if (error.customNodeStack) {
-        setTimeout(() => {
-          throw new Error(error.customNodeStack)
-        })
-      }
       if (error.fatal) {
         throw error
       }
@@ -390,7 +384,7 @@ function renderFunctionComponent(
   props: Record<string, unknown>,
   shouldSyncProps: boolean
 ): unknown {
-  const { render, propSyncs } = vNode
+  let { render, propSyncs } = vNode
 
   if (render) {
     if (shouldSyncProps) {
@@ -400,9 +394,20 @@ function renderFunctionComponent(
     return render(props)
   }
 
-  let newChild = latest(type)(props)
+  if (__DEV__) {
+    type = latest(type)
+    if (typeof type !== "function") {
+      throw new KiruError({
+        message: `received invalid component type: ${type}`,
+        fatal: true,
+        vNode,
+      })
+    }
+  }
+
+  let newChild = type(props)
   if (typeof newChild === "function") {
-    vNode.subs?.forEach(call) // unsub from signals observered during setup
+    vNode.subs?.forEach(call) // unsub from signals observed during setup
     vNode.render = newChild
     if (shouldSyncProps) {
       const p = { ...props }
@@ -445,7 +450,7 @@ function updateHostComponent(vNode: DomVNode): VNode | null {
 function checkForTooManyConsecutiveDirtyRenders(): void {
   if (consecutiveDirtyCount > CONSECUTIVE_DIRTY_LIMIT) {
     throw new KiruError(
-      "Maximum update depth exceeded. This can happen when a component repeatedly calls setState during render or in useLayoutEffect. Kiru limits the number of nested updates to prevent infinite loops."
+      "Maximum update depth exceeded. This can happen when a component repeatedly updates during render or in onBeforeMount. Kiru limits the number of nested updates to prevent infinite loops."
     )
   }
 }