@kasperrt/smolter 0.0.0-stage → 0.0.1-rc.2

package/dist/internal/vite/transport.d.ts

@@ -0,0 +1,2 @@
+import type { ViteDevServer } from "vite";
+export declare function configureTransport(server: ViteDevServer, publicId: string): void;

package/dist/internal/vite/transport.js

@@ -0,0 +1,42 @@
+export function configureTransport(server, publicId) {
+    server.middlewares.use((incoming, outgoing, next) => {
+        if (!incoming.url?.startsWith("/_smolter?"))
+            return next();
+        const dispatch = async () => {
+            const origin = `http://${incoming.headers.host}`;
+            const target = new URL(incoming.url, origin).searchParams.get("url");
+            if (!target?.startsWith("/") || target.startsWith("//")) {
+                outgoing.statusCode = 400;
+                outgoing.end("Invalid route URL");
+                return;
+            }
+            const headers = new Headers();
+            for (const [name, value] of Object.entries(incoming.headers)) {
+                if (value)
+                    headers.set(name, Array.isArray(value) ? value.join(", ") : value);
+            }
+            const chunks = [];
+            for await (const chunk of incoming)
+                chunks.push(chunk);
+            const controller = new AbortController();
+            outgoing.once("close", () => controller.abort());
+            const request = new Request(new URL(target, origin), {
+                signal: controller.signal,
+                method: incoming.method,
+                headers,
+                ...(incoming.method !== "GET" && {
+                    body: new Uint8Array(Buffer.concat(chunks)),
+                }),
+            });
+            const [{ default: routes }, { handleRequest }] = await Promise.all([
+                server.ssrLoadModule(publicId),
+                server.ssrLoadModule("@kasperrt/smolter/server"),
+            ]);
+            const response = await handleRequest(routes, request);
+            outgoing.statusCode = response.status;
+            response.headers.forEach((value, name) => outgoing.setHeader(name, value));
+            outgoing.end(new Uint8Array(await response.arrayBuffer()));
+        };
+        void dispatch().catch(next);
+    });
+}

package/dist/preact.d.ts

@@ -0,0 +1,2 @@
+/** Preact entry point. @module */
+export * from "./internal/preact/index.ts";

package/dist/preact.js

@@ -0,0 +1,2 @@
+/** Preact entry point. @module */
+export * from "./internal/preact/index.js";

package/dist/react.d.ts

@@ -0,0 +1,2 @@
+/** React entry point. @module */
+export * from "./internal/react/index.ts";

package/dist/react.js

@@ -0,0 +1,2 @@
+/** React entry point. @module */
+export * from "./internal/react/index.js";

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+/** Server entry point. @module */
+export * from "./internal/server/index.ts";

package/dist/server.js

@@ -0,0 +1,2 @@
+/** Server entry point. @module */
+export * from "./internal/server/index.js";

package/dist/vite.d.ts

@@ -0,0 +1,2 @@
+/** Vite entry point. @module */
+export * from "./internal/vite/index.ts";

package/dist/vite.js

@@ -0,0 +1,2 @@
+/** Vite entry point. @module */
+export * from "./internal/vite/index.js";

package/jsr.json

@@ -0,0 +1,26 @@
+{
+  "name": "@kasperrt/smolter",
+  "version": "0.0.1-rc.2",
+  "exports": {
+    ".": "./src/core.ts",
+    "./preact": "./src/preact.ts",
+    "./core": "./src/core.ts",
+    "./server": "./src/server.ts",
+    "./client": "./src/client.ts",
+    "./files": "./src/files.ts",
+    "./react": "./src/react.ts"
+  },
+  "imports": {
+    "react": "npm:react@19.3.1",
+    "preact/compat": "npm:preact@11.0.1/compat"
+  },
+  "publish": {
+    "include": ["src", "README.md", "LICENSE", "jsr.json"],
+    "exclude": ["src/vite.ts", "src/internal/vite"]
+  },
+  "license": "MIT",
+  "compatibility": {
+    "node": ">=22",
+    "browser": true
+  }
+}

package/package.json

