@bgord/tools 0.2.2 → 0.3.1

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

@@ -0,0 +1,9 @@
+import type { TimestampType } from "./timestamp.vo";
+type GetStartOfDayTsInTzConfigType = {
+    now: TimestampType;
+    timeZoneOffsetMs: number;
+};
+export declare class DateCalculator {
+    static getStartOfDayTsInTz(config: GetStartOfDayTsInTzConfigType): number;
+}
+export {};

package/dist/date-calculator.service.js

@@ -0,0 +1,16 @@
+import { Time } from "./time.service";
+export class DateCalculator {
+    static getStartOfDayTsInTz(config) {
+        const startOfDayUTC = new Date();
+        startOfDayUTC.setUTCHours(0, 0, 0, 0);
+        const startOfDayInTimeZone = startOfDayUTC.getTime() + config.timeZoneOffsetMs;
+        const timeSinceNewDayInTimeZoneRelativeToUtcStartOfDay = (config.now - startOfDayInTimeZone) % Time.Days(1).ms;
+        if (timeSinceNewDayInTimeZoneRelativeToUtcStartOfDay >= Time.Days(1).ms) {
+            return config.now - timeSinceNewDayInTimeZoneRelativeToUtcStartOfDay + Time.Days(1).ms;
+        }
+        if (timeSinceNewDayInTimeZoneRelativeToUtcStartOfDay >= 0) {
+            return config.now - timeSinceNewDayInTimeZoneRelativeToUtcStartOfDay;
+        }
+        return config.now - timeSinceNewDayInTimeZoneRelativeToUtcStartOfDay - Time.Days(1).ms;
+    }
+}

package/dist/date-formatter.service.d.ts

@@ -0,0 +1,10 @@
+import { format } from "date-fns";
+type FormattedDateType = string;
+type DateFormattersInputType = Parameters<typeof format>[0];
+export declare class DateFormatters {
+    static datetime(date: DateFormattersInputType): FormattedDateType;
+    static date(date: DateFormattersInputType): FormattedDateType;
+    static monthDay(date: DateFormattersInputType): FormattedDateType;
+    static relative(date: DateFormattersInputType): string;
+}
+export {};

package/dist/date-formatter.service.js

@@ -0,0 +1,15 @@
+import { format, formatDistanceToNow } from "date-fns";
+export class DateFormatters {
+    static datetime(date) {
+        return format(date, "yyyy/MM/dd HH:mm");
+    }
+    static date(date) {
+        return format(date, "yyyy/MM/dd");
+    }
+    static monthDay(date) {
+        return format(date, "MM/dd");
+    }
+    static relative(date) {
+        return formatDistanceToNow(date, { addSuffix: true });
+    }
+}

package/dist/dates-of-the-week.vo.d.ts

@@ -0,0 +1,9 @@
+export declare enum DayOfTheWeekEnum {
+    Monday = 1,
+    Tuesday = 2,
+    Wednesday = 3,
+    Thursday = 4,
+    Friday = 5,
+    Saturday = 6,
+    Sunday = 0
+}

package/dist/dates-of-the-week.vo.js

@@ -0,0 +1,10 @@
+export var DayOfTheWeekEnum;
+(function (DayOfTheWeekEnum) {
+    DayOfTheWeekEnum[DayOfTheWeekEnum["Monday"] = 1] = "Monday";
+    DayOfTheWeekEnum[DayOfTheWeekEnum["Tuesday"] = 2] = "Tuesday";
+    DayOfTheWeekEnum[DayOfTheWeekEnum["Wednesday"] = 3] = "Wednesday";
+    DayOfTheWeekEnum[DayOfTheWeekEnum["Thursday"] = 4] = "Thursday";
+    DayOfTheWeekEnum[DayOfTheWeekEnum["Friday"] = 5] = "Friday";
+    DayOfTheWeekEnum[DayOfTheWeekEnum["Saturday"] = 6] = "Saturday";
+    DayOfTheWeekEnum[DayOfTheWeekEnum["Sunday"] = 0] = "Sunday";
+})(DayOfTheWeekEnum || (DayOfTheWeekEnum = {}));

package/dist/etags.vo.d.ts

