mielk-fn 1.0.26 → 1.0.28

package/.github/workflows/release.yaml

@@ -0,0 +1,39 @@
+name: release.yaml
+
+on:
+    push:
+        branches:
+            - master
+    workflow_dispatch:
+
+permissions:
+    contents: read
+    id-token: write
+
+jobs:
+    publish:
+        runs-on: ubuntu-latest
+
+        steps:
+            - name: Checkout repository
+              uses: actions/checkout@v4
+
+            - name: Setup Node.js
+              uses: actions/setup-node@v4
+              with:
+                  node-version: 20
+                  registry-url: https://registry.npmjs.org
+
+            - name: Install dependencies
+              run: npm install
+
+            - name: Run tests
+              run: npm test
+
+            - name: Build package
+              run: npm run build
+
+            - name: Publish to npm
+              run: npm publish
+              env:
+                  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
+
+### [1.0.28](https://github.com/mielk/mielk-fn/compare/v1.0.27...v1.0.28) (2026-03-25)
+
+### 1.0.27 (2026-03-25)

package/jest.config.js

@@ -0,0 +1,27 @@
+export default {
+  roots: ['<rootDir>/src'], // Specify the root directory for Jest to look for tests
+  transform: {
+    '^.+\\.tsx?$': 'ts-jest', // Transform TypeScript files using ts-jest
+  },
+  testMatch: [
+    '**/?(*.)+(spec|test).ts?(x)', // Match test files with .spec.ts or .test.ts extensions
+  ],
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
+  moduleNameMapper: {
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+  },
+  reporters: [
+    'default',
+    [
+      'jest-html-reporters',
+      {
+        publicPath: './reports/html-report',
+        filename: 'report.html',
+        pageTitle: 'mielk-fn - Test Report',
+        expand: true,
+        openReport: true,
+        groupBy: ['describe'],
+      },
+    ],
+  ],
+};

package/package.json

@@ -1,40 +1,83 @@
-{
-  "name": "mielk-fn",
-  "version": "1.0.26",
-  "description": "Set of helpful functions",
-  "main": "lib/index.js",
-  "type": "module",
-  "scripts": {
-    "prepublishOnly": "npm test",
-    "test": "jest --detectOpenHandles",
-    "build": "tsc"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/mielk/mielk-fn.git"
-  },
-  "author": "Tomasz Mielniczek",
-  "license": "ISC",
-  "bugs": {
-    "url": "https://github.com/mielk/mielk-fn/issues"
-  },
-  "homepage": "https://github.com/mielk/mielk-fn#readme",
-  "devDependencies": {
-    "@babel/cli": "^7.25.7",
-    "@babel/core": "^7.25.7",
-    "@babel/node": "^7.25.7",
-    "@babel/plugin-transform-modules-commonjs": "^7.25.7",
-    "@babel/preset-env": "^7.25.7",
-    "@babel/preset-typescript": "^7.25.7",
-    "@types/jest": "^29.5.13",
-    "@types/node": "^22.7.4",
-    "babel-jest": "^29.7.0",
-    "jest-html-reporters": "^3.1.7",
-    "ts-jest": "^29.2.5",
-    "tsc-alias": "^1.8.10",
-    "typescript": "^5.6.2"
-  },
-  "files": [
-    "lib"
-  ]
-}
+{
+	"name": "mielk-fn",
+	"version": "1.0.28",
+	"keywords": [],
+	"author": "mielk",
+	"description": "Generic functions used in various projects",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		},
+		"./arrays": {
+			"types": "./dist/arrays/index.d.ts",
+			"import": "./dist/arrays/index.js",
+			"default": "./dist/arrays/index.js"
+		},
+		"./dates": {
+			"types": "./dist/dates/index.d.ts",
+			"import": "./dist/dates/index.js",
+			"default": "./dist/dates/index.js"
+		},
+		"./io": {
+			"types": "./dist/io/index.d.ts",
+			"import": "./dist/io/index.js",
+			"default": "./dist/io/index.js"
+		},
+		"./math": {
+			"types": "./dist/math/index.d.ts",
+			"import": "./dist/math/index.js",
+			"default": "./dist/math/index.js"
+		},
+		"./objects": {
+			"types": "./dist/objects/index.d.ts",
+			"import": "./dist/objects/index.js",
+			"default": "./dist/objects/index.js"
+		},
+		"./regex": {
+			"types": "./dist/regex/index.d.ts",
+			"import": "./dist/regex/index.js",
+			"default": "./dist/regex/index.js"
+		},
+		"./strings": {
+			"types": "./dist/strings/index.d.ts",
+			"import": "./dist/strings/index.js",
+			"default": "./dist/strings/index.js"
+		},
+		"./types": {
+			"types": "./dist/types/index.d.ts",
+			"import": "./dist/types/index.js",
+			"default": "./dist/types/index.js"
+		},
+		"./variables": {
+			"types": "./dist/variables/index.d.ts",
+			"import": "./dist/variables/index.js",
+			"default": "./dist/variables/index.js"
+		}
+	},
+	"scripts": {
+		"test": "jest --detectOpenHandles",
+		"build": "tsc",
+		"prepublishOnly": "npm test && npm run build",
+		"dev": "tsc -w",
+		"release": "standard-version"
+	},
+	"license": "ISC",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/mielk/mielk-fn.git"
+	},
+	"homepage": "https://mielk.github.io/mielk-fn/",
+	"devDependencies": {
+		"@types/jest": "^30.0.0",
+		"jest": "^30.3.0",
+		"jest-html-reporters": "^3.1.7",
+		"standard-version": "^9.5.0",
+		"ts-jest": "^29.4.6",
+		"typescript": "^5.9.2"
+	}
+}

