@heyramzi/utils 0.0.0-stage → 1.12.0

package/src/logger.ts

@@ -0,0 +1,24 @@
+import type { Logger, LogEntry, LogLevel } from "#src/logger-types.js";
+
+let _logger: Logger | null = null;
+
+/** Set the global logger. Call once at app startup. */
+export function setLogger(logger: Logger): void {
+  _logger = logger;
+}
+
+/** Fire-and-forget log. Never throws. */
+export function log(level: LogLevel, message: string, data?: Record<string, unknown>): void {
+  if (!_logger) return;
+  const entry: LogEntry = { level, message, ...data };
+  try {
+    const result = _logger.log(entry);
+    if (result instanceof Promise) {
+      result.catch((err: unknown) => {
+        console.error("[logs] Logger failed:", err);
+      });
+    }
+  } catch (err) {
+    console.error("[logs] Logger failed:", err);
+  }
+}

package/src/math.test.ts

@@ -0,0 +1,41 @@
+import { describe, it, expect } from "vite-plus/test";
+import { clamp } from "#src/math.ts";
+
+describe("clamp", () => {
+  it("returns the value when within range", () => {
+    expect(clamp(5, 0, 10)).toBe(5);
+  });
+
+  it("returns min when value is below min", () => {
+    expect(clamp(-5, 0, 10)).toBe(0);
+  });
+
+  it("returns max when value is above max", () => {
+    expect(clamp(15, 0, 10)).toBe(10);
+  });
+
+  it("returns value when equal to min", () => {
+    expect(clamp(0, 0, 10)).toBe(0);
+  });
+
+  it("returns value when equal to max", () => {
+    expect(clamp(10, 0, 10)).toBe(10);
+  });
+
+  it("works with negative ranges", () => {
+    expect(clamp(-5, -10, -1)).toBe(-5);
+    expect(clamp(-15, -10, -1)).toBe(-10);
+    expect(clamp(0, -10, -1)).toBe(-1);
+  });
+
+  it("works with decimal values", () => {
+    expect(clamp(0.5, 0, 1)).toBe(0.5);
+    expect(clamp(1.5, 0, 1)).toBe(1);
+    expect(clamp(-0.1, 0, 1)).toBe(0);
+  });
+
+  it("works when min equals max", () => {
+    expect(clamp(5, 3, 3)).toBe(3);
+    expect(clamp(3, 3, 3)).toBe(3);
+  });
+});

package/src/math.ts

@@ -0,0 +1,3 @@
+export function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}

package/src/og/fonts.ts

@@ -0,0 +1,69 @@
+// Apps compile this source, and only a reference carries the wawoff2 types to them.
+// oxlint-disable-next-line typescript/triple-slash-reference
+/// <reference path="./wawoff2.d.ts" />
+import { readFileSync } from "node:fs";
+import { tryCatch, tryCatchAsync } from "#src/result.js";
+import type { Font } from "satori";
+import type { FontConfig } from "#src/og/types.js";
+
+const cache = new Map<string, ArrayBuffer>();
+
+function readRaw(path: string): Uint8Array | null {
+  const result = tryCatch(() => readFileSync(path));
+  return result.ok ? result.value : null;
+}
+
+function toArrayBuffer(bytes: Uint8Array): ArrayBuffer {
+  const out = new ArrayBuffer(bytes.byteLength);
+  new Uint8Array(out).set(bytes);
+  return out;
+}
+
+async function decodeFont(path: string): Promise<ArrayBuffer | null> {
+  const cached = cache.get(path);
+  if (cached) return cached;
+
+  const raw = readRaw(path);
+  if (!raw) return null;
+
+  const isWoff2 = path.toLowerCase().endsWith(".woff2");
+  if (!isWoff2) {
+    const buf = toArrayBuffer(raw);
+    cache.set(path, buf);
+    return buf;
+  }
+
+  const decoded = await tryCatchAsync(async () => {
+    const { decompress } = await import("wawoff2");
+    return decompress(raw);
+  });
+  if (!decoded.ok) return null;
+  const buf = toArrayBuffer(decoded.value);
+  cache.set(path, buf);
+  return buf;
+}
+
+/**
+ * Load fonts from disk for satori. Supports .ttf, .otf, and .woff2. woff2 files are decoded to TTF in memory on first load.
+ */
+
+/*
+ * Results are cached per path for the lifetime of the process. Fonts that fail to load or decode are skipped silently.
+ */
+export async function loadFonts(configs: FontConfig[]): Promise<Font[]> {
+  // Decode serially: wawoff2.decompress returns a Uint8Array view into a
+  // shared WASM heap, so concurrent calls overwrite each other's output
+  // before toArrayBuffer can copy the bytes out.
+  const decoded: Font[] = [];
+  for (const config of configs) {
+    const data = await decodeFont(config.path);
+    if (!data) continue;
+    decoded.push({
+      name: config.name,
+      data,
+      weight: config.weight,
+      style: config.style ?? "normal",
+    });
+  }
+  return decoded;
+}

