@bgord/tools 0.6.0 → 0.8.0

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,7 +1,9 @@
 import { z } from "zod/v4";
 
 type MajorType = number;
+
 type MinorType = number;
+
 type PatchType = number;
 
 export const PackageVersionValue = z

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));
+  }
+}

package/src/random.service.ts

@@ -0,0 +1,29 @@
+type RandomGenerateConfigType = {
+  min: number;
+  max: number;
+};
+
+export class Random {
+  static generate(config?: RandomGenerateConfigType) {
+    const min = config?.min ?? 0;
+    const max = config?.max ?? 1;
+
+    if (!Number.isInteger(min)) {
+      throw new Error("Minimum value is not an integer");
+    }
+
+    if (!Number.isInteger(max)) {
+      throw new Error("Maximum value is not an integer");
+    }
+
+    if (min === max) {
+      throw new Error("Minimum and maximum values cannot be equal");
+    }
+
+    if (min > max) {
+      throw new Error("Minimum value cannot be greater than maximum value");
+    }
+
+    return Math.floor(Math.random() * (max - min + 1)) + min;
+  }
+}

package/src/rate-limiter.service.ts

@@ -1,9 +1,7 @@
 import type { TimestampType } from "./timestamp.vo";
 import type { Falsy } from "./ts-utils";
 
-type RateLimiterOptionsType = {
-  ms: TimestampType;
-};
+type RateLimiterOptionsType = { ms: TimestampType };
 
 type RateLimiterResultSuccessType = { allowed: true };