@zerotal/core 1.0.0

package/src/helpers/response.ts

@@ -0,0 +1,411 @@
+/**
+ * Global response helpers usable from controller handlers — `redirect()`,
+ * `back()`, `json()`, `view()`, `html()`, `markdown()`, `file()`, and `abort()`
+ * — plus the fluent `ResponseBuilder` / `MarkdownBuilder` they return.
+ */
+import { RequestContext } from "../context/RequestContext.ts";
+import { HttpError, NotFoundError } from "../errors/HttpError.ts";
+import { route } from "../router/Router.ts";
+import { safeRedirectPath } from "../pipeline/HttpContext.ts";
+import { DEFAULT_MD_OPTIONS, type BunMarkdownOptions } from "../helpers/markdown.ts";
+import type { ZerotalError } from "../errors/ZerotalError.ts";
+import type { HttpContext } from "../pipeline/HttpContext.ts";
+
+/** Markup a view renders to — a string or anything stringifiable (e.g. JSX `SafeHtml`). */
+type ViewMarkup = string | { toString(): string };
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- supertype of every view component the public overloads accept.
+type AnyViewComponent = (ctx: HttpContext<any>, props: any) => ViewMarkup | Promise<ViewMarkup>;
+
+function _ctx(): HttpContext {
+  const ctx = RequestContext.tryGet();
+  if (!ctx) {
+    throw new Error(
+      "[Zerotal] Response helpers (back, redirect, json, etc.) must be called inside an active HTTP request.",
+    );
+  }
+  return ctx;
+}
+
+// ── ResponseBuilder ────────────────────────────────────────────────────────
+
+/**
+ * Fluent builder returned by the redirect helpers for attaching flash data
+ * (`.withErrors()`, `.withSuccess()`, …) to the response.
+ *
+ * It implements `PromiseLike<void>` so that `return back().withErrors(...)`
+ * compiles cleanly in handlers typed as `async (ctx): Promise<void>`: TypeScript
+ * unwraps `PromiseLike<void>` in async context, making the builder void-compatible.
+ */
+export class ResponseBuilder implements PromiseLike<void> {
+  readonly #ctx: HttpContext;
+
+  constructor(ctx: HttpContext) {
+    this.#ctx = ctx;
+  }
+
+  /** Flash an arbitrary key/value onto the next request's session. */
+  with(key: string, value: unknown): this {
+    this.#ctx.flash(key, value);
+    return this;
+  }
+
+  /** Flash a map of field errors under the `errors` key. */
+  withErrors(errors: Record<string, string>): this {
+    return this.with("errors", errors);
+  }
+
+  /** Flash a success message under the `success` key. */
+  withSuccess(message: string): this {
+    return this.with("success", message);
+  }
+
+  /** Flash an error message under the `error` key. */
+  withError(message: string): this {
+    return this.with("error", message);
+  }
+
+  /** Flash a warning message under the `warning` key. */
+  withWarning(message: string): this {
+    return this.with("warning", message);
+  }
+
+  /** Flash an info message under the `info` key. */
+  withInfo(message: string): this {
+    return this.with("info", message);
+  }
+
+  then<TResult1 = void, TResult2 = never>(
+    onfulfilled?: ((value: void) => TResult1 | PromiseLike<TResult1>) | null,
+    onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null,
+  ): PromiseLike<TResult1 | TResult2> {
+    return Promise.resolve<void>(undefined).then(onfulfilled, onrejected);
+  }
+}
+
+// ── RedirectBuilder ─────────────────────────────────────────────────────────
+
+/**
+ * Returned by the no-argument `redirect()` form to pick a destination fluently. Each method
+ * sets the redirect target and returns a {@link ResponseBuilder} so flash data can be chained:
+ *
+ * @example
+ * redirect("/login", 302).withError("Please log in to continue.");
+ * redirect().back().withErrors({ email: "Invalid email or password." });
+ * redirect().intended("/").withInfo("Please log in to continue.");
+ * redirect().to("profile", { username: "alice" }).withSuccess("Profile updated.");
+ */
+export class RedirectBuilder {
+  readonly #ctx: HttpContext;
+
+  constructor(ctx: HttpContext) {
+    this.#ctx = ctx;
+  }
+
+  /** Redirect to an absolute or relative URL. */
+  away(url: string, status: 301 | 302 | 303 | 307 | 308 = 302): ResponseBuilder {
+    this.#ctx.redirect(url, status);
+    return new ResponseBuilder(this.#ctx);
+  }
+
+  /** Redirect to a named route, resolving its URL from the route name and params. */
+  to(
+    name: string,
+    params: Record<string, string | number> = {},
+    status: 301 | 302 | 303 | 307 | 308 = 302,
+  ): ResponseBuilder {
+    this.#ctx.redirect(route(name, params), status);
+    return new ResponseBuilder(this.#ctx);
+  }
+
+  /** Redirect to the previous URL (the `Referer`). */
+  back(status: 301 | 302 | 303 | 307 | 308 = 302): ResponseBuilder {
+    this.#ctx.back(status);
+    return new ResponseBuilder(this.#ctx);
+  }
+
+  /**
+   * Redirect to the URL stored in session under `intended_url` (set by RequireAuth when
+   * intercepting an unauthenticated request), then clear it. Falls back to `fallback` when
+   * none is stored, or when the stored URL is cross-origin (open-redirect guard).
+   */
+  intended(fallback = "/", status: 301 | 302 | 303 | 307 | 308 = 302): ResponseBuilder {
+    const session = (
+      this.#ctx as unknown as {
+        session?: { get<T>(k: string): T | undefined; forget(k: string): void };
+      }
+    ).session;
+    const stored = session?.get<string>("intended_url");
+    if (stored) session?.forget("intended_url");
+    this.#ctx.redirect(safeRedirectPath(stored, this.#ctx.url.origin) ?? fallback, status);
+    return new ResponseBuilder(this.#ctx);
+  }
+}
+
+/**
+ * Return type for controller handler methods.
+ *
+ * `void` covers the direct helpers (`json()`, `view()`, `ctx.json()`, etc.).
+ * `ResponseBuilder` covers fluent redirect helpers (`back()`, `redirect()`, etc.)
+ * `MarkdownBuilder` covers `markdown().withLayout(...)` chains.
+ * Both builder types implement `PromiseLike<void>` so they are valid in
+ * `async (): Promise<void>` handlers.
+ *
+ * @example
+ * async store(ctx: HttpContext): Promise<ControllerResponse> {
+ *   return back().withErrors({ title: 'Required' });
+ * }
+ */
+export type ControllerResponse = void | ResponseBuilder | MarkdownBuilder;
+
+// ── MarkdownBuilder ────────────────────────────────────────────────────────
+
+/**
+ * Builder returned by `markdown()` that enables optional layout chaining, e.g.
+ * `return markdown(content, { title }).withLayout(Layout, { title })`.
+ *
+ * Calling `.withLayout()` re-renders the markdown inside the provided layout
+ * function, overwriting the plain markdown response already set by `markdown()`.
+ * Implements `PromiseLike<void>` following the same pattern as `ResponseBuilder`.
+ */
+export class MarkdownBuilder implements PromiseLike<void> {
+  readonly #content: string;
+  readonly #options: BunMarkdownOptions & { title?: string };
+  readonly #status: number;
+
+  constructor(content: string, options?: BunMarkdownOptions & { title?: string }, status = 200) {
+    this.#content = content;
+    this.#options = options ?? {};
+    this.#status = status;
+  }
+
+  /**
+   * Re-render the markdown content inside a custom layout function.
+   *
+   * `layoutFn` receives `{ ...props, content: <rendered-html> }` and must return
+   * a complete HTML string. This call REPLACES the plain markdown response
+   * that was set when `markdown()` was first called.
+   *
+   * @example
+   * import { Layout } from "./_layout";
+   *
+   * export function GET() {
+   *   const title = "Welcome to Zerotal!";
+   *   return markdown(CONTENT, { title }).withLayout(Layout, { title });
+   * }
+   */
+  withLayout<P extends { content: string }>(
+    layoutFn: (props: P) => string,
+    props: Omit<P, "content">,
+  ): void {
+    const { title: _title, ...mdOptions } = this.#options;
+    const body = Bun.markdown.html(this.#content, {
+      ...DEFAULT_MD_OPTIONS,
+      ...(mdOptions as BunMarkdownOptions),
+    });
+    const ctx = RequestContext.tryGet();
+    if (!ctx) {
+      throw new Error(
+        "[Zerotal] MarkdownBuilder.withLayout() must be called inside an active HTTP request.",
+      );
+    }
+    ctx.html(layoutFn({ ...props, content: body } as P), this.#status);
+  }
+
+  then<TResult1 = void, TResult2 = never>(
+    onfulfilled?: ((value: void) => TResult1 | PromiseLike<TResult1>) | null,
+    onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null,
+  ): PromiseLike<TResult1 | TResult2> {
+    return Promise.resolve<void>(undefined).then(onfulfilled, onrejected);
+  }
+}
+
+// ── redirect() ────────────────────────────────────────────────────────────
+
+/**
+ * Single entry point for every redirect. Pass a URL for a direct redirect, or call with no
+ * arguments to pick the destination fluently via {@link RedirectBuilder}. All forms return a
+ * {@link ResponseBuilder} so flash data chains naturally.
+ *
+ * @example
+ * redirect("/login", 302).withError("Please log in to continue.");
+ * redirect().back().withErrors({ email: "Invalid email or password." });
+ * redirect().intended("/").withInfo("Please log in to continue.");
+ * redirect().to("profile", { username: "alice" }).withSuccess("Profile updated.");
+ *
+ * @throws {Error} when called outside an active HTTP request.
+ */
+export function redirect(url: string, status?: 301 | 302 | 303 | 307 | 308): ResponseBuilder;
+export function redirect(): RedirectBuilder;
+export function redirect(
+  url?: string,
+  status: 301 | 302 | 303 | 307 | 308 = 302,
+): ResponseBuilder | RedirectBuilder {
+  const ctx = _ctx();
+  if (url === undefined) return new RedirectBuilder(ctx);
+  ctx.redirect(url, status);
+  return new ResponseBuilder(ctx);
+}
+
+/**
+ * Redirect to a named route.
+ * @param name - The route name to redirect to.
+ * @param params - Optional route parameters to interpolate into the route path.
+ * @param status - Optional HTTP status code (default: 302).
+ * @returns
+ */
+export function redirectTo(
+  name: string,
+  params: Record<string, string | number> = {},
+  status: 301 | 302 | 303 | 307 | 308 = 302,
+): ResponseBuilder {
+  return redirect().to(name, params, status);
+}
+
+// ── json() ───────────────────────────────────────────────────────────────
+
+/**
+ * Set a JSON response body on the current request.
+ *
+ * @param data - Any JSON-serializable value.
+ * @param status - HTTP status code (default: 200).
+ * @throws {Error} when called outside an active HTTP request.
+ * @example
+ * json({ user: { id: 1, name: 'Alice' } });      // 200
+ * json({ message: 'Created' }, 201);
+ */
+export function json(data: unknown, status = 200): void {
+  _ctx().json(data, status);
+}
+
+// ── view() ───────────────────────────────────────────────────────────────
+
+/**
+ * Render a view as the current response. Accepts either pre-rendered markup, or
+ * a view component plus its props — in which case the component receives the
+ * active request's `HttpContext` (route params and model bindings live on
+ * `ctx.params`) and the `props` you pass as a second argument.
+ *
+ * @example
+ * // component + props — the request HttpContext is passed automatically:
+ * view(Welcome, { title: "Welcome to Zerotal" });
+ *
+ * // pre-rendered markup:
+ * view(<Welcome title="Hi" />);
+ */
+export function view(markup: string | { toString(): string }, status?: number): void;
+export function view<P extends Record<string, unknown> = Record<string, never>>(
+  component: (ctx: HttpContext, props: P) => ViewMarkup | Promise<ViewMarkup>,
+  props?: P,
+  status?: number,
+): void | Promise<void>;
+export function view(
+  markupOrComponent: ViewMarkup | AnyViewComponent,
+  propsOrStatus?: Record<string, unknown> | number,
+  status = 200,
+): void | Promise<void> {
+  // Delegate to HttpContext.view, which carries the same dual overload.
+  return (_ctx().view as (...args: unknown[]) => void | Promise<void>)(
+    markupOrComponent,
+    propsOrStatus,
+    status,
+  );
+}
+
+// ── html() ───────────────────────────────────────────────────────────────
+
+/** Set a raw HTML response body on the current request. */
+export function html(markup: string | { toString(): string }, status = 200): void {
+  _ctx().html(markup, status);
+}
+
+// ── markdown() ───────────────────────────────────────────────────────────
+
+/**
+ * Render markdown content and set it as the current response.
+ *
+ * Returns a `MarkdownBuilder` that can optionally chain `.withLayout(layoutFn, props)`
+ * to re-render the content inside a custom layout. When `.withLayout()` is called it
+ * replaces the plain markdown response set here with the layout-wrapped version.
+ *
+ * @example — plain (backward-compatible)
+ * markdown(content);
+ *
+ * @example — with custom layout
+ * return markdown(content, { title }).withLayout(Layout, { title });
+ */
+export function markdown(
+  content: string,
+  options?: BunMarkdownOptions & { title?: string },
+  status = 200,
+): MarkdownBuilder {
+  // Render immediately so plain usage (no .withLayout) works without returning.
+  _ctx().markdown(content, options, status);
+  return new MarkdownBuilder(content, options, status);
+}
+
+// ── file() ───────────────────────────────────────────────────────────────
+
+/**
+ * Stream a file from disk as the response. Defaults to `attachment` disposition
+ * (a browser download) with the file's basename; override either via `options`.
+ *
+ * @param path - Absolute or working-directory-relative path to the file.
+ * @param options - Optional `filename` (download name) and `disposition`
+ * (`"attachment"` to download, `"inline"` to display in the browser).
+ * @throws {NotFoundError} If no file exists at `path`.
+ * @example
+ * await file('storage/invoices/2026-07.pdf');                          // download as "2026-07.pdf"
+ * await file('storage/report.pdf', { filename: 'Q3-Report.pdf' });     // download, renamed
+ * await file('storage/preview.pdf', { disposition: 'inline' });        // view in-browser
+ */
+export async function file(
+  path: string,
+  options?: { filename?: string; disposition?: "attachment" | "inline" },
+): Promise<void> {
+  const ctx = _ctx();
+  const bunFile = Bun.file(path);
+
+  if (!(await bunFile.exists())) throw new NotFoundError(`File not found: ${path}`);
+
+  const name = options?.filename ?? path.replace(/\\/g, "/").split("/").pop() ?? "download";
+  const disposition = options?.disposition ?? "attachment";
+
+  // Bun's FileRef is a Blob-compatible body but its TS type predates the W3C Blob interface — cast needed.
+  const blob = bunFile as unknown as Blob;
+
+  ctx.response = new Response(blob, {
+    headers: {
+      "Content-Disposition": `${disposition}; filename="${name}"`,
+      "Content-Type": blob.type || "application/octet-stream",
+    },
+  });
+}
+
+// ── abort() ──────────────────────────────────────────────────────────────
+
+/**
+ * Throw an HTTP error to end the request. Accepts a message (defaults to 500),
+ * an explicit status plus message, or a `ZerotalError` subclass to instantiate.
+ *
+ * @throws {HttpError} (or the given `ZerotalError` subclass) — always; the return
+ * type is `never`.
+ * @example
+ * abort('Something went wrong');           // 500
+ * abort(403, 'Forbidden');                 // explicit status
+ * abort(NotFoundError);                    // throw a specific error class
+ */
+export function abort(message: string): never;
+export function abort(status: number, message: string): never;
+export function abort(ErrorClass: new () => ZerotalError): never;
+export function abort(
+  statusOrMessageOrError: string | number | (new () => ZerotalError),
+  message?: string,
+): never {
+  if (typeof statusOrMessageOrError === "function") {
+    throw new (statusOrMessageOrError as new () => ZerotalError)();
+  }
+  if (typeof statusOrMessageOrError === "string") {
+    throw new HttpError(statusOrMessageOrError, 500);
+  }
+  throw new HttpError(message ?? "Aborted", statusOrMessageOrError);
+}

package/src/helpers/str.ts

@@ -0,0 +1,208 @@
+/**
+ * The `Str` string-manipulation utility — a collection of case converters,
+ * substring helpers, and a `macro()` hook for registering project-specific
+ * string methods at runtime.
+ */
+export const Str = {
+  /** 'hello-world' | 'hello_world' | 'hello world' → 'helloWorld' */
+  camelCase(value: string): string {
+    return value.toLowerCase().replace(/[-_\s]+([a-z])/g, (_, char: string) => char.toUpperCase());
+  },
+
+  /** 'helloWorld' → 'hello_world' */
+  snakeCase(value: string): string {
+    return value
+      .replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")
+      .replace(/([a-z\d])([A-Z])/g, "$1_$2")
+      .toLowerCase();
+  },
+
+  /** 'helloWorld' | 'hello world' → 'hello-world' */
+  slugify(value: string): string {
+    return (
+      value
+        .replace(/([A-Z])/g, " $1")
+        .normalize("NFD")
+        // Strip combining diacritical marks (U+0300–U+036F) so accented letters slug cleanly.
+        .replace(/[̀-ͯ]/g, "")
+        .toLowerCase()
+        .trim()
+        .replace(/[^a-z0-9\s-]/g, "")
+        .replace(/[\s_]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "")
+    );
+  },
+
+  /** 'hello world' → 'Hello World' */
+  titleCase(value: string): string {
+    return value.replace(/\b[a-z]/g, (char) => char.toUpperCase());
+  },
+
+  /** 'hello-world' | 'helloWorld' → 'HelloWorld' */
+  pascalCase(value: string): string {
+    // Collapse separators without lowercasing so existing camelCase humps survive.
+    const collapsed = value.replace(/[-_\s]+([a-zA-Z])/g, (_, char: string) => char.toUpperCase());
+    return collapsed.charAt(0).toUpperCase() + collapsed.slice(1);
+  },
+
+  /** Upper-case the first character only. 'hello world' → 'Hello world' */
+  capitalize(value: string): string {
+    return value.charAt(0).toUpperCase() + value.slice(1);
+  },
+
+  /** Lower-case the first character only. 'BlogPost' → 'blogPost' */
+  lcfirst(value: string): string {
+    return value.charAt(0).toLowerCase() + value.slice(1);
+  },
+
+  /**
+   * Truncate to maxLength, appending suffix if truncated.
+   * truncate('hello world', 7) → 'hell...'
+   */
+  truncate(value: string, maxLength: number, suffix = "..."): string {
+    if (value.length <= maxLength) return value;
+    return value.slice(0, Math.max(0, maxLength - suffix.length)) + suffix;
+  },
+
+  /** Returns true if the value contains only alphanumeric characters (non-empty). */
+  isAlphanumeric(value: string): boolean {
+    return /^[a-zA-Z0-9]+$/.test(value);
+  },
+
+  /** Pad left: padLeft('42', 5, '0') → '00042' */
+  padLeft(value: string, length: number, char = " "): string {
+    return value.padStart(length, char);
+  },
+
+  /** 'helloWorld' | 'hello world' → 'hello-world' */
+  kebab(value: string): string {
+    return value
+      .replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
+      .replace(/([a-z\d])([A-Z])/g, "$1-$2")
+      .replace(/[\s_]+/g, "-")
+      .toLowerCase();
+  },
+
+  /** Collapse all consecutive whitespace (including newlines) into a single space and trim. */
+  squish(value: string): string {
+    return value.replace(/\s+/g, " ").trim();
+  },
+
+  /**
+   * Ensure the string ends with `cap`.
+   * If it already ends with `cap`, returns as-is.
+   * finish('https://example.com', '/') → 'https://example.com/'
+   */
+  finish(value: string, cap: string): string {
+    return value.endsWith(cap) ? value : value + cap;
+  },
+
+  /**
+   * Ensure the string starts with `prefix`.
+   * If it already starts with `prefix`, returns as-is.
+   * start('path/to/file', '/') → '/path/to/file'
+   */
+  start(value: string, prefix: string): string {
+    return value.startsWith(prefix) ? value : prefix + value;
+  },
+
+  /** Return everything after the first occurrence of `needle`, or the full string if not found. */
+  after(value: string, needle: string): string {
+    const index = value.indexOf(needle);
+    return index === -1 ? value : value.slice(index + needle.length);
+  },
+
+  /** Return everything before the first occurrence of `needle`, or the full string if not found. */
+  before(value: string, needle: string): string {
+    const index = value.indexOf(needle);
+    return index === -1 ? value : value.slice(0, index);
+  },
+
+  /** Return everything after the LAST occurrence of `needle`. */
+  afterLast(value: string, needle: string): string {
+    const index = value.lastIndexOf(needle);
+    return index === -1 ? value : value.slice(index + needle.length);
+  },
+
+  /** Return everything before the LAST occurrence of `needle`. */
+  beforeLast(value: string, needle: string): string {
+    const index = value.lastIndexOf(needle);
+    return index === -1 ? value : value.slice(0, index);
+  },
+
+  /** Return true if `value` contains `substring` (case-sensitive). */
+  contains(value: string, substring: string): boolean {
+    return value.includes(substring);
+  },
+
+  /**
+   * Generate a cryptographically random alphanumeric string of the given length.
+   * Uses `crypto.getRandomValues` — no external dependencies.
+   */
+  random(length = 32): string {
+    const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+    const bytes = crypto.getRandomValues(new Uint8Array(length));
+    return Array.from(bytes, (byte) => chars[byte % chars.length]).join("");
+  },
+
+  /**
+   * Replace the first occurrence of `search` with `replace`.
+   * replaceFirst('the cat sat on the mat', 'the', 'a') → 'a cat sat on the mat'
+   */
+  replaceFirst(value: string, search: string, replace: string): string {
+    const index = value.indexOf(search);
+    return index === -1
+      ? value
+      : value.slice(0, index) + replace + value.slice(index + search.length);
+  },
+
+  /**
+   * Replace the last occurrence of `search` with `replace`.
+   */
+  replaceLast(value: string, search: string, replace: string): string {
+    const index = value.lastIndexOf(search);
+    return index === -1
+      ? value
+      : value.slice(0, index) + replace + value.slice(index + search.length);
+  },
+
+  /** Reverse a string: reverse('hello') → 'olleh' */
+  reverse(value: string): string {
+    return [...value].reverse().join("");
+  },
+
+  /**
+   * Limit the string to `maxWords` words, appending `suffix` if truncated.
+   * words('One two three four', 2) → 'One two...'
+   */
+  words(value: string, maxWords: number, suffix = "..."): string {
+    const parts = value.trim().split(/\s+/);
+    if (parts.length <= maxWords) return value;
+    return parts.slice(0, maxWords).join(" ") + suffix;
+  },
+
+  /**
+   * Register a macro (custom method) on the Str object.
+   *
+   * The function is assigned directly to `Str`, so you call it as `Str.myMacro(...)`.
+   * Add a module augmentation to your project for full TypeScript type safety:
+   *
+   * @example
+   * // In AppServiceProvider.onBooted():
+   * Str.macro('readableSize', (bytes: number) =>
+   *   bytes < 1024 ? `${bytes} B` : `${(bytes / 1024).toFixed(1)} KB`
+   * );
+   *
+   * // In types.d.ts (for type safety):
+   * declare module '@zerotal/core' {
+   *   interface StrMacros { readableSize(bytes: number): string; }
+   * }
+   *
+   * // In a controller:
+   * (Str as typeof Str & StrMacros).readableSize(2048); // '2.0 KB'
+   */
+  macro(name: string, fn: (...args: unknown[]) => unknown): void {
+    (Str as Record<string, unknown>)[name] = fn;
+  },
+};