mutts 1.0.7 → 1.0.9

package/src/async/browser.ts

@@ -1,65 +1,301 @@
-import { Hook, Restorer, asyncHooks } from '.'
+import { asyncHooks, hooks, type Restorer } from '.'
 
-const hooks = new Set<Hook>()
+const promiseContexts = new WeakMap<Promise<any>, Set<Restorer>>()
 
-asyncHooks.addHook = function (hook: Hook) {
-	hooks.add(hook)
-	return () => {
-		hooks.delete(hook)
+// [HACK]: Sanitization
+// If a Promise is created inside the zone, it carries the "Sticky" zone context.
+// If returned to the outer scope, that context leaks. We wrap it in a new Promise
+// created here (in the outer scope) to break the chain and sanitize the return value.
+// See BROWSER_ASYNC_POLYFILL.md for full details.
+asyncHooks.sanitizePromise = (res: any) => {
+	if (res && typeof (res as any).then === 'function') {
+		return new Promise((resolve, reject) => {
+			setTimeout(() => {
+				;(res as any).then(resolve, reject)
+			}, 0)
+		})
 	}
+	return res
 }
 
-export * from '../index'
-
-function wrap<Args extends any[], R>(fn: ((...args: Args) => R) | null | undefined) {
-	if (typeof fn !== 'function') return fn
+function captureRestorers() {
 	const restorers = new Set<Restorer>()
-	for (const hook of hooks) restorers.add(hook())
+	for (const hook of hooks) {
+		const restorer = hook()
+		if (restorer) restorers.add(restorer)
+	}
+	return restorers
+}
 
+function wrap<Args extends any[], R>(
+	fn: ((...args: Args) => R) | null | undefined,
+	capturedRestorers?: Set<Restorer>
+) {
+	if (typeof fn !== 'function') return fn
+	const restorers = capturedRestorers || captureRestorers()
 	return function (this: any, ...args: Args) {
-		const undoers = new Set<() => void>()
-		for (const restore of restorers) undoers.add(restore())
+		const undoers: (() => void)[] = []
+		for (const restore of restorers) undoers.push(restore())
 		try {
 			return fn.apply(this, args)
 		} finally {
-			for (const undo of undoers) undo()
+			if (originals.queueMicrotask) {
+				// Double microtask ensures we run after the first await resumption microtask
+				originals.queueMicrotask.call(globalThis, () => {
+					originals.queueMicrotask.call(globalThis, () => {
+						originals.queueMicrotask.call(globalThis, () => {
+							for (let i = undoers.length - 1; i >= 0; i--) undoers[i]()
+						})
+					})
+				})
+			} else {
+				for (let i = undoers.length - 1; i >= 0; i--) undoers[i]()
+			}
+		}
+	}
+}
+
+const targetWrappers = new WeakMap<any, Map<string, WeakMap<Function, Function>>>()
+
+function patchEventTarget(proto: any) {
+	if (!proto || !proto.addEventListener || !proto.removeEventListener) return
+	const nativeAdd = proto.addEventListener
+	const nativeRemove = proto.removeEventListener
+
+	proto.addEventListener = function (this: any, type: string, listener: any, options: any) {
+		if (typeof listener !== 'function') {
+			return nativeAdd.call(this, type, listener, options)
+		}
+
+		let types = targetWrappers.get(this)
+		if (!types) {
+			types = new Map()
+			targetWrappers.set(this, types)
+		}
+		let listeners = types.get(type)
+		if (!listeners) {
+			listeners = new WeakMap()
+			types.set(type, listeners)
+		}
+
+		let wrapped = listeners.get(listener)
+		if (!wrapped) {
+			wrapped = wrap(listener)
+			listeners.set(listener, wrapped)
+		}
+
+		return nativeAdd.call(this, type, wrapped, options)
+	}
+
+	proto.removeEventListener = function (this: any, type: string, listener: any, options: any) {
+		if (typeof listener !== 'function') {
+			return nativeRemove.call(this, type, listener, options)
+		}
+
+		const types = targetWrappers.get(this)
+		if (types) {
+			const listeners = types.get(type)
+			if (listeners) {
+				const wrapped = listeners.get(listener)
+				if (wrapped) {
+					return nativeRemove.call(this, type, wrapped, options)
+				}
+			}
 		}
+
+		return nativeRemove.call(this, type, listener, options)
 	}
 }
 
-const originals = {
-	then: Promise.prototype.then,
-	catch: Promise.prototype.catch,
-	finally: Promise.prototype.finally,
-	setTimeout: globalThis.setTimeout,
-	setInterval: globalThis.setInterval,
-	setImmediate: globalThis.setImmediate,
-	requestAnimationFrame: globalThis.requestAnimationFrame,
-	queueMicrotask: globalThis.queueMicrotask,
+function patchOnProperties(proto: any) {
+	if (!proto) return
+	for (const prop of Object.getOwnPropertyNames(proto)) {
+		if (prop.startsWith('on')) {
+			const desc = Object.getOwnPropertyDescriptor(proto, prop)
+			if (desc && desc.set && desc.configurable) {
+				const nativeSet = desc.set
+				Object.defineProperty(proto, prop, {
+					...desc,
+					set: function (this: any, fn: any) {
+						nativeSet.call(this, wrap(fn))
+					},
+				})
+			}
+		}
+	}
 }
 
-Promise.prototype.then = function <T, R1, R2>(
-	this: Promise<T>,
-	onFulfilled?: ((value: T) => R1 | PromiseLike<R1>) | null,
-	onRejected?: ((reason: any) => R2 | PromiseLike<R2>) | null
-): Promise<R1 | R2> {
-	return originals.then.call(this, wrap(onFulfilled), wrap(onRejected))
+if (typeof EventTarget !== 'undefined') {
+	patchEventTarget(EventTarget.prototype)
 }
 
-Promise.prototype.catch = function <T>(
-	this: Promise<T>,
-	onRejected?: ((reason: any) => T | PromiseLike<T>) | null
-): Promise<T> {
-	return originals.catch.call(this, wrap(onRejected))
+const prototypesToPatch = [
+	typeof EventTarget !== 'undefined' && EventTarget.prototype,
+	typeof HTMLElement !== 'undefined' && HTMLElement.prototype,
+	typeof Window !== 'undefined' && Window.prototype,
+	typeof Document !== 'undefined' && Document.prototype,
+	typeof MessagePort !== 'undefined' && MessagePort.prototype,
+	typeof XMLHttpRequest !== 'undefined' && XMLHttpRequest.prototype,
+	typeof IDBRequest !== 'undefined' && IDBRequest.prototype,
+	typeof IDBTransaction !== 'undefined' && IDBTransaction.prototype,
+	typeof IDBDatabase !== 'undefined' && IDBDatabase.prototype,
+	typeof FileReader !== 'undefined' && FileReader.prototype,
+	typeof AbortSignal !== 'undefined' && AbortSignal.prototype,
+]
+
+for (const proto of prototypesToPatch) {
+	if (proto) {
+		patchOnProperties(proto)
+	}
 }
 
-Promise.prototype.finally = function <T>(
-	this: Promise<T>,
-	onFinally?: (() => void) | null
-): Promise<T> {
-	return originals.finally.call(this, wrap(onFinally))
+const GLOBAL_ORIGINALS = Symbol.for('mutts.originals')
+const GLOBAL_PROMISE = Symbol.for('mutts.OriginalPromise')
+
+let originals: any
+let OriginalPromise: any
+
+if ((globalThis as any)[GLOBAL_ORIGINALS]) {
+	originals = (globalThis as any)[GLOBAL_ORIGINALS]
+	OriginalPromise = (globalThis as any)[GLOBAL_PROMISE]
+} else {
+	OriginalPromise = globalThis.Promise
+	originals = {
+		then: OriginalPromise.prototype.then,
+		catch: OriginalPromise.prototype.catch,
+		finally: OriginalPromise.prototype.finally,
+		resolve: OriginalPromise.resolve,
+		reject: OriginalPromise.reject,
+		all: OriginalPromise.all,
+		allSettled: (OriginalPromise as any).allSettled,
+		race: OriginalPromise.race,
+		any: (OriginalPromise as any).any,
+		setTimeout: globalThis.setTimeout,
+		setInterval: globalThis.setInterval,
+		setImmediate: (globalThis as any).setImmediate,
+		requestAnimationFrame: (globalThis as any).requestAnimationFrame,
+		queueMicrotask: globalThis.queueMicrotask,
+	}
+	;(globalThis as any)[GLOBAL_ORIGINALS] = originals
+	;(globalThis as any)[GLOBAL_PROMISE] = OriginalPromise
 }
 
+// Ensure modern statics are captured even if originals was cached from an older version
+if (!originals.allSettled) originals.allSettled = (OriginalPromise as any).allSettled
+if (!originals.any) originals.any = (OriginalPromise as any).any
+if (!originals.race) originals.race = OriginalPromise.race
+
+function patchedThen(this: any, onFulfilled: any, onRejected: any) {
+	const context = promiseContexts.get(this) || captureRestorers()
+	const nextPromise = originals.then.call(
+		this,
+		wrap(onFulfilled, context),
+		wrap(onRejected, context)
+	)
+	if (context.size > 0) promiseContexts.set(nextPromise, context)
+	return nextPromise
+}
+
+function patchedCatch(this: any, onRejected: any) {
+	const context = promiseContexts.get(this) || captureRestorers()
+	const nextPromise = originals.catch.call(this, wrap(onRejected, context))
+	if (context.size > 0) promiseContexts.set(nextPromise, context)
+	return nextPromise
+}
+
+function patchedFinally(this: any, onFinally: any) {
+	const context = promiseContexts.get(this) || captureRestorers()
+	const nextPromise = originals.finally.call(this, wrap(onFinally, context))
+	if (context.size > 0) promiseContexts.set(nextPromise, context)
+	return nextPromise
+}
+
+function PatchedPromise<T>(
+	this: any,
+	executor: (resolve: (value: T | PromiseLike<T>) => void, reject: (reason?: any) => void) => void
+) {
+	if (typeof executor === 'function') {
+		const p = new OriginalPromise((resolve, reject) => {
+			const wrappedResolve = wrap(resolve)
+			const wrappedReject = wrap(reject)
+			executor(wrappedResolve, wrappedReject)
+		})
+		const context = captureRestorers()
+		promiseContexts.set(p, context) // Always set, even if empty (Sticky Root)
+		return p
+	}
+	return new OriginalPromise(executor)
+}
+
+// Copy statics
+Object.assign(PatchedPromise, OriginalPromise as any)
+
+// Inherit prototype for instanceof checks
+PatchedPromise.prototype = OriginalPromise.prototype
+
+PatchedPromise.resolve = (<T>(value?: T | PromiseLike<T>): Promise<T> => {
+	const p = originals.resolve.call(OriginalPromise, value) as Promise<T>
+	const context = captureRestorers()
+	// Ensure we don't overwrite if it already has context (e.g. from constructor)
+	if (context.size > 0 && !promiseContexts.has(p)) promiseContexts.set(p, context)
+	return p
+}) as any
+
+PatchedPromise.reject = (<T = never>(reason?: any): Promise<T> => {
+	const p = originals.reject.call(OriginalPromise, reason) as Promise<T>
+	const context = captureRestorers()
+	if (context.size > 0) promiseContexts.set(p, context)
+	return p
+}) as any
+
+PatchedPromise.all = (<T>(values: Iterable<T | PromiseLike<T>>): Promise<Awaited<T>[]> => {
+	const p = originals.all.call(OriginalPromise, values) as Promise<Awaited<T>[]>
+	const context = captureRestorers()
+	if (context.size > 0) promiseContexts.set(p, context)
+	return p
+}) as any
+
+PatchedPromise.allSettled = (<T>(
+	values: Iterable<T | PromiseLike<T>>
+): Promise<PromiseSettledResult<Awaited<T>>[]> => {
+	const p = (originals.allSettled as any).call(OriginalPromise, values)
+	const context = captureRestorers()
+	if (context.size > 0) promiseContexts.set(p, context)
+	return p
+}) as any
+
+PatchedPromise.race = (<T>(values: Iterable<T | PromiseLike<T>>): Promise<Awaited<T>> => {
+	const p = originals.race.call(OriginalPromise, values) as Promise<Awaited<T>>
+	const context = captureRestorers()
+	if (context.size > 0) promiseContexts.set(p, context)
+	return p
+}) as any
+
+PatchedPromise.any = (<T>(values: Iterable<T | PromiseLike<T>>): Promise<Awaited<T>> => {
+	const p = (originals.any as any).call(OriginalPromise, values)
+	const context = captureRestorers()
+	if (context.size > 0) promiseContexts.set(p, context)
+	return p
+}) as any
+
+// Only apply patches if not already applied (or re-apply safely)
+// Note: OriginalPromise.prototype might be shared if we used the global one.
+// We must ensure we don't patch it twice if it's the SAME object.
+if (OriginalPromise.prototype.then !== patchedThen) {
+	OriginalPromise.prototype.then = patchedThen as any
+	OriginalPromise.prototype.catch = patchedCatch as any
+	OriginalPromise.prototype.finally = patchedFinally as any
+}
+
+try {
+	Object.defineProperty(OriginalPromise, Symbol.species, {
+		get: () => PatchedPromise,
+		configurable: true,
+	})
+} catch (e) {}
+
+;(globalThis as any).Promise = PatchedPromise
+
 globalThis.setTimeout = ((callback: Function, ...args: any[]) => {
 	return originals.setTimeout.call(globalThis, wrap(callback as any), ...args)
 }) as any
@@ -69,7 +305,7 @@ globalThis.setInterval = ((callback: Function, ...args: any[]) => {
 }) as any
 
 if (originals.setImmediate) {
-	globalThis.setImmediate = ((callback: Function, ...args: any[]) => {
+	;(globalThis as any).setImmediate = ((callback: Function, ...args: any[]) => {
 		return originals.setImmediate.call(globalThis, wrap(callback as any), ...args)
 	}) as any
 }
@@ -84,4 +320,4 @@ if (originals.queueMicrotask) {
 	globalThis.queueMicrotask = (callback: VoidFunction): void => {
 		originals.queueMicrotask.call(globalThis, wrap(callback))
 	}
-}
+}

package/src/async/index.ts

@@ -1,8 +1,27 @@
 export type Restorer = () => () => void
 export type Hook = () => Restorer
 
+// Queue for hooks registered before the environment is ready (circular dependency fix)
+export const hooks = new Set<Hook>()
+
 export const asyncHooks = {
-	addHook(_hook: Hook): () => void {
-		throw 'One must import the library from the server or the client side'
-	}
-}
+	addHook(hook: Hook): () => void {
+		hooks.add(hook)
+		return () => hooks.delete(hook)
+	},
+	/**
+	 * [Hack] Sanitize a promise (or value) to prevent context leaks.
+	 * Default: Identity function.
+	 * Browser: Uses Macrotask wrapping to break microtask chains.
+	 */
+	sanitizePromise(p: any): any {
+		return p
+	},
+}
+
+/**
+ * Register a hook that will be called whenever an asynchronous operation is initiated.
+ * The hook should return a restorer function which will be called just before the async callback runs.
+ * That restorer should in turn return an undoer function which will be called just after the async callback finishes.
+ */
+export const asyncHook = (hook: Hook) => asyncHooks.addHook(hook)

package/src/async/node.ts

@@ -1,46 +1,92 @@
 import { createHook } from 'node:async_hooks'
-import { Hook, Restorer, asyncHooks } from '.'
+import { hooks, type Restorer } from '.'
 
-const hooks = new Set<Hook>()
-const restorersPerAsyncId = new Map<number, Set<Restorer>>()
-const undoersPerAsyncId = new Map<number, Set<() => void>>()
+// 1. Generic async_hooks implementation for Hooks
+// This maintains support for 'asyncHooks.addHook' for generic use cases.
 
-createHook({
-	init(asyncId) {
-		const restorers = new Set<Restorer>()
-		for (const hook of hooks) {
-			restorers.add(hook())
+const contexts = new Map<number, Restorer[]>()
+const activeUndoers = new Map<number, (() => void)[]>()
+
+// Helper to capture current hooks state
+function captureRestorers() {
+	if (hooks.size === 0) return []
+	const restorers: Restorer[] = []
+	for (const h of hooks) {
+		const r = h()
+		if (r) restorers.push(r)
+	}
+	return restorers
+}
+
+// Manual Wrap function to handle Promise callbacks
+function wrap<Args extends any[], R>(fn: ((...args: Args) => R) | null | undefined) {
+	if (typeof fn !== 'function') return fn
+	const restorers = captureRestorers()
+	if (restorers.length === 0) return fn
+
+	return function (this: any, ...args: Args) {
+		const undoers: (() => void)[] = []
+		for (const restore of restorers) {
+			const u = restore()
+			if (u) undoers.push(u)
+		}
+		try {
+			return fn.apply(this, args)
+		} finally {
+			for (let i = undoers.length - 1; i >= 0; i--) undoers[i]()
 		}
-		restorersPerAsyncId.set(asyncId, restorers)
+	}
+}
+
+const hook = createHook({
+	init(asyncId, _type, _triggerId, _resource) {
+		// Used for native resources like Timers
+		const restorers = captureRestorers()
+		if (restorers.length > 0) contexts.set(asyncId, restorers)
 	},
 	before(asyncId) {
-		const restorers = restorersPerAsyncId.get(asyncId)
-		if (restorers) {
-			const undoers = new Set<() => void>()
-			for (const restore of restorers) {
-				undoers.add(restore())
-			}
-			undoersPerAsyncId.set(asyncId, undoers)
+		const restorers = contexts.get(asyncId)
+		if (!restorers) return
+		const undoers: (() => void)[] = []
+		for (const restore of restorers) {
+			const u = restore()
+			if (u) undoers.push(u)
 		}
+		if (undoers.length > 0) activeUndoers.set(asyncId, undoers)
 	},
 	after(asyncId) {
-		const undoers = undoersPerAsyncId.get(asyncId)
-		if (undoers) {
-			for (const undo of undoers) undo()
-			undoersPerAsyncId.delete(asyncId)
-		}
+		const undoers = activeUndoers.get(asyncId)
+		if (!undoers) return
+		for (let i = undoers.length - 1; i >= 0; i--) undoers[i]()
+		activeUndoers.delete(asyncId)
 	},
 	destroy(asyncId) {
-		restorersPerAsyncId.delete(asyncId)
-		undoersPerAsyncId.delete(asyncId)
-	}
-}).enable()
+		contexts.delete(asyncId)
+		activeUndoers.delete(asyncId)
+	},
+})
+hook.enable()
 
-asyncHooks.addHook = function (hook: Hook) {
-	hooks.add(hook)
-	return () => {
-		hooks.delete(hook)
-	}
+// 2. Shadow Promise Implementation
+// Ensures V8 await resumptions are visible as .then callbacks, wrapping them to restore context.
+
+const OriginalPromise = globalThis.Promise
+const originalMethods = {
+	then: OriginalPromise.prototype.then,
+	catch: OriginalPromise.prototype.catch,
+	finally: OriginalPromise.prototype.finally,
+	resolve: OriginalPromise.resolve,
+	reject: OriginalPromise.reject,
+	all: OriginalPromise.all,
 }
 
-export * from '../index'
+// Patch prototype
+OriginalPromise.prototype.then = function (onFulfilled, onRejected) {
+	return originalMethods.then.call(this, wrap(onFulfilled), wrap(onRejected))
+} as any
+OriginalPromise.prototype.catch = function (onRejected) {
+	return originalMethods.catch.call(this, wrap(onRejected))
+} as any
+OriginalPromise.prototype.finally = function (onFinally) {
+	return originalMethods.finally.call(this, wrap(onFinally))
+} as any

package/src/entry-browser.ts

@@ -0,0 +1,5 @@
+// Import environment-specific patches first (SIDE EFFECTS)
+import './async/browser'
+
+// Then export the library
+export * from './index'

package/src/entry-node.ts

@@ -0,0 +1,5 @@
+// Import environment-specific patches first (SIDE EFFECTS)
+import './async/node'
+
+// Then export the library
+export * from './index'

package/src/eventful.ts

@@ -2,76 +2,109 @@
  * 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)
-		}
-	}
+const events = Symbol('events')
+const hooks = Symbol('hooks')
 
-	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]
+const eventBehavior = {
+	on<EventType extends keyof EventsBase>(
+		eventOrEvents: EventType | Partial<EventsBase>,
+		cb?: EventsBase[EventType]
 	): () => void {
 		if (typeof eventOrEvents === 'object') {
-			for (const e of Object.keys(eventOrEvents) as (keyof Events)[]) {
+			for (const e of Object.keys(eventOrEvents) as (keyof EventsBase)[]) {
 				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)
+			const callbacks = this[events].get(eventOrEvents) ?? new Set<EventsBase[EventType]>()
+			if (!callbacks.has(cb)) callbacks.add(cb)
+			this[events].set(eventOrEvents, callbacks)
 		}
-		// @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]
+	},
+	off<EventType extends keyof EventsBase>(
+		eventOrEvents: EventType | Partial<EventsBase>,
+		cb?: EventsBase[EventType]
 	): void {
 		if (typeof eventOrEvents === 'object') {
-			for (const e of Object.keys(eventOrEvents) as (keyof Events)[]) {
+			for (const e of Object.keys(eventOrEvents) as (keyof EventsBase)[]) {
 				this.off(e, eventOrEvents[e])
 			}
 		} else if (cb !== null && cb !== undefined) {
-			const callbacks = this.#events.get(eventOrEvents)
+			const callbacks = this[events].get(eventOrEvents)
 			if (callbacks) {
-				this.#events.set(
-					eventOrEvents,
-					callbacks.filter((c) => c !== cb)
-				)
+				callbacks.delete(cb)
+				if (!callbacks.size) this[events].delete(eventOrEvents)
 			}
 		} else {
 			// Remove all listeners for this event
-			this.#events.delete(eventOrEvents)
+			this[events].delete(eventOrEvents)
 		}
-	}
-	public emit<EventType extends keyof Events>(
+	},
+	emit<EventType extends keyof EventsBase>(
 		event: EventType,
-		...args: Parameters<Events[EventType]>
+		...args: Parameters<EventsBase[EventType]>
 	) {
-		const callbacks = this.#events.get(event)
+		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)
+		for (const cb of this[hooks]) cb.call(this, event, ...args)
+	},
+}
+
+function perEvent(
+	eventful: Eventful<any>,
+	fct: (event: string, ...args: any[]) => void,
+	use?: 'use'
+) {
+	const cache = new Map<string, (...args: any[]) => any>()
+	return new Proxy(fct, {
+		get(target, prop: PropertyKey) {
+			if (typeof prop !== 'string') return target[prop]
+			if (use && !eventful[events].has(prop) && !eventful[hooks].size) return () => {}
+
+			// Return cached function or create and cache
+			let cached = cache.get(prop)
+			if (!cached) {
+				cached = (...args: any[]) => fct.apply(eventful, [prop, ...args])
+				cache.set(prop, cached)
+			}
+			return cached
+		},
+	})
+}
+
+/**
+ * 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> {
+	private readonly [events] = new Map<keyof Events, Set<(...args: any[]) => void>>()
+	private readonly [hooks] = new Set<(...args: any[]) => void>()
+
+	public hook(
+		cb: <EventType extends keyof Events>(
+			event: EventType,
+			...args: Parameters<Events[EventType]>
+		) => void
+	): () => void {
+		this[hooks].add(cb)
+		return () => {
+			this[hooks].delete(cb)
+		}
 	}
+
+	public on = perEvent(this, eventBehavior.on) as ((events: Partial<Events>) => void) &
+		(<EventType extends keyof Events>(event: EventType, cb: Events[EventType]) => () => void) & {
+			[event in keyof Events]: (cb: Events[event]) => () => void
+		}
+	public off = perEvent(this, eventBehavior.off) as ((events: Partial<Events>) => void) &
+		(<EventType extends keyof Events>(event: EventType, cb?: Events[EventType]) => void) & {
+			[event in keyof Events]: (cb?: Events[event]) => void
+		}
+
+	public emit = perEvent(this, eventBehavior.emit, 'use') as (<EventType extends keyof Events>(
+		event: EventType,
+		...args: Parameters<Events[EventType]>
+	) => void) &
+		Events
 }