@@ -0,0 +1,22 @@
+import { z } from "zod/v4";
+declare const RevisionValueSchema: z.ZodNumber;
+type RevisionValueSchemaType = z.infer<typeof RevisionValueSchema>;
+type ETagValueType = string;
+export declare class ETag {
+    readonly revision: RevisionValueSchemaType;
+    static HEADER_NAME: string;
+    static IF_MATCH_HEADER_NAME: string;
+    readonly value: ETagValueType;
+    private constructor();
+    static fromHeader(value?: ETagValueType): ETag | null;
+}
+export type WeakETagValueType = string;
+export declare class WeakETag {
+    readonly revision: RevisionValueSchemaType;
+    static HEADER_NAME: string;
+    static IF_MATCH_HEADER_NAME: string;
+    readonly value: WeakETagValueType;
+    private constructor();
+    static fromHeader(value?: WeakETagValueType): WeakETag | null;
+}
+export {};

package/dist/etags.vo.js

@@ -0,0 +1,34 @@
+import { z } from "zod/v4";
+const RevisionValueSchema = z.number().int().min(0);
+export class ETag {
+    constructor(revision) {
+        this.revision = revision;
+        this.value = revision.toString();
+    }
+    static fromHeader(value) {
+        if (value?.startsWith("W/"))
+            return null;
+        const candidate = Number(value);
+        if (Number.isNaN(candidate))
+            return null;
+        return new ETag(candidate);
+    }
+}
+ETag.HEADER_NAME = "ETag";
+ETag.IF_MATCH_HEADER_NAME = "if-match";
+export class WeakETag {
+    constructor(revision) {
+        this.revision = revision;
+        this.value = `W/${revision.toString()}`;
+    }
+    static fromHeader(value) {
+        if (!value?.startsWith("W/"))
+            throw Error("Invalid WeakETag");
+        const candidate = Number(value.split("W/")[1]);
+        if (Number.isNaN(candidate))
+            return null;
+        return new WeakETag(candidate);
+    }
+}
+WeakETag.HEADER_NAME = "ETag";
+WeakETag.IF_MATCH_HEADER_NAME = "if-match";

package/dist/index.d.ts

@@ -1,2 +1,15 @@
-export * from "./rounding.service";
+export * from "./date-calculator.service";
+export * from "./date-formatter.service";
+export * from "./dates-of-the-week.vo";
+export * from "./etags.vo";
+export * from "./mime.vo";
 export * from "./noop.service";
+export * from "./rate-limiter.service";
+export * from "./relative-date.vo";
+export * from "./rounding.service";
+export * from "./size.vo";
+export * from "./sleep.service";
+export * from "./stopwatch.service";
+export * from "./time.service";
+export * from "./timestamp.vo";
+export * from "./ts-utils";

package/dist/index.js

@@ -1,2 +1,15 @@
-export * from "./rounding.service";
+export * from "./date-calculator.service";
+export * from "./date-formatter.service";
+export * from "./dates-of-the-week.vo";
+export * from "./etags.vo";
+export * from "./mime.vo";
 export * from "./noop.service";
+export * from "./rate-limiter.service";
+export * from "./relative-date.vo";
+export * from "./rounding.service";
+export * from "./size.vo";
+export * from "./sleep.service";
+export * from "./stopwatch.service";
+export * from "./time.service";
+export * from "./timestamp.vo";
+export * from "./ts-utils";

package/dist/mime.vo.d.ts

@@ -0,0 +1,18 @@
+type MimeRawType = string;
+type MimeTypeType = string;
+type MimeSubtypeType = string;
+export declare class Mime {
+    readonly raw: MimeRawType;
+    readonly type: MimeTypeType;
+    readonly subtype: MimeSubtypeType;
+    constructor(value: MimeRawType);
+    isSatisfiedBy(another: Mime): boolean;
+}
+export declare class InvalidMimeError extends Error {
+    constructor();
+}
+export declare class NotAcceptedMimeError extends Error {
+    mime: MimeRawType;
+    constructor(mime: MimeRawType);
+}
+export {};

package/dist/mime.vo.js

