alabjs 0.1.0

package/src/server/index.ts

@@ -0,0 +1,144 @@
+import type { ServerFn, ServerFnContext } from "../types/index.js";
+import { getCached, setCache, CACHE_MISS } from "./cache.js";
+
+// ─── Cache options ─────────────────────────────────────────────────────────────
+
+export interface ServerFnCacheOptions<Input> {
+  /** How long to keep the result in seconds. Required when `cache` is set. */
+  ttl: number;
+  /**
+   * Tags for group invalidation via `invalidateCache({ tags })`.
+   * Can be a static array or a function that receives the input and returns tags,
+   * allowing per-argument granularity like `post:${input.id}`.
+   */
+  tags?: string[] | ((input: Input) => string[]);
+}
+
+export interface DefineServerFnOptions<Input> {
+  /** Opt-in result caching. Nothing is cached unless this is specified. */
+  cache?: ServerFnCacheOptions<Input>;
+}
+
+// ─── Zod schema detection (duck-typed, no hard Zod dependency) ────────────────
+
+interface ZodLike<T> {
+  safeParse(input: unknown): { success: true; data: T } | { success: false; error: unknown };
+}
+
+function isZodSchema(v: unknown): v is ZodLike<unknown> {
+  return (
+    v !== null &&
+    typeof v === "object" &&
+    "safeParse" in v &&
+    typeof (v as Record<string, unknown>)["safeParse"] === "function"
+  );
+}
+
+// ─── defineServerFn overloads ─────────────────────────────────────────────────
+
+/**
+ * Define a server-only function (no input schema).
+ *
+ * @example
+ * ```ts
+ * export const getPosts = defineServerFn(async () => db.posts.findAll());
+ * ```
+ */
+export function defineServerFn<Input = undefined, Output = unknown>(
+  handler: (ctx: ServerFnContext, input: Input) => Promise<Output>,
+  options?: DefineServerFnOptions<Input>,
+): ServerFn<Input, Output>;
+
+/**
+ * Define a server-only function with **Zod input validation**.
+ *
+ * If validation fails, an HTTP 422 response with the Zod error is returned
+ * automatically — the handler is never called with invalid data.
+ *
+ * The client's `useMutation` / `useServerData` will receive
+ * `{ zodError: ZodError }` instead of throwing an untyped error.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ *
+ * export const createPost = defineServerFn(
+ *   z.object({ title: z.string().min(1), body: z.string() }),
+ *   async ({ params }, input) => db.posts.create(input),
+ *   { cache: { ttl: 0, tags: ["posts"] } },
+ * );
+ * ```
+ */
+export function defineServerFn<Schema extends ZodLike<unknown>, Output = unknown>(
+  schema: Schema,
+  handler: (
+    ctx: ServerFnContext,
+    input: Schema extends ZodLike<infer T> ? T : never,
+  ) => Promise<Output>,
+  options?: DefineServerFnOptions<Schema extends ZodLike<infer T> ? T : never>,
+): ServerFn<Schema extends ZodLike<infer T> ? T : never, Output>;
+
+// ─── Implementation ───────────────────────────────────────────────────────────
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function defineServerFn(...args: any[]): ServerFn<any, any> {
+  const [schemaOrHandler, handlerOrOptions, maybeOptions] = args as [
+    ZodLike<unknown> | ((...a: unknown[]) => Promise<unknown>),
+    ((...a: unknown[]) => Promise<unknown>) | DefineServerFnOptions<unknown> | undefined,
+    DefineServerFnOptions<unknown> | undefined,
+  ];
+  let schema: ZodLike<unknown> | null = null;
+  let handler: (...args: unknown[]) => Promise<unknown>;
+  let options: DefineServerFnOptions<unknown> | undefined;
+
+  if (isZodSchema(schemaOrHandler)) {
+    schema = schemaOrHandler;
+    handler = handlerOrOptions as (...args: unknown[]) => Promise<unknown>;
+    options = maybeOptions;
+  } else {
+    handler = schemaOrHandler as (...args: unknown[]) => Promise<unknown>;
+    options = handlerOrOptions as DefineServerFnOptions<unknown> | undefined;
+  }
+
+  const cacheOpts = options?.cache;
+
+  const wrapped = async (ctx: ServerFnContext, input: unknown): Promise<unknown> => {
+    // ── Zod validation ───────────────────────────────────────────────────────
+    let validatedInput = input;
+    if (schema) {
+      const result = schema.safeParse(input);
+      if (!result.success) {
+        // Throw a structured validation error that the dev/prod server will
+        // serialise as { zodError: ... } with HTTP 422.
+        const err = new Error("[alabjs] Validation failed") as Error & { zodError: unknown };
+        err.zodError = result.error;
+        throw err;
+      }
+      validatedInput = result.data;
+    }
+
+    // ── Cache lookup ─────────────────────────────────────────────────────────
+    if (cacheOpts) {
+      const cacheKey = `${handler.name}:${JSON.stringify(validatedInput)}`;
+      const cached = getCached(cacheKey);
+      if (cached !== CACHE_MISS) return cached;
+
+      const data = await handler(ctx, validatedInput);
+
+      const tags =
+        typeof cacheOpts.tags === "function"
+          ? cacheOpts.tags(validatedInput)
+          : (cacheOpts.tags ?? []);
+      setCache(cacheKey, data, { ttl: cacheOpts.ttl, tags });
+      return data;
+    }
+
+    return handler(ctx, validatedInput);
+  };
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return wrapped as ServerFn<any, any>;
+}
+
+export { defineSSEHandler } from "./sse.js";
+export type { SSEEvent } from "./sse.js";

