@zeix/cause-effect 0.18.0 → 0.18.1

package/test/memo.test.ts

@@ -1,6 +1,9 @@
 import { describe, expect, test } from 'bun:test'
 import {
+	batch,
+	createEffect,
 	createMemo,
+	createScope,
 	createState,
 	isMemo,
 	isState,
@@ -377,4 +380,195 @@ describe('Memo', () => {
 			}).toThrow('[Memo] Signal value cannot be null or undefined')
 		})
 	})
+
+	describe('options.watched', () => {
+		test('should call watched on first effect access', () => {
+			let watchedCount = 0
+			const externalValue = 1
+
+			const memo = createMemo(() => externalValue, {
+				value: 0,
+				watched: _invalidate => {
+					watchedCount++
+					return () => {}
+				},
+			})
+
+			expect(watchedCount).toBe(0)
+
+			const dispose = createScope(() => {
+				createEffect(() => {
+					void memo.get()
+				})
+			})
+
+			expect(watchedCount).toBe(1)
+			dispose()
+		})
+
+		test('should call cleanup when last effect stops watching', () => {
+			let cleanedUp = false
+			const externalValue = 1
+
+			const memo = createMemo(() => externalValue, {
+				value: 0,
+				watched: _invalidate => {
+					return () => {
+						cleanedUp = true
+					}
+				},
+			})
+
+			const dispose = createScope(() => {
+				createEffect(() => {
+					void memo.get()
+				})
+			})
+
+			expect(cleanedUp).toBe(false)
+			dispose()
+			expect(cleanedUp).toBe(true)
+		})
+
+		test('should recompute memo when invalidate is called', () => {
+			let externalValue = 10
+			let computeCount = 0
+			let invalidate!: () => void
+
+			const memo = createMemo(
+				() => {
+					computeCount++
+					return externalValue
+				},
+				{
+					value: 0,
+					watched: inv => {
+						invalidate = inv
+						return () => {}
+					},
+				},
+			)
+
+			let observed = 0
+			const dispose = createScope(() => {
+				createEffect(() => {
+					observed = memo.get()
+				})
+			})
+
+			expect(observed).toBe(10)
+			expect(computeCount).toBe(1)
+
+			externalValue = 20
+			invalidate()
+			expect(observed).toBe(20)
+			expect(computeCount).toBe(2)
+
+			dispose()
+		})
+
+		test('should defer flush when invalidate is called inside batch', () => {
+			let externalValue = 1
+			let invalidate!: () => void
+
+			const memo = createMemo(() => externalValue, {
+				value: 0,
+				watched: inv => {
+					invalidate = inv
+					return () => {}
+				},
+			})
+
+			let observed = 0
+			const dispose = createScope(() => {
+				createEffect(() => {
+					observed = memo.get()
+				})
+			})
+
+			expect(observed).toBe(1)
+
+			batch(() => {
+				externalValue = 2
+				invalidate()
+				expect(observed).toBe(1) // not yet flushed
+			})
+			expect(observed).toBe(2) // flushed after batch
+
+			dispose()
+		})
+
+		test('should re-activate watched after cleanup and new effect access', () => {
+			let watchedCount = 0
+			const externalValue = 1
+
+			const memo = createMemo(() => externalValue, {
+				value: 0,
+				watched: _invalidate => {
+					watchedCount++
+					return () => {}
+				},
+			})
+
+			const dispose1 = createScope(() => {
+				createEffect(() => {
+					void memo.get()
+				})
+			})
+			expect(watchedCount).toBe(1)
+			dispose1()
+
+			const dispose2 = createScope(() => {
+				createEffect(() => {
+					void memo.get()
+				})
+			})
+			expect(watchedCount).toBe(2)
+			dispose2()
+		})
+
+		test('should work with both tracked dependencies and watched', () => {
+			const source = createState(1)
+			let externalValue = 100
+			let computeCount = 0
+			let invalidate!: () => void
+
+			const memo = createMemo(
+				() => {
+					computeCount++
+					return source.get() + externalValue
+				},
+				{
+					value: 0,
+					watched: inv => {
+						invalidate = inv
+						return () => {}
+					},
+				},
+			)
+
+			let observed = 0
+			const dispose = createScope(() => {
+				createEffect(() => {
+					observed = memo.get()
+				})
+			})
+
+			expect(observed).toBe(101)
+			expect(computeCount).toBe(1)
+
+			// Tracked dependency triggers recomputation
+			source.set(2)
+			expect(observed).toBe(102)
+			expect(computeCount).toBe(2)
+
+			// External invalidation triggers recomputation
+			externalValue = 200
+			invalidate()
+			expect(observed).toBe(202)
+			expect(computeCount).toBe(3)
+
+			dispose()
+		})
+	})
 })

