strict null checks (#19)

Author: Zheruel

CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] - 2025-09-07
+
+### Added
+
+- **Comprehensive Null/Undefined Safety** - All functions now handle null/undefined gracefully
+  - Added defensive null checks to 22+ functions that previously lacked them
+  - Consistent behavior across all utilities: string functions preserve null/undefined, boolean functions return false, array functions return empty arrays
+  - Zero runtime errors - functions no longer throw TypeErrors on null/undefined inputs
+  - Maintains full backward compatibility for valid string inputs
+  - Added 36 comprehensive tests for null/undefined handling
+  - No performance impact - benchmarks show consistent speed
+  - Minimal bundle size impact - only 0.02 kB increase
+
+### Improved
+
+- **Developer Experience** - Safer API with predictable edge case handling
+  - Users no longer need defensive checks before calling functions
+  - All functions behave consistently with falsy values
+  - Better alignment with TypeScript's strict null checks
+
 ## [0.8.0] - 2025-09-07
 
 ### Added

README.md

@@ -19,6 +19,7 @@ Ultra-lightweight string utilities with zero dependencies. Tree-shakeable, fully
 - ⚡ **ESM & CJS** - Works everywhere
 - 🧪 **100% tested** - Reliable and production-ready
 - 🔒 **Type-safe** - Written in strict TypeScript with enhanced type inference and compile-time transformations
+- 🛡️ **Null-safe** - All functions handle null/undefined gracefully without throwing errors
 - 📝 **Well documented** - JSDoc comments for all functions
 
 ## Installation
@@ -901,15 +902,15 @@ const result = camelCase(userInput);
 #### All Case Conversions Support Template Literals
 
 ```typescript
-camelCase("hello-world");    // Type: "helloWorld"
-kebabCase("helloWorld");     // Type: "hello-world"
-snakeCase("HelloWorld");     // Type: "hello_world"
-pascalCase("hello-world");   // Type: "HelloWorld"
-constantCase("helloWorld");  // Type: "HELLO_WORLD"
-dotCase("HelloWorld");       // Type: "hello.world"
-pathCase("helloWorld");      // Type: "hello/world"
+camelCase("hello-world"); // Type: "helloWorld"
+kebabCase("helloWorld"); // Type: "hello-world"
+snakeCase("HelloWorld"); // Type: "hello_world"
+pascalCase("hello-world"); // Type: "HelloWorld"
+constantCase("helloWorld"); // Type: "HELLO_WORLD"
+dotCase("HelloWorld"); // Type: "hello.world"
+pathCase("helloWorld"); // Type: "hello/world"
 sentenceCase("hello-world"); // Type: "Hello world"
-titleCase("hello-world");    // Type: "Hello World"
+titleCase("hello-world"); // Type: "Hello World"
 ```
 
 #### Type-Safe Configuration Objects
@@ -943,11 +944,39 @@ type MethodNames = {
 ```
 
 Benefits:
+
 - ✅ **Zero runtime cost** - All transformations happen at compile time
 - ✅ **Better IDE support** - Autocomplete shows exact transformed strings
 - ✅ **Type safety** - Catch typos and incorrect transformations during development
 - ✅ **Backward compatible** - Runtime strings work exactly as before
 
+### Null/Undefined Safety
+
+All functions in nano-string-utils handle null and undefined inputs gracefully:
+
+```typescript
+// No more runtime errors!
+slugify(null); // Returns: null
+slugify(undefined); // Returns: undefined
+slugify(""); // Returns: ""
+
+// Consistent behavior across all functions
+isEmail(null); // Returns: false (validation functions)
+words(null); // Returns: [] (array functions)
+wordCount(null); // Returns: 0 (counting functions)
+
+// Safe to use without defensive checks
+const userInput = getUserInput(); // might be null/undefined
+const slug = slugify(userInput); // Won't throw!
+```
+
+This means:
+
+- ✅ **No TypeErrors** - Functions never throw on null/undefined
+- ✅ **Predictable behavior** - Consistent handling across all utilities
+- ✅ **Cleaner code** - No need for defensive checks before calling functions
+- ✅ **Zero performance cost** - Minimal overhead from null checks
+
 ## Bundle Size
 
 Each utility is optimized to be as small as possible:

jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@zheruel/nano-string-utils",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "exports": "./src/index.ts",
   "publish": {
     "include": ["src/**/*.ts", "README.md", "LICENSE", "CHANGELOG.md"],

package.json

@@ -1,6 +1,6 @@
 {
   "name": "nano-string-utils",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Ultra-lightweight string utilities with zero dependencies",
   "type": "module",
   "main": "./dist/index.cjs",

src/camelCase.ts

@@ -16,6 +16,8 @@ import type { CamelCase } from "./types/string-literals.js";
 export function camelCase<T extends string>(str: T): CamelCase<T>;
 export function camelCase(str: string): string;
 export function camelCase(str: string): string {
+  if (!str) return str;
+
   const wordList = words(str);
 
   if (wordList.length === 0) return "";

src/codePoints.ts

@@ -9,6 +9,8 @@
  * codePoints('a👍b') // [97, 128077, 98]
  */
 export function codePoints(str: string): number[] {
+  if (!str) return [];
+
   const points: number[] = [];
   for (const char of str) {
     const point = char.codePointAt(0);

src/deburr.ts

@@ -29,6 +29,8 @@ const SPECIAL_CHARS_MAP: Record<string, string> = {
  * deburr('São Paulo') // 'Sao Paulo'
  */
 export function deburr(str: string): string {
+  if (!str) return str;
+
   // Replace special characters with single regex pass
   const result = str.replace(
     SPECIAL_CHARS_PATTERN,

src/escapeHtml.ts

@@ -17,6 +17,7 @@ const HTML_ENTITIES: Record<string, string> = {
  * escapeHtml("It's <script>") // 'It&#39;s &lt;script&gt;'
  */
 export const escapeHtml = (str: string): string => {
+  if (!str) return str;
   return str.replace(
     HTML_ESCAPE_REGEX,
     (match) => HTML_ENTITIES[match] ?? match

src/hashString.ts

@@ -7,6 +7,8 @@
  * hashString('world') // 3582672807
  */
 export const hashString = (str: string): number => {
+  if (str == null) return 0;
+
   let hash = 2166136261; // FNV offset basis
 
   if (str.length === 0) return hash >>> 0;

src/isASCII.ts

@@ -10,6 +10,8 @@
  * isASCII('') // true
  */
 export function isASCII(str: string): boolean {
+  if (str == null) return false;
+
   for (let i = 0; i < str.length; i++) {
     if (str.charCodeAt(i) > 127) {
       return false;