mutts 1.0.2 → 1.0.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mutts",
   "description": "Modern UTility TS: A collection of TypeScript utilities",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "main": "dist/index.js",
   "module": "dist/index.esm.js",
   "types": "dist/index.d.ts",
@@ -70,17 +70,27 @@
   },
   "files": [
     "dist",
+    "src",
     "README.md",
     "docs"
   ],
   "scripts": {
     "build:js": "rollup -c",
-    "build": "npm run build:js",
+    "build:devtools": "rollup -c rollup.devtools.config.mjs",
+    "build": "npm run build:js && npm run build:devtools",
     "build:watch": "rollup -c --watch",
     "prepublishOnly": "npm run build",
     "test": "node --expose-gc node_modules/.bin/jest",
+    "test:coverage": "node --expose-gc node_modules/.bin/jest --coverage",
+    "test:coverage:watch": "node --expose-gc node_modules/.bin/jest --coverage --watch",
     "test:legacy": "TSCONFIG=tsconfig.legacy.json node node_modules/.bin/jest --detectOpenHandles --testPathPatterns=decorator",
     "test:modern": "TSCONFIG=tsconfig.modern.json node node_modules/.bin/jest --detectOpenHandles --testPathPatterns=decorator",
+    "test:profile": "RUN_PROFILING=1 node --expose-gc node_modules/.bin/jest --testPathPatterns=profiling",
+    "test:profile:benchmark": "RUN_PROFILING=1 node --expose-gc node_modules/.bin/jest --testPathPatterns=profiling --testNamePattern=benchmark",
+    "test:profile:detailed": "RUN_PROFILING=1 node --prof node_modules/.bin/jest --testPathPatterns=profiling --no-coverage",
+    "benchmark:save": "tsx tests/profiling/benchmark.ts save",
+    "benchmark:compare": "tsx tests/profiling/benchmark.ts compare",
+    "benchmark:list": "tsx tests/profiling/benchmark.ts list",
     "biome": "biome check --write src"
   },
   "keywords": [
@@ -120,12 +130,15 @@
     "@types/jest": "^30.0.0",
     "jest": "^30.0.4",
     "rollup": "^4.52.2",
+    "rollup-plugin-copy": "^3.5.0",
     "rollup-plugin-dts": "^6.2.3",
     "rollup-plugin-typescript2": "^0.36.0",
     "ts-jest": "^29.4.0",
     "ts-node": "^10.9.2",
     "tslib": "^2.8.1",
     "tsx": "^4.20.4",
-    "typescript": "^5.8.3"
-  }
-}
+    "typescript": "^5.8.3",
+    "vis-network": "^9.1.9"
+  },
+  "packageManager": "pnpm@10.7.1+sha512.2d92c86b7928dc8284f53494fb4201f983da65f0fb4f0d40baafa5cf628fa31dae3e5968f12466f17df7e97310e30f343a648baea1b9b350685dafafffdf5808"
+}

package/src/decorator.ts

