kiru 1.2.1 → 1.3.1

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

@@ -280,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
       }
@@ -389,7 +384,7 @@ function renderFunctionComponent(
   props: Record<string, unknown>,
   shouldSyncProps: boolean
 ): unknown {
-  const { render, propSyncs } = vNode
+  let { render, propSyncs } = vNode
 
   if (render) {
     if (shouldSyncProps) {
@@ -399,7 +394,18 @@ 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 observed during setup
     vNode.render = newChild
@@ -444,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."
     )
   }
 }

package/src/signals/base.ts

@@ -9,16 +9,15 @@ import { $DEV_FILE_LINK, $HMR_ACCEPT, $SIGNAL } from "../constants.js"
 import { __DEV__, isBrowser } from "../env.js"
 import { node } from "../globals.js"
 import { requestUpdate } from "../scheduler.js"
-import { signalSubsMap } from "./globals.js"
 import { tracking } from "./tracking.js"
-import type { SignalSubscriber, ReadonlySignal } from "./types.js"
+import type { SignalSubscriber } from "./types.js"
 import type { HMRAccept } from "../hmr.js"
 
 export class Signal<T> {
   [$SIGNAL] = true;
   [$HMR_ACCEPT]?: HMRAccept<Signal<any>>
   displayName?: string
-  protected $subs?: Set<SignalSubscriber<any>>
+  protected $subs: Set<SignalSubscriber<any>>
   protected $id: string
   protected $value: T
   protected $prevValue?: T
@@ -29,10 +28,10 @@ export class Signal<T> {
   constructor(initial: T, displayName?: string) {
     this.$id = generateRandomID()
     this.$value = initial
+    this.$subs = new Set()
     if (displayName) this.displayName = displayName
 
     if (__DEV__) {
-      signalSubsMap.set(this.$id, new Set())
       this.$initialValue = safeStringify(initial)
       this[$HMR_ACCEPT] = {
         provide: () => {
@@ -40,11 +39,11 @@ export class Signal<T> {
         },
         inject: (prev) => {
           if (isBrowser) window.__kiru.devtools?.untrack(prev)
-          signalSubsMap.get(this.$id)?.clear?.()
-          signalSubsMap.delete(this.$id)
           this.$id = prev.$id
-          // @ts-ignore - this handles scenarios where a reference to the prev has been encapsulated
-          // and we need to be able to refer to the latest version of the signal.
+          this.$subs = prev.$subs
+          // this is a nice-to-have so that implementations of signal-on-signal don't need to do it themselves.
+          // eg. Object.assign(signal, { nestedSignal })
+          // it's only done by our HMR pass for top-level signals.
           prev.__next = this
 
           if (this.$initialValue === prev.$initialValue) {
@@ -55,8 +54,6 @@ export class Signal<T> {
         },
         destroy: () => {},
       } satisfies HMRAccept<Signal<any>>
-    } else {
-      this.$subs = new Set()
     }
 
     const n = node.current
@@ -121,33 +118,30 @@ export class Signal<T> {
   subscribe(cb: (state: T, prevState?: T) => void): () => void {
     if (__DEV__) {
       const tgt = latest(this)
-      const subs = signalSubsMap.get(tgt.$id)!
-      if (__DEV__ && !subs) {
+      if (__DEV__ && tgt.$isDisposed) {
         const name = tgt.displayName ?? tgt.$id
-        let message = `Attempting to subscribe to a signal that has been disposed: ${name}`
+        let message = `Attempted to subscribe to a signal that has been disposed: ${name}`
         if ($DEV_FILE_LINK in tgt) {
           message += `\nFile: ${tgt[$DEV_FILE_LINK]}`
         }
         message += `\nInitial value: ${tgt.$initialValue}`
         throw new Error(message)
       }
-      subs.add(cb)
-      return () => subs.delete(cb)
     }
-    this.$subs!.add(cb)
-    return () => this.$subs!.delete(cb)
+    this.$subs.add(cb)
+    return () => this.$subs.delete(cb)
   }
 
   notify(filter?: (sub: SignalSubscriber) => boolean) {
     if (__DEV__) {
       const tgt = latest(this)
-      return signalSubsMap.get(tgt.$id)?.forEach((sub) => {
+      return tgt.$subs.forEach((sub) => {
         if (filter && !filter(sub)) return
         const { $value, $prevValue } = latest(this)
         return sub($value, $prevValue)
       })
     }
-    this.$subs!.forEach((sub) => {
+    this.$subs.forEach((sub) => {
       if (filter && !filter(sub)) return
       return sub(this.$value, this.$prevValue)
     })
@@ -158,43 +152,9 @@ export class Signal<T> {
   }
 
   static subscribers(signal: Signal<any>) {
-    if (__DEV__) {
-      signal = latest(signal)
-      return signalSubsMap.get(signal.$id)!
-    }
     return signal.$subs
   }
 
-  static makeReadonly<T>(signal: Signal<T>): ReadonlySignal<T> {
-    if (__DEV__) signal = latest(signal)
-    const desc = Object.getOwnPropertyDescriptor(signal, "value")
-    if (desc && !desc.writable) return signal
-    return Object.defineProperty(signal, "value", {
-      get: function (this: Signal<T>) {
-        Signal.entangle(this)
-        return this.$value
-      },
-      configurable: true,
-    })
-  }
-
-  static makeWritable<T>(signal: Signal<T>): Signal<T> {
-    if (__DEV__) signal = latest(signal)
-    const desc = Object.getOwnPropertyDescriptor(signal, "value")
-    if (desc && desc.writable) return signal
-    return Object.defineProperty(signal, "value", {
-      get: function (this: Signal<T>) {
-        Signal.entangle(this)
-        return this.$value
-      },
-      set: function (this: Signal<T>, value) {
-        this.$value = value
-        this.notify()
-      },
-      configurable: true,
-    })
-  }
-
   static entangle<T>(signal: Signal<T>) {
     if (tracking.enabled === false) return
     if (__DEV__) signal = latest(signal)
@@ -202,6 +162,7 @@ export class Signal<T> {
     const vNode = node.current
     const trackedSignalObservations = tracking.current()
     if (trackedSignalObservations) {
+      // track non-rendering access, only track rendering access if renderMode is DOM/hydrate
       if (!vNode || (vNode && sideEffectsEnabled())) {
         trackedSignalObservations.set(signal.$id, signal)
       }
@@ -213,14 +174,14 @@ export class Signal<T> {
   }
 
   static dispose(signal: Signal<any>) {
+    if (signal.$isDisposed) return
+
     signal.$isDisposed = true
     if (__DEV__) {
-      signal = latest(signal)
-      signalSubsMap.delete(signal.$id)
-      if (isBrowser) window.__kiru.devtools?.untrack(signal)
+      if (isBrowser) window.__kiru.devtools?.untrack(latest(signal))
       return
     }
-    signal.$subs!.clear()
+    signal.$subs.clear()
   }
 }
 

package/src/signals/computed.ts

@@ -1,7 +1,7 @@
 import { __DEV__ } from "../env.js"
 import { $HMR_ACCEPT } from "../constants.js"
 import { call, latest } from "../utils/index.js"
-import { effectQueue, signalSubsMap } from "./globals.js"
+import { effectQueue } from "./globals.js"
 import { executeWithTracking } from "./tracking.js"
 import { Signal } from "./base.js"
 import type { HMRAccept } from "../hmr.js"
@@ -17,14 +17,14 @@ export class ComputedSignal<T> extends Signal<T> {
     this.$isDirty = true
 
     if (__DEV__) {
-      const inject = this[$HMR_ACCEPT]!.inject!
+      const { inject: baseInject } = this[$HMR_ACCEPT]!
       // @ts-expect-error this is fine 😅
       this[$HMR_ACCEPT] = {
         provide: () => {
           return this
         },
         inject: (prev) => {
-          inject(prev)
+          baseInject(prev)
           // Stop any pending reactions on the previous instance and mark
           // this computed as dirty so it will recompute with the latest
           // dependencies after HMR.
@@ -96,11 +96,7 @@ export class ComputedSignal<T> extends Signal<T> {
       fn: () => $getter(computed.$value),
       onDepChanged: () => {
         computed.$isDirty = true
-        if (__DEV__) {
-          if (!signalSubsMap?.get(id)?.size) return
-        } else {
-          if (!computed.$subs!.size) return
-        }
+        if (!computed.$subs.size) return
         ComputedSignal.run(computed)
         if (Object.is(computed.$value, computed.$prevValue)) return
         computed.notify()

package/src/signals/globals.ts

@@ -1,4 +1 @@
-import type { SignalSubscriber } from "./types.js"
-
 export const effectQueue = new Map<string, Function>()
-export const signalSubsMap: Map<string, Set<SignalSubscriber<any>>> = new Map()

package/src/signals/types.ts

@@ -1,13 +1,10 @@
 import type { Signal } from "./base.js"
 
-export type ReadonlySignal<T> = Signal<T> & {
-  readonly value: T
-}
 export type SignalSubscriber<T = unknown> = (value: T, prevValue?: T) => void
 
 export type SignalValues<T extends readonly Signal<unknown>[]> = {
   [I in keyof T]: T[I] extends Signal<infer V>
-    ? V extends Kiru.StatefulPromiseBase<infer P>
+    ? V extends Kiru.StatefulPromise<infer P>
       ? P
       : V
     : never

package/src/ssr/server.ts

@@ -1,4 +1,3 @@
-import { Readable } from "node:stream"
 import { Fragment } from "../element.js"
 import { renderMode } from "../globals.js"
 import { STREAMED_DATA_EVENT } from "../constants.js"
@@ -20,13 +19,21 @@ d.currentScript.remove()
 </script>
 `
 
-export function renderToReadableStream(element: JSX.Element): {
+export interface ReadableStreamRenderResult {
   immediate: string
-  stream: Readable
-} {
-  const stream = new Readable({ read() {} })
+  stream: ReadableStream
+}
+
+export function renderToReadableStream(element: JSX.Element): ReadableStreamRenderResult {
+  let controller!: ReadableStreamDefaultController<string>
+  const stream = new ReadableStream<string>({
+    start(c) {
+      controller = c
+    },
+  })
+  
   const rootNode = Fragment({ children: element })
-  const streamPromises = new Set<Kiru.StatefulPromiseBase<unknown>>()
+  const streamPromises = new Set<Kiru.StatefulPromise<unknown>>()
   const pendingWritePromises: Promise<void>[] = []
 
   let immediate = ""
@@ -43,7 +50,7 @@ export function renderToReadableStream(element: JSX.Element): {
           .catch(() => ({ error: promise.error?.message }))
           .then((value) => {
             const content = JSON.stringify(value)
-            stream.push(
+            controller.enqueue(
               `<script id="${promise.id}" k-data type="application/json">${content}</script>`
             )
           })
@@ -55,16 +62,16 @@ export function renderToReadableStream(element: JSX.Element): {
 
   const prev = renderMode.current
   renderMode.current = "stream"
-  headlessRender(ctx, rootNode, null, 0)
+  headlessRender(ctx, rootNode)
   renderMode.current = prev
 
   if (pendingWritePromises.length > 0) {
     Promise.all(pendingWritePromises).then(() => {
-      stream.push(STREAMED_DATA_SETUP)
-      stream.push(null)
+      controller.enqueue(STREAMED_DATA_SETUP)
+      controller.close()
     })
   } else {
-    stream.push(null)
+    controller.close()
   }
 
   return { immediate, stream }

package/src/types.ts

@@ -1,4 +1,4 @@
-import type { ReadonlySignal, Signal as SignalClass } from "./signals"
+import type { Signal as SignalClass } from "./signals"
 import type { $CONTEXT, $ERROR_BOUNDARY, $FRAGMENT } from "./constants"
 import type { KiruGlobalContext } from "./globalContext"
 import type {
@@ -123,9 +123,9 @@ declare global {
     }
 
     export interface FC<T = {}> {
-      (props: T):
-        | Exclude<JSX.Element, Kiru.FC<any>>
-        | ((props: T) => JSX.Element)
+      (
+        props: T
+      ): Exclude<JSX.Element, Kiru.FC<any>> | ((props: T) => JSX.Element)
       /** Used to display the name of the component in devtools  */
       displayName?: string
     }
@@ -148,13 +148,13 @@ declare global {
       error?: Error
     }
 
-    interface StatefulPromiseBase<T> extends Promise<T>, PromiseState<T> {}
+    interface StatefulPromise<T> extends Promise<T>, PromiseState<T> {}
 
     type RenderMode = "dom" | "hydrate" | "string" | "stream"
 
     type StateSetter<T> = T | ((prev: T) => T)
 
-    type Signal<T> = SignalClass<T> | ReadonlySignal<T>
+    type Signal<T> = SignalClass<T>
 
     type ExoticSymbol =
       | typeof $FRAGMENT

package/src/utils/index.ts

@@ -1,6 +1,7 @@
 export * from "./compare.js"
 export * from "./dom.js"
 export * from "./format.js"
+export * from "./generateId.js"
 export * from "./runtime.js"
+export * from "./stream.js"
 export * from "./vdom.js"
-export * from "./generateId.js"

package/src/utils/stream.ts

@@ -0,0 +1,17 @@
+import { $STREAM_DATA } from "../constants.js"
+
+export interface StreamDataThrowValue {
+  [$STREAM_DATA]: {
+    fallback?: JSX.Element
+    data: Kiru.StatefulPromise<unknown>[]
+  }
+}
+
+/**
+ * Returns true if the value is a {@link StreamDataThrowValue}
+ */
+export function isStreamDataThrowValue(
+  value: unknown
+): value is StreamDataThrowValue {
+  return typeof value === "object" && !!value && $STREAM_DATA in value
+}

package/dist/statefulPromise.d.ts

@@ -1,22 +0,0 @@
-import { $STREAM_DATA } from "./constants.js";
-import { Signal } from "./signals/base.js";
-export interface StreamDataThrowValue {
-    [$STREAM_DATA]: {
-        fallback?: JSX.Element;
-        data: Kiru.StatefulPromiseBase<unknown>[];
-    };
-}
-/**
- * Returns true if the value is a {@link StreamDataThrowValue}
- */
-export declare function isStreamDataThrowValue(value: unknown): value is StreamDataThrowValue;
-/**
- * Returns true if the value is a {@link Kiru.StatefulPromiseBase}
- */
-export declare function isStatefulPromise(thing: unknown): thing is Kiru.StatefulPromiseBase<unknown>;
-type StatefulPromise<T> = Kiru.StatefulPromiseBase<T> & {
-    isPending: Signal<boolean>;
-};
-export declare function statefulPromise<T>(callback: (signal: AbortSignal) => Promise<T>): StatefulPromise<T>;
-export {};
-//# sourceMappingURL=statefulPromise.d.ts.map

package/dist/statefulPromise.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"statefulPromise.d.ts","sourceRoot":"","sources":["../src/statefulPromise.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAuB,MAAM,gBAAgB,CAAA;AAElE,OAAO,EAAE,MAAM,EAAU,MAAM,mBAAmB,CAAA;AAIlD,MAAM,WAAW,oBAAoB;IACnC,CAAC,YAAY,CAAC,EAAE;QACd,QAAQ,CAAC,EAAE,GAAG,CAAC,OAAO,CAAA;QACtB,IAAI,EAAE,IAAI,CAAC,mBAAmB,CAAC,OAAO,CAAC,EAAE,CAAA;KAC1C,CAAA;CACF;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,oBAAoB,CAE/B;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,IAAI,CAAC,mBAAmB,CAAC,OAAO,CAAC,CAE5C;AAID,KAAK,eAAe,CAAC,CAAC,IAAI,IAAI,CAAC,mBAAmB,CAAC,CAAC,CAAC,GAAG;IACtD,SAAS,EAAE,MAAM,CAAC,OAAO,CAAC,CAAA;CAC3B,CAAA;AAED,wBAAgB,eAAe,CAAC,CAAC,EAC/B,QAAQ,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,GAC5C,eAAe,CAAC,CAAC,CAAC,CAuDpB"}