@bgord/tools 0.17.2 → 1.0.1

package/src/image.vo.ts

@@ -1,22 +1,24 @@
 import { z } from "zod/v4";
 
-export const ImageWidthError = { error: "invalid.image.width" } as const;
-export const ImageHeightError = { error: "invalid.image.height" } as const;
+export const ImageWidthError = { Type: "image.width.type", Length: "image.width.length" } as const;
+export const ImageHeightError = { Type: "image.height.type", Length: "image.height.length" } as const;
+
+const IMAGE_DIMENSIONS_CONSTRAINTS = { min: 1, max: 10_000 };
 
 export const ImageWidth = z
-  .number(ImageWidthError)
-  .int(ImageWidthError)
-  .positive(ImageWidthError)
-  .max(10_000, ImageWidthError)
-  .brand("image-width");
+  .number(ImageWidthError.Type)
+  .int(ImageWidthError.Type)
+  .min(IMAGE_DIMENSIONS_CONSTRAINTS.min, ImageWidthError.Length)
+  .max(IMAGE_DIMENSIONS_CONSTRAINTS.max, ImageWidthError.Length)
+  .brand("ImageWidth");
 
 export type ImageWidthType = z.infer<typeof ImageWidth>;
 
 export const ImageHeight = z
-  .number(ImageHeightError)
-  .int(ImageHeightError)
-  .positive(ImageHeightError)
-  .max(10_000, ImageHeightError)
-  .brand("image-height");
+  .number(ImageHeightError.Type)
+  .int(ImageHeightError.Type)
+  .min(IMAGE_DIMENSIONS_CONSTRAINTS.min, ImageHeightError.Length)
+  .max(IMAGE_DIMENSIONS_CONSTRAINTS.max, ImageHeightError.Length)
+  .brand("ImageHeight");
 
 export type ImageHeightType = z.infer<typeof ImageHeight>;

package/src/index.ts

@@ -1,7 +1,9 @@
 export * from "./age.vo";
+export * from "./age-years.vo";
 export * from "./api-key.vo";
 export * from "./basename.vo";
 export * from "./clock.vo";
+export * from "./clock-format.service";
 export * from "./date-calculator.service";
 export * from "./date-formatter.service";
 export * from "./date-range.vo";
@@ -9,12 +11,15 @@ export * from "./day.vo";
 export * from "./day-iso-id.vo";
 export * from "./directory-path-absolute.vo";
 export * from "./directory-path-relative.vo";
+export * from "./division-factor.vo";
 export * from "./dll.service";
 export * from "./duration.service";
+export * from "./duration-ms.vo";
 export * from "./email-mask.service";
 export * from "./etags.vo";
 export * from "./extension.vo";
 export * from "./feature-flag.vo";
+export * from "./feature-flag-value.vo";
 export * from "./file-path.vo";
 export * from "./file-path-absolute-schema.vo";
 export * from "./file-path-relative-schema.vo";
@@ -22,25 +27,39 @@ export * from "./filename.vo";
 export * from "./filename-from-string.vo";
 export * from "./filename-suffix.vo";
 export * from "./height.vo";
+export * from "./height-milimiters.vo";
 export * from "./hour.vo";
+export * from "./hour-format.service";
+export * from "./hour-schema.vo";
 export * from "./iban.vo";
 export * from "./iban-mask.service";
+export * from "./iban-schema.vo";
 export * from "./image.vo";
+export * from "./index";
 export * from "./language.vo";
+export * from "./linear-regression.service";
 export * from "./mean.service";
 export * from "./mime.vo";
 export * from "./mime-types.vo";
+export * from "./mime-value.vo";
 export * from "./min-max-scaler.service";
 export * from "./minute.vo";
+export * from "./minute-schema.vo";
 export * from "./money.vo";
+export * from "./money-amount.vo";
 export * from "./month.vo";
 export * from "./month-iso-id.vo";
+export * from "./multiplication-factor.vo";
 export * from "./noop.service";
 export * from "./notification-template.vo";
 export * from "./object-key.vo";
 export * from "./outlier-detector.service";
 export * from "./package-version.vo";
+export * from "./package-version-schema.vo";
 export * from "./pagination.service";
