diff --git a/packages/ts/react-signals/src/FullStackSignal.ts b/packages/ts/react-signals/src/FullStackSignal.ts index 07c569d638..d7b9f99317 100644 --- a/packages/ts/react-signals/src/FullStackSignal.ts +++ b/packages/ts/react-signals/src/FullStackSignal.ts @@ -6,11 +6,22 @@ import { createSetStateEvent, type StateEvent } from './events.js'; const ENDPOINT = 'SignalsHandler'; /** - * A return type for signal operations. + * A return type for signal operations that exposes a `result` property of type + * `Promise`, that resolves when the operation is completed. It allows defining + * callbacks to be run after the operation is completed, or error handling when + * the operation fails. + * + * @example + * ```ts + * const sharedName = NameService.sharedName({ defaultValue: '' }); + * sharedName.replace('John').result + * .then(() => console.log('Name updated successfully')) + * .catch((error) => console.error('Failed to update the name:', error)); + * ``` */ -export type Operation = { +export interface Operation { result: Promise; -}; +} /** * An abstraction of a signal that tracks the number of subscribers, and calls @@ -215,7 +226,7 @@ export abstract class FullStackSignal extends DependencyTrackingSignal { } >(); - // creates the obejct to be returned by operations to allow defining callbacks + // creates the object to be returned by operations to allow defining callbacks protected [$createOperation]({ id, promise }: { id?: string; promise?: Promise }): Operation { const thens = this.#operationPromises; const promises: Array> = []; diff --git a/packages/ts/react-signals/src/ListSignal.ts b/packages/ts/react-signals/src/ListSignal.ts index 95c8c86922..ab8a1187f2 100644 --- a/packages/ts/react-signals/src/ListSignal.ts +++ b/packages/ts/react-signals/src/ListSignal.ts @@ -154,6 +154,7 @@ export class ListSignal extends CollectionSignal /** * Inserts a new value at the end of the list. * @param value - The value to insert. + * @returns An operation object that allows to perform additional actions. */ insertLast(value: T): Operation { const event = createInsertLastStateEvent(value); @@ -164,6 +165,7 @@ export class ListSignal extends CollectionSignal /** * Removes the given item from the list. * @param item - The item to remove. + * @returns An operation object that allows to perform additional actions. */ remove(item: ValueSignal): Operation { const entryToRemove = this.#values.get(item.id); diff --git a/packages/ts/react-signals/src/ValueSignal.ts b/packages/ts/react-signals/src/ValueSignal.ts index e2dce28d36..a78aa2b648 100644 --- a/packages/ts/react-signals/src/ValueSignal.ts +++ b/packages/ts/react-signals/src/ValueSignal.ts @@ -44,6 +44,7 @@ export class ValueSignal extends FullStackSignal { * `replace` method instead. * * @param value - The new value. + * @returns An operation object that allows to perform additional actions. */ set(value: T): Operation { const { parentClientSignalId } = this.server.config; @@ -81,7 +82,8 @@ export class ValueSignal extends FullStackSignal { * * @param callback - The function that is applied on the current value to * produce the new value. - * @returns An operation object that allows to perform additional actions, including cancellation. + * @returns An operation object that allows to perform additional actions, + * including cancellation. */ update(callback: (value: T) => T): OperationSubscription { const newValue = callback(this.value); diff --git a/packages/ts/react-signals/src/index.ts b/packages/ts/react-signals/src/index.ts index f207840225..d77e5a6aac 100644 --- a/packages/ts/react-signals/src/index.ts +++ b/packages/ts/react-signals/src/index.ts @@ -8,3 +8,4 @@ export { ValueSignal } from './ValueSignal.js'; export { ListSignal } from './ListSignal.js'; export type { OperationSubscription } from './ValueSignal.js'; export { FullStackSignal } from './FullStackSignal.js'; +export type { Operation } from './FullStackSignal.js';