From c5555be90eb55019b0cdcaabc6c4789199a12c75 Mon Sep 17 00:00:00 2001
From: Maxence Van Bockstaele <maxence.vanbockstaele@sagacify.com>
Date: Fri, 13 Jun 2025 14:37:41 +0200
Subject: [PATCH] feat(head): adds head object command

---
 src/S3Handler.ts       | 16 +++++++++++++++
 test/src/headObject.ts | 44 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 60 insertions(+)
 create mode 100644 test/src/headObject.ts

diff --git a/src/S3Handler.ts b/src/S3Handler.ts
index c05db19..71e94a4 100644
--- a/src/S3Handler.ts
+++ b/src/S3Handler.ts
@@ -8,6 +8,9 @@ import {
   GetObjectCommand,
   GetObjectCommandInput,
   GetObjectCommandOutput,
+  HeadObjectCommand,
+  HeadObjectCommandInput,
+  HeadObjectCommandOutput,
   ListObjectsV2Command,
   ListObjectsV2CommandInput,
   ObjectIdentifier,
@@ -179,6 +182,19 @@ export class S3Handler {
     const command = new PutObjectCommand({ Bucket: this.bucket, Key: key, ...getObjectOptions });
     return getSignedUrl(this.client, command, signedUrlOptions);
   }
+
+  async headObject(
+    key: string,
+    options: Omit<HeadObjectCommandInput, 'Bucket' | 'Key'> = {}
+  ): Promise<HeadObjectCommandOutput> {
+    const headObjectCommand = new HeadObjectCommand({
+      Bucket: this.bucket,
+      Key: key,
+      ...options
+    });
+
+    return this.client.send(headObjectCommand);
+  }
 }
 
 export default S3Handler;
diff --git a/test/src/headObject.ts b/test/src/headObject.ts
new file mode 100644
index 0000000..b11e907
--- /dev/null
+++ b/test/src/headObject.ts
@@ -0,0 +1,44 @@
+import { expect } from 'chai';
+import { HeadObjectCommand, S3Client } from '@aws-sdk/client-s3';
+import { mockClient } from 'aws-sdk-client-mock';
+import { S3Handler } from '../../src/S3Handler';
+
+describe('S3Handler.headObject', () => {
+  const s3ClientMock = mockClient(S3Client);
+
+  beforeEach(() => {
+    s3ClientMock.reset();
+  });
+
+  it('should call headObject with the correct key', async () => {
+    s3ClientMock.on(HeadObjectCommand).resolvesOnce({});
+
+    const s3Handler = new S3Handler(new S3Client({}), 'my-dummy-bucket');
+
+    await s3Handler.headObject('my-key');
+
+    expect(s3ClientMock.commandCalls(HeadObjectCommand).length).to.equal(1);
+    expect(s3ClientMock.commandCalls(HeadObjectCommand)[0].args[0].input).to.deep.equal({
+      Bucket: 'my-dummy-bucket',
+      Key: 'my-key'
+    });
+  });
+
+  it('should call headObject and return metadata', async () => {
+    s3ClientMock.on(HeadObjectCommand).resolvesOnce({
+      Metadata: { myCustomId: '1' },
+      ContentType: 'text/plain'
+    });
+
+    const s3Handler = new S3Handler(new S3Client({}), 'my-dummy-bucket');
+
+    const res = await s3Handler.headObject('my-key');
+
+    expect(res).to.deep.equal({
+      Metadata: { myCustomId: '1' },
+      ContentType: 'text/plain'
+    });
+
+    expect(s3ClientMock.commandCalls(HeadObjectCommand).length).to.equal(1);
+  });
+});