@bgord/tools 0.15.1 → 0.16.0

package/src/time.service.ts

@@ -12,75 +12,74 @@ interface TimeResultInterface {
 
   isAfter(another: TimeResultInterface): boolean;
   isBefore(another: TimeResultInterface): boolean;
+
+  add(another: TimeResultInterface): TimeResultInterface;
+  subtract(another: TimeResultInterface): TimeResultInterface;
 }
 
 export class TimeResult implements TimeResultInterface {
-  constructor(
-    readonly days: number,
-    readonly hours: number,
-    readonly minutes: number,
-    readonly seconds: number,
-    readonly ms: TimestampType,
-  ) {}
+  private readonly valueMs: TimestampType;
+
+  constructor(ms: TimestampType) {
+    this.valueMs = ms;
+  }
+
+  get days(): number {
+    return rounding.round(this.valueMs / 86_400_000);
+  }
+
+  get hours(): number {
+    return rounding.round(this.valueMs / 3_600_000);
+  }
+
+  get minutes(): number {
+    return rounding.round(this.valueMs / 60_000);
+  }
+
+  get seconds(): number {
+    return rounding.round(this.valueMs / 1_000);
+  }
+
+  get ms(): TimestampType {
+    return this.valueMs;
+  }
 
   isAfter(another: TimeResultInterface): boolean {
-    return this.ms > another.ms;
+    return this.valueMs > another.ms;
   }
 
   isBefore(another: TimeResultInterface): boolean {
-    return this.ms < another.ms;
+    return this.valueMs < another.ms;
+  }
+
+  add(another: TimeResultInterface): TimeResultInterface {
+    return new TimeResult((this.valueMs + another.ms) as TimestampType);
+  }
+
+  subtract(another: TimeResultInterface): TimeResultInterface {
+    return new TimeResult((this.valueMs - another.ms) as TimestampType);
   }
 }
 
 export class Time {
   static Days(value: number): TimeResultInterface {
-    return new TimeResult(
-      value,
-      value * 24,
-      value * 24 * 60,
-      value * 24 * 60 * 60,
-      (value * 24 * 60 * 60 * 1000) as TimestampType,
-    );
+    return new TimeResult((value * 86_400_000) as TimestampType);
   }
 
   static Hours(value: number): TimeResultInterface {
-    return new TimeResult(
-      rounding.round(value / 24),
-      value,
-      value * 60,
-      value * 60 * 60,
-      (value * 60 * 60 * 1000) as TimestampType,
-    );
+    return new TimeResult((value * 3_600_000) as TimestampType);
   }
 
   static Minutes(value: number): TimeResultInterface {
-    return new TimeResult(
-      rounding.round(value / 60 / 24),
-      rounding.round(value / 60),
-      value,
-      value * 60,
-      (value * 60 * 1000) as TimestampType,
-    );
+    return new TimeResult((value * 60_000) as TimestampType);
   }
 
   static Seconds(value: number): TimeResultInterface {
-    return new TimeResult(
-      rounding.round(value / 60 / 60 / 24),
-      rounding.round(value / 60 / 60),
-      rounding.round(value / 60),
-      value,
-      (value * 1000) as TimestampType,
-    );
+    return new TimeResult((value * 1_000) as TimestampType);
   }
 
   static Ms(value: number): TimeResultInterface {
-    return new TimeResult(
-      rounding.round(value / 1000 / 60 / 60 / 24),
-      rounding.round(value / 1000 / 60 / 60),
-      rounding.round(value / 1000 / 60),
-      rounding.round(value / 1000),
-      value as TimestampType,
-    );
+    return new TimeResult(value as TimestampType);
   }
 
   static Now(now: TimestampType) {
@@ -88,7 +87,6 @@ export class Time {
       Minus(time: TimeResultInterface): TimeResultInterface {
         return Time.Ms(now - time.ms);
       },
-
       Add(time: TimeResultInterface): TimeResultInterface {
         return Time.Ms(now + time.ms);
       },

package/src/timezone.vo.ts

@@ -7,9 +7,7 @@ export const Timezone = z
   .min(1, TimezoneError)
   .refine((value) => {
     try {
-      const date = new Date();
-      const formatter = new Intl.DateTimeFormat("en-US", { timeZone: value });
-      formatter.format(date);
+      new Intl.DateTimeFormat("en-US", { timeZone: value }).format(new Date());
       return true;
     } catch (_error) {
       return false;

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

@@ -1,23 +1,22 @@
 import { getISOWeeksInYear } from "date-fns";
 import { z } from "zod/v4";
 
+export const WeekIsoIdError = { error: "week-iso-id.invalid" } as const;
+
 export const WeekIsoId = z
-  .string()
-  .regex(/^\d{4}-W\d{2}$/)
-  .refine(
-    (value) => {
-      const [yearPart, weekPart] = value.split("-W");
+  .string(WeekIsoIdError)
+  .regex(/^\d{4}-W\d{2}$/, WeekIsoIdError)
+  .refine((value) => {
+    const [yearPart, weekPart] = value.split("-W");
+
+    const year = Number(yearPart);
+    const week = Number(weekPart);
 
-      const year = Number(yearPart);
-      const week = Number(weekPart);
+    if (!(Number.isInteger(year) && Number.isInteger(week)) || week < 1) return false;
 
-      if (!(Number.isInteger(year) && Number.isInteger(week)) || week < 1) return false;
+    const weeksInYear = getISOWeeksInYear(new Date(Date.UTC(year, 0, 4)));
 
-      // Does this ISO week-year actually have that many weeks?
-      const weeksInYear = getISOWeeksInYear(new Date(Date.UTC(year, 0, 4)));
+    return week <= weeksInYear;
+  }, WeekIsoIdError);
 
-      return week <= weeksInYear;
-    },
-    { message: "week-iso-id.invalid" },
-  );
 export type WeekIsoIdType = z.infer<typeof WeekIsoId>;

package/src/week.vo.ts

@@ -8,21 +8,24 @@ export class Week extends DateRange {
     const year = getISOWeekYear(this.getStart());
     const week = getISOWeek(this.getStart()).toString().padStart(2, "0");
 
-    return `${year}-W${week}`;
+    return WeekIsoId.parse(`${year}-W${week}`);
   }
 
   previous(): Week {
     const shifted = addWeeks(new Date(this.getStart()), -1).getTime();
+
     return Week.fromTimestamp(Timestamp.parse(shifted));
   }
 
   next(): Week {
     const shifted = addWeeks(new Date(this.getStart()), 1).getTime();
+
     return Week.fromTimestamp(Timestamp.parse(shifted));
   }
 
   shift(count: number): Week {
     const shifted = addWeeks(new Date(this.getStart()), count).getTime();
+
     return Week.fromTimestamp(Timestamp.parse(shifted));
   }
 
@@ -39,7 +42,6 @@ export class Week extends DateRange {
 
   static fromIsoId(isoId: WeekIsoIdType): Week {
     const [yearPart, weekPart] = WeekIsoId.parse(isoId).split("-W");
-
     const year = Number(yearPart);
     const week = Number(weekPart);
 

package/src/weekday.vo.ts

@@ -9,6 +9,8 @@ export enum WeekdayFormatterEnum {
   ZERO_BASED_NUMBER = "ZERO_BASED_NUMBER", // Sunday=0 ... Saturday=6 (JS)
 }
 
+export const WeekdayValueError = "invalid.weekday" as const;
+
 const FULL_NAMES: readonly string[] = [
   "Sunday",
   "Monday",
@@ -29,8 +31,10 @@ export const WeekdayFormatters: Record<WeekdayFormatterEnum, WeekdayFormatter> =
 } as const;
 
 export class Weekday {
+  // 0..6 (Sun..Sat)
   private readonly value: number;
 
+  // default formatter used by toString()/format() when no runtime formatter given
   private readonly formatter: WeekdayFormatter;
 
   static readonly SUNDAY = new Weekday(0);
@@ -42,28 +46,35 @@ export class Weekday {
   static readonly SATURDAY = new Weekday(6);
 
   constructor(candidate: number, formatter?: WeekdayFormatter) {
-    if (!Number.isInteger(candidate)) throw new Error("Invalid weekday");
-    if (candidate < 0) throw new Error("Invalid weekday");
-    if (candidate > 6) throw new Error("Invalid weekday");
+    if (!Number.isInteger(candidate) || candidate < 0 || candidate > 6) throw new Error(WeekdayValueError);
 
     this.value = candidate;
-    this.formatter = (formatter as WeekdayFormatter) ?? WeekdayFormatters.FULL;
+    this.formatter = formatter ?? WeekdayFormatters.FULL;
   }
 
   static fromUtcTimestamp(timestamp: TimestampType, formatter?: WeekdayFormatter): Weekday {
-    const day = new Date(timestamp).getUTCDay(); // 0..6
-    return new Weekday(day, formatter);
+    const dayZeroBased = new Date(timestamp).getUTCDay(); // 0..6
+    return new Weekday(dayZeroBased, formatter);
+  }
+
+  get(): number {
+    return this.value;
   }
 
-  get(formatter?: WeekdayFormatter) {
-    const format = formatter ?? this.formatter;
-    return { raw: this.value, formatted: format(this.value) };
+  format(formatter?: WeekdayFormatter): string {
+    const chosen = formatter ?? this.formatter;
+    return chosen(this.value);
+  }
+
+  toString(): string {
+    return this.format(WeekdayFormatters.FULL);
   }
 
   equals(another: Weekday): boolean {
-    return this.value === another.get().raw;
+    return this.value === another.value;
   }
 
+  /** ISO-8601 weekday number: Monday=1 ... Sunday=7 */
   toIsoNumber(): number {
     return this.value === 0 ? 7 : this.value;
   }
@@ -90,12 +101,15 @@ export class Weekday {
     return this.value === 0;
   }
 
-  static list(formatter?: WeekdayFormatter): Weekday[] {
-    return Array.from({ length: 7 }).map((_, index) => new Weekday(index, formatter));
+  static list(formatter?: WeekdayFormatter): readonly Weekday[] {
+    const chosen = formatter ?? undefined;
+
+    return Array.from({ length: 7 }, (_, index) => new Weekday(index, chosen));
   }
 
-  static listMondayFirst(formatter?: WeekdayFormatter): Weekday[] {
+  static listMondayFirst(formatter?: WeekdayFormatter): readonly Weekday[] {
     const days = Weekday.list(formatter);
+
     return [...days.slice(1), days[0]];
   }
 }

package/src/weight.vo.ts

@@ -2,18 +2,31 @@ import { z } from "zod/v4";
 import { RoundToDecimal } from "./rounding.adapter";
 import type { RoundingPort } from "./rounding.port";
 
-const FiniteNumericValue = z.number().refine(Number.isFinite, { message: "Expected a finite number" });
-const NonNegativeNumericValue = FiniteNumericValue.min(0, { message: "Must be greater than or equal to 0" });
-const PositiveNumericValue = FiniteNumericValue.gt(0, { message: "Must be greater than 0" });
-const NonNegativeIntegerGrams = FiniteNumericValue.int().min(0, {
-  message: "Grams must be an integer greater than or equal to 0",
-});
-
 export enum WeightUnit {
   kg = "kg",
   lb = "lb",
 }
 
+export const WeightNonFiniteError = { error: "weight.non_finite" } as const;
+export const WeightNegativeError = { error: "weight.negative" } as const;
+export const WeightNonPositiveError = { error: "weight.non_positive" } as const;
+export const WeightGramsNonNegativeError = { error: "weight.grams_non_negative" } as const;
+
+const WeightQuantityNumber = z
+  .number(WeightNonFiniteError)
+  .refine(Number.isFinite, WeightNonFiniteError)
+  .min(0, WeightNegativeError);
+
+const DivisionScalarNumber = z
+  .number(WeightNonFiniteError)
+  .refine(Number.isFinite, WeightNonFiniteError)
+  .gt(0, WeightNonPositiveError);
+
+const CanonicalGramsInteger = z
+  .number(WeightGramsNonNegativeError)
+  .int(WeightGramsNonNegativeError)
+  .min(0, WeightGramsNonNegativeError);
+
 export class Weight {
   private static readonly GRAMS_PER_KILOGRAM = 1_000;
   private static readonly POUNDS_PER_KILOGRAM = 2.2046226218487757;
@@ -22,24 +35,27 @@ export class Weight {
   private constructor(private readonly grams: number) {}
 
   static fromKilograms(kilograms: number): Weight {
-    NonNegativeNumericValue.parse(kilograms);
-    const gramsRounded = Math.round(kilograms * Weight.GRAMS_PER_KILOGRAM);
-    NonNegativeIntegerGrams.parse(gramsRounded);
-    return new Weight(gramsRounded);
+    const kilogramsParsed = WeightQuantityNumber.parse(kilograms);
+    const gramsRounded = Math.round(kilogramsParsed * Weight.GRAMS_PER_KILOGRAM);
+    const grams = CanonicalGramsInteger.parse(gramsRounded);
+
+    return new Weight(grams);
   }
 
   static fromPounds(pounds: number): Weight {
-    NonNegativeNumericValue.parse(pounds);
-    const gramsRounded = Math.round(pounds * Weight.KILOGRAMS_PER_POUND * Weight.GRAMS_PER_KILOGRAM);
-    NonNegativeIntegerGrams.parse(gramsRounded);
-    return new Weight(gramsRounded);
+    const poundsParsed = WeightQuantityNumber.parse(pounds);
+    const gramsRounded = Math.round(poundsParsed * Weight.KILOGRAMS_PER_POUND * Weight.GRAMS_PER_KILOGRAM);
+    const grams = CanonicalGramsInteger.parse(gramsRounded);
+
+    return new Weight(grams);
   }
 
   static fromGrams(grams: number): Weight {
-    NonNegativeNumericValue.parse(grams);
-    const gramsRounded = Math.round(grams);
-    NonNegativeIntegerGrams.parse(gramsRounded);
-    return new Weight(gramsRounded);
+    const gramsParsed = WeightQuantityNumber.parse(grams);
+    const gramsRounded = Math.round(gramsParsed);
+    const integerGrams = CanonicalGramsInteger.parse(gramsRounded);
+
+    return new Weight(integerGrams);
   }
 
   static zero(): Weight {
@@ -52,18 +68,18 @@ export class Weight {
 
   toKilograms(rounding?: RoundingPort): number {
     const kilograms = this.grams / Weight.GRAMS_PER_KILOGRAM;
+
     return rounding ? rounding.round(kilograms) : kilograms;
   }
 
   toPounds(rounding?: RoundingPort): number {
     const pounds = (this.grams / Weight.GRAMS_PER_KILOGRAM) * Weight.POUNDS_PER_KILOGRAM;
+
     return rounding ? rounding.round(pounds) : pounds;
   }
 
   format(unit: WeightUnit, rounding: RoundingPort = new RoundToDecimal(2)): string {
-    const value = { [WeightUnit.kg]: this.toKilograms(rounding), [WeightUnit.lb]: this.toPounds(rounding) }[
-      unit
-    ];
+    const value = unit === WeightUnit.kg ? this.toKilograms(rounding) : this.toPounds(rounding);
 
     return `${value.toString()} ${unit}`;
   }
@@ -74,21 +90,24 @@ export class Weight {
 
   subtract(other: Weight): Weight {
     const result = this.grams - other.grams;
+
     return new Weight(result < 0 ? 0 : result);
   }
 
   multiply(factor: number): Weight {
-    NonNegativeNumericValue.parse(factor);
-    const gramsRounded = Math.round(this.grams * factor);
-    NonNegativeIntegerGrams.parse(gramsRounded);
-    return new Weight(gramsRounded);
+    const factorParsed = WeightQuantityNumber.parse(factor);
+    const gramsRounded = Math.round(this.grams * factorParsed);
+    const grams = CanonicalGramsInteger.parse(gramsRounded);
+
+    return new Weight(grams);
   }
 
   divideByScalar(divisor: number): Weight {
-    PositiveNumericValue.parse(divisor);
-    const gramsRounded = Math.round(this.grams / divisor);
-    NonNegativeIntegerGrams.parse(gramsRounded);
-    return new Weight(gramsRounded);
+    const divisorParsed = DivisionScalarNumber.parse(divisor);
+    const gramsRounded = Math.round(this.grams / divisorParsed);
+    const grams = CanonicalGramsInteger.parse(gramsRounded);
+
+    return new Weight(grams);
   }
 
   equals(other: Weight): boolean {

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

@@ -1,13 +1,10 @@
 import { z } from "zod/v4";
 
+export const YearIsoIdError = { error: "year-iso-id.invalid" } as const;
+
 export const YearIsoId = z
-  .string()
-  .regex(/^\d{4}$/)
-  .refine(
-    (value) => {
-      const year = Number(value);
-      return value.length === 4 && Number.isInteger(year);
-    },
-    { message: "year-iso-id.invalid" },
-  );
+  .string(YearIsoIdError)
+  .regex(/^\d{4}$/, YearIsoIdError)
+  .refine((value) => Number.isInteger(Number(value)), YearIsoIdError);
+
 export type YearIsoIdType = z.infer<typeof YearIsoId>;

package/src/year.vo.ts

@@ -3,6 +3,9 @@ import { DateRange } from "./date-range.vo";
 import { Timestamp, type TimestampType } from "./timestamp.vo";
 import { YearIsoId, type YearIsoIdType } from "./year-iso-id.vo";
 
+export const YearInvalidIntegerError = "year.invalid_integer" as const;
+export const YearOutOfRangeError = "year.out_of_range" as const;
+
 export class Year extends DateRange {
   toIsoId(): YearIsoIdType {
     return String(getYear(this.getStart())) as YearIsoIdType;
@@ -10,27 +13,32 @@ export class Year extends DateRange {
 
   isLeapYear(): boolean {
     const year = getYear(this.getStart());
+
     return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
   }
 
   previous(): Year {
     const shifted = addYears(new Date(this.getStart()), -1).getTime();
+
     return Year.fromTimestamp(Timestamp.parse(shifted));
   }
 
   next(): Year {
     const shifted = addYears(new Date(this.getStart()), 1).getTime();
+
     return Year.fromTimestamp(Timestamp.parse(shifted));
   }
 
   shift(count: number): Year {
     const shifted = addYears(new Date(this.getStart()), count).getTime();
+
     return Year.fromTimestamp(Timestamp.parse(shifted));
   }
 
   static fromTimestamp(timestamp: TimestampType): Year {
     const start = Timestamp.parse(startOfYear(timestamp).getTime());
     const end = Timestamp.parse(endOfYear(timestamp).getTime());
+
     return new Year(start, end);
   }
 
@@ -39,9 +47,11 @@ export class Year extends DateRange {
   }
 
   static fromNumber(value: number): Year {
-    if (!Number.isInteger(value)) throw new Error("year.invalid_integer");
-    if (value < 0 || value > 9999) throw new Error("year.out_of_range");
+    if (!Number.isInteger(value)) throw new Error(YearInvalidIntegerError);
+    if (value < 0 || value > 9999) throw new Error(YearOutOfRangeError);
+
     const reference = Timestamp.parse(Date.UTC(value, 0, 1, 0, 0, 0, 0));
+
     return Year.fromTimestamp(reference);
   }
 

package/dist/stepper.service.d.ts

@@ -1,23 +0,0 @@
-type StepType = number;
-type StepperConfigType = {
-    total: StepType;
-};
-export declare class Stepper {
-    static readonly DEFAULT_CURRENT = 1;
-    private current;
-    private readonly total;
-    constructor(config: StepperConfigType);
-    continue(): Stepper;
-    read(): {
-        finished: boolean;
-        raw: {
-            current: number;
-            total: number;
-        };
-        formatted: string;
-    };
-    reset(): Stepper;
-    format(): string;
-    isFinished(): boolean;
-}
-export {};

package/dist/stepper.service.js

@@ -1,33 +0,0 @@
-export class Stepper {
-    static DEFAULT_CURRENT = 1;
-    current = Stepper.DEFAULT_CURRENT;
-    total;
-    constructor(config) {
-        if (!Number.isInteger(config.total))
-            throw new Error("Total value is not an integer");
-        if (config.total <= Stepper.DEFAULT_CURRENT)
-            throw new Error("Total value should be greater than one");
-        this.total = config.total;
-    }
-    continue() {
-        this.current = Math.min(this.current + 1, this.total);
-        return this;
-    }
-    read() {
-        return {
-            finished: this.isFinished(),
-            raw: { current: this.current, total: this.total },
-            formatted: `${this.current}/${this.total}`,
-        };
-    }
-    reset() {
-        this.current = Stepper.DEFAULT_CURRENT;
-        return this;
-    }
-    format() {
-        return this.read().formatted;
-    }
-    isFinished() {
-        return this.current === this.total;
-    }
-}

package/src/stepper.service.ts

@@ -1,43 +0,0 @@
-type StepType = number;
-type StepperConfigType = { total: StepType };
-
-export class Stepper {
-  static readonly DEFAULT_CURRENT = 1;
-
-  private current: StepType = Stepper.DEFAULT_CURRENT;
-
-  private readonly total: StepType;
-
-  constructor(config: StepperConfigType) {
-    if (!Number.isInteger(config.total)) throw new Error("Total value is not an integer");
-    if (config.total <= Stepper.DEFAULT_CURRENT) throw new Error("Total value should be greater than one");
-    this.total = config.total;
-  }
-
-  continue(): Stepper {
-    this.current = Math.min(this.current + 1, this.total);
-
-    return this;
-  }
-
-  read() {
-    return {
-      finished: this.isFinished(),
-      raw: { current: this.current, total: this.total },
-      formatted: `${this.current}/${this.total}`,
-    };
-  }
-
-  reset(): Stepper {
-    this.current = Stepper.DEFAULT_CURRENT;
-    return this;
-  }
-
-  format(): string {
-    return this.read().formatted;
-  }
-
-  isFinished(): boolean {
-    return this.current === this.total;
-  }
-}