@storyshelf/storage-s3 0.1.0

package/README.md

@@ -0,0 +1,58 @@
+# @storyshelf/storage-s3
+
+The S3-compatible storage adapter for StoryShelf: reads and writes blobs to any S3-compatible object store, including AWS S3, Cloudflare R2, MinIO, and DigitalOcean Spaces.
+
+## Install
+
+```sh
+nub add @storyshelf/storage-s3
+```
+
+or
+
+```sh
+npm install @storyshelf/storage-s3
+```
+
+## Quick start
+
+```ts
+import { createS3Storage } from "@storyshelf/storage-s3";
+import { createShelfRouter } from "@storyshelf/core";
+
+const storage = createS3Storage({
+  bucket: "my-shelf",
+  prefix: "storyshelf",
+  endpoint: process.env.S3_ENDPOINT, // optional, e.g. for MinIO/R2
+  region: "us-east-1",               // optional
+});
+
+const app = createShelfRouter({ database, storage });
+```
+
+## API
+
+### `S3StorageOptions`
+
+```ts
+interface S3StorageOptions {
+  bucket: string;      // required bucket name
+  prefix?: string;     // optional key prefix, defaults to ""
+  endpoint?: string;   // optional custom endpoint (MinIO, R2, etc.)
+  region?: string;     // optional region, defaults to "us-east-1"
+}
+```
+
+### `createS3Storage(options: S3StorageOptions): StorageAdapter`
+
+Creates an S3 client (with `forcePathStyle` enabled for compatibility with MinIO/R2) and returns a `StorageAdapter`. The returned adapter implements every method of the `StorageAdapter` interface (`read`, `write`, `delete`, `exists`, `list(prefix)`).
+
+### `s3Key(prefix: string, path: string): string`
+
+Helper that joins a storage prefix with a relative path into an object key.
+
+## How it fits in
+
+`storage-s3` is the `storage` option for `createShelfRouter` in cloud or multi-node deployments. It implements the same `StorageAdapter` interface as `@storyshelf/storage-local`, so switching between local disk and object storage requires no changes elsewhere.
+
+See `docs/architecture.md` and ADR 0006.

package/dist/index.d.mts

