@zeix/cause-effect 0.15.0 → 0.15.1

package/test/signal.test.ts

@@ -0,0 +1,451 @@
+import { describe, expect, test } from 'bun:test'
+import {
+	type Computed,
+	computed,
+	isComputed,
+	isState,
+	isStore,
+	type Signal,
+	type State,
+	type Store,
+	state,
+	store,
+	toMutableSignal,
+	toSignal,
+	type UnknownRecord,
+} from '..'
+
+/* === Tests === */
+
+describe('toSignal', () => {
+	describe('type inference and runtime behavior', () => {
+		test('converts array to Store<Record<string, T>>', () => {
+			const arr = [
+				{ id: 1, name: 'Alice' },
+				{ id: 2, name: 'Bob' },
+			]
+			const result = toSignal(arr)
+
+			// Runtime behavior
+			expect(isStore(result)).toBe(true)
+			expect(result['0'].get()).toEqual({ id: 1, name: 'Alice' })
+			expect(result['1'].get()).toEqual({ id: 2, name: 'Bob' })
+
+			// Type inference test - now correctly returns Store<Record<string, {id: number, name: string}>>
+			const typedResult: Store<
+				Record<string, { id: number; name: string }>
+			> = result
+			expect(typedResult).toBeDefined()
+		})
+
+		test('converts empty array to Store<Record<string, never>>', () => {
+			const arr: never[] = []
+			const result = toSignal(arr)
+
+			// Runtime behavior
+			expect(isStore(result)).toBe(true)
+			expect(Object.keys(result).length).toBe(0)
+		})
+
+		test('converts record to Store<T>', () => {
+			const record = { name: 'Alice', age: 30 }
+			const result = toSignal(record)
+
+			// Runtime behavior
+			expect(isStore(result)).toBe(true)
+			expect(result.name.get()).toBe('Alice')
+			expect(result.age.get()).toBe(30)
+
+			// Type inference test - should be Store<{name: string, age: number}>
+			const typedResult: Store<{ name: string; age: number }> = result
+			expect(typedResult).toBeDefined()
+		})
+
+		test('passes through existing Store unchanged', () => {
+			const originalStore = store({ count: 5 })
+			const result = toSignal(originalStore)
+
+			// Runtime behavior
+			expect(result).toBe(originalStore) // Should be the same instance
+			expect(isStore(result)).toBe(true)
+			expect(result.count.get()).toBe(5)
+
+			// Type inference test - should remain Store<{count: number}>
+			const typedResult: Store<{ count: number }> = result
+			expect(typedResult).toBeDefined()
+		})
+
+		test('passes through existing State unchanged', () => {
+			const originalState = state(42)
+			const result = toSignal(originalState)
+
+			// Runtime behavior
+			expect(result).toBe(originalState) // Should be the same instance
+			expect(isState(result)).toBe(true)
+			expect(result.get()).toBe(42)
+
+			// Type inference test - should remain State<number>
+			const typedResult: State<number> = result
+			expect(typedResult).toBeDefined()
+		})
+
+		test('passes through existing Computed unchanged', () => {
+			const originalComputed = computed(() => 'hello world')
+			const result = toSignal(originalComputed)
+
+			// Runtime behavior
+			expect(result).toBe(originalComputed) // Should be the same instance
+			expect(isComputed(result)).toBe(true)
+			expect(result.get()).toBe('hello world')
+
+			// Type inference test - should remain Computed<string>
+			const typedResult: Computed<string> = result
+			expect(typedResult).toBeDefined()
+		})
+
+		test('converts function to Computed<T>', () => {
+			const fn = () => Math.random()
+			const result = toSignal(fn)
+
+			// Runtime behavior - functions are correctly converted to Computed
+			expect(isComputed(result)).toBe(true)
+			expect(typeof result.get()).toBe('number')
+
+			// Type inference test - should be Computed<number>
+			const typedResult: Computed<number> = result
+			expect(typedResult).toBeDefined()
+		})
+
+		test('converts primitive to State<T>', () => {
+			const num = 42
+			const result = toSignal(num)
+
+			// Runtime behavior - primitives are correctly converted to State
+			expect(isState(result)).toBe(true)
+			expect(result.get()).toBe(42)
+
+			// Type inference test - should be State<number>
+			const typedResult: State<number> = result
+			expect(typedResult).toBeDefined()
+		})
+
+		test('converts object to State<T>', () => {
+			const obj = new Date('2024-01-01')
+			const result = toSignal(obj)
+
+			// Runtime behavior - objects are correctly converted to State
+			expect(isState(result)).toBe(true)
+			expect(result.get()).toBe(obj)
+
+			// Type inference test - should be State<Date>
+			const typedResult: State<Date> = result
+			expect(typedResult).toBeDefined()
+		})
+	})
+
+	describe('edge cases', () => {
+		test('handles nested arrays', () => {
+			const nestedArr = [
+				[1, 2],
+				[3, 4],
+			]
+			const result = toSignal(nestedArr)
+
+			expect(isStore(result)).toBe(true)
+			// With the fixed behavior, nested arrays should be recovered as arrays
+			const firstElement = result[0].get()
+			const secondElement = result[1].get()
+
+			// The expected behavior - nested arrays are recovered as arrays
+			expect(firstElement).toEqual([1, 2])
+			expect(secondElement).toEqual([3, 4])
+		})
+
+		test('handles arrays with mixed types', () => {
+			const mixedArr = [1, 'hello', { key: 'value' }]
+			const result = toSignal(mixedArr)
+
+			expect(isStore(result)).toBe(true)
+			expect(result['0'].get()).toBe(1)
+			expect(result['1'].get()).toBe('hello')
+			expect(result['2'].get()).toEqual({ key: 'value' })
+		})
+
+		test('handles sparse arrays', () => {
+			const sparseArr = new Array(3)
+			sparseArr[1] = 'middle'
+			const result = toSignal(sparseArr)
+
+			expect(isStore(result)).toBe(true)
+			expect('0' in result).toBe(false)
+			expect(result['1'].get()).toBe('middle')
+			expect('2' in result).toBe(false)
+		})
+	})
+})
+
+describe('toMutableSignal', () => {
+	describe('type inference and runtime behavior', () => {
+		test('converts array to Store<Record<string, T>>', () => {
+			const arr = [
+				{ id: 1, name: 'Alice' },
+				{ id: 2, name: 'Bob' },
+			]
+			const result = toMutableSignal(arr)
+
+			// Runtime behavior
+			expect(isStore(result)).toBe(true)
+			expect(result['0'].get()).toEqual({ id: 1, name: 'Alice' })
+			expect(result['1'].get()).toEqual({ id: 2, name: 'Bob' })
+
+			// Type inference test - now correctly returns Store<Record<string, {id: number, name: string}>>
+			const typedResult: Store<
+				Record<string, { id: number; name: string }>
+			> = result
+			expect(typedResult).toBeDefined()
+		})
+
+		test('converts record to Store<T>', () => {
+			const record = { name: 'Alice', age: 30 }
+			const result = toMutableSignal(record)
+
+			// Runtime behavior
+			expect(isStore(result)).toBe(true)
+			expect(result.name.get()).toBe('Alice')
+			expect(result.age.get()).toBe(30)
+
+			// Type inference test - should be Store<{name: string, age: number}>
+			const typedResult: Store<{ name: string; age: number }> = result
+			expect(typedResult).toBeDefined()
+		})
+
+		test('passes through existing Store unchanged', () => {
+			const originalStore = store({ count: 5 })
+			const result = toMutableSignal(originalStore)
+
+			// Runtime behavior
+			expect(result).toBe(originalStore) // Should be the same instance
+			expect(isStore(result)).toBe(true)
+			expect(result.count.get()).toBe(5)
+		})
+
+		test('passes through existing State unchanged', () => {
+			const originalState = state(42)
+			const result = toMutableSignal(originalState)
+
+			// Runtime behavior
+			expect(result).toBe(originalState) // Should be the same instance
+			expect(isState(result)).toBe(true)
+			expect(result.get()).toBe(42)
+
+			// Type inference test - should be State<number>
+			const typedResult: State<number> = result
+			expect(typedResult).toBeDefined()
+		})
+
+		test('converts primitive to State<T>', () => {
+			const num = 42
+			const result = toMutableSignal(num)
+
+			// Runtime behavior - primitives are correctly converted to State
+			expect(isState(result)).toBe(true)
+			expect(result.get()).toBe(42)
+		})
+
+		test('converts object to State<T> (not Store)', () => {
+			const obj = new Date('2024-01-01')
+			const result = toMutableSignal(obj)
+
+			// Runtime behavior - objects are correctly converted to State
+			expect(isState(result)).toBe(true)
+			expect(result.get()).toBe(obj)
+
+			// Type inference test - should be State<Date>
+			const typedResult: State<Date> = result
+			expect(typedResult).toBeDefined()
+		})
+	})
+
+	describe('differences from toSignal', () => {
+		test('does not accept functions (only mutable signals)', () => {
+			// toMutableSignal should not have a function overload
+			// This test documents the expected behavior difference
+			const fn = () => 'test'
+			const result = toMutableSignal(fn)
+
+			// Should treat function as a regular value and create State
+			expect(isState(result)).toBe(true)
+			expect(result.get()).toBe(fn)
+		})
+
+		test('does not accept Computed signals', () => {
+			// toMutableSignal should not accept Computed signals
+			const comp = computed(() => 'computed value')
+			const result = toMutableSignal(comp)
+
+			// Should treat Computed as a regular object and create State
+			expect(isState(result)).toBe(true)
+			expect(result.get()).toBe(comp)
+		})
+	})
+})
+
+describe('Signal compatibility', () => {
+	test('all results implement Signal<T> interface', () => {
+		const arraySignal = toSignal([1, 2, 3])
+		const recordSignal = toSignal({ a: 1, b: 2 })
+		const primitiveSignal = toSignal(42)
+		const functionSignal = toSignal(() => 'hello')
+		const stateSignal = toSignal(state(true))
+
+		// All should have get() method
+		expect(typeof arraySignal.get).toBe('function')
+		expect(typeof recordSignal.get).toBe('function')
+		expect(typeof primitiveSignal.get).toBe('function')
+		expect(typeof functionSignal.get).toBe('function')
+		expect(typeof stateSignal.get).toBe('function')
+
+		// All should be assignable to Signal<T>
+		const signals: Signal<unknown & {}>[] = [
+			arraySignal,
+			recordSignal,
+			primitiveSignal,
+			functionSignal,
+			stateSignal,
+		]
+		expect(signals.length).toBe(5)
+	})
+})
+
+describe('Type precision tests', () => {
+	test('array type should infer element type correctly', () => {
+		// Test that arrays infer the correct element type
+		const stringArray = ['a', 'b', 'c']
+		const stringArraySignal = toSignal(stringArray)
+
+		// Should be Store<Record<string, string>>
+		expect(stringArraySignal['0'].get()).toBe('a')
+
+		const numberArray = [1, 2, 3]
+		const numberArraySignal = toSignal(numberArray)
+
+		// Should be Store<Record<string, number>>
+		expect(typeof numberArraySignal['0'].get()).toBe('number')
+	})
+
+	test('complex object arrays maintain precise typing', () => {
+		interface User {
+			id: number
+			name: string
+			email: string
+		}
+
+		const users: User[] = [
+			{ id: 1, name: 'Alice', email: 'alice@example.com' },
+			{ id: 2, name: 'Bob', email: 'bob@example.com' },
+		]
+
+		const usersSignal = toSignal(users)
+
+		// Should maintain User type for each element
+		const firstUser = usersSignal['0'].get()
+		expect(firstUser.id).toBe(1)
+		expect(firstUser.name).toBe('Alice')
+		expect(firstUser.email).toBe('alice@example.com')
+	})
+
+	describe('Type inference issues', () => {
+		test('demonstrates current type inference problem', () => {
+			// Current issue: when passing an array, T is inferred as the array type
+			// instead of the element type, causing type compatibility problems
+			const items = [{ id: 1 }, { id: 2 }]
+			const result = toSignal(items)
+
+			// This should work but may have type issues in external libraries
+			// The return type should be Store<Record<string, {id: number}>>
+			// But currently it might be inferred as Store<Record<string, {id: number}[]>>
+
+			// Let's verify the actual behavior
+			expect(isStore(result)).toBe(true)
+			expect(result['0'].get()).toEqual({ id: 1 })
+			expect(result['1'].get()).toEqual({ id: 2 })
+
+			// Type assertion test - this should now work with correct typing
+			const typedResult: Store<Record<string, { id: number }>> = result
+			expect(typedResult).toBeDefined()
+
+			// Simulate external library usage where P[K] represents element type
+			interface ExternalLibraryConstraint<P extends UnknownRecord> {
+				process<K extends keyof P>(signal: Signal<P[K]>): void
+			}
+
+			// This should work if types are correct
+			const processor: ExternalLibraryConstraint<
+				Record<string, { id: number }>
+			> = {
+				process: <K extends keyof Record<string, { id: number }>>(
+					signal: Signal<Record<string, { id: number }>[K]>,
+				) => {
+					// Process the signal
+					const value = signal.get()
+					expect(value).toHaveProperty('id')
+				},
+			}
+
+			// This call should work without type errors
+			processor.process(result['0'])
+		})
+
+		test('verifies fixed type inference for external library compatibility', () => {
+			// This test ensures the fix for the type inference issue works
+			// Fixed: toSignal<T extends unknown & {}>(value: T[]): Store<Record<string, T>>
+			// Now T = {id: number} (element type), T[] = {id: number}[] (array of elements)
+			// Return type: Store<Record<string, {id: number}>> (correct)
+
+			const items = [
+				{ id: 1, name: 'Alice' },
+				{ id: 2, name: 'Bob' },
+			]
+			const signal = toSignal(items)
+
+			// Type should be Store<Record<string, {id: number, name: string}>>
+			// Each property signal should be Signal<{id: number, name: string}>
+			const firstItemSignal = signal['0']
+			const secondItemSignal = signal['1']
+
+			// Runtime behavior works correctly
+			expect(isStore(signal)).toBe(true)
+			expect(firstItemSignal.get()).toEqual({ id: 1, name: 'Alice' })
+			expect(secondItemSignal.get()).toEqual({ id: 2, name: 'Bob' })
+
+			// Type inference should now work correctly:
+			const properlyTyped: Store<
+				Record<string, { id: number; name: string }>
+			> = signal
+			expect(properlyTyped).toBeDefined()
+
+			// These should work without type errors in external libraries
+			// that expect Signal<P[K]> where P[K] is the individual element type
+			interface ExternalAPI<P extends UnknownRecord> {
+				process<K extends keyof P>(key: K, signal: Signal<P[K]>): P[K]
+			}
+
+			const api: ExternalAPI<
+				Record<string, { id: number; name: string }>
+			> = {
+				process: (_key, signal) => signal.get(),
+			}
+
+			// These calls should work with proper typing now
+			const result1 = api.process('0', firstItemSignal)
+			const result2 = api.process('1', secondItemSignal)
+
+			expect(result1).toEqual({ id: 1, name: 'Alice' })
+			expect(result2).toEqual({ id: 2, name: 'Bob' })
+
+			// Verify the types are precise
+			expect(typeof result1.id).toBe('number')
+			expect(typeof result1.name).toBe('string')
+		})
+	})
+})

