@invariant--labs/foundation 1.1.2

package/src/utils/date/isSame.spec.ts

@@ -0,0 +1,111 @@
+import { isSame } from "./date";
+
+const DATE = +new Date("2023-01-01");
+
+const ONE_MS = 1;
+const ONE_SECOND = ONE_MS * 1000;
+const ONE_MINUTE = ONE_SECOND * 60;
+const ONE_HOUR = ONE_MINUTE * 60;
+const ONE_DAY = ONE_HOUR * 60;
+const ONE_MONTH = ONE_DAY * 31;
+const ONE_YEAR = ONE_MONTH * 12;
+
+describe("isSame", () => {
+  describe("millisecond", () => {
+    it("should return true", () => {
+      const result = isSame(new Date(DATE), new Date(DATE), "millisecond");
+
+      expect(result).toEqual(true);
+    });
+
+    it("should return false", () => {
+      const result = isSame(new Date(DATE), new Date(DATE + ONE_MS), "millisecond");
+
+      expect(result).toEqual(false);
+    });
+  });
+
+  describe("second", () => {
+    it("should return true", () => {
+      const result = isSame(new Date(DATE), new Date(DATE + ONE_MS), "second");
+
+      expect(result).toEqual(true);
+    });
+
+    it("should return false", () => {
+      const result = isSame(new Date(DATE), new Date(DATE + ONE_SECOND), "second");
+
+      expect(result).toEqual(false);
+    });
+  });
+
+  describe("minute", () => {
+    it("should return true", () => {
+      const result = isSame(new Date(DATE), new Date(DATE + ONE_SECOND), "minute");
+
+      expect(result).toEqual(true);
+    });
+
+    it("should return false", () => {
+      const result = isSame(new Date(DATE), new Date(DATE + ONE_MINUTE), "minute");
+
+      expect(result).toEqual(false);
+    });
+  });
+
+  describe("hour", () => {
+    it("should return true", () => {
+      const result = isSame(new Date(DATE), new Date(DATE + ONE_MINUTE), "hour");
+
+      expect(result).toEqual(true);
+    });
+
+    it("should return false", () => {
+      const result = isSame(new Date(DATE), new Date(DATE + ONE_HOUR), "hour");
+
+      expect(result).toEqual(false);
+    });
+  });
+
+  describe("day", () => {
+    it("should return true", () => {
+      const result = isSame(new Date(DATE), new Date(DATE + ONE_HOUR), "day");
+
+      expect(result).toEqual(true);
+    });
+
+    it("should return false", () => {
+      const result = isSame(new Date(DATE), new Date(DATE + ONE_DAY), "day");
+
+      expect(result).toEqual(false);
+    });
+  });
+
+  describe("month", () => {
+    it("should return true", () => {
+      const result = isSame(new Date(DATE), new Date(DATE + ONE_DAY), "month");
+
+      expect(result).toEqual(true);
+    });
+
+    it("should return false", () => {
+      const result = isSame(new Date(DATE), new Date(DATE + ONE_MONTH), "month");
+
+      expect(result).toEqual(false);
+    });
+  });
+
+  describe("year", () => {
+    it("should return true", () => {
+      const result = isSame(new Date(DATE), new Date(DATE + ONE_MONTH), "year");
+
+      expect(result).toEqual(true);
+    });
+
+    it("should return false", () => {
+      const result = isSame(new Date(DATE), new Date(DATE + ONE_YEAR), "year");
+
+      expect(result).toEqual(false);
+    });
+  });
+});

package/src/utils/file.spec.ts

