@heyramzi/utils 0.0.0-stage → 1.13.0

package/dist/crypto.js

@@ -0,0 +1,117 @@
+import { Buffer } from "node:buffer";
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+const ALGORITHM = "aes-256-gcm";
+const AUTH_TAG_BYTES = 16;
+const IV_BYTES = 12;
+const KEY_BYTES = 32;
+const KEY_ENV = "HEYRAMZI_UTILS_CRYPTO_KEY";
+const BASE64_PATTERN = /^[A-Za-z0-9+/]+={0,2}$/;
+const HEX_PATTERN = /^[0-9a-fA-F]{64}$/;
+function ensureServerEnv() {
+    const runtimeProcess = globalThis.process;
+    if (!runtimeProcess?.env) {
+        throw new Error("[crypto] process.env is unavailable. @heyramzi/utils/crypto is server-only.");
+    }
+    return runtimeProcess.env;
+}
+function decodeBase64(value, label) {
+    const normalized = value.trim();
+    if (!normalized || normalized.length % 4 !== 0 || !BASE64_PATTERN.test(normalized)) {
+        throw new Error(`[crypto] ${label} must be valid base64.`);
+    }
+    const bytes = Buffer.from(normalized, "base64");
+    if (bytes.toString("base64") !== normalized) {
+        throw new Error(`[crypto] ${label} must be valid base64.`);
+    }
+    return bytes;
+}
+function decodeSecretKey(rawValue, label) {
+    if (!rawValue) {
+        throw new Error(`[crypto] Missing ${label}. Set a 32-byte key encoded as base64 (recommended) or 64-character hex.`);
+    }
+    if (HEX_PATTERN.test(rawValue)) {
+        return Buffer.from(rawValue, "hex");
+    }
+    const key = decodeBase64(rawValue, label);
+    if (key.length !== KEY_BYTES) {
+        throw new Error(`[crypto] ${label} must decode to exactly ${KEY_BYTES} bytes for AES-256-GCM.`);
+    }
+    return key;
+}
+function getSecretKey() {
+    const env = ensureServerEnv();
+    const rawValue = env[KEY_ENV]?.trim();
+    return decodeSecretKey(rawValue ?? "", KEY_ENV);
+}
+function encryptWithKey(plaintext, key) {
+    const iv = randomBytes(IV_BYTES);
+    const cipher = createCipheriv(ALGORITHM, key, iv);
+    const ciphertext = Buffer.concat([
+        cipher.update(plaintext, "utf8"),
+        cipher.final(),
+        cipher.getAuthTag()
+    ]);
+    return {
+        ciphertext: ciphertext.toString("base64"),
+        iv: iv.toString("base64")
+    };
+}
+function decryptWithKey(ciphertext, iv, key) {
+    const ivBytes = decodeBase64(iv, "iv");
+    if (ivBytes.length !== IV_BYTES) {
+        throw new Error(`[crypto] iv must decode to exactly ${IV_BYTES} bytes.`);
+    }
+    const payload = decodeBase64(ciphertext, "ciphertext");
+    if (payload.length < AUTH_TAG_BYTES) {
+        throw new Error("[crypto] ciphertext payload is invalid.");
+    }
+    const encrypted = payload.subarray(0, -AUTH_TAG_BYTES);
+    const authTag = payload.subarray(-AUTH_TAG_BYTES);
+    try {
+        const decipher = createDecipheriv(ALGORITHM, key, ivBytes);
+        decipher.setAuthTag(authTag);
+        return Buffer.concat([
+            decipher.update(encrypted),
+            decipher.final()
+        ]).toString("utf8");
+    } catch (error) {
+        throw new Error("[crypto] Failed to decrypt secret. The payload may be tampered with or invalid.", {
+            cause: error
+        });
+    }
+}
+export function encryptSecret(plaintext) {
+    return encryptWithKey(plaintext, getSecretKey());
+}
+export function decryptSecret(ciphertext, iv) {
+    return decryptWithKey(ciphertext, iv, getSecretKey());
+}
+export function encryptSecretWithKey(plaintext, key) {
+    return encryptWithKey(plaintext, decodeSecretKey(key.trim(), "key"));
+}
+export function decryptSecretWithKey(ciphertext, iv, key) {
+    return decryptWithKey(ciphertext, iv, decodeSecretKey(key.trim(), "key"));
+}
+export function packSecret(secret) {
+    const ivBytes = decodeBase64(secret.iv, "iv");
+    if (ivBytes.length !== IV_BYTES) {
+        throw new Error(`[crypto] iv must decode to exactly ${IV_BYTES} bytes.`);
+    }
+    const ciphertextBytes = decodeBase64(secret.ciphertext, "ciphertext");
+    return Buffer.concat([
+        ivBytes,
+        ciphertextBytes
+    ]).toString("base64");
+}
+export function unpackSecret(payload) {
+    const packed = decodeBase64(payload, "payload");
+    if (packed.length < IV_BYTES + AUTH_TAG_BYTES) {
+        throw new Error("[crypto] packed payload is invalid.");
+    }
+    const iv = packed.subarray(0, IV_BYTES);
+    const ciphertext = packed.subarray(IV_BYTES);
+    return {
+        ciphertext: ciphertext.toString("base64"),
+        iv: iv.toString("base64")
+    };
+}

