@utilix-tech/sdk 0.22.0 → 0.24.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.24.0
+- Add `calculateDiscount` / `applySuccessiveDiscounts` (discount-calculator): solve a sale price, amount saved, or discount percent from any one of them, and stack discounts in sequence where 20% then 10% is an effective 28% off.
+- Add `parseSubtitles`, `convertSubtitles`, `shiftSubtitles`, and their timestamp/format helpers (subtitle-converter): convert between SubRip and WebVTT and shift every cue by a fixed offset.
+
+## 0.23.0
+- Add `calculateMarginMarkup` (margin-markup-calculator): given exactly two of cost, price, margin percent, and markup percent, solve for the other two plus the gross profit.
+- Add `marginToMarkup` / `markupToMargin` helpers for converting between the two percentage bases.
+
 ## 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.

package/README.md

@@ -1,6 +1,6 @@
 # @utilix-tech/sdk
 
-**558 developer utility functions for Node.js: runs locally, no API key required.**
+**573 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)
@@ -170,12 +170,13 @@ detectFillerWords("At the end of the day, I just really think we should circle b
 
 ---
 
-### `/data`: CSV / YAML / TOML / XML / INI / NDJSON / .env diff
+### `/data`: CSV / YAML / TOML / XML / INI / NDJSON / .env diff / subtitles
 
 ```ts
 import { parseCsv, csvToJson, validateYaml, tomlToJson, jsonToToml,
          formatXml, xmlToJson, jsonToXml, parseIni,
-         validateNdjson, formatNdjson, ndjsonToJsonArray, diffEnvExample } from "@utilix-tech/sdk/data";
+         validateNdjson, formatNdjson, ndjsonToJsonArray, diffEnvExample,
+         parseSubtitles, convertSubtitles, shiftSubtitles } from "@utilix-tech/sdk/data";
 
 // CSV
 const rows = parseCsv("name,age\nalice,30\nbob,25");
@@ -203,6 +204,12 @@ ndjsonToJsonArray('{"id":1}\n{"id":2}');     // '[\n  { "id": 1 },\n  { "id": 2
 // Diff a .env file against its .env.example template
 diffEnvExample("FOO=1\nBAR=2", "FOO=\nBAR=y\nBAZ=z");
 // { missingInExample: [], missingInEnv: ["BAZ"], emptyValueInExample: ["FOO"], keysInBoth: 2 }
+
+// Subtitles: SubRip <-> WebVTT, with an optional resync offset
+convertSubtitles("1\n00:00:01,000 --> 00:00:04,000\nHello there.\n", "vtt");
+// { format: "vtt", sourceFormat: "srt", output: "WEBVTT\n\n00:00:01.000 --> ...", cueCount: 1, ... }
+shiftSubtitles("1\n00:00:01,000 --> 00:00:04,000\nHi\n", -2.5);
+// shifts every cue 2.5s earlier, clamping anything below zero to 00:00:00
 ```
 
 ---
@@ -261,7 +268,7 @@ formatIso8601Duration(90061);        // { iso: "P1DT1H1M1S", ... }
 ### `/units`: Conversions
 
 ```ts
-import { convertBytes, pxToAll, convert, formatValue, validateCardNumber, validateIban, calculateLoan, validateBarcode, calculateTax, calculateCompoundInterest, validateIsbn, calculateTipSplit, calculateSimpleInterest, calculateTimeValue, calculatePercentageChange, convertAprApy } from "@utilix-tech/sdk/units";
+import { convertBytes, pxToAll, convert, formatValue, validateCardNumber, validateIban, calculateLoan, validateBarcode, calculateTax, calculateCompoundInterest, validateIsbn, calculateTipSplit, calculateSimpleInterest, calculateTimeValue, calculatePercentageChange, convertAprApy, calculateMarginMarkup, calculateDiscount, applySuccessiveDiscounts } from "@utilix-tech/sdk/units";
 
 // File sizes
 convertBytes(1073741824, "GB");  // 1
@@ -327,6 +334,18 @@ calculatePercentageChange(200, 250);
 // APR <-> APY conversion for a given compounding frequency
 convertAprApy(12, 12, "apr-to-apy");
 // { apr: 12, apy: 12.682503, difference: 0.682503, compoundsPerYear: 12, ... }
+
+// Margin/markup: pass any TWO of cost, price, marginPercent, markupPercent
+calculateMarginMarkup({ cost: 80, price: 100 });
+// { cost: 80, price: 100, profit: 20, marginPercent: 20, markupPercent: 25, ... }
+
+// Discount: original price plus exactly ONE of percent, amount, or final price
+calculateDiscount({ originalPrice: 80, discountPercent: 25 });
+// { originalPrice: 80, finalPrice: 60, discountAmount: 20, discountPercent: 25, ... }
+
+// Stacked discounts: 20% then a further 10% is 28% off, not 30%
+applySuccessiveDiscounts(100, [20, 10]);
+// { finalPrice: 72, totalSaved: 28, effectiveDiscountPercent: 28, sumOfDiscountPercents: 30, ... }
 ```
 
 ---
@@ -577,7 +596,7 @@ readIcoInfo(new Uint8Array(icoBytes));
 | `@utilix-tech/sdk/encoding` | Base64, URL, HTML entities, Base32/Base58/Base62 encode/decode |
 | `@utilix-tech/sdk/hashing` | MD5, SHA-1/256/512, bcrypt, HMAC, .htpasswd |
 | `@utilix-tech/sdk/text` | Case convert, slugify, word count, lorem ipsum, line ops, HTML→Markdown |
-| `@utilix-tech/sdk/data` | CSV, YAML, TOML, XML, INI, NDJSON parse and convert |
+| `@utilix-tech/sdk/data` | CSV, YAML, TOML, XML, INI, NDJSON parse and convert, SRT/WebVTT subtitles |
 | `@utilix-tech/sdk/generators` | UUID v4/v7, ULID, passwords, strength check, fake data |
 | `@utilix-tech/sdk/time` | Date diff, timezone convert, cron parse, relative time |
 | `@utilix-tech/sdk/units` | Bytes, CSS px/rem, number bases, currency format, credit card/IBAN/barcode/ISBN validation, loan calculator, compound/simple interest calculators, VAT/sales tax calculator, tip/bill split calculator |

package/dist/{chunk-TINQFTLO.js → chunk-66QHV5KW.js}

@@ -5,12 +5,15 @@ import { parse, stringify } from 'smol-toml';
 // src/tools/data.ts
 var data_exports = {};
 __export(data_exports, {
+  convertSubtitles: () => convertSubtitles,
   csvToJson: () => csvToJson,
   detectDelimiter: () => detectDelimiter,
+  detectSubtitleFormat: () => detectSubtitleFormat,
   diffEnvExample: () => diffEnvExample,
   envToExport: () => envToExport,
   envToJson: () => envToJson,
   formatNdjson: () => formatNdjson,
+  formatSubtitleTimestamp: () => formatSubtitleTimestamp,
   formatToml: () => formatToml,
   formatXml: () => formatXml,
   getSection: () => getSection,
@@ -30,7 +33,11 @@ __export(data_exports, {
   parseCsv: () => parseCsv,
   parseEnv: () => parseEnv,
   parseIni: () => parseIni,
+  parseSubtitleTimestamp: () => parseSubtitleTimestamp,
+  parseSubtitles: () => parseSubtitles,
   parseXmlToObject: () => parseXmlToObject,
+  serializeSubtitles: () => serializeSubtitles,
+  shiftSubtitles: () => shiftSubtitles,
   stringifyIni: () => stringifyIni,
   toCsvString: () => toCsvString,
   tomlToJson: () => tomlToJson,
@@ -1157,5 +1164,175 @@ function jsonArrayToNdjson(input) {
   if (!Array.isArray(parsed)) return { error: "Input must be a JSON array" };
   return parsed.map((item) => JSON.stringify(item)).join("\n");
 }
+var _SUBTITLE_TIMESTAMP_RE = /(\d+):(\d{1,2}):(\d{1,2})[.,](\d{1,3})|(\d{1,3}):(\d{1,2})[.,](\d{1,3})/;
+var _VTT_BLOCK_KEYWORDS = ["NOTE", "STYLE", "REGION"];
+function parseSubtitleTimestamp(raw) {
+  const m = _SUBTITLE_TIMESTAMP_RE.exec(raw.trim());
+  if (!m || m.index !== 0) return null;
+  let hours;
+  let minutes;
+  let seconds;
+  let millis;
+  if (m[1] !== void 0) {
+    hours = Number(m[1]);
+    minutes = Number(m[2]);
+    seconds = Number(m[3]);
+    millis = m[4];
+  } else {
+    hours = 0;
+    minutes = Number(m[5]);
+    seconds = Number(m[6]);
+    millis = m[7];
+  }
+  if (minutes > 59 || seconds > 59) return null;
+  return hours * 3600 + minutes * 60 + seconds + Number(millis.padEnd(3, "0")) / 1e3;
+}
+function formatSubtitleTimestamp(totalSeconds, format) {
+  const totalMs = Math.round(Math.max(0, totalSeconds) * 1e3);
+  const ms = totalMs % 1e3;
+  const totalSecs = Math.floor(totalMs / 1e3);
+  const pad = (n, width = 2) => String(n).padStart(width, "0");
+  return `${pad(Math.floor(totalSecs / 3600))}:${pad(Math.floor(totalSecs / 60) % 60)}:${pad(totalSecs % 60)}${format === "srt" ? "," : "."}${pad(ms, 3)}`;
+}
+function _stripBom(input) {
+  return input.charCodeAt(0) === 65279 ? input.slice(1) : input;
+}
+function detectSubtitleFormat(input) {
+  const text = _stripBom(input).trimStart();
+  if (/^WEBVTT/.test(text)) return "vtt";
+  const arrow = /(\d{1,3}):(\d{1,2})(?::(\d{1,2}))?([.,])(\d{1,3})\s*-->/.exec(text);
+  if (arrow && arrow[4] === ".") return "vtt";
+  return "srt";
+}
+function parseSubtitles(input, format) {
+  if (typeof input !== "string" || input.trim().length === 0) {
+    return { error: "Subtitle input is empty" };
+  }
+  const sourceFormat = format ?? detectSubtitleFormat(input);
+  const normalised = _stripBom(input).replace(/\r\n?/g, "\n");
+  const warnings = [];
+  let body = normalised;
+  if (sourceFormat === "vtt") {
+    const headerMatch = /^WEBVTT[^\n]*\n?/.exec(body.trimStart());
+    if (headerMatch) {
+      body = body.trimStart().slice(headerMatch[0].length);
+    } else {
+      warnings.push('WebVTT input is missing its "WEBVTT" header line');
+    }
+  }
+  const blocks = body.split(/\n[ \t]*\n+/).map((b) => b.trim()).filter((b) => b.length > 0);
+  const cues = [];
+  for (const block of blocks) {
+    const lines = block.split("\n");
+    const arrowIdx = lines.findIndex((l) => l.includes("-->"));
+    if (arrowIdx === -1) {
+      const keyword = _VTT_BLOCK_KEYWORDS.find((k) => lines[0] === k || lines[0].startsWith(`${k} `));
+      if (sourceFormat === "vtt" && keyword) {
+        warnings.push(`Dropped a WebVTT ${keyword} block, which has no SRT equivalent`);
+      } else {
+        warnings.push(`Skipped a block with no "-->" timing line: ${JSON.stringify(lines[0].slice(0, 40))}`);
+      }
+      continue;
+    }
+    const timingLine = lines[arrowIdx];
+    const parts = timingLine.split("-->");
+    const start = parseSubtitleTimestamp(parts[0] ?? "");
+    const rightTrimmed = (parts[1] ?? "").trim();
+    const end = parseSubtitleTimestamp(rightTrimmed);
+    if (start === null || end === null) {
+      warnings.push(`Skipped a cue with an unparseable timing line: ${JSON.stringify(timingLine.slice(0, 60))}`);
+      continue;
+    }
+    const endMatch = _SUBTITLE_TIMESTAMP_RE.exec(rightTrimmed);
+    const settings = endMatch ? rightTrimmed.slice(endMatch[0].length).trim() : "";
+    const idLines = lines.slice(0, arrowIdx).filter((l) => l.trim().length > 0);
+    const text = lines.slice(arrowIdx + 1).join("\n").trim();
+    const cue = { index: cues.length + 1, start, end, text };
+    if (sourceFormat === "vtt" && idLines.length > 0) cue.id = idLines[idLines.length - 1].trim();
+    if (settings.length > 0) cue.settings = settings;
+    if (end < start) warnings.push(`Cue ${cue.index} ends before it starts`);
+    if (text.length === 0) warnings.push(`Cue ${cue.index} has no text`);
+    if (cues.length > 0 && start < cues[cues.length - 1].end) {
+      warnings.push(`Cue ${cue.index} starts before cue ${cue.index - 1} ends (overlapping cues)`);
+    }
+    cues.push(cue);
+  }
+  if (cues.length === 0) {
+    return { error: "No subtitle cues found: check that the input is a valid SRT or WebVTT file" };
+  }
+  return {
+    format: sourceFormat,
+    cues,
+    cueCount: cues.length,
+    duration: Math.round(Math.max(...cues.map((c) => c.end)) * 1e3) / 1e3,
+    warnings
+  };
+}
+function serializeSubtitles(cues, format) {
+  const blocks = cues.map((cue, i) => {
+    const time = `${formatSubtitleTimestamp(cue.start, format)} --> ${formatSubtitleTimestamp(cue.end, format)}`;
+    if (format === "srt") return `${i + 1}
+${time}
+${cue.text}`;
+    const timing = cue.settings ? `${time} ${cue.settings}` : time;
+    return cue.id ? `${cue.id}
+${timing}
+${cue.text}` : `${timing}
+${cue.text}`;
+  });
+  const body = blocks.join("\n\n");
+  return format === "vtt" ? `WEBVTT
+
+${body}
+` : `${body}
+`;
+}
+function convertSubtitles(input, target, sourceFormat) {
+  if (target !== "srt" && target !== "vtt") return { error: 'target must be "srt" or "vtt"' };
+  const parsed = parseSubtitles(input, sourceFormat);
+  if ("error" in parsed) return parsed;
+  const warnings = [...parsed.warnings];
+  if (target === "srt") {
+    const droppedSettings = parsed.cues.filter((c) => c.settings).length;
+    const droppedIds = parsed.cues.filter((c) => c.id).length;
+    if (droppedSettings > 0) {
+      warnings.push(`Dropped WebVTT cue settings on ${droppedSettings} cue(s): SRT has no equivalent`);
+    }
+    if (droppedIds > 0) {
+      warnings.push(`Dropped ${droppedIds} WebVTT cue identifier(s): SRT numbers cues sequentially instead`);
+    }
+  }
+  return {
+    format: target,
+    sourceFormat: parsed.format,
+    output: serializeSubtitles(parsed.cues, target),
+    cueCount: parsed.cueCount,
+    duration: parsed.duration,
+    warnings
+  };
+}
+function shiftSubtitles(input, offsetSeconds, target) {
+  if (!Number.isFinite(offsetSeconds)) return { error: "offsetSeconds must be a finite number" };
+  const parsed = parseSubtitles(input);
+  if ("error" in parsed) return parsed;
+  const warnings = [...parsed.warnings];
+  let clamped = 0;
+  const shifted = parsed.cues.map((cue) => {
+    const start = cue.start + offsetSeconds;
+    const end = cue.end + offsetSeconds;
+    if (start < 0) clamped += 1;
+    return { ...cue, start: Math.max(0, start), end: Math.max(0, end) };
+  });
+  if (clamped > 0) warnings.push(`${clamped} cue(s) would start before zero and were clamped to 00:00:00`);
+  const outFormat = target ?? parsed.format;
+  return {
+    format: outFormat,
+    sourceFormat: parsed.format,
+    output: serializeSubtitles(shifted, outFormat),
+    cueCount: shifted.length,
+    duration: Math.round(Math.max(...shifted.map((c) => c.end)) * 1e3) / 1e3,
+    warnings
+  };
+}
 
-export { csvToJson, data_exports, detectDelimiter, diffEnvExample, envToExport, envToJson, formatNdjson, formatToml, formatXml, getSection, getSectionNames, getTomlStats, getXmlStats, getYamlStats, iniToJson, jsonArrayToNdjson, jsonToIni, jsonToToml, jsonToXml, minifyNdjson, minifyToml, minifyXml, ndjsonToJsonArray, parseCsv, parseEnv, parseIni, parseXmlToObject, stringifyIni, toCsvString, tomlToJson, validateEnvKey, validateIni, validateNdjson, validateToml, validateXml, validateYaml, xmlToJson };
+export { convertSubtitles, csvToJson, data_exports, detectDelimiter, detectSubtitleFormat, diffEnvExample, envToExport, envToJson, formatNdjson, formatSubtitleTimestamp, formatToml, formatXml, getSection, getSectionNames, getTomlStats, getXmlStats, getYamlStats, iniToJson, jsonArrayToNdjson, jsonToIni, jsonToToml, jsonToXml, minifyNdjson, minifyToml, minifyXml, ndjsonToJsonArray, parseCsv, parseEnv, parseIni, parseSubtitleTimestamp, parseSubtitles, parseXmlToObject, serializeSubtitles, shiftSubtitles, stringifyIni, toCsvString, tomlToJson, validateEnvKey, validateIni, validateNdjson, validateToml, validateXml, validateYaml, xmlToJson };

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

@@ -14,12 +14,15 @@ __export(units_exports, {
   COMMON_TAX_RATES: () => COMMON_TAX_RATES,
   COMMON_TIP_PERCENTAGES: () => COMMON_TIP_PERCENTAGES,
   COMMON_VIEWPORTS: () => COMMON_VIEWPORTS,
+  applySuccessiveDiscounts: () => applySuccessiveDiscounts,
   autoFormat: () => autoFormat,
   bumpVersion: () => bumpVersion,
   calcAspectRatio: () => calcAspectRatio,
   calcSubnet: () => calcSubnet,
   calculateCompoundInterest: () => calculateCompoundInterest,
+  calculateDiscount: () => calculateDiscount,
   calculateLoan: () => calculateLoan,
+  calculateMarginMarkup: () => calculateMarginMarkup,
   calculatePercentageChange: () => calculatePercentageChange,
   calculateSimpleInterest: () => calculateSimpleInterest,
   calculateTax: () => calculateTax,
@@ -52,6 +55,8 @@ __export(units_exports, {
   isValidCidr: () => isValidCidr,
   isValidIp: () => isValidIp,
   isValidIpv4: () => isValidIpv4,
+  marginToMarkup: () => marginToMarkup,
+  markupToMargin: () => markupToMargin,
   octalToPermissions: () => octalToPermissions,
   parseFileSize: () => parseFileSize,
   parseInput: () => parseInput,
@@ -1394,5 +1399,154 @@ function convertAprApy(rate, compoundsPerYear, direction) {
     difference: round6(apy - apr)
   };
 }
+var _MARGIN_FIELDS = ["cost", "price", "marginPercent", "markupPercent"];
+function calculateMarginMarkup(input) {
+  const provided = (v) => typeof v === "number" && Number.isFinite(v);
+  const given = _MARGIN_FIELDS.filter((f) => provided(input[f]));
+  if (given.length !== 2) {
+    return { error: `Provide exactly two of cost, price, marginPercent, markupPercent (got ${given.length})` };
+  }
+  const has = (f) => given.includes(f);
+  const cost0 = input.cost;
+  const price0 = input.price;
+  const margin0 = input.marginPercent;
+  const markup0 = input.markupPercent;
+  if (has("cost") && cost0 <= 0) return { error: "Cost must be greater than zero" };
+  if (has("price") && price0 <= 0) return { error: "Price must be greater than zero" };
+  if (has("marginPercent") && margin0 >= 100) {
+    return { error: "Margin percent must be below 100 (a 100% margin implies a zero cost)" };
+  }
+  if (has("markupPercent") && markup0 <= -100) {
+    return { error: "Markup percent must be greater than -100" };
+  }
+  let cost;
+  let price;
+  if (has("cost") && has("price")) {
+    cost = cost0;
+    price = price0;
+  } else if (has("cost") && has("marginPercent")) {
+    cost = cost0;
+    price = cost0 / (1 - margin0 / 100);
+  } else if (has("cost") && has("markupPercent")) {
+    cost = cost0;
+    price = cost0 * (1 + markup0 / 100);
+  } else if (has("price") && has("marginPercent")) {
+    price = price0;
+    cost = price0 * (1 - margin0 / 100);
+  } else if (has("price") && has("markupPercent")) {
+    price = price0;
+    cost = price0 / (1 + markup0 / 100);
+  } else {
+    return { error: "Margin and markup alone cannot be solved: also provide a cost or a price" };
+  }
+  if (!Number.isFinite(cost) || !Number.isFinite(price)) return { error: "Inputs produce a non-finite result" };
+  if (cost <= 0) return { error: "Those inputs imply a cost of zero or less" };
+  if (price <= 0) return { error: "Those inputs imply a price of zero or less" };
+  const round4 = (n) => Math.round(n * 1e4) / 1e4;
+  const profit = price - cost;
+  return {
+    cost: round4(cost),
+    price: round4(price),
+    profit: round4(profit),
+    marginPercent: round4(profit / price * 100),
+    markupPercent: round4(profit / cost * 100),
+    given,
+    solvedFor: _MARGIN_FIELDS.filter((f) => !given.includes(f))
+  };
+}
+function marginToMarkup(marginPercent) {
+  if (!Number.isFinite(marginPercent) || marginPercent >= 100) {
+    return { error: "Margin percent must be a finite number below 100" };
+  }
+  return Math.round(marginPercent / (100 - marginPercent) * 100 * 1e4) / 1e4;
+}
+function markupToMargin(markupPercent) {
+  if (!Number.isFinite(markupPercent) || markupPercent <= -100) {
+    return { error: "Markup percent must be a finite number greater than -100" };
+  }
+  return Math.round(markupPercent / (100 + markupPercent) * 100 * 1e4) / 1e4;
+}
+var _DISCOUNT_FIELDS = ["discountPercent", "discountAmount", "finalPrice"];
+function calculateDiscount(input) {
+  const provided = (v) => typeof v === "number" && Number.isFinite(v);
+  if (!provided(input.originalPrice)) {
+    return { error: "originalPrice is required and must be a finite number" };
+  }
+  const originalPrice = input.originalPrice;
+  if (originalPrice <= 0) return { error: "Original price must be greater than zero" };
+  const given = _DISCOUNT_FIELDS.filter((f) => provided(input[f]));
+  if (given.length !== 1) {
+    return { error: `Provide exactly one of discountPercent, discountAmount, finalPrice (got ${given.length})` };
+  }
+  const field = given[0];
+  let discountAmount;
+  if (field === "discountPercent") {
+    const pct = input.discountPercent;
+    if (pct < 0) return { error: "Discount percent cannot be negative" };
+    if (pct > 100) return { error: "Discount percent cannot exceed 100" };
+    discountAmount = originalPrice * (pct / 100);
+  } else if (field === "discountAmount") {
+    const amt = input.discountAmount;
+    if (amt < 0) return { error: "Discount amount cannot be negative" };
+    if (amt > originalPrice) return { error: "Discount amount cannot exceed the original price" };
+    discountAmount = amt;
+  } else {
+    const fin = input.finalPrice;
+    if (fin < 0) return { error: "Final price cannot be negative" };
+    if (fin > originalPrice) {
+      return { error: "Final price cannot exceed the original price: that is a price increase, not a discount" };
+    }
+    discountAmount = originalPrice - fin;
+  }
+  const round4 = (n) => Math.round(n * 1e4) / 1e4;
+  const finalPrice = originalPrice - discountAmount;
+  return {
+    originalPrice: round4(originalPrice),
+    finalPrice: round4(finalPrice),
+    discountAmount: round4(discountAmount),
+    discountPercent: round4(discountAmount / originalPrice * 100),
+    given: field,
+    solvedFor: _DISCOUNT_FIELDS.filter((f) => f !== field)
+  };
+}
+function applySuccessiveDiscounts(originalPrice, discountPercents) {
+  if (!Number.isFinite(originalPrice) || originalPrice <= 0) {
+    return { error: "Original price must be a finite number greater than zero" };
+  }
+  if (!Array.isArray(discountPercents) || discountPercents.length === 0) {
+    return { error: "Provide at least one discount percent" };
+  }
+  if (discountPercents.length > 20) {
+    return { error: "Provide at most 20 successive discounts" };
+  }
+  const round4 = (n) => Math.round(n * 1e4) / 1e4;
+  const steps = [];
+  let running = originalPrice;
+  let sumOfDiscountPercents = 0;
+  for (const pct of discountPercents) {
+    if (!Number.isFinite(pct)) return { error: "Every discount percent must be a finite number" };
+    if (pct < 0) return { error: "Discount percent cannot be negative" };
+    if (pct > 100) return { error: "Discount percent cannot exceed 100" };
+    const priceBefore = running;
+    const saved = priceBefore * (pct / 100);
+    running = priceBefore - saved;
+    sumOfDiscountPercents += pct;
+    steps.push({
+      discountPercent: round4(pct),
+      priceBefore: round4(priceBefore),
+      priceAfter: round4(running),
+      saved: round4(saved)
+    });
+  }
+  const totalSaved = originalPrice - running;
+  return {
+    originalPrice: round4(originalPrice),
+    finalPrice: round4(running),
+    totalSaved: round4(totalSaved),
+    effectiveDiscountPercent: round4(totalSaved / originalPrice * 100),
+    sumOfDiscountPercents: round4(sumOfDiscountPercents),
+    steps
+  };
+}
 
-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 };
+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, applySuccessiveDiscounts, autoFormat, bumpVersion, calcAspectRatio, calcSubnet, calculateCompoundInterest, calculateDiscount, calculateLoan, calculateMarginMarkup, 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, marginToMarkup, markupToMargin, 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/{data-D8XTI7Du.d.cts → data-XRb0D7Zn.d.cts}

@@ -12,6 +12,7 @@
  *  - env-parser      : parseEnv, envToJson, envToExport, validateEnvKey
  *  - env-diff-checker: diffEnvExample
  *  - ndjson-formatter: validateNdjson, minifyNdjson, formatNdjson, ndjsonToJsonArray, jsonArrayToNdjson
+ *  - subtitle-converter: parseSubtitleTimestamp, formatSubtitleTimestamp, detectSubtitleFormat, parseSubtitles, serializeSubtitles, convertSubtitles, shiftSubtitles
  */
 interface ValidationResult {
     valid: boolean;
@@ -210,7 +211,69 @@ declare function ndjsonToJsonArray(input: string): string | {
 declare function jsonArrayToNdjson(input: string): string | {
     error: string;
 };
+type SubtitleFormat = "srt" | "vtt";
+interface SubtitleCue {
+    index: number;
+    /** Cue identifier line, when the source had one (WebVTT only). */
+    id?: string;
+    /** Start time in seconds. */
+    start: number;
+    /** End time in seconds. */
+    end: number;
+    /** WebVTT cue settings that followed the timestamp (e.g. `line:0 align:start`). */
+    settings?: string;
+    text: string;
+}
+interface ParsedSubtitles {
+    format: SubtitleFormat;
+    cues: SubtitleCue[];
+    cueCount: number;
+    /** End time of the last cue, in seconds. */
+    duration: number;
+    warnings: string[];
+}
+interface ConvertedSubtitles {
+    format: SubtitleFormat;
+    sourceFormat: SubtitleFormat;
+    output: string;
+    cueCount: number;
+    duration: number;
+    warnings: string[];
+}
+/** Parse `HH:MM:SS,mmm`, `HH:MM:SS.mmm`, or WebVTT's `MM:SS.mmm` into seconds. */
+declare function parseSubtitleTimestamp(raw: string): number | null;
+/** Format seconds as `HH:MM:SS,mmm` (SRT) or `HH:MM:SS.mmm` (WebVTT). */
+declare function formatSubtitleTimestamp(totalSeconds: number, format: SubtitleFormat): string;
+/** Auto-detect the source format from the WEBVTT signature or timestamp separator. */
+declare function detectSubtitleFormat(input: string): SubtitleFormat;
+/**
+ * Parse an SRT or WebVTT file into normalised cues. The format is auto-detected
+ * unless you pass one. Malformed blocks are reported as warnings rather than
+ * throwing, so a mostly-good file still converts.
+ */
+declare function parseSubtitles(input: string, format?: SubtitleFormat): ParsedSubtitles | {
+    error: string;
+};
+/** Serialise parsed cues back into SRT or WebVTT text. */
+declare function serializeSubtitles(cues: SubtitleCue[], format: SubtitleFormat): string;
+/**
+ * Convert a subtitle file to the target format. Converting WebVTT to SRT drops
+ * cue identifiers, cue settings, and NOTE/STYLE/REGION blocks, since SRT has no
+ * equivalent for any of them; each drop is reported as a warning.
+ */
+declare function convertSubtitles(input: string, target: SubtitleFormat, sourceFormat?: SubtitleFormat): ConvertedSubtitles | {
+    error: string;
+};
+/**
+ * Shift every cue by a fixed offset in seconds, keeping the source format
+ * unless a target is given. Negative offsets clamp at zero, so a cue that would
+ * start before the video does starts at 00:00:00 instead.
+ */
+declare function shiftSubtitles(input: string, offsetSeconds: number, target?: SubtitleFormat): ConvertedSubtitles | {
+    error: string;
+};
 
+type data_ConvertedSubtitles = ConvertedSubtitles;
 type data_CsvParseResult = CsvParseResult;
 type data_EnvDiffError = EnvDiffError;
 type data_EnvDiffResult = EnvDiffResult;
@@ -221,16 +284,22 @@ type data_NdjsonLineResult = NdjsonLineResult;
 type data_NdjsonValidateResult = NdjsonValidateResult;
 type data_ParseOptions = ParseOptions;
 type data_ParsedIni = ParsedIni;
+type data_ParsedSubtitles = ParsedSubtitles;
+type data_SubtitleCue = SubtitleCue;
+type data_SubtitleFormat = SubtitleFormat;
 type data_TomlFormatResult = TomlFormatResult;
 type data_ValidationResult = ValidationResult;
 type data_XmlFormatResult = XmlFormatResult;
 type data_XmlToJsonOptions = XmlToJsonOptions;
+declare const data_convertSubtitles: typeof convertSubtitles;
 declare const data_csvToJson: typeof csvToJson;
 declare const data_detectDelimiter: typeof detectDelimiter;
+declare const data_detectSubtitleFormat: typeof detectSubtitleFormat;
 declare const data_diffEnvExample: typeof diffEnvExample;
 declare const data_envToExport: typeof envToExport;
 declare const data_envToJson: typeof envToJson;
 declare const data_formatNdjson: typeof formatNdjson;
+declare const data_formatSubtitleTimestamp: typeof formatSubtitleTimestamp;
 declare const data_formatToml: typeof formatToml;
 declare const data_formatXml: typeof formatXml;
 declare const data_getSection: typeof getSection;
@@ -250,7 +319,11 @@ declare const data_ndjsonToJsonArray: typeof ndjsonToJsonArray;
 declare const data_parseCsv: typeof parseCsv;
 declare const data_parseEnv: typeof parseEnv;
 declare const data_parseIni: typeof parseIni;
+declare const data_parseSubtitleTimestamp: typeof parseSubtitleTimestamp;
+declare const data_parseSubtitles: typeof parseSubtitles;
 declare const data_parseXmlToObject: typeof parseXmlToObject;
+declare const data_serializeSubtitles: typeof serializeSubtitles;
+declare const data_shiftSubtitles: typeof shiftSubtitles;
 declare const data_stringifyIni: typeof stringifyIni;
 declare const data_toCsvString: typeof toCsvString;
 declare const data_tomlToJson: typeof tomlToJson;
@@ -262,7 +335,7 @@ declare const data_validateXml: typeof validateXml;
 declare const data_validateYaml: typeof validateYaml;
 declare const data_xmlToJson: typeof xmlToJson;
 declare namespace data {
-  export { type data_CsvParseResult as CsvParseResult, type data_EnvDiffError as EnvDiffError, type data_EnvDiffResult as EnvDiffResult, type data_EnvEntry as EnvEntry, type data_EnvParseResult as EnvParseResult, type data_IniSection as IniSection, type data_NdjsonLineResult as NdjsonLineResult, type data_NdjsonValidateResult as NdjsonValidateResult, type data_ParseOptions as ParseOptions, type data_ParsedIni as ParsedIni, type data_TomlFormatResult as TomlFormatResult, type data_ValidationResult as ValidationResult, type data_XmlFormatResult as XmlFormatResult, type data_XmlToJsonOptions as XmlToJsonOptions, data_csvToJson as csvToJson, data_detectDelimiter as detectDelimiter, data_diffEnvExample as diffEnvExample, data_envToExport as envToExport, data_envToJson as envToJson, data_formatNdjson as formatNdjson, data_formatToml as formatToml, data_formatXml as formatXml, data_getSection as getSection, data_getSectionNames as getSectionNames, data_getTomlStats as getTomlStats, data_getXmlStats as getXmlStats, data_getYamlStats as getYamlStats, data_iniToJson as iniToJson, data_jsonArrayToNdjson as jsonArrayToNdjson, data_jsonToIni as jsonToIni, data_jsonToToml as jsonToToml, data_jsonToXml as jsonToXml, data_minifyNdjson as minifyNdjson, data_minifyToml as minifyToml, data_minifyXml as minifyXml, data_ndjsonToJsonArray as ndjsonToJsonArray, data_parseCsv as parseCsv, data_parseEnv as parseEnv, data_parseIni as parseIni, data_parseXmlToObject as parseXmlToObject, data_stringifyIni as stringifyIni, data_toCsvString as toCsvString, data_tomlToJson as tomlToJson, data_validateEnvKey as validateEnvKey, data_validateIni as validateIni, data_validateNdjson as validateNdjson, data_validateToml as validateToml, data_validateXml as validateXml, data_validateYaml as validateYaml, data_xmlToJson as xmlToJson };
+  export { type data_ConvertedSubtitles as ConvertedSubtitles, type data_CsvParseResult as CsvParseResult, type data_EnvDiffError as EnvDiffError, type data_EnvDiffResult as EnvDiffResult, type data_EnvEntry as EnvEntry, type data_EnvParseResult as EnvParseResult, type data_IniSection as IniSection, type data_NdjsonLineResult as NdjsonLineResult, type data_NdjsonValidateResult as NdjsonValidateResult, type data_ParseOptions as ParseOptions, type data_ParsedIni as ParsedIni, type data_ParsedSubtitles as ParsedSubtitles, type data_SubtitleCue as SubtitleCue, type data_SubtitleFormat as SubtitleFormat, type data_TomlFormatResult as TomlFormatResult, type data_ValidationResult as ValidationResult, type data_XmlFormatResult as XmlFormatResult, type data_XmlToJsonOptions as XmlToJsonOptions, data_convertSubtitles as convertSubtitles, data_csvToJson as csvToJson, data_detectDelimiter as detectDelimiter, data_detectSubtitleFormat as detectSubtitleFormat, data_diffEnvExample as diffEnvExample, data_envToExport as envToExport, data_envToJson as envToJson, data_formatNdjson as formatNdjson, data_formatSubtitleTimestamp as formatSubtitleTimestamp, data_formatToml as formatToml, data_formatXml as formatXml, data_getSection as getSection, data_getSectionNames as getSectionNames, data_getTomlStats as getTomlStats, data_getXmlStats as getXmlStats, data_getYamlStats as getYamlStats, data_iniToJson as iniToJson, data_jsonArrayToNdjson as jsonArrayToNdjson, data_jsonToIni as jsonToIni, data_jsonToToml as jsonToToml, data_jsonToXml as jsonToXml, data_minifyNdjson as minifyNdjson, data_minifyToml as minifyToml, data_minifyXml as minifyXml, data_ndjsonToJsonArray as ndjsonToJsonArray, data_parseCsv as parseCsv, data_parseEnv as parseEnv, data_parseIni as parseIni, data_parseSubtitleTimestamp as parseSubtitleTimestamp, data_parseSubtitles as parseSubtitles, data_parseXmlToObject as parseXmlToObject, data_serializeSubtitles as serializeSubtitles, data_shiftSubtitles as shiftSubtitles, data_stringifyIni as stringifyIni, data_toCsvString as toCsvString, data_tomlToJson as tomlToJson, data_validateEnvKey as validateEnvKey, data_validateIni as validateIni, data_validateNdjson as validateNdjson, data_validateToml as validateToml, data_validateXml as validateXml, data_validateYaml as validateYaml, data_xmlToJson as xmlToJson };
 }
 
-export { minifyToml as A, minifyXml as B, type CsvParseResult as C, ndjsonToJsonArray as D, type EnvDiffError as E, parseCsv as F, parseEnv as G, parseIni as H, type IniSection as I, parseXmlToObject as J, stringifyIni as K, toCsvString as L, tomlToJson as M, type NdjsonLineResult as N, validateEnvKey as O, type ParseOptions as P, validateIni as Q, validateNdjson as R, validateToml as S, type TomlFormatResult as T, validateXml as U, type ValidationResult as V, validateYaml as W, type XmlFormatResult as X, xmlToJson as Y, type EnvDiffResult as a, type EnvEntry as b, type EnvParseResult as c, data as d, type NdjsonValidateResult as e, type ParsedIni as f, type XmlToJsonOptions as g, csvToJson as h, detectDelimiter as i, diffEnvExample as j, envToExport as k, envToJson as l, formatNdjson as m, formatToml as n, formatXml as o, getSection as p, getSectionNames as q, getTomlStats as r, getXmlStats as s, getYamlStats as t, iniToJson as u, jsonArrayToNdjson as v, jsonToIni as w, jsonToToml as x, jsonToXml as y, minifyNdjson as z };
+export { toCsvString as $, iniToJson as A, jsonArrayToNdjson as B, type ConvertedSubtitles as C, jsonToIni as D, type EnvDiffError as E, jsonToToml as F, jsonToXml as G, minifyNdjson as H, type IniSection as I, minifyToml as J, minifyXml as K, ndjsonToJsonArray as L, parseCsv as M, type NdjsonLineResult as N, parseEnv as O, type ParseOptions as P, parseIni as Q, parseSubtitleTimestamp as R, type SubtitleCue as S, type TomlFormatResult as T, parseSubtitles as U, type ValidationResult as V, parseXmlToObject as W, type XmlFormatResult as X, serializeSubtitles as Y, shiftSubtitles as Z, stringifyIni as _, type CsvParseResult as a, tomlToJson as a0, validateEnvKey as a1, validateIni as a2, validateNdjson as a3, validateToml as a4, validateXml as a5, validateYaml as a6, xmlToJson as a7, type EnvDiffResult as b, type EnvEntry as c, data as d, type EnvParseResult as e, type NdjsonValidateResult as f, type ParsedIni as g, type ParsedSubtitles as h, type SubtitleFormat as i, type XmlToJsonOptions as j, convertSubtitles as k, csvToJson as l, detectDelimiter as m, detectSubtitleFormat as n, diffEnvExample as o, envToExport as p, envToJson as q, formatNdjson as r, formatSubtitleTimestamp as s, formatToml as t, formatXml as u, getSection as v, getSectionNames as w, getTomlStats as x, getXmlStats as y, getYamlStats as z };