@arraypress/storage-r2 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Sherlock / ArrayPress Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,135 @@
+# @arraypress/storage-r2
+
+Cloudflare R2 native bindings adapter for `@arraypress/storage`. Uses the R2Bucket API directly for zero SDK overhead and maximum performance on Cloudflare Workers.
+
+Works in Cloudflare Workers only (requires R2 bucket binding).
+
+## Installation
+
+```bash
+npm install @arraypress/storage-r2 @arraypress/storage
+```
+
+## Usage
+
+### With Hono on Cloudflare Workers
+
+```ts
+import { Hono } from 'hono';
+import { createR2Storage } from '@arraypress/storage-r2';
+
+type Env = {
+  Bindings: {
+    BUCKET: R2Bucket;
+  };
+};
+
+const app = new Hono<Env>();
+
+app.post('/upload', async (c) => {
+  const storage = createR2Storage({
+    bucket: c.env.BUCKET,
+    publicUrl: 'https://media.mystore.com',
+  });
+
+  const body = await c.req.arrayBuffer();
+
+  const result = await storage.upload({
+    key: 'uploads/photo.jpg',
+    body: new Uint8Array(body),
+    contentType: 'image/jpeg',
+  });
+
+  return c.json(result);
+});
+
+app.get('/download/:key{.+}', async (c) => {
+  const storage = createR2Storage({ bucket: c.env.BUCKET });
+  const file = await storage.download(c.req.param('key'));
+
+  if (!file) return c.notFound();
+
+  return new Response(file.body, {
+    headers: {
+      'Content-Type': file.contentType,
+      'Content-Length': String(file.size),
+    },
+  });
+});
+
+export default app;
+```
+
+### wrangler.toml
+
+```toml
+[[r2_buckets]]
+binding = "BUCKET"
+bucket_name = "my-bucket"
+```
+
+### Content-Addressed Uploads (Deduplication)
+
+```ts
+import { createR2Storage } from '@arraypress/storage-r2';
+import { contentHash, contentAddressedKey } from '@arraypress/storage';
+
+const storage = createR2Storage({ bucket: env.BUCKET });
+const hash = await contentHash(fileBuffer);
+const key = contentAddressedKey(hash, 'photo.jpg', 'media/');
+
+if (!await storage.exists(key)) {
+  await storage.upload({ key, body: fileBuffer, contentType: 'image/jpeg' });
+}
+```
+
+### Multipart Uploads
+
+```ts
+const storage = createR2Storage({ bucket: env.BUCKET });
+
+const mpu = await storage.createMultipartUpload('large-file.zip', {
+  contentType: 'application/zip',
+});
+
+const part1 = await mpu.uploadPart(1, chunk1);
+const part2 = await mpu.uploadPart(2, chunk2);
+
+await mpu.complete([part1, part2]);
+```
+
+### Signed URLs
+
+R2 native bindings have limited presigned URL support. If you need reliable signed URLs (e.g. for direct client uploads), use `@arraypress/storage-s3` with R2's S3-compatible API instead.
+
+```ts
+// May throw StorageError with code 'NOT_SUPPORTED' depending on environment
+const signed = await storage.getSignedDownloadUrl({
+  key: 'uploads/photo.jpg',
+  expiresIn: 3600,
+});
+```
+
+## API Reference
+
+### `createR2Storage(options): Storage`
+
+Creates a Storage adapter backed by Cloudflare R2 native bindings.
+
+#### Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `bucket` | `R2Bucket` | Yes | R2 bucket binding from `wrangler.toml` |
+| `publicUrl` | `string` | No | Public URL prefix for `getPublicUrl()` (e.g. `'https://media.mystore.com'`) |
+
+### Re-exported from `@arraypress/storage`
+
+- `Storage` interface
+- `StorageError` class
+- `contentHash()`, `contentAddressedKey()`, `safeDisposition()` helpers
+- All type definitions
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@arraypress/storage-r2",
+  "version": "1.0.0",
+  "description": "Cloudflare R2 native bindings adapter for @arraypress/storage",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "peerDependencies": {
+    "@arraypress/storage": "^1.0.0"
+  },
+  "keywords": [
+    "storage",
+    "r2",
+    "cloudflare",
+    "workers",
+    "adapter"
+  ],
+  "author": "ArrayPress",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/arraypress/storage-r2"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,11 @@
+import type { Storage } from '@arraypress/storage';
+
+export interface R2StorageOptions {
+  /** R2 bucket binding from wrangler.toml. */
+  bucket: R2Bucket;
+  /** Public URL prefix for the bucket (e.g. 'https://media.mystore.com'). Used by getPublicUrl(). */
+  publicUrl?: string;
+}
+
+/** Create a Storage adapter backed by Cloudflare R2 native bindings. */
+export function createR2Storage(options: R2StorageOptions): Storage;

