@sprqvntrs/helpers 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 SPRQVNTRS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,28 @@
+# @sprqvntrs/helpers
+
+Common helper utilities for the SPRQVNTRS platform: date, environment, number, string
+and timing helpers.
+
+## Install
+
+```bash
+pnpm add @sprqvntrs/helpers
+```
+
+## Usage
+
+```ts
+import { requireEnv, formatNumber } from '@sprqvntrs/helpers';
+```
+
+See `src/` for the full surface.
+
+## Raw TypeScript
+
+This package ships raw TypeScript (`main` and `types` point at `index.ts`), so a Vite
+consumer (Vite, React Router, Remix) must add the scope to `ssr.noExternal`:
+`ssr: { noExternal: [/^@sprqvntrs\//] }`.
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,38 @@
+/**
+ * @sprqvntrs/helpers
+ *
+ * Common helper utilities for the SPRQVNTRS platform.
+ *
+ * @packageDocumentation
+ */
+
+// =============================================================================
+// Environment Helpers
+// =============================================================================
+
+export { requireEnv, optionalEnv, optionalBoolEnv, optionalIntEnv } from './src/env';
+
+// =============================================================================
+// String Helpers
+// =============================================================================
+
+export { slugify, normalizeEuropeanChars, generateRandomString } from './src/string';
+
+// =============================================================================
+// Date Helpers
+// =============================================================================
+
+export { slugifyDate, daysAgo } from './src/date';
+
+// =============================================================================
+// Timing Helpers
+// =============================================================================
+
+export { measureExecutionTime } from './src/timing';
+
+// =============================================================================
+// Number Helpers
+// =============================================================================
+
+export { formatNumber, formatDecimal, formatInteger, formatSmart } from './src/number';
+export type { NumberFormatOptions } from './src/number';

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@sprqvntrs/helpers",
+  "version": "0.2.0",
+  "description": "Common helper utilities for the SPRQVNTRS platform",
+  "type": "module",
+  "main": "./index.ts",
+  "types": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SPRQVNTRS/platform.git",
+    "directory": "packages/helpers"
+  },
+  "files": [
+    "src/**/*",
+    "index.ts",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/SPRQVNTRS/platform/tree/main/packages/helpers#readme",
+  "bugs": {
+    "url": "https://github.com/SPRQVNTRS/platform/issues"
+  }
+}

package/src/date.ts

@@ -0,0 +1,58 @@
+/**
+ * Date manipulation helper functions
+ */
+
+/**
+ * Formats a date string to a URL-friendly slug format (YYYY-MM-DD).
+ *
+ * Parses the input date and returns it in ISO date format,
+ * suitable for use in URLs, filenames, or database queries.
+ *
+ * @param date - A date string parseable by `new Date()`
+ * @returns The date formatted as YYYY-MM-DD
+ *
+ * @example
+ * ```typescript
+ * slugifyDate('2024-03-15T10:30:00Z');
+ * // => '2024-03-15'
+ *
+ * slugifyDate('March 15, 2024');
+ * // => '2024-03-15'
+ *
+ * slugifyDate('2024/03/15');
+ * // => '2024-03-15'
+ * ```
+ */
+export function slugifyDate(date: string): string {
+  const dateObj = new Date(date);
+  return dateObj.toISOString().split('T')[0]!;
+}
+
+/**
+ * Calculates the number of days between a given date and today.
+ *
+ * Returns a positive number for dates in the past, representing
+ * how many days ago the date occurred.
+ *
+ * @param date - A date string parseable by `new Date()`
+ * @returns The number of whole days between the date and now
+ *
+ * @example
+ * ```typescript
+ * // If today is 2024-03-15:
+ * daysAgo('2024-03-10');
+ * // => 5
+ *
+ * daysAgo('2024-03-14');
+ * // => 1
+ *
+ * daysAgo('2024-03-15');
+ * // => 0
+ * ```
+ */
+export function daysAgo(date: string): number {
+  const now = new Date();
+  const fixtureDate = new Date(date);
+  const diff = now.getTime() - fixtureDate.getTime();
+  return Math.floor(diff / (1000 * 60 * 60 * 24));
+}

package/src/env.ts

