Various Improvements - v0.20.0 (#43)

* chore: bump version to 0.20.0 and update package metadata

feat: enhance documentation with examples for string utility functions
- Added detailed examples for `capitalize`, `codePoints`, `deburr`, `detectScript`, `escapeHtml`, `fuzzyMatch`, `graphemes`, `hashString`, `pad`, `padEnd`, `padStart`, `pluralize`, `randomString`, `reverse`, `singularize`, `smartSplit`, `stripHtml`, `toASCII`, and `wordCount`.

feat: introduce SafeHTML type and sanitization functions
- Added `SafeHTML` branded type for sanitized HTML.
- Implemented `toSafeHTML` for sanitizing strings into SafeHTML.
- Added `unsafeSafeHTML` for casting strings to SafeHTML without sanitization.

fix: update size limits in package.json for better performance
- Adjusted size limits for `dist/index.js` and `dist/index.cjs`.

test: add unit tests for new SafeHTML functionality
- Created tests for `toSafeHTML` and `unsafeSafeHTML` to ensure proper sanitization and type safety.

* update package json

Author: Zheruel

CHANGELOG.md

@@ -7,6 +7,58 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.20.0] - 2025-10-09
+
+### Added
+
+- **New Branded Type: `SafeHTML`** - Compile-time XSS prevention with type-safe HTML sanitization
+
+  - New `toSafeHTML()` builder function creates sanitized HTML with opinionated secure defaults
+    - Strips all HTML by default for maximum security
+    - Removes script tags and dangerous content
+    - Removes non-printable characters
+    - Optional configuration to allow specific safe tags
+  - New `unsafeSafeHTML()` for trusted input bypass (use with caution)
+  - Zero runtime overhead - type safety enforced at compile time
+  - Full test coverage with 11 comprehensive tests
+  - Integrates with existing branded type system alongside `Email`, `URL`, and `Slug`
+
+- **Brand Pattern Documentation** - Comprehensive guide for extending the type system
+
+  - Added "Extending with Custom Branded Types" section to README
+  - Examples showing how to create custom branded types (PhoneNumber, PostalCode, CreditCard)
+  - Pattern demonstrates type-safe constructors and validation without bloating the library
+  - Shows composability of custom types with built-in branded types
+
+- **Enhanced JSDoc Examples** - Real-world usage examples for better developer experience
+  - Added comprehensive TypeScript examples to 20+ utility functions
+  - All examples now use proper ```ts code blocks for syntax highlighting
+  - Includes practical use cases: form validation, search normalization, file naming, etc.
+  - Functions enhanced: `capitalize`, `codePoints`, `deburr`, `detectScript`, `escapeHtml`, `graphemes`, `hashString`, `pad`, `padEnd`, `padStart`, `pluralize`, `randomString`, `reverse`, `singularize`, `smartSplit`, `stripHtml`, `toASCII`
+
+### Fixed
+
+- **Type Safety** - Resolved TypeScript strict mode violations with array access
+  - Added non-null assertions for mathematically guaranteed valid array access in `levenshtein`, `pad`, `fuzzyMatch`, `smartSplit`
+  - Fixed `randomString` to handle empty charset edge case (early return)
+  - Zero runtime cost fixes - all type assertions validated by algorithm guarantees
+  - All 1207 tests passing
+
+### Changed
+
+- **Bundle Size Limits** - Increased to accommodate SafeHTML feature
+  - ESM: 9.1 KB → 9.5 KB (+400 bytes headroom)
+  - CJS: 9.5 KB → 10 KB (+500 bytes headroom)
+  - Current actual size: 8.84 KB ESM / 9.36 KB CJS (well under new limits)
+  - SafeHTML adds ~500 bytes for compile-time XSS prevention
+
+### Security
+
+- **XSS Prevention** - SafeHTML branded type provides compile-time protection against XSS attacks
+  - Functions accepting user input can now require `SafeHTML` type
+  - Compiler enforces sanitization before rendering untrusted content
+  - Type system prevents accidentally using unvalidated strings in unsafe contexts
+
 ## [0.19.1] - 2025-10-07
 
 ### Changed
@@ -510,6 +562,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 100% test coverage for utility functions
 - Modern build tooling with tsup and Vitest
 
+[0.20.0]: https://github.com/Zheruel/nano-string-utils/releases/tag/v0.20.0
 [0.19.1]: https://github.com/Zheruel/nano-string-utils/releases/tag/v0.19.1
 [0.19.0]: https://github.com/Zheruel/nano-string-utils/releases/tag/v0.19.0
 [0.18.0]: https://github.com/Zheruel/nano-string-utils/releases/tag/v0.18.0

README.md

@@ -1310,6 +1310,62 @@ if (validated) {
 }
 ```
 
