mutts 1.0.1 → 1.0.3

package/src/iterableWeak.ts

@@ -0,0 +1,233 @@
+/// <reference lib="esnext.collection" />
+
+/**
+ * Uses weak references but still may iterate through them
+ * Note: The behavior is highly dependant on the garbage collector - some entries are perhaps deemed to be collected: don't resuscitate them
+ */
+export class IterableWeakMap<K extends WeakKey, V> implements Map<K, V> {
+	private uuids = new WeakMap<K, string>()
+	private refs: Record<string, [WeakRef<K>, any]> = {}
+	private readonly registry: FinalizationRegistry<string>
+
+	constructor(entries?: Iterable<[K, V]>) {
+		// Create a FinalizationRegistry to clean up refs when keys are garbage collected
+		this.registry = new FinalizationRegistry((uuid: string) => {
+			delete this.refs[uuid]
+		})
+		if (entries) for (const [k, v] of entries) this.set(k, v)
+	}
+	private createIterator<I>(cb: (key: K, value: V) => I): MapIterator<I> {
+		const { refs } = this
+		return (function* () {
+			for (const uuid of Object.keys(refs)) {
+				const [keyRef, value] = refs[uuid]
+				const key = keyRef.deref()
+				if (key) yield cb(key, value)
+				else delete refs[uuid]
+			}
+			return undefined
+		})()
+	}
+	clear(): void {
+		// Unregister all keys from the FinalizationRegistry
+		for (const uuid of Object.keys(this.refs)) {
+			const key = this.refs[uuid][0].deref()
+			if (key) this.registry.unregister(key)
+		}
+		this.uuids = new WeakMap<K, string>()
+		this.refs = {}
+	}
+	delete(key: K): boolean {
+		const uuid = this.uuids.get(key)
+		if (!uuid) return false
+		delete this.refs[uuid]
+		this.uuids.delete(key)
+		this.registry.unregister(key)
+		return true
+	}
+	forEach(callbackfn: (value: V, key: K, map: Map<K, V>) => void, thisArg?: any): void {
+		for (const [k, v] of this) callbackfn.call(thisArg ?? this, v, k, thisArg ?? this)
+	}
+	get(key: K): V | undefined {
+		const uuid = this.uuids.get(key)
+		if (!uuid) return undefined
+		return this.refs[uuid][1]
+	}
+	has(key: K): boolean {
+		return this.uuids.has(key)
+	}
+	set(key: K, value: V): this {
+		let uuid = this.uuids.get(key)
+		if (uuid) {
+			this.refs[uuid][1] = value
+		} else {
+			uuid = crypto.randomUUID()
+			this.uuids.set(key, uuid)
+			this.refs[uuid] = [new WeakRef(key), value]
+			// Register key for cleanup when garbage collected
+			this.registry.register(key, uuid, key)
+		}
+		return this
+	}
+	get size(): number {
+		return [...this].length
+	}
+	entries(): MapIterator<[K, V]> {
+		return this.createIterator((key, value) => [key, value] as [K, V])
+	}
+	keys(): MapIterator<K> {
+		return this.createIterator((key, _value) => key)
+	}
+	values(): MapIterator<V> {
+		return this.createIterator((_key, value) => value)
+	}
+	[Symbol.iterator](): MapIterator<[K, V]> {
+		return this.entries()
+	}
+	readonly [Symbol.toStringTag]: string = 'IterableWeakMap'
+}
+
+/**
+ * Uses weak references but still may iterate through them
+ * Note: The behavior is highly dependant on the garbage collector - some entries are perhaps deemed to be collected: don't resuscitate them
+ */
+export class IterableWeakSet<K extends WeakKey> implements Set<K> {
+	private uuids = new WeakMap<K, string>()
+	private refs: Record<string, WeakRef<K>> = {}
+	private readonly registry: FinalizationRegistry<string>
+
+	constructor(entries?: Iterable<K>) {
+		// Create a FinalizationRegistry to clean up refs when values are garbage collected
+		this.registry = new FinalizationRegistry((uuid: string) => {
+			delete this.refs[uuid]
+		})
+		if (entries) for (const k of entries) this.add(k)
+	}
+	private createIterator<I>(cb: (key: K) => I): MapIterator<I> {
+		const { refs } = this
+		return (function* () {
+			for (const uuid of Object.keys(refs)) {
+				const key = refs[uuid].deref()
+				if (key) yield cb(key)
+				else delete refs[uuid]
+			}
+			return undefined
+		})()
+	}
+
+	clear(): void {
+		// Unregister all values from the FinalizationRegistry
+		for (const uuid of Object.keys(this.refs)) {
+			const value = this.refs[uuid].deref()
+			if (value) this.registry.unregister(value)
+		}
+		this.uuids = new WeakMap<K, string>()
+		this.refs = {}
+	}
+
+	add(value: K): this {
+		let uuid = this.uuids.get(value)
+		if (!uuid) {
+			uuid = crypto.randomUUID()
+			this.uuids.set(value, uuid)
+			this.refs[uuid] = new WeakRef(value)
+			// Register value for cleanup when garbage collected
+			this.registry.register(value, uuid, value)
+		}
+		return this
+	}
+	delete(value: K): boolean {
+		const uuid = this.uuids.get(value)
+		if (!uuid) return false
+		delete this.refs[uuid]
+		this.uuids.delete(value)
+		this.registry.unregister(value)
+		return true
+	}
+
+	forEach(callbackfn: (value: K, value2: K, set: Set<K>) => void, thisArg?: any): void {
+		for (const value of this) callbackfn.call(thisArg ?? this, value, value, thisArg ?? this)
+	}
+
+	has(value: K): boolean {
+		return this.uuids.has(value)
+	}
+	get size(): number {
+		return [...this].length
+	}
+	entries(): SetIterator<[K, K]> {
+		return this.createIterator((key) => [key, key] as [K, K])
+	}
+	keys(): SetIterator<K> {
+		return this.createIterator((key) => key)
+	}
+	values(): SetIterator<K> {
+		return this.createIterator((key) => key)
+	}
+	[Symbol.iterator](): SetIterator<K> {
+		return this.keys()
+	}
+	readonly [Symbol.toStringTag]: string = 'IterableWeakSet'
+
+	union<U>(other: ReadonlySetLike<U>): Set<K | U> {
+		const others = {
+			[Symbol.iterator]() {
+				return other.keys()
+			},
+		}
+		const that = this
+		return new Set(
+			(function* () {
+				yield* that
+				for (const value of others) if (!that.has(<K>(<unknown>value))) yield value
+			})()
+		)
+	}
+	intersection<U /**/>(other: ReadonlySetLike<U>): Set<K & U> {
+		const that = this
+		return new Set(
+			(function* () {
+				for (const value of that) if (other.has(<U>(<unknown>value))) yield <K & U>value
+			})()
+		)
+	}
+	difference<U>(other: ReadonlySetLike<U>): Set<K> {
+		const that = this
+		return new Set(
+			(function* () {
+				for (const value of that) if (!other.has(<U>(<unknown>value))) yield <K>value
+			})()
+		)
+	}
+	symmetricDifference<U>(other: ReadonlySetLike<U>): Set<K | U> {
+		const others = {
+			[Symbol.iterator]() {
+				return other.keys()
+			},
+		}
+		const that = this
+		return new Set(
+			(function* () {
+				for (const value of that) if (!other.has(<U>(<unknown>value))) yield <K | U>value
+				for (const value of others) if (!that.has(<K>(<unknown>value))) yield <K | U>value
+			})()
+		)
+	}
+	isSubsetOf(other: ReadonlySetLike<unknown>): boolean {
+		for (const value of this) if (!other.has(value)) return false
+		return true
+	}
+	isSupersetOf(other: ReadonlySetLike<unknown>): boolean {
+		const others = {
+			[Symbol.iterator]() {
+				return other.keys()
+			},
+		}
+		for (const value of others) if (!this.has(<K>value)) return false
+		return true
+	}
+	isDisjointFrom(other: ReadonlySetLike<unknown>): boolean {
+		for (const value of this) if (other.has(value)) return false
+		return true
+	}
+}

