@ppabari/strio 1.0.2 → 1.1.0

package/CHANGELOG.md

@@ -6,6 +6,48 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [1.1.0] — 2026-07-07
+
+### Added
+
+**String-utility toolkit** — new `@ppabari/strio/str` subpath export (~60 pure, tree-shakeable functions):
+
+- **Manipulation** — `capitalize`, `capitalizeWords`, `reverse`, `truncate`, `truncateWords`, `trim`, `insert`, `mask`
+- **Case conversion** — `camelize`, `pascalize`, `dasherize`, `underscore`
+- **Validation** — `isEmpty`, `isBlank`, `isString`, `isAlpha`, `isNumeric`, `isAlphaNumeric`, `isUpperCase`, `isLowerCase`
+- **Searching** — `contains`, `containsAll`, `containsAny`, `count`, `between`, `betweenAll`
+- **Formatting** — `humanize`, `titleCase`, `slugify`, `ordinalize`, `pluralize`
+- **Utilities** — `words`, `wordCount`, `join`, `template`, `random`, `randomAlpha`, `randomNumeric`, `randomAlphanumeric`, `similarity`, `transliterate`
+- **Padding & indentation** — `padLeft`, `padRight`, `padCenter`, `indent`, `dedent`
+- **Security** — `escapeHtml`, `unescapeHtml`, `escapeRegExp`, `stripTags`, `collapseWhitespace`, `stripPrefix`, `stripSuffix`
+- **Ensuring** — `ensureLeft`, `ensureRight`
+
+> The `random*` helpers reuse the same bias-free Web-Crypto engine as the core library, so they are cryptographically secure.
+
+**Compatibility checks** (main export)
+
+- `checkCompatibility()` — inspect the runtime (Web Crypto availability, detected runtime, Node version) without throwing
+- `assertCompatible()` — throw a descriptive error on an unsupported runtime
+- `MIN_NODE_VERSION` constant and `CompatibilityResult` / `Runtime` types
+- CLI: new `--check` (alias `--compat`) flag prints a compatibility report
+
+**Docs**
+
+- New VitePress documentation site with a categorized API reference
+
+### Maintenance
+
+- Upgraded the entire dev toolchain to latest — `vitest` & `@vitest/coverage-v8` v4, `vitepress` v2, `typescript` v6, `@types/node` v26, `zod` v4 (dev/test only) — resolving **all** `npm audit` findings (6 → 0, including the vite dev-server high/critical advisories). All were dev-only and never affected the published package.
+- Pinned transitive `esbuild` to a safe `0.27.2` via `overrides`.
+- Added `"ignoreDeprecations": "6.0"` to `tsconfig.json` for TypeScript 6 compatibility.
+- Note: building/testing the package now requires Node ≥ 20 (per vitest 4). The published library's **runtime** support is unchanged — still Node ≥ 18, browsers, Deno, Bun, and edge runtimes.
+
+### Notes
+
+- Fully backward compatible — no changes to the existing `.` or `/zod` surface. String utilities are isolated under `/str`, so names that overlap conceptually with the core API (`random`, `mask`) do not collide.
+
+---
+
 ## [1.0.0] — 2025
 
 ### Added

package/README.md

@@ -1,11 +1,13 @@
 # @ppabari/strio
 
