helper-tools/README.md

Helper Tools

Helper Tools is a local-first browser workbench and the source of the @add-ideas/toolbox-helpers TypeScript package. It provides small, explicit, bounded building blocks for common developer calculations without network requests, telemetry, persistence, or server processing.

The reusable package includes:

• strict Base64, Base64URL, hexadecimal, UTF-8, UTF-16 and Latin-1 conversion;
• URL component and form encoding, Unicode scalar/grapheme inspection, case, normalization and line-ending transforms;
• exact BigInt base conversion, SI/IEC data sizes, and common physical units;
• CRC-32, Adler-32, FNV-1a and Web Crypto SHA digests;
• strict IPv4/IPv6 parsing and exact CIDR ranges and containment;
• timestamp and bounded duration parsing and formatting;
• hardened JSON parsing, deterministic JSON and bounded CSV conversion; and
• secure random bytes/integers plus explicitly non-cryptographic seeded random primitives for repeatable tests and samples;
• checked offset arithmetic and a bounded typed byte cursor for binary parsers;
• deterministic byte-size formatting, collision-free multi-file download plans, and explicit Blob URL lease pools;
• cancellable disposable-worker jobs with progress and hard deadlines; and
• incremental CRC-32, Adler-32 and FNV-1a processing plus bounded, cancellable byte-source reads for Web Crypto digests.

Browser app

npm ci
npm run dev

All workspaces are deep-linkable through URL hashes. Values live only in React component state and disappear on refresh. Downloads use short-lived object URLs that are revoked after use.

Reusable package

The package is framework-free ESM with generated TypeScript declarations and no install/runtime dependency. React and the Toolbox SDK are development-only app build inputs and are not dependencies of package consumers. Every helper is exported from one stable root:

import {
  ByteCursor,
  bytesToBase64Url,
  createIncrementalChecksum,
  digestHex,
  formatBytes,
  parseCidr,
  safeJsonParse,
} from "@add-ideas/toolbox-helpers";

const token = bytesToBase64Url(new Uint8Array([1, 2, 3]));
const hash = await digestHex(new TextEncoder().encode("local"));
const network = parseCidr("2001:db8::1/64");
const data = safeJsonParse('{"enabled":true}');
const size = formatBytes(1_572_864); // 1.50 MiB
const cursor = new ByteCursor(new Uint8Array([0, 1, 0, 2]));
const first = cursor.readUint16();
const checksum = createIncrementalChecksum("CRC-32").update(
  new Uint8Array([1, 2, 3]),
);

See docs/API.md for the export groups and their security boundaries. The browser app imports the same public root implementation; it does not maintain a second calculator code path.

Build and inspect the package locally:

npm run build:library
npm pack --dry-run

Verification and artifacts

npm run check
npm run test:browser
npm run package:release -- --force
npm run package:library -- --force

The application ZIP and npm-compatible .tgz are produced deterministically with adjacent SHA-256 sidecars in release/. Neither artifact is published by these commands.

Licence

Helper Tools and @add-ideas/toolbox-helpers are licensed under GPL-3.0-or-later. See LICENSE. Shared Toolbox SDK and React notices remain under their respective licences in THIRD_PARTY_NOTICES.md and the generated release inventory.