mutts 1.0.0

package/src/destroyable.test.ts

@@ -0,0 +1,155 @@
+import {
+	allocated,
+	allocatedValues,
+	Destroyable,
+	DestructionError,
+	destructor,
+} from './destroyable'
+
+function tick(ms: number = 0) {
+	return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+const gc = global.gc
+
+async function collectGarbages() {
+	await tick()
+	gc!()
+	await tick()
+}
+
+describe('Destroyable', () => {
+	describe('with base class and destructor object', () => {
+		it('should create destroyable class with custom destructor', async () => {
+			let receivedAllocated: any = null
+
+			class MyClass extends Destroyable({
+				destructor(allocated) {
+					receivedAllocated = allocated
+				},
+			}) {
+				constructor(public name: string) {
+					super()
+					this[allocatedValues].name = name
+				}
+			}
+
+			;(() => {
+				const obj = new MyClass('test')
+				expect(obj.name).toBe('test')
+			})()
+			await collectGarbages()
+			expect(receivedAllocated.name).toBe('test')
+		})
+
+		it('should pass constructor arguments to base class', () => {
+			class BaseClass {
+				constructor(public value: number) {}
+			}
+
+			const DestroyableBaseClass = Destroyable(BaseClass, {
+				destructor: () => {},
+			})
+
+			const obj = new DestroyableBaseClass(42)
+			expect(obj.value).toBe(42)
+		})
+
+		it('should throw error when accessing destroyed object', () => {
+			class MyClass {
+				constructor(public name: string) {}
+			}
+
+			const DestroyableMyClass = Destroyable(MyClass, {
+				destructor: () => {},
+			})
+
+			const obj = new DestroyableMyClass('test')
+			DestroyableMyClass.destroy(obj)
+
+			expect(() => obj.name).toThrow(DestructionError)
+			expect(() => {
+				obj.name = 'value'
+			}).toThrow(DestructionError)
+		})
+	})
+
+	describe('with destructor object only', () => {
+		it('should create destroyable class from scratch', () => {
+			let destructorCalled = false
+
+			const DestroyableClass = Destroyable({
+				destructor: () => {
+					destructorCalled = true
+				},
+			})
+
+			const obj = new DestroyableClass()
+			expect(DestroyableClass.isDestroyable(obj)).toBe(true)
+			expect(destructorCalled).toBe(false)
+
+			const result = DestroyableClass.destroy(obj)
+			expect(result).toBe(true)
+			expect(destructorCalled).toBe(true)
+		})
+	})
+
+	describe('with base class only', () => {
+		it('should create destroyable class with default destructor', () => {
+			class MyClass {
+				constructor(public name: string) {}
+			}
+
+			const DestroyableMyClass = Destroyable(MyClass)
+
+			expect(() => new DestroyableMyClass('test')).toThrow(DestructionError)
+		})
+	})
+
+	describe('class with [destructor] method', () => {
+		it('should call [destructor] method with allocated values', async () => {
+			let receivedAllocated: any = null
+
+			class MyClass extends Destroyable() {
+				constructor(public name: string) {
+					super()
+					this[allocatedValues].name = name
+				}
+				[destructor](allocated: any) {
+					receivedAllocated = allocated
+				}
+			}
+
+			;(() => {
+				const obj = new MyClass('test')
+				expect(obj.name).toBe('test')
+			})()
+			await collectGarbages()
+			expect(receivedAllocated.name).toBe('test')
+		})
+	})
+	describe('decorators usage', () => {
+		it('should collect allocated from decorators', async () => {
+			let receivedAllocated: any = null
+
+			class MyClass extends Destroyable() {
+				@allocated
+				accessor name: string
+				constructor(name: string) {
+					super()
+					this.name = name
+				}
+				[destructor](allocated: any) {
+					receivedAllocated = allocated
+				}
+			}
+
+			;(() => {
+				const obj = new MyClass('test')
+				expect(obj.name).toBe('test')
+			})()
+			await collectGarbages()
+			expect(receivedAllocated.name).toBe('test')
+		})
+	})
+})

package/src/destroyable.ts

@@ -0,0 +1,158 @@
+import { decorator } from './decorator'
+
+// Integrated with `using` statement via Symbol.dispose
+const fr = new FinalizationRegistry<() => void>((f) => f())
+export const destructor = Symbol('destructor')
+export const allocatedValues = Symbol('allocated')
+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
+}
+
+export function Destroyable<
+	T extends new (
+		...args: any[]
+	) => any,
+	Allocated extends Partial<typeof this>,
+>(
+	base: T,
+	destructorObj: Destructor<Allocated>
+): (new (
+	...args: ConstructorParameters<T>
+) => InstanceType<T> & { [allocatedValues]: Allocated }) & {
+	destroy(obj: InstanceType<T>): boolean
+	isDestroyable(obj: InstanceType<T>): boolean
+}
+
+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
+}
+
+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
+}
+
+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')
+export const allocated = decorator({
+	setter(original, propertyKey) {
+		return function (value) {
+			this[allocatedValues][propertyKey] = value
+			return original.call(this, value)
+		}
+	},
+})
+
+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 `with` statement integration
+export interface ContextManager<T = any> {
+	[Symbol.dispose](): void
+	value?: T
+}