package/src/mixins.ts

@@ -0,0 +1,123 @@
+import { isConstructor, ReflectGet } from './utils'
+
+/**
+ * A mixin function that takes a base class and returns a new class with mixed-in functionality
+ * @template Mixed - The functionality to be mixed in
+ */
+export type MixinFunction<Mixed> = <Base>(
+	base: new (...args: any[]) => Base
+) => new (
+	...args: any[]
+) => Base & Mixed
+
+/**
+ * A mixin class that can be used both as a base class and as a mixin function
+ * @template Mixed - The functionality to be mixed in
+ */
+export type MixinClass<Mixed> = new (...args: any[]) => Mixed
+
+/**
+ * Creates a mixin that can be used both as a class (extends) and as a function (mixin)
+ *
+ * This function supports:
+ * - Using mixins as base classes: `class MyClass extends MyMixin`
+ * - Using mixins as functions: `class MyClass extends MyMixin(SomeBase)`
+ * - Composing mixins: `const Composed = MixinA(MixinB)`
+ * - Type-safe property inference for all patterns
+ *
+ * @param mixinFunction - The function that creates the mixin
+ * @param unwrapFunction - Optional function to unwrap reactive objects for method calls
+ * @returns A mixin that can be used both as a class and as a function
+ */
+export function mixin<MixinFn extends (base: any) => new (...args: any[]) => any>(
+	mixinFunction: MixinFn,
+	unwrapFunction?: (obj: any) => any
+): (new (
+	...args: any[]
+) => InstanceType<ReturnType<MixinFn>>) &
+	(<Base>(
+		base: abstract new (...args: any[]) => Base
+	) => new (
+		...args: any[]
+	) => InstanceType<ReturnType<MixinFn>> & Base) {
+	/**
+	 * Cache for mixin results to ensure the same base class always returns the same mixed class
+	 */
+	const mixinCache = new WeakMap<new (...args: any[]) => any, new (...args: any[]) => any>()
+
+	// Apply the mixin to Object as the base class
+	const MixedBase = mixinFunction(Object)
+	mixinCache.set(Object, MixedBase)
+
+	// Create the proxy that handles both constructor and function calls
+	return new Proxy(MixedBase, {
+		// Handle `MixinClass(SomeBase)` - use as mixin function
+		apply(_target, _thisArg, args) {
+			if (args.length === 0) {
+				throw new Error('Mixin requires a base class')
+			}
+
+			const baseClass = args[0]
+			if (typeof baseClass !== 'function') {
+				throw new Error('Mixin requires a constructor function')
+			}
+
+			// Check if it's a valid constructor or a mixin
+			if (
+				!isConstructor(baseClass) &&
+				!(baseClass && typeof baseClass === 'function' && baseClass.prototype)
+			) {
+				throw new Error('Mixin requires a valid constructor')
+			}
+
+			// Check cache first
+			const cached = mixinCache.get(baseClass)
+			if (cached) {
+				return cached
+			}
+
+			let usedBase = baseClass
+			if (unwrapFunction) {
+				// Create a proxied base class that handles method unwrapping
+				const ProxiedBaseClass = class extends baseClass {}
+
+				// Proxy the prototype methods to handle unwrapping
+				const originalPrototype = baseClass.prototype
+				const proxiedPrototype = new Proxy(originalPrototype, {
+					get(target, prop, receiver) {
+						const value = ReflectGet(target, prop, receiver)
+
+						// Only wrap methods that are likely to access private fields
+						// Skip symbols and special properties that the reactive system needs
+						if (
+							typeof value === 'function' &&
+							typeof prop === 'string' &&
+							!['constructor', 'toString', 'valueOf'].includes(prop)
+						) {
+							// Return a wrapped version that uses unwrapped context
+							return function (this: any, ...args: any[]) {
+								// Use the unwrapping function if provided, otherwise use this
+								const context = unwrapFunction(this as any)
+								return value.apply(context, args)
+							}
+						}
+
+						return value
+					},
+				})
+
+				// Set the proxied prototype
+				Object.setPrototypeOf(ProxiedBaseClass.prototype, proxiedPrototype)
+				usedBase = ProxiedBaseClass
+			}
+
+			// Create the mixed class using the proxied base class
+			const mixedClass = mixinFunction(usedBase)
+
+			// Cache the result
+			mixinCache.set(baseClass, mixedClass)
+
+			return mixedClass
+		},
+	}) as MixinFn & (new (...args: any[]) => InstanceType<ReturnType<MixinFn>>)
+}

