@jsonresume/utils 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2014-2026 JSON Resume contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@jsonresume/utils",
+  "version": "0.2.0",
+  "private": false,
+  "description": "Framework-free pure utilities for JSON Resume: date formatting, metrics, and URL safety",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": "./src/index.js",
+    "./dates": "./src/dates.js",
+    "./metrics": "./src/metrics/index.js",
+    "./url": "./src/url.js"
+  },
+  "files": [
+    "src"
+  ],
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^2",
+    "@jsonresume/types": "0.2.0",
+    "@repo/eslint-config-custom": "^0.0.0",
+    "tsconfig": "0.0.0"
+  },
+  "keywords": [
+    "resume",
+    "cv",
+    "json-resume",
+    "dates",
+    "metrics",
+    "utilities"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jsonresume/jsonresume.org",
+    "directory": "packages/utils"
+  },
+  "homepage": "https://github.com/jsonresume/jsonresume.org/tree/master/packages/utils",
+  "bugs": {
+    "url": "https://github.com/jsonresume/jsonresume.org/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src --cache --cache-location node_modules/.cache/.eslintcache",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  }
+}

package/src/__tests__/calculations.test.js

@@ -0,0 +1,56 @@
+import { describe, it, expect } from 'vitest';
+import * as barrel from '../metrics/index.js';
+import { calculateTotalExperience } from '../metrics/experience.js';
+import { work } from './fixtures.js';
+
+/** Every public calculation helper, grouped by implementation module. */
+const EXPECTED_EXPORTS = [
+  // experience.js
+  'calculateTotalExperience',
+  'calculateCurrentRoleExperience',
+  'countCareerPositions',
+  'getCareerProgressionRate',
+  'countTotalHighlights',
+  // counts.js
+  'countCompanies',
+  'countProjects',
+  'countPublications',
+  'countAwards',
+  'countTotalSkills',
+  'countSkillCategories',
+  'countLanguages',
+  // education.js
+  'calculateEducationYears',
+  'getHighestDegree',
+  // workHistory.js
+  'calculateVolunteerYears',
+  'getUniqueIndustries',
+  'getCurrentEmployer',
+  'isCurrentlyEmployed',
+  // keyMetrics.js
+  'calculateKeyMetrics',
+];
+
+describe('metrics barrel', () => {
+  it('re-exports exactly the 19 calculation helpers', () => {
+    expect(EXPECTED_EXPORTS).toHaveLength(19);
+    expect(Object.keys(barrel).sort()).toEqual([...EXPECTED_EXPORTS].sort());
+  });
+
+  it('exports a function for every helper', () => {
+    for (const name of EXPECTED_EXPORTS) {
+      expect(barrel[name], `${name} should be a function`).toBeTypeOf(
+        'function'
+      );
+    }
+  });
+
+  it('re-exports the same implementations as the focused modules', () => {
+    expect(barrel.calculateTotalExperience).toBe(calculateTotalExperience);
+  });
+
+  it('helpers are callable through the barrel', () => {
+    // countCompanies is date-independent: 2 unique companies in the fixture.
+    expect(barrel.countCompanies(work)).toBe(2);
+  });
+});

package/src/__tests__/counts.test.js