package/src/og/index.ts

@@ -0,0 +1,5 @@
+export { renderImage, MIME_TYPES } from "#src/og/renderer.js";
+export { loadFonts } from "#src/og/fonts.js";
+export { html, raw } from "#src/og/markup.js";
+export type { HtmlExpression, RawMarkup, SatoriNode } from "#src/og/markup.js";
+export type { Font, FontConfig, ImageFormat, ImageSize, RenderOptions } from "#src/og/types.js";

package/src/og/markup.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from "vite-plus/test";
+import { html, raw } from "#src/og/markup.js";
+
+function serialize(node: ReturnType<typeof html>): string {
+  return JSON.stringify(node);
+}
+
+describe("markup", () => {
+  it("interpolates text expressions as escaped text", () => {
+    const unsafe = "<script>alert(1)</script>";
+    const node = html`<div>${unsafe}</div>`;
+    expect(serialize(node)).toContain("&lt;script&gt;alert(1)&lt;/script&gt;");
+    expect(serialize(node)).not.toContain("<script>");
+  });
+
+  it("inserts raw() fragments as markup", () => {
+    const rects = raw(`<rect width="10" height="10"/><rect width="20" height="20"/>`);
+    const node = html`<svg>${rects}</svg>`;
+    const out = serialize(node);
+    expect(out).toContain('"rect"');
+    expect(out).not.toContain("&lt;rect");
+  });
+
+  it("inserts raw() fragments with dynamic nested SVG defs", () => {
+    const stops = raw(
+      [1, 2, 3]
+        .map(
+          (i) =>
+            `<radialGradient id="g-${i}" cx="50%" cy="50%" r="50%"><stop offset="0%" stop-color="#000"/></radialGradient>`,
+        )
+        .join(""),
+    );
+    const node = html`<svg><defs>${stops}</defs></svg>`;
+    const out = serialize(node);
+    expect(out).toContain('"radialGradient"');
+    expect(out).toContain("g-1");
+    expect(out).toContain("g-3");
+    expect(out).not.toContain("&lt;radialGradient");
+  });
+
+  it("skips null / undefined / false expressions", () => {
+    const node = html`<div>${null}${undefined}${false}x</div>`;
+    expect(serialize(node)).toContain("x");
+    expect(serialize(node)).not.toContain("null");
+    expect(serialize(node)).not.toContain("undefined");
+    expect(serialize(node)).not.toContain("false");
+  });
+
+  it("interpolates arrays: escapes strings, inlines RawMarkup", () => {
+    const children = ["<b>escaped</b>", raw("<span>raw</span>"), 42, null];
+    const node = html`<div>${children}</div>`;
+    const out = serialize(node);
+    expect(out).toContain("&lt;b&gt;escaped&lt;/b&gt;");
+    expect(out).toContain('"span"');
+    expect(out).toContain("42");
+  });
+
+  it("preserves attribute-value interpolation as text", () => {
+    const color = "#abc123";
+    const node = html`<div style="color:${color};"></div>`;
+    expect(serialize(node)).toContain('"color":"#abc123"');
+  });
+
+  // Type-level regression: passing the return value of html() into another
+  // html() call used to stringify to "[object Object]". The typed signature
+  // now rejects it at compile time. Enforce with @ts-expect-error.
+  it("type-rejects nested html()", () => {
+    const inner = html`<span>hi</span>`;
+    // @ts-expect-error -- nested SatoriNode is not a valid HtmlExpression
+    const _node = html`<div>${inner}</div>`;
+    void _node;
+  });
+});

