evolit 0.1.0-alpha.0

package/src/request-context.js

@@ -0,0 +1,230 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+const REQUEST_CONTEXT_STORAGE = Symbol.for("evolit.request-context.storage");
+const HTTP_SIGNAL_CLASS = Symbol.for("evolit.request-context.http-signal");
+
+const requestContextStorage = globalThis[REQUEST_CONTEXT_STORAGE] ??= new AsyncLocalStorage();
+const EvolitHttpSignal = globalThis[HTTP_SIGNAL_CLASS] ??= class EvolitHttpSignal extends Error {
+  constructor(type, options = {}) {
+    super(type);
+    this.type = type;
+    this.status = options.status;
+    this.location = options.location;
+  }
+};
+
+function getActiveContext() {
+  const context = requestContextStorage.getStore();
+  if (!context) {
+    throw new Error("Request APIs can only be called while rendering a evolit route.");
+  }
+
+  return context;
+}
+
+function parseCookieHeader(value) {
+  const values = new Map();
+  if (typeof value !== "string" || value.length === 0) {
+    return values;
+  }
+
+  for (const entry of value.split(";")) {
+    const separator = entry.indexOf("=");
+    if (separator === -1) {
+      continue;
+    }
+
+    const name = entry.slice(0, separator).trim();
+    if (!name) {
+      continue;
+    }
+
+    values.set(name, decodeURIComponent(entry.slice(separator + 1).trim()));
+  }
+
+  return values;
+}
+
+function serializeCookie(name, value, options = {}) {
+  const attributes = [`${name}=${encodeURIComponent(value)}`];
+  if (options.maxAge != null) attributes.push(`Max-Age=${Math.floor(options.maxAge)}`);
+  if (options.domain) attributes.push(`Domain=${options.domain}`);
+  attributes.push(`Path=${options.path ?? "/"}`);
+  if (options.expires) attributes.push(`Expires=${new Date(options.expires).toUTCString()}`);
+  if (options.httpOnly) attributes.push("HttpOnly");
+  if (options.secure) attributes.push("Secure");
+  if (options.sameSite) attributes.push(`SameSite=${options.sameSite}`);
+  return attributes.join("; ");
+}
+
+function createCookieStore(context) {
+  const requestCookies = parseCookieHeader(context.request.headers.get("cookie"));
+
+  return Object.freeze({
+    get(name) {
+      const value = requestCookies.get(name);
+      return value == null ? undefined : { name, value };
+    },
+    getAll(name) {
+      if (name) {
+        const cookie = this.get(name);
+        return cookie ? [cookie] : [];
+      }
+
+      return [...requestCookies.entries()].map(([cookieName, value]) => ({ name: cookieName, value }));
+    },
+    has(name) {
+      return requestCookies.has(name);
+    },
+    set(name, value, options = {}) {
+      context.responseCookies.push(serializeCookie(name, String(value), options));
+      requestCookies.set(name, String(value));
+      context.didUseDynamicRequestData = true;
+    },
+    delete(name, options = {}) {
+      context.responseCookies.push(serializeCookie(name, "", { ...options, maxAge: 0 }));
+      requestCookies.delete(name);
+      context.didUseDynamicRequestData = true;
+    },
+  });
+}
+
+function createRouteRequest(context) {
+  return new Proxy(context.request, {
+    get(target, property) {
+      if (property !== "constructor" && property !== Symbol.toStringTag) {
+        context.didUseDynamicRequestData = true;
+      }
+
+      const value = Reflect.get(target, property, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  });
+}
+
+export function createRequestContext({ request, params = {}, searchParams = {} }) {
+  const context = {
+    request,
+    params: Object.freeze({ ...params }),
+    searchParams: Object.freeze({ ...searchParams }),
+    responseHeaders: new Headers(),
+    responseCookies: [],
+    didUseDynamicRequestData: false,
+  };
+  context.cookieStore = createCookieStore(context);
+  context.routeRequest = createRouteRequest(context);
+  return context;
+}
+
+export function runWithRequestContext(context, callback) {
+  return requestContextStorage.run(context, callback);
+}
+
+/**
+ * Returns the incoming request headers and marks the current route dynamic.
+ *
+ * @returns {Headers} The incoming request headers.
+ */
+export function headers() {
+  const context = getActiveContext();
+  context.didUseDynamicRequestData = true;
+  return context.request.headers;
+}
+
+/**
+ * Returns the request cookie store and marks the current route dynamic.
+ * Mutations are merged into the outgoing response.
+ *
+ * @returns {object} A cookie store with `get`, `getAll`, `has`, `set`, and `delete`.
+ */
+export function cookies() {
+  const context = getActiveContext();
+  context.didUseDynamicRequestData = true;
+  return context.cookieStore;
+}
+
+/**
+ * Returns the incoming request URL and marks the current route dynamic.
+ *
+ * @returns {URL} The request URL.
+ */
+export function requestUrl() {
+  const context = getActiveContext();
+  context.didUseDynamicRequestData = true;
+  return new URL(context.request.url);
+}
+
+/**
+ * Returns mutable headers merged into the response after route rendering.
+ *
+ * @returns {Headers} Response headers.
+ */
+export function responseHeaders() {
+  return getActiveContext().responseHeaders;
+}
+
+/**
+ * Stops route execution and responds with a redirect.
+ *
+ * @param {string} location Redirect destination.
+ * @param {number} [status=307] Redirect HTTP status.
+ * @returns {never}
+ */
+export function redirect(location, status = 307) {
+  throw new EvolitHttpSignal("redirect", { location: String(location), status });
+}
+
+/**
+ * Stops route execution and responds with a permanent HTTP 308 redirect.
+ *
+ * @param {string} location Redirect destination.
+ * @returns {never}
+ */
+export function permanentRedirect(location) {
+  redirect(location, 308);
+}
+
+/**
+ * Stops route execution with a 404 signal for the nearest `not-found.litsx` boundary.
+ *
+ * @returns {never}
+ */
+export function notFound() {
+  throw new EvolitHttpSignal("not-found", { status: 404 });
+}
+
+export function isEvolitHttpSignal(error) {
+  return error instanceof EvolitHttpSignal;
+}
+
+export function getRequestContextResponse(context) {
+  const headers = Object.fromEntries(context.responseHeaders.entries());
+  if (context.responseCookies.length > 0) {
+    headers["set-cookie"] = context.responseCookies;
+  }
+
+  return {
+    headers,
+    didUseDynamicRequestData: context.didUseDynamicRequestData,
+  };
+}
+
+export function applyRequestContextToResponse(response, context) {
+  if (!(response instanceof Response)) {
+    throw new Error("Expected a route handler to return a Web Response.");
+  }
+
+  const headers = new Headers(response.headers);
+  for (const [name, value] of context.responseHeaders.entries()) {
+    headers.set(name, value);
+  }
+  for (const cookie of context.responseCookies) {
+    headers.append("set-cookie", cookie);
+  }
+
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}

package/src/response-cache.js

@@ -0,0 +1,214 @@
+import fs from "node:fs/promises";
+import crypto from "node:crypto";
+import path from "node:path";
+import { BUILD_DIRECTORY, INTERNAL_DIRECTORY, ROUTE_CACHE_DIRECTORY } from "./constants.js";
+import { ensureDirectory, pathExists, readJson, writeJson } from "./fs-utils.js";
+
+function createCacheFileName(cacheKey) {
+  return `${crypto.createHash("sha1").update(cacheKey).digest("hex")}.json`;
+}
+
+function createCacheObjectKey(cacheKey, prefix = "") {
+  const normalizedPrefix = typeof prefix === "string" ? prefix.replace(/\/+$/g, "") : "";
+  const fileName = createCacheFileName(cacheKey);
+  return normalizedPrefix ? `${normalizedPrefix}/${fileName}` : fileName;
+}
+
+export function createCachedRouteResponse(response, cachePolicy, now = new Date()) {
+  const ttlSeconds = cachePolicy?.mode === "revalidate" ? cachePolicy.ttlSeconds : null;
+  const createdAt = now.toISOString();
+  const expiresAt = ttlSeconds == null
+    ? null
+    : new Date(now.getTime() + (ttlSeconds * 1000)).toISOString();
+
+  return {
+    status: response.status,
+    headers: { ...(response.headers ?? {}) },
+    body: String(response.body ?? ""),
+    createdAt,
+    expiresAt,
+  };
+}
+
+export function isCachedRouteResponseFresh(entry, now = new Date()) {
+  if (!entry || typeof entry !== "object") {
+    return false;
+  }
+
+  if (!entry.expiresAt) {
+    return true;
+  }
+
+  return new Date(entry.expiresAt).getTime() > now.getTime();
+}
+
+export class MemoryResponseCacheStore {
+  #entries = new Map();
+
+  async get(cacheKey) {
+    return this.#entries.get(cacheKey) ?? null;
+  }
+
+  async put(cacheKey, entry) {
+    this.#entries.set(cacheKey, entry);
+  }
+
+  async delete(cacheKey) {
+    this.#entries.delete(cacheKey);
+  }
+
+  async clear() {
+    this.#entries.clear();
+  }
+}
+
+export class FileSystemResponseCacheStore {
+  #rootDirectory;
+
+  constructor(rootDirectory) {
+    this.#rootDirectory = rootDirectory;
+  }
+
+  getRootDirectory() {
+    return this.#rootDirectory;
+  }
+
+  getFilePath(cacheKey) {
+    return path.join(this.#rootDirectory, createCacheFileName(cacheKey));
+  }
+
+  async get(cacheKey) {
+    const filePath = this.getFilePath(cacheKey);
+    if (!(await pathExists(filePath))) {
+      return null;
+    }
+
+    const entry = await readJson(filePath);
+    return entry?.key === cacheKey ? entry.value ?? null : null;
+  }
+
+  async put(cacheKey, entry) {
+    const filePath = this.getFilePath(cacheKey);
+    await ensureDirectory(path.dirname(filePath));
+    await writeJson(filePath, {
+      key: cacheKey,
+      value: entry,
+    });
+  }
+
+  async delete(cacheKey) {
+    const filePath = this.getFilePath(cacheKey);
+    if (await pathExists(filePath)) {
+      await fs.unlink(filePath);
+    }
+  }
+}
+
+export class ObjectStorageResponseCacheStore {
+  #prefix;
+  #getObject;
+  #putObject;
+  #deleteObject;
+
+  constructor(options = {}) {
+    this.#prefix = options.prefix ?? "";
+    this.#getObject = options.getObject;
+    this.#putObject = options.putObject;
+    this.#deleteObject = options.deleteObject ?? null;
+
+    if (typeof this.#getObject !== "function") {
+      throw new Error("Expected ObjectStorageResponseCacheStore options.getObject to be a function.");
+    }
+
+    if (typeof this.#putObject !== "function") {
+      throw new Error("Expected ObjectStorageResponseCacheStore options.putObject to be a function.");
+    }
+  }
+
+  getObjectKey(cacheKey) {
+    return createCacheObjectKey(cacheKey, this.#prefix);
+  }
+
+  async get(cacheKey) {
+    const serializedEntry = await this.#getObject(this.getObjectKey(cacheKey));
+    if (typeof serializedEntry !== "string" || serializedEntry.length === 0) {
+      return null;
+    }
+
+    const entry = JSON.parse(serializedEntry);
+    return entry?.key === cacheKey ? entry.value ?? null : null;
+  }
+
+  async put(cacheKey, entry) {
+    await this.#putObject(
+      this.getObjectKey(cacheKey),
+      `${JSON.stringify({
+        key: cacheKey,
+        value: entry,
+      }, null, 2)}\n`,
+    );
+  }
+
+  async delete(cacheKey) {
+    if (typeof this.#deleteObject !== "function") {
+      return;
+    }
+
+    await this.#deleteObject(this.getObjectKey(cacheKey));
+  }
+}
+
+export function createDefaultRouteCacheKey(request) {
+  const url = new URL(request.url);
+  return `${url.pathname}${url.search}`;
+}
+
+export function getRouteCacheArtifactFileName(cacheKey) {
+  return createCacheFileName(cacheKey);
+}
+
+export function createDefaultResponseCacheStore(projectRoot, mode) {
+  if (mode === "development") {
+    return new MemoryResponseCacheStore();
+  }
+
+  return new FileSystemResponseCacheStore(
+    path.join(projectRoot, INTERNAL_DIRECTORY, BUILD_DIRECTORY, ROUTE_CACHE_DIRECTORY),
+  );
+}
+
+function isResponseCacheStore(value) {
+  return (
+    value != null &&
+    typeof value === "object" &&
+    typeof value.get === "function" &&
+    typeof value.put === "function"
+  );
+}
+
+export async function resolveResponseCacheRuntime(projectRoot, mode, evolitConfig = {}) {
+  const defaultStore = createDefaultResponseCacheStore(projectRoot, mode);
+  const responseCacheConfig = evolitConfig?.responseCache ?? {};
+
+  let store = defaultStore;
+  if (typeof responseCacheConfig?.createStore === "function") {
+    store = await responseCacheConfig.createStore({
+      projectRoot,
+      mode,
+      defaultStore,
+    });
+  }
+
+  if (!isResponseCacheStore(store)) {
+    throw new Error("Expected responseCache.createStore() to return an object with get() and put() methods.");
+  }
+
+  const createKey = typeof responseCacheConfig?.createKey === "function"
+    ? responseCacheConfig.createKey
+    : ({ request }) => createDefaultRouteCacheKey(request);
+
+  return {
+    store,
+    createKey,
+  };
+}

package/src/route-config.js

@@ -0,0 +1,60 @@
+function normalizeRevalidatePolicy(cacheConfig) {
+  if (!cacheConfig || typeof cacheConfig !== "object" || Array.isArray(cacheConfig)) {
+    throw new Error("Expected routeConfig.cache to be an object when using revalidate mode.");
+  }
+
+  const ttlSeconds = cacheConfig.revalidate;
+  if (!Number.isInteger(ttlSeconds) || ttlSeconds <= 0) {
+    throw new Error("Expected routeConfig.cache.revalidate to be a positive integer.");
+  }
+
+  return {
+    mode: "revalidate",
+    ttlSeconds,
+  };
+}
+
+export function normalizeRouteCachePolicy(routeConfig = {}) {
+  const cacheConfig = routeConfig?.cache ?? "dynamic";
+
+  if (cacheConfig === "dynamic") {
+    return { mode: "dynamic" };
+  }
+
+  if (cacheConfig === "static") {
+    return { mode: "static" };
+  }
+
+  return normalizeRevalidatePolicy(cacheConfig);
+}
+
+export function mergeRouteConfig(modules) {
+  return modules.reduce((config, moduleRecord) => {
+    if (!moduleRecord || moduleRecord.routeConfig == null) {
+      return config;
+    }
+
+    if (typeof moduleRecord.routeConfig !== "object" || Array.isArray(moduleRecord.routeConfig)) {
+      throw new Error("Expected routeConfig to export an object.");
+    }
+
+    return {
+      ...config,
+      ...moduleRecord.routeConfig,
+    };
+  }, {});
+}
+
+export function serializeRouteCachePolicy(cachePolicy) {
+  if (!cachePolicy || cachePolicy.mode === "dynamic") {
+    return "dynamic";
+  }
+
+  if (cachePolicy.mode === "static") {
+    return "static";
+  }
+
+  return {
+    revalidate: cachePolicy.ttlSeconds,
+  };
+}

package/src/scaffold.js

@@ -0,0 +1,107 @@
+import fs from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { copyDirectory, ensureDirectory, pathExists, writeJson } from "./fs-utils.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+const { version: frameworkVersion } = require("../package.json");
+const TEMPLATE_ROOT = path.resolve(__dirname, "../templates/default");
+
+async function writeSitePackageJson(targetDirectory, siteName) {
+  const packageJsonPath = path.join(targetDirectory, "package.json");
+  const packageJson = {
+    name: siteName,
+    version: "0.1.0",
+    private: true,
+    type: "module",
+    scripts: {
+      dev: "evolit dev",
+      build: "evolit build",
+      start: "evolit start",
+      typecheck: "litsx-tsc -p jsconfig.json --noEmit",
+    },
+    dependencies: {
+      "@litsx/core": "0.17.0-canary-feat-ssr-20260726130435",
+      evolit: frameworkVersion,
+    },
+    devDependencies: {
+      "@litsx/typescript": "^0.9.0",
+      "typescript": "^6.0.0",
+    },
+  };
+
+  await writeJson(packageJsonPath, packageJson);
+}
+
+export async function scaffoldSite(targetDirectory, options = {}) {
+  const absoluteTargetDirectory = path.resolve(targetDirectory);
+  const siteName = options.name ?? path.basename(absoluteTargetDirectory);
+
+  if (await pathExists(absoluteTargetDirectory)) {
+    const entries = await fs.readdir(absoluteTargetDirectory);
+    if (entries.length > 0) {
+      throw new Error(`Target directory is not empty: ${absoluteTargetDirectory}`);
+    }
+  } else {
+    await ensureDirectory(absoluteTargetDirectory);
+  }
+
+  await copyDirectory(TEMPLATE_ROOT, absoluteTargetDirectory);
+  await writeSitePackageJson(absoluteTargetDirectory, siteName);
+  await fs.writeFile(
+    path.join(absoluteTargetDirectory, "evolit.config.js"),
+    [
+      "export default {",
+      "  // Reserved for framework configuration.",
+      "  // Response cache adapters and deployment-specific runtime hooks can live here.",
+      "  // Example for object storage adapters such as S3:",
+      "  // import { ObjectStorageResponseCacheStore } from \"evolit\";",
+      "  // import {",
+      "  //   DeleteObjectCommand,",
+      "  //   GetObjectCommand,",
+      "  //   PutObjectCommand,",
+      "  //   S3Client,",
+      "  // } from \"@aws-sdk/client-s3\";",
+      "  //",
+      "  // const s3 = new S3Client({ region: process.env.AWS_REGION });",
+      "  // const bucket = process.env.EVOLIT_CACHE_BUCKET;",
+      "  // responseCache: {",
+      "  //   async createStore() {",
+      "  //     return new ObjectStorageResponseCacheStore({",
+      "  //       prefix: \"routes\",",
+      "  //       async getObject(key) {",
+      "  //         try {",
+      "  //           const result = await s3.send(new GetObjectCommand({ Bucket: bucket, Key: key }));",
+      "  //           return await result.Body.transformToString();",
+      "  //         } catch (error) {",
+      "  //           if (error?.name === \"NoSuchKey\") return null;",
+      "  //           throw error;",
+      "  //         }",
+      "  //       },",
+      "  //       async putObject(key, value) {",
+      "  //         await s3.send(new PutObjectCommand({",
+      "  //           Bucket: bucket,",
+      "  //           Key: key,",
+      "  //           Body: value,",
+      "  //           ContentType: \"application/json; charset=utf-8\",",
+      "  //         }));",
+      "  //       },",
+      "  //       async deleteObject(key) {",
+      "  //         await s3.send(new DeleteObjectCommand({ Bucket: bucket, Key: key }));",
+      "  //       },",
+      "  //     });",
+      "  //   },",
+      "  //   createKey({ request }) {",
+      "  //     return new URL(request.url).pathname;",
+      "  //   },",
+      "  // },",
+      "};",
+      "",
+    ].join("\n"),
+    "utf8",
+  );
+
+  return absoluteTargetDirectory;
+}

package/src/server-api.js

@@ -0,0 +1,51 @@
+/**
+ * Reads request cookies and exposes mutations for the outgoing response.
+ *
+ * @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";