@zeix/cause-effect 0.17.0 → 0.17.1

package/test/ref.test.ts

@@ -0,0 +1,227 @@
+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, isConfig)).not.toThrow()
+	expect(() => new Ref(invalidConfig, 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)
+})

package/types/index.d.ts

@@ -1,18 +1,19 @@
 /**
  * @name Cause & Effect
- * @version 0.17.0
+ * @version 0.17.1
  * @author Esther Brunner
  */
-export { Collection, type CollectionCallback, isCollection, TYPE_COLLECTION, } from './src/classes/collection';
+export { type Collection, type CollectionCallback, type CollectionSource, DerivedCollection, isCollection, TYPE_COLLECTION, } from './src/classes/collection';
 export { type Computed, createComputed, isComputed, isMemoCallback, isTaskCallback, Memo, type MemoCallback, Task, type TaskCallback, TYPE_COMPUTED, } from './src/classes/computed';
 export { type ArrayToRecord, isList, type KeyConfig, List, TYPE_LIST, } from './src/classes/list';
+export { isRef, Ref, TYPE_REF } from './src/classes/ref';
 export { isState, State, TYPE_STATE } from './src/classes/state';
 export { BaseStore, createStore, isStore, type Store, TYPE_STORE, } from './src/classes/store';
 export { type DiffResult, diff, isEqual, type UnknownArray, type UnknownRecord, } from './src/diff';
 export { createEffect, type EffectCallback, type MaybeCleanup, } from './src/effect';
-export { CircularDependencyError, DuplicateKeyError, InvalidCallbackError, InvalidSignalValueError, NullishSignalValueError, ReadonlySignalError, } from './src/errors';
+export { CircularDependencyError, createError, DuplicateKeyError, type Guard, guardMutableSignal, InvalidCallbackError, InvalidCollectionSourceError, InvalidSignalValueError, NullishSignalValueError, ReadonlySignalError, validateCallback, validateSignalValue, } from './src/errors';
 export { type MatchHandlers, match } from './src/match';
 export { type ResolveResult, resolve } from './src/resolve';
 export { createSignal, isMutableSignal, isSignal, type Signal, type SignalValues, type UnknownSignalRecord, } from './src/signal';
 export { batchSignalWrites, type Cleanup, createWatcher, emitNotification, flushPendingReactions, type Listener, type Listeners, type Notifications, notifyWatchers, subscribeActiveWatcher, trackSignalReads, type Watcher, } from './src/system';
-export { isAbortError, isAsyncFunction, isFunction, isNumber, isObjectOfType, isRecord, isRecordOrArray, isString, isSymbol, toError, UNSET, valueString, } from './src/util';
+export { isAbortError, isAsyncFunction, isFunction, isNumber, isObjectOfType, isRecord, isRecordOrArray, isString, isSymbol, UNSET, valueString, } from './src/util';

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

@@ -1,14 +1,28 @@
+import type { Signal } from '../signal';
 import { type Cleanup, type Listener, type Listeners } from '../system';
 import { type Computed } from './computed';
 import { type List } from './list';
-type CollectionSource<T extends {}> = List<T> | Collection<T, any>;
+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>>;
+    get: () => T[];
+    at: (index: number) => Signal<T> | undefined;
+    byKey: (key: string) => Signal<T> | undefined;
+    keyAt: (index: number) => string | undefined;
+    indexOfKey: (key: string) => number | undefined;
+    on: <K extends keyof Listeners>(type: K, listener: Listener<K>) => Cleanup;
+    deriveCollection: <R extends {}>(callback: CollectionCallback<R, T>) => DerivedCollection<R, T>;
+    readonly length: number;
+};
 declare const TYPE_COLLECTION: "Collection";
