@zerotal/core 1.0.0

package/src/helpers/index.ts

@@ -0,0 +1,266 @@
+/**
+ * Named helper exports — importable, tree-shakeable, never globals. Import from
+ * `@zerotal/core/helpers`.
+ *
+ * A grab-bag of small, dependency-free utilities used throughout an application:
+ * path resolution ({@link basePath}), environment-variable access
+ * ({@link env}, {@link requireEnv}, {@link setAppEnv}), value-flow combinators
+ * ({@link tap}, {@link tapAsync}, {@link pipe}, {@link pipeAsync}), error
+ * suppression ({@link rescue}, {@link rescueSync}), safe nested lookups
+ * ({@link data_get}), the {@link Str} string helper, and {@link markdownPage}
+ * for rendering standalone Markdown documents.
+ *
+ * @example
+ * import { env, requireEnv, tap, data_get } from '@zerotal/core/helpers';
+ *
+ * const debug   = env('APP_DEBUG', false);          // boolean, coerced
+ * const appKey  = requireEnv('APP_KEY');            // throws if unset
+ * const city    = data_get(payload, 'user.address.city', 'Unknown');
+ * const user    = tap(await User.create(data), (u) => log(`created ${u.id}`));
+ *
+ * @packageDocumentation
+ */
+import { join } from "node:path";
+import { ConfigError } from "../errors/ConfigError.ts";
+
+// ── basePath() ────────────────────────────────────────────────────────────────
+
+/**
+ * Resolve a path relative to the application root (`process.cwd()`).
+ *
+ * Use in `bootstrap/app.ts` when declaring route files or directories so paths
+ * are always resolved from the project root rather than the calling file's
+ * directory.
+ *
+ * @example
+ * // bootstrap/app.ts
+ * Application.create({ providers })
+ *   .routing({ web: basePath('routes/web.ts') })
+ *   .fileBasedRouting({ web: basePath('app/routes') });
+ */
+export function basePath(...segments: string[]): string {
+  return join(process.cwd(), ...segments);
+}
+
+// ── setAppEnv() ───────────────────────────────────────────────────────────────
+
+/**
+ * Set `APP_ENV` from the CLI command name — call this in `zerotal.ts` BEFORE
+ * the dynamic import of `bootstrap/app.ts` so `Application.create()` sees
+ * the correct environment.
+ *
+ * If `APP_ENV` is already set (e.g. from `.env` or the shell), this is a no-op.
+ *
+ * | Command              | APP_ENV   |
+ * |----------------------|-----------|
+ * | serve / start / s    | web       |
+ * | worker / queue:work  | worker    |
+ * | anything else        | console   |
+ *
+ * @example
+ * // zerotal.ts
+ * import { setAppEnv, CommandRunner } from '@zerotal/core';
+ * setAppEnv(process.argv[2]);
+ * const { default: app } = await import('./bootstrap/app.ts');
+ */
+/** Runtime-mode values that Application understands natively — never remapped. */
+const _RUNTIME_MODES = new Set(["web", "worker", "console", "test", "testing", "repl"]);
+
+export function setAppEnv(command?: string): void {
+  const normalizedCommand = (command ?? "").toLowerCase();
+  const current = Bun.env["APP_ENV"];
+  const environment = Bun.env as Record<string, string>;
+
+  if (["serve", "start", "s"].includes(normalizedCommand)) {
+    // Always force web mode for the HTTP server — deployment-env names like
+    // "local" or "production" must not leave the app in console mode.
+    if (!current || !_RUNTIME_MODES.has(current.toLowerCase())) {
+      environment["APP_ENV"] = "web";
+    }
+  } else if (["worker", "queue:work"].includes(normalizedCommand)) {
+    if (!current || !_RUNTIME_MODES.has(current.toLowerCase())) {
+      environment["APP_ENV"] = "worker";
+    }
+  } else if (!current || !_RUNTIME_MODES.has(current.toLowerCase())) {
+    // Mirror the serve/worker branches: a deployment-env name like "local" or
+    // "production" must not leave the app in web mode for a CLI command.
+    environment["APP_ENV"] = "console";
+  }
+}
+
+/**
+ * Read an environment variable with an optional typed fallback.
+ *
+ * @example
+ * env('APP_NAME', 'Zerotal App')   // string
+ * env('APP_DEBUG', false)        // boolean (coerces 'true'/'false' strings)
+ * env('PORT', 3000)              // number  (coerces numeric strings)
+ * env('APP_KEY')                 // string | undefined — no fallback
+ */
+export function env(key: string): string | undefined;
+export function env(key: string, fallback: string): string;
+export function env(key: string, fallback: boolean): boolean;
+export function env(key: string, fallback: number): number;
+export function env(
+  key: string,
+  fallback?: string | boolean | number,
+): string | boolean | number | undefined {
+  const raw = Bun.env[key];
+
+  if (raw === undefined) return fallback;
+
+  // Coerce to match fallback type
+  if (typeof fallback === "boolean") {
+    return raw === "true" || raw === "1";
+  }
+  if (typeof fallback === "number") {
+    const parsed = Number(raw);
+    return Number.isNaN(parsed) ? fallback : parsed;
+  }
+  return raw;
+}
+
+/**
+ * Read a required environment variable.
+ * Throws ConfigError if the variable is not set.
+ *
+ * @example
+ * requireEnv('APP_KEY') // throws at boot if APP_KEY is missing
+ */
+export { Str } from "./str.ts";
+
+export function requireEnv(key: string): string {
+  const value = Bun.env[key];
+  if (!value) {
+    throw new ConfigError(`Required environment variable "${key}" is not set.`);
+  }
+  return value;
+}
+
+// ── tap() / tapAsync() ────────────────────────────────────────────────────────
+
+/**
+ * Pass a value to a callback and return the original value.
+ * Great for side-effects (logging, events) in the middle of a chain.
+ *
+ * @example
+ * return tap(await User.create(data), (user) => Events.emit(new UserRegistered(user.id)));
+ */
+export function tap<T>(value: T, callback: (val: T) => void): T {
+  callback(value);
+  return value;
+}
+
+/**
+ * Async version of tap. Awaits the callback then returns the original value.
+ *
+ * @example
+ * return await tapAsync(await User.create(data), async (user) => {
+ *   await Notification.send(user, new WelcomeEmail());
+ * });
+ */
+export async function tapAsync<T>(value: T, callback: (val: T) => Promise<void>): Promise<T> {
+  await callback(value);
+  return value;
+}
+
+// ── pipe() / pipeAsync() ──────────────────────────────────────────────────────
+
+/**
+ * Pass a value to a transformation function and return its result.
+ * The sibling of tap — use pipe when the value should change, tap when it shouldn't.
+ *
+ * @example
+ * const slug = pipe(post.title, (t) => t.toLowerCase().replace(/\s+/g, '-'));
+ */
+export function pipe<T, R>(value: T, fn: (val: T) => R): R {
+  return fn(value);
+}
+
+/**
+ * Async version of pipe.
+ *
+ * @example
+ * const hashed = await pipeAsync(password, (p) => bcrypt.hash(p, 12));
+ */
+export async function pipeAsync<T, R>(value: T, fn: (val: T) => Promise<R>): Promise<R> {
+  return fn(value);
+}
+
+// ── rescue() ──────────────────────────────────────────────────────────────────
+
+/**
+ * Execute a callback and return its value. On exception, return `fallback`
+ * instead of propagating. Fallback may itself be a function that receives
+ * the caught error.
+ *
+ * @example
+ * const price = await rescue(() => stripe.getPrice(id), 0);
+ * const user  = await rescue(() => User.findOrFail(id), (e) => { log(e); return null; });
+ */
+export async function rescue<T>(
+  callback: () => Promise<T> | T,
+  fallback: T | ((error: unknown) => T | Promise<T>),
+): Promise<T> {
+  try {
+    return await callback();
+  } catch (error) {
+    return typeof fallback === "function"
+      ? (fallback as (error: unknown) => T | Promise<T>)(error)
+      : fallback;
+  }
+}
+
+/**
+ * Synchronous sibling of `rescue` — for code paths that cannot await (JSON
+ * parsing, attribute decoding, hot loops). Runs `callback` and returns its
+ * value; on exception returns `fallback` (or the result of calling it with the
+ * caught error).
+ *
+ * @example
+ * const payload = rescueSync(() => JSON.parse(raw), {});
+ * const cursor  = rescueSync(() => JSON.parse(atob(token)), null);
+ */
+export function rescueSync<T>(callback: () => T, fallback: T | ((error: unknown) => T)): T {
+  try {
+    return callback();
+  } catch (error) {
+    return typeof fallback === "function" ? (fallback as (error: unknown) => T)(error) : fallback;
+  }
+}
+
+// ── data_get() ────────────────────────────────────────────────────────────────
+
+/**
+ * Safely read a deeply nested value using dot-notation.
+ * Returns `defaultValue` (default `undefined`) if any segment is absent.
+ *
+ * Designed for untyped JSON payloads (webhooks, external API responses) where
+ * optional chaining would be excessively verbose.
+ *
+ * @example
+ * data_get(payload, 'user.address.city')          // 'Cape Town' or undefined
+ * data_get(payload, 'items.0.price', 0)           // first item's price or 0
+ */
+export function data_get(target: unknown, key: string, defaultValue?: unknown): unknown {
+  if (target === undefined || target === null) return defaultValue;
+  const keys = key.split(".");
+  let current = target as Record<string, unknown>;
+  for (const segment of keys) {
+    if (current === undefined || current === null) return defaultValue;
+    current = (current as Record<string, unknown>)[segment] as Record<string, unknown>;
+  }
+  return current !== undefined ? current : defaultValue;
+}
+
+export { markdownPage, type BunMarkdownOptions } from "./markdown.ts";
+
+// ── Shared framework helpers — canonical home ────────────────────────────────
+// The one HTML escaper (both JSX runtimes render through it), the English
+// inflector the convention layer builds table names with, deep config merging,
+// and request-cookie parsing. Import from `@zerotal/core/helpers`; packages
+// must not carry private copies.
+export { escapeHtml } from "./html.ts";
+export { pluralize, singularize, tableNameFor } from "../support/str.ts";
+export { deepMerge } from "../support/deepMerge.ts";
+export { parseCookieHeader } from "../support/cookie.ts";

