effect-start 0.29.0 → 0.30.0

package/src/{hyper/HyperHtml.ts → Html.ts}

@@ -1,27 +1,46 @@
-/**
- * Renders Hyper JSX nodes to HTML.
- *
- * Effect Start comes with {@link Hyper} and {@link JsxRuntime} to enable
- * JSX support. The advantage of using JSX over HTML strings or templates
- * is type safety and better editor support.
- *
- * JSX nodes are compatible with React's and Solid's.
-
- * You can enable JSX support by updating `tsconfig.json`:
- *
- * {
- *   compilerOptions: {
- *     jsx: "react-jsx",
- *     jsxImportSource: "effect-start" | "react" | "praect" // etc.
- *   }
- * }
- */
-
-import type * as Hyper from "./Hyper.ts"
-import type * as HyperNode from "./HyperNode.ts"
-import type * as JsxRuntime from "./jsx-runtime.ts"
 import type { JSX } from "./jsx.d.ts"
 
+export const TypeId = "~effect-start/HyperNode" as const
+
+const NoChildren: ReadonlyArray<never> = Object.freeze([])
+
+type Primitive = string | number | boolean | null | undefined
+
+export type ElementType = string | Component
+
+export type ElemenetProps = {
+  [key: string]:
+    | Primitive
+    | Element
+    | Iterable<Primitive | Element>
+    | Record<string, unknown>
+    | ((window: Window) => void)
+}
+
+export type Component = (props: ElemenetProps) => Element | Primitive
+
+export interface Element {
+  type: ElementType
+  props: ElemenetProps
+}
+
+export function make(type: ElementType, props: ElemenetProps): Element {
+  return {
+    type,
+    props: {
+      ...props,
+      children: props.children ?? NoChildren,
+    },
+  }
+}
+
+export function isGenericJsxObject(value: unknown): value is {
+  type: any
+  props: any
+} {
+  return typeof value === "object" && value !== null && "type" in value && "props" in value
+}
+
 const EMPTY_TAGS = [
   "area",
   "base",
@@ -53,12 +72,11 @@ let map = {
 
 const RAW_TEXT_TAGS = ["script", "style"]
 
-// Prevents closing html tags in embedded css/js source
 const escapeRawText = (text: string) => text.replaceAll("</", "<\\/")
 
 export function renderToString(
   node: JSX.Children,
-  hooks?: { onNode?: (node: HyperNode.HyperNode) => void },
+  hooks?: { onNode?: (node: Element) => void },
 ): string {
   const stack: Array<any> = [node]
   let result = ""
@@ -68,7 +86,6 @@ export function renderToString(
 
     if (typeof current === "string") {
       if (current.startsWith("<") && current.endsWith(">")) {
-        // This is a closing tag, don't escape it
         result += current
       } else {
         result += esc(current)
@@ -82,17 +99,14 @@ export function renderToString(
     }
 
     if (typeof current === "boolean") {
-      // React-like behavior: booleans render nothing
       continue
     }
 
     if (current === null || current === undefined) {
-      // React-like behavior: null/undefined render nothing
       continue
     }
 
     if (Array.isArray(current)) {
-      // Handle arrays by pushing all items to stack in reverse order
       for (let i = current.length - 1; i >= 0; i--) {
         stack.push(current[i])
       }
@@ -165,10 +179,56 @@ export function renderToString(
         }
       }
     } else if (current && typeof current === "object") {
-      // Handle objects without type property - convert to string or ignore
-      // This prevents [object Object] from appearing
       continue
     }
   }
   return result
 }
+
+const HtmlStringSymbol = Symbol.for("HtmlString")
+
+export interface HtmlString {
+  readonly [HtmlStringSymbol]: true
+  readonly value: string
+}
+
+const makeHtmlString = (value: string): HtmlString => ({
+  [HtmlStringSymbol]: true,
+  value,
+})
+
+const isHtmlString = (value: unknown): value is HtmlString =>
+  typeof value === "object" && value !== null && HtmlStringSymbol in value
+
+type HtmlValue =
+  | string
+  | number
+  | bigint
+  | boolean
+  | null
+  | undefined
+  | HtmlString
+  | Function
+  | Record<string, unknown>
+  | ReadonlyArray<HtmlValue>
+
+const resolveValue = (value: HtmlValue): string => {
+  if (value === null || value === undefined || value === false || value === true) return ""
+  if (isHtmlString(value)) return value.value
+  if (Array.isArray(value)) return (value as Array<HtmlValue>).map(resolveValue).join("")
+  if (typeof value === "function") return value.toString()
+  if (typeof value === "object") return JSON.stringify(value)
+  if (typeof value === "string") return value
+  return String(value)
+}
+
+export const html = (strings: TemplateStringsArray, ...values: Array<HtmlValue>): HtmlString => {
+  let result = strings[0]
+  for (let i = 0; i < values.length; i++) {
+    result += resolveValue(values[i])
+    result += strings[i + 1]
+  }
+  return makeHtmlString(result)
+}
+
+html.raw = (value: string): HtmlString => makeHtmlString(value)

package/src/Route.ts

@@ -1,12 +1,18 @@
 import * as Context from "effect/Context"
 import * as Effect from "effect/Effect"
 import * as Layer from "effect/Layer"
+import * as Option from "effect/Option"
 import * as Pipeable from "effect/Pipeable"
 import * as Predicate from "effect/Predicate"
+import * as Development from "./Development.ts"
 import * as Entity from "./Entity.ts"
 import * as RouteBody from "./RouteBody.ts"
 import * as RouteTree from "./RouteTree.ts"
 import type * as Values from "./_Values.ts"
+import * as Html from "./Html.ts"
+import type { JSX } from "./jsx.d.ts"
+
+export const render = RouteBody.render
 
 export const RouteItems: unique symbol = Symbol()
 export const RouteDescriptor: unique symbol = Symbol()
@@ -162,6 +168,7 @@ export function items<T extends RouteSet.Data<any, any, any>>(self: T): RouteSet
 export function descriptor<T extends RouteSet.Data<any, any, any>>(
   self: T,
 ): T[typeof RouteDescriptor]
+export function descriptor<E extends RouteDescriptor.Any>(self: RouteSet.Data<any, any, any>): E
 export function descriptor<T extends RouteSet.Data<any, any, any>>(
   self: Iterable<T>,
 ): Array<T[typeof RouteDescriptor]>
@@ -203,8 +210,10 @@ export const text = RouteBody.build<string, "text">({
   format: "text",
 })
 
-export const html = RouteBody.build<string, "html">({
+export const html = RouteBody.build<string | JSX.Children, string, "html">({
   format: "html",
+  handle: (body) =>
+    typeof body === "string" ? body : Html.renderToString(body as JSX.Children),
 })
 
 export const json = RouteBody.build<Values.Json, "json">({
@@ -215,20 +224,31 @@ export const bytes = RouteBody.build<Uint8Array, "bytes">({
   format: "bytes",
 })
 
-export { render } from "./RouteBody.ts"
-
 export { sse } from "./RouteSse.ts"
 
-export function redirect(
+export function redirect<D extends RouteDescriptor.Any, B, I extends Route.Tuple>(
   url: string | URL,
   options?: { status?: 301 | 302 | 303 | 307 | 308 },
-): Entity.Entity<""> {
-  return Entity.make("", {
-    status: options?.status ?? 302,
-    headers: {
-      location: url instanceof URL ? url.href : url,
-    },
-  })
+): (
+  self: RouteSet.RouteSet<D, B, I>,
+) => RouteSet.RouteSet<D, B, [...I, Route.Route<{}, {}, "", never, never>]> {
+  const route = make<{}, {}, "">(
+    () =>
+      Effect.succeed(
+        Entity.make("", {
+          status: options?.status ?? 302,
+          headers: {
+            location: url instanceof URL ? url.href : url,
+          },
+        }),
+      ),
+  )
+
+  return (self) =>
+    set<D, B, [...I, Route.Route<{}, {}, "", never, never>]>(
+      [...items(self), route],
+      descriptor(self),
+    )
 }
 
 export class Routes extends Context.Tag("effect-start/Routes")<Routes, RouteTree.RouteTree>() {}
@@ -237,6 +257,42 @@ export function layer(routes: RouteTree.RouteMap | RouteTree.RouteTree) {
   return Layer.sync(Routes, () => (RouteTree.isRouteTree(routes) ? routes : RouteTree.make(routes)))
 }
 
+/**
+ * Creates a route that short-curcits in development.
+ *
+ * Note that when we convert the routes to web handles in {@link import("./RouteHttp.ts")},
+ * we exclude them altogeteher in development.
+ */
+export function devOnly<D extends RouteDescriptor.Any, B, I extends Route.Tuple>(
+  self: RouteSet.RouteSet<D, B, I>,
+): RouteSet.RouteSet<D, B, [...I, Route.Route<{ dev: true }, { dev: true }, unknown, any, any>]> {
+  const route: Route.Route<{ dev: true }, { dev: true }, unknown, any, any> = make<
+    { dev: true },
+    { dev: true },
+    unknown,
+    any,
+    any
+  >(
+    (context, next) =>
+      Effect.flatMap(Development.option, (developmentOption) =>
+        Option.isSome(developmentOption)
+          ? Effect.succeed(next({ ...context, dev: true }))
+          : Effect.succeed(Entity.make("", { status: 404 })),
+      ),
+    { dev: true },
+  )
+
+  const nextItems: [...I, Route.Route<{ dev: true }, { dev: true }, unknown, any, any>] = [
+    ...items(self),
+    route,
+  ]
+
+  return set<D, B, [...I, Route.Route<{ dev: true }, { dev: true }, unknown, any, any>]>(
+    nextItems,
+    descriptor(self),
+  )
+}
+
 export { make as tree } from "./RouteTree.ts"
 
 export function lazy<T extends RouteSet.Any>(

package/src/RouteBody.ts

@@ -3,6 +3,7 @@ import type * as Stream from "effect/Stream"
 import type * as Utils from "effect/Utils"
 import * as Entity from "./Entity.ts"
 import * as Route from "./Route.ts"
+import * as StreamExtra from "./_StreamExtra.ts"
 import type * as Values from "./_Values.ts"
 
 export type Format = "text" | "html" | "json" | "bytes" | "*"
@@ -21,21 +22,36 @@ type YieldError<T> = T extends Utils.YieldWrap<Effect.Effect<any, infer E, any>>
 
 type YieldContext<T> = T extends Utils.YieldWrap<Effect.Effect<any, any, infer R>> ? R : never
 
+type Next<B, A> = (context?: Partial<B> & Record<string, unknown>) => Entity.Entity<UnwrapStream<A>>
+
+type HandlerReturn<A> =
+  | A
+  | Entity.Entity<A>
+  | ((self: Route.RouteSet.Any) => Route.RouteSet.Any)
+
+type HandlerFunction<B, A, E, R> = (
+  context: Values.Simplify<B>,
+  next: Next<B, A>,
+) =>
+  | Effect.Effect<HandlerReturn<A>, E, R>
+  | Generator<Utils.YieldWrap<Effect.Effect<unknown, E, R>>, HandlerReturn<A>, unknown>
+
 export type GeneratorHandler<B, A, Y> = (
   context: Values.Simplify<B>,
-  next: (context?: Partial<B> & Record<string, unknown>) => Entity.Entity<UnwrapStream<A>>,
-) => Generator<Y, A | Entity.Entity<A>, never>
+  next: Next<B, A>,
+) => Generator<Y, HandlerReturn<A>, never>
 
 export type HandlerInput<B, A, E, R> =
   | A
   | Entity.Entity<A>
-  | Effect.Effect<A | Entity.Entity<A>, E, R>
-  | ((
-      context: Values.Simplify<B>,
-      next: (context?: Partial<B> & Record<string, unknown>) => Entity.Entity<UnwrapStream<A>>,
-    ) =>
-      | Effect.Effect<A | Entity.Entity<A>, E, R>
-      | Generator<Utils.YieldWrap<Effect.Effect<unknown, E, R>>, A | Entity.Entity<A>, unknown>)
+  | Effect.Effect<HandlerReturn<A>, E, R>
+  | HandlerFunction<B, A, E, R>
+
+function isHandlerFunction<B, A, E, R>(
+  handler: HandlerInput<B, A, E, R>,
+): handler is HandlerFunction<B, A, E, R> {
+  return typeof handler === "function"
+}
 
 export function handle<B, A, Y extends Utils.YieldWrap<Effect.Effect<any, any, any>>>(
   handler: GeneratorHandler<B, A, Y>,
@@ -46,38 +62,44 @@ export function handle<B, A, E, R>(
 export function handle<B, A, E, R>(
   handler: HandlerInput<B, A, E, R>,
 ): Route.Route.Handler<B, A, E, R> {
-  if (typeof handler === "function") {
-    return (
-      context: B,
-      next: (context?: Partial<B> & Record<string, unknown>) => Entity.Entity<A>,
-    ): Effect.Effect<Entity.Entity<A>, E, R> => {
-      const result = (handler as Function)(context, next)
+  if (isHandlerFunction(handler)) {
+    return ((context: any, next: any) => {
+      const result = handler(context, next)
       const effect = Effect.isEffect(result)
-        ? (result as Effect.Effect<A | Entity.Entity<A>, E, R>)
-        : (Effect.gen(function* () {
+        ? result
+        : Effect.gen(function* () {
             return yield* result
-          }) as Effect.Effect<A | Entity.Entity<A>, E, R>)
-      return Effect.map(effect, normalizeToEntity)
-    }
+          })
+      return Effect.flatMap(effect, normalizeToEntity)
+    }) as Route.Route.Handler<B, A, E, R>
   }
   if (Effect.isEffect(handler)) {
-    return (_context, _next) =>
-      Effect.map(handler, normalizeToEntity) as Effect.Effect<Entity.Entity<A>, E, R>
+    return ((_context: any, _next: any) =>
+      Effect.flatMap(handler, normalizeToEntity)) as Route.Route.Handler<B, A, E, R>
   }
   if (Entity.isEntity(handler)) {
     return (_context, _next) => Effect.succeed(handler as Entity.Entity<A>)
   }
-  return (_context, _next) => Effect.succeed(normalizeToEntity(handler as A) as Entity.Entity<A>)
+  return ((_context: any, _next: any) =>
+    normalizeToEntity(handler)) as Route.Route.Handler<B, A, E, R>
 }
 
-function normalizeToEntity<A>(value: A | Entity.Entity<A>): Entity.Entity<A> {
+function normalizeToEntity(value: unknown): Effect.Effect<Entity.Entity<any>> {
+  if (typeof value === "function") {
+    const result = (value as (self: Route.RouteSet.Any) => Route.RouteSet.Any)(Route.empty)
+    const routes = Route.items(result)
+    const route = routes[0]
+    if (route) {
+      return route.handler({}, () => Entity.make("")) as Effect.Effect<Entity.Entity<any>>
+    }
+  }
   if (Entity.isEntity(value)) {
-    return value as Entity.Entity<A>
+    return Effect.succeed(value)
   }
-  return Entity.make(value as A, { status: 200 })
+  return Effect.succeed(Entity.make(value, { status: 200 }))
 }
 
-export interface BuildReturn<Value, F extends Format> {
+export interface BuildReturn<Value, F extends Format, Body = never> {
   <
     D extends Route.RouteDescriptor.Any,
     B,
@@ -91,7 +113,7 @@ export interface BuildReturn<Value, F extends Format> {
   ) => Route.RouteSet.RouteSet<
     D,
     B,
-    [...I, Route.Route.Route<{ format: F }, {}, A, YieldError<Y>, YieldContext<Y>>]
+    [...I, Route.Route.Route<{ format: F }, {}, [Body] extends [never] ? A : Body, YieldError<Y>, YieldContext<Y>>]
   >
 
   <
@@ -105,50 +127,54 @@ export interface BuildReturn<Value, F extends Format> {
     handler: HandlerInput<NoInfer<D & B & Route.ExtractBindings<I> & { format: F }>, A, E, R>,
   ): (
     self: Route.RouteSet.RouteSet<D, B, I>,
-  ) => Route.RouteSet.RouteSet<D, B, [...I, Route.Route.Route<{ format: F }, {}, A, E, R>]>
+  ) => Route.RouteSet.RouteSet<D, B, [...I, Route.Route.Route<{ format: F }, {}, [Body] extends [never] ? A : Body, E, R>]>
 }
 
-export function build<Value, F extends Format>(descriptors: { format: F }) {
+export function build<Value, F extends Format>(options: { format: F }): BuildReturn<Value, F>
+export function build<Value, Body, F extends Format>(options: {
+  format: F
+  handle: (body: Value) => Body
+}): BuildReturn<Value, F, Body>
+export function build<Value, F extends Format>(options: {
+  format: F
+  handle?: (body: any) => any
+}): any {
+  const { handle: handleBody, ...descriptors } = options
   return function <
     D extends Route.RouteDescriptor.Any,
-    B extends {},
+    B,
     I extends Route.Route.Tuple,
     A extends F extends "json" ? Value : Value | Stream.Stream<Value, any, any>,
     E = never,
     R = never,
   >(handler: HandlerInput<NoInfer<D & B & Route.ExtractBindings<I> & { format: F }>, A, E, R>) {
-    return function (self: Route.RouteSet.RouteSet<D, B, I>) {
+    return (self: Route.RouteSet.RouteSet<D, B, I>) => {
       const contentType = formatToContentType[descriptors.format]
       const baseHandler = handle(handler)
-      const wrappedHandler: Route.Route.Handler<
-        D & B & Route.ExtractBindings<I> & { format: F },
-        A,
-        E,
-        R
-      > = (ctx, next) =>
-        Effect.map(baseHandler(ctx as any, next as any), (entity) =>
-          entity.headers["content-type"]
-            ? entity
-            : Entity.make(entity.body, {
-                status: entity.status,
-                url: entity.url,
-                headers: { ...entity.headers, "content-type": contentType },
-              }),
+      const wrappedHandler: Route.Route.Handler<{ format: F }, A, E, R> = (ctx, next) =>
+        baseHandler(ctx as D & B & Route.ExtractBindings<I> & { format: F }, next).pipe(
+          Effect.map((entity) => {
+            const body = handleBody && !StreamExtra.isStream(entity.body) ? handleBody(entity.body) : entity.body
+            if (body === entity.body && (entity.headers["content-type"] || contentType === undefined))
+              return entity
+            return Entity.make(body as A, {
+              status: entity.status,
+              url: entity.url,
+              headers: entity.headers["content-type"] || contentType === undefined
+                ? entity.headers
+                : { ...entity.headers, "content-type": contentType },
+            })
+          }),
         )
 
-      const route = Route.make<{ format: F }, {}, A, E, R>(wrappedHandler as any, descriptors)
-
-      const items: [...I, Route.Route.Route<{ format: F }, {}, A, E, R>] = [
-        ...Route.items(self),
-        route,
-      ]
+      const route = Route.make<{ format: F }, {}, A, E, R>(wrappedHandler, descriptors)
 
       return Route.set<D, B, [...I, Route.Route.Route<{ format: F }, {}, A, E, R>]>(
-        items,
+        [...Route.items(self), route],
         Route.descriptor(self),
       )
     }
-  } as unknown as BuildReturn<Value, F>
+  } as BuildReturn<Value, F>
 }
 
 export type RenderValue = string | Uint8Array | Stream.Stream<string | Uint8Array, any, any>
@@ -188,16 +214,15 @@ export function render<
   E = never,
   R = never,
 >(handler: HandlerInput<NoInfer<D & B & Route.ExtractBindings<I> & { format: "*" }>, A, E, R>) {
-  return function (self: Route.RouteSet.RouteSet<D, B, I>) {
-    const route = Route.make<{ format: "*" }, {}, A, E, R>(handle(handler) as any, { format: "*" })
-
-    const items: [...I, Route.Route.Route<{ format: "*" }, {}, A, E, R>] = [
-      ...Route.items(self),
-      route,
-    ]
+  return (self: Route.RouteSet.RouteSet<D, B, I>) => {
+    const baseHandler = handle(handler)
+    const route = Route.make<{ format: "*" }, {}, A, E, R>(
+      (ctx, next) => baseHandler(ctx as D & B & Route.ExtractBindings<I> & { format: "*" }, next),
+      { format: "*" },
+    )
 
     return Route.set<D, B, [...I, Route.Route.Route<{ format: "*" }, {}, A, E, R>]>(
-      items,
+      [...Route.items(self), route],
       Route.descriptor(self),
     )
   }

package/src/RouteHttp.ts

@@ -8,6 +8,7 @@ import type * as ParseResult from "effect/ParseResult"
 import * as Runtime from "effect/Runtime"
 import * as Stream from "effect/Stream"
 import * as ContentNegotiation from "./_ContentNegotiation.ts"
+import * as Development from "./Development.ts"
 import * as Entity from "./Entity.ts"
 import type * as Http from "./_Http.ts"
 import * as Route from "./Route.ts"
@@ -388,9 +389,26 @@ export function* walkHandles(
   runtime: Runtime.Runtime<never> = Runtime.defaultRuntime,
 ): Generator<[path: string, handler: Http.WebHandler]> {
   const pathGroups = new Map<string, Array<RouteMount.MountedRoute>>()
+  const runSync = Runtime.runSync(runtime)
+  const inDevelopment = Option.isSome(runSync(Development.option))
+  const developmentPaths = new Set<string>()
 
   for (const route of RouteTree.walk(tree)) {
-    const path = Route.descriptor(route).path
+    const descriptor = Route.descriptor<{ path: string; dev?: boolean }>(route)
+    if (descriptor.dev === true) {
+      developmentPaths.add(descriptor.path)
+    }
+  }
+
+  for (const route of RouteTree.walk(tree)) {
+    const descriptor = Route.descriptor<{ path: string; dev?: boolean }>(route)
+    if (descriptor.dev === true) {
+      continue
+    }
+    const path = descriptor.path
+    if (!inDevelopment && developmentPaths.has(path)) {
+      continue
+    }
     const group = pathGroups.get(path) ?? []
     group.push(route)
     pathGroups.set(path, group)

package/src/RouteMount.ts

@@ -83,7 +83,7 @@ function makeMethodDescriber<M extends RouteMount.Method>(method: M): RouteMount
     const result = f(methodSet)
     const resultItems = Route.items(result)
 
-    // Items are already flat (only Routes), just merge method into each descriptor
+    // Items are already flat (only Routes), merge method into each descriptor
     const flattenedItems = resultItems.map((item) => {
       const itemDescriptor = Route.descriptor(item)
       const newDescriptor = { method, ...itemDescriptor }

package/src/System.ts

@@ -67,7 +67,7 @@ export const which = (name: string): Effect.Effect<string, SystemError> =>
   )
 
 export const spawn = (
-  cmd: readonly [string, ...Array<string>],
+  cmd: [string, ...Array<string>] | string[],
   options?: ChildProcess.Command.Options,
 ): Effect.Effect<
   ChildProcess.ChildProcessHandle,

package/src/_ChildProcess.ts

@@ -57,7 +57,7 @@ const CommandProto = {
 export const isCommand = (u: unknown): u is Command => Predicate.hasProperty(u, TypeId)
 
 export const make = (
-  cmd: readonly [string, ...Array<string>],
+  cmd: [string, ...Array<string>] | string[],
   options?: Command.Options,
 ): Command =>
   Object.assign(Object.create(CommandProto), {