ts-packages 1.0.0 → 3.0.0

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

@@ -0,0 +1,292 @@
+import { defineExtension } from "src/utils"
+
+let arrayExtended = false
+
+export function extendArray() {
+	if (arrayExtended) return
+	arrayExtended = true
+
+	defineExtension(
+		Array.prototype,
+		'unique',
+		function <T>(this: readonly T[]): T[] {
+			return [...new Set(this)]
+		},
+	)
+
+	defineExtension(
+		Array.prototype,
+		'shuffle',
+		function <T>(this: readonly T[]): T[] {
+			const arr = [...this]
+			for (let i = arr.length - 1; i > 0; i--) {
+				const j = Math.floor(Math.random() * (i + 1))
+					;[arr[i], arr[j]] = [arr[j], arr[i]]
+			}
+			return arr
+		},
+	)
+
+	defineExtension(
+		Array.prototype,
+		'chunk',
+		function <T>(this: readonly T[], size: number): T[][] {
+			if (!Number.isInteger(size) || size <= 0) {
+				throw new TypeError(`chunk: size must be a positive integer, got ${size}`)
+			}
+			const chunks: T[][] = []
+			for (let i = 0; i < this.length; i += size) {
+				chunks.push(this.slice(i, i + size))
+			}
+			return chunks
+		},
+	)
+
+	defineExtension(
+		Array.prototype,
+		'groupBy',
+		function <T>(
+			this: readonly T[],
+			keyFn: (item: T) => string | number,
+		): Record<string | number, T[]> {
+			if (typeof keyFn !== 'function') {
+				throw new TypeError(
+					`groupBy: keyFn must be a function, got ${typeof keyFn}`,
+				)
+			}
+
+			return this.reduce(
+				(groups, item) => {
+					const key = keyFn(item)
+					if (!groups[key]) groups[key] = []
+					groups[key].push(item)
+					return groups
+				},
+				{} as Record<string | number, T[]>,
+			)
+		},
+	)
+
+	defineExtension(
+		Array.prototype,
+		'sum',
+		function (this: readonly number[]): number {
+			if (this.length === 0) {
+				throw new TypeError('sum: array must contain at least one number')
+			}
+			return this.reduce((sum, num) => sum + num, 0)
+		},
+	)
+
+	defineExtension(
+		Array.prototype,
+		'average',
+		function (this: readonly number[]): number {
+			if (this.length === 0) {
+				throw new TypeError('average: array must contain at least one number')
+			}
+			return this.reduce((sum, num) => sum + num, 0) / this.length
+		},
+	)
+
+	defineExtension(
+		Array.prototype,
+		'compact',
+		function <T>(this: readonly T[]): T[] {
+			return this.filter(
+				(item) => item !== null && item !== undefined && item !== '',
+			)
+		},
+	)
+
+	defineExtension(
+		Array.prototype,
+		'compactTruthy',
+		function <T>(this: readonly T[]): T[] {
+			return this.filter(Boolean)
+		},
+	)
+
+	defineExtension(
+		Array.prototype,
+		'pluck',
+		function <T extends Record<PropertyKey, any>, K extends keyof T>(
+			this: readonly T[],
+			key: K,
+		): T[K][] {
+			return this
+				.map((item) => item[key])
+				.filter((val): val is T[K] => val !== undefined)
+		},
+	)
+
+
+	defineExtension(
+		Array.prototype,
+		'findLast',
+		function <T>(
+			this: readonly T[],
+			predicate: (item: T) => boolean,
+		): T | undefined {
+			if (typeof predicate !== 'function') {
+				throw new TypeError(
+					`findLast: predicate must be a function, got ${typeof predicate}`,
+				)
+			}
+
+			for (let i = this.length - 1; i >= 0; i--) {
+				if (predicate(this[i])) return this[i]
+			}
+			return undefined
+		},
+	)
+
+	defineExtension(
+		Array.prototype,
+		'partition',
+		function <T>(
+			this: readonly T[],
+			predicate: (item: T) => boolean,
+		): [T[], T[]] {
+			if (typeof predicate !== 'function') {
+				throw new TypeError(
+					`partition: predicate must be a function, got ${typeof predicate}`,
+				)
+			}
+
+			const truthy: T[] = []
+			const falsy: T[] = []
+
+			this.forEach((item) =>
+				predicate(item) ? truthy.push(item) : falsy.push(item),
+			)
+
+			return [truthy, falsy]
+		},
+	)
+
+	defineExtension(
+		Array.prototype,
+		'flatten',
+		function (this: readonly any[], depth = 1): any[] {
+			return depth > 0
+				? this.reduce(
+					(acc: any[], val) =>
+						acc.concat(
+							Array.isArray(val) ? val.flatten(depth - 1) : val,
+						),
+					[],
+				)
+				: this.slice()
+		},
+	)
+
+	defineExtension(
+		Array.prototype,
+		'deepFlatten',
+		function (this: readonly any[]): any[] {
+			return this.reduce(
+				(acc: any[], val) =>
+					acc.concat(Array.isArray(val) ? val.deepFlatten() : val),
+				[],
+			)
+		},
+	)
+
+	defineExtension(
+		Array.prototype,
+		'difference',
+		function <T>(this: readonly T[], other: T[]): T[] {
+			if (!Array.isArray(other)) {
+				throw new TypeError(
+					`difference: other must be an array, got ${typeof other}`,
+				)
+			}
+			return this.filter((item) => !other.includes(item))
+		},
+	)
+
+	defineExtension(
+		Array.prototype,
+		'intersection',
+		function <T>(this: readonly T[], other: T[]): T[] {
+			if (!Array.isArray(other)) {
+				throw new TypeError(
+					`intersection: other must be an array, got ${typeof other}`,
+				)
+			}
+			return this.filter((item) => other.includes(item))
+		},
+	)
+
+	defineExtension(
+		Array.prototype,
+		'union',
+		function <T>(this: readonly T[], other: T[]): T[] {
+			if (!Array.isArray(other)) {
+				throw new TypeError(`union: other must be an array, got ${typeof other}`)
+			}
+			return [...new Set([...this, ...other])]
+		},
+	)
+
+	defineExtension(
+		Array.prototype,
+		'sample',
+		function <T>(this: readonly T[]): T | undefined {
+			return this.length > 0
+				? this[Math.floor(Math.random() * this.length)]
+				: undefined
+		},
+	)
+
+	defineExtension(
+		Array.prototype,
+		'take',
+		function <T>(this: readonly T[], count: number): T[] {
+			return this.slice(0, Math.max(0, count))
+		},
+	)
+
+	defineExtension(
+		Array.prototype,
+		'drop',
+		function <T>(this: readonly T[], count: number): T[] {
+			return this.slice(Math.max(0, count))
+		},
+	)
+
+	defineExtension(Array.prototype, 'uniqueBy', function <T, K>(this: readonly T[], keyFn: (item: T) => K): T[] {
+		if (typeof keyFn !== 'function') {
+			throw new TypeError(`uniqueBy: keyFn must be a function, got ${typeof keyFn}`);
+		}
+		const seen = new Set<K>();
+		const result: T[] = [];
+		for (const item of this) {
+			const key = keyFn(item);
+			if (!seen.has(key)) {
+				seen.add(key);
+				result.push(item);
+			}
+		}
+		return result;
+	});
+
+	defineExtension(Array.prototype, 'sortBy', function <T>(this: readonly T[], keyFn: (item: T) => any): T[] {
+		if (typeof keyFn !== 'function') {
+			throw new TypeError(`sortBy: keyFn must be a function, got ${typeof keyFn}`);
+		}
+		return [...this].sort((a, b) => {
+			const aVal = keyFn(a);
+			const bVal = keyFn(b);
+			if (aVal < bVal) return -1;
+			if (aVal > bVal) return 1;
+			return 0;
+		});
+	});
+
+	defineExtension(Array.prototype, 'last', function <T>(this: readonly T[]): T | undefined {
+		return this.length > 0 ? this[this.length - 1] : undefined;
+	});
+
+}

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