@@ -0,0 +1,266 @@
+// biome-ignore-all lint/suspicious/noConfusingVoidType: We *love* voids
+// Standardized decorator system that works with both Legacy and Modern decorators
+
+import { isConstructor } from './utils'
+
+/**
+ * Error thrown when decorator operations fail
+ */
+export class DecoratorError extends Error {
+	constructor(message: string) {
+		super(message)
+		this.name = 'DecoratorException'
+	}
+}
+//#region all decorator types
+
+// Used for get/set and method decorators
+/**
+ * Legacy property decorator type for methods, getters, and setters
+ */
+export type LegacyPropertyDecorator<T> = (
+	target: T,
+	name: string | symbol,
+	descriptor: PropertyDescriptor
+) => any
+
+/**
+ * Legacy class decorator type
+ */
+export type LegacyClassDecorator<T> = (target: T) => any
+
+/**
+ * Modern method decorator type
+ */
+export type ModernMethodDecorator<T> = (target: T, context: ClassMethodDecoratorContext) => any
+
+/**
+ * Modern getter decorator type
+ */
+export type ModernGetterDecorator<T> = (target: T, context: ClassGetterDecoratorContext) => any
+
+/**
+ * Modern setter decorator type
+ */
+export type ModernSetterDecorator<T> = (target: T, context: ClassSetterDecoratorContext) => any
+
+/**
+ * Modern accessor decorator type
+ */
+export type ModernAccessorDecorator<T> = (target: T, context: ClassAccessorDecoratorContext) => any
+
+/**
+ * Modern class decorator type
+ */
+export type ModernClassDecorator<T> = (target: T, context: ClassDecoratorContext) => any
+
+//#endregion
+
+type DDMethod<T> = (
+	original: (this: T, ...args: any[]) => any,
+	name: PropertyKey
+) => ((this: T, ...args: any[]) => any) | void
+
+type DDGetter<T> = (original: (this: T) => any, name: PropertyKey) => ((this: T) => any) | void
+
+type DDSetter<T> = (
+	original: (this: T, value: any) => void,
+	name: PropertyKey
+) => ((this: T, value: any) => void) | void
+
+type DDClass<T> = <Ctor extends new (...args: any[]) => T = new (...args: any[]) => T>(
+	target: Ctor
+) => Ctor | void
+/**
+ * Description object for creating decorators that work with both Legacy and Modern decorator proposals
+ */
+export interface DecoratorDescription<T> {
+	/** Handler for method decorators */
+	method?: DDMethod<T>
+	/** Handler for class decorators */
+	class?: DDClass<T>
+	/** Handler for getter decorators */
+	getter?: DDGetter<T>
+	/** Handler for setter decorators */
+	setter?: DDSetter<T>
+	/** Default handler for any decorator type not explicitly defined */
+	default?: (...args: any[]) => any
+}
+
+/**
+ * Type for decorators that work with both Legacy and Modern decorator proposals
+ * Automatically infers the correct decorator type based on the description
+ */
+export type Decorator<T, Description extends DecoratorDescription<T>> = (Description extends {
+	method: DDMethod<T>
+}
+	? LegacyPropertyDecorator<T> & ModernMethodDecorator<T>
+	: unknown) &
+	(Description extends { class: DDClass<new (...args: any[]) => T> }
+		? LegacyClassDecorator<new (...args: any[]) => T> &
+				ModernClassDecorator<new (...args: any[]) => T>
+		: unknown) &
+	(Description extends { getter: DDGetter<T> }
+		? LegacyPropertyDecorator<T> & ModernGetterDecorator<T> & ModernAccessorDecorator<T>
+		: unknown) &
+	(Description extends { setter: DDSetter<T> }
+		? LegacyPropertyDecorator<T> & ModernSetterDecorator<T> & ModernAccessorDecorator<T>
+		: unknown) &
+	(Description extends { default: infer Signature } ? Signature : unknown)
+
+/**
+ * Factory type for creating decorators that work with both Legacy and Modern decorator proposals
+ */
+export type DecoratorFactory<T> = <Description extends DecoratorDescription<T>>(
+	description: Description
+) => (Description extends { method: DDMethod<T> }
+	? LegacyPropertyDecorator<T> & ModernMethodDecorator<T>
+	: unknown) &
+	(Description extends { class: DDClass<new (...args: any[]) => T> }
+		? LegacyClassDecorator<new (...args: any[]) => T> &
+				ModernClassDecorator<new (...args: any[]) => T>
+		: unknown) &
+	(Description extends { getter: DDGetter<T> }
+		? LegacyPropertyDecorator<T> & ModernGetterDecorator<T> & ModernAccessorDecorator<T>
+		: unknown) &
+	(Description extends { setter: DDSetter<T> }
+		? LegacyPropertyDecorator<T> & ModernSetterDecorator<T> & ModernAccessorDecorator<T>
+		: unknown) &
+	(Description extends { default: infer Signature } ? Signature : unknown)
+
+/**
+ * Creates a decorator that works with Legacy decorator proposals
+ * @param description - The decorator description object
+ * @returns A decorator function compatible with Legacy decorators
+ */
+export function legacyDecorator<T = any>(description: DecoratorDescription<T>): any {
+	return function (
+		this: any,
+		target: any,
+		propertyKey?: PropertyKey,
+		descriptor?: PropertyDescriptor,
+		...args: any[]
+	) {
+		if (propertyKey === undefined) {
+			if (isConstructor(target)) {
+				if (!('class' in description)) throw new Error('Decorator cannot be applied to a class')
+				return description.class!(target)
+			}
+		} else if (typeof target === 'object' && ['string', 'symbol'].includes(typeof propertyKey)) {
+			if (!descriptor) throw new Error('Decorator cannot be applied to a field')
+			else if (typeof descriptor === 'object' && 'configurable' in descriptor) {
+				if ('get' in descriptor || 'set' in descriptor) {
+					if (!('getter' in description || 'setter' in description))
+						throw new Error('Decorator cannot be applied to a getter or setter')
+					if ('getter' in description) {
+						const newGetter = description.getter!(descriptor.get as any, propertyKey)
+						if (newGetter) descriptor.get = newGetter
+					}
+					if ('setter' in description) {
+						const newSetter = description.setter!(descriptor.set as any, propertyKey)
+						if (newSetter) descriptor.set = newSetter
+					}
+					return descriptor
+				} else if (typeof descriptor.value === 'function') {
+					if (!('method' in description)) throw new Error('Decorator cannot be applied to a method')
+					const newMethod = description.method!(descriptor.value, propertyKey)
+					if (newMethod) descriptor.value = newMethod
+					return descriptor
+				}
+			}
+		}
+		if (!('default' in description))
+			throw new Error('Decorator do not have a default implementation')
+		return description.default!.call(this, target, propertyKey, descriptor, ...args)
+	}
+}
+
+/**
+ * Creates a decorator that works with Modern decorator proposals
+ * @param description - The decorator description object
+ * @returns A decorator function compatible with Modern decorators
+ */
+export function modernDecorator<T = any>(description: DecoratorDescription<T>): any {
+	/*return function (target: any, context?: DecoratorContext, ...args: any[]) {*/
+	return function (this: any, target: any, context?: DecoratorContext, ...args: any[]) {
+		if (!context?.kind || typeof context.kind !== 'string') {
+			if (!('default' in description))
+				throw new Error('Decorator do not have a default implementation')
+			return description.default!.call(this, target, context, ...args)
+		}
+		switch (context.kind) {
+			case 'class':
+				if (!('class' in description)) throw new Error('Decorator cannot be applied to a class')
+				return description.class!(target)
+			case 'field':
+				throw new Error('Decorator cannot be applied to a field')
+			case 'getter':
+				if (!('getter' in description)) throw new Error('Decorator cannot be applied to a getter')
+				return description.getter!(target, context.name)
+			case 'setter':
+				if (!('setter' in description)) throw new Error('Decorator cannot be applied to a setter')
+				return description.setter!(target, context.name)
+			case 'method':
+				if (!('method' in description)) throw new Error('Decorator cannot be applied to a method')
+				return description.method!(target, context.name)
+			case 'accessor': {
+				if (!('getter' in description || 'setter' in description))
+					throw new Error('Decorator cannot be applied to a getter or setter')
+				const rv: Partial<ClassAccessorDecoratorResult<any, any>> = {}
+				if ('getter' in description) {
+					const newGetter = description.getter!(target.get, context.name)
+					if (newGetter) rv.get = newGetter
+				}
+				if ('setter' in description) {
+					const newSetter = description.setter!(target.set, context.name)
+					if (newSetter) rv.set = newSetter
+				}
+				return rv
+			}
+			//return description.accessor?.(target, context.name, target)
+		}
+	}
+}
+
+/**
+ * Detects if the decorator is being called in modern (Modern) or legacy (Legacy) mode
+ * based on the arguments passed to the decorator function
+ */
+function detectDecoratorMode(
+	_target: any,
+	contextOrKey?: any,
+	_descriptor?: any
+): 'modern' | 'legacy' {
+	// Modern decorators have a context object as the second parameter
+	// Legacy decorators have a string/symbol key as the second parameter
+	if (
+		typeof contextOrKey === 'object' &&
+		contextOrKey !== null &&
+		typeof contextOrKey.kind === 'string'
+	) {
+		return 'modern'
+	}
+	return 'legacy'
+}
+
+/**
+ * Main decorator factory that automatically detects and works with both Legacy and Modern decorator proposals
+ * @param description - The decorator description object
+ * @returns A decorator that works in both Legacy and Modern environments
+ */
+export const decorator: DecoratorFactory<any> = (description: DecoratorDescription<any>) => {
+	const modern = modernDecorator(description)
+	const legacy = legacyDecorator(description)
+	return ((target: any, contextOrKey?: any, ...args: any[]) => {
+		const mode = detectDecoratorMode(target, contextOrKey, args[0])
+		return mode === 'modern'
+			? modern(target, contextOrKey, ...args)
+			: legacy(target, contextOrKey, ...args)
+	}) as any
+}
+
+/**
+ * Generic class decorator type that works with both Legacy and Modern decorator proposals
+ */
+export type GenericClassDecorator<T> = LegacyClassDecorator<abstract new (...args: any[]) => T> &
+	ModernClassDecorator<abstract new (...args: any[]) => T>