package/src/arrays/arrays.spec.ts

@@ -0,0 +1,113 @@
+import { toIndexedArray, toMap } from "./arrays.js";
+
+
+
+describe('toMap', () => {
+  const objects = [
+    { name: 'Adam', id: 1 },
+    { name: 'Bartek', id: 4 },
+    { name: 'Czesiek', id: 5 },
+  ];
+  const primitives = ['Adam', 'Bartek', 'Czesiek'];
+
+  it('should create a map from an array of objects', () => {
+    const map = toMap(objects, (obj) => obj.id);
+    expect(map.size).toBe(3);
+    expect(map.get(1)).toEqual(objects[0]);
+    expect(map.get(4)).toEqual(objects[1]);
+    expect(map.get(5)).toEqual(objects[2]);
+  });
+
+  it('should create a map from an array of primitives', () => {
+    const map = toMap(primitives, (str) => str.charAt(0));
+    expect(map.size).toBe(3);
+    expect(map.get('A')).toEqual(primitives[0]);
+    expect(map.get('B')).toEqual(primitives[1]);
+    expect(map.get('C')).toEqual(primitives[2]);
+  });
+
+  it('should allow custom value callback', () => {
+    const map = toMap(
+      objects,
+      (obj) => obj.id,
+      (obj) => obj.name
+    );
+    expect(map.size).toBe(3);
+    expect(map.get(1)).toBe('Adam');
+    expect(map.get(4)).toBe('Bartek');
+    expect(map.get(5)).toBe('Czesiek');
+  });
+
+  it('should ignore duplicate keys by default', () => {
+    const objectsWithDuplicate = [
+      { name: 'Adam', id: 1 },
+      { name: 'Bartek', id: 4 },
+      { name: 'Czesiek', id: 4 },
+    ];
+    const map = toMap(objectsWithDuplicate, (obj) => obj.id);
+    expect(map.size).toBe(2);
+    expect(map.get(1)).toEqual(objectsWithDuplicate[0]);
+    expect(map.get(4)).toEqual(objectsWithDuplicate[1]);
+  });
+});
+
+describe('toIndexedArray', () => {
+  it('should return an indexed array with basic objects', () => {
+    const items = [
+      { name: 'Adam', id: 1 },
+      { name: 'Bartek', id: 4 },
+      { name: 'Czesiek', id: 5 },
+    ];
+
+    const callback = (item: any) => item.id;
+    const result = toIndexedArray(items, callback);
+
+    expect(result[1]).toEqual({ name: 'Adam', id: 1 });
+    expect(result[4]).toEqual({ name: 'Bartek', id: 4 });
+    expect(result[5]).toEqual({ name: 'Czesiek', id: 5 });
+  });
+
+  it('should handle custom class instances', () => {
+    class Person {
+      fullName: string;
+      id: number;
+
+      constructor(fullName: string, id: number) {
+        this.fullName = fullName;
+        this.id = id;
+      }
+    }
+
+    const items = [new Person('Adam', 1), new Person('Bartek', 4), new Person('Czesiek', 5)];
+
+    const callback = (item: unknown) => {
+      if (typeof item === 'object' && item !== null && 'id' in item) {
+        return (item as Person).id;
+      }
+      return -1;
+    };
+    const result = toIndexedArray(items, callback);
+
+    expect(result[1]).toEqual(new Person('Adam', 1));
+    expect(result[4]).toEqual(new Person('Bartek', 4));
+    expect(result[5]).toEqual(new Person('Czesiek', 5));
+  });
+
+  it('should throw an error when the callback returns a non-number value', () => {
+    const items = [
+      { name: 'Adam', id: '1' },
+      { name: 'Bartek', id: '4' },
+      { name: 'Czesiek', id: '5' },
+    ];
+
+    const callback = (item: any) => item.id;
+    expect(() => toIndexedArray(items, callback)).toThrow(new TypeError('Callback should return a number.'));
+  });
+
+  it('should handle an empty array', () => {
+    const items: any[] = [];
+    const callback = (item: any) => item.id;
+    const result = toIndexedArray(items, callback);
+    expect(result).toEqual([]);
+  });
+});

