@jsonresume/utils 0.2.0

package/src/__tests__/fixtures.js

@@ -0,0 +1,103 @@
+/**
+ * Shared fixtures for calculation helper tests.
+ *
+ * All date math in these tests pins "now" to FIXED_NOW via vi.setSystemTime
+ * so that open-ended entries (no endDate) produce deterministic values.
+ */
+
+/** Pinned system time used by every date-dependent test. */
+export const FIXED_NOW = new Date('2026-01-01T00:00:00Z');
+
+/**
+ * Work history (most recent first, matching JSON Resume convention):
+ * - Acme Corp (current, no endDate): 2021-01-01 -> now = ~5.0 years
+ * - Globex: 2018-01-01 -> 2021-01-01 = ~3.0 years
+ * - Acme Corp (again, duplicate company name): 2016-01-01 -> 2018-01-01 = ~2.0 years
+ * Total ~10.0 years, 2 unique companies, 3 unique positions, 5 highlights.
+ */
+export const work = [
+  {
+    name: 'Acme Corp',
+    position: 'Senior Engineer',
+    startDate: '2021-01-01',
+    industry: 'Technology',
+    highlights: ['Led platform migration', 'Mentored four engineers'],
+  },
+  {
+    name: 'Globex',
+    position: 'Engineer',
+    startDate: '2018-01-01',
+    endDate: '2021-01-01',
+    industry: 'Finance',
+    highlights: [
+      'Shipped payments service',
+      'Cut API latency 40%',
+      'On-call rotation lead',
+    ],
+  },
+  {
+    name: 'Acme Corp',
+    position: 'Junior Engineer',
+    startDate: '2016-01-01',
+    endDate: '2018-01-01',
+  },
+];
+
+export const education = [
+  {
+    institution: 'State University',
+    studyType: 'Bachelor of Science',
+    area: 'Computer Science',
+    startDate: '2012-09-01',
+    endDate: '2016-06-01',
+  },
+  {
+    institution: 'State University',
+    studyType: 'Master of Science',
+    area: 'Computer Science',
+    startDate: '2016-09-01',
+    endDate: '2018-06-01',
+  },
+];
+
+export const volunteer = [
+  {
+    organization: 'Code Club',
+    position: 'Mentor',
+    startDate: '2019-01-01',
+    endDate: '2022-01-01',
+  },
+  // No startDate: must be skipped by duration calculations.
+  { organization: 'Food Bank', position: 'Helper' },
+];
+
+export const skills = [
+  { name: 'Web', keywords: ['JavaScript', 'TypeScript', 'React'] },
+  { name: 'Ops', keywords: ['Docker'] },
+  // No keywords: contributes 0 to countTotalSkills but 1 category.
+  { name: 'Soft Skills' },
+];
+
+export const projects = [{ name: 'Project One' }, { name: 'Project Two' }];
+
+export const publications = [{ name: 'A Paper' }];
+
+export const awards = [{ title: 'Best Engineer' }];
+
+export const languages = [
+  { language: 'English', fluency: 'Native' },
+  { language: 'Spanish', fluency: 'Professional' },
+];
+
+/** A representative, fully-populated JSON Resume object. */
+export const fullResume = {
+  basics: { name: 'Jane Developer' },
+  work,
+  education,
+  volunteer,
+  skills,
+  projects,
+  publications,
+  awards,
+  languages,
+};

package/src/__tests__/keyMetrics.test.js