@@ -0,0 +1,60 @@
+/**
+ * Environment variable helper functions
+ */
+
+/**
+ * Ensures a required environment variable exists
+ * @throws Error if the environment variable is not set
+ */
+export function requireEnv(key: string): string {
+  const value = process.env[key];
+  if (!value) {
+    throw new Error(
+      `Missing required environment variable: ${key}\n` +
+        `Please ensure ${key} is set in your .env file or environment.`,
+    );
+  }
+  return value;
+}
+
+/**
+ * Gets an optional environment variable with a default value
+ */
+export function optionalEnv(key: string, defaultValue: string): string {
+  return process.env[key] || defaultValue;
+}
+
+/**
+ * Gets an optional boolean environment variable
+ */
+export function optionalBoolEnv(key: string, defaultValue: boolean): boolean {
+  const value = process.env[key];
+  if (!value) return defaultValue;
+  return value.toLowerCase() === 'true';
+}
+
+/**
+ * Gets an optional integer environment variable.
+ *
+ * Parses the environment variable as a base-10 integer.
+ * Returns the default value if the variable is not set or cannot be parsed.
+ *
+ * @param key - The environment variable name
+ * @param defaultValue - The value to return if the variable is not set or invalid
+ * @returns The parsed integer or the default value
+ *
+ * @example
+ * ```typescript
+ * const port = optionalIntEnv('PORT', 3000);
+ * // => 8080 if PORT=8080, or 3000 if not set
+ *
+ * const workers = optionalIntEnv('WORKER_COUNT', 4);
+ * // => 4 if WORKER_COUNT is not set or invalid
+ * ```
+ */
+export function optionalIntEnv(key: string, defaultValue: number): number {
+  const value = process.env[key];
+  if (!value) return defaultValue;
+  const parsed = parseInt(value, 10);
+  return isNaN(parsed) ? defaultValue : parsed;
+}

package/src/number.test.ts

