chore: add custom-timeout example (#205)

examples/custom-timeout/README.md

@@ -0,0 +1,37 @@
+# Timeout Requests
+
+This example shows how to use `@prismicio/client` with an explicit request timeout limit. `fetch()` implementations typically have their own default timeout limit. Chrome, for example, times out requests after 300 seconds, while Firefox times outs at 90 seconds.
+
+If you want to customize this value, you can use an [AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) to cancel (or "abort") a request after a certain duration.
+
+In this example, we're using a library called [node-fetch][node-fetch] to make
+network requests. This is a nearly drop-in Node.js implementation for the
+browser's `fetch()` function.
+
+We're also using a library called [abort-controller][abort-controller] to cancel network requests. This is only necessary in Node.js versions older than 14.17.0. Anything newer, or when using in the browser, does not require this library.
+
+**Note**: This example is written for Node.js. If you plan to use this code for
+the browser, you can remove `node-fetch` and `abort-controller` from the example.
+
+```diff
+  import * as prismic from '@prismicio/client'
+- import fetch from 'node-fetch'
+- import { AbortController } from "abort-controller";
+```
+
+## How to run the example
+
+```sh
+# Clone the repository to your computer
+git clone https://github.com/prismicio/prismic-client.git
+cd prismic-client/examples/custom-timeout
+
+# Install the dependencies
+npm install
+
+# Run the example
+node index.js
+```
+
+[node-fetch]: https://github.com/node-fetch/node-fetch
+[abort-controller]: https://github.com/mysticatea/abort-controller

examples/custom-timeout/index.js

@@ -0,0 +1,52 @@
+import * as prismic from "@prismicio/client";
+import fetch, { AbortError } from "node-fetch";
+
+// AbortController was added in node v14.17.0 globally. If you are using a node
+// version >=14.17.0, or are not in a node environment, remove this line.
+import { AbortController } from "abort-controller";
+
+const endpoint = prismic.getEndpoint("qwerty");
+const client = prismic.createClient(endpoint, {
+	fetch: async (url, options) => {
+		// Create an AbortController. This will be used to cancel the
+		// `fetch()` request if it does not resolve within the given
+		// timespan.
+		const controller = new AbortController();
+
+		// After 1ms, cancel the `fetch()` request.
+		// 1ms is used to force a timeout. In a real-world scenario,
+		// something like 3000ms is more appropriate.
+		const timeoutId = setTimeout(() => controller.abort(), 1);
+
+		// Fetch the requested URL with the AbortController. If
+		// `controller.abort()` is called, the `fetch()` request will
+		// be cancelled.
+		const res = await fetch(url, {
+			signal: controller.signal,
+			...options,
+		});
+
+		// We must stop the timeout once the `fetch()` request is
+		// complete.
+		clearTimeout(timeoutId);
+
+		return res;
+	},
+});
+
+// This query will throw if it does not resolve within the timeout duration.
+const articles = await client.getAllByType("article");
+console.info(articles);
+// => A list of all `article` documents
+
+// If you want to handle timeouts, you can check the error's type.
+try {
+	const articles = await client.getAllByType("article");
+	console.info(articles);
+} catch (error) {
+	if (error instanceof AbortError) {
+		console.error("The request timed out.");
+	} else {
+		throw error;
+	}
+}

examples/custom-timeout/package.json

@@ -0,0 +1,8 @@
+{
+	"type": "module",
+	"dependencies": {
+		"@prismicio/client": "alpha",
+		"abort-controller": "^3.0.0",
+		"node-fetch": "^3.1.0"
+	}
+}