Merge pull request #53 from LabO8/feature/prefix-algorithm-setting

feat: allow custom prefix algorithm implementation

Author: MartinAndreev

site/docs/prefixing.md

@@ -0,0 +1,66 @@
+---
+id: prefixing
+title: Prefixing
+sidebar_label: Prefixing
+slug: /prefixing
+---
+
+## Introduction
+
+As our app grows, we might want to store our objects in a more organized way. This is where the prefix comes in.
+
+The prefix is a string that is prepended to the object key. This allows us to organize our objects in a folder-like structure.
+
+For example, if we have a bucket called `my-bucket` and we want to store our objects in a folder called `my-folder`, we can do that by prepending the prefix `my-folder/` to the object key.
+
+## Usage
+
+By default, the prefix is an empty string. This means that the object key is not modified, but if you set a prefix, when you initialize the module, the prefix will be prepended to the object key.
+
+The default algorithm for prefixing will just prepend the prefix to the object key, but you can also specify a custom algorithm.
+
+**All services like the `ObjectService` will use the prefix service by default.**
+
+## Custom prefixing
+
+In order to use a custom prefixing algorithm, you need to specify the `prefixingAlgorithm` when initializing the module.
+
+```typescript
+class CustomPrefixService implements IPrefixAlgorithm {
+  prefix(remote: string, prefix: string, bucket?: string): string {
+    return `${bucket}/${prefix}${remote}`;
+  }
+}
+
+S3Module.forRoot({
+  region: 'region',
+  accessKeyId: '***',
+  secretAccessKey: '***',
+  prefix: 'test/',
+  prefixAlgorithm: new CustomPrefixService(),
+})
+```
+
+you can also use injectables
+
+```typescript
+ class CustomPrefixWithDIService implements IPrefixAlgorithm {
+  public constructor(private readonly globalPrefix: string) {}
+
+  prefix(remote: string, prefix: string, bucket?: string): string {
+    return `${bucket}/${this.globalPrefix}${prefix}${remote}`;
+  }
+}
+
+S3Module.forRootAsync({
+  imports: [SomeModuleThatProvidesTheGlobalPrefix],
+  prefixAlgorithmInject: ['GLOBAL_PREFIX'],
+  prefixAlgorithmFactory: (globalPrefix: string) => new CustomPrefixWithDIService(globalPrefix),
+  useFactory: () => ({
+    region: 'region',
+    accessKeyId: '***',
+    secretAccessKey: '***',
+    prefix: 'test/',
+  }),
+})
+```

site/sidebars.js