package/src/server/middleware.test.ts

@@ -0,0 +1,151 @@
+import { describe, it, expect } from "vitest";
+import {
+  matcherToRegex,
+  matchesMiddleware,
+  runMiddleware,
+  redirect,
+  next,
+  type MiddlewareModule,
+} from "./middleware.js";
+
+// ─── matcherToRegex ───────────────────────────────────────────────────────────
+
+describe("matcherToRegex", () => {
+  it("matches exact static path", () => {
+    const re = matcherToRegex("/dashboard");
+    expect(re.test("/dashboard")).toBe(true);
+    expect(re.test("/dashboard/")).toBe(true);
+    expect(re.test("/other")).toBe(false);
+  });
+
+  it("handles :param as single segment", () => {
+    const re = matcherToRegex("/users/:id");
+    expect(re.test("/users/123")).toBe(true);
+    expect(re.test("/users/abc")).toBe(true);
+    expect(re.test("/users/")).toBe(false);
+    expect(re.test("/users/123/extra")).toBe(false);
+  });
+
+  it("handles * as single segment wildcard", () => {
+    const re = matcherToRegex("/api/*");
+    expect(re.test("/api/health")).toBe(true);
+    expect(re.test("/api/users")).toBe(true);
+    expect(re.test("/api/")).toBe(false);
+    expect(re.test("/api/a/b")).toBe(false);
+  });
+
+  it("handles ** as zero-or-more segments", () => {
+    const re = matcherToRegex("/docs/**");
+    expect(re.test("/docs/")).toBe(true);
+    expect(re.test("/docs/intro")).toBe(true);
+    expect(re.test("/docs/guides/auth")).toBe(true);
+  });
+
+  it("handles :param* (Next.js :path* style)", () => {
+    const re = matcherToRegex("/dashboard/:path*");
+    expect(re.test("/dashboard")).toBe(true);
+    expect(re.test("/dashboard/")).toBe(true);
+    expect(re.test("/dashboard/settings")).toBe(true);
+    expect(re.test("/dashboard/users/42")).toBe(true);
+  });
+
+  it("escapes special regex characters in static segments", () => {
+    const re = matcherToRegex("/search.html");
+    expect(re.test("/search.html")).toBe(true);
+    expect(re.test("/searchXhtml")).toBe(false);
+  });
+});
+
+// ─── matchesMiddleware ────────────────────────────────────────────────────────
+
+describe("matchesMiddleware", () => {
+  it("matches all paths when no matchers provided", () => {
+    expect(matchesMiddleware("/anything")).toBe(true);
+    expect(matchesMiddleware("/anything", undefined)).toBe(true);
+    expect(matchesMiddleware("/anything", [])).toBe(true);
+  });
+
+  it("matches when pathname fits a pattern", () => {
+    const matchers = ["/dashboard/:path*", "/api/*"];
+    expect(matchesMiddleware("/dashboard/settings", matchers)).toBe(true);
+    expect(matchesMiddleware("/api/health", matchers)).toBe(true);
+    expect(matchesMiddleware("/login", matchers)).toBe(false);
+  });
+});
+
+// ─── redirect and next helpers ────────────────────────────────────────────────
+
+describe("redirect", () => {
+  it("returns a Response with redirect status", () => {
+    const res = redirect("https://example.com/login");
+    expect(res).toBeInstanceOf(Response);
+    expect(res.status).toBe(307);
+  });
+
+  it("supports custom status codes", () => {
+    const res = redirect("https://example.com/login", 301);
+    expect(res.status).toBe(301);
+  });
+});
+
+describe("next", () => {
+  it("returns null", () => {
+    expect(next()).toBe(null);
+  });
+});
+
+// ─── runMiddleware ────────────────────────────────────────────────────────────
+
+describe("runMiddleware", () => {
+  it("returns null if pathname does not match the matcher", async () => {
+    const mod: MiddlewareModule = {
+      middleware: () => redirect("https://example.com/login"),
+      config: { matcher: ["/dashboard/:path*"] },
+    };
+    const req = new Request("http://localhost/login");
+    const result = await runMiddleware(mod, req);
+    expect(result).toBe(null);
+  });
+
+  it("returns Response when middleware redirects", async () => {
+    const mod: MiddlewareModule = {
+      middleware: () => redirect("https://example.com/login"),
+      config: { matcher: ["/dashboard/:path*"] },
+    };
+    const req = new Request("http://localhost/dashboard/settings");
+    const result = await runMiddleware(mod, req);
+    expect(result).toBeInstanceOf(Response);
+    expect(result!.status).toBe(307);
+  });
+
+  it("returns null when middleware passes through", async () => {
+    const mod: MiddlewareModule = {
+      middleware: () => undefined,
+    };
+    const req = new Request("http://localhost/anything");
+    const result = await runMiddleware(mod, req);
+    expect(result).toBe(null);
+  });
+
+  it("returns null when middleware returns null (via next())", async () => {
+    const mod: MiddlewareModule = {
+      middleware: () => next(),
+    };
+    const req = new Request("http://localhost/anything");
+    const result = await runMiddleware(mod, req);
+    expect(result).toBe(null);
+  });
+
+  it("runs on all paths when no config.matcher is set", async () => {
+    let called = false;
+    const mod: MiddlewareModule = {
+      middleware: () => {
+        called = true;
+        return null;
+      },
+    };
+    const req = new Request("http://localhost/random/path");
+    await runMiddleware(mod, req);
+    expect(called).toBe(true);
+  });
+});