package/dist/error.js

@@ -0,0 +1,15 @@
+export async function fetchApi(url, options) {
+    const response = await fetch(url, {
+        headers: {
+            "Content-Type": "application/json",
+            ...options?.headers
+        },
+        ...options
+    });
+    const data = await response.json();
+    if (!response.ok) {
+        const message = data?.error ?? `Request failed (${response.status})`;
+        throw new Error(message);
+    }
+    return data;
+}

package/dist/errors/sentry/index.js

@@ -0,0 +1,15 @@
+import { buildErrorRequest } from "./protocol.js";
+export { buildErrorRequest, parseDsn, parseStack } from "./protocol.js";
+export async function captureError(input) {
+    const req = buildErrorRequest(input);
+    if (!req) return;
+    try {
+        await fetch(req.url, {
+            method: "POST",
+            headers: req.headers,
+            body: req.body
+        });
+    } catch (err) {
+        console.error("[errors] Sentry capture failed:", err);
+    }
+}

package/dist/errors/sentry/protocol.js

@@ -0,0 +1,130 @@
+export function parseDsn(dsn) {
+    const m = /^(https?):\/\/([^@/]+)@([^/]+)\/(?:.*\/)?(\d+)\/?$/.exec(dsn.trim());
+    const [, scheme, publicKey, host, projectId] = m ?? [];
+    if (!scheme || !publicKey || !host || !projectId) return null;
+    return {
+        publicKey,
+        origin: `${scheme}://${host}`,
+        projectId
+    };
+}
+function randomHex32() {
+    let out = "";
+    for(let i = 0; i < 32; i++)out += Math.floor(Math.random() * 16).toString(16);
+    return out;
+}
+const V8_FRAME = /^\s*at (?:(.+?) \()?(.+?):(\d+):(\d+)\)?\s*$/;
+export function parseStack(stack) {
+    if (!stack) return [];
+    const frames = [];
+    for (const line of stack.split("\n")){
+        const m = V8_FRAME.exec(line);
+        if (!m) continue;
+        const frame = {
+            filename: m[2],
+            lineno: Number(m[3]),
+            colno: Number(m[4])
+        };
+        if (m[1]) frame.function = m[1];
+        frames.push(frame);
+    }
+    return frames.reverse();
+}
+function describe(error) {
+    if (error instanceof Error) {
+        return {
+            type: error.name || "Error",
+            value: error.message,
+            stack: error.stack
+        };
+    }
+    if (typeof error === "string") return {
+        type: "Error",
+        value: error
+    };
+    try {
+        return {
+            type: "Error",
+            value: JSON.stringify(error)
+        };
+    } catch  {
+        return {
+            type: "Error",
+            value: String(error)
+        };
+    }
+}
+const MAX_CHAIN = 5;
+function describeChain(error) {
+    const chain = [
+        describe(error)
+    ];
+    const seen = new Set([
+        error
+    ]);
+    let next = error instanceof Error ? error.cause : undefined;
+    while(next !== undefined && next !== null && !seen.has(next) && chain.length < MAX_CHAIN){
+        seen.add(next);
+        chain.push(describe(next));
+        next = next instanceof Error ? next.cause : undefined;
+    }
+    return chain.reverse();
+}
+function cleanTags(input) {
+    const tags = {};
+    for (const [k, v] of Object.entries(input.tags ?? {})){
+        if (v !== null && v !== undefined) tags[k] = String(v);
+    }
+    if (input.surface) tags.surface = input.surface;
+    return tags;
+}
+export function buildErrorRequest(input) {
+    const dsn = parseDsn(input.dsn ?? "");
+    if (!dsn) return null;
+    const eventId = input.eventId ?? randomHex32();
+    const now = input.now ?? Date.now();
+    const values = describeChain(input.error).map(({ type, value, stack })=>{
+        const exception = {
+            type,
+            value
+        };
+        const frames = parseStack(stack);
+        if (frames.length) exception.stacktrace = {
+            frames
+        };
+        return exception;
+    });
+    const event = {
+        event_id: eventId,
+        timestamp: now / 1000,
+        platform: "javascript",
+        level: "error",
+        tags: cleanTags(input),
+        exception: {
+            values
+        }
+    };
+    if (input.release) event.release = input.release;
+    if (input.environment) event.environment = input.environment;
+    if (input.user) event.user = input.user;
+    if (input.extra) event.extra = input.extra;
+    const sentAt = new Date(now).toISOString();
+    const body = [
+        JSON.stringify({
+            event_id: eventId,
+            sent_at: sentAt,
+            dsn: input.dsn
+        }),
+        JSON.stringify({
+            type: "event"
+        }),
+        JSON.stringify(event)
+    ].join("\n");
+    return {
+        url: `${dsn.origin}/api/${dsn.projectId}/envelope/?sentry_key=${dsn.publicKey}&sentry_version=7`,
+        headers: {
+            "Content-Type": "application/x-sentry-envelope"
+        },
+        body
+    };
+}

