@bgord/tools 0.17.2 → 1.0.0

package/dist/week.vo.d.ts

@@ -2,11 +2,12 @@ import { DateRange } from "./date-range.vo";
 import { type TimestampType } from "./timestamp.vo";
 import { type WeekIsoIdType } from "./week-iso-id.vo";
 export declare class Week extends DateRange {
+    static fromTimestamp(timestamp: TimestampType): Week;
+    static fromNow(now: TimestampType): Week;
+    static fromIsoId(isoId: WeekIsoIdType): Week;
     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;
+    toString(): string;
 }

package/dist/week.vo.js

@@ -3,23 +3,6 @@ import { DateRange } from "./date-range.vo";
 import { Timestamp } from "./timestamp.vo";
 import { WeekIsoId } from "./week-iso-id.vo";
 export class Week extends DateRange {
-    toIsoId() {
-        const year = getISOWeekYear(this.getStart());
-        const week = getISOWeek(this.getStart()).toString().padStart(2, "0");
-        return WeekIsoId.parse(`${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());
@@ -29,11 +12,27 @@ export class Week extends DateRange {
         return Week.fromTimestamp(now);
     }
     static fromIsoId(isoId) {
-        const [yearPart, weekPart] = WeekIsoId.parse(isoId).split("-W");
-        const year = Number(yearPart);
-        const week = Number(weekPart);
+        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(new Date(Date.UTC(year, 0, 4)), week);
-        return Week.fromTimestamp(Timestamp.parse(reference.getTime()));
+        const reference = setISOWeek(Date.UTC(year, 0, 4), week).getTime();
+        return Week.fromTimestamp(Timestamp.parse(reference));
+    }
+    toIsoId() {
+        const year = getISOWeekYear(this.getStart());
+        const week = getISOWeek(this.getStart());
+        return WeekIsoId.parse(`${year}-W${String(week).padStart(2, "0")}`);
+    }
+    previous() {
+        return this.shift(-1);
+    }
+    next() {
+        return this.shift(1);
+    }
+    shift(count) {
+        const shifted = addWeeks(this.getStart(), count).getTime();
+        return Week.fromTimestamp(Timestamp.parse(shifted));
+    }
+    toString() {
+        return this.toIsoId();
     }
 }

package/dist/weekday.vo.d.ts

@@ -21,7 +21,7 @@ export declare class Weekday {
     constructor(candidate: number, formatter?: WeekdayFormatter);
     static fromUtcTimestamp(timestamp: TimestampType, formatter?: WeekdayFormatter): Weekday;
     get(): number;
-    format(formatter?: WeekdayFormatter): string;
+    format(): string;
     toString(): string;
     equals(another: Weekday): boolean;
     /** ISO-8601 weekday number: Monday=1 ... Sunday=7 */

package/dist/weekday.vo.js

@@ -47,12 +47,11 @@ export class Weekday {
     get() {
         return this.value;
     }
-    format(formatter) {
-        const chosen = formatter ?? this.formatter;
-        return chosen(this.value);
+    format() {
+        return this.formatter(this.value);
     }
     toString() {
-        return this.format(WeekdayFormatters.FULL);
+        return this.format();
     }
     equals(another) {
         return this.value === another.value;
@@ -83,11 +82,10 @@ export class Weekday {
         return this.value === 0;
     }
     static list(formatter) {
-        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) {
-        const days = Weekday.list(formatter);
-        return [...days.slice(1), days[0]];
+        const [Sunday, ...rest] = Weekday.list(formatter);
+        return [...rest, Sunday];
     }
 }

package/dist/weight-grams.vo.d.ts

@@ -0,0 +1,7 @@
+import { z } from "zod/v4";
+export declare const WeightGramsError: {
+    readonly Type: "weight.grams.type";
+    readonly Invalid: "weight.grams.invalid";
+};
+export declare const WeightGrams: z.core.$ZodBranded<z.ZodNumber, "WeightGrams">;
+export type WeightGramsType = z.infer<typeof WeightGrams>;

package/dist/weight-grams.vo.js

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

package/dist/weight.vo.d.ts

@@ -1,50 +1,27 @@
+import type { DivisionFactorType } from "./division-factor.vo";
+import type { MultiplicationFactorType } from "./multiplication-factor.vo";
 import type { RoundingPort } from "./rounding.port";
-export declare enum WeightUnit {
-    kg = "kg",
-    lb = "lb"
-}
-export declare const WeightNonFiniteError: {
-    readonly error: "weight.non_finite";
-};
-export declare const WeightNegativeError: {
-    readonly error: "weight.negative";
-};
-export declare const WeightNonPositiveError: {
-    readonly error: "weight.non_positive";
-};
-export declare const WeightGramsNonNegativeError: {
-    readonly error: "weight.grams_non_negative";
-};
 export declare class Weight {
     private readonly grams;
+    private readonly rounding;
     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 fromKilograms(kilograms: number, rounding?: RoundingPort): Weight;
+    static fromGrams(grams: number, rounding?: RoundingPort): Weight;
     static zero(): Weight;
-    toGrams(): number;
-    toKilograms(rounding?: RoundingPort): number;
-    toPounds(rounding?: RoundingPort): number;
-    format(unit: WeightUnit, rounding?: RoundingPort): string;
+    get(): number;
+    toKilograms(): number;
+    format(): string;
     add(other: Weight): Weight;
     subtract(other: Weight): Weight;
-    multiply(factor: number): Weight;
-    divideByScalar(divisor: number): Weight;
+    multiply(factor: MultiplicationFactorType): Weight;
+    divide(divisor: DivisionFactorType): 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;
+    toString(): string;
+    toJSON(): number;
 }

package/dist/weight.vo.js

@@ -1,69 +1,32 @@
-import { z } from "zod/v4";
-import { RoundToDecimal } from "./rounding.adapter";
-export var WeightUnit;
-(function (WeightUnit) {
-    WeightUnit["kg"] = "kg";
-    WeightUnit["lb"] = "lb";
-})(WeightUnit || (WeightUnit = {}));
-export const WeightNonFiniteError = { error: "weight.non_finite" };
-export const WeightNegativeError = { error: "weight.negative" };
-export const WeightNonPositiveError = { error: "weight.non_positive" };
-export const WeightGramsNonNegativeError = { error: "weight.grams_non_negative" };
-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);
+import { RoundToNearest } from "./rounding.adapter";
+import { WeightGrams } from "./weight-grams.vo";
 export class Weight {
     grams;
+    rounding;
     static GRAMS_PER_KILOGRAM = 1_000;
-    static POUNDS_PER_KILOGRAM = 2.2046226218487757;
-    static KILOGRAMS_PER_POUND = 1 / Weight.POUNDS_PER_KILOGRAM;
-    constructor(grams) {
+    constructor(grams, rounding = new RoundToNearest()) {
         this.grams = grams;
+        this.rounding = rounding;
     }
-    static fromKilograms(kilograms) {
-        const kilogramsParsed = WeightQuantityNumber.parse(kilograms);
-        const gramsRounded = Math.round(kilogramsParsed * Weight.GRAMS_PER_KILOGRAM);
-        const grams = CanonicalGramsInteger.parse(gramsRounded);
-        return new Weight(grams);
+    static fromKilograms(kilograms, rounding = new RoundToNearest()) {
+        const grams = rounding.round(kilograms * Weight.GRAMS_PER_KILOGRAM);
+        return new Weight(WeightGrams.parse(grams), rounding);
     }
-    static fromPounds(pounds) {
-        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) {
-        const gramsParsed = WeightQuantityNumber.parse(grams);
-        const gramsRounded = Math.round(gramsParsed);
-        const integerGrams = CanonicalGramsInteger.parse(gramsRounded);
-        return new Weight(integerGrams);
+    static fromGrams(grams, rounding = new RoundToNearest()) {
+        return new Weight(WeightGrams.parse(grams), rounding);
     }
     static zero() {
         return new Weight(0);
     }
-    toGrams() {
+    get() {
         return this.grams;
     }
-    toKilograms(rounding) {
+    toKilograms() {
         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;
+        return this.rounding.round(kilograms);
     }
-    format(unit, rounding = new RoundToDecimal(2)) {
-        const value = unit === WeightUnit.kg ? this.toKilograms(rounding) : this.toPounds(rounding);
-        return `${value.toString()} ${unit}`;
+    format() {
+        return `${this.grams} g`;
     }
     add(other) {
         return new Weight(this.grams + other.grams);
@@ -73,25 +36,16 @@ export class Weight {
         return new Weight(result < 0 ? 0 : result);
     }
     multiply(factor) {
-        const factorParsed = WeightQuantityNumber.parse(factor);
-        const gramsRounded = Math.round(this.grams * factorParsed);
-        const grams = CanonicalGramsInteger.parse(gramsRounded);
-        return new Weight(grams);
+        const grams = this.rounding.round(this.grams * factor);
+        return new Weight(WeightGrams.parse(grams));
     }
-    divideByScalar(divisor) {
-        const divisorParsed = DivisionScalarNumber.parse(divisor);
-        const gramsRounded = Math.round(this.grams / divisorParsed);
-        const grams = CanonicalGramsInteger.parse(gramsRounded);
-        return new Weight(grams);
+    divide(divisor) {
+        const grams = this.rounding.round(this.grams / divisor);
+        return new Weight(WeightGrams.parse(grams));
     }
     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;
     }
@@ -107,13 +61,10 @@ export class Weight {
     isZero() {
         return this.grams === 0;
     }
-    isPositive() {
-        return this.grams > 0;
+    toString() {
+        return this.format();
     }
     toJSON() {
-        return { g: this.grams };
-    }
-    static fromJSON(input) {
-        return Weight.fromGrams(input.g);
+        return this.grams;
     }
 }

package/dist/year-iso-id.vo.d.ts

@@ -1,6 +1,7 @@
 import { z } from "zod/v4";
 export declare const YearIsoIdError: {
-    readonly error: "year-iso-id.invalid";
+    readonly Type: "year.iso.id.type";
+    readonly BadChars: "year.iso.id.bad.chars";
 };
-export declare const YearIsoId: z.ZodString;
+export declare const YearIsoId: z.core.$ZodBranded<z.ZodString, "YearIsoId">;
 export type YearIsoIdType = z.infer<typeof YearIsoId>;

package/dist/year-iso-id.vo.js

@@ -1,6 +1,8 @@
 import { z } from "zod/v4";
-export const YearIsoIdError = { error: "year-iso-id.invalid" };
+export const YearIsoIdError = { Type: "year.iso.id.type", BadChars: "year.iso.id.bad.chars" };
+// Four digits
+const YEAR_ISO_ID_CHARS_WHITELIST = /^[0-9]{4}$/;
 export const YearIsoId = z
-    .string(YearIsoIdError)
-    .regex(/^\d{4}$/, YearIsoIdError)
-    .refine((value) => Number.isInteger(Number(value)), YearIsoIdError);
+    .string(YearIsoIdError.Type)
+    .regex(YEAR_ISO_ID_CHARS_WHITELIST, YearIsoIdError.BadChars)
+    .brand("YearIsoId");

package/dist/year.vo.d.ts

@@ -1,16 +1,15 @@
 import { DateRange } from "./date-range.vo";
 import { type TimestampType } from "./timestamp.vo";
 import { type YearIsoIdType } from "./year-iso-id.vo";
-export declare const YearInvalidIntegerError: "year.invalid_integer";
-export declare const YearOutOfRangeError: "year.out_of_range";
 export declare class Year extends DateRange {
+    static fromTimestamp(timestamp: TimestampType): Year;
+    static fromNow(now: TimestampType): Year;
+    static fromNumber(candidate: number): Year;
+    static fromIsoId(isoId: YearIsoIdType): Year;
     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;
-    static fromIsoId(isoId: YearIsoIdType): Year;
+    toString(): string;
 }

package/dist/year.vo.js

@@ -2,45 +2,40 @@ 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";
-export const YearInvalidIntegerError = "year.invalid_integer";
-export const YearOutOfRangeError = "year.out_of_range";
 export class Year extends DateRange {
+    static fromTimestamp(timestamp) {
+        const start = Timestamp.parse(startOfYear(timestamp).getTime());
+        const end = Timestamp.parse(endOfYear(timestamp).getTime());
+        return new Year(start, end);
+    }
+    static fromNow(now) {
+        return Year.fromTimestamp(now);
+    }
+    static fromNumber(candidate) {
+        return Year.fromIsoId(YearIsoId.parse(String(candidate)));
+    }
+    static fromIsoId(isoId) {
+        const reference = Date.UTC(Number(isoId));
+        return Year.fromTimestamp(Timestamp.parse(reference));
+    }
     toIsoId() {
-        return String(getYear(this.getStart()));
+        return YearIsoId.parse(String(getYear(this.getStart())));
     }
     isLeapYear() {
         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));
+        return this.shift(-1);
     }
     next() {
-        const shifted = addYears(new Date(this.getStart()), 1).getTime();
-        return Year.fromTimestamp(Timestamp.parse(shifted));
+        return this.shift(1);
     }
     shift(count) {
-        const shifted = addYears(new Date(this.getStart()), count).getTime();
+        const shifted = addYears(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());
-        return new Year(start, end);
-    }
-    static fromNow(now) {
-        return Year.fromTimestamp(now);
-    }
-    static fromNumber(value) {
-        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);
-    }
-    static fromIsoId(isoId) {
-        return Year.fromNumber(Number(YearIsoId.parse(isoId)));
+    toString() {
+        return this.toIsoId();
     }
 }

package/dist/z-score.service.d.ts

@@ -1,5 +1,7 @@
 import type { RoundingPort } from "./rounding.port";
-export declare const ZScoreMinValuesError: "zscore.min.values";
+export declare const ZScoreError: {
+    readonly NotEnoughValues: "z.score.not.enough.values";
+};
 export declare class ZScore {
     private readonly rounding;
     private readonly mean;

package/dist/z-score.service.js

@@ -1,7 +1,7 @@
 import { Mean } from "./mean.service";
 import { PopulationStandardDeviation } from "./population-standard-deviation.service";
 import { RoundToDecimal } from "./rounding.adapter";
-export const ZScoreMinValuesError = "zscore.min.values";
+export const ZScoreError = { NotEnoughValues: "z.score.not.enough.values" };
 export class ZScore {
     rounding;
     mean;
@@ -9,7 +9,7 @@ export class ZScore {
     constructor(values, rounding = new RoundToDecimal(2)) {
         this.rounding = rounding;
         if (values.length < 2)
-            throw new Error(ZScoreMinValuesError);
+            throw new Error(ZScoreError.NotEnoughValues);
         this.mean = Mean.calculate(values);
         this.standardDeviation = PopulationStandardDeviation.calculate(values);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bgord/tools",
-  "version": "0.17.2",
+  "version": "1.0.0",
   "type": "module",
   "license": "MIT",
   "author": "Bartosz Gordon",
@@ -21,13 +21,13 @@
     "preinstall": "bunx only-allow bun"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.2.5",
+    "@biomejs/biome": "2.2.6",
     "@commitlint/cli": "20.1.0",
     "@commitlint/config-conventional": "20.0.0",
-    "@types/bun": "1.2.23",
+    "@types/bun": "1.3.0",
     "@types/mime-types": "3.0.1",
     "cspell": "9.2.1",
-    "knip": "5.64.2",
+    "knip": "5.65.0",
     "lefthook": "1.13.6",
     "only-allow": "1.2.1",
     "shellcheck": "4.1.0",

package/readme.md

@@ -24,6 +24,7 @@ Run the tests
 
 ```
 src/
+├── age-years.vo.ts
 ├── age.vo.ts
 ├── api-key.vo.ts
 ├── basename.vo.ts
@@ -36,11 +37,14 @@ src/
 ├── day.vo.ts
 ├── directory-path-absolute.vo.ts
 ├── directory-path-relative.vo.ts
+├── division-factor.vo.ts
 ├── dll.service.ts
+├── duration-ms.vo.ts
 ├── duration.service.ts
 ├── email-mask.service.ts
 ├── etags.vo.ts
 ├── extension.vo.ts
+├── feature-flag-value.vo.ts
 ├── feature-flag.vo.ts
 ├── file-path-absolute-schema.vo.ts
 ├── file-path-relative-schema.vo.ts
@@ -48,26 +52,38 @@ src/
 ├── filename-from-string.vo.ts
 ├── filename-suffix.vo.ts
 ├── filename.vo.ts
+├── height-milimiters.vo.ts
 ├── height.vo.ts
 ├── hour-format.service.ts
+├── hour-schema.vo.ts
 ├── hour.vo.ts
 ├── iban-mask.service.ts
+├── iban-schema.vo.ts
 ├── iban.vo.ts
 ├── image.vo.ts
 ├── language.vo.ts
+├── linear-regression.service.ts
 ├── mean.service.ts
 ├── mime-types.vo.ts
+├── mime-value.vo.ts
 ├── mime.vo.ts
 ├── min-max-scaler.service.ts
+├── minute-schema.vo.ts
 ├── minute.vo.ts
+├── money-amount.vo.ts
 ├── money.vo.ts
 ├── month-iso-id.vo.ts
 ├── month.vo.ts
+├── multiplication-factor.vo.ts
 ├── noop.service.ts
 ├── notification-template.vo.ts
 ├── object-key.vo.ts
 ├── outlier-detector.service.ts
+├── package-version-schema.vo.ts
 ├── package-version.vo.ts
+├── pagination-page.vo.ts
+├── pagination-skip.vo.ts
+├── pagination-take.vo.ts
 ├── pagination.service.ts
 ├── percentage.service.ts
 ├── population-standard-deviation.service.ts
@@ -76,17 +92,19 @@ src/
 ├── random.service.ts
 ├── rate-limiter.service.ts
 ├── relative-date.vo.ts
+├── reordering-item-position-value.vo.ts
 ├── reordering.service.ts
+├── revision-value.vo.ts
 ├── revision.vo.ts
 ├── rounding.adapter.ts
 ├── rounding.port.ts
-├── simple-linear-regression.service.ts
+├── size-bytes.vo.ts
 ├── size.vo.ts
 ├── stopwatch.service.ts
-├── streak-calculator.service.ts
 ├── sum.service.ts
 ├── thousands-separator.service.ts
 ├── time-zone-offset-value.vo.ts
+├── time.service.ts
 ├── timestamp.vo.ts
 ├── timezone.vo.ts
 ├── ts-utils.ts
@@ -94,6 +112,7 @@ src/
 ├── week-iso-id.vo.ts
 ├── week.vo.ts
 ├── weekday.vo.ts
+├── weight-grams.vo.ts
 ├── weight.vo.ts
 ├── year-iso-id.vo.ts
 ├── year.vo.ts

package/src/age-years.vo.ts

@@ -0,0 +1,14 @@
+import { z } from "zod/v4";
+
+export const AgeYearsError = { Type: "age.years.type", Invalid: "age.years.invalid" } as const;
+
+export const AgeYearsConstraints = { min: 1, max: 130 };
+
+export const AgeYears = z
+  .number(AgeYearsError.Type)
+  .int(AgeYearsError.Type)
+  .min(1, AgeYearsError.Invalid)
+  .max(130, AgeYearsError.Invalid)
+  .brand("AgeYears");
+
+export type AgeYearsType = z.infer<typeof AgeYears>;