ts-packages 2.0.0 → 3.0.0

package/packages/js-extensions/src/string/string-extensions.ts

@@ -1,138 +1,142 @@
-// String prototype extensions
+import { defineExtension } from "src/utils"
+
+
+let stringExtended = false
+
 export function extendString() {
-	String.prototype.toCapitalize = function (): string {
+	if (stringExtended) return
+	stringExtended = true
+
+	defineExtension(String.prototype, 'toCapitalize', function (this: string): string {
 		return this.charAt(0).toUpperCase() + this.slice(1).toLowerCase()
-	}
+	})
 
-	String.prototype.toCamelCase = function (): string {
-		return this.replace(/[-_\s]+(.)?/g, (_, char) =>
-			char ? char.toUpperCase() : '',
-		)
-	}
+	defineExtension(String.prototype, 'toCamelCase', function (this: string): string {
+		return this.replace(/[-_\s]+(.)?/g, (_, char) => (char ? char.toUpperCase() : ''))
+	})
 
-	String.prototype.toKebabCase = function (): string {
+	defineExtension(String.prototype, 'toKebabCase', function (this: string): string {
 		return this.replace(/([a-z])([A-Z])/g, '$1-$2')
 			.replace(/[\s_]+/g, '-')
 			.toLowerCase()
-	}
+	})
 
-	String.prototype.toSnakeCase = function (): string {
+	defineExtension(String.prototype, 'toSnakeCase', function (this: string): string {
 		return this.replace(/([a-z])([A-Z])/g, '$1_$2')
 			.replace(/[\s-]+/g, '_')
 			.toLowerCase()
-	}
+	})
 
-	String.prototype.truncate = function (
-		length: number,
-		suffix = '...',
-	): string {
+	defineExtension(String.prototype, 'truncate', function (this: string, length: number, suffix = '...'): string {
 		if (!Number.isInteger(length) || length < 0) {
-			throw new TypeError(
-				`truncate: length must be a non-negative integer, got ${length}`,
-			)
+			throw new TypeError(`truncate: length must be a non-negative integer, got ${length}`)
 		}
-		return this.length > length
-			? this.substring(0, length) + suffix
-			: this.toString()
-	}
+		return this.length > length ? this.substring(0, length) + suffix : this.toString()
+	})
 
-	String.prototype.isEmail = function (): boolean {
+	defineExtension(String.prototype, 'isEmail', function (this: string): boolean {
 		const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
 		return emailRegex.test(this.toString())
-	}
+	})
 
-	String.prototype.isUrl = function (): boolean {
+	defineExtension(String.prototype, 'isUrl', function (this: string): boolean {
 		try {
 			new URL(this.toString())
 			return true
 		} catch {
 			return false
 		}
-	}
+	})
 
-	String.prototype.removeWhitespace = function (): string {
+	defineExtension(String.prototype, 'removeWhitespace', function (this: string): string {
 		return this.replace(/\s+/g, '')
-	}
+	})
 
-	String.prototype.reverse = function (): string {
+	defineExtension(String.prototype, 'reverse', function (this: string): string {
 		return this.split('').reverse().join('')
-	}
+	})
 
-	String.prototype.isPalindrome = function (): boolean {
+	defineExtension(String.prototype, 'isPalindrome', function (this: string): boolean {
 		const cleaned = this.toLowerCase().replace(/[^a-z0-9]/g, '')
 		return cleaned === cleaned.split('').reverse().join('')
-	}
+	})
 
-	String.prototype.toTitleCase = function (): string {
-		return this.replace(
-			/\w\S*/g,
-			(txt) => txt.charAt(0).toUpperCase() + txt.substr(1).toLowerCase(),
-		)
-	}
+	defineExtension(String.prototype, 'toTitleCase', function (this: string): string {
+		return this.replace(/\w\S*/g, (txt) => txt.charAt(0).toUpperCase() + txt.substr(1).toLowerCase())
+	})
 
-	String.prototype.stripHtml = function (): string {
+	defineExtension(String.prototype, 'stripHtml', function (this: string): string {
 		return this.replace(/<[^>]*>/g, '')
-	}
+	})
 
-	String.prototype.padStart = function (
-		targetLength: number,
-		padString = ' ',
-	): string {
+	defineExtension(String.prototype, 'padStart', function (this: string, targetLength: number, padString = ' '): string {
 		if (!Number.isInteger(targetLength) || targetLength < 0) {
-			throw new TypeError(
-				`padStart: targetLength must be a non-negative integer, got ${targetLength}`,
-			)
+			throw new TypeError(`padStart: targetLength must be a non-negative integer, got ${targetLength}`)
 		}
 		if (typeof padString !== 'string') {
-			throw new TypeError(
-				`padStart: padString must be a string, got ${typeof padString}`,
-			)
+			throw new TypeError(`padStart: padString must be a string, got ${typeof padString}`)
 		}
 		if (padString.length === 0) {
 			throw new TypeError('padStart: padString cannot be empty')
 		}
 		return this.toString().padStart(targetLength, padString)
-	}
+	})
 
-	String.prototype.padEnd = function (
-		targetLength: number,
-		padString = ' ',
-	): string {
+	defineExtension(String.prototype, 'padEnd', function (this: string, targetLength: number, padString = ' '): string {
 		if (!Number.isInteger(targetLength) || targetLength < 0) {
-			throw new TypeError(
-				`padEnd: targetLength must be a non-negative integer, got ${targetLength}`,
-			)
+			throw new TypeError(`padEnd: targetLength must be a non-negative integer, got ${targetLength}`)
 		}
 		if (typeof padString !== 'string') {
-			throw new TypeError(
-				`padEnd: padString must be a string, got ${typeof padString}`,
-			)
+			throw new TypeError(`padEnd: padString must be a string, got ${typeof padString}`)
 		}
 		if (padString.length === 0) {
 			throw new TypeError('padEnd: padString cannot be empty')
 		}
 		return this.toString().padEnd(targetLength, padString)
-	}
+	})
 
-	String.prototype.count = function (substring: string): number {
+	defineExtension(String.prototype, 'count', function (this: string, substring: string): number {
 		if (typeof substring !== 'string') {
-			throw new TypeError(
-				`count: substring must be a string, got ${typeof substring}`,
-			)
+			throw new TypeError(`count: substring must be a string, got ${typeof substring}`)
 		}
 		if (substring === '') {
 			throw new TypeError('count: substring cannot be empty')
 		}
-		return (this.match(new RegExp(substring, 'g')) || []).length
-	}
+		const escaped = substring.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+		return (this.match(new RegExp(escaped, 'g')) || []).length
+	})
 
-	String.prototype.words = function (): string[] {
-		return this.trim()
-			.split(/\s+/)
-			.filter((word) => word.length > 0)
-	}
+	defineExtension(String.prototype, 'words', function (this: string): string[] {
+		return this.trim().split(/\s+/).filter((word) => word.length > 0)
+	})
 
-	String.prototype.lines = function (): string[] {
+	defineExtension(String.prototype, 'lines', function (this: string): string[] {
 		return this.split(/\r?\n/)
-	}
+	})
+
+	defineExtension(String.prototype, 'capitalizeWords', function (this: string): string {
+		return this.toString().replace(/\b\w/g, (char) => char.toUpperCase());
+	});
+
+	defineExtension(String.prototype, 'reverseWords', function (this: string): string {
+		return this.toString().split(/\s+/).reverse().join(' ');
+	});
+
+	defineExtension(String.prototype, 'truncateWords', function (this: string, count: number, suffix = '...'): string {
+		if (!Number.isInteger(count) || count < 0) {
+			throw new TypeError(`truncateWords: count must be a non-negative integer, got ${count}`);
+		}
+		const words = this.toString().split(/\s+/);
+		if (words.length <= count) return this.toString();
+		return words.slice(0, count).join(' ') + suffix;
+	});
+
+	defineExtension(String.prototype, 'slugify', function (this: string): string {
+		return this.toString()
+			.toLowerCase()
+			.replace(/[^\w\s-]/g, '')
+			.trim()
+			.replace(/[\s_-]+/g, '-');
+	});
+
 }

