mutts 1.0.7 → 1.0.9

package/src/flavored.ts

@@ -0,0 +1,106 @@
+/**
+ * Creates a flavored (extensible) version of a function with chainable property modifiers.
+ *
+ * Each property defined in `flavors` returns a new flavored function that transforms
+ * how the original function is called. This enables a fluent API where properties
+ * create specialized variants of the base function.
+ *
+ * @param fn - The base function to flavor
+ * @param flavors - Object defining the flavor properties (getters or methods)
+ * @returns A proxy of the function with the flavor properties attached
+ *
+ * @example
+ * ```typescript
+ * function greet(name: string, options?: { loud?: boolean }) {
+ *   const greeting = `Hello, ${name}!`
+ *   return options?.loud ? greeting.toUpperCase() : greeting
+ * }
+ *
+ * const flavoredGreet = flavored(greet, {
+ *   get loud() {
+ *     return createFlavor(this, (name, opts) => [name, { ...opts, loud: true }])
+ *   }
+ * })
+ *
+ * flavoredGreet('World') // "Hello, World!"
+ * flavoredGreet.loud('World') // "HELLO, WORLD!"
+ * ```
+ */
+import { named } from './utils'
+
+/**
+ * Creates a flavored (extensible) version of a function with chainable property modifiers.
+ */
+export function flavored<T extends (...args: any[]) => any, F extends Record<string, any>>(
+	fn: T,
+	flavors: F
+): T & F {
+	// Store flavors for recursive flavoring
+	;(fn as any).flavors = flavors
+
+	return new Proxy(fn, {
+		get(target, prop, receiver) {
+			if (prop in flavors) {
+				return Reflect.get(flavors, prop, receiver)
+			}
+			return (target as any)[prop]
+		},
+	}) as T & F
+}
+
+/**
+ * Creates a new flavored function that transforms arguments before calling the base.
+ *
+ * @param fn - The base flavored function
+ * @param transform - Function that receives the original arguments and returns transformed arguments
+ * @returns A new flavored function with the transformation applied
+ *
+ * @example
+ * ```typescript
+ * const loudGreet = createFlavor(greet, (name, opts) => [name, { ...opts, loud: true }])
+ * ```
+ */
+export function createFlavor<T extends (...args: any[]) => any>(
+	fn: T,
+	transform: (...args: Parameters<T>) => Parameters<T>,
+	name?: string
+): T {
+	const fct = function flavorWrapper(this: any, ...args: Parameters<T>) {
+		return fn.apply(this, transform(...args))
+	}
+	if (name) named(name, fct)
+
+	return flavored(fct as any as T, (fn as any).flavors || {})
+}
+
+/**
+ * Creates a new flavored function that merges options objects.
+ * Useful when the last argument is an options object that should be merged.
+ *
+ * @param fn - The base flavored function
+ * @param defaultOptions - Options to merge with the provided options
+ * @returns A new flavored function with merged options
+ *
+ * @example
+ * ```typescript
+ * const opaqueEffect = flavorOptions(effect, { opaque: true })
+ * const namedEffect = flavorOptions(effect, { name: 'myEffect' })
+ * ```
+ */
+export function flavorOptions<T extends (...args: any[]) => any>(
+	fn: T,
+	defaultOptions: Record<string, any>,
+	name?: string
+): T {
+	const fct = function flavorOptionsWrapper(this: any, ...args: any[]) {
+		const lastArg = args[args.length - 1]
+		const mergedArgs =
+			lastArg !== undefined && typeof lastArg === 'object'
+				? [...args.slice(0, -1), { ...defaultOptions, ...lastArg }]
+				: [...args, defaultOptions]
+		return fn.apply(this, mergedArgs)
+	}
+	if (name) named(name, fct)
+
+	return flavored(fct as any as T, (fn as any).flavors || {})
+}

package/src/index.d.ts

