@zeix/cause-effect 0.14.1 → 0.15.0

package/test/util/framework-types.ts

@@ -1,5 +1,5 @@
-import { TestResult } from './perf-tests'
-import { ReactiveFramework } from './reactive-framework'
+import type { TestResult } from './perf-tests'
+import type { ReactiveFramework } from './reactive-framework'
 
 /** Parameters for a running a performance benchmark test
  *

package/test/util/perf-tests.ts

@@ -1,4 +1,4 @@
-import { FrameworkInfo, TestConfig } from './framework-types'
+import type { FrameworkInfo, TestConfig } from './framework-types'
 
 export interface TestResult {
 	sum: number
@@ -25,7 +25,7 @@ export function verifyBenchResult(
 
 	if (expected.sum) {
 		console.assert(
-			result.sum == expected.sum,
+			result.sum === expected.sum,
 			`sum ${framework.name} ${config.name} result:${result.sum} expected:${expected.sum}`,
 		)
 	}

package/test/util/reactive-framework.ts

@@ -6,7 +6,7 @@ export interface ReactiveFramework {
 	name: string
 	signal<T>(initialValue: T): Signal<T>
 	computed<T>(fn: () => T): Computed<T>
-	effect(fn: () => void): void
+	effect(fn: () => undefined): void
 	withBatch<T>(fn: () => T): void
 	withBuild<T>(fn: () => T): T
 }

package/tsconfig.json

@@ -7,28 +7,27 @@
 		"moduleDetection": "force",
 		"jsx": "react-jsx",
 		"allowJs": true,
-	
+
 		// Bundler mode
 		"moduleResolution": "bundler",
 		"allowImportingTsExtensions": true,
 		"verbatimModuleSyntax": true,
-		
+
 		// Best practices
 		"strict": true,
 		"skipLibCheck": true,
 		"noFallthroughCasesInSwitch": true,
-	
+
 		// Some stricter flags (disabled by default)
 		"noUnusedLocals": false,
 		"noUnusedParameters": false,
 		"noPropertyAccessFromIndexSignature": false,
-	
+
 		// Declarations
 		"declaration": true,
-		"declarationDir": "./",
-		"emitDeclarationOnly": true,
+		"declarationDir": "./types",
+		"emitDeclarationOnly": true
 	},
-	"include": ["./*.ts", "./lib/*.ts"],
-	"exclude": ["node_modules", "test"],
-  }
-  
+	"include": ["./*.ts", "./src/*.ts"],
+	"exclude": ["node_modules", "test", "types"]
+}

package/types/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @name Cause & Effect
+ * @version 0.15.0
+ * @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 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 { 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';

package/{src → types/src}/computed.d.ts

@@ -3,7 +3,7 @@ type Computed<T extends {}> = {
     get(): T;
 };
 type ComputedCallback<T extends {} & {
-    then?: void;
+    then?: undefined;
 }> = ((abort: AbortSignal) => Promise<T>) | (() => T);
 declare const TYPE_COMPUTED = "Computed";
 /**
@@ -30,4 +30,4 @@ declare const isComputed: <T extends {}>(value: unknown) => value is Computed<T>
  * @returns {boolean} - true if value is a callback or callbacks object, false otherwise
  */
 declare const isComputedCallback: <T extends {}>(value: unknown) => value is ComputedCallback<T>;
-export { type Computed, type ComputedCallback, TYPE_COMPUTED, computed, isComputed, isComputedCallback, };
+export { TYPE_COMPUTED, computed, isComputed, isComputedCallback, type Computed, type ComputedCallback, };

package/types/src/diff.d.ts