package/src/arrays/arrays.ts

@@ -0,0 +1,30 @@
+export const toMap = (
+  items: any[],
+  keyCallback: (item: any) => string | number,
+  valueCallback: ((item: any) => any) = (item) => item,
+  ignoreDuplicates = true
+) => {
+  const map = new Map();
+  for (const item of items) {
+    const key = keyCallback(item);
+    const value = valueCallback ? valueCallback(item) : item;
+    if (!map.has(key) || !ignoreDuplicates) {
+      map.set(key, value);
+    }
+  }
+  return map;
+};
+
+export const toIndexedArray = <T>(items: T[], callback: (item: T) => number): T[] => {
+  const arr: any[] = [];
+  for (const item of items) {
+    const index = callback(item);
+    if (typeof index !== 'number') {
+      throw new TypeError('Callback should return a number.');
+    }
+    arr[index] = item;
+  }
+  return arr;
+};
+
+export default { toMap, toIndexedArray };

package/src/arrays/index.ts

@@ -0,0 +1 @@
+export * from './arrays.js';

package/src/dates/dates.spec.ts

@@ -0,0 +1,68 @@
+import { formatDateDefault } from "./dates";
+
+describe('formatDateDefault', () => {
+  it('should return empty string for undefined', () => {
+    expect(formatDateDefault(undefined)).toBe('');
+  });
+
+  it('should return string in format YYYY-MM-DD HH:mm:ss', () => {
+    const date = new Date('2024-01-02T03:04:05Z');
+
+    const result = formatDateDefault(date);
+
+    expect(result).toMatch(/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/);
+  });
+
+  it('should always have 2-digit month, day, hour, minute, second', () => {
+    const date = new Date('2024-04-05T06:07:08Z');
+
+    const result = formatDateDefault(date);
+
+    const [datePart, timePart] = result.split(' ');
+
+    const [year, month, day] = datePart.split('-');
+    const [hour, minute, second] = timePart.split(':');
+
+    expect(year.length).toBe(4);
+    expect(month.length).toBe(2);
+    expect(day.length).toBe(2);
+    expect(hour.length).toBe(2);
+    expect(minute.length).toBe(2);
+    expect(second.length).toBe(2);
+  });
+
+  it('should accept custom timeZone parameter', () => {
+    const date = new Date('2024-01-02T03:04:05Z');
+
+    const result = formatDateDefault(date, 'UTC');
+
+    expect(result).toMatch(/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/);
+  });
+
+  it('should still return valid structure for different time zones', () => {
+    const date = new Date('2024-06-15T10:20:30Z');
+
+    const resultWarsaw = formatDateDefault(date, 'Europe/Warsaw');
+    const resultUTC = formatDateDefault(date, 'UTC');
+
+    expect(resultWarsaw).toMatch(/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/);
+    expect(resultUTC).toMatch(/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/);
+
+    expect(resultWarsaw).not.toBe(resultUTC);
+  });
+
+  it('should be deterministic', () => {
+    const date = new Date('2024-06-15T10:20:30Z');
+
+    expect(formatDateDefault(date)).toBe(formatDateDefault(date));
+  });
+
+  it('should not mutate input date', () => {
+    const date = new Date('2024-01-01T00:00:00Z');
+    const time = date.getTime();
+
+    formatDateDefault(date);
+
+    expect(date.getTime()).toBe(time);
+  });
+});