@@ -0,0 +1,118 @@
+import { describe, it, expect } from 'vitest';
+import {
+  countCompanies,
+  countProjects,
+  countPublications,
+  countAwards,
+  countTotalSkills,
+  countSkillCategories,
+  countLanguages,
+} from '../metrics/counts.js';
+import {
+  work,
+  skills,
+  projects,
+  publications,
+  awards,
+  languages,
+} from './fixtures.js';
+
+describe('countCompanies', () => {
+  it('counts unique company names', () => {
+    // Acme Corp appears twice in the fixture
+    expect(countCompanies(work)).toBe(2);
+  });
+
+  it('ignores entries without a name', () => {
+    expect(
+      countCompanies([{ name: 'A' }, { position: 'Engineer' }, { name: 'B' }])
+    ).toBe(2);
+  });
+
+  it('returns 0 for empty, missing, or non-array input', () => {
+    expect(countCompanies([])).toBe(0);
+    expect(countCompanies()).toBe(0);
+    expect(countCompanies(null)).toBe(0);
+    expect(countCompanies('not-an-array')).toBe(0);
+  });
+});
+
+describe('countProjects', () => {
+  it('returns the number of projects', () => {
+    expect(countProjects(projects)).toBe(2);
+    expect(countProjects([{ name: 'Solo' }])).toBe(1);
+  });
+
+  it('returns 0 for empty, missing, or non-array input', () => {
+    expect(countProjects([])).toBe(0);
+    expect(countProjects()).toBe(0);
+    expect(countProjects(null)).toBe(0);
+    expect(countProjects({})).toBe(0);
+  });
+});
+
+describe('countPublications', () => {
+  it('returns the number of publications', () => {
+    expect(countPublications(publications)).toBe(1);
+  });
+
+  it('returns 0 for empty, missing, or non-array input', () => {
+    expect(countPublications([])).toBe(0);
+    expect(countPublications()).toBe(0);
+    expect(countPublications(null)).toBe(0);
+  });
+});
+
+describe('countAwards', () => {
+  it('returns the number of awards', () => {
+    expect(countAwards(awards)).toBe(1);
+  });
+
+  it('returns 0 for empty, missing, or non-array input', () => {
+    expect(countAwards([])).toBe(0);
+    expect(countAwards()).toBe(0);
+    expect(countAwards(null)).toBe(0);
+  });
+});
+
+describe('countTotalSkills', () => {
+  it('sums keywords across all skill categories', () => {
+    // 3 (Web) + 1 (Ops) + 0 (Soft Skills, no keywords)
+    expect(countTotalSkills(skills)).toBe(4);
+  });
+
+  it('treats categories without keywords as contributing 0', () => {
+    expect(countTotalSkills([{ name: 'Empty' }])).toBe(0);
+  });
+
+  it('returns 0 for empty, missing, or non-array input', () => {
+    expect(countTotalSkills([])).toBe(0);
+    expect(countTotalSkills()).toBe(0);
+    expect(countTotalSkills(null)).toBe(0);
+  });
+});
+
+describe('countSkillCategories', () => {
+  it('returns the number of skill categories', () => {
+    expect(countSkillCategories(skills)).toBe(3);
+  });
+
+  it('returns 0 for empty, missing, or non-array input', () => {
+    expect(countSkillCategories([])).toBe(0);
+    expect(countSkillCategories()).toBe(0);
+    expect(countSkillCategories(null)).toBe(0);
+  });
+});
+
+describe('countLanguages', () => {
+  it('returns the number of languages', () => {
+    expect(countLanguages(languages)).toBe(2);
+    expect(countLanguages([{ language: 'English' }])).toBe(1);
+  });
+
+  it('returns 0 for empty, missing, or non-array input', () => {
+    expect(countLanguages([])).toBe(0);
+    expect(countLanguages()).toBe(0);
+    expect(countLanguages(null)).toBe(0);
+  });
+});

package/src/__tests__/dates.test.js

