h3leaf 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shamilkotta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,50 @@
-# Temporary Holding Version
+# h3leaf
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Convention-based H3 route compiler, CLI, and optional Vite plugin (`h3leaf/vite`).
+
+## Route conventions
+
+Files under the routes directory are URL endpoints. `index.ts` resolves to its directory; extensions may be `.ts`, `.tsx`, `.js`, `.jsx`, `.mts`, or `.mjs`. Files beginning with `_`, test/spec files, and declaration files are ignored.
+
+| File                   | Route           |
+| ---------------------- | --------------- |
+| `health.ts`            | `/health`       |
+| `users/index.ts`       | `/users`        |
+| `users/[id].ts`        | `/users/:id`    |
+| `docs/[...path].ts`    | `/docs/**:path` |
+| `docs/[[...path]].ts`  | `/docs/**`      |
+| `blog/[[slug]].ts`     | `/blog/:slug?`  |
+| `(internal)/health.ts` | `/health`       |
+
+Routes export uppercase HTTP method handlers (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`, `CONNECT`, `TRACE`), plus an optional `handler` or default export for all methods. Specific methods win over `handler`; two route files resolving to the same path are rejected at build time.
+
+Generated handlers receive H3's `H3Event`, so H3's response conversion, params, middleware-compatible context, errors, and `event.waitUntil()` remain available. The compilation stage is represented as an `Effect` program, keeping filesystem failures typed and composable for embedding tools.
+
+## Optional app entry
+
+Place `_leaf.ts` (or another supported JS/TS extension) at the root of the routes directory to own the H3 app instance. Export a named `app` (recommended) or default `H3` instance; h3leaf attaches every discovered route to it. This is where application-wide middleware, H3 plugins, error hooks, and custom app configuration live.
+
+```ts
+// api/_leaf.ts
+import { H3 } from "h3";
+
+export const app = new H3().use((event) => {
+  event.res.headers.set("x-powered-by", "my-api");
+});
+```
+
+The CLI supports `--entry custom-app` for another module name. The compiler and Vite plugin accept `entryFile: "custom-app"`; set it to `false` to disable entry-file discovery.
+
+## Vite plugin
+
+Build the frontend and its H3 API Worker in one `vite build` command:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { h3leaf } from "h3leaf/vite";
+
+export default defineConfig({
+  plugins: [h3leaf({ routesDir: "api", base: "/api", outFile: "worker.mjs" })],
+});
+```

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/cli.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+import { n as generateEntry, r as resolveEntryFile, t as discoverRoutes } from "./src-DQ-jHPmt.mjs";
+import { Effect } from "effect";
+import path from "node:path";
+import { watch } from "node:fs";
+import { build, context } from "esbuild";
+import { pathToFileURL } from "node:url";
+import { tmpdir } from "node:os";
+import { H3, serve } from "h3";
+//#region src/cli.ts
+const args = process.argv.slice(2);
+const option = (name) => {
+	const index = args.indexOf(name);
+	return index === -1 ? void 0 : args[index + 1];
+};
+const usage = [
+	"Usage:",
+	"  h3leaf build [--routes api] [--base /api] [--entry _leaf] [--out dist/worker.mjs]",
+	"  h3leaf dev [--routes api] [--base /api] [--entry _leaf] [--port 3000]"
+].join("\n");
+const command = args[0];
+if (!command || args.includes("--help") || !["build", "dev"].includes(command)) {
+	console.log(usage);
+	process.exit(args.includes("--help") ? 0 : 1);
+}
+const routesDirectory = option("--routes") ?? "api";
+const base = option("--base");
+const entryFile = option("--entry");
+const virtualEntry = "virtual:h3leaf/entry";
+const prepareEntry = () => {
+	const resolvedRoutes = path.resolve(routesDirectory);
+	return Effect.all({
+		routes: discoverRoutes(resolvedRoutes),
+		resolvedEntry: resolveEntryFile(resolvedRoutes, entryFile)
+	}).pipe(Effect.map(({ routes, resolvedEntry }) => ({
+		routes,
+		contents: generateEntry(routes, {
+			routesDirectory: resolvedRoutes,
+			entryFile: resolvedEntry,
+			base,
+			importFile: (file) => file.replace(/\\/g, "/")
+		})
+	})));
+};
+const virtualEntryPlugin = (getContents) => ({
+	name: "h3leaf-virtual-entry",
+	setup(buildApi) {
+		buildApi.onResolve({ filter: /^virtual:h3leaf\/entry$/ }, () => ({
+			path: virtualEntry,
+			namespace: "h3leaf"
+		}));
+		buildApi.onLoad({
+			filter: /.*/,
+			namespace: "h3leaf"
+		}, () => ({
+			contents: getContents(),
+			loader: "ts",
+			resolveDir: path.resolve(routesDirectory)
+		}));
+	}
+});
+const sharedBundleOptions = {
+	entryPoints: [virtualEntry],
+	bundle: true,
+	format: "esm",
+	platform: "neutral",
+	target: "es2022",
+	legalComments: "none"
+};
+if (command === "build") {
+	const outFile = path.resolve(option("--out") ?? "dist/api.mjs");
+	const buildWorker = prepareEntry().pipe(Effect.flatMap(({ routes, contents }) => Effect.tryPromise({
+		try: async () => {
+			await build({
+				...sharedBundleOptions,
+				outfile: outFile,
+				sourcemap: false,
+				plugins: [virtualEntryPlugin(() => contents)]
+			});
+			return {
+				routes,
+				outFile
+			};
+		},
+		catch: (cause) => new Error(`Unable to bundle worker: ${cause instanceof Error ? cause.message : String(cause)}`, { cause })
+	})));
+	Effect.runPromise(buildWorker).then(({ routes, outFile: bundledFile }) => console.log(`h3leaf: bundled ${routes.length} route${routes.length === 1 ? "" : "s"} → ${bundledFile}`)).catch((error) => {
+		console.error(`h3leaf: ${error.message}`);
+		process.exitCode = 1;
+	});
+} else {
+	const port = Number(option("--port") ?? "3000");
+	const bundledWorker = path.join(tmpdir(), `h3leaf-dev-${process.pid}.mjs`);
+	let entryContents = "";
+	const bundler = await context({
+		...sharedBundleOptions,
+		sourcemap: true,
+		outfile: bundledWorker,
+		plugins: [virtualEntryPlugin(() => entryContents)]
+	});
+	let activeApp;
+	let timer;
+	const reload = async () => {
+		try {
+			const { routes, contents } = await Effect.runPromise(prepareEntry());
+			entryContents = contents;
+			await bundler.rebuild();
+			activeApp = (await import(`${pathToFileURL(bundledWorker).href}?v=${Date.now()}`)).app;
+			console.log(`h3leaf: reloaded ${routes.length} route${routes.length === 1 ? "" : "s"}`);
+		} catch (error) {
+			console.error(`h3leaf: reload failed; keeping the last working app\n${error}`);
+		}
+	};
+	await reload();
+	if (!activeApp) process.exit(1);
+	const devApp = new H3().all("/**", (event) => activeApp ? activeApp.fetch(event.req) : new Response("h3leaf is reloading", { status: 503 }));
+	const listener = serve(devApp, { port });
+	const watcher = watch(path.resolve(routesDirectory), { recursive: true }, () => {
+		if (timer) clearTimeout(timer);
+		timer = setTimeout(reload, 60);
+	});
+	const shutdown = () => {
+		watcher.close();
+		listener.close();
+		bundler.dispose();
+	};
+	process.once("SIGINT", shutdown);
+	process.once("SIGTERM", shutdown);
+}
+//#endregion
+export {};

package/dist/src-DQ-jHPmt.mjs

@@ -0,0 +1,96 @@
+import { Data, Effect } from "effect";
+import path from "node:path";
+import { promises } from "node:fs";
+//#region src/index.ts
+const HTTP_METHODS = [
+	"GET",
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE",
+	"HEAD",
+	"OPTIONS",
+	"CONNECT",
+	"TRACE"
+];
+var CompileError = class extends Data.TaggedError("CompileError") {};
+const extensions = /* @__PURE__ */ new Set([
+	".ts",
+	".tsx",
+	".js",
+	".jsx",
+	".mts",
+	".mjs"
+]);
+const ignored = (name) => name.startsWith("_") || name.endsWith(".d.ts") || /\.(test|spec)\.[cm]?[jt]sx?$/.test(name);
+const walk = (directory) => Effect.tryPromise({
+	try: async () => {
+		const entries = await promises.readdir(directory, { withFileTypes: true });
+		return (await Promise.all(entries.map(async (entry) => {
+			const candidate = path.join(directory, entry.name);
+			if (entry.isDirectory()) return ignored(entry.name) ? [] : await Effect.runPromise(walk(candidate));
+			return entry.isFile() && extensions.has(path.extname(entry.name)) && !ignored(entry.name) ? [candidate] : [];
+		}))).flat();
+	},
+	catch: (cause) => new CompileError({
+		message: `Unable to read routes directory: ${directory}`,
+		cause
+	})
+});
+const fileToRoute = (routesDirectory, file) => {
+	return `/${path.relative(routesDirectory, file).replace(/\.[^.]+$/, "").split(path.sep).filter((segment) => segment !== "index" && !/^\(.+\)$/.test(segment)).map((segment) => {
+		if (/^\[\[\.\.\.(.+)\]\]$/.test(segment)) return "**";
+		if (/^\[\.\.\.(.+)\]$/.test(segment)) return `**:${segment.slice(4, -1)}`;
+		if (/^\[\[(.+)\]\]$/.test(segment)) return `:${segment.slice(2, -2)}?`;
+		if (/^\[(.+)\]$/.test(segment)) return `:${segment.slice(1, -1)}`;
+		return segment;
+	}).join("/")}`.replace(/\/$/, "") || "/";
+};
+const discoverRoutes = (routesDirectory) => walk(routesDirectory).pipe(Effect.map((files) => files.map((file) => ({
+	file,
+	route: fileToRoute(routesDirectory, file)
+})).toSorted((a, b) => a.route.localeCompare(b.route) || a.file.localeCompare(b.file))), Effect.flatMap((routes) => {
+	const duplicate = routes.find((route, index) => index > 0 && routes[index - 1]?.route === route.route);
+	return duplicate ? Effect.fail(new CompileError({ message: `Two route files resolve to ${duplicate.route}: ${routes.filter((r) => r.route === duplicate.route).map((r) => r.file).join(", ")}` })) : Effect.succeed(routes);
+}));
+/** Resolves an optional root `_leaf` module (or a configured replacement). */
+const resolveEntryFile = (routesDirectory, entryFile = void 0) => {
+	if (entryFile === false) return Effect.succeed(void 0);
+	const requested = entryFile ?? "_leaf";
+	const resolved = path.resolve(routesDirectory, requested);
+	const directory = path.dirname(resolved);
+	const fileName = path.basename(resolved);
+	const candidates = extensions.has(path.extname(fileName)) ? [fileName] : [...extensions].map((extension) => `${fileName}${extension}`);
+	return Effect.tryPromise({
+		try: () => promises.readdir(directory, { withFileTypes: true }),
+		catch: (cause) => new CompileError({
+			message: `Unable to read entry directory: ${directory}`,
+			cause
+		})
+	}).pipe(Effect.flatMap((entries) => {
+		const matches = entries.filter((entry) => entry.isFile() && candidates.includes(entry.name)).map((entry) => path.join(directory, entry.name));
+		if (matches.length === 0 && entryFile === void 0) return Effect.succeed(void 0);
+		if (matches.length === 1) return Effect.succeed(matches[0]);
+		return Effect.fail(new CompileError({ message: matches.length === 0 ? `Configured entry file was not found: ${resolved}` : `More than one entry file matches ${requested}: ${matches.join(", ")}` }));
+	}));
+};
+const generateEntry = (routes, options) => {
+	const base = options.base && options.base !== "/" ? `/${options.base.replace(/^\/+|\/+$/g, "")}` : "";
+	const routePath = (route) => `${base}${route === "/" ? "" : route}` || "/";
+	const importFile = (file) => options.importFile?.(file) ?? path.relative(path.dirname(options.sourceFile ?? "entry.ts"), file).replace(/\\/g, "/").replace(/^(?!\.)/, "./");
+	const entryImport = options.entryFile ? `import * as leafEntry from ${JSON.stringify(importFile(options.entryFile))};\n` : "";
+	const imports = routes.map((route, index) => {
+		return `import * as route${index} from ${JSON.stringify(importFile(route.file))};`;
+	}).join("\n");
+	const registrations = routes.map((route, index) => `{
+  const module = route${index};
+  for (const [method, handler] of Object.entries(module)) {
+    if (${JSON.stringify(HTTP_METHODS)}.includes(method) && typeof handler === "function") app.on(method, ${JSON.stringify(routePath(route.route))}, handler);
+  }
+  const fallback = Object.entries(module).find(([name]) => name === "handler")?.[1] ?? Object.entries(module).find(([name]) => name === "default")?.[1];
+  if (typeof fallback === "function") app.all(${JSON.stringify(routePath(route.route))}, fallback);
+}`).join("\n");
+	return `// Generated by h3leaf. Do not edit.\nimport { H3 } from "h3";\n${entryImport}${imports}\n\nexport const app = ${options.entryFile ? "Object.entries(leafEntry).find(([name]) => name === \"app\")?.[1] ?? Object.entries(leafEntry).find(([name]) => name === \"default\")?.[1]" : "new H3()"};\nif (!app || typeof app.on !== "function" || typeof app.all !== "function") throw new TypeError("h3leaf entry must export an H3 app as named app or default export.");\n${registrations}\n\nexport const fetch = app.fetch;\nexport default { fetch };\n`;
+};
+//#endregion
+export { generateEntry as n, resolveEntryFile as r, discoverRoutes as t };

package/dist/vite.d.mts

@@ -0,0 +1,11 @@
+import { Plugin } from "vite";
+//#region src/vite.d.ts
+export type H3LeafPluginOptions = Readonly<{
+  routesDir?: string;
+  base?: string;
+  entryFile?: string | false;
+  outFile?: string;
+  sourcemap?: boolean;
+}>;
+export declare const h3leaf: (options?: H3LeafPluginOptions) => Plugin;
+//#endregion

package/dist/vite.mjs

@@ -0,0 +1,91 @@
+import { n as generateEntry, r as resolveEntryFile, t as discoverRoutes } from "./src-DQ-jHPmt.mjs";
+import { Effect } from "effect";
+import path from "node:path";
+import { Readable } from "node:stream";
+//#region src/vite.ts
+const environmentName = "h3leaf";
+const virtualEntryId = "virtual:h3leaf/worker-entry";
+const resolvedVirtualEntryId = `\0${virtualEntryId}`;
+const normalizedBase = (base) => base && base !== "/" ? `/${base.replace(/^\/+|\/+$/g, "")}` : void 0;
+const h3leaf = (options = {}) => {
+	return {
+		name: "h3leaf",
+		config(config) {
+			const outDir = config.build?.outDir ?? "dist";
+			return {
+				builder: {},
+				environments: { [environmentName]: {
+					consumer: "server",
+					resolve: { noExternal: true },
+					build: {
+						outDir,
+						emptyOutDir: false,
+						sourcemap: options.sourcemap ?? config.build?.sourcemap,
+						target: "es2022",
+						rollupOptions: {
+							input: virtualEntryId,
+							output: {
+								entryFileNames: options.outFile ?? (options.base ? `${options.base.replace(/^\/+|\/+$/g, "")}.mjs` : "api.mjs"),
+								format: "es"
+							}
+						}
+					}
+				} }
+			};
+		},
+		async buildApp(builder) {
+			for (const environment of Object.values(builder.environments)) if (!environment.isBuilt) await builder.build(environment);
+		},
+		resolveId(id) {
+			if (id === virtualEntryId && [environmentName, "ssr"].includes(this.environment.name)) return resolvedVirtualEntryId;
+		},
+		async load(id) {
+			if (id !== resolvedVirtualEntryId || ![environmentName, "ssr"].includes(this.environment.name)) return;
+			const routesDirectory = path.resolve(this.environment.config.root, options.routesDir ?? "api");
+			const { routes, entryFile } = await Effect.runPromise(Effect.all({
+				routes: discoverRoutes(routesDirectory),
+				entryFile: resolveEntryFile(routesDirectory, options.entryFile)
+			}));
+			return generateEntry(routes, {
+				routesDirectory,
+				sourceFile: path.join(this.environment.config.root, ".h3leaf", "entry.ts"),
+				entryFile,
+				base: options.base,
+				importFile: (file) => file.replace(/\\/g, "/")
+			});
+		},
+		configureServer(server) {
+			const base = normalizedBase(options.base);
+			if (!base) return;
+			server.middlewares.use((request, response, next) => {
+				if (request.url !== base && !request.url?.startsWith(`${base}/`)) return next();
+				(async () => {
+					try {
+						const worker = await server.ssrLoadModule(virtualEntryId);
+						const method = request.method ?? "GET";
+						const headers = new Headers();
+						Object.entries(request.headers).forEach(([name, value]) => {
+							if (value !== void 0) headers.set(name, Array.isArray(value) ? value.join(", ") : value);
+						});
+						const body = method === "GET" || method === "HEAD" ? void 0 : Readable.toWeb(request);
+						const webRequest = new Request(`http://${request.headers.host ?? "localhost"}${request.url ?? "/"}`, {
+							method,
+							headers,
+							body,
+							duplex: "half"
+						});
+						const webResponse = await worker.fetch(webRequest);
+						response.statusCode = webResponse.status;
+						webResponse.headers.forEach((value, name) => response.setHeader(name, value));
+						if (!webResponse.body) return response.end();
+						Readable.fromWeb(webResponse.body).pipe(response);
+					} catch (error) {
+						next(error);
+					}
+				})();
+			});
+		}
+	};
+};
+//#endregion
+export { h3leaf };

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "h3leaf",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Convention-based H3 route compiler, CLI, and optional Vite plugin for Workers and Web-standard runtimes",
+  "license": "MIT",
+  "author": "shamilkotta",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shamilkotta/h3leaf.git",
+    "directory": "packages/h3leaf"
+  },
+  "homepage": "https://github.com/shamilkotta/h3leaf/tree/main/packages/h3leaf#readme",
+  "bugs": {
+    "url": "https://github.com/shamilkotta/h3leaf/issues"
+  },
+  "keywords": [
+    "h3",
+    "vite",
+    "cloudflare",
+    "workers",
+    "router",
+    "file-based-routing",
+    "api",
+    "effect"
+  ],
+  "type": "module",
+  "bin": {
+    "h3leaf": "./dist/cli.mjs"
+  },
+  "exports": {
+    "./vite": {
+      "types": "./dist/vite.d.mts",
+      "import": "./dist/vite.mjs",
+      "default": "./dist/vite.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "effect": "^3.17.8",
+    "esbuild": "^0.25.10"
+  },
+  "devDependencies": {
+    "@types/node": "^24.19.2",
+    "tsdown": "^0.23.0",
+    "vite": "^7.1.7"
+  },
+  "peerDependencies": {
+    "h3": "^2.0.1-rc.9",
+    "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
 }