Release Helper Tools 0.1.0

2026-09-01 02:33:45 +02:00
commit 5fffd48642
78 changed files with 11635 additions and 0 deletions
@@ -0,0 +1,82 @@
+# 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.
+
+Version 0.1.0 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.
+
+## Browser app
+
+```sh
+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:
+
+```ts
+import {
+  bytesToBase64Url,
+  digestHex,
+  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}');
+```
+
+See [`docs/API.md`](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:
+
+```sh
+npm run build:library
+npm pack --dry-run
+```
+
+## Verification and artifacts
+
+```sh
+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`](LICENSE). Shared Toolbox SDK and React notices
+remain under their respective licences in `THIRD_PARTY_NOTICES.md` and the
+generated release inventory.