@arraypress/storage 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,124 @@
+# @arraypress/storage
+
+Storage interface, types, and helper utilities for portable file storage across R2, S3, and local filesystem.
+
+Works in any JavaScript runtime (Cloudflare Workers, Node.js, Deno, Bun, browsers).
+
+## Installation
+
+```bash
+npm install @arraypress/storage
+```
+
+## Usage
+
+This package defines the `Storage` interface that all adapter packages implement. You typically don't use this package directly -- instead, install one of the adapters:
+
+| Adapter | Backend |
+|---------|---------|
+| `@arraypress/storage-r2` | Cloudflare R2 native bindings |
+| `@arraypress/storage-s3` | AWS S3, R2 via S3 API, MinIO |
+| `@arraypress/storage-local` | Local filesystem (Node.js) |
+
+### Storage Interface
+
+Every adapter returns an object implementing this interface:
+
+```ts
+interface Storage {
+  upload(options: UploadOptions): Promise<UploadResult>;
+  download(key: string): Promise<DownloadResult | null>;
+  delete(key: string): Promise<void>;
+  exists(key: string): Promise<boolean>;
+  list(options?: ListOptions): Promise<ListResult>;
+  getSignedDownloadUrl(options: SignedUrlOptions): Promise<SignedUrl>;
+  getSignedUploadUrl(options: SignedUploadUrlOptions): Promise<SignedUrl>;
+  getPublicUrl(key: string): string;
+  createMultipartUpload(key: string, options?: MultipartUploadOptions): Promise<MultipartUpload>;
+  resumeMultipartUpload(key: string, uploadId: string): MultipartUpload;
+}
+```
+
+### Helpers
+
+The package also exports helper utilities for common storage operations:
+
+```js
+import { contentHash, contentAddressedKey, safeDisposition, StorageError } from '@arraypress/storage';
+
+// SHA-256 content hashing for deduplication
+const hash = await contentHash(fileBuffer);
+// => 'a1b2c3d4e5f6...'
+
+// Generate content-addressed storage keys
+const key = contentAddressedKey(hash, 'photo.jpg', 'media/');
+// => 'media/a1b2c3d4e5f6.jpg'
+
+// Determine safe Content-Disposition for downloads
+safeDisposition('image/jpeg');        // => 'inline'
+safeDisposition('image/svg+xml');     // => 'attachment' (XSS risk)
+safeDisposition('application/pdf');   // => 'inline'
+safeDisposition('text/html');         // => 'attachment'
+
+// Typed storage errors
+throw new StorageError('File not found', 'NOT_FOUND');
+```
+
+### Content-Addressed Uploads
+
+Combine `contentHash` and `contentAddressedKey` to skip duplicate uploads:
+
+```js
+import { contentHash, contentAddressedKey } from '@arraypress/storage';
+
+async function uploadDeduped(storage, file, originalName) {
+  const hash = await contentHash(file);
+  const key = contentAddressedKey(hash, originalName, 'uploads/');
+
+  // Skip upload if identical file already exists
+  if (await storage.exists(key)) {
+    return { key, skipped: true };
+  }
+
+  const result = await storage.upload({
+    key,
+    body: file,
+    contentType: 'application/octet-stream',
+  });
+
+  return { key: result.key, skipped: false };
+}
+```
+
+## API Reference
+
+### Types
+
+- `Storage` -- Main storage interface implemented by all adapters
+- `UploadOptions` -- Options for `upload()`: `key`, `body`, `contentType`, `metadata?`
+- `UploadResult` -- Result from `upload()`: `key`, `size`, `etag?`
+- `DownloadResult` -- Result from `download()`: `body`, `contentType`, `size`, `etag?`
+- `ListOptions` -- Options for `list()`: `prefix?`, `limit?`, `cursor?`
+- `ListResult` -- Result from `list()`: `objects`, `truncated`, `cursor?`
+- `ListObject` -- Individual object in list: `key`, `size`, `lastModified?`, `etag?`
+- `SignedUrlOptions` -- Options for signed URLs: `key`, `expiresIn?`
+- `SignedUploadUrlOptions` -- Extends `SignedUrlOptions` with `contentType`
+- `SignedUrl` -- Signed URL result: `url`, `expiresAt`
+- `MultipartUploadOptions` -- Options for multipart: `contentType?`, `metadata?`
+- `MultipartUpload` -- Multipart upload handle: `uploadId`, `key`, `uploadPart()`, `complete()`, `abort()`
+- `MultipartPart` -- Completed part: `partNumber`, `etag`
+- `StorageErrorCode` -- `'NOT_FOUND' | 'NOT_SUPPORTED' | 'PERMISSION_DENIED' | 'ALREADY_EXISTS' | 'UNKNOWN'`
+
+### Classes
+
+- `StorageError` -- Error class with a `code` property (`StorageErrorCode`)
+
+### Functions
+
+- `contentHash(body)` -- Compute SHA-256 hash of a body. Returns lowercase hex string. Uses Web Crypto API.
+- `contentAddressedKey(hash, originalName, prefix?)` -- Generate a storage key from a hash and original filename, preserving the file extension.
+- `safeDisposition(mimeType)` -- Returns `'inline'` for safe types (images, audio, video, PDF) or `'attachment'` for everything else (SVG, HTML, etc.).
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@arraypress/storage",
+  "version": "1.0.0",
+  "description": "Storage interface + types + helpers for portable file storage across R2, S3, and local filesystem",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "storage",
+    "r2",
+    "s3",
+    "file-storage",
+    "cloudflare",
+    "interface"
+  ],
+  "author": "ArrayPress",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/arraypress/storage"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,192 @@
+// === Upload ===
+
+export interface UploadOptions {
+  /** Storage key (path) for the object. */
+  key: string;
+  /** File body — accepts any standard web body type. */
+  body: ReadableStream | ArrayBuffer | Uint8Array | Blob;
+  /** MIME content type. */
+  contentType: string;
+  /** Optional key-value metadata stored alongside the object. */
+  metadata?: Record<string, string>;
+}
+
+export interface UploadResult {
+  /** The key the object was stored under. */
+  key: string;
+  /** Object size in bytes. */
+  size: number;
+  /** ETag if provided by the backend. */
+  etag?: string;
+}
+
+// === Download ===
+
+export interface DownloadResult {
+  /** Object body as a readable stream. */
+  body: ReadableStream;
+  /** MIME content type. */
+  contentType: string;
+  /** Object size in bytes. */
+  size: number;
+  /** ETag if provided by the backend. */
+  etag?: string;
+}
+
+// === List ===
+
+export interface ListOptions {
+  /** Filter objects by key prefix. */
+  prefix?: string;
+  /** Maximum number of objects to return. */
+  limit?: number;
+  /** Pagination cursor from a previous list call. */
+  cursor?: string;
+}
+
+export interface ListResult {
+  /** Matching objects. */
+  objects: ListObject[];
+  /** Whether there are more results beyond this page. */
+  truncated: boolean;
+  /** Cursor for the next page, if truncated. */
+  cursor?: string;
+}
+
+export interface ListObject {
+  /** Object key (path). */
+  key: string;
+  /** Object size in bytes. */
+  size: number;
+  /** Last modified date, if available. */
+  lastModified?: Date;
+  /** ETag if available. */
+  etag?: string;
+}
+
+// === Signed URLs ===
+
+export interface SignedUrlOptions {
+  /** Object key. */
+  key: string;
+  /** Expiration time in seconds. Default: 3600. */
+  expiresIn?: number;
+}
+
+export interface SignedUploadUrlOptions extends SignedUrlOptions {
+  /** Content type for the upload. */
+  contentType: string;
+}
+
+export interface SignedUrl {
+  /** The signed URL. */
+  url: string;
+  /** When the URL expires. */
+  expiresAt: Date;
+}
+
+// === Multipart Upload ===
+
+export interface MultipartUploadOptions {
+  /** MIME content type. */
+  contentType?: string;
+  /** Optional metadata. */
+  metadata?: Record<string, string>;
+}
+
+export interface MultipartUpload {
+  /** Backend-assigned upload ID. */
+  uploadId: string;
+  /** Object key. */
+  key: string;
+  /** Upload a single part. Part numbers start at 1. */
+  uploadPart(partNumber: number, body: ArrayBuffer | Uint8Array): Promise<MultipartPart>;
+  /** Finalise the upload with all parts. */
+  complete(parts: MultipartPart[]): Promise<void>;
+  /** Cancel the upload and discard uploaded parts. */
+  abort(): Promise<void>;
+}
+
+export interface MultipartPart {
+  /** Part number (1-based). */
+  partNumber: number;
+  /** ETag returned by the backend for this part. */
+  etag: string;
+}
+
+// === Storage Interface ===
+
+export interface Storage {
+  /** Upload an object. */
+  upload(options: UploadOptions): Promise<UploadResult>;
+
+  /** Download an object. Returns null if not found. */
+  download(key: string): Promise<DownloadResult | null>;
+
+  /** Delete an object. Does not throw if the key doesn't exist. */
+  delete(key: string): Promise<void>;
+
+  /** Check whether an object exists. */
+  exists(key: string): Promise<boolean>;
+
+  /** List objects, optionally filtered by prefix. */
+  list(options?: ListOptions): Promise<ListResult>;
+
+  /**
+   * Get a signed URL for downloading an object.
+   * Throws StorageError with code NOT_SUPPORTED if the backend doesn't support signed URLs.
+   */
+  getSignedDownloadUrl(options: SignedUrlOptions): Promise<SignedUrl>;
+
+  /**
+   * Get a signed URL for uploading an object directly.
+   * Throws StorageError with code NOT_SUPPORTED if the backend doesn't support signed URLs.
+   */
+  getSignedUploadUrl(options: SignedUploadUrlOptions): Promise<SignedUrl>;
+
+  /** Get the public URL for an object. Requires the bucket to be publicly accessible. */
+  getPublicUrl(key: string): string;
+
+  /**
+   * Start a multipart upload for large files.
+   * Throws StorageError with code NOT_SUPPORTED if the backend doesn't support multipart uploads.
+   */
+  createMultipartUpload(key: string, options?: MultipartUploadOptions): Promise<MultipartUpload>;
+
+  /**
+   * Resume an in-progress multipart upload.
+   * Throws StorageError with code NOT_SUPPORTED if the backend doesn't support multipart uploads.
+   */
+  resumeMultipartUpload(key: string, uploadId: string): MultipartUpload;
+}
+
+// === Error ===
+
+export type StorageErrorCode =
+  | 'NOT_FOUND'
+  | 'NOT_SUPPORTED'
+  | 'PERMISSION_DENIED'
+  | 'ALREADY_EXISTS'
+  | 'UNKNOWN';
+
+export declare class StorageError extends Error {
+  code: StorageErrorCode;
+  constructor(message: string, code: StorageErrorCode);
+}
+
+// === Helpers ===
+
+/** Compute SHA-256 hash of a body. Returns lowercase hex string. Uses Web Crypto API. */
+export function contentHash(body: ArrayBuffer | Uint8Array | ReadableStream | Blob): Promise<string>;
+
+/**
+ * Generate a content-addressed storage key from a hash and original filename.
+ * Example: contentAddressedKey('abc123', 'photo.jpg', 'media/') → 'media/abc123.jpg'
+ */
+export function contentAddressedKey(hash: string, originalName: string, prefix?: string): string;
+
+/**
+ * Determine the safe Content-Disposition for a given MIME type.
+ * Safe types (images, audio, video, PDF) → 'inline'; everything else → 'attachment'.
+ */
+export function safeDisposition(mimeType: string): 'inline' | 'attachment';