@@ -1,6 +1,96 @@
 {
   "name": "@kasperrt/smolter",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1-rc.2",
+  "description": "A tiny typed data router for React and Preact.",
+  "type": "module",
+  "sideEffects": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kasperrt/smolter.git",
+    "directory": "packages/smolter"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/core.d.ts",
+      "import": "./dist/core.js"
+    },
+    "./preact": {
+      "types": "./dist/preact.d.ts",
+      "import": "./dist/preact.js"
+    },
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "import": "./dist/core.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./files": {
+      "types": "./dist/files.d.ts",
+      "import": "./dist/files.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "import": "./dist/vite.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./package.json": "./package.json",
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE",
+    "jsr.json"
+  ],
+  "scripts": {
+    "build": "node ../../scripts/build.mjs"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "preact": ">=10.25.0",
+    "vite": ">=8"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "preact": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    }
+  },
+  "author": "Kasper Rynning-Tønnesen <kasperrt@users.noreply.github.com> (https://github.com/kasperrt)",
+  "homepage": "https://kasperrt.github.io/smolter/",
+  "bugs": {
+    "url": "https://github.com/kasperrt/smolter/issues"
+  },
+  "keywords": [
+    "router",
+    "react",
+    "preact",
+    "typescript",
+    "loader",
+    "action",
+    "fetcher",
+    "ssr",
+    "file-routing"
+  ],
+  "main": "./dist/core.js",
+  "types": "./dist/core.d.ts",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/src/client.ts

@@ -0,0 +1,2 @@
+/** Client entry point. @module */
+export * from "./internal/client/index.ts";

package/src/core.ts

@@ -0,0 +1,2 @@
+/** Core entry point. @module */
+export * from "./internal/core/index.ts";

package/src/files.ts

@@ -0,0 +1,2 @@
+/** Files entry point. @module */
+export * from "./internal/files/index.ts";

package/src/internal/client/deserialize.ts

@@ -0,0 +1,15 @@
+import type { Snapshot } from "../core/index.ts";
+
+/** Restore a trusted snapshot produced by @kasperrt/smolter/server serialize, including its route error. */
+export function deserialize(json: string): Snapshot {
+  const snapshot: Snapshot = JSON.parse(json);
+  const error = snapshot.error;
+
+  if (error) {
+    snapshot.error = Object.assign(new Error(error.message), {
+      name: error.name,
+    });
+  }
+
+  return snapshot;
+}

package/src/internal/client/index.ts

@@ -0,0 +1,84 @@
+/**
+ * Optional browser transport for server loaders and actions.
+ * @module
+ */
+
+import type {
+  ClientActionArgs,
+  ClientLoaderArgs,
+  DataArgs,
+  Route,
+  RouteModule,
+} from "../core/index.ts";
+
+export type { ClientActionArgs, ClientLoaderArgs } from "../core/index.ts";
+export { deserialize } from "./deserialize.ts";
+
+/** Browser-safe route exports, excluding server implementation code. */
+export interface ClientRouteModule {
+  default?: unknown;
+  HydrateFallback?: unknown;
+  ErrorBoundary?: unknown;
+  clientLoader?(args: ClientLoaderArgs): unknown;
+  clientAction?(args: ClientActionArgs): unknown;
+  shouldRevalidate?: RouteModule["shouldRevalidate"];
+}
+
+/** Select the server loader and action proxies available on a browser route. */
+export interface ServerHandlers {
+  loader?: boolean;
+  action?: boolean;
+}
+
+/** Browser transport for server routes. File-router builds generate this call. */
+export function serverRoute<M extends RouteModule = RouteModule>(
+  path: string,
+  module: ClientRouteModule,
+  handlers: ServerHandlers = { loader: true, action: true },
+): Route<M> {
+  const remote = async ({ request, signal }: DataArgs) => {
+    const url = new URL(request.url);
+    const response = await fetch(
+      `/_smolter?url=${encodeURIComponent(url.pathname + url.search)}`,
+      {
+        method: request.method,
+        signal,
+        ...(request.method !== "GET" && { body: await request.formData() }),
+      },
+    );
+    const location = response.headers.get("X-Smolter-Redirect");
+
+    if (location)
+      return new Response(null, {
+        status: 303,
+        headers: { Location: location },
+      });
+
+    const data = await response.json();
+
+    if (!response.ok) return new Error(data.error ?? "Route request failed");
+
+    return data;
+  };
+
+  return {
+    ...module,
+    path,
+    ...(handlers.loader && { loader: remote }),
+    ...(handlers.action && { action: remote }),
+    ...(module.clientLoader && {
+      clientLoader: (args: DataArgs) =>
+        module.clientLoader!({ ...args, serverLoader: () => remote(args) }),
+    }),
+    ...(module.clientAction && {
+      clientAction: (args: DataArgs) => {
+        const request = args.request.clone();
+
+        return module.clientAction!({
+          ...args,
+          serverAction: () => remote({ ...args, request: request.clone() }),
+        });
+      },
+    }),
+  } as Route<M>;
+}