@@ -0,0 +1,35 @@
+export class Mime {
+    constructor(value) {
+        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();
+        }
+        this.raw = value;
+        this.type = type;
+        this.subtype = subtype;
+    }
+    isSatisfiedBy(another) {
+        if (this.raw === another.raw)
+            return true;
+        const typeMatches = this.type === another.type || this.type === "*";
+        if (!typeMatches)
+            return false;
+        return this.subtype === another.subtype || this.subtype === "*";
+    }
+}
+export class InvalidMimeError extends Error {
+    constructor() {
+        super();
+        Object.setPrototypeOf(this, InvalidMimeError.prototype);
+    }
+}
+export class NotAcceptedMimeError extends Error {
+    constructor(mime) {
+        super();
+        Object.setPrototypeOf(this, NotAcceptedMimeError.prototype);
+        this.mime = mime;
+    }
+}

package/dist/rate-limiter.service.d.ts

@@ -0,0 +1,19 @@
+import type { TimestampType } from "./timestamp.vo";
+type RateLimiterOptionsType = {
+    ms: TimestampType;
+};
+type RateLimiterResultSuccessType = {
+    allowed: true;
+};
+type RateLimiterResultErrorType = {
+    allowed: false;
+    remainingMs: TimestampType;
+};
+type RateLimiterResultType = RateLimiterResultSuccessType | RateLimiterResultErrorType;
+export declare class RateLimiter {
+    private readonly options;
+    private lastInvocationTimestampMs;
+    constructor(options: RateLimiterOptionsType);
+    verify(currentTimestampMs: TimestampType): RateLimiterResultType;
+}
+export {};

package/dist/rate-limiter.service.js

@@ -0,0 +1,21 @@
+export class RateLimiter {
+    constructor(options) {
+        this.options = options;
+        this.lastInvocationTimestampMs = null;
+    }
+    verify(currentTimestampMs) {
+        if (this.lastInvocationTimestampMs === null || this.lastInvocationTimestampMs === undefined) {
+            this.lastInvocationTimestampMs = currentTimestampMs;
+            return { allowed: true };
+        }
+        const nextAllowedTimestampMs = this.lastInvocationTimestampMs + this.options.ms;
+        if (nextAllowedTimestampMs <= currentTimestampMs) {
+            this.lastInvocationTimestampMs = currentTimestampMs;
+            return { allowed: true };
+        }
+        return {
+            allowed: false,
+            remainingMs: nextAllowedTimestampMs - currentTimestampMs,
+        };
+    }
+}

package/dist/relative-date.vo.d.ts

@@ -0,0 +1,12 @@
+import type { TimestampType } from "./timestamp.vo";
+import type { Falsy } from "./ts-utils";
+type RelativeDateType = {
+    raw: TimestampType;
+    relative: string;
+};
+export declare class RelativeDate {
+    static truthy(timestampMs: TimestampType): RelativeDateType;
+    static falsy(timestampMs: Falsy<TimestampType>): RelativeDateType | null;
+    private static _format;
+}
+export {};

package/dist/relative-date.vo.js

@@ -0,0 +1,17 @@
+import { DateFormatters } from "./date-formatter.service";
+export class RelativeDate {
+    static truthy(timestampMs) {
+        return RelativeDate._format(timestampMs);
+    }
+    static falsy(timestampMs) {
+        if (!timestampMs)
+            return null;
+        return RelativeDate._format(timestampMs);
+    }
+    static _format(timestampMs) {
+        return {
+            raw: timestampMs,
+            relative: DateFormatters.relative(timestampMs),
+        };
+    }
+}

package/dist/size.vo.d.ts

@@ -0,0 +1,30 @@
+import { z } from "zod/v4";
+export declare enum SizeUnit {
+    b = "b",
+    kB = "kB",
+    MB = "MB",
+    GB = "GB"
+}
+declare const SizeValueSchema: z.ZodNumber;
+type SizeValueType = z.infer<typeof SizeValueSchema>;
+type SizeConfigType = {
+    unit: SizeUnit;
+    value: SizeValueType;
+};
+export declare class Size {
+    private readonly unit;
+    private readonly value;
+    private readonly bytes;
+    private static readonly KB_MULTIPLIER;
+    private static readonly MB_MULTIPLIER;
+    private static readonly GB_MULTIPLIER;
+    constructor(config: SizeConfigType);
+    toString(): string;
+    toBytes(): SizeValueType;
+    isGreaterThan(another: Size): boolean;
+    format(unit: SizeUnit): string;
+    static toBytes(config: SizeConfigType): SizeValueType;
+    static unit: typeof SizeUnit;
+    private calculateBytes;
+}
+export {};

