@zeix/cause-effect 0.17.3 → 0.18.0

package/test/ref.test.ts

@@ -1,353 +0,0 @@
-import { expect, mock, test } from 'bun:test'
-import { isRef, Ref } from '../src/classes/ref'
-import { createEffect } from '../src/effect'
-
-test('Ref - basic functionality', () => {
-	const obj = { name: 'test', value: 42 }
-	const ref = new Ref(obj)
-
-	expect(ref.get()).toBe(obj)
-	expect(ref[Symbol.toStringTag]).toBe('Ref')
-})
-
-test('Ref - isRef type guard', () => {
-	const ref = new Ref({ test: true })
-	const notRef = { test: true }
-
-	expect(isRef(ref)).toBe(true)
-	expect(isRef(notRef)).toBe(false)
-	expect(isRef(null)).toBe(false)
-	expect(isRef(undefined)).toBe(false)
-})
-
-test('Ref - validation with guard function', () => {
-	const isConfig = (
-		value: unknown,
-	): value is { host: string; port: number } =>
-		typeof value === 'object' &&
-		value !== null &&
-		'host' in value &&
-		'port' in value &&
-		typeof value.host === 'string' &&
-		typeof value.port === 'number'
-
-	const validConfig = { host: 'localhost', port: 3000 }
-	const invalidConfig = { host: 'localhost' } // missing port
-
-	expect(() => new Ref(validConfig, { guard: isConfig })).not.toThrow()
-	expect(() => new Ref(invalidConfig, { guard: isConfig })).toThrow()
-})
-
-test('Ref - reactive subscriptions', () => {
-	const server = { status: 'offline', connections: 0 }
-	const ref = new Ref(server)
-
-	let effectRunCount = 0
-	let lastStatus: string = ''
-
-	createEffect(() => {
-		const current = ref.get()
-		lastStatus = current.status
-		effectRunCount++
-	})
-
-	expect(effectRunCount).toBe(1)
-	expect(lastStatus).toBe('offline')
-
-	// Simulate external change without going through reactive system
-	server.status = 'online'
-	server.connections = 5
-
-	// Effect shouldn't re-run yet (reference hasn't changed)
-	expect(effectRunCount).toBe(1)
-
-	// Notify that the external object has changed
-	ref.notify()
-
-	expect(effectRunCount).toBe(2)
-	expect(lastStatus).toBe('online')
-})
-
-test('Ref - notify triggers watchers even with same reference', () => {
-	const fileObj = { path: '/test.txt', size: 100, modified: Date.now() }
-	const ref = new Ref(fileObj)
-
-	const mockCallback = mock(() => {})
-
-	createEffect(() => {
-		ref.get()
-		mockCallback()
-	})
-
-	expect(mockCallback).toHaveBeenCalledTimes(1)
-
-	// Simulate file modification (same object reference, different content)
-	fileObj.size = 200
-	fileObj.modified = Date.now()
-
-	// Notify about external change
-	ref.notify()
-
-	expect(mockCallback).toHaveBeenCalledTimes(2)
-
-	// Multiple notifies should trigger multiple times
-	ref.notify()
-	expect(mockCallback).toHaveBeenCalledTimes(3)
-})
-
-test('Ref - multiple effects with same ref', () => {
-	const database = { connected: false, queries: 0 }
-	const ref = new Ref(database)
-
-	const effect1Mock = mock(() => {})
-	const effect2Mock = mock((_connected: boolean) => {})
-
-	createEffect(() => {
-		ref.get()
-		effect1Mock()
-	})
-
-	createEffect(() => {
-		const db = ref.get()
-		effect2Mock(db.connected)
-	})
-
-	expect(effect1Mock).toHaveBeenCalledTimes(1)
-	expect(effect2Mock).toHaveBeenCalledTimes(1)
-	expect(effect2Mock).toHaveBeenCalledWith(false)
-
-	// Simulate database connection change
-	database.connected = true
-	database.queries = 10
-	ref.notify()
-
-	expect(effect1Mock).toHaveBeenCalledTimes(2)
-	expect(effect2Mock).toHaveBeenCalledTimes(2)
-	expect(effect2Mock).toHaveBeenLastCalledWith(true)
-})
-
-test('Ref - with Bun.file() scenario', () => {
-	// Mock a file-like object that could change externally
-	const fileRef = {
-		name: 'config.json',
-		size: 1024,
-		lastModified: Date.now(),
-		// Simulate file methods
-		exists: () => true,
-		text: () => Promise.resolve('{"version": "1.0"}'),
-	}
-
-	const ref = new Ref(fileRef)
-
-	let sizeChanges = 0
-	createEffect(() => {
-		const file = ref.get()
-		if (file.size > 1000) sizeChanges++
-	})
-
-	expect(sizeChanges).toBe(1) // Initial run
-
-	// Simulate file growing (external change)
-	fileRef.size = 2048
-	fileRef.lastModified = Date.now()
-	ref.notify()
-
-	expect(sizeChanges).toBe(2) // Effect re-ran and condition still met
-
-	// Simulate file shrinking
-	fileRef.size = 500
-	ref.notify()
-
-	expect(sizeChanges).toBe(2) // Effect re-ran but condition no longer met
-})
-
-test('Ref - validation errors', () => {
-	// @ts-expect-error deliberatly provoked error
-	expect(() => new Ref(null)).toThrow()
-	// @ts-expect-error deliberatly provoked error
-	expect(() => new Ref(undefined)).toThrow()
-})
-
-test('Ref - server config object scenario', () => {
-	const config = {
-		host: 'localhost',
-		port: 3000,
-		ssl: false,
-		maxConnections: 100,
-	}
-
-	const configRef = new Ref(config)
-	const connectionAttempts: string[] = []
-
-	createEffect(() => {
-		const cfg = configRef.get()
-		const protocol = cfg.ssl ? 'https' : 'http'
-		connectionAttempts.push(`${protocol}://${cfg.host}:${cfg.port}`)
-	})
-
-	expect(connectionAttempts).toEqual(['http://localhost:3000'])
-
-	// Simulate config reload from file/environment
-	config.ssl = true
-	config.port = 8443
-	configRef.notify()
-
-	expect(connectionAttempts).toEqual([
-		'http://localhost:3000',
-		'https://localhost:8443',
-	])
-})
-
-test('Ref - handles complex nested objects', () => {
-	const apiResponse = {
-		status: 200,
-		data: {
-			users: [{ id: 1, name: 'Alice' }],
-			pagination: { page: 1, total: 1 },
-		},
-		headers: { 'content-type': 'application/json' },
-	}
-
-	const ref = new Ref(apiResponse)
-	let userCount = 0
-
-	createEffect(() => {
-		const response = ref.get()
-		userCount = response.data.users.length
-	})
-
-	expect(userCount).toBe(1)
-
-	// Simulate API response update
-	apiResponse.data.users.push({ id: 2, name: 'Bob' })
-	apiResponse.data.pagination.total = 2
-	ref.notify()
-
-	expect(userCount).toBe(2)
-})
-
-test('Ref - options.watched lazy resource management', async () => {
-	// 1. Create Ref with current Date
-	let counter = 0
-	let intervalId: Timer | undefined
-	const ref = new Ref(new Date(), {
-		watched: () => {
-			intervalId = setInterval(() => {
-				counter++
-			}, 10)
-		},
-		unwatched: () => {
-			if (intervalId) {
-				clearInterval(intervalId)
-				intervalId = undefined
-			}
-		},
-	})
-
-	// 2. Counter should not be running yet
-	expect(counter).toBe(0)
-
-	// Wait a bit to ensure counter doesn't increment
-	await new Promise(resolve => setTimeout(resolve, 50))
-	expect(counter).toBe(0)
-	expect(intervalId).toBeUndefined()
-
-	// 3. Effect subscribes by .get()ting the signal value
-	const effectCleanup = createEffect(() => {
-		ref.get()
-	})
-
-	// 4. Counter should now be running
-	await new Promise(resolve => setTimeout(resolve, 50))
-	expect(counter).toBeGreaterThan(0)
-	expect(intervalId).toBeDefined()
-
-	// 5. Call effect cleanup, which should stop internal watcher and unsubscribe
-	effectCleanup()
-	const counterAfterStop = counter
-
-	// 6. Ref signal should call #unwatch() and counter should stop incrementing
-	await new Promise(resolve => setTimeout(resolve, 50))
-	expect(counter).toBe(counterAfterStop) // Counter should not have incremented
-	expect(intervalId).toBeUndefined() // Interval should be cleared
-})
-
-test('Ref - options.watched exception handling', async () => {
-	const ref = new Ref(
-		{ test: 'value' },
-		{
-			watched: () => {
-				throwingCallbackCalled = true
-				throw new Error('Test error in watched callback')
-			},
-		},
-	)
-
-	// Mock console.error to capture error logs
-	const originalError = console.error
-	const errorSpy = mock(() => {})
-	console.error = errorSpy
-
-	let throwingCallbackCalled = false
-
-	// Subscribe to trigger watched callback
-	const effectCleanup = createEffect(() => {
-		ref.get()
-	})
-
-	// Both callbacks should have been called despite the exception
-	expect(throwingCallbackCalled).toBe(true)
-
-	// Error should have been logged
-	expect(errorSpy).toHaveBeenCalledWith(
-		'Error in effect callback:',
-		expect.any(Error),
-	)
-
-	// Cleanup
-	effectCleanup()
-	console.error = originalError
-})
-
-test('Ref - options.unwatched exception handling', async () => {
-	const ref = new Ref(
-		{ test: 'value' },
-		{
-			watched: () => {},
-			unwatched: () => {
-				cleanup1Called = true
-				throw new Error('Test error in cleanup function')
-			},
-		},
-	)
-
-	// Mock console.error to capture error logs
-	const originalError = console.error
-	const errorSpy = mock(() => {})
-	console.error = errorSpy
-
-	let cleanup1Called = false
-
-	// Subscribe and then unsubscribe to trigger cleanup
-	const effectCleanup = createEffect(() => {
-		ref.get()
-	})
-
-	// Unsubscribe to trigger cleanup functions
-	effectCleanup()
-
-	// Wait a bit for cleanup to complete
-	await new Promise(resolve => setTimeout(resolve, 10))
-
-	// Both cleanup functions should have been called despite the exception
-	expect(cleanup1Called).toBe(true)
-
-	// Error should have been logged
-	expect(errorSpy).toHaveBeenCalledWith(
-		'Error in effect cleanup:',
-		expect.any(Error),
-	)
-
-	// Cleanup
-	console.error = originalError
-})