@@ -15,7 +15,7 @@
 const sidebars = {
   docsSidebar: {
     Introduction: ['getting-started'],
-    Services: ['buckets', 'objects', 'signed-url', 'download-helper', 'deletion-helper'],
+    Services: ['buckets', 'objects', 'signed-url', 'download-helper', 'prefix', 'deletion-helper'],
     API: [
       {
         type: 'autogenerated',

src/constants.ts

@@ -1,4 +1,4 @@
 export const S3_CONFIG = 's3.config';
 export const S3_SERVICE = 's3.service';
-
+export const PREFIX_ALGORITHM = 'prefix.algorithm';
 export const DEFAULT_EXPIRES_IN = 3600;

src/interfaces/index.ts

@@ -0,0 +1 @@
+export * from './prefix-algorithm.interface';

src/interfaces/prefix-algorithm.interface.ts

@@ -0,0 +1,3 @@
+export interface IPrefixAlgorithm {
+  prefix(remote: string, prefix?: string, bucket?: string): string;
+}

src/s3.module.ts

@@ -1,8 +1,14 @@
 import { HttpModule } from '@nestjs/axios';
 import { DynamicModule, Global, Module, Provider } from '@nestjs/common';
-import { S3_CONFIG } from './constants';
+import { PREFIX_ALGORITHM, S3_CONFIG } from './constants';
 import { createS3ServiceProvider } from './s3-service.factory';
-import { BucketsService, ObjectsService, PrefixService, SignedUrlService } from './services';
+import {
+  BucketsService,
+  DefaultPrefixAlgorithmService,
+  ObjectsService,
+  PrefixService,
+  SignedUrlService,
+} from './services';
 import { S3AsyncConfig, S3Config } from './types';
 import { DeletionService, DownloadService } from './utils';
 
@@ -21,6 +27,10 @@ const createSharedProviders = (config: S3Config): Provider[] => [
     provide: S3_CONFIG,
     useValue: config,
   },
+  {
+    provide: PREFIX_ALGORITHM,
+    useValue: config.prefixAlgorithm ? (config.prefixAlgorithm as any) : new DefaultPrefixAlgorithmService(),
+  },
   ...providers,
 ];
 
@@ -30,6 +40,13 @@ const createSharedProvidersAsync = (provider: S3AsyncConfig): Provider[] => [
     useFactory: provider.useFactory,
     inject: provider.inject || [],
   },
+  {
+    provide: PREFIX_ALGORITHM,
+    useFactory: provider.prefixAlgorithmFactory
+      ? provider.prefixAlgorithmFactory
+      : () => new DefaultPrefixAlgorithmService(),
+    inject: provider.prefixAlgorithmInject || [],
+  },
   ...providers,
 ];
 

src/services/default-prefix-algorithm.service.ts

@@ -0,0 +1,11 @@
+import { IPrefixAlgorithm } from '../interfaces';
+
+export class DefaultPrefixAlgorithmService implements IPrefixAlgorithm {
+  prefix(remote: string, prefix?: string, bucket?: string): string {
+    if (!prefix) {
+      return remote;
+    }
+
+    return `${prefix}${remote}`;
+  }
+}

src/services/index.ts

@@ -2,3 +2,4 @@ export * from './buckers.service';
 export * from './objects.service';
 export * from './prefix.service';
 export * from './signed-url.service';
+export * from './default-prefix-algorithm.service';

src/services/objects.service.ts

@@ -46,7 +46,7 @@ export class ObjectsService {
       new PutObjectCommand({
         Bucket: bucket,
         Body: body,
-        Key: disableAutoPrefix ? remote : this.prefixService.prefix(remote),
+        Key: disableAutoPrefix ? remote : this.prefixService.prefix(remote, bucket),
         ...preparedOptions,
       }),
     );
@@ -73,7 +73,7 @@ export class ObjectsService {
     return this.client.send(
       new DeleteObjectCommand({
         Bucket: bucket,
-        Key: disableAutoPrefix ? remote : this.prefixService.prefix(remote),
+        Key: disableAutoPrefix ? remote : this.prefixService.prefix(remote, bucket),
         ...preparedOptions,
       }),
     );
@@ -90,7 +90,7 @@ export class ObjectsService {
       new DeleteObjectsCommand({
         Bucket: bucket,
         Delete: {
-          Objects: remotes.map((r) => ({ Key: disableAutoPrefix ? r : this.prefixService.prefix(r) })),
+          Objects: remotes.map((r) => ({ Key: disableAutoPrefix ? r : this.prefixService.prefix(r, bucket) })),
         },
         ...preparedOptions,
       }),
@@ -103,7 +103,7 @@ export class ObjectsService {
     return this.client.send(
       new GetObjectCommand({
         Bucket: bucket,
-        Key: disableAutoPrefix ? remote : this.prefixService.prefix(remote),
+        Key: disableAutoPrefix ? remote : this.prefixService.prefix(remote, bucket),
         ...preparedOptions,
       }),
     );

src/services/prefix.service.ts

@@ -1,18 +1,18 @@
 import { Inject, Injectable } from '@nestjs/common';
-import { S3_CONFIG } from '../constants';
+import { PREFIX_ALGORITHM, S3_CONFIG } from '../constants';
 import { S3Config } from '../types';
+import { IPrefixAlgorithm } from '../interfaces';
 
 @Injectable()
 export class PrefixService {
-  public constructor(@Inject(S3_CONFIG) private readonly config: S3Config) {}
+  public constructor(
+    @Inject(S3_CONFIG) private readonly config: S3Config,
+    @Inject(PREFIX_ALGORITHM) private readonly prefixAlgorithm: IPrefixAlgorithm,
+  ) {}
 
-  public prefix(remote: string): string {
+  public prefix(remote: string, bucket?: string): string {
     const { prefix } = this.config;
 
-    if (!prefix) {
-      return remote;
-    }
-
-    return `${prefix}${remote}`;
+    return this.prefixAlgorithm.prefix(remote, prefix, bucket);
   }
 }