package/test/task.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from 'bun:test'
 import {
 	createEffect,
 	createMemo,
+	createScope,
 	createState,
 	createTask,
 	isMemo,
@@ -392,4 +393,137 @@ describe('Task', () => {
 			}).toThrow('[Task] Signal value cannot be null or undefined')
 		})
 	})
+
+	describe('options.watched', () => {
+		test('should call watched on first effect access', () => {
+			let watchedCount = 0
+
+			const task = createTask(
+				async () => {
+					await wait(10)
+					return 1
+				},
+				{
+					value: 0,
+					watched: _invalidate => {
+						watchedCount++
+						return () => {}
+					},
+				},
+			)
+
+			expect(watchedCount).toBe(0)
+
+			const dispose = createScope(() => {
+				createEffect(() => {
+					void task.get()
+				})
+			})
+
+			expect(watchedCount).toBe(1)
+			dispose()
+		})
+
+		test('should call cleanup when last effect stops watching', () => {
+			let cleanedUp = false
+
+			const task = createTask(
+				async () => {
+					await wait(10)
+					return 1
+				},
+				{
+					value: 0,
+					watched: _invalidate => {
+						return () => {
+							cleanedUp = true
+						}
+					},
+				},
+			)
+
+			const dispose = createScope(() => {
+				createEffect(() => {
+					void task.get()
+				})
+			})
+
+			expect(cleanedUp).toBe(false)
+			dispose()
+			expect(cleanedUp).toBe(true)
+		})
+
+		test('should re-execute task when invalidate is called', async () => {
+			let externalValue = 10
+			let computeCount = 0
+			let invalidate!: () => void
+
+			const task = createTask(
+				async () => {
+					computeCount++
+					await wait(10)
+					return externalValue
+				},
+				{
+					value: 0,
+					watched: inv => {
+						invalidate = inv
+						return () => {}
+					},
+				},
+			)
+
+			let observed = 0
+			const dispose = createScope(() => {
+				createEffect(() => {
+					observed = task.get()
+				})
+			})
+
+			await wait(20)
+			expect(observed).toBe(10)
+			expect(computeCount).toBe(1)
+
+			externalValue = 20
+			invalidate()
+			await wait(20)
+			expect(observed).toBe(20)
+			expect(computeCount).toBe(2)
+
+			dispose()
+		})
+
+		test('should abort in-flight task when invalidate is called', async () => {
+			let wasAborted = false
+			let invalidate!: () => void
+
+			const task = createTask(
+				async (_prev, signal) => {
+					await wait(100)
+					if (signal.aborted) wasAborted = true
+					return 1
+				},
+				{
+					value: 0,
+					watched: inv => {
+						invalidate = inv
+						return () => {}
+					},
+				},
+			)
+
+			const dispose = createScope(() => {
+				createEffect(() => {
+					void task.get()
+				})
+			})
+
+			await wait(10) // task is in-flight
+			invalidate() // should trigger re-execution, aborting the current one
+			await wait(110)
+			expect(wasAborted).toBe(true)
+
+			dispose()
+		})
+	})
 })

package/types/index.d.ts

@@ -1,15 +1,15 @@
 /**
  * @name Cause & Effect
- * @version 0.18.0
+ * @version 0.18.1
  * @author Esther Brunner
  */
 export { CircularDependencyError, type Guard, InvalidCallbackError, InvalidSignalValueError, NullishSignalValueError, RequiredOwnerError, UnsetSignalValueError, } from './src/errors';