package/src/og/markup.ts

@@ -0,0 +1,90 @@
+import { html as satoriHtml } from "satori-html";
+import { __unsafeHTML } from "ultrahtml";
+
+/**
+ * Branded marker for pre-built HTML/SVG markup that must NOT be HTML-escaped when interpolated into an `html` tagged template.
+ */
+
+/*
+ * Produced by `raw()`. The runtime shape matches ultrahtml's `__unsafeHTML` return value so it flows through satori-html's parser untouched.
+ */
+export type RawMarkup = { readonly value: string; readonly [RAW_MARKUP]: true };
+
+const RAW_MARKUP: unique symbol = Symbol.for("@heyramzi/marketing/imagegen/RawMarkup");
+
+/**
+ * Wrap a string as raw HTML/SVG markup so it bypasses HTML escaping when interpolated into `html\`...\``. Without this, any `<tag>` in an interpolated string becomes `&lt;tag&gt;` text.
+ */
+
+/*
+ * Use for dynamically-built fragments (lists of `<rect>`, `<radialGradient>`, etc.). Never call with user-supplied content: there is no sanitization.
+ */
+export function raw(markup: string): RawMarkup {
+  const marked = __unsafeHTML(markup) as { value: string };
+  Object.defineProperty(marked, RAW_MARKUP, { value: true, enumerable: false });
+  return marked as RawMarkup;
+}
+
+/**
+ * Expression types allowed inside an `html\`...\`` template literal.
+ */
+
+/*
+ * `string | number | boolean` is interpolated as escaped text. `RawMarkup` is interpolated as raw markup (wrap fragment strings with `raw()`). `null | undefined` is skipped.
+ */
+
+/*
+ * Arrays of the above are concatenated.
+ */
+
+/*
+ * Notably excludes arbitrary objects, which prevents accidentally passing the return value of a nested `html\`...\`` call, which would stringify to `[object Object]` at runtime.
+ */
+export type HtmlExpression =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | RawMarkup
+  | ReadonlyArray<string | number | boolean | null | undefined | RawMarkup>;
+
+/**
+ * Satori-compatible markup object. The exact shape is an internal detail of
+ * satori-html; treat it as opaque and pass it to `renderImage`.
+ */
+export type SatoriNode = ReturnType<typeof satoriHtml>;
+
+/**
+ * Typed tagged template for building satori-compatible markup.
+ */
+
+/*
+ * Text interpolations (`${stringVar}`) are HTML-escaped. Markup interpolations (`${raw(fragment)}`) are inserted verbatim. Nested `html\`...\`` calls aren't supported, so compose in a single tag.
+ */
+
+/*
+ * Example: ```ts const stops = raw(items.map((s) => `<stop offset="${s.offset}"/>`).join("")); return html`<svg><defs><radialGradient>${stops}</radialGradient></defs></svg>`; ```
+ */
+export function html(strings: TemplateStringsArray, ...values: HtmlExpression[]): SatoriNode {
+  const flattened = values.map((value) => {
+    if (Array.isArray(value)) {
+      const parts = value.map((item) => {
+        if (item == null || item === false) return "";
+        if (isRawMarkup(item)) return item.value;
+        return escapeHtml(String(item));
+      });
+      return raw(parts.join(""));
+    }
+    return value;
+  });
+  return satoriHtml(strings, ...flattened);
+}
+
+function isRawMarkup(value: unknown): value is RawMarkup {
+  return typeof value === "object" && value !== null && RAW_MARKUP in value;
+}
+
+function escapeHtml(input: string): string {
+  return input.replace(/[&<>]/g, (c) => (c === "&" ? "&amp;" : c === "<" ? "&lt;" : "&gt;"));
+}

package/src/og/renderer.ts

