@zeyos/zx 2.1.0 → 2.2.0

package/src/core/format.js

@@ -0,0 +1,283 @@
+// @ts-check
+import { getLanguage } from './i18n.js';
+
+/**
+ * @typedef {Object} NumberFormatOptions
+ * @property {string} [locale=getLanguage()] BCP 47 language tag; defaults to the active language.
+ * @property {number} [decimals] Shorthand setting both the minimum and maximum fraction digits.
+ * @property {number} [minDecimals] Minimum fraction digits.
+ * @property {number} [maxDecimals] Maximum fraction digits.
+ * @property {boolean} [group=true] Whether to insert the locale's grouping separators.
+ */
+
+/**
+ * @typedef {Object} CurrencyFormatOptions
+ * @property {string} [locale=getLanguage()] BCP 47 language tag.
+ * @property {number} [decimals] Fraction digits; defaults to the currency's own minor-unit count.
+ */
+
+/**
+ * @typedef {Object} PercentFormatOptions
+ * @property {string} [locale=getLanguage()] BCP 47 language tag.
+ * @property {number} [decimals=0] Fraction digits.
+ */
+
+/**
+ * @typedef {Object} FileSizeFormatOptions
+ * @property {string} [locale=getLanguage()] BCP 47 language tag.
+ * @property {number} [decimals=1] Maximum fraction digits; trailing zeros are dropped.
+ * @property {'iec'|'si'} [standard='iec'] Binary KiB/MiB/GiB or decimal kB/MB/GB units.
+ */
+
+/**
+ * @typedef {Object} RelativeTimeFormatOptions
+ * @property {Date|number|string} [now=new Date()] Reference point the date is measured against.
+ * @property {string} [locale=getLanguage()] BCP 47 language tag.
+ * @property {'auto'|'always'} [numeric='auto'] `auto` produces "yesterday", `always` "1 day ago".
+ */
+
+/** Fraction-digit bounds accepted by `Intl.NumberFormat`. */
+const MIN_DIGITS = 0;
+const MAX_DIGITS = 20;
+/** `Intl.NumberFormat`'s own default maximum for plain decimal formatting. */
+const DEFAULT_MAX_DIGITS = 3;
+
+const IEC_UNITS = ['B', 'KiB', 'MiB', 'GiB', 'TiB', 'PiB', 'EiB'];
+const SI_UNITS = ['B', 'kB', 'MB', 'GB', 'TB', 'PB', 'EB'];
+
+/**
+ * Largest-first units with their length in milliseconds and the threshold below which the unit is
+ * still the sensible choice: 45 s, 45 min, 22 h, 6 d, 4 w, 11 months.
+ */
+const TIME_DIVISIONS = [
+  { unit: 'second', ms: 1000, limit: 45 },
+  { unit: 'minute', ms: 60000, limit: 45 },
+  { unit: 'hour', ms: 3600000, limit: 22 },
+  { unit: 'day', ms: 86400000, limit: 6 },
+  { unit: 'week', ms: 604800000, limit: 4 },
+  { unit: 'month', ms: 2629800000, limit: 11 },
+  { unit: 'year', ms: 31557600000, limit: Infinity }
+];
+
+/**
+ * Intl formatters are expensive to construct and tables call these helpers once per cell, so every
+ * instance is cached under its locale and options.
+ * @type {Map<string, Intl.NumberFormat>}
+ */
+const numberFormatters = new Map();
+/** @type {Map<string, Intl.RelativeTimeFormat>} */
+const relativeFormatters = new Map();
+
+/**
+ * Formats a number for the active language.
+ * @param {number|string|null|undefined} value Value to format.
+ * @param {NumberFormatOptions} [options={}] Formatting options.
+ * @returns {string} Formatted number, or an empty string for null, undefined, and NaN.
+ */
+export function formatNumber(value, options = {}) {
+  const number = toFiniteNumber(value);
+  if (number === null) return '';
+  const { locale = getLanguage(), decimals, minDecimals, maxDecimals, group = true } = options;
+  return format(locale, digitOptions({ decimals, minDecimals, maxDecimals, group }), number);
+}
+
+/**
+ * Formats a monetary amount, falling back to plain number formatting when the currency code is
+ * missing or not shaped like an ISO 4217 code.
+ * @param {number|string|null|undefined} value Amount to format.
+ * @param {string|null|undefined} currency Three-letter ISO 4217 code such as `EUR`.
+ * @param {CurrencyFormatOptions} [options={}] Formatting options.
+ * @returns {string} Formatted amount, or an empty string for null, undefined, and NaN.
+ */
+export function formatCurrency(value, currency, options = {}) {
+  const number = toFiniteNumber(value);
+  if (number === null) return '';
+  const { locale = getLanguage(), decimals } = options;
+  const code = currencyCode(currency);
+  if (code === null) return formatNumber(number, { locale, decimals });
+
+  const digits = digitOptions({ decimals, group: true });
+  return format(locale, { ...digits, style: 'currency', currency: code }, number);
+}
+
+/**
+ * Formats a fraction as a percentage: `0.42` becomes `42%`.
+ * @param {number|string|null|undefined} value Fraction to format.
+ * @param {PercentFormatOptions} [options={}] Formatting options.
+ * @returns {string} Formatted percentage, or an empty string for null, undefined, and NaN.
+ */
+export function formatPercent(value, options = {}) {
+  const number = toFiniteNumber(value);
+  if (number === null) return '';
+  const { locale = getLanguage(), decimals = 0 } = options;
+  return format(locale, { ...digitOptions({ decimals, group: true }), style: 'percent' }, number);
+}
+
+/**
+ * Formats a byte count with binary (KiB) or decimal (kB) units.
+ * @param {number|string|null|undefined} bytes Byte count.
+ * @param {FileSizeFormatOptions} [options={}] Formatting options.
+ * @returns {string} Formatted size, `'0 B'` for zero, or an empty string for null and NaN.
+ */
+export function formatFileSize(bytes, options = {}) {
+  const number = toFiniteNumber(bytes);
+  if (number === null) return '';
+  const { locale = getLanguage(), decimals = 1, standard = 'iec' } = options;
+  if (number === 0) return `${formatNumber(0, { locale, decimals: 0 })} B`;
+
+  const units = standard === 'si' ? SI_UNITS : IEC_UNITS;
+  const base = standard === 'si' ? 1000 : 1024;
+  const absolute = Math.abs(number);
+  let exponent = Math.min(units.length - 1, Math.max(0, Math.floor(Math.log(absolute) / Math.log(base))));
+  let scaled = absolute / base ** exponent;
+  // Rounding can push a value up into the next unit (1023.9 KiB at one decimal is 1024.0 KiB).
+  // Whole bytes never get fraction digits, so the check runs against the digits actually used.
+  if (roundTo(scaled, exponent === 0 ? 0 : decimals) >= base && exponent < units.length - 1) {
+    exponent += 1;
+    scaled = absolute / base ** exponent;
+  }
+
+  const signed = number < 0 ? -scaled : scaled;
+  const digits = exponent === 0 ? 0 : decimals;
+  const text = formatNumber(signed, { locale, minDecimals: 0, maxDecimals: digits });
+  return `${text} ${units[exponent]}`;
+}
+
+/**
+ * Formats a date relative to a reference point, picking the largest sensible unit.
+ * @param {Date|number|string|null|undefined} date Date, Unix timestamp in seconds, or ISO string.
+ * @param {RelativeTimeFormatOptions} [options={}] Formatting options.
+ * @returns {string} Formatted phrase, or an empty string when the date cannot be read.
+ */
+export function formatRelativeTime(date, options = {}) {
+  const target = toDate(date);
+  if (target === null) return '';
+  const { now = new Date(), locale = getLanguage(), numeric = 'auto' } = options;
+  const reference = toDate(now);
+  if (reference === null) return '';
+
+  const diff = target.getTime() - reference.getTime();
+  const division = TIME_DIVISIONS.find(({ ms, limit }) => Math.abs(diff) / ms < limit)
+    ?? TIME_DIVISIONS[TIME_DIVISIONS.length - 1];
+  const value = Math.round(diff / division.ms);
+  return relativeFormatter(locale, numeric)
+    .format(value, /** @type {Intl.RelativeTimeFormatUnit} */ (division.unit));
+}
+
+/**
+ * Returns a cached `Intl.NumberFormat`, falling back to the runtime default for unusable locales.
+ * @param {string} locale BCP 47 language tag.
+ * @param {Intl.NumberFormatOptions} options Formatter options.
+ * @param {number} value Number to format.
+ * @returns {string}
+ */
+function format(locale, options, value) {
+  const key = `${locale}\u0000${JSON.stringify(options)}`;
+  let formatter = numberFormatters.get(key);
+  if (formatter === undefined) {
+    formatter = createNumberFormat(locale, options);
+    numberFormatters.set(key, formatter);
+  }
+  return formatter.format(value);
+}
+
+/**
+ * @param {string} locale BCP 47 language tag.
+ * @param {Intl.NumberFormatOptions} options Formatter options.
+ * @returns {Intl.NumberFormat}
+ */
+function createNumberFormat(locale, options) {
+  try {
+    return new Intl.NumberFormat(locale, options);
+  } catch {
+    try {
+      return new Intl.NumberFormat(undefined, options);
+    } catch {
+      // Unusable options (an unsupported currency style, say) still have to produce digits.
+      return new Intl.NumberFormat();
+    }
+  }
+}
+
+/**
+ * @param {string} locale BCP 47 language tag.
+ * @param {'auto'|'always'} numeric Numeric-phrasing mode.
+ * @returns {Intl.RelativeTimeFormat}
+ */
+function relativeFormatter(locale, numeric) {
+  const key = `${locale}\u0000${numeric}`;
+  let formatter = relativeFormatters.get(key);
+  if (formatter === undefined) {
+    try {
+      formatter = new Intl.RelativeTimeFormat(locale, { numeric });
+    } catch {
+      formatter = new Intl.RelativeTimeFormat(undefined, { numeric: 'auto' });
+    }
+    relativeFormatters.set(key, formatter);
+  }
+  return formatter;
+}
+
+/**
+ * Turns the decimals shorthand and its explicit siblings into `Intl.NumberFormat` digit options.
+ * @param {{decimals?: number, minDecimals?: number, maxDecimals?: number, group?: boolean}} options
+ * @returns {Intl.NumberFormatOptions}
+ */
+function digitOptions({ decimals, minDecimals, maxDecimals, group = true }) {
+  /** @type {Intl.NumberFormatOptions} */
+  const result = { useGrouping: group !== false };
+  const min = digitCount(minDecimals ?? decimals);
+  const max = digitCount(maxDecimals ?? decimals);
+
+  if (min !== null) result.minimumFractionDigits = min;
+  if (max !== null) {
+    result.maximumFractionDigits = max;
+    // Intl throws when the minimum exceeds the maximum, so the pair is reconciled here instead.
+    if (min !== null && min > max) result.minimumFractionDigits = max;
+  } else if (min !== null) {
+    result.maximumFractionDigits = Math.max(min, DEFAULT_MAX_DIGITS);
+  }
+  return result;
+}
+
+/** @param {unknown} value @returns {number|null} */
+function digitCount(value) {
+  if (value == null) return null;
+  const number = Number(value);
+  if (!Number.isFinite(number)) return null;
+  return Math.min(MAX_DIGITS, Math.max(MIN_DIGITS, Math.round(number)));
+}
+
+/** @param {unknown} value @returns {number|null} */
+function toFiniteNumber(value) {
+  if (value === null || value === undefined || value === '') return null;
+  const number = typeof value === 'number' ? value : Number(value);
+  return Number.isFinite(number) ? number : null;
+}
+
+/** @param {unknown} value @returns {string|null} */
+function currencyCode(value) {
+  if (typeof value !== 'string') return null;
+  const code = value.trim().toUpperCase();
+  return /^[A-Z]{3}$/.test(code) ? code : null;
+}
+
+/** @param {Date|number|string|null|undefined} value @returns {Date|null} */
+function toDate(value) {
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value;
+  if (typeof value === 'number') return Number.isFinite(value) ? new Date(value * 1000) : null;
+  if (typeof value === 'string') {
+    const text = value.trim();
+    if (text === '') return null;
+    // Unix seconds arrive as strings from ZeyOS kernel payloads often enough to accept them here.
+    const parsed = /^-?\d+$/.test(text) ? new Date(Number(text) * 1000) : new Date(text);
+    return Number.isNaN(parsed.getTime()) ? null : parsed;
+  }
+  return null;
+}
+
+/** @param {number} value @param {number} digits @returns {number} */
+function roundTo(value, digits) {
+  const factor = 10 ** digits;
+  return Math.round(value * factor) / factor;
+}