package/dist/size.vo.js

@@ -0,0 +1,67 @@
+import { z } from "zod/v4";
+import { RoundToDecimal } from "./rounding.service";
+export var SizeUnit;
+(function (SizeUnit) {
+    SizeUnit["b"] = "b";
+    SizeUnit["kB"] = "kB";
+    SizeUnit["MB"] = "MB";
+    SizeUnit["GB"] = "GB";
+})(SizeUnit || (SizeUnit = {}));
+const SizeValueSchema = z.number().positive();
+export class Size {
+    constructor(config) {
+        this.unit = config.unit;
+        this.value = SizeValueSchema.parse(config.value);
+        this.bytes = this.calculateBytes(config);
+    }
+    toString() {
+        return `${this.value} ${this.unit}`;
+    }
+    toBytes() {
+        return this.bytes;
+    }
+    isGreaterThan(another) {
+        return this.bytes > another.toBytes();
+    }
+    format(unit) {
+        const rounding = new RoundToDecimal(2);
+        switch (unit) {
+            case SizeUnit.kB: {
+                const kbs = rounding.round(this.bytes / Size.KB_MULTIPLIER);
+                return `${kbs} ${SizeUnit.kB}`;
+            }
+            case SizeUnit.MB: {
+                const mbs = rounding.round(this.bytes / Size.MB_MULTIPLIER);
+                return `${mbs} ${SizeUnit.MB}`;
+            }
+            case SizeUnit.GB: {
+                const gbs = rounding.round(this.bytes / Size.GB_MULTIPLIER);
+                return `${gbs} ${SizeUnit.GB}`;
+            }
+            default: {
+                // SizeUnit.b
+                return `${this.bytes} ${SizeUnit.b}`;
+            }
+        }
+    }
+    static toBytes(config) {
+        return new Size(config).toBytes();
+    }
+    calculateBytes(config) {
+        switch (config.unit) {
+            case SizeUnit.kB:
+                return config.value * Size.KB_MULTIPLIER;
+            case SizeUnit.MB:
+                return config.value * Size.MB_MULTIPLIER;
+            case SizeUnit.GB:
+                return 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/sleep.service.d.ts

@@ -0,0 +1,3 @@
+export declare function sleep(config: {
+    ms: number;
+}): Promise<unknown>;

package/dist/sleep.service.js

@@ -0,0 +1,3 @@
+export function sleep(config) {
+    return new Promise((resolve) => setTimeout(resolve, config.ms));
+}

package/dist/stopwatch.service.d.ts

@@ -0,0 +1,11 @@
+import type { TimestampType } from "./timestamp.vo";
+type StopwatchResultType = {
+    durationMs: TimestampType;
+};
+export declare class Stopwatch {
+    private state;
+    private readonly startMs;
+    private stopMs;
+    stop(): StopwatchResultType;
+}
+export {};

package/dist/stopwatch.service.js

@@ -0,0 +1,19 @@
+var StopwatchState;
+(function (StopwatchState) {
+    StopwatchState["started"] = "started";
+    StopwatchState["stopped"] = "finished";
+})(StopwatchState || (StopwatchState = {}));
+export class Stopwatch {
+    constructor() {
+        this.state = StopwatchState.started;
+        this.startMs = Date.now();
+    }
+    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 };
+    }
+}

package/dist/time.service.d.ts

@@ -0,0 +1,21 @@
+interface TimeResultInterface {
+    readonly days: number;
+    readonly hours: number;
+    readonly minutes: number;
+    readonly seconds: number;
+    readonly ms: number;
+    isAfter(another: TimeResultInterface): boolean;
+    isBefore(another: TimeResultInterface): boolean;
+}
+export declare class Time {
+    static Days(value: number): TimeResultInterface;
+    static Hours(value: number): TimeResultInterface;
+    static Minutes(value: number): TimeResultInterface;
+    static Seconds(value: number): TimeResultInterface;
+    static Ms(value: number): TimeResultInterface;
+    static Now(now?: number): {
+        Minus(time: TimeResultInterface): TimeResultInterface;
+        Add(time: TimeResultInterface): TimeResultInterface;
+    };
+}
+export {};

package/dist/time.service.js

@@ -0,0 +1,44 @@
+import { RoundToDecimal } from "./rounding.service";
+const rounding = new RoundToDecimal(2);
+class TimeResult {
+    constructor(days, hours, minutes, seconds, ms) {
+        this.days = days;
+        this.hours = hours;
+        this.minutes = minutes;
+        this.seconds = seconds;
+        this.ms = ms;
+    }
+    isAfter(another) {
+        return this.ms > another.ms;
+    }
+    isBefore(another) {
+        return this.ms < another.ms;
+    }
+}
+export class Time {
+    static Days(value) {
+        return new TimeResult(value, value * 24, value * 24 * 60, value * 24 * 60 * 60, value * 24 * 60 * 60 * 1000);
+    }
+    static Hours(value) {
+        return new TimeResult(rounding.round(value / 24), value, value * 60, value * 60 * 60, value * 60 * 60 * 1000);
+    }
+    static Minutes(value) {
+        return new TimeResult(rounding.round(value / 60 / 24), rounding.round(value / 60), value, value * 60, value * 60 * 1000);
+    }
+    static Seconds(value) {
+        return new TimeResult(rounding.round(value / 60 / 60 / 24), rounding.round(value / 60 / 60), rounding.round(value / 60), value, value * 1000);
+    }
+    static Ms(value) {
+        return new TimeResult(rounding.round(value / 1000 / 60 / 60 / 24), rounding.round(value / 1000 / 60 / 60), rounding.round(value / 1000 / 60), rounding.round(value / 1000), value);
+    }
+    static Now(now = Date.now()) {
+        return {
+            Minus(time) {
+                return Time.Ms(now - time.ms);
+            },
+            Add(time) {
+                return Time.Ms(now + time.ms);
+            },
+        };
+    }
+}

package/dist/timestamp.vo.d.ts

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

package/dist/timestamp.vo.js

@@ -0,0 +1,6 @@
+import { z } from "zod/v4";
+export const Timestamp = z
+    .number()
+    .int()
+    .positive()
+    .default(() => Date.now());

package/dist/ts-utils.d.ts

@@ -0,0 +1,3 @@
+export type Constructor<T> = new (...args: any[]) => T;
+export type Falsy<T> = T | null | undefined;
+export type Nullable<T> = T | null;

package/dist/ts-utils.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bgord/tools",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "type": "module",
   "license": "MIT",
   "author": "Bartosz Gordon",
@@ -21,12 +21,16 @@
     "@biomejs/biome": "1.9.4",
     "@commitlint/cli": "19.8.1",
     "@commitlint/config-conventional": "19.8.1",
+    "@types/bun": "1.2.15",
     "cspell": "9.0.2",
-    "lefthook": "1.11.4",
+    "lefthook": "1.11.13",
     "only-allow": "1.2.1",
     "shellcheck": "3.1.0",
-    "typescript": "5.8.3",
-    "vitest": "3.1.4"
+    "typescript": "5.8.3"
+  },
+  "dependencies": {
+    "date-fns": "4.1.0",
+    "zod": "3.25.46"
   },
   "sideEffects": false
 }