package/packages/js-extensions/src/types/global-augmentations.ts

@@ -28,6 +28,7 @@ declare global {
 		sum(): number
 		average(): number
 		compact(): T[]
+		compactTruthy(): T[]
 		pluck<K extends keyof T>(key: K): T[K][]
 		findLast(predicate: (item: T) => boolean): T | undefined
 		partition(predicate: (item: T) => boolean): [T[], T[]]
@@ -77,4 +78,4 @@ declare global {
 	}
 }
 
-export {}
+export { }

package/packages/js-extensions/src/utils/defineExtension.ts

@@ -0,0 +1,14 @@
+export function defineExtension<T extends object>(
+    prototype: T,
+    name: string,
+    fn: Function,
+) {
+    if (!Object.prototype.hasOwnProperty.call(prototype, name)) {
+        Object.defineProperty(prototype, name, {
+            value: fn,
+            writable: false,
+            configurable: false,
+            enumerable: false,
+        })
+    }
+}

package/packages/js-extensions/src/utils/index.ts

@@ -1,3 +1,4 @@
 // Re-export all utilities
 export * from './config'
 export * from './helpers'
+export * from './defineExtension'

package/packages/response-utils/README.md

@@ -1,24 +1,25 @@
 # @naman_deep_singh/response-utils
 