package/src/helpers/make.ts

@@ -0,0 +1,35 @@
+/**
+ * Global DI helpers — `make()` resolves from the container, `app()` returns the
+ * running application kernel. Thin wrappers over the {@link App} facade so app
+ * code can resolve dependencies without importing `Application` directly.
+ */
+import type { Application } from "../application/Application.ts";
+import { currentApp } from "../application/currentApp.ts";
+import { App } from "../facade/facades/App.ts";
+import type { BindingToken } from "../container/types.ts";
+
+/**
+ * Resolve a binding — or auto-wire a class via its `@inject()`
+ * metadata — from the application container.
+ *
+ * @example
+ * const users = await make(UsersService);
+ * const events = await make("events");
+ */
+export function make<T>(token: BindingToken<T>): Promise<T> {
+  return App.make(token);
+}
+
+/**
+ * Return the running {@link Application} kernel, or — when passed a token —
+ * resolve it from the container (`app(Token)`).
+ *
+ * @example
+ * app().bind((c) => c.singleton(Clock, () => new SystemClock())); // kernel
+ * const users = await app(UsersService);                          // resolve
+ */
+export function app(): Application;
+export function app<T>(token: BindingToken<T>): Promise<T>;
+export function app<T>(token?: BindingToken<T>): Application | Promise<T> {
+  return token === undefined ? currentApp() : App.make(token);
+}