package/src/promiseChain.ts

@@ -0,0 +1,110 @@
+type Resolved<T> =
+	T extends Promise<infer U>
+		? Resolved<U>
+		: T extends (...args: infer Args) => infer R
+			? (...args: Args) => Resolved<R>
+			: T extends object
+				? {
+						[k in keyof T]: k extends 'then' | 'catch' | 'finally' ? T[k] : Resolved<T[k]>
+					}
+				: T
+type PromiseAnd<T> = Resolved<T> & Promise<Resolved<T>>
+/**
+ * Type that transforms promises into chainable objects
+ * Allows calling methods directly on promise results without awaiting them first
+ */
+export type PromiseChain<T> = T extends (...args: infer Args) => infer R
+	? PromiseAnd<(...args: Args) => PromiseChain<Resolved<R>>>
+	: T extends object
+		? PromiseAnd<{
+				[k in keyof T]: k extends 'then' | 'catch' | 'finally' ? T[k] : PromiseChain<Resolved<T[k]>>
+			}>
+		: Promise<Resolved<T>>
+
+const forward =
+	(name: string, target: any) =>
+	(...args: any[]) => {
+		return target[name](...args)
+	}
+
+const alreadyChained = new WeakMap<any, PromiseChain<any>>()
+const originals = new WeakMap<Promise<any>, any>()
+
+function cache(target: any, rv: PromiseChain<any>) {
+	originals.set(rv, target)
+	alreadyChained.set(target, rv)
+}
+
+type ChainedFunction<T> = ((...args: any[]) => PromiseChain<T>) & {
+	then: Promise<T>['then']
+	catch: Promise<T>['catch']
+	finally: Promise<T>['finally']
+}
+
+const promiseProxyHandler: ProxyHandler<ChainedFunction<any>> = {
+	//@ts-expect-error
+	[Symbol.toStringTag]: 'MutTs PromiseChain function',
+	get(target, prop) {
+		if (prop === Symbol.toStringTag) return 'PromiseProxy'
+		if (typeof prop === 'string' && ['then', 'catch', 'finally'].includes(prop))
+			return target[prop as keyof typeof target]
+		return chainPromise(target.then((r) => r[prop as keyof typeof r]))
+	},
+}
+const promiseForward = (target: any) => ({
+	// biome-ignore lint/suspicious/noThenProperty: This one is the whole point
+	then: forward('then', target),
+	catch: forward('catch', target),
+	finally: forward('finally', target),
+})
+const objectProxyHandler: ProxyHandler<any> = {
+	//@ts-expect-error
+	[Symbol.toStringTag]: 'MutTs PromiseChain object',
+	get(target, prop, receiver) {
+		const getter = Object.getOwnPropertyDescriptor(target, prop)?.get
+		const rv = getter ? getter.call(receiver) : target[prop]
+		// Allows fct.call or fct.apply to bypass the chain system
+		if (typeof target === 'function') return rv
+		return chainPromise(rv)
+	},
+	apply(target, thisArg, args) {
+		return chainPromise(target.apply(thisArg, args))
+	},
+}
+function chainObject<T extends object | Function>(given: T): PromiseChain<T> {
+	const rv = new Proxy(given, objectProxyHandler) as PromiseChain<T>
+	cache(given, rv)
+	return rv
+}
+
+function chainable(x: any): x is object | Function {
+	return x && ['function', 'object'].includes(typeof x)
+}
+/**
+ * Transforms a promise or value into a chainable object
+ * Allows calling methods directly on promise results without awaiting them first
+ * @param given - The promise or value to make chainable
+ * @returns A chainable version of the input
+ */
+export function chainPromise<T>(given: Promise<T> | T): PromiseChain<T> {
+	if (!chainable(given)) return given as PromiseChain<T>
+	if (alreadyChained.has(given)) return alreadyChained.get(given) as PromiseChain<T>
+	if (!(given instanceof Promise)) return chainObject(given)
+	// @ts-expect-error It's ok as we check if it's an object above
+	given = given.then((r) => (chainable(r) ? chainObject(r) : r))
+	const target = Object.assign(function (this: any, ...args: any[]) {
+		return chainPromise(
+			given.then((r) => {
+				return this?.then
+					? this.then((t: any) => (r as any).apply(t, args))
+					: (r as any).apply(this, args)
+			})
+		)
+	}, promiseForward(given)) as ChainedFunction<T>
+	const chained = new Proxy(
+		target,
+		promiseProxyHandler as ProxyHandler<ChainedFunction<T>>
+	) as PromiseChain<T>
+	cache(given, chained as PromiseChain<any>)
+	return chained
+}