@teyik0/furin 0.1.0-alpha.3

package/src/client.ts

@@ -0,0 +1,237 @@
+/*
+  biome-ignore-all lint/complexity/noBannedTypes: The fundamental problem is that
+  `Record<string, unknown>` requires an index signature, and any type without one
+  (like `{}`, `object`, or a named interface) won't satisfy it. But `{}` is the only type that:
+  1. Satisfies `Record<string, unknown>` as a generic default (TS special-cases `{}`)
+  2. Doesn't have an index signature (so unknown prop access errors)
+  3. Is transparent in intersections(`{} & T = T`)
+*/
+
+import type { Cookie, StatusMap } from "elysia";
+import type { AnySchema, HTTPHeaders, UnwrapSchema } from "elysia/types";
+
+declare const UNSET: unique symbol;
+type Unset = typeof UNSET;
+
+type ResolvedSchema<T> = [T] extends [Unset]
+  ? Unset
+  : T extends AnySchema
+    ? UnwrapSchema<T>
+    : Unset;
+
+type MergeSchema<TParent, TOwn> = [TParent] extends [Unset]
+  ? TOwn
+  : [TOwn] extends [Unset]
+    ? TParent
+    : TParent & TOwn;
+
+type NormalizeUnset<T> = [T] extends [Unset] ? {} : T;
+
+export interface RouteContext<TParams = {}, TQuery = {}> {
+  cookie: Record<string, Cookie<unknown>>;
+  headers: Record<string, string | undefined>;
+  params: NormalizeUnset<TParams>;
+  path: string;
+  query: NormalizeUnset<TQuery>;
+  redirect: (url: string, status?: 301 | 302 | 303 | 307 | 308) => Response;
+  request: Request;
+  set: {
+    headers: HTTPHeaders;
+    status?: number | keyof StatusMap;
+  };
+}
+
+export interface ComponentProps<TParams = {}, TQuery = {}> {
+  params: NormalizeUnset<TParams>;
+  path: string;
+  query: NormalizeUnset<TQuery>;
+}
+
+type ResolveParent<T> =
+  T extends RouteRef<infer D, infer P, infer Q>
+    ? { data: D; params: P; query: Q }
+    : { data: {}; params: Unset; query: Unset };
+
+interface Resolved<TParentRef, TLoaderData, TParamsSchema = Unset, TQuerySchema = Unset> {
+  data: ResolveParent<TParentRef>["data"] & TLoaderData;
+  params: MergeSchema<ResolveParent<TParentRef>["params"], ResolvedSchema<TParamsSchema>>;
+  query: MergeSchema<ResolveParent<TParentRef>["query"], ResolvedSchema<TQuerySchema>>;
+}
+
+export type MetaDescriptor =
+  | { charSet: "utf-8" }
+  | { title: string }
+  | { name: string; content: string }
+  | { property: string; content: string }
+  | { httpEquiv: string; content: string }
+  | { "script:ld+json": object }
+  | { tagName: "meta" | "link"; [name: string]: string | undefined };
+
+export interface HeadOptions {
+  links?: Array<{ rel: string; href: string; [key: string]: string }>;
+  meta?: MetaDescriptor[];
+  scripts?: Array<{
+    src?: string;
+    type?: string;
+    children?: string;
+    [key: string]: string | undefined;
+  }>;
+  styles?: Array<{ type?: string; children: string }>;
+}
+
+export type LoaderDeps = (route: { __type: string }) => Promise<Record<string, unknown>>;
+
+export interface PageConfig<
+  TParentData extends Record<string, unknown>,
+  TParams,
+  TQuery,
+  TPageLoaderData extends Record<string, unknown> = {},
+> {
+  component: React.FC<TParentData & TPageLoaderData & ComponentProps<TParams, TQuery>>;
+  head?: (ctx: ComponentProps<TParams, TQuery> & TParentData & TPageLoaderData) => HeadOptions;
+  loader?: (
+    ctx: RouteContext<TParams, TQuery> & TParentData,
+    deps: TypedDeps
+  ) => Promise<TPageLoaderData> | TPageLoaderData;
+  staticParams?: () => Promise<NormalizeUnset<TParams>[]> | NormalizeUnset<TParams>[];
+}
+
+export interface RuntimeRoute {
+  __type: "FURIN_ROUTE";
+  layout?: React.FC<Record<string, unknown> & { children: React.ReactNode }>;
+  loader?(
+    ctx: Record<string, unknown>,
+    deps: LoaderDeps
+  ): Promise<Record<string, unknown>> | Record<string, unknown>;
+  mode?: "ssr" | "ssg" | "isr";
+  params?: unknown;
+  parent?: RuntimeRoute;
+  query?: unknown;
+  revalidate?: number;
+}
+
+export interface RuntimePage {
+  __type: "FURIN_PAGE";
+  _route: RuntimeRoute;
+  component: React.FC<Record<string, unknown>>;
+  head?(ctx: Record<string, unknown>): HeadOptions;
+  loader?(
+    ctx: Record<string, unknown>,
+    deps: LoaderDeps
+  ): Promise<Record<string, unknown>> | Record<string, unknown>;
+  staticParams?(): Promise<Record<string, string>[]> | Record<string, string>[];
+}
+
+export interface RouteRef<
+  TData extends Record<string, unknown> = Record<string, unknown>,
+  TParams = unknown,
+  TQuery = unknown,
+> {
+  readonly __brand: "FURIN_ROUTE_REF";
+  readonly __phantom: { data: TData; params: TParams; query: TQuery };
+}
+
+interface PageResult<
+  TData extends Record<string, unknown>,
+  TParams,
+  TQuery,
+  TPageLoaderData extends Record<string, unknown>,
+> {
+  __type: "FURIN_PAGE";
+  _route: Route<TData, TParams, TQuery>;
+  component: React.FC<TData & TPageLoaderData & ComponentProps<TParams, TQuery>>;
+  head?: (ctx: ComponentProps<TParams, TQuery> & TData & TPageLoaderData) => HeadOptions;
+  loader?: (
+    ctx: RouteContext<TParams, TQuery> & TData,
+    deps: TypedDeps
+  ) => Promise<TPageLoaderData> | TPageLoaderData;
+}
+
+export interface Route<TParentData extends Record<string, unknown>, TParams, TQuery> {
+  __type: "FURIN_ROUTE";
+  layout?: React.FC<TParentData & { children: React.ReactNode } & ComponentProps<TParams, TQuery>>;
+  loader?(
+    ctx: RouteContext<TParams, TQuery> & TParentData,
+    deps: TypedDeps
+  ): Promise<TParentData> | TParentData;
+  mode?: "ssr" | "ssg" | "isr";
+
+  page<TPageLoaderData extends Record<string, unknown> = {}>(
+    config: PageConfig<TParentData, TParams, TQuery, TPageLoaderData>
+  ): PageResult<TParentData, TParams, TQuery, TPageLoaderData>;
+
+  params?: unknown;
+  parent?: RuntimeRoute;
+  query?: unknown;
+
+  /** Branded ref for type inference when used as a parent. */
+  ref: RouteRef<TParentData, TParams, TQuery>;
+  revalidate?: number;
+}
+
+// User-facing typed deps: infers the loader data type from the route ref.
+type TypedDeps = <TData extends Record<string, unknown>>(
+  // biome-ignore lint/suspicious/noExplicitAny: any needed for flexible route type inference
+  route: Route<TData, any, any>
+) => Promise<TData>;
+
+export function createRoute<
+  TParentRef extends RouteRef | undefined = undefined,
+  TParamsSchema extends AnySchema | Unset = Unset,
+  TQuerySchema extends AnySchema | Unset = Unset,
+  TLoaderData extends Record<string, unknown> = {},
+>(config?: {
+  parent?: { ref: TParentRef } & { __type: "FURIN_ROUTE" };
+  mode?: "ssr" | "ssg" | "isr";
+  revalidate?: number;
+  params?: TParamsSchema;
+  query?: TQuerySchema;
+  loader?: (
+    ctx: RouteContext<
+      Resolved<TParentRef, TLoaderData, TParamsSchema, TQuerySchema>["params"],
+      Resolved<TParentRef, TLoaderData, TParamsSchema, TQuerySchema>["query"]
+    > &
+      ResolveParent<TParentRef>["data"],
+    deps: TypedDeps
+  ) => Promise<TLoaderData> | TLoaderData;
+  layout?: React.FC<
+    Resolved<TParentRef, TLoaderData, TParamsSchema, TQuerySchema>["data"] & {
+      children: React.ReactNode;
+    } & ComponentProps<
+        Resolved<TParentRef, TLoaderData, TParamsSchema, TQuerySchema>["params"],
+        Resolved<TParentRef, TLoaderData, TParamsSchema, TQuerySchema>["query"]
+      >
+  >;
+}): Route<
+  Resolved<TParentRef, TLoaderData, TParamsSchema, TQuerySchema>["data"],
+  Resolved<TParentRef, TLoaderData, TParamsSchema, TQuerySchema>["params"],
+  Resolved<TParentRef, TLoaderData, TParamsSchema, TQuerySchema>["query"]
+> {
+  type R = Resolved<TParentRef, TLoaderData, TParamsSchema, TQuerySchema>;
+
+  const route = {
+    ...config,
+    __type: "FURIN_ROUTE" as const,
+    ref: {} as RouteRef<R["data"], R["params"], R["query"]>,
+
+    page<TPageLoaderData extends Record<string, unknown> = {}>(
+      pageConfig: PageConfig<R["data"], R["params"], R["query"], TPageLoaderData>
+    ) {
+      return {
+        ...pageConfig,
+        __type: "FURIN_PAGE" as const,
+        _route: route,
+      };
+    },
+  };
+  return route as Route<R["data"], R["params"], R["query"]>;
+}
+
+export type InferProps<T> = T extends {
+  __type: "ELYRA_PAGE";
+  component: React.FC<infer P>;
+}
+  ? P
+  : T extends Route<infer D, infer P, infer Q>
+    ? D & { children: React.ReactNode } & ComponentProps<P, Q>
+    : never;