@@ -0,0 +1,27 @@
+type UnknownRecord = Record<string, unknown & {}>;
+type DiffResult<T extends UnknownRecord = UnknownRecord> = {
+    changed: boolean;
+    add: Partial<T>;
+    change: Partial<T>;
+    remove: Partial<T>;
+};
+/**
+ * Checks if two values are equal with cycle detection
+ *
+ * @since 0.15.0
+ * @param {T} a - First value to compare
+ * @param {T} b - Second value to compare
+ * @param {WeakSet<object>} visited - Set to track visited objects for cycle detection
+ * @returns {boolean} Whether the two values are equal
+ */
+declare const isEqual: <T>(a: T, b: T, visited?: WeakSet<object>) => boolean;
+/**
+ * Compares two records and returns a result object containing the differences.
+ *
+ * @since 0.15.0
+ * @param {T} oldObj - The old record to compare
+ * @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 };

package/types/src/effect.d.ts

@@ -0,0 +1,16 @@
+import { type Cleanup } from './scheduler';
+type MaybeCleanup = Cleanup | undefined | void;
+type EffectCallback = (() => MaybeCleanup) | ((abort: AbortSignal) => Promise<MaybeCleanup>);
+/**
+ * Define what happens when a reactive state changes
+ *
+ * The callback can be synchronous or asynchronous. Async callbacks receive
+ * an AbortSignal parameter, which is automatically aborted when the effect
+ * re-runs or is cleaned up, preventing stale async operations.
+ *
+ * @since 0.1.0
+ * @param {EffectCallback} callback - Synchronous or asynchronous effect callback
+ * @returns {Cleanup} - Cleanup function for the effect
+ */
+declare const effect: (callback: EffectCallback) => Cleanup;
+export { type MaybeCleanup, type EffectCallback, effect };

package/types/src/match.d.ts

@@ -0,0 +1,21 @@
+import type { ResolveResult } from './resolve';
+import type { Signal, SignalValues } from './signal';
+type MatchHandlers<S extends Record<string, Signal<unknown & {}>>> = {
+    ok?: (values: SignalValues<S>) => void;
+    err?: (errors: readonly Error[]) => void;
+    nil?: () => void;
+};
+/**
+ * Match on resolve result and call appropriate handler for side effects
+ *
+ * This is a utility function for those who prefer the handler pattern.
+ * All handlers are for side effects only and return void. If you need
+ * cleanup logic, use a hoisted let variable in your effect.
+ *
+ * @since 0.15.0
+ * @param {ResolveResult<S>} result - Result from resolve()
+ * @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;
+export { match, type MatchHandlers };

package/types/src/resolve.d.ts

@@ -0,0 +1,29 @@
+import { type Signal, type SignalValues } from './signal';
+type ResolveResult<S extends Record<string, Signal<unknown & {}>>> = {
+    ok: true;
+    values: SignalValues<S>;
+    errors?: never;
+    pending?: never;
+} | {
+    ok: false;
+    errors: readonly Error[];
+    values?: never;
+    pending?: never;
+} | {
+    ok: false;
+    pending: true;
+    values?: never;
+    errors?: never;
+};
+/**
+ * Resolve signal values with perfect type inference
+ *
+ * Always returns a discriminated union result, regardless of whether
+ * handlers are provided or not. This ensures a predictable API.
+ *
+ * @since 0.15.0
+ * @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>;
+export { resolve, type ResolveResult };

package/{src → types/src}/scheduler.d.ts

@@ -4,7 +4,7 @@ type Watcher = {
     off(cleanup: Cleanup): void;
     cleanup(): void;
 };
-type Updater = <T>() => T | boolean | void;
+type Updater = <T>() => T | boolean | undefined;
 /**
  * Create a watcher that can be used to observe changes to a signal
  *
@@ -51,5 +51,5 @@ declare const observe: (run: () => void, watcher?: Watcher) => void;
  * @param {Updater} fn - function to be executed on the next animation frame; can return updated value <T>, success <boolean> or void
  * @param {symbol} dedupe - Symbol for deduplication; if not provided, a unique Symbol is created ensuring the update is always executed
  */
