@typed/template 0.11.0 → 0.13.0

package/src/internal/v2/render.ts

@@ -1,9 +1,10 @@
 import * as Context from "@typed/context"
 import * as Fx from "@typed/fx"
 import type { Rendered } from "@typed/wire"
-import { persistent } from "@typed/wire"
-import type * as Cause from "effect/Cause"
-import type { Chunk } from "effect/Chunk"
+import { isText, persistent } from "@typed/wire"
+import { Option } from "effect"
+import * as Cause from "effect/Cause"
+import * as Chunk from "effect/Chunk"
 import * as Effect from "effect/Effect"
 import * as ExecutionStrategy from "effect/ExecutionStrategy"
 import { flow } from "effect/Function"
@@ -20,12 +21,24 @@ import { DomRenderEvent, type RenderEvent } from "../../RenderEvent.js"
 import { DEFAULT_PRIORITY, RenderQueue } from "../../RenderQueue.js"
 import type { RenderTemplate } from "../../RenderTemplate.js"
 import type * as Template from "../../Template.js"
+import { CouldNotFindCommentError, isHydrationError } from "../errors.js"
 import type { EventSource } from "../EventSource.js"
 import { makeEventSource } from "../EventSource.js"
+import { HydrateContext } from "../HydrateContext.js"
 import type { IndexRefCounter } from "../indexRefCounter.js"
 import { makeRefCounter } from "../indexRefCounter.js"
-import { findHoleComment, findPath, keyToPartType } from "../utils.js"
+import type { ParentChildNodes } from "../utils.js"
+import { findHoleComment, findHydratePath, findPath, isCommentWithValue, keyToPartType } from "../utils.js"
 import { isNullOrUndefined } from "./helpers.js"
+import type { HydrationHole, HydrationNode, HydrationTemplate } from "./hydration-template.js"
+import {
+  findHydrationHole,
+  findHydrationMany,
+  findHydrationTemplate,
+  getChildNodes,
+  getNodes,
+  getPreviousNodes
+} from "./hydration-template.js"
 import { EventPartImpl, RefPartImpl, syncPartToPart } from "./parts.js"
 import { getBrowserEntry } from "./render-entry.js"
 import * as SyncPartsInternal from "./render-sync-parts.js"
