@bgord/tools 0.13.3 → 0.14.2

package/dist/age.vo.d.ts

@@ -0,0 +1,27 @@
+import { z } from "zod/v4";
+import type { TimestampType } from "./timestamp.vo";
+export declare const AgeValueError: {
+    error: string;
+};
+export declare class Age {
+    private readonly value;
+    static readonly MIN = 1;
+    static readonly MAX = 130;
+    static readonly AgeValue: z.core.$ZodBranded<z.ZodNumber, "AgeValue">;
+    private constructor();
+    get(): number;
+    compare(other: Age): -1 | 0 | 1;
+    equals(another: Age): boolean;
+    isOlderThan(another: Age): boolean;
+    isYoungerThan(another: Age): boolean;
+    isAdult(minAge: Age): boolean;
+    static fromValue(candidate: number): Age;
+    static fromBirthdateTimestamp(params: {
+        birthdate: TimestampType;
+        now: TimestampType;
+    }): Age;
+    static fromBirthdate(params: {
+        birthdate: string;
+        now: TimestampType;
+    }): Age;
+}

package/dist/age.vo.js

@@ -0,0 +1,51 @@
+import { differenceInYears } from "date-fns";
+import { z } from "zod/v4";
+export const AgeValueError = { error: "invalid.age" };
+export class Age {
+    value;
+    static MIN = 1;
+    static MAX = 130;
+    static AgeValue = z
+        .number(AgeValueError)
+        .int(AgeValueError)
+        .min(Age.MIN, AgeValueError)
+        .max(Age.MAX, AgeValueError)
+        .brand("AgeValue");
+    constructor(value) {
+        this.value = value;
+    }
+    get() {
+        return this.value;
+    }
+    compare(other) {
+        return this.value === other.value ? 0 : this.value < other.value ? -1 : 1;
+    }
+    equals(another) {
+        return this.compare(another) === 0;
+    }
+    isOlderThan(another) {
+        return this.compare(another) === 1;
+    }
+    isYoungerThan(another) {
+        return this.compare(another) === -1;
+    }
+    isAdult(minAge) {
+        return this.equals(minAge) || this.isOlderThan(minAge);
+    }
+    static fromValue(candidate) {
+        return new Age(Age.AgeValue.parse(candidate));
+    }
+    static fromBirthdateTimestamp(params) {
+        if (params.birthdate > params.now)
+            throw new Error("invalid.birthdate_in_future");
+        const years = differenceInYears(new Date(params.now), new Date(params.birthdate));
+        return Age.fromValue(years);
+    }
+    static fromBirthdate(params) {
+        const birthdate = new Date(params.birthdate).getTime();
+        if (birthdate > params.now)
+            throw new Error("invalid.birthdate_in_future");
+        const years = differenceInYears(new Date(params.now), new Date(birthdate));
+        return Age.fromValue(years);
+    }
+}

package/dist/day.vo.d.ts

