@bgord/tools 0.17.2 → 1.0.0

package/src/month.vo.ts

@@ -1,46 +1,47 @@
+import { endOfMonth, format, getMonth, setMonth, 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());
 
-  previous(): Month {
-    return Month.fromTimestamp(Timestamp.parse(this.getStart() - 1));
+    return new Month(start, end);
   }
 
-  next(): Month {
-    return Month.fromTimestamp(Timestamp.parse(this.getEnd() + 1));
+  static fromNow(now: TimestampType): Month {
+    return Month.fromTimestamp(now);
   }
 
-  shift(count: number): Month {
-    const date = new Date(this.getStart());
-    date.setUTCMonth(date.getUTCMonth() + count);
+  static fromIsoId(iso: MonthIsoIdType): Month {
+    const [year, month] = MonthIsoId.parse(iso).split("-").map(Number);
+
+    const reference = setMonth(Date.UTC(year), month - 1).getTime();
 
-    return Month.fromTimestamp(Timestamp.parse(date.getTime()));
+    return Month.fromTimestamp(Timestamp.parse(reference));
   }
 
-  static fromTimestamp(timestamp: TimestampType): Month {
-    const isoMonth = new Date(timestamp).toISOString().slice(0, 7) as MonthIsoIdType;
+  toIsoId(): MonthIsoIdType {
+    return MonthIsoId.parse(format(this.getStart(), "yyyy-MM"));
+  }
 
-    return Month.fromIsoId(isoMonth);
+  previous(): Month {
+    return this.shift(-1);
   }
 
-  static fromNow(now: TimestampType): Month {
-    return Month.fromTimestamp(now);
+  next(): Month {
+    return this.shift(1);
   }
 
-  static fromIsoId(iso: MonthIsoIdType): Month {
-    const validated = MonthIsoId.parse(iso);
-    const year = Number(validated.slice(0, 4));
-    const monthIndex = Number(validated.slice(5, 7)) - 1;
+  shift(count: number): Month {
+    const shifted = setMonth(this.getStart(), getMonth(this.getStart()) + count).getTime();
 
-    const startUtc = Date.UTC(year, monthIndex, 1);
-    const nextStartUtc = Date.UTC(year, monthIndex + 1, 1);
-    const endUtc = nextStartUtc - 1;
+    return Month.fromTimestamp(Timestamp.parse(shifted));
+  }
 
-    return new Month(Timestamp.parse(startUtc), Timestamp.parse(endUtc));
+  toString(): string {
+    return this.toIsoId();
   }
 }

package/src/multiplication-factor.vo.ts

@@ -0,0 +1,13 @@
+import { z } from "zod/v4";
+
+export const MultiplicationFactorError = {
+  Type: "multiplication.factor.type",
+  Invalid: "multiplication.factor.invalid",
+} as const;
+
+export const MultiplicationFactor = z
+  .number(MultiplicationFactorError.Type)
+  .min(0, MultiplicationFactorError.Invalid)
+  .brand("MultiplicationFactor");
+
+export type MultiplicationFactorType = z.infer<typeof MultiplicationFactor>;

package/src/object-key.vo.ts

@@ -1,30 +1,34 @@
 import { z } from "zod/v4";
 
-export const ObjectKeyMustNotStartWithSlashError = "obj_key_must_not_start_with_slash" as const;
-export const ObjectKeyBackslashForbiddenError = "obj_key_backslash_forbidden" as const;
-export const ObjectKeyControlCharsForbiddenError = "obj_key_control_chars_forbidden" as const;
-export const ObjectKeyEmptyError = "obj_key_empty" as const;
-export const ObjectKeyBadSegmentsError = "obj_key_bad_segments" as const;
+export const ObjectKeyError = {
+  Type: "object.key.type",
+  LeadingSlash: "object.key.leading.slash",
+  Empty: "object.key.empty",
+  TooLong: "object.key.too.long",
+  BadChars: "object.key.bad.chars",
+  DotSegments: "object.key.dot.segments",
+} as const;
 
-// biome-ignore lint: lint/suspicious/noControlCharactersInRegex
-const CONTROL_CHARS_REGEX = /[\u0000-\u001F\u007F]/;
-const SEGMENT_ALLOWED_REGEX = /^[a-z0-9._-]+$/;
+// Lowercase letters, digits, dots, underscores, and hyphens
+const OBJECT_KEY_SEGMENT_CHARS_WHITELIST = /^[a-z0-9._-]+$/;
+
+const DOT_SEGMENTS = [".", ".."];
 
 export const ObjectKey = z
-  .string()
-  .trim()
-  // fastest early exits first:
-  .refine((value) => value.length > 0, ObjectKeyEmptyError)
-  .refine((value) => !value.startsWith("/"), ObjectKeyMustNotStartWithSlashError)
-  .refine((value) => !value.includes("\\"), ObjectKeyBackslashForbiddenError)
-  .refine((value) => !CONTROL_CHARS_REGEX.test(value), ObjectKeyControlCharsForbiddenError)
+  .string(ObjectKeyError.Type)
+  .min(1, ObjectKeyError.Empty)
+  .max(256, ObjectKeyError.TooLong)
+  .refine((value) => !value.startsWith("/"), ObjectKeyError.LeadingSlash)
+  // Allow only known characters for users/avatars/1234567890/avatar.png segments
+  .refine(
+    (value) => value.split("/").every((segment) => OBJECT_KEY_SEGMENT_CHARS_WHITELIST.test(segment)),
+    ObjectKeyError.BadChars,
+  )
+  // Reject object keys like users/./avatar.png or users/../avatar.png
   .refine(
-    (value) =>
-      value
-        .split("/")
-        .every((segment) => SEGMENT_ALLOWED_REGEX.test(segment) && segment !== "." && segment !== ".."),
-    ObjectKeyBadSegmentsError,
+    (value) => value.split("/").every((segment) => !DOT_SEGMENTS.includes(segment)),
+    ObjectKeyError.DotSegments,
   )
-  .brand("object_key");
+  .brand("ObjectKey");
 
 export type ObjectKeyType = z.infer<typeof ObjectKey>;

package/src/outlier-detector.service.ts

@@ -1,13 +1,13 @@
 import { ZScore } from "./z-score.service";
 
-export const OutlierDetectorMinValuesError = "outlier.detector.min.values" as const;
+export const OutlierDetectorError = { NotEnoughValues: "outlier.detector.not.enough.values" } as const;
 
 export class OutlierDetector {
   private readonly zScore: ZScore;
   private readonly threshold: number;
 
   constructor(values: number[], threshold: number) {
-    if (values.length < 2) throw new Error(OutlierDetectorMinValuesError);
+    if (values.length < 2) throw new Error(OutlierDetectorError.NotEnoughValues);
 
     this.zScore = new ZScore(values);
     this.threshold = Math.abs(threshold);

package/src/package-version-schema.vo.ts

@@ -0,0 +1,21 @@
+import { z } from "zod/v4";
+
+export const PackageVersionSchemaError = {
+  Type: "package.version.schema.error",
+  BadChars: "package.version.schema.bad.chars",
+} as const;
+
+// v, 1-4 digits, dot, 1-4 digits, dot, 1-4 digits - () for capturing groups
+const PACKAGE_VERSIONS_CHARS_WHITELIST = /^v([0-9]{1,4})\.([0-9]{1,4})\.([0-9]{1,4})$/;
+
+export const PackageVersionSchema = z
+  .string(PackageVersionSchemaError.Type)
+  .regex(PACKAGE_VERSIONS_CHARS_WHITELIST, PackageVersionSchemaError.BadChars)
+  .transform((value) => {
+    const match = PACKAGE_VERSIONS_CHARS_WHITELIST.exec(value)!;
+
+    return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) };
+  })
+  .brand("PackageVersionSchema");
+
+export type PackageVersionSchemaType = z.infer<typeof PackageVersionSchema>;

package/src/package-version.vo.ts

@@ -1,33 +1,23 @@
-import { z } from "zod/v4";
+import { PackageVersionSchema } from "./package-version-schema.vo";
 
-type MajorType = number;
-type MinorType = number;
-type PatchType = number;
-
-export const PackageVersionError = { error: "package.version.error" } as const;
-
-export const PackageVersionValue = z
-  .string(PackageVersionError)
-  .regex(/^v(\d+)\.(\d+)\.(\d+)$/, PackageVersionError)
-  .transform((value) => {
-    const match = /^v(\d+)\.(\d+)\.(\d+)$/.exec(value)!;
+export class PackageVersion {
+  constructor(
+    private readonly major: number,
+    private readonly minor: number,
+    private readonly patch: number,
+  ) {}
 
-    const major = Number(match[1]);
-    const minor = Number(match[2]);
-    const patch = Number(match[3]);
+  static fromStringWithV(candidate: string): PackageVersion {
+    const version = PackageVersionSchema.parse(candidate);
 
-    return { major, minor, patch };
-  })
-  .brand("PackageVersionValue");
+    return new PackageVersion(version.major, version.minor, version.patch);
+  }
 
-export type PackageVersionValueType = z.infer<typeof PackageVersionValue>;
+  static fromString(candidate: string): PackageVersion {
+    const version = PackageVersionSchema.parse(`v${candidate}`);
 
-export class PackageVersion {
-  constructor(
-    readonly major: MajorType,
-    readonly minor: MinorType,
-    readonly patch: PatchType,
-  ) {}
+    return new PackageVersion(version.major, version.minor, version.patch);
+  }
 
   isGreaterThanOrEqual(another: PackageVersion): boolean {
     if (this.major > another.major) return true;
@@ -46,13 +36,7 @@ export class PackageVersion {
     return `${this.major}.${this.minor}.${this.patch}`;
   }
 
-  static fromStringWithV(value: string): PackageVersion {
-    const parsed = PackageVersionValue.parse(value);
-    return new PackageVersion(parsed.major, parsed.minor, parsed.patch);
-  }
-
-  static fromString(value: string): PackageVersion {
-    const parsed = PackageVersionValue.parse(`v${value}`);
-    return new PackageVersion(parsed.major, parsed.minor, parsed.patch);
+  toJSON(): { major: number; minor: number; patch: number } {
+    return { major: this.major, minor: this.minor, patch: this.patch };
   }
 }

package/src/pagination-page.vo.ts

@@ -0,0 +1,11 @@
+import { z } from "zod/v4";
+
+export const PaginationPageError = { Type: "pagination.page.Type" } as const;
+
+export const Page = z.coerce
+  .number(PaginationPageError.Type)
+  .int(PaginationPageError.Type)
+  .transform((value) => (value <= 0 ? 1 : value))
+  .default(1);
+
+export type PageType = z.infer<typeof Page>;

package/src/pagination-skip.vo.ts

@@ -0,0 +1,13 @@
+import { z } from "zod/v4";
+
+export const PaginationSkipError = {
+  Type: "pagination.skip.type",
+  Invalid: "pagination.skip.invalid",
+} as const;
+
+export const Skip = z
+  .number(PaginationSkipError.Type)
+  .int(PaginationSkipError.Type)
+  .gte(0, PaginationSkipError.Invalid);
+
+export type SkipType = z.infer<typeof Skip>;

package/src/pagination-take.vo.ts

@@ -0,0 +1,13 @@
+import { z } from "zod/v4";
+
+export const PaginationTakeError = {
+  Type: "pagination.take.type",
+  Invalid: "pagination.take.invalid",
+} as const;
+
+export const Take = z
+  .number(PaginationTakeError.Type)
+  .int(PaginationTakeError.Type)
+  .gte(1, PaginationTakeError.Invalid);
+
+export type TakeType = z.infer<typeof Take>;

package/src/pagination.service.ts

@@ -1,24 +1,7 @@
-import { z } from "zod/v4";
-
-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(PaginationSkipError).int(PaginationSkipError).gte(0, PaginationSkipError);
-
-type SkipType = z.infer<typeof Skip>;
-
-const Page = z.coerce
-  .number(PaginationPageError)
-  .int(PaginationPageError)
-  .transform((value) => (value <= 0 ? 1 : value))
-  .default(1);
-
-export type PageType = z.infer<typeof Page>;
+import { Page, type PageType } from "./pagination-page.vo";
+import { Skip, type SkipType } from "./pagination-skip.vo";
+import { Take, type TakeType } from "./pagination-take.vo";
+import { RoundUp } from "./rounding.adapter";
 
 export type PaginationType = { values: { take: TakeType; skip: SkipType }; page: PageType };
 export type PaginationValuesType = Record<string, unknown>;
@@ -57,7 +40,7 @@ export class Pagination {
   }
 
   private static getLastPage(config: PaginationExhaustedConfig): PageType {
-    return Page.parse(Math.ceil(config.total / config.pagination.values.take));
+    return Page.parse(new RoundUp().round(config.total / config.pagination.values.take));
   }
 
   static empty = {

package/src/percentage.service.ts

@@ -1,11 +1,11 @@
 import { RoundToNearest } from "./rounding.adapter";
 import type { RoundingPort } from "./rounding.port";
 
-export const PercentageInvalidDenominatorError = "percentage.invalid.denominator" as const;
+export const PercentageError = { InvalidDenominator: "percentage.invalid.denominator" } as const;
 
 export class Percentage {
   static of(numerator: number, denominator: number, rounding: RoundingPort = new RoundToNearest()): number {
-    if (denominator === 0) throw new Error(PercentageInvalidDenominatorError);
+    if (denominator === 0) throw new Error(PercentageError.InvalidDenominator);
     if (numerator === 0) return 0;
     return rounding.round((numerator / denominator) * 100);
   }

package/src/population-standard-deviation.service.ts

@@ -3,19 +3,20 @@ import { RoundToDecimal } from "./rounding.adapter";
 import type { RoundingPort } from "./rounding.port";
 import { Sum } from "./sum.service";
 
-export const PopulationStandardDeviationMinValuesError = "population.standard.deviation.min.values" as const;
+export const PopulationStandardDeviationError = {
+  NotEnoughValues: "population.standard.deviation.not.enough.values",
+} as const;
 
 export class PopulationStandardDeviation {
   static calculate(values: number[], rounding: RoundingPort = new RoundToDecimal(2)): number {
-    if (values.length < 2) throw new Error(PopulationStandardDeviationMinValuesError);
+    if (values.length < 2) throw new Error(PopulationStandardDeviationError.NotEnoughValues);
 
     const mean = Mean.calculate(values);
     const count = values.length;
 
     const squaredDifferences = values.map((value) => (value - mean) ** 2);
-    const sumOfSquaredDifferences = Sum.of(squaredDifferences);
 
-    const variance = sumOfSquaredDifferences / count;
+    const variance = Sum.of(squaredDifferences) / count;
 
     return rounding.round(Math.sqrt(variance));
   }

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

@@ -1,16 +1,13 @@
 import { z } from "zod/v4";
 
-export const QuarterIsoIdError = { error: "quarter-iso-id.invalid" } as const;
+export const QuarterIsoIdError = {
+  Type: "quarter.iso.id.type",
+  BadChars: "quarter.iso.id.bad.chars",
+} as const;
 
 export const QuarterIsoId = z
-  .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);
+  .string(QuarterIsoIdError.Type)
+  .regex(/^\d{4}-Q[1-4]$/, QuarterIsoIdError.BadChars)
+  .brand("QuarterIsoId");
 
 export type QuarterIsoIdType = z.infer<typeof QuarterIsoId>;

package/src/quarter.vo.ts

@@ -4,13 +4,6 @@ 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());
@@ -24,8 +17,20 @@ 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()));
+    const reference = setQuarter(Date.UTC(year), quarter).getTime();
+
+    return Quarter.fromTimestamp(Timestamp.parse(reference));
+  }
+
+  toIsoId(): QuarterIsoIdType {
+    const year = getYear(this.getStart());
+    const quarter = getQuarter(this.getStart());
+
+    return QuarterIsoId.parse(`${year}-Q${quarter}`);
+  }
+
+  toString(): string {
+    return this.toIsoId();
   }
 }

package/src/random.service.ts

@@ -1,9 +1,8 @@
+import { RoundDown } from "./rounding.adapter";
+
 type RandomGenerateConfigType = { min: number; max: number };
 
-export const RandomMinNotIntegerError = "random.min.not.integer" as const;
-export const RandomMaxNotIntegerError = "random.max.not.integer" as const;
-export const RandomMinEqualsMaxError = "random.min.equals.max" as const;
-export const RandomMinGreaterThanMaxError = "random.min.greater.than.max" as const;
+export const RandomError = { MinMax: "random.min.max" } as const;
 
 export class Random {
   private static readonly DEFAULT_MIN = 0;
@@ -13,11 +12,9 @@ export class Random {
     const min = config ? config.min : Random.DEFAULT_MIN;
     const max = config ? config.max : Random.DEFAULT_MAX;
 
-    if (!Number.isInteger(min)) throw new Error(RandomMinNotIntegerError);
-    if (!Number.isInteger(max)) throw new Error(RandomMaxNotIntegerError);
-    if (min === max) throw new Error(RandomMinEqualsMaxError);
-    if (min > max) throw new Error(RandomMinGreaterThanMaxError);
+    if (min === max) throw new Error(RandomError.MinMax);
+    if (min > max) throw new Error(RandomError.MinMax);
 
-    return Math.floor(Math.random() * (max - min + 1)) + min;
+    return new RoundDown().round(Math.random() * (max - min + 1)) + min;
   }
 }

package/src/rate-limiter.service.ts

@@ -6,25 +6,26 @@ type RateLimiterResultErrorType = { allowed: false; remaining: Duration };
 type RateLimiterResultType = RateLimiterResultSuccessType | RateLimiterResultErrorType;
 
 export class RateLimiter {
-  private lastInvocationTimestampMs: TimestampType | null = null;
+  private lastInvocation: TimestampType | null = null;
 
   constructor(private readonly duration: Duration) {}
 
-  verify(currentTimestampMs: TimestampType): RateLimiterResultType {
-    if (this.lastInvocationTimestampMs == null) {
-      this.lastInvocationTimestampMs = currentTimestampMs;
+  verify(now: TimestampType): RateLimiterResultType {
+    if (this.lastInvocation == null) {
+      this.lastInvocation = now;
 
       return { allowed: true };
     }
 
-    const nextAllowedTimestampMs = this.lastInvocationTimestampMs + this.duration.ms;
+    const nextAllowedTimestamp = this.lastInvocation + this.duration.ms;
+
+    if (nextAllowedTimestamp <= now) {
+      this.lastInvocation = now;
 
-    if (nextAllowedTimestampMs <= currentTimestampMs) {
-      this.lastInvocationTimestampMs = currentTimestampMs;
       return { allowed: true };
     }
 
-    const remainingDelta = nextAllowedTimestampMs - currentTimestampMs;
+    const remainingDelta = nextAllowedTimestamp - now;
 
     return { allowed: false, remaining: Duration.Ms(remainingDelta) };
   }

package/src/reordering-item-position-value.vo.ts

@@ -0,0 +1,10 @@
+import { z } from "zod/v4";
+
+export const ReorderingItemPositionValueError = { Invalid: "reordering.position.type" } as const;
+
+export const ReorderingItemPositionValue = z
+  .number(ReorderingItemPositionValueError.Invalid)
+  .int(ReorderingItemPositionValueError.Invalid)
+  .min(0, ReorderingItemPositionValueError.Invalid);
+
+export type ReorderingItemPositionValueType = z.infer<typeof ReorderingItemPositionValue>;

package/src/reordering.service.ts

@@ -1,30 +1,24 @@
 import { z } from "zod/v4";
 import { DoublyLinkedList, Node } from "./dll.service";
+import {
+  ReorderingItemPositionValue,
+  type ReorderingItemPositionValueType,
+} from "./reordering-item-position-value.vo";
 
-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 ReorderingError = {
+  CannotFindItem: "reordering.cannot.find.item",
+  CannotFindCurrent: "reordering.cannot.find.current",
+  CannotFindTarget: "reordering.cannot.find.target",
+};
 
-export const ReorderingItemPositionValue = z
-  .number(ReorderingPositionError)
-  .int(ReorderingPositionError)
-  .min(0, ReorderingPositionError);
-export type ReorderingItemPositionValueType = z.infer<typeof ReorderingItemPositionValue>;
+const ReorderingIdError = { Type: "reordering.id.type" } as const;
 
-export const ReorderingCorrelationId = z
-  .string(ReorderingCorrelationIdError)
-  .min(1, ReorderingCorrelationIdError);
-export type ReorderingCorrelationIdType = z.infer<typeof ReorderingCorrelationId>;
-
-export const ReorderingItemId = z.string(ReorderingItemIdError);
-export type ReorderingItemIdType = z.infer<typeof ReorderingItemId>;
+export const ReorderingId = z.string(ReorderingIdError.Type).min(1, ReorderingIdError.Type);
+export type ReorderingItemIdType = z.infer<typeof ReorderingId>;
 
 export const Reordering = z.object({
-  correlationId: ReorderingCorrelationId,
-  id: ReorderingItemId,
+  correlationId: ReorderingId,
+  id: ReorderingId,
   position: ReorderingItemPositionValue,
 });
 export type ReorderingType = z.infer<typeof Reordering>;
@@ -35,10 +29,7 @@ export class ReorderingPosition {
   readonly value: ReorderingItemPositionValueType;
 
   constructor(value: ReorderingItemPositionValueType) {
-    const parsed = ReorderingItemPositionValue.safeParse(value);
-    if (!parsed.success) throw new Error(ReorderingPositionError.error);
-
-    this.value = value;
+    this.value = ReorderingItemPositionValue.parse(value);
   }
 
   eq(another: ReorderingPosition): boolean {
@@ -108,7 +99,7 @@ export class ReorderingCalculator {
 
   delete(id: ReorderingItem["id"]) {
     const node = this.dll.find((x) => x.data.eq(id));
-    if (!node) throw new Error(ReorderingCannotFindItemError.error);
+    if (!node) throw new Error(ReorderingError.CannotFindItem);
 
     this.dll.remove(node);
     this.recalculate();
@@ -116,10 +107,10 @@ export class ReorderingCalculator {
 
   transfer(transfer: ReorderingTransfer): ReturnType<ReorderingCalculator["read"]> {
     const current = this.dll.find((node) => node.data.eq(transfer.id));
-    if (!current) throw new Error(ReorderingCannotFindCurrentError.error);
+    if (!current) throw new Error(ReorderingError.CannotFindCurrent);
 
     const target = this.dll.find((node) => node.data.position.eq(transfer.to));
-    if (!target) throw new Error(ReorderingCannotFindTargetError.error);
+    if (!target) throw new Error(ReorderingError.CannotFindTarget);
 
     const direction = transfer.getDirection(current.data.position);
     if (direction === ReorderingTransferDirection.noop) return this.read();
@@ -147,7 +138,7 @@ export class ReorderingCalculator {
     let index = 0;
     for (const node of this.dll) {
       const id = node.data.id;
-      const position = new ReorderingPosition(index);
+      const position = new ReorderingPosition(ReorderingItemPositionValue.parse(index));
       node.data = new ReorderingItem(id, position);
       index += 1;
     }

package/src/revision-value.vo.ts

@@ -0,0 +1,10 @@
+import { z } from "zod/v4";
+
+export const RevisionValueError = { Type: "revision.value.type", Invalid: "revision.value.invalid" } as const;
+
+export const RevisionValue = z
+  .number(RevisionValueError.Type)
+  .int(RevisionValueError.Type)
+  .min(0, RevisionValueError.Invalid);
+
+export type RevisionValueType = z.infer<typeof RevisionValue>;