@@ -41,7 +54,6 @@ export type TemplateContext = {
    */
   spreadIndex: number
 
-  readonly content: DocumentFragment
   readonly context: Context.Context<Scope.Scope>
   readonly document: Document
   readonly eventSource: EventSource
@@ -52,6 +64,9 @@ export type TemplateContext = {
   readonly scope: Scope.CloseableScope
   readonly values: ReadonlyArray<Renderable<any, any>>
   readonly onCause: (cause: Cause.Cause<any>) => Effect.Effect<unknown>
+  readonly manyKey: string | undefined
+
+  readonly hydrateContext: Option.Option<HydrateContext>
 }
 
 export const renderTemplate: (
@@ -63,28 +78,48 @@ export const renderTemplate: (
   values: Values
 ) => {
   const entry = getBrowserEntry(document, renderContext, templateStrings)
-  if (entry.template.parts.length === 0) {
-    return Fx.succeed(DomRenderEvent(persistent(document, document.importNode(entry.content, true))))
-  }
 
   return Fx.make<
     RenderEvent,
     Placeholder.Error<Values[number]>,
     Scope.Scope | RenderQueue | Placeholder.Context<Values[number]>
-  >((sink) =>
-    Effect.catchAllCause(
+  >(function render(
+    sink
+  ): Effect.Effect<unknown, never, Scope.Scope | RenderQueue | Placeholder.Context<Values[number]>> {
+    return Effect.catchAllCause(
       Effect.gen(function*() {
         // Create a context for rendering our template
         const ctx = yield* makeTemplateContext<Values>(
-          entry.content,
           document,
           renderContext,
           values,
           sink.onFailure
         )
 
-        // Setup all parts
-        const effects = setupParts(entry.template.parts, ctx)
+        const hydration = attemptHydration(ctx, entry.template.hash)
+
+        let effects: Array<Effect.Effect<void, any, any>>
+        let content: DocumentFragment
+        let wire: Rendered | undefined
+
+        if (Option.isSome(hydration)) {
+          const { hydrateCtx, where } = hydration.value
+          effects = setupHydrateParts(entry.template.parts, {
+            ...ctx,
+            where,
+            manyKey: hydrateCtx.manyKey,
+            makeHydrateContext: (where: HydrationNode): HydrateContext => ({
+              where,
+              hydrate: true
+            })
+          })
+
+          wire = getWire(where)
+        } else {
+          content = ctx.document.importNode(entry.content, true)
+          effects = setupRenderParts(entry.template.parts, content, ctx)
+        }
+
         if (effects.length > 0) {
           yield* Effect.forEach(effects, flow(Effect.catchAllCause(ctx.onCause), Effect.forkIn(ctx.scope)))
         }
@@ -95,14 +130,21 @@ export const renderTemplate: (
           yield* ctx.refCounter.wait
         }
 
-        // Create a persistent wire from our content
-        const wire = persistent(document, ctx.content)
+        // If we're not hydrating, we need to create our wire from our content
+        if (wire === undefined) {
+          wire = persistent(ctx.document, content!)
+        }
 
         // Setup our event listeners for our wire.
         // We use the parentScope to allow event listeners to exist
         // beyond the lifetime of the current Fiber, but no further than its parent template.
         yield* ctx.eventSource.setup(wire, ctx.parentScope)
 
+        // If we're hydrating, we need to mark this part of the stack as hydrated
+        if (Option.isSome(hydration)) {
+          hydration.value.hydrateCtx.hydrate = false
+        }
+
         // Emit our DomRenderEvent
         yield* sink.onSuccess(DomRenderEvent(wire)).pipe(
           // Ensure our templates last forever in the DOM environment
@@ -112,13 +154,22 @@ export const renderTemplate: (
           Effect.onExit((exit) => Scope.close(ctx.scope, exit))
         )
       }),
-      sink.onFailure
+      (cause) => {
+        const hydrationFailure = Chunk.findFirst(Cause.defects(cause), isHydrationError)
+        if (Option.isSome(hydrationFailure)) {
+          return HydrateContext.pipe(
+            Effect.tap((ctx) => ctx.hydrate = false),
+            Effect.flatMap(() => render(sink))
+          )
+        }
+
+        return sink.onFailure(cause)
+      }
     )
-  )
+  })
 }
 
 export function makeTemplateContext<Values extends ReadonlyArray<Renderable<any, any>>>(
-  entry: DocumentFragment,
   document: Document,
   renderContext: RenderContext,
   values: ReadonlyArray<Renderable<any, any>>,
@@ -130,15 +181,16 @@ export function makeTemplateContext<Values extends ReadonlyArray<Renderable<any,
     const queue = Context.get(context, RenderQueue)
     const parentScope = Context.get(context, Scope.Scope)
     const eventSource = makeEventSource()
-    const content = document.importNode(entry, true)
     const scope = yield* Scope.fork(parentScope, ExecutionStrategy.sequential)
+    const hydrateContext = Context.getOption(context, HydrateContext)
     const templateContext: TemplateContext = {
       context: Context.add(context, Scope.Scope, scope),
       expected: 0,
-      content,
       document,
       eventSource,
+      hydrateContext,
       parentScope,
+      manyKey: undefined,
       queue,
       refCounter,
       renderContext,
@@ -152,11 +204,33 @@ export function makeTemplateContext<Values extends ReadonlyArray<Renderable<any,
   })
 }
 
-function setupParts(parts: Template.Template["parts"], ctx: TemplateContext) {
+export function attemptHydration(
+  ctx: TemplateContext,
+  hash: string
+): Option.Option<{ readonly where: HydrationTemplate; readonly hydrateCtx: HydrateContext }> {
+  if (Option.isSome(ctx.hydrateContext) && ctx.hydrateContext.value.hydrate) {
+    const hydrateCtx = ctx.hydrateContext.value
+    const where = findHydrationTemplateByHash(hydrateCtx, hash)
+    if (where === null) {
+      hydrateCtx.hydrate = false
+      return Option.none()
+    } else {
+      return Option.some({ where, hydrateCtx })
+    }
+  }
+
+  return Option.none()
+}
+
+function setupRenderParts(
+  parts: Template.Template["parts"],
+  content: ParentChildNodes,
+  ctx: TemplateContext
+) {
   const effects: Array<Effect.Effect<void, any, any>> = []
 
   for (const [part, path] of parts) {
-    const effect = setupPart(part, path, ctx)
+    const effect = setupRenderPart(part, content, path, ctx)
     if (effect) {
       effects.push(effect)
     }
@@ -165,58 +239,59 @@ function setupParts(parts: Template.Template["parts"], ctx: TemplateContext) {
   return effects
 }
 
-function setupPart(
+function setupRenderPart(
   part: Template.PartNode | Template.SparsePartNode,
-  path: Chunk<number>,
+  content: ParentChildNodes,
+  path: Chunk.Chunk<number>,
   ctx: TemplateContext
 ) {
   switch (part._tag) {
     case "attr":
-      return setupAttrPart(part, findPath(ctx.content, path) as HTMLElement | SVGElement, ctx, ctx.values[part.index])
+      return setupAttrPart(part, findPath(content, path) as HTMLElement | SVGElement, ctx, ctx.values[part.index])
     case "boolean-part":
       return setupBooleanPart(
         part,
-        findPath(ctx.content, path) as HTMLElement | SVGElement,
+        findPath(content, path) as HTMLElement | SVGElement,
         ctx,
         ctx.values[part.index]
       )
     case "className-part":
       return setupClassNamePart(
         part,
-        findPath(ctx.content, path) as HTMLElement | SVGElement,
+        findPath(content, path) as HTMLElement | SVGElement,
         ctx,
         ctx.values[part.index]
       )
     case "comment-part":
-      return setupCommentPart(part, findPath(ctx.content, path) as Comment, ctx)
+      return setupCommentPart(part, findPath(content, path) as Comment, ctx, ctx.values[part.index])
     case "data":
-      return setupDataPart(part, findPath(ctx.content, path) as HTMLElement | SVGElement, ctx, ctx.values[part.index])
+      return setupDataPart(part, findPath(content, path) as HTMLElement | SVGElement, ctx, ctx.values[part.index])
     case "event":
-      return setupEventPart(part, findPath(ctx.content, path) as HTMLElement | SVGElement, ctx, ctx.values[part.index])
+      return setupEventPart(part, findPath(content, path) as HTMLElement | SVGElement, ctx, ctx.values[part.index])
     case "node": {
-      const parent = findPath(ctx.content, path) as Element
+      const parent = findPath(content, path) as Element
       const comment = findHoleComment(parent, part.index)
       return setupNodePart(part, comment, ctx, null, [])
     }
     case "properties":
-      return setupPropertiesPart(part, findPath(ctx.content, path) as HTMLElement | SVGElement, ctx)
+      return setupPropertiesPart(findPath(content, path) as HTMLElement | SVGElement, ctx, ctx.values[part.index])
     case "property":
       return setupPropertyPart(
         part,
-        findPath(ctx.content, path) as HTMLElement | SVGElement,
+        findPath(content, path) as HTMLElement | SVGElement,
         ctx,
         ctx.values[part.index]
       )
     case "ref":
-      return setupRefPart(part, findPath(ctx.content, path) as HTMLElement | SVGElement, ctx)
+      return setupRefPart(part, findPath(content, path) as HTMLElement | SVGElement, ctx)
     case "sparse-attr":
-      return setupSparseAttrPart(part, findPath(ctx.content, path) as HTMLElement | SVGElement, ctx)
+      return setupSparseAttrPart(part, findPath(content, path) as HTMLElement | SVGElement, ctx)
     case "sparse-class-name":
-      return setupSparseClassNamePart(part, findPath(ctx.content, path) as HTMLElement | SVGElement, ctx)
+      return setupSparseClassNamePart(part, findPath(content, path) as HTMLElement | SVGElement, ctx)
     case "sparse-comment":
-      return setupSparseCommentPart(part, findPath(ctx.content, path) as Comment, ctx)
+      return setupSparseCommentPart(part, findPath(content, path) as Comment, ctx)
     case "text-part": {
-      const parent = findPath(ctx.content, path) as Element
+      const parent = findPath(content, path) as Element
       const comment = findHoleComment(parent, part.index)
       return setupTextPart(part, comment, ctx)
     }
@@ -257,10 +332,10 @@ export function setupClassNamePart(
 export function setupCommentPart(
   { index }: Pick<Template.CommentPartNode, "index">,
   comment: Comment,
-  ctx: TemplateContext
+  ctx: TemplateContext,
+  renderable: Renderable<any, any>
 ) {
   const part = SyncPartsInternal.makeCommentPart(index, comment)
-  const renderable = ctx.values[index]
   return matchSyncPart(renderable, ctx, part)
 }
 
@@ -348,10 +423,8 @@ export function setupPropertyPart(
 export function setupRefPart(
   { index }: Pick<Template.RefPartNode, "index">,
   element: HTMLElement | SVGElement,
-  ctx: TemplateContext
+  renderable: Renderable<any, any>
 ) {
-  const renderable = ctx.values[index]
-
   if (isNullOrUndefined(renderable)) return null
   else if (isDirective(renderable)) {
     return renderable(
@@ -366,11 +439,10 @@ export function setupRefPart(
 }
 
 export function setupPropertiesPart(
-  { index }: Pick<Template.PropertiesPartNode, "index">,
   element: HTMLElement | SVGElement,
-  ctx: TemplateContext
+  ctx: TemplateContext,
+  renderable: Renderable<any, any>
 ) {
-  const renderable = ctx.values[index]
   if (renderable && typeof renderable === "object") {
     const effects: Array<Effect.Effect<void, any, any>> = []
     const addEffect = (effect: Effect.Effect<void, any, any> | null | undefined) => {
@@ -410,7 +482,7 @@ export function setupPropertiesPart(
 }
 
 export function setupSparseAttrPart(
-  { name, nodes }: Template.SparseAttrNode,
+  { name, nodes }: Pick<Template.SparseAttrNode, "name" | "nodes">,
   element: HTMLElement | SVGElement,
   ctx: TemplateContext
 ) {
@@ -427,7 +499,7 @@ export function setupSparseAttrPart(
 }
 
 export function setupSparseClassNamePart(
-  { nodes }: Template.SparseClassNameNode,
+  { nodes }: Pick<Template.SparseClassNameNode, "nodes">,
   element: HTMLElement | SVGElement,
   ctx: TemplateContext
 ) {
@@ -442,7 +514,7 @@ export function setupSparseClassNamePart(
 }
 
 export function setupSparseCommentPart(
-  { nodes }: Template.SparseCommentNode,
+  { nodes }: Pick<Template.SparseCommentNode, "nodes">,
   comment: Comment,
   ctx: TemplateContext
 ) {
@@ -499,9 +571,8 @@ function unwrapRenderable<E, R>(renderable: unknown): Fx.Fx<any, E, R> {
       else if (Array.isArray(renderable)) {
         return renderable.length === 0
           ? Fx.succeed(null)
-          // TODO: We need to ensure the ordering of these values in server environments
           : Fx.map(Fx.tuple(renderable.map(unwrapRenderable)), (xs) => xs.flat()) as any
-      } else if (Fx.TypeId in renderable) {
+      } else if (Fx.FxTypeId in renderable) {
         return renderable as any
       } else if (Effect.EffectTypeId in renderable) {
         return Fx.fromFxEffect(Effect.map(renderable as any, unwrapRenderable<E, R>))
@@ -573,16 +644,170 @@ export function attachRoot<T extends RenderEvent | null>(
 }
 
 export function removeChildren(where: HTMLElement, previous: Rendered) {
-  for (const node of getNodes(previous)) {
+  for (const node of getNodesFromRendered(previous)) {
     where.removeChild(node)
   }
 }
 
 export function replaceChildren(where: HTMLElement, wire: Rendered) {
-  where.replaceChildren(...getNodes(wire))
+  where.replaceChildren(...getNodesFromRendered(wire))
 }
 
-export function getNodes(rendered: Rendered): Array<globalThis.Node> {
+export function getNodesFromRendered(rendered: Rendered): Array<globalThis.Node> {
   const value = rendered.valueOf() as globalThis.Node | Array<globalThis.Node>
   return Array.isArray(value) ? value : [value]
 }
+
+export type HydrateTemplateContext = TemplateContext & {
+  readonly where: HydrationNode
+  readonly makeHydrateContext: (where: HydrationNode, index: number) => HydrateContext
+}
+
+export function findHydrationTemplateByHash(hydrateCtx: HydrateContext, hash: string): HydrationTemplate | null {
+  // If there is not a manyKey, we can just find the template by its hash
+  if (hydrateCtx.manyKey === undefined) {
+    return findHydrationTemplate(getChildNodes(hydrateCtx.where), hash)
+  }
+
+  // If there is a manyKey, we need to find the many node first
+  const many = findHydrationMany(getChildNodes(hydrateCtx.where), hydrateCtx.manyKey)
+
+  if (many === null) return null
+
+  // Then we can find the template by its hash
+  return findHydrationTemplate(getChildNodes(many), hash)
+}
+
+export function setupHydrateParts(parts: Template.Template["parts"], ctx: HydrateTemplateContext) {
+  const effects: Array<Effect.Effect<void, any, any>> = []
+
+  for (const [part, path] of parts) {
+    const effect = setupHydratePart(part, path, ctx)
+    if (effect) {
+      effects.push(effect)
+    }
+  }
+
+  return effects
+}
+
+export function setupHydratePart(
+  part: Template.PartNode | Template.SparsePartNode,
+  path: Chunk.Chunk<number>,
+  ctx: HydrateTemplateContext
+) {
+  switch (part._tag) {
+    case "attr":
+      return setupAttrPart(part, findHydratePath(ctx.where, path) as any, ctx, ctx.values[part.index])
+    case "boolean-part":
+      return setupBooleanPart(part, findHydratePath(ctx.where, path) as any, ctx, ctx.values[part.index])
+    case "className-part":
+      return setupClassNamePart(part, findHydratePath(ctx.where, path) as any, ctx, ctx.values[part.index])
+    case "comment-part":
+      return setupCommentPart(part, findHydratePath(ctx.where, path) as any, ctx, ctx.values[part.index])
+    case "data":
+      return setupDataPart(part, findHydratePath(ctx.where, path) as any, ctx, ctx.values[part.index])
+    case "event":
+      return setupEventPart(part, findHydratePath(ctx.where, path) as any, ctx, ctx.values[part.index])
+    case "node": {
+      const hole = findHydrationHole(getChildNodes(ctx.where), part.index)
+      if (hole === null) {
+        throw new CouldNotFindCommentError(part.index)
+      }
+      return setupHydratedNodePart(part, hole, ctx)
+    }
+    case "properties":
+      return setupPropertiesPart(findHydratePath(ctx.where, path) as any, ctx, ctx.values[part.index])
+    case "property":
+      return setupPropertyPart(part, findHydratePath(ctx.where, path) as any, ctx, ctx.values[part.index])
+    case "ref":
+      return setupRefPart(part, findHydratePath(ctx.where, path) as any, ctx.values[part.index])
+    case "sparse-attr":
+      return setupSparseAttrPart(part, findHydratePath(ctx.where, path) as any, ctx)
+    case "sparse-class-name":
+      return setupSparseClassNamePart(part, findHydratePath(ctx.where, path) as any, ctx)
+    case "sparse-comment":
+      return setupSparseCommentPart(part, findHydratePath(ctx.where, path) as any, ctx)
+    case "text-part": {
+      const hole = findHydrationHole(getChildNodes(ctx.where), part.index)
+      if (hole === null) throw new CouldNotFindCommentError(part.index)
+      return setupTextPart(part, hole.endComment, ctx)
+    }
+  }
+}
+
+export function setupHydratedNodePart(
+  part: Template.NodePart,
+  hole: HydrationHole,
+  ctx: HydrateTemplateContext
+) {
+  const nestedCtx = ctx.makeHydrateContext(hole, part.index)
+  const previousNodes = getPreviousNodes(hole)
+  const text = previousNodes.length === 2 && isCommentWithValue(previousNodes[0], "text") && isText(previousNodes[1])
+    ? previousNodes[1]
+    : null
+  const effect = setupNodePart(part, hole.endComment, ctx, text, text === null ? previousNodes : [text])
+  if (effect === null) return null
+  return Effect.provideService(effect, HydrateContext, nestedCtx)
+}
+
+export function findRootParentChildNodes(where: HTMLElement): ParentChildNodes {
+  const childNodes = findRootChildNodes(where)
+
+  return {
+    parentNode: where,
+    childNodes
+  }
+}
+
+const START = "typed-start"
+const END = "typed-end"
+
+// Finds all of the childNodes between the "typed-start" and "typed-end" comments
+export function findRootChildNodes(where: HTMLElement): Array<Node> {
+  let start = -1
+  let end = -1
+
+  const { childNodes } = where
+  const length = childNodes.length
+
+  for (let i = 0; i < length; i++) {
+    const node = childNodes[i]
+
+    if (node.nodeType === node.COMMENT_NODE && node.nodeValue === START) {
+      start = i
+      break
+    }
+  }
+
+  for (let i = length - 1; i >= Math.max(start, 0); i--) {
+    const node = childNodes[i]
+
+    if (node.nodeType === node.COMMENT_NODE && node.nodeValue === END) {
+      end = i
+      break
+    }
+  }
+
+  // If we can't find the start and end comments, just return all childNodes
+  if (start === -1 && end === -1) {
+    return Array.from(childNodes)
+  }
+
+  start = start === -1 ? 0 : start
+  end = end === -1 ? length - 1 : end
+
+  const rootChildNodes: Array<Node> = Array(end - start)
+
+  for (let i = start + 1, j = 0; i <= end; i++) {
+    rootChildNodes[j++] = childNodes[i]
+  }
+
+  return rootChildNodes
+}
+
+export function getWire(where: HydrationNode) {
+  const nodes = getNodes(where)
+  if (nodes.length === 1) return nodes[0]
+  return nodes
+}