package/test/resolve.test.ts

@@ -1,154 +0,0 @@
-import { describe, expect, test } from 'bun:test'
-import { Memo, resolve, State, Task, UNSET } from '../index.ts'
-
-/* === Tests === */
-
-describe('Resolve Function', () => {
-	test('should return discriminated union for successful resolution', () => {
-		const a = new State(10)
-		const b = new State('hello')
-
-		const result = resolve({ a, b })
-
-		expect(result.ok).toBe(true)
-		if (result.ok) {
-			expect(result.values.a).toBe(10)
-			expect(result.values.b).toBe('hello')
-			expect(result.errors).toBeUndefined()
-			expect(result.pending).toBeUndefined()
-		}
-	})
-
-	test('should return discriminated union for pending signals', () => {
-		const a = new State(10)
-		const b = new State(UNSET)
-
-		const result = resolve({ a, b })
-
-		expect(result.ok).toBe(false)
-		expect(result.pending).toBe(true)
-		expect(result.values).toBeUndefined()
-		expect(result.errors).toBeUndefined()
-	})
-
-	test('should return discriminated union for error signals', () => {
-		const a = new State(10)
-		const b = new Memo(() => {
-			throw new Error('Test error')
-		})
-
-		const result = resolve({ a, b })
-
-		expect(result.ok).toBe(false)
-		expect(result.pending).toBeUndefined()
-		expect(result.values).toBeUndefined()
-		expect(result.errors).toBeDefined()
-		if (result.errors) {
-			expect(result.errors[0].message).toBe('Test error')
-		}
-	})
-
-	test('should handle mixed error and valid signals', () => {
-		const valid = new State('valid')
-		const error1 = new Memo(() => {
-			throw new Error('Error 1')
-		})
-		const error2 = new Memo(() => {
-			throw new Error('Error 2')
-		})
-
-		const result = resolve({ valid, error1, error2 })
-
-		expect(result.ok).toBe(false)
-		expect(result.errors).toBeDefined()
-		if (result.errors) {
-			expect(result.errors).toHaveLength(2)
-			expect(result.errors[0].message).toBe('Error 1')
-			expect(result.errors[1].message).toBe('Error 2')
-		}
-	})
-
-	test('should prioritize pending over errors', () => {
-		const pending = new State(UNSET)
-		const error = new Memo(() => {
-			throw new Error('Test error')
-		})
-
-		const result = resolve({ pending, error })
-
-		expect(result.ok).toBe(false)
-		expect(result.pending).toBe(true)
-		expect(result.errors).toBeUndefined()
-	})
-
-	test('should handle empty signals object', () => {
-		const result = resolve({})
-
-		expect(result.ok).toBe(true)
-		if (result.ok) {
-			expect(result.values).toEqual({})
-		}
-	})
-
-	test('should handle complex nested object signals', () => {
-		const user = new State({ name: 'Alice', age: 25 })
-		const settings = new State({ theme: 'dark', lang: 'en' })
-
-		const result = resolve({ user, settings })
-
-		expect(result.ok).toBe(true)
-		if (result.ok) {
-			expect(result.values.user.name).toBe('Alice')
-			expect(result.values.user.age).toBe(25)
-			expect(result.values.settings.theme).toBe('dark')
-			expect(result.values.settings.lang).toBe('en')
-		}
-	})
-
-	test('should handle async computed signals that resolve', async () => {
-		const wait = (ms: number) =>
-			new Promise(resolve => setTimeout(resolve, ms))
-
-		const asyncSignal = new Task(async () => {
-			await wait(10)
-			return 'async result'
-		})
-
-		// Initially should be pending
-		let result = resolve({ asyncSignal })
-		expect(result.ok).toBe(false)
-		expect(result.pending).toBe(true)
-
-		// Wait for resolution
-		await wait(20)
-
-		result = resolve({ asyncSignal })
-		expect(result.ok).toBe(true)
-		if (result.ok) expect(result.values.asyncSignal).toBe('async result')
-	})
-
-	test('should handle async computed signals that error', async () => {
-		const wait = (ms: number) =>
-			new Promise(resolve => setTimeout(resolve, ms))
-
-		const asyncError = new Task(async () => {
-			await wait(10)
-			throw new Error('Async error')
-		})
-
-		// Initially should be pending
-		let result = resolve({ asyncError })
-		expect(result.ok).toBe(false)
-		expect(result.pending).toBe(true)
-
-		// Wait for error
-		await wait(20)
-
-		result = resolve({ asyncError })
-		expect(result.ok).toBe(false)
-		expect(result.errors).toBeDefined()
-		if (result.errors) {
-			expect(result.errors[0].message).toBe('Async error')
-		}
-	})
-})