@@ -0,0 +1,56 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { calculateKeyMetrics } from '../metrics/keyMetrics.js';
+import { fullResume, skills, languages, FIXED_NOW } from './fixtures.js';
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  vi.setSystemTime(FIXED_NOW);
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe('calculateKeyMetrics', () => {
+  it('builds the full dashboard metric list in order for a populated resume', () => {
+    expect(calculateKeyMetrics(fullResume)).toEqual([
+      { label: 'Years Experience', value: 10 },
+      { label: 'Companies', value: 2 },
+      { label: 'Projects', value: 2 },
+      { label: 'Core Skills', value: 4 },
+      { label: 'Publications', value: 1 },
+      { label: 'Awards', value: 1 },
+      { label: 'Education', value: 'Master of Science' },
+      { label: 'Languages', value: 2 },
+    ]);
+  });
+
+  it('returns an empty array for an empty resume object', () => {
+    expect(calculateKeyMetrics({})).toEqual([]);
+  });
+
+  it('only includes metrics for populated sections', () => {
+    expect(calculateKeyMetrics({ skills })).toEqual([
+      { label: 'Core Skills', value: 4 },
+    ]);
+  });
+
+  it('omits the Languages metric unless multilingual (more than one)', () => {
+    expect(calculateKeyMetrics({ languages: [languages[0]] })).toEqual([]);
+    expect(calculateKeyMetrics({ languages })).toEqual([
+      { label: 'Languages', value: 2 },
+    ]);
+  });
+
+  it('omits Education when no studyType matches a known degree', () => {
+    expect(
+      calculateKeyMetrics({ education: [{ institution: 'No Degree U' }] })
+    ).toEqual([]);
+  });
+
+  // Documents current behavior: the resume argument has no default, so
+  // destructuring undefined throws. Callers must pass an object.
+  it('throws when called without a resume object', () => {
+    expect(() => calculateKeyMetrics()).toThrow(TypeError);
+  });
+});

package/src/__tests__/resume.test.js

@@ -0,0 +1,78 @@
+import { describe, it, expect } from 'vitest';
+import { formatLocation, normalizeResume } from '../resume.js';
+
+describe('formatLocation', () => {
+  it('joins city, region, countryCode with ", "', () => {
+    expect(
+      formatLocation({ city: 'Berlin', region: 'BE', countryCode: 'DE' })
+    ).toBe('Berlin, BE, DE');
+  });
+
+  it('drops empty / missing parts', () => {
+    expect(formatLocation({ city: 'Berlin', countryCode: 'DE' })).toBe(
+      'Berlin, DE'
+    );
+    expect(formatLocation({ region: 'CA' })).toBe('CA');
+  });
+
+  it('returns empty string for falsy / non-object input', () => {
+    expect(formatLocation()).toBe('');
+    expect(formatLocation(null)).toBe('');
+    expect(formatLocation('x')).toBe('');
+    expect(formatLocation({})).toBe('');
+  });
+});
+
+describe('normalizeResume', () => {
+  it('defaults all eleven array sections to [] and basics to {}', () => {
+    const out = normalizeResume({});
+    expect(out.basics).toEqual({});
+    for (const section of [
+      'work',
+      'volunteer',
+      'education',
+      'awards',
+      'certificates',
+      'publications',
+      'skills',
+      'languages',
+      'interests',
+      'references',
+      'projects',
+    ]) {
+      expect(out[section]).toEqual([]);
+    }
+  });
+
+  it('preserves existing sections and basics', () => {
+    const resume = {
+      basics: { name: 'A' },
+      work: [{ name: 'Co' }],
+    };
+    const out = normalizeResume(resume);
+    expect(out.basics).toEqual({ name: 'A' });
+    expect(out.work).toEqual([{ name: 'Co' }]);
+    expect(out.education).toEqual([]);
+  });
+
+  it('coerces non-array section values to []', () => {
+    expect(normalizeResume({ work: 'nope' }).work).toEqual([]);
+    expect(normalizeResume({ skills: { a: 1 } }).skills).toEqual([]);
+  });
+
+  it('handles falsy / non-object input by returning fully-defaulted shape', () => {
+    expect(normalizeResume().basics).toEqual({});
+    expect(normalizeResume(null).work).toEqual([]);
+  });
+
+  it('does not mutate the input', () => {
+    const resume = { basics: { name: 'A' } };
+    const out = normalizeResume(resume);
+    expect(resume.work).toBeUndefined();
+    expect(out).not.toBe(resume);
+  });
+
+  it('preserves unknown extra fields', () => {
+    expect(normalizeResume({ custom: 1 }).custom).toBe(1);
+  });
+});

package/src/__tests__/url.test.js