@@ -0,0 +1,29 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { S3Client } from "@aws-sdk/client-s3";
+import { StorageAdapter } from "@storyshelf/core/adapter/storage";
+//#region src/index.d.ts
+/** Options for configuring an S3-compatible storage adapter. */
+interface S3StorageOptions {
+  /** S3 bucket name. */
+  bucket: string;
+  /** Optional key prefix applied to all stored objects. */
+  prefix?: string;
+  /** Custom endpoint for S3-compatible services (e.g. MinIO, R2). */
+  endpoint?: string;
+  /** AWS region. Defaults to `us-east-1`. */
+  region?: string;
+  /** Pre-configured S3 client. Defaults to a client built from the other options. */
+  client?: S3Client;
+}
+declare function s3Key(prefix: string, path: string): string;
+/**
+ * Create an S3-compatible StorageAdapter (AWS S3, R2, MinIO, etc.).
+ *
+ * @param options - S3 configuration options.
+ * @returns A StorageAdapter backed by the configured S3 bucket.
+ */
+declare function createS3Storage(options: S3StorageOptions): StorageAdapter;
+//#endregion
+export { S3StorageOptions, createS3Storage, s3Key };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,79 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { DeleteObjectCommand, GetObjectCommand, HeadObjectCommand, ListObjectsV2Command, PutObjectCommand, S3Client, S3ServiceException } from "@aws-sdk/client-s3";
+//#region src/index.ts
+function s3Key(prefix, path) {
+	return prefix === "" ? path : `${prefix}/${path}`;
+}
+function s3Rel(prefix, key) {
+	return prefix === "" ? key : key.slice(prefix.length + 1);
+}
+function isNotFound(error) {
+	return error instanceof S3ServiceException && error.$metadata.httpStatusCode === 404;
+}
+/**
+* Create an S3-compatible StorageAdapter (AWS S3, R2, MinIO, etc.).
+*
+* @param options - S3 configuration options.
+* @returns A StorageAdapter backed by the configured S3 bucket.
+*/
+function createS3Storage(options) {
+	const { bucket, prefix = "", endpoint, region = "us-east-1", client: injectedClient } = options;
+	const client = injectedClient ?? new S3Client({
+		endpoint,
+		region,
+		forcePathStyle: true
+	});
+	return {
+		metadata: {
+			name: "S3 Storage",
+			version: "0.1.0",
+			description: "S3-compatible storage adapter",
+			kind: "s3"
+		},
+		async read(path) {
+			const body = (await client.send(new GetObjectCommand({
+				Bucket: bucket,
+				Key: s3Key(prefix, path)
+			}))).Body;
+			if (body === void 0) return Buffer.alloc(0);
+			return Buffer.from(await body.transformToByteArray());
+		},
+		async write(path, data) {
+			await client.send(new PutObjectCommand({
+				Bucket: bucket,
+				Key: s3Key(prefix, path),
+				Body: data
+			}));
+		},
+		async delete(path) {
+			await client.send(new DeleteObjectCommand({
+				Bucket: bucket,
+				Key: s3Key(prefix, path)
+			}));
+		},
+		async exists(path) {
+			try {
+				await client.send(new HeadObjectCommand({
+					Bucket: bucket,
+					Key: s3Key(prefix, path)
+				}));
+				return true;
+			} catch (error) {
+				if (isNotFound(error)) return false;
+				throw error;
+			}
+		},
+		async list(listPrefix) {
+			return ((await client.send(new ListObjectsV2Command({
+				Bucket: bucket,
+				Prefix: s3Key(prefix, listPrefix)
+			}))).Contents ?? []).map((item) => item.Key).filter((key) => key !== void 0).map((key) => s3Rel(prefix, key));
+		}
+	};
+}
+//#endregion
+export { createS3Storage, s3Key };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["import {\n  DeleteObjectCommand,\n  GetObjectCommand,\n  HeadObjectCommand,\n  ListObjectsV2Command,\n  PutObjectCommand,\n  S3Client,\n  S3ServiceException,\n} from \"@aws-sdk/client-s3\";\n\nimport type { StorageAdapter } from \"@storyshelf/core/adapter/storage\";\n\ndeclare const __PKG_VERSION__: string;\n\n/** Options for configuring an S3-compatible storage adapter. */\nexport interface S3StorageOptions {\n  /** S3 bucket name. */\n  bucket: string;\n  /** Optional key prefix applied to all stored objects. */\n  prefix?: string;\n  /** Custom endpoint for S3-compatible services (e.g. MinIO, R2). */\n  endpoint?: string;\n  /** AWS region. Defaults to `us-east-1`. */\n  region?: string;\n  /** Pre-configured S3 client. Defaults to a client built from the other options. */\n  client?: S3Client;\n}\n\nexport function s3Key(prefix: string, path: string): string {\n  return prefix === \"\" ? path : `${prefix}/${path}`;\n}\n\nfunction s3Rel(prefix: string, key: string): string {\n  return prefix === \"\" ? key : key.slice(prefix.length + 1);\n}\n\nfunction isNotFound(error: unknown): boolean {\n  return error instanceof S3ServiceException && error.$metadata.httpStatusCode === 404;\n}\n\n/**\n * Create an S3-compatible StorageAdapter (AWS S3, R2, MinIO, etc.).\n *\n * @param options - S3 configuration options.\n * @returns A StorageAdapter backed by the configured S3 bucket.\n */\nexport function createS3Storage(options: S3StorageOptions): StorageAdapter {\n  const { bucket, prefix = \"\", endpoint, region = \"us-east-1\", client: injectedClient } = options;\n  const client = injectedClient ?? new S3Client({ endpoint, region, forcePathStyle: true });\n\n  return {\n    metadata: {\n      name: \"S3 Storage\",\n      version: typeof __PKG_VERSION__ === \"undefined\" ? \"0.0.0\" : __PKG_VERSION__, // oxlint-disable-line unicorn/no-typeof-undefined\n      description: \"S3-compatible storage adapter\",\n      kind: \"s3\",\n    },\n    async read(path) {\n      const response = await client.send(\n        new GetObjectCommand({ Bucket: bucket, Key: s3Key(prefix, path) }),\n      );\n      const body = response.Body;\n      if (body === undefined) {\n        return Buffer.alloc(0);\n      }\n      return Buffer.from(await body.transformToByteArray());\n    },\n    async write(path, data) {\n      await client.send(\n        new PutObjectCommand({ Bucket: bucket, Key: s3Key(prefix, path), Body: data }),\n      );\n    },\n    async delete(path) {\n      await client.send(\n        new DeleteObjectCommand({ Bucket: bucket, Key: s3Key(prefix, path) }),\n      );\n    },\n    async exists(path) {\n      try {\n        await client.send(new HeadObjectCommand({ Bucket: bucket, Key: s3Key(prefix, path) }));\n        return true;\n      } catch (error) {\n        if (isNotFound(error)) {\n          return false;\n        }\n        throw error;\n      }\n    },\n    async list(listPrefix) {\n      const response = await client.send(\n        new ListObjectsV2Command({ Bucket: bucket, Prefix: s3Key(prefix, listPrefix) }),\n      );\n      return (response.Contents ?? [])\n        .map((item) => item.Key)\n        .filter((key): key is string => key !== undefined)\n        .map((key) => s3Rel(prefix, key));\n    },\n  };\n}\n"],"mappings":";;;;;AA4BA,SAAgB,MAAM,QAAgB,MAAsB;CAC1D,OAAO,WAAW,KAAK,OAAO,GAAG,OAAO,GAAG;AAC7C;AAEA,SAAS,MAAM,QAAgB,KAAqB;CAClD,OAAO,WAAW,KAAK,MAAM,IAAI,MAAM,OAAO,SAAS,CAAC;AAC1D;AAEA,SAAS,WAAW,OAAyB;CAC3C,OAAO,iBAAiB,sBAAsB,MAAM,UAAU,mBAAmB;AACnF;;;;;;;AAQA,SAAgB,gBAAgB,SAA2C;CACzE,MAAM,EAAE,QAAQ,SAAS,IAAI,UAAU,SAAS,aAAa,QAAQ,mBAAmB;CACxF,MAAM,SAAS,kBAAkB,IAAI,SAAS;EAAE;EAAU;EAAQ,gBAAgB;CAAK,CAAC;CAExF,OAAO;EACL,UAAU;GACR,MAAM;GACN,SAAA;GACA,aAAa;GACb,MAAM;EACR;EACA,MAAM,KAAK,MAAM;GAIf,MAAM,QAAO,MAHU,OAAO,KAC5B,IAAI,iBAAiB;IAAE,QAAQ;IAAQ,KAAK,MAAM,QAAQ,IAAI;GAAE,CAAC,CACnE,EAAA,CACsB;GACtB,IAAI,SAAS,KAAA,GACX,OAAO,OAAO,MAAM,CAAC;GAEvB,OAAO,OAAO,KAAK,MAAM,KAAK,qBAAqB,CAAC;EACtD;EACA,MAAM,MAAM,MAAM,MAAM;GACtB,MAAM,OAAO,KACX,IAAI,iBAAiB;IAAE,QAAQ;IAAQ,KAAK,MAAM,QAAQ,IAAI;IAAG,MAAM;GAAK,CAAC,CAC/E;EACF;EACA,MAAM,OAAO,MAAM;GACjB,MAAM,OAAO,KACX,IAAI,oBAAoB;IAAE,QAAQ;IAAQ,KAAK,MAAM,QAAQ,IAAI;GAAE,CAAC,CACtE;EACF;EACA,MAAM,OAAO,MAAM;GACjB,IAAI;IACF,MAAM,OAAO,KAAK,IAAI,kBAAkB;KAAE,QAAQ;KAAQ,KAAK,MAAM,QAAQ,IAAI;IAAE,CAAC,CAAC;IACrF,OAAO;GACT,SAAS,OAAO;IACd,IAAI,WAAW,KAAK,GAClB,OAAO;IAET,MAAM;GACR;EACF;EACA,MAAM,KAAK,YAAY;GAIrB,SAAQ,MAHe,OAAO,KAC5B,IAAI,qBAAqB;IAAE,QAAQ;IAAQ,QAAQ,MAAM,QAAQ,UAAU;GAAE,CAAC,CAChF,EAAA,CACiB,YAAY,CAAC,EAAA,CAC3B,KAAK,SAAS,KAAK,GAAG,CAAC,CACvB,QAAQ,QAAuB,QAAQ,KAAA,CAAS,CAAC,CACjD,KAAK,QAAQ,MAAM,QAAQ,GAAG,CAAC;EACpC;CACF;AACF"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@storyshelf/storage-s3",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "S3-compatible storage adapter for StoryShelf (AWS SDK v3).",
+  "author": {
+    "name": "Siddhant Gupta",
+    "url": "https://guptasiddhant.com"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GuptaSiddhant/storyshelf.git",
+    "directory": "packages/storage-s3"
+  },
+  "homepage": "https://github.com/GuptaSiddhant/storyshelf#readme",
+  "bugs": {
+    "url": "https://github.com/GuptaSiddhant/storyshelf/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": "./dist/index.mjs",
+      "./package.json": "./package.json"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown -w",
+    "fmt": "oxfmt -c ../../.oxfmtrc.json ./src",
+    "lint": "oxlint --type-aware --type-check ./src",
+    "test": "vitest run",
+    "prepublishOnly": "nub run build"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.700.0",
+    "@storyshelf/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "@vitest/coverage-v8": "catalog:",
+    "oxfmt": "catalog:",
+    "oxlint": "catalog:",
+    "oxlint-tsgolint": "catalog:",
+    "tsdown": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  },
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  }
+}