@jsfsi-core/ts-crossplatform 1.0.5

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@jsfsi-core/ts-crossplatform",
+  "version": "1.0.5",
+  "description": "",
+  "license": "ISC",
+  "author": "",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/src/index.d.ts",
+  "scripts": {
+    "build": "npm run lint && tsc && vite build",
+    "clean": "rm -rf dist && rm -rf node_modules && rm -rf coverage",
+    "format": "prettier --write \"src/**/*.{ts,tsx,js,jsx,json,css,md}\"",
+    "lint": "npm run lint:fix && npm run format",
+    "lint:fix": "eslint src --ext ts,tsx --report-unused-disable-directives --max-warnings 0 --fix",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "uuid": "11.1.0",
+    "zod": "3.25.67"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "3.2.4",
+    "vite": "7.0.0",
+    "vite-plugin-dts": "4.5.4",
+    "vitest": "3.2.4"
+  }
+}

package/src/configuration/configuration.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+
+import { parseConfig } from './configuration';
+
+describe('configuration', () => {
+  describe('parseConfig', () => {
+    it('parses config with valid schema', () => {
+      const schema = z.object({
+        foo: z.number(),
+        bar: z.string(),
+      });
+
+      const config = parseConfig(schema, {
+        foo: 3000,
+        bar: 'test',
+      });
+
+      expect(config).toEqual({
+        foo: 3000,
+        bar: 'test',
+      });
+    });
+
+    it('throws an error with invalid schema', () => {
+      const schema = z.object({
+        foo: z.number(),
+      });
+
+      expect(() =>
+        parseConfig(schema, {
+          foo: 'test',
+        }),
+      ).toThrow(
+        new Error(
+          'Invalid environment variables: [{"code":"invalid_type","expected":"number","received":"string","path":["foo"],"message":"Expected number, received string"}]',
+        ),
+      );
+    });
+  });
+});

package/src/configuration/configuration.ts

@@ -0,0 +1,14 @@
+import { z, ZodSchema } from 'zod';
+
+export const parseConfig = <T extends ZodSchema>(
+  configSchema: T,
+  env: unknown = process.env,
+): z.infer<T> => {
+  const result = configSchema.safeParse(env);
+
+  if (!result.success) {
+    throw new Error(`Invalid environment variables: ${JSON.stringify(result.error.issues)}`);
+  }
+
+  return result.data;
+};

package/src/datetime/datetime.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+
+import { formatDate, formatDateTime, formatTime, sleep } from './datetime';
+
+describe('datetime', () => {
+  describe('#sleep', () => {
+    it('sleeps for a 15ms', async () => {
+      const start = Date.now();
+      await sleep(15);
+      const end = Date.now();
+
+      expect(end - start).toBeGreaterThanOrEqual(15);
+    });
+  });
+
+  describe('#formatDate', () => {
+    it('formats a date', () => {
+      expect(formatDate(new Date('2025-01-01').getTime())).toEqual('01/01/2025');
+    });
+  });
+
+  describe('#formatTime', () => {
+    it.each`
+      date                                         | expected
+      ${new Date('2025-01-01T00:00:00').getTime()} | ${'00:00:00'}
+      ${new Date('2025-01-01T00:00:02').getTime()} | ${'00:00:02'}
+      ${new Date('2025-01-01T00:01:00').getTime()} | ${'00:01:00'}
+      ${new Date('2025-01-01T10:16:00').getTime()} | ${'10:16:00'}
+      ${new Date('2025-01-01T16:00:00').getTime()} | ${'16:00:00'}
+    `('formats a time', ({ date, expected }) => {
+      expect(formatTime(date)).toEqual(expected);
+    });
+  });
+
+  describe('#formatDateTime', () => {
+    it('formats a date and time', () => {
+      expect(formatDateTime(new Date('2025-01-01T00:00:00').getTime())).toEqual(
+        '01/01/2025 00:00:00',
+      );
+    });
+  });
+});

package/src/datetime/datetime.ts

