feat: add getDeployStore method

Author: eduardoboucas

README.md

@@ -126,25 +126,23 @@ know whether an item is still relevant or safe to delete.
 But sometimes it's useful to have data pegged to a specific deploy, and shift to the platform the responsibility of
 managing that data — keep it as long as the deploy is around, and wipe it if the deploy is deleted.
 
-You can opt-in to this behavior by supplying a `deployID` instead of a `name` to the `getStore` method.
+You can opt-in to this behavior by creating the store using the `getDeployStore` method.
 
 ```ts
 import { assert } from 'node:assert'
 
-import { getStore } from '@netlify/blobs'
+import { getDeployStore } from '@netlify/blobs'
 
 // Using API access
-const store1 = getStore({
+const store1 = getDeployStore({
   deployID: 'MY_DEPLOY_ID',
   token: 'MY_API_TOKEN',
 })
 
 await store1.set('my-key', 'my value')
 
 // Using environment-based configuration
-const store2 = getStore({
-  deployID: 'MY_DEPLOY_ID',
-})
+const store2 = getDeployStore()
 
 assert.equal(await store2.get('my-key'), 'my value')
 ```

src/client.ts

@@ -1,30 +1,6 @@
-import { Buffer } from 'node:buffer'
-import { env } from 'node:process'
-
 import { fetchAndRetry } from './retry.ts'
 import { BlobInput, Fetcher, HTTPMethod } from './types.ts'
 
