feat(blob): allow folder creation

packages/blob/src/index.ts

@@ -22,8 +22,8 @@ export type { PutBlobResult, PutCommandOptions } from './put';
  *
  * If you want to upload from the browser directly, check out the documentation for client uploads: https://vercel.com/docs/storage/vercel-blob/using-blob-sdk#client-uploads
  *
- * @param pathname - The pathname to upload the blob to. This includes the filename.
- * @param body - The contents of your blob. This has to be a supported fetch body type https://developer.mozilla.org/en-US/docs/Web/API/fetch#body.
+ * @param pathname - The pathname to upload the blob to. For file upload this includes the filename. Pathnames that end with a slash are treated as folder creations.
+ * @param body - The contents of your blob. This has to be either a supported fetch body type https://developer.mozilla.org/en-US/docs/Web/API/fetch#body or undefined for folder creations.
  * @param options - Additional options like `token` or `contentType`.
  */
 export const put = createPutMethod<PutCommandOptions>({

packages/blob/src/put.ts

@@ -42,26 +42,42 @@ export function createPutMethod<
   getToken?: (pathname: string, options: T) => Promise<string>;
   extraChecks?: (options: T) => void;
 }) {
-  return async function put(
-    pathname: string,
-    body:
-      | string
-      | Readable
-      | Blob
-      | ArrayBuffer
-      | FormData
-      | ReadableStream
-      | File,
-    options?: T,
+  return async function put<TPath extends string>(
+    pathname: TPath,
+    bodyOrOptions: TPath extends `${string}/`
+      ? T
+      :
+          | string
+          | Readable
+          | Blob
+          | ArrayBuffer
+          | FormData
+          | ReadableStream
+          | File,
+    optionsInput?: T,
   ): Promise<PutBlobResult> {
     if (!pathname) {
       throw new BlobError('pathname is required');
     }
 
-    if (!body) {
+    const isEmptyFolder = pathname.endsWith('/');
+
+    // avoid using the options as body
+    const body = isEmptyFolder ? undefined : (bodyOrOptions as BodyInit);
+
+    // when no body is required options are the second argument
+    const options = isEmptyFolder ? (bodyOrOptions as T) : optionsInput;
+
+    // prevent empty bodies for files
+    if (!body && !isEmptyFolder) {
       throw new BlobError('body is required');
     }
 
+    // runtime check for non TS users that provide all three args
+    if (bodyOrOptions && optionsInput && isEmptyFolder) {
+      throw new BlobError('body is not allowed for creating empty folders');
+    }
+
     if (!options) {
       throw new BlobError('missing options, see usage');
     }
@@ -105,7 +121,7 @@ export function createPutMethod<
 
     const blobApiResponse = await fetch(getApiUrl(`/${pathname}`), {
       method: 'PUT',
-      body: body as BodyInit,
+      body,
       headers,
       // required in order to stream some body types to Cloudflare
       // currently only supported in Node.js, we may have to feature detect this

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

@@ -32,6 +32,7 @@ async function run(): Promise<void> {
     weirdCharactersExample(),
     copyTextFile(),
     listFolders(),
+    createFolder(),
   ]);
 
   await Promise.all(
@@ -291,3 +292,15 @@ async function listFolders() {
 
   return blob.url;
 }
+
+async function createFolder() {
+  const start = Date.now();
+
+  const blob = await vercelBlob.put('foolder/file.txt', '', {
+    access: 'public',
+  });
+
+  console.log('create folder example:', blob, `(${Date.now() - start}ms)`);
+
+  return blob.url;
+}