fix: clarify TS Docs for better DX (#3076)

* fix: clarify TS Docs for better DX Fixes #2936 * add TS Docs example --------- Co-authored-by: Luciano Vernaschi <[email protected]>
vaadin · Jan 13, 2025 · b5626fa · b5626fa
1 parent d0f59c8
commit b5626fa
Show file tree

Hide file tree

Showing 4 changed files with 21 additions and 5 deletions.
diff --git 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<void>;
-};
+}
 
 /**
  * An abstraction of a signal that tracks the number of subscribers, and calls
@@ -215,7 +226,7 @@ export abstract class FullStackSignal<T> extends DependencyTrackingSignal<T> {
     }
   >();
 
-  // 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<void> }): Operation {
     const thens = this.#operationPromises;
     const promises: Array<Promise<void>> = [];

diff --git a/packages/ts/react-signals/src/ListSignal.ts b/packages/ts/react-signals/src/ListSignal.ts
@@ -154,6 +154,7 @@ export class ListSignal<T> extends CollectionSignal<ReadonlyArray<ValueSignal<T>
   /**
    * 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<T> extends CollectionSignal<ReadonlyArray<ValueSignal<T>
   /**
    * 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<T>): 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
@@ -44,6 +44,7 @@ export class ValueSignal<T> extends FullStackSignal<T> {
    * `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<T> extends FullStackSignal<T> {
    *
    * @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
@@ -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';