fix(storage): add copy options for addMetadata

packages/helix-shared-storage/src/storage.d.ts

@@ -12,12 +12,32 @@
 
 import { S3Client } from "@aws-sdk/client-s3";
 
+
+export interface ObjectInfo {
+  key: string;
+  /** the path to the object, w/o the prefix */
+  path: string;
+  lastModified: string;
+  contentLength: number;
+  contentType: string;
+}
+
+/**
+ * @returns {boolean} {@code true} if the object is accepted
+ */
+export type ObjectFilter = (info: ObjectInfo) => boolean;
+
+export interface CopyOptions {
+  /** metadata to merge with existing metadata */
+  addMetadata?: Record<string, unknown>;
+}
+
 export declare interface Bucket {
-  get client():S3Client;
+  get client(): S3Client;
 
-  get bucket():string;
+  get bucket(): string;
 
-  get log():Console;
+  get log(): Console;
 
   get(key: string, meta?: object): Promise<Buffer | null>;
 
@@ -51,7 +71,7 @@ export declare interface Bucket {
    * @param {boolean} [compress = true]
    * @returns result obtained from S3
    */
-  put(path: string, body: Buffer, contentType?: string, meta?: object, compress?: bool): Promise<object>;
+  put(path: string, body: Buffer, contentType?: string, meta?: object, compress?: boolean): Promise<object>;
 
   /**
    * Updates the metadata
@@ -67,9 +87,10 @@ export declare interface Bucket {
    *
    * @param {string} src source key
    * @param {string} dst destination key
+   * @param {CopyOptions} [opts]
    * @returns result obtained from S3
    */
-  copy(src: string, dst: string): Promise<void>;
+  copy(src: string, dst: string, opts?: CopyOptions): Promise<void>;
 
   /**
    * Remove object(s)
@@ -93,50 +114,51 @@ export declare interface Bucket {
    * @param {string} src Source prefix
    * @param {string} dst Destination prefix
    * @param {ObjectFilter} filter Filter function
+   * @param {CopyOptions} [opts]
    * @returns {Promise<*[]>}
    */
-  copyDeep(src: string, dst: string, filter?: function): Promise<object[]>;
+  copyDeep(src: string, dst: string, filter?: ObjectFilter, opts?: CopyOptions): Promise<object[]>;
 
   rmdir(src: string): Promise<void>;
 }
 
 /**
  * The Helix Storage provides a factory for simplified bucket operations to S3 and R2
  */
-export class HelixStorage {
-  static fromContext(context:AdminContext):HelixStorage;
+export declare class HelixStorage {
+  static fromContext(context: AdminContext): HelixStorage;
 
-  s3():S3Client;
+  s3(): S3Client;
 
   /**
    * creates a bucket instance that allows to perform storage related operations.
    * @param bucketId
    * @returns {Bucket}
    */
-  bucket(bucketId:string):Bucket;;
+  bucket(bucketId: string): Bucket;;
 
   /**
    * @returns {Bucket}
    */
-  contentBus():Bucket;
+  contentBus(): Bucket;
 
   /**
    * @returns {Bucket}
    */
-  codeBus():Bucket;
+  codeBus(): Bucket;
 
   /**
    * @returns {Bucket}
    */
-  mediaBus():Bucket;
+  mediaBus(): Bucket;
 
   /**
    * @returns {Bucket}
    */
-  configBus():Bucket;
+  configBus(): Bucket;
 
   /**
    * Close this storage. Destroys the S3 client used.
    */
-  close()
+  close(): void;
 }

packages/helix-shared-storage/src/storage.js

@@ -35,21 +35,11 @@ const gunzip = promisify(zlib.gunzip);
 
 /**
  * @typedef {import('@aws-sdk/client-s3').CommandInput} CommandInput
- */
-
-/**
- * @typedef ObjectInfo
- * @property {string} key
- * @property {string} path the path to the object, w/o the prefix
- * @property {string} lastModified
- * @property {number} contentLength
- * @property {string} contentType
- */
-
-/**
- * @callback ObjectFilter
- * @param {ObjectInfo} info of the object to filter
- * @returns {boolean} {@code true} if the object is accepted
+ * @typedef {import('./storage.d').Bucket} BucketType
+ * @typedef {import('./storage.d').HelixStorage} HelixStorageType
+ * @typedef {import('./storage.d').ObjectInfo} ObjectInfo
+ * @typedef {import('./storage.d').ObjectFilter} ObjectFilter
+ * @typedef {import('./storage.d').CopyOptions} CopyOptions
  */
 
 /**
@@ -92,6 +82,7 @@ function sanitizeKey(keyOrPath) {
 
 /**
  * Bucket class
+ * @implements {BucketType}
  */
 class Bucket {
   constructor(opts) {
@@ -308,16 +299,23 @@ class Bucket {
    *
    * @param {string} src source key
    * @param {string} dst destination key
+   * @param {CopyOptions} [opts]
    * @returns result obtained from S3
    */
-  async copy(src, dst) {
+  async copy(src, dst, opts = {}) {
+    const key = sanitizeKey(src);
     const input = {
       Bucket: this.bucket,
-      CopySource: `${this.bucket}/${sanitizeKey(src)}`,
+      CopySource: `${this.bucket}/${key}`,
       Key: sanitizeKey(dst),
     };
 
     try {
+      if (opts.addMetadata) {
+        const meta = await this.metadata(key) ?? {};
+        input.Metadata = { ...meta, ...opts.addMetadata };
+        input.MetadataDirective = 'REPLACE';
+      }
       // write to s3 and r2 (mirror) in parallel
       await this.sendToS3andR2(CopyObjectCommand, input);
       this.log.info(`object copied from ${input.CopySource} to: ${input.Bucket}/${input.Key}`);
@@ -432,9 +430,10 @@ class Bucket {
    * @param {string} src Source prefix
    * @param {string} dst Destination prefix
    * @param {ObjectFilter} filter Filter function
+   * @param {CopyOptions} [opts={}]
    * @returns {Promise<*[]>}
    */
-  async copyDeep(src, dst, filter = () => true) {
+  async copyDeep(src, dst, filter = () => true, opts = {}) {
     const { log } = this;
     const tasks = [];
     const Prefix = sanitizeKey(src);
@@ -465,6 +464,11 @@ class Bucket {
         Key: task.dst,
       };
       try {
+        if (opts.addMetadata) {
+          const meta = await this.metadata(task.src) ?? {};
+          input.Metadata = { ...meta, ...opts.addMetadata };
+          input.MetadataDirective = 'REPLACE';
+        }
         // write to s3 and r2 (mirror) in parallel
         await this.sendToS3andR2(CopyObjectCommand, input);
         changes.push(task);
@@ -510,6 +514,7 @@ class Bucket {
 
 /**
  * The Helix Storage provides a factory for simplified bucket operations to S3 and R2
+ * @implements {HelixStorageType}
  */
 export class HelixStorage {
   static fromContext(context) {