package/src/index.js

@@ -0,0 +1,156 @@
+/**
+ * @arraypress/storage-r2
+ *
+ * Cloudflare R2 native bindings adapter for @arraypress/storage.
+ * Uses R2Bucket API directly — faster than S3 API, no SDK overhead.
+ *
+ * @module @arraypress/storage-r2
+ */
+
+import { StorageError } from '@arraypress/storage';
+
+/**
+ * Create a Storage adapter backed by Cloudflare R2 native bindings.
+ *
+ * @param {import('./index.d.ts').R2StorageOptions} options
+ * @returns {import('@arraypress/storage').Storage}
+ */
+export function createR2Storage(options) {
+  const { bucket, publicUrl } = options;
+
+  return {
+    async upload({ key, body, contentType, metadata }) {
+      const object = await bucket.put(key, body, {
+        httpMetadata: { contentType },
+        ...(metadata ? { customMetadata: metadata } : {}),
+      });
+      return {
+        key,
+        size: object?.size ?? 0,
+        etag: object?.etag,
+      };
+    },
+
+    async download(key) {
+      const object = await bucket.get(key);
+      if (!object) return null;
+      return {
+        body: object.body,
+        contentType: object.httpMetadata?.contentType || 'application/octet-stream',
+        size: object.size,
+        etag: object.etag,
+      };
+    },
+
+    async delete(key) {
+      await bucket.delete(key);
+    },
+
+    async exists(key) {
+      const head = await bucket.head(key);
+      return head !== null;
+    },
+
+    async list(options = {}) {
+      const { prefix, limit, cursor } = options;
+      const result = await bucket.list({
+        ...(prefix ? { prefix } : {}),
+        ...(limit ? { limit } : {}),
+        ...(cursor ? { cursor } : {}),
+      });
+      return {
+        objects: result.objects.map((obj) => ({
+          key: obj.key,
+          size: obj.size,
+          lastModified: obj.uploaded ? new Date(obj.uploaded) : undefined,
+          etag: obj.etag,
+        })),
+        truncated: result.truncated,
+        cursor: result.truncated ? result.cursor : undefined,
+      };
+    },
+
+    async getSignedDownloadUrl({ key, expiresIn = 3600 }) {
+      try {
+        // R2 presigned URL support — may not be available in all environments
+        const url = await /** @type {any} */ (bucket).createPresignedUrl(key, {
+          expiresIn,
+          httpMethod: 'GET',
+        });
+        if (!url) throw new Error('No URL returned');
+        return {
+          url,
+          expiresAt: new Date(Date.now() + expiresIn * 1000),
+        };
+      } catch {
+        throw new StorageError(
+          'R2 presigned download URLs are not supported in this environment',
+          'NOT_SUPPORTED',
+        );
+      }
+    },
+
+    async getSignedUploadUrl({ key, contentType, expiresIn = 3600 }) {
+      try {
+        const url = await /** @type {any} */ (bucket).createPresignedUrl(key, {
+          expiresIn,
+          httpMethod: 'PUT',
+        });
+        if (!url) throw new Error('No URL returned');
+        return {
+          url,
+          expiresAt: new Date(Date.now() + expiresIn * 1000),
+        };
+      } catch {
+        throw new StorageError(
+          'R2 presigned upload URLs are not supported in this environment',
+          'NOT_SUPPORTED',
+        );
+      }
+    },
+
+    getPublicUrl(key) {
+      if (!publicUrl) {
+        throw new StorageError(
+          'publicUrl not configured — pass it to createR2Storage()',
+          'NOT_SUPPORTED',
+        );
+      }
+      return `${publicUrl.replace(/\/$/, '')}/${key}`;
+    },
+
+    async createMultipartUpload(key, options = {}) {
+      const { contentType, metadata } = options;
+      const mpu = await bucket.createMultipartUpload(key, {
+        ...(contentType ? { httpMetadata: { contentType } } : {}),
+        ...(metadata ? { customMetadata: metadata } : {}),
+      });
+      return wrapMultipartUpload(mpu, key);
+    },
+
+    resumeMultipartUpload(key, uploadId) {
+      const mpu = bucket.resumeMultipartUpload(key, uploadId);
+      return wrapMultipartUpload(mpu, key);
+    },
+  };
+}
+
+/**
+ * Wrap an R2 multipart upload object into the Storage MultipartUpload interface.
+ */
+function wrapMultipartUpload(mpu, key) {
+  return {
+    uploadId: mpu.uploadId,
+    key,
+    async uploadPart(partNumber, body) {
+      const part = await mpu.uploadPart(partNumber, body);
+      return { partNumber: part.partNumber, etag: part.etag };
+    },
+    async complete(parts) {
+      await mpu.complete(parts);
+    },
+    async abort() {
+      await mpu.abort();
+    },
+  };
+}