package/src/server/middleware.ts

@@ -0,0 +1,95 @@
+/**
+ * Middleware runner — loads and executes the user's `middleware.ts` file.
+ *
+ * Convention (mirrors Next.js):
+ * ```ts
+ * // middleware.ts (project root)
+ * export async function middleware(req: Request): Promise<Response | void> {
+ *   if (!isAuthed(req)) return Response.redirect(new URL("/login", req.url));
+ *   // return nothing (or return NextResponse.next()) to continue
+ * }
+ *
+ * // Optional — restrict which paths the middleware runs on.
+ * // Patterns support * and ** wildcards (like path-to-regexp lite).
+ * export const config = {
+ *   matcher: ["/dashboard/:path*", "/api/:path*"],
+ * };
+ * ```
+ */
+
+// ─── Public helpers (importable from "alabjs/middleware") ───────────────────────
+
+/** Redirect the request to a new URL (defaults to 307 Temporary Redirect). */
+export function redirect(url: string, status: 301 | 302 | 307 | 308 = 307): Response {
+  return Response.redirect(url, status);
+}
+
+/**
+ * Pass the request through to the next handler (no-op).
+ * Return the result of `next()` from your middleware to signal "continue".
+ */
+export function next(): null {
+  return null;
+}
+
+// ─── Internal types + runner ──────────────────────────────────────────────────
+
+export interface MiddlewareModule {
+  middleware: (req: Request) => Promise<Response | null | void> | Response | null | void;
+  config?: { matcher?: string[] };
+}
+
+/**
+ * Convert a matcher pattern like `/dashboard/:path*` or `/api/*` to a RegExp.
+ *
+ * Supported syntax:
+ * - `:param`   — one path segment (any chars except `/`)
+ * - `*`        — one path segment wildcard
+ * - `**`       — zero or more segments (greedy)
+ * - `:param*`  — zero or more remaining segments (Next.js `:path*` style)
+ */
+export function matcherToRegex(pattern: string): RegExp {
+  // Escape regex special chars except the ones we handle manually
+  const escaped = pattern
+    .replace(/[.+*^${}()|[\]\\]/g, "\\$&")
+    // :param* → zero-or-more segments (greedy, optional slash)
+    .replace(/\/:[a-zA-Z_][a-zA-Z0-9_]*\\\*/g, "(?:/.*)?")
+    .replace(/:[a-zA-Z_][a-zA-Z0-9_]*\\\*/g, "(?:/.*)?")
+    // :param  → single segment
+    .replace(/:[a-zA-Z_][a-zA-Z0-9_]*/g, "[^/]+")
+    // ** → zero-or-more segments (greedy, optional slash)
+    .replace(/\/\*\*\\\*/g, "(?:/.*)?")
+    .replace(/\\\*\\\*/g, ".*")
+    // * → single segment
+    .replace(/\\\*/g, "[^/]+");
+
+  return new RegExp(`^${escaped}\\/?$`);
+}
+
+/**
+ * Test whether a pathname matches any of the given matcher patterns.
+ * If no patterns are provided, the middleware runs on every request.
+ */
+export function matchesMiddleware(pathname: string, matchers?: string[]): boolean {
+  if (!matchers || matchers.length === 0) return true;
+  return matchers.some((pattern) => matcherToRegex(pattern).test(pathname));
+}
+
+/**
+ * Run the user middleware against the current request.
+ * Returns a `Response` if the middleware handled the request (redirect, early
+ * return, etc.) or `null` if it passed through (return nothing / undefined).
+ */
+export async function runMiddleware(
+  mod: MiddlewareModule,
+  req: Request,
+): Promise<Response | null> {
+  const { middleware, config } = mod;
+  const pathname = new URL(req.url).pathname;
+
+  if (!matchesMiddleware(pathname, config?.matcher)) return null;
+
+  const result = await middleware(req);
+  if (result instanceof Response) return result;
+  return null;
+}