package/types/src/classes/collection.d.ts

@@ -1,45 +0,0 @@
-import type { Signal } from '../signal';
-import { type SignalOptions } from '../system';
-import { type Computed } from './computed';
-import { type List } from './list';
-type CollectionSource<T extends {}> = List<T> | Collection<T>;
-type CollectionCallback<T extends {}, U extends {}> = ((sourceValue: U) => T) | ((sourceValue: U, abort: AbortSignal) => Promise<T>);
-type Collection<T extends {}> = {
-    readonly [Symbol.toStringTag]: 'Collection';
-    readonly [Symbol.isConcatSpreadable]: true;
-    [Symbol.iterator](): IterableIterator<Signal<T>>;
-    keys(): IterableIterator<string>;
-    get: () => T[];
-    at: (index: number) => Signal<T> | undefined;
-    byKey: (key: string) => Signal<T> | undefined;
-    keyAt: (index: number) => string | undefined;
-    indexOfKey: (key: string) => number | undefined;
-    deriveCollection: <R extends {}>(callback: CollectionCallback<R, T>) => DerivedCollection<R, T>;
-    readonly length: number;
-};
-declare const TYPE_COLLECTION: "Collection";
-declare class DerivedCollection<T extends {}, U extends {}> implements Collection<T> {
-    #private;
-    constructor(source: CollectionSource<U> | (() => CollectionSource<U>), callback: CollectionCallback<T, U>, options?: SignalOptions<T[]>);
-    get [Symbol.toStringTag](): 'Collection';
-    get [Symbol.isConcatSpreadable](): true;
-    [Symbol.iterator](): IterableIterator<Computed<T>>;
-    keys(): IterableIterator<string>;
-    get(): T[];
-    at(index: number): Computed<T> | undefined;
-    byKey(key: string): Computed<T> | undefined;
-    keyAt(index: number): string | undefined;
-    indexOfKey(key: string): number;
-    deriveCollection<R extends {}>(callback: (sourceValue: T) => R, options?: SignalOptions<R[]>): DerivedCollection<R, T>;
-    deriveCollection<R extends {}>(callback: (sourceValue: T, abort: AbortSignal) => Promise<R>, options?: SignalOptions<R[]>): DerivedCollection<R, T>;
-    get length(): number;
-}
-/**
- * Check if a value is a collection signal
- *
- * @since 0.17.2
- * @param {unknown} value - Value to check
- * @returns {boolean} - True if value is a collection signal, false otherwise
- */
-declare const isCollection: <T extends {}>(value: unknown) => value is Collection<T>;
-export { type Collection, type CollectionSource, type CollectionCallback, DerivedCollection, isCollection, TYPE_COLLECTION, };

