evolit 0.1.0-alpha.0

package/src/deployment-runtime.js

@@ -0,0 +1,463 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { compileModuleGraph } from "./compiler.js";
+import {
+  collectTransitiveAssetPreloads,
+  collectTransitiveStyleUrls,
+  createAssetResolver,
+  createHydrationBootstrap,
+  createStaticAssetPublicUrlMap,
+  emitBundledClientAssetsWithState,
+  getAssetByPublicUrl,
+  getSharedOutputRoot,
+  normalizeHydrationDataForClient,
+  normalizeClientAssetManifest,
+  resolveSharedVendorModuleUrl,
+  resolveBrowserPackageAssetFilePath,
+  rewriteHydrationDataScript,
+} from "./client-assets.js";
+import { loadEvolitConfig } from "./config.js";
+import { createRouteResolver } from "./render.js";
+import {
+  createCachedRouteResponse,
+  createDefaultRouteCacheKey,
+  isCachedRouteResponseFresh,
+  resolveResponseCacheRuntime,
+} from "./response-cache.js";
+import { createSsrAdapter, renderRouteTreeWithAdapter } from "./ssr-adapter.js";
+const CONTENT_TYPE_BY_EXTENSION = new Map([
+  [".css", "text/css; charset=utf-8"],
+  [".svg", "image/svg+xml"],
+  [".png", "image/png"],
+  [".jpg", "image/jpeg"],
+  [".jpeg", "image/jpeg"],
+  [".gif", "image/gif"],
+  [".webp", "image/webp"],
+  [".avif", "image/avif"],
+  [".ico", "image/x-icon"],
+  [".woff", "font/woff"],
+  [".woff2", "font/woff2"],
+  [".ttf", "font/ttf"],
+  [".otf", "font/otf"],
+  [".map", "application/json; charset=utf-8"],
+  [".mjs", "text/javascript; charset=utf-8"],
+  [".js", "text/javascript; charset=utf-8"],
+]);
+
+function getContentType(filePath) {
+  return CONTENT_TYPE_BY_EXTENSION.get(path.extname(filePath)) ?? "application/octet-stream";
+}
+
+function applyRouteCacheHeaders(response, cachePolicy) {
+  const headers = { ...(response.headers ?? {}) };
+
+  if (cachePolicy?.mode === "static") {
+    headers["cache-control"] = "public, max-age=31536000, immutable";
+  } else if (cachePolicy?.mode === "revalidate") {
+    headers["cache-control"] = `public, max-age=${cachePolicy.ttlSeconds}, stale-while-revalidate=${cachePolicy.ttlSeconds}`;
+  } else {
+    headers["cache-control"] = "no-store";
+  }
+
+  return {
+    ...response,
+    headers,
+  };
+}
+
+export function createPublicAssetOrigin({ projectRoot, mode, assetManifest, getAssetManifest }) {
+  function resolveAssetManifest() {
+    return normalizeClientAssetManifest(
+      typeof getAssetManifest === "function" ? getAssetManifest() : assetManifest,
+    );
+  }
+
+  return {
+    async resolve(pathname) {
+      if (pathname.startsWith("/_evolit/static/")) {
+        const normalizedAssetManifest = resolveAssetManifest();
+        const decodedPathname = decodeURIComponent(pathname);
+        const filePath = getAssetByPublicUrl(normalizedAssetManifest, decodedPathname)?.outputPath
+          ?? getAssetByPublicUrl(normalizedAssetManifest, pathname)?.outputPath
+          ?? null;
+        if (!filePath) {
+          return null;
+        }
+
+        return {
+          filePath,
+          contentType: getContentType(filePath),
+        };
+      }
+
+      if (pathname.startsWith("/_evolit/shared/")) {
+        const sharedRoot = getSharedOutputRoot(projectRoot, mode);
+        const relativePath = decodeURIComponent(pathname.slice("/_evolit/shared/".length));
+        const filePath = path.join(sharedRoot, relativePath);
+        return {
+          filePath,
+          contentType: getContentType(filePath),
+        };
+      }
+
+      if (pathname.startsWith("/_evolit/pkg/")) {
+        const filePath = await resolveBrowserPackageAssetFilePath(pathname);
+        if (!filePath) {
+          return null;
+        }
+        return {
+          filePath,
+          contentType: getContentType(filePath),
+        };
+      }
+
+      return null;
+    },
+    async read(pathname) {
+      const asset = await this.resolve(pathname);
+      if (!asset) {
+        return null;
+      }
+
+      return {
+        status: 200,
+        headers: { "content-type": asset.contentType },
+        body: await fs.readFile(asset.filePath),
+      };
+    },
+  };
+}
+
+export function createResponseCacheController({ responseCacheRuntime }) {
+  return {
+    async getCacheKey(request, routeResult) {
+      return responseCacheRuntime.createKey({
+        request,
+        routeResult,
+      });
+    },
+    createResponse(routeResult, response, cacheState) {
+      const nextResponse = applyRouteCacheHeaders(response, routeResult.cachePolicy);
+      if (!cacheState) {
+        return nextResponse;
+      }
+
+      return {
+        ...nextResponse,
+        headers: {
+          ...nextResponse.headers,
+          "x-evolit-cache": cacheState,
+        },
+      };
+    },
+    async read(request, routeResult) {
+      if (routeResult.type !== "route" || routeResult.cachePolicy.mode === "dynamic") {
+        return null;
+      }
+
+      const cacheKey = await this.getCacheKey(request, routeResult);
+      const cachedResponse = await responseCacheRuntime.store.get(cacheKey);
+      if (!cachedResponse) {
+        return null;
+      }
+
+      const response = this.createResponse(routeResult, {
+        status: cachedResponse.status,
+        headers: { ...cachedResponse.headers },
+        body: cachedResponse.body,
+      }, isCachedRouteResponseFresh(cachedResponse) ? "HIT" : "STALE");
+
+      return {
+        cacheKey,
+        entry: cachedResponse,
+        fresh: isCachedRouteResponseFresh(cachedResponse),
+        response,
+      };
+    },
+    async store(request, routeResult, response, cacheKey) {
+      if (routeResult.type !== "route") {
+        return false;
+      }
+
+      const nextResponse = applyRouteCacheHeaders(response, routeResult.cachePolicy);
+      if (routeResult.cachePolicy.mode !== "dynamic" && nextResponse.status === 200) {
+        const effectiveCacheKey = cacheKey ?? await this.getCacheKey(request, routeResult);
+        await responseCacheRuntime.store.put(
+          effectiveCacheKey,
+          createCachedRouteResponse(nextResponse, routeResult.cachePolicy),
+        );
+        return true;
+      }
+
+      return false;
+    },
+    async write(request, routeResult, response, options = {}) {
+      const didStore = await this.store(
+        request,
+        routeResult,
+        response,
+        options.cacheKey,
+      );
+
+      return this.createResponse(
+        routeResult,
+        response,
+        options.cacheState ?? (didStore ? "MISS" : "SKIP"),
+      );
+    },
+  };
+}
+
+export async function createRequestRenderer({ projectRoot, mode, assetManifest, routeResolver, responseCacheRuntime }) {
+  let currentAssetManifest = normalizeClientAssetManifest(assetManifest);
+  let currentAssetResolver = createAssetResolver(projectRoot, {
+    assetManifest: currentAssetManifest,
+  });
+  let currentHydrationModuleUrl = await resolveSharedVendorModuleUrl(
+    projectRoot,
+    mode,
+    "@litsx/ssr/hydration",
+  );
+  const devBundledEntries = new Set();
+  let devRollupCache = null;
+  const usesFrameworkRouteResolver = !routeResolver;
+  async function createFrameworkRouteResolver() {
+    return createRouteResolver(projectRoot, mode, {
+      getStaticAssetPublicUrls() {
+        return createStaticAssetPublicUrlMap(currentAssetManifest);
+      },
+    });
+  }
+  let effectiveRouteResolver = routeResolver ?? await createFrameworkRouteResolver();
+  const ssrAdapter = createSsrAdapter({
+    assetResolver(moduleId) {
+      return currentAssetResolver(moduleId);
+    },
+    async resolveAdditionalHead({ result }) {
+      const clientImports = Array.isArray(result.clientImports) ? result.clientImports : [];
+      const urls = currentAssetManifest
+        ? collectTransitiveAssetPreloads(clientImports, currentAssetManifest)
+        : [];
+      const styleUrls = currentAssetManifest
+        ? collectTransitiveStyleUrls(clientImports, currentAssetManifest)
+        : [];
+      if (urls.length === 0 && styleUrls.length === 0) {
+        return "";
+      }
+
+      return [
+        ...urls.map((href) => `<link rel="modulepreload" href="${href}">`),
+        ...styleUrls.map((href) => `<link rel="stylesheet" href="${href}">`),
+      ].join("\n");
+    },
+    resolveBootstrap({ result }) {
+      return createHydrationBootstrap({
+        hydrationData: normalizeHydrationDataForClient(result.hydrationData, projectRoot),
+        assetResolver(moduleId) {
+          return currentAssetResolver(moduleId);
+        },
+        hydrationModuleUrl: currentHydrationModuleUrl,
+      });
+    },
+    transformDocument({ result, document }) {
+      return rewriteHydrationDataScript(
+        document,
+        normalizeHydrationDataForClient(result.hydrationData, projectRoot),
+      );
+    },
+  });
+  const responseCacheController = createResponseCacheController({
+    responseCacheRuntime: responseCacheRuntime ?? {
+      store: { get: async () => null, put: async () => {} },
+      createKey: ({ request }) => createDefaultRouteCacheKey(request),
+    },
+  });
+
+  return {
+    get routeResolver() {
+      return effectiveRouteResolver;
+    },
+    responseCacheController,
+    async invalidateDevelopmentState() {
+      if (mode !== "development") {
+        return;
+      }
+
+      currentAssetManifest = null;
+      currentAssetResolver = createAssetResolver(projectRoot, {
+        assetManifest: currentAssetManifest,
+      });
+      devBundledEntries.clear();
+      devRollupCache = null;
+
+      if (usesFrameworkRouteResolver) {
+        effectiveRouteResolver = await createFrameworkRouteResolver();
+      }
+    },
+    async prepareRouteClientArtifacts(routeResult) {
+      if (routeResult.type !== "route" && !routeResult.boundaryModule) {
+        return;
+      }
+
+      const clientModules = [
+        ...(routeResult.type === "route" ? [routeResult.route.page, ...routeResult.route.layouts] : []),
+        ...(routeResult.boundaryModule ? [routeResult.boundaryModule] : []),
+      ];
+
+      for (const clientModule of new Set(clientModules)) {
+        const clientBuild = await compileModuleGraph(clientModule, {
+          projectRoot,
+          mode,
+          sourceMaps: mode === "development",
+          target: "client",
+        });
+        devBundledEntries.add(
+          path.relative(clientBuild.outputRoot, clientBuild.entrypoint).split(path.sep).join("/"),
+        );
+      }
+
+      if (mode === "development") {
+        const bundledClientAssets = await emitBundledClientAssetsWithState(projectRoot, {
+          mode: "development",
+          entryClientModules: devBundledEntries,
+          rollupCache: devRollupCache,
+        });
+        currentAssetManifest = bundledClientAssets.manifest;
+        currentAssetResolver = createAssetResolver(projectRoot, {
+          assetManifest: currentAssetManifest,
+        });
+        currentHydrationModuleUrl = await resolveSharedVendorModuleUrl(
+          projectRoot,
+          mode,
+          "@litsx/ssr/hydration",
+          {
+            assetManifest: currentAssetManifest,
+            entryClientModules: [...devBundledEntries],
+          },
+        ) ?? currentHydrationModuleUrl;
+        devRollupCache = bundledClientAssets.rollupCache;
+      }
+    },
+    async resolveRoutePolicy(request) {
+      return effectiveRouteResolver.resolveRoutePolicy(request);
+    },
+    async renderRoute(request, routePolicyResult = null) {
+      const shouldPrepareBeforeResolve = mode === "development" && !currentAssetManifest;
+      if (shouldPrepareBeforeResolve) {
+        const resolvedRoutePolicyResult = routePolicyResult ?? await effectiveRouteResolver.resolveRoutePolicy(request);
+        await this.prepareRouteClientArtifacts(resolvedRoutePolicyResult);
+      }
+
+      const routeResult = await effectiveRouteResolver.resolveRequest(request);
+      if (!shouldPrepareBeforeResolve || routeResult.boundaryModule) {
+        await this.prepareRouteClientArtifacts(routeResult);
+      }
+      const response = await renderRouteTreeWithAdapter(routeResult, ssrAdapter);
+      return {
+        routeResult,
+        response,
+      };
+    },
+    get assetManifest() {
+      return currentAssetManifest;
+    },
+  };
+}
+
+export async function createDeploymentRuntime({
+  projectRoot,
+  mode,
+  assetManifest,
+  responseCacheRuntime,
+  routeResolver,
+} = {}) {
+  const effectiveResponseCacheRuntime = responseCacheRuntime
+    ?? await resolveResponseCacheRuntime(
+      projectRoot,
+      mode,
+      await loadEvolitConfig(projectRoot),
+    );
+  const runtimeState = {
+    assetManifest: normalizeClientAssetManifest(assetManifest),
+  };
+  const assets = createPublicAssetOrigin({
+    projectRoot,
+    mode,
+    getAssetManifest() {
+      return runtimeState.assetManifest;
+    },
+  });
+  const renderer = await createRequestRenderer({
+    projectRoot,
+    mode,
+    assetManifest: runtimeState.assetManifest,
+    responseCacheRuntime: effectiveResponseCacheRuntime,
+    routeResolver,
+  });
+
+  return {
+    assets,
+    cache: renderer.responseCacheController,
+    renderer,
+    async invalidateDevelopmentState() {
+      if (mode !== "development") {
+        return;
+      }
+
+      await renderer.invalidateDevelopmentState();
+      if (typeof effectiveResponseCacheRuntime.store.clear === "function") {
+        await effectiveResponseCacheRuntime.store.clear();
+      }
+      runtimeState.assetManifest = null;
+    },
+    async handle(request) {
+      const revalidationTasks = this.revalidationTasks ??= new Map();
+      const pathname = new URL(request.url).pathname;
+      const assetResponse = await assets.read(pathname);
+      if (assetResponse) {
+        return assetResponse;
+      }
+
+      const routePolicyResult = await renderer.resolveRoutePolicy(request);
+      const cachedResponse = await renderer.responseCacheController.read(request, routePolicyResult);
+      if (cachedResponse) {
+        if (cachedResponse.fresh) {
+          return cachedResponse.response;
+        }
+
+        if (
+          routePolicyResult.type === "route"
+          && routePolicyResult.cachePolicy.mode === "revalidate"
+          && !revalidationTasks.has(cachedResponse.cacheKey)
+        ) {
+          const revalidationTask = (async () => {
+            const { routeResult, response } = await renderer.renderRoute(request, routePolicyResult);
+            await renderer.responseCacheController.store(
+              request,
+              routeResult,
+              response,
+              cachedResponse.cacheKey,
+            );
+          })()
+            .catch(() => {})
+            .finally(() => {
+              revalidationTasks.delete(cachedResponse.cacheKey);
+            });
+          revalidationTasks.set(cachedResponse.cacheKey, revalidationTask);
+        }
+
+        return cachedResponse.response;
+      }
+
+      const { routeResult, response } = await renderer.renderRoute(request, routePolicyResult);
+      runtimeState.assetManifest = normalizeClientAssetManifest(renderer.assetManifest);
+      return renderer.responseCacheController.write(request, routeResult, response);
+    },
+    async close() {
+      const revalidationTasks = this.revalidationTasks;
+      if (revalidationTasks) {
+        await Promise.all(revalidationTasks.values());
+      }
+    },
+  };
+}