@@ -0,0 +1,113 @@
+import { describe, it, expect, vi } from 'vitest';
+import {
+  safeUrl,
+  getLinkRel,
+  sanitizeHtml,
+  isExternalUrl,
+  formatUrlForDisplay,
+} from '../url.js';
+
+describe('safeUrl', () => {
+  it('passes through safe protocols', () => {
+    expect(safeUrl('https://example.com')).toBe('https://example.com');
+    expect(safeUrl('mailto:a@b.com')).toBe('mailto:a@b.com');
+    expect(safeUrl('tel:+123')).toBe('tel:+123');
+  });
+
+  it('blocks dangerous schemes (returns null)', () => {
+    expect(safeUrl('javascript:alert(1)')).toBeNull();
+    expect(safeUrl('data:text/html,<script>')).toBeNull();
+    expect(safeUrl('vbscript:msgbox')).toBeNull();
+    expect(safeUrl('file:///etc/passwd')).toBeNull();
+    expect(safeUrl('about:blank')).toBeNull();
+  });
+
+  it('keeps relative URLs as-is', () => {
+    expect(safeUrl('/about')).toBe('/about');
+    expect(safeUrl('./x')).toBe('./x');
+  });
+
+  it('prefixes https for bare www and bare domains', () => {
+    expect(safeUrl('www.example.com')).toBe('https://www.example.com');
+    expect(safeUrl('example.com')).toBe('https://example.com');
+  });
+
+  it('returns null for falsy / non-string input', () => {
+    expect(safeUrl('')).toBeNull();
+    expect(safeUrl(null)).toBeNull();
+    expect(safeUrl(undefined)).toBeNull();
+    expect(safeUrl(42)).toBeNull();
+  });
+
+  it('does not write to the console for blocked or uncertain URLs', () => {
+    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    safeUrl('javascript:alert(1)');
+    safeUrl('some uncertain value');
+    expect(spy).not.toHaveBeenCalled();
+    spy.mockRestore();
+  });
+});
+
+describe('getLinkRel', () => {
+  it('adds noopener noreferrer for http(s) opening in a new tab', () => {
+    expect(getLinkRel('https://example.com', true)).toBe('noopener noreferrer');
+  });
+
+  it('returns empty otherwise', () => {
+    expect(getLinkRel('https://example.com', false)).toBe('');
+    expect(getLinkRel('mailto:a@b.com', true)).toBe('');
+    expect(getLinkRel('', true)).toBe('');
+  });
+});
+
+describe('sanitizeHtml', () => {
+  it('escapes HTML-significant characters', () => {
+    expect(sanitizeHtml('<script>alert(1)</script>')).toBe(
+      '&lt;script&gt;alert(1)&lt;/script&gt;'
+    );
+    expect(sanitizeHtml(`"&'`)).toBe('&quot;&amp;&#039;');
+  });
+
+  it('returns empty string for falsy / non-string input', () => {
+    expect(sanitizeHtml('')).toBe('');
+    expect(sanitizeHtml(null)).toBe('');
+  });
+});
+
+describe('isExternalUrl', () => {
+  it('treats relative, hash, mailto, tel as not external', () => {
+    expect(isExternalUrl('/about')).toBe(false);
+    expect(isExternalUrl('#top')).toBe(false);
+    expect(isExternalUrl('mailto:a@b.com')).toBe(false);
+  });
+
+  it('compares origins when one is provided', () => {
+    expect(isExternalUrl('https://other.com/x', 'https://me.com')).toBe(true);
+    expect(isExternalUrl('https://me.com/x', 'https://me.com')).toBe(false);
+  });
+
+  it('returns false for falsy / non-string input', () => {
+    expect(isExternalUrl('')).toBe(false);
+    expect(isExternalUrl(null)).toBe(false);
+  });
+});
+
+describe('formatUrlForDisplay', () => {
+  it('strips protocol and trailing slash', () => {
+    expect(formatUrlForDisplay('https://example.com/')).toBe('example.com');
+    expect(formatUrlForDisplay('http://example.com/blog')).toBe(
+      'example.com/blog'
+    );
+    expect(formatUrlForDisplay('https://example.com///')).toBe('example.com');
+  });
+
+  it('leaves protocol-less URLs alone (minus trailing slash)', () => {
+    expect(formatUrlForDisplay('example.com/')).toBe('example.com');
+  });
+
+  it('returns empty string for falsy / non-string input', () => {
+    expect(formatUrlForDisplay('')).toBe('');
+    expect(formatUrlForDisplay(null)).toBe('');
+    expect(formatUrlForDisplay(123)).toBe('');
+  });
+});