package/types/src/classes/computed.d.ts

@@ -1,94 +0,0 @@
-import { type SignalOptions } from '../system';
-type Computed<T extends {}> = {
-    readonly [Symbol.toStringTag]: 'Computed';
-    get(): T;
-};
-type ComputedOptions<T extends {}> = SignalOptions<T> & {
-    initialValue?: T;
-};
-type MemoCallback<T extends {} & {
-    then?: undefined;
-}> = (oldValue: T) => T;
-type TaskCallback<T extends {} & {
-    then?: undefined;
-}> = (oldValue: T, abort: AbortSignal) => Promise<T>;
-declare const TYPE_COMPUTED: "Computed";
-/**
- * Create a new memoized signal for a synchronous function.
- *
- * @since 0.17.0
- * @param {MemoCallback<T>} callback - Callback function to compute the memoized value
- * @param {T} [initialValue = UNSET] - Initial value of the signal
- * @throws {InvalidCallbackError} If the callback is not an sync function
- * @throws {InvalidSignalValueError} If the initial value is not valid
- */
-declare class Memo<T extends {}> {
-    #private;
-    constructor(callback: MemoCallback<T>, options?: ComputedOptions<T>);
-    get [Symbol.toStringTag](): 'Computed';
-    /**
-     * Return the memoized value after computing it if necessary.
-     *
-     * @returns {T}
-     * @throws {CircularDependencyError} If a circular dependency is detected
-     * @throws {Error} If an error occurs during computation
-     */
-    get(): T;
-}
-/**
- * Create a new task signals that memoizes the result of an asynchronous function.
- *
- * @since 0.17.0
- * @param {TaskCallback<T>} callback - The asynchronous function to compute the memoized value
- * @param {T} [initialValue = UNSET] - Initial value of the signal
- * @throws {InvalidCallbackError} If the callback is not an async function
- * @throws {InvalidSignalValueError} If the initial value is not valid
- */
-declare class Task<T extends {}> {
-    #private;
-    constructor(callback: TaskCallback<T>, options?: ComputedOptions<T>);
-    get [Symbol.toStringTag](): 'Computed';
-    /**
-     * Return the memoized value after executing the async function if necessary.
-     *
-     * @returns {T}
-     * @throws {CircularDependencyError} If a circular dependency is detected
-     * @throws {Error} If an error occurs during computation
-     */
-    get(): T;
-}
-/**
- * Create a derived signal from existing signals
- *
- * @since 0.9.0
- * @param {MemoCallback<T> | TaskCallback<T>} callback - Computation callback function
- * @param {ComputedOptions<T>} options - Optional configuration
- */
-declare const createComputed: <T extends {}>(callback: TaskCallback<T> | MemoCallback<T>, options?: ComputedOptions<T>) => Task<T> | Memo<T>;
-/**
- * Check if a value is a computed signal
- *
- * @since 0.9.0
- * @param {unknown} value - Value to check
- * @returns {boolean} - True if value is a computed signal, false otherwise
- */
-declare const isComputed: <T extends {}>(value: unknown) => value is Memo<T>;
-/**
- * Check if the provided value is a callback that may be used as input for createSignal() to derive a computed state
- *
- * @since 0.12.0
- * @param {unknown} value - Value to check
- * @returns {boolean} - True if value is a sync callback, false otherwise
- */
-declare const isMemoCallback: <T extends {} & {
-    then?: undefined;
-}>(value: unknown) => value is MemoCallback<T>;
-/**
- * Check if the provided value is a callback that may be used as input for createSignal() to derive a computed state
- *
- * @since 0.17.0
- * @param {unknown} value - Value to check
- * @returns {boolean} - True if value is an async callback, false otherwise
- */
-declare const isTaskCallback: <T extends {}>(value: unknown) => value is TaskCallback<T>;
-export { TYPE_COMPUTED, createComputed, isComputed, isMemoCallback, isTaskCallback, Memo, Task, type Computed, type ComputedOptions, type MemoCallback, type TaskCallback, };

