ts-packages 1.0.0 → 2.0.0

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

@@ -0,0 +1,162 @@
+// Number prototype extensions
+import { withCache } from '../core/performance'
+
+export function extendNumber() {
+	Number.prototype.toPercent = function (decimals = 2): string {
+		return `${(this.valueOf() * 100).toFixed(decimals)}%`
+	}
+
+	Number.prototype.toCurrency = function (
+		currency = 'USD',
+		locale = 'en-US',
+	): string {
+		return new Intl.NumberFormat(locale, {
+			style: 'currency',
+			currency,
+		}).format(this.valueOf())
+	}
+
+	Number.prototype.clamp = function (min: number, max: number): number {
+		if (min > max) {
+			throw new RangeError(
+				`clamp: min (${min}) cannot be greater than max (${max})`,
+			)
+		}
+		return Math.min(Math.max(this.valueOf(), min), max)
+	}
+
+	Number.prototype.isEven = function (): boolean {
+		return this.valueOf() % 2 === 0
+	}
+
+	Number.prototype.isOdd = function (): boolean {
+		return this.valueOf() % 2 !== 0
+	}
+
+	Number.prototype.isPrime = function (): boolean {
+		const num = this.valueOf()
+		return withCache(`prime_${num}`, () => {
+			if (num < 2) return false
+			for (let i = 2; i <= Math.sqrt(num); i++) {
+				if (num % i === 0) return false
+			}
+			return true
+		})
+	}
+
+	Number.prototype.factorial = function (): number {
+		const num = Math.floor(this.valueOf())
+		return withCache(`factorial_${num}`, () => {
+			if (num < 0) return Number.NaN
+			if (num === 0 || num === 1) return 1
+			let result = 1
+			for (let i = 2; i <= num; i++) {
+				result *= i
+			}
+			return result
+		})
+	}
+
+	Number.prototype.toOrdinal = function (): string {
+		const num = Math.floor(this.valueOf())
+		const suffix = ['th', 'st', 'nd', 'rd']
+		const v = num % 100
+		return num + (suffix[(v - 20) % 10] || suffix[v] || suffix[0])
+	}
+
+	Number.prototype.toRoman = function (): string {
+		const num = Math.floor(this.valueOf())
+
+		// Better validation for roman numerals
+		if (num <= 0) {
+			throw new RangeError('toRoman: number must be positive')
+		}
+		if (num >= 4000) {
+			throw new RangeError('toRoman: number must be less than 4000')
+		}
+
+		return withCache(`roman_${num}`, () => {
+			const values = [1000, 900, 500, 400, 100, 90, 50, 40, 10, 9, 5, 4, 1]
+			const symbols = [
+				'M',
+				'CM',
+				'D',
+				'CD',
+				'C',
+				'XC',
+				'L',
+				'XL',
+				'X',
+				'IX',
+				'V',
+				'IV',
+				'I',
+			]
+			let result = ''
+			let n = num
+			for (let i = 0; i < values.length; i++) {
+				while (n >= values[i]) {
+					result += symbols[i]
+					n -= values[i]
+				}
+			}
+			return result
+		})
+	}
+
+	Number.prototype.inRange = function (min: number, max: number): boolean {
+		const num = this.valueOf()
+		return num >= min && num <= max
+	}
+
+	Number.prototype.round = function (decimals = 0): number {
+		if (!Number.isInteger(decimals) || decimals < 0) {
+			throw new TypeError(
+				`round: decimals must be a non-negative integer, got ${decimals}`,
+			)
+		}
+		const factor = Math.pow(10, decimals)
+		return Math.round(this.valueOf() * factor) / factor
+	}
+
+	Number.prototype.ceil = function (decimals = 0): number {
+		if (!Number.isInteger(decimals) || decimals < 0) {
+			throw new TypeError(
+				`ceil: decimals must be a non-negative integer, got ${decimals}`,
+			)
+		}
+		const factor = Math.pow(10, decimals)
+		return Math.ceil(this.valueOf() * factor) / factor
+	}
+
+	Number.prototype.floor = function (decimals = 0): number {
+		if (!Number.isInteger(decimals) || decimals < 0) {
+			throw new TypeError(
+				`floor: decimals must be a non-negative integer, got ${decimals}`,
+			)
+		}
+		const factor = Math.pow(10, decimals)
+		return Math.floor(this.valueOf() * factor) / factor
+	}
+
+	Number.prototype.abs = function (): number {
+		return Math.abs(this.valueOf())
+	}
+
+	Number.prototype.sign = function (): number {
+		return Math.sign(this.valueOf())
+	}
+
+	Number.prototype.times = function (callback: (index: number) => void): void {
+		if (typeof callback !== 'function') {
+			throw new TypeError(
+				`times: callback must be a function, got ${typeof callback}`,
+			)
+		}
+
+		const num = Math.floor(this.valueOf())
+		for (let i = 0; i < num; i++) {
+			callback(i)
+		}
+	}
+}

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