-Cryptographically secure string generation for Node.js and browsers.  
-Tokens · IDs · Passphrases · Patterns · Expiring tokens — bias-free, zero dependencies, fully typed.
+Cryptographically secure string generation **and** a general-purpose string-utility toolkit for Node.js and browsers.  
+Tokens · IDs · Passphrases · Patterns · Expiring tokens · 60+ string helpers — bias-free, zero dependencies, fully typed.
 
 [![npm](https://img.shields.io/npm/v/@ppabari/strio)](https://www.npmjs.com/package/@ppabari/strio)
 [![license](https://img.shields.io/npm/l/@ppabari/strio)](./LICENSE)
-[![tests](https://img.shields.io/github/actions/workflow/status/ppabari/strio/ci.yml?label=tests)](https://github.com/ppabari/strio/actions)
+[![tests](https://img.shields.io/github/actions/workflow/status/parthpabari/strio/ci.yml?label=tests)](https://github.com/parthpabari/strio/actions)
+
+📖 **[Documentation](https://parthpabari.github.io/strio/)** · [API Reference](https://parthpabari.github.io/strio/api/overview)
 
 ---
 
@@ -61,11 +63,63 @@ npx @ppabari/strio --passphrase --words 5 --capitalize
 npx @ppabari/strio --id --prefix usr
 npx @ppabari/strio --expiring --ttl 900
 npx @ppabari/strio --entropy --preset PASSWORD
+npx @ppabari/strio --check                  # runtime compatibility report
 npx @ppabari/strio --help
 ```
 
 ---
 
+## String Utility Toolkit
+
+Beyond secure generation, strio ships **60+ general-purpose string helpers** from the tree-shakeable `@ppabari/strio/str` subpath. Every function is a pure named export.
+
+```ts
+import { slugify, camelize, truncate, pluralize } from '@ppabari/strio/str';
+
+slugify('Héllo, World!');            // → 'hello-world'
+camelize('foo-bar_baz');             // → 'fooBarBaz'
+truncate('The quick brown fox', 12); // → 'The quick b…'
+pluralize('child');                  // → 'children'
+```
+
+| Category | Functions |
+| --- | --- |
+| **Manipulation** | `capitalize` `capitalizeWords` `reverse` `truncate` `truncateWords` `trim` `insert` `mask` |
+| **Case Conversion** | `camelize` `pascalize` `dasherize` `underscore` |
+| **Validation** | `isEmpty` `isBlank` `isString` `isAlpha` `isNumeric` `isAlphaNumeric` `isUpperCase` `isLowerCase` |
+| **Searching** | `contains` `containsAll` `containsAny` `count` `between` `betweenAll` |
+| **Formatting** | `humanize` `titleCase` `slugify` `ordinalize` `pluralize` |
+| **Utilities** | `words` `wordCount` `join` `template` `random` `randomAlpha` `randomNumeric` `randomAlphanumeric` `similarity` `transliterate` |
+| **Padding & Indentation** | `padLeft` `padRight` `padCenter` `indent` `dedent` |
+| **Security** | `escapeHtml` `unescapeHtml` `escapeRegExp` `stripTags` `collapseWhitespace` `stripPrefix` `stripSuffix` |
+| **Ensuring** | `ensureLeft` `ensureRight` |
+
+> The `random*` helpers reuse the same bias-free Web-Crypto engine as the core library — they are cryptographically secure, not `Math.random`.
+
+Full signatures and examples: **[API Reference →](https://parthpabari.github.io/strio/api/overview)**
+
+---
+
+## Compatibility Check
+
+```ts
+import { checkCompatibility, assertCompatible } from '@ppabari/strio';
+
+const report = checkCompatibility();
+// { ok: true, cryptoAvailable: true, runtime: 'node', nodeVersion: '20.11.0', warnings: [] }
+
+assertCompatible(); // throws on an unsupported runtime
+```
+
+| Environment | Supported |
+| --- | --- |
+| Node.js | ✅ ≥ 18 |
+| Browsers (modern) | ✅ |
+| Deno · Bun · Cloudflare Workers | ✅ |
+| TypeScript | ✅ ≥ 5.0 |
+
+---
+
 ## Core API
 
 ### `generateRandomString(options?)`

package/dist/bin/strio.js

@@ -1218,6 +1218,47 @@ function approximateCombinations(charsetSize, length) {
   return Math.round(Math.pow(charsetSize, length)).toString();
 }
 
+// src/compat.ts
+var MIN_NODE_VERSION = 18;
+function detectRuntime() {
+  const g = globalThis;
+  if (typeof g.Deno !== "undefined") return { runtime: "deno" };
+  if (typeof g.Bun !== "undefined") return { runtime: "bun" };
+  if (typeof g.process !== "undefined" && g.process?.versions?.node) {
+    return { runtime: "node", nodeVersion: String(g.process.versions.node) };
+  }
+  if (typeof g.WebSocketPair !== "undefined") return { runtime: "workerd" };
+  if (typeof g.window !== "undefined" || typeof g.document !== "undefined") {
+    return { runtime: "browser" };
+  }
+  return { runtime: "unknown" };
+}
+function checkCompatibility() {
+  const warnings = [];
+  const { runtime, nodeVersion } = detectRuntime();
+  const cryptoAvailable = typeof globalThis.crypto !== "undefined" && typeof globalThis.crypto.getRandomValues === "function";
+  if (!cryptoAvailable) {
+    warnings.push(
+      "Web Crypto API (crypto.getRandomValues) is unavailable. Secure generation will fail. On Node.js, upgrade to v18 or newer."
+    );
+  }
+  if (runtime === "node" && nodeVersion) {
+    const major = parseInt(nodeVersion.split(".")[0] ?? "0", 10);
+    if (major < MIN_NODE_VERSION) {
+      warnings.push(
+        `Node.js ${nodeVersion} is below the supported minimum (v${MIN_NODE_VERSION}). Please upgrade.`
+      );
+    }
+  }
+  return {
+    ok: cryptoAvailable && warnings.length === 0,
+    cryptoAvailable,
+    runtime,
+    ...nodeVersion ? { nodeVersion } : {},
+    warnings
+  };
+}
+
 // src/presets.ts
 var PRESETS = {
   /**
@@ -1380,6 +1421,7 @@ if (hasFlag("help") || hasFlag("h")) {
       --payload <n>       Payload length (default: 24)
 
     --entropy             Show entropy estimate only (no string generated)
+    --check               Check runtime compatibility and exit
 
   PRESETS
     TOKEN       32-char alphanumeric API token
@@ -1406,6 +1448,17 @@ if (hasFlag("help") || hasFlag("h")) {
 `);
   process.exit(0);
 }
+if (hasFlag("check") || hasFlag("compat")) {
+  const report = checkCompatibility();
+  console.log(`Runtime        : ${report.runtime}${report.nodeVersion ? ` (Node ${report.nodeVersion})` : ""}`);
+  console.log(`Web Crypto     : ${report.cryptoAvailable ? "available" : "MISSING"}`);
+  console.log(`Compatible     : ${report.ok ? "yes" : "no"}`);
+  if (report.warnings.length > 0) {
+    console.log("Warnings       :");
+    report.warnings.forEach((w) => console.log(`  - ${w}`));
+  }
+  process.exit(report.ok ? 0 : 1);
+}
 if (hasFlag("passphrase")) {
   const words = parseInt(getFlag("words") ?? "4", 10);
   const separator = getFlag("separator") ?? "-";

package/dist/index.cjs

@@ -1431,6 +1431,54 @@ function validatePattern(str, pattern) {
   return errors;
 }
 
+// src/compat.ts
+var MIN_NODE_VERSION = 18;
+function detectRuntime() {
+  const g = globalThis;
+  if (typeof g.Deno !== "undefined") return { runtime: "deno" };
+  if (typeof g.Bun !== "undefined") return { runtime: "bun" };
+  if (typeof g.process !== "undefined" && g.process?.versions?.node) {
+    return { runtime: "node", nodeVersion: String(g.process.versions.node) };
+  }
+  if (typeof g.WebSocketPair !== "undefined") return { runtime: "workerd" };
+  if (typeof g.window !== "undefined" || typeof g.document !== "undefined") {
+    return { runtime: "browser" };
+  }
+  return { runtime: "unknown" };
+}
+function checkCompatibility() {
+  const warnings = [];
+  const { runtime, nodeVersion } = detectRuntime();
+  const cryptoAvailable = typeof globalThis.crypto !== "undefined" && typeof globalThis.crypto.getRandomValues === "function";
+  if (!cryptoAvailable) {
+    warnings.push(
+      "Web Crypto API (crypto.getRandomValues) is unavailable. Secure generation will fail. On Node.js, upgrade to v18 or newer."
+    );
+  }
+  if (runtime === "node" && nodeVersion) {
+    const major = parseInt(nodeVersion.split(".")[0] ?? "0", 10);
+    if (major < MIN_NODE_VERSION) {
+      warnings.push(
+        `Node.js ${nodeVersion} is below the supported minimum (v${MIN_NODE_VERSION}). Please upgrade.`
+      );
+    }
+  }
+  return {
+    ok: cryptoAvailable && warnings.length === 0,
+    cryptoAvailable,
+    runtime,
+    ...nodeVersion ? { nodeVersion } : {},
+    warnings
+  };
+}
+function assertCompatible() {
+  const report = checkCompatibility();
+  if (!report.ok) {
+    throw new Error(`@ppabari/strio: incompatible runtime.
+- ${report.warnings.join("\n- ")}`);
+  }
+}
+
 // src/presets.ts
 var PRESETS = {
   /**
@@ -1880,7 +1928,10 @@ async function generateRandomStringAsync(options = {}) {
 
 exports.BUILT_IN_WORD_LIST = WORD_LIST;
 exports.CHARSET_ALIASES = CHARSET_ALIASES;
+exports.MIN_NODE_VERSION = MIN_NODE_VERSION;
 exports.PRESETS = PRESETS;
+exports.assertCompatible = assertCompatible;
+exports.checkCompatibility = checkCompatibility;
 exports.estimateEntropy = estimateEntropy;
 exports.generateAesKey = generateAesKey;
 exports.generateApiKey = generateApiKey;