@@ -0,0 +1,146 @@
+import { describe, it, expect } from 'vitest';
+import { formatNumber, formatDecimal, formatInteger, formatSmart } from './number';
+
+// ---------------------------------------------------------------------------
+// formatNumber
+// ---------------------------------------------------------------------------
+
+describe('formatNumber', () => {
+  describe('decimal separator localisation', () => {
+    it('formats 3.6 with de locale using comma decimal', () => {
+      expect(formatNumber(3.6, 'de', { maximumFractionDigits: 1 })).toBe('3,6');
+    });
+
+    it('formats 3.6 with en locale using period decimal', () => {
+      expect(formatNumber(3.6, 'en', { maximumFractionDigits: 1 })).toBe('3.6');
+    });
+
+    it('accepts a full BCP-47 tag (de-DE) in place of a short code', () => {
+      expect(formatNumber(3.6, 'de-DE', { maximumFractionDigits: 1 })).toBe('3,6');
+    });
+  });
+
+  describe('collapse behaviour with maximumFractionDigits: 1', () => {
+    it('rounds 0.001 to "0" for de locale', () => {
+      expect(formatNumber(0.001, 'de', { maximumFractionDigits: 1 })).toBe('0');
+    });
+
+    it('rounds 0.001 to "0" for en locale', () => {
+      expect(formatNumber(0.001, 'en', { maximumFractionDigits: 1 })).toBe('0');
+    });
+  });
+
+  describe('integers are unchanged', () => {
+    it('formats 100 with de locale and maximumFractionDigits: 1', () => {
+      expect(formatNumber(100, 'de', { maximumFractionDigits: 1 })).toBe('100');
+    });
+
+    it('formats 49 with en locale and maximumFractionDigits: 1', () => {
+      expect(formatNumber(49, 'en', { maximumFractionDigits: 1 })).toBe('49');
+    });
+  });
+
+  describe('grouping separators', () => {
+    it('uses period as thousands separator for de locale', () => {
+      expect(formatNumber(1234.56, 'de')).toBe('1.234,56');
+    });
+
+    it('uses comma as thousands separator for en locale', () => {
+      expect(formatNumber(1234.56, 'en')).toBe('1,234.56');
+    });
+
+    it('uses space (possibly narrow no-break) as thousands separator for fr locale', () => {
+      // Node ICU may emit U+202F (narrow no-break space) — normalise all whitespace
+      const result = formatNumber(1234.5, 'fr', { maximumFractionDigits: 1 }).replace(/\s/g, ' ');
+      expect(result).toMatch(/1 ?234,5/);
+    });
+  });
+
+  describe('zero', () => {
+    it('formats 0 as "0" for de', () => {
+      expect(formatNumber(0, 'de')).toBe('0');
+    });
+
+    it('formats 0 as "0" for en', () => {
+      expect(formatNumber(0, 'en')).toBe('0');
+    });
+
+    it('formats 0 as "0" for fr', () => {
+      expect(formatNumber(0, 'fr')).toBe('0');
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// formatDecimal
+// ---------------------------------------------------------------------------
+
+describe('formatDecimal', () => {
+  it('formats 5 with 1 decimal place for de locale', () => {
+    expect(formatDecimal(5, 'de', 1)).toBe('5,0');
+  });
+
+  it('formats 5 with 1 decimal place for en locale', () => {
+    expect(formatDecimal(5, 'en', 1)).toBe('5.0');
+  });
+
+  it('defaults to 1 decimal place when decimals is omitted', () => {
+    expect(formatDecimal(5, 'en')).toBe('5.0');
+  });
+
+  it('preserves trailing zeros to fill fixed precision', () => {
+    expect(formatDecimal(3, 'en', 2)).toBe('3.00');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// formatInteger
+// ---------------------------------------------------------------------------
+
+describe('formatInteger', () => {
+  it('rounds 52.7 to 53 for de locale', () => {
+    expect(formatInteger(52.7, 'de')).toBe('53');
+  });
+
+  it('adds period thousands separator for de locale on 1300', () => {
+    expect(formatInteger(1300, 'de')).toBe('1.300');
+  });
+
+  it('adds comma thousands separator for en locale on 1300', () => {
+    expect(formatInteger(1300, 'en')).toBe('1,300');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// formatSmart
+// ---------------------------------------------------------------------------
+
+describe('formatSmart', () => {
+  it('formats values >= 100 as an integer (0 decimal places)', () => {
+    expect(formatSmart(250, 'en')).toBe('250');
+  });
+
+  it('formats values >= 10 with 1 decimal place', () => {
+    expect(formatSmart(42.37, 'en')).toBe('42.4');
+  });
+
+  it('formats values >= 1 with 2 decimal places', () => {
+    expect(formatSmart(4.378, 'en')).toBe('4.38');
+  });
+
+  it('formats values >= 0.01 with 3 decimal places', () => {
+    expect(formatSmart(0.045, 'en')).toBe('0.045');
+  });
+
+  it('formats values < 0.01 with 4 decimal places', () => {
+    expect(formatSmart(0.0012, 'en')).toBe('0.0012');
+  });
+
+  it('formats 0 with 4 decimal places for de (0 < 0.01 threshold)', () => {
+    expect(formatSmart(0, 'de')).toBe('0,0000');
+  });
+
+  it('formats 0 with 4 decimal places for en (0 < 0.01 threshold)', () => {
+    expect(formatSmart(0, 'en')).toBe('0.0000');
+  });
+});

package/src/number.ts

@@ -0,0 +1,161 @@
+/**
+ * Locale-aware number formatting helper functions.
+ *
+ * A thin wrapper around `Intl.NumberFormat` that produces locale-correct decimal
+ * and grouping separators on both server and client. Mirrors the API of the
+ * `remix-lcc` `useNumberFormat` hook so that server-side content rendering and
+ * scripts produce identical output without requiring a React context.
+ *
+ * ### Accepted locale values
+ *
+ * The `locale` parameter accepts any value that `Intl.NumberFormat` understands:
+ * - Short IANA subtag: `'en'`, `'de'`, `'fr'`
+ * - Full BCP-47 tag: `'de-DE'`, `'fr-FR'`, `'es-ES'`
+ *
+ * Both forms are equivalent — `Intl` normalises them internally.
+ *
+ * ### Decimal and grouping separator reference
+ *
+ * | Locale              | Example output       |
+ * |---------------------|----------------------|
+ * | `en` / `en-US`      | `1,234.56` (comma group, period decimal) |
+ * | `de` / `es` / `it` / `nl` | `1.234,56` (period group, comma decimal) |
+ * | `fr` / `fr-FR`      | `1 234,56` (narrow no-break space group, comma decimal) |
+ *
+ * @module number
+ */
+
+/**
+ * Re-export of `Intl.NumberFormatOptions` for consumers that want to type
+ * options objects without importing from `lib.es2015.intl.d.ts` directly.
+ */
+export type NumberFormatOptions = Intl.NumberFormatOptions;
+
+/**
+ * Formats a number using the given locale and optional `Intl.NumberFormat` options.
+ *
+ * This is the lowest-level formatter — it delegates directly to `Intl.NumberFormat`
+ * with no opinion on precision. Use the higher-level helpers (`formatDecimal`,
+ * `formatInteger`, `formatSmart`) for consistent precision behaviour.
+ *
+ * **Collapse behaviour:** passing `{ maximumFractionDigits: 1 }` both localises
+ * the decimal separator AND silently rounds very small values to zero
+ * (e.g. `0.001` → `"0"`). This is the intended behaviour for the LCC content
+ * pipeline, where trace nutrient amounts should display as `"0"` rather than
+ * scientific notation.
+ *
+ * @param value - The number to format
+ * @param locale - IANA locale subtag (`'de'`) or BCP-47 tag (`'de-DE'`)
+ * @param options - Optional `Intl.NumberFormat` options (precision, style, etc.)
+ * @returns The locale-formatted string
+ *
+ * @example
+ * ```typescript
+ * formatNumber(1234.56, 'en');
+ * // => '1,234.56'
+ *
+ * formatNumber(1234.56, 'de');
+ * // => '1.234,56'
+ *
+ * formatNumber(3.6, 'de', { maximumFractionDigits: 1 });
+ * // => '3,6'
+ *
+ * // Collapse: maximumFractionDigits rounds 0.001 to "0"
+ * formatNumber(0.001, 'en', { maximumFractionDigits: 1 });
+ * // => '0'
+ * ```
+ */
+export function formatNumber(value: number, locale: string, options?: Intl.NumberFormatOptions): string {
+  return new Intl.NumberFormat(locale, options).format(value);
+}
+
+/**
+ * Formats a number with a fixed number of decimal places using the given locale.
+ *
+ * Both `minimumFractionDigits` and `maximumFractionDigits` are set to `decimals`,
+ * so trailing zeros are always preserved (e.g. `5` → `'5.0'` at one decimal place).
+ *
+ * @param value - The number to format
+ * @param locale - IANA locale subtag (`'de'`) or BCP-47 tag (`'de-DE'`)
+ * @param decimals - Number of decimal places to show (default `1`)
+ * @returns The locale-formatted string with exactly `decimals` fraction digits
+ *
+ * @example
+ * ```typescript
+ * formatDecimal(5, 'en', 1);
+ * // => '5.0'
+ *
+ * formatDecimal(5, 'de', 1);
+ * // => '5,0'
+ *
+ * formatDecimal(3.14159, 'en', 2);
+ * // => '3.14'
+ * ```
+ */
+export function formatDecimal(value: number, locale: string, decimals: number = 1): string {
+  return new Intl.NumberFormat(locale, {
+    minimumFractionDigits: decimals,
+    maximumFractionDigits: decimals,
+  }).format(value);
+}
+
+/**
+ * Rounds a number to the nearest integer and formats it with no decimal places.
+ *
+ * Grouping separators are applied according to the locale (e.g. `1300` → `'1.300'`
+ * in German, `'1,300'` in English).
+ *
+ * @param value - The number to format (will be rounded with `Math.round`)
+ * @param locale - IANA locale subtag (`'de'`) or BCP-47 tag (`'de-DE'`)
+ * @returns The locale-formatted integer string
+ *
+ * @example
+ * ```typescript
+ * formatInteger(52.7, 'de');
+ * // => '53'
+ *
+ * formatInteger(1300, 'de');
+ * // => '1.300'
+ *
+ * formatInteger(1300, 'en');
+ * // => '1,300'
+ * ```
+ */
+export function formatInteger(value: number, locale: string): string {
+  return new Intl.NumberFormat(locale, { maximumFractionDigits: 0 }).format(Math.round(value));
+}
+
+/**
+ * Formats a number with magnitude-based precision using the given locale.
+ *
+ * Selects the number of decimal places based on the raw (non-absolute) value,
+ * matching the precision thresholds of the `remix-lcc` `useNumberFormat` hook:
+ *
+ * | Value range | Decimal places | Example (`en`) |
+ * |-------------|----------------|----------------|
+ * | `>= 100`    | 0 (integer)    | `250` → `'250'` |
+ * | `>= 10`     | 1              | `42.37` → `'42.4'` |
+ * | `>= 1`      | 2              | `4.378` → `'4.38'` |
+ * | `>= 0.01`   | 3              | `0.045` → `'0.045'` |
+ * | `< 0.01`    | 4              | `0.0012` → `'0.0012'` |
+ *
+ * @param value - The number to format
+ * @param locale - IANA locale subtag (`'de'`) or BCP-47 tag (`'de-DE'`)
+ * @returns The locale-formatted string with magnitude-appropriate precision
+ *
+ * @example
+ * ```typescript
+ * formatSmart(250, 'en');    // => '250'
+ * formatSmart(42.37, 'en'); // => '42.4'
+ * formatSmart(4.378, 'en'); // => '4.38'
+ * formatSmart(0.045, 'en'); // => '0.045'
+ * formatSmart(0.0012, 'en'); // => '0.0012'
+ * ```
+ */
+export function formatSmart(value: number, locale: string): string {
+  if (value >= 100) return formatInteger(value, locale);
+  if (value >= 10) return formatDecimal(value, locale, 1);
+  if (value >= 1) return formatDecimal(value, locale, 2);
+  if (value >= 0.01) return formatDecimal(value, locale, 3);
+  return formatDecimal(value, locale, 4);
+}

package/src/string.ts

@@ -0,0 +1,208 @@
+/**
+ * String manipulation helper functions
+ */
+
+const slugifyCharMap: Record<string, string> = {
+  ä: 'a',
+  ö: 'o',
+  ü: 'u',
+  ß: 'ss',
+  Ä: 'A',
+  Ö: 'O',
+  Ü: 'U',
+  é: 'e',
+  è: 'e',
+  ê: 'e',
+  ë: 'e',
+  ç: 'c',
+  à: 'a',
+  â: 'a',
+  ô: 'o',
+  ù: 'u',
+  û: 'u',
+  î: 'i',
+  ï: 'i',
+  É: 'E',
+  È: 'E',
+  Ê: 'E',
+  Ë: 'E',
+  Ç: 'C',
+  À: 'A',
+  Â: 'A',
+  Ô: 'O',
+  Ù: 'U',
+  Û: 'U',
+  Î: 'I',
+  Ï: 'I',
+};
+
+/**
+ * Converts a string to a URL-friendly slug.
+ *
+ * Handles special characters, diacritics, and European characters by
+ * normalizing them to ASCII equivalents.
+ *
+ * @param text - The string to slugify
+ * @returns A lowercase, hyphenated slug safe for URLs
+ *
+ * @example
+ * ```typescript
+ * slugify('Hello World!');
+ * // => 'hello-world'
+ *
+ * slugify('Café München');
+ * // => 'cafe-munchen'
+ *
+ * slugify('Products / Services');
+ * // => 'products-services'
+ * ```
+ */
+export function slugify(text: string): string {
+  return (
+    text
+      .normalize('NFD')
+      .replace(/[\u0300-\u036f]/g, '')
+      .replace(/\//g, '-')
+      .replace(/[^a-zA-Z0-9\s]/g, (ch) => slugifyCharMap[ch] || ch)
+      .toLowerCase()
+      .replace(/[\s.]+/g, '-')
+      .replace(/[^\w-]+/g, '')
+      .replace(/[-]+/g, '-')
+      .replace(/^-+/, '')
+      .replace(/-+$/, '')
+  );
+}
+
+const europeanCharMap: Record<string, string> = {
+  // Lowercase letters
+  à: 'a',
+  á: 'a',
+  â: 'a',
+  ã: 'a',
+  ä: 'ae',
+  å: 'a',
+  ā: 'a',
+  è: 'e',
+  é: 'e',
+  ê: 'e',
+  ë: 'e',
+  ē: 'e',
+  ì: 'i',
+  í: 'i',
+  î: 'i',
+  ï: 'i',
+  ī: 'i',
+  ı: 'i',
+  ò: 'o',
+  ó: 'o',
+  ô: 'o',
+  õ: 'o',
+  ö: 'oe',
+  ō: 'o',
+  ù: 'u',
+  ú: 'u',
+  û: 'u',
+  ü: 'ue',
+  ū: 'u',
+  ý: 'y',
+  ÿ: 'y',
+  ñ: 'n',
+  ń: 'n',
+  ß: 'ss',
+  ç: 'c',
+  ş: 's',
+  š: 's',
+  ś: 's',
+
+  // Uppercase letters
+  À: 'A',
+  Á: 'A',
+  Â: 'A',
+  Ã: 'A',
+  Ä: 'AE',
+  Å: 'A',
+  Ā: 'A',
+  È: 'E',
+  É: 'E',
+  Ê: 'E',
+  Ë: 'E',
+  Ē: 'E',
+  Ì: 'I',
+  Í: 'I',
+  Î: 'I',
+  Ï: 'I',
+  Ī: 'I',
+  İ: 'I',
+  Ò: 'O',
+  Ó: 'O',
+  Ô: 'O',
+  Õ: 'O',
+  Ö: 'OE',
+  Ō: 'O',
+  Ù: 'U',
+  Ú: 'U',
+  Û: 'U',
+  Ü: 'UE',
+  Ū: 'U',
+  Ý: 'Y',
+  Ñ: 'N',
+  Ń: 'N',
+  Ç: 'C',
+  Ş: 'S',
+  Š: 'S',
+  Ś: 'S',
+};
+
+/**
+ * Normalizes European characters to their ASCII equivalents.
+ *
+ * Unlike `slugify`, this preserves the original casing and spacing,
+ * only replacing accented/special characters with their closest ASCII representation.
+ * German umlauts are expanded (ä → ae, ö → oe, ü → ue).
+ *
+ * @param text - The string containing European characters
+ * @returns The string with European characters replaced by ASCII equivalents
+ *
+ * @example
+ * ```typescript
+ * normalizeEuropeanChars('Müller');
+ * // => 'Mueller'
+ *
+ * normalizeEuropeanChars('François Château');
+ * // => 'Francois Chateau'
+ *
+ * normalizeEuropeanChars('Straße');
+ * // => 'Strasse'
+ * ```
+ */
+export function normalizeEuropeanChars(text: string): string {
+  return text.replace(/[^\u0000-\u007F]/g, (char) => europeanCharMap[char] || char);
+}
+
+/**
+ * Generates a random alphanumeric string of the specified length.
+ *
+ * Uses uppercase letters, lowercase letters, and digits (A-Z, a-z, 0-9).
+ * Note: This is not cryptographically secure; use `crypto.randomBytes`
+ * for security-sensitive applications.
+ *
+ * @param length - The desired length of the random string
+ * @returns A random alphanumeric string
+ *
+ * @example
+ * ```typescript
+ * generateRandomString(8);
+ * // => 'xK9mPq2L' (example output)
+ *
+ * generateRandomString(16);
+ * // => 'aBcDeFgH12345678' (example output)
+ * ```
+ */
+export function generateRandomString(length: number): string {
+  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+  let result = '';
+  for (let i = 0; i < length; i++) {
+    result += chars.charAt(Math.floor(Math.random() * chars.length));
+  }
+  return result;
+}

package/src/timing.ts

@@ -0,0 +1,44 @@
+/**
+ * Timing and performance helper functions
+ */
+
+/**
+ * Measures the execution time of a synchronous or asynchronous function.
+ *
+ * Wraps a function call and returns both its result and the time taken
+ * to execute in milliseconds. Useful for performance profiling and logging.
+ *
+ * @typeParam T - The return type of the function being measured
+ * @param fn - The function to measure (can be sync or async)
+ * @returns A tuple containing [result, executionTimeMs]
+ *
+ * @example
+ * ```typescript
+ * // Measure a synchronous function
+ * const [sum, timeMs] = await measureExecutionTime(() => {
+ *   return Array.from({ length: 1000000 }, (_, i) => i).reduce((a, b) => a + b, 0);
+ * });
+ * console.log(`Sum: ${sum}, took ${timeMs}ms`);
+ *
+ * // Measure an async function
+ * const [data, fetchTime] = await measureExecutionTime(async () => {
+ *   const response = await fetch('https://api.example.com/data');
+ *   return response.json();
+ * });
+ * console.log(`Fetched ${data.length} items in ${fetchTime}ms`);
+ *
+ * // Use with existing async functions
+ * const [user, queryTime] = await measureExecutionTime(() => db.users.findOne({ id: 123 }));
+ * if (queryTime > 100) {
+ *   console.warn(`Slow query: ${queryTime}ms`);
+ * }
+ * ```
+ */
+export async function measureExecutionTime<T>(fn: () => T | Promise<T>): Promise<[T, number]> {
+  const start = performance.now();
+  const result = await Promise.resolve(fn());
+  const end = performance.now();
+  const executionTime = end - start;
+
+  return [result, executionTime];
+}