kiru 0.54.4 → 1.1.0

package/src/env.ts

@@ -4,3 +4,6 @@ if (NODE_ENV !== "development" && NODE_ENV !== "production") {
 }
 
 export const __DEV__ = NODE_ENV === "development"
+
+export const isBrowser = "window" in globalThis && typeof window !== "undefined"
+export const isServer = !isBrowser

package/src/globalContext.ts

@@ -1,63 +1,16 @@
 import { __DEV__ } from "./env.js"
-import { createHMRContext } from "./hmr.js"
+import { createHmrContext } from "./hmr.js"
 import { createProfilingContext } from "./profiling.js"
 import { fileRouterInstance } from "./router/globals.js"
 import type { FileRouterController } from "./router/fileRouterController"
-import type { AppContext } from "./appContext"
-import type { Store } from "./store"
-import type { SWRCache } from "./swr"
-import type { requestUpdate } from "./index.js"
+import type { AppHandle } from "./appHandle"
 
 export { createKiruGlobalContext, type GlobalKiruEvent, type KiruGlobalContext }
 
-interface ReactiveMap<V> {
-  add(key: string, value: V): void
-  delete(key: string): void
-  subscribe(cb: (value: Record<string, V>) => void): () => void
-  readonly size: number
-}
-
-function createReactiveMap<V>(): ReactiveMap<V> {
-  const map = new Map<string, V>()
-  const listeners = new Set<(value: Record<string, V>) => void>()
-
-  function add(key: string, value: V): void {
-    if (map.has(key)) return
-    map.set(key, value)
-    notify()
-  }
-
-  function deleteKey(key: string): void {
-    if (!map.has(key)) return
-    map.delete(key)
-    notify()
-  }
-
-  function notify(): void {
-    const val = Object.fromEntries(map)
-    listeners.forEach((cb) => cb(val))
-  }
-
-  function subscribe(cb: (value: Record<string, V>) => void): () => void {
-    listeners.add(cb)
-    cb(Object.fromEntries(map))
-    return () => listeners.delete(cb)
-  }
-
-  return {
-    add,
-    delete: deleteKey,
-    subscribe,
-    get size() {
-      return map.size
-    },
-  }
-}
-
 type Evt =
   | {
       name: "mount"
-      data?: typeof requestUpdate
+      data?: undefined
     }
   | {
       name: "unmount"
@@ -74,52 +27,51 @@ type Evt =
 
 type GlobalKiruEvent = Evt["name"]
 
-interface SchedulerInterface {
-  requestUpdate: (vNode: Kiru.VNode) => void
+export type DebuggerEntry = {
+  label: string
+  signal: Kiru.Signal<unknown>
 }
 
 interface KiruGlobalContext {
-  readonly apps: AppContext[]
-  emit<T extends Evt>(event: T["name"], ctx: AppContext, data?: T["data"]): void
+  readonly apps: AppHandle[]
+  emit<T extends Evt>(event: T["name"], app: AppHandle, data?: T["data"]): void
   on<T extends Evt>(
     event: T["name"],
-    callback: (ctx: AppContext, data: T["data"]) => void
+    callback: (app: AppHandle, data: T["data"]) => void
   ): void
   off<T extends Evt>(
     event: T["name"],
-    callback: (ctx: AppContext, data?: T["data"]) => void
+    callback: (app: AppHandle, data?: T["data"]) => void
   ): void
-  stores?: ReactiveMap<Store<any, any>>
-  HMRContext?: ReturnType<typeof createHMRContext>
+  devtools?: {
+    track: (signal: Kiru.Signal<unknown>, label?: string) => void
+    untrack: (signal: Kiru.Signal<unknown>) => void
+    subscribe: (callback: (entries: Set<DebuggerEntry>) => void) => () => void
+  }
+  HMRContext?: ReturnType<typeof createHmrContext>
   profilingContext?: ReturnType<typeof createProfilingContext>
-  SWRGlobalCache?: SWRCache
   fileRouterInstance?: {
     current: FileRouterController | null
   }
-  getSchedulerInterface?: (app: AppContext) => SchedulerInterface | null
 }
 
 function createKiruGlobalContext(): KiruGlobalContext {
-  const contexts = new Set<AppContext>()
-  const contextToSchedulerInterface = new WeakMap<
-    AppContext,
-    SchedulerInterface
-  >()
+  const apps = new Set<AppHandle>()
   const listeners = new Map<
     GlobalKiruEvent,
-    Set<(ctx: AppContext, data?: Evt["data"]) => void>
+    Set<(app: AppHandle, data?: Evt["data"]) => void>
   >()
   function emit<T extends Evt>(
     event: T["name"],
-    ctx: AppContext,
+    app: AppHandle,
     data?: T["data"]
   ): void {
-    listeners.get(event)?.forEach((cb) => cb(ctx, data))
+    listeners.get(event)?.forEach((cb) => cb(app, data))
   }
 
   function on<T extends Evt>(
     event: T["name"],
-    callback: (ctx: AppContext, data: T["data"]) => void
+    callback: (app: AppHandle, data: T["data"]) => void
   ): void {
     if (!listeners.has(event)) {
       listeners.set(event, new Set())
@@ -129,14 +81,14 @@ function createKiruGlobalContext(): KiruGlobalContext {
 
   function off<T extends Evt>(
     event: T["name"],
-    callback: (ctx: AppContext, data?: T["data"]) => void
+    callback: (ctx: AppHandle, data?: T["data"]) => void
   ): void {
     listeners.get(event)?.delete(callback)
   }
 
   const globalContext: KiruGlobalContext = {
     get apps() {
-      return Array.from(contexts)
+      return Array.from(apps)
     },
     emit,
     on,
@@ -144,24 +96,38 @@ function createKiruGlobalContext(): KiruGlobalContext {
   }
 
   // Initialize event listeners
-  on("mount", (ctx, requestUpdate) => {
-    contexts.add(ctx)
-    if (requestUpdate && typeof requestUpdate === "function") {
-      contextToSchedulerInterface.set(ctx, { requestUpdate })
-    }
-  })
-  on("unmount", (ctx) => {
-    contexts.delete(ctx)
-    contextToSchedulerInterface.delete(ctx)
-  })
+  on("mount", (app) => apps.add(app))
+  on("unmount", (app) => apps.delete(app))
 
   if (__DEV__) {
-    globalContext.HMRContext = createHMRContext()
+    globalContext.HMRContext = createHmrContext()
     globalContext.profilingContext = createProfilingContext()
-    globalContext.stores = createReactiveMap()
     globalContext.fileRouterInstance = fileRouterInstance
-    globalContext.getSchedulerInterface = (app) => {
-      return contextToSchedulerInterface.get(app) ?? null
+
+    const debuggerEntries = new Set<DebuggerEntry>()
+    const subscribers = new Set<(debuggerEntries: Set<DebuggerEntry>) => void>()
+
+    globalContext.devtools = {
+      track: (signal, label) => {
+        debuggerEntries.add({
+          label: label ?? signal.displayName ?? "Unnamed Signal",
+          signal,
+        })
+        subscribers.forEach((cb) => cb(debuggerEntries))
+      },
+      untrack: (signal) => {
+        debuggerEntries.forEach((entry) => {
+          if (entry.signal === signal) {
+            debuggerEntries.delete(entry)
+          }
+        })
+        subscribers.forEach((cb) => cb(debuggerEntries))
+      },
+      subscribe: (cb) => {
+        subscribers.add(cb)
+        cb(debuggerEntries)
+        return () => subscribers.delete(cb)
+      },
     }
   }
 

package/src/globals.ts

@@ -1,17 +1,36 @@
-export { node, hookIndex, renderMode, hydrationMode }
+import { Setup } from "./hooks/index.js"
+import { isBrowser } from "./env.js"
+export { node, renderMode, hydrationMode, setups, postEffectCleanups }
 
+/**
+ * A reference to the current VNode (always a component) being rendered.
+ */
 const node = {
   current: null as Kiru.VNode | null,
 }
 
-const hookIndex = {
-  current: 0,
-}
-
+/**
+ * The current render mode. Can be "dom" "string", "stream", or "hydrate".
+ */
 const renderMode = {
-  current: ("window" in globalThis ? "dom" : "string") as Kiru.RenderMode,
+  current: (isBrowser ? "dom" : "string") as Kiru.RenderMode,
 }
 
+/**
+ * The current hydration mode. Can be "static" or "dynamic".
+ * Used to indicate whether the page being hydrated will contain streamed content.
+ */
 const hydrationMode = {
   current: "dynamic" as "static" | "dynamic",
 }
+
+/**
+ * A map of VNodes (components) to their setup functions.
+ */
+const setups: WeakMap<Kiru.VNode, Setup<any>> = new WeakMap()
+
+/**
+ * Cleanup functions from onMount() that run after components
+ * have been unmounted and the browser has painted.
+ */
+const postEffectCleanups: (() => void)[] = []

package/src/{recursiveRender.ts → headlessRender.ts}

@@ -1,4 +1,4 @@
-import { node, hookIndex } from "./globals.js"
+import { node } from "./globals.js"
 import {
   isVNode,
   encodeHtmlEntities,
@@ -8,7 +8,7 @@ import {
   isPrimitiveChild,
   isValidTextChild,
 } from "./utils/index.js"
-import { isStreamDataThrowValue } from "./utils/promise.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,12 +16,10 @@ import type { ErrorBoundaryNode } from "./types.utils"
 
 export interface HeadlessRenderContext {
   write(chunk: string): void
-  onStreamData?: (data: Kiru.StatefulPromise<unknown>[]) => void
+  onStreamData?: (data: Kiru.StatefulPromiseBase<unknown>[]) => void
 }
 
-export { render as headlessRender }
-
-function render(
+export function headlessRender(
   ctx: HeadlessRenderContext,
   el: unknown,
   parent: Kiru.VNode | null,
@@ -37,7 +35,7 @@ function render(
     return ctx.write(el.toString())
   }
   if (el instanceof Array) {
-    return el.forEach((c, i) => render(ctx, c, parent, i))
+    return el.forEach((c, i) => headlessRender(ctx, c, parent, i))
   }
   if (Signal.isSignal(el)) {
     const value = el.peek()
@@ -68,7 +66,7 @@ function render(
   if (isExoticType(type)) {
     if (type === $ERROR_BOUNDARY) {
       let boundaryBuffer = ""
-      const streamPromises = new Set<Kiru.StatefulPromise<unknown>>()
+      const streamPromises = new Set<Kiru.StatefulPromiseBase<unknown>>()
       const boundaryCtx: HeadlessRenderContext = {
         write(chunk) {
           boundaryBuffer += chunk
@@ -78,7 +76,7 @@ function render(
         },
       }
       try {
-        render(boundaryCtx, children, el, idx)
+        headlessRender(boundaryCtx, children, el, idx)
         // flush successful render
         ctx.write(boundaryBuffer)
         ctx.onStreamData?.([...streamPromises])
@@ -91,27 +89,29 @@ function render(
         onError?.(e)
         const fallbackContent =
           typeof fallback === "function" ? fallback(e) : fallback
-        render(ctx, fallbackContent, el, 0)
+        headlessRender(ctx, fallbackContent, el, 0)
       }
       return
     }
 
-    render(ctx, children, el, idx)
+    headlessRender(ctx, children, el, idx)
     return
   }
 
-  if (typeof type !== "string") {
+  if (typeof type === "function") {
     try {
-      hookIndex.current = 0
       node.current = el
-      const res = type(props)
-      render(ctx, res, el, idx)
+      let children = type(props)
+      if (typeof children === "function") {
+        children = children(props)
+      }
+      headlessRender(ctx, children, el, idx)
       return
     } catch (error) {
       if (isStreamDataThrowValue(error)) {
         const { fallback, data } = error[$STREAM_DATA]
         ctx.onStreamData?.(data)
-        return render(ctx, fallback, el, 0)
+        return headlessRender(ctx, fallback, el, 0)
       }
       throw error
     } finally {
@@ -134,9 +134,9 @@ function render(
       )
     )
   } else if (Array.isArray(children)) {
-    children.forEach((c, i) => render(ctx, c, el, i))
+    children.forEach((c, i) => headlessRender(ctx, c, el, i))
   } else {
-    render(ctx, children, el, 0)
+    headlessRender(ctx, children, el, 0)
   }
   ctx.write(`</${type}>`)
 }

package/src/hmr.ts

@@ -2,9 +2,7 @@ import { $HMR_ACCEPT, $DEV_FILE_LINK } from "./constants.js"
 import { traverseApply } from "./utils/index.js"
 import { flushSync, requestUpdate } from "./scheduler.js"
 import { Signal } from "./signals/base.js"
-import type { WatchEffect } from "./signals/watch.js"
-import type { Store } from "./store.js"
-import type { AppContext } from "./appContext.js"
+import type { Effect } from "./signals/effect.js"
 
 export type HMRAccept<T = {}> = {
   provide: () => T
@@ -15,7 +13,7 @@ export type HMRAccept<T = {}> = {
 export type GenericHMRAcceptor<T = {}> = {
   [$HMR_ACCEPT]: HMRAccept<T>
 }
-type HotVar = Kiru.FC | Store<any, any> | Signal<any> | Kiru.Context<any>
+type HotVar = Kiru.FC | Signal<any> | Kiru.Context<any>
 
 type HotVarDesc = {
   type: string
@@ -43,7 +41,8 @@ export function isGenericHmrAcceptor(
 
 type ModuleMemory = {
   hotVars: Map<string, HotVarDesc>
-  unnamedWatchers: Array<WatchEffect>
+  unnamedEffects: Array<Effect>
+  hmrCallbacks: Array<() => void>
 }
 
 type HotVarRegistrationEntry = {
@@ -52,18 +51,22 @@ type HotVarRegistrationEntry = {
   link: string
 }
 
-export function createHMRContext() {
+export function createHmrContext() {
   type FilePath = string
   const moduleMap = new Map<FilePath, ModuleMemory>()
   let currentModuleFilePath: string | null = null
   let currentModuleMemory: ModuleMemory | null = null
   let isModuleReplacementExecution = false
   const isReplacement = () => isModuleReplacementExecution
-  let isWaitingForNextWatchCall = false
+  let isWaitingForNextEffect = false
 
-  const onHmrCallbacks: Array<() => void> = []
+  const globalHmrCallbacks: Array<() => void> = []
   const onHmr = (callback: () => void) => {
-    onHmrCallbacks.push(callback)
+    if (currentModuleMemory) {
+      currentModuleMemory.hmrCallbacks.push(callback)
+      return
+    }
+    globalHmrCallbacks.push(callback)
   }
 
   const prepare = (filePath: string) => {
@@ -72,14 +75,17 @@ export function createHMRContext() {
     if (!mod) {
       mod = {
         hotVars: new Map(),
-        unnamedWatchers: [],
+        unnamedEffects: [],
+        hmrCallbacks: [],
       }
       moduleMap.set(filePath, mod)
     } else {
-      while (onHmrCallbacks.length) onHmrCallbacks.shift()!()
-      for (const prevWatcher of mod.unnamedWatchers.splice(0)) {
-        prevWatcher.stop()
+      while (mod.hmrCallbacks.length) mod.hmrCallbacks.shift()!()
+      while (globalHmrCallbacks.length) globalHmrCallbacks.shift()!()
+      for (const effect of mod.unnamedEffects) {
+        effect.stop()
       }
+      mod.unnamedEffects.length = 0
     }
 
     currentModuleMemory = mod!
@@ -92,26 +98,20 @@ export function createHMRContext() {
     if (currentModuleMemory === null)
       throw new Error("[kiru]: HMR could not register: No active module")
 
-    let dirtiedApps: Set<AppContext> = new Set()
+    let dirtyNodes = new Set<Kiru.VNode>()
     for (const [name, newEntry] of Object.entries(hotVarRegistrationEntries)) {
       const oldEntry = currentModuleMemory.hotVars.get(name)
 
       // @ts-ignore - this is how we tell devtools what file the hotvar is from
       newEntry.value[$DEV_FILE_LINK] = newEntry.link
 
-      if (typeof newEntry.value === "function") {
-        if (oldEntry?.value) {
-          /**
-           * this is how, when the previous function has been stored somewhere else (eg. in a Map, or by Vike),
-           * we can trace it to its latest version
-           */
-          // @ts-ignore
-          oldEntry.value.__next = newEntry.value
-        }
-      }
-
-      if (newEntry.type === "createStore") {
-        window.__kiru.stores!.add(name, newEntry.value as Store<any, any>)
+      if (oldEntry?.value) {
+        /**
+         * this is how, when the previous value has been stored somewhere else (eg. in a Map, or by Vike),
+         * we can trace it to its current version by using latest(value)
+         */
+        // @ts-ignore
+        oldEntry.value.__next = newEntry.value
       }
 
       currentModuleMemory.hotVars.set(name, newEntry)
@@ -127,20 +127,20 @@ export function createHMRContext() {
         continue
       }
       if (oldEntry.type === "component" && newEntry.type === "component") {
-        window.__kiru.apps.forEach((ctx) => {
-          traverseApply(ctx.rootNode, (vNode) => {
+        window.__kiru.apps.forEach((app) => {
+          traverseApply(app.rootNode, (vNode) => {
             if (vNode.type === oldEntry.value) {
               vNode.type = newEntry.value as any
-              dirtiedApps.add(ctx)
+              dirtyNodes.add(vNode)
             }
           })
         })
       }
     }
 
-    if (dirtiedApps.size) {
+    if (dirtyNodes.size) {
       _isHmrUpdate = true
-      dirtiedApps.forEach((ctx) => requestUpdate(ctx.rootNode))
+      dirtyNodes.forEach((n) => requestUpdate(n))
       flushSync()
       _isHmrUpdate = false
     }
@@ -150,16 +150,14 @@ export function createHMRContext() {
     currentModuleFilePath = null
   }
 
-  const signals = {
-    registerNextWatch() {
-      isWaitingForNextWatchCall = true
-    },
-    isWaitingForNextWatchCall() {
-      return isWaitingForNextWatchCall
+  const moduleEffects = {
+    registerNext() {
+      isWaitingForNextEffect = true
     },
-    pushWatch(watch: WatchEffect) {
-      currentModuleMemory!.unnamedWatchers.push(watch)
-      isWaitingForNextWatchCall = false
+    push(effect: Effect<any>) {
+      if (!isWaitingForNextEffect) return
+      currentModuleMemory!.unnamedEffects.push(effect)
+      isWaitingForNextEffect = false
     },
   }
 
@@ -167,10 +165,30 @@ export function createHMRContext() {
     register,
     prepare,
     isReplacement,
-    signals,
+    moduleEffects,
     onHmr,
     getCurrentFilePath() {
       return currentModuleFilePath
     },
   }
 }
+
+/**
+ * Queues a callback to be fired when HMR is triggered. This is a no-op in non-browser environments or in production.
+ * - If called during current module evaluation, the callback will be fired the next time the current module is evaluated.
+ * - If called at any other time, the callback will be fired the next time HMR is triggered.
+ * @see https://kirujs.dev/docs/api/lifecycles#onHmr
+ * 
+ * ```ts
+ * import { onHmr } from "kiru"
+ * // start an interval in the module scope
+ * const interval = setInterval(() => {...}, 1000)
+ * // stop the interval when this file is reloaded
+ * onHmr(() => clearInterval(interval))
+ ```
+ */
+export function onHmr(callback: () => void): void {
+  if ("window" in globalThis && window.__kiru.HMRContext) {
+    window.__kiru.HMRContext.onHmr(callback)
+  }
+}

package/src/hooks/index.ts

@@ -1,15 +1,5 @@
-export * from "./useAsync.js"
-export * from "./useCallback.js"
-export * from "./useContext.js"
-export * from "./useEffect.js"
-export * from "./useEffectEvent.js"
-export * from "./useId.js"
-export * from "./useLayoutEffect.js"
-export * from "./useMemo.js"
-export * from "./usePromise.js"
-export * from "./useReducer.js"
-export * from "./useRef.js"
-export * from "./useState.js"
-export * from "./useSyncExternalStore.js"
-export * from "./useViewTransition.js"
+export * from "./onCleanup.js"
+export * from "./onMount.js"
+export * from "./onBeforeMount.js"
+export * from "./setup.js"
 export * from "./utils.js"

package/src/hooks/onBeforeMount.ts

@@ -0,0 +1,18 @@
+import { sideEffectsEnabled } from "../utils/index.js"
+import { getVNodeLifecycleHooks, wrapLifecycleHookCallback } from "./utils.js"
+
+/**
+ * Registers a callback that runs after the component is first mounted to the DOM, but before the DOM is painted.
+ * Optionally returns a cleanup function that will run when the component unmounts.
+ * Intended for use during component setup when the component returns a render function.
+ *
+ * @see https://kirujs.dev/docs/api/lifecycles#onBeforeMount
+ */
+export function onBeforeMount(fn: () => (() => void) | void): void {
+  if (!sideEffectsEnabled()) return
+  const hooks = getVNodeLifecycleHooks()
+  if (!hooks) {
+    throw new Error("Cannot queue beforeMount effect outside of a component")
+  }
+  hooks.pre.push(wrapLifecycleHookCallback(fn, hooks.preCleanups))
+}

package/src/hooks/onCleanup.ts

@@ -0,0 +1,21 @@
+import { node } from "../globals.js"
+import {
+  generateRandomID,
+  registerVNodeCleanup,
+  sideEffectsEnabled,
+} from "../utils/index.js"
+
+/**
+ * Registers a cleanup function that runs when the component unmounts.
+ * Intended for use during component setup when the component returns a render function.
+ *
+ * @see https://kirujs.dev/docs/api/lifecycles#onCleanup
+ */
+export function onCleanup(fn: () => void): void {
+  if (!sideEffectsEnabled()) return
+  const vNode = node.current!
+  if (!vNode) {
+    throw new Error("Cannot queue onCleanup effect outside of a component")
+  }
+  registerVNodeCleanup(vNode, generateRandomID(10), fn)
+}

package/src/hooks/onMount.ts

@@ -0,0 +1,18 @@
+import { sideEffectsEnabled } from "../utils/index.js"
+import { getVNodeLifecycleHooks, wrapLifecycleHookCallback } from "./utils.js"
+
+/**
+ * Registers a callback that runs after the component is first mounted to the DOM.
+ * Optionally returns a cleanup function that will run after the component unmounts.
+ * Intended for use during component setup when the component returns a render function.
+ *
+ * @see https://kirujs.dev/docs/api/lifecycles#onMount
+ */
+export function onMount(fn: () => (() => void) | void): void {
+  if (!sideEffectsEnabled()) return
+  const hooks = getVNodeLifecycleHooks()
+  if (!hooks) {
+    throw new Error("Cannot queue onMount effect outside of a component")
+  }
+  hooks.post.push(wrapLifecycleHookCallback(fn, hooks.postCleanups))
+}