-**Version:** 2.1.2
+**Version:** 2.1.4
 
-A flexible, framework-agnostic **TypeScript** response utility library for building consistent and configurable API responses.  
-Supports **Express.js**, pagination, typed payloads, and expandable response adapters.
+A flexible, framework-agnostic **TypeScript response utility library** for building consistent, typed, and configurable API responses.
+
+Designed with a clean **core + adapter** architecture.  
+First-class support for **Express.js**, pagination, and standardized HTTP status handling.
 
 ---
 
 ## 🚀 Features
 
-| Feature                                        | Status |
-| ---------------------------------------------- | :----: |
-| Fully Typesafe Response Envelopes              |   ✅   |
-| Framework-Agnostic Core                        |   ✅   |
-| Express.js Adapter + Middleware                |   ✅   |
-| Automatic HTTP Status Handling                 |   ✅   |
-| Pagination Responses                           |   ✅   |
-| Centralized Response Config                    |   ✅   |
-| Status Code Constants                          |   ✅   |
-| Legacy API (`success`, `error`, etc.)          |   ⚠️ Deprecated   |
+| Feature                                      | Status |
+|---------------------------------------------|:------:|
+| Fully typesafe response envelopes            |   ✅   |
+| Framework-agnostic core                      |   ✅   |
+| Express.js responder adapter                 |   ✅   |
+| Express middleware injection                 |   ✅   |
+| Pagination helpers                           |   ✅   |
+| Centralized responder configuration          |   ✅   |
+| HTTP status constants                        |   ✅   |
 
 ---
 
@@ -26,221 +27,178 @@ Supports **Express.js**, pagination, typed payloads, and expandable response ada
 
 ```sh
 npm install @naman_deep_singh/response-utils
-```
-
-## 🧠 Architecture Overview
-
-```
+🧠 Architecture Overview
 response-utils
-├─ core/          → BaseResponder + config + factory (framework-independent)
+├─ core/               → Framework-agnostic responders
+│  ├─ BaseResponder
+│  ├─ config
+│  ├─ factory
+│  └─ types
+│
 ├─ adapters/
-│   └─ express/   → ExpressResponder + middleware
-├─ constants/     → HTTP status constants
-└─ legacy/        → success(), error(), etc. (optional migration layer)
-```
-
-## 📄 Response Format (Default Envelope)
-
-```typescript
+│  └─ express/         → ExpressResponder
+│
+├─ middleware/
+│  └─ express/         → responderMiddleware
+│
+├─ constants/          → HTTP status constants
+
+📄 Response Envelope (Default Shape)
 interface ResponseEnvelope<P = unknown, M = Record<string, unknown>> {
-  success: boolean;
-  message?: string;
-  data?: P;
-  error: { message: string; code?: string; details?: unknown } | null;
-  meta: M | null;
+  success: boolean
+  message?: string
+  data?: P
+  error: {
+    message: string
+    code?: string
+    details?: unknown
+  } | null
+  meta: M | null
 }
-```
-
-## 🛠️ Usage Examples
+🛠️ Usage
+✔ Framework-Agnostic (No Express)
+import { BaseResponder } from '@naman_deep_singh/response-utils'
 
