@bgord/tools 0.5.0 → 0.7.0

package/dist/revision.vo.js

@@ -0,0 +1,45 @@
+import { z } from "zod/v4";
+export const RevisionValue = z.number().int().min(0);
+export class Revision {
+    constructor(value) {
+        const result = RevisionValue.safeParse(value);
+        if (!result.success)
+            throw new InvalidRevisionError();
+        this.value = result.data;
+    }
+    matches(another) {
+        return this.value === another;
+    }
+    validate(another) {
+        if (!this.matches(another))
+            throw new RevisionMismatchError();
+    }
+    next() {
+        return new Revision(this.value + 1);
+    }
+    static fromETag(etag) {
+        if (!etag) {
+            throw new InvalidRevisionError();
+        }
+        return new Revision(etag.revision);
+    }
+    static fromWeakETag(weakEtag) {
+        if (!weakEtag) {
+            throw new InvalidRevisionError();
+        }
+        return new Revision(weakEtag.revision);
+    }
+}
+Revision.initial = 0;
+export class RevisionMismatchError extends Error {
+    constructor() {
+        super();
+        Object.setPrototypeOf(this, RevisionMismatchError.prototype);
+    }
+}
+export class InvalidRevisionError extends Error {
+    constructor() {
+        super();
+        Object.setPrototypeOf(this, InvalidRevisionError.prototype);
+    }
+}

package/dist/simple-linear-regression.service.d.ts

@@ -0,0 +1,18 @@
+import { RoundingStrategy } from "./rounding.service";
+export type SLRPairType = {
+    x: number;
+    y: number;
+};
+export type SLRParamsType = {
+    a: number;
+    b: number;
+};
+export type SLRPredictionType = number;
+export declare class SimpleLinearRegression {
+    private readonly params;
+    private readonly rounding;
+    constructor(params: SLRParamsType, rounding?: RoundingStrategy);
+    static fromPairs(pairs: SLRPairType[], rounding?: RoundingStrategy): SimpleLinearRegression;
+    predict(x: SLRPairType["x"], strategy?: RoundingStrategy): SLRPredictionType;
+    inspect(): SimpleLinearRegression["params"];
+}

package/dist/simple-linear-regression.service.js

@@ -0,0 +1,50 @@
+import { RoundToNearest } from "./rounding.service";
+import { Sum } from "./sum.service";
+export class SimpleLinearRegression {
+    constructor(params, rounding) {
+        this.params = params;
+        this.rounding = new RoundToNearest();
+        this.rounding = rounding ?? this.rounding;
+    }
+    static fromPairs(pairs, rounding) {
+        const n = pairs.length;
+        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);
+        const xx = x.map((x) => x ** 2);
+        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");
+        }
+        const sY = Sum.of(y);
+        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");
+        }
+        const sXY = Sum.of(xy);
+        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");
+        }
+        const b = (sXY - (sX * sY) / n) / bDenominator;
+        const a = (sY - b * sX) / n;
+        return new SimpleLinearRegression({ a, b }, rounding);
+    }
+    predict(x, strategy) {
+        const rounding = strategy ?? this.rounding;
+        const prediction = this.params.b * x + this.params.a;
+        return rounding.round(prediction);
+    }
+    inspect() {
+        return this.params;
+    }
+}

package/dist/size.vo.d.ts

@@ -5,8 +5,8 @@ export declare enum SizeUnit {
     MB = "MB",
     GB = "GB"
 }
-declare const SizeValueSchema: z.ZodNumber;
-export type SizeValueType = z.infer<typeof SizeValueSchema>;
+declare const SizeValue: z.ZodNumber;
+export type SizeValueType = z.infer<typeof SizeValue>;
 type SizeConfigType = {
     unit: SizeUnit;
     value: SizeValueType;

package/dist/size.vo.js

@@ -7,11 +7,11 @@ export var SizeUnit;
     SizeUnit["MB"] = "MB";
     SizeUnit["GB"] = "GB";
 })(SizeUnit || (SizeUnit = {}));