package/src/core/http.js

@@ -0,0 +1,246 @@
+// @ts-check
+/**
+ * @typedef {Object} HttpOptions
+ * @property {string} [base=''] URL prefix.
+ * @property {Record<string, string>} [headers={}] Default request headers.
+ * @property {((error: Error, context: {path: string, options: RequestOptions}) => void)|null} [onError=null]
+ * @property {number} [timeout=30000] Timeout in milliseconds; zero disables it.
+ */
+
+/**
+ * @typedef {Object} RequestOptions
+ * @property {string} [method='GET'] HTTP method.
+ * @property {unknown} [data=null] JSON or form data.
+ * @property {File|FileList|File[]} [files=null] Files that switch the body to FormData.
+ * @property {string|URLSearchParams|Record<string, unknown>} [query=null] Query parameters.
+ * @property {Record<string, string>} [headers={}] Per-request headers.
+ */
+
+/** Dependency-free JSON fetch wrapper with legacy ZeyOS envelope handling. */
+export class Http {
+  /** @type {string} */
+  base;
+  /** @type {Readonly<Record<string, string>>} */
+  headers;
+  /** @type {HttpOptions['onError']} */
+  onError;
+  /** @type {number} */
+  timeout;
+
+  /**
+   * @param {HttpOptions} [options={}] Client defaults.
+   */
+  constructor({ base = '', headers = {}, onError = null, timeout = 30000 } = {}) {
+    this.base = String(base);
+    this.headers = Object.freeze({ ...headers });
+    this.onError = onError;
+    this.timeout = Number(timeout);
+  }
+
+  /**
+   * Performs a request and returns its parsed JSON payload or legacy `result` value.
+   * @param {string} path Path relative to the configured base.
+   * @param {RequestOptions} [options={}] Request settings.
+   * @returns {Promise<any>}
+   */
+  async request(path, options = {}) {
+    const {
+      method = 'GET', data = null, files = null, query = null, headers = {}
+    } = options;
+    const controller = new AbortController();
+    const timeoutId = this.timeout > 0 ? setTimeout(() => controller.abort(), this.timeout) : null;
+    const requestHeaders = new Headers(this.headers);
+    for (const [name, value] of Object.entries(headers)) requestHeaders.set(name, value);
+    requestHeaders.set('Accept', requestHeaders.get('Accept') ?? 'application/json');
+
+    let body;
+    if (files !== null) {
+      body = createFormData(data, files);
+      requestHeaders.delete('Content-Type');
+    } else if (data !== null && method.toUpperCase() !== 'GET' && method.toUpperCase() !== 'HEAD') {
+      body = JSON.stringify(data);
+      requestHeaders.set('Content-Type', requestHeaders.get('Content-Type') ?? 'application/json');
+    }
+
+    const url = appendQuery(this.base + path, query);
+    try {
+      const response = await fetch(url, {
+        method: method.toUpperCase(),
+        headers: requestHeaders,
+        body,
+        signal: controller.signal
+      });
+      const text = await response.text();
+      let json = null;
+      if (text !== '') {
+        try {
+          json = JSON.parse(text);
+        } catch (cause) {
+          const error = /** @type {Error & {response?: Response}} */ (
+            new Error('Invalid JSON response', { cause })
+          );
+          error.response = response;
+          throw error;
+        }
+      }
+
+      if (!response.ok) {
+        try {
+          parseResult(json);
+        } catch (error) {
+          /** @type {Error & {response?: Response}} */ (error).response = response;
+          throw error;
+        }
+        const error = /** @type {Error & {response?: Response}} */ (
+          new Error(`HTTP ${response.status} ${response.statusText}`.trim())
+        );
+        error.response = response;
+        throw error;
+      }
+      return parseResult(json);
+    } catch (caught) {
+      const error = caught instanceof Error ? caught : new Error(String(caught));
+      if (this.onError) {
+        try {
+          this.onError(error, { path, options });
+        } catch {
+          // Observer failures do not hide the request failure.
+        }
+      }
+      throw error;
+    } finally {
+      if (timeoutId !== null) clearTimeout(timeoutId);
+    }
+  }
+
+  /**
+   * Sends a GET request with query parameters.
+   * @param {string} path Request path.
+   * @param {RequestOptions['query']} [query=null] Query parameters.
+   * @returns {Promise<any>}
+   */
+  get(path, query = null) {
+    return this.request(path, { method: 'GET', query });
+  }
+
+  /**
+   * Sends a POST request with a JSON body.
+   * @param {string} path Request path.
+   * @param {unknown} [data=null] Request data.
+   * @returns {Promise<any>}
+   */
+  post(path, data = null) {
+    return this.request(path, { method: 'POST', data });
+  }
+
+  /**
+   * Sends a PUT request with a JSON body.
+   * @param {string} path Request path.
+   * @param {unknown} [data=null] Request data.
+   * @returns {Promise<any>}
+   */
+  put(path, data = null) {
+    return this.request(path, { method: 'PUT', data });
+  }
+
+  /**
+   * Sends a DELETE request with a JSON body.
+   * @param {string} path Request path.
+   * @param {unknown} [data=null] Request data.
+   * @returns {Promise<any>}
+   */
+  delete(path, data = null) {
+    return this.request(path, { method: 'DELETE', data });
+  }
+}
+
+/**
+ * Creates an Http client for a ZeyOS remote-call service.
+ * @param {string} service Service name.
+ * @param {string} [accesskey=''] Optional service access key.
+ * @param {HttpOptions & {apiBase?: string}} [options={}] Client and API-base options.
+ * @returns {Http}
+ */
+export function zeyosService(service, accesskey = '', options = {}) {
+  const { apiBase = '../remotecall/', ...httpOptions } = options;
+  const base = `${apiBase}${service}${accesskey ? `:${accesskey}` : ''}/`;
+  return new Http({ ...httpOptions, base });
+}
+
+/**
+ * Unwraps a legacy `{result}` response or throws a legacy `{error}` response.
+ * JSON values without either envelope key pass through unchanged.
+ * @param {any} json Parsed JSON value.
+ * @returns {any}
+ */
+export function parseResult(json) {
+  if (json && typeof json === 'object') {
+    if (Object.prototype.hasOwnProperty.call(json, 'error') && json.error != null) {
+      const message = typeof json.error === 'string' ? json.error : JSON.stringify(json.error);
+      throw new Error(message || 'Server error');
+    }
+    if (Object.prototype.hasOwnProperty.call(json, 'result')) return json.result;
+  }
+  return json;
+}
+
+/**
+ * @param {string} url
+ * @param {RequestOptions['query']} query
+ * @returns {string}
+ */
+function appendQuery(url, query) {
+  if (query == null) return url;
+  let encoded;
+  if (typeof query === 'string') encoded = query.replace(/^\?/, '');
+  else if (query instanceof URLSearchParams) encoded = query.toString();
+  else {
+    const parameters = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) appendParameter(parameters, key, value);
+    encoded = parameters.toString();
+  }
+  if (!encoded) return url;
+  return url + (url.includes('?') ? '&' : '?') + encoded;
+}
+
+/** @param {URLSearchParams} parameters @param {string} key @param {unknown} value @returns {void} */
+function appendParameter(parameters, key, value) {
+  if (value == null) return;
+  if (Array.isArray(value)) {
+    for (const item of value) appendParameter(parameters, key, item);
+  } else {
+    parameters.append(key, typeof value === 'object' ? JSON.stringify(value) : String(value));
+  }
+}
+
+/** @param {unknown} data @param {File|FileList|File[]} files @returns {FormData} */
+function createFormData(data, files) {
+  const form = new FormData();
+  if (data && typeof data === 'object' && !Array.isArray(data)) {
+    for (const [key, value] of Object.entries(data)) appendFormValue(form, key, value);
+  } else if (data != null) {
+    form.append('data', typeof data === 'string' ? data : JSON.stringify(data));
+  }
+
+  const list = isFileList(files) || Array.isArray(files) ? Array.from(files) : [files];
+  for (const file of list) form.append('files', file);
+  return form;
+}
+
+/** @param {FormData} form @param {string} key @param {unknown} value @returns {void} */
+function appendFormValue(form, key, value) {
+  if (value == null) return;
+  if (Array.isArray(value)) {
+    for (const item of value) appendFormValue(form, key, item);
+  } else {
+    const isBlob = typeof Blob === 'function' && value instanceof Blob;
+    form.append(key, typeof value === 'object' && !isBlob
+      ? JSON.stringify(value)
+      : /** @type {string|Blob} */ (value));
+  }
+}
+
+/** @param {unknown} value @returns {value is FileList} */
+function isFileList(value) {
+  return typeof FileList === 'function' && value instanceof FileList;
+}