package/types/src/classes/list.d.ts

@@ -1,43 +0,0 @@
-import { type UnknownArray } from '../diff';
-import { type SignalOptions } from '../system';
-import { DerivedCollection } from './collection';
-import { State } from './state';
-type ArrayToRecord<T extends UnknownArray> = {
-    [key: string]: T extends Array<infer U extends {}> ? U : never;
-};
-type KeyConfig<T> = string | ((item: T) => string);
-type ListOptions<T extends {}> = SignalOptions<T> & {
-    keyConfig?: KeyConfig<T>;
-};
-declare const TYPE_LIST: "List";
-declare class List<T extends {}> {
-    #private;
-    constructor(initialValue: T[], options?: ListOptions<T>);
-    get [Symbol.toStringTag](): 'List';
-    get [Symbol.isConcatSpreadable](): true;
-    [Symbol.iterator](): IterableIterator<State<T>>;
-    get length(): number;
-    get(): T[];
-    set(newValue: T[]): void;
-    update(fn: (oldValue: T[]) => T[]): void;
-    at(index: number): State<T> | undefined;
-    keys(): IterableIterator<string>;
-    byKey(key: string): State<T> | undefined;
-    keyAt(index: number): string | undefined;
-    indexOfKey(key: string): number;
-    add(value: T): string;
-    remove(keyOrIndex: string | number): void;
-    sort(compareFn?: (a: T, b: T) => number): void;
-    splice(start: number, deleteCount?: number, ...items: T[]): T[];
-    deriveCollection<R extends {}>(callback: (sourceValue: T) => R, options?: SignalOptions<R[]>): DerivedCollection<R, T>;
-    deriveCollection<R extends {}>(callback: (sourceValue: T, abort: AbortSignal) => Promise<R>, options?: SignalOptions<R[]>): DerivedCollection<R, T>;
-}
-/**
- * Check if the provided value is a List instance
- *
- * @since 0.15.0
- * @param {unknown} value - Value to check
- * @returns {boolean} - True if the value is a List instance, false otherwise
- */
-declare const isList: <T extends {}>(value: unknown) => value is List<T>;
-export { isList, List, TYPE_LIST, type ArrayToRecord, type KeyConfig, type ListOptions, };