hanzio 1.1.0 → 2.0.0

package/dist/function/index.d.ts

@@ -0,0 +1,60 @@
+export type Debounced<A extends unknown[]> = ((...args: A) => void) & {
+    /** Drops the pending call. */
+    cancel(): void;
+    /** Runs the pending call now, if any. */
+    flush(): void;
+    /** True while a trailing call is waiting. */
+    pending(): boolean;
+};
+/**
+ * Calls `fn` with the latest args once calls stop for `waitMs` (trailing).
+ * `leading` also calls on the first call of a burst; `maxWaitMs` forces a
+ * call at least that often during a continuous burst.
+ */
+export declare function debounce<A extends unknown[]>(fn: (...args: A) => void, waitMs: number, options?: {
+    leading?: boolean;
+    maxWaitMs?: number;
+}): Debounced<A>;
+/**
+ * One independent trailing debounce per key. `cancel`/`flush` without a key
+ * apply to every pending key.
+ */
+export declare function keyedDebounce<K, A extends unknown[]>(fn: (key: K, ...args: A) => void, waitMs: number): {
+    call(key: K, ...args: A): void;
+    cancel(key?: K): void;
+    flush(key?: K): void;
+};
+/**
+ * Calls `fn` immediately, then at most once per `intervalMs`. With `trailing`
+ * (default), the last call made during an interval runs when it ends.
+ */
+export declare function throttle<A extends unknown[]>(fn: (...args: A) => void, intervalMs: number, options?: {
+    trailing?: boolean;
+}): ((...args: A) => void) & {
+    cancel(): void;
+};
+/** Calls `fn` on the first call only; later calls return the first result. */
+export declare function once<A extends unknown[], R>(fn: (...args: A) => R): (...args: A) => R;
+export type HeartbeatOptions = {
+    /** Called on the first activity, then at most once per `intervalMs`. */
+    send: () => void;
+    /** Called once when an active heartbeat stops (idle or `stop()`). */
+    onStop?: () => void;
+    intervalMs: number;
+    /** Stop after this long without `activity()`. */
+    idleMs: number;
+    now?: () => number;
+    setTimeout?: (callback: () => void, ms: number) => unknown;
+    clearTimeout?: (timer: unknown) => void;
+};
+/**
+ * Turns bursts of activity into heartbeats (e.g. "is typing" signals): sends
+ * immediately on the first activity, then at most once per `intervalMs` while
+ * activity continues, and stops after `idleMs` without activity.
+ */
+export declare function createHeartbeat(options: HeartbeatOptions): {
+    /** Report activity. */
+    activity(): void;
+    /** Stop now; calls `onStop` if active. Safe to call repeatedly. */
+    stop(): void;
+};

package/dist/guard/index.d.ts

@@ -0,0 +1,20 @@
+import type { NonEmptyArray } from '../types';
+/** Non-null object that is not an array. */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** Object literal or `Object.create(null)`; excludes arrays, class instances, Dates, Maps. */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+export declare function isDefined<T>(value: T): value is NonNullable<T>;
+export declare function isTruthy<T>(value: T): value is Exclude<T, false | 0 | 0n | '' | null | undefined>;
+export declare function isString(value: unknown): value is string;
+/** `typeof number`, excluding NaN. Infinity passes. */
+export declare function isNumber(value: unknown): value is number;
+export declare function isBoolean(value: unknown): value is boolean;
+export declare function isFunction(value: unknown): value is (...args: any[]) => any;
+/** Whether `value` is in `list`. Omit `value` to get a reusable guard, e.g. for `.filter`. */
+export declare function isOneOf<const T extends readonly unknown[]>(list: T): (value: unknown) => value is T[number];
+export declare function isOneOf<const T extends readonly unknown[]>(list: T, value: unknown): value is T[number];
+/** Own-property check that narrows `key` to `keyof O`. */
+export declare function hasKey<O extends object>(object: O, key: PropertyKey): key is keyof O;
+export declare function isNonEmpty<T>(array: readonly T[]): array is readonly [T, ...T[]];
+/** Copy of `array` typed as non-empty (e.g. for `z.enum`); throws when empty. */
+export declare function nonEmpty<T>(array: readonly T[], message?: string): NonEmptyArray<T>;

