@maroonedsoftware/storage 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Marooned Software
+
+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,172 @@
+# @maroonedsoftware/storage
+
+Object storage abstraction for ServerKit. Provides a DI-friendly `StorageProvider` interface and ready-made backends for the local filesystem, AWS S3, and Google Cloud Storage.
+
+## Installation
+
+```bash
+pnpm add @maroonedsoftware/storage
+```
+
+The cloud SDKs are **optional peer dependencies** — install only the one(s) you use. The disk backend needs nothing extra.
+
+```bash
+# AWS S3
+pnpm add @aws-sdk/client-s3 @aws-sdk/lib-storage @aws-sdk/s3-request-presigner
+
+# Google Cloud Storage
+pnpm add @google-cloud/storage
+```
+
+## Usage
+
+### 1. Bind a provider in your DI container
+
+Consumers depend only on the abstract `StorageProvider`; bind whichever backend fits the environment.
+
+```typescript
+import { StorageProvider, DiskStorageProvider, DiskStorageProviderOptions } from '@maroonedsoftware/storage';
+
+// Local disk (great for development and tests)
+container.bind(StorageProvider).toConstantValue(new DiskStorageProvider(new DiskStorageProviderOptions({ rootDir: '/var/data' })));
+```
+
+```typescript
+import { S3Client } from '@aws-sdk/client-s3';
+import { StorageProvider, S3StorageProvider, S3StorageProviderOptions } from '@maroonedsoftware/storage';
+
+// AWS S3 — both the client and the options are injectable tokens
+container.bind(S3Client).toConstantValue(new S3Client({ region: 'us-east-1' }));
+container.bind(S3StorageProviderOptions).toConstantValue(new S3StorageProviderOptions({ bucket: 'my-bucket' }));
+container.bind(StorageProvider).to(S3StorageProvider);
+```
+
+```typescript
+import { Storage } from '@google-cloud/storage';
+import { StorageProvider, GcsStorageProvider, GcsStorageProviderOptions } from '@maroonedsoftware/storage';
+
+// Google Cloud Storage
+container.bind(Storage).toConstantValue(new Storage());
+container.bind(GcsStorageProviderOptions).toConstantValue(new GcsStorageProviderOptions({ bucket: 'my-bucket' }));
+container.bind(StorageProvider).to(GcsStorageProvider);
+```
+
+### 2. Inject and use
+
+```typescript
+import { Injectable } from 'injectkit';
+import { Duration } from 'luxon';
+import { StorageProvider } from '@maroonedsoftware/storage';
+
+@Injectable()
+class AvatarService {
+  constructor(private readonly storage: StorageProvider) {}
+
+  async save(userId: string, body: Buffer) {
+    await this.storage.write(`users/${userId}/avatar.png`, body, { contentType: 'image/png' });
+  }
+
+  async thumbnail(userId: string) {
+    // Partial read — first 1 KiB only
+    return await this.storage.read(`users/${userId}/avatar.png`, { range: { start: 0, end: 1023 } });
+  }
+
+  async downloadUrl(userId: string) {
+    // Time-limited URL for the client to fetch directly
+    return await this.storage.getSignedUrl(`users/${userId}/avatar.png`, {
+      operation: 'read',
+      expiresIn: Duration.fromObject({ minutes: 15 }),
+    });
+  }
+}
+```
+
+## API
+
+### `StorageProvider` (abstract)
+
+Base class to extend when implementing a custom backend. Keys are hierarchical, `/`-separated paths (e.g. `users/42/avatar.png`).
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `write` | `(key, body: Readable \| Buffer \| string, options?: StorageWriteOptions) => Promise<void>` | Writes `key`, overwriting any existing object. |
+| `read` | `(key, options?: StorageReadOptions) => Promise<Readable>` | Opens a stream, optionally for an inclusive byte range. Throws if absent. |
+| `stat` | `(key) => Promise<StorageObjectMetadata>` | Fetches metadata without reading the body. Throws if absent. |
+| `exists` | `(key) => Promise<boolean>` | `true` / `false` — never throws for absence. |
+| `delete` | `(key) => Promise<void>` | Idempotent — deleting a missing key is a no-op. |
+| `copy` | `(sourceKey, destinationKey) => Promise<void>` | Server-side copy within the backend. Throws if the source is missing. |
+| `move` | `(sourceKey, destinationKey) => Promise<void>` | Move/rename within the backend. Throws if the source is missing. |
+| `list` | `(options?: StorageListOptions) => Promise<StorageListResult>` | One page of objects, optionally filtered by `prefix`, with a `cursor` for the next page. |
+| `getSignedUrl` | `(key, options: SignedUrlOptions) => Promise<string>` | Time-limited URL for direct client read/write. |
+
+#### Behaviour contract
+
+- `read` / `stat` on a missing key throw `StorageObjectNotFoundError`.
+- A permission failure throws `StorageAccessDeniedError`.
+- `delete` is idempotent; `copy` / `move` overwrite the destination and operate **within one backend** (same bucket/root) — cross-backend transfers are out of scope.
+- `getSignedUrl` throws `StorageOperationNotSupportedError` on backends that can't sign.
+
+### Errors
+
+All extend `StorageError`, which extends `ServerkitError` (so `errorMiddleware` renders them):
+
+- `StorageObjectNotFoundError` — missing object (carries `key`).
+- `StorageAccessDeniedError` — permission failure (carries `key`).
+- `StorageOperationNotSupportedError` — operation unsupported by the active backend.
+
+## Backends
+
+### `DiskStorageProvider`
+
+Local filesystem rooted at a directory. Nested keys create intermediate directories on write; path traversal outside the root is rejected. User metadata is not persisted (the filesystem has no native slot). `getSignedUrl` requires a `publicBaseUrl`:
+
+```typescript
+new DiskStorageProvider(new DiskStorageProviderOptions({ rootDir: '/var/data', publicBaseUrl: 'https://cdn.example.com' }));
+```
+
+> `list` walks the whole tree and `stat`s each match per call — fine for development and modest trees, not for very large directories.
+
+### `S3StorageProvider`
+
+AWS S3 (or any S3-compatible endpoint). Streaming writes use `@aws-sdk/lib-storage`'s multipart `Upload`; buffer/string writes use a single `PutObject`. Signed URLs come from `@aws-sdk/s3-request-presigner`.
+
+> `copy` (and therefore `move`) uses S3's single-request `CopyObject`, which is capped at 5 GB. Larger objects need a multipart copy, which this provider does not yet implement.
+
+### `GcsStorageProvider`
+
+Google Cloud Storage via `@google-cloud/storage`, including native `copy` / `move` and v4 signed URLs.
+
+## Custom implementations
+
+Extend `StorageProvider` to add your own backend (in-memory, Azure Blob, etc.) and honour the behaviour contract above:
+
+```typescript
+import { Injectable } from 'injectkit';
+import { Readable } from 'node:stream';
+import { StorageProvider, StorageObjectNotFoundError } from '@maroonedsoftware/storage';
+
+@Injectable()
+export class InMemoryStorageProvider extends StorageProvider {
+  private readonly store = new Map<string, Buffer>();
+
+  async write(key: string, body: Readable | Buffer | string) {
+    this.store.set(key, body instanceof Readable ? Buffer.concat(await body.toArray()) : Buffer.from(body));
+  }
+
+  async read(key: string) {
+    const data = this.store.get(key);
+    if (!data) throw new StorageObjectNotFoundError(key);
+    return Readable.from(data);
+  }
+
+  // ...stat, exists, delete, copy, move, list, getSignedUrl
+}
+```
+
+## Configuration
+
+The provider options are plain injectable classes, so the package stays decoupled from `@maroonedsoftware/appconfig`. To drive a bucket name from typed config, bridge it at bootstrap rather than importing AppConfig into the provider:
+
+```typescript
+registry.register(S3StorageProviderOptions).useFactory(c => new S3StorageProviderOptions({ bucket: c.get(StorageOptions).value.bucket }));
+```

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@maroonedsoftware/storage",
+  "version": "0.1.0",
+  "description": "Storage utilities for ServerKit.",
+  "author": {
+    "name": "Marooned Software",
+    "url": "https://github.com/MaroonedSoftware/serverkit"
+  },
+  "bugs": {
+    "url": "https://github.com/MaroonedSoftware/serverkit/issues"
+  },
+  "homepage": "https://github.com/MaroonedSoftware/serverkit/packages/storage#readme",
+  "keywords": [
+    "backend",
+    "storage",
+    "serverkit",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MaroonedSoftware/serverkit.git"
+  },
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "license": "MIT",
+  "files": [
+    "dist/**"
+  ],
+  "dependencies": {
+    "injectkit": "^1.5.0",
+    "luxon": "^3.7.2",
+    "mime-types": "^2.1.35",
+    "@maroonedsoftware/errors": "1.7.0"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-s3": "^3.700.0",
+    "@aws-sdk/lib-storage": "^3.700.0",
+    "@aws-sdk/s3-request-presigner": "^3.700.0",
+    "@google-cloud/storage": "^7.14.0"
+  },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "@aws-sdk/lib-storage": {
+      "optional": true
+    },
+    "@aws-sdk/s3-request-presigner": {
+      "optional": true
+    },
+    "@google-cloud/storage": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@aws-sdk/client-s3": "^3.700.0",
+    "@aws-sdk/lib-storage": "^3.700.0",
+    "@aws-sdk/s3-request-presigner": "^3.700.0",
+    "@google-cloud/storage": "^7.14.0",
+    "@types/luxon": "^3.7.2",
+    "@types/mime-types": "^2.1.4",
+    "@repo/config-typescript": "0.1.0",
+    "@repo/config-eslint": "0.2.1"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --sourcemap && tsc --emitDeclarationOnly --declaration",
+    "build:ci": "eslint --max-warnings=0 && pnpm run build",
+    "lint": "eslint --fix",
+    "format": "prettier --write .",
+    "test": "vitest run",
+    "test:ci": "vitest run --coverage",
+    "test:integration": "vitest run --config vitest.integration.config.ts"
+  }
+}