-export { batch, type Cleanup, type ComputedOptions, createScope, type EffectCallback, type MemoCallback, type Signal, type SignalOptions, SKIP_EQUALITY, type TaskCallback, untrack, } from './src/graph';
-export { type Collection, type CollectionCallback, type CollectionOptions, createCollection, type DeriveCollectionCallback, isCollection, } from './src/nodes/collection';
+export { batch, type Cleanup, type ComputedOptions, createScope, type EffectCallback, type MaybeCleanup, type MemoCallback, type Signal, type SignalOptions, SKIP_EQUALITY, type TaskCallback, untrack, } from './src/graph';
+export { type Collection, type CollectionCallback, type CollectionChanges, type CollectionOptions, createCollection, type DeriveCollectionCallback, isCollection, } from './src/nodes/collection';
 export { createEffect, type MatchHandlers, type MaybePromise, match, } from './src/nodes/effect';
-export { createList, type DiffResult, isEqual, isList, type KeyConfig, type List, type ListOptions, } from './src/nodes/list';
+export { createList, isEqual, isList, type KeyConfig, type List, type ListOptions, } from './src/nodes/list';
 export { createMemo, isMemo, type Memo } from './src/nodes/memo';
-export { createSensor, isSensor, type Sensor, type SensorCallback, } from './src/nodes/sensor';
+export { createSensor, isSensor, type Sensor, type SensorCallback, type SensorOptions, } from './src/nodes/sensor';
 export { createState, isState, type State, type UpdateCallback, } from './src/nodes/state';
 export { createStore, isStore, type Store, type StoreOptions, } from './src/nodes/store';
 export { createTask, isTask, type Task } from './src/nodes/task';

package/types/src/graph.d.ts

@@ -76,6 +76,16 @@ type ComputedOptions<T extends {}> = SignalOptions<T> & {
      * Useful for reducer patterns so that calculations start with a value of correct type.
      */
     value?: T;
+    /**
+     * Optional callback invoked when the signal is first watched by an effect.
+     * Receives an `invalidate` function that marks the signal dirty and triggers re-evaluation.
+     * Must return a cleanup function that is called when the signal is no longer watched.
+     *
+     * This enables lazy resource activation for computed signals that need to
+     * react to external events (e.g. DOM mutations, timers) in addition to
+     * tracked signal dependencies.
+     */
+    watched?: (invalidate: () => void) => Cleanup;
 };
 /**
  * A callback function for memos that computes a value based on the previous value.
@@ -97,7 +107,7 @@ type TaskCallback<T extends {}> = (prev: T | undefined, signal: AbortSignal) =>
 /**
  * A callback function for effects that can perform side effects.
  *
- * @param match - A function to register cleanup callbacks that will be called before the effect re-runs or is disposed
+ * @returns An optional cleanup function that will be called before the effect re-runs or is disposed
  */
 type EffectCallback = () => MaybeCleanup;
 declare const TYPE_STATE = "State";