package/dist/i18n/index.d.ts

@@ -0,0 +1,37 @@
+export type PlaceholderValue = string | number;
+type Chars<S extends string> = S extends `${infer C}${infer Rest}` ? C | Chars<Rest> : never;
+type Letter = Chars<'abcdefghijklmnopqrstuvwxyz'>;
+type WordChar = Letter | Uppercase<Letter> | Chars<'0123456789_'>;
+type IsWord<S extends string> = S extends `${infer C}${infer Rest}` ? C extends WordChar ? Rest extends '' ? true : IsWord<Rest> : false : false;
+type AfterLastBrace<S extends string> = S extends `${string}{${infer Rest}` ? AfterLastBrace<Rest> : S;
+type ExtractNames<S extends string, Found extends string = never> = S extends `${string}{${infer Body}}${infer Rest}` ? ExtractNames<Rest, Found | (IsWord<AfterLastBrace<Body>> extends true ? AfterLastBrace<Body> : never)> : Found;
+/** `'Hi {name}, you have {count}'` → `'name' | 'count'`; `string` for non-literal templates. */
+export type PlaceholderNames<S extends string> = string extends S ? string : ExtractNames<S>;
+export type PlaceholderParams<S extends string> = Record<PlaceholderNames<S>, PlaceholderValue>;
+/** Params argument: required with placeholders, absent without, optional for non-literal templates. */
+export type PlaceholderArgs<S extends string> = string extends S ? [params?: PlaceholderParams<S>] : [PlaceholderNames<S>] extends [never] ? [] : [params: PlaceholderParams<S>];
+/** Unique placeholder names in order of first appearance. */
+export declare function extractPlaceholders<S extends string>(template: S): PlaceholderNames<S>[];
+/**
+ * Replaces `{name}` placeholders with `params`. Placeholders without a
+ * (non-null) param are left as-is. There is no escape syntax.
+ */
+export declare function interpolate<S extends string>(template: S, ...args: PlaceholderArgs<S>): string;
+export type Messages = {
+    readonly [key: string]: string | Messages;
+};
+/** Dot-path keys of the string leaves: `{ a: { b: 'x' } }` → `'a.b'`. */
+export type MessageKeys<T> = {
+    [K in keyof T & string]: T[K] extends string ? K : `${K}.${MessageKeys<T[K]>}`;
+}[keyof T & string];
+/** Message at a dot-path key. */
+export type MessageAt<T, K extends string> = K extends keyof T ? T[K] : K extends `${infer Head}.${infer Rest}` ? Head extends keyof T ? MessageAt<T[Head], Rest> : never : never;
+/** `{ a: { b: 'x' } }` → `{ 'a.b': 'x' }` */
+export declare function flattenMessages<const T extends Messages>(messages: T): Record<MessageKeys<T>, string>;
+/**
+ * Typed `t(key, params)` over a nested messages object. With literal messages
+ * (inline `const` objects), params are required exactly when the message has
+ * placeholders. Unknown keys at runtime return the key.
+ */
+export declare function createTranslator<const T extends Messages>(messages: T): <K extends MessageKeys<T>>(key: K, ...args: PlaceholderArgs<Extract<MessageAt<T, K>, string>>) => string;
+export {};

package/dist/index-0zvtcbzy.js

