@jsonresume/utils 0.2.0

package/src/metrics/index.js

@@ -0,0 +1,45 @@
+/**
+ * Resume Data Calculation Helpers
+ *
+ * Pure functions for computing metrics and insights from JSON Resume data.
+ * Use these helpers in themes to display calculated metrics, statistics, and insights.
+ *
+ * This module is a thin re-export barrel. The implementations live in focused
+ * sibling modules grouped by concern:
+ *   - ./experience.js   work tenure & career progression
+ *   - ./counts.js       simple section tallies
+ *   - ./education.js    education years & highest degree
+ *   - ./workHistory.js  employment status, industries, volunteer tenure
+ *   - ./keyMetrics.js   dashboard metrics aggregation
+ *
+ * @module @jsonresume/utils/metrics
+ */
+
+export {
+  calculateTotalExperience,
+  calculateCurrentRoleExperience,
+  countCareerPositions,
+  getCareerProgressionRate,
+  countTotalHighlights,
+} from './experience.js';
+
+export {
+  countCompanies,
+  countProjects,
+  countPublications,
+  countAwards,
+  countTotalSkills,
+  countSkillCategories,
+  countLanguages,
+} from './counts.js';
+
+export { calculateEducationYears, getHighestDegree } from './education.js';
+
+export {
+  calculateVolunteerYears,
+  getUniqueIndustries,
+  getCurrentEmployer,
+  isCurrentlyEmployed,
+} from './workHistory.js';
+
+export { calculateKeyMetrics } from './keyMetrics.js';

package/src/metrics/keyMetrics.js

@@ -0,0 +1,98 @@
+/**
+ * Resume Key Metrics Aggregation Helper
+ *
+ * Composes the focused calculation helpers into a dashboard-ready summary
+ * of key metrics derived from a complete JSON Resume object.
+ *
+ * @module @jsonresume/utils/metrics/keyMetrics
+ */
+
+import { calculateTotalExperience } from './experience.js';
+import {
+  countCompanies,
+  countProjects,
+  countTotalSkills,
+  countPublications,
+  countAwards,
+  countLanguages,
+} from './counts.js';
+import { getHighestDegree } from './education.js';
+
+/**
+ * Calculate comprehensive Key Metrics object for dashboard displays
+ * @param {Object} resume - Complete JSON Resume object
+ * @returns {Array<Object>} Array of metric objects with label and value
+ *
+ * @example
+ * const metrics = calculateKeyMetrics(resume);
+ * // => [
+ * //   { label: 'Years Experience', value: 8 },
+ * //   { label: 'Companies', value: 5 },
+ * //   { label: 'Projects', value: 12 },
+ * //   { label: 'Core Skills', value: 42 }
+ * // ]
+ */
+export function calculateKeyMetrics(resume) {
+  const metrics = [];
+
+  const {
+    work = [],
+    projects = [],
+    skills = [],
+    publications = [],
+    awards = [],
+    education = [],
+    languages = [],
+  } = resume;
+
+  // Experience
+  const experience = calculateTotalExperience(work);
+  if (experience > 0) {
+    metrics.push({ label: 'Years Experience', value: experience });
+  }
+
+  // Companies
+  const companies = countCompanies(work);
+  if (companies > 0) {
+    metrics.push({ label: 'Companies', value: companies });
+  }
+
+  // Projects
+  const projectCount = countProjects(projects);
+  if (projectCount > 0) {
+    metrics.push({ label: 'Projects', value: projectCount });
+  }
+
+  // Skills
+  const skillCount = countTotalSkills(skills);
+  if (skillCount > 0) {
+    metrics.push({ label: 'Core Skills', value: skillCount });
+  }
+
+  // Publications
+  const pubCount = countPublications(publications);
+  if (pubCount > 0) {
+    metrics.push({ label: 'Publications', value: pubCount });
+  }
+
+  // Awards
+  const awardCount = countAwards(awards);
+  if (awardCount > 0) {
+    metrics.push({ label: 'Awards', value: awardCount });
+  }
+
+  // Education
+  const degree = getHighestDegree(education);
+  if (degree) {
+    metrics.push({ label: 'Education', value: degree });
+  }
+
+  // Languages
+  const langCount = countLanguages(languages);
+  if (langCount > 1) {
+    // Only show if multilingual
+    metrics.push({ label: 'Languages', value: langCount });
+  }
+
+  return metrics;
+}

package/src/metrics/workHistory.js

