feat: restore ref methods and scope release methods

src/client.ts

@@ -129,6 +129,17 @@ const findRef = (refs: Ref[], predicate: (ref: Ref) => boolean): Ref => {
   return ref
 }
 
+/**
+ * Returns a copy of an array of refs without the master ref, is present.
+ *
+ * @param refs A list of refs.
+ *
+ * @returns `refs` without the master ref, is present.
+ */
+const onlyReleaseRefs = (refs: Ref[]): Ref[] => {
+  return refs.filter((ref) => !ref.isMasterRef)
+}
+
 /**
  * Creates a Prismic client that can be used to query a repository.
  *
@@ -652,42 +663,42 @@ export class Client {
   }
 
   /**
-   * Returns a list of all Releases for the Prismic repository. Releases are used to group content changes.
+   * Returns a list of all refs for the Prismic repository.
    *
-   * All repositories will have at least one Release pointing to the latest published content called the "master ref".
+   * Refs are used to identify which version of the repository's content should be queried. All repositories will have at least one ref pointing to the latest published content called the "master ref".
    *
-   * @returns A list of all Releases for the Prismic repository.
+   * @returns A list of all refs for the Prismic repository.
    */
-  async getReleases(): Promise<Ref[]> {
+  async getRefs(): Promise<Ref[]> {
     const res = await this.fetch<Repository>(this.endpoint)
 
     return res.refs
   }
 
   /**
-   * Returns a Release for the Prismic repository with a matching ID.
+   * Returns a ref for the Prismic repository with a matching ID.
    *
-   * @param id ID of the Release.
+   * @param id ID of the ref.
    *
-   * @returns The Release with a matching ID, if it exists.
+   * @returns The ref with a matching ID, if it exists.
    */
-  async getReleaseById(id: string): Promise<Ref> {
-    const releases = await this.getReleases()
+  async getRefById(id: string): Promise<Ref> {
+    const refs = await this.getRefs()
 
-    return findRef(releases, (ref) => ref.id === id)
+    return findRef(refs, (ref) => ref.id === id)
   }
 
   /**
-   * Returns a Release for the Prismic repository with a matching label.
+   * Returns a ref for the Prismic repository with a matching label.
    *
    * @param label Label of the ref.
    *
    * @returns The ref with a matching label, if it exists.
    */
-  async getReleaseByLabel(label: string): Promise<Ref> {
-    const releases = await this.getReleases()
+  async getRefByLabel(label: string): Promise<Ref> {
+    const refs = await this.getRefs()
 
-    return findRef(releases, (ref) => ref.label === label)
+    return findRef(refs, (ref) => ref.label === label)
   }
 
   /**
@@ -696,9 +707,44 @@ export class Client {
    * @returns The repository's master ref.
    */
   async getMasterRef(): Promise<Ref> {
+    const refs = await this.getRefs()
+
+    return findRef(refs, (ref) => ref.isMasterRef)
+  }
+
+  /**
+   * Returns a list of all Releases for the Prismic repository. Releases are used to group content changes before publishing.
+   *
+   * @returns A list of all Releases for the Prismic repository.
+   */
+  async getReleases(): Promise<Ref[]> {
+    return onlyReleaseRefs(await this.getRefs())
+  }
+
+  /**
+   * Returns a Release for the Prismic repository with a matching ID.
+   *
+   * @param id ID of the Release.
+   *
+   * @returns The Release with a matching ID, if it exists.
+   */
+  async getReleaseById(id: string): Promise<Ref> {
     const releases = await this.getReleases()
 
-    return findRef(releases, (ref) => ref.isMasterRef)
+    return findRef(releases, (ref) => ref.id === id)
+  }
+
+  /**
+   * Returns a Release for the Prismic repository with a matching label.
+   *
+   * @param label Label of the ref.
+   *
+   * @returns The ref with a matching label, if it exists.
+   */
+  async getReleaseByLabel(label: string): Promise<Ref> {
+    const releases = await this.getReleases()
+
+    return findRef(releases, (ref) => ref.label === label)
   }
 
   /**

test/client-getRefByID.test.ts

@@ -0,0 +1,33 @@
+import test from 'ava'
+import * as mswNode from 'msw/node'
+
+import { createMockRepositoryHandler } from './__testutils__/createMockRepositoryHandler'
+import { createRepositoryResponse } from './__testutils__/createRepositoryResponse'
+import { createTestClient } from './__testutils__/createClient'
+import { createRef } from './__testutils__/createRef'
+
+const server = mswNode.setupServer()
+test.before(() => server.listen({ onUnhandledRequest: 'error' }))
+test.after(() => server.close())
+
+test('returns a ref by ID', async (t) => {
+  const ref1 = createRef(true)
+  const ref2 = createRef(false)
+  const response = createRepositoryResponse({ refs: [ref1, ref2] })
+  server.use(createMockRepositoryHandler(t, response))
+
+  const client = createTestClient(t)
+  const res = await client.getRefById(ref2.id)
+
+  t.deepEqual(res, ref2)
+})
+
+test('throws if ref could not be found', async (t) => {
+  server.use(createMockRepositoryHandler(t))
+
+  const client = createTestClient(t)
+
+  await t.throwsAsync(async () => await client.getRefById('non-existant'), {
+    message: /could not be found/i,
+  })
+})

test/client-getRefByLabel.test.ts

@@ -0,0 +1,33 @@
+import test from 'ava'
+import * as mswNode from 'msw/node'
+
+import { createMockRepositoryHandler } from './__testutils__/createMockRepositoryHandler'
+import { createRepositoryResponse } from './__testutils__/createRepositoryResponse'
+import { createTestClient } from './__testutils__/createClient'
+import { createRef } from './__testutils__/createRef'
+
+const server = mswNode.setupServer()
+test.before(() => server.listen({ onUnhandledRequest: 'error' }))
+test.after(() => server.close())
+
+test('returns a ref by label', async (t) => {
+  const ref1 = createRef(true)
+  const ref2 = createRef(false)
+  const response = createRepositoryResponse({ refs: [ref1, ref2] })
+  server.use(createMockRepositoryHandler(t, response))
+
+  const client = createTestClient(t)
+  const res = await client.getRefByLabel(ref2.label)
+
+  t.deepEqual(res, ref2)
+})
+
+test('throws if ref could not be found', async (t) => {
+  server.use(createMockRepositoryHandler(t))
+
+  const client = createTestClient(t)
+
+  await t.throwsAsync(async () => await client.getRefByLabel('non-existant'), {
+    message: /could not be found/i,
+  })
+})

test/client-getRefs.test.ts

@@ -0,0 +1,20 @@
+import test from 'ava'
+import * as mswNode from 'msw/node'
+
+import { createMockRepositoryHandler } from './__testutils__/createMockRepositoryHandler'
+import { createRepositoryResponse } from './__testutils__/createRepositoryResponse'
+import { createTestClient } from './__testutils__/createClient'
+
+const server = mswNode.setupServer()
+test.before(() => server.listen({ onUnhandledRequest: 'error' }))
+test.after(() => server.close())
+
+test('returns all refs', async (t) => {
+  const response = createRepositoryResponse()
+  server.use(createMockRepositoryHandler(t, response))
+
+  const client = createTestClient(t)
+  const res = await client.getRefs()
+
+  t.deepEqual(res, response.refs)
+})

test/client-getReleases.test.ts

@@ -16,5 +16,8 @@ test('returns all Releases', async (t) => {
   const client = createTestClient(t)
   const res = await client.getReleases()
 
-  t.deepEqual(res, response.refs)
+  t.deepEqual(
+    res,
+    response.refs.filter((ref) => !ref.isMasterRef),
+  )
 })