package/test/store.test.ts

@@ -8,6 +8,7 @@ import {
 	type StoreRemoveEvent,
 	state,
 	store,
+	toSignal,
 	UNSET,
 } from '..'
 
@@ -44,6 +45,32 @@ describe('store', () => {
 				name: 'Hannah',
 				email: 'hannah@example.com',
 			})
+
+			/**
+			 * store() only accepts object map types for arrays
+			 */
+			const participants = store<{
+				[x: number]: { name: string; tags: string[] }
+			}>([
+				{ name: 'Alice', tags: ['friends', 'mates'] },
+				{ name: 'Bob', tags: ['friends'] },
+			])
+			expect(participants.get()).toEqual([
+				{ name: 'Alice', tags: ['friends', 'mates'] },
+				{ name: 'Bob', tags: ['friends'] },
+			])
+
+			/**
+			 * toSignal() converts arrays to object map types when creating stores
+			 */
+			const participants2 = toSignal<{ name: string; tags: string[] }[]>([
+				{ name: 'Alice', tags: ['friends', 'mates'] },
+				{ name: 'Bob', tags: ['friends'] },
+			])
+			expect(participants2.get()).toEqual([
+				{ name: 'Alice', tags: ['friends', 'mates'] },
+				{ name: 'Bob', tags: ['friends'] },
+			])
 		})
 	})
 