@@ -0,0 +1,167 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import {
+  formatDateRange,
+  getRelativeTime,
+  getDuration,
+  normalizeDates,
+} from '../dates.js';
+
+const FIXED_NOW = new Date('2026-01-01T00:00:00Z');
+
+describe('formatDateRange', () => {
+  it('returns empty string when startDate is missing', () => {
+    expect(formatDateRange({ startDate: '' })).toBe('');
+    expect(formatDateRange({ startDate: null })).toBe('');
+    expect(formatDateRange({ startDate: undefined })).toBe('');
+  });
+
+  it('renders a single date (no "Present") when endDate is undefined', () => {
+    // An omitted endDate is a point in time (award/certificate/publication
+    // date), NOT an ongoing range. It must render just the start with no
+    // separator and no "Present" — single-date theme sections depend on this.
+    const out = formatDateRange({ startDate: '2020-01-15' });
+    expect(out).toContain('2020');
+    expect(out).not.toContain('Present');
+    expect(out).not.toContain(' - ');
+  });
+
+  it('shows "Present" for an ongoing role when endDate is null', () => {
+    const out = formatDateRange({ startDate: '2020-01-15', endDate: null });
+    expect(out).toContain('2020');
+    expect(out).toContain('Present');
+    expect(out).toContain(' - ');
+  });
+
+  it('distinguishes undefined (single date) from null (Present)', () => {
+    expect(formatDateRange({ startDate: '2020-01-15' })).not.toBe(
+      formatDateRange({ startDate: '2020-01-15', endDate: null })
+    );
+  });
+
+  it('formats a closed range with start and end', () => {
+    const out = formatDateRange({
+      startDate: '2018-06-01',
+      endDate: '2020-03-01',
+    });
+    expect(out).toContain('2018');
+    expect(out).toContain('2020');
+    expect(out).toContain(' - ');
+    expect(out).not.toContain('Present');
+  });
+
+  it('supports long and numeric month formats', () => {
+    expect(
+      formatDateRange({ startDate: '2020-01-15', format: 'long' })
+    ).toContain('January');
+    expect(
+      formatDateRange({ startDate: '2020-01-15', format: 'numeric' })
+    ).toMatch(/01\/2020|01\s*2020/);
+  });
+
+  it('localizes the present label (fr-FR => Présent, de => Heute)', () => {
+    expect(
+      formatDateRange({
+        startDate: '2020-01-15',
+        endDate: null,
+        locale: 'fr-FR',
+      })
+    ).toContain('Présent');
+    expect(
+      formatDateRange({ startDate: '2020-01-15', endDate: null, locale: 'de' })
+    ).toContain('Heute');
+  });
+
+  it('honours an explicit presentLabel override', () => {
+    expect(
+      formatDateRange({
+        startDate: '2020-01-15',
+        endDate: null,
+        presentLabel: 'Now',
+      })
+    ).toContain('Now');
+  });
+
+  it('returns an invalid start date string as-is (single date, undefined end)', () => {
+    expect(formatDateRange({ startDate: 'not-a-date' })).toBe('not-a-date');
+  });
+
+  it('tags an invalid start date with Present when endDate is explicitly null', () => {
+    expect(formatDateRange({ startDate: 'not-a-date', endDate: null })).toBe(
+      'not-a-date - Present'
+    );
+  });
+
+  it('accepts Date objects as well as strings', () => {
+    expect(
+      formatDateRange({ startDate: new Date('2021-05-01'), endDate: null })
+    ).toContain('2021');
+  });
+});
+
+describe('getRelativeTime', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(FIXED_NOW);
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('reports whole years ago', () => {
+    expect(getRelativeTime('2020-01-01')).toBe('6 years ago');
+  });
+
+  it('drops the suffix when ago=false', () => {
+    expect(getRelativeTime('2025-12-01', false)).toBe('1 month');
+  });
+
+  it('returns "just now" for the present moment', () => {
+    expect(getRelativeTime(FIXED_NOW)).toBe('just now');
+  });
+});
+
+describe('getDuration', () => {
+  it('reports years and months between two dates', () => {
+    expect(getDuration('2020-01-01', '2022-07-05')).toBe('2 years, 6 months');
+  });
+
+  it('reports whole years when no extra months', () => {
+    expect(getDuration('2020-01-01', '2023-01-02')).toBe('3 years');
+  });
+
+  it('reports months when under a year', () => {
+    expect(getDuration('2023-01-01', '2023-04-05')).toBe('3 months');
+  });
+
+  it('reports days when under a month', () => {
+    expect(getDuration('2023-01-01', '2023-01-10')).toBe('9 days');
+  });
+});
+
+describe('normalizeDates', () => {
+  it('stringifies Date-valued date fields across sections', () => {
+    const resume = {
+      basics: { name: 'A' },
+      work: [{ name: 'Co', startDate: new Date('2020-01-15T00:00:00Z') }],
+    };
+    const out = normalizeDates(resume);
+    expect(out.work[0].startDate).toBe('2020-01-15');
+  });
+
+  it('leaves string date fields untouched', () => {
+    const resume = { work: [{ startDate: '2020-01' }] };
+    expect(normalizeDates(resume).work[0].startDate).toBe('2020-01');
+  });
+
+  it('does not coerce non-Date object/array date fields', () => {
+    const resume = { work: [{ startDate: { y: 2020 } }] };
+    expect(normalizeDates(resume).work[0].startDate).toEqual({ y: 2020 });
+  });
+
+  it('does not mutate the input resume', () => {
+    const start = new Date('2020-01-15T00:00:00Z');
+    const resume = { work: [{ startDate: start }] };
+    normalizeDates(resume);
+    expect(resume.work[0].startDate).toBe(start);
+  });
+});