@@ -0,0 +1 @@
+export { extendObject } from './object-extensions'

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

@@ -0,0 +1,171 @@
+// Object prototype extensions
+
+export function extendObject() {
+	Object.prototype.isEmpty = function (): boolean {
+		return Object.keys(this).length === 0
+	}
+
+	Object.prototype.pick = function <
+		T extends Record<string, any>,
+		K extends keyof T,
+	>(keys: K[]): Pick<T, K> {
+		if (this === null || this === undefined) {
+			throw new TypeError('pick: cannot be called on null or undefined')
+		}
+		if (!Array.isArray(keys)) {
+			throw new TypeError(`pick: keys must be an array, got ${typeof keys}`)
+		}
+		if (keys.length === 0) {
+			throw new TypeError('pick: keys array cannot be empty')
+		}
+
+		const result = {} as Pick<T, K>
+		const obj = this as T
+		keys.forEach((key) => {
+			if (key in obj) {
+				result[key] = obj[key]
+			}
+		})
+		return result
+	}
+
+	Object.prototype.omit = function <
+		T extends Record<string, any>,
+		K extends keyof T,
+	>(keys: K[]): Omit<T, K> {
+		if (this === null || this === undefined) {
+			throw new TypeError('omit: cannot be called on null or undefined')
+		}
+		if (!Array.isArray(keys)) {
+			throw new TypeError(`omit: keys must be an array, got ${typeof keys}`)
+		}
+		if (keys.length === 0) {
+			throw new TypeError('omit: keys array cannot be empty')
+		}
+
+		const result = { ...this } as T
+		keys.forEach((key) => {
+			delete result[key]
+		})
+		return result as Omit<T, K>
+	}
+
+	Object.prototype.deepClone = function <T>(): T {
+		// Simple cycle detection without caching key generation
+		if (this === null || typeof this !== 'object') return this
+
+		// Handle Date objects
+		if (this instanceof Date) return new Date(this.getTime()) as unknown as T
+
+		// Handle Array objects
+		if (Array.isArray(this)) {
+			return this.map((item) => {
+				if (
+					item &&
+					typeof item === 'object' &&
+					typeof (item as any).deepClone === 'function'
+				) {
+					return (item as any).deepClone()
+				}
+				return item
+			}) as unknown as T
+		}
+
+		// Handle regular objects with better cycle detection
+		const visited = new WeakSet()
+
+		function deepCloneSafe(obj: any): any {
+			if (obj === null || typeof obj !== 'object') return obj
+
+			if (visited.has(obj)) {
+				throw new Error('Circular reference detected in deepClone')
+			}
+
+			visited.add(obj)
+
+			if (obj instanceof Date) return new Date(obj.getTime())
+			if (Array.isArray(obj)) return obj.map((item) => deepCloneSafe(item))
+
+			const cloned = {} as Record<string, unknown>
+			Object.keys(obj).forEach((key) => {
+				cloned[key] = deepCloneSafe(obj[key])
+			})
+
+			return cloned
+		}
+
+		return deepCloneSafe(this) as T
+	}
+
+	Object.prototype.merge = function <T extends Record<string, unknown>>(
+		other: Partial<T>,
+	): T {
+		return { ...this, ...other } as T
+	}
+
+	Object.prototype.deepFreeze = function <T>(): T {
+		const propNames = Object.getOwnPropertyNames(this)
+		for (const name of propNames) {
+			const value = (this as any)[name]
+			if (value && typeof value === 'object') {
+				value.deepFreeze()
+			}
+		}
+		return Object.freeze(this) as T
+	}
+
+	Object.prototype.hasPath = function (path: string): boolean {
+		if (typeof path !== 'string') {
+			throw new TypeError(`hasPath: path must be a string, got ${typeof path}`)
+		}
+		if (path.trim() === '') {
+			throw new TypeError('hasPath: path cannot be empty or whitespace')
+		}
+
+		const keys = path.split('.')
+		let current: any = this
+		for (const key of keys) {
+			if (current == null || !(key in current)) return false
+			current = current[key]
+		}
+		return true
+	}
+
+	Object.prototype.getPath = function (path: string, defaultValue?: any): any {
+		if (typeof path !== 'string') {
+			throw new TypeError(`getPath: path must be a string, got ${typeof path}`)
+		}
+		if (path.trim() === '') {
+			throw new TypeError('getPath: path cannot be empty or whitespace')
+		}
+
+		const keys = path.split('.')
+		let current: any = this
+		for (const key of keys) {
+			if (current == null || !(key in current)) return defaultValue
+			current = current[key]
+		}
+		return current
+	}
+
+	Object.prototype.setPath = function (path: string, value: any): any {
+		if (typeof path !== 'string') {
+			throw new TypeError(`setPath: path must be a string, got ${typeof path}`)
+		}
+		if (path.trim() === '') {
+			throw new TypeError('setPath: path cannot be empty or whitespace')
+		}
+
+		const keys = path.split('.')
+		let current: any = this
+		for (let i = 0; i < keys.length - 1; i++) {
+			const key = keys[i]
+			if (!(key in current) || typeof current[key] !== 'object') {
+				current[key] = {}
+			}
+			current = current[key]
+		}
+		current[keys[keys.length - 1]] = value
+		return this
+	}
+}

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