@@ -205,4 +215,4 @@ declare function untrack<T>(fn: () => T): T;
  * ```
  */
 declare function createScope(fn: () => MaybeCleanup): Cleanup;
-export { type Cleanup, type ComputedOptions, type EffectCallback, type EffectNode, type MaybeCleanup, type MemoCallback, type MemoNode, type Scope, type Signal, type SignalOptions, type SinkNode, type StateNode, type TaskCallback, type TaskNode, activeOwner, activeSink, batch, batchDepth, createScope, DEFAULT_EQUALITY as defaultEquals, SKIP_EQUALITY, FLAG_CLEAN, FLAG_DIRTY, flush, link, propagate, refresh, registerCleanup, runCleanup, runEffect, setState, trimSources, TYPE_COLLECTION, TYPE_LIST, TYPE_MEMO, TYPE_SENSOR, TYPE_STATE, TYPE_STORE, TYPE_TASK, unlink, untrack, };
+export { type Cleanup, type ComputedOptions, type EffectCallback, type EffectNode, type MaybeCleanup, type MemoCallback, type MemoNode, type Scope, type Signal, type SignalOptions, type SinkNode, type StateNode, type TaskCallback, type TaskNode, activeOwner, activeSink, batch, batchDepth, createScope, DEFAULT_EQUALITY, SKIP_EQUALITY, FLAG_CLEAN, FLAG_DIRTY, flush, link, propagate, refresh, registerCleanup, runCleanup, runEffect, setState, trimSources, TYPE_COLLECTION, TYPE_LIST, TYPE_MEMO, TYPE_SENSOR, TYPE_STATE, TYPE_STORE, TYPE_TASK, unlink, untrack, };

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

@@ -1,5 +1,5 @@
 import { type Cleanup, type Signal } from '../graph';
-import { type DiffResult, type KeyConfig, type List } from './list';
+import { type KeyConfig, type List } from './list';
 type CollectionSource<T extends {}> = List<T> | Collection<T>;
 type DeriveCollectionCallback<T extends {}, U extends {}> = ((sourceValue: U) => T) | ((sourceValue: U, abort: AbortSignal) => Promise<T>);
 type Collection<T extends {}> = {
@@ -16,12 +16,17 @@ type Collection<T extends {}> = {
     deriveCollection<R extends {}>(callback: (sourceValue: T, abort: AbortSignal) => Promise<R>): Collection<R>;
     readonly length: number;
 };
+type CollectionChanges<T> = {
+    add?: T[];
+    change?: T[];
+    remove?: T[];
+};
 type CollectionOptions<T extends {}> = {
     value?: T[];
     keyConfig?: KeyConfig<T>;
-    createItem?: (key: string, value: T) => Signal<T>;
+    createItem?: (value: T) => Signal<T>;
 };
-type CollectionCallback = (applyChanges: (changes: DiffResult) => void) => Cleanup;
+type CollectionCallback<T extends {}> = (apply: (changes: CollectionChanges<T>) => void) => Cleanup;
 /**
  * Creates a derived Collection from a List or another Collection with item-level memoization.
  * Sync callbacks use createMemo, async callbacks use createTask.
@@ -36,15 +41,15 @@ declare function deriveCollection<T extends {}, U extends {}>(source: Collection
 declare function deriveCollection<T extends {}, U extends {}>(source: CollectionSource<U>, callback: (sourceValue: U, abort: AbortSignal) => Promise<T>): Collection<T>;
 /**
  * Creates an externally-driven Collection with a watched lifecycle.
- * Items are managed by the start callback via `applyChanges(diffResult)`.
+ * Items are managed via the `applyChanges(changes)` helper passed to the watched callback.
  * The collection activates when first accessed by an effect and deactivates when no longer watched.
  *
  * @since 0.18.0
- * @param start - Callback invoked when the collection starts being watched, receives applyChanges helper
+ * @param watched - Callback invoked when the collection starts being watched, receives applyChanges helper
  * @param options - Optional configuration including initial value, key generation, and item signal creation
  * @returns A read-only Collection signal
  */
-declare function createCollection<T extends {}>(start: CollectionCallback, options?: CollectionOptions<T>): Collection<T>;
+declare function createCollection<T extends {}>(watched: CollectionCallback<T>, options?: CollectionOptions<T>): Collection<T>;
 /**
  * Checks if a value is a Collection signal.
  *
@@ -61,4 +66,4 @@ declare function isCollection<T extends {}>(value: unknown): value is Collection
  * @returns True if the value is a List or Collection
  */
 declare function isCollectionSource<T extends {}>(value: unknown): value is CollectionSource<T>;
-export { createCollection, deriveCollection, isCollection, isCollectionSource, type Collection, type CollectionCallback, type CollectionOptions, type CollectionSource, type DeriveCollectionCallback, };
+export { createCollection, deriveCollection, isCollection, isCollectionSource, type Collection, type CollectionCallback, type CollectionChanges, type CollectionOptions, type CollectionSource, type DeriveCollectionCallback, };

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

@@ -8,7 +8,7 @@ type DiffResult = {
     change: UnknownRecord;
     remove: UnknownRecord;
 };
-type KeyConfig<T> = string | ((item: T) => string);
+type KeyConfig<T> = string | ((item: T) => string | undefined);
 type ListOptions<T extends {}> = {
     keyConfig?: KeyConfig<T>;
     watched?: () => Cleanup;
@@ -19,8 +19,8 @@ type List<T extends {}> = {
     [Symbol.iterator](): IterableIterator<State<T>>;
     readonly length: number;
     get(): T[];
-    set(newValue: T[]): void;
-    update(fn: (oldValue: T[]) => T[]): void;
+    set(next: T[]): void;
+    update(fn: (prev: T[]) => T[]): void;
     at(index: number): State<T> | undefined;
     keys(): IterableIterator<string>;
     byKey(key: string): State<T> | undefined;
@@ -37,23 +37,24 @@ type List<T extends {}> = {
  * 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
+ * @param a - First value to compare
+ * @param b - Second value to compare
+ * @param visited - Set to track visited objects for cycle detection
+ * @returns Whether the two values are equal
  */
+declare function isEqual<T>(a: T, b: T, visited?: WeakSet<object>): boolean;
 /** Shallow equality check for string arrays */
 declare function keysEqual(a: string[], b: string[]): boolean;
-declare function isEqual<T>(a: T, b: T, visited?: WeakSet<object>): boolean;
+declare function getKeyGenerator<T extends {}>(keyConfig?: KeyConfig<T>): [(item: T) => string, boolean];
 /**
  * Creates a reactive list with stable keys and per-item reactivity.
  *
  * @since 0.18.0
- * @param initialValue - Initial array of items
+ * @param value - Initial array of items
  * @param options - Optional configuration for key generation and watch lifecycle
  * @returns A List signal
  */
-declare function createList<T extends {}>(initialValue: T[], options?: ListOptions<T>): List<T>;
+declare function createList<T extends {}>(value: T[], options?: ListOptions<T>): List<T>;
 /**
  * Checks if a value is a List signal.
  *
@@ -62,4 +63,4 @@ declare function createList<T extends {}>(initialValue: T[], options?: ListOptio
  * @returns True if the value is a List
  */
 declare function isList<T extends {}>(value: unknown): value is List<T>;
-export { type DiffResult, type KeyConfig, type List, type ListOptions, type UnknownRecord, createList, isEqual, isList, keysEqual, TYPE_LIST, };
+export { type DiffResult, type KeyConfig, type List, type ListOptions, type UnknownRecord, createList, isEqual, isList, getKeyGenerator, keysEqual, TYPE_LIST, };

package/types/src/nodes/memo.d.ts

@@ -25,6 +25,12 @@ type Memo<T extends {}> = {
  * @template T - The type of value computed by the memo
  * @param fn - The computation function that receives the previous value
  * @param options - Optional configuration for the memo
+ * @param options.value - Optional initial value for reducer patterns
+ * @param options.equals - Optional equality function. Defaults to strict equality (`===`)
+ * @param options.guard - Optional type guard to validate values
+ * @param options.watched - Optional callback invoked when the memo is first watched by an effect.
+ *   Receives an `invalidate` function to mark the memo dirty and trigger recomputation.
+ *   Must return a cleanup function called when no effects are watching.
  * @returns A Memo object with a get() method
  *
  * @example

package/types/src/nodes/sensor.d.ts

@@ -1,4 +1,4 @@
-import { type Cleanup, type ComputedOptions } from '../graph';
+import { type Cleanup, type SignalOptions } from '../graph';
 /**
  * A read-only signal that tracks external input and updates a state value as long as it is active.
  *
@@ -8,7 +8,6 @@ type Sensor<T extends {}> = {
     readonly [Symbol.toStringTag]: 'Sensor';
     /**
      * Gets the current value of the sensor.
-     * Updates its state value if the sensor is active.
      * When called inside another reactive context, creates a dependency.
      * @returns The sensor value
      * @throws UnsetSignalValueError If the sensor value is still unset when read.
@@ -22,6 +21,13 @@ type Sensor<T extends {}> = {
  * @param set - A function to set the observed value
  * @returns A cleanup function when the sensor stops being watched
  */
+type SensorOptions<T extends {}> = SignalOptions<T> & {
+    /**
+     * Optional initial value. Avoids `UnsetSignalValueError` on first read
+     * before the watched callback fires.
+     */
+    value?: T;
+};
 type SensorCallback<T extends {}> = (set: (next: T) => void) => Cleanup;
 /**
  * Creates a sensor that tracks external input and updates a state value as long as it is active.
@@ -29,12 +35,12 @@ type SensorCallback<T extends {}> = (set: (next: T) => void) => Cleanup;
  * no longer watched. This lazy activation pattern ensures resources are only consumed when needed.
  *
  * @since 0.18.0
- * @template T - The type of value stored in the state
- * @param start - The callback function that starts the sensor and returns a cleanup function.
- * @param options - Optional options for the sensor.
+ * @template T - The type of value produced by the sensor
+ * @param watched - The callback invoked when the sensor starts being watched, receives a `set` function and returns a cleanup function.
+ * @param options - Optional configuration for the sensor.
  * @param options.value - Optional initial value. Avoids `UnsetSignalValueError` on first read
- *   before the start callback fires. Essential for the mutable-object observation pattern.
- * @param options.equals - Optional equality function. Defaults to `Object.is`. Use `SKIP_EQUALITY`
+ *   before the watched callback fires. Essential for the mutable-object observation pattern.
+ * @param options.equals - Optional equality function. Defaults to strict equality (`===`). Use `SKIP_EQUALITY`
  *   for mutable objects where the reference stays the same but internal state changes.
  * @param options.guard - Optional type guard to validate values.
  * @returns A read-only sensor signal.
@@ -63,7 +69,7 @@ type SensorCallback<T extends {}> = (set: (next: T) => void) => Cleanup;
  * }, { value: node, equals: SKIP_EQUALITY });
  * ```
  */
