mutts 1.0.0

package/src/decorator.test.ts

@@ -0,0 +1,495 @@
+// Test the decorator system with all decorator types
+import { decorator } from './decorator'
+
+describe('Decorator System', () => {
+	describe('Method Decorators', () => {
+		it('should wrap method calls', () => {
+			const methodDecorator = decorator({
+				method(original, _name) {
+					return function (this: any, ...args: any[]) {
+						return `wrapped: ${original.apply(this, args)}`
+					}
+				},
+			})
+
+			class TestClass {
+				@methodDecorator
+				greet(name: string) {
+					return `Hello ${name}`
+				}
+			}
+
+			const instance = new TestClass()
+			expect(instance.greet('World')).toBe('wrapped: Hello World')
+		})
+
+		it('should work with multiple methods', () => {
+			const methodDecorator = decorator({
+				method(original, name) {
+					return function (this: any, ...args: any[]) {
+						return `${String(name)}: ${original.apply(this, args)}`
+					}
+				},
+			})
+
+			class TestClass {
+				@methodDecorator
+				first() {
+					return 'first'
+				}
+
+				@methodDecorator
+				second() {
+					return 'second'
+				}
+			}
+
+			const instance = new TestClass()
+			expect(instance.first()).toBe('first: first')
+			expect(instance.second()).toBe('second: second')
+		})
+	})
+
+	describe('Class Decorators', () => {
+		it('should modify class behavior', () => {
+			const classDecorator = decorator({
+				class: (target) => {
+					// Add a static property to the class
+					;(target as any).decorated = true
+					return target
+				},
+			})
+
+			@classDecorator
+			class TestClass {
+				static original = 'original'
+			}
+
+			expect((TestClass as any).decorated).toBe(true)
+			expect(TestClass.original).toBe('original')
+		})
+
+		it('should work with class inheritance', () => {
+			const classDecorator = decorator({
+				class: (target) => {
+					;(target as any).decorated = true
+					return target
+				},
+			})
+
+			@classDecorator
+			class BaseClass {}
+
+			class ExtendedClass extends BaseClass {}
+
+			expect((BaseClass as any).decorated).toBe(true)
+			// In legacy decorators, the decorator is applied to the class itself
+			// so ExtendedClass should also have the decorated property
+			expect((ExtendedClass as any).decorated).toBe(true)
+		})
+	})
+
+	describe('Getter Decorators', () => {
+		it('should wrap getter calls', () => {
+			const getterDecorator = decorator({
+				getter(original, _name) {
+					return function (this: any) {
+						return `wrapped: ${original.call(this)}`
+					}
+				},
+			})
+
+			class TestClass {
+				private _value = 'test'
+
+				@getterDecorator
+				get value() {
+					return this._value
+				}
+			}
+
+			const instance = new TestClass()
+			expect(instance.value).toBe('wrapped: test')
+		})
+
+		it('should work with multiple getters', () => {
+			const getterDecorator = decorator({
+				getter(original, name) {
+					return function (this: any) {
+						return `${String(name)}: ${original.call(this)}`
+					}
+				},
+			})
+
+			class TestClass {
+				private _first = 'first'
+				private _second = 'second'
+
+				@getterDecorator
+				get first() {
+					return this._first
+				}
+
+				@getterDecorator
+				get second() {
+					return this._second
+				}
+			}
+
+			const instance = new TestClass()
+			expect(instance.first).toBe('first: first')
+			expect(instance.second).toBe('second: second')
+		})
+	})
+
+	describe('Setter Decorators', () => {
+		it('should wrap setter calls', () => {
+			const setterDecorator = decorator({
+				setter(original, _name) {
+					return function (this: any, value: any) {
+						return original.call(this, `wrapped: ${value}`)
+					}
+				},
+			})
+
+			class TestClass {
+				private _value = ''
+
+				@setterDecorator
+				set value(v: string) {
+					this._value = v
+				}
+
+				get value() {
+					return this._value
+				}
+			}
+
+			const instance = new TestClass()
+			instance.value = 'test'
+			expect(instance.value).toBe('wrapped: test')
+		})
+
+		it('should work with multiple setters', () => {
+			const setterDecorator = decorator({
+				setter(original, name) {
+					return function (this: any, value: any) {
+						return original.call(this, `${String(name)}: ${value}`)
+					}
+				},
+			})
+
+			class TestClass {
+				private _first = ''
+				private _second = ''
+
+				@setterDecorator
+				set first(v: string) {
+					this._first = v
+				}
+
+				@setterDecorator
+				set second(v: string) {
+					this._second = v
+				}
+
+				get first() {
+					return this._first
+				}
+
+				get second() {
+					return this._second
+				}
+			}
+
+			const instance = new TestClass()
+			instance.first = 'test1'
+			instance.second = 'test2'
+			expect(instance.first).toBe('first: test1')
+			expect(instance.second).toBe('second: test2')
+		})
+	})
+
+	describe('Combined Decorators', () => {
+		it('should work with method and class decorators together', () => {
+			const myDecorator = decorator({
+				class: (target) => {
+					;(target as any).decorated = true
+					return target
+				},
+				method(original, _name) {
+					return function (this: any, ...args: any[]) {
+						return `method: ${original.apply(this, args)}`
+					}
+				},
+			})
+
+			@myDecorator
+			class TestClass {
+				@myDecorator
+				greet(name: string) {
+					return `Hello ${name}`
+				}
+			}
+
+			expect((TestClass as any).decorated).toBe(true)
+			const instance = new TestClass()
+			expect(instance.greet('World')).toBe('method: Hello World')
+		})
+
+		it('should work with getter and setter decorators on different properties', () => {
+			const myDecorator = decorator({
+				getter(original, _name) {
+					return function (this: any) {
+						return `get: ${original.call(this)}`
+					}
+				},
+				setter(original, _name) {
+					return function (this: any, value: any) {
+						return original.call(this, `set: ${value}`)
+					}
+				},
+			})
+
+			class TestClass {
+				private _value1 = ''
+				private _value2 = ''
+
+				@myDecorator
+				get value1() {
+					return this._value1
+				}
+
+				@myDecorator
+				set value2(v: string) {
+					this._value2 = v
+				}
+				//@ts-ignore: The end-user should put a decorator here if modern, and not if legacy
+				@myDecorator
+				get value2() {
+					return this._value2
+				}
+			}
+
+			const instance = new TestClass()
+			instance.value2 = 'test'
+			expect(instance.value1).toBe('get: ')
+			expect(instance.value2).toBe('get: set: test')
+		})
+
+		it('should work with all decorator types together', () => {
+			const myDecorator = decorator({
+				class: (target) => {
+					;(target as any).decorated = true
+					return target
+				},
+				method(original, _name) {
+					return function (this: any, ...args: any[]) {
+						return `method: ${original.apply(this, args)}`
+					}
+				},
+				getter(original, _name) {
+					return function (this: any) {
+						return `get: ${original.call(this)}`
+					}
+				},
+				default(...args) {
+					return args.length
+				},
+			})
+
+			@myDecorator
+			class TestClass {
+				value = 'initial'
+
+				@myDecorator
+				greet(name: string) {
+					return `Hello ${name}`
+				}
+
+				private _data = ''
+
+				@myDecorator
+				get data() {
+					return this._data
+				}
+
+				set data(v: string) {
+					this._data = v
+				}
+			}
+
+			// Test class decoration
+			expect((TestClass as any).decorated).toBe(true)
+
+			const instance = new TestClass()
+
+			// Test method decoration
+			expect(instance.greet('World')).toBe('method: Hello World')
+
+			// Test accessor decoration
+			instance.data = 'test'
+			expect(instance.data).toBe('get: test')
+			expect(myDecorator(1, 2, 3)).toBe(3)
+		})
+
+		it('should call all decorator types without changing behavior', () => {
+			const callLog: string[] = []
+
+			const noOpDecorator = decorator({
+				class(original) {
+					callLog.push('class decorator called')
+					return original // Return unchanged
+				},
+				method(original, name) {
+					callLog.push(`method decorator called for ${String(name)}`)
+					return original // Return unchanged
+				},
+				getter(original, name) {
+					callLog.push(`getter decorator called for ${String(name)}`)
+					return original // Return unchanged
+				},
+				setter(original, name) {
+					callLog.push(`setter decorator called for ${String(name)}`)
+					return original // Return unchanged
+				},
+			})
+
+			@noOpDecorator
+			class TestClass {
+				value = 'initial'
+
+				@noOpDecorator
+				greet(name: string) {
+					return `Hello ${name}`
+				}
+
+				private _data = ''
+
+				@noOpDecorator
+				get data() {
+					return this._data
+				}
+
+				set data(v: string) {
+					this._data = v
+				}
+			}
+
+			// Verify all decorators were called
+			expect(callLog).toContain('class decorator called')
+			expect(callLog).toContain('method decorator called for greet')
+			expect(callLog).toContain('getter decorator called for data')
+
+			const instance = new TestClass()
+
+			// Verify behavior is unchanged (no wrapping occurred)
+			expect(instance.greet('World')).toBe('Hello World') // No "method:" prefix
+			expect(instance.value).toBe('initial')
+
+			instance.data = 'test'
+			expect(instance.data).toBe('test') // No "get:" prefix
+		})
+
+		it('should call setter decorator without changing behavior', () => {
+			const callLog: string[] = []
+
+			const noOpDecorator = decorator({
+				setter(original, name) {
+					callLog.push(`setter decorator called for ${String(name)}`)
+					return original // Return unchanged
+				},
+			})
+
+			class TestClass {
+				private _value = ''
+
+				@noOpDecorator
+				set value(v: string) {
+					this._value = v
+				}
+
+				get value() {
+					return this._value
+				}
+			}
+
+			// Verify setter decorator was called
+			expect(callLog).toContain('setter decorator called for value')
+
+			const instance = new TestClass()
+
+			// Verify behavior is unchanged (no wrapping occurred)
+			instance.value = 'test'
+			expect(instance.value).toBe('test') // No wrapping
+		})
+	})
+
+	describe('Error Handling', () => {
+		it('should throw error when decorator is applied to wrong target', () => {
+			const methodOnlyDecorator = decorator({
+				method(original, _name) {
+					return original
+				},
+			})
+
+			expect(() => {
+				class TestClass {
+					// @ts-ignore
+					@methodOnlyDecorator
+					value = 'test'
+				}
+				void new TestClass()
+			}).toThrow('Decorator cannot be applied to a field')
+		})
+
+		it('should throw error when class decorator is applied to method', () => {
+			const classOnlyDecorator = decorator({
+				class: (target) => target,
+			})
+
+			expect(() => {
+				class TestClass {
+					// @ts-ignore
+					@classOnlyDecorator
+					method() {}
+				}
+				void new TestClass()
+			}).toThrow('Decorator cannot be applied to a method')
+		})
+
+		it('should throw error when getter decorator is applied to method', () => {
+			const getterOnlyDecorator = decorator({
+				getter(original, _name) {
+					return original
+				},
+			})
+
+			expect(() => {
+				class TestClass {
+					// @ts-ignore
+					@getterOnlyDecorator
+					method() {}
+				}
+				void new TestClass()
+			}).toThrow('Decorator cannot be applied to a method')
+		})
+
+		it('should throw error when decorating a field', () => {
+			const anyDecorator = decorator({
+				method(original, _name) {
+					return original
+				},
+			})
+
+			expect(() => {
+				class TestClass {
+					// @ts-ignore
+					@anyDecorator
+					field = 'value'
+				}
+				void new TestClass()
+			}).toThrow('Decorator cannot be applied to a field')
+		})
+	})
+})