@@ -0,0 +1,224 @@
+// src/promise/index.ts
+function ok2(data) {
+  return { ok: true, data, error: null };
+}
+function err2(error) {
+  return { ok: false, data: null, error };
+}
+function isSuccess2(result) {
+  return result.ok;
+}
+function isFailure2(result) {
+  return !result.ok;
+}
+function unwrapResult2(result) {
+  if (result.ok)
+    return result.data;
+  throw result.error;
+}
+function backgroundPromise2(promiseFactory, options = {}) {
+  const run = () => {
+    promiseFactory().then(() => options.onSuccess?.()).catch((error) => options.onError?.(error));
+  };
+  if (options.scheduler) {
+    options.scheduler(run);
+    return;
+  }
+  run();
+}
+function backgroundPromiseSync2(promiseFactory, options = {}) {
+  backgroundPromise2(promiseFactory, {
+    ...options,
+    scheduler: options.scheduler ?? queueMicrotask
+  });
+}
+function promiseTimeout2(ms, options = {}) {
+  const { signal } = options;
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason);
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal?.reason);
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+async function tryCatch2(input) {
+  try {
+    return ok2(await (typeof input === "function" ? input() : input));
+  } catch (error) {
+    return err2(error);
+  }
+}
+
+class PromiseTimeoutError2 extends Error {
+  timeoutMs;
+  constructor(timeoutMs, message) {
+    super(message ?? `Promise timed out after ${timeoutMs}ms`);
+    this.name = "PromiseTimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+}
+async function withTimeout2(input, ms, options = {}) {
+  const controller = new AbortController;
+  const onAbort = () => controller.abort(options.signal?.reason);
+  if (options.signal?.aborted)
+    onAbort();
+  else
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+  const timer = setTimeout(() => controller.abort(new PromiseTimeoutError2(ms, options.message)), ms);
+  let rejectOnAbort = () => {};
+  try {
+    const aborted = new Promise((_, reject) => {
+      rejectOnAbort = () => reject(controller.signal.reason);
+      controller.signal.addEventListener("abort", rejectOnAbort, { once: true });
+    });
+    if (controller.signal.aborted)
+      throw controller.signal.reason;
+    const promise = typeof input === "function" ? input(controller.signal) : input;
+    return await Promise.race([promise, aborted]);
+  } finally {
+    clearTimeout(timer);
+    options.signal?.removeEventListener("abort", onAbort);
+    controller.signal.removeEventListener("abort", rejectOnAbort);
+  }
+}
+function exponentialBackoff2(attempt, options = {}) {
+  const {
+    baseMs = 300,
+    maxMs = 30000,
+    jitter = true,
+    jitterRatio = 0.25,
+    random = Math.random
+  } = options;
+  const delay = Math.min(maxMs, baseMs * 2 ** Math.max(0, attempt - 1));
+  if (jitter === "partial")
+    return Math.round(delay * (1 + jitterRatio * random()));
+  return jitter ? Math.round(random() * delay) : delay;
+}
+async function retry2(fn, options = {}) {
+  const { retries = 3, delayMs, shouldRetry, onRetry, signal } = options;
+  for (let attempt = 0;; attempt++) {
+    signal?.throwIfAborted();
+    try {
+      return await fn({ attempt, signal });
+    } catch (error) {
+      const nextAttempt = attempt + 1;
+      if (attempt >= retries || shouldRetry?.(error, nextAttempt) === false) {
+        throw error;
+      }
+      const delay = delayMs === undefined ? exponentialBackoff2(nextAttempt) : typeof delayMs === "function" ? delayMs(nextAttempt, error) : delayMs;
+      onRetry?.(error, nextAttempt, delay);
+      await promiseTimeout2(delay, { signal });
+    }
+  }
+}
+async function pMap2(items, fn, options = {}) {
+  const { concurrency = Number.POSITIVE_INFINITY, signal } = options;
+  if (!(concurrency >= 1)) {
+    throw new Error("Concurrency must be at least 1");
+  }
+  const list = [...items];
+  const results = new Array(list.length);
+  let next = 0;
+  const worker = async () => {
+    while (next < list.length) {
+      signal?.throwIfAborted();
+      const index = next++;
+      results[index] = await fn(list[index], index);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(concurrency, list.length) }, worker));
+  return results;
+}
+var clock = () => globalThis.performance?.now() ?? Date.now();
+function startTimer2() {
+  const start = clock();
+  return () => clock() - start;
+}
+async function timed2(fn) {
+  const elapsed = startTimer2();
+  const result = await fn();
+  return { result, durationMs: elapsed() };
+}
+function anySignal2(...signals) {
+  const list = signals.filter((signal) => signal !== undefined);
+  if (list.length === 1)
+    return list[0];
+  if (typeof AbortSignal.any === "function")
+    return AbortSignal.any(list);
+  const controller = new AbortController;
+  const aborted = list.find((signal) => signal.aborted);
+  if (aborted) {
+    controller.abort(aborted.reason);
+    return controller.signal;
+  }
+  const onAbort = (event) => {
+    for (const signal of list)
+      signal.removeEventListener("abort", onAbort);
+    controller.abort(event.target.reason);
+  };
+  for (const signal of list)
+    signal.addEventListener("abort", onAbort);
+  return controller.signal;
+}
+function timeoutSignal2(ms, signal) {
+  if (typeof AbortSignal.timeout === "function") {
+    return anySignal2(AbortSignal.timeout(ms), signal);
+  }
+  const controller = new AbortController;
+  setTimeout(() => {
+    const reason = new Error("The operation timed out.");
+    reason.name = "TimeoutError";
+    controller.abort(reason);
+  }, ms);
+  return anySignal2(controller.signal, signal);
+}
+async function raceAbort2(promise, signal) {
+  if (!signal)
+    return promise;
+  let onAbort = () => {};
+  const aborted = new Promise((_, reject) => {
+    onAbort = () => reject(signal.reason);
+    if (signal.aborted)
+      onAbort();
+    else
+      signal.addEventListener("abort", onAbort, { once: true });
+  });
+  try {
+    return await Promise.race([aborted, promise]);
+  } finally {
+    signal.removeEventListener("abort", onAbort);
+  }
+}
+function createLatestGuard2() {
+  let current = 0;
+  const isCurrent = (token) => token === current;
+  return {
+    next: () => ++current,
+    isCurrent,
+    invalidate: () => {
+      current++;
+    },
+    async run(fn) {
+      const token = ++current;
+      try {
+        const value = await fn();
+        return isCurrent(token) ? { stale: false, value } : { stale: true };
+      } catch (error) {
+        if (!isCurrent(token))
+          return { stale: true };
+        throw error;
+      }
+    }
+  };
+}
+
+export { ok2, err2, isSuccess2, isFailure2, unwrapResult2, backgroundPromise2, backgroundPromiseSync2, promiseTimeout2, tryCatch2, PromiseTimeoutError2, withTimeout2, exponentialBackoff2, retry2, pMap2, startTimer2, timed2, anySignal2, timeoutSignal2, raceAbort2, createLatestGuard2 };

package/dist/index-181e6vfw.js

@@ -0,0 +1,29 @@
+import {
+  SecretLoadError2
+} from "./index-srt06xd2.js";
+
+// src/secrets/vite.ts
+function getViteDefine2(secretSet, options = {}) {
+  const values = secretSet.secrets();
+  const keys = options.publicKeys ?? Object.keys(values);
+  if (!options.publicKeys && keys.some((key) => !key.startsWith("VITE_"))) {
+    throw new SecretLoadError2("CONFIGURATION", "Vite secret sets must contain only VITE_ keys, or provide an explicit publicKeys list.");
+  }
+  for (const key of keys) {
+    if (!Object.hasOwn(values, key) || !/^[A-Za-z_$][\w$]*$/.test(key)) {
+      throw new SecretLoadError2("CONFIGURATION", "Vite publicKeys must reference configured keys with valid JavaScript identifiers.");
+    }
+    if (["MODE", "BASE_URL", "PROD", "DEV", "SSR"].includes(key)) {
+      throw new SecretLoadError2("CONFIGURATION", "Vite built-in environment constants cannot be overridden by secrets.");
+    }
+  }
+  return Object.fromEntries(keys.map((key) => [`import.meta.env.${key}`, JSON.stringify(values[key])]));
+}
+function viteSecretSetPlugin2(secretSet, options = {}) {
+  return {
+    name: "hanzio-secret-set",
+    config: () => ({ define: getViteDefine2(secretSet, options) })
+  };
+}
+
+export { getViteDefine2, viteSecretSetPlugin2 };

package/dist/index-8r2vdzjg.js

@@ -0,0 +1,87 @@
+// src/error/index.ts
+class InvariantError2 extends Error {
+  name = "InvariantError";
+}
+function getErrorMessage2(error, fallback = "") {
+  let message;
+  if (typeof error === "string")
+    message = error;
+  else if (typeof error === "object" && error !== null && "message" in error && typeof error.message === "string")
+    message = error.message;
+  else {
+    try {
+      message = String(error);
+    } catch {
+      message = "";
+    }
+  }
+  return message || fallback;
+}
+function toError2(error, prefix) {
+  if (error instanceof Error && !prefix)
+    return error;
+  const message = getErrorMessage2(error);
+  return new Error(prefix ? `${prefix}: ${message}` : message, {
+    cause: error
+  });
+}
+function fail(message, fallback) {
+  throw typeof message === "function" ? message() : new InvariantError2(message ?? fallback);
+}
+function must2(value, message) {
+  if (value === null || value === undefined) {
+    fail(message, "Expected value to be defined");
+  }
+  return value;
+}
+function invariant2(condition, message) {
+  if (!condition)
+    fail(message, "Invariant failed");
+}
+
+// src/guard/index.ts
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isPlainObject2(value) {
+  if (!isRecord2(value))
+    return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function isDefined2(value) {
+  return value !== null && value !== undefined;
+}
+function isTruthy2(value) {
+  return Boolean(value);
+}
+function isString2(value) {
+  return typeof value === "string";
+}
+function isNumber2(value) {
+  return typeof value === "number" && !Number.isNaN(value);
+}
+function isBoolean2(value) {
+  return typeof value === "boolean";
+}
+function isFunction2(value) {
+  return typeof value === "function";
+}
+function isOneOf2(list, ...value) {
+  if (value.length === 0)
+    return (item) => list.includes(item);
+  return list.includes(value[0]);
+}
+function hasKey2(object, key) {
+  return Object.hasOwn(object, key);
+}
+function isNonEmpty2(array) {
+  return array.length > 0;
+}
+function nonEmpty2(array, message = "Expected a non-empty array") {
+  if (!isNonEmpty2(array))
+    throw new InvariantError2(message);
+  return [...array];
+}
+
+export { InvariantError2, getErrorMessage2, toError2, must2, invariant2, isRecord2, isPlainObject2, isDefined2, isTruthy2, isString2, isNumber2, isBoolean2, isFunction2, isOneOf2, hasKey2, isNonEmpty2, nonEmpty2 };

package/dist/index-hy7kbb99.js

@@ -0,0 +1,157 @@
+import {
+  stableStringify2
+} from "./index-kj1phgrx.js";
+
+// src/array/index.ts
+function chunkArray2(array, chunkSize) {
+  if (!Number.isInteger(chunkSize) || chunkSize <= 0) {
+    throw new Error("Chunk size must be a positive integer");
+  }
+  const chunks = [];
+  for (let index = 0;index < array.length; index += chunkSize) {
+    chunks.push(array.slice(index, index + chunkSize));
+  }
+  return chunks;
+}
+function findArrayDifferenceByKey2(current, next, key, options = {}) {
+  const { isEqual } = options;
+  const getKey = (item) => String(typeof key === "function" ? key(item) : item[key]);
+  const currentByKey = new Map(current.map((item) => [getKey(item), item]));
+  const matchedKeys = new Set;
+  const newItems = [];
+  const upsertItems = [];
+  const updateItems = [];
+  const unchangedItems = [];
+  for (const item of next) {
+    const itemKey = getKey(item);
+    if (!currentByKey.has(itemKey)) {
+      newItems.push(item);
+      continue;
+    }
+    matchedKeys.add(itemKey);
+    upsertItems.push(item);
+    if (isEqual) {
+      const target = isEqual(currentByKey.get(itemKey), item) ? unchangedItems : updateItems;
+      target.push(item);
+    }
+  }
+  const difference = {
+    new: newItems,
+    upsert: upsertItems,
+    delete: current.filter((item) => !matchedKeys.has(getKey(item)))
+  };
+  return isEqual ? { ...difference, update: updateItems, unchanged: unchangedItems } : difference;
+}
+function getUniqueValues2(array) {
+  const seen = new Map;
+  for (const element of array) {
+    const key = stableStringify2(element);
+    if (!seen.has(key)) {
+      seen.set(key, element);
+    }
+  }
+  return Array.from(seen.values());
+}
+function compact2(array) {
+  return array.filter((item) => item != null);
+}
+function getUniqueValuesByKey2(array, keyOrFn) {
+  const seen = new Set;
+  const result = [];
+  for (const item of array) {
+    const value = typeof keyOrFn === "function" ? keyOrFn(item) : item[keyOrFn];
+    if (seen.has(value))
+      continue;
+    seen.add(value);
+    result.push(item);
+  }
+  return result;
+}
+function groupBy2(array, keyOrFn) {
+  const result = {};
+  for (const item of array) {
+    const groupKey = typeof keyOrFn === "function" ? keyOrFn(item) : item[keyOrFn];
+    result[groupKey] ??= [];
+    result[groupKey].push(item);
+  }
+  return result;
+}
+function countBy2(array, keyOrFn) {
+  const result = {};
+  for (const item of array) {
+    const groupKey = typeof keyOrFn === "function" ? keyOrFn(item) : item[keyOrFn];
+    result[groupKey] = (result[groupKey] ?? 0) + 1;
+  }
+  return result;
+}
+function keyBy2(array, keyOrFn) {
+  const result = {};
+  for (const item of array) {
+    const recordKey = typeof keyOrFn === "function" ? keyOrFn(item) : item[keyOrFn];
+    result[recordKey] = item;
+  }
+  return result;
+}
+function partition2(array, predicate) {
+  const matched = [];
+  const unmatched = [];
+  array.forEach((item, index) => {
+    if (predicate(item, index)) {
+      matched.push(item);
+    } else {
+      unmatched.push(item);
+    }
+  });
+  return [matched, unmatched];
+}
+function pickItemsInArray2(array, key, values) {
+  return array.filter((item) => values.includes(item[key]));
+}
+function toArray2(value) {
+  if (value == null)
+    return [];
+  if (Array.isArray(value))
+    return [...value];
+  return [value];
+}
+function sumBy2(array, keyOrFn) {
+  let sum = 0;
+  for (const item of array) {
+    const value = typeof keyOrFn === "function" ? keyOrFn(item) : item[keyOrFn];
+    sum += value ?? 0;
+  }
+  return sum;
+}
+function sortBy2(array, ...criteria) {
+  const comparators = (criteria.length ? criteria : [(item) => item]).map((criterion) => {
+    const { by, order } = typeof criterion === "object" ? criterion : { by: criterion, order: "asc" };
+    const select = (item) => typeof by === "function" ? by(item) : item[by];
+    const direction = order === "desc" ? -1 : 1;
+    return (left, right) => {
+      const a = select(left);
+      const b = select(right);
+      if (a == null || b == null)
+        return a == null ? b == null ? 0 : 1 : -1;
+      return a < b ? -direction : a > b ? direction : 0;
+    };
+  });
+  return [...array].sort((left, right) => {
+    for (const compare of comparators) {
+      const result = compare(left, right);
+      if (result !== 0)
+        return result;
+    }
+    return 0;
+  });
+}
+function range2(start, end, step) {
+  const from = end === undefined ? 0 : start;
+  const to = end ?? start;
+  const increment = step ?? (to < from ? -1 : 1);
+  if (increment === 0)
+    throw new Error("Step must not be zero");
+  const length = Math.max(Math.ceil((to - from) / increment), 0);
+  return Array.from({ length }, (_, index) => from + index * increment);
+}
+
+export { chunkArray2, findArrayDifferenceByKey2, getUniqueValues2, compact2, getUniqueValuesByKey2, groupBy2, countBy2, keyBy2, partition2, pickItemsInArray2, toArray2, sumBy2, sortBy2, range2 };