package/src/dates/dates.ts

@@ -0,0 +1,34 @@
+const defaultTimeZone = 'Europe/Warsaw';
+const formatterCache = new Map<string, Intl.DateTimeFormat>();
+
+function getFormatter(timeZone: string) {
+	if (formatterCache.has(timeZone)) {
+		return formatterCache.get(timeZone)!;
+	}
+
+	const formatter = new Intl.DateTimeFormat('en-US', {
+		year: 'numeric',
+		month: '2-digit',
+		day: '2-digit',
+		hour: '2-digit',
+		minute: '2-digit',
+		second: '2-digit',
+		hour12: false,
+		timeZone,
+	});
+
+	formatterCache.set(timeZone, formatter);
+	return formatter;
+}
+
+
+export function formatDateDefault(date: Date | undefined, timeZone = defaultTimeZone): string {
+	if (!date) return '';
+
+	const formatter = getFormatter(timeZone);
+	const parts = formatter.formatToParts(date);
+	const map = Object.fromEntries(parts.map((p) => [p.type, p.value])) as Record<Intl.DateTimeFormatPartTypes, string>;
+	return `${map.year}-${map.month}-${map.day} ${map.hour}:${map.minute}:${map.second}`;
+}
+
+export default { formatDateToDefault: formatDateDefault }

package/src/dates/index.ts

@@ -0,0 +1 @@
+export * from './dates.js';

package/src/index.ts

@@ -0,0 +1,5 @@
+export * as dates from './dates/index.js';
+export * as numbers from './math/index.js';
+export * as objects from './variables/index.js';
+export * as strings from './strings/index.js';
+export * as types from './types/index.js';

package/src/io/index.ts

@@ -0,0 +1 @@
+export * from './io.js';

package/src/io/io.spec.ts

@@ -0,0 +1,81 @@
+import { parseJsonFile } from './io.js';
+
+describe('parseJson', () => {
+  it('should return default object when valid', () => {
+    const input = {
+      a: 12,
+      default: { x: 1, y: 2 },
+    };
+    expect(parseJsonFile(input)).toEqual({ x: 1, y: 2 });
+  });
+
+  it('should return empty object when default is missing', () => {
+    const input = { a: 12, b: 23 };
+    expect(parseJsonFile(input)).toEqual({});
+  });
+
+  it('should return empty object when default is null', () => {
+    const input = { default: null };
+    expect(parseJsonFile(input)).toEqual({});
+  });
+
+  it('should return empty object when default is not an object', () => {
+    expect(parseJsonFile({ default: 123 })).toEqual({});
+    expect(parseJsonFile({ default: 'text' })).toEqual({});
+    expect(parseJsonFile({ default: true })).toEqual({});
+  });
+
+  it('should return empty object when default is an array', () => {
+    expect(parseJsonFile({ default: [] })).toEqual({});
+  });
+
+  it('should return empty object when input is null', () => {
+    expect(parseJsonFile(null)).toEqual({});
+  });
+
+  it('should return empty object when input is undefined', () => {
+    expect(parseJsonFile(undefined)).toEqual({});
+  });
+
+  it('should return empty object when input is primitive', () => {
+    expect(parseJsonFile(123)).toEqual({});
+    expect(parseJsonFile('text')).toEqual({});
+    expect(parseJsonFile(true)).toEqual({});
+  });
+
+  it('should return empty object when input is array', () => {
+    expect(parseJsonFile([])).toEqual({});
+  });
+
+  it('should return empty object when default is a special object (Date, Map, etc.)', () => {
+    expect(parseJsonFile({ default: new Date() })).toEqual({});
+    expect(parseJsonFile({ default: new Map() })).toEqual({});
+  });
+
+  it('should handle nested default object', () => {
+    const input = {
+      default: {
+        nested: {
+          value: 42,
+        },
+      },
+    };
+
+    expect(parseJsonFile(input)).toEqual({
+      nested: {
+        value: 42,
+      },
+    });
+  });
+
+  it('should not mutate input object', () => {
+    const input = {
+      default: { a: 1 },
+    };
+
+    const result = parseJsonFile(input);
+
+    expect(result).toEqual({ a: 1 });
+    expect(input.default).toEqual({ a: 1 });
+  });
+});

package/src/io/io.ts