+#### Extending with Custom Branded Types
+
+The `Brand<T, K>` utility allows you to create your own custom branded types beyond the built-in ones. This is perfect for domain-specific validation without bloating the library.
+
+```typescript
+import type { Brand } from "nano-string-utils";
+import { sanitize } from "nano-string-utils";
+
+// Create custom branded types for your domain
+type PhoneNumber = Brand<string, "PhoneNumber">;
+type PostalCode = Brand<string, "PostalCode">;
+type CreditCard = Brand<string, "CreditCard">;
+
+// Build type-safe constructors
+function toPhoneNumber(str: string): PhoneNumber | null {
+  const cleaned = str.replace(/\D/g, "");
+  if (cleaned.length === 10 || cleaned.length === 11) {
+    return cleaned as PhoneNumber;
+  }
+  return null;
+}
+
+function toPostalCode(str: string): PostalCode | null {
+  // US ZIP code validation
+  if (/^\d{5}(-\d{4})?$/.test(str)) {
+    return str as PostalCode;
+  }
+  return null;
+}
+
+// Type guards for runtime checking
+function isPhoneNumber(str: string): str is PhoneNumber {
+  return toPhoneNumber(str) !== null;
+}
+
+// Use in your application
+function sendSMS(phone: PhoneNumber, message: string) {
+  // Can only be called with validated phone numbers
+  console.log(`Sending to ${phone}: ${message}`);
+}
+
+const userInput = "(555) 123-4567";
+const phone = toPhoneNumber(userInput);
+if (phone) {
+  sendSMS(phone); // ✅ Type safe!
+}
+// sendSMS(userInput); // ❌ Type error - string is not PhoneNumber
+```
+
+This pattern gives you:
+
+- **Compile-time safety** - Prevent using unvalidated data
+- **Zero bundle cost** - Only import what you use from the library
+- **Domain modeling** - Express business rules in the type system
+- **Composability** - Mix custom types with built-in branded types
+
 ### Template Literal Types (TypeScript)
 
 Case conversion functions now provide precise type inference for literal strings at compile time. This feature enhances IDE support with exact type transformations while maintaining full backward compatibility.
