@bgord/tools 0.12.26 → 0.13.1

package/src/mime.vo.ts

@@ -2,9 +2,7 @@ import * as mime from "mime-types";
 import { ExtensionSchema, type ExtensionType } from "./extension.vo";
 
 export type MimeRawType = string;
-
 type MimeTypeType = string;
-
 type MimeSubtypeType = string;
 
 export class Mime {
@@ -15,13 +13,8 @@ export class Mime {
   constructor(value: MimeRawType) {
     const [type, subtype] = value.split("/");
 
-    if (typeof type !== "string" || type.length === 0) {
-      throw new InvalidMimeError();
-    }
-
-    if (typeof subtype !== "string" || subtype.length === 0) {
-      throw new InvalidMimeError();
-    }
+    if (typeof type !== "string" || type.length === 0) throw new InvalidMimeError();
+    if (typeof subtype !== "string" || subtype.length === 0) throw new InvalidMimeError();
 
     this.raw = value;
     this.type = type;

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

@@ -1,14 +1,10 @@
 import { type RoundingStrategy, RoundToDecimal } from "./rounding.service";
 
 type MinMaxScalerValueType = number;
-
 type MinMaxScalerConfigType = {
   min: MinMaxScalerValueType;
   max: MinMaxScalerValueType;
-  bound?: {
-    lower: MinMaxScalerValueType;
-    upper: MinMaxScalerValueType;
-  };
+  bound?: { lower: MinMaxScalerValueType; upper: MinMaxScalerValueType };
   rounding?: RoundingStrategy;
 };
 
@@ -26,13 +22,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("Invalid MinMaxScaler min-max config");
-    }
-
-    if (upper - lower <= 0) {
-      throw new Error("Invalid MinMaxScaler bound config");
-    }
+    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;
 
@@ -45,9 +36,7 @@ export class MinMaxScaler {
   scale(value: MinMaxScalerValueType) {
     const { min, max, lower, upper } = this;
 
-    if (value < min || value > max) {
-      throw new Error("Value out of min/max range");
-    }
+    if (value < min || value > max) throw new Error("Value out of min/max range");
 
     if (min === max)
       return {
@@ -70,9 +59,7 @@ export class MinMaxScaler {
   descale(scaled: MinMaxScalerValueType) {
     const { min, max, lower, upper } = this;
 
-    if (scaled < lower || scaled > upper) {
-      throw new Error("Scaled value out of bounds");
-    }
+    if (scaled < lower || scaled > upper) throw new Error("Scaled value out of bounds");
 
     const result = ((scaled - lower) / (upper - lower)) * (max - min) + min;
 
@@ -85,9 +72,7 @@ export class MinMaxScaler {
   }
 
   static getMinMax(values: MinMaxScalerValueType[]) {
-    if (values.length === 0) {
-      throw new Error("An empty array supplied");
-    }
+    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

@@ -1,3 +1,5 @@
+import type { TimestampType } from "./timestamp.vo";
+
 export class Minute {
   private readonly value: number;
 
@@ -6,26 +8,20 @@ export class Minute {
   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");
-    }
+    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;
   }
 
+  static fromUtcTimestamp(timestamp: TimestampType): Minute {
+    const minutes = new Date(timestamp).getUTCMinutes();
+    return new Minute(minutes);
+  }
+
   get() {
-    return {
-      raw: this.value,
-      formatted: this.value.toString().padStart(2, "0"),
-    };
+    return { raw: this.value, formatted: this.value.toString().padStart(2, "0") };
   }
 
   equals(another: Minute): boolean {

package/src/money.vo.ts

@@ -3,8 +3,8 @@ import { type RoundingStrategy, RoundToNearest } from "./rounding.service";
 
 export const MoneyAmount = z
   .number()
-  .int({ message: "money.amount.invalid " })
-  .min(0, { message: "money.amount.invalid " })
+  .int({ message: "money.amount.invalid" })
+  .min(0, { message: "money.amount.invalid" })
   .brand("MoneyAmount");
 
 export type MoneyAmountType = z.infer<typeof MoneyAmount>;
@@ -55,18 +55,12 @@ export class Money {
   subtract(money: Money) {
     const result = this.rounding.round(this.amount - money.getAmount());
 
-    if (result < Money.ZERO) {
-      throw new Error("Less than zero");
-    }
+    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);

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

@@ -0,0 +1,25 @@
+import { z } from "zod/v4";
+
+export const MonthIsoId = z
+  .string()
+  .regex(/^\d{4}-\d{2}$/)
+  .refine(
+    (value) => {
+      const [y, m] = value.split("-");
+
+      const year = Number(y);
+      const month = Number(m);
+
+      return (
+        y.length === 4 &&
+        m.length === 2 &&
+        Number.isInteger(year) &&
+        Number.isInteger(month) &&
+        month >= 1 &&
+        month <= 12
+      );
+    },
+    { message: "month-iso-id.invalid" },
+  );
+
+export type MonthIsoIdType = z.infer<typeof MonthIsoId>;

package/src/month.vo.ts

@@ -0,0 +1,26 @@
+import { 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";
+
+export class Month extends DateRange {
+  toIsoId(): MonthIsoIdType {
+    return new Date(this.getStart()).toISOString().slice(0, 7) as MonthIsoIdType;
+  }
+
+  static fromTimestamp(timestamp: TimestampType): Month {
+    const start = Timestamp.parse(startOfMonth(timestamp).getTime());
+    const end = Timestamp.parse(endOfMonth(timestamp).getTime());
+    return new Month(start, end);
+  }
+
+  static fromNow(now: TimestampType): Month {
+    return Month.fromTimestamp(now);
+  }
+
+  static fromIsoId(iso: MonthIsoIdType): Month {
+    const [year, month] = MonthIsoId.parse(iso).split("-").map(Number);
+    const reference = new Date(Date.UTC(year, month - 1, 1));
+    return Month.fromTimestamp(Timestamp.parse(reference.getTime()));
+  }
+}

package/src/object-key.vo.ts

@@ -13,5 +13,4 @@ export const ObjectKey = z
     "obj_key_bad_segments",
   )
   .brand("object_key");
-
 export type ObjectKeyType = z.infer<typeof ObjectKey>;

package/src/outlier-detector.service.ts

@@ -6,9 +6,7 @@ export class OutlierDetector {
   private readonly threshold: number;
 
   constructor(values: number[], threshold: number) {
-    if (values.length < 2) {
-      throw new Error("At least two values are needed");
-    }
+    if (values.length < 2) throw new Error("At least two values are needed");
 
     this.zScore = new ZScore(values);
     this.threshold = Math.abs(threshold);

package/src/package-version.vo.ts

@@ -1,9 +1,7 @@
 import { z } from "zod/v4";
 
 type MajorType = number;
-
 type MinorType = number;
-
 type PatchType = number;
 
 export const PackageVersionValue = z
@@ -30,16 +28,6 @@ export const PackageVersionValue = z
           return false;
         }
 
-        if (
-          !(
-            Number.isInteger(Number(major)) &&
-            Number.isInteger(Number(minor)) &&
-            Number.isInteger(Number(patch))
-          )
-        ) {
-          return false;
-        }
-
         return true;
       } catch (_error) {
         return false;

package/src/pagination.service.ts

@@ -1,11 +1,9 @@
 import { z } from "zod/v4";
 
 const Take = z.number().int().gte(0);
-
 type TakeType = z.infer<typeof Take>;
 
 const Skip = z.number().int().gte(0);
-
 type SkipType = z.infer<typeof Skip>;
 
 const Page = z.coerce
@@ -13,30 +11,14 @@ const Page = z.coerce
   .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 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 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 {
@@ -59,14 +41,7 @@ export class Pagination {
 
     return {
       result: config.result,
-      meta: {
-        exhausted,
-        currentPage,
-        previousPage,
-        nextPage,
-        lastPage,
-        total: config.total,
-      },
+      meta: { exhausted, currentPage, previousPage, nextPage, lastPage, total: config.total },
     };
   }
 

package/src/percentage.service.ts

@@ -6,12 +6,8 @@ export class Percentage {
     denominator: number,
     rounding: RoundingStrategy = new RoundToNearest(),
   ): number {
-    if (denominator === 0) {
-      throw new Error("Invalid denominator");
-    }
-
+    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

@@ -4,9 +4,7 @@ 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");
-    }
+    if (values.length < 2) throw new Error("At least two values are needed");
 
     const mean = Mean.calculate(values);
     const n = values.length;

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

@@ -0,0 +1,18 @@
+import { z } from "zod/v4";
+
+export const QuarterIsoId = z
+  .string()
+  .regex(/^\d{4}-Q[1-4]$/)
+  .refine(
+    (value) => {
+      const [y, q] = value.split("-Q");
+      const year = Number(y);
+      const quarter = Number(q);
+
+      return (
+        y.length === 4 && Number.isInteger(year) && Number.isInteger(quarter) && quarter >= 1 && quarter <= 4
+      );
+    },
+    { message: "quarter-iso-id.invalid" },
+  );
+export type QuarterIsoIdType = z.infer<typeof QuarterIsoId>;

package/src/quarter.vo.ts

@@ -0,0 +1,28 @@
+import { endOfQuarter, getQuarter, getYear, setQuarter, startOfQuarter } from "date-fns";
+import { DateRange } from "./date-range.vo";
+import { QuarterIsoId, type QuarterIsoIdType } from "./quarter-iso-id.vo";
+import { Timestamp, type TimestampType } from "./timestamp.vo";
+
+export class Quarter extends DateRange {
+  toIsoId(): QuarterIsoIdType {
+    const year = getYear(this.getStart());
+    const quarter = getQuarter(this.getStart());
+    return `${year}-Q${quarter}` as QuarterIsoIdType;
+  }
+
+  static fromTimestamp(timestamp: TimestampType): Quarter {
+    const start = Timestamp.parse(startOfQuarter(timestamp).getTime());
+    const end = Timestamp.parse(endOfQuarter(timestamp).getTime());
+    return new Quarter(start, end);
+  }
+
+  static fromNow(now: TimestampType): Quarter {
+    return Quarter.fromTimestamp(now);
+  }
+
+  static fromIsoId(isoId: QuarterIsoIdType): Quarter {
+    const [year, quarter] = QuarterIsoId.parse(isoId).split("-Q").map(Number);
+    const reference = setQuarter(new Date(Date.UTC(year, 0, 1)), quarter);
+    return Quarter.fromTimestamp(Timestamp.parse(reference.getTime()));
+  }
+}

package/src/random.service.ts

@@ -1,28 +1,14 @@
-type RandomGenerateConfigType = {
-  min: number;
-  max: number;
-};
+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");
-    }
+    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

@@ -3,11 +3,8 @@ import { Timestamp, type TimestampType } from "./timestamp.vo";
 import type { Falsy } from "./ts-utils";
 
 type RateLimiterOptionsType = Pick<TimeResult, "ms">;
-
 type RateLimiterResultSuccessType = { allowed: true };
-
 type RateLimiterResultErrorType = { allowed: false; remainingMs: TimestampType };
-
 type RateLimiterResultType = RateLimiterResultSuccessType | RateLimiterResultErrorType;
 
 export class RateLimiter {

package/src/reordering.service.ts

@@ -2,15 +2,12 @@ import { z } from "zod/v4";
 import { DoublyLinkedList, Node } from "./dll.service";
 
 export const ReorderingItemPositionValue = z.number().int().min(0);
-
 export type ReorderingItemPositionValueType = z.infer<typeof ReorderingItemPositionValue>;
 
 export const ReorderingCorrelationId = z.string().min(1);
-
 export type ReorderingCorrelationIdType = z.infer<typeof ReorderingCorrelationId>;
 
 export const ReorderingItemId = z.uuid();
-
 export type ReorderingItemIdType = z.infer<typeof ReorderingItemId>;
 
 export const Reordering = z.object({
@@ -21,9 +18,7 @@ export const Reordering = z.object({
 
 export type ReorderingType = z.infer<typeof Reordering>;
 
-export type WithReorderingPositionValue<T> = T & {
-  position: ReorderingItemPositionValueType;
-};
+export type WithReorderingPositionValue<T> = T & { position: ReorderingItemPositionValueType };
 
 export class ReorderingPosition {
   readonly value: ReorderingItemPositionValueType;
@@ -63,10 +58,7 @@ export class ReorderingTransfer {
 
   readonly to: ReorderingPosition;
 
-  constructor(config: {
-    id: ReorderingItem["id"];
-    to: ReorderingItemPositionValueType;
-  }) {
+  constructor(config: { id: ReorderingItem["id"]; to: ReorderingItemPositionValueType }) {
     this.id = config.id;
     this.to = new ReorderingPosition(config.to);
   }
@@ -106,9 +98,8 @@ export class ReorderingCalculator {
 
   delete(id: ReorderingItem["id"]) {
     const item = this.dll.find((x) => x.data.eq(id));
-    if (!item) {
-      throw new Error("Cannot find Item");
-    }
+    if (!item) throw new Error("Cannot find Item");
+
     this.dll.remove(item);
     this.recalculate();
   }
@@ -117,12 +108,8 @@ export class ReorderingCalculator {
     const current = this.dll.find((node) => node.data.eq(transfer.id));
     const target = this.dll.find((node) => node.data.position.eq(transfer.to));
 
-    if (!current) {
-      throw new Error("Cannot find current Item");
-    }
-    if (!target) {
-      throw new Error("Cannot find target Item");
-    }
+    if (!current) throw new Error("Cannot find current Item");
+    if (!target) throw new Error("Cannot find target Item");
 
     const direction = transfer.getDirection(current.data.position);
 

package/src/revision.vo.ts

@@ -2,12 +2,10 @@ import { z } from "zod/v4";
 import type { ETag, WeakETag } from "./etags.vo";
 
 export const RevisionValue = z.number().int().min(0);
-
 export type RevisionValueType = z.infer<typeof RevisionValue>;
 
 export class Revision {
   readonly value: RevisionValueType;
-
   static initial: RevisionValueType = 0;
 
   constructor(value: unknown) {
@@ -31,16 +29,12 @@ export class Revision {
   }
 
   static fromETag(etag: ETag | null): Revision {
-    if (!etag) {
-      throw new InvalidRevisionError();
-    }
+    if (!etag) throw new InvalidRevisionError();
     return new Revision(etag.revision);
   }
 
   static fromWeakETag(weakEtag: WeakETag | null): Revision {
-    if (!weakEtag) {
-      throw new InvalidRevisionError();
-    }
+    if (!weakEtag) throw new InvalidRevisionError();
     return new Revision(weakEtag.revision);
   }
 }

package/src/simple-linear-regression.service.ts

@@ -2,9 +2,7 @@ import { type RoundingStrategy, RoundToNearest } from "./rounding.service";
 import { Sum } from "./sum.service";
 
 export type SLRPairType = { x: number; y: number };
-
 export type SLRParamsType = { a: number; b: number };
-
 export type SLRPredictionType = number;
 
 export class SimpleLinearRegression {
@@ -20,9 +18,7 @@ export class SimpleLinearRegression {
   static fromPairs(pairs: SLRPairType[], rounding?: RoundingStrategy) {
     const n = pairs.length;
 
-    if (n < 2) {
-      throw new Error("At least two pairs needed");
-    }
+    if (n < 2) throw new Error("At least two pairs needed");
 
     const x = pairs.map((pair) => pair.x);
     const y = pairs.map((pair) => pair.y);
@@ -30,30 +26,19 @@ export class SimpleLinearRegression {
     const xy = pairs.map((pair) => pair.x * pair.y);
 
     const sX = Sum.of(x);
-    if (sX >= Number.MAX_SAFE_INTEGER) {
-      throw new Error("Sum of x values is too big");
-    }
+    if (sX >= Number.MAX_SAFE_INTEGER) throw new Error("Sum of x values is too big");
 
     const sY = Sum.of(y);
-    if (sY >= Number.MAX_SAFE_INTEGER) {
-      throw new Error("Sum of y values is too big");
-    }
+    if (sY >= Number.MAX_SAFE_INTEGER) throw new Error("Sum of y values is too big");
 
     const sSX = Sum.of(xx);
-    if (sSX >= Number.MAX_SAFE_INTEGER) {
-      throw new Error("Sum of x squared values is too big");
-    }
+    if (sSX >= Number.MAX_SAFE_INTEGER) throw new Error("Sum of x squared values is too big");
 
     const sXY = Sum.of(xy);
-    if (sXY >= Number.MAX_SAFE_INTEGER) {
-      throw new Error("Sum of x times y values is too big");
-    }
+    if (sXY >= Number.MAX_SAFE_INTEGER) throw new Error("Sum of x times y values is too big");
 
     const bDenominator = sSX - sX ** 2 / n;
-
-    if (bDenominator === 0) {
-      throw new Error("Unable to create the model");
-    }
+    if (bDenominator === 0) throw new Error("Unable to create the model");
 
     const b = (sXY - (sX * sY) / n) / bDenominator;
     const a = (sY - b * sX) / n;

package/src/size.vo.ts

@@ -9,7 +9,6 @@ export enum SizeUnit {
 }
 
 export const SizeValue = z.number().positive().brand("SizeValue");
-
 type SizeValueType = z.infer<typeof SizeValue>;
 
 type SizeConfigType = { unit: SizeUnit; value: number };

package/src/stepper.service.ts

@@ -1,5 +1,4 @@
 type StepType = number;
-
 type StepperConfigType = { total: StepType };
 
 export class Stepper {
@@ -10,14 +9,8 @@ export class Stepper {
   private readonly total: StepType;
 
   constructor(config: StepperConfigType) {
-    if (!Number.isInteger(config.total)) {
-      throw new Error("Total value is not an integer");
-    }
-
-    if (config.total <= Stepper.DEFAULT_CURRENT) {
-      throw new Error("Total value should be greater than one");
-    }
-
+    if (!Number.isInteger(config.total)) throw new Error("Total value is not an integer");
+    if (config.total <= Stepper.DEFAULT_CURRENT) throw new Error("Total value should be greater than one");
     this.total = config.total;
   }
 

package/src/stopwatch.service.ts

@@ -3,7 +3,7 @@ import type { Falsy } from "./ts-utils";
 
 enum StopwatchState {
   started = "started",
-  stopped = "finished",
+  stopped = "stopped",
 }
 
 export type StopwatchResultType = { durationMs: TimestampType };
@@ -16,9 +16,7 @@ export class Stopwatch {
   constructor(private readonly startMs: TimestampType) {}
 
   stop(): StopwatchResultType {
-    if (this.state === StopwatchState.stopped) {
-      throw new Error("Stopwatch is already stopped");
-    }
+    if (this.state === StopwatchState.stopped) throw new Error("Stopwatch is already stopped");
 
     this.state = StopwatchState.stopped;
     this.stopMs = Timestamp.parse(Date.now());

package/src/streak-calculator.service.ts

@@ -1,12 +1,7 @@
 import { format, isAfter, isEqual, subDays } from "date-fns";
 
 type DateType = string;
-
-export type StreakType = {
-  cutoff: DateType;
-  dates: DateType[];
-  streak: number;
-};
+export type StreakType = { cutoff: DateType; dates: DateType[]; streak: number };
 
 export class StreakCalculator {
   private readonly cutoff: DateType;

package/src/time-zone-offset-value.vo.ts

@@ -7,5 +7,4 @@ export const TimeZoneOffsetValue = z
   .transform((value) => Number(value))
   .transform((value) => (Number.isNaN(value) ? 0 : value))
   .brand("TimeZoneOffsetValue");
-
 export type TimeZoneOffsetValueType = z.infer<typeof TimeZoneOffsetValue>;