package/src/destroyable.ts

@@ -0,0 +1,199 @@
+import { decorator } from './decorator'
+
+// Integrated with `using` statement via Symbol.dispose
+const fr = new FinalizationRegistry<() => void>((f) => f())
+/**
+ * Symbol for marking destructor methods
+ */
+export const destructor = Symbol('destructor')
+/**
+ * Symbol for accessing allocated values in destroyable objects
+ */
+export const allocatedValues = Symbol('allocated')
+/**
+ * Error thrown when attempting to access a destroyed object
+ */
+export class DestructionError extends Error {
+	static throw<_T = void>(msg: string) {
+		return () => {
+			throw new DestructionError(msg)
+		}
+	}
+	constructor(msg: string) {
+		super(`Object is destroyed. ${msg}`)
+		this.name = 'DestroyedAccessError'
+	}
+}
+const destroyedHandler = {
+	[Symbol.toStringTag]: 'MutTs Destroyable',
+	get: DestructionError.throw('Cannot access destroyed object'),
+	set: DestructionError.throw('Cannot access destroyed object'),
+} as const
+
+abstract class AbstractDestroyable<Allocated> {
+	abstract [destructor](allocated: Allocated): void
+	[Symbol.dispose](): void {
+		this[destructor](this as unknown as Allocated)
+	}
+}
+
+interface Destructor<Allocated> {
+	destructor(allocated: Allocated): void
+}
+
+/**
+ * Creates a destroyable class with a base class and destructor object
+ * @param base - The base class to extend
+ * @param destructorObj - Object containing the destructor method
+ * @returns A destroyable class with static destroy and isDestroyable methods
+ */
+export function Destroyable<
+	T extends new (
+		...args: any[]
+	) => any,
+	Allocated extends Partial<InstanceType<T>>,
+>(
+	base: T,
+	destructorObj: Destructor<Allocated>
+): (new (
+	...args: ConstructorParameters<T>
+) => InstanceType<T> & { [allocatedValues]: Allocated }) & {
+	destroy(obj: InstanceType<T>): boolean
+	isDestroyable(obj: InstanceType<T>): boolean
+}
+
+/**
+ * Creates a destroyable class with only a destructor object (no base class)
+ * @param destructorObj - Object containing the destructor method
+ * @returns A destroyable class with static destroy and isDestroyable methods
+ */
+export function Destroyable<Allocated extends Record<PropertyKey, any> = Record<PropertyKey, any>>(
+	destructorObj: Destructor<Allocated>
+): (new () => { [allocatedValues]: Allocated }) & {
+	destroy(obj: any): boolean
+	isDestroyable(obj: any): boolean
+}
+
+/**
+ * Creates a destroyable class with a base class (requires [destructor] method)
+ * @param base - The base class to extend
+ * @returns A destroyable class with static destroy and isDestroyable methods
+ */
+export function Destroyable<
+	T extends new (
+		...args: any[]
+	) => any,
+	Allocated extends Record<PropertyKey, any> = Record<PropertyKey, any>,
+>(
+	base: T
+): (new (
+	...args: ConstructorParameters<T>
+) => AbstractDestroyable<Allocated> & InstanceType<T> & { [allocatedValues]: Allocated }) & {
+	destroy(obj: InstanceType<T>): boolean
+	isDestroyable(obj: InstanceType<T>): boolean
+}
+
+/**
+ * Creates an abstract destroyable base class
+ * @returns An abstract destroyable class with static destroy and isDestroyable methods
+ */
+export function Destroyable<
+	Allocated extends Record<PropertyKey, any> = Record<PropertyKey, any>,
+>(): abstract new () => (AbstractDestroyable<Allocated> & {
+	[allocatedValues]: Allocated
+}) & {
+	destroy(obj: any): boolean
+	isDestroyable(obj: any): boolean
+}
+
+export function Destroyable<
+	T extends new (
+		...args: any[]
+	) => any,
+	Allocated extends Record<PropertyKey, any> = Record<PropertyKey, any>,
+>(base?: T | Destructor<Allocated>, destructorObj?: Destructor<Allocated>) {
+	if (base && typeof base !== 'function') {
+		destructorObj = base as Destructor<Allocated>
+		base = undefined
+	}
+	if (!base) {
+		base = class {} as T
+	}
+
+	return class Destroyable extends (base as T) {
+		static readonly destructors = new WeakMap<any, () => void>()
+		static destroy(obj: Destroyable) {
+			const destructor = Destroyable.destructors.get(obj)
+			if (!destructor) return false
+			fr.unregister(obj)
+			Destroyable.destructors.delete(obj)
+			Object.setPrototypeOf(obj, new Proxy({}, destroyedHandler))
+			// Clear all own properties
+			for (const key of Object.getOwnPropertyNames(obj)) {
+				delete (obj as any)[key]
+			}
+			destructor()
+			return true
+		}
+		static isDestroyable(obj: Destroyable) {
+			return Destroyable.destructors.has(obj)
+		}
+
+		declare [forwardProperties]: PropertyKey[]
+		readonly [allocatedValues]: Allocated
+		constructor(...args: any[]) {
+			super(...args)
+			const allocated = {} as Allocated
+			this[allocatedValues] = allocated
+			// @ts-expect-error `this` is an AbstractDestroyable
+			const myDestructor = destructorObj?.destructor ?? this[destructor]
+			if (!myDestructor) {
+				throw new DestructionError('Destructor is not defined')
+			}
+			function destruction() {
+				myDestructor(allocated)
+			}
+			Destroyable.destructors.set(this, destruction)
+			fr.register(this, destruction, this)
+		}
+	}
+}
+
+const forwardProperties = Symbol('forwardProperties')
+/**
+ * Decorator that marks properties to be stored in the allocated object and passed to the destructor
+ * Use with accessor properties or explicit get/set pairs
+ */
+export const allocated = decorator({
+	setter(original, propertyKey) {
+		return function (value) {
+			this[allocatedValues][propertyKey] = value
+			return original.call(this, value)
+		}
+	},
+})
+
+/**
+ * Registers a callback to be called when an object is garbage collected
+ * @param cb - The callback function to execute on garbage collection
+ * @returns The object whose reference can be collected
+ */
+export function callOnGC(cb: () => void) {
+	let called = false
+	const forward = () => {
+		if (called) return
+		called = true
+		cb()
+	}
+	fr.register(forward, cb, cb)
+	return forward
+}
+
+/**
+ * Context Manager Protocol for `using` statement integration
+ * Provides automatic resource cleanup when used with the `using` statement
+ */
+export interface ContextManager<T = any> {
+	[Symbol.dispose](): void
+	value?: T
+}