-/**
- * The name of the environment variable that holds the context in a Base64,
- * JSON-encoded object. If we ever need to change the encoding or the shape
- * of this object, we should bump the version and create a new variable, so
- * that the client knows how to consume the data and can advise the user to
- * update the client if needed.
- */
-export const NETLIFY_CONTEXT_VARIABLE = 'NETLIFY_BLOBS_CONTEXT'
-
-export interface Context {
-  apiURL?: string
-  edgeURL?: string
-  siteID?: string
-  token?: string
-}
-
-interface PopulatedContext extends Context {
-  siteID: string
-  token: string
-}
-
 interface MakeStoreRequestOptions {
   body?: BlobInput | null
   headers?: Record<string, string>
@@ -33,59 +9,45 @@ interface MakeStoreRequestOptions {
   storeName: string
 }
 
+export interface ClientOptions {
+  apiURL?: string
+  edgeURL?: string
+  fetch?: Fetcher
+  siteID: string
+  token: string
+}
+
 export class Client {
-  private context?: Context
+  private apiURL?: string
+  private edgeURL?: string
   private fetch?: Fetcher
+  private siteID: string
+  private token: string
 
-  constructor(context?: Context, fetch?: Fetcher) {
-    this.context = context ?? {}
+  constructor({ apiURL, edgeURL, fetch, siteID, token }: ClientOptions) {
+    this.apiURL = apiURL
+    this.edgeURL = edgeURL
     this.fetch = fetch
-  }
-
-  private static getEnvironmentContext() {
-    if (!env[NETLIFY_CONTEXT_VARIABLE]) {
-      return
-    }
-
-    const data = Buffer.from(env[NETLIFY_CONTEXT_VARIABLE], 'base64').toString()
-
-    try {
-      return JSON.parse(data) as Context
-    } catch {
-      // no-op
-    }
-  }
-
-  private getContext() {
-    const context = {
-      ...Client.getEnvironmentContext(),
-      ...this.context,
-    }
-
-    if (!context.siteID || !context.token) {
-      throw new Error(`The blob store is unavailable because it's missing required configuration properties`)
-    }
-
-    return context as PopulatedContext
+    this.siteID = siteID
+    this.token = token
   }
 
   private async getFinalRequest(storeName: string, key: string, method: string) {
-    const context = this.getContext()
     const encodedKey = encodeURIComponent(key)
 
-    if ('edgeURL' in context) {
+    if (this.edgeURL) {
       return {
         headers: {
-          authorization: `Bearer ${context.token}`,
+          authorization: `Bearer ${this.token}`,
         },
-        url: `${context.edgeURL}/${context.siteID}/${storeName}/${encodedKey}`,
+        url: `${this.edgeURL}/${this.siteID}/${storeName}/${encodedKey}`,
       }
     }
 
-    const apiURL = `${context.apiURL ?? 'https://api.netlify.com'}/api/v1/sites/${
-      context.siteID
+    const apiURL = `${this.apiURL ?? 'https://api.netlify.com'}/api/v1/sites/${
+      this.siteID
     }/blobs/${encodedKey}?context=${storeName}`
-    const headers = { authorization: `Bearer ${context.token}` }
+    const headers = { authorization: `Bearer ${this.token}` }
     const fetch = this.fetch ?? globalThis.fetch
     const res = await fetch(apiURL, { headers, method })
 

src/environment.ts

@@ -0,0 +1,50 @@
+import { Buffer } from 'node:buffer'
+import { env } from 'node:process'
+
+/**
+ * The name of the environment variable that holds the context in a Base64,
+ * JSON-encoded object. If we ever need to change the encoding or the shape
+ * of this object, we should bump the version and create a new variable, so
+ * that the client knows how to consume the data and can advise the user to
+ * update the client if needed.
+ */
+const NETLIFY_CONTEXT_VARIABLE = 'NETLIFY_BLOBS_CONTEXT'
+
+/**
+ * The context object that we expect in the environment.
+ */
+export interface EnvironmentContext {
+  apiURL?: string
+  deployID?: string
+  edgeURL?: string
+  siteID?: string
+  token?: string
+}
+
+export const getEnvironmentContext = (): EnvironmentContext => {
+  if (!env[NETLIFY_CONTEXT_VARIABLE]) {
+    return {}
+  }
+
+  const data = Buffer.from(env[NETLIFY_CONTEXT_VARIABLE], 'base64').toString()
+
+  try {
+    return JSON.parse(data) as EnvironmentContext
+  } catch {
+    // no-op
+  }
+
+  return {}
+}
+
+export class MissingBlobsEnvironmentError extends Error {
+  constructor(requiredProperties: string[]) {
+    super(
+      `The environment has not been configured to use Netlify Blobs. To use it manually, supply the following properties when creating a store: ${requiredProperties.join(
+        ', ',
+      )}`,
+    )
+
+    this.name = 'MissingBlobsEnvironmentError'
+  }
+}

src/main.test.ts

@@ -7,7 +7,8 @@ import { describe, test, expect, beforeAll, afterEach } from 'vitest'
 import { MockFetch } from '../test/mock_fetch.js'
 import { streamToString } from '../test/util.js'
 
-import { getStore } from './main.js'
+import { MissingBlobsEnvironmentError } from './environment.js'
+import { getDeployStore, getStore } from './main.js'
 
 beforeAll(async () => {
   if (semver.lt(nodeVersion, '18.0.0')) {
@@ -315,28 +316,6 @@ describe('get', () => {
       expect(mockStore.fulfilled).toBeTruthy()
     })
   })
-
-  test('Throws when the instance is missing required configuration properties', async () => {
-    const { fetch } = new MockFetch()
-
-    globalThis.fetch = fetch
-
-    const blobs1 = getStore('production')
-
-    expect(async () => await blobs1.get(key)).rejects.toThrowError(
-      `The blob store is unavailable because it's missing required configuration properties`,
-    )
-
-    const blobs2 = getStore({
-      name: 'production',
-      token: apiToken,
-      siteID: '',
-    })
-
-    expect(async () => await blobs2.get(key)).rejects.toThrowError(
-      `The blob store is unavailable because it's missing required configuration properties`,
-    )
-  })
 })
 
 describe('set', () => {
@@ -584,28 +563,6 @@ describe('set', () => {
       expect(mockStore.fulfilled).toBeTruthy()
     })
   })
