@zeix/cause-effect 0.15.1 → 0.16.0

package/test/effect.test.ts

@@ -1,11 +1,11 @@
 import { describe, expect, mock, test } from 'bun:test'
 import {
-	computed,
-	effect,
+	createComputed,
+	createEffect,
+	createState,
 	isAbortError,
 	match,
 	resolve,
-	state,
 	UNSET,
 } from '../'
 
@@ -17,9 +17,9 @@ const wait = (ms: number) => new Promise(resolve => setTimeout(resolve, ms))
 
 describe('Effect', () => {
 	test('should be triggered after a state change', () => {
-		const cause = state('foo')
+		const cause = createState('foo')
 		let count = 0
-		effect(() => {
+		createEffect(() => {
 			cause.get()
 			count++
 		})
@@ -29,17 +29,17 @@ describe('Effect', () => {
 	})
 
 	test('should be triggered after computed async signals resolve without waterfalls', async () => {
-		const a = computed(async () => {
+		const a = createComputed(async () => {
 			await wait(100)
 			return 10
 		})
-		const b = computed(async () => {
+		const b = createComputed(async () => {
 			await wait(100)
 			return 20
 		})
 		let result = 0
 		let count = 0
-		effect(() => {
+		createEffect(() => {
 			const resolved = resolve({ a, b })
 			match(resolved, {
 				ok: ({ a: aValue, b: bValue }) => {
@@ -56,10 +56,10 @@ describe('Effect', () => {
 	})
 
 	test('should be triggered repeatedly after repeated state change', async () => {
-		const cause = state(0)
+		const cause = createState(0)
 		let result = 0
 		let count = 0
-		effect(() => {
+		createEffect(() => {
 			result = cause.get()
 			count++
 		})
@@ -71,15 +71,15 @@ describe('Effect', () => {
 	})
 
 	test('should handle errors in effects with resolve handlers', () => {
-		const a = state(1)
-		const b = computed(() => {
+		const a = createState(1)
+		const b = createComputed(() => {
 			const v = a.get()
 			if (v > 5) throw new Error('Value too high')
 			return v * 2
 		})
 		let normalCallCount = 0
 		let errorCallCount = 0
-		effect(() => {
+		createEffect(() => {
 			const resolved = resolve({ b })
 			match(resolved, {
 				ok: () => {
@@ -109,15 +109,15 @@ describe('Effect', () => {
 	})
 
 	test('should handle errors in effects with resolve result', () => {
-		const a = state(1)
-		const b = computed(() => {
+		const a = createState(1)
+		const b = createComputed(() => {
 			const v = a.get()
 			if (v > 5) throw new Error('Value too high')
 			return v * 2
 		})
 		let normalCallCount = 0
 		let errorCallCount = 0
-		effect(() => {
+		createEffect(() => {
 			const result = resolve({ b })
 			if (result.ok) {
 				normalCallCount++
@@ -144,13 +144,13 @@ describe('Effect', () => {
 	})
 
 	test('should handle UNSET values in effects with resolve handlers', async () => {
-		const a = computed(async () => {
+		const a = createComputed(async () => {
 			await wait(100)
 			return 42
 		})
 		let normalCallCount = 0
 		let nilCount = 0
-		effect(() => {
+		createEffect(() => {
 			const resolved = resolve({ a })
 			match(resolved, {
 				ok: values => {
@@ -173,13 +173,13 @@ describe('Effect', () => {
 	})
 
 	test('should handle UNSET values in effects with resolve result', async () => {
-		const a = computed(async () => {
+		const a = createComputed(async () => {
 			await wait(100)
 			return 42
 		})
 		let normalCallCount = 0
 		let nilCount = 0
-		effect(() => {
+		createEffect(() => {
 			const result = resolve({ a })
 			if (result.ok) {
 				normalCallCount++
@@ -205,15 +205,15 @@ describe('Effect', () => {
 		console.error = mockConsoleError
 
 		try {
-			const a = state(1)
-			const b = computed(() => {
+			const a = createState(1)
+			const b = createComputed(() => {
 				const v = a.get()
 				if (v > 5) throw new Error('Value too high')
 				return v * 2
 			})
 
 			// Create an effect without explicit error handling
-			effect(() => {
+			createEffect(() => {
 				b.get()
 			})
 
@@ -232,10 +232,10 @@ describe('Effect', () => {
 	})
 
 	test('should clean up subscriptions when disposed', () => {
-		const count = state(42)
+		const count = createState(42)
 		let received = 0
 
-		const cleanup = effect(() => {
+		const cleanup = createEffect(() => {
 			received = count.get()
 		})
 
@@ -250,9 +250,9 @@ describe('Effect', () => {
 	test('should detect and throw error for circular dependencies in effects', () => {
 		let okCount = 0
 		let errCount = 0
-		const count = state(0)
+		const count = createState(0)
 
-		effect(() => {
+		createEffect(() => {
 			const resolved = resolve({ count })
 			match(resolved, {
 				ok: () => {
@@ -264,7 +264,7 @@ describe('Effect', () => {
 					errCount++
 					expect(errors[0]).toBeInstanceOf(Error)
 					expect(errors[0].message).toBe(
-						'Circular dependency in effect detected',
+						'Circular dependency detected in effect',
 					)
 				},
 			})
@@ -282,7 +282,7 @@ describe('Effect - Async with AbortSignal', () => {
 		let abortSignalReceived = false
 		let effectCompleted = false
 
-		effect(async (abort: AbortSignal) => {
+		createEffect(async (abort: AbortSignal) => {
 			expect(abort).toBeInstanceOf(AbortSignal)
 			expect(abort.aborted).toBe(false)
 			abortSignalReceived = true
@@ -298,12 +298,12 @@ describe('Effect - Async with AbortSignal', () => {
 	})
 
 	test('should abort async operations when signal changes', async () => {
-		const testSignal = state(1)
+		const testSignal = createState(1)
 		let operationAborted = false
 		let operationCompleted = false
 		let abortReason: DOMException | undefined
 
-		effect(async abort => {
+		createEffect(async abort => {
 			const result = resolve({ testSignal })
 			if (!result.ok) return
 
@@ -340,7 +340,7 @@ describe('Effect - Async with AbortSignal', () => {
 		let operationAborted = false
 		let abortReason: DOMException | undefined
 
-		const cleanup = effect(async abort => {
+		const cleanup = createEffect(async abort => {
 			abort.addEventListener('abort', () => {
 				operationAborted = true
 				abortReason = abort.reason
@@ -364,9 +364,9 @@ describe('Effect - Async with AbortSignal', () => {
 		console.error = mockConsoleError
 
 		try {
-			const testSignal = state(1)
+			const testSignal = createState(1)
 
-			effect(async abort => {
+			createEffect(async abort => {
 				const result = resolve({ testSignal })
 				if (!result.ok) return
 
@@ -408,9 +408,9 @@ describe('Effect - Async with AbortSignal', () => {
 	test('should handle async effects that return cleanup functions', async () => {
 		let asyncEffectCompleted = false
 		let cleanupRegistered = false
-		const testSignal = state('initial')
+		const testSignal = createState('initial')
 
-		const cleanup = effect(async () => {
+		const cleanup = createEffect(async () => {
 			const result = resolve({ testSignal })
 			if (!result.ok) return
 
@@ -431,11 +431,11 @@ describe('Effect - Async with AbortSignal', () => {
 	})
 
 	test('should handle rapid signal changes with concurrent async operations', async () => {
-		const testSignal = state(0)
+		const testSignal = createState(0)
 		let completedOperations = 0
 		let abortedOperations = 0
 
-		effect(async abort => {
+		createEffect(async abort => {
 			const result = resolve({ testSignal })
 			if (!result.ok) return
 
@@ -477,15 +477,15 @@ describe('Effect - Async with AbortSignal', () => {
 		console.error = mockConsoleError
 
 		try {
-			const testSignal = state(1)
+			const testSignal = createState(1)
 
-			const errorThrower = computed(() => {
+			const errorThrower = createComputed(() => {
 				const value = testSignal.get()
 				if (value > 5) throw new Error('Value too high')
 				return value
 			})
 
-			effect(async () => {
+			createEffect(async () => {
 				const result = resolve({ errorThrower })
 				if (result.ok) {
 					// Normal operation
@@ -517,9 +517,9 @@ describe('Effect - Async with AbortSignal', () => {
 	test('should handle promise-based async effects', async () => {
 		let promiseResolved = false
 		let effectValue = ''
-		const testSignal = state('test-value')
+		const testSignal = createState('test-value')
 
-		effect(async abort => {
+		createEffect(async abort => {
 			const result = resolve({ testSignal })
 			if (!result.ok) return
 
@@ -548,7 +548,7 @@ describe('Effect - Async with AbortSignal', () => {
 	})
 
 	test('should not create AbortController for sync functions', () => {
-		const testSignal = state('test')
+		const testSignal = createState('test')
 		let syncCallCount = 0
 
 		// Mock AbortController constructor to detect if it's called
@@ -563,7 +563,7 @@ describe('Effect - Async with AbortSignal', () => {
 		}
 
 		try {
-			effect(() => {
+			createEffect(() => {
 				const result = resolve({ testSignal })
 				if (result.ok) {
 					syncCallCount++
@@ -579,11 +579,11 @@ describe('Effect - Async with AbortSignal', () => {
 	})
 
 	test('should handle concurrent async operations with abort', async () => {
-		const testSignal = state(1)
+		const testSignal = createState(1)
 		let operation1Completed = false
 		let operation1Aborted = false
 
-		effect(async abort => {
+		createEffect(async abort => {
 			const result = resolve({ testSignal })
 			if (!result.ok) return
 
@@ -629,11 +629,11 @@ describe('Effect - Async with AbortSignal', () => {
 
 describe('Effect + Resolve Integration', () => {
 	test('should work with resolve discriminated union', () => {
-		const a = state(10)
-		const b = state('hello')
+		const a = createState(10)
+		const b = createState('hello')
 		let effectRan = false
 
-		effect(() => {
+		createEffect(() => {
 			const result = resolve({ a, b })
 
 			if (result.ok) {
@@ -647,10 +647,10 @@ describe('Effect + Resolve Integration', () => {
 	})
 
 	test('should work with match function', () => {
-		const a = state(42)
+		const a = createState(42)
 		let matchedValue = 0
 
-		effect(() => {
+		createEffect(() => {
 			const result = resolve({ a })
 			match(result, {
 				ok: values => {
@@ -666,12 +666,12 @@ describe('Effect + Resolve Integration', () => {
 describe('Effect - Race Conditions and Consistency', () => {
 	test('should handle race conditions between abort and cleanup properly', async () => {
 		// This test explores potential race conditions in effect cleanup
-		const testSignal = state(0)
+		const testSignal = createState(0)
 		let cleanupCallCount = 0
 		let abortCallCount = 0
 		let operationCount = 0
 
-		effect(async abort => {
+		createEffect(async abort => {
 			testSignal.get()
 			++operationCount
 
@@ -706,19 +706,19 @@ describe('Effect - Race Conditions and Consistency', () => {
 
 	test('should demonstrate difference in abort handling between computed and effect', async () => {
 		// This test shows why computed needs an abort listener but effect might not
-		const source = state(1)
+		const source = createState(1)
 		let computedRetries = 0
 		let effectRuns = 0
 
 		// Computed with abort listener (current implementation)
-		const comp = computed(async () => {
+		const comp = createComputed(async () => {
 			computedRetries++
 			await wait(30)
 			return source.get() * 2
 		})
 
 		// Effect without abort listener (current implementation)
-		effect(async () => {
+		createEffect(async () => {
 			effectRuns++
 			// Must access the source to make effect reactive
 			source.get()
@@ -741,12 +741,12 @@ describe('Effect - Race Conditions and Consistency', () => {
 
 	test('should prevent stale cleanup registration with generation counter approach', async () => {
 		// This test verifies that the currentController check prevents stale cleanups
-		const testSignal = state(0)
+		const testSignal = createState(0)
 		let cleanupCallCount = 0
 		let effectRunCount = 0
 		let staleCleanupAttempts = 0
 
-		effect(async () => {
+		createEffect(async () => {
 			effectRunCount++
 			const currentRun = effectRunCount
 			testSignal.get() // Make reactive
@@ -782,11 +782,11 @@ describe('Effect - Race Conditions and Consistency', () => {
 
 	test('should demonstrate why computed needs immediate retry via abort listener', async () => {
 		// This test shows the performance benefit of immediate retry in computed
-		const source = state(1)
+		const source = createState(1)
 		let computeAttempts = 0
 		let finalValue: number = 0
 
-		const comp = computed(async () => {
+		const comp = createComputed(async () => {
 			computeAttempts++
 			await wait(30)
 			return source.get() * 2

package/test/match.test.ts

@@ -1,12 +1,12 @@
 import { describe, expect, test } from 'bun:test'
-import { computed, match, resolve, state, UNSET } from '../'
+import { createComputed, createState, match, resolve, UNSET } from '../'
 
 /* === Tests === */
 
 describe('Match Function', () => {
 	test('should call ok handler for successful resolution', () => {
-		const a = state(10)
-		const b = state('hello')
+		const a = createState(10)
+		const b = createState('hello')
 		let okCalled = false
 		let okValues: { a: number; b: string } | null = null
 
@@ -32,8 +32,8 @@ describe('Match Function', () => {
 	})
 
 	test('should call nil handler for pending signals', () => {
-		const a = state(10)
-		const b = state(UNSET)
+		const a = createState(10)
+		const b = createState(UNSET)
 		let nilCalled = false
 
 		match(resolve({ a, b }), {
@@ -52,8 +52,8 @@ describe('Match Function', () => {
 	})
 
 	test('should call error handler for error signals', () => {
-		const a = state(10)
-		const b = computed(() => {
+		const a = createState(10)
+		const b = createComputed(() => {
 			throw new Error('Test error')
 		})
 		let errCalled = false
@@ -77,18 +77,22 @@ describe('Match Function', () => {
 		expect((errValue as unknown as Error).message).toBe('Test error')
 	})
 
-	test('should handle missing handlers gracefully', () => {
-		const a = state(10)
+	test('should handle missing optional handlers gracefully', () => {
+		const a = createState(10)
 		const result = resolve({ a })
 
-		// Should not throw even with no handlers
+		// Should not throw even with only required ok handler (err and nil are optional)
 		expect(() => {
-			match(result, {})
+			match(result, {
+				ok: () => {
+					// This handler is required, but err and nil are optional
+				},
+			})
 		}).not.toThrow()
 	})
 
 	test('should return void always', () => {
-		const a = state(42)
+		const a = createState(42)
 
 		const returnValue = match(resolve({ a }), {
 			ok: () => {
@@ -101,7 +105,7 @@ describe('Match Function', () => {
 	})
 
 	test('should handle handler errors by calling error handler', () => {
-		const a = state(10)
+		const a = createState(10)
 		let handlerErrorCalled = false
 		let handlerError: Error | null = null
 
@@ -121,7 +125,7 @@ describe('Match Function', () => {
 	})
 
 	test('should rethrow handler errors if no error handler available', () => {
-		const a = state(10)
+		const a = createState(10)
 
 		expect(() => {
 			match(resolve({ a }), {
@@ -133,12 +137,15 @@ describe('Match Function', () => {
 	})
 
 	test('should combine existing errors with handler errors', () => {
-		const a = computed(() => {
+		const a = createComputed(() => {
 			throw new Error('Signal error')
 		})
 		let allErrors: readonly Error[] | null = null
 
 		match(resolve({ a }), {
+			ok: () => {
+				// This won't be called since there are errors, but it's required
+			},
 			err: errors => {
 				// First call with signal error
 				if (errors.length === 1) {
@@ -160,9 +167,9 @@ describe('Match Function', () => {
 	})
 
 	test('should work with complex type inference', () => {
-		const user = state({ id: 1, name: 'Alice' })
-		const posts = state([{ id: 1, title: 'Hello' }])
-		const settings = state({ theme: 'dark' })
+		const user = createState({ id: 1, name: 'Alice' })
+		const posts = createState([{ id: 1, title: 'Hello' }])
+		const settings = createState({ theme: 'dark' })
 
 		let typeTestPassed = false
 
@@ -187,8 +194,8 @@ describe('Match Function', () => {
 	})
 
 	test('should handle side effects only pattern', () => {
-		const count = state(5)
-		const name = state('test')
+		const count = createState(5)
+		const name = createState('test')
 		let sideEffectExecuted = false
 		let capturedData = ''
 
@@ -207,15 +214,18 @@ describe('Match Function', () => {
 	})
 
 	test('should handle multiple error types correctly', () => {
-		const error1 = computed(() => {
+		const error1 = createComputed(() => {
 			throw new Error('First error')
 		})
-		const error2 = computed(() => {
+		const error2 = createComputed(() => {
 			throw new Error('Second error')
 		})
 		let errorMessages: string[] = []
 
 		match(resolve({ error1, error2 }), {
+			ok: () => {
+				// This won't be called since there are errors, but it's required
+			},
 			err: errors => {
 				errorMessages = errors.map(e => e.message)
 			},
@@ -230,7 +240,7 @@ describe('Match Function', () => {
 		const wait = (ms: number) =>
 			new Promise(resolve => setTimeout(resolve, ms))
 
-		const asyncSignal = computed(async () => {
+		const asyncSignal = createComputed(async () => {
 			await wait(10)
 			return 'async result'
 		})
@@ -270,7 +280,7 @@ describe('Match Function', () => {
 	})
 
 	test('should maintain referential transparency', () => {
-		const a = state(42)
+		const a = createState(42)
 		const result = resolve({ a })
 		let callCount = 0
 
@@ -293,7 +303,7 @@ describe('Match Function', () => {
 
 describe('Match Function Integration', () => {
 	test('should work seamlessly with resolve', () => {
-		const data = state({ id: 1, value: 'test' })
+		const data = createState({ id: 1, value: 'test' })
 		let processed = false
 		let processedValue = ''
 
@@ -312,12 +322,12 @@ describe('Match Function Integration', () => {
 		const wait = (ms: number) =>
 			new Promise(resolve => setTimeout(resolve, ms))
 
-		const syncData = state('available')
-		const asyncData = computed(async () => {
+		const syncData = createState('available')
+		const asyncData = createComputed(async () => {
 			await wait(10)
 			return 'loaded'
 		})
-		const errorData = computed(() => {
+		const errorData = createComputed(() => {
 			throw new Error('Failed to load')
 		})
 

package/test/resolve.test.ts

@@ -1,12 +1,12 @@
 import { describe, expect, test } from 'bun:test'
-import { computed, resolve, state, UNSET } from '../'
+import { createComputed, resolve, createState, UNSET } from '../'
 
 /* === Tests === */
 
 describe('Resolve Function', () => {
 	test('should return discriminated union for successful resolution', () => {
-		const a = state(10)
-		const b = state('hello')
+		const a = createState(10)
+		const b = createState('hello')
 
 		const result = resolve({ a, b })
 
@@ -20,8 +20,8 @@ describe('Resolve Function', () => {
 	})
 
 	test('should return discriminated union for pending signals', () => {
-		const a = state(10)
-		const b = state(UNSET)
+		const a = createState(10)
+		const b = createState(UNSET)
 
 		const result = resolve({ a, b })
 
@@ -32,8 +32,8 @@ describe('Resolve Function', () => {
 	})
 
 	test('should return discriminated union for error signals', () => {
-		const a = state(10)
-		const b = computed(() => {
+		const a = createState(10)
+		const b = createComputed(() => {
 			throw new Error('Test error')
 		})
 
@@ -49,11 +49,11 @@ describe('Resolve Function', () => {
 	})
 
 	test('should handle mixed error and valid signals', () => {
-		const valid = state('valid')
-		const error1 = computed(() => {
+		const valid = createState('valid')
+		const error1 = createComputed(() => {
 			throw new Error('Error 1')
 		})
-		const error2 = computed(() => {
+		const error2 = createComputed(() => {
 			throw new Error('Error 2')
 		})
 
@@ -69,8 +69,8 @@ describe('Resolve Function', () => {
 	})
 
 	test('should prioritize pending over errors', () => {
-		const pending = state(UNSET)
-		const error = computed(() => {
+		const pending = createState(UNSET)
+		const error = createComputed(() => {
 			throw new Error('Test error')
 		})
 
@@ -91,8 +91,8 @@ describe('Resolve Function', () => {
 	})
 
 	test('should handle complex nested object signals', () => {
-		const user = state({ name: 'Alice', age: 25 })
-		const settings = state({ theme: 'dark', lang: 'en' })
+		const user = createState({ name: 'Alice', age: 25 })
+		const settings = createState({ theme: 'dark', lang: 'en' })
 
 		const result = resolve({ user, settings })
 
@@ -109,7 +109,7 @@ describe('Resolve Function', () => {
 		const wait = (ms: number) =>
 			new Promise(resolve => setTimeout(resolve, ms))
 
-		const asyncSignal = computed(async () => {
+		const asyncSignal = createComputed(async () => {
 			await wait(10)
 			return 'async result'
 		})
@@ -133,7 +133,7 @@ describe('Resolve Function', () => {
 		const wait = (ms: number) =>
 			new Promise(resolve => setTimeout(resolve, ms))
 
-		const asyncError = computed(async () => {
+		const asyncError = createComputed(async () => {
 			await wait(10)
 			throw new Error('Async error')
 		})