From 6e2a03d1962d779acae986912b0044e819f5c2a6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Hask=C5=8D?= <hasko@Haskos-MacBook-Air-M5.local>
Date: Tue, 13 Oct 2026 10:16:08 +0200
Subject: [PATCH] =?UTF-8?q?fix(file-size):=20=F0=9F=90=9B=20Type=20FileSiz?=
 =?UTF-8?q?e=20add=20and=20subtract=20as=20FileSize?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/reference/file-size.md             | 20 ++++++++++----------
 src/value-objects/file-size/FileSize.ts |  8 ++++++++
 tests/value-objects/FileSize.spec.ts    |  4 ++++
 3 files changed, 22 insertions(+), 10 deletions(-)

diff --git a/docs/reference/file-size.md b/docs/reference/file-size.md
index 1b77c4f..5e8dd12 100644
--- a/docs/reference/file-size.md
+++ b/docs/reference/file-size.md
@@ -31,16 +31,16 @@ Accepts integers greater than or equal to `0`.
 
 ## Methods
 
-| Method | Description |
-| --- | --- |
-| `static fromBytes(bytes)` | Creates a size from bytes. |
-| `static from(value, unit)` | Creates a size from a value in a `FileSizeUnit`, rounded to the nearest byte. |
-| `static parse(text)` | Parses text such as `1.5 MiB` or `2MB`. |
-| `toBytes()` | Returns the bytes as `PositiveInteger`. |
-| `to(unit)` | Returns the size in `unit` as `NumberValueObject`, without rounding. |
-| `toHumanReadable(units)` | Returns `{ value, unit }` using the largest unit of `units` that fits. |
-| `add(other)` | Returns the sum as `FileSize`. |
-| `subtract(other)` | Returns the difference as `FileSize`. |
+| Method                      | Description                                                                                          |
+| --------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `static fromBytes(bytes)`   | Creates a size from bytes.                                                                           |
+| `static from(value, unit)`  | Creates a size from a value in a `FileSizeUnit`, rounded to the nearest byte.                        |
+| `static parse(text)`        | Parses text such as `1.5 MiB` or `2MB`.                                                              |
+| `toBytes()`                 | Returns the bytes as `PositiveInteger`.                                                              |
+| `to(unit)`                  | Returns the size in `unit` as `NumberValueObject`, without rounding.                                 |
+| `toHumanReadable(units)`    | Returns `{ value, unit }` using the largest unit of `units` that fits.                               |
+| `add(other: FileSize)`      | Returns the sum as `FileSize`.                                                                       |
+| `subtract(other: FileSize)` | Returns the difference as `FileSize`. Throws `InvalidPositiveNumberError` if the result is negative. |
 
 Comparison and the rest of the arithmetic are inherited from `NumberValueObject`.
 
diff --git a/src/value-objects/file-size/FileSize.ts b/src/value-objects/file-size/FileSize.ts
index 17f1247..4e8a246 100644
--- a/src/value-objects/file-size/FileSize.ts
+++ b/src/value-objects/file-size/FileSize.ts
@@ -41,6 +41,14 @@ export class FileSize extends PositiveInteger {
     return new this(Math.round(Number(value) * unit.getBytes().valueOf()));
   }
 
+  public add(other: FileSize): FileSize {
+    return this.clone(this.value + other.valueOf());
+  }
+
+  public subtract(other: FileSize): FileSize {
+    return this.clone(this.value - other.valueOf());
+  }
+
   public toBytes(): PositiveInteger {
     return new PositiveInteger(this.value);
   }
diff --git a/tests/value-objects/FileSize.spec.ts b/tests/value-objects/FileSize.spec.ts
index 52563a7..cf6ad02 100644
--- a/tests/value-objects/FileSize.spec.ts
+++ b/tests/value-objects/FileSize.spec.ts
@@ -60,6 +60,10 @@ describe('FileSize', () => {
       const sum = new FileSize(1000).add(new FileSize(24));
       const diff = new FileSize(1000).subtract(new FileSize(400));
 
+      // Compile-time check: only compiles if both return FileSize
+      expect(sum.to(FileSizeUnit.KIBIBYTE).valueOf()).toBeCloseTo(1);
+      expect(diff.to(FileSizeUnit.BYTE).valueOf()).toBe(600);
+
       expect(sum).toBeInstanceOf(FileSize);
       expect(sum.valueOf()).toBe(1024);
       expect(diff).toBeInstanceOf(FileSize);