@@ -0,0 +1,42 @@
+import satori from "satori";
+import sharp from "sharp";
+import type { SatoriNode } from "#src/og/markup.js";
+import type { ImageFormat, RenderOptions } from "#src/og/types.js";
+
+/**
+ * Render satori-compatible markup to an image buffer.
+ *
+ * - `svg` returns the raw SVG bytes from satori.
+ * - `png` / `avif` pipe the SVG through sharp.
+ */
+export async function renderImage(markup: SatoriNode, options: RenderOptions): Promise<Uint8Array> {
+  const format: ImageFormat = options.format ?? "png";
+
+  // satori types its input as React's ReactNode but reads only `{ type, props }`, which is what
+  // satori-html's `html` returns. This cast is where the two types disagree.
+  const svg = await satori(markup as Parameters<typeof satori>[0], {
+    width: options.size.width,
+    height: options.size.height,
+    fonts: options.fonts,
+  });
+
+  if (format === "svg") {
+    return new TextEncoder().encode(svg);
+  }
+
+  const pipeline = sharp(Buffer.from(svg));
+
+  if (format === "avif") {
+    const buffer = await pipeline.avif({ quality: options.quality ?? 82 }).toBuffer();
+    return new Uint8Array(buffer);
+  }
+
+  const buffer = await pipeline.png({ quality: options.quality ?? 90 }).toBuffer();
+  return new Uint8Array(buffer);
+}
+
+export const MIME_TYPES: Record<ImageFormat, string> = {
+  svg: "image/svg+xml",
+  png: "image/png",
+  avif: "image/avif",
+};

package/src/og/types.ts

@@ -0,0 +1,26 @@
+import type { Font } from "satori";
+
+export type { Font };
+
+export type ImageSize = {
+  width: number;
+  height: number;
+};
+
+export type ImageFormat = "svg" | "png" | "avif";
+
+export type FontConfig = {
+  name: string;
+  /** Path to .ttf, .otf, or .woff2 file. woff2 is decoded to ttf at load time. */
+  path: string;
+  weight: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+  style?: "normal" | "italic";
+};
+
+export type RenderOptions = {
+  fonts: Font[];
+  size: ImageSize;
+  format?: ImageFormat;
+  /** PNG/AVIF compression quality, 1 to 100. Defaults to 90 for PNG, 82 for AVIF. */
+  quality?: number;
+};

package/src/og/wawoff2.d.ts

@@ -0,0 +1,6 @@
+declare module "wawoff2" {
+  /** Decompress WOFF2 bytes to a TTF Uint8Array. */
+  export function decompress(buffer: Uint8Array | Buffer): Promise<Uint8Array>;
+  /** Compress TTF bytes to WOFF2. */
+  export function compress(buffer: Uint8Array | Buffer): Promise<Uint8Array>;
+}

package/src/package-imports.test.mjs

