@zerotal/core 1.0.0

package/src/support/str.ts

@@ -0,0 +1,122 @@
+/**
+ * Minimal, dependency-free English inflector used by the convention layer to
+ * derive table names and concern associations. Covers the common pluralisation
+ * rules plus an irregular/uncountable table; cases beyond the table should be
+ * handled with an explicit override (e.g. `@table("...")`).
+ */
+
+const IRREGULAR: Record<string, string> = {
+  person: "people",
+  man: "men",
+  woman: "women",
+  child: "children",
+  tooth: "teeth",
+  foot: "feet",
+  mouse: "mice",
+  goose: "geese",
+  ox: "oxen",
+  leaf: "leaves",
+  life: "lives",
+  knife: "knives",
+  wife: "wives",
+  half: "halves",
+  loaf: "loaves",
+  potato: "potatoes",
+  tomato: "tomatoes",
+  hero: "heroes",
+  cactus: "cacti",
+  focus: "foci",
+  datum: "data",
+  analysis: "analyses",
+  index: "indices",
+  matrix: "matrices",
+  vertex: "vertices",
+};
+
+const IRREGULAR_INVERSE: Record<string, string> = Object.fromEntries(
+  Object.entries(IRREGULAR).map(([singular, plural]) => [plural, singular]),
+);
+
+// Words with no distinct plural form.
+const UNCOUNTABLE = new Set([
+  "equipment",
+  "information",
+  "rice",
+  "money",
+  "species",
+  "series",
+  "fish",
+  "sheep",
+  "deer",
+  "aircraft",
+  "news",
+  "data",
+  "media",
+]);
+
+/** Mirror the source word's leading capital onto an irregular-table result, so
+ *  Title Case inputs (admin labels: `Person` → `People`) survive inflection.
+ *  Table-name derivation feeds lowercase and is unaffected. */
+function matchCase(source: string, result: string): string {
+  return /^[A-Z]/.test(source) ? result.charAt(0).toUpperCase() + result.slice(1) : result;
+}
+
+/** Pluralize a single word (English, best-effort). */
+function pluralizeWord(word: string): string {
+  if (!word) return word;
+  const lower = word.toLowerCase();
+  if (UNCOUNTABLE.has(lower)) return word;
+  if (IRREGULAR[lower]) return matchCase(word, IRREGULAR[lower]!);
+  if (/[^aeiou]y$/.test(word)) return word.slice(0, -1) + "ies";
+  if (/(s|x|z|ch|sh)$/.test(word)) return word + "es";
+  return word + "s";
+}
+
+/** Singularize a single word (English, best-effort). */
+function singularizeWord(word: string): string {
+  if (!word) return word;
+  const lower = word.toLowerCase();
+  if (UNCOUNTABLE.has(lower)) return word;
+  if (IRREGULAR_INVERSE[lower]) return matchCase(word, IRREGULAR_INVERSE[lower]!);
+  if (/[^aeiou]ies$/.test(word)) return word.slice(0, -3) + "y";
+  if (/(ses|xes|zes|ches|shes)$/.test(word)) return word.slice(0, -2);
+  if (/s$/.test(word) && !/ss$/.test(word)) return word.slice(0, -1);
+  return word;
+}
+
+/**
+ * Pluralize a snake_case or single word, inflecting only the final segment.
+ * `"blog_post"` → `"blog_posts"`, `"category"` → `"categories"`, `"person"` → `"people"`.
+ */
+export function pluralize(value: string): string {
+  const parts = value.split("_");
+  parts[parts.length - 1] = pluralizeWord(parts[parts.length - 1] ?? "");
+  return parts.join("_");
+}
+
+/** Singularize a snake_case or single word, inflecting only the final segment. */
+export function singularize(value: string): string {
+  const parts = value.split("_");
+  parts[parts.length - 1] = singularizeWord(parts[parts.length - 1] ?? "");
+  return parts.join("_");
+}
+
+/** `BlogPost` → `blog_post`, `userEmail` → `user_email`. */
+export function snakeCase(value: string): string {
+  return value
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .replace(/[\s-]+/g, "_")
+    .toLowerCase();
+}
+
+/** `blog_post` / `blog-post` → `blogPost`. */
+export function camelCase(value: string): string {
+  return value
+    .replace(/[_-]+(.)?/g, (_, char: string | undefined) => (char ? char.toUpperCase() : ""))
+    .replace(/^(.)/, (_, char: string) => char.toLowerCase());
+}
+
+/** Convention table name for a model class name: snake_case + pluralized. `User` → `users`. */
+export function tableNameFor(className: string): string {
+  return pluralize(snakeCase(className));
+}