package/src/__tests__/workHistory.test.js

@@ -0,0 +1,107 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import {
+  calculateVolunteerYears,
+  getUniqueIndustries,
+  getCurrentEmployer,
+  isCurrentlyEmployed,
+} from '../metrics/workHistory.js';
+import { work, volunteer, FIXED_NOW } from './fixtures.js';
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  vi.setSystemTime(FIXED_NOW);
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe('calculateVolunteerYears', () => {
+  it('sums volunteer tenure, skipping entries without a startDate', () => {
+    // 3 years at Code Club; Food Bank entry has no startDate
+    expect(calculateVolunteerYears(volunteer)).toBe(3);
+  });
+
+  it('uses the current date for ongoing roles (no endDate)', () => {
+    expect(calculateVolunteerYears([{ startDate: '2024-01-01' }])).toBe(2);
+  });
+
+  it('returns 0 for empty, missing, or non-array input', () => {
+    expect(calculateVolunteerYears([])).toBe(0);
+    expect(calculateVolunteerYears()).toBe(0);
+    expect(calculateVolunteerYears(null)).toBe(0);
+    expect(calculateVolunteerYears('not-an-array')).toBe(0);
+  });
+});
+
+describe('getUniqueIndustries', () => {
+  it('returns unique industries in insertion order, skipping missing ones', () => {
+    expect(getUniqueIndustries(work)).toEqual(['Technology', 'Finance']);
+  });
+
+  it('deduplicates repeated industries', () => {
+    expect(
+      getUniqueIndustries([
+        { industry: 'Technology' },
+        { industry: 'Technology' },
+        { industry: 'Healthcare' },
+      ])
+    ).toEqual(['Technology', 'Healthcare']);
+  });
+
+  it('returns an empty array for empty, missing, or non-array input', () => {
+    expect(getUniqueIndustries([])).toEqual([]);
+    expect(getUniqueIndustries()).toEqual([]);
+    expect(getUniqueIndustries(null)).toEqual([]);
+  });
+});
+
+describe('getCurrentEmployer', () => {
+  it('returns the first job without an endDate', () => {
+    expect(getCurrentEmployer(work)).toBe(work[0]);
+  });
+
+  it('finds the current job even when it is not first in the array', () => {
+    const current = { name: 'Now Co', startDate: '2024-01-01' };
+    expect(
+      getCurrentEmployer([
+        { name: 'Old Co', startDate: '2018-01-01', endDate: '2021-01-01' },
+        current,
+      ])
+    ).toBe(current);
+  });
+
+  it('falls back to the first entry when every job has ended', () => {
+    const jobs = [
+      { name: 'A', startDate: '2018-01-01', endDate: '2021-01-01' },
+      { name: 'B', startDate: '2016-01-01', endDate: '2018-01-01' },
+    ];
+    expect(getCurrentEmployer(jobs)).toBe(jobs[0]);
+  });
+
+  it('returns null for empty, missing, or non-array input', () => {
+    expect(getCurrentEmployer([])).toBeNull();
+    expect(getCurrentEmployer()).toBeNull();
+    expect(getCurrentEmployer(null)).toBeNull();
+  });
+});
+
+describe('isCurrentlyEmployed', () => {
+  it('returns true when any job has no endDate', () => {
+    expect(isCurrentlyEmployed(work)).toBe(true);
+  });
+
+  it('returns false when every job has ended', () => {
+    expect(
+      isCurrentlyEmployed([
+        { name: 'A', startDate: '2018-01-01', endDate: '2021-01-01' },
+      ])
+    ).toBe(false);
+  });
+
+  it('returns false for empty, missing, or non-array input', () => {
+    expect(isCurrentlyEmployed([])).toBe(false);
+    expect(isCurrentlyEmployed()).toBe(false);
+    expect(isCurrentlyEmployed(null)).toBe(false);
+  });
+});