@jsonresume/utils 0.2.0

package/src/dates.js

@@ -0,0 +1,247 @@
+/**
+ * Pure date utilities for JSON Resume.
+ *
+ * Framework-free: no React, no styled-components. The styled DateRange /
+ * RelativeDate components in @jsonresume/core import these functions back.
+ *
+ * @module @jsonresume/utils/dates
+ */
+
+/**
+ * Date formatting utility with Intl.DateTimeFormat
+ * Formats date ranges for work/education experience with full locale support
+ *
+ * @param {Object} options - DateRange options
+ * @param {string|Date} options.startDate - Start date (ISO string or Date object)
+ * @param {string|Date} [options.endDate] - End date (ISO string, Date object, or null/undefined for "Present")
+ * @param {string} [options.format='short'] - Format style: 'short' (default), 'long', 'numeric'
+ * @param {string} [options.locale='en-US'] - BCP 47 locale (e.g., 'en-US', 'fr-FR', 'ar-SA')
+ * @param {string} [options.numberingSystem] - Numbering system (e.g., 'arab', 'latn', 'hanidec')
+ * @param {string} [options.presentLabel] - Custom label for present/ongoing (defaults to localized)
+ * @returns {string} Formatted date range
+ *
+ * @example
+ * formatDateRange({ startDate: '2020-01-15', endDate: null })
+ * // 'Jan 2020 - Present'
+ *
+ * @example
+ * formatDateRange({
+ *   startDate: '2020-01-15',
+ *   locale: 'fr-FR',
+ *   format: 'long'
+ * })
+ * // 'janvier 2020 - Présent'
+ *
+ * @example
+ * formatDateRange({
+ *   startDate: '2020-01-15',
+ *   locale: 'ar-SA',
+ *   numberingSystem: 'arab'
+ * })
+ * // With Arabic numerals
+ */
+export function formatDateRange({
+  startDate,
+  endDate,
+  format = 'short',
+  locale = 'en-US',
+  numberingSystem,
+  presentLabel,
+}) {
+  if (!startDate) return '';
+
+  // Determine "Present" label based on locale
+  const getPresentLabel = () => {
+    if (presentLabel) return presentLabel;
+
+    const labels = {
+      en: 'Present',
+      'en-US': 'Present',
+      'en-GB': 'Present',
+      fr: 'Présent',
+      'fr-FR': 'Présent',
+      es: 'Presente',
+      'es-ES': 'Presente',
+      de: 'Heute',
+      'de-DE': 'Heute',
+      it: 'Presente',
+      'it-IT': 'Presente',
+      pt: 'Presente',
+      'pt-BR': 'Presente',
+      ja: '現在',
+      'ja-JP': '現在',
+      zh: '至今',
+      'zh-CN': '至今',
+      'zh-TW': '至今',
+      ko: '현재',
+      'ko-KR': '현재',
+      ar: 'حاضر',
+      'ar-SA': 'حاضر',
+    };
+
+    return labels[locale] || labels[locale.split('-')[0]] || 'Present';
+  };
+
+  const formatDate = (dateStr) => {
+    if (!dateStr) return getPresentLabel();
+
+    const date = typeof dateStr === 'string' ? new Date(dateStr) : dateStr;
+
+    if (isNaN(date.getTime())) return dateStr; // Invalid date, return as-is
+
+    // Configure Intl.DateTimeFormat based on format style
+    const monthFormats = {
+      short: { month: 'short' },
+      long: { month: 'long' },
+      numeric: { month: '2-digit' },
+    };
+
+    const options = {
+      ...monthFormats[format],
+      year: 'numeric',
+    };
+
+    // Add numbering system if provided
+    if (numberingSystem) {
+      options.numberingSystem = numberingSystem;
+    }
+
+    // Use Intl.DateTimeFormat for proper locale support
+    const formatter = new Intl.DateTimeFormat(locale, options);
+    return formatter.format(date);
+  };
+
+  const start = formatDate(startDate);
+
+  // A genuinely absent endDate (key omitted -> undefined) is a single point in
+  // time (e.g. an award/certificate/publication date) and renders just the
+  // start. An explicit `null` endDate is the "ongoing" sentinel and renders
+  // start + separator + "Present" (formatDate returns the localized present
+  // label for a falsy-but-not-undefined value). This matches long-standing
+  // behavior; do not collapse the two — single-date sections depend on it.
+  if (endDate === undefined) {
+    return start;
+  }
+
+  const end = formatDate(endDate);
+
+  return `${start} - ${end}`;
+}
+
+/**
+ * Calculate relative time from a date
+ * @param {string|Date} date - Date to calculate from
+ * @param {boolean} [ago=true] - Include "ago" suffix
+ * @returns {string} Relative time string
+ *
+ * @example
+ * getRelativeTime('2020-01-01') // '6 years ago'
+ */
+export function getRelativeTime(date, ago = true) {
+  const now = new Date();
+  const past = new Date(date);
+  const diffMs = now - past;
+  const diffSec = Math.floor(diffMs / 1000);
+  const diffMin = Math.floor(diffSec / 60);
+  const diffHour = Math.floor(diffMin / 60);
+  const diffDay = Math.floor(diffHour / 24);
+  const diffWeek = Math.floor(diffDay / 7);
+  const diffMonth = Math.floor(diffDay / 30);
+  const diffYear = Math.floor(diffDay / 365);
+
+  const suffix = ago ? ' ago' : '';
+
+  if (diffYear > 0) {
+    return `${diffYear} year${diffYear !== 1 ? 's' : ''}${suffix}`;
+  }
+  if (diffMonth > 0) {
+    return `${diffMonth} month${diffMonth !== 1 ? 's' : ''}${suffix}`;
+  }
+  if (diffWeek > 0) {
+    return `${diffWeek} week${diffWeek !== 1 ? 's' : ''}${suffix}`;
+  }
+  if (diffDay > 0) {
+    return `${diffDay} day${diffDay !== 1 ? 's' : ''}${suffix}`;
+  }
+  if (diffHour > 0) {
+    return `${diffHour} hour${diffHour !== 1 ? 's' : ''}${suffix}`;
+  }
+  if (diffMin > 0) {
+    return `${diffMin} minute${diffMin !== 1 ? 's' : ''}${suffix}`;
+  }
+  return 'just now';
+}
+
+/**
+ * Calculate duration between two dates
+ * @param {string|Date} startDate - Start date
+ * @param {string|Date} [endDate=new Date()] - End date (defaults to now)
+ * @returns {string} Duration string
+ *
+ * @example
+ * getDuration('2020-01-01', '2022-07-01') // '2 years, 6 months'
+ */
+export function getDuration(startDate, endDate = new Date()) {
+  const start = new Date(startDate);
+  const end = new Date(endDate);
+  const diffMs = end - start;
+  const diffDay = Math.floor(diffMs / (1000 * 60 * 60 * 24));
+  const diffMonth = Math.floor(diffDay / 30);
+  const diffYear = Math.floor(diffDay / 365);
+
+  const years = diffYear;
+  const months = diffMonth % 12;
+
+  if (years > 0 && months > 0) {
+    return `${years} year${years !== 1 ? 's' : ''}, ${months} month${
+      months !== 1 ? 's' : ''
+    }`;
+  }
+  if (years > 0) {
+    return `${years} year${years !== 1 ? 's' : ''}`;
+  }
+  if (months > 0) {
+    return `${months} month${months !== 1 ? 's' : ''}`;
+  }
+  return `${diffDay} day${diffDay !== 1 ? 's' : ''}`;
+}
+
+/**
+ * Ensures all date fields in the resume are plain strings.
+ * Some themes (e.g. macchiato) use moment.js or Handlebars helpers that
+ * break when dates are Date objects instead of strings.
+ *
+ * @param {Object} resume - JSON Resume object
+ * @returns {Object} A shallow copy with Date-valued date fields stringified
+ */
+export function normalizeDates(resume) {
+  const dateFields = ['startDate', 'endDate', 'date', 'releaseDate'];
+  const sections = [
+    'work',
+    'education',
+    'volunteer',
+    'projects',
+    'awards',
+    'publications',
+  ];
+
+  const normalized = { ...resume };
+  for (const section of sections) {
+    if (Array.isArray(normalized[section])) {
+      normalized[section] = normalized[section].map((item) => {
+        const copy = { ...item };
+        for (const field of dateFields) {
+          if (copy[field] instanceof Date) {
+            copy[field] = copy[field].toISOString().split('T')[0];
+          }
+          // Non-Date, non-string values (plain objects, arrays, etc.) are left
+          // untouched. Previously these were String()-coerced, which turned a
+          // malformed object date into the literal "[object Object]" and joined
+          // arrays into comma strings — mangling the value handed to the theme.
+        }
+        return copy;
+      });
+    }
+  }
+  return normalized;
+}