@@ -0,0 +1,66 @@
+import { getFileExtension } from "./file";
+
+describe("getFileExtension", () => {
+  it("should return the file extension based on the mimetype", () => {
+    const cases = [
+      {
+        mimetype: "image/jpeg",
+        expected: "jpg",
+      },
+      {
+        mimetype: "image/png",
+        expected: "png",
+      },
+      {
+        mimetype: "application/pdf",
+        expected: "pdf",
+      },
+      {
+        mimetype: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        expected: "docx",
+      },
+    ];
+
+    cases.forEach((c) => {
+      const file = {
+        mimetype: c.mimetype,
+        originalname: `test.${c.expected}`,
+      } as Express.Multer.File;
+
+      const extension = getFileExtension(file);
+
+      expect(extension).toEqual(c.expected);
+    });
+  });
+
+  it("should return the file extension based on the originalname if mimetype is not available", () => {
+    const cases = [
+      {
+        originalname: "test.jpg",
+        expected: "jpg",
+      },
+      {
+        originalname: "test.png",
+        expected: "png",
+      },
+      {
+        originalname: "test.pdf",
+        expected: "pdf",
+      },
+      {
+        originalname: "test.docx",
+        expected: "docx",
+      },
+    ];
+
+    cases.forEach((c) => {
+      const file = {
+        originalname: c.originalname,
+      } as Express.Multer.File;
+
+      const extension = getFileExtension(file);
+
+      expect(extension).toEqual(c.expected);
+    });
+  });
+});

package/src/utils/file.ts

@@ -0,0 +1,5 @@
+import mime from "mime-types";
+
+export const getFileExtension = (file: Express.Multer.File) => {
+  return (mime.extension(file.mimetype) || file.originalname.split(".").pop()) as string;
+};

package/src/utils/hash-key.ts

@@ -0,0 +1,23 @@
+/* eslint-disable @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access */
+export function hashKey(queryKey: unknown): string {
+  return JSON.stringify(queryKey, (_, val) =>
+    isPlainObject(val)
+      ? Object.keys(val)
+          .sort()
+          .reduce<Record<string, unknown>>((result, key) => {
+            result[key] = val[key];
+            return result;
+          }, {})
+      : val,
+  );
+}
+
+function isPlainObject(o: unknown): o is Record<PropertyKey, unknown> {
+  if (Object.prototype.toString.call(o) !== "[object Object]") {return false;}
+
+  const proto = Object.getPrototypeOf(o);
+  if (proto === null) {return true;}
+
+  const ctor = proto.constructor;
+  return typeof ctor === "function" && ctor instanceof ctor && Object.getPrototypeOf(o) === Object.prototype;
+}

package/src/utils/index.ts

@@ -0,0 +1,14 @@
+export * as arrayUtils from "./array";
+export * from "./base64";
+export * as collectionUtils from "./collection";
+export * as csvUtils from "./csv";
+export * as dateUtils from "./date";
+export * as fileUtils from "./file";
+export * from "./invariant";
+export * from "./iso-date";
+export * as objectUtils from "./object";
+export * from "./paginated";
+export * as stringUtils from "./string";
+export * as typeUtils from "./type";
+export * as xmlUtils from "./xml";
+export * from "./hash-key";

package/src/utils/invariant.ts

@@ -0,0 +1,3 @@
+import invariant from "tiny-invariant";
+
+export { invariant };

package/src/utils/iso-date.ts

@@ -0,0 +1,11 @@
+import { DateTime } from "luxon";
+
+export type ISODate = `${number}-${number}-${number}`;
+
+export const toISODate = (date: Date): ISODate => {
+  return DateTime.fromJSDate(date).toISODate() as ISODate;
+};
+
+export const isValidISODate = (date: string): boolean => {
+  return DateTime.fromFormat(date, "yyyy-MM-dd").isValid;
+};

package/src/utils/object.spec.ts

@@ -0,0 +1,18 @@
+import { isNotNil } from "./object";
+
+describe(isNotNil.name, () => {
+  it("should return true if value is not null or undefined", () => {
+    expect(isNotNil(1)).toBe(true);
+    expect(isNotNil("")).toBe(true);
+    expect(isNotNil({})).toBe(true);
+    expect(isNotNil([])).toBe(true);
+    expect(isNotNil(false)).toBe(true);
+    expect(isNotNil(true)).toBe(true);
+    expect(isNotNil(0)).toBe(true);
+  });
+
+  it("should return false if value is null or undefined", () => {
+    expect(isNotNil(null)).toBe(false);
+    expect(isNotNil(undefined)).toBe(false);
+  });
+});

package/src/utils/object.ts

@@ -0,0 +1,6 @@
+import _ from "lodash";
+
+// eslint-disable-next-line @typescript-eslint/no-unsafe-return
+export const get = <T>(obj: T, path: string) => _.get(obj, path);
+export const omit = <T extends object, K extends keyof T>(obj: T, ...paths: K[]) => _.omit(obj, ...paths);
+export const isNotNil = <T>(value: T | null | undefined): value is T => value != null;