-### ✔ Framework-Agnostic (no Express)
-```typescript
-import { BaseResponder } from '@naman_deep_singh/response-utils';
+const responder = new BaseResponder()
 
-const r = new BaseResponder();
-const result = r.ok({ user: "John" }, "Loaded");
-console.log(result);
-```
+const result = responder.ok({ user: 'John' }, 'Loaded')
 
-### 🌐 Express Integration
+// When no sender is attached, returns:
+// { status: 200, body: ResponseEnvelope }
+console.log(result)
+🌐 Express Integration
+1️⃣ Register Middleware
+import express from 'express'
+import { responderMiddleware } from '@naman_deep_singh/response-utils'
 
-#### 1️⃣ Add Middleware
+const app = express()
 
-```typescript
-import express from 'express';
-import { responderMiddleware } from '@naman_deep_singh/response-utils';
+app.use(responderMiddleware())
+This injects a res.responder() factory into every request.
 
-const app = express();
-app.use(responderMiddleware());
-```
-
-#### 2️⃣ Controller Usage
-
-```typescript
+2️⃣ Controller Usage
 app.get('/user', (req, res) => {
-  const responder = (res as any).responder();
-  return responder.okAndSend({ id: 1, name: "John Doe" }, "User found");
-});
-```
+  const responder = res.responder<{ id: number; name: string }>()
+
+  responder.okAndSend(
+    { id: 1, name: 'John Doe' },
+    'User found'
+  )
+})
+✅ okAndSend() automatically:
 
-`okAndSend()` automatically applies HTTP status + JSON response.
+sets HTTP status
 
-#### ⚙️ Config Options
+sends JSON response
 
-```typescript
-app.use(responderMiddleware({
-  timestamp: true,
-  extra: { service: "user-service" }
-}));
-```
+returns void for clean controller ergonomics
 
-Example output:
+⚙️ Middleware Configuration
+app.use(
+  responderMiddleware({
+    timestamp: true,
+    extra: { service: 'user-service' },
+  })
+)
+Example response:
 