package/src/decorator.ts

@@ -0,0 +1,205 @@
+// biome-ignore-all lint/suspicious/noConfusingVoidType: We *love* voids
+// Standardized decorator system that works with both Legacy and Modern decorators
+
+import { isConstructor } from './utils'
+
+export class DecoratorError extends Error {
+	constructor(message: string) {
+		super(message)
+		this.name = 'DecoratorException'
+	}
+}
+//#region all decorator types
+
+// Used for get/set and method decorators
+export type LegacyPropertyDecorator<T> = (
+	target: T,
+	name: string | symbol,
+	descriptor: PropertyDescriptor
+) => any
+
+export type LegacyClassDecorator<T> = (target: T) => any
+
+export type ModernMethodDecorator<T> = (target: T, context: ClassMethodDecoratorContext) => any
+
+export type ModernGetterDecorator<T> = (target: T, context: ClassGetterDecoratorContext) => any
+
+export type ModernSetterDecorator<T> = (target: T, context: ClassSetterDecoratorContext) => any
+
+export type ModernAccessorDecorator<T> = (target: T, context: ClassAccessorDecoratorContext) => any
+
+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
+export interface DecoratorDescription<T> {
+	method?: DDMethod<T>
+	class?: DDClass<T>
+	getter?: DDGetter<T>
+	setter?: DDSetter<T>
+	default?: (...args: any[]) => any
+}
+
+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)
+
+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)
+
+export function legacyDecorator<T = any>(description: DecoratorDescription<T>): any {
+	return function (
+		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, propertyKey)
+						if (newGetter) descriptor.get = newGetter
+					}
+					if ('setter' in description) {
+						const newSetter = description.setter?.(descriptor.set, 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)
+	}
+}
+
+export function modernDecorator<T = any>(description: DecoratorDescription<T>): any {
+	return function (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'
+}
+
+export const decorator: DecoratorFactory<any> = (description: DecoratorDescription<any>) => {
+	return ((target: any, contextOrKey?: any, ...args: any[]) => {
+		const mode = detectDecoratorMode(target, contextOrKey, args[0])
+		return mode === 'modern'
+			? modernDecorator(description)(target, contextOrKey, ...args)
+			: legacyDecorator(description)(target, contextOrKey, ...args)
+	}) as any
+}
+
+export type GenericClassDecorator<T> = LegacyClassDecorator<new (...args: any[]) => T> &
+	ModernClassDecorator<new (...args: any[]) => T>