@bgord/tools 0.5.0 → 0.7.0

package/src/filter.vo.ts

@@ -0,0 +1,38 @@
+import { z } from "zod/v4";
+
+export type DefaultFilterSchemaType = z.ZodRawShape;
+
+export type FilterValuesType = Record<string, unknown>;
+
+export type FilterSchemaType<T extends DefaultFilterSchemaType> = z.ZodObject<T>;
+
+export type FilterParseConfigType<T extends DefaultFilterSchemaType> = {
+  schema: FilterSchemaType<T>;
+  values: FilterValuesType;
+};
+
+export class Filter<T extends DefaultFilterSchemaType> {
+  constructor(private readonly schema: FilterSchemaType<T>) {}
+
+  parse(values: FilterValuesType) {
+    return Filter._parse({ schema: this.schema, values });
+  }
+
+  default() {
+    return this.parse({});
+  }
+
+  static parse<T extends DefaultFilterSchemaType>(config: FilterParseConfigType<T>) {
+    return Filter._parse(config);
+  }
+
+  static default<T extends DefaultFilterSchemaType>(config: Omit<FilterParseConfigType<T>, "values">) {
+    return Filter._parse({ schema: config.schema, values: {} });
+  }
+
+  private static _parse<T extends DefaultFilterSchemaType>(config: FilterParseConfigType<T>) {
+    const result = config.schema.safeParse(config.values);
+
+    return result.success ? result.data : undefined;
+  }
+}

package/src/hour.vo.ts

@@ -0,0 +1,71 @@
+export type HourFormatter = (value: Hour["value"]) => string;
+
+export enum HourFormatterEnum {
+  TWENTY_FOUR_HOURS = "TWENTY_FOUR_HOURS",
+  TWENTY_FOUR_HOURS_WO_PADDING = "TWENTY_FOUR_HOURS_WO_PADDING",
+  AM_PM = "AM_PM",
+  TWELVE_HOURS = "TWELVE_HOURS",
+  TWELVE_HOURS_WO_PADDING = "TWELVE_HOURS_WO_PADDING",
+}
+
+export const HourFormatters: Record<HourFormatterEnum, HourFormatter> = {
+  TWENTY_FOUR_HOURS: (value) => value.toString().padStart(2, "0"),
+
+  TWENTY_FOUR_HOURS_WO_PADDING: (value) => value.toString(),
+
+  AM_PM: (value) => {
+    if (value < 12) return `${value.toString()} a.m.`;
+    return `${value.toString()} p.m.`;
+  },
+
+  TWELVE_HOURS: (value) => (value % 12).toString().padStart(2, "0"),
+
+  TWELVE_HOURS_WO_PADDING: (value) => (value % 12).toString(),
+} as const;
+
+export class Hour {
+  private readonly value: number;
+
+  private readonly formatter: HourFormatter;
+
+  static readonly ZERO = new Hour(0);
+
+  static readonly MAX = new Hour(23);
+
+  constructor(candidate: number, formatter?: HourFormatter) {
+    if (!Number.isInteger(candidate)) {
+      throw new Error("Invalid hour");
+    }
+    if (candidate < 0) {
+      throw new Error("Invalid hour");
+    }
+    if (candidate >= 24) {
+      throw new Error("Invalid hour");
+    }
+
+    this.value = candidate;
+    this.formatter = (formatter as HourFormatter) ?? HourFormatters.TWENTY_FOUR_HOURS;
+  }
+
+  get(formatter?: HourFormatter) {
+    const format = formatter ?? this.formatter;
+
+    return { raw: this.value, formatted: format(this.value) };
+  }
+
+  equals(another: Hour): boolean {
+    return this.value === another.get().raw;
+  }
+
+  isAfter(another: Hour): boolean {
+    return this.value > another.get().raw;
+  }
+
+  isBefore(another: Hour): boolean {
+    return this.value < another.get().raw;
+  }
+
+  static list(formatter?: HourFormatter) {
+    return Array.from({ length: 24 }).map((_, index) => new Hour(index, formatter));
+  }
+}

package/src/image.vo.ts