-const SizeValueSchema = z.number().positive();
+const SizeValue = z.number().positive();
 export class Size {
     constructor(config) {
         this.unit = config.unit;
-        this.value = SizeValueSchema.parse(config.value);
+        this.value = SizeValue.parse(config.value);
         this.bytes = this.calculateBytes(config);
     }
     toString() {

package/dist/stepper.service.d.ts

@@ -0,0 +1,23 @@
+type StepType = number;
+type StepperConfigType = {
+    total: StepType;
+};
+export declare class Stepper {
+    static readonly DEFAULT_CURRENT = 1;
+    private current;
+    private readonly total;
+    constructor(config: StepperConfigType);
+    continue(): Stepper;
+    read(): {
+        finished: boolean;
+        raw: {
+            current: number;
+            total: number;
+        };
+        formatted: string;
+    };
+    reset(): Stepper;
+    format(): string;
+    isFinished(): boolean;
+}
+export {};

package/dist/stepper.service.js

@@ -0,0 +1,34 @@
+export class Stepper {
+    constructor(config) {
+        this.current = Stepper.DEFAULT_CURRENT;
+        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;
+    }
+    continue() {
+        this.current = Math.min(this.current + 1, this.total);
+        return this;
+    }
+    read() {
+        return {
+            finished: this.isFinished(),
+            raw: { current: this.current, total: this.total },
+            formatted: `${this.current}/${this.total}`,
+        };
+    }
+    reset() {
+        this.current = Stepper.DEFAULT_CURRENT;
+        return this;
+    }
+    format() {
+        return this.read().formatted;
+    }
+    isFinished() {
+        return this.current === this.total;
+    }
+}
+Stepper.DEFAULT_CURRENT = 1;

package/dist/streak-calculator.service.d.ts

@@ -0,0 +1,14 @@
+import { format } from "date-fns";
+type DateType = string;
+export type StreakType = {
+    cutoff: DateType;
+    dates: DateType[];
+    streak: number;
+};
+export declare class StreakCalculator {
+    private readonly cutoff;
+    constructor();
+    calculate(_dates: DateType[]): StreakType;
+    static format(date: Parameters<typeof format>[0]): DateType;
+}
+export {};

package/dist/streak-calculator.service.js

@@ -0,0 +1,27 @@
+import { format, isAfter, isEqual, subDays } from "date-fns";
+export class StreakCalculator {
+    constructor() {
+        const today = new Date();
+        this.cutoff = StreakCalculator.format(today);
+    }
+    calculate(_dates) {
+        const dates = Array.from(new Set(_dates));
+        let streak = 0;
+        let streakTail = this.cutoff;
+        for (let i = 0; i < dates.length; i++) {
+            const date = dates[i];
+            if (isAfter(date, streakTail))
+                continue;
+            if (isEqual(streakTail, date) || isAfter(date, streakTail)) {
+                streakTail = StreakCalculator.format(subDays(date, 1));
+                streak++;
+            }
+            else
+                break;
+        }
+        return { cutoff: this.cutoff, dates, streak };
+    }
+    static format(date) {
+        return format(date, "yyyy-MM-dd");
+    }
+}

package/dist/sum.service.d.ts

@@ -0,0 +1,3 @@
+export declare class Sum {
+    static of(values: number[]): number;
+}

package/dist/sum.service.js

@@ -0,0 +1,5 @@
+export class Sum {
+    static of(values) {
+        return values.reduce((sum, x) => sum + x, 0);
+    }
+}

package/dist/thousands-separator.service.d.ts

@@ -0,0 +1,4 @@
+export declare class ThousandsSeparator {
+    private static DEFAULT_SEPARATOR;
+    static format(value: number, separator?: string): string;
+}

package/dist/thousands-separator.service.js

@@ -0,0 +1,6 @@
+export class ThousandsSeparator {
+    static format(value, separator = ThousandsSeparator.DEFAULT_SEPARATOR) {
+        return value.toString().replace(/\B(?=(\d{3})+(?!\d))/g, separator);
+    }
+}
+ThousandsSeparator.DEFAULT_SEPARATOR = " ";

package/dist/visually-unambiguous-characters-generator.service.d.ts

@@ -0,0 +1,4 @@
+export declare class VisuallyUnambiguousCharactersGenerator {
+    static chars: string[];
+    static generate(length?: number): string;
+}

package/dist/visually-unambiguous-characters-generator.service.js

@@ -0,0 +1,35 @@
+import { Random } from "./random.service";
+export class VisuallyUnambiguousCharactersGenerator {
+    static generate(length = 1) {
+        return Array.from({ length })
+            .map(() => VisuallyUnambiguousCharactersGenerator.chars[Random.generate({
+            min: 0,
+            max: VisuallyUnambiguousCharactersGenerator.chars.length - 1,
+        })])
+            .join("");
+    }
+}
+VisuallyUnambiguousCharactersGenerator.chars = [
+    "a",
+    "b",
+    "c",
+    "d",
+    "e",
+    "f",
+    "h",
+    "i",
+    "j",
+    "k",
+    "m",
+    "n",
+    "o",
+    "p",
+    "r",
+    "s",
+    "t",
+    "w",
+    "x",
+    "y",
+    "3",
+    "4",
+];

package/dist/z-score.service.d.ts

@@ -0,0 +1,8 @@
+import { RoundingStrategy } from "./rounding.service";
+export declare class ZScore {
+    private readonly rounding;
+    private readonly mean;
+    private readonly standardDeviation;
+    constructor(values: number[], rounding?: RoundingStrategy);
+    calculate(value: number): number;
+}

package/dist/z-score.service.js

@@ -0,0 +1,16 @@
+import { Mean } from "./mean.service";
+import { PopulationStandardDeviation } from "./population-standard-deviation.service";
+import { RoundToDecimal } from "./rounding.service";
+export class ZScore {
+    constructor(values, rounding = new RoundToDecimal(2)) {
+        this.rounding = rounding;
+        if (values.length < 2) {
+            throw new Error("At least two values are needed");
+        }
+        this.mean = Mean.calculate(values);
+        this.standardDeviation = PopulationStandardDeviation.calculate(values);
+    }
+    calculate(value) {
+        return this.rounding.round((value - this.mean) / this.standardDeviation);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bgord/tools",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "type": "module",
   "license": "MIT",
   "author": "Bartosz Gordon",
@@ -30,7 +30,7 @@
   },
   "dependencies": {
     "date-fns": "4.1.0",
-    "zod": "3.25.46"
+    "zod": "3.25.55"
   },
   "sideEffects": false
 }

package/src/api-key.vo.ts

@@ -1,4 +1,5 @@
 import { z } from "zod/v4";
 
 export const ApiKey = z.string().trim().length(64);
+
 export type ApiKeyType = z.infer<typeof ApiKey>;

package/src/clock.vo.ts

@@ -0,0 +1,67 @@
+import { Hour, HourFormatters } from "./hour.vo";
+import { Minute } from "./minute.vo";
+
+export type ClockFormatter = (hour: Hour, minute: Minute) => string;
+
+enum ClockFormatterEnum {
+  TWENTY_FOUR_HOURS = "TWENTY_FOUR_HOURS",
+  TWELVE_HOURS = "TWELVE_HOURS",
+}
+
+export const ClockFormatters: Record<ClockFormatterEnum, ClockFormatter> = {
+  TWENTY_FOUR_HOURS: (hour, minute) => `${hour.get().formatted}:${minute.get().formatted}`,
+
+  TWELVE_HOURS: (hour, minute) =>
+    `${hour.get(HourFormatters.TWELVE_HOURS).formatted}:${minute.get().formatted}`,
+} as const;
+
+export class Clock {
+  private readonly formatter: ClockFormatter;
+
+  constructor(
+    private readonly hour: Hour,
+    private readonly minute: Minute,
+    formatter?: ClockFormatter,
+  ) {
+    this.formatter = (formatter as ClockFormatter) ?? ClockFormatters.TWENTY_FOUR_HOURS;
+  }
+
+  get(formatter?: ClockFormatter) {
+    const format = formatter ?? this.formatter;
+
+    return {
+      raw: { hour: this.hour.get().raw, minute: this.minute.get().raw },
+      formatted: format(this.hour, this.minute),
+    };
+  }
+
+  equals(another: Clock): boolean {
+    return (
+      this.hour.get().raw === another.get().raw.hour && this.minute.get().raw === another.get().raw.minute
+    );
+  }
+
+  isAfter(another: Clock): boolean {
+    if (this.hour.get().raw > another.hour.get().raw) {
+      return true;
+    }
+
+    if (this.hour.get().raw === another.hour.get().raw && this.minute.get().raw > another.minute.get().raw) {
+      return true;
+    }
+
+    return false;
+  }
+
+  isBefore(another: Clock): boolean {
+    if (this.hour.get().raw < another.hour.get().raw) {
+      return true;
+    }
+
+    if (this.hour.get().raw === another.hour.get().raw && this.minute.get().raw < another.minute.get().raw) {
+      return true;
+    }
+
+    return false;
+  }
+}

package/src/dll.service.ts

@@ -0,0 +1,185 @@
+export class Node<T> {
+  data: T;
+
+  prev: Node<T> | null = null;
+
+  next: Node<T> | null = null;
+
+  constructor(data: Node<T>["data"]) {
+    this.data = data;
+  }
+
+  forward(n: number): Node<T> | null {
+    let currentNode: Node<T> | null = this;
+
+    for (let i = 0; i < n; i++) {
+      if (currentNode === null) {
+        return currentNode;
+      }
+
+      currentNode = currentNode.next;
+    }
+
+    return currentNode;
+  }
+
+  backward(n: number): Node<T> | null {
+    let currentNode: Node<T> | null = this;
+
+    for (let i = 0; i < n; i++) {
+      if (currentNode === null) {
+        return currentNode;
+      }
+
+      currentNode = currentNode.prev;
+    }
+    return currentNode;
+  }
+}
+
+export class DoublyLinkedList<T> {
+  static EMPTY_SIZE = 0;
+
+  private size = DoublyLinkedList.EMPTY_SIZE;
+
+  private head: Node<T> | null = null;
+
+  private tail: Node<T> | null = null;
+
+  getSize(): DoublyLinkedList<T>["size"] {
+    return this.size;
+  }
+
+  isEmpty(): boolean {
+    return this.size === 0;
+  }
+
+  getHead(): DoublyLinkedList<T>["head"] {
+    return this.head;
+  }
+
+  getTail(): DoublyLinkedList<T>["tail"] {
+    return this.tail;
+  }
+
+  append(node: Node<T>): void {
+    if (this.head === null || this.tail === null) {
+      this.size++;
+
+      this.head = node;
+      this.tail = node;
+    } else {
+      this.size++;
+
+      this.tail.next = node;
+      node.prev = this.tail;
+
+      this.tail = node;
+    }
+  }
+
+  prepend(node: Node<T>): void {
+    if (this.head === null || this.tail === null) {
+      this.size++;
+
+      this.head = node;
+      this.tail = node;
+    } else {
+      this.size++;
+
+      node.next = this.head;
+      this.head.prev = node;
+      this.head = node;
+    }
+  }
+
+  clear(): void {
+    this.size = 0;
+
+    this.head = null;
+    this.tail = null;
+  }
+
+  remove(node: Node<T>): void {
+    if (node.prev) {
+      node.prev.next = node.next;
+    } else {
+      this.head = node.next;
+    }
+
+    if (node.next) {
+      node.next.prev = node.prev;
+    } else {
+      this.tail = node.prev;
+    }
+
+    this.size--;
+    node.prev = null;
+    node.next = null;
+  }
+
+  insertAfter(node: Node<T>, target: Node<T>): void {
+    if (target === this.tail) {
+      this.append(node);
+    } else {
+      this.size++;
+
+      node.prev = target;
+      node.next = target.next;
+      // biome-ignore lint: lint/style/noNonNullAssertion
+      target.next!.prev = node;
+      target.next = node;
+    }
+  }
+
+  insertBefore(node: Node<T>, target: Node<T>): void {
+    if (target === this.head) {
+      this.prepend(node);
+    } else {
+      this.size++;
+
+      node.next = target;
+      node.prev = target.prev;
+      // biome-ignore lint: lint/style/noNonNullAssertion
+      target.prev!.next = node;
+      target.prev = node;
+    }
+  }
+
+  find(callback: (node: Node<T>) => boolean): Node<T> | null {
+    return Array.from(this).find(callback) ?? null;
+  }
+
+  reverse(): void {
+    [this.head, this.tail] = [this.tail, this.head];
+
+    // @ts-ignore
+    for (const node of this) {
+      [node.prev, node.next] = [node.next, node.prev];
+    }
+  }
+
+  toArray(): Node<T>[] {
+    return Array.from(this);
+  }
+
+  static fromArray<T>(array: T[]): DoublyLinkedList<T> {
+    const dll = new DoublyLinkedList<T>();
+
+    for (const item of array) {
+      dll.append(new Node<T>(item));
+    }
+
+    return dll;
+  }
+
+  *[Symbol.iterator](): IterableIterator<Node<T>> {
+    let current: Node<T> | null = this.head;
+
+    while (current) {
+      yield current;
+
+      current = current.next;
+    }
+  }
+}

package/src/email-mask.service.ts

@@ -0,0 +1,22 @@
+import { z } from "zod/v4";
+
+export const Email = z.email();
+
+export type EmailType = z.infer<typeof Email>;
+
+export class EmailMask {
+  static censor(email: EmailType): EmailType {
+    const [beforeAt, afterAt] = email.split("@");
+
+    const local = beforeAt as string;
+    const domain = afterAt as string;
+
+    if (local.length <= 2) {
+      return `${"*".repeat(local.length)}@${domain}`;
+    }
+
+    const censoredLocal = `${local.at(0)}${"*".repeat(local.length - 2)}${local.at(-1)}`;
+
+    return `${censoredLocal}@${domain}`;
+  }
+}

package/src/etags.vo.ts

@@ -1,8 +1,8 @@
 import { z } from "zod/v4";
 
-const RevisionValueSchema = z.number().int().min(0);
+const RevisionValue = z.number().int().min(0);
 
-type RevisionValueSchemaType = z.infer<typeof RevisionValueSchema>;
+type RevisionValueType = z.infer<typeof RevisionValue>;
 
 type ETagValueType = string;
 
@@ -13,7 +13,7 @@ export class ETag {
 
   readonly value: ETagValueType;
 
-  private constructor(readonly revision: RevisionValueSchemaType) {
+  private constructor(readonly revision: RevisionValueType) {
     this.value = revision.toString();
   }
 
@@ -36,7 +36,7 @@ export class WeakETag {
 
   readonly value: WeakETagValueType;
 
-  private constructor(readonly revision: RevisionValueSchemaType) {
+  private constructor(readonly revision: RevisionValueType) {
     this.value = `W/${revision.toString()}`;
   }
 

package/src/feature-flag.vo.ts

@@ -0,0 +1,19 @@
+import { z } from "zod/v4";
+
+export enum FeatureFlagEnum {
+  yes = "yes",
+  no = "no",
+}
+export const FeatureFlagValue = z.enum(FeatureFlagEnum);
+
+export type FeatureFlagValueType = z.infer<typeof FeatureFlagValue>;
+
+export class FeatureFlag {
+  static isEnabled(flag: FeatureFlagValueType): boolean {
+    return flag === FeatureFlagEnum.yes;
+  }
+
+  static isDisabled(flag: FeatureFlagValueType): boolean {
+    return flag === FeatureFlagEnum.no;
+  }
+}