-declare function createSensor<T extends {}>(start: SensorCallback<T>, options?: ComputedOptions<T>): Sensor<T>;
+declare function createSensor<T extends {}>(watched: SensorCallback<T>, options?: SensorOptions<T>): Sensor<T>;
 /**
  * Checks if a value is a Sensor signal.
  *
@@ -72,4 +78,4 @@ declare function createSensor<T extends {}>(start: SensorCallback<T>, options?:
  * @returns True if the value is a Sensor
  */
 declare function isSensor<T extends {} = unknown & {}>(value: unknown): value is Sensor<T>;
-export { createSensor, isSensor, type Sensor, type SensorCallback };
+export { createSensor, isSensor, type Sensor, type SensorCallback, type SensorOptions, };

package/types/src/nodes/store.d.ts

@@ -14,8 +14,8 @@ type BaseStore<T extends UnknownRecord> = {
     keys(): IterableIterator<string>;
     byKey<K extends keyof T & string>(key: K): T[K] extends readonly (infer U extends {})[] ? List<U> : T[K] extends UnknownRecord ? Store<T[K]> : T[K] extends unknown & {} ? State<T[K] & {}> : State<T[K] & {}> | undefined;
     get(): T;
-    set(newValue: T): void;
-    update(fn: (oldValue: T) => T): void;
+    set(next: T): void;
+    update(fn: (prev: T) => T): void;
     add<K extends keyof T & string>(key: K, value: T[K]): K;
     remove(key: string): void;
 };