@@ -0,0 +1,9 @@
+import { z } from "zod/v4";
+
+export const Width = z.number().int().positive().max(10000);
+
+export type WidthType = z.infer<typeof Width>;
+
+export const Height = z.number().int().positive().max(10000);
+
+export type HeightType = z.infer<typeof Height>;

package/src/index.ts

@@ -1,21 +1,48 @@
 export * from "./api-key.vo";
 export * from "./build-version.vo";
+export * from "./clock.vo";
 export * from "./date-calculator.service";
 export * from "./date-formatter.service";
 export * from "./dates-of-the-week.vo";
+export * from "./dll.service";
+export * from "./email-mask.service";
 export * from "./etags.vo";
+export * from "./feature-flag.vo";
+export * from "./filter.vo";
+export * from "./hour.vo";
+export * from "./image.vo";
 export * from "./language.vo";
+export * from "./leap-year-checker.service";
+export * from "./mean.service";
+export * from "./mime-types.vo";
 export * from "./mime.vo";
+export * from "./min-max-scaler.service";
+export * from "./minute.vo";
+export * from "./money.vo";
 export * from "./noop.service";
+export * from "./outlier-detector.service";
 export * from "./package-version.vo";
+export * from "./pagination.service";
+export * from "./percentage.service";
+export * from "./population-standard-deviation.service";
+export * from "./random.service";
 export * from "./rate-limiter.service";
 export * from "./relative-date.vo";
+export * from "./reordering.service";
+export * from "./revision.vo";
 export * from "./rounding.service";
+export * from "./simple-linear-regression.service";
 export * from "./size.vo";
 export * from "./sleep.service";
+export * from "./stepper.service";
 export * from "./stopwatch.service";
+export * from "./streak-calculator.service";
+export * from "./sum.service";
+export * from "./thousands-separator.service";
 export * from "./time-zone-offset-value.vo";
 export * from "./time.service";
 export * from "./timestamp.vo";
 export * from "./timezone.vo";
 export * from "./ts-utils";
+export * from "./visually-unambiguous-characters-generator.service";
+export * from "./z-score.service";

package/src/leap-year-checker.service.ts

@@ -0,0 +1,11 @@
+export class LeapYearChecker {
+  static isLeapYear(year: number): boolean {
+    return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+  }
+
+  static isCurrentYearLeapYear(): boolean {
+    const year = new Date().getFullYear();
+
+    return LeapYearChecker.isLeapYear(year);
+  }
+}

package/src/mean.service.ts

@@ -0,0 +1,14 @@
+import { RoundToDecimal, RoundingStrategy } from "./rounding.service";
+import { Sum } from "./sum.service";
+
+export class Mean {
+  static calculate(values: number[], rounding: RoundingStrategy = new RoundToDecimal(2)): number {
+    if (values.length === 0) {
+      throw new Error("Values should not be empty");
+    }
+
+    const mean = Sum.of(values) / values.length;
+
+    return rounding.round(mean);
+  }
+}

package/src/mime-types.vo.ts

@@ -0,0 +1,9 @@
+import type { MimeRawType } from "./mime.vo";
+
+export const MIME_TYPES: Record<string, MimeRawType[]> = {
+  wildcard: ["*/*"],
+  jpeg: ["image/jpeg"],
+  png: ["image/png"],
+  wav: ["audio/x-wav", "audio/wav"],
+  mp4: ["video/mp4"],
+};

package/src/mime.vo.ts

@@ -1,5 +1,7 @@
-type MimeRawType = string;
+export type MimeRawType = string;
+
 type MimeTypeType = string;