@@ -0,0 +1,80 @@
+/**
+ * Resume Work History Insight Helpers
+ *
+ * Pure functions for deriving employment status, industries, and volunteer
+ * tenure from JSON Resume data.
+ *
+ * @module @jsonresume/utils/metrics/workHistory
+ */
+
+/**
+ * Calculate total volunteer hours (if duration data is available)
+ * @param {Array} volunteer - Array of volunteer objects with startDate and endDate
+ * @returns {number} Total volunteer years
+ *
+ * @example
+ * const volunteerYears = calculateVolunteerYears(resume.volunteer);
+ * // => 4
+ */
+export function calculateVolunteerYears(volunteer = []) {
+  if (!Array.isArray(volunteer) || volunteer.length === 0) return 0;
+
+  const totalYears = volunteer.reduce((acc, vol) => {
+    if (!vol.startDate) return acc;
+
+    const start = new Date(vol.startDate);
+    const end = vol.endDate ? new Date(vol.endDate) : new Date();
+    const years = (end - start) / (1000 * 60 * 60 * 24 * 365.25);
+
+    return acc + years;
+  }, 0);
+
+  return Math.round(totalYears);
+}
+
+/**
+ * Get all unique industries from work experience
+ * @param {Array} work - Array of work experience objects with industry field
+ * @returns {Array<string>} Array of unique industries
+ *
+ * @example
+ * const industries = getUniqueIndustries(resume.work);
+ * // => ["Technology", "Finance", "Healthcare"]
+ */
+export function getUniqueIndustries(work = []) {
+  if (!Array.isArray(work) || work.length === 0) return [];
+
+  const industries = new Set(work.map((job) => job.industry).filter(Boolean));
+
+  return Array.from(industries);
+}
+
+/**
+ * Get most recent/current employer
+ * @param {Array} work - Array of work experience objects
+ * @returns {Object|null} Most recent work object
+ *
+ * @example
+ * const current = getCurrentEmployer(resume.work);
+ * // => { name: "Google", position: "Senior Engineer", ... }
+ */
+export function getCurrentEmployer(work = []) {
+  if (!Array.isArray(work) || work.length === 0) return null;
+
+  // Find first job without endDate (current), or first in array
+  return work.find((job) => !job.endDate) || work[0];
+}
+
+/**
+ * Check if currently employed
+ * @param {Array} work - Array of work experience objects
+ * @returns {boolean} True if currently employed
+ *
+ * @example
+ * const employed = isCurrentlyEmployed(resume.work);
+ * // => true
+ */
+export function isCurrentlyEmployed(work = []) {
+  if (!Array.isArray(work) || work.length === 0) return false;
+  return work.some((job) => !job.endDate);
+}

package/src/resume.js

@@ -0,0 +1,72 @@
+/**
+ * Pure resume-shape utilities for JSON Resume.
+ *
+ * Framework-free helpers for formatting and normalizing resume data.
+ *
+ * @module @jsonresume/utils/resume
+ */
+
+/**
+ * The eleven standard array sections of a JSON Resume. Together with `basics`
+ * these make up the twelve standard sections normalizeResume guarantees.
+ * @type {ReadonlyArray<string>}
+ */
+const STANDARD_ARRAY_SECTIONS = [
+  'work',
+  'volunteer',
+  'education',
+  'awards',
+  'certificates',
+  'publications',
+  'skills',
+  'languages',
+  'interests',
+  'references',
+  'projects',
+];
+
+/**
+ * Format a JSON Resume location into a single display line.
+ * Drops empty parts and joins the rest with ', '.
+ *
+ * @param {Object} [location] - JSON Resume location object
+ * @returns {string} e.g. 'City, Region, CC' (empty string when nothing is set)
+ *
+ * @example
+ * formatLocation({ city: 'Berlin', region: 'BE', countryCode: 'DE' })
+ * // 'Berlin, BE, DE'
+ */
+export function formatLocation(location) {
+  if (!location || typeof location !== 'object') {
+    return '';
+  }
+
+  return [location.city, location.region, location.countryCode]
+    .filter(Boolean)
+    .join(', ');
+}
+
+/**
+ * Normalize a resume into an object with all twelve standard array sections
+ * defaulted to [] and `basics` defaulted to an object. Never mutates the input.
+ * Unknown extra fields are preserved (JSON Resume allows additional properties).
+ *
+ * @param {Object} [resume] - JSON Resume object (possibly partial)
+ * @returns {Object} A new object with standard sections guaranteed present
+ *
+ * @example
+ * normalizeResume({ basics: { name: 'A' } }).work // []
+ */
+export function normalizeResume(resume) {
+  const source = resume && typeof resume === 'object' ? resume : {};
+
+  const normalized = { ...source };
+  normalized.basics =
+    source.basics && typeof source.basics === 'object' ? source.basics : {};
+
+  for (const section of STANDARD_ARRAY_SECTIONS) {
+    normalized[section] = Array.isArray(source[section]) ? source[section] : [];
+  }
+
+  return normalized;
+}

package/src/url.js