-```json
 {
   "success": true,
   "data": { ... },
   "error": null,
   "meta": {
-    "timestamp": "2025-11-22T12:00:00Z",
-    "service": "user-service"
-  }
+    "timestamp": "2025-11-22T12:00:00Z"
+  },
+  "service": "user-service"
 }
-```
-
-### 🔢 Pagination Support
-
-```typescript
+🔢 Pagination Support
 responder.paginateAndSend(
   [{ id: 1 }],
-  1, // page
-  10, // limit
-  42, // total
-  "Loaded"
-);
-```
-
-## 📚 Supported Methods
-
-### Success Methods
-| Method | Status |
-|--------|--------|
-| `ok()` | 200 |
-| `created()` | 201 |
-| `noContent()` | 204 |
-| `paginated()` | 200 |
-
-### Error Methods
-| Method | Status |
-|--------|--------|
-| `badRequest()` | 400 |
-| `unauthorized()` | 401 |
-| `forbidden()` | 403 |
-| `notFound()` | 404 |
-| `conflict()` | 409 |
-| `unprocessableEntity()` | 422 |
-| `tooManyRequests()` | 429 |
-| `serverError()` | 500 |
-
-**Each has an Express `*AndSend()` variant**  
-Example → `notFoundAndSend()`, `createdAndSend()`
-
-### 🧩 Status Constants
-
-```typescript
-import { HTTP_STATUS } from '@naman_deep_singh/response-utils';
-
-console.log(HTTP_STATUS.CLIENT_ERROR.NOT_FOUND); // 404
-console.log(HTTP_STATUS.SUCCESS.CREATED); // 201
-```
-
-**Categories:**
-- `SUCCESS`
-- `REDIRECTION`
-- `CLIENT_ERROR`
-- `SERVER_ERROR`
-
-**All fully readonly + literal typed** ✔
-
-
-### 🧩 Status Constants
-
-```typescript
-import { HTTP_STATUS } from '@naman_deep_singh/response-utils';
-
-console.log(HTTP_STATUS.CLIENT_ERROR.NOT_FOUND); // 404
-console.log(HTTP_STATUS.SUCCESS.CREATED); // 201
-```
-
-**Categories available:**
-
-- `SUCCESS`
-- `REDIRECTION`
-- `CLIENT_ERROR`
-- `SERVER_ERROR`
-
-All values are:
-
-✔ Object.freeze() protected  
-✔ Strongly typed using as const  
-✔ Auto-complete supported in IDEs  
-✔ Works with any HTTP framework
-
-### 🕘 Legacy API (Migration-friendly)
-
-```typescript
-import { success, error } from '@naman_deep_singh/response-utils/legacy';
-
-// Success response
-const result = success({ id: 1, name: 'John' }, 'User found', 200);
-// Returns: { success: true, message: 'User found', data: {...}, statusCode: 200 }
-
-// Error response  
-const errorResult = error('User not found', 404, 'NOT_FOUND');
-// Returns: { success: false, message: 'User not found', error: 'NOT_FOUND', statusCode: 404 }
-
-// With Express response object
-success({ users: [] }, 'Success', 200, res); // Automatically sends response
-error('Server error', 500, undefined, res); // Automatically sends error
-```
-
-**Legacy Functions:**
-- `success(data, message?, status?, res?)` - Create success response
-- `error(message, status?, error?, res?)` - Create error response
-
-⚠ **Recommended only for old codebases.** Use BaseResponder/ExpressResponder for new projects.
-
-## 🔜 Roadmap
-
-| Feature | Status |
-|---------|--------|
-| Fastify Adapter | Planned |
-| Hono Adapter | Planned |
-| Custom Error Classes | Planned |
-
-## Integration with Other Packages
-
-### With @naman_deep_singh/server-utils
+  1,    // page
+  10,   // limit
+  42,   // total
+  'Loaded'
+)
+Pagination metadata is automatically calculated.
+
+📚 Available Methods
+✅ Success Responses
+Method	HTTP
+ok()	200
+created()	201
+noContent()	204
+paginate()	200
+Each method has an Express variant:
+
+okAndSend()
+
+createdAndSend()
+
+paginateAndSend()
+
+❌ Error Responses
+Method	HTTP
+badRequest()	400
+unauthorized()	401
+forbidden()	403
+notFound()	404
+conflict()	409
+unprocessableEntity()	422
+tooManyRequests()	429
+serverError()	500
+Each also has a *AndSend() variant.
+
+🧩 HTTP Status Constants
+import { HTTP_STATUS } from '@naman_deep_singh/response-utils'
+
+HTTP_STATUS.SUCCESS.OK              // 200
+HTTP_STATUS.CLIENT_ERROR.NOT_FOUND  // 404
+HTTP_STATUS.SERVER_ERROR.INTERNAL_SERVER_ERROR // 500
+Categories
+SUCCESS
+
+REDIRECTION
+
+CLIENT_ERROR
+
+SERVER_ERROR
+
+✔ Object.freeze() protected
+✔ Fully literal-typed (as const)
+✔ IDE autocomplete friendly
+
+🧩 TypeScript: Express Response Augmentation (Recommended)
+For full type safety, add this once in your project:
+
+import type { ExpressResponder } from '@naman_deep_singh/response-utils'
+
+declare global {
+  namespace Express {
+    interface Response {
+      responder: <P = unknown>() => ExpressResponder<P>
+    }
+  }
+}
 
-```typescript
-import { createServer } from '@naman_deep_singh/server-utils';
-import { responderMiddleware } from '@naman_deep_singh/response-utils';
+⚠️ Do not use for new projects.
 
-const server = createServer('My API', '1.0.0');
-server.app.use(responderMiddleware());
+🔗 Integration with Other Packages
+With @naman_deep_singh/server-utils
+import { responderMiddleware } from '@naman_deep_singh/response-utils'
 
-// All server-utils middleware now uses consistent response format
-```
+server.app.use(responderMiddleware())
+With @naman_deep_singh/errors-utils
+import { expressErrorHandler } from '@naman_deep_singh/errors-utils'
 
-### With @naman_deep_singh/errors-utils
+server.app.use(expressErrorHandler)
+Provides consistent error responses across services.
 
-```typescript
-import { expressErrorHandler } from '@naman_deep_singh/errors-utils';
+🔜 Roadmap
+Fastify adapter
 
-// Advanced error handling with consistent responses
-server.app.use(expressErrorHandler);
-```
+Hono adapter
 
-## 📄 License
+Configurable envelope key mapping
 
+📄 License
 MIT © Naman Deep Singh