@stackonward/utils

Focused framework-independent helpers shared by StackOnward packages: bounded logging, random values, DOM scrolling, idempotency-key construction, string normalization, password-strength checks, schema-guided coercion, and localized text fallback.

Import only the operations you need; the package is side-effect free apart from explicit logging and DOM calls.

Install

pnpm add @stackonward/utils

Usage

import {
  createIdempotencyKey,
  createLocalizedTextResolver,
  coerceParamsBySchema,
} from "@stackonward/utils";

const idempotencyKey = createIdempotencyKey("asset-upload");
const resolveText = createLocalizedTextResolver(["en"]);
const label = resolveText({ en: "Continue", fr: "Continuer" }, "fr", "Continue");

const params = coerceParamsBySchema(
  { duration: "5", enabled: "true" },
  {
    properties: {
      duration: { type: "integer" },
      enabled: { type: "boolean" },
    },
  },
);

Public API

| Area | Exports | | ---------------------------- | ------------------------------------------------------------------------------------ | | Logging | logger, LogLevel, logDebug, logInfo, logWarn, logError | | Random values | getRandomInt, getRandomFloat, getSeedRange, getRandomString, getRandomUUID | | DOM scrolling | findScrollParent, scrollToTop, scrollElementIntoContainer | | Operation identity | createIdempotencyKey | | Strings and analytics values | toUrlSlug, toAnalyticsKey, hasAnalyticsValue | | Password UX | validatePasswordStrength | | Schema coercion | coerceParamsBySchema and its schema contracts | | Localized text | resolveLocalizedText, createLocalizedTextResolver |

Important boundaries

• Random helpers use Math.random and are not suitable for passwords, signing keys, session locators, or other security tokens.
• createIdempotencyKey prefers crypto.randomUUID; its fallback is for operation correlation, not authentication material.
• validatePasswordStrength provides client-side UX feedback. The server still owns password policy, breach checks, and password hashing.
• coerceParamsBySchema handles flat string, number, integer, and boolean fields. Unsafe conversions remain unchanged for the real validator to reject.
• toUrlSlug lowercases and replaces whitespace only; it is not a complete international slugification or URL-encoding function.
• DOM helpers require browser globals when invoked.
• Localized fallback order is current locale, configured fallbacks, first non-empty map value, then the caller fallback.

Logging behavior

The logger defaults to debug level outside NODE_ENV=production and error level in production. Debug, info, and warning output is development-only; errors remain enabled. Library and application code must not pass secrets, tokens, signed URLs, or user payloads to the logger.

Compatibility

• ESM with TypeScript declarations
• Pure helpers run in standard JavaScript runtimes
• DOM helpers require a modern browser

License

MIT