package/dist/errors/sentry/sveltekit.js

@@ -0,0 +1,145 @@
+import { captureError } from "./index.js";
+const LOCAL_HOSTS = new Set([
+    "localhost",
+    "127.0.0.1",
+    "[::1]"
+]);
+export function shouldReport({ kind, error }) {
+    if (kind === "app") return false;
+    if (kind === "unknown") return true;
+    const status = error?.status;
+    return typeof status === "number" ? status >= 500 : true;
+}
+const STALE_CHUNK = /Failed to fetch dynamically imported module|Importing a module script failed|error loading dynamically imported module/;
+export function isStaleChunk(error) {
+    const message = error?.message;
+    return typeof message === "string" && STALE_CHUNK.test(message);
+}
+const RELOAD_KEY = "heyramzi:stale-chunk-reload";
+const RELOAD_WINDOW_MS = 30_000;
+function browserEnv() {
+    try {
+        return {
+            storage: sessionStorage,
+            now: Date.now,
+            reload: ()=>location.reload()
+        };
+    } catch  {
+        return null;
+    }
+}
+export function reloadForStaleChunk(env = browserEnv()) {
+    if (!env) return false;
+    try {
+        const last = Number(env.storage.getItem(RELOAD_KEY));
+        if (env.now() - last < RELOAD_WINDOW_MS) return false;
+        env.storage.setItem(RELOAD_KEY, String(env.now()));
+        env.reload();
+        return true;
+    } catch  {
+        return false;
+    }
+}
+function toError(raw) {
+    if (raw instanceof Error) return raw;
+    const message = raw?.message;
+    return typeof message === "string" ? new Error(message) : raw;
+}
+const STACK_LINES = 8;
+export function devErrorDetails(error) {
+    if (!(error instanceof Error)) {
+        const message = error?.message;
+        if (typeof message === "string") return {
+            message
+        };
+        try {
+            return {
+                message: typeof error === "object" ? JSON.stringify(error) : String(error)
+            };
+        } catch  {
+            return {
+                message: String(error)
+            };
+        }
+    }
+    const header = String(error);
+    const stack = error.stack?.startsWith(header) ? error.stack.slice(header.length) : error.stack;
+    const frames = stack?.split("\n").map((line)=>line.trim()).filter(Boolean).slice(0, STACK_LINES);
+    return {
+        message: error.message,
+        stack: frames?.length ? frames.join("\n") : undefined
+    };
+}
+function isLocalHost(input) {
+    return LOCAL_HOSTS.has(input.event.url.hostname);
+}
+async function report(options, input, extraTags) {
+    const { dsn, dev, release, surface, environment = "production", tags } = options;
+    if (dev || !dsn || isLocalHost(input)) return;
+    await captureError({
+        dsn,
+        error: toError(input.error),
+        surface,
+        release,
+        environment,
+        tags: {
+            ...tags,
+            ...extraTags,
+            route: input.event.route.id
+        },
+        extra: {
+            pathname: input.event.url.pathname,
+            kind: input.kind
+        }
+    });
+}
+async function respondTo(options, input) {
+    if (!options.respond) return undefined;
+    try {
+        return await options.respond(input);
+    } catch (err) {
+        console.error("[handleError] respond threw:", err);
+        return undefined;
+    }
+}
+async function answer(options, input) {
+    const body = await respondTo(options, input);
+    if (!options.dev || !shouldReport(input)) return body;
+    return {
+        ...body,
+        ...devErrorDetails(input.error)
+    };
+}
+export function createHandleClientError(options) {
+    return async (input)=>{
+        try {
+            let tags;
+            if (isStaleChunk(input.error)) {
+                if (reloadForStaleChunk()) return respondTo(options, input);
+                tags = {
+                    stale_chunk: true
+                };
+            }
+            if (shouldReport(input)) {
+                if (options.log !== false) console.error("[handleError]", input.error);
+                if (!await options.skip?.(input)) await report(options, input, tags);
+            }
+        } catch (err) {
+            console.error("[handleError] reporting failed:", err);
+        }
+        return answer(options, input);
+    };
+}
+export function createHandleServerError(options) {
+    return async (input)=>{
+        try {
+            if (shouldReport(input)) {
+                if (options.log !== false) console.error("[handleError]", toError(input.error));
+                await report(options, input);
+            }
+        } catch (err) {
+            console.error("[handleError] reporting failed:", err);
+        }
+        return answer(options, input);
+    };
+}