@@ -0,0 +1,24 @@
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export function formatDate(date: number, locales?: Intl.LocalesArgument) {
+  return new Date(date).toLocaleDateString(locales, {
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+  });
+}
+
+export function formatTime(date: number, locales?: Intl.LocalesArgument) {
+  return new Date(date).toLocaleTimeString(locales, {
+    hour12: false,
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+  });
+}
+
+export function formatDateTime(date: number, locales?: Intl.LocalesArgument) {
+  return `${formatDate(date, locales)} ${formatTime(date, locales)}`;
+}

package/src/failures/failure.ts

@@ -0,0 +1,7 @@
+export class Failure {
+  public readonly name: string;
+
+  constructor() {
+    this.name = this.constructor.name;
+  }
+}

package/src/failures/index.ts

@@ -0,0 +1,2 @@
+export * from './failure';
+export * from './matchers';

package/src/failures/matchers.ts

@@ -0,0 +1,13 @@
+import { Failure } from './failure';
+
+export const notFailure =
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  <F extends Failure>(f: new (...args: any[]) => F) =>
+    <T>(m: T | F): m is Exclude<T, F> =>
+      !(m instanceof f);
+
+export const isFailure =
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  <F extends Failure>(f: new (...args: any[]) => F) =>
+    <T>(m: T | F): m is F =>
+      m instanceof f;

package/src/failures/matchers.unit.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest';
+
+import { Failure } from './failure';
+import { isFailure, notFailure } from './matchers';
+
+class FailureWithSingleProperty extends Failure {
+  constructor(public readonly property: string) {
+    super();
+  }
+}
+
+class FailureWithMultipleProperties extends Failure {
+  constructor(
+    public readonly property1: string,
+    public readonly property2: string,
+  ) {
+    super();
+  }
+}
+
+describe('matchers', () => {
+  it('matches when is not a failure', () => {
+    class NotAFailure {}
+
+    const result = notFailure(Failure)(NotAFailure);
+
+    expect(result).toBe(true);
+  });
+
+  it('matches when is not a failure with single property', () => {
+    const result = notFailure(FailureWithSingleProperty)(new Failure());
+
+    expect(result).toBe(true);
+  });
+
+  it('matches when is not a failure with multiple properties', () => {
+    const result = notFailure(FailureWithMultipleProperties)(new Failure());
+
+    expect(result).toBe(true);
+  });
+
+  it('matches when is a failure', () => {
+    const result = isFailure(Failure)(new Failure());
+
+    expect(result).toBe(true);
+  });
+
+  it('matches when is a failure with single property', () => {
+    const result = isFailure(FailureWithSingleProperty)(new FailureWithSingleProperty('test'));
+
+    expect(result).toBe(true);
+  });
+
+  it('matches when is a failure with multiple properties', () => {
+    const result = isFailure(FailureWithMultipleProperties)(
+      new FailureWithMultipleProperties('test1', 'test2'),
+    );
+
+    expect(result).toBe(true);
+  });
+});

package/src/guid/Guid.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest';
+
+import { Guid } from './Guid';
+
+describe('#Guid', () => {
+  it('created a valid guid', () => {
+    const guid = Guid.new();
+
+    expect(Guid.isValid(guid.toString())).toBe(true);
+  });
+
+  it.each([undefined, null])('null or empty guid is not valid', (guid?: string | null) => {
+    expect(Guid.isValid(guid)).toBe(false);
+  });
+
+  it('creates an empty string', () => {
+    const emptyGuid = Guid.empty();
+
+    expect(emptyGuid.toString()).toEqual('00000000-0000-0000-0000-000000000000');
+  });
+
+  it('validates different guids are equal', () => {
+    const firstGuid = Guid.new();
+    const secondGuid = new Guid(firstGuid.toString());
+
+    expect(firstGuid.equals(secondGuid)).toBe(true);
+  });
+
+  it.each`
+    value                                     | result
+    ${undefined}                              | ${undefined}
+    ${null}                                   | ${undefined}
+    ${''}                                     | ${undefined}
+    ${'invalid guid'}                         | ${undefined}
+    ${'9474c66b-4516-48d9-915b-be006d86fc4d'} | ${new Guid('9474c66b-4516-48d9-915b-be006d86fc4d')}
+  `(
+    'parses string `$value` to guid `$result`',
+    ({ value, result }: { value: string; result: Guid }) => {
+      const parsedGuid = Guid.parse(value);
+
+      expect(parsedGuid).toEqual(result);
+    },
+  );
+});