@@ -0,0 +1,22 @@
+import { expect, test } from "vite-plus/test";
+import { packageImportsOverKitAlias } from "#src/vite.js";
+
+test("package imports survive Kit aliases without removing unrelated aliases", () => {
+  const aliases = [
+    { find: /^#src\/(.+)$/, replacement: "/app/src/$1" },
+    { find: /^#scripts\/(.+)$/, replacement: "/app/scripts/$1" },
+    { find: /^\$lib\/(.+)$/, replacement: "/app/lib/$1" },
+    { find: "#src-extra", replacement: "/extra" },
+  ];
+  const config = { resolve: { alias: aliases } };
+  packageImportsOverKitAlias().config(config);
+  expect(config.resolve.alias).toEqual(aliases.slice(2));
+});
+
+test("missing aliases and object aliases remain usable", () => {
+  const plugin = packageImportsOverKitAlias();
+  plugin.config({});
+  const config = { resolve: { alias: { $lib: "/lib" } } };
+  plugin.config(config);
+  expect(config.resolve.alias).toEqual({ $lib: "/lib" });
+});

package/src/result.test.ts

@@ -0,0 +1,149 @@
+import { describe, it, expect } from "vite-plus/test";
+import { Ok, Err, tryCatch, tryCatchAsync } from "#src/result.ts";
+
+describe("Ok", () => {
+  it("creates a success result with ok: true", () => {
+    const result = Ok(42);
+    expect(result.ok).toBe(true);
+  });
+
+  it("holds the provided value", () => {
+    const result = Ok("hello");
+    if (result.ok) {
+      expect(result.value).toBe("hello");
+    }
+  });
+
+  it("works with object values", () => {
+    const data = { id: 1, name: "test" };
+    const result = Ok(data);
+    if (result.ok) {
+      expect(result.value).toEqual(data);
+    }
+  });
+
+  it("works with null value", () => {
+    const result = Ok(null);
+    if (result.ok) {
+      expect(result.value).toBeNull();
+    }
+  });
+});
+
+describe("Err", () => {
+  it("creates a failure result with ok: false", () => {
+    const result = Err(new Error("boom"));
+    expect(result.ok).toBe(false);
+  });
+
+  it("holds the provided error", () => {
+    const err = new Error("something failed");
+    const result = Err(err);
+    if (!result.ok) {
+      expect(result.error).toBe(err);
+    }
+  });
+
+  it("works with string errors", () => {
+    const result = Err("custom error string");
+    if (!result.ok) {
+      expect(result.error).toBe("custom error string");
+    }
+  });
+
+  it("works with custom error objects", () => {
+    const result = Err({ code: 404, message: "Not found" });
+    if (!result.ok) {
+      expect(result.error).toEqual({ code: 404, message: "Not found" });
+    }
+  });
+});
+
+describe("tryCatch", () => {
+  it("returns Ok when function succeeds", () => {
+    const result = tryCatch(() => 42);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value).toBe(42);
+    }
+  });
+
+  it("returns Err when function throws an Error", () => {
+    const result = tryCatch(() => {
+      throw new Error("fail");
+    });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.message).toBe("fail");
+    }
+  });
+
+  it("wraps a thrown non-Error value in an Error", () => {
+    const result = tryCatch(() => {
+      throw "string error";
+    });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(Error);
+      expect(result.error.message).toBe("string error");
+    }
+  });
+
+  it("wraps a thrown number in an Error", () => {
+    const result = tryCatch(() => {
+      throw 42;
+    });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(Error);
+      expect(result.error.message).toBe("42");
+    }
+  });
+
+  it("works with a function returning an object", () => {
+    const result = tryCatch(() => ({ a: 1, b: 2 }));
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value).toEqual({ a: 1, b: 2 });
+    }
+  });
+});
+
+describe("tryCatchAsync", () => {
+  it("returns Ok when async function resolves", async () => {
+    const result = await tryCatchAsync(async () => "resolved");
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value).toBe("resolved");
+    }
+  });
+
+  it("returns Err when async function rejects with an Error", async () => {
+    const result = await tryCatchAsync(async () => {
+      throw new Error("async fail");
+    });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.message).toBe("async fail");
+    }
+  });
+
+  it("wraps a rejected non-Error value in an Error", async () => {
+    const result = await tryCatchAsync(async () => {
+      throw "rejected string";
+    });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(Error);
+      expect(result.error.message).toBe("rejected string");
+    }
+  });
+
+  it("works with async functions returning objects", async () => {
+    const result = await tryCatchAsync(async () => ({ data: [1, 2, 3] }));
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value).toEqual({ data: [1, 2, 3] });
+    }
+  });
+});

package/src/result.ts

@@ -0,0 +1,29 @@
+// Lightweight Result type for typed error handling
+
+export type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };
+
+export function Ok<T>(value: T): Result<T, never> {
+  return { ok: true, value };
+}
+
+export function Err<E>(error: E): Result<never, E> {
+  return { ok: false, error };
+}
+
+// Wrap a synchronous function that might throw
+export function tryCatch<T>(fn: () => T): Result<T> {
+  try {
+    return Ok(fn());
+  } catch (e) {
+    return Err(e instanceof Error ? e : new Error(String(e)));
+  }
+}
+
+// Wrap an async function that might throw
+export async function tryCatchAsync<T>(fn: () => Promise<T>): Promise<Result<T>> {
+  try {
+    return Ok(await fn());
+  } catch (e) {
+    return Err(e instanceof Error ? e : new Error(String(e)));
+  }
+}