package/src/utils/paginated.ts

@@ -0,0 +1,36 @@
+export interface PaginatedInput {
+  take: number;
+  skip: number;
+}
+
+export interface PaginatedResults<T> {
+  items: T[];
+  total?: number;
+  hasMore: boolean;
+}
+
+export interface CursorPaginatedResult<T> {
+  items: T[];
+  nextCursor: string | null;
+}
+
+export enum OrderByEnum {
+  ASC = "asc",
+  DESC = "desc",
+}
+
+export interface DataPaginatedInput {
+  first: number;
+  after: number;
+}
+
+export interface DataPaginatedResults<T> {
+  data: T[];
+  page_info: DataPageInfo;
+}
+
+export interface DataPageInfo {
+  has_more: boolean;
+  next_page: number;
+  total?: number;
+}

package/src/utils/string.spec.ts

@@ -0,0 +1,10 @@
+import { generateTextWithLength } from "./string";
+
+describe("generateTextWithLength", () => {
+  it("should generate a string with the given length", () => {
+    const length = 100;
+    const str = generateTextWithLength(length);
+
+    expect(str.length).toEqual(length);
+  });
+});

package/src/utils/string.ts

@@ -0,0 +1,19 @@
+import slugify from "slugify";
+
+export type SlugOpts = {
+  replacement?: string;
+  remove?: RegExp;
+  lower?: boolean;
+  strict?: boolean;
+  locale?: string;
+  trim?: boolean;
+};
+
+export const generateSlug = (str: string, ops: SlugOpts = {}) => slugify(str, { lower: true, ...ops });
+
+export const generateTextWithLength = (length: number) => "a".repeat(length);
+
+export const validateEmail = (email: string) => {
+  const pattern = /^[\w-+.]+@([\w-]+\.)+[\w-]{2,4}$/;
+  return pattern.test(email);
+};

package/src/utils/type.ts

@@ -0,0 +1,9 @@
+export type PartialPick<T, F extends keyof T> = Omit<T, F> & Partial<Pick<T, F>>;
+
+export type RequiredPick<T, F extends keyof T> = Omit<T, F> & {
+  [P in F]-?: T[P];
+};
+
+export type NonNullablePick<T, F extends keyof T> = Omit<T, F> & {
+  [P in F]: NonNullable<T[P]>;
+};

package/src/utils/xml.ts

@@ -0,0 +1,6 @@
+import { XMLBuilder } from "fast-xml-parser";
+
+export const buildXml = (obj: object) => {
+  const builder = new XMLBuilder();
+  return builder.build(obj);
+};

package/src/validation/ensure-array.decorator.ts

@@ -0,0 +1,5 @@
+import { applyDecorators } from "@nestjs/common";
+import { Transform } from "class-transformer";
+
+// eslint-disable-next-line @typescript-eslint/no-unsafe-return
+export const EnsureArray = () => applyDecorators(Transform(({ value }) => (typeof value === "string" ? [value] : value)));

package/src/validation/index.ts

@@ -0,0 +1,7 @@
+export * from "./ensure-array.decorator";
+export * from "./is-iso-date.decorator";
+export * from "./is-less-than.decorator";
+export * from "./is-less-than-or-equal.decorator";
+export * from "./is-more-than.decorator";
+export * from "./is-more-than-or-equal.decorator";
+export * from "./is-time-string.decorator";

package/src/validation/is-iso-date.decorator.spec.ts

@@ -0,0 +1,29 @@
+import { describe, it, expect } from "@jest/globals";
+import { validate } from "class-validator";
+
+import { IsISODate } from "./is-iso-date.decorator";
+
+class Dto {
+  @IsISODate()
+  date: unknown;
+}
+
+describe("IsISODate", () => {
+  it("should accept yyyy-MM-dd format", async () => {
+    const dto = Object.assign(new Dto(), { date: "2024-01-15" });
+    const errors = await validate(dto);
+    expect(errors).toHaveLength(0);
+  });
+
+  it("should reject invalid date strings", async () => {
+    const dto = Object.assign(new Dto(), { date: "15-01-2024" });
+    const errors = await validate(dto);
+    expect(errors.length).toBeGreaterThan(0);
+  });
+
+  it("should reject non-string values", async () => {
+    const dto = Object.assign(new Dto(), { date: 12345 });
+    const errors = await validate(dto);
+    expect(errors.length).toBeGreaterThan(0);
+  });
+});