package/src/guid/Guid.ts

@@ -0,0 +1,34 @@
+import * as uuid from 'uuid';
+
+export class Guid {
+  private readonly uuid: string;
+
+  constructor(value: string) {
+    uuid.parse(value);
+    this.uuid = value;
+  }
+
+  public toString(): string {
+    return this.uuid;
+  }
+
+  public equals(other: Guid): boolean {
+    return this.uuid === other.toString();
+  }
+
+  public static new(): Guid {
+    return new Guid(uuid.v4());
+  }
+
+  public static empty(): Guid {
+    return new Guid(uuid.NIL);
+  }
+
+  public static isValid(value?: string | null): boolean {
+    return Boolean(value && uuid.validate(value));
+  }
+
+  public static parse(value: string): Guid | undefined {
+    return value && Guid.isValid(value) ? new Guid(value) : undefined;
+  }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from './mocks/mock';
+export * from './partials/RecursivePartial';
+export * from './result/result';
+export * from './failures';
+export * from './configuration/configuration';
+export * from './datetime/datetime';
+export * from './guid/Guid';
+export * from './paging';

package/src/mocks/mock.ts

@@ -0,0 +1,3 @@
+import { type RecursivePartial } from '../partials/RecursivePartial';
+
+export const mock = <T>(input: RecursivePartial<T> = {}): T => input as T;

package/src/mocks/mock.unit.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest';
+
+import { mock } from './mock';
+
+class SomeEntity {
+  a: string;
+  b: number;
+  c: boolean;
+}
+
+describe('mock', () => {
+  it('mocks an entity without properties', () => {
+    const mockedEntity = mock<SomeEntity>();
+
+    expect(mockedEntity).toEqual({});
+  });
+
+  it('mocks an entity with partial properties', () => {
+    const mockedEntity = mock<SomeEntity>({
+      b: 1,
+    });
+
+    expect(mockedEntity).toEqual({
+      b: 1,
+    });
+  });
+
+  it('mocks an entity with all properties', () => {
+    const mockedEntity = mock<SomeEntity>({
+      a: 'a',
+      b: 1,
+      c: true,
+    });
+
+    expect(mockedEntity).toEqual({
+      a: 'a',
+      b: 1,
+      c: true,
+    });
+  });
+});

package/src/paging/Page.ts

@@ -0,0 +1,20 @@
+import { z, ZodTypeAny } from 'zod';
+
+export const createPageSchema = <T extends ZodTypeAny>(elementSchema: T) =>
+  z.object({
+    pages: z.number(),
+    nextPage: z.number().optional(),
+    totalElements: z.number(),
+    currentPage: z.number(),
+    pageSize: z.number(),
+    elements: z.array(elementSchema),
+  });
+
+export type Page<T> = {
+  pages: number;
+  nextPage: number | undefined;
+  totalElements: number;
+  currentPage: number;
+  pageSize: number;
+  elements: T[];
+};

package/src/paging/PageQuery.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+
+export const PageQuery = z.object({
+  page: z.number(),
+  pageSize: z.number(),
+});
+
+export type PageQuery = z.infer<typeof PageQuery>;

package/src/paging/index.ts

@@ -0,0 +1,2 @@
+export * from './Page';
+export * from './PageQuery';

package/src/partials/RecursivePartial.ts

@@ -0,0 +1,3 @@
+export type RecursivePartial<T> = {
+  [P in keyof T]?: RecursivePartial<T[P]>;
+};

package/src/result/result.ts

@@ -0,0 +1,10 @@
+import { Failure } from '../failures/failure';
+
+export type Result<T = undefined, E extends Failure | undefined = Failure> = [T, E | undefined];
+
+export const Ok = <T>(value: T): Result<T, undefined> => [value, undefined];
+
+export const Fail = <T = undefined, E extends Failure = Failure>(failure: E): Result<T, E> => [
+  undefined as T,
+  failure,
+];

package/src/result/result.unit.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from 'vitest';
+
+import { Failure, isFailure } from '../failures';
+
+import { Fail, Ok, Result } from './result';
+
+describe('ResultTuple', () => {
+  describe('result with value', () => {
+    it('returns value', () => {
+      const doSomething = (): Result<number, Failure> => Ok(1);
+
+      const [value, error] = doSomething();
+
+      expect(value).toEqual(1);
+      expect(error).toBeUndefined();
+    });
+
+    it('returns value object with properties', () => {
+      const doSomething = (): Result<{ foo: string }, Failure> => Ok({ foo: 'bar' });
+
+      const [value] = doSomething();
+
+      expect(value.foo).toEqual('bar');
+    });
+  });
+
+  describe('result with failure', () => {
+    it('returns failure', () => {
+      const doSomething = () => Fail(new Failure());
+
+      const [value, failure] = doSomething();
+
+      expect(value).toBeUndefined();
+      expect(failure).toEqual(new Failure());
+    });
+
+    it('returns custom failure', () => {
+      class CustomFailure extends Failure {
+        constructor(public readonly message: string) {
+          super();
+        }
+      }
+
+      const doSomething = () => Fail(new CustomFailure('error'));
+
+      const [value, failure] = doSomething();
+
+      expect(value).toBeUndefined();
+      expect(failure).toEqual(new CustomFailure('error'));
+      expect(isFailure(CustomFailure)(failure)).toBe(true);
+    });
+
+    it('returns multiple custom failure types', () => {
+      class CustomFailure extends Failure {}
+      class AnotherCustomFailure extends Failure {}
+
+      const doSomething = (
+        failureType: 'custom' | 'another',
+      ): Result<number, CustomFailure | AnotherCustomFailure> =>
+        failureType === 'custom' ? Fail(new CustomFailure()) : Fail(new AnotherCustomFailure());
+
+      const [customValue, customFailure] = doSomething('custom');
+      const [anotherValue, anotherCustomFailure] = doSomething('another');
+
+      expect(customValue).toBeUndefined();
+      expect(anotherValue).toBeUndefined();
+      expect(customFailure).toEqual(new CustomFailure());
+      expect(anotherCustomFailure).toEqual(new AnotherCustomFailure());
+      expect(isFailure(CustomFailure)(customFailure)).toBe(true);
+      expect(isFailure(AnotherCustomFailure)(anotherCustomFailure)).toBe(true);
+    });
+
+    it('returns value without Ok function', () => {
+      const doSomething = (): Result<number, Failure> => [1, undefined];
+
+      const [value, failure] = doSomething();
+
+      expect(value).toEqual(1);
+      expect(failure).toBeUndefined();
+    });
+
+    it('returns failure without Fail function', () => {
+      const doSomething = (): Result<undefined, Failure> => [undefined, new Failure()];
+
+      const [value, failure] = doSomething();
+
+      expect(value).toBeUndefined();
+      expect(isFailure(Failure)(failure)).toEqual(true);
+    });
+
+    it('returns undefined value for void', () => {
+      const doSomething = () => Ok(undefined);
+
+      const [value, failure] = doSomething();
+
+      expect(value).toBeUndefined();
+      expect(failure).toBeUndefined();
+    });
+  });
+});

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*.ts", "vite.config.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/vite.config.ts

@@ -0,0 +1,24 @@
+import { defineConfig } from 'vite';
+import dts from 'vite-plugin-dts';
+
+export default defineConfig({
+  plugins: [
+    dts({
+      insertTypesEntry: true,
+    }),
+  ],
+  build: {
+    emptyOutDir: true,
+    lib: {
+      entry: 'src/index.ts',
+      formats: ['es', 'cjs'],
+      fileName: (format) => `index.${format === 'es' ? 'mjs' : 'cjs'}`,
+    },
+    rollupOptions: {
+      external: [],
+      output: {
+        globals: {},
+      },
+    },
+  },
+});

package/vitest.config.ts

@@ -0,0 +1,28 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  plugins: [],
+  test: {
+    globals: true,
+    environment: 'node',
+    setupFiles: [],
+    css: true,
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      include: ['src/**/*.ts'],
+      exclude: ['src/index.ts', 'src/paging/**'],
+      thresholds: {
+        statements: 100,
+        branches: 100,
+        functions: 100,
+        lines: 100,
+      },
+    },
+  },
+  resolve: {
+    alias: {
+      '@': '/src',
+    },
+  },
+});