feat(serialization): ✨ Add toJSON to value objects

docs/guides/serialization.md

@@ -5,7 +5,17 @@ description: Serialization notes for @haskou/value-objects
 
 # Serialization
 
-Most value objects serialize through `valueOf()`.
+Every value object implements `toJSON()` returning its primitive, so `JSON.stringify` emits clean values.
+
+```typescript
+JSON.stringify({
+  email: new Email('user@example.com'),
+  createdAt: new Timestamp(1782218400000),
+});
+// {"email":"user@example.com","createdAt":1782218400000}
+```
+
+`valueOf()` returns the same primitive.
 
 ```typescript
 const email = new Email('user@example.com');

docs/reference/value-object.md

@@ -83,6 +83,7 @@ Specialized Value Objects may normalize value comparison by overriding `hasValue
 | `static enableNullObjectCreation()` | Restores automatic NullObject creation. |
 | `valueOf()` | Returns the wrapped primitive value. Null objects return `undefined`. |
 | `toString()` | Returns `valueOf().toString()`. |
+| `toJSON()` | Returns the wrapped primitive, so `JSON.stringify` emits `"a@b.co"` instead of `{"value":"a@b.co"}`. |
 | `hasValue(other)` | Compares only the wrapped value; accepts another Value Object or a primitive. |
 | `isEqual(other)` | Returns true only for the same concrete Value Object class with an equal value. |
 | `isNotEqual(other)` | Negates `isEqual()`. |
@@ -103,6 +104,8 @@ name.hasValue('hasko'); // true
 
 ## Notes
 
+- `toString()` and `toJSON()` throw `NullObjectError` on null objects, like every other method.
+
 - Use `isEqual()` for domain equality between Value Objects.
 - Use `hasValue()` only when comparing the underlying value is intentional.
 - Most concrete classes in this package extend `ValueObject` directly or indirectly.

src/value-objects/ValueObject.ts

@@ -26,7 +26,7 @@
     Object.defineProperty(this, 'value', {
       value,
       writable: false,
       configurable: false,
       enumerable: true,
     });
   }
@@ -66,4 +66,8 @@
   public toString(): string {
     return this.value!.toString();
   }
+
+  public toJSON(): T {
+    return this.value;
+  }
 }

tests/value-objects/Serialization.spec.ts

@@ -0,0 +1,46 @@
+import {
+  Coordinates,
+  Email,
+  NullObject,
+  NullObjectError,
+  NumberValueObject,
+  StringValueObject,
+  Timestamp,
+} from '../../src';
+
+describe('Serialization', () => {
+  it('should serialize primitives in JSON.stringify', () => {
+    const payload = {
+      coordinates: new Coordinates(1, 2),
+      email: new Email('a@b.co'),
+      number: new NumberValueObject(3),
+      timestamp: new Timestamp(1000),
+    };
+
+    expect(JSON.parse(JSON.stringify(payload))).toEqual({
+      coordinates: '1,2',
+      email: 'a@b.co',
+      number: 3,
+      timestamp: 1000,
+    });
+  });
+
+  it('should return the primitive from toJSON', () => {
+    expect(new StringValueObject('abc').toJSON()).toBe('abc');
+    expect(new NumberValueObject(7).toJSON()).toBe(7);
+  });
+
+  it('should keep toString as the string representation', () => {
+    expect(new NumberValueObject(7).toString()).toBe('7');
+    expect(new Coordinates(1, 2).toString()).toBe('1,2');
+  });
+
+  it('should throw NullObjectError on a NullObject', () => {
+    const nullObject = new StringValueObject(null as never);
+
+    expect(NullObject.isNullObject(nullObject)).toBeTrue();
+    expect(() => nullObject.toJSON()).toThrow(NullObjectError);
+    expect(() => nullObject.toString()).toThrow(NullObjectError);
+    expect(() => JSON.stringify({ nullObject })).toThrow(NullObjectError);
+  });
+});