package/src/validation/is-iso-date.decorator.ts

@@ -0,0 +1,30 @@
+import {
+  registerDecorator,
+  ValidationArguments,
+  ValidationOptions,
+  ValidatorConstraint,
+  ValidatorConstraintInterface,
+} from "class-validator";
+import { DateTime } from "luxon";
+
+export function IsISODate(validationOptions?: ValidationOptions) {
+  return function (object: object, propertyName: string) {
+    registerDecorator({
+      target: object.constructor,
+      propertyName,
+      options: validationOptions,
+      validator: IsISODateConstraint,
+    });
+  };
+}
+
+@ValidatorConstraint({ name: "isISODate" })
+class IsISODateConstraint implements ValidatorConstraintInterface {
+  validate(value: unknown) {
+    return typeof value === "string" && DateTime.fromFormat(value, "yyyy-MM-dd").isValid;
+  }
+
+  defaultMessage(args: ValidationArguments) {
+    return `${args.property} must be in yyyy-MM-dd format`;
+  }
+}

package/src/validation/is-less-than-or-equal.decorator.spec.ts

@@ -0,0 +1,30 @@
+import { describe, it, expect } from "@jest/globals";
+import { validate } from "class-validator";
+
+import { IsLessThanOrEqual } from "./is-less-than-or-equal.decorator";
+
+class Dto {
+  max: number;
+  @IsLessThanOrEqual("max")
+  min: number;
+}
+
+describe("IsLessThanOrEqual", () => {
+  it("should pass when value is less", async () => {
+    const dto = Object.assign(new Dto(), { max: 10, min: 5 });
+    const errors = await validate(dto);
+    expect(errors).toHaveLength(0);
+  });
+
+  it("should pass when value is equal", async () => {
+    const dto = Object.assign(new Dto(), { max: 5, min: 5 });
+    const errors = await validate(dto);
+    expect(errors).toHaveLength(0);
+  });
+
+  it("should fail when value is greater", async () => {
+    const dto = Object.assign(new Dto(), { max: 5, min: 10 });
+    const errors = await validate(dto);
+    expect(errors.length).toBeGreaterThan(0);
+  });
+});

package/src/validation/is-less-than-or-equal.decorator.ts

@@ -0,0 +1,52 @@
+import {
+  registerDecorator,
+  ValidationArguments,
+  ValidationOptions,
+  ValidatorConstraint,
+  ValidatorConstraintInterface,
+} from "class-validator";
+
+import { isValidISODate } from "../utils";
+
+export function IsLessThanOrEqual(property: string, validationOptions?: ValidationOptions) {
+  return function (object: object, propertyName: string) {
+    registerDecorator({
+      target: object.constructor,
+      propertyName,
+      constraints: [property],
+      options: validationOptions,
+      validator: IsLessThanOrEqualConstraint,
+    });
+  };
+}
+
+@ValidatorConstraint({ name: "isLessThanOrEqual" })
+class IsLessThanOrEqualConstraint implements ValidatorConstraintInterface {
+  validate(value: unknown, args: ValidationArguments) {
+    const relatedPropertyName = args.constraints[0] as string;
+    const relatedValue = (args.object as Record<string, unknown>)[relatedPropertyName];
+
+    if (!relatedValue) {
+      return true;
+    }
+
+    if (typeof value === "number" && typeof relatedValue === "number") {
+      return value <= relatedValue;
+    }
+
+    if (value instanceof Date && relatedValue instanceof Date) {
+      return +value <= +relatedValue;
+    }
+
+    if (typeof value === "string" && typeof relatedValue === "string" && isValidISODate(value) && isValidISODate(relatedValue)) {
+      return +new Date(value) <= +new Date(relatedValue);
+    }
+
+    throw new Error("Unsupported comparison");
+  }
+
+  defaultMessage(args: ValidationArguments) {
+    const relatedPropertyName = args.constraints[0] as string;
+    return `${args.property} must be more than or equal ${relatedPropertyName}`;
+  }
+}