@@ -0,0 +1 @@
+export { extendString } from './string-extensions'

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

@@ -0,0 +1,138 @@
+// String prototype extensions
+export function extendString() {
+	String.prototype.toCapitalize = function (): string {
+		return this.charAt(0).toUpperCase() + this.slice(1).toLowerCase()
+	}
+
+	String.prototype.toCamelCase = function (): string {
+		return this.replace(/[-_\s]+(.)?/g, (_, char) =>
+			char ? char.toUpperCase() : '',
+		)
+	}
+
+	String.prototype.toKebabCase = function (): string {
+		return this.replace(/([a-z])([A-Z])/g, '$1-$2')
+			.replace(/[\s_]+/g, '-')
+			.toLowerCase()
+	}
+
+	String.prototype.toSnakeCase = function (): string {
+		return this.replace(/([a-z])([A-Z])/g, '$1_$2')
+			.replace(/[\s-]+/g, '_')
+			.toLowerCase()
+	}
+
+	String.prototype.truncate = function (
+		length: number,
+		suffix = '...',
+	): string {
+		if (!Number.isInteger(length) || length < 0) {
+			throw new TypeError(
+				`truncate: length must be a non-negative integer, got ${length}`,
+			)
+		}
+		return this.length > length
+			? this.substring(0, length) + suffix
+			: this.toString()
+	}
+
+	String.prototype.isEmail = function (): boolean {
+		const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+		return emailRegex.test(this.toString())
+	}
+
+	String.prototype.isUrl = function (): boolean {
+		try {
+			new URL(this.toString())
+			return true
+		} catch {
+			return false
+		}
+	}
+
+	String.prototype.removeWhitespace = function (): string {
+		return this.replace(/\s+/g, '')
+	}
+
+	String.prototype.reverse = function (): string {
+		return this.split('').reverse().join('')
+	}
+
+	String.prototype.isPalindrome = function (): 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(),
+		)
+	}
+
+	String.prototype.stripHtml = function (): string {
+		return this.replace(/<[^>]*>/g, '')
+	}
+
+	String.prototype.padStart = function (
+		targetLength: number,
+		padString = ' ',
+	): string {
+		if (!Number.isInteger(targetLength) || targetLength < 0) {
+			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}`,
+			)
+		}
+		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 {
+		if (!Number.isInteger(targetLength) || targetLength < 0) {
+			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}`,
+			)
+		}
+		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 {
+		if (typeof substring !== 'string') {
+			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
+	}
+
+	String.prototype.words = function (): string[] {
+		return this.trim()
+			.split(/\s+/)
+			.filter((word) => word.length > 0)
+	}
+
+	String.prototype.lines = function (): string[] {
+		return this.split(/\r?\n/)
+	}
+}

package/packages/js-extensions/src/types/extension-types.ts

@@ -0,0 +1,12 @@
+// Types for extension options and configurations
+import { PerformanceConfig } from '../core/performance'
+
+export interface ExtensionOptions {
+	string?: boolean
+	array?: boolean
+	object?: boolean
+	number?: boolean
+	performance?: PerformanceConfig
+}
+
+export { PerformanceConfig }

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