package/src/index.js

@@ -0,0 +1,85 @@
+/**
+ * @arraypress/storage
+ *
+ * Core storage interface, types, and helper utilities.
+ * Zero dependencies — works in any JavaScript runtime.
+ *
+ * @module @arraypress/storage
+ */
+
+// === Error ===
+
+export class StorageError extends Error {
+  /**
+   * @param {string} message
+   * @param {import('./index.d.ts').StorageErrorCode} code
+   */
+  constructor(message, code = 'UNKNOWN') {
+    super(message);
+    this.name = 'StorageError';
+    this.code = code;
+  }
+}
+
+// === Helpers ===
+
+/**
+ * Compute SHA-256 hash of a body. Returns lowercase hex string.
+ *
+ * @param {ArrayBuffer | Uint8Array | ReadableStream | Blob} body
+ * @returns {Promise<string>}
+ */
+export async function contentHash(body) {
+  let buffer;
+  if (body instanceof ArrayBuffer) {
+    buffer = body;
+  } else if (body instanceof Uint8Array) {
+    buffer = body.buffer;
+  } else {
+    // ReadableStream or Blob — convert via Response
+    buffer = await new Response(body).arrayBuffer();
+  }
+  const hash = await crypto.subtle.digest('SHA-256', buffer);
+  return Array.from(new Uint8Array(hash))
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+/**
+ * Generate a content-addressed storage key from a hash and original filename.
+ *
+ * @param {string} hash - The content hash (e.g. SHA-256 hex).
+ * @param {string} originalName - Original filename to extract extension from.
+ * @param {string} [prefix=''] - Optional key prefix (e.g. 'media/').
+ * @returns {string}
+ *
+ * @example
+ * contentAddressedKey('abc123', 'photo.jpg', 'media/')
+ * // → 'media/abc123.jpg'
+ */
+export function contentAddressedKey(hash, originalName, prefix = '') {
+  const dotIndex = originalName.lastIndexOf('.');
+  const ext = dotIndex > 0 ? originalName.slice(dotIndex) : '';
+  return `${prefix}${hash}${ext}`;
+}
+
+/** MIME types that are safe to serve inline (no XSS risk). */
+const INLINE_TYPES = new Set([
+  'image/jpeg', 'image/png', 'image/gif', 'image/webp', 'image/avif', 'image/bmp', 'image/tiff',
+  'audio/mpeg', 'audio/ogg', 'audio/wav', 'audio/webm', 'audio/aac', 'audio/flac',
+  'video/mp4', 'video/webm', 'video/ogg',
+  'application/pdf',
+]);
+
+/**
+ * Determine the safe Content-Disposition for a given MIME type.
+ * Safe types (images, audio, video, PDF) → 'inline'; everything else → 'attachment'.
+ *
+ * SVG, HTML, and other scriptable types are forced to 'attachment' to prevent XSS.
+ *
+ * @param {string} mimeType
+ * @returns {'inline' | 'attachment'}
+ */
+export function safeDisposition(mimeType) {
+  return INLINE_TYPES.has(mimeType) ? 'inline' : 'attachment';
+}