@utilix-tech/sdk 0.20.0 → 0.22.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 Full release notes for all Utilix surfaces (browser tools, REST API, SDKs, MCP server) live at [utilix.tech/changelog](https://utilix.tech/changelog). This file tracks just this package.
 
+## 0.22.0
+- Add `convertAprApy` (apr-apy-converter): convert between a nominal APR and effective APY for a given compounding frequency, in both directions.
+- Add `parseIso8601Duration` / `formatIso8601Duration` (iso8601-duration): parse an ISO 8601 duration into components and total seconds, or format seconds into a canonical duration string.
+
+## 0.21.0
+- Add `calculatePercentageChange` (percentage-change-calculator): percentage change between two numbers, with absolute change, direction, and multiplier.
+- Add `resolveJsonPointer` (json-pointer-resolver): resolve an RFC 6901 JSON Pointer against a document, with ~0/~1 escaping and clear not-found reasons.
+
 ## 0.20.0
 - Add `buildCacheControl` (cache-control-builder): assemble and explain a `Cache-Control` response header from directives, with warnings for combinations that cancel out.
 - Add `detectFillerWords` (filler-word-detector): scan text for filler words, hedge phrases, and clichés with per-phrase counts and a density score.

package/README.md

@@ -1,6 +1,6 @@
 # @utilix-tech/sdk
 
-**556 developer utility functions for Node.js: runs locally, no API key required.**
+**558 developer utility functions for Node.js: runs locally, no API key required.**
 
 [![npm version](https://img.shields.io/npm/v/@utilix-tech/sdk?style=flat-square&color=cb3837)](https://www.npmjs.com/package/@utilix-tech/sdk)
 [![npm downloads](https://img.shields.io/npm/dm/@utilix-tech/sdk?style=flat-square)](https://www.npmjs.com/package/@utilix-tech/sdk)
@@ -66,7 +66,7 @@ const { formatJson } = require("@utilix-tech/sdk/json");
 
 ```ts
 import { formatJson, minifyJson, diffJson, jsonToTypescript, validateJson,
-         evaluateJsonPath, jsonToCsv, yamlToJson, jsonToYaml, getJsonStats } from "@utilix-tech/sdk/json";
+         evaluateJsonPath, resolveJsonPointer, jsonToCsv, yamlToJson, jsonToYaml, getJsonStats } from "@utilix-tech/sdk/json";
 
 // Format with 2-space indent
 formatJson('{"name":"alice","age":30}', { indent: 2 });
@@ -80,6 +80,10 @@ jsonToTypescript('{"id":1,"name":"Alice"}', { rootName: "User" });
 // Query with JSONPath
 evaluateJsonPath(obj, "$.users[*].name");
 
+// Resolve an RFC 6901 JSON Pointer
+resolveJsonPointer('{"users":[{"name":"Alice"}]}', "/users/0/name");
+// { found: true, value: "Alice", tokens: ["users", "0", "name"] }
+
 // Convert JSON to CSV
 jsonToCsv('[{"a":1,"b":2}]');
 
@@ -230,7 +234,8 @@ generateData([
 
 ```ts
 import { diffDates, parseCron, convertTime, formatRelative,
-         getNextRuns, humanizeDiff } from "@utilix-tech/sdk/time";
+         getNextRuns, humanizeDiff, parseIso8601Duration,
+         formatIso8601Duration } from "@utilix-tech/sdk/time";
 
 formatRelative(new Date("2024-01-01"));  // "2 years ago"
 
@@ -245,6 +250,10 @@ parseCron("0 9 * * MON-FRI");
 // { description: "At 09:00, Monday through Friday", ... }
 
 getNextRuns("*/5 * * * *", 5);  // next 5 run timestamps
+
+// ISO 8601 durations, both directions
+parseIso8601Duration("P3DT4H30M");   // { totalSeconds: 275400, days: 3, ... }
+formatIso8601Duration(90061);        // { iso: "P1DT1H1M1S", ... }
 ```
 
 ---
@@ -252,7 +261,7 @@ getNextRuns("*/5 * * * *", 5);  // next 5 run timestamps
 ### `/units`: Conversions
 
 ```ts
-import { convertBytes, pxToAll, convert, formatValue, validateCardNumber, validateIban, calculateLoan, validateBarcode, calculateTax, calculateCompoundInterest, validateIsbn, calculateTipSplit, calculateSimpleInterest, calculateTimeValue } from "@utilix-tech/sdk/units";
+import { convertBytes, pxToAll, convert, formatValue, validateCardNumber, validateIban, calculateLoan, validateBarcode, calculateTax, calculateCompoundInterest, validateIsbn, calculateTipSplit, calculateSimpleInterest, calculateTimeValue, calculatePercentageChange, convertAprApy } from "@utilix-tech/sdk/units";
 
 // File sizes
 convertBytes(1073741824, "GB");  // 1
@@ -310,6 +319,14 @@ calculateSimpleInterest(1000, 5, 2);
 // Present / future value (time value of money), either direction
 calculateTimeValue(1000, 5, 10, "future");
 // { presentValue: 1000, futureValue: 1628.89, growthFactor: 1.628895, ... }
+
+// Percentage change between two numbers
+calculatePercentageChange(200, 250);
+// { percentChange: 25, absoluteChange: 50, direction: "increase", multiplier: 1.25 }
+
+// APR <-> APY conversion for a given compounding frequency
+convertAprApy(12, 12, "apr-to-apy");
+// { apr: 12, apy: 12.682503, difference: 0.682503, compoundsPerYear: 12, ... }
 ```
 
 ---

package/dist/{chunk-ZPQZEIXP.js → chunk-IEPWZERQ.js}

@@ -9,6 +9,7 @@ __export(time_exports, {
   convertTime: () => convertTime,
   diffDates: () => diffDates,
   formatInTimezone: () => formatInTimezone,
+  formatIso8601Duration: () => formatIso8601Duration,
   formatRelative: () => formatRelative,
   formatRunDate: () => formatRunDate,
   fromIsoString: () => fromIsoString,
@@ -21,7 +22,8 @@ __export(time_exports, {
   humanizeDiff: () => humanizeDiff,
   parseCron: () => parseCron,
   parseCronExpression: () => parseCronExpression,
-  parseDate: () => parseDate
+  parseDate: () => parseDate,
+  parseIso8601Duration: () => parseIso8601Duration
 });
 function formatRelative(diffMs) {
   const absMs = Math.abs(diffMs);
@@ -681,5 +683,96 @@ function getRunInterval(dates) {
   const days = Math.round(diffMins / 1440);
   return `Every ${days} days`;
 }
+var DURATION_SECONDS_PER_YEAR = 365 * 86400;
+var DURATION_SECONDS_PER_MONTH = 30 * 86400;
+function humanizeDurationParts(parts) {
+  const pieces = [];
+  for (const [value, label] of parts) {
+    if (value === 0) continue;
+    pieces.push(`${value} ${label}${value === 1 ? "" : "s"}`);
+  }
+  return pieces.length > 0 ? pieces.join(", ") : "0 seconds";
+}
+function parseIso8601Duration(input) {
+  if (typeof input !== "string") return { error: "Duration must be a string" };
+  const trimmed = input.trim();
+  if (trimmed.length === 0) return { error: "Duration is empty" };
+  const match = trimmed.match(
+    /^P(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)W)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?)?$/
+  );
+  if (!match) {
+    return { error: 'Not a valid ISO 8601 duration (expected a form like "P3DT4H30M")' };
+  }
+  const years = match[1] ? parseInt(match[1], 10) : 0;
+  const months = match[2] ? parseInt(match[2], 10) : 0;
+  const weeks = match[3] ? parseInt(match[3], 10) : 0;
+  const days = match[4] ? parseInt(match[4], 10) : 0;
+  const hours = match[5] ? parseInt(match[5], 10) : 0;
+  const minutes = match[6] ? parseInt(match[6], 10) : 0;
+  const seconds = match[7] ? parseFloat(match[7]) : 0;
+  if (years + months + weeks + days + hours + minutes + seconds === 0) {
+    return { error: 'Duration has no components (a bare "P" or "PT" is not valid)' };
+  }
+  const approximate = years > 0 || months > 0;
+  const totalSeconds = years * DURATION_SECONDS_PER_YEAR + months * DURATION_SECONDS_PER_MONTH + weeks * 7 * 86400 + days * 86400 + hours * 3600 + minutes * 60 + seconds;
+  const human = humanizeDurationParts([
+    [years, "year"],
+    [months, "month"],
+    [weeks, "week"],
+    [days, "day"],
+    [hours, "hour"],
+    [minutes, "minute"],
+    [seconds, "second"]
+  ]);
+  return {
+    input: trimmed,
+    years,
+    months,
+    weeks,
+    days,
+    hours,
+    minutes,
+    seconds,
+    totalSeconds: Math.round(totalSeconds * 1e6) / 1e6,
+    approximate,
+    human
+  };
+}
+function formatIso8601Duration(seconds) {
+  if (typeof seconds !== "number" || !Number.isFinite(seconds) || seconds < 0) {
+    return { error: "Seconds must be zero or a positive number" };
+  }
+  const totalDays = Math.floor(seconds / 86400);
+  let rem = seconds - totalDays * 86400;
+  const hours = Math.floor(rem / 3600);
+  rem -= hours * 3600;
+  const minutes = Math.floor(rem / 60);
+  let secs = rem - minutes * 60;
+  secs = Math.round(secs * 1e6) / 1e6;
+  let iso = "P";
+  if (totalDays > 0) iso += `${totalDays}D`;
+  const hasTime = hours > 0 || minutes > 0 || secs > 0;
+  if (hasTime) {
+    iso += "T";
+    if (hours > 0) iso += `${hours}H`;
+    if (minutes > 0) iso += `${minutes}M`;
+    if (secs > 0) iso += `${secs}S`;
+  }
+  if (iso === "P") iso = "PT0S";
+  const human = humanizeDurationParts([
+    [totalDays, "day"],
+    [hours, "hour"],
+    [minutes, "minute"],
+    [secs, "second"]
+  ]);
+  return {
+    seconds,
+    iso,
+    days: totalDays,
+    hours,
+    minutes,
+    human
+  };
+}
 
-export { COMMON_CRONS, COMMON_DATE_PRESETS, TIMEZONES, convertTime, diffDates, formatInTimezone, formatRelative, formatRunDate, fromIsoString, fromUnix, getAllZonesForTime, getNextRuns, getNow, getRunInterval, getTimezoneOffset, humanizeDiff, parseCron, parseCronExpression, parseDate, time_exports };
+export { COMMON_CRONS, COMMON_DATE_PRESETS, TIMEZONES, convertTime, diffDates, formatInTimezone, formatIso8601Duration, formatRelative, formatRunDate, fromIsoString, fromUnix, getAllZonesForTime, getNextRuns, getNow, getRunInterval, getTimezoneOffset, humanizeDiff, parseCron, parseCronExpression, parseDate, parseIso8601Duration, time_exports };

package/dist/{chunk-U34B5XPK.js → chunk-TLRSQHMP.js}

@@ -20,12 +20,14 @@ __export(units_exports, {
   calcSubnet: () => calcSubnet,
   calculateCompoundInterest: () => calculateCompoundInterest,
   calculateLoan: () => calculateLoan,
+  calculatePercentageChange: () => calculatePercentageChange,
   calculateSimpleInterest: () => calculateSimpleInterest,
   calculateTax: () => calculateTax,
   calculateTimeValue: () => calculateTimeValue,
   calculateTipSplit: () => calculateTipSplit,
   compareSemver: () => compareSemver,
   convert: () => convert,
+  convertAprApy: () => convertAprApy,
   convertBytes: () => convertBytes,
   convertIp: () => convertIp,
   coverBox: () => coverBox,
@@ -1337,5 +1339,60 @@ function calculateTimeValue(amount, annualRatePercent, years, direction, compoun
     interest: round22(futureValue - presentValue)
   };
 }
+function calculatePercentageChange(oldValue, newValue) {
+  if (!Number.isFinite(oldValue)) return { error: "Original value must be a finite number" };
+  if (!Number.isFinite(newValue)) return { error: "New value must be a finite number" };
+  if (oldValue === 0 && newValue !== 0) {
+    return { error: "Percentage change from zero is undefined (division by zero); use a nonzero original value" };
+  }
+  const round4 = (n) => Math.round(n * 1e4) / 1e4;
+  const absoluteChange = newValue - oldValue;
+  const percentChange = oldValue === 0 ? 0 : absoluteChange / Math.abs(oldValue) * 100;
+  const multiplier = oldValue === 0 ? 1 : newValue / oldValue;
+  let direction;
+  if (absoluteChange > 0) direction = "increase";
+  else if (absoluteChange < 0) direction = "decrease";
+  else direction = "no change";
+  return {
+    oldValue,
+    newValue,
+    absoluteChange: round4(absoluteChange),
+    percentChange: round4(percentChange),
+    direction,
+    multiplier: round4(multiplier)
+  };
+}
+function convertAprApy(rate, compoundsPerYear, direction) {
+  if (!Number.isFinite(rate) || rate < 0) return { error: "Rate must be zero or a positive number" };
+  if (!Number.isInteger(compoundsPerYear) || compoundsPerYear <= 0) {
+    return { error: "Compounding frequency must be a positive whole number of periods per year" };
+  }
+  if (direction !== "apr-to-apy" && direction !== "apy-to-apr") {
+    return { error: 'Direction must be "apr-to-apy" or "apy-to-apr"' };
+  }
+  const round6 = (n2) => Math.round(n2 * 1e6) / 1e6;
+  const round8 = (n2) => Math.round(n2 * 1e8) / 1e8;
+  const n = compoundsPerYear;
+  let aprDecimal;
+  let apyDecimal;
+  if (direction === "apr-to-apy") {
+    aprDecimal = rate / 100;
+    apyDecimal = Math.pow(1 + aprDecimal / n, n) - 1;
+  } else {
+    apyDecimal = rate / 100;
+    aprDecimal = n * (Math.pow(1 + apyDecimal, 1 / n) - 1);
+  }
+  const apr = round6(aprDecimal * 100);
+  const apy = round6(apyDecimal * 100);
+  return {
+    direction,
+    compoundsPerYear: n,
+    apr,
+    apy,
+    aprDecimal: round8(aprDecimal),
+    apyDecimal: round8(apyDecimal),
+    difference: round6(apy - apr)
+  };
+}
 
-export { BASE_LABELS, BASE_PREFIXES, BYTE_UNITS, COMMON_CURRENCIES, COMMON_LOCALES, COMMON_PERMISSIONS, COMMON_RATIOS, COMMON_SIZES, COMMON_TAX_RATES, COMMON_TIP_PERCENTAGES, COMMON_VIEWPORTS, autoFormat, bumpVersion, calcAspectRatio, calcSubnet, calculateCompoundInterest, calculateLoan, calculateSimpleInterest, calculateTax, calculateTimeValue, calculateTipSplit, compareSemver, convert, convertBytes, convertIp, coverBox, decimalToIp, decimalToIpCidr, describePermissions, fitIntoBox, formatNumber, formatValue, formatVwValue, formatWithSeparator, gcd, ipFromBinary, ipFromDecimal, ipFromHex, ipToBinary, ipToDecimal, ipToDecimalCidr, ipToHex, ipToOctal, isValid, isValidCidr, isValidIp, isValidIpv4, octalToPermissions, parseFileSize, parseInput, parseNumberString, parseSemver, permissionsToChmod, permissionsToOctal, permissionsToSymbolic, ptToPx, pxToAll, pxToViewport, remToPx, satisfiesRange, scaleByHeight, scaleByWidth, sortVersions, splitSubnet, symbolicToPermissions, units_exports, validateBarcode, validateCardNumber, validateIban, validateIsbn, viewportToPx };
+export { BASE_LABELS, BASE_PREFIXES, BYTE_UNITS, COMMON_CURRENCIES, COMMON_LOCALES, COMMON_PERMISSIONS, COMMON_RATIOS, COMMON_SIZES, COMMON_TAX_RATES, COMMON_TIP_PERCENTAGES, COMMON_VIEWPORTS, autoFormat, bumpVersion, calcAspectRatio, calcSubnet, calculateCompoundInterest, calculateLoan, calculatePercentageChange, calculateSimpleInterest, calculateTax, calculateTimeValue, calculateTipSplit, compareSemver, convert, convertAprApy, convertBytes, convertIp, coverBox, decimalToIp, decimalToIpCidr, describePermissions, fitIntoBox, formatNumber, formatValue, formatVwValue, formatWithSeparator, gcd, ipFromBinary, ipFromDecimal, ipFromHex, ipToBinary, ipToDecimal, ipToDecimalCidr, ipToHex, ipToOctal, isValid, isValidCidr, isValidIp, isValidIpv4, octalToPermissions, parseFileSize, parseInput, parseNumberString, parseSemver, permissionsToChmod, permissionsToOctal, permissionsToSymbolic, ptToPx, pxToAll, pxToViewport, remToPx, satisfiesRange, scaleByHeight, scaleByWidth, sortVersions, splitSubnet, symbolicToPermissions, units_exports, validateBarcode, validateCardNumber, validateIban, validateIsbn, viewportToPx };

package/dist/{chunk-TSAGO3XP.js → chunk-WO3LJMVV.js}

@@ -24,6 +24,7 @@ __export(json_exports, {
   minifyJson: () => minifyJson,
   parseJson: () => parseJson,
   parseStructs: () => parseStructs,
+  resolveJsonPointer: () => resolveJsonPointer,
   toPascalCase: () => toPascalCase,
   toSnakeCase: () => toSnakeCase,
   validateJson: () => validateJson,
@@ -1249,5 +1250,57 @@ function jsonToZod(json, options) {
 
 export const ${rootName}Schema = ${schema}`;
 }
+function _unescapePointerToken(token) {
+  return token.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+function resolveJsonPointer(json, pointer) {
+  let parsed;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    return { pointer, found: false, tokens: [], error: "Invalid JSON input" };
+  }
+  let ptr = pointer;
+  if (ptr.startsWith("#")) {
+    ptr = ptr.slice(1);
+    try {
+      ptr = decodeURIComponent(ptr);
+    } catch {
+      return { pointer, found: false, tokens: [], error: "Invalid percent-encoding in URI-fragment pointer" };
+    }
+  }
+  if (ptr === "") {
+    return { pointer, found: true, value: parsed, tokens: [] };
+  }
+  if (!ptr.startsWith("/")) {
+    return { pointer, found: false, tokens: [], error: "Pointer must be empty or start with '/' (RFC 6901)" };
+  }
+  const tokens = ptr.split("/").slice(1).map(_unescapePointerToken);
+  let current = parsed;
+  for (const token of tokens) {
+    if (Array.isArray(current)) {
+      if (token === "-") {
+        return { pointer, found: false, tokens, failedAt: token, reason: '"-" refers to the nonexistent element after the end of the array' };
+      }
+      if (!/^(0|[1-9][0-9]*)$/.test(token)) {
+        return { pointer, found: false, tokens, failedAt: token, reason: `"${token}" is not a valid array index` };
+      }
+      const idx = Number(token);
+      if (idx >= current.length) {
+        return { pointer, found: false, tokens, failedAt: token, reason: `array index ${idx} is out of bounds (length ${current.length})` };
+      }
+      current = current[idx];
+    } else if (current !== null && typeof current === "object") {
+      const obj = current;
+      if (!Object.prototype.hasOwnProperty.call(obj, token)) {
+        return { pointer, found: false, tokens, failedAt: token, reason: `key "${token}" not found` };
+      }
+      current = obj[token];
+    } else {
+      return { pointer, found: false, tokens, failedAt: token, reason: `cannot descend into ${current === null ? "null" : typeof current} at "${token}"` };
+    }
+  }
+  return { pointer, found: true, value: current, tokens };
+}
 
-export { csvToJson, detectFormat, diffJson, evaluateJsonPath, formatDiffLine, formatJson, generateExample, getJsonStats, inferGoType, inferPythonType, inferType, jsonToCsv, jsonToGo, jsonToPython, jsonToTypescript, jsonToYaml, jsonToZod, json_exports, minifyJson, parseJson, parseStructs, toPascalCase, toSnakeCase, validateJson, validateJsonPath, validateJsonString, yamlToJson };
+export { csvToJson, detectFormat, diffJson, evaluateJsonPath, formatDiffLine, formatJson, generateExample, getJsonStats, inferGoType, inferPythonType, inferType, jsonToCsv, jsonToGo, jsonToPython, jsonToTypescript, jsonToYaml, jsonToZod, json_exports, minifyJson, parseJson, parseStructs, resolveJsonPointer, toPascalCase, toSnakeCase, validateJson, validateJsonPath, validateJsonString, yamlToJson };

package/dist/index.cjs

@@ -62,6 +62,7 @@ __export(json_exports, {
   minifyJson: () => minifyJson,
   parseJson: () => parseJson,
   parseStructs: () => parseStructs,
+  resolveJsonPointer: () => resolveJsonPointer,
   toPascalCase: () => toPascalCase,
   toSnakeCase: () => toSnakeCase,
   validateJson: () => validateJson,
@@ -1287,6 +1288,58 @@ function jsonToZod(json, options) {
 
 export const ${rootName}Schema = ${schema}`;
 }
+function _unescapePointerToken(token) {
+  return token.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+function resolveJsonPointer(json, pointer) {
+  let parsed;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    return { pointer, found: false, tokens: [], error: "Invalid JSON input" };
+  }
+  let ptr = pointer;
+  if (ptr.startsWith("#")) {
+    ptr = ptr.slice(1);
+    try {
+      ptr = decodeURIComponent(ptr);
+    } catch {
+      return { pointer, found: false, tokens: [], error: "Invalid percent-encoding in URI-fragment pointer" };
+    }
+  }
+  if (ptr === "") {
+    return { pointer, found: true, value: parsed, tokens: [] };
+  }
+  if (!ptr.startsWith("/")) {
+    return { pointer, found: false, tokens: [], error: "Pointer must be empty or start with '/' (RFC 6901)" };
+  }
+  const tokens = ptr.split("/").slice(1).map(_unescapePointerToken);
+  let current = parsed;
+  for (const token of tokens) {
+    if (Array.isArray(current)) {
+      if (token === "-") {
+        return { pointer, found: false, tokens, failedAt: token, reason: '"-" refers to the nonexistent element after the end of the array' };
+      }
+      if (!/^(0|[1-9][0-9]*)$/.test(token)) {
+        return { pointer, found: false, tokens, failedAt: token, reason: `"${token}" is not a valid array index` };
+      }
+      const idx = Number(token);
+      if (idx >= current.length) {
+        return { pointer, found: false, tokens, failedAt: token, reason: `array index ${idx} is out of bounds (length ${current.length})` };
+      }
+      current = current[idx];
+    } else if (current !== null && typeof current === "object") {
+      const obj = current;
+      if (!Object.prototype.hasOwnProperty.call(obj, token)) {
+        return { pointer, found: false, tokens, failedAt: token, reason: `key "${token}" not found` };
+      }
+      current = obj[token];
+    } else {
+      return { pointer, found: false, tokens, failedAt: token, reason: `cannot descend into ${current === null ? "null" : typeof current} at "${token}"` };
+    }
+  }
+  return { pointer, found: true, value: current, tokens };
+}
 
 // src/tools/encoding.ts
 var encoding_exports = {};
@@ -6091,6 +6144,7 @@ __export(time_exports, {
   convertTime: () => convertTime,
   diffDates: () => diffDates,
   formatInTimezone: () => formatInTimezone,
+  formatIso8601Duration: () => formatIso8601Duration,
   formatRelative: () => formatRelative,
   formatRunDate: () => formatRunDate,
   fromIsoString: () => fromIsoString,
@@ -6103,7 +6157,8 @@ __export(time_exports, {
   humanizeDiff: () => humanizeDiff,
   parseCron: () => parseCron,
   parseCronExpression: () => parseCronExpression,
-  parseDate: () => parseDate
+  parseDate: () => parseDate,
+  parseIso8601Duration: () => parseIso8601Duration
 });
 function formatRelative(diffMs) {
   const absMs = Math.abs(diffMs);
@@ -6763,6 +6818,97 @@ function getRunInterval(dates) {
   const days = Math.round(diffMins / 1440);
   return `Every ${days} days`;
 }
+var DURATION_SECONDS_PER_YEAR = 365 * 86400;
+var DURATION_SECONDS_PER_MONTH = 30 * 86400;
+function humanizeDurationParts(parts) {
+  const pieces = [];
+  for (const [value, label] of parts) {
+    if (value === 0) continue;
+    pieces.push(`${value} ${label}${value === 1 ? "" : "s"}`);
+  }
+  return pieces.length > 0 ? pieces.join(", ") : "0 seconds";
+}
+function parseIso8601Duration(input) {
+  if (typeof input !== "string") return { error: "Duration must be a string" };
+  const trimmed = input.trim();
+  if (trimmed.length === 0) return { error: "Duration is empty" };
+  const match = trimmed.match(
+    /^P(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)W)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?)?$/
+  );
+  if (!match) {
+    return { error: 'Not a valid ISO 8601 duration (expected a form like "P3DT4H30M")' };
+  }
+  const years = match[1] ? parseInt(match[1], 10) : 0;
+  const months = match[2] ? parseInt(match[2], 10) : 0;
+  const weeks = match[3] ? parseInt(match[3], 10) : 0;
+  const days = match[4] ? parseInt(match[4], 10) : 0;
+  const hours = match[5] ? parseInt(match[5], 10) : 0;
+  const minutes = match[6] ? parseInt(match[6], 10) : 0;
+  const seconds = match[7] ? parseFloat(match[7]) : 0;
+  if (years + months + weeks + days + hours + minutes + seconds === 0) {
+    return { error: 'Duration has no components (a bare "P" or "PT" is not valid)' };
+  }
+  const approximate = years > 0 || months > 0;
+  const totalSeconds = years * DURATION_SECONDS_PER_YEAR + months * DURATION_SECONDS_PER_MONTH + weeks * 7 * 86400 + days * 86400 + hours * 3600 + minutes * 60 + seconds;
+  const human = humanizeDurationParts([
+    [years, "year"],
+    [months, "month"],
+    [weeks, "week"],
+    [days, "day"],
+    [hours, "hour"],
+    [minutes, "minute"],
+    [seconds, "second"]
+  ]);
+  return {
+    input: trimmed,
+    years,
+    months,
+    weeks,
+    days,
+    hours,
+    minutes,
+    seconds,
+    totalSeconds: Math.round(totalSeconds * 1e6) / 1e6,
+    approximate,
+    human
+  };
+}
+function formatIso8601Duration(seconds) {
+  if (typeof seconds !== "number" || !Number.isFinite(seconds) || seconds < 0) {
+    return { error: "Seconds must be zero or a positive number" };
+  }
+  const totalDays = Math.floor(seconds / 86400);
+  let rem = seconds - totalDays * 86400;
+  const hours = Math.floor(rem / 3600);
+  rem -= hours * 3600;
+  const minutes = Math.floor(rem / 60);
+  let secs = rem - minutes * 60;
+  secs = Math.round(secs * 1e6) / 1e6;
+  let iso = "P";
+  if (totalDays > 0) iso += `${totalDays}D`;
+  const hasTime = hours > 0 || minutes > 0 || secs > 0;
+  if (hasTime) {
+    iso += "T";
+    if (hours > 0) iso += `${hours}H`;
+    if (minutes > 0) iso += `${minutes}M`;
+    if (secs > 0) iso += `${secs}S`;
+  }
+  if (iso === "P") iso = "PT0S";
+  const human = humanizeDurationParts([
+    [totalDays, "day"],
+    [hours, "hour"],
+    [minutes, "minute"],
+    [secs, "second"]
+  ]);
+  return {
+    seconds,
+    iso,
+    days: totalDays,
+    hours,
+    minutes,
+    human
+  };
+}
 
 // src/tools/units.ts
 var units_exports = {};
@@ -6784,12 +6930,14 @@ __export(units_exports, {
   calcSubnet: () => calcSubnet,
   calculateCompoundInterest: () => calculateCompoundInterest,
   calculateLoan: () => calculateLoan,
+  calculatePercentageChange: () => calculatePercentageChange,
   calculateSimpleInterest: () => calculateSimpleInterest,
   calculateTax: () => calculateTax,
   calculateTimeValue: () => calculateTimeValue,
   calculateTipSplit: () => calculateTipSplit,
   compareSemver: () => compareSemver,
   convert: () => convert,
+  convertAprApy: () => convertAprApy,
   convertBytes: () => convertBytes,
   convertIp: () => convertIp,
   coverBox: () => coverBox,
@@ -8101,6 +8249,61 @@ function calculateTimeValue(amount, annualRatePercent, years, direction, compoun
     interest: round23(futureValue - presentValue)
   };
 }
+function calculatePercentageChange(oldValue, newValue) {
+  if (!Number.isFinite(oldValue)) return { error: "Original value must be a finite number" };
+  if (!Number.isFinite(newValue)) return { error: "New value must be a finite number" };
+  if (oldValue === 0 && newValue !== 0) {
+    return { error: "Percentage change from zero is undefined (division by zero); use a nonzero original value" };
+  }
+  const round4 = (n) => Math.round(n * 1e4) / 1e4;
+  const absoluteChange = newValue - oldValue;
+  const percentChange = oldValue === 0 ? 0 : absoluteChange / Math.abs(oldValue) * 100;
+  const multiplier = oldValue === 0 ? 1 : newValue / oldValue;
+  let direction;
+  if (absoluteChange > 0) direction = "increase";
+  else if (absoluteChange < 0) direction = "decrease";
+  else direction = "no change";
+  return {
+    oldValue,
+    newValue,
+    absoluteChange: round4(absoluteChange),
+    percentChange: round4(percentChange),
+    direction,
+    multiplier: round4(multiplier)
+  };
+}
+function convertAprApy(rate, compoundsPerYear, direction) {
+  if (!Number.isFinite(rate) || rate < 0) return { error: "Rate must be zero or a positive number" };
+  if (!Number.isInteger(compoundsPerYear) || compoundsPerYear <= 0) {
+    return { error: "Compounding frequency must be a positive whole number of periods per year" };
+  }
+  if (direction !== "apr-to-apy" && direction !== "apy-to-apr") {
+    return { error: 'Direction must be "apr-to-apy" or "apy-to-apr"' };
+  }
+  const round6 = (n2) => Math.round(n2 * 1e6) / 1e6;
+  const round8 = (n2) => Math.round(n2 * 1e8) / 1e8;
+  const n = compoundsPerYear;
+  let aprDecimal;
+  let apyDecimal;
+  if (direction === "apr-to-apy") {
+    aprDecimal = rate / 100;
+    apyDecimal = Math.pow(1 + aprDecimal / n, n) - 1;
+  } else {
+    apyDecimal = rate / 100;
+    aprDecimal = n * (Math.pow(1 + apyDecimal, 1 / n) - 1);
+  }
+  const apr = round6(aprDecimal * 100);
+  const apy = round6(apyDecimal * 100);
+  return {
+    direction,
+    compoundsPerYear: n,
+    apr,
+    apy,
+    aprDecimal: round8(aprDecimal),
+    apyDecimal: round8(apyDecimal),
+    difference: round6(apy - apr)
+  };
+}
 
 // src/tools/network.ts
 var network_exports = {};

package/dist/index.d.cts

@@ -1,11 +1,11 @@
-export { j as json } from './json-BjSoIS1h.cjs';
+export { j as json } from './json-DEVFIpsC.cjs';
 export { e as encoding } from './encoding-Dk3wpmb3.cjs';
 export { h as hashing } from './hashing-CnetQFD_.cjs';
 export { t as text } from './text-DS70aMY5.cjs';
 export { d as data } from './data-D8XTI7Du.cjs';
 export { g as generators } from './generators-BGtRGpJZ.cjs';
-export { t as time } from './time-DbT8fjaF.cjs';
-export { u as units } from './units-BFTQwpBu.cjs';
+export { t as time } from './time-KqJjdqII.cjs';
+export { u as units } from './units-KrjRyu0w.cjs';
 export { n as network } from './network-BJOjJnmY.cjs';
 export { a as api } from './api-Xl7OzIgq.cjs';
 export { c as code } from './code-DaRvff2v.cjs';

package/dist/index.d.ts

@@ -1,11 +1,11 @@
-export { j as json } from './json-BjSoIS1h.js';
+export { j as json } from './json-DEVFIpsC.js';
 export { e as encoding } from './encoding-Dk3wpmb3.js';
 export { h as hashing } from './hashing-CnetQFD_.js';
 export { t as text } from './text-DS70aMY5.js';
 export { d as data } from './data-D8XTI7Du.js';
 export { g as generators } from './generators-BGtRGpJZ.js';
-export { t as time } from './time-DbT8fjaF.js';
-export { u as units } from './units-BFTQwpBu.js';
+export { t as time } from './time-KqJjdqII.js';
+export { u as units } from './units-KrjRyu0w.js';
 export { n as network } from './network-BJOjJnmY.js';
 export { a as api } from './api-Xl7OzIgq.js';
 export { c as code } from './code-DaRvff2v.js';

package/dist/index.js

@@ -1,5 +1,5 @@
 export { media_exports as media } from './chunk-XMKJYVKB.js';
-export { units_exports as units } from './chunk-U34B5XPK.js';
+export { units_exports as units } from './chunk-TLRSQHMP.js';
 export { network_exports as network } from './chunk-Y5OOP6WN.js';
 export { api_exports as api } from './chunk-Q3B3YWOA.js';
 export { code_exports as code } from './chunk-LXKIPPDG.js';
@@ -7,13 +7,13 @@ export { color_exports as color } from './chunk-BPVAB4P2.js';
 export { css_exports as css } from './chunk-6YPV2AB5.js';
 export { misc_exports as misc } from './chunk-GX7H6TAX.js';
 export { ai_agent_exports as ai_agent } from './chunk-265NPGKH.js';
-export { json_exports as json } from './chunk-TSAGO3XP.js';
+export { json_exports as json } from './chunk-WO3LJMVV.js';
 export { encoding_exports as encoding } from './chunk-DOWQZUTP.js';
 export { hashing_exports as hashing } from './chunk-GEFVMGZR.js';
 export { text_exports as text } from './chunk-2I4O5YCT.js';
 export { data_exports as data } from './chunk-TINQFTLO.js';
 export { generators_exports as generators } from './chunk-2CJSLYWI.js';
-export { time_exports as time } from './chunk-ZPQZEIXP.js';
+export { time_exports as time } from './chunk-IEPWZERQ.js';
 import './chunk-MLKGABMK.js';
 
 // src/index.ts