+export * from "./pagination-page.vo";
+export * from "./pagination-skip.vo";
+export * from "./pagination-take.vo";
 export * from "./percentage.service";
 export * from "./population-standard-deviation.service";
 export * from "./quarter.vo";
@@ -49,15 +68,17 @@ export * from "./random.service";
 export * from "./rate-limiter.service";
 export * from "./relative-date.vo";
 export * from "./reordering.service";
+export * from "./reordering-item-position-value.vo";
 export * from "./revision.vo";
+export * from "./revision-value.vo";
 export * from "./rounding.adapter";
 export * from "./rounding.port";
-export * from "./simple-linear-regression.service";
 export * from "./size.vo";
+export * from "./size-bytes.vo";
 export * from "./stopwatch.service";
-export * from "./streak-calculator.service";
 export * from "./sum.service";
 export * from "./thousands-separator.service";
+export * from "./time.service";
 export * from "./time-zone-offset-value.vo";
 export * from "./timestamp.vo";
 export * from "./timezone.vo";
@@ -67,6 +88,7 @@ export * from "./week.vo";
 export * from "./week-iso-id.vo";
 export * from "./weekday.vo";
 export * from "./weight.vo";
+export * from "./weight-grams.vo";
 export * from "./year.vo";
 export * from "./year-iso-id.vo";
 export * from "./z-score.service";

package/src/language.vo.ts

@@ -1,10 +1,13 @@
 import { z } from "zod/v4";
 
-export const LanguageError = { error: "invalid.language" } as const;
+export const LanguageError = { Type: "language.type", BadChars: "language.bad.chars" } as const;
+
+// Two lowercase letters
+const LANGUAGE_CHARS_WHITELIST = /^[a-z]{2}$/;
 
 export const Language = z
-  .string(LanguageError)
-  .length(2, LanguageError)
-  .regex(/^[a-z]{2}$/, LanguageError);
+  .string(LanguageError.Type)
+  .toLowerCase()
+  .regex(LANGUAGE_CHARS_WHITELIST, LanguageError.BadChars);
 
 export type LanguageType = z.infer<typeof Language>;

package/src/linear-regression.service.ts

@@ -0,0 +1,71 @@
+import { RoundToNearest } from "./rounding.adapter";
+import type { RoundingPort } from "./rounding.port";
+
+export type LinearRegressionPairType = { x: number; y: number };
+export type LinearRegressionParamsType = { a: number; b: number };
+export type LinearRegressionPredictionType = number;
+
+export const LinearRegressionError = {
+  MinPairs: "linear.regression.min.pairs",
+  SumXTooBig: "linear.regression.sum.x.too.big",
+  SumYTooBig: "linear.regression.sum.y.too.big",
+  SumXSquaredTooBig: "linear.regression.sum.x.squared.too.big",
+  SumXTimesYTooBig: "linear.regression.sum.x.times.y.too.big",
+  ModelCreation: "linear.regression.model.creation",
+} as const;
+
+export class LinearRegression {
+  private static readonly DEFAULT_ROUNDING: RoundingPort = new RoundToNearest();
+
+  private readonly params: LinearRegressionParamsType;
+  private readonly rounding: RoundingPort;
+
+  constructor(params: LinearRegressionParamsType, rounding?: RoundingPort) {
+    this.params = params;
+    this.rounding = rounding ?? LinearRegression.DEFAULT_ROUNDING;
+  }
+
+  static fromPairs(pairs: LinearRegressionPairType[], rounding?: RoundingPort): LinearRegression {
+    const count = pairs.length;
+
+    if (count < 2) throw new Error(LinearRegressionError.MinPairs);
+
+    let sumX = 0;
+    let sumY = 0;
+    let sumXX = 0;
+    let sumXY = 0;
+
+    for (let index = 0; index < count; index++) {
+      const pair = pairs[index];
+      sumX += pair.x;
+      sumY += pair.y;
+      sumXX += pair.x * pair.x;
+      sumXY += pair.x * pair.y;
+    }
+
+    if (Math.abs(sumX) >= Number.MAX_SAFE_INTEGER) throw new Error(LinearRegressionError.SumXTooBig);
+    if (Math.abs(sumY) >= Number.MAX_SAFE_INTEGER) throw new Error(LinearRegressionError.SumYTooBig);
+    if (Math.abs(sumXY) >= Number.MAX_SAFE_INTEGER) throw new Error(LinearRegressionError.SumXTimesYTooBig);
+    if (Math.abs(sumXX) >= Number.MAX_SAFE_INTEGER) throw new Error(LinearRegressionError.SumXSquaredTooBig);
+
+    const bDenominator = sumXX - sumX ** 2 / count;
+
+    if (bDenominator === 0) throw new Error(LinearRegressionError.ModelCreation);
+
+    const b = (sumXY - (sumX * sumY) / count) / bDenominator;
+    const a = (sumY - b * sumX) / count;
+
+    return new LinearRegression({ a, b }, rounding);
+  }
+
+  predict(x: LinearRegressionPairType["x"], rounding?: RoundingPort): LinearRegressionPredictionType {
+    const chosen = rounding ?? this.rounding;
+    const prediction = this.params.b * x + this.params.a;
+
+    return chosen.round(prediction);
+  }
+
+  inspect(): LinearRegression["params"] {
+    return this.params;
+  }
+}

