@bgord/tools 1.0.4 → 1.1.0

package/dist/week.vo.js

@@ -4,8 +4,8 @@ import { Timestamp } from "./timestamp.vo";
 import { WeekIsoId } from "./week-iso-id.vo";
 export class Week extends DateRange {
     static fromTimestamp(timestamp) {
-        const start = Timestamp.parse(startOfISOWeek(timestamp).getTime());
-        const end = Timestamp.parse(endOfISOWeek(timestamp).getTime());
+        const start = Timestamp.fromNumber(startOfISOWeek(timestamp.get()).getTime());
+        const end = Timestamp.fromNumber(endOfISOWeek(timestamp.get()).getTime());
         return new Week(start, end);
     }
     static fromNow(now) {
@@ -15,11 +15,11 @@ export class Week extends DateRange {
         const [year, week] = WeekIsoId.parse(isoId).split("-W").map(Number);
         // ISO-8601 rule: Jan 4 is always in week 01 of the ISO week-year.
         const reference = setISOWeek(Date.UTC(year, 0, 4), week).getTime();
-        return Week.fromTimestamp(Timestamp.parse(reference));
+        return Week.fromTimestamp(Timestamp.fromNumber(reference));
     }
     toIsoId() {
-        const year = getISOWeekYear(this.getStart());
-        const week = getISOWeek(this.getStart());
+        const year = getISOWeekYear(this.getStart().get());
+        const week = getISOWeek(this.getStart().get());
         return WeekIsoId.parse(`${year}-W${String(week).padStart(2, "0")}`);
     }
     previous() {
@@ -29,8 +29,8 @@ export class Week extends DateRange {
         return this.shift(1);
     }
     shift(count) {
-        const shifted = addWeeks(this.getStart(), count).getTime();
-        return Week.fromTimestamp(Timestamp.parse(shifted));
+        const shifted = addWeeks(this.getStart().get(), count).getTime();
+        return Week.fromTimestamp(Timestamp.fromNumber(shifted));
     }
     toString() {
         return this.toIsoId();

package/dist/weekday.vo.d.ts

@@ -1,4 +1,4 @@
-import type { TimestampType } from "./timestamp.vo";
+import type { Timestamp } from "./timestamp.vo";
 export type WeekdayFormatter = (value: Weekday["value"]) => string;
 export declare enum WeekdayFormatterEnum {
     FULL = "FULL",// "Sunday"
@@ -19,7 +19,7 @@ export declare class Weekday {
     static readonly FRIDAY: Weekday;
     static readonly SATURDAY: Weekday;
     constructor(candidate: number, formatter?: WeekdayFormatter);
-    static fromUtcTimestamp(timestamp: TimestampType, formatter?: WeekdayFormatter): Weekday;
+    static fromUtcTimestamp(timestamp: Timestamp, formatter?: WeekdayFormatter): Weekday;
     get(): number;
     format(): string;
     toString(): string;

package/dist/weekday.vo.js

@@ -41,7 +41,7 @@ export class Weekday {
         this.formatter = formatter ?? WeekdayFormatters.FULL;
     }
     static fromUtcTimestamp(timestamp, formatter) {
-        const dayZeroBased = new Date(timestamp).getUTCDay(); // 0..6
+        const dayZeroBased = new Date(timestamp.get()).getUTCDay(); // 0..6
         return new Weekday(dayZeroBased, formatter);
     }
     get() {

package/dist/year.vo.d.ts

@@ -1,9 +1,9 @@
 import { DateRange } from "./date-range.vo";
-import { type TimestampType } from "./timestamp.vo";
+import { Timestamp } from "./timestamp.vo";
 import { type YearIsoIdType } from "./year-iso-id.vo";
 export declare class Year extends DateRange {
-    static fromTimestamp(timestamp: TimestampType): Year;
-    static fromNow(now: TimestampType): Year;
+    static fromTimestamp(timestamp: Timestamp): Year;
+    static fromNow(now: Timestamp): Year;
     static fromNumber(candidate: number): Year;
     static fromIsoId(isoId: YearIsoIdType): Year;
     toIsoId(): YearIsoIdType;

package/dist/year.vo.js

@@ -4,8 +4,8 @@ import { Timestamp } from "./timestamp.vo";
 import { YearIsoId } from "./year-iso-id.vo";
 export class Year extends DateRange {
     static fromTimestamp(timestamp) {
-        const start = Timestamp.parse(startOfYear(timestamp).getTime());
-        const end = Timestamp.parse(endOfYear(timestamp).getTime());
+        const start = Timestamp.fromNumber(startOfYear(timestamp.get()).getTime());
+        const end = Timestamp.fromNumber(endOfYear(timestamp.get()).getTime());
         return new Year(start, end);
     }
     static fromNow(now) {
@@ -16,13 +16,13 @@ export class Year extends DateRange {
     }
     static fromIsoId(isoId) {
         const reference = Date.UTC(Number(isoId));
-        return Year.fromTimestamp(Timestamp.parse(reference));
+        return Year.fromTimestamp(Timestamp.fromNumber(reference));
     }
     toIsoId() {
-        return YearIsoId.parse(String(getYear(this.getStart())));
+        return YearIsoId.parse(String(getYear(this.getStart().get())));
     }
     isLeapYear() {
-        const year = getYear(this.getStart());
+        const year = getYear(this.getStart().get());
         return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
     }
     previous() {
@@ -32,8 +32,8 @@ export class Year extends DateRange {
         return this.shift(1);
     }
     shift(count) {
-        const shifted = addYears(this.getStart(), count).getTime();
-        return Year.fromTimestamp(Timestamp.parse(shifted));
+        const shifted = addYears(this.getStart().get(), count).getTime();
+        return Year.fromTimestamp(Timestamp.fromNumber(shifted));
     }
     toString() {
         return this.toIsoId();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bgord/tools",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "type": "module",
   "license": "MIT",
   "author": "Bartosz Gordon",
@@ -21,14 +21,14 @@
     "preinstall": "bunx only-allow bun"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.3.1",
+    "@biomejs/biome": "2.3.2",
     "@commitlint/cli": "20.1.0",
     "@commitlint/config-conventional": "20.0.0",
     "@types/bun": "1.3.1",
     "@types/mime-types": "3.0.1",
     "cspell": "9.2.2",
-    "knip": "5.66.3",
-    "lefthook": "2.0.1",
+    "knip": "5.66.4",
+    "lefthook": "2.0.2",
     "only-allow": "1.2.1",
     "shellcheck": "4.1.0",
     "typescript": "5.9.3",

package/readme.md

@@ -104,7 +104,7 @@ src/
 ├── sum.service.ts
 ├── thousands-separator.service.ts
 ├── time-zone-offset-value.vo.ts
-├── time.service.ts
+├── timestamp-value.vo.ts
 ├── timestamp.vo.ts
 ├── timezone.vo.ts
 ├── ts-utils.ts

package/src/age.vo.ts

@@ -1,6 +1,6 @@
 import { differenceInYears } from "date-fns";
 import { AgeYears, AgeYearsConstraints, type AgeYearsType } from "./age-years.vo";
-import type { TimestampType } from "./timestamp.vo";
+import { Timestamp } from "./timestamp.vo";
 
 export const AgeError = { FutureBirthdate: "age.future.birthdate" } as const;
 
@@ -14,16 +14,16 @@ export class Age {
     return new Age(AgeYears.parse(candidate));
   }
 
-  static fromBirthdateEpochMs(params: { birthdate: TimestampType; now: TimestampType }): Age {
-    if (params.birthdate > params.now) throw new Error(AgeError.FutureBirthdate);
-    return Age.fromValue(differenceInYears(params.now, params.birthdate));
+  static fromBirthdateEpochMs(params: { birthdate: Timestamp; now: Timestamp }): Age {
+    if (params.birthdate.isAfter(params.now)) throw new Error(AgeError.FutureBirthdate);
+    return Age.fromValue(differenceInYears(params.now.get(), params.birthdate.get()));
   }
 
-  static fromBirthdate(candidate: { birthdate: string; now: TimestampType }): Age {
-    const birthdateMs = new Date(candidate.birthdate).getTime();
+  static fromBirthdate(candidate: { birthdate: string; now: Timestamp }): Age {
+    const birthdate = Timestamp.fromNumber(new Date(candidate.birthdate).getTime());
 
-    if (birthdateMs > candidate.now) throw new Error(AgeError.FutureBirthdate);
-    return Age.fromValue(differenceInYears(candidate.now, birthdateMs));
+    if (birthdate.isAfter(candidate.now)) throw new Error(AgeError.FutureBirthdate);
+    return Age.fromValue(differenceInYears(candidate.now.get(), birthdate.get()));
   }
 
   get(): number {

package/src/clock.vo.ts

@@ -3,7 +3,7 @@ import { Hour } from "./hour.vo";
 import type { HourSchemaType } from "./hour-schema.vo";
 import { Minute } from "./minute.vo";
 import type { MinuteSchemaType } from "./minute-schema.vo";
-import type { TimestampType } from "./timestamp.vo";
+import type { Timestamp } from "./timestamp.vo";
 
 export class Clock {
   private readonly formatter: ClockFormatter;
@@ -16,7 +16,7 @@ export class Clock {
     this.formatter = formatter ?? ClockFormatters.TWENTY_FOUR_HOURS;
   }
 
-  static fromEpochMs(timestamp: TimestampType, formatter?: ClockFormatter): Clock {
+  static fromEpochMs(timestamp: Timestamp, formatter?: ClockFormatter): Clock {
     const hour = Hour.fromEpochMs(timestamp);
     const minute = Minute.fromEpochMs(timestamp);
 
@@ -32,17 +32,17 @@ export class Clock {
   }
 
   equals(another: Clock): boolean {
-    return this.hour.get() === another.hour.get() && this.minute.get() === another.minute.get();
+    return this.hour.equals(another.hour) && this.minute.equals(another.minute);
   }
 
   isAfter(another: Clock): boolean {
-    if (this.hour.get() !== another.hour.get()) return this.hour.get() > another.hour.get();
-    return this.minute.get() > another.minute.get();
+    if (!this.hour.equals(another.hour)) return this.hour.isAfter(another.hour);
+    return this.minute.isAfter(another.minute);
   }
 
   isBefore(another: Clock): boolean {
-    if (this.hour.get() !== another.hour.get()) return this.hour.get() < another.hour.get();
-    return this.minute.get() < another.minute.get();
+    if (!this.hour.equals(another.hour)) return this.hour.isBefore(another.hour);
+    return this.minute.isBefore(another.minute);
   }
 
   toString(): string {

package/src/date-calculator.service.ts

@@ -1,22 +1,22 @@
 import { Duration } from "./duration.service";
 import type { TimeZoneOffsetValueType } from "./time-zone-offset-value.vo";
-import { Timestamp, type TimestampType } from "./timestamp.vo";
+import { Timestamp } from "./timestamp.vo";
 
-type GetStartOfDayTsInTzConfigType = { now: TimestampType; timeZoneOffsetMs: TimeZoneOffsetValueType };
+type GetStartOfDayTsInTzConfigType = { now: Timestamp; timeZoneOffsetMs: TimeZoneOffsetValueType };
 
 export class DateCalculator {
-  static getStartOfDayTsInTz(config: GetStartOfDayTsInTzConfigType): TimestampType {
+  static getStartOfDayTsInTz(config: GetStartOfDayTsInTzConfigType): Timestamp {
     const dayMs = Duration.Days(1).ms;
 
     // UTC midnight for the UTC date of `now`
-    const utcMidnight = Math.floor(config.now / dayMs) * dayMs;
+    const utcMidnight = Math.floor(config.now.get() / dayMs) * dayMs;
 
     // Candidate start of the local day (in UTC), anchored to the same UTC date
     let start = utcMidnight + config.timeZoneOffsetMs;
 
     // If the candidate is in the future relative to `now`, it means local midnight was "yesterday" in UTC.
-    if (start > config.now) start -= dayMs;
+    if (start > config.now.get()) start -= dayMs;
 
-    return Timestamp.parse(start);
+    return Timestamp.fromNumber(start);
   }
 }

package/src/date-range.vo.ts

@@ -1,36 +1,36 @@
-import type { TimestampType } from "./timestamp.vo";
+import type { Timestamp } from "./timestamp.vo";
 
 export const DateRangeError = { Invalid: "date.range.invalid" } as const;
 
 export class DateRange {
   constructor(
-    private readonly start: TimestampType,
-    private readonly end: TimestampType,
+    private readonly start: Timestamp,
+    private readonly end: Timestamp,
   ) {
-    if (start > end) throw new Error(DateRangeError.Invalid);
+    if (start.isAfter(end)) throw new Error(DateRangeError.Invalid);
   }
 
-  getStart(): TimestampType {
+  getStart(): Timestamp {
     return this.start;
   }
 
-  getEnd(): TimestampType {
+  getEnd(): Timestamp {
     return this.end;
   }
 
-  toRange(): [TimestampType, TimestampType] {
+  toRange(): [Timestamp, Timestamp] {
     return [this.start, this.end];
   }
 
-  contains(timestamp: TimestampType): boolean {
-    return timestamp >= this.start && timestamp <= this.end;
+  contains(timestamp: Timestamp): boolean {
+    return timestamp.isAfterOrEqual(this.start) && timestamp.isBeforeOrEqual(this.end);
   }
 
   equals(other: DateRange): boolean {
-    return this.start === other.start && this.end === other.end;
+    return this.start.equals(other.start) && this.end.equals(other.end);
   }
 
   toJSON(): { start: number; end: number } {
-    return { start: this.getStart(), end: this.getEnd() };
+    return { start: this.getStart().get(), end: this.getEnd().get() };
   }
 }

package/src/day.vo.ts

@@ -2,39 +2,37 @@ import { formatISO } from "date-fns";
 import { DateRange } from "./date-range.vo";
 import { DayIsoId, type DayIsoIdType } from "./day-iso-id.vo";
 import { Duration } from "./duration.service";
-import { Timestamp, type TimestampType } from "./timestamp.vo";
+import { Timestamp } from "./timestamp.vo";
 
 export class Day extends DateRange {
-  private constructor(start: TimestampType, end: TimestampType) {
-    super(start, end);
-  }
-
-  static fromTimestamp(timestamp: TimestampType): Day {
-    const date = new Date(timestamp);
+  static fromTimestamp(timestamp: Timestamp): Day {
+    const date = new Date(timestamp.get());
 
-    const startUtc = Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate());
-    const endUtc = startUtc + Duration.Days(1).ms - 1;
+    const startUtc = Timestamp.fromNumber(
+      Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()),
+    );
+    const endUtc = startUtc.add(Duration.Days(1)).subtract(Duration.Ms(1));
 
-    return new Day(Timestamp.parse(startUtc), Timestamp.parse(endUtc));
+    return new Day(startUtc, endUtc);
   }
 
-  static fromNow(now: TimestampType): Day {
+  static fromNow(now: Timestamp): Day {
     return Day.fromTimestamp(now);
   }
 
   static fromIsoId(isoId: DayIsoIdType): Day {
     const [year, month, day] = DayIsoId.parse(isoId).split("-").map(Number);
 
-    const startUtc = Date.UTC(year, month - 1, day);
-    const endUtc = startUtc + Duration.Days(1).ms - 1;
+    const startUtc = Timestamp.fromNumber(Date.UTC(year, month - 1, day));
+    const endUtc = startUtc.add(Duration.Days(1)).subtract(Duration.Ms(1));
 
-    return new Day(Timestamp.parse(startUtc), Timestamp.parse(endUtc));
+    return new Day(startUtc, endUtc);
   }
 
   toIsoId(): DayIsoIdType {
-    const midday = this.getStart() + Duration.Hours(12).ms;
+    const midday = this.getStart().add(Duration.Hours(12));
 
-    return DayIsoId.parse(formatISO(midday, { representation: "date" }));
+    return DayIsoId.parse(formatISO(midday.get(), { representation: "date" }));
   }
 
   previous(): Day {
@@ -46,9 +44,7 @@ export class Day extends DateRange {
   }
 
   shift(count: number): Day {
-    const timestamp = this.getStart() + count * Duration.Days(1).ms;
-
-    return Day.fromTimestamp(Timestamp.parse(timestamp));
+    return Day.fromTimestamp(this.getStart().add(Duration.Days(count)));
   }
 
   toString(): string {

package/src/hour.vo.ts

@@ -1,6 +1,6 @@
 import { type HourFormatter, HourFormatters } from "./hour-format.service";
 import { HourSchema, type HourSchemaType } from "./hour-schema.vo";
-import type { TimestampType } from "./timestamp.vo";
+import type { Timestamp } from "./timestamp.vo";
 
 export class Hour {
   private readonly value: HourSchemaType;
@@ -12,8 +12,8 @@ export class Hour {
     this.value = HourSchema.parse(candidate);
   }
 
-  static fromEpochMs(timestamp: TimestampType): Hour {
-    return new Hour(new Date(timestamp).getUTCHours());
+  static fromEpochMs(timestamp: Timestamp): Hour {
+    return new Hour(new Date(timestamp.get()).getUTCHours());
   }
 
   get(): HourSchemaType {

package/src/index.ts

@@ -78,9 +78,9 @@ export * from "./size-bytes.vo";
 export * from "./stopwatch.service";
 export * from "./sum.service";
 export * from "./thousands-separator.service";
-export * from "./time.service";
 export * from "./time-zone-offset-value.vo";
 export * from "./timestamp.vo";
+export * from "./timestamp-value.vo";
 export * from "./timezone.vo";
 export * from "./ts-utils";
 export * from "./visually-unambiguous-characters-generator.service";

package/src/minute.vo.ts

@@ -1,5 +1,5 @@
 import { MinuteSchema, type MinuteSchemaType } from "./minute-schema.vo";
-import type { TimestampType } from "./timestamp.vo";
+import type { Timestamp } from "./timestamp.vo";
 
 export class Minute {
   private readonly value: MinuteSchemaType;
@@ -11,8 +11,8 @@ export class Minute {
     this.value = MinuteSchema.parse(candidate);
   }
 
-  static fromEpochMs(timestamp: TimestampType): Minute {
-    return new Minute(new Date(timestamp).getUTCMinutes());
+  static fromEpochMs(timestamp: Timestamp): Minute {
+    return new Minute(new Date(timestamp.get()).getUTCMinutes());
   }
 
   get(): MinuteSchemaType {

package/src/month.vo.ts

@@ -1,17 +1,17 @@
 import { endOfMonth, format, getMonth, setMonth, startOfMonth } from "date-fns";
 import { DateRange } from "./date-range.vo";
 import { MonthIsoId, type MonthIsoIdType } from "./month-iso-id.vo";
-import { Timestamp, type TimestampType } from "./timestamp.vo";
+import { Timestamp } from "./timestamp.vo";
 
 export class Month extends DateRange {
-  static fromTimestamp(timestamp: TimestampType): Month {
-    const start = Timestamp.parse(startOfMonth(timestamp).getTime());
-    const end = Timestamp.parse(endOfMonth(timestamp).getTime());
+  static fromTimestamp(timestamp: Timestamp): Month {
+    const start = Timestamp.fromNumber(startOfMonth(timestamp.get()).getTime());
+    const end = Timestamp.fromNumber(endOfMonth(timestamp.get()).getTime());
 
     return new Month(start, end);
   }
 
-  static fromNow(now: TimestampType): Month {
+  static fromNow(now: Timestamp): Month {
     return Month.fromTimestamp(now);
   }
 
@@ -20,11 +20,11 @@ export class Month extends DateRange {
 
     const reference = setMonth(Date.UTC(year), month - 1).getTime();
 
-    return Month.fromTimestamp(Timestamp.parse(reference));
+    return Month.fromTimestamp(Timestamp.fromNumber(reference));
   }
 
   toIsoId(): MonthIsoIdType {
-    return MonthIsoId.parse(format(this.getStart(), "yyyy-MM"));
+    return MonthIsoId.parse(format(this.getStart().get(), "yyyy-MM"));
   }
 
   previous(): Month {
@@ -36,9 +36,9 @@ export class Month extends DateRange {
   }
 
   shift(count: number): Month {
-    const shifted = setMonth(this.getStart(), getMonth(this.getStart()) + count).getTime();
+    const shifted = setMonth(this.getStart().get(), getMonth(this.getStart().get()) + count).getTime();
 
-    return Month.fromTimestamp(Timestamp.parse(shifted));
+    return Month.fromTimestamp(Timestamp.fromNumber(shifted));
   }
 
   toString(): string {

package/src/quarter.vo.ts

@@ -1,17 +1,17 @@
 import { endOfQuarter, getQuarter, getYear, setQuarter, startOfQuarter } from "date-fns";
 import { DateRange } from "./date-range.vo";
 import { QuarterIsoId, type QuarterIsoIdType } from "./quarter-iso-id.vo";
-import { Timestamp, type TimestampType } from "./timestamp.vo";
+import { Timestamp } from "./timestamp.vo";
 
 export class Quarter extends DateRange {
-  static fromTimestamp(timestamp: TimestampType): Quarter {
-    const start = Timestamp.parse(startOfQuarter(timestamp).getTime());
-    const end = Timestamp.parse(endOfQuarter(timestamp).getTime());
+  static fromTimestamp(timestamp: Timestamp): Quarter {
+    const start = Timestamp.fromNumber(startOfQuarter(timestamp.get()).getTime());
+    const end = Timestamp.fromNumber(endOfQuarter(timestamp.get()).getTime());
 
     return new Quarter(start, end);
   }
 
-  static fromNow(now: TimestampType): Quarter {
+  static fromNow(now: Timestamp): Quarter {
     return Quarter.fromTimestamp(now);
   }
 
@@ -20,12 +20,12 @@ export class Quarter extends DateRange {
 
     const reference = setQuarter(Date.UTC(year), quarter).getTime();
 
-    return Quarter.fromTimestamp(Timestamp.parse(reference));
+    return Quarter.fromTimestamp(Timestamp.fromNumber(reference));
   }
 
   toIsoId(): QuarterIsoIdType {
-    const year = getYear(this.getStart());
-    const quarter = getQuarter(this.getStart());
+    const year = getYear(this.getStart().get());
+    const quarter = getQuarter(this.getStart().get());
 
     return QuarterIsoId.parse(`${year}-Q${quarter}`);
   }

package/src/rate-limiter.service.ts

@@ -1,31 +1,31 @@
 import { Duration } from "./duration.service";
-import type { TimestampType } from "./timestamp.vo";
+import type { Timestamp } from "./timestamp.vo";
 
 type RateLimiterResultSuccessType = { allowed: true };
 type RateLimiterResultErrorType = { allowed: false; remaining: Duration };
 type RateLimiterResultType = RateLimiterResultSuccessType | RateLimiterResultErrorType;
 
 export class RateLimiter {
-  private lastInvocation: TimestampType | null = null;
+  private lastInvocation: Timestamp | null = null;
 
   constructor(private readonly duration: Duration) {}
 
-  verify(now: TimestampType): RateLimiterResultType {
+  verify(now: Timestamp): RateLimiterResultType {
     if (this.lastInvocation == null) {
       this.lastInvocation = now;
 
       return { allowed: true };
     }
 
-    const nextAllowedTimestamp = this.lastInvocation + this.duration.ms;
+    const nextAllowedTimestamp = this.lastInvocation.add(this.duration);
 
-    if (nextAllowedTimestamp <= now) {
+    if (nextAllowedTimestamp.isBeforeOrEqual(now)) {
       this.lastInvocation = now;
 
       return { allowed: true };
     }
 
-    const remainingDelta = nextAllowedTimestamp - now;
+    const remainingDelta = nextAllowedTimestamp.get() - now.get();
 
     return { allowed: false, remaining: Duration.Ms(remainingDelta) };
   }

package/src/relative-date.vo.ts

@@ -1,20 +1,21 @@
 import { DateFormatters } from "./date-formatter.service";
-import type { TimestampType } from "./timestamp.vo";
+import type { Timestamp } from "./timestamp.vo";
+import type { TimestampValueType } from "./timestamp-value.vo";
 import type { Falsy } from "./ts-utils";
 
-type RelativeDateType = { raw: TimestampType; relative: string };
+type RelativeDateType = { raw: TimestampValueType; relative: string };
 
 export class RelativeDate {
-  static truthy(timestamp: TimestampType): RelativeDateType {
+  static truthy(timestamp: Timestamp): RelativeDateType {
     return RelativeDate._format(timestamp);
   }
 
-  static falsy(timestamp: Falsy<TimestampType>): RelativeDateType | null {
+  static falsy(timestamp: Falsy<Timestamp>): RelativeDateType | null {
     if (!timestamp) return null;
     return RelativeDate._format(timestamp);
   }
 
-  private static _format(timestampMs: TimestampType): RelativeDateType {
-    return { raw: timestampMs, relative: DateFormatters.relative(timestampMs) };
+  private static _format(timestamp: Timestamp): RelativeDateType {
+    return { raw: timestamp.get(), relative: DateFormatters.relative(timestamp.get()) };
   }
 }

package/src/stopwatch.service.ts

@@ -1,5 +1,5 @@
 import { Duration } from "./duration.service";
-import { Timestamp, type TimestampType } from "./timestamp.vo";
+import { Timestamp } from "./timestamp.vo";
 
 export const StopwatchError = { AlreadyStopped: "stopwatch.already.stopped" } as const;
 
@@ -13,13 +13,13 @@ export type StopwatchResultType = Duration;
 export class Stopwatch {
   private state: StopwatchState = StopwatchState.started;
 
-  constructor(private readonly startMs: TimestampType) {}
+  constructor(private readonly start: Timestamp) {}
 
   stop(): StopwatchResultType {
     if (this.state === StopwatchState.stopped) throw new Error(StopwatchError.AlreadyStopped);
 
     this.state = StopwatchState.stopped;
 
-    return Duration.Ms(Timestamp.parse(Date.now() - this.startMs));
+    return Duration.Ms(Timestamp.fromNumber(Date.now() - this.start.get()).get());
   }
 }

package/src/timestamp-value.vo.ts

@@ -0,0 +1,11 @@
+import { z } from "zod/v4";
+
+export const TimestampValueError = { Invalid: "timestamp.invalid" } as const;
+
+export const TimestampValue = z
+  .number(TimestampValueError.Invalid)
+  .int(TimestampValueError.Invalid)
+  .gte(0, TimestampValueError.Invalid)
+  .brand("TimestampValue");
+
+export type TimestampValueType = z.infer<typeof TimestampValue>;