@@ -0,0 +1 @@
+export { extendArray } from './array-extensions'

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

@@ -0,0 +1,3 @@
+// Re-export core utilities
+export * from './validation'
+export * from './performance'

package/packages/js-extensions/src/core/performance.ts

@@ -0,0 +1,103 @@
+import { getPackageVersion } from "./version"
+
+// Performance optimization utilities
+export interface PerformanceConfig {
+	enableCaching?: boolean
+	maxCacheSize?: number
+	enableValidation?: boolean
+}
+
+const defaultConfig: PerformanceConfig = {
+	enableCaching: false,
+	maxCacheSize: 100,
+	enableValidation: true,
+}
+
+let config: PerformanceConfig = { ...defaultConfig }
+
+export function setPerformanceConfig(
+	newConfig: Partial<PerformanceConfig>,
+): void {
+	const oldMaxSize = config.maxCacheSize
+	config = { ...config, ...newConfig }
+
+	// Recreate cache if maxCacheSize changed
+	if (cache && oldMaxSize !== config.maxCacheSize) {
+		cache = new LRUCache(config.maxCacheSize)
+	}
+}
+
+export function getPerformanceConfig(): PerformanceConfig {
+	return { ...config }
+}
+
+// Simple LRU cache for expensive operations
+export class LRUCache<K, V> {
+	private cache = new Map<K, V>()
+	private maxSize: number
+
+	constructor(maxSize = 100) {
+		this.maxSize = maxSize
+	}
+
+	get(key: K): V | undefined {
+		const value = this.cache.get(key)
+		if (value !== undefined) {
+			// Move to end (most recently used)
+			this.cache.delete(key)
+			this.cache.set(key, value)
+		}
+		return value
+	}
+
+	set(key: K, value: V): void {
+		if (this.cache.has(key)) {
+			this.cache.delete(key)
+		} else if (this.cache.size >= this.maxSize) {
+			// Remove least recently used (first item)
+			const firstKey = this.cache.keys().next().value
+			if (firstKey !== undefined) {
+				this.cache.delete(firstKey)
+			}
+		}
+		this.cache.set(key, value)
+	}
+
+	clear(): void {
+		this.cache.clear()
+	}
+}
+
+let cache: LRUCache<string, any> | null = null
+
+function getOrCreateCache(): LRUCache<string, any> {
+	if (!cache) {
+		cache = new LRUCache(config.maxCacheSize)
+	}
+	return cache
+}
+
+
+export function makeInternalCacheKey(
+	domain: string,
+	key: string | number,
+): string {
+	const INTERNAL_CACHE_PREFIX = '@js-ext' + getPackageVersion();
+	return `${INTERNAL_CACHE_PREFIX}:${domain}:${key}`;
+}
+
+export function withCache<T>(key: string, fn: () => T): T {
+	if (!config.enableCaching) {
+		return fn()
+	}
+
+	const currentCache = getOrCreateCache()
+	const cached = currentCache.get(key)
+	if (cached !== undefined) {
+		return cached as T
+	}
+
+	const result = fn()
+	currentCache.set(key, result)
+	return result
+}