-declare class Collection<T extends {}, U extends {}> {
+declare class DerivedCollection<T extends {}, U extends {}> implements Collection<T> {
     #private;
     constructor(source: CollectionSource<U> | (() => CollectionSource<U>), callback: CollectionCallback<T, U>);
     get [Symbol.toStringTag](): 'Collection';
-    get [Symbol.isConcatSpreadable](): boolean;
+    get [Symbol.isConcatSpreadable](): true;
     [Symbol.iterator](): IterableIterator<Computed<T>>;
     get length(): number;
     get(): T[];
@@ -18,8 +32,8 @@ declare class Collection<T extends {}, U extends {}> {
     keyAt(index: number): string | undefined;
     indexOfKey(key: string): number;
     on<K extends keyof Listeners>(type: K, listener: Listener<K>): Cleanup;
-    deriveCollection<R extends {}>(callback: (sourceValue: T) => R): Collection<R, T>;
-    deriveCollection<R extends {}>(callback: (sourceValue: T, abort: AbortSignal) => Promise<R>): Collection<R, T>;
+    deriveCollection<R extends {}>(callback: (sourceValue: T) => R): DerivedCollection<R, T>;
+    deriveCollection<R extends {}>(callback: (sourceValue: T, abort: AbortSignal) => Promise<R>): DerivedCollection<R, T>;
 }
 /**
  * Check if a value is a collection signal
@@ -28,5 +42,5 @@ declare class Collection<T extends {}, U extends {}> {
  * @param {unknown} value - Value to check
  * @returns {boolean} - True if value is a collection signal, false otherwise
  */
-declare const isCollection: <T extends {}, U extends {}>(value: unknown) => value is Collection<T, U>;
-export { Collection, type CollectionSource, type CollectionCallback, isCollection, TYPE_COLLECTION, };
+declare const isCollection: <T extends {}, U extends {}>(value: unknown) => value is DerivedCollection<T, U>;
+export { type Collection, type CollectionSource, type CollectionCallback, DerivedCollection, isCollection, TYPE_COLLECTION, };

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

@@ -1,6 +1,6 @@
 import { type UnknownArray } from '../diff';
 import { type Cleanup, type Listener, type Notifications } from '../system';
-import { Collection } from './collection';
+import { DerivedCollection } from './collection';
 import { State } from './state';
 type ArrayToRecord<T extends UnknownArray> = {
     [key: string]: T extends Array<infer U extends {}> ? U : never;
@@ -11,7 +11,7 @@ declare class List<T extends {}> {
     #private;
     constructor(initialValue: T[], keyConfig?: KeyConfig<T>);
     get [Symbol.toStringTag](): 'List';
-    get [Symbol.isConcatSpreadable](): boolean;
+    get [Symbol.isConcatSpreadable](): true;
     [Symbol.iterator](): IterableIterator<State<T>>;
     get length(): number;
     get(): T[];
@@ -27,8 +27,8 @@ declare class List<T extends {}> {
     sort(compareFn?: (a: T, b: T) => number): void;
     splice(start: number, deleteCount?: number, ...items: T[]): T[];
     on<K extends keyof Notifications>(type: K, listener: Listener<K>): Cleanup;
-    deriveCollection<R extends {}>(callback: (sourceValue: T) => R): Collection<R, T>;
-    deriveCollection<R extends {}>(callback: (sourceValue: T, abort: AbortSignal) => Promise<R>): Collection<R, T>;
+    deriveCollection<R extends {}>(callback: (sourceValue: T) => R): DerivedCollection<R, T>;
+    deriveCollection<R extends {}>(callback: (sourceValue: T, abort: AbortSignal) => Promise<R>): DerivedCollection<R, T>;
 }
 /**
  * Check if the provided value is a List instance

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

@@ -0,0 +1,39 @@
+import { type Guard } from '../errors';
+declare const TYPE_REF = "Ref";
+/**
+ * Create a new ref signal.
+ *
+ * @since 0.17.1
+ */
+declare class Ref<T extends {}> {
+    #private;
+    /**
+     * Create a new ref signal.
+     *
+     * @param {T} value - Reference to external object
+     * @param {Guard<T>} guard - Optional guard function to validate the value
+     * @throws {NullishSignalValueError} - If the value is null or undefined
+     * @throws {InvalidSignalValueError} - If the value is invalid
+     */
+    constructor(value: T, guard?: Guard<T>);
+    get [Symbol.toStringTag](): string;
+    /**
+     * Get the value of the ref signal.
+     *
+     * @returns {T} - Object reference
+     */
+    get(): T;
+    /**
+     * Notify watchers of relevant changes in the external reference
+     */
+    notify(): void;
+}
+/**
+ * Check if the provided value is a Ref instance
+ *
+ * @since 0.17.1
+ * @param {unknown} value - Value to check
+ * @returns {boolean} - True if the value is a Ref instance, false otherwise
+ */
+declare const isRef: <T extends {}>(value: unknown) => value is Ref<T>;
+export { TYPE_REF, Ref, isRef };

package/types/src/errors.d.ts

@@ -1,4 +1,5 @@
 import { type MutableSignal } from './signal';
+type Guard<T> = (value: unknown) => value is T;
 declare class CircularDependencyError extends Error {
     constructor(where: string);
 }
@@ -8,6 +9,9 @@ declare class DuplicateKeyError extends Error {
 declare class InvalidCallbackError extends TypeError {
     constructor(where: string, value: unknown);
 }
+declare class InvalidCollectionSourceError extends TypeError {
+    constructor(where: string, value: unknown);
+}
 declare class InvalidSignalValueError extends TypeError {
     constructor(where: string, value: unknown);
 }
@@ -17,7 +21,8 @@ declare class NullishSignalValueError extends TypeError {
 declare class ReadonlySignalError extends Error {
     constructor(what: string, value: unknown);
 }
+declare const createError: (reason: unknown) => Error;
 declare const validateCallback: (where: string, value: unknown, guard?: (value: unknown) => boolean) => void;
 declare const validateSignalValue: (where: string, value: unknown, guard?: (value: unknown) => boolean) => void;
 declare const guardMutableSignal: <T extends {}>(what: string, value: unknown, signal: unknown) => signal is MutableSignal<T>;
-export { CircularDependencyError, DuplicateKeyError, InvalidCallbackError, InvalidSignalValueError, NullishSignalValueError, ReadonlySignalError, validateCallback, validateSignalValue, guardMutableSignal, };
+export { type Guard, CircularDependencyError, DuplicateKeyError, InvalidCallbackError, InvalidCollectionSourceError, InvalidSignalValueError, NullishSignalValueError, ReadonlySignalError, createError, validateCallback, validateSignalValue, guardMutableSignal, };

package/types/src/util.d.ts

@@ -14,6 +14,5 @@ declare const isRecordOrArray: <T extends Record<string | number, unknown> | Rea
 declare const isUniformArray: <T>(value: unknown, guard?: (item: T) => item is T & {}) => value is T[];
 declare const hasMethod: <T extends object & Record<string, (...args: unknown[]) => unknown>>(obj: T, methodName: string) => obj is T & Record<string, (...args: unknown[]) => unknown>;
 declare const isAbortError: (error: unknown) => boolean;
-declare const toError: (reason: unknown) => Error;
 declare const valueString: (value: unknown) => string;
-export { UNSET, isString, isNumber, isSymbol, isFunction, isAsyncFunction, isSyncFunction, isNonNullObject, isObjectOfType, isRecord, isRecordOrArray, isUniformArray, hasMethod, isAbortError, toError, valueString, };
+export { UNSET, isString, isNumber, isSymbol, isFunction, isAsyncFunction, isSyncFunction, isNonNullObject, isObjectOfType, isRecord, isRecordOrArray, isUniformArray, hasMethod, isAbortError, valueString, };