rename functions

.github/workflows/validate-merge-request.yml

@@ -1,11 +1,14 @@
-name: Validate @agape/string in monorepo context
+name: Validate @agape/string
 
 on:
   pull_request:
 
 jobs:
   test:
+    name: Unit Tests
     runs-on: ubuntu-latest
+    env:
+      NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}
 
     steps:
       - name: Checkout agape-string (this repo)
@@ -53,7 +56,7 @@ jobs:
             fi
           '
 
-      - name: Replace string code in monorepo
+      - name: Replace library code in monorepo
         run: |
           rm -rf ../AgapeToolkit/libs/string
           cp -r . ../AgapeToolkit/libs/string

README.md

@@ -1,97 +1,190 @@
 # @agape/string
 
-String and token manipulation
+String manipulation and transformation utilities for TypeScript.
 
-## Synopsis
+## ✨ Functions
 
-```
-camelize('user name')          // userName
-camelize('email-address')      // emailAddress
+### `toCamelCase(input: string)`
+Converts a string to camelCase format.
 
-kebabify('Display Name')       // display-name
-kebabify('userProfileId')      // user-profile-id
+### `toKebabCase(input: string)`
+Converts a string to kebab-case format.
 
-pascalize('user id')           // UserId
-pascalize('api_response_code') // ApiResponseCode
+### `toPascalCase(input: string)`
+Converts a string to PascalCase format.
 
-pluralize('city')              // cities
-pluralize('analysis')          // analyses
+### `toSnakeCase(input: string)`
+Converts a string to snake_case format.
 
-quantify(1, 'item')            // 1 item
-quantify(3, 'box')             // 3 boxes
+### `toTitleCase(input: string)`
+Converts a string to Title Case format.
 
-singularize('cities')          // city
-singularize('analyses')        // analysis
+### `toWords(input: string)`
+Converts identifiers to natural language words.
 
-snakify('userName')            // user_name
-snakify('APIResponseCode')     // api_response_code
+### `toPlural(word: string)`
+Converts a singular word to its plural form.
 
-titalize('the lord of the rings')  // The Lord of the Rings
-titalize('war and peace')          // War and Peace
+### `toSingular(word: string)`
+Converts a plural word to its singular form.
 
-verbalize('user-profile-id')   // User profile id
-verbalize('XMLHttpRequest')    // XML Http Request
-```
+### `quantify(count: number | string, unit: string, plural?: string)`
+Formats a number with a unit, automatically pluralizing based on count.
+
+---
+
+## 🚀 Example
+
+```ts
+import { 
+  toCamelCase, 
+  toKebabCase, 
+  toPascalCase, 
+  toSnakeCase, 
+  toTitleCase, 
+  toWords, 
+  toPlural, 
+  toSingular, 
+  quantify 
+} from '@agape/string';
+
+// Case conversion
+toCamelCase('user name')          // "userName"
+toCamelCase('email-address')      // "emailAddress"
+
+toKebabCase('Display Name')       // "display-name"
+toKebabCase('userProfileId')      // "user-profile-id"
 
-## Description
+toPascalCase('user id')           // "UserId"
+toPascalCase('api_response_code') // "ApiResponseCode"
+
+toSnakeCase('userName')           // "user_name"
+toSnakeCase('APIResponseCode')    // "api_response_code"
+
+toTitleCase('the lord of the rings')  // "The Lord of the Rings"
+toTitleCase('war and peace')          // "War and Peace"
+
+// Natural language
+toWords('user-profile-id')        // "User profile id"
+toWords('XMLHttpRequest')         // "XML Http Request"
+
+// Pluralization
+toPlural('city')                  // "cities"
+toPlural('analysis')              // "analyses"
+toPlural('API')                   // "APIs"
+
+toSingular('cities')              // "city"
+toSingular('analyses')            // "analysis"
+toSingular('APIs')                // "API"
+
+// Quantification
+quantify(1, 'item')               // "1 item"
+quantify(3, 'box')                // "3 boxes"
+quantify(1, 'child', 'children')  // "1 child"
+quantify(2, 'child', 'children')  // "2 children"
+quantify(5, 'CPU')                // "5 CPUs"
+```
 
-Translate strings between different representations.
+---
 
-## Functions
+## 🔧 Function Details
 
-`camelize(input: string)`
+### `toCamelCase(input: string)`
+Converts a string to camelCase by removing non-alphanumeric separators and capitalizing each word except the first.
 
-Convert to camel case.
+**Examples:**
+- `"hello world"` → `"helloWorld"`
+- `"API_response_code"` → `"apiResponseCode"`
+- `"user-42-profile"` → `"user42Profile"`
 
-`kebabify(input: string)`
+### `toKebabCase(input: string)`
+Converts a string to kebab-case by replacing spaces, underscores, and camelCase transitions with dashes. Preserves version tokens like "v2".
 
-Converted to kebab-case: lower case, word boundaries replaced with dashes. 
+**Examples:**
+- `"hello world"` → `"hello-world"`
+- `"UserProfileV2"` → `"user-profile-v2"`
+- `"HTML5 Parser"` → `"html-5-parser"`
 
-`pascalize(input: string)`
+### `toPascalCase(input: string)`
+Converts a string to PascalCase by removing non-alphanumeric characters, splitting on casing and digits, and capitalizing each word.
 
-Remove all symbols and spaces, captialize words.
+**Examples:**
+- `"hello world"` → `"HelloWorld"`
+- `"user42Profile"` → `"User42Profile"`
+- `"API response code"` → `"ApiResponseCode"`
 