@@ -4,6 +4,9 @@ import { type TimestampType } from "./timestamp.vo";
 export declare class Day extends DateRange {
     private constructor();
     toIsoId(): DayIsoIdType;
+    previous(): Day;
+    next(): Day;
+    shift(count: number): Day;
     static fromTimestamp(timestamp: TimestampType): Day;
     static fromNow(now: TimestampType): Day;
     static fromIsoId(isoId: DayIsoIdType): Day;

package/dist/day.vo.js

@@ -1,4 +1,4 @@
-import { endOfDay, startOfDay } from "date-fns";
+import { addDays, endOfDay, startOfDay } from "date-fns";
 import { DateRange } from "./date-range.vo";
 import { DayIsoId } from "./day-iso-id.vo";
 import { Time } from "./time.service";
@@ -10,6 +10,18 @@ export class Day extends DateRange {
     toIsoId() {
         return new Date(this.getStart() + Time.Hours(12).ms).toISOString().slice(0, 10);
     }
+    previous() {
+        const shifted = addDays(new Date(this.getStart()), -1).getTime();
+        return Day.fromTimestamp(Timestamp.parse(shifted));
+    }
+    next() {
+        const shifted = addDays(new Date(this.getStart()), 1).getTime();
+        return Day.fromTimestamp(Timestamp.parse(shifted));
+    }
+    shift(count) {
+        const shifted = addDays(new Date(this.getStart()), count).getTime();
+        return Day.fromTimestamp(Timestamp.parse(shifted));
+    }
     static fromTimestamp(timestamp) {
         const start = Timestamp.parse(startOfDay(timestamp).getTime());
         const end = Timestamp.parse(endOfDay(timestamp).getTime());

package/dist/height.vo.d.ts

@@ -0,0 +1,34 @@
+import { type RoundingStrategy } from "./rounding.service";
+export declare enum HeightUnit {
+    cm = "cm",
+    ft_in = "ft_in"
+}
+export declare class Height {
+    private readonly millimeters;
+    private static readonly MILLIMETERS_PER_CENTIMETER;
+    private static readonly MILLIMETERS_PER_INCH;
+    private static readonly INCHES_PER_FOOT;
+    private constructor();
+    static fromCentimeters(centimeters: number, rounding?: RoundingStrategy): Height;
+    static fromFeetInches(feet: number, inches?: number, rounding?: RoundingStrategy): Height;
+    static fromMillimeters(millimeters: number, rounding?: RoundingStrategy): Height;
+    static zero(): Height;
+    toMillimeters(): number;
+    toCentimeters(rounding?: RoundingStrategy): number;
+    toFeetInches(rounding?: RoundingStrategy): {
+        feet: number;
+        inches: number;
+    };
+    format(unit: HeightUnit, roundingStrategy?: RoundingStrategy): string;
+    equals(other: Height): boolean;
+    compare(other: Height): -1 | 0 | 1;
+    greaterThan(other: Height): boolean;
+    lessThan(other: Height): boolean;
+    isZero(): boolean;
+    toJSON(): {
+        mm: number;
+    };
+    static fromJSON(input: {
+        mm: number;
+    }): Height;
+}

package/dist/height.vo.js

@@ -0,0 +1,100 @@
+import { z } from "zod/v4";
+import { RoundToDecimal, RoundToNearest } from "./rounding.service";
+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 NonNegativeIntegerMillimeters = FiniteNumericValue.int().min(0, {
+    message: "Millimeters must be an integer greater than or equal to 0",
+});
+const NonNegativeIntegerValue = FiniteNumericValue.int().min(0, {
+    message: "Value must be an integer greater than or equal to 0",
+});
+export var HeightUnit;
+(function (HeightUnit) {
+    HeightUnit["cm"] = "cm";
+    HeightUnit["ft_in"] = "ft_in";
+})(HeightUnit || (HeightUnit = {}));
+export class Height {
+    millimeters;
+    static MILLIMETERS_PER_CENTIMETER = 10;
+    static MILLIMETERS_PER_INCH = 25.4;
+    static INCHES_PER_FOOT = 12;
+    constructor(millimeters) {
+        this.millimeters = millimeters;
+    }
+    static fromCentimeters(centimeters, rounding = new RoundToNearest()) {
+        NonNegativeNumericValue.parse(centimeters);
+        const mmFloat = centimeters * Height.MILLIMETERS_PER_CENTIMETER;
+        const mmRounded = rounding.round(mmFloat);
+        NonNegativeIntegerMillimeters.parse(mmRounded);
+        return new Height(mmRounded);
+    }
+    static fromFeetInches(feet, inches = 0, rounding = new RoundToNearest()) {
+        NonNegativeNumericValue.parse(feet);
+        NonNegativeNumericValue.parse(inches);
+        const totalInches = feet * Height.INCHES_PER_FOOT + inches;
+        const mmFloat = totalInches * Height.MILLIMETERS_PER_INCH;
+        const mmRounded = rounding.round(mmFloat);
+        NonNegativeIntegerMillimeters.parse(mmRounded);
+        return new Height(mmRounded);
+    }
+    static fromMillimeters(millimeters, rounding = new RoundToNearest()) {
+        NonNegativeNumericValue.parse(millimeters);
+        const mmRounded = rounding.round(millimeters);
+        NonNegativeIntegerMillimeters.parse(mmRounded);
+        return new Height(mmRounded);
+    }
+    static zero() {
+        return new Height(0);
+    }
+    toMillimeters() {
+        return this.millimeters;
+    }
+    toCentimeters(rounding) {
+        const cm = this.millimeters / Height.MILLIMETERS_PER_CENTIMETER;
+        return rounding ? rounding.round(cm) : cm;
+    }
+    toFeetInches(rounding = new RoundToNearest()) {
+        const totalInchesFloat = this.millimeters / Height.MILLIMETERS_PER_INCH;
+        const totalInchesRounded = rounding.round(totalInchesFloat);
+        const integerInches = NonNegativeIntegerValue.parse(totalInchesRounded);
+        const feet = (integerInches - (integerInches % Height.INCHES_PER_FOOT)) / Height.INCHES_PER_FOOT;
+        const inches = integerInches % Height.INCHES_PER_FOOT;
+        return { feet, inches };
+    }
+    format(unit, roundingStrategy) {
+        return {
+            [HeightUnit.cm]: () => {
+                const rounding = roundingStrategy ?? new RoundToDecimal(1);
+                return `${this.toCentimeters(rounding)} cm`;
+            },
+            [HeightUnit.ft_in]: () => {
+                const rounding = roundingStrategy ?? new RoundToNearest();
+                const { feet, inches } = this.toFeetInches(rounding);
+                return `${feet}′${inches}″`;
+            },
+        }[unit]();
+    }
+    equals(other) {
+        return this.millimeters === other.millimeters;
+    }
+    compare(other) {
+        if (this.equals(other))
+            return 0;
+        return this.millimeters < other.millimeters ? -1 : 1;
+    }
+    greaterThan(other) {
+        return this.millimeters > other.millimeters;
+    }
+    lessThan(other) {
+        return this.millimeters < other.millimeters;
+    }
+    isZero() {
+        return this.millimeters === 0;
+    }
+    toJSON() {
+        return { mm: this.millimeters };
+    }
+    static fromJSON(input) {
+        return Height.fromMillimeters(input.mm);
+    }
+}

package/dist/image.vo.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod/v4";
-export declare const Width: z.core.$ZodBranded<z.ZodNumber, "Width">;
-export type WidthType = z.infer<typeof Width>;
-export declare const Height: z.core.$ZodBranded<z.ZodNumber, "Height">;
-export type HeightType = z.infer<typeof Height>;
+export declare const ImageWidth: z.core.$ZodBranded<z.ZodNumber, "image-width">;
+export type WidthType = z.infer<typeof ImageWidth>;
+export declare const ImageHeight: z.core.$ZodBranded<z.ZodNumber, "image-height">;
+export type HeightType = z.infer<typeof ImageHeight>;

package/dist/image.vo.js

@@ -1,3 +1,3 @@
 import { z } from "zod/v4";
-export const Width = z.number().int().positive().max(10000).brand("Width");
-export const Height = z.number().int().positive().max(10000).brand("Height");
+export const ImageWidth = z.number().int().positive().max(10000).brand("image-width");
+export const ImageHeight = z.number().int().positive().max(10000).brand("image-height");

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./age.vo";
 export * from "./api-key.vo";
 export * from "./basename.vo";
 export * from "./clock.vo";
@@ -20,6 +21,7 @@ export * from "./file-path-relative-schema.vo";
 export * from "./filename.vo";
 export * from "./filename-from-string.vo";
 export * from "./filename-suffix.vo";
+export * from "./height.vo";
 export * from "./hour.vo";
 export * from "./iban.vo";
 export * from "./iban-mask.service";
@@ -65,6 +67,7 @@ export * from "./visually-unambiguous-characters-generator.service";
 export * from "./week.vo";
 export * from "./week-iso-id.vo";
 export * from "./weekday.vo";
+export * from "./weight.vo";
 export * from "./year.vo";
 export * from "./year-iso-id.vo";
 export * from "./z-score.service";

package/dist/index.js

@@ -1,3 +1,4 @@
+export * from "./age.vo";
 export * from "./api-key.vo";
 export * from "./basename.vo";
 export * from "./clock.vo";
@@ -20,6 +21,7 @@ export * from "./file-path-relative-schema.vo";
 export * from "./filename.vo";
 export * from "./filename-from-string.vo";
 export * from "./filename-suffix.vo";
+export * from "./height.vo";
 export * from "./hour.vo";
 export * from "./iban.vo";
 export * from "./iban-mask.service";
@@ -65,6 +67,7 @@ export * from "./visually-unambiguous-characters-generator.service";
 export * from "./week.vo";
 export * from "./week-iso-id.vo";
 export * from "./weekday.vo";
+export * from "./weight.vo";
 export * from "./year.vo";
 export * from "./year-iso-id.vo";
 export * from "./z-score.service";

package/dist/month.vo.d.ts

@@ -3,6 +3,9 @@ import { type MonthIsoIdType } from "./month-iso-id.vo";
 import { type TimestampType } from "./timestamp.vo";
 export declare class Month extends DateRange {
     toIsoId(): MonthIsoIdType;
+    previous(): Month;
+    next(): Month;
+    shift(count: number): Month;
     static fromTimestamp(timestamp: TimestampType): Month;
     static fromNow(now: TimestampType): Month;
     static fromIsoId(iso: MonthIsoIdType): Month;

package/dist/month.vo.js

@@ -1,4 +1,4 @@
-import { endOfMonth, startOfMonth } from "date-fns";
+import { addMonths, endOfMonth, startOfMonth } from "date-fns";
 import { DateRange } from "./date-range.vo";
 import { MonthIsoId } from "./month-iso-id.vo";
 import { Timestamp } from "./timestamp.vo";
@@ -6,6 +6,18 @@ export class Month extends DateRange {
     toIsoId() {
         return new Date(this.getStart()).toISOString().slice(0, 7);
     }
+    previous() {
+        const shifted = addMonths(new Date(this.getStart()), -1).getTime();
+        return Month.fromTimestamp(Timestamp.parse(shifted));
+    }
+    next() {
+        const shifted = addMonths(new Date(this.getStart()), 1).getTime();
+        return Month.fromTimestamp(Timestamp.parse(shifted));
+    }
+    shift(count) {
+        const shifted = addMonths(new Date(this.getStart()), count).getTime();
+        return Month.fromTimestamp(Timestamp.parse(shifted));
+    }
     static fromTimestamp(timestamp) {
         const start = Timestamp.parse(startOfMonth(timestamp).getTime());
         const end = Timestamp.parse(endOfMonth(timestamp).getTime());

package/dist/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../src/api-key.vo.ts","../src/basename.vo.ts","../src/clock.vo.ts","../src/date-calculator.service.ts","../src/date-formatter.service.ts","../src/date-range.vo.ts","../src/dates-of-the-week.vo.ts","../src/day-iso-id.vo.ts","../src/day.vo.ts","../src/directory-path-absolute.vo.ts","../src/directory-path-relative.vo.ts","../src/dll.service.ts","../src/email-mask.service.ts","../src/etags.vo.ts","../src/extension.vo.ts","../src/feature-flag.vo.ts","../src/file-path-absolute-schema.vo.ts","../src/file-path-relative-schema.vo.ts","../src/file-path.vo.ts","../src/filename-from-string.vo.ts","../src/filename-suffix.vo.ts","../src/filename.vo.ts","../src/hour.vo.ts","../src/iban-mask.service.ts","../src/iban.vo.ts","../src/image.vo.ts","../src/index.ts","../src/language.vo.ts","../src/mean.service.ts","../src/mime-types.vo.ts","../src/mime.vo.ts","../src/min-max-scaler.service.ts","../src/minute.vo.ts","../src/money.vo.ts","../src/month-iso-id.vo.ts","../src/month.vo.ts","../src/noop.service.ts","../src/notification-template.vo.ts","../src/object-key.vo.ts","../src/outlier-detector.service.ts","../src/package-version.vo.ts","../src/pagination.service.ts","../src/percentage.service.ts","../src/population-standard-deviation.service.ts","../src/quarter-iso-id.vo.ts","../src/quarter.vo.ts","../src/random.service.ts","../src/rate-limiter.service.ts","../src/relative-date.vo.ts","../src/reordering.service.ts","../src/revision.vo.ts","../src/rounding.service.ts","../src/simple-linear-regression.service.ts","../src/size.vo.ts","../src/stepper.service.ts","../src/stopwatch.service.ts","../src/streak-calculator.service.ts","../src/sum.service.ts","../src/thousands-separator.service.ts","../src/time-zone-offset-value.vo.ts","../src/time.service.ts","../src/timestamp.vo.ts","../src/timezone.vo.ts","../src/ts-utils.ts","../src/visually-unambiguous-characters-generator.service.ts","../src/week-iso-id.vo.ts","../src/week.vo.ts","../src/weekday.vo.ts","../src/year-iso-id.vo.ts","../src/year.vo.ts","../src/z-score.service.ts"],"version":"5.9.2"}
+{"root":["../src/age.vo.ts","../src/api-key.vo.ts","../src/basename.vo.ts","../src/clock.vo.ts","../src/date-calculator.service.ts","../src/date-formatter.service.ts","../src/date-range.vo.ts","../src/dates-of-the-week.vo.ts","../src/day-iso-id.vo.ts","../src/day.vo.ts","../src/directory-path-absolute.vo.ts","../src/directory-path-relative.vo.ts","../src/dll.service.ts","../src/email-mask.service.ts","../src/etags.vo.ts","../src/extension.vo.ts","../src/feature-flag.vo.ts","../src/file-path-absolute-schema.vo.ts","../src/file-path-relative-schema.vo.ts","../src/file-path.vo.ts","../src/filename-from-string.vo.ts","../src/filename-suffix.vo.ts","../src/filename.vo.ts","../src/height.vo.ts","../src/hour.vo.ts","../src/iban-mask.service.ts","../src/iban.vo.ts","../src/image.vo.ts","../src/index.ts","../src/language.vo.ts","../src/mean.service.ts","../src/mime-types.vo.ts","../src/mime.vo.ts","../src/min-max-scaler.service.ts","../src/minute.vo.ts","../src/money.vo.ts","../src/month-iso-id.vo.ts","../src/month.vo.ts","../src/noop.service.ts","../src/notification-template.vo.ts","../src/object-key.vo.ts","../src/outlier-detector.service.ts","../src/package-version.vo.ts","../src/pagination.service.ts","../src/percentage.service.ts","../src/population-standard-deviation.service.ts","../src/quarter-iso-id.vo.ts","../src/quarter.vo.ts","../src/random.service.ts","../src/rate-limiter.service.ts","../src/relative-date.vo.ts","../src/reordering.service.ts","../src/revision.vo.ts","../src/rounding.service.ts","../src/simple-linear-regression.service.ts","../src/size.vo.ts","../src/stepper.service.ts","../src/stopwatch.service.ts","../src/streak-calculator.service.ts","../src/sum.service.ts","../src/thousands-separator.service.ts","../src/time-zone-offset-value.vo.ts","../src/time.service.ts","../src/timestamp.vo.ts","../src/timezone.vo.ts","../src/ts-utils.ts","../src/visually-unambiguous-characters-generator.service.ts","../src/week-iso-id.vo.ts","../src/week.vo.ts","../src/weekday.vo.ts","../src/weight.vo.ts","../src/year-iso-id.vo.ts","../src/year.vo.ts","../src/z-score.service.ts"],"version":"5.9.2"}

package/dist/week.vo.d.ts

@@ -3,6 +3,9 @@ import { type TimestampType } from "./timestamp.vo";
 import { type WeekIsoIdType } from "./week-iso-id.vo";
 export declare class Week extends DateRange {
     toIsoId(): WeekIsoIdType;
+    previous(): Week;
+    next(): Week;
+    shift(count: number): Week;
     static fromTimestamp(timestamp: TimestampType): Week;
     static fromNow(now: TimestampType): Week;
     static fromIsoId(isoId: WeekIsoIdType): Week;

package/dist/week.vo.js

@@ -1,4 +1,4 @@
-import { endOfISOWeek, getISOWeek, getISOWeekYear, setISOWeek, startOfISOWeek } from "date-fns";
+import { addWeeks, endOfISOWeek, getISOWeek, getISOWeekYear, setISOWeek, startOfISOWeek } from "date-fns";
 import { DateRange } from "./date-range.vo";
 import { Timestamp } from "./timestamp.vo";
 import { WeekIsoId } from "./week-iso-id.vo";
@@ -8,6 +8,18 @@ export class Week extends DateRange {
         const week = getISOWeek(this.getStart()).toString().padStart(2, "0");
         return `${year}-W${week}`;
     }
+    previous() {
+        const shifted = addWeeks(new Date(this.getStart()), -1).getTime();
+        return Week.fromTimestamp(Timestamp.parse(shifted));
+    }
+    next() {
+        const shifted = addWeeks(new Date(this.getStart()), 1).getTime();
+        return Week.fromTimestamp(Timestamp.parse(shifted));
+    }
+    shift(count) {
+        const shifted = addWeeks(new Date(this.getStart()), count).getTime();
+        return Week.fromTimestamp(Timestamp.parse(shifted));
+    }
     static fromTimestamp(timestamp) {
         const start = Timestamp.parse(startOfISOWeek(timestamp).getTime());
         const end = Timestamp.parse(endOfISOWeek(timestamp).getTime());

package/dist/weight.vo.d.ts

@@ -0,0 +1,38 @@
+import { type RoundingStrategy } from "./rounding.service";
+export declare enum WeightUnit {
+    kg = "kg",
+    lb = "lb"
+}
+export declare class Weight {
+    private readonly grams;
+    private static readonly GRAMS_PER_KILOGRAM;
+    private static readonly POUNDS_PER_KILOGRAM;
+    private static readonly KILOGRAMS_PER_POUND;
+    private constructor();
+    static fromKilograms(kilograms: number): Weight;
+    static fromPounds(pounds: number): Weight;
+    static fromGrams(grams: number): Weight;
+    static zero(): Weight;
+    toGrams(): number;
+    toKilograms(rounding?: RoundingStrategy): number;
+    toPounds(rounding?: RoundingStrategy): number;
+    format(unit: WeightUnit, rounding?: RoundingStrategy): string;
+    add(other: Weight): Weight;
+    subtract(other: Weight): Weight;
+    multiply(factor: number): Weight;
+    divideByScalar(divisor: number): Weight;
+    equals(other: Weight): boolean;
+    compare(other: Weight): -1 | 0 | 1;
+    greaterThan(other: Weight): boolean;
+    greaterThanOrEqual(other: Weight): boolean;
+    lessThan(other: Weight): boolean;
+    lessThanOrEqual(other: Weight): boolean;
+    isZero(): boolean;
+    isPositive(): boolean;
+    toJSON(): {
+        g: number;
+    };
+    static fromJSON(input: {
+        g: number;
+    }): Weight;
+}

package/dist/weight.vo.js

@@ -0,0 +1,109 @@
+import { z } from "zod/v4";
+import { RoundToDecimal } from "./rounding.service";
+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 var WeightUnit;
+(function (WeightUnit) {
+    WeightUnit["kg"] = "kg";
+    WeightUnit["lb"] = "lb";
+})(WeightUnit || (WeightUnit = {}));
+export class Weight {
+    grams;
+    static GRAMS_PER_KILOGRAM = 1_000;
+    static POUNDS_PER_KILOGRAM = 2.2046226218487757;
+    static KILOGRAMS_PER_POUND = 1 / Weight.POUNDS_PER_KILOGRAM;
+    constructor(grams) {
+        this.grams = grams;
+    }
+    static fromKilograms(kilograms) {
+        NonNegativeNumericValue.parse(kilograms);
+        const gramsRounded = Math.round(kilograms * Weight.GRAMS_PER_KILOGRAM);
+        NonNegativeIntegerGrams.parse(gramsRounded);
+        return new Weight(gramsRounded);
+    }
+    static fromPounds(pounds) {
+        NonNegativeNumericValue.parse(pounds);
+        const gramsRounded = Math.round(pounds * Weight.KILOGRAMS_PER_POUND * Weight.GRAMS_PER_KILOGRAM);
+        NonNegativeIntegerGrams.parse(gramsRounded);
+        return new Weight(gramsRounded);
+    }
+    static fromGrams(grams) {
+        NonNegativeNumericValue.parse(grams);
+        const gramsRounded = Math.round(grams);
+        NonNegativeIntegerGrams.parse(gramsRounded);
+        return new Weight(gramsRounded);
+    }
+    static zero() {
+        return new Weight(0);
+    }
+    toGrams() {
+        return this.grams;
+    }
+    toKilograms(rounding) {
+        const kilograms = this.grams / Weight.GRAMS_PER_KILOGRAM;
+        return rounding ? rounding.round(kilograms) : kilograms;
+    }
+    toPounds(rounding) {
+        const pounds = (this.grams / Weight.GRAMS_PER_KILOGRAM) * Weight.POUNDS_PER_KILOGRAM;
+        return rounding ? rounding.round(pounds) : pounds;
+    }
+    format(unit, rounding = new RoundToDecimal(2)) {
+        const value = { [WeightUnit.kg]: this.toKilograms(rounding), [WeightUnit.lb]: this.toPounds(rounding) }[unit];
+        return `${value.toString()} ${unit}`;
+    }
+    add(other) {
+        return new Weight(this.grams + other.grams);
+    }
+    subtract(other) {
+        const result = this.grams - other.grams;
+        return new Weight(result < 0 ? 0 : result);
+    }
+    multiply(factor) {
+        NonNegativeNumericValue.parse(factor);
+        const gramsRounded = Math.round(this.grams * factor);
+        NonNegativeIntegerGrams.parse(gramsRounded);
+        return new Weight(gramsRounded);
+    }
+    divideByScalar(divisor) {
+        PositiveNumericValue.parse(divisor);
+        const gramsRounded = Math.round(this.grams / divisor);
+        NonNegativeIntegerGrams.parse(gramsRounded);
+        return new Weight(gramsRounded);
+    }
+    equals(other) {
+        return this.grams === other.grams;
+    }
+    compare(other) {
+        if (this.grams === other.grams)
+            return 0;
+        return this.grams < other.grams ? -1 : 1;
+    }
+    greaterThan(other) {
+        return this.grams > other.grams;
+    }
+    greaterThanOrEqual(other) {
+        return this.grams >= other.grams;
+    }
+    lessThan(other) {
+        return this.grams < other.grams;
+    }
+    lessThanOrEqual(other) {
+        return this.grams <= other.grams;
+    }
+    isZero() {
+        return this.grams === 0;
+    }
+    isPositive() {
+        return this.grams > 0;
+    }
+    toJSON() {
+        return { g: this.grams };
+    }
+    static fromJSON(input) {
+        return Weight.fromGrams(input.g);
+    }
+}

package/dist/year.vo.d.ts

@@ -4,6 +4,9 @@ import { type YearIsoIdType } from "./year-iso-id.vo";
 export declare class Year extends DateRange {
     toIsoId(): YearIsoIdType;
     isLeapYear(): boolean;
+    previous(): Year;
+    next(): Year;
+    shift(count: number): Year;
     static fromTimestamp(timestamp: TimestampType): Year;
     static fromNow(now: TimestampType): Year;
     static fromNumber(value: number): Year;

package/dist/year.vo.js

@@ -1,4 +1,4 @@
-import { endOfYear, getYear, startOfYear } from "date-fns";
+import { addYears, endOfYear, getYear, startOfYear } from "date-fns";
 import { DateRange } from "./date-range.vo";
 import { Timestamp } from "./timestamp.vo";
 import { YearIsoId } from "./year-iso-id.vo";
@@ -10,6 +10,18 @@ export class Year extends DateRange {
         const year = getYear(this.getStart());
         return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
     }
+    previous() {
+        const shifted = addYears(new Date(this.getStart()), -1).getTime();
+        return Year.fromTimestamp(Timestamp.parse(shifted));
+    }
+    next() {
+        const shifted = addYears(new Date(this.getStart()), 1).getTime();
+        return Year.fromTimestamp(Timestamp.parse(shifted));
+    }
+    shift(count) {
+        const shifted = addYears(new Date(this.getStart()), count).getTime();
+        return Year.fromTimestamp(Timestamp.parse(shifted));
+    }
     static fromTimestamp(timestamp) {
         const start = Timestamp.parse(startOfYear(timestamp).getTime());
         const end = Timestamp.parse(endOfYear(timestamp).getTime());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bgord/tools",
-  "version": "0.13.3",
+  "version": "0.14.2",
   "type": "module",
   "license": "MIT",
   "author": "Bartosz Gordon",
@@ -22,13 +22,13 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.2.4",
-    "@commitlint/cli": "20.0.0",
+    "@commitlint/cli": "20.1.0",
     "@commitlint/config-conventional": "20.0.0",
-    "@types/bun": "1.2.22",
+    "@types/bun": "1.2.23",
     "@types/mime-types": "3.0.1",
     "cspell": "9.2.1",
-    "knip": "5.64.0",
-    "lefthook": "1.13.4",
+    "knip": "5.64.1",
+    "lefthook": "1.13.6",
     "only-allow": "1.2.1",
     "shellcheck": "4.1.0",
     "typescript": "5.9.2",

package/readme.md

@@ -24,6 +24,7 @@ Run the tests
 
 ```
 src/
+├── age.vo.ts
 ├── api-key.vo.ts
 ├── basename.vo.ts
 ├── clock.vo.ts
@@ -46,6 +47,7 @@ src/
 ├── filename-from-string.vo.ts
 ├── filename-suffix.vo.ts
 ├── filename.vo.ts
+├── height.vo.ts
 ├── hour.vo.ts
 ├── iban-mask.service.ts
 ├── iban.vo.ts
@@ -91,6 +93,7 @@ src/
 ├── week-iso-id.vo.ts
 ├── week.vo.ts
 ├── weekday.vo.ts
+├── weight.vo.ts
 ├── year-iso-id.vo.ts
 ├── year.vo.ts
 └── z-score.service.ts

package/src/age.vo.ts

@@ -0,0 +1,65 @@
+import { differenceInYears } from "date-fns";
+import { z } from "zod/v4";
+import type { TimestampType } from "./timestamp.vo";
+
+export const AgeValueError = { error: "invalid.age" };
+
+export class Age {
+  static readonly MIN = 1;
+  static readonly MAX = 130;
+
+  static readonly AgeValue = z
+    .number(AgeValueError)
+    .int(AgeValueError)
+    .min(Age.MIN, AgeValueError)
+    .max(Age.MAX, AgeValueError)
+    .brand("AgeValue");
+
+  private constructor(private readonly value: z.infer<typeof Age.AgeValue>) {}
+
+  get(): number {
+    return this.value as number;
+  }
+
+  compare(other: Age): -1 | 0 | 1 {
+    return this.value === other.value ? 0 : this.value < other.value ? -1 : 1;
+  }
+
+  equals(another: Age): boolean {
+    return this.compare(another) === 0;
+  }
+
+  isOlderThan(another: Age): boolean {
+    return this.compare(another) === 1;
+  }
+
+  isYoungerThan(another: Age): boolean {
+    return this.compare(another) === -1;
+  }
+
+  isAdult(minAge: Age): boolean {
+    return this.equals(minAge) || this.isOlderThan(minAge);
+  }
+
+  static fromValue(candidate: number): Age {
+    return new Age(Age.AgeValue.parse(candidate));
+  }
+
+  static fromBirthdateTimestamp(params: { birthdate: TimestampType; now: TimestampType }): Age {
+    if (params.birthdate > params.now) throw new Error("invalid.birthdate_in_future");
+
+    const years = differenceInYears(new Date(params.now), new Date(params.birthdate));
+
+    return Age.fromValue(years);
+  }
+
+  static fromBirthdate(params: { birthdate: string; now: TimestampType }): Age {
+    const birthdate = new Date(params.birthdate).getTime();
+
+    if (birthdate > params.now) throw new Error("invalid.birthdate_in_future");
+
+    const years = differenceInYears(new Date(params.now), new Date(birthdate));
+
+    return Age.fromValue(years);
+  }
+}

package/src/day.vo.ts

@@ -1,4 +1,4 @@
-import { endOfDay, startOfDay } from "date-fns";
+import { addDays, endOfDay, startOfDay } from "date-fns";
 import { DateRange } from "./date-range.vo";
 import { DayIsoId, type DayIsoIdType } from "./day-iso-id.vo";
 import { Time } from "./time.service";
@@ -13,6 +13,21 @@ export class Day extends DateRange {
     return new Date(this.getStart() + Time.Hours(12).ms).toISOString().slice(0, 10) as DayIsoIdType;
   }
 
+  previous(): Day {
+    const shifted = addDays(new Date(this.getStart()), -1).getTime();
+    return Day.fromTimestamp(Timestamp.parse(shifted));
+  }
+
+  next(): Day {
+    const shifted = addDays(new Date(this.getStart()), 1).getTime();
+    return Day.fromTimestamp(Timestamp.parse(shifted));
+  }
+
+  shift(count: number): Day {
+    const shifted = addDays(new Date(this.getStart()), count).getTime();
+    return Day.fromTimestamp(Timestamp.parse(shifted));
+  }
+
   static fromTimestamp(timestamp: TimestampType): Day {
     const start = Timestamp.parse(startOfDay(timestamp).getTime());
     const end = Timestamp.parse(endOfDay(timestamp).getTime());

package/src/height.vo.ts

@@ -0,0 +1,121 @@
+import { z } from "zod/v4";
+import { type RoundingStrategy, RoundToDecimal, RoundToNearest } from "./rounding.service";
+
+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 NonNegativeIntegerMillimeters = FiniteNumericValue.int().min(0, {
+  message: "Millimeters must be an integer greater than or equal to 0",
+});
+const NonNegativeIntegerValue = FiniteNumericValue.int().min(0, {
+  message: "Value must be an integer greater than or equal to 0",
+});
+
+export enum HeightUnit {
+  cm = "cm",
+  ft_in = "ft_in",
+}
+
+export class Height {
+  private static readonly MILLIMETERS_PER_CENTIMETER = 10;
+  private static readonly MILLIMETERS_PER_INCH = 25.4;
+  private static readonly INCHES_PER_FOOT = 12;
+
+  private constructor(private readonly millimeters: number) {}
+
+  static fromCentimeters(centimeters: number, rounding: RoundingStrategy = new RoundToNearest()): Height {
+    NonNegativeNumericValue.parse(centimeters);
+    const mmFloat = centimeters * Height.MILLIMETERS_PER_CENTIMETER;
+    const mmRounded = rounding.round(mmFloat);
+    NonNegativeIntegerMillimeters.parse(mmRounded);
+    return new Height(mmRounded);
+  }
+
+  static fromFeetInches(feet: number, inches = 0, rounding: RoundingStrategy = new RoundToNearest()): Height {
+    NonNegativeNumericValue.parse(feet);
+    NonNegativeNumericValue.parse(inches);
+    const totalInches = feet * Height.INCHES_PER_FOOT + inches;
+    const mmFloat = totalInches * Height.MILLIMETERS_PER_INCH;
+    const mmRounded = rounding.round(mmFloat);
+    NonNegativeIntegerMillimeters.parse(mmRounded);
+    return new Height(mmRounded);
+  }
+
+  static fromMillimeters(millimeters: number, rounding: RoundingStrategy = new RoundToNearest()): Height {
+    NonNegativeNumericValue.parse(millimeters);
+    const mmRounded = rounding.round(millimeters);
+    NonNegativeIntegerMillimeters.parse(mmRounded);
+    return new Height(mmRounded);
+  }
+
+  static zero(): Height {
+    return new Height(0);
+  }
+
+  toMillimeters(): number {
+    return this.millimeters;
+  }
+
+  toCentimeters(rounding?: RoundingStrategy): number {
+    const cm = this.millimeters / Height.MILLIMETERS_PER_CENTIMETER;
+    return rounding ? rounding.round(cm) : cm;
+  }
+
+  toFeetInches(rounding: RoundingStrategy = new RoundToNearest()): {
+    feet: number;
+    inches: number;
+  } {
+    const totalInchesFloat = this.millimeters / Height.MILLIMETERS_PER_INCH;
+    const totalInchesRounded = rounding.round(totalInchesFloat);
+    const integerInches = NonNegativeIntegerValue.parse(totalInchesRounded);
+
+    const feet = (integerInches - (integerInches % Height.INCHES_PER_FOOT)) / Height.INCHES_PER_FOOT;
+    const inches = integerInches % Height.INCHES_PER_FOOT;
+
+    return { feet, inches };
+  }
+
+  format(unit: HeightUnit, roundingStrategy?: RoundingStrategy): string {
+    return {
+      [HeightUnit.cm]: () => {
+        const rounding = roundingStrategy ?? new RoundToDecimal(1);
+
+        return `${this.toCentimeters(rounding)} cm`;
+      },
+      [HeightUnit.ft_in]: () => {
+        const rounding = roundingStrategy ?? new RoundToNearest();
+        const { feet, inches } = this.toFeetInches(rounding);
+
+        return `${feet}′${inches}″`;
+      },
+    }[unit]();
+  }
+
+  equals(other: Height): boolean {
+    return this.millimeters === other.millimeters;
+  }
+
+  compare(other: Height): -1 | 0 | 1 {
+    if (this.equals(other)) return 0;
+    return this.millimeters < other.millimeters ? -1 : 1;
+  }
+
+  greaterThan(other: Height): boolean {
+    return this.millimeters > other.millimeters;
+  }
+
+  lessThan(other: Height): boolean {
+    return this.millimeters < other.millimeters;
+  }
+
+  isZero(): boolean {
+    return this.millimeters === 0;
+  }
+
+  toJSON(): { mm: number } {
+    return { mm: this.millimeters };
+  }
+
+  static fromJSON(input: { mm: number }): Height {
+    return Height.fromMillimeters(input.mm);
+  }
+}

package/src/image.vo.ts

@@ -1,7 +1,7 @@
 import { z } from "zod/v4";
 
-export const Width = z.number().int().positive().max(10000).brand("Width");
-export type WidthType = z.infer<typeof Width>;
+export const ImageWidth = z.number().int().positive().max(10000).brand("image-width");
+export type WidthType = z.infer<typeof ImageWidth>;
 
-export const Height = z.number().int().positive().max(10000).brand("Height");
-export type HeightType = z.infer<typeof Height>;
+export const ImageHeight = z.number().int().positive().max(10000).brand("image-height");
+export type HeightType = z.infer<typeof ImageHeight>;

package/src/index.ts

@@ -1,3 +1,4 @@
+export * from "./age.vo";
 export * from "./api-key.vo";
 export * from "./basename.vo";
 export * from "./clock.vo";
@@ -20,6 +21,7 @@ export * from "./file-path-relative-schema.vo";
 export * from "./filename.vo";
 export * from "./filename-from-string.vo";
 export * from "./filename-suffix.vo";
+export * from "./height.vo";
 export * from "./hour.vo";
 export * from "./iban.vo";
 export * from "./iban-mask.service";
@@ -65,6 +67,7 @@ export * from "./visually-unambiguous-characters-generator.service";
 export * from "./week.vo";
 export * from "./week-iso-id.vo";
 export * from "./weekday.vo";
+export * from "./weight.vo";
 export * from "./year.vo";
 export * from "./year-iso-id.vo";
 export * from "./z-score.service";

package/src/month.vo.ts

@@ -1,4 +1,4 @@
-import { endOfMonth, startOfMonth } from "date-fns";
+import { addMonths, endOfMonth, 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";
@@ -8,6 +8,21 @@ export class Month extends DateRange {
     return new Date(this.getStart()).toISOString().slice(0, 7) as MonthIsoIdType;
   }
 
+  previous(): Month {
+    const shifted = addMonths(new Date(this.getStart()), -1).getTime();
+    return Month.fromTimestamp(Timestamp.parse(shifted));
+  }
+
+  next(): Month {
+    const shifted = addMonths(new Date(this.getStart()), 1).getTime();
+    return Month.fromTimestamp(Timestamp.parse(shifted));
+  }
+
+  shift(count: number): Month {
+    const shifted = addMonths(new Date(this.getStart()), count).getTime();
+    return Month.fromTimestamp(Timestamp.parse(shifted));
+  }
+
   static fromTimestamp(timestamp: TimestampType): Month {
     const start = Timestamp.parse(startOfMonth(timestamp).getTime());
     const end = Timestamp.parse(endOfMonth(timestamp).getTime());

package/src/week.vo.ts

@@ -1,4 +1,4 @@
-import { endOfISOWeek, getISOWeek, getISOWeekYear, setISOWeek, startOfISOWeek } from "date-fns";
+import { addWeeks, endOfISOWeek, getISOWeek, getISOWeekYear, setISOWeek, startOfISOWeek } from "date-fns";
 import { DateRange } from "./date-range.vo";
 import { Timestamp, type TimestampType } from "./timestamp.vo";
 import { WeekIsoId, type WeekIsoIdType } from "./week-iso-id.vo";
@@ -11,6 +11,21 @@ export class Week extends DateRange {
     return `${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));
+  }
+
   static fromTimestamp(timestamp: TimestampType): Week {
     const start = Timestamp.parse(startOfISOWeek(timestamp).getTime());
     const end = Timestamp.parse(endOfISOWeek(timestamp).getTime());

package/src/weight.vo.ts

@@ -0,0 +1,133 @@
+import { z } from "zod/v4";
+import { type RoundingStrategy, RoundToDecimal } from "./rounding.service";
+
+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 class Weight {
+  private static readonly GRAMS_PER_KILOGRAM = 1_000;
+  private static readonly POUNDS_PER_KILOGRAM = 2.2046226218487757;
+  private static readonly KILOGRAMS_PER_POUND = 1 / Weight.POUNDS_PER_KILOGRAM;
+
+  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);
+  }
+
+  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);
+  }
+
+  static fromGrams(grams: number): Weight {
+    NonNegativeNumericValue.parse(grams);
+    const gramsRounded = Math.round(grams);
+    NonNegativeIntegerGrams.parse(gramsRounded);
+    return new Weight(gramsRounded);
+  }
+
+  static zero(): Weight {
+    return new Weight(0);
+  }
+
+  toGrams(): number {
+    return this.grams;
+  }
+
+  toKilograms(rounding?: RoundingStrategy): number {
+    const kilograms = this.grams / Weight.GRAMS_PER_KILOGRAM;
+    return rounding ? rounding.round(kilograms) : kilograms;
+  }
+
+  toPounds(rounding?: RoundingStrategy): number {
+    const pounds = (this.grams / Weight.GRAMS_PER_KILOGRAM) * Weight.POUNDS_PER_KILOGRAM;
+    return rounding ? rounding.round(pounds) : pounds;
+  }
+
+  format(unit: WeightUnit, rounding: RoundingStrategy = new RoundToDecimal(2)): string {
+    const value = { [WeightUnit.kg]: this.toKilograms(rounding), [WeightUnit.lb]: this.toPounds(rounding) }[
+      unit
+    ];
+
+    return `${value.toString()} ${unit}`;
+  }
+
+  add(other: Weight): Weight {
+    return new Weight(this.grams + other.grams);
+  }
+
+  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);
+  }
+
+  divideByScalar(divisor: number): Weight {
+    PositiveNumericValue.parse(divisor);
+    const gramsRounded = Math.round(this.grams / divisor);
+    NonNegativeIntegerGrams.parse(gramsRounded);
+    return new Weight(gramsRounded);
+  }
+
+  equals(other: Weight): boolean {
+    return this.grams === other.grams;
+  }
+
+  compare(other: Weight): -1 | 0 | 1 {
+    if (this.grams === other.grams) return 0;
+    return this.grams < other.grams ? -1 : 1;
+  }
+
+  greaterThan(other: Weight): boolean {
+    return this.grams > other.grams;
+  }
+
+  greaterThanOrEqual(other: Weight): boolean {
+    return this.grams >= other.grams;
+  }
+
+  lessThan(other: Weight): boolean {
+    return this.grams < other.grams;
+  }
+
+  lessThanOrEqual(other: Weight): boolean {
+    return this.grams <= other.grams;
+  }
+
+  isZero(): boolean {
+    return this.grams === 0;
+  }
+
+  isPositive(): boolean {
+    return this.grams > 0;
+  }
+
+  toJSON(): { g: number } {
+    return { g: this.grams };
+  }
+
+  static fromJSON(input: { g: number }): Weight {
+    return Weight.fromGrams(input.g);
+  }
+}

package/src/year.vo.ts

@@ -1,4 +1,4 @@
-import { endOfYear, getYear, startOfYear } from "date-fns";
+import { addYears, endOfYear, getYear, startOfYear } from "date-fns";
 import { DateRange } from "./date-range.vo";
 import { Timestamp, type TimestampType } from "./timestamp.vo";
 import { YearIsoId, type YearIsoIdType } from "./year-iso-id.vo";
@@ -13,6 +13,21 @@ export class Year extends DateRange {
     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());