From fdc7b888d7c24507711de6aa58216865b4f143a3 Mon Sep 17 00:00:00 2001
From: taefi <taefi.soroosh@gmail.com>
Date: Fri, 20 Dec 2024 14:17:42 +0200
Subject: [PATCH 1/2] fix: clarify TS Docs for better DX

Fixes #2936
---
 packages/ts/react-signals/src/FullStackSignal.ts | 7 +++++--
 packages/ts/react-signals/src/ListSignal.ts      | 2 ++
 packages/ts/react-signals/src/ValueSignal.ts     | 4 +++-
 3 files changed, 10 insertions(+), 3 deletions(-)

diff --git a/packages/ts/react-signals/src/FullStackSignal.ts b/packages/ts/react-signals/src/FullStackSignal.ts
index 8b4abe3cb1..539d5bc0d5 100644
--- a/packages/ts/react-signals/src/FullStackSignal.ts
+++ b/packages/ts/react-signals/src/FullStackSignal.ts
@@ -14,7 +14,10 @@ interface VaadinGlobal {
 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.
  */
 export type Operation = {
   result: Promise<void>;
@@ -230,7 +233,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
index 5c26d4b273..9e7e2d4940 100644
--- a/packages/ts/react-signals/src/ListSignal.ts
+++ b/packages/ts/react-signals/src/ListSignal.ts
@@ -151,6 +151,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);
@@ -161,6 +162,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
index 83114ab11a..ea72a234ff 100644
--- 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);

From 1ad5a4a79c9444d5f33fdd360c21cf24b833dcc2 Mon Sep 17 00:00:00 2001
From: taefi <taefi.soroosh@gmail.com>
Date: Wed, 8 Jan 2025 16:24:18 +0200
Subject: [PATCH 2/2] add TS Docs example

---
 packages/ts/react-signals/src/FullStackSignal.ts | 14 +++++++++++---
 packages/ts/react-signals/src/index.ts           |  1 +
 2 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/packages/ts/react-signals/src/FullStackSignal.ts b/packages/ts/react-signals/src/FullStackSignal.ts
index 07e8ae96a3..d7b9f99317 100644
--- a/packages/ts/react-signals/src/FullStackSignal.ts
+++ b/packages/ts/react-signals/src/FullStackSignal.ts
@@ -7,13 +7,21 @@ const ENDPOINT = 'SignalsHandler';
 
 /**
  * A return type for signal operations that exposes a `result` property of type
- * Promise, that resolves when the operation is completed. It allows defining
+ * `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
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';