package/src/eventful.ts

@@ -0,0 +1,77 @@
+/**
+ * Base type for event maps - all event handlers must be functions
+ */
+export type EventsBase = Record<string, (...args: any[]) => void>
+/**
+ * A type-safe event system that provides a clean API for event handling
+ * @template Events - The event map defining event names and their handler signatures
+ */
+export class Eventful<Events extends EventsBase> {
+	readonly #events = new Map<keyof Events, ((...args: any[]) => void)[]>()
+	readonly #hooks = [] as ((...args: any[]) => void)[]
+
+	public hook(
+		cb: <EventType extends keyof Events>(
+			event: EventType,
+			...args: Parameters<Events[EventType]>
+		) => void
+	): () => void {
+		if (!this.#hooks.includes(cb)) this.#hooks.push(cb)
+		return () => {
+			this.#hooks.splice(this.#hooks.indexOf(cb), 1)
+		}
+	}
+
+	public on(events: Partial<Events>): void
+	public on<EventType extends keyof Events>(event: EventType, cb: Events[EventType]): () => void
+	public on<EventType extends keyof Events>(
+		eventOrEvents: EventType | Partial<Events>,
+		cb?: Events[EventType]
+	): () => void {
+		if (typeof eventOrEvents === 'object') {
+			for (const e of Object.keys(eventOrEvents) as (keyof Events)[]) {
+				this.on(e, eventOrEvents[e]!)
+			}
+		} else if (cb !== undefined) {
+			let callbacks = this.#events.get(eventOrEvents)
+			if (!callbacks) {
+				callbacks = []
+				this.#events.set(eventOrEvents, callbacks)
+			}
+			callbacks.push(cb)
+		}
+		// @ts-expect-error Generic case leads to generic case
+		return () => this.off(eventOrEvents, cb)
+	}
+	public off(events: Partial<Events>): void
+	public off<EventType extends keyof Events>(event: EventType, cb?: Events[EventType]): void
+	public off<EventType extends keyof Events>(
+		eventOrEvents: EventType | Partial<Events>,
+		cb?: Events[EventType]
+	): void {
+		if (typeof eventOrEvents === 'object') {
+			for (const e of Object.keys(eventOrEvents) as (keyof Events)[]) {
+				this.off(e, eventOrEvents[e])
+			}
+		} else if (cb !== null && cb !== undefined) {
+			const callbacks = this.#events.get(eventOrEvents)
+			if (callbacks) {
+				this.#events.set(
+					eventOrEvents,
+					callbacks.filter((c) => c !== cb)
+				)
+			}
+		} else {
+			// Remove all listeners for this event
+			this.#events.delete(eventOrEvents)
+		}
+	}
+	public emit<EventType extends keyof Events>(
+		event: EventType,
+		...args: Parameters<Events[EventType]>
+	) {
+		const callbacks = this.#events.get(event)
+		if (callbacks) for (const cb of callbacks) cb.apply(this, args)
+		for (const cb of this.#hooks) cb.call(this, event, ...args)
+	}
+}

package/src/index.d.ts

@@ -0,0 +1,9 @@
+// Augment Array.isArray to properly handle readonly arrays in type narrowing
+interface ArrayConstructor {
+	/**
+	 * Determines whether an object is an array.
+	 * @param arg Any value to test.
+	 * @returns True if the value is an array (mutable or readonly), false otherwise.
+	 */
+	isArray(arg: any): arg is any[] | readonly any[]
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export * from './decorator'
+export * from './destroyable'
+export * from './eventful'
+export * from './indexable'
+export * from './iterableWeak'
+export * from './mixins'
+export * from './reactive'
+export * from './std-decorators'
+export * from './utils'