@@ -0,0 +1,176 @@
+/**
+ * URL safety utilities for JSON Resume.
+ *
+ * Framework-free. Prevents XSS attacks and ensures safe URL handling.
+ *
+ * @module @jsonresume/utils/url
+ */
+
+/**
+ * Sanitizes URLs to prevent XSS attacks
+ * - Blocks javascript:, data:, vbscript: schemes
+ * - Allows http:, https:, mailto:, tel: schemes
+ * - Returns null for invalid/dangerous URLs
+ *
+ * @param {string} url - The URL to sanitize
+ * @returns {string|null} - Safe URL or null if dangerous
+ *
+ * @example
+ * safeUrl('https://example.com') // 'https://example.com'
+ * safeUrl('javascript:alert(1)') // null
+ * safeUrl('mailto:user@example.com') // 'mailto:user@example.com'
+ */
+export function safeUrl(url) {
+  if (!url || typeof url !== 'string') {
+    return null;
+  }
+
+  // Trim whitespace
+  const trimmed = url.trim();
+
+  // Check for dangerous protocols
+  const dangerousProtocols = /^(javascript|data|vbscript|file|about):/i;
+  if (dangerousProtocols.test(trimmed)) {
+    // Dangerous URL blocked. (Intentionally silent: no console output so this
+    // stays usable in SSR/library contexts that forbid console writes.)
+    return null;
+  }
+
+  // Allow safe protocols
+  const safeProtocols = /^(https?|mailto|tel|sms|ftp):/i;
+  if (safeProtocols.test(trimmed)) {
+    return trimmed;
+  }
+
+  // Allow relative URLs (starting with / or .)
+  if (trimmed.startsWith('/') || trimmed.startsWith('.')) {
+    return trimmed;
+  }
+
+  // Allow URLs without protocol (assume https)
+  if (/^www\./i.test(trimmed)) {
+    return `https://${trimmed}`;
+  }
+
+  // For other cases, check if it looks like a valid domain
+  // Allow alphanumeric, hyphens, dots, and common TLDs
+  if (/^[a-z0-9][a-z0-9.-]+\.[a-z]{2,}$/i.test(trimmed)) {
+    return `https://${trimmed}`;
+  }
+
+  // If we can't determine safety, return the original (let the browser handle
+  // it). Intentionally silent — no console output in this library context.
+  return trimmed;
+}
+
+/**
+ * Returns proper rel attribute for external links
+ * Adds security attributes for links opening in new windows
+ *
+ * @param {string} url - The URL to check
+ * @param {boolean} [openInNewTab=false] - Whether link opens in new tab
+ * @returns {string} - rel attribute value
+ *
+ * @example
+ * getLinkRel('https://example.com', true) // 'noopener noreferrer'
+ * getLinkRel('mailto:user@example.com', false) // ''
+ */
+export function getLinkRel(url, openInNewTab = false) {
+  if (!url || typeof url !== 'string') {
+    return '';
+  }
+
+  // Only add security attributes for http(s) links opening in new tabs
+  if (openInNewTab && /^https?:/i.test(url)) {
+    return 'noopener noreferrer';
+  }
+
+  return '';
+}
+
+/**
+ * Sanitizes HTML to prevent XSS
+ * Simple implementation that escapes dangerous characters
+ * For more complex needs, use DOMPurify
+ *
+ * @param {string} html - HTML string to sanitize
+ * @returns {string} - Sanitized HTML
+ *
+ * @example
+ * sanitizeHtml('<script>alert(1)</script>') // '&lt;script&gt;alert(1)&lt;/script&gt;'
+ */
+export function sanitizeHtml(html) {
+  if (!html || typeof html !== 'string') {
+    return '';
+  }
+
+  return html
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#039;');
+}
+
+/**
+ * Checks if a URL is external (different origin)
+ *
+ * @param {string} url - URL to check
+ * @param {string} [currentOrigin=null] - Current site origin (default: window.location.origin if available)
+ * @returns {boolean} - True if URL is external
+ *
+ * @example
+ * isExternalUrl('https://example.com') // true (if on different domain)
+ * isExternalUrl('/about') // false
+ */
+export function isExternalUrl(url, currentOrigin = null) {
+  if (!url || typeof url !== 'string') {
+    return false;
+  }
+
+  // Relative URLs are not external
+  if (url.startsWith('/') || url.startsWith('.') || url.startsWith('#')) {
+    return false;
+  }
+
+  // mailto:, tel:, etc. are not external in the HTTP sense
+  if (/^(mailto|tel|sms):/i.test(url)) {
+    return false;
+  }
+
+  // If no origin provided and we're in a browser, use window.location
+  if (!currentOrigin && typeof window !== 'undefined') {
+    currentOrigin = window.location.origin;
+  }
+
+  // If still no origin, we can't determine (assume external for safety)
+  if (!currentOrigin) {
+    return true;
+  }
+
+  try {
+    const urlObj = new URL(url, currentOrigin);
+    return urlObj.origin !== currentOrigin;
+  } catch (e) {
+    // Invalid URL, treat as external for safety
+    return true;
+  }
+}
+
+/**
+ * Format a URL for display: strip the protocol and any trailing slash.
+ *
+ * @param {string} url - URL to format
+ * @returns {string} Display-friendly URL (empty string for falsy/non-string)
+ *
+ * @example
+ * formatUrlForDisplay('https://example.com/') // 'example.com'
+ * formatUrlForDisplay('http://example.com/blog') // 'example.com/blog'
+ */
+export function formatUrlForDisplay(url) {
+  if (!url || typeof url !== 'string') {
+    return '';
+  }
+
+  return url.replace(/^[a-z][a-z0-9+.-]*:\/\//i, '').replace(/\/+$/, '');
+}