package/packages/js-extensions/src/core/validation.ts

@@ -0,0 +1,42 @@
+// Validation utilities for extensions
+export function validateExtensionInput(
+	value: any,
+	type: string,
+	methodName: string,
+): void {
+	if (value == null) {
+		throw new TypeError(`Cannot call ${methodName} on ${value}`)
+	}
+
+	const actualType = typeof value
+	if (actualType !== type) {
+		throw new TypeError(
+			`${methodName} can only be called on ${type} values, got ${actualType}`,
+		)
+	}
+}
+
+export function validateArrayInput<T>(arr: T[], methodName: string): void {
+	if (!Array.isArray(arr)) {
+		throw new TypeError(`${methodName} can only be called on arrays`)
+	}
+}
+
+export function validateNumberRange(
+	num: number,
+	min: number,
+	max: number,
+	methodName: string,
+): void {
+	if (num < min || num > max) {
+		throw new RangeError(
+			`${methodName}: number must be between ${min} and ${max}, got ${num}`,
+		)
+	}
+}
+
+export function validatePositiveInteger(num: number, methodName: string): void {
+	if (!Number.isInteger(num) || num < 0) {
+		throw new TypeError(`${methodName}: expected positive integer, got ${num}`)
+	}
+}

package/packages/js-extensions/src/core/version.ts

@@ -0,0 +1,7 @@
+import { createRequire } from 'node:module';
+
+const requireFn = createRequire("../../package.json");
+
+export const getPackageVersion = (): string => {
+    return requireFn('../package.json').version as string;
+}

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

@@ -0,0 +1,5 @@
+// Re-export all extensions
+export * from '../string'
+export * from '../array'
+export * from '../object'
+export * from '../number'

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