-declare const enqueue: <T>(fn: Updater, dedupe?: symbol) => Promise<boolean | void | T>;
+declare const enqueue: <T>(fn: Updater, dedupe?: symbol) => Promise<boolean | T | undefined>;
 export { type Cleanup, type Watcher, type Updater, subscribe, notify, flush, batch, watch, observe, enqueue, };

package/types/src/signal.d.ts

@@ -0,0 +1,40 @@
+import { type Computed, type ComputedCallback } from './computed';
+import { type State } from './state';
+import { type Store } from './store';
+type Signal<T extends {}> = {
+    get(): T;
+};
+type MaybeSignal<T extends {}> = T | Signal<T> | ComputedCallback<T>;
+type SignalValues<S extends Record<string, Signal<unknown & {}>>> = {
+    [K in keyof S]: S[K] extends Signal<infer T> ? T : never;
+};
+declare const UNSET: any;
+/**
+ * Check whether a value is a Signal or not
+ *
+ * @since 0.9.0
+ * @param {unknown} value - value to check
+ * @returns {boolean} - true if value is a Signal, false otherwise
+ */
+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
+ */
+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>;
+/**
+ * Convert a value to a mutable Signal if it's not already a Signal
+ *
+ * @since 0.9.6
+ */
+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, };

package/{src → types/src}/state.d.ts

@@ -21,4 +21,4 @@ declare const state: <T extends {}>(initialValue: T) => State<T>;
  * @returns {boolean} - true if the value is a State instance, false otherwise
  */
 declare const isState: <T extends {}>(value: unknown) => value is State<T>;
-export { type State, TYPE_STATE, state, isState };
+export { TYPE_STATE, isState, state, type State };

package/types/src/store.d.ts

@@ -0,0 +1,57 @@
+import { type UnknownRecord } from './diff';
+import { type Signal } from './signal';
+import { type State } from './state';
+declare const TYPE_STORE = "Store";
+interface StoreAddEvent<T extends UnknownRecord> extends CustomEvent {
+    type: 'store-add';
+    detail: Partial<T>;
+}
+interface StoreChangeEvent<T extends UnknownRecord> extends CustomEvent {
+    type: 'store-change';
+    detail: Partial<T>;
+}
+interface StoreRemoveEvent<T extends UnknownRecord> extends CustomEvent {
+    type: 'store-remove';
+    detail: Partial<T>;
+}
+type StoreEventMap<T extends UnknownRecord> = {
+    'store-add': StoreAddEvent<T>;
+    'store-change': StoreChangeEvent<T>;
+    'store-remove': StoreRemoveEvent<T>;
+};
+interface StoreEventTarget<T extends UnknownRecord> extends EventTarget {
+    addEventListener<K extends keyof StoreEventMap<T>>(type: K, listener: (event: StoreEventMap<T>[K]) => void, options?: boolean | AddEventListenerOptions): void;
+    addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener<K extends keyof StoreEventMap<T>>(type: K, listener: (event: StoreEventMap<T>[K]) => void, options?: boolean | EventListenerOptions): void;
+    removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+    dispatchEvent(event: Event): boolean;
+}
+type Store<T extends UnknownRecord = UnknownRecord> = {
+    [K in keyof T & string]: T[K] extends UnknownRecord ? Store<T[K]> : State<T[K]>;
+} & StoreEventTarget<T> & {
+    [Symbol.toStringTag]: 'Store';
+    [Symbol.iterator](): IterableIterator<[string, Signal<T[keyof T]>]>;
+    add<K extends keyof T & string>(key: K, value: T[K]): void;
+    get(): T;
+    remove<K extends keyof T & string>(key: K): void;
+    set(value: T): void;
+    update(updater: (value: T) => T): void;
+    size: State<number>;
+};
+/**
+ * Create a new store with deeply nested reactive properties
+ *
+ * @since 0.15.0
+ * @param {T} initialValue - initial object value of the store
+ * @returns {Store<T>} - new store with reactive properties
+ */
+declare const store: <T extends UnknownRecord>(initialValue: T) => Store<T>;
+/**
+ * Check if the provided value is a Store instance
+ *
+ * @since 0.15.0
+ * @param {unknown} value - value to check
+ * @returns {boolean} - true if the value is a Store instance, false otherwise
+ */
+declare const isStore: <T extends UnknownRecord>(value: unknown) => value is Store<T>;
+export { TYPE_STORE, isStore, store, type Store, type StoreAddEvent, type StoreChangeEvent, type StoreRemoveEvent, type StoreEventMap, };

