@bgord/tools 0.15.2 → 0.16.0

package/src/package-version.vo.ts

@@ -4,49 +4,22 @@ type MajorType = number;
 type MinorType = number;
 type PatchType = number;
 
-export const PackageVersionValue = z
-  .string()
-  .min(1)
-  .refine(
-    (value) => {
-      try {
-        if (!value.startsWith("v")) return false;
-
-        const [, version] = value.split("v");
-        if (!version) return false;
-
-        const [major, minor, patch] = version.split(".");
-        if (!(major && minor && patch)) return false;
-
-        if (
-          !(
-            Number.isInteger(Number(major)) &&
-            Number.isInteger(Number(minor)) &&
-            Number.isInteger(Number(patch))
-          )
-        ) {
-          return false;
-        }
+export const PackageVersionError = { error: "package.version.error" } as const;
 
-        return true;
-      } catch (_error) {
-        return false;
-      }
-    },
-    { message: "package.version.error" },
-  )
+export const PackageVersionValue = z
+  .string(PackageVersionError)
+  .regex(/^v(\d+)\.(\d+)\.(\d+)$/, PackageVersionError)
   .transform((value) => {
-    const [, version] = value.split("v");
+    const match = /^v(\d+)\.(\d+)\.(\d+)$/.exec(value)!;
 
-    const [major, minor, patch] = (version as string).split(".");
+    const major = Number(match[1]);
+    const minor = Number(match[2]);
+    const patch = Number(match[3]);
 
-    return {
-      major: Number(major),
-      minor: Number(minor),
-      patch: Number(patch),
-    };
+    return { major, minor, patch };
   })
   .brand("PackageVersionValue");