+
 type MimeSubtypeType = string;
 
 export class Mime {

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

@@ -0,0 +1,94 @@
+import { RoundToDecimal, RoundingStrategy } from "./rounding.service";
+
+type MinMaxScalerValueType = number;
+
+type MinMaxScalerConfigType = {
+  min: MinMaxScalerValueType;
+  max: MinMaxScalerValueType;
+  bound?: {
+    lower: MinMaxScalerValueType;
+    upper: MinMaxScalerValueType;
+  };
+  rounding?: RoundingStrategy;
+};
+
+export class MinMaxScaler {
+  private readonly min: MinMaxScalerValueType;
+  private readonly max: MinMaxScalerValueType;
+  private readonly lower: MinMaxScalerValueType;
+  private readonly upper: MinMaxScalerValueType;
+
+  private readonly rounding: RoundingStrategy;
+
+  constructor(config: MinMaxScalerConfigType) {
+    const rounding = config.rounding ?? new RoundToDecimal(2);
+
+    const lower = config.bound?.lower ?? 0;
+    const upper = config.bound?.upper ?? 1;
+
+    if (config.max - config.min < 0) {
+      throw new Error("Invalid MinMaxScaler min-max config");
+    }
+
+    if (upper - lower <= 0) {
+      throw new Error("Invalid MinMaxScaler bound config");
+    }
+
+    this.rounding = rounding;
+
+    this.min = config.min;
+    this.max = config.max;
+    this.lower = lower;
+    this.upper = upper;
+  }
+
+  scale(value: MinMaxScalerValueType) {
+    const { min, max, lower, upper } = this;
+
+    if (value < min || value > max) {
+      throw new Error("Value out of min/max range");
+    }
+
+    if (min === max)
+      return {
+        original: value,
+        scaled: (lower + upper) / 2,
+        isMin: value === min,
+        isMax: value === max,
+      };
+
+    const result = ((value - min) / (max - min)) * (upper - lower) + lower;
+
+    return {
+      original: value,
+      scaled: this.rounding.round(result),
+      isMin: value === min,
+      isMax: value === max,
+    };
+  }
+
+  descale(scaled: MinMaxScalerValueType) {
+    const { min, max, lower, upper } = this;
+
+    if (scaled < lower || scaled > upper) {
+      throw new Error("Scaled value out of bounds");
+    }
+
+    const result = ((scaled - lower) / (upper - lower)) * (max - min) + min;
+
+    return {
+      original: this.rounding.round(result),
+      scaled,
+      isLowerBound: scaled === lower,
+      isUpperBound: scaled === upper,
+    };
+  }
+
+  static getMinMax(values: MinMaxScalerValueType[]) {
+    if (values.length === 0) {
+      throw new Error("An empty array supplied");
+    }
+
+    return { min: Math.min(...values), max: Math.max(...values) };
+  }
+}

package/src/minute.vo.ts

@@ -0,0 +1,46 @@
+export class Minute {
+  private readonly value: number;
+
+  static readonly ZERO = new Minute(0);
+
+  static readonly MAX = new Minute(59);
+
+  constructor(candidate: number) {
+    if (!Number.isInteger(candidate)) {
+      throw new Error("Invalid minute");
+    }
+
+    if (candidate < 0) {
+      throw new Error("Invalid minute");
+    }
+
+    if (candidate >= 60) {
+      throw new Error("Invalid minute");
+    }
+
+    this.value = candidate;
+  }
+
+  get() {
+    return {
+      raw: this.value,
+      formatted: this.value.toString().padStart(2, "0"),
+    };
+  }
+
+  equals(another: Minute): boolean {
+    return this.value === another.get().raw;
+  }
+
+  isAfter(another: Minute): boolean {
+    return this.value > another.get().raw;
+  }
+
+  isBefore(another: Minute): boolean {
+    return this.value < another.get().raw;
+  }
+
+  static list() {
+    return Array.from({ length: 60 }).map((_, index) => new Minute(index));
+  }
+}

package/src/money.vo.ts

@@ -0,0 +1,99 @@
+import { z } from "zod/v4";
+
+import { RoundToNearest, RoundingStrategy } from "./rounding.service";
+
+export const MoneyAmount = z
+  .number()
+  .int({ message: "money.amount.invalid " })
+  .min(0, { message: "money.amount.invalid " });
+
+export type MoneyAmountType = z.infer<typeof MoneyAmount>;
+
+export const MoneyMultiplicationFactor = z
+  .number()
+  .min(0, { message: "money.multiplication-factor.invalid" });
+
+export type MoneyMultiplicationFactorType = z.infer<typeof MoneyMultiplicationFactor>;
+
+export const MoneyDivisionFactor = z
+  .number()
+  .min(0, { message: "money.division-factor.invalid" })
+  .refine((value) => value !== 0, { message: "money.division-factor.invalid" });
+
+export type MoneyDivisionFactorType = z.infer<typeof MoneyDivisionFactor>;
+
+export class Money {
+  private static readonly ZERO = 0;
+
+  private readonly amount: MoneyAmountType;
+
+  private readonly rounding: RoundingStrategy;
+
+  constructor(value: number = Money.ZERO, rounding?: RoundingStrategy) {
+    this.amount = MoneyAmount.parse(value);
+    this.rounding = rounding ?? new RoundToNearest();
+  }
+
+  getAmount(): MoneyAmountType {
+    return this.amount;
+  }
+
+  add(money: Money) {
+    const result = this.rounding.round(this.amount + money.getAmount());
+
+    return new Money(MoneyAmount.parse(result), this.rounding);
+  }
+
+  multiply(factor: MoneyMultiplicationFactorType) {
+    const result = this.rounding.round(this.amount * factor);
+
+    return new Money(MoneyAmount.parse(result), this.rounding);
+  }
+
+  subtract(money: Money) {
+    const result = this.rounding.round(this.amount - money.getAmount());
+
+    if (result < Money.ZERO) {
+      throw new Error("Less than zero");
+    }
+
+    return new Money(MoneyAmount.parse(result), this.rounding);
+  }
+
+  divide(factor: MoneyDivisionFactorType) {
+    if (factor === 0) {
+      throw new Error("Cannot divide by zero");
+    }
+
+    const result = this.rounding.round(this.amount / factor);
+
+    return new Money(MoneyAmount.parse(result), this.rounding);
+  }
+
+  equals(another: Money): boolean {
+    return this.amount === another.getAmount();
+  }
+
+  isGreaterThan(another: Money): boolean {
+    return this.amount > another.getAmount();
+  }
+
+  isLessThan(another: Money): boolean {
+    return this.amount < another.getAmount();
+  }
+
+  isZero(): boolean {
+    return this.amount === Money.ZERO;
+  }
+
+  format(): string {
+    const result = this.amount / 100;
+
+    const whole = Math.floor(result);
+
+    const fraction = this.amount % 100;
+    const fractionFormatted = fraction.toString().padStart(2, "0");
+
+    return `${whole}.${fractionFormatted}`;
+  }
+}

package/src/outlier-detector.service.ts

@@ -0,0 +1,20 @@
+import { ZScore } from "./z-score.service";
+
+export class OutlierDetector {
+  private readonly zScore: ZScore;
+
+  private readonly threshold: number;
+
+  constructor(values: number[], threshold: number) {
+    if (values.length < 2) {
+      throw new Error("At least two values are needed");
+    }
+
+    this.zScore = new ZScore(values);
+    this.threshold = Math.abs(threshold);
+  }
+
+  check(value: number): boolean {
+    return this.zScore.calculate(value) <= this.threshold;
+  }
+}

package/src/package-version.vo.ts

@@ -1,10 +1,12 @@
 import { z } from "zod/v4";
 
 type MajorType = number;
+
 type MinorType = number;
+
 type PatchType = number;
 
-export const PackageVersionSchema = z
+export const PackageVersionValue = z
   .string()
   .min(1)
   .refine(
@@ -56,7 +58,7 @@ export const PackageVersionSchema = z
       patch: Number(patch),
     };
   });