@@ -1,9 +1,12 @@
-// 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[]
-}
+export * from './decorator'
+export * from './destroyable'
+export * from './eventful'
+export * from './indexable'
+export * from './iterableWeak'
+export * from './mixins'
+export * from './promiseChain'
+export * from './reactive'
+export * from './std-decorators'
+export * from './utils'
+export * from './zone'
+export * from './async'

package/src/index.ts

@@ -1,6 +1,8 @@
+export * from './async'
 export * from './decorator'
 export * from './destroyable'
 export * from './eventful'
+export * from './flavored'
 export * from './indexable'
 export * from './iterableWeak'
 export * from './mixins'
@@ -30,7 +32,6 @@ if (globalScope) {
 	let source = 'mutts/index'
 	const viteEval = eval
 	try {
-		// @ts-ignore
 		if (typeof __filename !== 'undefined') source = __filename
 		else {
 			// Using eval to avoid SyntaxError in CJS environments where import.meta is not allowed

package/src/introspection.ts

@@ -14,7 +14,7 @@ import {
 	type MutationRecord,
 	type ObjectNode,
 	type ReactivityGraph,
-} from './reactive/debug'
+} from '../debug/debug'
 import { options, type ReactiveDebugInfo, ReactiveErrorCode } from './reactive/types'
 
 export {

package/src/reactive/array.ts

@@ -25,29 +25,18 @@ export abstract class Indexer extends Array {
 		dependant(this, i)
 		return reactive(this[i])
 	}
+	// Returns undefined intentionally: signals the proxy handler that notifications
+	// were already dispatched via touched(), preventing double notification
 	set(i: number, value: any) {
 		const added = i >= this.length
 		this[i] = value
 		touched(this, { type: 'set', prop: i }, index(i, { length: added }))
 	}
-	getLength() {
-		dependant(this, 'length')
-		return this.length
-	}
-	setLength(value: number) {
-		const oldLength = this.length
-		try {
-			this.length = value
-		} finally {
-			touched(this, { type: 'set', prop: 'length' }, range(oldLength, value, { length: true }))
-		}
-	}
 }
 const indexLess = { get: FoolProof.get, set: FoolProof.set }
 Object.assign(FoolProof, {
 	get(obj: any, prop: any, receiver: any) {
 		if (obj instanceof Array && typeof prop === 'string') {
-			if (prop === 'length') return Indexer.prototype.getLength.call(obj)
 			const index = parseInt(prop)
 			if (!Number.isNaN(index)) return Indexer.prototype.get.call(obj, index)
 		}
@@ -55,7 +44,6 @@ Object.assign(FoolProof, {
 	},
 	set(obj: any, prop: any, value: any, receiver: any) {
 		if (obj instanceof Array && typeof prop === 'string') {
-			if (prop === 'length') return Indexer.prototype.setLength.call(obj, value)
 			const index = parseInt(prop)
 			if (!Number.isNaN(index)) return Indexer.prototype.set.call(obj, index, value)
 		}
@@ -67,13 +55,24 @@ export abstract class ReactiveArray extends Array {
 	toJSON() {
 		return this
 	}
-	get [Symbol.toStringTag]() {
-		return 'ReactiveArray'
+	get length(): number {
+		dependant(this, 'length')
+		return this.length
+	}
+	set length(value: number) {
+		const oldLength = this.length
+		if (oldLength === value) return
+		try {
+			this.length = value
+		} finally {
+			touched(this, { type: 'set', prop: 'length' }, range(oldLength, value, { length: true }))
+		}
 	}
 	// Safe array access with negative indices
 	at(index: number): any {
 		const actualIndex = index < 0 ? this.length + index : index
 		dependant(this, actualIndex)
+		if (index < 0) dependant(this, 'length')
 		if (actualIndex < 0 || actualIndex >= this.length) return undefined
 		return reactive(this[actualIndex])
 	}
@@ -102,17 +101,17 @@ export abstract class ReactiveArray extends Array {
 	}
 
 	// Iterator methods with reactivity tracking
-	entries() {
+	entries(): any {
 		dependant(this)
 		return makeReactiveEntriesIterator(this.entries())
 	}
 
-	keys() {
+	keys(): any {
 		dependant(this, 'length')
 		return this.keys()
 	}
 
-	values() {
+	values(): any {
 		dependant(this)
 		return makeReactiveIterator(this.values())
 	}
@@ -136,36 +135,57 @@ export abstract class ReactiveArray extends Array {
 	}
 
 	indexOf(searchElement: any, fromIndex?: number): number {
-		dependant(this)
+		const length = this.length
+		let i = fromIndex === undefined ? 0 : fromIndex
+		if (i < 0) i = Math.max(length + i, 0)
+
 		const unwrappedSearch = unwrap(searchElement)
-		// Check both wrapped and unwrapped versions since array may contain either
-		const index = this.indexOf(unwrappedSearch, fromIndex)
-		if (index !== -1) return index
-		// If not found with unwrapped, try with wrapped (in case array contains wrapped version)
-		return this.indexOf(searchElement, fromIndex)
+
+		for (; i < length; i++) {
+			dependant(this, i)
+			const item = this[i]
+			if (item === searchElement || item === unwrappedSearch || unwrap(item) === unwrappedSearch) {
+				return i
+			}
+		}
+
+		dependant(this, 'length')
+		return -1
 	}
 
 	lastIndexOf(searchElement: any, fromIndex?: number): number {
-		dependant(this)
+		const length = this.length
+		let i = fromIndex === undefined ? length - 1 : fromIndex
+		if (i >= length) i = length - 1
+		if (i < 0) i = Math.max(length + i, -1) // -1 ensures loop condition i >= 0 works correctly
+
 		const unwrappedSearch = unwrap(searchElement)
-		// Check both wrapped and unwrapped versions since array may contain either
-		const index = this.lastIndexOf(unwrappedSearch, fromIndex)
-		if (index !== -1) return index
-		// If not found with unwrapped, try with wrapped (in case array contains wrapped version)
-		return this.lastIndexOf(searchElement, fromIndex)
+
+		for (; i >= 0; i--) {
+			dependant(this, i)
+			const item = this[i]
+			if (item === searchElement || item === unwrappedSearch || unwrap(item) === unwrappedSearch) {
+				return i
+			}
+		}
+
+		// If we scanned the whole relevant part and didn't find it, we depend on length
+		// (because adding elements might shift indices or add the element)
+		// Actually for lastIndexOf, if we start from end, length dependency is implicit in the start index calculation?
+		// But if we return -1, it means we didn't find it.
+		// If we push an element, should lastIndexOf update?
+		// Yes, if the new element is the one we are looking for.
+		dependant(this, 'length')
+		return -1
 	}
 
 	includes(searchElement: any, fromIndex?: number): boolean {
-		dependant(this)
-		const unwrappedSearch = unwrap(searchElement)
-		// Check both wrapped and unwrapped versions since array may contain either
-		return this.includes(unwrappedSearch, fromIndex) || this.includes(searchElement, fromIndex)
+		return this.indexOf(searchElement, fromIndex) !== -1
 	}
 
 	find(predicate: (this: any, value: any, index: number, obj: any[]) => boolean, thisArg?: any): any
 	find(searchElement: any, fromIndex?: number): any
 	find(predicateOrElement: any, thisArg?: any): any {
-		dependant(this)
 		if (typeof predicateOrElement === 'function') {
 			const predicate = predicateOrElement as (
 				this: any,
@@ -173,12 +193,18 @@ export abstract class ReactiveArray extends Array {
 				index: number,
 				obj: any[]
 			) => boolean
-			return reactive(
-				this.find(
-					(value, index, array) => predicate.call(thisArg, reactive(value), index, array),
-					thisArg
-				)
-			)
+			const length = this.length
+
+			for (let i = 0; i < length; i++) {
+				dependant(this, i)
+				const val = reactive(this[i])
+				if (predicate.call(thisArg, val, i, this)) {
+					return val
+				}
+			}
+
+			dependant(this, 'length')
+			return undefined
 		}
 		const fromIndex = typeof thisArg === 'number' ? thisArg : undefined
 		const index = this.indexOf(predicateOrElement, fromIndex)
@@ -192,7 +218,6 @@ export abstract class ReactiveArray extends Array {
 	): number
 	findIndex(searchElement: any, fromIndex?: number): number
 	findIndex(predicateOrElement: any, thisArg?: any): number {
-		dependant(this)
 		if (typeof predicateOrElement === 'function') {
 			const predicate = predicateOrElement as (
 				this: any,
@@ -200,10 +225,18 @@ export abstract class ReactiveArray extends Array {
 				index: number,
 				obj: any[]
 			) => boolean
-			return this.findIndex(
-				(value, index, array) => predicate.call(thisArg, reactive(value), index, array),
-				thisArg
-			)
+			const length = this.length
+
+			for (let i = 0; i < length; i++) {
+				dependant(this, i)
+				const val = reactive(this[i])
+				if (predicate.call(thisArg, val, i, this)) {
+					return i
+				}
+			}
+
+			dependant(this, 'length')
+			return -1
 		}
 		const fromIndex = typeof thisArg === 'number' ? thisArg : undefined
 		return this.indexOf(predicateOrElement, fromIndex)
@@ -291,7 +324,6 @@ export abstract class ReactiveArray extends Array {
 		})
 	}
 
-	// TODO: re-implement for fun dependencies? (eg - every only check the first ones until it find some),
 	// no need to make it dependant on indexes after the found one
 	every<S>(
 		predicate: (value: any, index: number, array: any[]) => value is S,
@@ -299,21 +331,34 @@ export abstract class ReactiveArray extends Array {
 	): this is S[]
 	every(callbackfn: (value: any, index: number, array: any[]) => boolean, thisArg?: any): boolean
 	every(callbackfn: (value: any, index: number, array: any[]) => boolean, thisArg?: any): boolean {
-		dependant(this)
-		return this.every(
-			(value, index, array) => callbackfn.call(thisArg, reactive(value), index, array),
-			thisArg
-		)
+		const length = this.length
+
+		for (let i = 0; i < length; i++) {
+			dependant(this, i)
+			if (!callbackfn.call(thisArg, reactive(this[i]), i, this)) {
+				return false
+			}
+		}
+
+		dependant(this, 'length')
+		return true
 	}
+
 	some(callbackfn: (value: any, index: number, array: any[]) => boolean, thisArg?: any): boolean {
-		dependant(this)
-		return this.some(
-			(value, index, array) => callbackfn.call(thisArg, reactive(value), index, array),
-			thisArg
-		)
+		const length = this.length
+
+		for (let i = 0; i < length; i++) {
+			dependant(this, i)
+			if (callbackfn.call(thisArg, reactive(this[i]), i, this)) {
+				return true
+			}
+		}
+
+		dependant(this, 'length')
+		return false
 	}
 	// Side-effectful
-	push(...items: any[]) {
+	push(...items: any[]): number {
 		const oldLength = this.length
 		try {
 			return this.push(...items)
@@ -326,7 +371,7 @@ export abstract class ReactiveArray extends Array {
 		}
 	}
 
-	pop() {
+	pop(): any {
 		if (this.length === 0) return undefined
 		try {
 			return reactive(this.pop())
@@ -335,7 +380,7 @@ export abstract class ReactiveArray extends Array {
 		}
 	}
 
-	shift() {
+	shift(): any {
 		if (this.length === 0) return undefined
 		try {
 			return reactive(this.shift())
@@ -344,7 +389,7 @@ export abstract class ReactiveArray extends Array {
 		}
 	}
 
-	unshift(...items: any[]) {
+	unshift(...items: any[]): number {
 		try {
 			return this.unshift(...items)
 		} finally {
@@ -356,9 +401,22 @@ export abstract class ReactiveArray extends Array {
 		}
 	}
 
-	splice(start: number, deleteCount?: number, ...items: any[]) {
+	splice(start: number, deleteCount?: number, ...items: any[]): any[] {
 		const oldLength = this.length
-		if (deleteCount === undefined) deleteCount = oldLength - start
+
+		// Normalize start index
+		let actualStart = start
+		if (actualStart < 0) actualStart = Math.max(oldLength + actualStart, 0)
+		else actualStart = Math.min(actualStart, oldLength)
+
+		// Normalize deleteCount
+		let actualDeleteCount = deleteCount
+		if (actualDeleteCount === undefined) {
+			actualDeleteCount = oldLength - actualStart
+		} else {
+			actualDeleteCount = Math.max(0, Math.min(actualDeleteCount, oldLength - actualStart))
+		}
+
 		try {
 			if (deleteCount === undefined) return reactive(this.splice(start))
 			return reactive(this.splice(start, deleteCount, ...items))
@@ -366,17 +424,16 @@ export abstract class ReactiveArray extends Array {
 			touched(
 				this,
 				{ type: 'bunch', method: 'splice' },
-				// TODO: edge cases
-				deleteCount === items.length
-					? range(start, start + deleteCount)
-					: range(start, oldLength + Math.max(items.length - deleteCount, 0), {
+				actualDeleteCount === items.length
+					? range(actualStart, actualStart + actualDeleteCount - 1)
+					: range(actualStart, oldLength + Math.max(items.length - actualDeleteCount, 0), {
 							length: true,
 						})
 			)
 		}
 	}
 
-	reverse() {
+	reverse(): any[] {
 		try {
 			return this.reverse()
 		} finally {
@@ -384,7 +441,7 @@ export abstract class ReactiveArray extends Array {
 		}
 	}
 
-	sort(compareFn?: (a: any, b: any) => number) {
+	sort(compareFn?: (a: any, b: any) => number): this {
 		compareFn = compareFn || ((a, b) => a.toString().localeCompare(b.toString()))
 		try {
 			return this.sort((a, b) => compareFn(reactive(a), reactive(b))) as any
@@ -393,28 +450,51 @@ export abstract class ReactiveArray extends Array {
 		}
 	}
 
-	fill(value: any, start?: number, end?: number) {
+	fill(value: any, start?: number, end?: number): this {
+		const len = this.length
+		let k = start === undefined ? 0 : start
+		if (k < 0) k = Math.max(len + k, 0)
+		else k = Math.min(k, len)
+
+		let final = end === undefined ? len : end
+		if (final < 0) final = Math.max(len + final, 0)
+		else final = Math.min(final, len)
+
 		try {
 			if (start === undefined) return this.fill(value) as any
 			if (end === undefined) return this.fill(value, start) as any
 			return this.fill(value, start, end) as any
 		} finally {
-			touched(this, { type: 'bunch', method: 'fill' }, range(0, this.length - 1))
+			if (final > k) {
+				touched(this, { type: 'bunch', method: 'fill' }, range(k, final - 1))
+			}
 		}
 	}
 
-	copyWithin(target: number, start: number, end?: number) {
+	copyWithin(target: number, start: number, end?: number): this {
 		try {
 			if (end === undefined) return this.copyWithin(target, start) as any
 			return this.copyWithin(target, start, end) as any
 		} finally {
-			touched(
-				this,
-				{ type: 'bunch', method: 'copyWithin' },
-				// TODO: calculate the range properly
-				range(0, this.length - 1)
-			)
+			const len = this.length
+
+			let to = target
+			if (to < 0) to = Math.max(len + to, 0)
+			else if (to >= len) to = len
+
+			let from = start
+			if (from < 0) from = Math.max(len + from, 0)
+			else if (from >= len) from = len
+
+			let final = end === undefined ? len : end
+			if (final < 0) final = Math.max(len + final, 0)
+			else if (final >= len) final = len
+
+			const count = Math.min(final - from, len - to)
+
+			if (count > 0) {
+				touched(this, { type: 'bunch', method: 'copyWithin' }, range(to, to + count - 1))
+			}
 		}
-		// Touch all affected indices with a single allProps call
 	}
 }