package/src/date-calculator.service.ts

@@ -0,0 +1,29 @@
+import { Time } from "./time.service";
+import type { TimestampType } from "./timestamp.vo";
+
+type GetStartOfDayTsInTzConfigType = {
+  now: TimestampType;
+  timeZoneOffsetMs: number;
+};
+
+export class DateCalculator {
+  static getStartOfDayTsInTz(config: GetStartOfDayTsInTzConfigType) {
+    const startOfDayUTC = new Date();
+    startOfDayUTC.setUTCHours(0, 0, 0, 0);
+
+    const startOfDayInTimeZone = startOfDayUTC.getTime() + config.timeZoneOffsetMs;
+
+    const timeSinceNewDayInTimeZoneRelativeToUtcStartOfDay =
+      (config.now - startOfDayInTimeZone) % Time.Days(1).ms;
+
+    if (timeSinceNewDayInTimeZoneRelativeToUtcStartOfDay >= Time.Days(1).ms) {
+      return config.now - timeSinceNewDayInTimeZoneRelativeToUtcStartOfDay + Time.Days(1).ms;
+    }
+
+    if (timeSinceNewDayInTimeZoneRelativeToUtcStartOfDay >= 0) {
+      return config.now - timeSinceNewDayInTimeZoneRelativeToUtcStartOfDay;
+    }
+
+    return config.now - timeSinceNewDayInTimeZoneRelativeToUtcStartOfDay - Time.Days(1).ms;
+  }
+}