package/src/config.ts

@@ -0,0 +1,31 @@
+export type { BunPlugin } from "bun";
+
+import { t } from "elysia";
+
+export const BUILD_TARGETS = ["bun", "node", "vercel", "cloudflare"] as const;
+
+export type BuildTarget = (typeof BUILD_TARGETS)[number];
+
+const buildTargetSchema = t.Union(BUILD_TARGETS.map((v) => t.Literal(v)));
+const compileTargetSchema = t.Union([t.Literal("server"), t.Literal("embed")]);
+
+export const configSchema = t.Object({
+  rootDir: t.Optional(t.String()),
+  pagesDir: t.Optional(t.String()),
+  serverEntry: t.Optional(t.String()),
+  targets: t.Optional(t.Array(buildTargetSchema)),
+  bun: t.Optional(
+    t.Object({
+      compile: t.Optional(compileTargetSchema),
+    })
+  ),
+  // plugins omitted : TypeBox can't validate Bun.BunPlugin[] (functions)
+});
+
+export type FurinConfig = (typeof configSchema)["static"] & {
+  plugins?: Bun.BunPlugin[];
+};
+
+export function defineConfig(config: FurinConfig): FurinConfig {
+  return config;
+}

package/src/furin.ts

@@ -0,0 +1,251 @@
+import { existsSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { staticPlugin } from "@elysiajs/static";
+import { Elysia } from "elysia";
+import type { EmbeddedAppData } from "./internal.ts";
+import { getCompileContext } from "./internal.ts";
+import { warmSSGCache } from "./render/index.ts";
+import { setProductionTemplateContent, setProductionTemplatePath } from "./render/template.ts";
+import { createRoutePlugin, loadProdRoutes, scanPages } from "./router.ts";
+import { IS_DEV } from "./runtime-env.ts";
+
+function resolveClientDirFromArgv(): string {
+  return (
+    resolveClientDirFromEnv() ??
+    resolveClientDirFromModuleUrl() ??
+    resolveClientDirFromProcessArgs() ??
+    resolveFallbackClientDir()
+  );
+}
+
+function resolveClientDirFromEnv(): string | null {
+  const envClientDir = process.env.FURIN_CLIENT_DIR;
+  if (!envClientDir) {
+    return null;
+  }
+  return envClientDir.startsWith("/") ? envClientDir : resolve(process.cwd(), envClientDir);
+}
+
+function resolveClientDirFromModuleUrl(): string | null {
+  try {
+    const moduleUrl = new URL(import.meta.url);
+    if (moduleUrl.protocol !== "file:") {
+      return null;
+    }
+    const modulePath = fileURLToPath(moduleUrl);
+    if (modulePath.includes("/$bunfs/")) {
+      return null;
+    }
+    const moduleClientDir = join(dirname(modulePath), "client");
+    if (existsSync(join(moduleClientDir, "index.html"))) {
+      return moduleClientDir;
+    }
+  } catch {
+    // ignore, fallback to argv-based resolution
+  }
+  return null;
+}
+
+function resolveClientDirFromProcessArgs(): string | null {
+  const candidates = [
+    process.argv[1],
+    process.argv[0],
+    (process as { argv0?: string }).argv0,
+    process.execPath,
+  ].filter((value): value is string => typeof value === "string" && value.length > 0);
+
+  for (const candidate of candidates) {
+    const resolved = resolveClientDirFromCandidate(candidate);
+    if (resolved) {
+      return resolved;
+    }
+  }
+
+  return null;
+}
+
+function resolveClientDirFromCandidate(candidate: string): string | null {
+  const name = basename(candidate);
+  if (name === "bun" || name === "node") {
+    return null;
+  }
+  if (candidate.includes("/$bunfs/") || candidate.startsWith("bunfs:")) {
+    return null;
+  }
+
+  const absolute = candidate.startsWith("/") ? candidate : resolve(process.cwd(), candidate);
+  if (existsSync(absolute)) {
+    return join(dirname(absolute), "client");
+  }
+
+  if (!candidate.includes("/")) {
+    return resolveClientDirFromPath(candidate);
+  }
+
+  return null;
+}
+
+function resolveClientDirFromPath(candidate: string): string | null {
+  const pathEntries = process.env.PATH?.split(":") ?? [];
+  for (const dir of pathEntries) {
+    const fullPath = join(dir, candidate);
+    if (existsSync(fullPath)) {
+      return join(dirname(fullPath), "client");
+    }
+  }
+  return null;
+}
+
+function resolveFallbackClientDir(): string {
+  const defaultClientDir = resolve(process.cwd(), ".furin/build/bun/client");
+  if (existsSync(join(defaultClientDir, "index.html"))) {
+    return defaultClientDir;
+  }
+
+  return join(process.cwd(), "client");
+}
+
+async function setupProdTemplate(
+  embedded: EmbeddedAppData | undefined,
+  clientDir: string
+): Promise<void> {
+  if (embedded) {
+    if (!embedded.template) {
+      throw new Error("[furin] Embedded app is missing its HTML template (index.html).");
+    }
+    const html = await Bun.file(embedded.template).text();
+    setProductionTemplateContent(html);
+    return;
+  }
+
+  const templatePath = join(clientDir, "index.html");
+  if (!existsSync(templatePath)) {
+    throw new Error("[furin] No pre-built assets found. Run `bun run build` first.");
+  }
+  setProductionTemplatePath(templatePath);
+}
+
+function buildEmbedInstance(
+  instanceName: string,
+  resolvedPagesDir: string,
+  embedded: EmbeddedAppData
+): Elysia {
+  const { assets } = embedded;
+  // Explicit wildcard route — lifecycle hooks don't fire for unmatched routes.
+  return new Elysia({ name: instanceName, seed: resolvedPagesDir })
+    .get("/_client/*", ({ params }) => {
+      const filePath = assets[`/_client/${params["*"]}`];
+      return filePath
+        ? new Response(Bun.file(filePath))
+        : new Response("Not Found", { status: 404 });
+    })
+    .get("/public/*", ({ params }) => {
+      const filePath = assets[`/public/${params["*"]}`];
+      return filePath
+        ? new Response(Bun.file(filePath))
+        : new Response("Not Found", { status: 404 });
+    }) as unknown as Elysia;
+}
+
+async function buildDiskInstance(
+  instanceName: string,
+  resolvedPagesDir: string,
+  clientDir: string,
+  publicDir: string
+): Promise<Elysia> {
+  let instance = new Elysia({ name: instanceName, seed: resolvedPagesDir });
+
+  if (existsSync(publicDir)) {
+    instance = instance.use(await staticPlugin({ assets: publicDir, prefix: "/public" }));
+  }
+
+  instance = instance.use(await staticPlugin({ assets: clientDir, prefix: "/_client" }));
+  return instance;
+}
+
+/**
+ * Main Furin plugin.
+ *
+ * Returns a standalone Elysia instance (async function) so that routes are
+ * properly registered in Elysia's router for SPA navigation to work.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * new Elysia()
+ *   .use(await furin({ ... }))
+ *   .listen(3000)
+ * ```
+ */
+export async function furin({ pagesDir }: { pagesDir?: string }) {
+  const cwd = process.cwd();
+  const ctx = getCompileContext();
+  const resolvedPagesDir = ctx?.rootPath
+    ? dirname(ctx.rootPath)
+    : resolve(cwd, pagesDir ?? "src/pages");
+
+  // Unique name per pagesDir to avoid Elysia's name-based plugin dedup.
+  const instanceName = `furin-${resolvedPagesDir.replaceAll("\\", "/")}`;
+
+  // ── Dev: Bun native HMR ────────────────────────────────────────────────
+  if (IS_DEV) {
+    const furinDir = resolve(cwd, ".furin");
+    const { root, routes } = await scanPages(resolvedPagesDir);
+    console.info(
+      `[furin] Configuration: ${routes.length} page(s) — ${IS_DEV ? "dev (Bun HMR)" : "production"}`
+    );
+    for (const route of routes) {
+      const hasLayout = route.routeChain.some((r) => r.layout);
+      console.info(
+        `  ${route.mode.toUpperCase().padEnd(4)} ${route.pattern}${hasLayout ? " + layout" : ""}`
+      );
+    }
+    // Lazy import — build pipeline has native deps not available in compiled binaries
+    const { writeDevFiles } = await import("./build/hydrate.ts");
+    writeDevFiles(routes, { outDir: furinDir, rootLayout: root.path });
+
+    let instance = new Elysia({ name: instanceName, seed: resolvedPagesDir })
+      .use(await staticPlugin({ assets: furinDir, prefix: "/_bun_hmr_entry" }))
+      .use(await staticPlugin());
+
+    for (const route of routes) {
+      instance = instance.use(createRoutePlugin(route, root));
+    }
+
+    return instance;
+  }
+
+  // ── Production ──────────────────────────────────────────────────────────
+  if (!ctx) {
+    throw new Error("[furin] No pre-built assets found. Run `bun run build` first.");
+  }
+  const { root, routes } = loadProdRoutes(ctx);
+
+  const embedded = ctx?.embedded;
+  const clientDir = embedded ? "" : resolveClientDirFromArgv();
+  const publicDir = embedded ? "" : join(dirname(clientDir), "public");
+
+  await setupProdTemplate(embedded, clientDir);
+
+  let instance = embedded
+    ? buildEmbedInstance(instanceName, resolvedPagesDir, embedded)
+    : await buildDiskInstance(instanceName, resolvedPagesDir, clientDir, publicDir);
+
+  for (const route of routes) {
+    instance = instance.use(createRoutePlugin(route, root));
+  }
+
+  // Pre-render SSG routes with staticParams before the first request arrives.
+  const ssgTargets = routes.filter((r) => r.mode === "ssg" && r.page?.staticParams);
+  if (ssgTargets.length > 0) {
+    instance = instance.onStart(async ({ server }) => {
+      const origin = server?.url?.origin ?? "http://localhost:3000";
+      console.log(`[furin] Warming SSG cache for ${ssgTargets.length} route(s)…`);
+      await warmSSGCache(ssgTargets, root, origin);
+      console.log("[furin] SSG warm-up complete.");
+    });
+  }
+
+  return instance;
+}

package/src/internal.ts

@@ -0,0 +1,36 @@
+// ── Compile-time context for compiled binaries ──────────────────────────────
+// The generated compile entry calls `__setCompileContext()` before importing
+// server.ts. At runtime, `router.ts` and `furin.ts` use `getCompileContext()`
+// to resolve modules and assets from the binary instead of the filesystem.
+
+export interface EmbeddedAppData {
+  assets: Record<string, string>;
+  template: string;
+}
+
+export interface CompileContextRoute {
+  mode: "ssr" | "ssg" | "isr";
+  path: string;
+  pattern: string;
+}
+
+export interface CompileContext {
+  embedded?: EmbeddedAppData;
+  modules: Record<string, unknown>;
+  rootPath: string;
+  routes: CompileContextRoute[];
+}
+
+let _compileCtx: CompileContext | null = null;
+
+export function __setCompileContext(ctx: CompileContext): void {
+  _compileCtx = ctx;
+}
+
+export function getCompileContext(): CompileContext | null {
+  return _compileCtx;
+}
+
+export function __resetCompileContext(): void {
+  _compileCtx = null;
+}