package/src/index.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Public type surface for @jsonresume/utils.
+ *
+ * The runtime is plain JS (src/*.js); these declarations type the public API
+ * against @jsonresume/types so consumers get full inference.
+ */
+import type {
+  Resume,
+  ResumeLocation,
+  WorkItem,
+  VolunteerItem,
+  EducationItem,
+  SkillItem,
+} from '@jsonresume/types';
+
+// --- dates ---
+
+export interface DateRangeOptions {
+  startDate?: string | Date;
+  endDate?: string | Date | null;
+  format?: 'short' | 'long' | 'numeric';
+  locale?: string;
+  numberingSystem?: string;
+  presentLabel?: string;
+}
+
+export function formatDateRange(options: DateRangeOptions): string;
+export function getRelativeTime(date: string | Date, ago?: boolean): string;
+export function getDuration(
+  startDate: string | Date,
+  endDate?: string | Date
+): string;
+export function normalizeDates(resume: Resume): Resume;
+
+// --- metrics ---
+
+export interface KeyMetric {
+  label: string;
+  value: string | number;
+}
+
+export function calculateTotalExperience(work?: WorkItem[]): number;
+export function calculateCurrentRoleExperience(work?: WorkItem[]): number;
+export function countCareerPositions(work?: WorkItem[]): number;
+export function getCareerProgressionRate(work?: WorkItem[]): number;
+export function countTotalHighlights(work?: WorkItem[]): number;
+export function countCompanies(work?: WorkItem[]): number;
+export function countProjects(projects?: unknown[]): number;
+export function countPublications(publications?: unknown[]): number;
+export function countAwards(awards?: unknown[]): number;
+export function countTotalSkills(skills?: SkillItem[]): number;
+export function countSkillCategories(skills?: SkillItem[]): number;
+export function countLanguages(languages?: unknown[]): number;
+export function calculateEducationYears(education?: EducationItem[]): number;
+export function getHighestDegree(education?: EducationItem[]): string;
+export function calculateVolunteerYears(volunteer?: VolunteerItem[]): number;
+export function getUniqueIndustries(work?: WorkItem[]): string[];
+export function getCurrentEmployer(work?: WorkItem[]): WorkItem | null;
+export function isCurrentlyEmployed(work?: WorkItem[]): boolean;
+export function calculateKeyMetrics(resume: Resume): KeyMetric[];
+
+// --- url ---
+
+export function safeUrl(url: string): string | null;
+export function getLinkRel(url: string, openInNewTab?: boolean): string;
+export function sanitizeHtml(html: string): string;
+export function isExternalUrl(
+  url: string,
+  currentOrigin?: string | null
+): boolean;
+export function formatUrlForDisplay(url: string): string;
+
+// --- resume shape ---
+
+export function formatLocation(location?: ResumeLocation): string;
+export function normalizeResume(resume?: Partial<Resume>): Resume;

package/src/index.js

@@ -0,0 +1,54 @@
+/**
+ * @jsonresume/utils
+ *
+ * Framework-free pure utilities for JSON Resume. No React, no
+ * styled-components — safe to use anywhere (server, CLI, browser, themes).
+ *
+ * Subpath exports: './dates', './metrics', './url'. The root barrel below
+ * re-exports everything for convenience.
+ *
+ * @module @jsonresume/utils
+ */
+
+// Date utilities
+export {
+  formatDateRange,
+  getRelativeTime,
+  getDuration,
+  normalizeDates,
+} from './dates.js';
+
+// Metrics / calculation helpers
+export {
+  calculateTotalExperience,
+  calculateCurrentRoleExperience,
+  countCareerPositions,
+  getCareerProgressionRate,
+  countTotalHighlights,
+  countCompanies,
+  countProjects,
+  countPublications,
+  countAwards,
+  countTotalSkills,
+  countSkillCategories,
+  countLanguages,
+  calculateEducationYears,
+  getHighestDegree,
+  calculateVolunteerYears,
+  getUniqueIndustries,
+  getCurrentEmployer,
+  isCurrentlyEmployed,
+  calculateKeyMetrics,
+} from './metrics/index.js';
+
+// URL / security utilities
+export {
+  safeUrl,
+  getLinkRel,
+  sanitizeHtml,
+  isExternalUrl,
+  formatUrlForDisplay,
+} from './url.js';
+
+// Resume-shape utilities
+export { formatLocation, normalizeResume } from './resume.js';

package/src/metrics/counts.js

@@ -0,0 +1,107 @@
+/**
+ * Resume Count Calculation Helpers
+ *
+ * Pure functions for tallying simple counts across JSON Resume sections.
+ *
+ * @module @jsonresume/utils/metrics/counts
+ */
+
+/**
+ * Count total number of companies worked at
+ * @param {Array} work - Array of work experience objects
+ * @returns {number} Number of unique companies
+ *
+ * @example
+ * const companies = countCompanies(resume.work);
+ * // => 5
+ */
+export function countCompanies(work = []) {
+  if (!Array.isArray(work) || work.length === 0) return 0;
+
+  const uniqueCompanies = new Set(work.map((job) => job.name).filter(Boolean));
+
+  return uniqueCompanies.size;
+}
+
+/**
+ * Count total number of projects
+ * @param {Array} projects - Array of project objects
+ * @returns {number} Number of projects
+ *
+ * @example
+ * const projectCount = countProjects(resume.projects);
+ * // => 12
+ */
+export function countProjects(projects = []) {
+  return Array.isArray(projects) ? projects.length : 0;
+}
+
+/**
+ * Count total number of publications
+ * @param {Array} publications - Array of publication objects
+ * @returns {number} Number of publications
+ *
+ * @example
+ * const pubCount = countPublications(resume.publications);
+ * // => 8
+ */
+export function countPublications(publications = []) {
+  return Array.isArray(publications) ? publications.length : 0;
+}
+
+/**
+ * Count total number of awards received
+ * @param {Array} awards - Array of award objects
+ * @returns {number} Number of awards
+ *
+ * @example
+ * const awardCount = countAwards(resume.awards);
+ * // => 3
+ */
+export function countAwards(awards = []) {
+  return Array.isArray(awards) ? awards.length : 0;
+}
+
+/**
+ * Count total skills across all skill categories
+ * @param {Array} skills - Array of skill objects with keywords
+ * @returns {number} Total number of skill keywords
+ *
+ * @example
+ * const skillCount = countTotalSkills(resume.skills);
+ * // => 42
+ */
+export function countTotalSkills(skills = []) {
+  if (!Array.isArray(skills) || skills.length === 0) return 0;
+
+  return skills.reduce((total, skill) => {
+    const keywords = skill.keywords || [];
+    return total + keywords.length;
+  }, 0);
+}
+
+/**
+ * Count skill categories
+ * @param {Array} skills - Array of skill objects
+ * @returns {number} Number of skill categories
+ *
+ * @example
+ * const categories = countSkillCategories(resume.skills);
+ * // => 6
+ */
+export function countSkillCategories(skills = []) {
+  return Array.isArray(skills) ? skills.length : 0;
+}
+
+/**
+ * Count languages spoken
+ * @param {Array} languages - Array of language objects
+ * @returns {number} Number of languages
+ *
+ * @example
+ * const langCount = countLanguages(resume.languages);
+ * // => 3
+ */
+export function countLanguages(languages = []) {
+  return Array.isArray(languages) ? languages.length : 0;
+}

package/src/metrics/education.js

@@ -0,0 +1,74 @@
+/**
+ * Resume Education Calculation Helpers
+ *
+ * Pure functions for computing education metrics from JSON Resume data.
+ *
+ * @module @jsonresume/utils/metrics/education
+ */
+
+/**
+ * Calculate total education years
+ * @param {Array} education - Array of education objects with startDate and endDate
+ * @returns {number} Total years of education
+ *
+ * @example
+ * const eduYears = calculateEducationYears(resume.education);
+ * // => 6
+ */
+export function calculateEducationYears(education = []) {
+  if (!Array.isArray(education) || education.length === 0) return 0;
+
+  const totalYears = education.reduce((acc, edu) => {
+    if (!edu.startDate) return acc;
+
+    const start = new Date(edu.startDate);
+    const end = edu.endDate ? new Date(edu.endDate) : new Date();
+    // Use 365.25 for leap years (matches calculateTotalExperience). Previously
+    // this divided by (ms-per-day / 365.25), inflating the result ~133M-fold.
+    const years = (end - start) / (1000 * 60 * 60 * 24 * 365.25);
+
+    return acc + years;
+  }, 0);
+
+  return Math.round(totalYears);
+}
+
+/**
+ * Get highest education level
+ * @param {Array} education - Array of education objects with studyType
+ * @returns {string} Highest degree (PhD, Master's, Bachelor's, etc.)
+ *
+ * @example
+ * const degree = getHighestDegree(resume.education);
+ * // => "PhD"
+ */
+export function getHighestDegree(education = []) {
+  if (!Array.isArray(education) || education.length === 0) return '';
+
+  const degreeRanking = {
+    phd: 5,
+    doctorate: 5,
+    doctoral: 5,
+    master: 4,
+    mba: 4,
+    bachelor: 3,
+    associate: 2,
+    diploma: 1,
+    certificate: 1,
+  };
+
+  let highest = { level: 0, studyType: '' };
+
+  education.forEach((edu) => {
+    if (!edu.studyType) return;
+
+    const studyTypeLower = edu.studyType.toLowerCase();
+    for (const [key, level] of Object.entries(degreeRanking)) {
+      if (studyTypeLower.includes(key) && level > highest.level) {
+        highest = { level, studyType: edu.studyType };
+      }
+    }
+  });
+
+  return highest.studyType;
+}

package/src/metrics/experience.js

@@ -0,0 +1,111 @@
+/**
+ * Resume Experience Calculation Helpers
+ *
+ * Pure functions for computing work tenure and career progression metrics
+ * from JSON Resume work history.
+ *
+ * @module @jsonresume/utils/metrics/experience
+ */
+
+/**
+ * Calculate total years of professional experience from work history
+ * @param {Array} work - Array of work experience objects with startDate and endDate
+ * @returns {number} Total years of experience (rounded to nearest year)
+ *
+ * @example
+ * const years = calculateTotalExperience(resume.work);
+ * // => 8 (years)
+ */
+export function calculateTotalExperience(work = []) {
+  if (!Array.isArray(work) || work.length === 0) return 0;
+
+  const totalYears = work.reduce((acc, job) => {
+    if (!job.startDate) return acc;
+
+    const start = new Date(job.startDate);
+    const end = job.endDate ? new Date(job.endDate) : new Date();
+    const years = (end - start) / (1000 * 60 * 60 * 24 * 365.25); // Use 365.25 for leap years
+
+    return acc + years;
+  }, 0);
+
+  return Math.round(totalYears);
+}
+
+/**
+ * Calculate years of experience for the current/most recent role
+ * @param {Array} work - Array of work experience objects
+ * @returns {number} Years in current role (rounded to 1 decimal)
+ *
+ * @example
+ * const currentYears = calculateCurrentRoleExperience(resume.work);
+ * // => 2.5 (years)
+ */
+export function calculateCurrentRoleExperience(work = []) {
+  if (!Array.isArray(work) || work.length === 0) return 0;
+
+  // Assume first item is most recent (no endDate or latest endDate)
+  const currentRole = work.find((job) => !job.endDate) || work[0];
+  if (!currentRole || !currentRole.startDate) return 0;
+
+  const start = new Date(currentRole.startDate);
+  const end = currentRole.endDate ? new Date(currentRole.endDate) : new Date();
+  const years = (end - start) / (1000 * 60 * 60 * 24 * 365.25);
+
+  return Math.round(years * 10) / 10; // Round to 1 decimal
+}
+
+/**
+ * Calculate career trajectory (promotions/role changes)
+ * @param {Array} work - Array of work experience objects with position
+ * @returns {number} Number of distinct positions held
+ *
+ * @example
+ * const positions = countCareerPositions(resume.work);
+ * // => 7
+ */
+export function countCareerPositions(work = []) {
+  if (!Array.isArray(work) || work.length === 0) return 0;
+
+  const uniquePositions = new Set(
+    work.map((job) => job.position).filter(Boolean)
+  );
+
+  return uniquePositions.size;
+}
+
+/**
+ * Get career progression rate (positions per year)
+ * @param {Array} work - Array of work experience objects
+ * @returns {number} Average years per position
+ *
+ * @example
+ * const rate = getCareerProgressionRate(resume.work);
+ * // => 2.3 (years per position)
+ */
+export function getCareerProgressionRate(work = []) {
+  const totalYears = calculateTotalExperience(work);
+  const positions = countCareerPositions(work);
+
+  if (totalYears === 0 || positions === 0) return 0;
+
+  return Math.round((totalYears / positions) * 10) / 10;
+}
+
+/**
+ * Calculate total highlights/achievements across work experience
+ * @param {Array} work - Array of work experience objects with highlights
+ * @returns {number} Total number of highlights
+ *
+ * @example
+ * const achievements = countTotalHighlights(resume.work);
+ * // => 28
+ */
+export function countTotalHighlights(work = []) {
+  if (!Array.isArray(work) || work.length === 0) return 0;
+
+  return work.reduce((total, job) => {
+    const highlights = job.highlights || [];
+    return total + highlights.length;
+  }, 0);
+}