package/src/server/revalidate.test.ts

@@ -0,0 +1,106 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { applyRevalidate, checkRevalidateAuth } from "./revalidate.js";
+import { setCachedPage, getCachedPage, setCache, getCached, CACHE_MISS, revalidatePath } from "./cache.js";
+
+// ─── checkRevalidateAuth ──────────────────────────────────────────────────────
+
+describe("checkRevalidateAuth", () => {
+  const savedEnv = process.env["ALAB_REVALIDATE_SECRET"];
+
+  afterEach(() => {
+    if (savedEnv === undefined) delete process.env["ALAB_REVALIDATE_SECRET"];
+    else process.env["ALAB_REVALIDATE_SECRET"] = savedEnv;
+  });
+
+  it("returns true when no secret is configured", () => {
+    delete process.env["ALAB_REVALIDATE_SECRET"];
+    expect(checkRevalidateAuth(undefined)).toBe(true);
+    expect(checkRevalidateAuth(null)).toBe(true);
+    expect(checkRevalidateAuth("Bearer anything")).toBe(true);
+  });
+
+  it("returns true when correct Bearer token is supplied", () => {
+    process.env["ALAB_REVALIDATE_SECRET"] = "my-secret";
+    expect(checkRevalidateAuth("Bearer my-secret")).toBe(true);
+  });
+
+  it("returns false when wrong token is supplied", () => {
+    process.env["ALAB_REVALIDATE_SECRET"] = "my-secret";
+    expect(checkRevalidateAuth("Bearer wrong")).toBe(false);
+  });
+
+  it("returns false when Authorization header is missing", () => {
+    process.env["ALAB_REVALIDATE_SECRET"] = "my-secret";
+    expect(checkRevalidateAuth(undefined)).toBe(false);
+  });
+
+  it("returns false when header is not Bearer scheme", () => {
+    process.env["ALAB_REVALIDATE_SECRET"] = "my-secret";
+    expect(checkRevalidateAuth("Basic my-secret")).toBe(false);
+  });
+});
+
+// ─── applyRevalidate ──────────────────────────────────────────────────────────
+
+describe("applyRevalidate", () => {
+  beforeEach(() => {
+    revalidatePath("/posts");
+    revalidatePath("/posts/1");
+    revalidatePath("/about");
+  });
+
+  it("returns 400 for non-object body", () => {
+    const result = applyRevalidate("not an object");
+    expect("error" in result).toBe(true);
+    if ("error" in result) expect(result.status).toBe(400);
+  });
+
+  it("returns 400 when no fields are provided", () => {
+    const result = applyRevalidate({});
+    expect("error" in result).toBe(true);
+    if ("error" in result) expect(result.status).toBe(400);
+  });
+
+  it("returns 400 when tags is an empty array", () => {
+    const result = applyRevalidate({ tags: [] });
+    expect("error" in result).toBe(true);
+    if ("error" in result) expect(result.status).toBe(400);
+  });
+
+  it("purges a single path and returns it in response", () => {
+    setCachedPage("/posts/1", "<html>post</html>", 60);
+    const result = applyRevalidate({ path: "/posts/1" });
+    expect(result).toEqual({ revalidated: true, path: "/posts/1" });
+    expect(getCachedPage("/posts/1")).toBe(null);
+  });
+
+  it("purges all paths matching a prefix", () => {
+    setCachedPage("/posts", "<html>posts</html>", 60);
+    setCachedPage("/posts/1", "<html>post 1</html>", 60);
+    setCachedPage("/about", "<html>about</html>", 60);
+
+    const result = applyRevalidate({ prefix: "/posts" });
+    expect(result).toEqual({ revalidated: true, prefix: "/posts" });
+    expect(getCachedPage("/posts")).toBe(null);
+    expect(getCachedPage("/posts/1")).toBe(null);
+    expect(getCachedPage("/about")).not.toBe(null);
+  });
+
+  it("purges page HTML and server-fn data cache by tags", () => {
+    setCachedPage("/posts", "<html>posts</html>", 60, ["posts"]);
+    setCache("getPosts:", "data", { ttl: 60, tags: ["posts"] });
+
+    const result = applyRevalidate({ tags: ["posts"] });
+    expect(result).toEqual({ revalidated: true, tags: ["posts"] });
+    expect(getCachedPage("/posts")).toBe(null);
+    expect(getCached("getPosts:")).toBe(CACHE_MISS);
+  });
+
+  it("accepts path, prefix, and tags together", () => {
+    setCachedPage("/posts/1", "<html>post</html>", 60);
+    setCachedPage("/about", "<html>about</html>", 60);
+    const result = applyRevalidate({ path: "/posts/1", tags: ["static"] });
+    expect(result).toMatchObject({ revalidated: true, path: "/posts/1", tags: ["static"] });
+    expect(getCachedPage("/posts/1")).toBe(null);
+  });
+});