package/src/date-formatter.service.ts

@@ -0,0 +1,23 @@
+import { format, formatDistanceToNow } from "date-fns";
+
+type FormattedDateType = string;
+
+type DateFormattersInputType = Parameters<typeof format>[0];
+
+export class DateFormatters {
+  static datetime(date: DateFormattersInputType): FormattedDateType {
+    return format(date, "yyyy/MM/dd HH:mm");
+  }
+
+  static date(date: DateFormattersInputType): FormattedDateType {
+    return format(date, "yyyy/MM/dd");
+  }
+
+  static monthDay(date: DateFormattersInputType): FormattedDateType {
+    return format(date, "MM/dd");
+  }
+
+  static relative(date: DateFormattersInputType) {
+    return formatDistanceToNow(date, { addSuffix: true });
+  }
+}

package/src/dates-of-the-week.vo.ts

@@ -0,0 +1,9 @@
+export enum DayOfTheWeekEnum {
+  Monday = 1,
+  Tuesday = 2,
+  Wednesday = 3,
+  Thursday = 4,
+  Friday = 5,
+  Saturday = 6,
+  Sunday = 0,
+}

package/src/etags.vo.ts

@@ -0,0 +1,51 @@
+import { z } from "zod/v4";
+
+const RevisionValueSchema = z.number().int().min(0);
+
+type RevisionValueSchemaType = z.infer<typeof RevisionValueSchema>;
+
+type ETagValueType = string;
+
+export class ETag {
+  static HEADER_NAME = "ETag";
+
+  static IF_MATCH_HEADER_NAME = "if-match";
+
+  readonly value: ETagValueType;
+
+  private constructor(readonly revision: RevisionValueSchemaType) {
+    this.value = revision.toString();
+  }
+
+  static fromHeader(value?: ETagValueType): ETag | null {
+    if (value?.startsWith("W/")) return null;
+
+    const candidate = Number(value);
+
+    if (Number.isNaN(candidate)) return null;
+    return new ETag(candidate);
+  }
+}
+
+export type WeakETagValueType = string;
+
+export class WeakETag {
+  static HEADER_NAME = "ETag";
+
+  static IF_MATCH_HEADER_NAME = "if-match";
+
+  readonly value: WeakETagValueType;
+
+  private constructor(readonly revision: RevisionValueSchemaType) {
+    this.value = `W/${revision.toString()}`;
+  }
+
+  static fromHeader(value?: WeakETagValueType): WeakETag | null {
+    if (!value?.startsWith("W/")) throw Error("Invalid WeakETag");
+
+    const candidate = Number(value.split("W/")[1]);
+
+    if (Number.isNaN(candidate)) return null;
+    return new WeakETag(candidate);
+  }
+}

package/src/index.ts

@@ -1,2 +1,15 @@
-export * from "./rounding.service";
+export * from "./date-calculator.service";
+export * from "./date-formatter.service";
+export * from "./dates-of-the-week.vo";
+export * from "./etags.vo";
+export * from "./mime.vo";
 export * from "./noop.service";
+export * from "./rate-limiter.service";
+export * from "./relative-date.vo";
+export * from "./rounding.service";
+export * from "./size.vo";
+export * from "./sleep.service";
+export * from "./stopwatch.service";
+export * from "./time.service";
+export * from "./timestamp.vo";
+export * from "./ts-utils";

package/src/mime.vo.ts

@@ -0,0 +1,50 @@
+type MimeRawType = string;
+type MimeTypeType = string;
+type MimeSubtypeType = string;
+
+export class Mime {
+  readonly raw: MimeRawType;
+  readonly type: MimeTypeType;
+  readonly subtype: MimeSubtypeType;
+
+  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();
+    }
+
+    this.raw = value;
+    this.type = type;
+    this.subtype = subtype;
+  }
+
+  isSatisfiedBy(another: Mime): boolean {
+    if (this.raw === another.raw) return true;
+
+    const typeMatches = this.type === another.type || this.type === "*";
+    if (!typeMatches) return false;
+
+    return this.subtype === another.subtype || this.subtype === "*";
+  }
+}
+
+export class InvalidMimeError extends Error {
+  constructor() {
+    super();
+    Object.setPrototypeOf(this, InvalidMimeError.prototype);
+  }
+}
+
+export class NotAcceptedMimeError extends Error {
+  mime: MimeRawType;
+  constructor(mime: MimeRawType) {
+    super();
+    Object.setPrototypeOf(this, NotAcceptedMimeError.prototype);
+    this.mime = mime;
+  }
+}