package/src/internal/core/errors.ts

@@ -0,0 +1,13 @@
+import type { Result } from "./types.ts";
+
+/** Resolve returned or rejected errors into Error values without losing their cause. */
+export function safeWrapAsync<T>(
+  work: () => T | Promise<T>,
+): Promise<Result<T>> {
+  return Promise.resolve()
+    .then(work)
+    .then(
+      (data) => (data instanceof Error ? { error: data } : { data }),
+      (cause: unknown) => ({ error: new Error(String(cause), { cause }) }),
+    );
+}

package/src/internal/core/index.ts

@@ -0,0 +1,7 @@
+/** Framework-independent data routing. @module */
+
+export * from "./errors.ts";
+export * from "./match.ts";
+export * from "./router.ts";
+export * from "./types.ts";
+export * from "./url.ts";

package/src/internal/core/match.ts

@@ -0,0 +1,45 @@
+import type { Match, Params, Route, RouteModule } from "./types.ts";
+
+/** Associate a URL pattern with a module while retaining its inferred handler types. */
+export function defineRoute<const M extends RouteModule>(
+  path: string,
+  module: M,
+): Route<M> {
+  return { ...module, path };
+}
+
+/** Static segments, :params and a terminal * wildcard; first match wins. */
+export function matchRoutes(
+  routes: readonly Route[],
+  pathname: string,
+): Match | undefined {
+  const segments = pathname.replace(/\/$/, "").split("/");
+
+  for (const route of routes) {
+    const parts = route.path.replace(/\/$/, "").split("/");
+    const params: Params = {};
+    const matched =
+      (parts.length === segments.length || parts.at(-1) === "*") &&
+      parts.every((part, index) => {
+        const value = segments[index];
+
+        if (part === "*") {
+          params["*"] = segments.slice(index).join("/");
+
+          return true;
+        }
+
+        if (part[0] === ":" && value) {
+          params[part.slice(1)] = new URLSearchParams(
+            `=${value.replace(/[+&]/g, encodeURIComponent)}`,
+          ).get("")!;
+
+          return true;
+        }
+
+        return part === value;
+      });
+
+    if (matched) return { route, params };
+  }
+}

package/src/internal/core/router.ts