package/types/src/util.d.ts

@@ -0,0 +1,15 @@
+declare const isNumber: (value: unknown) => value is number;
+declare const isString: (value: unknown) => value is string;
+declare const isFunction: <T>(fn: unknown) => fn is (...args: unknown[]) => T;
+declare const isAsyncFunction: <T>(fn: unknown) => fn is (...args: unknown[]) => Promise<T>;
+declare const isObjectOfType: <T>(value: unknown, type: string) => value is T;
+declare const isRecord: <T extends Record<string, unknown>>(value: unknown) => value is T;
+declare const isPrimitive: (value: unknown) => boolean;
+declare const arrayToRecord: <T extends unknown & {}>(array: T[]) => Record<string, 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 class CircularDependencyError extends Error {
+    constructor(where: string);
+}
+export { isNumber, isString, isFunction, isAsyncFunction, isObjectOfType, isRecord, isPrimitive, arrayToRecord, hasMethod, isAbortError, toError, CircularDependencyError, };

package/types/test-new-effect.d.ts

@@ -0,0 +1 @@
+export {};

package/src/effect.d.ts

@@ -1,17 +0,0 @@
-import { type Signal, type SignalValues } from './signal';
-import { type Cleanup } from './scheduler';
-type EffectMatcher<S extends Signal<{}>[]> = {
-    signals: S;
-    ok: (...values: SignalValues<S>) => void | Cleanup;
-    err?: (...errors: Error[]) => void | Cleanup;
-    nil?: () => void | Cleanup;
-};
-/**
- * Define what happens when a reactive state changes
- *
- * @since 0.1.0
- * @param {EffectMatcher<S> | (() => void | Cleanup)} matcher - effect matcher or callback
- * @returns {Cleanup} - cleanup function for the effect
- */
-declare function effect<S extends Signal<{}>[]>(matcher: EffectMatcher<S> | (() => void | Cleanup)): Cleanup;
-export { type EffectMatcher, effect };

package/src/signal.d.ts

@@ -1,26 +0,0 @@
-import { type ComputedCallback, isComputedCallback } from './computed';
-type Signal<T extends {}> = {
-    get(): T;
-};
-type MaybeSignal<T extends {}> = T | Signal<T> | ComputedCallback<T>;
-type SignalValues<S extends Signal<{}>[]> = {
-    [K in keyof S]: S[K] extends Signal<infer T> ? T : never;
-};
-declare const UNSET: any;
-/**
- * Check whether a value is a Signal or not
- *
- * @since 0.9.0
- * @param {unknown} value - value to check
- * @returns {boolean} - true if value is a Signal, false otherwise
- */
-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 {MaybeSignal<T>} value - value to convert to a Signal
- * @returns {Signal<T>} - converted Signal
- */
-declare const toSignal: <T extends {}>(value: MaybeSignal<T>) => Signal<T>;
-export { type Signal, type MaybeSignal, type SignalValues, UNSET, isSignal, isComputedCallback, toSignal, };

package/src/util.d.ts

@@ -1,7 +0,0 @@
-declare const isFunction: <T>(value: unknown) => value is (...args: unknown[]) => T;
-declare const isObjectOfType: <T>(value: unknown, type: string) => value is T;
-declare const toError: (reason: unknown) => Error;
-declare class CircularDependencyError extends Error {
-    constructor(where: string);
-}
-export { isFunction, isObjectOfType, toError, CircularDependencyError };