documentation for @gradio/client (#8483)

* fix param name

* format

* docs

* add changeset

* Update client/js/README.md

Co-authored-by: Hannah <[email protected]>

* add changeset

* Apply suggestions from code review

Co-authored-by: Hannah <[email protected]>

---------

Co-authored-by: gradio-pr-bot <[email protected]>
Co-authored-by: Hannah <[email protected]>

Author: 3 people

.changeset/plain-mice-help.md

@@ -0,0 +1,6 @@
+---
+"@gradio/client": patch
+"gradio": patch
+---
+
+feat:documentation for @gradio/client

client/js/README.md

@@ -154,11 +154,19 @@ const submission = app.submit("/predict", { name: "Chewbacca" });
 
 The `submit` method accepts the same [`endpoint`](#endpoint) and [`payload`](#payload) arguments as `predict`.
 
-The `submit` method does not return a promise and should not be awaited, instead it returns an object with a `on`, `off`, and `cancel` methods.
+The `submit` method does not return a promise and should not be awaited, instead it returns an async iterator with a  `cancel` method.
 
-##### `on`
+##### Accessing values
 
-The `on` method allows you to subscribe to events related to the submitted API request. There are two types of event that can be subscribed to: `"data"` updates and `"status"` updates.
+Iterating the submission allows you to access the events related to the submitted API request. There are two types of events that can be listened for: `"data"` updates and `"status"` updates. By default only the `"data"` event is reported, but you can listen for the `"status"` event by manually passing the events you care about when instantiating the client:
+
+```ts
+import { Client } from "@gradio/client";
+
+const app = await Client.connect("user/space-name", {
+	events: ["data", "status"]
+});
+```
 
 `"data"` updates are issued when the API computes a value, the callback provided as the second argument will be called when such a value is sent to the client. The shape of the data depends on the way the API itself is constructed. This event may fire more than once if that endpoint supports emmitting new values over time.
 
@@ -187,49 +195,26 @@ interface Status {
 }
 ```
 
-Usage of these subscribe callback looks like this:
+Usage looks like this:
 
 ```ts
 import { Client } from "@gradio/client";
 
 const app = await Client.connect("user/space-name");
 const submission = app
 	.submit("/predict", { name: "Chewbacca" })
-	.on("data", (data) => console.log(data))
-	.on("status", (status: Status) => console.log(status));
-```
-
-##### `off`
-
-The `off` method unsubscribes from a specific event of the submitted job and works similarly to `document.removeEventListener`; both the event name and the original callback must be passed in to successfully unsubscribe:
-
-```ts
-import { Client } from "@gradio/client";
 
-const app = await Client.connect("user/space-name");
-const handle_data = (data) => console.log(data);
-
-const submission = app.submit("/predict", { name: "Chewbacca" }).on("data", handle_data);
+	for await (const msg of submission) {
+		if (msg.type === "data") {
+			console.log(msg.data);
+		}
 
-// later
-submission.off("/predict", handle_data);
+		if (msg.type === "status") {
+			console.log(msg);
+		}
+	}
 ```
 
-##### `destroy`
-
-The `destroy` method will remove all subscriptions to a job, regardless of whether or not they are `"data"` or `"status"` events. This is a convenience method for when you do not want to unsubscribe use the `off` method.
-
-```js
-import { Client } from "@gradio/client";
-
-const app = await Client.connect("user/space-name");
-const handle_data = (data) => console.log(data);
-
-const submission = app.submit("/predict", { name: "Chewbacca" }).on("data", handle_data);
-
-// later
-submission.destroy();
-```
 
 ##### `cancel`
 
@@ -241,7 +226,7 @@ import { Client } from "@gradio/client";
 const app = await Client.connect("user/space-name");
 const submission = app
 	.submit("/predict", { name: "Chewbacca" })
-	.on("data", (data) => console.log(data));
+
 
 // later
 

guides/08_gradio-clients-and-lite/02_getting-started-with-the-js-client.md

@@ -84,7 +84,7 @@ const response = await fetch(
 const audio_file = await response.blob();
 
 const app = await Client.duplicate("abidlabs/whisper", { hf_token: "hf_..." });
-const transcription = app.predict("/predict", [audio_file]);
+const transcription = await app.predict("/predict", [audio_file]);
 ```
 
 If you have previously duplicated a Space, re-running `Client.duplicate` will _not_ create a new Space. Instead, the client will attach to the previously-created Space. So it is safe to re-run the `Client.duplicate` method multiple times with the same space.
@@ -202,7 +202,7 @@ const result = await app.predict("/predict", [audio_file]);
 
 ## Using events
 
-If the API you are working with can return results over time, or you wish to access information about the status of a job, you can use the event interface for more flexibility. This is especially useful for iterative endpoints or generator endpoints that will produce a series of values over time as discreet responses.
+If the API you are working with can return results over time, or you wish to access information about the status of a job, you can use the iterable interface for more flexibility. This is especially useful for iterative endpoints or generator endpoints that will produce a series of values over time as discreet responses.
 
 ```js
 import { Client } from "@gradio/client";
@@ -218,12 +218,27 @@ function log_result(payload) {
 const app = await Client.connect("abidlabs/en2fr");
 const job = app.submit("/predict", ["Hello"]);
 
-job.on("data", log_result);
+for await (const message of job) {
+	log_result(message);
+}
 ```
 
 ## Status
 
-The event interface also allows you to get the status of the running job by listening to the `"status"` event. This returns an object with the following attributes: `status` (a human readbale status of the current job, `"pending" | "generating" | "complete" | "error"`), `code` (the detailed gradio code for the job), `position` (the current position of this job in the queue), `queue_size` (the total queue size), `eta` (estimated time this job will complete), `success` (a boolean representing whether the job completed successfully), and `time` ( as `Date` object detailing the time that the status was generated).
+The event interface also allows you to get the status of the running job by instantiating the client with the `events` options passing `status` and `data` as an array:
+
+
+```ts
+import { Client } from "@gradio/client";
+
+const app = await Client.connect("abidlabs/en2fr", {
+	events: ["status", "data"]
+});
+```
+
+This ensures that status messages are also reported to the client.
+
+`status`es are returned as an object with the following attributes: `status` (a human readbale status of the current job, `"pending" | "generating" | "complete" | "error"`), `code` (the detailed gradio code for the job), `position` (the current position of this job in the queue), `queue_size` (the total queue size), `eta` (estimated time this job will complete), `success` (a boolean representing whether the job completed successfully), and `time` ( as `Date` object detailing the time that the status was generated).
 
 ```js
 import { Client } from "@gradio/client";
@@ -234,10 +249,16 @@ function log_status(status) {
 	);
 }
 
-const app = await Client.connect("abidlabs/en2fr");
+const app = await Client.connect("abidlabs/en2fr", {
+	events: ["status", "data"]
+});
 const job = app.submit("/predict", ["Hello"]);
 
-job.on("status", log_status);
+for await (const message of job) {
+	if (message.type === "status") {
+		log_status(message);
+	}
+}
 ```
 
 ## Cancelling Jobs
@@ -259,15 +280,17 @@ If the first job has started processing, then it will not be canceled but the cl
 
 ## Generator Endpoints
 
-Some Gradio API endpoints do not return a single value, rather they return a series of values. You can listen for these values in real time using the event interface:
+Some Gradio API endpoints do not return a single value, rather they return a series of values. You can listen for these values in real time using the iterable interface:
 
 ```js
 import { Client } from "@gradio/client";
 
 const app = await Client.connect("gradio/count_generator");
 const job = app.submit(0, [9]);
 
-job.on("data", (data) => console.log(data));
+for await (const message of job) {
+	console.log(message.data);
+}
 ```
 
 This will log out the values as they are generated by the endpoint.
@@ -280,7 +303,9 @@ import { Client } from "@gradio/client";
 const app = await Client.connect("gradio/count_generator");
 const job = app.submit(0, [9]);
 
-job.on("data", (data) => console.log(data));
+for await (const message of job) {
+	console.log(message.data);
+}
 
 setTimeout(() => {
 	job.cancel();