@nestm/storage 0.1.0-alpha.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# @nestm/storage
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+The project intends to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
+after the initial experimental releases.
+
+## [Unreleased]
+
+## [0.1.0-alpha.0] - 2026-07-30
+
+### Added
+
+- NestJS 12 dynamic module with local-by-default root and feature registration.
+- Default and named stores through `StorageService.use()` and `@InjectStorage()`.
+- NestM-owned streaming, buffered, bulk, search, signing, resumable-upload, and
+  error contracts backed by `files-sdk`.
+- Cross-store streaming transfer and mirror/sync workflows.
+- Optional guard-required Express/Fastify HTTP gateway.
+- Node 22/24 CI and Changesets-based alpha publishing through npm OIDC.

package/CONTRIBUTING.md

@@ -0,0 +1,83 @@
+# Contributing
+
+Thank you for helping improve `@nestm/storage`.
+
+## Prerequisites
+
+- Node.js 22.12 or newer
+- Corepack
+- Git
+
+Enable the package manager declared by the repository:
+
+```sh
+corepack enable
+```
+
+## Local setup
+
+1. Fork and clone the repository.
+2. Create a focused branch from `main`.
+3. Install the locked dependencies:
+
+   ```sh
+   pnpm install --frozen-lockfile
+   ```
+
+4. Make the change and add or update tests.
+5. Run:
+
+   ```sh
+   pnpm run check
+   pnpm run test
+   pnpm run verify:pack
+   ```
+
+6. Add a Changeset for user-visible changes:
+
+   ```sh
+   pnpm changeset
+   ```
+
+## Design guidelines
+
+- Keep root public contracts owned by `@nestm/storage`; upstream
+  `files-sdk` types belong only in the explicit `files-sdk` bridge.
+- Preserve streaming and backpressure. Do not buffer an object unless the
+  method name and a tested byte limit make that behavior explicit.
+- Keep provider-specific dependencies optional and outside the build output.
+- Fail closed when a requested capability cannot be honored.
+- Keep the HTTP gateway optional, deny-by-default, and protected by Nest guards.
+- Keep `StorageModule` local by default.
+- Include `.js` suffixes for local imports compiled as Node ESM.
+
+Tests should cover the memory driver contract, named Nest registration,
+duplicate isolation, transfer/sync behavior, and both Express and Fastify for
+gateway changes. Keep tests deterministic and close every Nest application.
+
+## One-time npm bootstrap
+
+The first prerelease must be published interactively from a clean checkout of
+`main`:
+
+```sh
+npm publish --access public --tag alpha
+```
+
+Then configure npm Trusted Publishing:
+
+```sh
+npm trust github @nestm/storage \
+  --file release.yml \
+  --repository nestm-dev/storage \
+  --environment release \
+  --allow-publish
+```
+
+Subsequent releases use GitHub OIDC with provenance and keep prereleases on the
+`alpha` dist-tag.
+
+## Security issues
+
+Do not open a public issue for a suspected vulnerability. Follow
+[SECURITY.md](./SECURITY.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kauan Guesser
+
+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,386 @@
+# @nestm/storage
+
+NestJS 12 storage integration with named stores, explicit streaming I/O,
+cross-store workflows, and an optional guarded HTTP gateway.
+
+The package uses [`files-sdk`](https://github.com/haydenbleasel/files-sdk) as
+its provider engine, but owns the API injected into Nest applications. Provider
+SDK types, errors, and `files.raw` do not leak through the root package.
+
+> This package targets the NestJS 12 prerelease line and is itself published on
+> the `alpha` dist-tag.
+
+## Requirements
+
+- Node.js 22.12 or newer
+- NestJS `12.0.0-alpha.5` or newer in the Nest 12 prerelease line
+- ESM
+
+## Install
+
+```sh
+pnpm add @nestm/storage@alpha files-sdk@2.2.2
+```
+
+Install only the native SDKs required by the chosen provider. For example:
+
+```sh
+# S3 and S3-compatible providers
+pnpm add @aws-sdk/client-s3 @aws-sdk/s3-presigned-post \
+  @aws-sdk/s3-request-presigner @aws-sdk/lib-storage
+
+# Google Cloud Storage
+pnpm add @google-cloud/storage google-auth-library
+
+# Azure Blob Storage
+pnpm add @azure/storage-blob @azure/core-auth @azure/identity
+```
+
+`files-sdk` currently declares its optional Nest peer for Nest 10 and 11. This
+library does not import `files-sdk/nestjs`; the Nest 12 integration is entirely
+owned here. A package manager may nevertheless report that temporary optional
+peer mismatch while Nest 12 remains prerelease.
+
+NestJS 12 alpha also has prerelease peer declarations that npm may reject under
+its strict resolver. If npm reports an `ERESOLVE` error for Nest's own peers,
+install with `npm install --legacy-peer-deps`; pnpm works with the repository's
+checked-in peer-version policy.
+
+## Configure named stores
+
+Create provider adapters with `files-sdk`, wrap them through the explicit
+bridge, and register the resulting drivers:
+
+```ts
+import { Module } from '@nestjs/common';
+import { s3 } from 'files-sdk/s3';
+import { gcs } from 'files-sdk/gcs';
+import { createFilesSdkDriver } from '@nestm/storage/files-sdk';
+import { StorageModule } from '@nestm/storage';
+
+export const StorageKey = {
+  MEDIA: 'media',
+  ARCHIVE: 'archive',
+} as const;
+
+@Module({
+  imports: [
+    StorageModule.forRoot({
+      default: StorageKey.MEDIA,
+      stores: [
+        {
+          name: StorageKey.MEDIA,
+          driver: createFilesSdkDriver({
+            adapter: s3({
+              bucket: 'media',
+              region: 'us-east-1',
+            }),
+          }),
+        },
+        {
+          name: StorageKey.ARCHIVE,
+          driver: createFilesSdkDriver({
+            adapter: gcs({
+              bucket: 'archive',
+            }),
+          }),
+        },
+      ],
+    }),
+  ],
+  exports: [StorageModule],
+})
+export class AppStorageModule {}
+```
+
+`StorageModule` is not global by default. Import the configured module wherever
+its exports are needed, re-export it from an infrastructure module as above, or
+set `isGlobal: true` deliberately.
+
+Inject one store directly:
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { InjectStorage, type StorageClient } from '@nestm/storage';
+
+@Injectable()
+export class AvatarService {
+  constructor(
+    @InjectStorage(StorageKey.MEDIA)
+    private readonly media: StorageClient,
+  ) {}
+
+  upload(userId: string, body: ReadableStream<Uint8Array>) {
+    return this.media.upload(`avatars/${userId}.png`, body, {
+      contentType: 'image/png',
+      multipart: true,
+    });
+  }
+}
+```
+
+Or select stores through the manager:
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { StorageService } from '@nestm/storage';
+
+@Injectable()
+export class ArchiveService {
+  constructor(private readonly storage: StorageService) {}
+
+  async archive(key: string) {
+    const object = await this.storage.use(StorageKey.MEDIA).downloadStream(key);
+    return this.storage
+      .use(StorageKey.ARCHIVE)
+      .upload(`retained/${key}`, object.body, {
+        contentType: object.contentType,
+        ...(object.metadata !== undefined && {
+          metadata: object.metadata,
+        }),
+      });
+  }
+}
+```
+
+`storage.use()` selects the configured default. When several stores are
+registered without `default`, callers must pass a name.
+
+### Async registration
+
+Store names remain static because Nest must create their injection tokens
+before an async factory runs:
+
+```ts
+StorageModule.forRootAsync({
+  default: 'media',
+  imports: [ConfigModule],
+  stores: [
+    {
+      name: 'media',
+      inject: [ConfigService],
+      useFactory: (config: ConfigService) =>
+        createFilesSdkDriver({
+          adapter: s3({
+            bucket: config.getOrThrow('MEDIA_BUCKET'),
+            region: config.getOrThrow('AWS_REGION'),
+          }),
+        }),
+    },
+  ],
+});
+```
+
+`useClass` and `useExisting` are also supported through
+`StorageDriverFactory#createStorageDriver(name)`. Feature-owned stores use the
+same shapes through `forFeature()` and `forFeatureAsync()` and export only
+their named `@InjectStorage(name)` clients; the root `StorageService` remains
+isolated to the stores declared by `forRoot`.
+
+Duplicate names within one registration fail immediately. Separate feature
+modules retain their own DI scope rather than mutating an application-wide
+registry. Names are case-sensitive and cannot contain leading or trailing
+whitespace.
+
+## Storage API
+
+`StorageClient` exposes:
+
+- `upload`, `downloadStream`, `head`, `exists`, `delete`, `copy`, and `move`;
+- `list`, cursor-aware `listAll`, and lazy `search`;
+- `signDownload` and discriminated PUT/POST `signUpload`;
+- `uploadMany`, `downloadMany`, `headMany`, `existsMany`, and `deleteMany`;
+- `file(key)` handles;
+- provider capability inspection; and
+- pause/resume/abort through `StorageUploadControl`.
+
+Downloads are streaming by default:
+
+```ts
+const object = await storage.use('media').downloadStream('video.mp4');
+// object.body is a Web ReadableStream<Uint8Array>
+```
+
+The explicit `downloadBytes`, `downloadText`, and `downloadJson` helpers default
+to a 10 MiB in-memory limit:
+
+```ts
+const manifest = await storage
+  .use('media')
+  .downloadJson<{ version: number }>('manifest.json', {
+    maxBytes: 256 * 1024,
+  });
+```
+
+Node `Readable` uploads are accepted and converted to Web streams without
+buffering. Provider capability gaps fail closed with `StorageError` rather than
+silently discarding a range, metadata, or cache-control request.
+
+### Resumable uploads
+
+```ts
+import { StorageUploadControl } from '@nestm/storage';
+
+const control = new StorageUploadControl();
+const upload = media.upload('large.bin', file, {
+  control,
+  multipart: { partSize: 8 * 1024 * 1024, concurrency: 4 },
+});
+
+control.pause();
+const token = control.toJSON(); // opaque and JSON-serializable
+control.resume();
+await upload;
+```
+
+Persisted tokens are intentionally opaque and versioned. Restore one with
+`StorageUploadControl.from(token)`. Resumable uploads require a repeatable,
+known-length body; a one-shot stream cannot be resumed.
+
+### Cross-store transfer and sync
+
+```ts
+await storage.transfer({
+  from: 'media',
+  to: 'archive',
+  prefix: 'uploads/',
+  concurrency: 4,
+});
+
+const preview = await storage.sync({
+  from: 'media',
+  to: 'archive',
+  compare: 'size',
+  prune: true,
+  dryRun: true,
+});
+```
+
+Object bodies stream directly between stores. Key lists and metadata are
+collected to provide deterministic progress and sync plans. Partial failures
+are returned in `errors`. `prune: true` is destructive; use `dryRun` first and
+scope the destination with `destinationPrefix`.
+
+## Optional HTTP gateway
+
+The gateway lives at `@nestm/storage/gateway` and is never mounted by
+`StorageModule`.
+
+```ts
+import { Module } from '@nestjs/common';
+import {
+  StorageGatewayModule,
+  StorageGatewayOperation,
+} from '@nestm/storage/gateway';
+
+@Module({
+  imports: [
+    AppStorageModule,
+    AuthModule,
+    StorageGatewayModule.register({
+      imports: [AppStorageModule, AuthModule],
+      store: 'media',
+      guards: [JwtAuthGuard],
+      mode: 'hybrid',
+      operations: [
+        StorageGatewayOperation.DOWNLOAD,
+        StorageGatewayOperation.UPLOAD,
+        StorageGatewayOperation.HEAD,
+        StorageGatewayOperation.LIST,
+        StorageGatewayOperation.SIGN_DOWNLOAD,
+        StorageGatewayOperation.SIGN_UPLOAD,
+      ],
+      maxUploadBytes: 100 * 1024 * 1024,
+      maxListResults: 1000,
+      maxSearchResults: 1000,
+      proxyInlineContentTypes: ['image/jpeg', 'image/png'],
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+Registration fails without at least one existing Nest guard. The only bypass is
+the explicit `allowUnauthenticated: true` development escape hatch. Operations
+are deny-by-default and must be allowlisted individually.
+
+Proxy downloads default to `Content-Disposition: attachment` and always send
+`X-Content-Type-Options: nosniff`. Add only trusted, non-active MIME types to
+`proxyInlineContentTypes` when browser rendering is required. Search responses
+are capped by `maxSearchResults`, and list pages by `maxListResults` (both
+1,000 by default).
+
+The fixed gateway prefix is `/storage`:
+
+| Method   | Path                        | Operation                            |
+| -------- | --------------------------- | ------------------------------------ |
+| `GET`    | `/storage/object?key=...`   | signed redirect or streamed download |
+| `PUT`    | `/storage/object?key=...`   | streamed proxy upload                |
+| `HEAD`   | `/storage/metadata?key=...` | object metadata                      |
+| `DELETE` | `/storage/object?key=...`   | delete                               |
+| `GET`    | `/storage/list`             | list one page                        |
+| `GET`    | `/storage/search`           | search keys                          |
+| `POST`   | `/storage/sign-download`    | sign download                        |
+| `POST`   | `/storage/sign-upload`      | sign direct upload                   |
+| `POST`   | `/storage/copy`             | copy                                 |
+| `POST`   | `/storage/move`             | move                                 |
+
+Proxy uploads use `Content-Type: application/octet-stream`; put the stored MIME
+type in `X-Storage-Content-Type`. This keeps Express and Fastify uploads as raw
+streams and avoids global body-parser changes. Generic multipart/form-data is
+not mounted by the gateway—prefer direct signed uploads or handle form parsing
+in an application controller.
+
+If an application has already registered an
+`application/octet-stream` parser, the gateway leaves it in place; that parser
+must enforce its own body limit and expose either a byte buffer or readable
+stream. Without an existing parser, the built-in Fastify parser is restricted
+to the marked gateway upload route.
+
+`hybrid` mode prefers a signed download when both `download` and
+`signDownload` are allowed and the provider advertises support, then uses the
+streaming proxy when signing is unavailable. `proxy` disables signing routes;
+`signed` disables proxy uploads and downloads.
+
+## Errors and capabilities
+
+Every thrown engine/provider failure is normalized to `StorageError`. Branch on
+`error.code`, not provider classes:
+
+```ts
+import { isStorageError, StorageErrorCode } from '@nestm/storage';
+
+try {
+  await media.head(key);
+} catch (error) {
+  if (isStorageError(error) && error.code === StorageErrorCode.NOT_FOUND) {
+    return null;
+  }
+  throw error;
+}
+```
+
+Capability flags cover range reads, native byte-level upload progress,
+delimiter listing, metadata, cache control, resumable uploads, server-side
+copy, and signed transfers.
+Provider-specific native clients are intentionally not exposed from the root
+package.
+
+## Local and in-memory stores
+
+The test helper wraps the `files-sdk` in-memory adapter:
+
+```ts
+import { createMemoryStorageDriver } from '@nestm/storage/testing';
+
+StorageModule.forRoot({
+  stores: [{ name: 'test', driver: createMemoryStorageDriver() }],
+});
+```
+
+For local filesystem storage, import `fs` from `files-sdk/fs` and pass it to
+`createFilesSdkDriver` exactly like a cloud adapter.
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,25 @@
+# Security Policy
+
+## Supported versions
+
+Until the first stable release, security fixes target the newest published
+prerelease. Pin and test the exact alpha version used with the matching NestJS
+12 prerelease.
+
+## Reporting a vulnerability
+
+Do not disclose a suspected vulnerability in a public issue, discussion, or
+pull request. Use GitHub's private vulnerability reporting flow:
+
+<https://github.com/nestm-dev/storage/security/advisories/new>
+
+Include the package and Nest versions, a minimal reproduction, expected and
+observed behavior, likely impact, and any tested mitigation.
+
+Reports about authorization bypasses in the optional gateway, unsafe signed URL
+behavior, unbounded buffering, path/key confusion, credential leakage,
+cross-store pruning, or dependency compromise are especially useful.
+
+For a vulnerability originating in NestJS, `files-sdk`, or a provider SDK,
+follow that project's security policy as well. You may still report it here
+privately when this integration needs a mitigation.

package/dist/files-sdk/files-sdk.driver.d.ts

@@ -0,0 +1,36 @@
+import { type Adapter, type FilesOptions } from 'files-sdk';
+import type { StorageDriver } from '../storage.driver.js';
+import type { StorageBody, StorageDownloadOptions, StorageListOptions, StorageListResult, StorageObject, StorageObjectMetadata, StorageOperationOptions, StorageSearchOptions, StorageSignedDownloadOptions, StorageSignedUpload, StorageSignedUploadOptions, StorageUploadOptions, StorageUploadResult } from '../storage.types.js';
+export type FilesSdkDriverOptions<AdapterType extends Adapter> = FilesOptions<AdapterType>;
+export declare class FilesSdkStorageDriver<AdapterType extends Adapter = Adapter> implements StorageDriver {
+    #private;
+    constructor(options: FilesSdkDriverOptions<AdapterType>);
+    get name(): string;
+    get capabilities(): {
+        cacheControl: boolean;
+        delimiter: boolean;
+        metadata: boolean;
+        rangeRead: boolean;
+        resumableUpload: boolean;
+        serverSideCopy: boolean;
+        signedDownload: {
+            supported: boolean;
+            maxExpiresIn?: number;
+        };
+        signedUpload: "runtime";
+        nativeUploadProgress: boolean;
+    };
+    upload(key: string, body: StorageBody, options?: StorageUploadOptions): Promise<StorageUploadResult>;
+    download(key: string, options?: StorageDownloadOptions): Promise<StorageObject>;
+    head(key: string, options?: StorageOperationOptions): Promise<StorageObjectMetadata>;
+    exists(key: string, options?: StorageOperationOptions): Promise<boolean>;
+    delete(key: string, options?: StorageOperationOptions): Promise<void>;
+    copy(sourceKey: string, destinationKey: string, options?: StorageOperationOptions): Promise<void>;
+    move(sourceKey: string, destinationKey: string, options?: StorageOperationOptions): Promise<void>;
+    list(options?: StorageListOptions): Promise<StorageListResult>;
+    search(pattern: string | RegExp, options?: StorageSearchOptions): AsyncIterable<StorageObjectMetadata>;
+    signDownload(key: string, options?: StorageSignedDownloadOptions): Promise<string>;
+    signUpload(key: string, options: StorageSignedUploadOptions): Promise<StorageSignedUpload>;
+}
+export declare function createFilesSdkDriver<AdapterType extends Adapter>(options: FilesSdkDriverOptions<AdapterType>): FilesSdkStorageDriver<AdapterType>;
+//# sourceMappingURL=files-sdk.driver.d.ts.map

package/dist/files-sdk/files-sdk.driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"files-sdk.driver.d.ts","sourceRoot":"","sources":["../../src/files-sdk/files-sdk.driver.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,OAAO,EAGZ,KAAK,YAAY,EAUlB,MAAM,WAAW,CAAC;AAGnB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EACV,WAAW,EACX,sBAAsB,EACtB,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,qBAAqB,EACrB,uBAAuB,EAEvB,oBAAoB,EACpB,4BAA4B,EAC5B,mBAAmB,EACnB,0BAA0B,EAC1B,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,qBAAqB,CAAC;AAG7B,MAAM,MAAM,qBAAqB,CAAC,WAAW,SAAS,OAAO,IAC3D,YAAY,CAAC,WAAW,CAAC,CAAC;AAyS5B,qBAAa,qBAAqB,CAChC,WAAW,SAAS,OAAO,GAAG,OAAO,CACrC,YAAW,aAAa;;gBAIZ,OAAO,EAAE,qBAAqB,CAAC,WAAW,CAAC;IAKvD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,YAAY;;;;;;;;;;;;;MAaf;IAEK,MAAM,CACV,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,mBAAmB,CAAC;IAQzB,QAAQ,CACZ,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,aAAa,CAAC;IAUnB,IAAI,CACR,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,qBAAqB,CAAC;IAMjC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,OAAO,CAAC;IAIxE,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IAMrE,IAAI,CACF,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,EACtB,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,IAAI,CAAC;IAMhB,IAAI,CACF,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,EACtB,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,IAAI,CAAC;IAMV,IAAI,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAapE,MAAM,CACJ,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,aAAa,CAAC,qBAAqB,CAAC;IAoBvC,YAAY,CACV,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,4BAA4B,GACrC,OAAO,CAAC,MAAM,CAAC;IAMlB,UAAU,CACR,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,mBAAmB,CAAC;CAahC;AAED,wBAAgB,oBAAoB,CAAC,WAAW,SAAS,OAAO,EAC9D,OAAO,EAAE,qBAAqB,CAAC,WAAW,CAAC,GAC1C,qBAAqB,CAAC,WAAW,CAAC,CAEpC"}