package/src/view/FileRouteResolver.ts

@@ -0,0 +1,59 @@
+import { Router } from "../router/Router.ts";
+import {
+  registerFileRouteResolver,
+  enableFileRouteLayouts,
+  type FileRouteContext,
+} from "../router/FileRouter.ts";
+import type { ViewComponent, ViewLayout, FileHandler } from "../router/Route.ts";
+import type { HttpContext } from "../pipeline/HttpContext.ts";
+import { SafeHtml, isViewComponent } from "./jsx-runtime.ts";
+
+function toHtml(value: unknown): string {
+  if (value instanceof SafeHtml) return value.value;
+  return value === null || value === undefined ? "" : String(value);
+}
+
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type -- accepts any function narrowed from a route module's default export.
+function isClass(fn: Function): boolean {
+  return /^class[\s{]/.test(Function.prototype.toString.call(fn));
+}
+
+/**
+ * Opt into rendering `.tsx`/`.jsx` file-route pages: a route file's default
+ * export that is a view component (or any function tagged via the view marker)
+ * is rendered to HTML, wrapped in the nearest `_layout`, and registered as a GET
+ * route. Call from a provider's `onRegister()` before file routes are scanned.
+ */
+export function registerViewFileRouteResolver(): void {
+  enableFileRouteLayouts();
+
+  registerFileRouteResolver((ctx: FileRouteContext): boolean => {
+    const mod = ctx.module as { default?: unknown; GET?: unknown; layout?: ViewComponent | null };
+    const component = mod.default;
+
+    if (typeof component !== "function") return false;
+    if (typeof mod.GET === "function") return false;
+    if (isClass(component)) return false;
+
+    const isJsxFile = /\.(tsx|jsx)$/.test(ctx.filePath);
+    if (!isJsxFile && !isViewComponent(component)) return false;
+
+    const resolvedLayout: ViewLayout | undefined =
+      mod.layout !== undefined
+        ? ((mod.layout ?? undefined) as ViewLayout | undefined)
+        : (ctx.layout as ViewLayout | undefined);
+
+    const page = component as ViewComponent;
+
+    const handler: FileHandler = async (http: HttpContext): Promise<Response> => {
+      const inner = toHtml(await page(http, http.params));
+      const body = resolvedLayout
+        ? toHtml(await resolvedLayout(http, { children: new SafeHtml(inner) }))
+        : inner;
+      return new Response(body, { headers: { "Content-Type": "text/html; charset=utf-8" } });
+    };
+
+    Router._registerFileHandler("GET", ctx.urlPath, handler, ctx.middleware, ctx.name);
+    return true;
+  });
+}

package/src/view/index.ts

@@ -0,0 +1,144 @@
+/**
+ * Server-side JSX views: the secure-by-default JSX runtime (`SafeHtml`), the
+ * page/layout authoring helpers, and the optional file-route resolver that
+ * renders `.tsx` pages automatically. All of this lives in core (the
+ * `@zerotal/core/view` subpath) so `ctx.view()` and the components it renders
+ * come from a single package. JSX children are auto-escaped by default; use
+ * {@link safe}/{@link Raw} to opt specific HTML out of escaping.
+ *
+ * @example
+ * ```tsx
+ * import { defineLayout } from "@zerotal/core/view";
+ *
+ * const wrap = defineLayout(AppLayout);
+ * export const Home = wrap<{ name: string }>(({ name }) => (
+ *   <main><h1>Hello {name}</h1></main>
+ * ));
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { SafeHtml, Fragment, markViewComponent } from "./jsx-runtime.ts";
+export { SafeHtml, Fragment };
+export type { FC, Children } from "./jsx-runtime.ts";
+
+export { VIEW_COMPONENT_SYMBOL, VIEW_COMPONENT_PROP } from "./jsx-runtime.ts";
+// Tested opt-in feature (see router/ViewLayout.test.ts) awaiting docs — kept public.
+export { registerViewFileRouteResolver } from "./FileRouteResolver.ts";
+
+import type { HttpContext } from "../pipeline/HttpContext.ts";
+
+/**
+ * Declare a page handler: a function of `(ctx, params)` returning HTML (or a
+ * string / promise thereof), tagged via {@link markViewComponent} so the router
+ * treats it as a view component. Returns the same function with its type intact.
+ *
+ * @example
+ * ```tsx
+ * import { definePage } from '@zerotal/core/view';
+ *
+ * export const Show = definePage<{ id: string }>((ctx, { id }) => (
+ *   <article><h1>Post {id}</h1></article>
+ * ));
+ * ```
+ */
+export function definePage<P extends Record<string, unknown> = Record<string, unknown>>(
+  component: (ctx: HttpContext, params: P) => SafeHtml | string | Promise<SafeHtml | string>,
+): typeof component {
+  return markViewComponent(component);
+}
+
+/**
+ * Wrap a pre-rendered HTML string as SafeHtml so it passes through
+ * renderChildren() without being escaped again.
+ *
+ * Use when you have HTML that was produced outside JSX (e.g. a Markdown
+ * renderer) and you want to embed it safely into a JSX tree.
+ *
+ * @example
+ * import { safe } from '@zerotal/core';
+ * <article>{safe(markdownToHtml(post.body))}</article>
+ */
+export function safe(html: string): SafeHtml {
+  return new SafeHtml(html);
+}
+
+/**
+ * Escape a raw value for safe use in a context where SafeHtml is not
+ * available — e.g. template-literal fallbacks or attribute values built
+ * outside JSX. Not needed for normal JSX children (auto-escaped by default).
+ *
+ * @example
+ * const attr = esc(user.name);  // safe inside a raw string template
+ */
+export function esc(val: unknown): string {
+  // Native, SIMD-optimized escaping (same set as the JSX runtime's escHtml).
+  return Bun.escapeHTML(String(val ?? ""));
+}
+
+/**
+ * Component that injects a raw HTML string without escaping.
+ * Prefer dangerouslySetInnerHTML on intrinsic elements for single-element
+ * cases; use Raw when you need it as a composable component.
+ *
+ * @example
+ * import { Raw } from '@zerotal/core';
+ * <div><Raw html={markdownToHtml(post.body)} /></div>
+ */
+export function Raw({ html }: { html: string }): SafeHtml {
+  return new SafeHtml(html);
+}
+
+// Re-export SafeHtml type for use in controller return-type annotations.
+export type { SafeHtml as Html };
+
+/**
+ * Bind a shared layout component to page components, eliminating the need
+ * to wrap every page in `<Layout>...</Layout>` manually.
+ *
+ * Returns a `wrap` factory.  Call `wrap(PageComponent)` to produce a new
+ * component that renders `PageComponent` inside the layout.  All props from
+ * both the layout (except `children`) and the page are merged — TypeScript
+ * enforces that callers supply every required field.
+ *
+ * @example
+ * // resources/views/layouts/AppLayout.tsx
+ * export function AppLayout({ children, title }: { children: unknown; title: string }) {
+ *   return (
+ *     <html>
+ *       <head><title>{title} — My App</title></head>
+ *       <body>{children}</body>
+ *     </html>
+ *   );
+ * }
+ *
+ * // resources/views/About.tsx
+ * import { defineLayout } from '@zerotal/core';
+ * import { AppLayout }    from './layouts/AppLayout.tsx';
+ *
+ * const wrap = defineLayout(AppLayout);
+ *
+ * export const AboutPage = wrap<{ title: string }>(({ title }) => (
+ *   <main>
+ *     <h1>{title}</h1>
+ *     <p>We build things.</p>
+ *   </main>
+ * ));
+ *
+ * // In routes/index.ts:
+ * Router.view('/about', AboutPage, { title: 'About Us' });
+ */
+export function defineLayout<LP extends Record<string, unknown>>(
+  Layout: (props: LP & { children?: unknown }) => SafeHtml,
+): <PP extends Record<string, unknown> = Record<string, never>>(
+  Page: (props: PP & { children?: unknown }) => SafeHtml,
+) => (props: LP & PP) => SafeHtml {
+  return function wrap<PP extends Record<string, unknown>>(
+    Page: (props: PP & { children?: unknown }) => SafeHtml,
+  ): (props: LP & PP) => SafeHtml {
+    return (props: LP & PP): SafeHtml => {
+      const children = Page(props as PP);
+      return Layout({ ...(props as unknown as LP), children });
+    };
+  };
+}

package/src/view/jsx-runtime.ts

@@ -0,0 +1,233 @@
+// ── View-component marker ──
+
+import { escapeHtml as escHtml } from "../helpers/html.ts";
+
+/**
+ * Well-known symbol stamped onto functions that are Zerotal view components,
+ * letting the renderer distinguish page/layout components from ordinary
+ * functions. Registered via `Symbol.for` so the marker survives across module
+ * realms.
+ */
+export const VIEW_COMPONENT_SYMBOL = Symbol.for("zerotal.view.component");
+
+/**
+ * String-keyed twin of {@link VIEW_COMPONENT_SYMBOL}. Set alongside the symbol
+ * as a fallback for tooling or environments that can't read symbol-keyed props.
+ */
+export const VIEW_COMPONENT_PROP = "__zerotalViewComponent";
+
+/**
+ * Tag a function as a Zerotal view component (mutates and returns it) so
+ * {@link isViewComponent} recognises it. Marking is best-effort — a frozen
+ * function simply stays unmarked. Applied automatically by {@link definePage},
+ * {@link defineLayout}, and the JSX factory when it renders a function tag.
+ *
+ * @param fn - The component function to mark.
+ * @returns The same function, now carrying the marker.
+ */
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type -- marks any component function, regardless of its specific signature.
+export function markViewComponent<T extends Function>(fn: T): T {
+  try {
+    (fn as unknown as Record<PropertyKey, unknown>)[VIEW_COMPONENT_SYMBOL] = true;
+    (fn as unknown as Record<string, unknown>)[VIEW_COMPONENT_PROP] = true;
+  } catch {
+    /* defining the marker is best-effort — frozen functions just stay unmarked. */
+  }
+  return fn;
+}
+
+/**
+ * Whether a value was tagged by {@link markViewComponent} — i.e. it is a Zerotal
+ * view component rather than a plain function. Returns `false` for non-functions.
+ *
+ * @param fn - The value to test.
+ */
+export function isViewComponent(fn: unknown): boolean {
+  if (typeof fn !== "function") return false;
+  const f = fn as unknown as Record<PropertyKey, unknown>;
+  return f[VIEW_COMPONENT_SYMBOL] === true || f[VIEW_COMPONENT_PROP] === true;
+}
+
+// ── SafeHtml ──────────────────────────────────────────────────────────────────
+
+/**
+ * Opaque runtime wrapper produced by every JSX expression.
+ * Signals to renderChildren() that the value is already-escaped HTML and
+ * must NOT be re-escaped. End users should not construct this directly —
+ * use JSX syntax or the safe() / Raw helpers from @zerotal/core.
+ */
+export class SafeHtml {
+  constructor(readonly value: string) {}
+  toString(): string {
+    return this.value;
+  }
+}
+
+// ── Global JSX type declarations ──────────────────────────────────────────────
+// When a file uses /** @jsxImportSource @zerotal/core */, TypeScript imports this
+// module and picks up these declarations, giving full type-safe JSX with
+// JSX.Element = SafeHtml (secure by default, never a plain string).
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace -- the JSX namespace is the only way to declare global JSX types.
+  namespace JSX {
+    type Element = SafeHtml;
+    interface ElementChildrenAttribute {
+      // eslint-disable-next-line @typescript-eslint/no-empty-object-type -- ElementChildrenAttribute names the children prop; the value type is irrelevant by JSX convention.
+      children: {};
+    }
+    interface IntrinsicElements {
+      [tag: string]: Record<string, unknown> & { children?: unknown };
+    }
+  }
+}
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Function-component type: a function taking typed props (plus optional
+ * `children`) and returning {@link SafeHtml}. Use it to annotate view
+ * components authored outside of `.tsx` files.
+ *
+ * @typeParam P - The component's own prop shape.
+ */
+export type FC<P extends Record<string, unknown> = Record<string, never>> = (
+  props: P & { children?: unknown },
+) => SafeHtml;
+
+// ── HTML element sets ─────────────────────────────────────────────────────────
+
+const VOID_ELEMENTS = new Set([
+  "area",
+  "base",
+  "br",
+  "col",
+  "embed",
+  "hr",
+  "img",
+  "input",
+  "link",
+  "meta",
+  "param",
+  "source",
+  "track",
+  "wbr",
+]);
+
+// ── Escaping ──────────────────────────────────────────────────────────────────
+// Attribute values and auto-escaped text children both go through `escHtml`,
+// imported from helpers/html.ts — the framework's one escaper
+// (Bun.escapeHTML underneath).
+
+// ── Child rendering ───────────────────────────────────────────────────────────
+//
+// The key security boundary:
+//   • SafeHtml  → pass through as-is (already rendered by jsx() / safe())
+//   • string    → AUTO-ESCAPE (treat as untrusted user data)
+//   • number    → convert to string, no escaping needed (numbers are inert)
+//   • boolean / null / undefined → render nothing (conditional rendering idiom)
+//   • Array     → recurse (children array from jsxs)
+
+function renderChildren(children: unknown): string {
+  if (children instanceof SafeHtml) return children.value;
+  if (typeof children === "string") return escHtml(children);
+  if (typeof children === "number") return String(children);
+  if (children === null || children === undefined || children === false || children === true)
+    return "";
+  if (Array.isArray(children)) return children.map(renderChildren).join("");
+  // Fallback: stringify and escape unknown values
+  return escHtml(String(children));
+}
+
+// ── Attribute rendering ───────────────────────────────────────────────────────
+
+function renderAttrs(props: Record<string, unknown>): string {
+  let out = "";
+  for (const [key, val] of Object.entries(props)) {
+    if (key === "children" || key === "key" || key === "dangerouslySetInnerHTML") continue;
+    if (val === undefined || val === null || val === false) continue;
+    if (val === true) {
+      out += ` ${key}`;
+      continue;
+    }
+    // Map React prop-name conventions to their HTML equivalents.
+    const attr = key === "className" ? "class" : key === "htmlFor" ? "for" : key;
+    if (typeof val === "string" || typeof val === "number") {
+      out += ` ${attr}="${escHtml(String(val))}"`;
+    }
+  }
+  return out;
+}
+
+// ── JSX factory ───────────────────────────────────────────────────────────────
+
+/**
+ * The JSX factory the TypeScript runtime calls for every element. Renders an
+ * intrinsic tag to an HTML string or invokes a component function, always
+ * returning {@link SafeHtml}. Not called directly — emitted by the compiler
+ * under `@jsxImportSource @zerotal/core`.
+ *
+ * @internal
+ */
+export function jsx(
+  tag: string | FC<Record<string, unknown>>,
+  props: Record<string, unknown> | null,
+  _key?: unknown,
+): SafeHtml {
+  const allProps = props ?? {};
+  const { children, dangerouslySetInnerHTML, ...rest } = allProps as Record<string, unknown> & {
+    children?: unknown;
+    dangerouslySetInnerHTML?: { __html: string };
+  };
+
+  if (typeof tag === "function") {
+    markViewComponent(tag);
+    return tag({ ...rest, children });
+  }
+
+  const attrs = renderAttrs(rest);
+
+  if (VOID_ELEMENTS.has(tag)) return new SafeHtml(`<${tag}${attrs}>`);
+
+  // dangerouslySetInnerHTML bypasses child rendering — explicit raw-HTML escape hatch.
+  const inner =
+    dangerouslySetInnerHTML !== undefined
+      ? dangerouslySetInnerHTML.__html
+      : renderChildren(children);
+
+  return new SafeHtml(`<${tag}${attrs}>${inner}</${tag}>`);
+}
+
+/**
+ * Alias of {@link jsx} — the runtime calls it when children is a static array
+ * literal. Emitted by the compiler, not called directly.
+ * @internal
+ */
+export const jsxs = jsx;
+
+/**
+ * Alias of {@link jsx} used by the compiler in development mode; the same
+ * implementation is correct for SSR.
+ * @internal
+ */
+export const jsxDEV = jsx;
+
+// ── Fragment ──────────────────────────────────────────────────────────────────
+
+/**
+ * JSX fragment component — renders its children with no wrapper element,
+ * concatenating them into a single {@link SafeHtml}. Written as `<>…</>` in JSX.
+ *
+ * @example
+ * ```tsx
+ * <>
+ *   <li>One</li>
+ *   <li>Two</li>
+ * </>
+ * ```
+ */
+export function Fragment({ children }: { children?: unknown }): SafeHtml {
+  return new SafeHtml(renderChildren(children));
+}
+
+/** The type of a component's `children` prop (any JSX-renderable value). */
+export type Children = Parameters<typeof Fragment>[0]["children"];