-
-  test('Throws when the instance is missing required configuration properties', async () => {
-    const { fetch } = new MockFetch()
-
-    globalThis.fetch = fetch
-
-    const blobs1 = getStore('production')
-
-    expect(async () => await blobs1.set(key, value)).rejects.toThrowError(
-      `The blob store is unavailable because it's missing required configuration properties`,
-    )
-
-    const blobs2 = getStore({
-      name: 'production',
-      token: apiToken,
-      siteID: '',
-    })
-
-    expect(async () => await blobs2.set(key, value)).rejects.toThrowError(
-      `The blob store is unavailable because it's missing required configuration properties`,
-    )
-  })
 })
 
 describe('setJSON', () => {
@@ -802,28 +759,6 @@ describe('delete', () => {
       expect(mockStore.fulfilled).toBeTruthy()
     })
   })
-
-  test('Throws when the instance is missing required configuration properties', async () => {
-    const { fetch } = new MockFetch()
-
-    globalThis.fetch = fetch
-
-    const blobs1 = getStore('production')
-
-    expect(async () => await blobs1.delete(key)).rejects.toThrowError(
-      `The blob store is unavailable because it's missing required configuration properties`,
-    )
-
-    const blobs2 = getStore({
-      name: 'production',
-      token: apiToken,
-      siteID: '',
-    })
-
-    expect(async () => await blobs2.delete(key)).rejects.toThrowError(
-      `The blob store is unavailable because it's missing required configuration properties`,
-    )
-  })
 })
 
 describe('Deploy scope', () => {
@@ -843,12 +778,12 @@ describe('Deploy scope', () => {
       .get({
         headers: { authorization: `Bearer ${mockToken}` },
         response: new Response(value),
-        url: `${edgeURL}/${siteID}/${deployID}/${key}`,
+        url: `${edgeURL}/${siteID}/deploy:${deployID}/${key}`,
       })
       .get({
         headers: { authorization: `Bearer ${mockToken}` },
         response: new Response(value),
-        url: `${edgeURL}/${siteID}/${deployID}/${key}`,
+        url: `${edgeURL}/${siteID}/deploy:${deployID}/${key}`,
       })
 
     globalThis.fetch = mockStore.fetch
@@ -879,6 +814,42 @@ describe('Deploy scope', () => {
 
     expect(mockStore.fulfilled).toBeTruthy()
   })
+
+  test('Returns a deploy-scoped store if the `getDeployStore` method is called', async () => {
+    const mockToken = 'some-token'
+    const mockStore = new MockFetch()
+      .get({
+        headers: { authorization: `Bearer ${mockToken}` },
+        response: new Response(value),
+        url: `${edgeURL}/${siteID}/deploy:${deployID}/${key}`,
+      })
+      .get({
+        headers: { authorization: `Bearer ${mockToken}` },
+        response: new Response(value),
+        url: `${edgeURL}/${siteID}/deploy:${deployID}/${key}`,
+      })
+
+    globalThis.fetch = mockStore.fetch
+
+    const context = {
+      deployID,
+      edgeURL,
+      siteID,
+      token: mockToken,
+    }
+
+    env.NETLIFY_BLOBS_CONTEXT = Buffer.from(JSON.stringify(context)).toString('base64')
+
+    const deployStore = getDeployStore()
+
+    const string = await deployStore.get(key)
+    expect(string).toBe(value)
+
+    const stream = await deployStore.get(key, { type: 'stream' })
+    expect(await streamToString(stream as unknown as NodeJS.ReadableStream)).toBe(value)
+
+    expect(mockStore.fulfilled).toBeTruthy()
+  })
 })
 
 describe('Custom `fetch`', () => {
@@ -909,3 +880,20 @@ describe('Custom `fetch`', () => {
     expect(mockStore.fulfilled).toBeTruthy()
   })
 })
+
+describe(`getStore`, () => {
+  test('Throws when the instance is missing required configuration properties', async () => {
+    const { fetch } = new MockFetch()
+
+    globalThis.fetch = fetch
+
+    expect(() => getStore('production')).toThrowError(MissingBlobsEnvironmentError)
+    expect(() =>
+      getStore({
+        name: 'production',
+        token: apiToken,
+        siteID: '',
+      }),
+    ).toThrowError(MissingBlobsEnvironmentError)
+  })
+})

src/main.ts

@@ -1 +1 @@
-export { getStore } from './store.ts'
+export { getDeployStore, getStore } from './store.ts'