@@ -0,0 +1,9 @@
+import { isPlainObject } from "../variables";
+
+export const parseJsonFile = (file: unknown): Record<string, unknown> => {
+    if (file && typeof file === 'object' && 'default' in file) {
+        const value = (file as Record<string, unknown>).default;
+        return isPlainObject(value) ? value : {};
+    }
+    return {};
+}

package/src/math/index.ts

@@ -0,0 +1 @@
+export * from './math.js';

package/src/math/math.spec.ts

@@ -0,0 +1,94 @@
+import { formatPercent, formatWithSign } from "./math";
+
+describe('formatWithSign', () => {
+  it('formats positive numbers with + sign', () => {
+    expect(formatWithSign(1.234)).toBe('+1');
+  });
+
+  it('formats negative numbers with unicode minus', () => {
+    expect(formatWithSign(-1.234)).toBe('−1');
+  });
+
+  it('returns plain zero without sign', () => {
+    expect(formatWithSign(0)).toBe('0');
+  });
+
+  it('respects decimals', () => {
+    expect(formatWithSign(1.234, 2)).toBe('+1.23');
+    expect(formatWithSign(-1.234, 2)).toBe('−1.23');
+  });
+
+  it('rounds values correctly', () => {
+    expect(formatWithSign(1.235, 2)).toBe('+1.24');
+    expect(formatWithSign(-1.235, 2)).toBe('−1.24');
+  });
+
+  it('handles NaN', () => {
+    expect(formatWithSign(NaN)).toBe('NaN');
+  });
+
+  it('handles Infinity', () => {
+    expect(formatWithSign(Infinity)).toBe('+Infinity');
+    expect(formatWithSign(-Infinity)).toBe('−Infinity');
+  });
+
+  it('handles very large numbers', () => {
+    expect(formatWithSign(1e20)).toBe('+100000000000000000000');
+  });
+
+  it('handles very small numbers', () => {
+    expect(formatWithSign(1e-10, 0)).toBe('+0');
+  });
+});
+
+describe('formatPercent', () => {
+  it('formats positive percentages without plus by default', () => {
+    expect(formatPercent(0.1234)).toBe('12%');
+  });
+
+  it('formats positive percentages with plus when flag is true', () => {
+    expect(formatPercent(0.1234, 2, true)).toBe('+12.34%');
+  });
+
+  it('formats negative percentages', () => {
+    expect(formatPercent(-0.1234)).toBe('−12%');
+  });
+
+  it('formats negative percentages with decimals', () => {
+    expect(formatPercent(-0.1234, 2)).toBe('−12.34%');
+  });
+
+  it('handles zero', () => {
+    expect(formatPercent(0)).toBe('0%');
+  });
+
+  it('handles zero with plus flag (still no sign)', () => {
+    expect(formatPercent(0, 0, true)).toBe('0%');
+  });
+
+  it('handles zero with fraction and plus flag (still no sign)', () => {
+    expect(formatPercent(0, 2, true)).toBe('0.00%');
+  });
+
+  it('respects decimals', () => {
+    expect(formatPercent(0.1234, 2)).toBe('12.34%');
+  });
+
+  it('multiplies by 100 correctly', () => {
+    expect(formatPercent(1)).toBe('100%');
+    expect(formatPercent(0.01)).toBe('1%');
+  });
+
+  it('rounds correctly', () => {
+    expect(formatPercent(0.01479, 2)).toBe('1.48%');
+  });
+
+  it('handles NaN', () => {
+    expect(formatPercent(NaN)).toBe('NaN%');
+  });
+
+  it('handles Infinity', () => {
+    expect(formatPercent(Infinity)).toBe('Infinity%');
+    expect(formatPercent(-Infinity)).toBe('−Infinity%');
+  });
+});

package/src/math/math.ts

@@ -0,0 +1,12 @@
+export function formatWithSign(value: number, decimals = 0): string {
+	const rounded = value.toFixed(decimals);
+	if (isNaN(value)) return 'NaN';
+	if (value === 0) return rounded;
+	if (value > 0) return '+' + rounded;
+	return '−' + rounded.substring(1);
+}
+
+export function formatPercent(value: number, decimals = 0, plusPrefixForPositive = false): string {
+	if (!plusPrefixForPositive && value > 0) return (value * 100).toFixed(decimals) + '%';
+	return formatWithSign(value * 100, decimals) + '%';
+}

package/src/objects/index.ts

@@ -0,0 +1 @@
+export * from './objects.js';