+
 export type PackageVersionValueType = z.infer<typeof PackageVersionValue>;
 
 export class PackageVersion {
@@ -56,7 +29,7 @@ export class PackageVersion {
     readonly patch: PatchType,
   ) {}
 
-  isGreaterThanOrEqual(another: PackageVersion) {
+  isGreaterThanOrEqual(another: PackageVersion): boolean {
     if (this.major > another.major) return true;
     if (this.major < another.major) return false;
 
@@ -69,19 +42,17 @@ export class PackageVersion {
     return true;
   }
 
-  toString() {
+  toString(): string {
     return `${this.major}.${this.minor}.${this.patch}`;
   }
 
-  static fromStringWithV(value: string) {
-    const version = PackageVersionValue.parse(value);
-
-    return new PackageVersion(version.major, version.minor, version.patch);
+  static fromStringWithV(value: string): PackageVersion {
+    const parsed = PackageVersionValue.parse(value);
+    return new PackageVersion(parsed.major, parsed.minor, parsed.patch);
   }
 
-  static fromString(value: string) {
-    const version = PackageVersionValue.parse(`v${value}`);
-
-    return new PackageVersion(version.major, version.minor, version.patch);
+  static fromString(value: string): PackageVersion {
+    const parsed = PackageVersionValue.parse(`v${value}`);
+    return new PackageVersion(parsed.major, parsed.minor, parsed.patch);
   }
 }

package/src/pagination.service.ts

@@ -1,16 +1,23 @@
 import { z } from "zod/v4";
 
-const Take = z.number().int().gte(0);
+const PaginationTakeError = { error: "pagination.take.invalid" } as const;
+const PaginationSkipError = { error: "pagination.skip.invalid" } as const;
+const PaginationPageError = { error: "pagination.page.invalid" } as const;
+
+const Take = z.number(PaginationTakeError).int(PaginationTakeError).gte(1, PaginationTakeError);
+
 type TakeType = z.infer<typeof Take>;
 
-const Skip = z.number().int().gte(0);
+const Skip = z.number(PaginationSkipError).int(PaginationSkipError).gte(0, PaginationSkipError);
+
 type SkipType = z.infer<typeof Skip>;
 
 const Page = z.coerce
-  .number()
-  .int()
+  .number(PaginationPageError)
+  .int(PaginationPageError)
   .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 };
@@ -46,16 +53,11 @@ export class Pagination {
   }
 
   static isExhausted(config: PaginationExhaustedConfig): ExhaustedType {
-    const lastPage = Pagination.getLastPage(config);
-    const currentPage = config.pagination.page;
-
-    return lastPage <= currentPage;
+    return Pagination.getLastPage(config) <= config.pagination.page;
   }
 
   private static getLastPage(config: PaginationExhaustedConfig): PageType {
-    const lastPage = Math.ceil(config.total / config.pagination.values.take);
-
-    return Page.parse(lastPage);
+    return Page.parse(Math.ceil(config.total / config.pagination.values.take));
   }
 
   static empty = {
@@ -70,8 +72,8 @@ export class Pagination {
     },
   };
 
-  static getFirstPage({ take }: { take: TakeType }): PaginationType {
-    return { values: { take, skip: Skip.parse(0) }, page: Page.parse(1) };
+  static getFirstPage(input: { take: TakeType }): PaginationType {
+    return { values: { take: Take.parse(input.take), skip: Skip.parse(0) }, page: Page.parse(1) };
   }
 }
 

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

@@ -1,18 +1,16 @@
 import { z } from "zod/v4";
 
+export const QuarterIsoIdError = { error: "quarter-iso-id.invalid" } as const;
+
 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);
+  .string(QuarterIsoIdError)
+  .regex(/^\d{4}-Q[1-4]$/, QuarterIsoIdError)
+  .refine((value) => {
+    const [yearPart, quarterPart] = value.split("-Q");
+    const year = Number(yearPart);
+    const quarter = Number(quarterPart);
+
+    return Number.isInteger(year) && Number.isInteger(quarter) && quarter >= 1 && quarter <= 4;
+  }, QuarterIsoIdError);
 
-      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

@@ -7,12 +7,14 @@ 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);
   }
 
@@ -23,6 +25,7 @@ export class Quarter extends DateRange {
   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/rate-limiter.service.ts

@@ -1,19 +1,17 @@
-import type { TimeResult } from "./time.service";
 import { Timestamp, type TimestampType } from "./timestamp.vo";
-import type { Falsy } from "./ts-utils";
 
-type RateLimiterOptionsType = Pick<TimeResult, "ms">;
+type RateLimiterOptionsType = { ms: TimestampType };
 type RateLimiterResultSuccessType = { allowed: true };
 type RateLimiterResultErrorType = { allowed: false; remainingMs: TimestampType };
 type RateLimiterResultType = RateLimiterResultSuccessType | RateLimiterResultErrorType;
 
 export class RateLimiter {
-  private lastInvocationTimestampMs: Falsy<TimestampType> = null;
+  private lastInvocationTimestampMs: TimestampType | null = null;
 
   constructor(private readonly options: RateLimiterOptionsType) {}
 
   verify(currentTimestampMs: TimestampType): RateLimiterResultType {
-    if (this.lastInvocationTimestampMs === null || this.lastInvocationTimestampMs === undefined) {
+    if (this.lastInvocationTimestampMs == null) {
       this.lastInvocationTimestampMs = currentTimestampMs;
 
       return { allowed: true };
@@ -23,10 +21,12 @@ export class RateLimiter {
 
     if (nextAllowedTimestampMs <= currentTimestampMs) {
       this.lastInvocationTimestampMs = currentTimestampMs;
-
       return { allowed: true };
     }
 
-    return { allowed: false, remainingMs: Timestamp.parse(nextAllowedTimestampMs - currentTimestampMs) };
+    const remainingDelta = nextAllowedTimestampMs - currentTimestampMs;
+    const remainingMs = Timestamp.parse(remainingDelta);
+
+    return { allowed: false, remainingMs };
   }
 }

package/src/reordering.service.ts

@@ -1,13 +1,25 @@
 import { z } from "zod/v4";
 import { DoublyLinkedList, Node } from "./dll.service";
 
-export const ReorderingItemPositionValue = z.number().int().min(0);
+export const ReorderingPositionError = { error: "reordering.position.invalid" } as const;
+export const ReorderingCannotFindItemError = { error: "reordering.item.not_found" } as const;
+export const ReorderingCannotFindCurrentError = { error: "reordering.current_item.not_found" } as const;
+export const ReorderingCannotFindTargetError = { error: "reordering.target_item.not_found" } as const;
+export const ReorderingCorrelationIdError = { error: "reordering.correlation_id.invalid" } as const;
+export const ReorderingItemIdError = { error: "reordering.item_id.invalid" } as const;
+
+export const ReorderingItemPositionValue = z
+  .number(ReorderingPositionError)
+  .int(ReorderingPositionError)
+  .min(0, ReorderingPositionError);
 export type ReorderingItemPositionValueType = z.infer<typeof ReorderingItemPositionValue>;
 
-export const ReorderingCorrelationId = z.string().min(1);
+export const ReorderingCorrelationId = z
+  .string(ReorderingCorrelationIdError)
+  .min(1, ReorderingCorrelationIdError);
 export type ReorderingCorrelationIdType = z.infer<typeof ReorderingCorrelationId>;
 
-export const ReorderingItemId = z.uuid();
+export const ReorderingItemId = z.string(ReorderingItemIdError);
 export type ReorderingItemIdType = z.infer<typeof ReorderingItemId>;
 
 export const Reordering = z.object({
@@ -15,7 +27,6 @@ export const Reordering = z.object({
   id: ReorderingItemId,
   position: ReorderingItemPositionValue,
 });
-
 export type ReorderingType = z.infer<typeof Reordering>;
 
 export type WithReorderingPositionValue<T> = T & { position: ReorderingItemPositionValueType };
@@ -24,9 +35,8 @@ export class ReorderingPosition {
   readonly value: ReorderingItemPositionValueType;
 
   constructor(value: ReorderingItemPositionValueType) {
-    if (!ReorderingItemPositionValue.safeParse(value).success) {
-      throw new Error("Position is not a positive integer");
-    }
+    const parsed = ReorderingItemPositionValue.safeParse(value);
+    if (!parsed.success) throw new Error(ReorderingPositionError.error);
 
     this.value = value;
   }
@@ -55,21 +65,19 @@ enum ReorderingTransferDirection {
 
 export class ReorderingTransfer {
   readonly id: ReorderingItem["id"];
-
   readonly to: ReorderingPosition;
 
   constructor(config: { id: ReorderingItem["id"]; to: ReorderingItemPositionValueType }) {
-    this.id = config.id;
-    this.to = new ReorderingPosition(config.to);
+    const id = config.id;
+    const to = new ReorderingPosition(config.to);
+
+    this.id = id;
+    this.to = to;
   }
 
   getDirection(currentPosition: ReorderingPosition): ReorderingTransferDirection {
     if (this.to.value === currentPosition.value) return ReorderingTransferDirection.noop;
-
-    if (this.to.value > currentPosition.value) {
-      return ReorderingTransferDirection.downwards;
-    }
-
+    if (this.to.value > currentPosition.value) return ReorderingTransferDirection.downwards;
     return ReorderingTransferDirection.upwards;
   }
 }
@@ -90,62 +98,68 @@ export class ReorderingCalculator {
   }
 
   add(id: ReorderingItem["id"]): ReorderingItem {
-    const position = new ReorderingPosition(ReorderingItemPositionValue.parse(this.dll.getSize()));
+    const size = this.dll.getSize();
+    const position = new ReorderingPosition(ReorderingItemPositionValue.parse(size));
     const item = new ReorderingItem(id, position);
-    this.dll.append(new Node(item));
+    const node = new Node(item);
+    this.dll.append(node);
     return item;
   }
 
   delete(id: ReorderingItem["id"]) {
-    const item = this.dll.find((x) => x.data.eq(id));
-    if (!item) throw new Error("Cannot find Item");
+    const node = this.dll.find((x) => x.data.eq(id));
+    if (!node) throw new Error(ReorderingCannotFindItemError.error);
 
-    this.dll.remove(item);
+    this.dll.remove(node);
     this.recalculate();
   }
 
   transfer(transfer: ReorderingTransfer): ReturnType<ReorderingCalculator["read"]> {
     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(ReorderingCannotFindCurrentError.error);
 
-    if (!current) throw new Error("Cannot find current Item");
-    if (!target) throw new Error("Cannot find target Item");
+    const target = this.dll.find((node) => node.data.position.eq(transfer.to));
+    if (!target) throw new Error(ReorderingCannotFindTargetError.error);
 
     const direction = transfer.getDirection(current.data.position);
-
     if (direction === ReorderingTransferDirection.noop) return this.read();
+
+    // remove first to avoid temporary invalid duplicates of positions
+    this.dll.remove(current);
+
     if (direction === ReorderingTransferDirection.upwards) {
-      this.dll.remove(current);
       this.dll.insertBefore(current, target);
-      this.recalculate();
-    }
-    if (direction === ReorderingTransferDirection.downwards) {
-      this.dll.remove(current);
+    } else {
       this.dll.insertAfter(current, target);
-      this.recalculate();
     }
+
+    this.recalculate();
     return this.read();
   }
 
   read() {
-    const ids = Array.from(this.dll).map((item) => item.data.id);
-    const items = Array.from(this.dll).map((item) => item.data);
+    const ids = Array.from(this.dll).map((node) => node.data.id);
+    const items = Array.from(this.dll).map((node) => node.data);
     return { ids, items };
   }
 
   private recalculate() {
-    this.dll = ReorderingCalculator.fromArray(this.read().ids).dll;
+    let index = 0;
+    for (const node of this.dll) {
+      const id = node.data.id;
+      const position = new ReorderingPosition(index);
+      node.data = new ReorderingItem(id, position);
+      index += 1;
+    }
   }
 }
 
 export class ReorderingIntegrator {
   static appendPosition(reordering: ReorderingType[]) {
     return function <T extends { id: ReorderingItemIdType }>(item: T): WithReorderingPositionValue<T> {
-      const position = ReorderingItemPositionValue.parse(
-        reordering.find((x) => x.id === item.id)?.position ?? 0,
-      );
-
-      return { ...item, position };
+      const found = reordering.find((x) => x.id === item.id);
+      const positionValue = ReorderingItemPositionValue.parse(found?.position ?? 0);
+      return { ...item, position: positionValue };
     };
   }
 

package/src/revision.vo.ts

@@ -1,27 +1,36 @@
 import { z } from "zod/v4";
 import type { ETag, WeakETag } from "./etags.vo";
 
-export const RevisionValue = z.number().int().min(0);
+export const RevisionValueError = { error: "invalid.revision.value" } as const;
+
+export const RevisionValue = z
+  .number(RevisionValueError)
+  .int(RevisionValueError)
+  .min(0, RevisionValueError)
+  .brand("RevisionValue");
+
 export type RevisionValueType = z.infer<typeof RevisionValue>;
 
+export const RevisionInvalidErrorMessage = "revision.invalid" as const;
+export const RevisionMismatchErrorMessage = "revision.mismatch" as const;
+
 export class Revision {
+  static readonly INITIAL: RevisionValueType = RevisionValue.parse(0);
+
   readonly value: RevisionValueType;
-  static initial: RevisionValueType = 0;
 
   constructor(value: unknown) {
     const result = RevisionValue.safeParse(value);
-
     if (!result.success) throw new InvalidRevisionError();
-
     this.value = result.data;
   }
 
-  matches(another: RevisionValueType): boolean {
+  equals(another: RevisionValueType): boolean {
     return this.value === another;
   }
 
   validate(another: RevisionValueType): void {
-    if (!this.matches(another)) throw new RevisionMismatchError();
+    if (!this.equals(another)) throw new RevisionMismatchError();
   }
 
   next(): Revision {
@@ -41,14 +50,14 @@ export class Revision {
 
 export class RevisionMismatchError extends Error {
   constructor() {
-    super();
+    super(RevisionMismatchErrorMessage);
     Object.setPrototypeOf(this, RevisionMismatchError.prototype);
   }
 }
 
 export class InvalidRevisionError extends Error {
   constructor() {
-    super();
+    super(RevisionInvalidErrorMessage);
     Object.setPrototypeOf(this, InvalidRevisionError.prototype);
   }
 }

package/src/rounding.adapter.ts

@@ -22,9 +22,7 @@ export const RoundingDecimalsError = "invalid.rounding.decimals" as const;
 
 export class RoundToDecimal implements RoundingPort {
   constructor(private readonly decimals: number) {
-    if (!Number.isInteger(decimals) || decimals < 0 || decimals > 100) {
-      throw new Error(RoundingDecimalsError);
-    }
+    if (!Number.isInteger(decimals) || decimals < 0 || decimals > 100) throw new Error(RoundingDecimalsError);
   }
 
   round(value: number): number {

package/src/size.vo.ts

@@ -15,17 +15,15 @@ type SizeConfigType = { unit: SizeUnit; value: number };
 
 export class Size {
   private readonly unit: SizeUnit;
-
   private readonly value: SizeValueType;
-
   private readonly bytes: SizeValueType;
 
   private static readonly KB_MULTIPLIER = 1024;
-
   private static readonly MB_MULTIPLIER = 1024 * Size.KB_MULTIPLIER;
-
   private static readonly GB_MULTIPLIER = 1024 * Size.MB_MULTIPLIER;
 
+  private static readonly ROUNDER = new RoundToDecimal(2);
+
   constructor(config: SizeConfigType) {
     this.unit = config.unit;
     this.value = SizeValue.parse(config.value);
@@ -60,28 +58,20 @@ export class Size {
     return this.bytes;
   }
 
-  isGreaterThan(another: Size) {
+  isGreaterThan(another: Size): boolean {
     return this.bytes > another.toBytes();
   }
 
   format(unit: SizeUnit): string {
-    const rounding = new RoundToDecimal(2);
-
     switch (unit) {
       case SizeUnit.kB: {
-        const kbs = rounding.round(this.bytes / Size.KB_MULTIPLIER);
-
-        return `${kbs} ${SizeUnit.kB}`;
+        return `${Size.ROUNDER.round(this.bytes / Size.KB_MULTIPLIER)} ${SizeUnit.kB}`;
       }
       case SizeUnit.MB: {
-        const mbs = rounding.round(this.bytes / Size.MB_MULTIPLIER);
-
-        return `${mbs} ${SizeUnit.MB}`;
+        return `${Size.ROUNDER.round(this.bytes / Size.MB_MULTIPLIER)} ${SizeUnit.MB}`;
       }
       case SizeUnit.GB: {
-        const gbs = rounding.round(this.bytes / Size.GB_MULTIPLIER);
-
-        return `${gbs} ${SizeUnit.GB}`;
+        return `${Size.ROUNDER.round(this.bytes / Size.GB_MULTIPLIER)} ${SizeUnit.GB}`;
       }
       default: {
         // SizeUnit.b

package/src/streak-calculator.service.ts

@@ -1,4 +1,4 @@
-import { format, isAfter, isEqual, subDays } from "date-fns";
+import { format, subDays } from "date-fns";
 
 type DateType = string;
 export type StreakType = { cutoff: DateType; dates: DateType[]; streak: number };
@@ -6,32 +6,27 @@ export type StreakType = { cutoff: DateType; dates: DateType[]; streak: number }
 export class StreakCalculator {
   private readonly cutoff: DateType;
 
-  constructor() {
-    const today = new Date();
-    this.cutoff = StreakCalculator.format(today);
+  constructor(now: Date = new Date()) {
+    this.cutoff = StreakCalculator.format(now);
   }
 
-  calculate(_dates: DateType[]): StreakType {
-    const dates = Array.from(new Set(_dates));
+  calculate(inputDates: DateType[]): StreakType {
+    const dates = Array.from(new Set(inputDates));
+    const datesSet = new Set(dates);
 
     let streak = 0;
-    let streakTail = this.cutoff;
+    let cursor = this.cutoff;
 
-    for (let i = 0; i < dates.length; i++) {
-      const date = dates[i] as string;
-
-      if (isAfter(date, streakTail)) continue;
-
-      if (isEqual(streakTail, date) || isAfter(date, streakTail)) {
-        streakTail = StreakCalculator.format(subDays(date, 1));
-        streak++;
-      } else break;
+    while (datesSet.has(cursor)) {
+      streak++;
+      const cursorDate = new Date(`${cursor}T00:00:00Z`);
+      cursor = StreakCalculator.format(subDays(cursorDate, 1));
     }
 
     return { cutoff: this.cutoff, dates, streak };
   }
 
-  static format(date: Parameters<typeof format>[0]): DateType {
+  static format(date: Date | number): DateType {
     return format(date, "yyyy-MM-dd");
   }
 }

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

@@ -1,10 +1,5 @@
 import { z } from "zod/v4";
 
-export const TimeZoneOffsetValue = z
-  .string()
-  .trim()
-  .or(z.undefined())
-  .transform((value) => Number(value))
-  .transform((value) => (Number.isNaN(value) ? 0 : value))
-  .brand("TimeZoneOffsetValue");
+export const TimeZoneOffsetValue = z.coerce.number().catch(0).brand("TimeZoneOffsetValue");
+
 export type TimeZoneOffsetValueType = z.infer<typeof TimeZoneOffsetValue>;