@tacxou/nestjs_module_factorydrive 1.1.6

package/dist/README.md

@@ -0,0 +1,245 @@
+<p align="center">
+  <a href="http://nestjs.com/" target="blank">
+    <img src="https://nestjs.com/img/logo_text.svg" width="320" alt="Nest Logo" />
+  </a>
+</p>
+
+<p align="center">
+  Factory drive module for NestJS framework
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/org/tacxou"><img src="https://img.shields.io/npm/v/@tacxou/nestjs_module_factorydrive.svg" alt="NPM Version" /></a>
+  <a href="https://www.npmjs.com/org/tacxou"><img src="https://img.shields.io/npm/l/@tacxou/nestjs_module_factorydrive.svg" alt="Package License" /></a>
+  <a href="https://github.com/tacxou/nestjs_module_rcon/actions/workflows/ci.yml"><img src="https://github.com/tacxou/nestjs_module_factorydrive/actions/workflows/ci.yml/badge.svg" alt="Publish Package to npmjs" /></a>
+</p>
+<br>
+
+## `@tacxou/nestjs_module_factorydrive`
+
+`nestjs_module_factorydrive` provides a simple storage abstraction for NestJS:
+- configure one or many disks
+- select a default disk
+- use built-in local filesystem driver
+- register custom drivers (S3, Spaces, etc.)
+
+## Maintained Packages
+
+Current maintained packages in the Factorydrive ecosystem:
+
+- `local`: [`nestjs_module_factorydrive`](https://github.com/tacxou/nestjs_module_factorydrive/blob/main/src/factorydrive/local-file-system.storage.ts)
+- `s3`: [`nestjs_module_factorydrive-s3`](https://github.com/tacxou/nestjs_module_factorydrive-s3)
+- `sftp`: [`nestjs_module_factorydrive-sftp`](https://github.com/tacxou/nestjs_module_factorydrive-sftp)
+
+## Requirements
+
+- Node.js `>= 22`
+- Bun `>= 1.0.0` (used for build/test in this repository)
+- NestJS `^6` to `^11` (`@nestjs/common` and `@nestjs/core`)
+
+## Installation
+
+```bash
+npm install @tacxou/nestjs_module_factorydrive
+```
+
+Or with other package managers:
+
+```bash
+yarn add @tacxou/nestjs_module_factorydrive
+pnpm add @tacxou/nestjs_module_factorydrive
+bun add @tacxou/nestjs_module_factorydrive
+```
+
+## Quick Start (synchronous config)
+
+```ts
+// app.module.ts
+import { Module } from '@nestjs/common'
+import { FactorydriveModule } from '@tacxou/nestjs_module_factorydrive'
+
+@Module({
+  imports: [
+    FactorydriveModule.forRoot({
+      default: 'local',
+      disks: {
+        local: {
+          driver: 'local',
+          config: {
+            root: `${process.cwd()}/storage`,
+          },
+        },
+      },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+## Async Configuration (`forRootAsync`)
+
+```ts
+// app.module.ts
+import { Module } from '@nestjs/common'
+import { ConfigModule, ConfigService } from '@nestjs/config'
+import { FactorydriveModule } from '@tacxou/nestjs_module_factorydrive'
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({ isGlobal: true }),
+    FactorydriveModule.forRootAsync({
+      imports: [ConfigModule],
+      inject: [ConfigService],
+      useFactory: async (config: ConfigService) => ({
+        default: config.get<string>('factorydrive.default', 'local'),
+        disks: {
+          local: {
+            driver: 'local',
+            config: {
+              root: config.get<string>('factorydrive.localRoot', `${process.cwd()}/storage`),
+            },
+          },
+        },
+      }),
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+## Usage
+
+Inject `FactorydriveService` and interact with a disk instance:
+
+```ts
+// file-storage.service.ts
+import { Injectable } from '@nestjs/common'
+import { FactorydriveService } from '@tacxou/nestjs_module_factorydrive'
+
+@Injectable()
+export class FileStorageService {
+  public constructor(private readonly factorydrive: FactorydriveService) {}
+
+  public async uploadFile(path: string, buffer: Buffer): Promise<void> {
+    await this.factorydrive.getDisk('local').put(path, buffer)
+  }
+
+  public async readFile(path: string): Promise<string> {
+    const { content } = await this.factorydrive.getDisk('local').get(path)
+    return content
+  }
+
+  public async deleteFile(path: string): Promise<boolean | null> {
+    const { wasDeleted } = await this.factorydrive.getDisk('local').delete(path)
+    return wasDeleted
+  }
+}
+```
+
+If no disk name is provided, the configured `default` disk is used:
+
+```ts
+const disk = this.factorydrive.getDisk()
+```
+
+## Built-in Local Driver
+
+The package includes a `local` driver with the following operations:
+
+- `append(location, content)`
+- `copy(src, dest)`
+- `delete(location)`
+- `exists(location)`
+- `get(location, encoding?)`
+- `getBuffer(location)`
+- `getStat(location)`
+- `getStream(location)`
+- `move(src, dest)`
+- `prepend(location, content)`
+- `put(location, content)`
+- `flatList(prefix?)`
+
+`content` for `put` accepts `Buffer | ReadableStream | string`.
+
+## Register a Custom Driver
+
+Custom drivers must extend `AbstractStorage` and implement the methods you need.
+
+```ts
+// aws-s3.storage.ts
+import { AbstractStorage, DeleteResponse, Response } from '@tacxou/nestjs_module_factorydrive'
+
+export class AwsS3Storage extends AbstractStorage {
+  public constructor(private readonly config: { bucket: string }) {
+    super()
+  }
+
+  public async put(location: string, content: Buffer | NodeJS.ReadableStream | string): Promise<Response> {
+    // Upload implementation...
+    return { raw: { location, uploaded: true, contentType: typeof content } }
+  }
+
+  public async delete(location: string): Promise<DeleteResponse> {
+    // Delete implementation...
+    return { raw: { location }, wasDeleted: true }
+  }
+}
+```
+
+Then register it at startup:
+
+```ts
+// app.module.ts
+import { Module, OnModuleInit } from '@nestjs/common'
+import { FactorydriveModule, FactorydriveService } from '@tacxou/nestjs_module_factorydrive'
+import { AwsS3Storage } from './aws-s3.storage'
+
+@Module({
+  imports: [
+    FactorydriveModule.forRoot({
+      default: 's3',
+      disks: {
+        s3: {
+          driver: 's3',
+          config: {
+            bucket: 'example',
+          },
+        },
+      },
+    }),
+  ],
+})
+export class AppModule implements OnModuleInit {
+  public constructor(private readonly factorydrive: FactorydriveService) {}
+
+  public onModuleInit(): void {
+    this.factorydrive.registerDriver('s3', AwsS3Storage)
+  }
+}
+```
+
+## Exported API
+
+Main exports from this package:
+
+- `FactorydriveModule`
+- `FactorydriveService`
+- `AbstractStorage`
+- `StorageManager`
+- storage config/types from `factorydrive/types`
+- exceptions from `exceptions`
+
+## Error Handling
+
+The module provides dedicated exceptions (for example):
+- `InvalidConfigException`
+- `DriverNotSupportedException`
+- `FileNotFoundException`
+- `PermissionMissingException`
+- `MethodNotSupportedException`
+
+Catch and map them in your service/controller layers as needed.
+
+## License
+
+MIT

package/dist/exceptions/authorization-required.exception.d.ts

@@ -0,0 +1,5 @@
+import { RuntimeException } from 'node-exceptions';
+export declare class AuthorizationRequiredException extends RuntimeException {
+    raw: Error;
+    constructor(err: Error, path: string);
+}

package/dist/exceptions/driver-not-supported.exception.d.ts

@@ -0,0 +1,5 @@
+import { RuntimeException } from 'node-exceptions';
+export declare class DriverNotSupportedException extends RuntimeException {
+    driver: string;
+    static driver(name: string): DriverNotSupportedException;
+}

package/dist/exceptions/file-not-found.exception.d.ts

@@ -0,0 +1,5 @@
+import { RuntimeException } from 'node-exceptions';
+export declare class FileNotFoundException extends RuntimeException {
+    raw: Error;
+    constructor(err: Error, path: string);
+}

package/dist/exceptions/index.d.ts

@@ -0,0 +1,9 @@
+export * from './authorization-required.exception';
+export * from './driver-not-supported.exception';
+export * from './file-not-found.exception';
+export * from './invalid-config.exception';
+export * from './method-not-supported.exception';
+export * from './no-such-bucket.exception';
+export * from './permission-missing.exception';
+export * from './unknown.exception';
+export * from './wrong-key-path.exception';

package/dist/exceptions/invalid-config.exception.d.ts

@@ -0,0 +1,7 @@
+import { RuntimeException } from 'node-exceptions';
+export declare class InvalidConfigException extends RuntimeException {
+    static missingDiskName(): InvalidConfigException;
+    static missingDiskConfig(name: string): InvalidConfigException;
+    static missingDiskDriver(name: string): InvalidConfigException;
+    static duplicateDiskName(name: string): InvalidConfigException;
+}

package/dist/exceptions/method-not-supported.exception.d.ts

@@ -0,0 +1,4 @@
+import { RuntimeException } from 'node-exceptions';
+export declare class MethodNotSupportedException extends RuntimeException {
+    constructor(name: string, driver: string);
+}

package/dist/exceptions/no-such-bucket.exception.d.ts

@@ -0,0 +1,5 @@
+import { RuntimeException } from 'node-exceptions';
+export declare class NoSuchBucketException extends RuntimeException {
+    raw: Error;
+    constructor(err: Error, bucket: string);
+}

package/dist/exceptions/permission-missing.exception.d.ts

@@ -0,0 +1,5 @@
+import { RuntimeException } from 'node-exceptions';
+export declare class PermissionMissingException extends RuntimeException {
+    raw: Error;
+    constructor(err: Error, path: string);
+}

package/dist/exceptions/unknown.exception.d.ts

@@ -0,0 +1,5 @@
+import { RuntimeException } from 'node-exceptions';
+export declare class UnknownException extends RuntimeException {
+    raw: Error;
+    constructor(err: Error, errorCode: string, path: string);
+}

package/dist/exceptions/wrong-key-path.exception.d.ts

@@ -0,0 +1,5 @@
+import { RuntimeException } from 'node-exceptions';
+export declare class WrongKeyPathException extends RuntimeException {
+    raw: Error;
+    constructor(err: Error, path: string);
+}

package/dist/factorydrive/abstract.storage.d.ts

@@ -0,0 +1,20 @@
+import { ContentResponse, DeleteResponse, ExistsResponse, FileListResponse, Response, SignedUrlOptions, SignedUrlResponse, StatResponse } from './types';
+export default abstract class AbstractStorage {
+    constructor();
+    onStorageInit(): void | Promise<void>;
+    append(_location: string, _content: Buffer | string): Promise<Response>;
+    copy(_src: string, _dest: string): Promise<Response>;
+    delete(_location: string): Promise<DeleteResponse>;
+    driver(): unknown;
+    exists(_location: string): Promise<ExistsResponse>;
+    get(_location: string, _encoding?: string): Promise<ContentResponse<string>>;
+    getBuffer(_location: string): Promise<ContentResponse<Buffer>>;
+    getSignedUrl(_location: string, _options?: SignedUrlOptions): Promise<SignedUrlResponse>;
+    getStat(_location: string): Promise<StatResponse>;
+    getStream(_location: string): Promise<NodeJS.ReadableStream>;
+    getUrl(_location: string): string;
+    move(_src: string, _dest: string): Promise<Response>;
+    put(_location: string, _content: Buffer | NodeJS.ReadableStream | string): Promise<Response>;
+    prepend(_location: string, _content: Buffer | string): Promise<Response>;
+    flatList(_prefix?: string): AsyncIterable<FileListResponse>;
+}

package/dist/factorydrive/index.d.ts

@@ -0,0 +1,5 @@
+export { default as AbstractStorage } from './abstract.storage';
+export { default as StorageManager } from './storage.manager';
+export { LocalFileSystemStorage } from './local-file-system.storage';
+export * from './utils';
+export * from './types';

package/dist/factorydrive/local-file-system.storage.d.ts

@@ -0,0 +1,25 @@
+import * as fse from 'fs-extra';
+import AbstractStorage from './abstract.storage';
+import { ContentResponse, DeleteResponse, ExistsResponse, FileListResponse, Response, StatResponse } from './types';
+export declare class LocalFileSystemStorage extends AbstractStorage {
+    private readonly $root;
+    constructor(config: LocalFileSystemStorageConfig);
+    private _fullPath;
+    append(location: string, content: Buffer | string): Promise<Response>;
+    copy(src: string, dest: string): Promise<Response>;
+    delete(location: string): Promise<DeleteResponse>;
+    driver(): typeof fse;
+    exists(location: string): Promise<ExistsResponse>;
+    get(location: string, encoding?: BufferEncoding): Promise<ContentResponse<string>>;
+    getBuffer(location: string): Promise<ContentResponse<Buffer>>;
+    getStat(location: string): Promise<StatResponse>;
+    getStream(location: string): Promise<NodeJS.ReadableStream>;
+    move(src: string, dest: string): Promise<Response>;
+    prepend(location: string, content: Buffer | string): Promise<Response>;
+    put(location: string, content: Buffer | NodeJS.ReadableStream | string): Promise<Response>;
+    flatList(prefix?: string): AsyncIterable<FileListResponse>;
+    private _flatDirIterator;
+}
+export type LocalFileSystemStorageConfig = {
+    root: string;
+};

package/dist/factorydrive/storage.manager.d.ts

@@ -0,0 +1,20 @@
+import AbstractStorage from './abstract.storage';
+import type { StorageManagerConfig, StorageManagerSingleDiskConfig } from './types';
+interface StorageConstructor<T extends AbstractStorage = AbstractStorage> {
+    new (...args: any[]): T;
+}
+export default class StorageManager {
+    private readonly logger;
+    private readonly defaultDisk;
+    private readonly disksConfig;
+    private _disks;
+    private _drivers;
+    constructor(config: StorageManagerConfig);
+    getDisks(): Map<string, AbstractStorage>;
+    getDrivers(): Map<string, StorageConstructor>;
+    initDisks(): Promise<void>;
+    disk<T extends AbstractStorage = AbstractStorage>(name?: string): T;
+    addDisk(name: string, config: StorageManagerSingleDiskConfig): void;
+    registerDriver<T extends AbstractStorage>(name: string, driver: StorageConstructor<T>): void;
+}
+export {};

package/dist/factorydrive/types.d.ts

@@ -0,0 +1,42 @@
+import { LocalFileSystemStorageConfig } from './local-file-system.storage';
+export type { LocalFileSystemStorageConfig };
+export type StorageManagerSingleDiskConfig = {
+    driver: 'local';
+    config: LocalFileSystemStorageConfig;
+} | {
+    driver: string;
+    config: unknown;
+};
+export interface StorageManagerDiskConfig {
+    [key: string]: StorageManagerSingleDiskConfig;
+}
+export interface StorageManagerConfig {
+    default?: string;
+    disks?: StorageManagerDiskConfig;
+    registerLocalDriver?: boolean;
+}
+export interface Response {
+    raw: unknown;
+}
+export interface ExistsResponse extends Response {
+    exists: boolean;
+}
+export interface ContentResponse<ContentType> extends Response {
+    content: ContentType;
+}
+export interface SignedUrlOptions {
+    expiresIn?: number;
+}
+export interface SignedUrlResponse extends Response {
+    signedUrl: string;
+}
+export interface StatResponse extends Response {
+    size: number;
+    modified: Date;
+}
+export interface FileListResponse extends Response {
+    path: string;
+}
+export interface DeleteResponse extends Response {
+    wasDeleted: boolean | null;
+}

package/dist/factorydrive/utils.d.ts

@@ -0,0 +1,3 @@
+import { pipeline as nodePipeline } from 'stream';
+export declare function isReadableStream(stream: any): stream is NodeJS.ReadableStream;
+export declare const pipeline: typeof nodePipeline.__promisify__;

package/dist/factorydrive.constants.d.ts

@@ -0,0 +1 @@
+export declare const FACTORYDRIVE_MODULE_OPTIONS_TOKEN = "FactorydriveModuleOptionsToken";

package/dist/factorydrive.core-module.d.ts

@@ -0,0 +1,10 @@
+import { DynamicModule } from '@nestjs/common';
+import type { FactorydriveModuleAsyncOptions } from './factorydrive.interfaces';
+import type { StorageManagerConfig } from './factorydrive';
+export declare class FactorydriveCoreModule {
+    constructor();
+    static forRoot(options: StorageManagerConfig): DynamicModule;
+    static forRootAsync(options: FactorydriveModuleAsyncOptions): DynamicModule;
+    private static createAsyncProviders;
+    private static createAsyncOptionsProvider;
+}

package/dist/factorydrive.interfaces.d.ts

@@ -0,0 +1,11 @@
+import { ModuleMetadata, Type } from '@nestjs/common';
+import type { StorageManagerConfig } from './factorydrive';
+export interface FactorydriveModuleOptionsFactory {
+    createFactorydriveModuleOptions(): Promise<StorageManagerConfig> | StorageManagerConfig;
+}
+export interface FactorydriveModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
+    inject?: any[];
+    useClass?: Type<FactorydriveModuleOptionsFactory>;
+    useExisting?: Type<FactorydriveModuleOptionsFactory>;
+    useFactory?: (...args: any[]) => Promise<StorageManagerConfig> | StorageManagerConfig;
+}

package/dist/factorydrive.module.d.ts

@@ -0,0 +1,7 @@
+import { DynamicModule } from '@nestjs/common';
+import type { FactorydriveModuleAsyncOptions } from './factorydrive.interfaces';
+import type { StorageManagerConfig } from './factorydrive';
+export declare class FactorydriveModule {
+    static forRoot(options: StorageManagerConfig): DynamicModule;
+    static forRootAsync(options: FactorydriveModuleAsyncOptions): DynamicModule;
+}

package/dist/factorydrive.service.d.ts

@@ -0,0 +1,10 @@
+import { AbstractStorage } from './factorydrive';
+import type { StorageManagerConfig } from './factorydrive';
+export declare class FactorydriveService {
+    protected options: StorageManagerConfig;
+    private storageManager;
+    constructor(options: StorageManagerConfig);
+    onModuleInit(): Promise<void>;
+    getDisk<T extends AbstractStorage>(name?: string): T;
+    registerDriver(name: string, driver: new (...args: any[]) => AbstractStorage): void;
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './factorydrive';
+export * from './exceptions';
+export * from './factorydrive.module';
+export * from './factorydrive.interfaces';
+export * from './factorydrive.service';