-export type PackageVersionSchemaType = z.infer<typeof PackageVersionSchema>;
+export type PackageVersionValueType = z.infer<typeof PackageVersionValue>;
 
 export class PackageVersion {
   constructor(
@@ -79,13 +81,13 @@ export class PackageVersion {
   }
 
   static fromStringWithV(value: string) {
-    const version = PackageVersionSchema.parse(value);
+    const version = PackageVersionValue.parse(value);
 
     return new PackageVersion(version.major, version.minor, version.patch);
   }
 
   static fromString(value: string) {
-    const version = PackageVersionSchema.parse(`v${value}`);
+    const version = PackageVersionValue.parse(`v${value}`);
 
     return new PackageVersion(version.major, version.minor, version.patch);
   }

package/src/pagination.service.ts

@@ -0,0 +1,111 @@
+import { z } from "zod/v4";
+
+const Take = z.number().int().positive();
+
+type TakeType = z.infer<typeof Take>;
+
+const Skip = z.number().int().positive();
+
+type SkipType = z.infer<typeof Skip>;
+
+const Page = z.coerce
+  .number()
+  .int()
+  .transform((value) => (value <= 0 ? 1 : value))
+  .default(1);
+
+export type PageType = z.infer<typeof Page>;
+
+export type PaginationType = {
+  values: { take: TakeType; skip: SkipType };
+  page: PageType;
+};
+
+export type PaginationValuesType = Record<string, unknown>;
+
+export type TotalType = number;
+
+export type ExhaustedType = boolean;
+
+export type PaginationExhaustedConfig = {
+  total: TotalType;
+  pagination: PaginationType;
+};
+
+export type PaginationPrepareConfigType<T> = {
+  total: TotalType;
+  pagination: PaginationType;
+  result: T[];
+};
+
+export class Pagination {
+  static parse(values: PaginationValuesType, _take: TakeType): PaginationType {
+    const page = Page.parse(values.page);
+    const take = Take.parse(_take);
+
+    const skip = (page - 1) * take;
+
+    return { values: { take, skip }, page };
+  }
+
+  static prepare<T>(config: PaginationPrepareConfigType<T>): Paged<T> {
+    const exhausted = Pagination.isExhausted(config);
+
+    const currentPage = config.pagination.page;
+    const lastPage = Pagination.getLastPage(config);
+
+    const previousPage = currentPage > 1 ? currentPage - 1 : undefined;
+    const nextPage = currentPage < lastPage ? currentPage + 1 : undefined;
+
+    return {
+      result: config.result,
+      meta: {
+        exhausted,
+        currentPage,
+        previousPage,
+        nextPage,
+        lastPage,
+        total: config.total,
+      },
+    };
+  }
+
+  static isExhausted(config: PaginationExhaustedConfig): ExhaustedType {
+    const lastPage = Pagination.getLastPage(config);
+    const currentPage = config.pagination.page;
+
+    return lastPage <= currentPage;
+  }
+
+  private static getLastPage(config: PaginationExhaustedConfig): PageType {
+    return Math.ceil(config.total / config.pagination.values.take);
+  }
+
+  static empty = {
+    result: [],
+    meta: {
+      exhausted: true,
+      currentPage: 1,
+      previousPage: undefined,
+      nextPage: undefined,
+      lastPage: 1,
+      total: 0,
+    },
+  };
+
+  static getFirstPage({ take }: { take: TakeType }): PaginationType {
+    return { values: { take, skip: 0 }, page: 1 };
+  }
+}
+
+export type Paged<T> = {
+  result: T[];
+  meta: {
+    exhausted: ExhaustedType;
+    currentPage: PageType;
+    previousPage: PageType | undefined;
+    nextPage: PageType | undefined;
+    lastPage: PageType;
+    total: TotalType;
+  };
+};

package/src/percentage.service.ts

@@ -0,0 +1,17 @@
+import { RoundToNearest, RoundingStrategy } from "./rounding.service";
+
+export class Percentage {
+  static of(
+    numerator: number,
+    denominator: number,
+    rounding: RoundingStrategy = new RoundToNearest(),
+  ): number {
+    if (denominator === 0) {
+      throw new Error("Invalid denominator");
+    }
+
+    if (numerator === 0) return 0;
+
+    return rounding.round((numerator / denominator) * 100);
+  }
+}

package/src/population-standard-deviation.service.ts

@@ -0,0 +1,21 @@
+import { Mean } from "./mean.service";
+import { RoundToDecimal, RoundingStrategy } from "./rounding.service";
+import { Sum } from "./sum.service";
+
+export class PopulationStandardDeviation {
+  static calculate(values: number[], rounding: RoundingStrategy = new RoundToDecimal(2)): number {
+    if (values.length < 2) {
+      throw new Error("At least two values are needed");
+    }
+
+    const mean = Mean.calculate(values);
+    const n = values.length;
+
+    const squaredDifferences = values.map((value) => (value - mean) ** 2);
+    const sumOfSquaredDifferences = Sum.of(squaredDifferences);
+
+    const variance = sumOfSquaredDifferences / n;
+
+    return rounding.round(Math.sqrt(variance));
+  }
+}