-`pluralize(input: string)`
+### `toSnakeCase(input: string)`
+Converts a string to snake_case by replacing spaces, dashes, and camelCase transitions with underscores. Preserves version tokens.
 
-Adds an 's' to most words. Words that end in 'y' are changed to 'ies'. 
-Words that end in s have 'es' appended to the word. Handles special cases
-like children and geese.
+**Examples:**
+- `"hello world"` → `"hello_world"`
+- `"UserProfileV2"` → `"user_profile_v2"`
+- `"HTML5 Parser"` → `"html_5_parser"`
 
-`quantify(value: number, unit: string, plural?: string)`
+### `toTitleCase(input: string)`
+Converts a string to Title Case by capitalizing the first letter of each word, except for small words (like "of", "and", "the") unless they appear at the beginning.
 
-The value will be paired with the unit, either singular or plural form
+**Examples:**
+- `"the quick brown fox"` → `"The Quick Brown Fox"`
+- `"a tale of two cities"` → `"A Tale of Two Cities"`
+- `"API reference guide"` → `"API Reference Guide"`
 
-`singularize(input: string)`
+### `toWords(input: string)`
+Converts identifiers to natural language words by splitting camelCase, PascalCase, snake_case, and kebab-case into space-separated words.
 
-Converts a word to it's singular form if it is a plural. Removes the 's' from
-most words. Replacies 'ies' with 'y'. Removes 'es' from the end of a word.
-Handles special cases like 'child' and 'goose'.
+**Examples:**
+- `"userProfileId"` → `"User profile id"`
+- `"XMLHttpRequest"` → `"XML Http Request"`
+- `"api_v2_response"` → `"Api v2 response"`
 
-`snakify(input: string)`
+### `toPlural(word: string)`
+Converts a singular word to its plural form using common English pluralization rules.
 
-Converted to snake_case: lower case, word boundaries replaced with underscores. 
+**Features:**
+- Handles irregular plurals (child → children, person → people)
+- Preserves acronyms (API → APIs, ID → IDs)
+- Maintains original casing
 
-`titalize(input: number)`
+**Examples:**
+- `"city"` → `"cities"`
+- `"box"` → `"boxes"`
+- `"child"` → `"children"`
+- `"API"` → `"APIs"`
 
-The first letter of each word is capitalized with the exception of
-`a, an, and, at, be, but, by, for, if, in, of, on, the, to` which are only 
-capitalized if they are the first word in the string, otherwise they 
-are converted to lowercase.
+### `toSingular(word: string)`
+Converts a plural word to its singular form using common English patterns.
 
-`verbalize(input: number)`
+**Features:**
+- Handles irregular plurals (children → child, people → person)
+- Preserves original casing
+- Smart about double letters (boss → boss, not bo)
 
-First character capitalized, word boundaries replaced with spaces.
+**Examples:**
+- `"cities"` → `"city"`
+- `"boxes"` → `"box"`
+- `"children"` → `"child"`
+- `"APIs"` → `"API"`
 
+### `quantify(count: number | string, unit: string, plural?: string)`
+Formats a number with a unit, automatically pluralizing the unit based on the count.
 
-## Author
+**Parameters:**
+- `count`: Number of units (number or string)
+- `unit`: Label for the singular unit
+- `plural`: Optional plural label (auto-generated if not provided)
 
-Maverik Minett  maverik.minett@gmail.com
+**Examples:**
+- `quantify(1, 'item')` → `"1 item"`
+- `quantify(3, 'box')` → `"3 boxes"`
+- `quantify(1, 'child', 'children')` → `"1 child"`
+- `quantify(2, 'child', 'children')` → `"2 children"`
 
+---
 
-## Copyright
+## 📚 Documentation
 
-© 2020-2025 Maverik Minett
+See the full API documentation at [agape.dev/api](https://agape.dev/api).
 
-## License
+## 📦 Agape Toolkit
 
-MIT
+This package is part of the [Agape Toolkit](https://github.com/AgapeToolkit/AgapeToolkit) - a comprehensive collection of TypeScript utilities and libraries for modern web development.

package.json

@@ -1,16 +1,17 @@
 {
   "name": "@agape/string",
-  "version": "2.2.6",
+  "version": "3.0.0",
   "description": "String and token manipulation",
   "main": "./cjs/index.js",
   "module": "./es2020/index.js",
   "keywords": [
     "agape",
     "string"
   ],
+  "homepage": "https://agape.dev",
   "repository": {
     "type": "git",
-    "url": "https://github.com/AgapeToolkit/agape-string"
+    "url": "https://github.com/AgapeToolkit/AgapeToolkit"
   },
   "author": "Maverik Minett",
   "license": "MIT",

src/index.ts

@@ -1,8 +1,8 @@
-export * from './lib/functions/camelize';
-export * from './lib/functions/kebabify';
-export * from './lib/functions/pascalize';
+export * from './lib/functions/toCamelCase';
+export * from './lib/functions/toKebabCase';
+export * from './lib/functions/toPascalCase';
 export * from './lib/functions/quantify';
-export * from './lib/functions/singularize';
-export * from './lib/functions/snakify';
-export * from './lib/functions/titalize';
-export * from './lib/functions/verbalize';
+export * from './lib/functions/toSingular';
+export * from './lib/functions/toSnakeCase';
+export * from './lib/functions/toTitleCase';
+export * from './lib/functions/toWords';