package/src/__tests__/education.test.js

@@ -0,0 +1,89 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import {
+  calculateEducationYears,
+  getHighestDegree,
+} from '../metrics/education.js';
+import { education, FIXED_NOW } from './fixtures.js';
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  vi.setSystemTime(FIXED_NOW);
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe('calculateEducationYears (BUGFIX: ms-per-year)', () => {
+  // The original implementation divided by ((ms-per-day) / 365.25) instead of
+  // (ms-per-day * 365.25), inflating results ~133M-fold. The fixture spans ~5.5
+  // real years of study; the fix now reports a sane, rounded number of years.
+  it('returns a realistic number of years for the fixture', () => {
+    expect(calculateEducationYears(education)).toBe(5);
+  });
+
+  it('returns realistic years for a single entry (~3.75y => 4)', () => {
+    expect(
+      calculateEducationYears([
+        { startDate: '2012-09-01', endDate: '2016-06-01' },
+      ])
+    ).toBe(4);
+  });
+
+  it('is the same order of magnitude as the real elapsed years (not inflated)', () => {
+    // Guards against a regression to the old (end-start)/(ms-per-day/365.25)
+    // formula, which returned 733057 for this fixture.
+    expect(calculateEducationYears(education)).toBeLessThan(20);
+  });
+
+  it('skips entries without a startDate', () => {
+    expect(calculateEducationYears([{ endDate: '2016-06-01' }, {}])).toBe(0);
+  });
+
+  it('returns 0 for empty, missing, or non-array input', () => {
+    expect(calculateEducationYears([])).toBe(0);
+    expect(calculateEducationYears()).toBe(0);
+    expect(calculateEducationYears(null)).toBe(0);
+    expect(calculateEducationYears('not-an-array')).toBe(0);
+  });
+});
+
+describe('getHighestDegree', () => {
+  it('returns the studyType of the highest ranked degree', () => {
+    expect(getHighestDegree(education)).toBe('Master of Science');
+  });
+
+  it('ranks doctorates above masters above bachelors', () => {
+    expect(
+      getHighestDegree([
+        { studyType: 'Bachelor of Arts' },
+        { studyType: 'PhD in Physics' },
+        { studyType: 'Master of Science' },
+      ])
+    ).toBe('PhD in Physics');
+  });
+
+  it('matches degree keywords case-insensitively', () => {
+    expect(getHighestDegree([{ studyType: 'BACHELOR OF ARTS' }])).toBe(
+      'BACHELOR OF ARTS'
+    );
+    expect(getHighestDegree([{ studyType: 'MBA' }])).toBe('MBA');
+  });
+
+  it('keeps the first entry on rank ties', () => {
+    expect(
+      getHighestDegree([{ studyType: 'Doctorate' }, { studyType: 'PhD' }])
+    ).toBe('Doctorate');
+  });
+
+  it('returns an empty string when no studyType matches a known degree', () => {
+    expect(getHighestDegree([{ studyType: 'Bootcamp' }])).toBe('');
+    expect(getHighestDegree([{ institution: 'No Study Type U' }])).toBe('');
+  });
+
+  it('returns an empty string for empty, missing, or non-array input', () => {
+    expect(getHighestDegree([])).toBe('');
+    expect(getHighestDegree()).toBe('');
+    expect(getHighestDegree(null)).toBe('');
+  });
+});

package/src/__tests__/experience.test.js