package/src/core/i18n.js

@@ -0,0 +1,83 @@
+// @ts-check
+/** @typedef {(key: string) => string|null|undefined} Translator */
+
+/** @type {Translator|null} */
+let translator = null;
+let language = 'en';
+
+/**
+ * Installs the host application's translation function, or clears it with null.
+ * @param {Translator|null} fn Translator function.
+ * @returns {void}
+ */
+export function setTranslator(fn) {
+  if (fn !== null && typeof fn !== 'function') {
+    throw new TypeError('Translator must be a function or null');
+  }
+  translator = fn;
+}
+
+/**
+ * Sets the active language identifier.
+ * @param {string} lang Language identifier such as "en" or "de-AT".
+ * @returns {void}
+ */
+export function setLanguage(lang) {
+  language = String(lang || 'en');
+}
+
+/**
+ * Returns the active language identifier.
+ * @returns {string}
+ */
+export function getLanguage() {
+  return language;
+}
+
+/**
+ * Translates a key through the injected host translator and interpolates arguments.
+ * @param {string} key Translation key.
+ * @param {unknown[]|Record<string, unknown>|string|number} [args] Interpolation arguments.
+ * @returns {string}
+ */
+export function translate(key, args) {
+  const translated = translator ? translator(key) : key;
+  return printf(translated == null ? key : String(translated), args);
+}
+
+/**
+ * Replaces one-based numeric placeholders and legacy percent-delimited placeholders.
+ * Arrays replace `%1`, `%2`, and legacy placeholders in encounter order; objects replace
+ * named placeholders such as `%name%`.
+ * @param {string} str Template string.
+ * @param {unknown[]|Record<string, unknown>|string|number} [args] Replacement values.
+ * @returns {string}
+ */
+export function printf(str, args) {
+  if (args == null) return String(str);
+
+  const positional = Array.isArray(args) ? args :
+    (typeof args === 'object' ? null : [args]);
+  let output = String(str).replace(/%(\d+)/g, (placeholder, indexText) => {
+    const index = Number(indexText) - 1;
+    let value;
+    if (positional) value = positional[index];
+    else if (Object.prototype.hasOwnProperty.call(args, indexText)) value = args[indexText];
+    return value == null ? placeholder : String(value);
+  });
+
+  let legacyIndex = 0;
+  output = output.replace(/%([A-Za-z_][\w.-]*)%/g, (placeholder, key) => {
+    if (!positional && Object.prototype.hasOwnProperty.call(args, key)) {
+      const value = args[key];
+      return value == null ? placeholder : String(value);
+    }
+    if (positional && legacyIndex < positional.length) {
+      const value = positional[legacyIndex];
+      legacyIndex += 1;
+      return value == null ? placeholder : String(value);
+    }
+    return placeholder;
+  });
+  return output;
+}