package/src/rate-limiter.service.ts

@@ -0,0 +1,42 @@
+import type { TimestampType } from "./timestamp.vo";
+import type { Falsy } from "./ts-utils";
+
+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;
+
+  constructor(private readonly options: RateLimiterOptionsType) {}
+
+  verify(currentTimestampMs: TimestampType): RateLimiterResultType {
+    if (this.lastInvocationTimestampMs === null || this.lastInvocationTimestampMs === undefined) {
+      this.lastInvocationTimestampMs = currentTimestampMs;
+
+      return { allowed: true };
+    }
+
+    const nextAllowedTimestampMs = this.lastInvocationTimestampMs + this.options.ms;
+
+    if (nextAllowedTimestampMs <= currentTimestampMs) {
+      this.lastInvocationTimestampMs = currentTimestampMs;
+
+      return { allowed: true };
+    }
+
+    return {
+      allowed: false,
+      remainingMs: nextAllowedTimestampMs - currentTimestampMs,
+    };
+  }
+}

package/src/relative-date.vo.ts

@@ -0,0 +1,24 @@
+import { DateFormatters } from "./date-formatter.service";
+import type { TimestampType } from "./timestamp.vo";
+import type { Falsy } from "./ts-utils";
+
+type RelativeDateType = { raw: TimestampType; relative: string };
+
+export class RelativeDate {
+  static truthy(timestampMs: TimestampType): RelativeDateType {
+    return RelativeDate._format(timestampMs);
+  }
+
+  static falsy(timestampMs: Falsy<TimestampType>): RelativeDateType | null {
+    if (!timestampMs) return null;
+
+    return RelativeDate._format(timestampMs);
+  }
+
+  private static _format(timestampMs: TimestampType): RelativeDateType {
+    return {
+      raw: timestampMs,
+      relative: DateFormatters.relative(timestampMs),
+    };
+  }
+}

package/src/size.vo.ts