package/src/mean.service.ts

@@ -2,19 +2,17 @@ import { RoundToDecimal } from "./rounding.adapter";
 import type { RoundingPort } from "./rounding.port";
 import { Sum } from "./sum.service";
 
-export const MeanEmptyValuesError = "mean.values.empty" as const;
+export const MeanError = { NotEnoughValues: "mean.not.enough.values" } as const;
 
 export class Mean {
   private static readonly DEFAULT_ROUNDING: RoundingPort = new RoundToDecimal(2);
 
   static calculate(values: number[], rounding?: RoundingPort): number {
-    if (values.length === 0) throw new Error(MeanEmptyValuesError);
+    if (values.length === 0) throw new Error(MeanError.NotEnoughValues);
 
     const sum = Sum.of(values);
     const mean = sum / values.length;
 
-    const chosen = rounding ?? Mean.DEFAULT_ROUNDING;
-
-    return chosen.round(mean);
+    return (rounding ?? Mean.DEFAULT_ROUNDING).round(mean);
   }
 }

package/src/mime-types.vo.ts

@@ -1,6 +1,4 @@
-import type { MimeRawType } from "./mime.vo";
-
-export const MIME_TYPES: Record<string, MimeRawType[]> = {
+export const MIME_TYPES: Record<string, string[]> = {
   wildcard: ["*/*"],
   jpeg: ["image/jpeg"],
   png: ["image/png"],

package/src/mime-value.vo.ts

@@ -0,0 +1,12 @@
+import { z } from "zod/v4";
+
+export const MimeValueError = { Type: "mime.value.type", Invalid: "mime.value.invalid" };
+
+// One to twenty four lowercase letters, asterisk or hyphen, forward slash, one to twenty four lowercase letters, asterisk or hyphen
+const MIME_VALUE_CHARS_WHITELIST = /^[a-z*-]{1,24}\/[a-z*-]{1,24}$/;
+
+export const MimeValue = z
+  .string(MimeValueError.Type)
+  .regex(MIME_VALUE_CHARS_WHITELIST, MimeValueError.Invalid)
+  .transform((value) => ({ type: value.split("/")[0], subtype: value.split("/")[1] }))
+  .brand("MimeValue");

package/src/mime.vo.ts

@@ -1,25 +1,16 @@
 import * as mime from "mime-types";
 import { Extension, type ExtensionType } from "./extension.vo";
+import { MimeValue } from "./mime-value.vo";
 
-export type MimeRawType = string;
-type MimeTypeType = string;
-type MimeSubtypeType = string;
-
-export const InvalidMimeErrorMessage = "invalid.mime" as const;
-export const NotAcceptedMimeErrorMessage = "mime.not.accepted" as const;
+export const MimeError = { NotAccepted: "mime.not.accepted" } as const;
 
 export class Mime {
-  readonly raw: MimeRawType;
-  readonly type: MimeTypeType;
-  readonly subtype: MimeSubtypeType;
-
-  constructor(value: MimeRawType) {
-    const [type, subtype] = value.split("/");
+  readonly type: string;
+  readonly subtype: string;
 
-    if (typeof type !== "string" || type.length === 0) throw new InvalidMimeError();
-    if (typeof subtype !== "string" || subtype.length === 0) throw new InvalidMimeError();
+  constructor(candidate: string) {
+    const { type, subtype } = MimeValue.parse(candidate);
 
-    this.raw = value;
     this.type = type;
     this.subtype = subtype;
   }
@@ -29,32 +20,20 @@ export class Mime {
   }
 
   isSatisfiedBy(another: Mime): boolean {
-    if (this.raw === another.raw) return true;
-
-    const typeMatches = this.type === another.type || this.type === "*";
-
-    if (!typeMatches) return false;
+    if (!(this.type === another.type || this.type === "*")) return false;
     return this.subtype === another.subtype || this.subtype === "*";
   }
 
   toExtension(): ExtensionType {
-    return Extension.parse(mime.extension(this.raw));
+    return Extension.parse(mime.extension(this.toString()));
   }
-}
 
-export class InvalidMimeError extends Error {
-  constructor() {
-    super(InvalidMimeErrorMessage);
-    Object.setPrototypeOf(this, InvalidMimeError.prototype);
+  toString(): string {
+    return `${this.type}/${this.subtype}`;
   }
-}
 
-export class NotAcceptedMimeError extends Error {
-  mime: MimeRawType;
-  constructor(mimeValue: MimeRawType) {
-    super(NotAcceptedMimeErrorMessage);
-    Object.setPrototypeOf(this, NotAcceptedMimeError.prototype);
-    this.mime = mimeValue;
+  toJSON(): { type: string; subtype: string } {
+    return { type: this.type, subtype: this.subtype };
   }
 }
 

package/src/min-max-scaler.service.ts

@@ -10,12 +10,6 @@ type MinMaxScalerConfigType = {
   rounding?: RoundingPort;
 };
 
-export const MinMaxInvalidMinMaxError = "minmax.invalid.minmax" as const;
-export const MinMaxInvalidBoundError = "minmax.invalid.bound" as const;
-export const MinMaxValueOutOfRangeError = "minmax.value.out.of.range" as const;
-export const MinMaxScaledOutOfBoundsError = "minmax.scaled.out.of.bounds" as const;
-export const MinMaxEmptyArrayError = "minmax.empty.array" as const;
-
 type ScaleResult = {
   original: MinMaxScalerValueType;
   scaled: MinMaxScalerValueType;
@@ -30,6 +24,14 @@ type DescaleResult = {
   isUpperBound: boolean;
 };
 
+export const MinMaxScalerError = {
+  InvalidMinMax: "min.max.scaler.invalid.min.max",
+  InvalidBound: "min.max.scaler.invalid.bound",
+  ValueOutOfRange: "min.max.scaler.value.out.of.range",
+  ScaledOutOfBounds: "min.max.scaler.scaled.out.of.bounds",
+  EmptyArray: "min.max.scaler.empty.array",
+} as const;
+
 export class MinMaxScaler {
   private static readonly DEFAULT_ROUNDING: RoundingPort = new RoundToDecimal(2);
 
@@ -43,8 +45,8 @@ export class MinMaxScaler {
     const lower = config.bound?.lower ?? 0;
     const upper = config.bound?.upper ?? 1;
 
-    if (config.max - config.min < 0) throw new Error(MinMaxInvalidMinMaxError);
-    if (upper - lower <= 0) throw new Error(MinMaxInvalidBoundError);
+    if (config.max - config.min < 0) throw new Error(MinMaxScalerError.InvalidMinMax);
+    if (upper - lower <= 0) throw new Error(MinMaxScalerError.InvalidBound);
 
     this.rounding = config.rounding ?? MinMaxScaler.DEFAULT_ROUNDING;
     this.min = config.min;
@@ -56,7 +58,7 @@ export class MinMaxScaler {
   scale(value: MinMaxScalerValueType): ScaleResult {
     const { min, max, lower, upper } = this;
 
-    if (value < min || value > max) throw new Error(MinMaxValueOutOfRangeError);
+    if (value < min || value > max) throw new Error(MinMaxScalerError.ValueOutOfRange);
 
     if (min === max) {
       return { original: value, scaled: (lower + upper) / 2, isMin: value === min, isMax: value === max };
@@ -75,7 +77,7 @@ export class MinMaxScaler {
   descale(scaled: MinMaxScalerValueType): DescaleResult {
     const { min, max, lower, upper } = this;
 
-    if (scaled < lower || scaled > upper) throw new Error(MinMaxScaledOutOfBoundsError);
+    if (scaled < lower || scaled > upper) throw new Error(MinMaxScalerError.ScaledOutOfBounds);
 
     const result = ((scaled - lower) / (upper - lower)) * (max - min) + min;
 
@@ -88,7 +90,7 @@ export class MinMaxScaler {
   }
 
   static getMinMax(values: MinMaxScalerValueType[]): { min: number; max: number } {
-    if (values.length === 0) throw new Error(MinMaxEmptyArrayError);
+    if (values.length === 0) throw new Error(MinMaxScalerError.EmptyArray);
     return { min: Math.min(...values), max: Math.max(...values) };
   }
 }

package/src/minute-schema.vo.ts

@@ -0,0 +1,12 @@
+import { z } from "zod/v4";
+
+export const MinuteSchemaError = { Type: "minute.schema.error", Invalid: "minute.schema.invalid" };
+
+export const MinuteSchema = z
+  .number(MinuteSchemaError.Type)
+  .int(MinuteSchemaError.Type)
+  .gte(0, MinuteSchemaError.Invalid)
+  .lte(59, MinuteSchemaError.Invalid)
+  .brand("MinuteSchema");
+
+export type MinuteSchemaType = z.infer<typeof MinuteSchema>;

package/src/minute.vo.ts

@@ -1,32 +1,24 @@
+import { MinuteSchema, type MinuteSchemaType } from "./minute-schema.vo";
 import type { TimestampType } from "./timestamp.vo";
 
-export const MinuteValueError = "invalid.minute" as const;
-
 export class Minute {
-  private readonly value: number;
+  private readonly value: MinuteSchemaType;
 
   static readonly ZERO = new Minute(0);
   static readonly MAX = new Minute(59);
 
   constructor(candidate: number) {
-    if (!Number.isInteger(candidate) || candidate < 0 || candidate >= 60) {
-      throw new Error(MinuteValueError);
-    }
-    this.value = candidate;
+    this.value = MinuteSchema.parse(candidate);
   }
 
   static fromEpochMs(timestamp: TimestampType): Minute {
     return new Minute(new Date(timestamp).getUTCMinutes());
   }
 
-  get(): number {
+  get(): MinuteSchemaType {
     return this.value;
   }
 
-  toString(): string {
-    return this.value.toString().padStart(2, "0");
-  }
-
   equals(another: Minute): boolean {
     return this.value === another.value;
   }
@@ -42,4 +34,12 @@ export class Minute {
   static list(): readonly Minute[] {
     return Array.from({ length: 60 }, (_, index) => new Minute(index));
   }
+
+  toString(): string {
+    return this.value.toString().padStart(2, "0");
+  }
+
+  toJSON(): number {
+    return this.value;
+  }
 }

package/src/money-amount.vo.ts

@@ -0,0 +1,11 @@
+import { z } from "zod/v4";
+
+export const MoneyAmountError = { Type: "money.amount.type", Invalid: "money.amount.invalid" };
+
+export const MoneyAmount = z
+  .number(MoneyAmountError.Type)
+  .int(MoneyAmountError.Type)
+  .min(0, MoneyAmountError.Invalid)
+  .brand("MoneyAmount");
+
+export type MoneyAmountType = z.infer<typeof MoneyAmount>;

package/src/money.vo.ts

@@ -1,35 +1,10 @@
-import { z } from "zod/v4";
-import { RoundToNearest } from "./rounding.adapter";
+import type { DivisionFactorType } from "./division-factor.vo";
+import { MoneyAmount, type MoneyAmountType } from "./money-amount.vo";
+import type { MultiplicationFactorType } from "./multiplication-factor.vo";
+import { RoundDown, RoundToNearest } from "./rounding.adapter";
 import type { RoundingPort } from "./rounding.port";
 
-export const MoneyAmountInvalidError = { error: "money.amount.invalid" } as const;
-export const MoneyMultiplicationFactorInvalidError = {
-  error: "money.multiplication-factor.invalid",
-} as const;
-export const MoneyDivisionFactorInvalidError = { error: "money.division-factor.invalid" } as const;
-export const MoneySubtractLessThanZeroError = "money.subtract.less.than.zero" as const;
-
-export const MoneyAmount = z
-  .number(MoneyAmountInvalidError)
-  .int(MoneyAmountInvalidError)
-  .min(0, MoneyAmountInvalidError)
-  .brand("MoneyAmount");
-
-export type MoneyAmountType = z.infer<typeof MoneyAmount>;
-
-export const MoneyMultiplicationFactor = z
-  .number(MoneyMultiplicationFactorInvalidError)
-  .min(0, MoneyMultiplicationFactorInvalidError)
-  .brand("MoneyMultiplicationFactor");
-
-export type MoneyMultiplicationFactorType = z.infer<typeof MoneyMultiplicationFactor>;
-
-export const MoneyDivisionFactor = z
-  .number(MoneyDivisionFactorInvalidError)
-  .gt(0, MoneyDivisionFactorInvalidError)
-  .brand("MoneyDivisionFactor");
-
-export type MoneyDivisionFactorType = z.infer<typeof MoneyDivisionFactor>;
+export const MoneyError = { SubtractResultLessThanZero: "money.subtract.result.less.than.zero" } as const;
 
 export class Money {
   private static readonly ZERO = 0;
@@ -48,25 +23,25 @@ export class Money {
   }
 
   add(money: Money): Money {
-    const result = this.rounding.round(this.amount + money.getAmount());
+    const result = this.amount + money.getAmount();
 
     return new Money(MoneyAmount.parse(result), this.rounding);
   }
 
-  multiply(factor: MoneyMultiplicationFactorType): Money {
+  multiply(factor: MultiplicationFactorType): Money {
     const result = this.rounding.round(this.amount * factor);
 
     return new Money(MoneyAmount.parse(result), this.rounding);
   }
 
   subtract(money: Money): Money {
-    const result = this.rounding.round(this.amount - money.getAmount());
+    const result = this.amount - money.getAmount();
 
-    if (result < Money.ZERO) throw new Error(MoneySubtractLessThanZeroError);
+    if (result < Money.ZERO) throw new Error(MoneyError.SubtractResultLessThanZero);
     return new Money(MoneyAmount.parse(result), this.rounding);
   }
 
-  divide(factor: MoneyDivisionFactorType): Money {
+  divide(factor: DivisionFactorType): Money {
     const result = this.rounding.round(this.amount / factor);
 
     return new Money(MoneyAmount.parse(result), this.rounding);
@@ -89,10 +64,17 @@ export class Money {
   }
 
   format(): string {
-    const whole = Math.floor(this.amount / 100);
+    const whole = new RoundDown().round(this.amount / 100);
     const fraction = this.amount % 100;
-    const fractionFormatted = fraction.toString().padStart(2, "0");
 
-    return `${whole}.${fractionFormatted}`;
+    return `${whole}.${fraction.toString().padStart(2, "0")}`;
+  }
+
+  toString(): string {
+    return this.format();
+  }
+
+  toJSON(): number {
+    return this.amount;
   }
 }

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

@@ -1,15 +1,22 @@
 import { z } from "zod/v4";
 
-export const MonthIsoIdError = { error: "month-iso-id.invalid" } as const;
+export const MonthIsoIdError = {
+  Type: "month.iso.id.type",
+  BadChars: "month.iso.id.bad.chars",
+  Invalid: "month.iso.id.invalid",
+} as const;
+
+// Four digits, hyphen, two digits
+const MONTH_ISO_ID_CHARS_WHITELIST = /^\d{4}-\d{2}$/;
 
 export const MonthIsoId = z
-  .string(MonthIsoIdError)
-  .regex(/^\d{4}-\d{2}$/, MonthIsoIdError)
+  .string(MonthIsoIdError.Type)
+  .regex(MONTH_ISO_ID_CHARS_WHITELIST, MonthIsoIdError.BadChars)
   .refine((value) => {
-    const year = Number(value.slice(0, 4));
-    const month = Number(value.slice(5, 7));
+    const month = value.split("-").map(Number)[1];
 
-    return Number.isInteger(year) && Number.isInteger(month) && month >= 1 && month <= 12;
-  }, MonthIsoIdError);
+    return month >= 1 && month <= 12;
+  }, MonthIsoIdError.Invalid)
+  .brand("MonthIsoId");
 
 export type MonthIsoIdType = z.infer<typeof MonthIsoId>;