package/src/helpers/markdown.ts

@@ -0,0 +1,73 @@
+/**
+ * Markdown rendering helpers: title extraction, a minimal HTML page shell, and
+ * the default `Bun.markdown` parser options the framework renders with.
+ */
+
+/** Pull the first H1/H2 from markdown text to use as the page title. */
+export function markdownExtractTitle(content: string): string | undefined {
+  return content.match(/^#{1,2}\s+(.+)$/m)?.[1]?.trim();
+}
+
+/** Minimal HTML shell for rendered markdown pages. */
+export function markdownPage(title: string, body: string): string {
+  return `<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${title}</title>
+<style>
+  *,*::before,*::after{box-sizing:border-box}
+  body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Oxygen,sans-serif;
+    line-height:1.7;color:#1a1a1a;max-width:860px;margin:0 auto;padding:2rem 1.5rem}
+  h1,h2,h3,h4{margin-top:2rem;margin-bottom:.5rem;line-height:1.3}
+  h1{font-size:2rem;border-bottom:2px solid #e5e7eb;padding-bottom:.5rem}
+  h2{font-size:1.5rem;border-bottom:1px solid #e5e7eb;padding-bottom:.3rem}
+  a{color:#2563eb}a:hover{color:#1d4ed8}
+  code{background:#f3f4f6;border-radius:4px;padding:.15em .35em;font-size:.9em}
+  pre{background:#f3f4f6;border-radius:6px;padding:1rem;overflow-x:auto;line-height:1.5}
+  pre code{background:none;padding:0;font-size:inherit}
+  blockquote{border-left:4px solid #d1d5db;margin:0;padding:.5rem 1rem;color:#6b7280}
+  table{border-collapse:collapse;width:100%;margin:1rem 0}
+  th,td{border:1px solid #d1d5db;padding:.5rem .75rem;text-align:left}
+  th{background:#f9fafb;font-weight:600}
+  img{max-width:100%;height:auto}
+  input[type=checkbox]{margin-right:.4em}
+  hr{border:none;border-top:1px solid #e5e7eb;margin:2rem 0}
+</style>
+</head>
+<body>
+${body}
+</body>
+</html>`;
+}
+
+/**
+ * Options for `Bun.markdown.html()`. bun-types exposes the options type only inside
+ * its `markdown` namespace; this is the named, exported equivalent the framework uses.
+ */
+export interface BunMarkdownOptions {
+  tables?: boolean;
+  strikethrough?: boolean;
+  tasklists?: boolean;
+  autolinks?: boolean | { url?: boolean; www?: boolean; email?: boolean };
+  headings?: boolean | { ids?: boolean };
+  hardSoftBreaks?: boolean;
+  wikiLinks?: boolean;
+  underline?: boolean;
+  latexMath?: boolean;
+  collapseWhitespace?: boolean;
+  permissiveAtxHeaders?: boolean;
+  noIndentedCodeBlocks?: boolean;
+  noHtmlBlocks?: boolean;
+  noHtmlSpans?: boolean;
+  tagFilter?: boolean;
+}
+
+/** Default markdown parser options — GFM extensions enabled. */
+export const DEFAULT_MD_OPTIONS: BunMarkdownOptions = {
+  tables: true,
+  strikethrough: true,
+  tasklists: true,
+  autolinks: true,
+  headings: { ids: true },
+};

package/src/helpers/pageElements.ts

@@ -0,0 +1,27 @@
+/**
+ * Page-number window for rendering a numbered pager, with `'...'` gaps —
+ * e.g. `[1, '...', 4, 5, 6, '...', 20]`. The first and last pages are always
+ * included. Shared by every paginator result (`Model.paginate()`, the in-memory
+ * helper) so a pager renders identically whatever produced the page.
+ *
+ * @param current - The current 1-based page.
+ * @param last - The last page number.
+ * @param each - How many page links to show on each side of the current page (default `1`).
+ * @returns Page numbers interleaved with `'...'` for elided ranges.
+ */
+export function pageElements(current: number, last: number, each = 1): (number | "...")[] {
+  if (last <= 1) return [1];
+  each = Math.max(0, each);
+  const wanted = new Set<number>([1, last]);
+  for (let p = current - each; p <= current + each; p++) {
+    if (p >= 1 && p <= last) wanted.add(p);
+  }
+  const out: (number | "...")[] = [];
+  let prev = 0;
+  for (const p of [...wanted].sort((a, b) => a - b)) {
+    if (prev && p - prev > 1) out.push("...");
+    out.push(p);
+    prev = p;
+  }
+  return out;
+}

package/src/helpers/request.ts

@@ -0,0 +1,62 @@
+/**
+ * The global `request()` helper — returns the active HTTP context, or reads a
+ * single merged input value from it (route params, body, then query string).
+ */
+import { RequestContext } from "../context/RequestContext.ts";
+import type { HttpContext } from "../pipeline/HttpContext.ts";
+
+/**
+ * Retrieves the active HTTP request context from the async execution fiber.
+ *
+ * @returns {HttpContext} The current request context.
+ * @throws {Error} If called outside of an active HTTP request lifecycle.
+ *
+ * @example
+ * // Access the full context
+ * const ctx = request();
+ * const token = ctx.bearerToken();
+ */
+export function request(): HttpContext;
+
+/**
+ * Retrieves a deeply merged input value from the current request.
+ *
+ * **Resolution Priority:**
+ * 1. Route parameters (e.g., `ctx.params['id']`)
+ * 2. Parsed body data (e.g., JSON or FormData)
+ * 3. Query string parameters (e.g., `?page=2`)
+ *
+ * ⚠️ **Note:** Body resolution is synchronous. It will only find body data if it
+ * has already been parsed and cached (e.g., via a `FormRequest` or `await ctx.body()`).
+ *
+ * @template T - The expected return type of the input value.
+ * @param {string} key - The name of the input field to resolve.
+ * @param {T} [fallback] - An optional default value to return if the key is missing.
+ * @returns {T | undefined} The resolved input value, the fallback, or undefined.
+ *
+ * @example
+ * // Get a value with a fallback
+ * const page = request('page', '1');
+ *
+ * // Get a typed value
+ * const id = request<number>('id');
+ */
+export function request<T = string>(key: string, fallback?: T): T | undefined;
+
+/**
+ * Implementation of the global request helper.
+ */
+export function request<T = string>(key?: string, fallback?: T): HttpContext | T | undefined {
+  const ctx = RequestContext.get();
+
+  if (!ctx)
+    throw new Error(
+      "The request() helper can only be called within an active HTTP request context.",
+    );
+
+  if (key === undefined) {
+    return ctx;
+  }
+
+  return ctx.input<T>(key, fallback);
+}