@@ -28,7 +28,7 @@ type Store<T extends UnknownRecord> = BaseStore<T> & {
  * Properties are accessible directly via proxy.
  *
  * @since 0.15.0
- * @param initialValue - Initial object value of the store
+ * @param value - Initial object value of the store
  * @param options - Optional configuration for watch lifecycle
  * @returns A Store with reactive properties
  *
@@ -39,7 +39,7 @@ type Store<T extends UnknownRecord> = BaseStore<T> & {
  * console.log(user.get()); // { name: 'Bob', age: 30 }
  * ```
  */
-declare function createStore<T extends UnknownRecord>(initialValue: T, options?: StoreOptions): Store<T>;
+declare function createStore<T extends UnknownRecord>(value: T, options?: StoreOptions): Store<T>;
 /**
  * Checks if a value is a Store signal.
  *

package/types/src/nodes/task.d.ts

@@ -36,6 +36,12 @@ type Task<T extends {}> = {
  * @template T - The type of value resolved by the task
  * @param fn - The async computation function that receives the previous value and an AbortSignal
  * @param options - Optional configuration for the task
+ * @param options.value - Optional initial value for reducer patterns
+ * @param options.equals - Optional equality function. Defaults to strict equality (`===`)
+ * @param options.guard - Optional type guard to validate values
+ * @param options.watched - Optional callback invoked when the task is first watched by an effect.
+ *   Receives an `invalidate` function to mark the task dirty and trigger re-execution.
+ *   Must return a cleanup function called when no effects are watching.
  * @returns A Task object with get(), isPending(), and abort() methods
  *
  * @example