@bgord/tools 0.7.0 → 0.9.0

package/dist/size.vo.js

@@ -7,8 +7,14 @@ export var SizeUnit;
     SizeUnit["MB"] = "MB";
     SizeUnit["GB"] = "GB";
 })(SizeUnit || (SizeUnit = {}));
-const SizeValue = z.number().positive();
+const SizeValue = z.number().positive().brand("SizeValue");
 export class Size {
+    unit;
+    value;
+    bytes;
+    static KB_MULTIPLIER = 1024;
+    static MB_MULTIPLIER = 1024 * Size.KB_MULTIPLIER;
+    static GB_MULTIPLIER = 1024 * Size.MB_MULTIPLIER;
     constructor(config) {
         this.unit = config.unit;
         this.value = SizeValue.parse(config.value);
@@ -47,21 +53,18 @@ export class Size {
     static toBytes(config) {
         return new Size(config).toBytes();
     }
+    static unit = SizeUnit;
     calculateBytes(config) {
         switch (config.unit) {
             case SizeUnit.kB:
-                return config.value * Size.KB_MULTIPLIER;
+                return SizeValue.parse(config.value * Size.KB_MULTIPLIER);
             case SizeUnit.MB:
-                return config.value * Size.MB_MULTIPLIER;
+                return SizeValue.parse(config.value * Size.MB_MULTIPLIER);
             case SizeUnit.GB:
-                return config.value * Size.GB_MULTIPLIER;
+                return SizeValue.parse(config.value * Size.GB_MULTIPLIER);
             default:
                 // SizeUnit.b
                 return config.value;
         }
     }
 }
-Size.KB_MULTIPLIER = 1024;
-Size.MB_MULTIPLIER = 1024 * Size.KB_MULTIPLIER;
-Size.GB_MULTIPLIER = 1024 * Size.MB_MULTIPLIER;
-Size.unit = SizeUnit;

package/dist/stepper.service.js

@@ -1,6 +1,8 @@
 export class Stepper {
+    static DEFAULT_CURRENT = 1;
+    current = Stepper.DEFAULT_CURRENT;
+    total;
     constructor(config) {
-        this.current = Stepper.DEFAULT_CURRENT;
         if (!Number.isInteger(config.total)) {
             throw new Error("Total value is not an integer");
         }
@@ -31,4 +33,3 @@ export class Stepper {
         return this.current === this.total;
     }
 }
-Stepper.DEFAULT_CURRENT = 1;

package/dist/stopwatch.service.d.ts

@@ -1,4 +1,4 @@
-import type { TimestampType } from "./timestamp.vo";
+import { TimestampType } from "./timestamp.vo";
 export type StopwatchResultType = {
     durationMs: TimestampType;
 };

package/dist/stopwatch.service.js

@@ -1,19 +1,19 @@
+import { Timestamp } from "./timestamp.vo";
 var StopwatchState;
 (function (StopwatchState) {
     StopwatchState["started"] = "started";
     StopwatchState["stopped"] = "finished";
 })(StopwatchState || (StopwatchState = {}));
 export class Stopwatch {
-    constructor() {
-        this.state = StopwatchState.started;
-        this.startMs = Date.now();
-    }
+    state = StopwatchState.started;
+    startMs = Timestamp.parse(Date.now());
+    stopMs;
     stop() {
         if (this.state === StopwatchState.stopped) {
             throw new Error("Stopwatch is already stopped");
         }
         this.state = StopwatchState.stopped;
-        this.stopMs = Date.now();
-        return { durationMs: this.stopMs - this.startMs };
+        this.stopMs = Timestamp.parse(Date.now());
+        return { durationMs: Timestamp.parse(this.stopMs - this.startMs) };
     }
 }

package/dist/streak-calculator.service.js

@@ -1,5 +1,6 @@
 import { format, isAfter, isEqual, subDays } from "date-fns";
 export class StreakCalculator {
+    cutoff;
     constructor() {
         const today = new Date();
         this.cutoff = StreakCalculator.format(today);

package/dist/thousands-separator.service.js

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

package/dist/time-zone-offset-value.vo.d.ts

@@ -1,3 +1,3 @@
 import { z } from "zod/v4";
-export declare const TimeZoneOffsetValue: z.ZodPipe<z.ZodPipe<z.ZodUnion<[z.ZodString, z.ZodUndefined]>, z.ZodTransform<number, string | undefined>>, z.ZodTransform<number, number>>;
+export declare const TimeZoneOffsetValue: z.core.$ZodBranded<z.ZodPipe<z.ZodPipe<z.ZodUnion<[z.ZodString, z.ZodUndefined]>, z.ZodTransform<number, string | undefined>>, z.ZodTransform<number, number>>, "TimeZoneOffsetValue">;
 export type TimeZoneOffsetValueType = z.infer<typeof TimeZoneOffsetValue>;

package/dist/time-zone-offset-value.vo.js

@@ -4,4 +4,5 @@ export const TimeZoneOffsetValue = z
     .trim()
     .or(z.undefined())
     .transform((value) => Number(value))
-    .transform((value) => (Number.isNaN(value) ? 0 : value));
+    .transform((value) => (Number.isNaN(value) ? 0 : value))
+    .brand("TimeZoneOffsetValue");

package/dist/time.service.js

@@ -1,6 +1,11 @@
 import { RoundToDecimal } from "./rounding.service";
 const rounding = new RoundToDecimal(2);
 export class TimeResult {
+    days;
+    hours;
+    minutes;
+    seconds;
+    ms;
     constructor(days, hours, minutes, seconds, ms) {
         this.days = days;
         this.hours = hours;

package/dist/timestamp.vo.d.ts

@@ -1,3 +1,3 @@
 import { z } from "zod/v4";
-export declare const Timestamp: z.ZodDefault<z.ZodNumber>;
+export declare const Timestamp: z.core.$ZodBranded<z.ZodDefault<z.ZodNumber>, "Timestamp">;
 export type TimestampType = z.infer<typeof Timestamp>;

package/dist/timestamp.vo.js

@@ -3,4 +3,5 @@ export const Timestamp = z
     .number()
     .int()
     .positive()
-    .default(() => Date.now());
+    .default(() => Date.now())
+    .brand("Timestamp");

package/dist/timezone.vo.d.ts

@@ -1,3 +1,3 @@
 import { z } from "zod/v4";
-export declare const Timezone: z.ZodString;
+export declare const Timezone: z.core.$ZodBranded<z.ZodString, "Timezone">;
 export type TimezoneType = z.infer<typeof Timezone>;

package/dist/timezone.vo.js

@@ -16,4 +16,5 @@ export const Timezone = z
         // An error occurred, indicating an invalid timezone
         return false;
     }
-}, { message: "timezone.invalid" });
+}, { message: "timezone.invalid" })
+    .brand("Timezone");

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

@@ -1,5 +1,29 @@
 import { Random } from "./random.service";
 export class VisuallyUnambiguousCharactersGenerator {
+    static chars = [
+        "a",
+        "b",
+        "c",
+        "d",
+        "e",
+        "f",
+        "h",
+        "i",
+        "j",
+        "k",
+        "m",
+        "n",
+        "o",
+        "p",
+        "r",
+        "s",
+        "t",
+        "w",
+        "x",
+        "y",
+        "3",
+        "4",
+    ];
     static generate(length = 1) {
         return Array.from({ length })
             .map(() => VisuallyUnambiguousCharactersGenerator.chars[Random.generate({
@@ -9,27 +33,3 @@ export class VisuallyUnambiguousCharactersGenerator {
             .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.js

@@ -2,6 +2,9 @@ import { Mean } from "./mean.service";
 import { PopulationStandardDeviation } from "./population-standard-deviation.service";
 import { RoundToDecimal } from "./rounding.service";
 export class ZScore {
+    rounding;
+    mean;
+    standardDeviation;
     constructor(values, rounding = new RoundToDecimal(2)) {
         this.rounding = rounding;
         if (values.length < 2) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bgord/tools",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "type": "module",
   "license": "MIT",
   "author": "Bartosz Gordon",
@@ -14,14 +14,14 @@
   },
   "files": ["dist", "src"],
   "scripts": {
-    "build": "tsc --build",
+    "build": "rm -rf dist/ && tsc --build",
     "preinstall": "bunx only-allow bun"
   },
   "devDependencies": {
     "@biomejs/biome": "1.9.4",
     "@commitlint/cli": "19.8.1",
     "@commitlint/config-conventional": "19.8.1",
-    "@types/bun": "1.2.15",
+    "@types/bun": "1.2.16",
     "cspell": "9.0.2",
     "lefthook": "1.11.13",
     "only-allow": "1.2.1",
@@ -30,7 +30,7 @@
   },
   "dependencies": {
     "date-fns": "4.1.0",
-    "zod": "3.25.55"
+    "zod": "3.25.64"
   },
   "sideEffects": false
 }

package/readme.md

@@ -0,0 +1 @@
+# @bgord/tools

package/src/api-key.vo.ts

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

package/src/build-version.vo.ts

@@ -1,5 +1,5 @@
 import { z } from "zod/v4";
 
-export const BuildVersion = z.string().min(1).max(8);
+export const BuildVersion = z.string().min(1).max(8).brand("BuildVersion");
 
 export type BuildVersionType = z.infer<typeof BuildVersion>;

package/src/email-mask.service.ts

@@ -1,11 +1,13 @@
 import { z } from "zod/v4";
 
-export const Email = z.email();
+export const Email = z.email().brand("Email");
 
 export type EmailType = z.infer<typeof Email>;
 
+type EmailMaskedType = string;
+
 export class EmailMask {
-  static censor(email: EmailType): EmailType {
+  static censor(email: EmailType): EmailMaskedType {
     const [beforeAt, afterAt] = email.split("@");
 
     const local = beforeAt as string;

package/src/etags.vo.ts

@@ -1,6 +1,6 @@
 import { z } from "zod/v4";
 
-const RevisionValue = z.number().int().min(0);
+const RevisionValue = z.number().int().min(0).brand("RevisionValue");
 
 type RevisionValueType = z.infer<typeof RevisionValue>;
 
@@ -23,7 +23,7 @@ export class ETag {
     const candidate = Number(value);
 
     if (Number.isNaN(candidate)) return null;
-    return new ETag(candidate);
+    return new ETag(RevisionValue.parse(candidate));
   }
 }
 
@@ -46,6 +46,6 @@ export class WeakETag {
     const candidate = Number(value.split("W/")[1]);
 
     if (Number.isNaN(candidate)) return null;
-    return new WeakETag(candidate);
+    return new WeakETag(RevisionValue.parse(candidate));
   }
 }

package/src/iban.vo.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+
+// Basic IBAN format regex (2-letter country code + 2 digits + 11–30 alphanumerics)
+const IBAN_REGEX = /^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,30}$/;
+
+const IBANValueSchema = z
+  .string()
+  .transform((val) => val.replace(/\s+/g, "").toUpperCase())
+  .refine((iban) => IBAN_REGEX.test(iban), {
+    message: "invalid.iban.format",
+  });
+
+type IBANValueType = z.infer<typeof IBANValueSchema>;
+
+type IBANCountryCode = string;
+
+export class IBAN {
+  private readonly value: IBANValueType;
+
+  constructor(value: string) {
+    this.value = IBANValueSchema.parse(value);
+  }
+
+  toString(): IBANValueType {
+    return this.value;
+  }
+
+  format(): string {
+    return this.value.replace(/(.{4})(?=.)/g, "$1 ");
+  }
+
+  get countryCode(): IBANCountryCode {
+    return this.value.slice(0, 2);
+  }
+
+  equals(other: IBAN): boolean {
+    return this.value === other.value;
+  }
+}

package/src/image.vo.ts

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

package/src/index.ts

@@ -10,6 +10,7 @@ export * from "./etags.vo";
 export * from "./feature-flag.vo";
 export * from "./filter.vo";
 export * from "./hour.vo";
+export * from "./iban.vo";
 export * from "./image.vo";
 export * from "./language.vo";
 export * from "./leap-year-checker.service";

package/src/language.vo.ts

@@ -3,6 +3,7 @@ import { z } from "zod/v4";
 export const Language = z
   .string()
   .length(2)
-  .regex(/^[a-z]{2}$/, { message: "invalid_language" });
+  .regex(/^[a-z]{2}$/, { message: "invalid_language" })
+  .brand("Language");
 
 export type LanguageType = z.infer<typeof Language>;

package/src/money.vo.ts

@@ -5,20 +5,23 @@ import { RoundToNearest, RoundingStrategy } from "./rounding.service";
 export const MoneyAmount = z
   .number()
   .int({ message: "money.amount.invalid " })
-  .min(0, { message: "money.amount.invalid " });
+  .min(0, { message: "money.amount.invalid " })
+  .brand("MoneyAmount");
 
 export type MoneyAmountType = z.infer<typeof MoneyAmount>;
 
 export const MoneyMultiplicationFactor = z
   .number()
-  .min(0, { message: "money.multiplication-factor.invalid" });
+  .min(0, { message: "money.multiplication-factor.invalid" })
+  .brand("MoneyMultiplicationFactor");
 
 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" });
+  .refine((value) => value !== 0, { message: "money.division-factor.invalid" })
+  .brand("MoneyDivisionFactor");
 
 export type MoneyDivisionFactorType = z.infer<typeof MoneyDivisionFactor>;
 

package/src/package-version.vo.ts

@@ -57,7 +57,8 @@ export const PackageVersionValue = z
       minor: Number(minor),
       patch: Number(patch),
     };
-  });
+  })
+  .brand("PackageVersionValue");
 export type PackageVersionValueType = z.infer<typeof PackageVersionValue>;
 
 export class PackageVersion {

package/src/pagination.service.ts

@@ -1,10 +1,10 @@
 import { z } from "zod/v4";
 
-const Take = z.number().int().positive();
+const Take = z.number().int().gte(0).brand("Take");
 
 type TakeType = z.infer<typeof Take>;
 
-const Skip = z.number().int().positive();
+const Skip = z.number().int().gte(0).brand("Skip");
 
 type SkipType = z.infer<typeof Skip>;
 
@@ -12,7 +12,8 @@ const Page = z.coerce
   .number()
   .int()
   .transform((value) => (value <= 0 ? 1 : value))
-  .default(1);
+  .default(1)
+  .brand("Page");
 
 export type PageType = z.infer<typeof Page>;
 
@@ -43,7 +44,7 @@ export class Pagination {
     const page = Page.parse(values.page);
     const take = Take.parse(_take);
 
-    const skip = (page - 1) * take;
+    const skip = Skip.parse((page - 1) * take);
 
     return { values: { take, skip }, page };
   }
@@ -54,8 +55,8 @@ export class Pagination {
     const currentPage = config.pagination.page;
     const lastPage = Pagination.getLastPage(config);
 
-    const previousPage = currentPage > 1 ? currentPage - 1 : undefined;
-    const nextPage = currentPage < lastPage ? currentPage + 1 : undefined;
+    const previousPage = currentPage > 1 ? Page.parse(currentPage - 1) : undefined;
+    const nextPage = currentPage < lastPage ? Page.parse(currentPage + 1) : undefined;
 
     return {
       result: config.result,
@@ -78,7 +79,9 @@ export class Pagination {
   }
 
   private static getLastPage(config: PaginationExhaustedConfig): PageType {
-    return Math.ceil(config.total / config.pagination.values.take);
+    const lastPage = Math.ceil(config.total / config.pagination.values.take);
+
+    return Page.parse(lastPage);
   }
 
   static empty = {
@@ -94,7 +97,7 @@ export class Pagination {
   };
 
   static getFirstPage({ take }: { take: TakeType }): PaginationType {
-    return { values: { take, skip: 0 }, page: 1 };
+    return { values: { take, skip: Skip.parse(0) }, page: Page.parse(1) };
   }
 }
 

package/src/rate-limiter.service.ts

@@ -1,4 +1,4 @@
-import type { TimestampType } from "./timestamp.vo";
+import { Timestamp, TimestampType } from "./timestamp.vo";
 import type { Falsy } from "./ts-utils";
 
 type RateLimiterOptionsType = { ms: TimestampType };
@@ -34,7 +34,7 @@ export class RateLimiter {
 
     return {
       allowed: false,
-      remainingMs: nextAllowedTimestampMs - currentTimestampMs,
+      remainingMs: Timestamp.parse(nextAllowedTimestampMs - currentTimestampMs),
     };
   }
 }

package/src/reordering.service.ts

@@ -2,15 +2,15 @@ import { z } from "zod/v4";
 
 import { DoublyLinkedList, Node } from "./dll.service";
 
-export const ReorderingItemPositionValue = z.number().int().min(0);
+export const ReorderingItemPositionValue = z.number().int().min(0).brand("ReorderingItemPositionValue");
 
 export type ReorderingItemPositionValueType = z.infer<typeof ReorderingItemPositionValue>;
 
-export const ReorderingCorrelationId = z.string().min(1);
+export const ReorderingCorrelationId = z.string().min(1).brand("ReorderingCorrelationId");
 
 export type ReorderingCorrelationIdType = z.infer<typeof ReorderingCorrelationId>;
 
-export const ReorderingItemId = z.uuid();
+export const ReorderingItemId = z.uuid().brand("ReorderingItemId");
 
 export type ReorderingItemIdType = z.infer<typeof ReorderingItemId>;
 
@@ -99,7 +99,7 @@ export class ReorderingCalculator {
   }
 
   add(id: ReorderingItem["id"]): ReorderingItem {
-    const position = new ReorderingPosition(this.dll.getSize());
+    const position = new ReorderingPosition(ReorderingItemPositionValue.parse(this.dll.getSize()));
     const item = new ReorderingItem(id, position);
     this.dll.append(new Node(item));
     return item;
@@ -155,10 +155,11 @@ export class ReorderingCalculator {
 export class ReorderingIntegrator {
   static appendPosition(reordering: ReorderingType[]) {
     return function <T extends { id: ReorderingItemIdType }>(item: T): WithReorderingPositionValue<T> {
-      return {
-        ...item,
-        position: reordering.find((x) => x.id === item.id)?.position ?? 0,
-      };
+      const position = ReorderingItemPositionValue.parse(
+        reordering.find((x) => x.id === item.id)?.position ?? 0,
+      );
+
+      return { ...item, position };
     };
   }
 

package/src/revision.vo.ts

@@ -2,14 +2,14 @@ import { z } from "zod/v4";
 
 import { ETag, WeakETag } from "./etags.vo";
 
-export const RevisionValue = z.number().int().min(0);
+export const RevisionValue = z.number().int().min(0).brand("RevisionValue");
 
 export type RevisionValueType = z.infer<typeof RevisionValue>;
 
 export class Revision {
   readonly value: RevisionValueType;
 
-  static initial: RevisionValueType = 0;
+  static initial: RevisionValueType = RevisionValue.parse(0);
 
   constructor(value: unknown) {
     const result = RevisionValue.safeParse(value);

package/src/size.vo.ts

@@ -9,7 +9,7 @@ export enum SizeUnit {
   GB = "GB",
 }
 
-const SizeValue = z.number().positive();
+const SizeValue = z.number().positive().brand("SizeValue");
 
 export type SizeValueType = z.infer<typeof SizeValue>;
 
@@ -81,11 +81,11 @@ export class Size {
   private calculateBytes(config: SizeConfigType): SizeValueType {
     switch (config.unit) {
       case SizeUnit.kB:
-        return config.value * Size.KB_MULTIPLIER;
+        return SizeValue.parse(config.value * Size.KB_MULTIPLIER);
       case SizeUnit.MB:
-        return config.value * Size.MB_MULTIPLIER;
+        return SizeValue.parse(config.value * Size.MB_MULTIPLIER);
       case SizeUnit.GB:
-        return config.value * Size.GB_MULTIPLIER;
+        return SizeValue.parse(config.value * Size.GB_MULTIPLIER);
       default:
         // SizeUnit.b
         return config.value;

package/src/stopwatch.service.ts

@@ -1,4 +1,4 @@
-import type { TimestampType } from "./timestamp.vo";
+import { Timestamp, TimestampType } from "./timestamp.vo";
 import type { Falsy } from "./ts-utils";
 
 enum StopwatchState {
@@ -11,7 +11,7 @@ export type StopwatchResultType = { durationMs: TimestampType };
 export class Stopwatch {
   private state: StopwatchState = StopwatchState.started;
 
-  private readonly startMs: TimestampType = Date.now();
+  private readonly startMs: TimestampType = Timestamp.parse(Date.now());
 
   private stopMs: Falsy<TimestampType>;
 
@@ -21,8 +21,8 @@ export class Stopwatch {
     }
 
     this.state = StopwatchState.stopped;
-    this.stopMs = Date.now();
+    this.stopMs = Timestamp.parse(Date.now());
 
-    return { durationMs: this.stopMs - this.startMs };
+    return { durationMs: Timestamp.parse(this.stopMs - this.startMs) };
   }
 }

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

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

package/src/timestamp.vo.ts

@@ -4,6 +4,7 @@ export const Timestamp = z
   .number()
   .int()
   .positive()
-  .default(() => Date.now());
+  .default(() => Date.now())
+  .brand("Timestamp");
 
 export type TimestampType = z.infer<typeof Timestamp>;

package/src/timezone.vo.ts

@@ -21,6 +21,7 @@ export const Timezone = z
       }
     },
     { message: "timezone.invalid" },
-  );
+  )
+  .brand("Timezone");
 
 export type TimezoneType = z.infer<typeof Timezone>;