package/src/fs-utils.js

@@ -0,0 +1,71 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export async function pathExists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function ensureDirectory(targetPath) {
+  await fs.mkdir(targetPath, { recursive: true });
+}
+
+export async function readJson(targetPath) {
+  return JSON.parse(await fs.readFile(targetPath, "utf8"));
+}
+
+export async function writeJson(targetPath, value) {
+  await ensureDirectory(path.dirname(targetPath));
+  await fs.writeFile(targetPath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+export async function walkFiles(rootDirectory) {
+  const files = [];
+
+  async function walk(currentDirectory) {
+    const entries = await fs.readdir(currentDirectory, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = path.join(currentDirectory, entry.name);
+      if (entry.isDirectory()) {
+        await walk(fullPath);
+        continue;
+      }
+
+      if (entry.isFile()) {
+        files.push(fullPath);
+      }
+    }
+  }
+
+  if (!(await pathExists(rootDirectory))) {
+    return files;
+  }
+
+  await walk(rootDirectory);
+  return files.sort();
+}
+
+export async function copyDirectory(sourceDirectory, targetDirectory) {
+  await ensureDirectory(targetDirectory);
+  const entries = await fs.readdir(sourceDirectory, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const sourcePath = path.join(sourceDirectory, entry.name);
+    const targetPath = path.join(targetDirectory, entry.name);
+
+    if (entry.isDirectory()) {
+      await copyDirectory(sourcePath, targetPath);
+      continue;
+    }
+
+    if (entry.isFile()) {
+      await ensureDirectory(path.dirname(targetPath));
+      await fs.copyFile(sourcePath, targetPath);
+    }
+  }
+}

package/src/index.js

@@ -0,0 +1,167 @@
+/**
+ * Builds an application into `.evolit/build`, including server output, browser assets, and
+ * platform-neutral deployment manifests.
+ *
+ * @param {string} projectRoot Absolute path to the application root.
+ * @returns {Promise<object>} The build manifest.
+ */
+export { buildProject } from "./build.js";
+
+/**
+ * Creates the request runtime used by standalone Node servers and deployment adapters.
+ * It resolves public assets, cached responses, and render misses through one `handle()` method.
+ *
+ * @param {object} options Runtime configuration, including `projectRoot` and `mode`.
+ * @returns {Promise<object>} A runtime with `handle(request)` and development invalidation hooks.
+ */
+export { createDeploymentRuntime } from "./deployment-runtime.js";
+
+/**
+ * Creates a development HTTP server with file watching and request-time compilation.
+ *
+ * @param {string} projectRoot Absolute path to the application root.
+ * @param {object} [options] Server options, including `port`.
+ * @returns {Promise<object>} A server controller with `listen()` and `close()`.
+ */
+export { createDevServer } from "./server.js";
+
+/**
+ * Creates a production HTTP server from existing `.evolit/build` output.
+ *
+ * @param {string} projectRoot Absolute path to the application root.
+ * @param {object} [options] Server options, including `port`.
+ * @returns {Promise<object>} A server controller with `listen()` and `close()`.
+ */
+export { createStartServer } from "./server.js";
+
+/**
+ * Discovers page routes, layouts, and route boundaries below an application's `app` directory.
+ *
+ * @param {string} projectRoot Absolute path to the application root.
+ * @returns {Promise<Array<object>>} Discovered route definitions.
+ */
+export { discoverAppRoutes } from "./app-discovery.js";
+
+/**
+ * Discovers HTTP route handler modules below an application's `app` directory.
+ *
+ * @param {string} projectRoot Absolute path to the application root.
+ * @returns {Promise<Array<object>>} Discovered handler definitions.
+ */
+export { discoverAppRouteHandlers } from "./app-discovery.js";
+
+/**
+ * Creates a starter Evolit application in an empty directory.
+ *
+ * @param {string} targetDirectory Directory to scaffold.
+ * @param {object} [options] Scaffold options, including `name`.
+ * @returns {Promise<void>}
+ */
+export { scaffoldSite } from "./scaffold.js";
+
+/**
+ * Creates the default LitSX SSR adapter used to turn route results into HTTP responses.
+ *
+ * @param {object} [options] Document metadata and rendering options.
+ * @returns {object} An adapter with `renderRouteTree(routeResult)`.
+ */
+export { createSsrAdapter } from "./ssr-adapter.js";
+
+/**
+ * Renders a resolved route result through an SSR adapter.
+ *
+ * @param {object} routeResult A result returned by the route resolver.
+ * @param {object} [adapter] SSR adapter. Defaults to `createSsrAdapter()`.
+ * @returns {Promise<{ status: number, headers: object, body: string|ReadableStream }>} HTTP response data.
+ */
+export { renderRouteTreeWithAdapter } from "./ssr-adapter.js";
+
+/**
+ * Reads request cookies and exposes mutations for the outgoing response.
+ * Only available while rendering a route or executing a route handler.
+ *
+ * @returns {object} A cookie store with `get`, `getAll`, `has`, `set`, and `delete`.
+ */
+export { cookies } from "./request-context.js";
+
+/**
+ * Returns the incoming request headers. Reading headers makes the current route dynamic.
+ *
+ * @returns {Headers} The incoming request headers.
+ */
+export { headers } from "./request-context.js";
+
+/**
+ * Signals a 404 response and renders the nearest `not-found.litsx` boundary when available.
+ *
+ * @returns {never}
+ */
+export { notFound } from "./request-context.js";
+
+/**
+ * Signals a permanent redirect with HTTP status 308.
+ *
+ * @param {string} location Redirect destination.
+ * @returns {never}
+ */
+export { permanentRedirect } from "./request-context.js";
+
+/**
+ * Signals a redirect response. The default status is 307.
+ *
+ * @param {string} location Redirect destination.
+ * @param {number} [status=307] Redirect HTTP status.
+ * @returns {never}
+ */
+export { redirect } from "./request-context.js";
+
+/**
+ * Returns the incoming request URL. Reading it makes the current route dynamic.
+ *
+ * @returns {URL} The incoming request URL.
+ */
+export { requestUrl } from "./request-context.js";
+
+/**
+ * Returns mutable response headers for the current route response.
+ *
+ * @returns {Headers} Headers merged into the outgoing response.
+ */
+export { responseHeaders } from "./request-context.js";
+
+/**
+ * In-memory response cache store, intended for development and tests.
+ */
+export { MemoryResponseCacheStore } from "./response-cache.js";
+
+/**
+ * Filesystem-backed response cache store used by the standalone production runtime.
+ *
+ * @param {string} rootDirectory Directory where cache records are stored.
+ */
+export { FileSystemResponseCacheStore } from "./response-cache.js";
+
+/**
+ * Response cache store backed by caller-provided object-storage operations.
+ *
+ * @param {object} options Object storage callbacks and an optional key prefix.
+ */
+export { ObjectStorageResponseCacheStore } from "./response-cache.js";
+
+/**
+ * Creates the default cache key from a request pathname and search string.
+ *
+ * @param {Request} request Incoming request.
+ * @returns {string} Cache key.
+ */
+export { createDefaultRouteCacheKey } from "./response-cache.js";
+
+/**
+ * Resolves the response cache store and cache-key factory from `evolit.config.js`.
+ *
+ * @param {string} projectRoot Absolute path to the application root.
+ * @param {"development"|"production"} mode Runtime mode.
+ * @param {object} [evolitConfig] Loaded framework configuration.
+ * @returns {Promise<{ store: object, createKey: Function }>} Cache runtime hooks.
+ */
+export { resolveResponseCacheRuntime } from "./response-cache.js";