package/src/server/revalidate.ts

@@ -0,0 +1,75 @@
+/**
+ * On-demand ISR revalidation handler.
+ *
+ * Exposes `POST /_alabjs/revalidate` so CMS webhooks, deploy scripts, or
+ * API routes can purge the page HTML and/or server-function data cache
+ * without restarting the server.
+ *
+ * Authentication
+ * --------------
+ * Set `ALAB_REVALIDATE_SECRET` in your environment. Every request must then
+ * include `Authorization: Bearer <secret>`. If the env var is not set the
+ * endpoint is open — useful in development, unsafe in production.
+ *
+ * Request body (JSON) — supply one or more fields:
+ * ```json
+ * { "path": "/posts/1" }            // purge a single page
+ * { "prefix": "/posts" }            // purge /posts, /posts/1, /posts/2, …
+ * { "tags": ["posts", "post:1"] }   // purge all entries tagged with any tag
+ * ```
+ *
+ * Response (200):
+ * ```json
+ * { "revalidated": true, "path": "/posts/1" }
+ * ```
+ */
+
+import { revalidatePath, revalidatePathPrefix, revalidateTag } from "./cache.js";
+
+export interface RevalidateBody {
+  /** Purge a single cached page path. */
+  path?: string;
+  /** Purge all cached pages whose path starts with this prefix. */
+  prefix?: string;
+  /** Purge all server-function and page cache entries carrying any of these tags. */
+  tags?: string[];
+}
+
+/** Returns `true` when the request is authorised to call the revalidate endpoint. */
+export function checkRevalidateAuth(authorizationHeader: string | null | undefined): boolean {
+  const secret = process.env["ALAB_REVALIDATE_SECRET"];
+  if (!secret) return true; // no secret configured — open endpoint
+  const provided = authorizationHeader?.startsWith("Bearer ")
+    ? authorizationHeader.slice(7)
+    : null;
+  return provided === secret;
+}
+
+/**
+ * Apply a revalidation request. Returns a result object on success or an
+ * `{ error }` object (with an HTTP status hint) on failure.
+ */
+export function applyRevalidate(
+  body: unknown,
+): { revalidated: true; path?: string; prefix?: string; tags?: string[] } | { status: number; error: string } {
+  if (typeof body !== "object" || body === null) {
+    return { status: 400, error: "Request body must be a JSON object." };
+  }
+
+  const { path, prefix, tags } = body as RevalidateBody;
+
+  if (!path && !prefix && (!tags || tags.length === 0)) {
+    return { status: 400, error: "Provide at least one of: path, prefix, tags." };
+  }
+
+  if (path) revalidatePath(path);
+  if (prefix) revalidatePathPrefix(prefix);
+  if (tags?.length) revalidateTag({ tags });
+
+  return {
+    revalidated: true,
+    ...(path !== undefined && { path }),
+    ...(prefix !== undefined && { prefix }),
+    ...(tags !== undefined && { tags }),
+  };
+}