package/types/index.d.ts

@@ -1,15 +1,15 @@
 /**
  * @name Cause & Effect
- * @version 0.15.0
+ * @version 0.15.1
  * @author Esther Brunner
  */
 export { type Computed, type ComputedCallback, computed, isComputed, isComputedCallback, TYPE_COMPUTED, } from './src/computed';
-export { type DiffResult, diff, isEqual, type UnknownRecord } from './src/diff';
+export { type DiffResult, diff, isEqual, type UnknownRecord, type UnknownRecordOrArray, } from './src/diff';
 export { type EffectCallback, effect, type MaybeCleanup } from './src/effect';
 export { type MatchHandlers, match } from './src/match';
 export { type ResolveResult, resolve } from './src/resolve';
 export { batch, type Cleanup, enqueue, flush, notify, observe, subscribe, type Updater, type Watcher, watch, } from './src/scheduler';
-export { isSignal, type MaybeSignal, type Signal, type SignalValues, toSignal, UNSET, } from './src/signal';
+export { isSignal, type MaybeSignal, type Signal, type SignalValues, toMutableSignal, toSignal, UNSET, type UnknownSignalRecord, } from './src/signal';
 export { isState, type State, state, TYPE_STATE } from './src/state';
 export { isStore, type Store, type StoreAddEvent, type StoreChangeEvent, type StoreEventMap, type StoreRemoveEvent, store, TYPE_STORE, } from './src/store';