package/src/validation/is-less-than.decorator.spec.ts

@@ -0,0 +1,36 @@
+import { describe, it, expect } from "@jest/globals";
+import { validate } from "class-validator";
+
+import { IsLessThan } from "./is-less-than.decorator";
+
+class Dto {
+  max: number;
+  @IsLessThan("max")
+  min: number;
+}
+
+describe("IsLessThan", () => {
+  it("should pass when value is less", async () => {
+    const dto = Object.assign(new Dto(), { max: 10, min: 5 });
+    const errors = await validate(dto);
+    expect(errors).toHaveLength(0);
+  });
+
+  it("should fail when value is equal", async () => {
+    const dto = Object.assign(new Dto(), { max: 5, min: 5 });
+    const errors = await validate(dto);
+    expect(errors.length).toBeGreaterThan(0);
+  });
+
+  it("should fail when value is greater", async () => {
+    const dto = Object.assign(new Dto(), { max: 5, min: 10 });
+    const errors = await validate(dto);
+    expect(errors.length).toBeGreaterThan(0);
+  });
+
+  it("should pass when related value is falsy", async () => {
+    const dto = Object.assign(new Dto(), { max: 0, min: 5 });
+    const errors = await validate(dto);
+    expect(errors).toHaveLength(0);
+  });
+});

package/src/validation/is-less-than.decorator.ts

@@ -0,0 +1,52 @@
+import {
+  registerDecorator,
+  ValidationArguments,
+  ValidationOptions,
+  ValidatorConstraint,
+  ValidatorConstraintInterface,
+} from "class-validator";
+
+import { isValidISODate } from "../utils";
+
+export function IsLessThan(property: string, validationOptions?: ValidationOptions) {
+  return function (object: object, propertyName: string) {
+    registerDecorator({
+      target: object.constructor,
+      propertyName,
+      constraints: [property],
+      options: validationOptions,
+      validator: IsLessThanConstraint,
+    });
+  };
+}
+
+@ValidatorConstraint({ name: "isLessThan" })
+class IsLessThanConstraint implements ValidatorConstraintInterface {
+  validate(value: unknown, args: ValidationArguments) {
+    const relatedPropertyName = args.constraints[0] as string;
+    const relatedValue = (args.object as Record<string, unknown>)[relatedPropertyName];
+
+    if (!relatedValue) {
+      return true;
+    }
+
+    if (typeof value === "number" && typeof relatedValue === "number") {
+      return value < relatedValue;
+    }
+
+    if (value instanceof Date && relatedValue instanceof Date) {
+      return +value < +relatedValue;
+    }
+
+    if (typeof value === "string" && typeof relatedValue === "string" && isValidISODate(value) && isValidISODate(relatedValue)) {
+      return +new Date(value) < +new Date(relatedValue);
+    }
+
+    throw new Error("Unsupported comparison");
+  }
+
+  defaultMessage(args: ValidationArguments) {
+    const relatedPropertyName = args.constraints[0] as string;
+    return `${args.property} must be more than ${relatedPropertyName}`;
+  }
+}

package/src/validation/is-more-than-or-equal.decorator.spec.ts

@@ -0,0 +1,30 @@
+import { describe, it, expect } from "@jest/globals";
+import { validate } from "class-validator";
+
+import { IsMoreThanOrEqual } from "./is-more-than-or-equal.decorator";
+
+class Dto {
+  min: number;
+  @IsMoreThanOrEqual("min")
+  max: number;
+}
+
+describe("IsMoreThanOrEqual", () => {
+  it("should pass when value is greater", async () => {
+    const dto = Object.assign(new Dto(), { min: 5, max: 10 });
+    const errors = await validate(dto);
+    expect(errors).toHaveLength(0);
+  });
+
+  it("should pass when value is equal", async () => {
+    const dto = Object.assign(new Dto(), { min: 5, max: 5 });
+    const errors = await validate(dto);
+    expect(errors).toHaveLength(0);
+  });
+
+  it("should fail when value is less", async () => {
+    const dto = Object.assign(new Dto(), { min: 10, max: 5 });
+    const errors = await validate(dto);
+    expect(errors.length).toBeGreaterThan(0);
+  });
+});