package/dist/format.js

@@ -0,0 +1,62 @@
+export function formatDate(date, locale = "en-US") {
+    if (!date) return "-";
+    const dateValue = typeof date === "string" && /^\d+$/.test(date) ? parseInt(date, 10) : date;
+    const parsed = new Date(dateValue);
+    if (Number.isNaN(parsed.getTime())) return "-";
+    return parsed.toLocaleDateString(locale, {
+        month: "short",
+        day: "numeric",
+        year: "numeric"
+    });
+}
+export function formatCurrency(value, currency = "USD", locale) {
+    if (!value) return "-";
+    const resolvedLocale = locale ?? (currency.toUpperCase() === "EUR" ? "fr-FR" : "en-US");
+    return new Intl.NumberFormat(resolvedLocale, {
+        style: "currency",
+        currency: currency.toUpperCase(),
+        minimumFractionDigits: 0
+    }).format(value);
+}
+export function formatAmount(cents, currency, locale = "en-US") {
+    return new Intl.NumberFormat(locale, {
+        style: "currency",
+        currency: currency.toUpperCase(),
+        minimumFractionDigits: 2
+    }).format(cents / 100);
+}
+const DEFAULT_LABELS = {
+    today: "Today",
+    yesterday: "Yesterday",
+    daysAgo: "{n} days ago",
+    weeksAgo: "{n} weeks ago",
+    monthsAgo: "{n} months ago",
+    yearsAgo: "{n} years ago",
+    weekAgo: "1 week ago",
+    monthAgo: "1 month ago",
+    yearAgo: "1 year ago"
+};
+export function formatRelativeTime(date, labels = DEFAULT_LABELS) {
+    if (!date) return "-";
+    const dateValue = typeof date === "string" && /^\d+$/.test(date) ? parseInt(date, 10) : date;
+    const parsed = new Date(dateValue);
+    if (Number.isNaN(parsed.getTime())) return "-";
+    const diffMs = Date.now() - parsed.getTime();
+    const diffDays = Math.floor(diffMs / (1000 * 60 * 60 * 24));
+    if (diffDays === 0) return labels.today;
+    if (diffDays === 1) return labels.yesterday;
+    if (diffDays < 7) return labels.daysAgo.replace("{n}", String(diffDays));
+    if (diffDays < 30) {
+        const weeks = Math.floor(diffDays / 7);
+        if (weeks === 1 && labels.weekAgo) return labels.weekAgo;
+        return labels.weeksAgo.replace("{n}", String(weeks));
+    }
+    if (diffDays < 365) {
+        const months = Math.floor(diffDays / 30);
+        if (months === 1 && labels.monthAgo) return labels.monthAgo;
+        return labels.monthsAgo.replace("{n}", String(months));
+    }
+    const years = Math.floor(diffDays / 365);
+    if (years === 1 && labels.yearAgo) return labels.yearAgo;
+    return labels.yearsAgo.replace("{n}", String(years));
+}

