feat: support Route Resolver uid, lang, and brokenRoute options (…

…#258) * feat: support Route Resolver `uid` and `brokenRoute` options * refactor: match API * docs: update property descriptions Co-authored-by: lihbr <[email protected]>
prismicio · Aug 23, 2022 · 22f01c6 · 22f01c6
1 parent 10c2c5a
commit 22f01c6
Show file tree

Hide file tree

Showing 5 changed files with 101 additions and 4 deletions.
diff --git a/src/buildQueryURL.ts b/src/buildQueryURL.ts
@@ -84,6 +84,16 @@ export interface QueryParams {
 	 * {@link https://prismic.io/docs/core-concepts/link-resolver-route-resolver#route-resolver}
 	 */
 	routes?: Route | string | (Route | string)[];
+
+	/**
+	 * The `brokenRoute` option allows you to define the route populated in the
+	 * `url` property for broken Link or Content Relationship fields. A broken
+	 * link is a Link or Content Relationship field whose linked document has been
+	 * unpublished or deleted.
+	 *
+	 * {@link https://prismic.io/docs/core-concepts/link-resolver-route-resolver#route-resolver}
+	 */
+	brokenRoute?: string;
 }
 
 /**

diff --git a/src/client.ts b/src/client.ts
@@ -139,13 +139,23 @@ export type ClientConfig = {
 	 */
 	routes?: NonNullable<BuildQueryURLArgs["routes"]>;
 
+	/**
+	 * The `brokenRoute` option allows you to define the route populated in the
+	 * `url` property for broken Link or Content Relationship fields. A broken
+	 * link is a Link or Content Relationship field whose linked document has been
+	 * unpublished or deleted.
+	 *
+	 * {@link https://prismic.io/docs/core-concepts/link-resolver-route-resolver#route-resolver}
+	 */
+	brokenRoute?: NonNullable<BuildQueryURLArgs["brokenRoute"]>;
+
 	/**
 	 * Default parameters that will be sent with each query. These parameters can
 	 * be overridden on each query if needed.
 	 */
 	defaultParams?: Omit<
 		BuildQueryURLArgs,
-		"ref" | "integrationFieldsRef" | "accessToken" | "routes"
+		"ref" | "integrationFieldsRef" | "accessToken" | "routes" | "brokenRoute"
 	>;
 
 	/**
@@ -314,6 +324,16 @@ export class Client<
 	 */
 	routes?: NonNullable<BuildQueryURLArgs["routes"]>;
 
+	/**
+	 * The `brokenRoute` option allows you to define the route populated in the
+	 * `url` property for broken Link or Content Relationship fields. A broken
+	 * link is a Link or Content Relationship field whose linked document has been
+	 * unpublished or deleted.
+	 *
+	 * {@link https://prismic.io/docs/core-concepts/link-resolver-route-resolver#route-resolver}
+	 */
+	brokenRoute?: NonNullable<BuildQueryURLArgs["brokenRoute"]>;
+
 	/**
 	 * The function used to make network requests to the Prismic REST API. In
 	 * environments where a global `fetch` function does not exist, such as
@@ -382,6 +402,7 @@ export class Client<
 
 		this.accessToken = options.accessToken;
 		this.routes = options.routes;
+		this.brokenRoute = options.brokenRoute;
 		this.defaultParams = options.defaultParams;
 
 		if (options.ref) {
@@ -1235,6 +1256,7 @@ export class Client<
 			ref,
 			integrationFieldsRef,
 			routes: params.routes || this.routes,
+			brokenRoute: params.brokenRoute || this.brokenRoute,
 			accessToken: params.accessToken || this.accessToken,
 		});
 	}

diff --git a/src/types.ts b/src/types.ts
@@ -140,17 +140,52 @@ export interface Ordering {
 /**
  * A `routes` parameter that determines how a document's URL field is resolved.
  *
+ * @example With a document's UID field.
+ *
+ * ```ts
+ * {
+ * 	"type": "page",
+ * 	"path": "/:uid"
+ * }
+ * ```
+ *
+ * @example With a Content Relationship `parent` field.
+ *
+ * ```ts
+ * {
+ * 	"type": "page",
+ * 	"path": "/:parent?/:uid",
+ * 	"resolvers": {
+ * 		"parent": "parent"
+ * 	}
+ * }
+ * ```
+ *
  * {@link https://prismic.io/docs/core-concepts/link-resolver-route-resolver#route-resolver}
  */
 export interface Route {
 	/**
 	 * The Custom Type of the document.
 	 */
 	type: string;
+
+	/**
+	 * A specific UID to which this route definition is scoped. The route is only
+	 * defined for the document whose UID matches the given UID.
+	 */
+	uid?: string;
+
+	/**
+	 * A specific language to which this route definition is scoped. The route is
+	 * only defined for documents whose language matches the given language.
+	 */
+	lang?: string;
+
 	/**
 	 * The resolved path of the document with optional placeholders.
 	 */
 	path: string;
+
 	/**
 	 * An object that lists the API IDs of the Content Relationships in the route.
 	 */

diff --git a/test/buildQueryURL.test.ts b/test/buildQueryURL.test.ts
@@ -54,10 +54,11 @@ it("supports params", () => {
 				lang: "lang",
 				orderings: "orderings",
 				routes: "routes",
+				brokenRoute: "brokenRoute",
 			}),
 		),
 	).toBe(
-		"https://qwerty.cdn.prismic.io/api/v2/documents/search?ref=ref&access_token=accessToken&pageSize=1&page=1&after=after&fetch=fetch&fetchLinks=fetchLinks&graphQuery=graphQuery&lang=lang&orderings=[orderings]&routes=routes",
+		"https://qwerty.cdn.prismic.io/api/v2/documents/search?ref=ref&access_token=accessToken&pageSize=1&page=1&after=after&fetch=fetch&fetchLinks=fetchLinks&graphQuery=graphQuery&lang=lang&orderings=[orderings]&routes=routes&brokenRoute=brokenRoute",
 	);
 });
 

diff --git a/test/client.test.ts b/test/client.test.ts
@@ -389,17 +389,27 @@ it("ignores the integration fields ref if the repository provides a null value",
 it("uses client-provided routes in queries", async (ctx) => {
 	const queryResponse = prismicM.api.query({ seed: ctx.meta.name });
 
-	const routes = [
+	const routes: prismic.Route[] = [
 		{
 			type: "page",
+			path: "/:uid",
+		},
+		{
+			type: "page",
+			uid: "home",
 			path: "/",
 		},
+		{
+			type: "page",
+			uid: "home",
+			lang: "it-it",
+			path: "/it",
+		},
 	];
 
 	mockPrismicRestAPIV2({
 		queryResponse,
 		queryRequiredParams: {
-			// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
 			routes: JSON.stringify(routes),
 		},
 		ctx,
@@ -411,6 +421,25 @@ it("uses client-provided routes in queries", async (ctx) => {
 	expect(res).toStrictEqual(queryResponse);
 });
 
+it("uses client-provided brokenRoute in queries", async (ctx) => {
+	const queryResponse = prismicM.api.query({ seed: ctx.meta.name });
+
+	const brokenRoute = "/404";
+
+	mockPrismicRestAPIV2({
+		queryResponse,
+		queryRequiredParams: {
+			brokenRoute,
+		},
+		ctx,
+	});
+
+	const client = createTestClient({ clientConfig: { brokenRoute } });
+	const res = await client.get();
+
+	expect(res).toStrictEqual(queryResponse);
+});
+
 it("throws ForbiddenError if access token is invalid for repository metadata", async (ctx) => {
 	mockPrismicRestAPIV2({
 		accessToken: "token",