@@ -0,0 +1,122 @@
+// Import types first
+import '../types/global-augmentations'
+
+import { extendArray } from './array'
+import { extendNumber } from './number'
+
+import { extendObject } from './object'
+// Import extension modules
+import { extendString } from './string'
+
+// Import core utilities
+import {
+	LRUCache,
+	getPerformanceConfig,
+	makeInternalCacheKey,
+	setPerformanceConfig,
+	withCache,
+} from './core/performance'
+
+// Import validation utilities
+import {
+	validateArrayInput,
+	validateExtensionInput,
+	validateNumberRange,
+	validatePositiveInteger,
+} from './core/validation'
+
+// Import utility functions
+import {
+	mergeConfigs,
+	validateConfig,
+	validatePerformanceSettings,
+} from './utils/config'
+
+import {
+	ensurePositiveInteger,
+	getPathSegments,
+	hasOwnProperty,
+	isValidArrayIndex,
+	safeClone,
+} from './utils/helpers'
+
+// Re-export types
+import { ExtensionOptions, PerformanceConfig } from './types/extension-types'
+export { ExtensionOptions, PerformanceConfig }
+
+// Export withCache for use in extensions
+export { withCache }
+
+// Import initialization functions
+import { extendAll, initExtensions } from './init/initializer'
+
+/**
+ * Initialize JavaScript prototype extensions
+ * @param options - Configure which extensions to enable (default: all enabled)
+ */
+export function initializeExtensions(options: ExtensionOptions = {}): void {
+	initExtensions(options)
+}
+
+/**
+ * Initialize all extensions (convenience function)
+ */
+export { extendAll }
+
+/**
+ * Selective prototype extension helpers
+ * Initialize only specific extensions
+ */
+export const extend = {
+	string: extendString,
+	array: extendArray,
+	object: extendObject,
+	number: extendNumber,
+}
+
+// Export validation utilities
+export {
+	validateExtensionInput,
+	validateArrayInput,
+	validateNumberRange,
+	validatePositiveInteger,
+}
+
+// Export utility functions
+export {
+	validateConfig,
+	validatePerformanceSettings,
+	mergeConfigs,
+	isValidArrayIndex,
+	ensurePositiveInteger,
+	safeClone,
+	getPathSegments,
+	hasOwnProperty,
+}
+
+// Export performance utilities
+export { LRUCache, setPerformanceConfig, getPerformanceConfig }
+
+// Default export
+export default {
+	initializeExtensions,
+	extendAll,
+	extend,
+	LRUCache,
+	setPerformanceConfig,
+	getPerformanceConfig,
+	// Validation utilities
+	validateExtensionInput,
+	validateArrayInput,
+	validateNumberRange,
+	validatePositiveInteger,
+	// Utility functions
+	validateConfig,
+	validatePerformanceSettings,
+	mergeConfigs,
+	isValidArrayIndex,
+	ensurePositiveInteger,
+	safeClone,
+	getPathSegments,
+	hasOwnProperty,
+}

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

@@ -0,0 +1,3 @@
+// Re-export initialization logic
+export * from './initializer'
+export * from './options'

package/packages/js-extensions/src/init/initializer.ts

@@ -0,0 +1,32 @@
+// Extension initialization logic
+import { extendArray } from '../array'
+import { setPerformanceConfig } from '../core/performance'
+import { extendNumber } from '../number'
+import { extendObject } from '../object'
+import { extendString } from '../string'
+
+import type { ExtensionOptions } from '../types/extension-types'
+
+export function initExtensions(options: ExtensionOptions = {}): void {
+	const {
+		string = true,
+		array = true,
+		object = true,
+		number = true,
+		performance,
+	} = options
+
+	if (performance) {
+		// Set performance config if provided
+		setPerformanceConfig(performance)
+	}
+
+	if (string) extendString()
+	if (array) extendArray()
+	if (object) extendObject()
+	if (number) extendNumber()
+}
+
+export function extendAll(): void {
+	initExtensions()
+}

package/packages/js-extensions/src/init/options.ts

@@ -0,0 +1,32 @@
+// Extension options validation
+import type { ExtensionOptions } from '../types/extension-types'
+
+export function validateExtensionOptions(
+	options: Partial<ExtensionOptions>,
+): ExtensionOptions {
+	const validated: ExtensionOptions = {
+		string: options.string !== false,
+		array: options.array !== false,
+		object: options.object !== false,
+		number: options.number !== false,
+		performance: options.performance,
+	}
+
+	return validated
+}
+
+export function createExtensionOptions(
+	enableString = true,
+	enableArray = true,
+	enableObject = true,
+	enableNumber = true,
+	performanceConfig?: any,
+): ExtensionOptions {
+	return {
+		string: enableString,
+		array: enableArray,
+		object: enableObject,
+		number: enableNumber,
+		performance: performanceConfig,
+	}
+}

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

@@ -0,0 +1 @@
+export { extendNumber } from './number-extensions'