package/src/eventful.test.ts

@@ -0,0 +1,380 @@
+import { Eventful } from './eventful'
+
+describe('Eventful', () => {
+	// Define test event types
+	interface TestEvents extends Record<string, (...args: any[]) => void> {
+		userLogin: (userId: string, timestamp: Date) => void
+		dataUpdate: (data: any[]) => void
+		error: (error: Error) => void
+		simple: () => void
+		withNumber: (value: number) => void
+	}
+
+	class TestEventful extends Eventful<TestEvents> {
+		// Test class that extends Eventful
+		// Just make `emit` public for testing
+		public emit<EventType extends keyof TestEvents>(
+			event: EventType,
+			...args: Parameters<TestEvents[EventType]>
+		) {
+			super.emit(event, ...args)
+		}
+	}
+
+	describe('basic functionality', () => {
+		it('should register and emit single events', () => {
+			const eventful = new TestEventful()
+			let callCount = 0
+			let receivedUserId = ''
+			let receivedTimestamp: Date | null = null
+
+			eventful.on('userLogin', (userId, timestamp) => {
+				callCount++
+				receivedUserId = userId
+				receivedTimestamp = timestamp
+			})
+
+			const testDate = new Date()
+			eventful.emit('userLogin', 'user123', testDate)
+
+			expect(callCount).toBe(1)
+			expect(receivedUserId).toBe('user123')
+			expect(receivedTimestamp).toBe(testDate)
+		})
+
+		it('should register and emit events with no parameters', () => {
+			const eventful = new TestEventful()
+			let callCount = 0
+
+			eventful.on('simple', () => {
+				callCount++
+			})
+
+			eventful.emit('simple')
+
+			expect(callCount).toBe(1)
+		})
+
+		it('should register and emit events with primitive parameters', () => {
+			const eventful = new TestEventful()
+			let receivedValue = 0
+
+			eventful.on('withNumber', (value) => {
+				receivedValue = value
+			})
+
+			eventful.emit('withNumber', 42)
+
+			expect(receivedValue).toBe(42)
+		})
+	})
+
+	describe('multiple listeners', () => {
+		it('should support multiple listeners for the same event', () => {
+			const eventful = new TestEventful()
+			let callCount1 = 0
+			let callCount2 = 0
+
+			eventful.on('simple', () => callCount1++)
+			eventful.on('simple', () => callCount2++)
+
+			eventful.emit('simple')
+
+			expect(callCount1).toBe(1)
+			expect(callCount2).toBe(1)
+		})
+
+		it('should call all listeners in registration order', () => {
+			const eventful = new TestEventful()
+			const callOrder: number[] = []
+
+			eventful.on('simple', () => callOrder.push(1))
+			eventful.on('simple', () => callOrder.push(2))
+			eventful.on('simple', () => callOrder.push(3))
+
+			eventful.emit('simple')
+
+			expect(callOrder).toEqual([1, 2, 3])
+		})
+	})
+
+	describe('unsubscribe functionality', () => {
+		it('should return unsubscribe function for single event', () => {
+			const eventful = new TestEventful()
+			let callCount = 0
+
+			const unsubscribe = eventful.on('simple', () => callCount++)
+
+			eventful.emit('simple')
+			expect(callCount).toBe(1)
+
+			unsubscribe()
+			eventful.emit('simple')
+			expect(callCount).toBe(1) // Should not increment
+		})
+
+		it('should unsubscribe specific callback when provided', () => {
+			const eventful = new TestEventful()
+			let callCount1 = 0
+			let callCount2 = 0
+
+			const callback1 = () => callCount1++
+			const callback2 = () => callCount2++
+
+			eventful.on('simple', callback1)
+			eventful.on('simple', callback2)
+
+			eventful.emit('simple')
+			expect(callCount1).toBe(1)
+			expect(callCount2).toBe(1)
+
+			eventful.off('simple', callback1)
+			eventful.emit('simple')
+			expect(callCount1).toBe(1) // Should not increment
+			expect(callCount2).toBe(2) // Should still increment
+		})
+
+		it('should remove all listeners when no callback provided to off', () => {
+			const eventful = new TestEventful()
+			let callCount1 = 0
+			let callCount2 = 0
+
+			eventful.on('simple', () => callCount1++)
+			eventful.on('simple', () => callCount2++)
+
+			eventful.emit('simple')
+			expect(callCount1).toBe(1)
+			expect(callCount2).toBe(1)
+
+			eventful.off('simple')
+			eventful.emit('simple')
+			expect(callCount1).toBe(1) // Should not increment
+			expect(callCount2).toBe(1) // Should not increment
+		})
+	})
+
+	describe('bulk event registration', () => {
+		it('should register multiple events at once', () => {
+			const eventful = new TestEventful()
+			let loginCount = 0
+			let dataCount = 0
+			let errorCount = 0
+
+			eventful.on({
+				userLogin: () => loginCount++,
+				dataUpdate: () => dataCount++,
+				error: () => errorCount++,
+			})
+
+			eventful.emit('userLogin', 'user123', new Date())
+			eventful.emit('dataUpdate', [1, 2, 3])
+			eventful.emit('error', new Error('test'))
+
+			expect(loginCount).toBe(1)
+			expect(dataCount).toBe(1)
+			expect(errorCount).toBe(1)
+		})
+
+		it('should unsubscribe multiple events at once', () => {
+			const eventful = new TestEventful()
+			let loginCount = 0
+			let dataCount = 0
+
+			const loginCallback = () => loginCount++
+			const dataCallback = () => dataCount++
+
+			eventful.on('userLogin', loginCallback)
+			eventful.on('dataUpdate', dataCallback)
+
+			eventful.emit('userLogin', 'user123', new Date())
+			eventful.emit('dataUpdate', [1, 2, 3])
+			expect(loginCount).toBe(1)
+			expect(dataCount).toBe(1)
+
+			eventful.off({
+				userLogin: loginCallback,
+				dataUpdate: dataCallback,
+			})
+
+			eventful.emit('userLogin', 'user123', new Date())
+			eventful.emit('dataUpdate', [1, 2, 3])
+			expect(loginCount).toBe(1) // Should not increment
+			expect(dataCount).toBe(1) // Should not increment
+		})
+	})
+
+	describe('global hooks', () => {
+		it('should call global hooks for all events', () => {
+			const eventful = new TestEventful()
+			const hookCalls: Array<{ event: string; args: any[] }> = []
+
+			eventful.hook((event, ...args) => {
+				hookCalls.push({ event: String(event), args })
+			})
+
+			eventful.emit('userLogin', 'user123', new Date())
+			eventful.emit('simple')
+			eventful.emit('withNumber', 42)
+
+			expect(hookCalls).toHaveLength(3)
+			expect(hookCalls[0].event).toBe('userLogin')
+			expect(hookCalls[0].args).toEqual(['user123', expect.any(Date)])
+			expect(hookCalls[1].event).toBe('simple')
+			expect(hookCalls[1].args).toEqual([])
+			expect(hookCalls[2].event).toBe('withNumber')
+			expect(hookCalls[2].args).toEqual([42])
+		})
+
+		it('should support multiple global hooks', () => {
+			const eventful = new TestEventful()
+			let hook1Count = 0
+			let hook2Count = 0
+
+			eventful.hook(() => hook1Count++)
+			eventful.hook(() => hook2Count++)
+
+			eventful.emit('simple')
+
+			expect(hook1Count).toBe(1)
+			expect(hook2Count).toBe(1)
+		})
+
+		it('should return unsubscribe function for hooks', () => {
+			const eventful = new TestEventful()
+			let hookCount = 0
+
+			const unsubscribe = eventful.hook(() => hookCount++)
+
+			eventful.emit('simple')
+			expect(hookCount).toBe(1)
+
+			unsubscribe()
+			eventful.emit('simple')
+			expect(hookCount).toBe(1) // Should not increment
+		})
+
+		it('should prevent duplicate hook registration', () => {
+			const eventful = new TestEventful()
+			let hookCount = 0
+
+			const hookCallback = () => hookCount++
+
+			eventful.hook(hookCallback)
+			eventful.hook(hookCallback) // Should not add duplicate
+
+			eventful.emit('simple')
+			expect(hookCount).toBe(1) // Should only be called once
+		})
+	})
+
+	describe('combined functionality', () => {
+		it('should call both specific listeners and global hooks', () => {
+			const eventful = new TestEventful()
+			let specificCount = 0
+			let hookCount = 0
+
+			eventful.on('simple', () => specificCount++)
+			eventful.hook(() => hookCount++)
+
+			eventful.emit('simple')
+
+			expect(specificCount).toBe(1)
+			expect(hookCount).toBe(1)
+		})
+
+		it('should handle complex event scenarios', () => {
+			const eventful = new TestEventful()
+			const events: string[] = []
+
+			// Register multiple listeners
+			eventful.on('userLogin', () => events.push('login1'))
+			eventful.on('userLogin', () => events.push('login2'))
+			eventful.on('dataUpdate', () => events.push('data1'))
+
+			// Register global hook
+			eventful.hook((event, ..._args) => {
+				events.push(`hook:${String(event)}`)
+			})
+
+			// Emit events
+			eventful.emit('userLogin', 'user123', new Date())
+			eventful.emit('dataUpdate', [1, 2, 3])
+
+			expect(events).toEqual(['login1', 'login2', 'hook:userLogin', 'data1', 'hook:dataUpdate'])
+		})
+	})
+
+	describe('edge cases', () => {
+		it('should handle emitting events with no listeners', () => {
+			const eventful = new TestEventful()
+
+			// Should not throw
+			expect(() => {
+				eventful.emit('userLogin', 'user123', new Date())
+				eventful.emit('simple')
+			}).not.toThrow()
+		})
+
+		it('should handle unsubscribing non-existent callbacks', () => {
+			const eventful = new TestEventful()
+
+			// Should not throw
+			expect(() => {
+				eventful.off('simple', () => {})
+				eventful.off('simple')
+			}).not.toThrow()
+		})
+
+		it('should handle unsubscribing from non-existent events', () => {
+			const eventful = new TestEventful()
+
+			// Should not throw
+			expect(() => {
+				eventful.off('nonExistentEvent' as any)
+			}).not.toThrow()
+		})
+
+		it('should handle multiple unsubscribes of the same callback', () => {
+			const eventful = new TestEventful()
+			let callCount = 0
+
+			const callback = () => callCount++
+			const unsubscribe = eventful.on('simple', callback)
+
+			eventful.emit('simple')
+			expect(callCount).toBe(1)
+
+			unsubscribe()
+			unsubscribe() // Should not throw
+			unsubscribe() // Should not throw
+
+			eventful.emit('simple')
+			expect(callCount).toBe(1) // Should not increment
+		})
+	})
+
+	describe('type safety', () => {
+		it('should enforce correct parameter types', () => {
+			const eventful = new TestEventful()
+
+			// These should compile without errors
+			eventful.on('userLogin', (userId: string, timestamp: Date) => {
+				expect(typeof userId).toBe('string')
+				expect(timestamp).toBeInstanceOf(Date)
+			})
+
+			eventful.on('dataUpdate', (data: any[]) => {
+				expect(Array.isArray(data)).toBe(true)
+			})
+
+			eventful.on('error', (error: Error) => {
+				expect(error).toBeInstanceOf(Error)
+			})
+
+			// Emit with correct types
+			eventful.emit('userLogin', 'user123', new Date())
+			eventful.emit('dataUpdate', [1, 2, 3])
+			eventful.emit('error', new Error('test'))
+		})
+	})
+})