package/dist/grab.js

@@ -0,0 +1,112 @@
+/**
+ * Alt+Click any element in a Svelte 5 dev build to copy its HTML and component stack for a coding agent.
+ */
+
+/*
+ * Usage in +layout.svelte: if (dev) import("@heyramzi/utils/grab");
+ */
+
+/*
+ * Plain JS with no imports, so a page can also inline this file as a <script type="module">.
+ */
+
+const MAX_HTML = 400;
+
+/** @param {Element} el */
+function sourceOf(el) {
+  /** @type {Element | null} */
+  let node = el;
+  while (node && !(/** @type {any} */ (node).__svelte_meta)) node = node.parentElement;
+  return node ? /** @type {any} */ (node).__svelte_meta : null;
+}
+
+/** @param {{ file: string, line: number, column: number }} at */
+function where(at) {
+  return `${at.file}:${at.line}:${at.column}`;
+}
+
+/** @param {Element} el */
+function describe(el) {
+  // Svelte's hydration markers are <!----> comments, noise to an agent.
+  const full = el.outerHTML.replace(/<!--[^]*?-->/g, "");
+  const html = full.length > MAX_HTML ? `${full.slice(0, MAX_HTML)}…` : full;
+  const meta = sourceOf(el);
+  if (!meta) return html;
+
+  const lines = [html, `  at ${where(meta.loc)}`];
+  for (let entry = meta.parent; entry; entry = entry.parent) {
+    if (entry.type === "component") lines.push(`  in <${entry.componentTag}> at ${where(entry)}`);
+  }
+  return lines.join("\n");
+}
+
+/** @param {Element} el */
+function label(el) {
+  const meta = sourceOf(el);
+  let entry = meta?.parent;
+  while (entry && entry.type !== "component") entry = entry.parent;
+  const name = entry ? `<${entry.componentTag}>` : el.tagName.toLowerCase();
+  return meta ? `${name}  ${meta.loc.file.split("/").pop()}:${meta.loc.line}` : name;
+}
+
+function start() {
+  const box = document.createElement("div");
+  const tag = document.createElement("div");
+  box.style.cssText =
+    "position:fixed;pointer-events:none;z-index:2147483647;border:2px solid #7c3aed;background:rgb(124 58 237 / 0.08);border-radius:3px;display:none";
+  tag.style.cssText =
+    "position:absolute;left:-2px;bottom:100%;margin-bottom:4px;padding:2px 6px;font:12px/1.4 ui-monospace,monospace;color:#fff;background:#7c3aed;border-radius:3px;white-space:nowrap";
+  box.append(tag);
+  document.body.append(box);
+
+  /** @type {Element | null} */
+  let target = null;
+
+  /** @param {Element | null} el */
+  function show(el) {
+    target = el;
+    if (!el) {
+      box.style.display = "none";
+      return;
+    }
+    const r = el.getBoundingClientRect();
+    Object.assign(box.style, {
+      display: "block",
+      left: `${r.left}px`,
+      top: `${r.top}px`,
+      width: `${r.width}px`,
+      height: `${r.height}px`,
+    });
+    tag.textContent = label(el);
+  }
+
+  /** @param {MouseEvent} e */
+  function onMove(e) {
+    show(e.altKey ? document.elementFromPoint(e.clientX, e.clientY) : null);
+  }
+
+  /** @param {MouseEvent} e */
+  function onClick(e) {
+    if (!e.altKey || !target) return;
+    // Option+click on a link downloads it in Chrome, so the click is swallowed here.
+    e.preventDefault();
+    e.stopImmediatePropagation();
+    if (e.type !== "click") return;
+    navigator.clipboard.writeText(describe(target)).then(() => {
+      tag.textContent = "Copied";
+    });
+  }
+
+  addEventListener("mousemove", onMove, true);
+  addEventListener("mousedown", onClick, true);
+  addEventListener("click", onClick, true);
+  addEventListener("keyup", (e) => e.key === "Alt" && show(null), true);
+  addEventListener("blur", () => show(null));
+}
+
+const w = /** @type {any} */ (globalThis);
+if (typeof document !== "undefined" && !w.__heyramziGrab) {
+  w.__heyramziGrab = true;
+  if (document.body) start();
+  else addEventListener("DOMContentLoaded", start);
+}