@@ -0,0 +1,251 @@
+import { safeWrapAsync } from "./errors.ts";
+import { matchRoutes } from "./match.ts";
+import type {
+  DataFunction,
+  NavigateOptions,
+  Result,
+  Route,
+  Router,
+  RouterOptions,
+  Snapshot,
+  SubmitOptions,
+} from "./types.ts";
+import { internalURL } from "./url.ts";
+
+type ChannelSnapshot = Partial<Snapshot> & Pick<Snapshot, "state">;
+
+interface OperationOptions extends SubmitOptions, NavigateOptions {
+  hops?: number;
+}
+
+/** Create an isolated router. Use browser: true for browser history, or loadRouter for SSR. */
+export function createRouter(
+  routes: readonly Route[],
+  options: RouterOptions = {},
+): Router {
+  const browser = options.browser && typeof window !== "undefined";
+  let initialized = options.hydrationData?.state === "idle";
+  const initial: Snapshot = {
+    loaded: initialized,
+    ...(options.hydrationData ?? {
+      url: new URL(
+        options.url ?? (browser ? location.href : "/"),
+        "http://localhost",
+      ).href,
+      params: {},
+      state: "idle",
+    }),
+  };
+  const disposers = new Set<() => void>();
+  const channel = <S extends ChannelSnapshot>(initial: S, local = false) => {
+    let snapshot = initial;
+    let controller: AbortController | undefined;
+    const listeners = new Set<() => void>();
+    const dispose = () => {
+      disposers.delete(dispose);
+      controller?.abort();
+      listeners.clear();
+    };
+    const emit = (next: Partial<Snapshot>) => {
+      snapshot = { ...snapshot, ...next };
+
+      for (const listener of listeners) listener();
+    };
+    const run = async (
+      href: string,
+      body?: FormData,
+      operation: OperationOptions = {},
+      // true pushes history; false handles popstate; undefined is a data request.
+      navigation?: boolean,
+    ): Promise<Result> => {
+      controller?.abort();
+
+      controller = new AbortController();
+
+      const { signal } = controller;
+      disposers.add(dispose);
+
+      const previous = snapshot;
+      const url = internalURL(main.getSnapshot().url, href);
+      const match = url && matchRoutes(routes, url.pathname);
+      const commit = () => {
+        if (local || !url) return;
+
+        const changed = snapshot.url !== url.href;
+
+        if (!changed && snapshot.path !== undefined) return;
+
+        if (browser && (navigation || body) && changed)
+          history[operation.replace ? "replaceState" : "pushState"](
+            null,
+            "",
+            url,
+          );
+        const sameRoute = snapshot.path === match?.route.path;
+
+        snapshot = {
+          ...snapshot,
+          url: url.href,
+          path: match?.route.path,
+          params: match?.params ?? {},
+          actionData: undefined,
+          data: sameRoute ? snapshot.data : undefined,
+          loaded: sameRoute && snapshot.loaded,
+        };
+      };
+
+      if (!body) commit();
+      emit({ state: body ? "submitting" : "loading", error: undefined });
+
+      const result = await safeWrapAsync(() => {
+        if (!match) return new Error(url ? "No route" : "External URL");
+
+        if (
+          navigation !== undefined &&
+          !body &&
+          previous.loaded &&
+          !previous.error &&
+          previous.path === match.route.path &&
+          match.route.shouldRevalidate?.({
+            url,
+            currentUrl: new URL(previous.url!),
+            nextUrl: url,
+            defaultShouldRevalidate: true,
+            reason: "navigation",
+          }) === false
+        )
+          return previous.data;
+
+        const fn =
+          match.route[body ? "clientAction" : "clientLoader"] ||
+          match.route[body ? "action" : "loader"];
+
+        if (!fn) return body && new Error("No action");
+
+        return (fn as DataFunction)({
+          request: new Request(url, {
+            signal,
+            method: body && (operation.method ?? "POST"),
+            body,
+          }),
+          params: match.params,
+          signal,
+        });
+      });
+
+      if (signal.aborted) return result;
+
+      const redirectTo =
+        result.data instanceof Response && result.data.headers.get("Location");
+
+      if (redirectTo && (operation.hops ?? 0) < 10) {
+        await main.load(
+          new URL(redirectTo, url!).href,
+          undefined,
+          {
+            replace: true,
+            hops: (operation.hops ?? 0) + 1,
+          },
+          true,
+        );
+
+        if (!signal.aborted) emit({ state: "idle" });
+
+        return result;
+      }
+
+      if (redirectTo) result.error = new Error("Redirect loop");
+
+      if (body && !result.error) commit();
+
+      emit({
+        [body && !local ? "actionData" : "data"]: result.data,
+        error: result.error,
+        loaded: body ? snapshot.loaded : !result.error,
+        state: body && !result.error ? "loading" : "idle",
+      });
+
+      if (body && !result.error) {
+        await router.revalidate("action", {
+          formMethod: operation.method ?? "POST",
+          formAction: url!.href,
+          formData: body,
+          actionResult: result.data,
+        });
+
+        if (!signal.aborted) emit({ state: "idle" });
+      }
+
+      return result;
+    };
+
+    return {
+      getSnapshot: () => snapshot,
+      subscribe(listener: () => void) {
+        listeners.add(listener);
+
+        return () => {
+          listeners.delete(listener);
+        };
+      },
+      load: run,
+      submit: run,
+      dispose,
+    };
+  };
+  const main = channel(initial);
+  let started = 0;
+  const pop = () => {
+    void main.load(location.href, undefined, undefined, false);
+  };
+  const router: Router = {
+    ...main,
+    routes,
+    start() {
+      if (!started++ && browser) addEventListener("popstate", pop);
+
+      if (!initialized) {
+        initialized = true;
+        void main.load(initial.url);
+      }
+
+      return () => {
+        if (!--started && browser) removeEventListener("popstate", pop);
+      };
+    },
+    async navigate(url, operation) {
+      initialized = true;
+      await main.load(url, undefined, operation, true);
+    },
+    async revalidate(reason = "manual", context = {}) {
+      const url = new URL(main.getSnapshot().url);
+
+      if (
+        matchRoutes(routes, url.pathname)?.route.shouldRevalidate?.({
+          ...context,
+          url,
+          currentUrl: url,
+          nextUrl: url,
+          defaultShouldRevalidate: true,
+          reason,
+        }) === false
+      )
+        return;
+      await main.load(url.href);
+    },
+
+    createFetcher() {
+      return channel({ state: "idle" }, true);
+    },
+
+    dispose() {
+      main.dispose();
+
+      for (const dispose of disposers) dispose();
+
+      if (browser) removeEventListener("popstate", pop);
+    },
+  };
+
+  return router;
+}