fix: lift restriction on release perspective name (#1005)

Author: bjoerge

src/config.ts

@@ -28,43 +28,31 @@ function validateApiVersion(apiVersion: string) {
   }
 }
 
+const VALID_PERSPECTIVE = /^[a-z0-9_]+$/i
+
 /**
  * @internal - it may have breaking changes in any release
  */
 export function validateApiPerspective(
   perspective: unknown,
 ): asserts perspective is ClientPerspective {
   if (Array.isArray(perspective)) {
-    for (const perspectiveValue of perspective) {
-      if (perspectiveValue === 'published') {
-        continue
-      }
-      if (perspectiveValue === 'drafts') {
-        continue
-      }
-      if (
-        typeof perspectiveValue === 'string' &&
-        perspectiveValue.startsWith('r') &&
-        perspectiveValue !== 'raw'
-      ) {
-        continue
-      }
+    if (perspective.includes('raw')) {
       throw new TypeError(
-        'Invalid API perspective value, expected `published`, `drafts` or a valid release identifier string',
+        `Invalid API perspective value: "raw". The raw-perspective can not be combined with other perspectives`,
       )
     }
-    return
   }
-  switch (perspective as ClientPerspective) {
-    case 'previewDrafts':
-    case 'drafts':
-    case 'published':
-    case 'raw':
-      return
-    default:
-      throw new TypeError(
-        'Invalid API perspective string, expected `published`, `previewDrafts` or `raw`',
-      )
+
+  const invalid = (Array.isArray(perspective) ? perspective : [perspective]).filter(
+    (perspectiveName) =>
+      typeof perspectiveName !== 'string' || !VALID_PERSPECTIVE.test(perspectiveName),
+  )
+  if (invalid.length > 0) {
+    const formatted = invalid.map((v) => JSON.stringify(v))
+    throw new TypeError(
+      `Invalid API perspective value${invalid.length === 1 ? '' : 's'}: ${formatted.join(', ')}, expected \`published\`, \`drafts\`, \`raw\` or a release identifier string`,
+    )
   }
 }
 

src/csm/resolvePerspectives.ts

@@ -1,5 +1,5 @@
 import {validateApiPerspective} from '../config'
-import type {ReleaseId} from '../types'
+import type {StackablePerspective} from '../types'
 import type {ClientPerspective} from './types'
 
 /**
@@ -9,7 +9,7 @@ import type {ClientPerspective} from './types'
  */
 export function resolvePerspectives(
   perspective: Exclude<ClientPerspective, 'raw'>,
-): ('published' | 'drafts' | ReleaseId)[] {
+): ('published' | 'drafts' | StackablePerspective)[] {
   validateApiPerspective(perspective)
 
   if (Array.isArray(perspective)) {

src/types.ts

@@ -31,16 +31,22 @@ export interface RequestOptions {
   signal?: AbortSignal
 }
 
-/** @public */
+/**
+ * @public
+ * @deprecated – The `r`-prefix is not required, use `string` instead
+ */
 export type ReleaseId = `r${string}`
 
+/** @public */
+export type StackablePerspective = ('published' | 'drafts' | string) & {}
+
 /** @public */
 export type ClientPerspective =
   | 'previewDrafts'
   | 'published'
   | 'drafts'
   | 'raw'
-  | ('published' | 'drafts' | ReleaseId)[]
+  | StackablePerspective[]
 
 /** @public */
 export interface ClientConfig {

test/client.test.ts

@@ -177,30 +177,34 @@ describe('client', async () => {
       expect(() => createClient({projectId: 'abc123', perspective: 'raw'})).not.toThrow(
         /Invalid API perspective/,
       )
+      expect(() => createClient({projectId: 'abc123', perspective: undefined})).not.toThrow(
+        /Invalid API perspective/,
+      )
+      // no whitespace allowed
       // @ts-expect-error -- we want to test that it throws an error
       expect(() => createClient({projectId: 'abc123', perspective: 'preview drafts'})).toThrow(
         /Invalid API perspective/,
       )
 
-      // valid because it begins with `r`
-      const validReleaseIdentifier = 'rfoobar'
+      const validReleaseIdentifier = 'foobar'
       expect(() =>
         createClient({
           projectId: 'abc123',
           perspective: ['published', 'drafts', validReleaseIdentifier],
         }),
       ).not.toThrow(/Invalid API perspective/)
 
-      // special case – "raw" would be a valid release id given that it starts with ´r`
-      // but 'raw' is not possible to use with multiple perspectives and is explicitly
-      // banned by the backend
       expect(() =>
-        createClient({projectId: 'abc123', perspective: ['published', 'drafts', 'raw']}),
+        createClient({
+          projectId: 'abc123',
+          perspective: ['published', 'drafts', 'this is not valid'],
+        }),
       ).toThrow(/Invalid API perspective/)
 
+      // special case – 'raw' can not be combined with multiple perspectives and is explicitly
+      // banned by the backend
       expect(() =>
-        // @ts-expect-error -- we want to test that it throws an error
-        createClient({projectId: 'abc123', perspective: ['XyzAbC']}),
+        createClient({projectId: 'abc123', perspective: ['published', 'drafts', 'raw']}),
       ).toThrow(/Invalid API perspective/)
     })