@@ -0,0 +1,150 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import {
+  calculateTotalExperience,
+  calculateCurrentRoleExperience,
+  countCareerPositions,
+  getCareerProgressionRate,
+  countTotalHighlights,
+} from '../metrics/experience.js';
+import { work, FIXED_NOW } from './fixtures.js';
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  vi.setSystemTime(FIXED_NOW);
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe('calculateTotalExperience', () => {
+  it('sums tenure across all jobs, rounded to nearest year', () => {
+    // ~5.0 (ongoing) + ~3.0 + ~2.0 years
+    expect(calculateTotalExperience(work)).toBe(10);
+  });
+
+  it('uses the current date for ongoing roles (no endDate)', () => {
+    expect(calculateTotalExperience([{ startDate: '2021-01-01' }])).toBe(5);
+  });
+
+  it('skips entries without a startDate', () => {
+    expect(
+      calculateTotalExperience([
+        { startDate: '2018-01-01', endDate: '2021-01-01' },
+        { endDate: '2020-01-01' },
+        {},
+      ])
+    ).toBe(3);
+  });
+
+  it('double-counts overlapping periods (naive per-job sum)', () => {
+    expect(
+      calculateTotalExperience([
+        { startDate: '2018-01-01', endDate: '2020-01-01' },
+        { startDate: '2019-01-01', endDate: '2021-01-01' },
+      ])
+    ).toBe(4);
+  });
+
+  it('returns 0 for empty, missing, or non-array input', () => {
+    expect(calculateTotalExperience([])).toBe(0);
+    expect(calculateTotalExperience()).toBe(0);
+    expect(calculateTotalExperience(null)).toBe(0);
+    expect(calculateTotalExperience('not-an-array')).toBe(0);
+  });
+});
+
+describe('calculateCurrentRoleExperience', () => {
+  it('measures the first role without an endDate, rounded to 1 decimal', () => {
+    expect(calculateCurrentRoleExperience(work)).toBe(5);
+  });
+
+  it('finds the current role even when it is not first in the array', () => {
+    expect(
+      calculateCurrentRoleExperience([
+        { startDate: '2018-01-01', endDate: '2021-01-01' },
+        { startDate: '2023-07-01' },
+      ])
+    ).toBe(2.5);
+  });
+
+  it('falls back to the first entry when every role has ended', () => {
+    expect(
+      calculateCurrentRoleExperience([
+        { startDate: '2018-01-01', endDate: '2021-01-01' },
+        { startDate: '2016-01-01', endDate: '2018-01-01' },
+      ])
+    ).toBe(3);
+  });
+
+  it('returns 0 when the selected role has no startDate', () => {
+    expect(calculateCurrentRoleExperience([{ position: 'Engineer' }])).toBe(0);
+  });
+
+  it('returns 0 for empty, missing, or non-array input', () => {
+    expect(calculateCurrentRoleExperience([])).toBe(0);
+    expect(calculateCurrentRoleExperience()).toBe(0);
+    expect(calculateCurrentRoleExperience(null)).toBe(0);
+  });
+});
+
+describe('countCareerPositions', () => {
+  it('counts unique position titles', () => {
+    expect(countCareerPositions(work)).toBe(3);
+  });
+
+  it('deduplicates repeated titles and ignores missing ones', () => {
+    expect(
+      countCareerPositions([
+        { position: 'Engineer' },
+        { position: 'Engineer' },
+        { name: 'No Position Inc' },
+        { position: 'Manager' },
+      ])
+    ).toBe(2);
+  });
+
+  it('returns 0 for empty, missing, or non-array input', () => {
+    expect(countCareerPositions([])).toBe(0);
+    expect(countCareerPositions()).toBe(0);
+    expect(countCareerPositions(null)).toBe(0);
+  });
+});
+
+describe('getCareerProgressionRate', () => {
+  it('returns average years per position, rounded to 1 decimal', () => {
+    // 10 total years / 3 unique positions
+    expect(getCareerProgressionRate(work)).toBe(3.3);
+  });
+
+  it('returns 0 when there is no work history', () => {
+    expect(getCareerProgressionRate([])).toBe(0);
+    expect(getCareerProgressionRate()).toBe(0);
+  });
+
+  it('returns 0 when total experience rounds down to 0 years', () => {
+    expect(
+      getCareerProgressionRate([
+        { position: 'Intern', startDate: '2025-11-01', endDate: '2025-12-01' },
+      ])
+    ).toBe(0);
+  });
+});
+
+describe('countTotalHighlights', () => {
+  it('sums highlights across all jobs', () => {
+    expect(countTotalHighlights(work)).toBe(5);
+  });
+
+  it('treats jobs without highlights as contributing 0', () => {
+    expect(
+      countTotalHighlights([{ highlights: ['a', 'b'] }, { name: 'None Inc' }])
+    ).toBe(2);
+  });
+
+  it('returns 0 for empty, missing, or non-array input', () => {
+    expect(countTotalHighlights([])).toBe(0);
+    expect(countTotalHighlights()).toBe(0);
+    expect(countTotalHighlights(null)).toBe(0);
+  });
+});