@@ -0,0 +1,94 @@
+import { z } from "zod/v4";
+
+import { RoundToDecimal } from "./rounding.service";
+
+export enum SizeUnit {
+  b = "b",
+  kB = "kB",
+  MB = "MB",
+  GB = "GB",
+}
+
+const SizeValueSchema = z.number().positive();
+
+export type SizeValueType = z.infer<typeof SizeValueSchema>;
+
+type SizeConfigType = { unit: SizeUnit; value: SizeValueType };
+
+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;
+
+  constructor(config: SizeConfigType) {
+    this.unit = config.unit;
+    this.value = SizeValueSchema.parse(config.value);
+    this.bytes = this.calculateBytes(config);
+  }
+
+  toString(): string {
+    return `${this.value} ${this.unit}`;
+  }
+
+  toBytes(): SizeValueType {
+    return this.bytes;
+  }
+
+  isGreaterThan(another: Size) {
+    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}`;
+      }
+      case SizeUnit.MB: {
+        const mbs = rounding.round(this.bytes / Size.MB_MULTIPLIER);
+
+        return `${mbs} ${SizeUnit.MB}`;
+      }
+      case SizeUnit.GB: {
+        const gbs = rounding.round(this.bytes / Size.GB_MULTIPLIER);
+
+        return `${gbs} ${SizeUnit.GB}`;
+      }
+      default: {
+        // SizeUnit.b
+        return `${this.bytes} ${SizeUnit.b}`;
+      }
+    }
+  }
+
+  static toBytes(config: SizeConfigType): SizeValueType {
+    return new Size(config).toBytes();
+  }
+
+  static unit = SizeUnit;
+
+  private calculateBytes(config: SizeConfigType): SizeValueType {
+    switch (config.unit) {
+      case SizeUnit.kB:
+        return config.value * Size.KB_MULTIPLIER;
+      case SizeUnit.MB:
+        return config.value * Size.MB_MULTIPLIER;
+      case SizeUnit.GB:
+        return config.value * Size.GB_MULTIPLIER;
+      default:
+        // SizeUnit.b
+        return config.value;
+    }
+  }
+}

package/src/sleep.service.ts

@@ -0,0 +1,3 @@
+export function sleep(config: { ms: number }) {
+  return new Promise((resolve) => setTimeout(resolve, config.ms));
+}

package/src/stopwatch.service.ts

@@ -0,0 +1,28 @@
+import type { TimestampType } from "./timestamp.vo";
+import type { Falsy } from "./ts-utils";
+
+enum StopwatchState {
+  started = "started",
+  stopped = "finished",
+}
+
+export type StopwatchResultType = { durationMs: TimestampType };
+
+export class Stopwatch {
+  private state: StopwatchState = StopwatchState.started;
+
+  private readonly startMs: TimestampType = Date.now();
+
+  private stopMs: Falsy<TimestampType>;
+
+  stop(): StopwatchResultType {
+    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 };
+  }
+}

package/src/time.service.ts

@@ -0,0 +1,96 @@
+import { RoundToDecimal } from "./rounding.service";
+
+const rounding = new RoundToDecimal(2);
+
+interface TimeResultInterface {
+  readonly days: number;
+  readonly hours: number;
+  readonly minutes: number;
+  readonly seconds: number;
+  readonly ms: number;
+
+  isAfter(another: TimeResultInterface): boolean;
+  isBefore(another: TimeResultInterface): boolean;
+}
+
+class TimeResult implements TimeResultInterface {
+  constructor(
+    readonly days: number,
+    readonly hours: number,
+    readonly minutes: number,
+    readonly seconds: number,
+    readonly ms: number,
+  ) {}
+
+  isAfter(another: TimeResultInterface): boolean {
+    return this.ms > another.ms;
+  }
+
+  isBefore(another: TimeResultInterface): boolean {
+    return this.ms < another.ms;
+  }
+}
+
+export class Time {
+  static Days(value: number): TimeResultInterface {
+    return new TimeResult(
+      value,
+      value * 24,
+      value * 24 * 60,
+      value * 24 * 60 * 60,
+      value * 24 * 60 * 60 * 1000,
+    );
+  }
+
+  static Hours(value: number): TimeResultInterface {
+    return new TimeResult(
+      rounding.round(value / 24),
+      value,
+      value * 60,
+      value * 60 * 60,
+      value * 60 * 60 * 1000,
+    );
+  }
+
+  static Minutes(value: number): TimeResultInterface {
+    return new TimeResult(
+      rounding.round(value / 60 / 24),
+      rounding.round(value / 60),
+      value,
+      value * 60,
+      value * 60 * 1000,
+    );
+  }
+
+  static Seconds(value: number): TimeResultInterface {
+    return new TimeResult(
+      rounding.round(value / 60 / 60 / 24),
+      rounding.round(value / 60 / 60),
+      rounding.round(value / 60),
+      value,
+      value * 1000,
+    );
+  }
+
+  static Ms(value: number): TimeResultInterface {
+    return new TimeResult(
+      rounding.round(value / 1000 / 60 / 60 / 24),
+      rounding.round(value / 1000 / 60 / 60),
+      rounding.round(value / 1000 / 60),
+      rounding.round(value / 1000),
+      value,
+    );
+  }
+
+  static Now(now = Date.now()) {
+    return {
+      Minus(time: TimeResultInterface): TimeResultInterface {
+        return Time.Ms(now - time.ms);
+      },
+
+      Add(time: TimeResultInterface): TimeResultInterface {
+        return Time.Ms(now + time.ms);
+      },
+    };
+  }
+}

package/src/timestamp.vo.ts

@@ -0,0 +1,9 @@
+import { z } from "zod/v4";
+
+export const Timestamp = z
+  .number()
+  .int()
+  .positive()
+  .default(() => Date.now());
+
+export type TimestampType = z.infer<typeof Timestamp>;

package/src/ts-utils.ts

@@ -0,0 +1,5 @@
+export type Constructor<T> = new (...args: any[]) => T;
+
+export type Falsy<T> = T | null | undefined;
+
+export type Nullable<T> = T | null;