@bgord/tools 0.17.2 → 1.0.1

package/src/revision.vo.ts

@@ -1,14 +1,7 @@
-import { z } from "zod/v4";
 import type { ETag, WeakETag } from "./etags.vo";
+import { RevisionValue, type RevisionValueType } from "./revision-value.vo";
 
-export const RevisionValueError = { error: "invalid.revision.value" } as const;
-
-export const RevisionValue = z.number(RevisionValueError).int(RevisionValueError).min(0, RevisionValueError);
-
-export type RevisionValueType = z.infer<typeof RevisionValue>;
-
-export const RevisionInvalidErrorMessage = "revision.invalid" as const;
-export const RevisionMismatchErrorMessage = "revision.mismatch" as const;
+export const RevisionError = { Missing: "revision.missing", Mismatch: "revision.mismatch" } as const;
 
 export class Revision {
   static readonly INITIAL: RevisionValueType = RevisionValue.parse(0);
@@ -16,9 +9,7 @@ export class Revision {
   readonly value: RevisionValueType;
 
   constructor(value: unknown) {
-    const result = RevisionValue.safeParse(value);
-    if (!result.success) throw new InvalidRevisionError();
-    this.value = result.data;
+    this.value = RevisionValue.parse(value);
   }
 
   equals(another: RevisionValueType): boolean {
@@ -26,7 +17,7 @@ export class Revision {
   }
 
   validate(another: RevisionValueType): void {
-    if (!this.equals(another)) throw new RevisionMismatchError();
+    if (!this.equals(another)) throw new Error(RevisionError.Mismatch);
   }
 
   next(): Revision {
@@ -34,26 +25,20 @@ export class Revision {
   }
 
   static fromETag(etag: ETag | null): Revision {
-    if (!etag) throw new InvalidRevisionError();
+    if (!etag) throw new Error(RevisionError.Missing);
     return new Revision(etag.revision);
   }
 
   static fromWeakETag(weakEtag: WeakETag | null): Revision {
-    if (!weakEtag) throw new InvalidRevisionError();
+    if (!weakEtag) throw new Error(RevisionError.Missing);
     return new Revision(weakEtag.revision);
   }
-}
 
-export class RevisionMismatchError extends Error {
-  constructor() {
-    super(RevisionMismatchErrorMessage);
-    Object.setPrototypeOf(this, RevisionMismatchError.prototype);
+  toString(): string {
+    return this.value.toString();
   }
-}
 
-export class InvalidRevisionError extends Error {
-  constructor() {
-    super(RevisionInvalidErrorMessage);
-    Object.setPrototypeOf(this, InvalidRevisionError.prototype);
+  toJSON(): number {
+    return this.value;
   }
 }

package/src/rounding.adapter.ts

@@ -1,3 +1,4 @@
+import { z } from "zod/v4";
 import type { RoundingPort } from "./rounding.port";
 
 export class RoundToNearest implements RoundingPort {
@@ -18,11 +19,23 @@ export class RoundDown implements RoundingPort {
   }
 }
 
-export const RoundingDecimalsError = "invalid.rounding.decimals" as const;
+export const RoundingDecimalError = {
+  Type: "rounding.decimal.type",
+  Invalid: "rounding.decimal.invalid",
+} as const;
+
+export const RoundingDecimal = z
+  .number(RoundingDecimalError.Type)
+  .int(RoundingDecimalError.Invalid)
+  .min(1, RoundingDecimalError.Invalid)
+  .max(100, RoundingDecimalError.Invalid)
+  .brand("RoundingDecimal");
 
 export class RoundToDecimal implements RoundingPort {
-  constructor(private readonly decimals: number) {
-    if (!Number.isInteger(decimals) || decimals < 0 || decimals > 100) throw new Error(RoundingDecimalsError);
+  private readonly decimals: number;
+
+  constructor(candidate: number) {
+    this.decimals = RoundingDecimal.parse(candidate);
   }
 
   round(value: number): number {

package/src/size-bytes.vo.ts

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

package/src/size.vo.ts

@@ -1,22 +1,18 @@
-import { z } from "zod/v4";
 import { RoundToDecimal } from "./rounding.adapter";
+import { SizeBytes, type SizeBytesType } from "./size-bytes.vo";
 
-export enum SizeUnit {
+enum SizeUnitEnum {
   b = "b",
   kB = "kB",
   MB = "MB",
   GB = "GB",
 }
 
-export const SizeValue = z.number().positive().brand("SizeValue");
-type SizeValueType = z.infer<typeof SizeValue>;
-
-type SizeConfigType = { unit: SizeUnit; value: number };
+type SizeConfigType = { unit: SizeUnitEnum; value: number };
 
 export class Size {
-  private readonly unit: SizeUnit;
-  private readonly value: SizeValueType;
-  private readonly bytes: SizeValueType;
+  private readonly unit: SizeUnitEnum;
+  private readonly bytes: SizeBytesType;
 
   private static readonly KB_MULTIPLIER = 1024;
   private static readonly MB_MULTIPLIER = 1024 * Size.KB_MULTIPLIER;
@@ -26,35 +22,26 @@ export class Size {
 
   constructor(config: SizeConfigType) {
     this.unit = config.unit;
-    this.value = SizeValue.parse(config.value);
-    this.bytes = this.calculateBytes();
-  }
-
-  static fromBytes(candidate: number): Size {
-    const value = SizeValue.parse(candidate);
-    return new Size({ value, unit: SizeUnit.b });
+    this.bytes = this.calculateBytes(config.value, config.unit);
   }
 
-  static fromKb(candidate: number): Size {
-    const value = SizeValue.parse(candidate);
-    return new Size({ value, unit: SizeUnit.kB });
+  static fromBytes(value: SizeConfigType["value"]): Size {
+    return new Size({ value, unit: SizeUnitEnum.b });
   }
 
-  static fromMB(candidate: number): Size {
-    const value = SizeValue.parse(candidate);
-    return new Size({ value, unit: SizeUnit.MB });
+  static fromKb(value: SizeConfigType["value"]): Size {
+    return new Size({ value, unit: SizeUnitEnum.kB });
   }
 
-  static fromGB(candidate: number): Size {
-    const value = SizeValue.parse(candidate);
-    return new Size({ value, unit: SizeUnit.GB });
+  static fromMB(value: SizeConfigType["value"]): Size {
+    return new Size({ value, unit: SizeUnitEnum.MB });
   }
 
-  toString(): string {
-    return `${this.value} ${this.unit}`;
+  static fromGB(value: SizeConfigType["value"]): Size {
+    return new Size({ value, unit: SizeUnitEnum.GB });
   }
 
-  toBytes(): SizeValueType {
+  toBytes(): SizeBytesType {
     return this.bytes;
   }
 
@@ -62,41 +49,43 @@ export class Size {
     return this.bytes > another.toBytes();
   }
 
-  format(unit: SizeUnit): string {
+  format(unit: SizeUnitEnum): string {
     switch (unit) {
-      case SizeUnit.kB: {
-        return `${Size.ROUNDER.round(this.bytes / Size.KB_MULTIPLIER)} ${SizeUnit.kB}`;
-      }
-      case SizeUnit.MB: {
-        return `${Size.ROUNDER.round(this.bytes / Size.MB_MULTIPLIER)} ${SizeUnit.MB}`;
-      }
-      case SizeUnit.GB: {
-        return `${Size.ROUNDER.round(this.bytes / Size.GB_MULTIPLIER)} ${SizeUnit.GB}`;
-      }
-      default: {
-        // SizeUnit.b
-        return `${this.bytes} ${SizeUnit.b}`;
-      }
+      case SizeUnitEnum.kB:
+        return `${Size.ROUNDER.round(this.bytes / Size.KB_MULTIPLIER)} ${SizeUnitEnum.kB}`;
+      case SizeUnitEnum.MB:
+        return `${Size.ROUNDER.round(this.bytes / Size.MB_MULTIPLIER)} ${SizeUnitEnum.MB}`;
+      case SizeUnitEnum.GB:
+        return `${Size.ROUNDER.round(this.bytes / Size.GB_MULTIPLIER)} ${SizeUnitEnum.GB}`;
+      default:
+        return `${this.bytes} ${SizeUnitEnum.b}`;
     }
   }
 
-  static toBytes(config: SizeConfigType): SizeValueType {
+  static toBytes(config: SizeConfigType): SizeBytesType {
     return new Size(config).toBytes();
   }
 
-  static unit = SizeUnit;
+  static unit = SizeUnitEnum;
 
-  private calculateBytes(): SizeValueType {
-    switch (this.unit) {
-      case SizeUnit.kB:
-        return SizeValue.parse(this.value * Size.KB_MULTIPLIER);
-      case SizeUnit.MB:
-        return SizeValue.parse(this.value * Size.MB_MULTIPLIER);
-      case SizeUnit.GB:
-        return SizeValue.parse(this.value * Size.GB_MULTIPLIER);
+  private calculateBytes(value: SizeConfigType["value"], unit: SizeUnitEnum): SizeBytesType {
+    switch (unit) {
+      case SizeUnitEnum.kB:
+        return SizeBytes.parse(value * Size.KB_MULTIPLIER);
+      case SizeUnitEnum.MB:
+        return SizeBytes.parse(value * Size.MB_MULTIPLIER);
+      case SizeUnitEnum.GB:
+        return SizeBytes.parse(value * Size.GB_MULTIPLIER);
       default:
-        // SizeUnit.b
-        return this.value;
+        return SizeBytes.parse(value);
     }
   }
+
+  toString(): string {
+    return this.format(this.unit);
+  }
+
+  toJSON(): { bytes: number } {
+    return { bytes: this.bytes };
+  }
 }

package/src/stopwatch.service.ts

@@ -1,13 +1,13 @@
 import { Duration } from "./duration.service";
 import { Timestamp, type TimestampType } from "./timestamp.vo";
 
+export const StopwatchError = { AlreadyStopped: "stopwatch.already.stopped" } as const;
+
 enum StopwatchState {
   started = "started",
   stopped = "stopped",
 }
 
-export const StopwatchStateError = "stopwatch.already.stopped" as const;
-
 export type StopwatchResultType = Duration;
 
 export class Stopwatch {
@@ -16,7 +16,7 @@ export class Stopwatch {
   constructor(private readonly startMs: TimestampType) {}
 
   stop(): StopwatchResultType {
-    if (this.state === StopwatchState.stopped) throw new Error(StopwatchStateError);
+    if (this.state === StopwatchState.stopped) throw new Error(StopwatchError.AlreadyStopped);
 
     this.state = StopwatchState.stopped;
 

package/src/sum.service.ts

@@ -4,16 +4,16 @@ export class Sum {
   }
 
   static precise(values: readonly number[]): number {
-    let runningTotal = 0;
-    let roundingCompensation = 0;
+    let sum = 0;
+    let compensation = 0;
 
-    for (const currentValue of values) {
-      const correctedAddend = currentValue - roundingCompensation;
-      const tentativeTotal = runningTotal + correctedAddend;
-      roundingCompensation = tentativeTotal - runningTotal - correctedAddend;
-      runningTotal = tentativeTotal;
+    for (const value of values) {
+      const adjusted = value - compensation;
+      const temporary = sum + adjusted;
+      compensation = temporary - sum - adjusted;
+      sum = temporary;
     }
 
-    return runningTotal;
+    return sum;
   }
 }

package/src/thousands-separator.service.ts

@@ -2,6 +2,9 @@ export class ThousandsSeparator {
   private static DEFAULT_SEPARATOR = " ";
 
   static format(value: number, separator = ThousandsSeparator.DEFAULT_SEPARATOR): string {
-    return value.toString().replace(/\B(?=(\d{3})+(?!\d))/g, separator);
+    // B - not a word boundary, prevents inserting at the very start
+    // (?=([0-9]{3})+(?![0-9])) - positive lookahead, find three digits
+    // (?![0-9]) - negative lookahead, the next character is not a digit
+    return value.toString().replace(/\B(?=([0-9]{3})+(?![0-9]))/g, separator);
   }
 }

package/src/time.service.ts

@@ -0,0 +1,15 @@
+import type { Duration } from "./duration.service";
+import { Timestamp, type TimestampType } from "./timestamp.vo";
+
+export const Time = {
+  Now(now: TimestampType) {
+    return {
+      Add(duration: Duration): TimestampType {
+        return Timestamp.parse(now + duration.ms);
+      },
+      Minus(duration: Duration): TimestampType {
+        return Timestamp.parse(now - duration.ms);
+      },
+    };
+  },
+};

package/src/timestamp.vo.ts

@@ -1,12 +1,11 @@
 import { z } from "zod/v4";
 
-export const TimestampError = { error: "invalid.timestamp" } as const;
+export const TimestampError = { Invalid: "timestamp.invalid" } as const;
 
 export const Timestamp = z
-  .number(TimestampError)
-  .int(TimestampError)
-  .gte(0, TimestampError)
-  .lte(Number.MAX_SAFE_INTEGER, TimestampError)
+  .number(TimestampError.Invalid)
+  .int(TimestampError.Invalid)
+  .gte(0, TimestampError.Invalid)
   .brand("Timestamp");
 
 export type TimestampType = z.infer<typeof Timestamp>;

package/src/timezone.vo.ts

@@ -1,18 +1,24 @@
 import { z } from "zod/v4";
 
-export const TimezoneError = { error: "timezone.invalid" } as const;
+export const TimezoneError = {
+  Type: "timezone.type",
+  Empty: "timezone.empty",
+  TooLong: "timezone.too.long",
+  Invalid: "timezone.invalid",
+} as const;
 
 export const Timezone = z
-  .string(TimezoneError)
-  .min(1, TimezoneError)
+  .string(TimezoneError.Type)
+  .min(1, TimezoneError.Empty)
+  .max(128, TimezoneError.TooLong)
   .refine((value) => {
     try {
-      new Intl.DateTimeFormat("en-US", { timeZone: value }).format(new Date());
+      new Intl.DateTimeFormat("en-US", { timeZone: value }).format(Date.now());
       return true;
-    } catch (_error) {
+    } catch {
       return false;
     }
-  }, TimezoneError)
+  }, TimezoneError.Invalid)
   .brand("Timezone");
 
 export type TimezoneType = z.infer<typeof Timezone>;

package/src/week-iso-id.vo.ts

@@ -1,22 +1,26 @@
 import { getISOWeeksInYear } from "date-fns";
 import { z } from "zod/v4";
 
-export const WeekIsoIdError = { error: "week-iso-id.invalid" } as const;
+export const WeekIsoIdError = {
+  Type: "week.iso.id.type",
+  BadChars: "week.iso.id.bad.chars",
+  Invalid: "week.iso.id.invalid",
+} as const;
+
+// Four digits, hypen, W, followed by two digits
+const WEEK_ISO_ID_CHARS_WHITELIST = /^[0-9]{4}-W[0-9]{2}$/;
 
 export const WeekIsoId = z
-  .string(WeekIsoIdError)
-  .regex(/^\d{4}-W\d{2}$/, WeekIsoIdError)
+  .string(WeekIsoIdError.Type)
+  .regex(WEEK_ISO_ID_CHARS_WHITELIST, WeekIsoIdError.BadChars)
   .refine((value) => {
-    const [yearPart, weekPart] = value.split("-W");
-
-    const year = Number(yearPart);
-    const week = Number(weekPart);
-
-    if (!(Number.isInteger(year) && Number.isInteger(week)) || week < 1) return false;
-
-    const weeksInYear = getISOWeeksInYear(new Date(Date.UTC(year, 0, 4)));
+    const [year, week] = value.split("-W").map(Number);
+    // ISO-8601 rule: Jan 4 is always in week 01 of the ISO week-year.
+    const weeksInYear = getISOWeeksInYear(Date.UTC(year, 0, 4));
 
+    if (week < 1) return false;
     return week <= weeksInYear;
-  }, WeekIsoIdError);
+  }, WeekIsoIdError.Invalid)
+  .brand("WeekIsoId");
 
 export type WeekIsoIdType = z.infer<typeof WeekIsoId>;

package/src/week.vo.ts

@@ -4,50 +4,48 @@ import { Timestamp, type TimestampType } from "./timestamp.vo";
 import { WeekIsoId, type WeekIsoIdType } from "./week-iso-id.vo";
 
 export class Week extends DateRange {
-  toIsoId(): WeekIsoIdType {
-    const year = getISOWeekYear(this.getStart());
-    const week = getISOWeek(this.getStart()).toString().padStart(2, "0");
+  static fromTimestamp(timestamp: TimestampType): Week {
+    const start = Timestamp.parse(startOfISOWeek(timestamp).getTime());
+    const end = Timestamp.parse(endOfISOWeek(timestamp).getTime());
 
-    return WeekIsoId.parse(`${year}-W${week}`);
+    return new Week(start, end);
   }
 
-  previous(): Week {
-    const shifted = addWeeks(new Date(this.getStart()), -1).getTime();
-
-    return Week.fromTimestamp(Timestamp.parse(shifted));
+  static fromNow(now: TimestampType): Week {
+    return Week.fromTimestamp(now);
   }
 
-  next(): Week {
-    const shifted = addWeeks(new Date(this.getStart()), 1).getTime();
+  static fromIsoId(isoId: WeekIsoIdType): Week {
+    const [year, week] = WeekIsoId.parse(isoId).split("-W").map(Number);
 
-    return Week.fromTimestamp(Timestamp.parse(shifted));
+    // 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));
   }
 
-  shift(count: number): Week {
-    const shifted = addWeeks(new Date(this.getStart()), count).getTime();
+  toIsoId(): WeekIsoIdType {
+    const year = getISOWeekYear(this.getStart());
+    const week = getISOWeek(this.getStart());
 
-    return Week.fromTimestamp(Timestamp.parse(shifted));
+    return WeekIsoId.parse(`${year}-W${String(week).padStart(2, "0")}`);
   }
 
-  static fromTimestamp(timestamp: TimestampType): Week {
-    const start = Timestamp.parse(startOfISOWeek(timestamp).getTime());
-    const end = Timestamp.parse(endOfISOWeek(timestamp).getTime());
-
-    return new Week(start, end);
+  previous(): Week {
+    return this.shift(-1);
   }
 
-  static fromNow(now: TimestampType): Week {
-    return Week.fromTimestamp(now);
+  next(): Week {
+    return this.shift(1);
   }
 
-  static fromIsoId(isoId: WeekIsoIdType): Week {
-    const [yearPart, weekPart] = WeekIsoId.parse(isoId).split("-W");
-    const year = Number(yearPart);
-    const week = Number(weekPart);
+  shift(count: number): Week {
+    const shifted = addWeeks(this.getStart(), count).getTime();
 
-    // ISO-8601 rule: Jan 4 is always in week 01 of the ISO week-year.
-    const reference = setISOWeek(new Date(Date.UTC(year, 0, 4)), week);
+    return Week.fromTimestamp(Timestamp.parse(shifted));
+  }
 
-    return Week.fromTimestamp(Timestamp.parse(reference.getTime()));
+  toString(): string {
+    return this.toIsoId();
   }
 }

package/src/weekday.vo.ts

@@ -61,13 +61,12 @@ export class Weekday {
     return this.value;
   }
 
-  format(formatter?: WeekdayFormatter): string {
-    const chosen = formatter ?? this.formatter;
-    return chosen(this.value);
+  format(): string {
+    return this.formatter(this.value);
   }
 
   toString(): string {
-    return this.format(WeekdayFormatters.FULL);
+    return this.format();
   }
 
   equals(another: Weekday): boolean {
@@ -102,14 +101,12 @@ export class Weekday {
   }
 
   static list(formatter?: WeekdayFormatter): readonly Weekday[] {
-    const chosen = formatter ?? undefined;
-
-    return Array.from({ length: 7 }, (_, index) => new Weekday(index, chosen));
+    return Array.from({ length: 7 }, (_, index) => new Weekday(index, formatter));
   }
 
   static listMondayFirst(formatter?: WeekdayFormatter): readonly Weekday[] {
-    const days = Weekday.list(formatter);
+    const [Sunday, ...rest] = Weekday.list(formatter);
 
-    return [...days.slice(1), days[0]];
+    return [...rest, Sunday];
   }
 }

package/src/weight-grams.vo.ts

@@ -0,0 +1,11 @@
+import { z } from "zod/v4";
+
+export const WeightGramsError = { Type: "weight.grams.type", Invalid: "weight.grams.invalid" } as const;
+
+export const WeightGrams = z
+  .number(WeightGramsError.Type)
+  .int(WeightGramsError.Type)
+  .gte(0, WeightGramsError.Invalid)
+  .brand("WeightGrams");
+
+export type WeightGramsType = z.infer<typeof WeightGrams>;