chore(docs): Use urlOrPathname when relevant (#859)

* chore(docs): Use urlOrPathname when relevant

* changeset

Author: vvo

.changeset/huge-coats-try.md

@@ -0,0 +1,5 @@
+---
+'@vercel/blob': patch
+---
+
+copy, head and del can receive a blob url or pathname, until now it was not very clear.

packages/blob/src/copy.ts

@@ -16,12 +16,12 @@ export interface CopyBlobResult {
  * Copies a blob to another location in your store.
  * Detailed documentation can be found here: https://vercel.com/docs/vercel-blob/using-blob-sdk#copy-a-blob
  *
- * @param fromUrl - The blob URL to copy. You can only copy blobs that are in the store, that your 'BLOB_READ_WRITE_TOKEN' has access to.
+ * @param fromUrlOrPathname - The blob URL (or pathname) to copy. You can only copy blobs that are in the store, that your 'BLOB_READ_WRITE_TOKEN' has access to.
  * @param toPathname - The pathname to copy the blob to. This includes the filename.
  * @param options - Additional options. The copy method will not preserve any metadata configuration (e.g.: 'cacheControlMaxAge') of the source blob. If you want to copy the metadata, you need to define it here again.
  */
 export async function copy(
-  fromUrl: string,
+  fromUrlOrPathname: string,
   toPathname: string,
   options: CopyCommandOptions,
 ): Promise<CopyBlobResult> {
@@ -67,7 +67,10 @@ export async function copy(
     headers['x-cache-control-max-age'] = options.cacheControlMaxAge.toString();
   }
 
-  const params = new URLSearchParams({ pathname: toPathname, fromUrl });
+  const params = new URLSearchParams({
+    pathname: toPathname,
+    fromUrl: fromUrlOrPathname,
+  });
 
   const response = await requestApi<CopyBlobResult>(
     `?${params.toString()}`,

packages/blob/src/del.ts

@@ -5,19 +5,21 @@ import type { BlobCommandOptions } from './helpers';
  * Deletes one or multiple blobs from your store.
  * Detailed documentation can be found here: https://vercel.com/docs/vercel-blob/using-blob-sdk#delete-a-blob
  *
- * @param url - Blob url or array of blob urls that identify the blobs to be deleted. You can only delete blobs that are located in a store, that your 'BLOB_READ_WRITE_TOKEN' has access to.
+ * @param urlOrPathname - Blob url (or pathname) to delete. You can pass either a single value or an array of values. You can only delete blobs that are located in a store, that your 'BLOB_READ_WRITE_TOKEN' has access to.
  * @param options - Additional options for the request.
  */
 export async function del(
-  url: string[] | string,
+  urlOrPathname: string[] | string,
   options?: BlobCommandOptions,
 ): Promise<void> {
   await requestApi(
     '/delete',
     {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ urls: Array.isArray(url) ? url : [url] }),
+      body: JSON.stringify({
+        urls: Array.isArray(urlOrPathname) ? urlOrPathname : [urlOrPathname],
+      }),
       signal: options?.abortSignal,
     },
     options,

packages/blob/src/head.ts

@@ -54,14 +54,14 @@ interface HeadBlobApiResponse extends Omit<HeadBlobResult, 'uploadedAt'> {
  * Fetches metadata of a blob object.
  * Detailed documentation can be found here: https://vercel.com/docs/vercel-blob/using-blob-sdk#get-blob-metadata
  *
- * @param url - Blob url to lookup.
+ * @param urlOrPathname - Blob url or pathname to lookup.
  * @param options - Additional options for the request.
  */
 export async function head(
-  url: string,
+  urlOrPathname: string,
   options?: BlobCommandOptions,
 ): Promise<HeadBlobResult> {
-  const searchParams = new URLSearchParams({ url });
+  const searchParams = new URLSearchParams({ url: urlOrPathname });
 
   const response = await requestApi<HeadBlobApiResponse>(
     `?${searchParams.toString()}`,

test/next/src/app/vercel/blob/script.mts

@@ -17,6 +17,22 @@ console.log('=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*');
 console.log();
 
 async function run(): Promise<void> {
+  let count = 0;
+  let hasMore = true;
+  let cursor: string | undefined;
+  while (hasMore) {
+    // eslint-disable-next-line no-await-in-loop -- [@vercel/style-guide@5 migration]
+    const listResult = await vercelBlob.list({
+      cursor,
+    });
+    if (listResult.blobs.length > 0) {
+      await vercelBlob.del(listResult.blobs.map((blob) => blob.url));
+    }
+    hasMore = listResult.hasMore;
+    cursor = listResult.cursor;
+    count += listResult.blobs.length;
+  }
+
   const urls = await Promise.all([
     textFileExample(),
     textFileNoRandomSuffixExample(),
@@ -33,7 +49,7 @@ async function run(): Promise<void> {
     createFolder(),
     manualMultipartUpload(),
     manualMultipartUploader(),
-    // cancelPut(),
+    cancelPut(),
 
     // The following stream examples will fail when targeting the local api-blob because the server doesn't buffer
     // the request body, so we have no idea of the size of the file we need to put in S3
@@ -61,19 +77,21 @@ async function run(): Promise<void> {
   );
 
   // list all blobs
-  let count = 0;
-  let hasMore = true;
-  let cursor: string | undefined;
+  count = 0;
+  hasMore = true;
   while (hasMore) {
     // eslint-disable-next-line no-await-in-loop -- [@vercel/style-guide@5 migration]
     const listResult = await vercelBlob.list({
       cursor,
     });
+    console.log(listResult);
     hasMore = listResult.hasMore;
     cursor = listResult.cursor;
     count += listResult.blobs.length;
   }
 
+  console.log(filteredUrls, 'filtered urls');
+
   console.log(count, 'blobs in this store');
 
   await Promise.all(filteredUrls.map((url) => vercelBlob.del(url)));
@@ -92,10 +110,16 @@ async function textFileExample(): Promise<string> {
     },
   );
   const head = await vercelBlob.head(blob.url);
-  console.log(head);
+  console.log('URL head', head);
+  console.log(
+    'pathname head',
+    await vercelBlob.head(
+      `some/new-folder/file-with-chars%20!'()@@{}[]-#?file.txt`,
+    ),
+  );
   const copy = await vercelBlob.copy(
-    blob.url,
-    `some/even-new-folder/file-with-chars%20!'()@@{}[]-#?file.txt`,
+    `some/new-folder/file-with-chars%20!'()@@{}[]-#?file.txt`,
+    `YO.txt`,
     {
       access: 'public',
     },