@@ -0,0 +1,80 @@
+// TypeScript declarations for all extensions
+declare global {
+	interface String {
+		toCapitalize(): string
+		toCamelCase(): string
+		toKebabCase(): string
+		toSnakeCase(): string
+		truncate(length: number, suffix?: string): string
+		isEmail(): boolean
+		isUrl(): boolean
+		removeWhitespace(): string
+		reverse(): string
+		isPalindrome(): boolean
+		toTitleCase(): string
+		stripHtml(): string
+		padStart(targetLength: number, padString?: string): string
+		padEnd(targetLength: number, padString?: string): string
+		count(substring: string): number
+		words(): string[]
+		lines(): string[]
+	}
+
+	interface Array<T> {
+		unique(): T[]
+		shuffle(): T[]
+		chunk(size: number): T[][]
+		groupBy<K extends string | number>(keyFn: (item: T) => K): Record<K, T[]>
+		sum(): number
+		average(): number
+		compact(): T[]
+		pluck<K extends keyof T>(key: K): T[K][]
+		findLast(predicate: (item: T) => boolean): T | undefined
+		partition(predicate: (item: T) => boolean): [T[], T[]]
+		flatten(depth?: number): any[]
+		deepFlatten(): any[]
+		difference(other: T[]): T[]
+		intersection(other: T[]): T[]
+		union(other: T[]): T[]
+		sample(): T | undefined
+		take(count: number): T[]
+		drop(count: number): T[]
+	}
+
+	interface Object {
+		isEmpty(): boolean
+		pick<T extends Record<string, any>, K extends keyof T>(
+			keys: K[],
+		): Pick<T, K>
+		omit<T extends Record<string, any>, K extends keyof T>(
+			keys: K[],
+		): Omit<T, K>
+		deepClone<T>(): T
+		merge(other: Record<string, any>): Record<string, any>
+		deepFreeze<T>(): T
+		hasPath(path: string): boolean
+		getPath(path: string, defaultValue?: any): any
+		setPath(path: string, value: any): any
+	}
+
+	interface Number {
+		toPercent(decimals?: number): string
+		toCurrency(currency?: string, locale?: string): string
+		clamp(min: number, max: number): number
+		isEven(): boolean
+		isOdd(): boolean
+		isPrime(): boolean
+		factorial(): number
+		toOrdinal(): string
+		toRoman(): string
+		inRange(min: number, max: number): boolean
+		round(decimals?: number): number
+		ceil(decimals?: number): number
+		floor(decimals?: number): number
+		abs(): number
+		sign(): number
+		times(callback: (index: number) => void): void
+	}
+}
+
+export {}

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

@@ -0,0 +1,3 @@
+// Re-export all types
+export * from './extension-types'
+export * from './global-augmentations'

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

@@ -0,0 +1,33 @@
+// Configuration validation utilities (import PerformanceConfig from core/performance)
+import type { PerformanceConfig } from '../core/performance'
+
+export function validateConfig(
+	config: Partial<PerformanceConfig>,
+	defaultConfig: PerformanceConfig,
+): PerformanceConfig {
+	return { ...defaultConfig, ...config }
+}
+
+export function validatePerformanceSettings(
+	settings: Partial<PerformanceConfig>,
+): PerformanceConfig {
+	const validated: PerformanceConfig = {
+		enableCaching: settings.enableCaching ?? false,
+		maxCacheSize: Math.max(1, settings.maxCacheSize ?? 100),
+		enableValidation: settings.enableValidation ?? true,
+	}
+	return validated
+}
+
+export function mergeConfigs<T extends Record<string, any>>(
+	base: T,
+	override: Partial<T>,
+): T {
+	const result = { ...base }
+	for (const key in override) {
+		if (override[key] !== undefined) {
+			result[key] = override[key]
+		}
+	}
+	return result
+}

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

@@ -0,0 +1,35 @@
+// Shared helper functions for extensions
+
+export function isValidArrayIndex(index: number): boolean {
+	return Number.isInteger(index) && index >= 0
+}
+
+export function ensurePositiveInteger(value: number, name: string): void {
+	if (!Number.isInteger(value) || value < 0) {
+		throw new TypeError(`${name} must be a positive integer`)
+	}
+}
+
+export function safeClone<T>(obj: T): T {
+	if (obj === null || typeof obj !== 'object') return obj
+
+	if (obj instanceof Date) return new Date(obj.getTime()) as unknown as T
+	if (Array.isArray(obj))
+		return obj.map((item) => safeClone(item)) as unknown as T
+
+	const cloned = {} as Record<string, unknown>
+	for (const key in obj) {
+		if (obj.hasOwnProperty(key)) {
+			cloned[key] = safeClone((obj as Record<string, unknown>)[key])
+		}
+	}
+	return cloned as T
+}
+
+export function getPathSegments(path: string): string[] {
+	return path.split('.').filter((segment) => segment.length > 0)
+}
+
+export function hasOwnProperty(obj: any, key: string): boolean {
+	return Object.prototype.hasOwnProperty.call(obj, key)
+}

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

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

package/packages/js-extensions/tsconfig.base.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "moduleResolution": "node",
+    "strict": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "baseUrl": ".",
+    "paths": {
+      "*": ["*", "*.ts", "*.js"]
+    },
+    "lib": ["ES2020", "DOM"]
+  },
+  "include": ["src/**/*"]
+}

package/packages/js-extensions/tsconfig.cjs.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "module": "CommonJS",
+    "moduleResolution": "Node",
+    "rootDir": "./src",
+    "outDir": "./dist/cjs"
+  }
+}

package/packages/js-extensions/tsconfig.esm.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "rootDir": "./src",
+    "outDir": "./dist/esm"
+  }
+}