83 lines
2.6 KiB
Markdown
83 lines
2.6 KiB
Markdown
# 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.
|