@@ -1534,14 +1590,11 @@ We continuously benchmark nano-string-utils against popular alternatives (lodash
 ### Running Benchmarks
 
 ```bash
-# Run all benchmarks
-npm run bench:all
-
-# Run performance benchmarks only
-npm run bench:perf
+# Run vitest benchmark tests
+npm run bench
 
-# Run bundle size analysis only
-npm run bench:size
+# Generate benchmark data for docs website
+npm run bench:data
 ```
 
 ### Latest Results
@@ -1578,7 +1631,7 @@ npm run bench:size
 
 - 🏆 **Smallest bundle sizes**: nano-string-utils wins 47 out of 48 tested functions (98% win rate)
 - ⚡ **Competitive performance**: Wins 10 out of 14 benchmarked functions against es-toolkit
-- 📊 **Detailed benchmarks**: See [benchmark-results.md](./benchmarks/benchmark-results.md) for full comparison
+- 📊 **[View full interactive benchmarks](https://zheruel.github.io/nano-string-utils/#bundle-size)** with detailed comparison
 - ⚡ **Optimized performance**:
   - **Case conversions**: 3.4M-4.3M ops/s, competitive with es-toolkit
   - **Truncate**: 23.4M ops/s for fast string truncation

benchmarks/benchmark-results.md

@@ -280,66 +280,6 @@ function formatBytes(bytes: number): string {
   return kb < 10 ? `${kb.toFixed(1)}KB` : `${Math.round(kb)}KB`;
 }
 
-function generateMarkdownTable(metrics: DetailedSizeMetrics[]): string {
-  let markdown = "# Bundle Size Comparison\n\n";
-  markdown += "## Overview\n\n";
-
-  // Summary stats
-  const totalNanoWins = metrics.filter((m) => m.winner === "nano").length;
-  const avgSavings =
-    metrics
-      .filter((m) => m.percentSavings !== undefined)
-      .reduce((sum, m) => sum + (m.percentSavings || 0), 0) / metrics.length;
-
-  markdown += `- **Total Functions**: ${metrics.length}\n`;
-  markdown += `- **Nano Wins**: ${totalNanoWins}/${metrics.length}\n`;
-  markdown += `- **Average Size Reduction**: ${Math.round(avgSavings)}%\n\n`;
-
-  markdown += "## Detailed Comparison\n\n";
-  markdown +=
-    "Sizes shown are minified (gzipped). For nano-string-utils, tree-shaken size is shown when different from bundled.\n\n";
-  markdown +=
-    "| Function | nano-string-utils | lodash | es-toolkit | Winner | Savings |\n";
-  markdown +=
-    "|----------|-------------------|--------|------------|--------|----------|\n";
-
-  for (const metric of metrics.sort((a, b) =>
-    a.function.localeCompare(b.function)
-  )) {
-    const nanoSize =
-      metric.nano.treeShaken.gzipped !== metric.nano.gzipped
-        ? `${formatBytes(metric.nano.minified)} (${formatBytes(
-            metric.nano.gzipped
-          )}) → ${formatBytes(metric.nano.treeShaken.minified)} (${formatBytes(
-            metric.nano.treeShaken.gzipped
-          )})`
-        : `${formatBytes(metric.nano.minified)} (${formatBytes(
-            metric.nano.gzipped
-          )})`;
-
-    const lodashSize = metric.lodash
-      ? `${formatBytes(metric.lodash.minified)} (${formatBytes(
-          metric.lodash.gzipped
-        )})`
-      : "-";
-
-    const esToolkitSize = metric.esToolkit
-      ? `${formatBytes(metric.esToolkit.minified)} (${formatBytes(
-          metric.esToolkit.gzipped
-        )})`
-      : "-";
-
-    const savingsStr =
-      metric.percentSavings !== undefined ? `${metric.percentSavings}%` : "-";
-
-    const winnerIcon = metric.winner === "nano" ? "🏆" : "";
-
-    markdown += `| ${metric.function} | ${nanoSize} | ${lodashSize} | ${esToolkitSize} | ${metric.winner} ${winnerIcon} | ${savingsStr} |\n`;
-  }
-
-  return markdown;
-}
-
 async function generateJSONReport(metrics: DetailedSizeMetrics[]) {
   const outputPath = path.join(__dirname, "bundle-sizes.json");
 
@@ -401,17 +341,9 @@ if (import.meta.url === `file://${process.argv[1]}`) {
   console.log("🚀 nano-string-utils Bundle Size Analysis\n");
   generateBundleSizeReport()
     .then(async ({ results, detailedMetrics }) => {
-      // Generate and save markdown report
-      const markdown = generateMarkdownTable(detailedMetrics);
-      console.log("\n" + markdown);
-
-      const mdPath = path.join(__dirname, "bundle-size-results.md");
-      await fs.writeFile(mdPath, markdown);
-      console.log(`\n✅ Markdown report saved to ${mdPath}`);
-
       // Generate and save JSON report
       const jsonPath = await generateJSONReport(detailedMetrics);
-      console.log(`✅ JSON report saved to ${jsonPath}`);
+      console.log(`\n✅ JSON report saved to ${jsonPath}`);
 
       // Copy to public directory for serving in documentation site
       const publicJsonPath = path.join(
@@ -423,9 +355,25 @@ if (import.meta.url === `file://${process.argv[1]}`) {
       );
       await fs.mkdir(path.dirname(publicJsonPath), { recursive: true });
       await fs.copyFile(jsonPath, publicJsonPath);
-      console.log(`✅ JSON copied to public at ${publicJsonPath}`);
+      console.log(`✅ JSON copied to docs-src/public/`);
+
+      // Summary
+      const totalNanoWins = detailedMetrics.filter(
+        (m) => m.winner === "nano"
+      ).length;
+      const avgSavings = Math.round(
+        detailedMetrics
+          .filter((m) => m.percentSavings !== undefined)
+          .reduce((sum, m) => sum + (m.percentSavings || 0), 0) /
+          detailedMetrics.length
+      );
+
+      console.log(`\n📊 Summary:`);
+      console.log(`   - Total functions: ${detailedMetrics.length}`);
+      console.log(`   - Nano wins: ${totalNanoWins}/${detailedMetrics.length}`);
+      console.log(`   - Average size reduction: ${avgSavings}%`);
     })
     .catch(console.error);
 }
 
-export { measureBundleSize, generateBundleSizeReport, generateMarkdownTable };
+export { measureBundleSize, generateBundleSizeReport, formatBytes };