-export { CircularDependencyError, isAbortError, isAsyncFunction, isFunction, toError, } from './src/util';
+export { CircularDependencyError, isAbortError, isAsyncFunction, isFunction, isNumber, isString, toError, } from './src/util';

package/types/src/diff.d.ts

@@ -1,5 +1,8 @@
 type UnknownRecord = Record<string, unknown & {}>;
-type DiffResult<T extends UnknownRecord = UnknownRecord> = {
+type UnknownRecordOrArray = {
+    [x: string | number]: unknown & {};
+};
+type DiffResult<T extends UnknownRecordOrArray = UnknownRecord> = {
     changed: boolean;
     add: Partial<T>;
     change: Partial<T>;
@@ -23,5 +26,5 @@ declare const isEqual: <T>(a: T, b: T, visited?: WeakSet<object>) => boolean;
  * @param {T} newObj - The new record to compare
  * @returns {DiffResult<T>} The result of the comparison
  */
-declare const diff: <T extends UnknownRecord>(oldObj: T, newObj: T) => DiffResult<T>;
-export { type DiffResult, diff, isEqual, type UnknownRecord };
+declare const diff: <T extends UnknownRecordOrArray>(oldObj: T, newObj: T) => DiffResult<T>;
+export { type DiffResult, diff, isEqual, type UnknownRecord, type UnknownRecordOrArray, };

package/types/src/match.d.ts

@@ -1,6 +1,6 @@
 import type { ResolveResult } from './resolve';
-import type { Signal, SignalValues } from './signal';
-type MatchHandlers<S extends Record<string, Signal<unknown & {}>>> = {
+import type { SignalValues, UnknownSignalRecord } from './signal';
+type MatchHandlers<S extends UnknownSignalRecord> = {
     ok?: (values: SignalValues<S>) => void;
     err?: (errors: readonly Error[]) => void;
     nil?: () => void;
@@ -17,5 +17,5 @@ type MatchHandlers<S extends Record<string, Signal<unknown & {}>>> = {
  * @param {MatchHandlers<S>} handlers - Handlers for different states (side effects only)
  * @returns {void} - Always returns void
  */
-declare function match<S extends Record<string, Signal<unknown & {}>>>(result: ResolveResult<S>, handlers: MatchHandlers<S>): void;
+declare function match<S extends UnknownSignalRecord>(result: ResolveResult<S>, handlers: MatchHandlers<S>): void;
 export { match, type MatchHandlers };

package/types/src/resolve.d.ts

@@ -1,5 +1,5 @@
-import { type Signal, type SignalValues } from './signal';
-type ResolveResult<S extends Record<string, Signal<unknown & {}>>> = {
+import { type SignalValues, type UnknownSignalRecord } from './signal';
+type ResolveResult<S extends UnknownSignalRecord> = {
     ok: true;
     values: SignalValues<S>;
     errors?: never;
@@ -25,5 +25,5 @@ type ResolveResult<S extends Record<string, Signal<unknown & {}>>> = {
  * @param {S} signals - Signals to resolve
  * @returns {ResolveResult<S>} - Discriminated union result
  */
-declare function resolve<S extends Record<string, Signal<unknown & {}>>>(signals: S): ResolveResult<S>;
+declare function resolve<S extends UnknownSignalRecord>(signals: S): ResolveResult<S>;
 export { resolve, type ResolveResult };

package/types/src/signal.d.ts

@@ -5,7 +5,8 @@ type Signal<T extends {}> = {
     get(): T;
 };
 type MaybeSignal<T extends {}> = T | Signal<T> | ComputedCallback<T>;
-type SignalValues<S extends Record<string, Signal<unknown & {}>>> = {
+type UnknownSignalRecord = Record<string, Signal<unknown & {}>>;
+type SignalValues<S extends UnknownSignalRecord> = {
     [K in keyof S]: S[K] extends Signal<infer T> ? T : never;
 };
 declare const UNSET: any;
@@ -21,20 +22,23 @@ declare const isSignal: <T extends {}>(value: unknown) => value is Signal<T>;
  * Convert a value to a Signal if it's not already a Signal
  *
  * @since 0.9.6
+ * @param {T} value - value to convert
+ * @returns {Signal<T>} - Signal instance
  */
-declare function toSignal<T extends Array<unknown & {}>>(value: T[]): Store<Record<string, T>>;
-declare function toSignal<T extends Record<keyof T, T[keyof T]>>(value: T): Store<T>;
-declare function toSignal<T extends {}>(value: ComputedCallback<T>): Computed<T>;
-declare function toSignal<T extends {}>(value: Signal<T>): Signal<T>;
-declare function toSignal<T extends {}>(value: T): State<T>;
+declare function toSignal<T extends {}>(value: T[]): Store<Record<string, T>>;
+declare function toSignal<T extends {}>(value: (() => T) | ((abort: AbortSignal) => Promise<T>)): Computed<T>;
+declare function toSignal<T extends {}>(value: T): T extends Store<infer U> ? Store<U> : T extends State<infer U> ? State<U> : T extends Computed<infer U> ? Computed<U> : T extends Signal<infer U> ? Signal<U> : T extends Record<string, unknown & {}> ? Store<{
+    [K in keyof T]: T[K];
+}> : State<T>;
 /**
  * Convert a value to a mutable Signal if it's not already a Signal
  *
- * @since 0.9.6
+ * @since 0.15.0
+ * @param {T} value - value to convert
+ * @returns {State<T> | Store<T>} - Signal instance
  */
-declare function toMutableSignal<T extends Array<unknown & {}>>(value: T[]): Store<Record<string, T>>;
-declare function toMutableSignal<T extends Record<keyof T, T[keyof T]>>(value: T): Store<T>;
-declare function toMutableSignal<T extends State<T>>(value: State<T>): State<T>;
-declare function toMutableSignal<T extends Store<T>>(value: Store<T>): Store<T>;
-declare function toMutableSignal<T extends {}>(value: T): State<T>;
-export { type Signal, type MaybeSignal, type SignalValues, UNSET, isSignal, toSignal, toMutableSignal, };
+declare function toMutableSignal<T extends {}>(value: T[]): Store<Record<string, T>>;
+declare function toMutableSignal<T extends {}>(value: T): T extends Store<infer U> ? Store<U> : T extends State<infer U> ? State<U> : T extends Record<string, unknown & {}> ? Store<{
+    [K in keyof T]: T[K];
+}> : State<T>;
+export { type Signal, type MaybeSignal, type UnknownSignalRecord, type SignalValues, UNSET, isSignal, toSignal, toMutableSignal, };