package/dist/index.js

@@ -0,0 +1,10 @@
+export { cn } from "./cn.js";
+export { formatDate, formatCurrency, formatAmount, formatRelativeTime } from "./format.js";
+export { slugify, generateSlug, buildSearchParams, parseJSON, parseCommaSeparatedList, matchesQuery } from "./string.js";
+export { fetchApi } from "./error.js";
+export { isCacheExpired } from "./cache.js";
+export { Ok, Err, tryCatch, tryCatchAsync } from "./result.js";
+export { setLogger, log } from "./logger.js";
+export { debounce, throttle, sleep } from "./timing.js";
+export { clamp } from "./math.js";
+export { groupBy } from "./collection.js";

package/dist/logger.js

@@ -0,0 +1,22 @@
+let _logger = null;
+export function setLogger(logger) {
+    _logger = logger;
+}
+export function log(level, message, data) {
+    if (!_logger) return;
+    const entry = {
+        level,
+        message,
+        ...data
+    };
+    try {
+        const result = _logger.log(entry);
+        if (result instanceof Promise) {
+            result.catch((err)=>{
+                console.error("[logs] Logger failed:", err);
+            });
+        }
+    } catch (err) {
+        console.error("[logs] Logger failed:", err);
+    }
+}

package/dist/math.js

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

package/dist/og/fonts.js

@@ -0,0 +1,46 @@
+import { readFileSync } from "node:fs";
+import { tryCatch, tryCatchAsync } from "../result.js";
+const cache = new Map();
+function readRaw(path) {
+    const result = tryCatch(()=>readFileSync(path));
+    return result.ok ? result.value : null;
+}
+function toArrayBuffer(bytes) {
+    const out = new ArrayBuffer(bytes.byteLength);
+    new Uint8Array(out).set(bytes);
+    return out;
+}
+async function decodeFont(path) {
+    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;
+}
+export async function loadFonts(configs) {
+    const decoded = [];
+    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/dist/og/index.js

@@ -0,0 +1,3 @@
+export { renderImage, MIME_TYPES } from "./renderer.js";
+export { loadFonts } from "./fonts.js";
+export { html, raw } from "./markup.js";