@utilix-tech/sdk 0.33.0 → 0.35.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.35.0
+- Add `calculateRoi` (roi-calculator): return on investment percent from an initial and final value, plus the annualized (CAGR) return given an optional holding period in years.
+- Add `searchEmoji`, `getEmojiByShortcode`, `getEmojiByChar`, `getEmojiByCategory`, `getEmojiCategories` (emoji-lookup): search a curated table of ~280 common emoji by name, keyword, or GitHub-style shortcode, or look one up exactly.
+
+## 0.34.0
+- Add `buildReferrerPolicy` (referrer-policy-builder): build a Referrer-Policy header value from one or more policy tokens with a plain-English explanation of each and warnings for risky choices like unsafe-url.
+- Add `generateMarkdownToc` (markdown-toc-generator): scan a Markdown document's ATX headings and build a nested table of contents with GitHub-style anchor slugs, disambiguating duplicates.
+
 ## 0.33.0
 - Add `lintConventionalCommit` (conventional-commit-linter): lint a git commit message against the Conventional Commits v1.0.0 spec, checking header format, blank-line separation, footer tokens, and BREAKING CHANGE casing.
 - Add `calculateSavingsGoal` (savings-goal-calculator): solve for months to reach a savings goal at a fixed monthly contribution, or the monthly contribution required to hit a goal by a target month count.

package/README.md

@@ -1,6 +1,6 @@
 # @utilix-tech/sdk
 
-**590 developer utility functions for Node.js: runs locally, no API key required.**
+**600 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)
@@ -140,7 +140,8 @@ generateHtpasswdFile([{ username: "alice", password: "secret" }]);
 ```ts
 import { convertCase, slugify, countWords, generateWords, generateParagraphs,
          escapeString, htmlToMarkdown, applyOps, detectPassiveVoice, scoreReadability,
-         detectFillerWords, calculateStringDistance, analyzeSentenceLengths } from "@utilix-tech/sdk/text";
+         detectFillerWords, calculateStringDistance, analyzeSentenceLengths,
+         searchEmoji, getEmojiByShortcode } from "@utilix-tech/sdk/text";
 
 convertCase("hello world", "camelCase");   // "helloWorld"
 convertCase("hello world", "PascalCase");  // "HelloWorld"
@@ -177,17 +178,22 @@ calculateStringDistance("kitten", "sitting");
 // Histogram + mean/median/stddev of sentence lengths, distinct from readability grade scores
 analyzeSentenceLengths("The cat sat on the mat. It was a sunny day, and the dog ran across the yard to play.");
 // { sentenceCount: 2, meanLength: 10, stdDev: 4, consistency: "Moderate variation in sentence length", buckets: [...] }
+
+// Search ~280 common emoji by name, keyword, or GitHub-style shortcode
+searchEmoji("fire");  // [{ emoji: "🔥", name: "fire", shortcode: "fire", codepoint: "U+1F525", ... }]
+getEmojiByShortcode(":joy:");  // { emoji: "😂", name: "face with tears of joy", ... }
 ```
 
 ---
 
-### `/data`: CSV / YAML / TOML / XML / INI / NDJSON / .env diff / subtitles / Markdown front matter
+### `/data`: CSV / YAML / TOML / XML / INI / NDJSON / .env diff / subtitles / Markdown front matter & TOC
 
 ```ts
 import { parseCsv, csvToJson, validateYaml, tomlToJson, jsonToToml,
          formatXml, xmlToJson, jsonToXml, parseIni,
          validateNdjson, formatNdjson, ndjsonToJsonArray, diffEnvExample,
-         parseSubtitles, convertSubtitles, shiftSubtitles, parseFrontMatter } from "@utilix-tech/sdk/data";
+         parseSubtitles, convertSubtitles, shiftSubtitles, parseFrontMatter,
+         generateMarkdownToc } from "@utilix-tech/sdk/data";
 
 // CSV
 const rows = parseCsv("name,age\nalice,30\nbob,25");
@@ -225,6 +231,10 @@ shiftSubtitles("1\n00:00:01,000 --> 00:00:04,000\nHi\n", -2.5);
 // Markdown front matter: split a document into its YAML front matter and body
 parseFrontMatter("---\ntitle: Hello World\ntags: [foo, bar]\n---\n# Body");
 // { frontMatter: { title: "Hello World", tags: ["foo", "bar"] }, body: "# Body", hasFrontMatter: true, ... }
+
+// Markdown table of contents: ATX headings -> nested links with GitHub-style slugs
+generateMarkdownToc("# Title\n\n## Section One\n\n## Section Two\n");
+// { toc: "- [Title](#title)\n  - [Section One](#section-one)\n  - [Section Two](#section-two)", entries: [...] }
 ```
 
 ---
@@ -286,7 +296,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, calculateMarginMarkup, calculateDiscount, applySuccessiveDiscounts, calculateBreakEven, calculateVideoBitrate, calculateRuleOf72, calculateEmi } 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, calculateBreakEven, calculateVideoBitrate, calculateRuleOf72, calculateEmi, calculateRoi } from "@utilix-tech/sdk/units";
 
 // File sizes
 convertBytes(1073741824, "GB");  // 1
@@ -380,6 +390,10 @@ calculateRuleOf72(8, "rate-to-years");
 // EMI: equated monthly installment with a year-by-year principal/interest breakdown
 calculateEmi(500000, 8.5, 5, "years");
 // { emi: 10258.27, totalInterest: 115495.89, tenureMonths: 60, yearlyBreakdown: [...] }
+
+// ROI: return on investment percent, plus annualized (CAGR) return if years is given
+calculateRoi({ initialValue: 1000, finalValue: 1610.51, years: 5 });
+// { profit: 610.51, roiPercent: 61.051, annualizedReturnPercent: 10, ... }
 ```
 
 ---
@@ -390,7 +404,7 @@ calculateEmi(500000, 8.5, 5, "years");
 import { getStatusCode, isValidIp, isValidIpv4, isValidIpv6,
          searchStatusCodes, buildGeoUrl, countryCodeToFlag,
          parseHar, validateSitemap, validateRobotsTxt,
-         parseUserAgent, buildCacheControl, parseIpv6Address } from "@utilix-tech/sdk/network";
+         parseUserAgent, buildCacheControl, buildReferrerPolicy, parseIpv6Address } from "@utilix-tech/sdk/network";
 
 getStatusCode(404);
 // { code: 404, text: "Not Found", description: "...", category: "Client Error" }
@@ -425,6 +439,10 @@ validateRobotsTxt("User-agent: *\nDisallow: /admin\nSitemap: https://example.com
 buildCacheControl({ visibility: "public", maxAge: 3600, mustRevalidate: true });
 // { header: "public, max-age=3600, must-revalidate", directives: [...], warnings: [] }
 
+// Build and explain a Referrer-Policy header from one or more fallback-chain tokens
+buildReferrerPolicy("strict-origin-when-cross-origin");
+// { header: "strict-origin-when-cross-origin", metaTag: '<meta name="referrer" content="...">', policies: [...], warnings: [] }
+
 // Expand/compress an IPv6 address (RFC 5952) and classify its address type
 parseIpv6Address("2001:db8::ff00:42:8329");
 // { expanded: "2001:0db8:0000:0000:0000:ff00:0042:8329", compressed: "2001:db8::ff00:42:8329",
@@ -658,11 +676,11 @@ readVideoInfo(new Uint8Array(videoBytes));
 | `@utilix-tech/sdk/json` | Format, minify, diff, validate, JSONPath, CSV↔JSON, YAML↔JSON, TS types from data or from a JSON Schema |
 | `@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, Levenshtein/Damerau string distance, readability scoring, sentence length distribution |
+| `@utilix-tech/sdk/text` | Case convert, slugify, word count, lorem ipsum, line ops, HTML→Markdown, Levenshtein/Damerau string distance, readability scoring, sentence length distribution, emoji lookup |
 | `@utilix-tech/sdk/data` | CSV, YAML, TOML, XML, INI, NDJSON parse and convert, SRT/WebVTT subtitles, Markdown front matter parser |
 | `@utilix-tech/sdk/generators` | UUID v4/v7, ULID, passwords, strength check, entropy estimator, 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, EMI calculator, compound/simple interest calculators, VAT/sales tax calculator, tip/bill split calculator, break-even point calculator, Rule of 72 calculator, savings goal calculator |
+| `@utilix-tech/sdk/units` | Bytes, CSS px/rem, number bases, currency format, credit card/IBAN/barcode/ISBN validation, loan calculator, EMI calculator, compound/simple interest calculators, VAT/sales tax calculator, tip/bill split calculator, break-even point calculator, Rule of 72 calculator, savings goal calculator, ROI calculator |
 | `@utilix-tech/sdk/network` | HTTP status codes, IP validation, country flags, geolocation URLs, HAR file parsing, User-Agent parsing, IPv6 address compress/expand |
 | `@utilix-tech/sdk/api` | cURL build/parse, JWT decode/sign, JWKS parse, CORS headers, CSP header |
 | `@utilix-tech/sdk/code` | SQL format/minify, HTML format/minify, regex tester, GraphQL format, MIME type lookup, GitHub URL parsing, regex ReDoS detector, Conventional Commits linter |

package/dist/{chunk-CSNTHZHF.js → chunk-3YUKLV5N.js}

@@ -5,11 +5,13 @@ var network_exports = {};
 __export(network_exports, {
   DNS_RECORD_TYPES: () => DNS_RECORD_TYPES,
   HTTP_HEADERS: () => HTTP_HEADERS,
+  REFERRER_POLICY_VALUES: () => REFERRER_POLICY_VALUES,
   STATUS_CODES: () => STATUS_CODES,
   buildCacheControl: () => buildCacheControl,
   buildDnsQueryUrl: () => buildDnsQueryUrl,
   buildGeoUrl: () => buildGeoUrl,
   buildMapUrl: () => buildMapUrl,
+  buildReferrerPolicy: () => buildReferrerPolicy,
   countryCodeToFlag: () => countryCodeToFlag,
   formatCoordinates: () => formatCoordinates,
   formatTtl: () => formatTtl,
@@ -1815,6 +1817,84 @@ function buildCacheControl(options = {}) {
   const snippet = `Cache-Control: ${header}`;
   return { header, headerName: "Cache-Control", snippet, directives, warnings };
 }
+var REFERRER_POLICY_VALUES = [
+  "no-referrer",
+  "no-referrer-when-downgrade",
+  "origin",
+  "origin-when-cross-origin",
+  "same-origin",
+  "strict-origin",
+  "strict-origin-when-cross-origin",
+  "unsafe-url"
+];
+var _REFERRER_POLICY_INFO = {
+  "no-referrer": {
+    explanation: "Never sends the Referer header, on any request. The strictest option; the destination learns nothing about where the request came from.",
+    leaksPathAndQuery: false,
+    sentOnDowngrade: false
+  },
+  "no-referrer-when-downgrade": {
+    explanation: "Sends the full URL (origin, path, and query string) for same-security-level or upgrading requests, but omits the header entirely when navigating from HTTPS to HTTP. This was the legacy browser default before strict-origin-when-cross-origin.",
+    leaksPathAndQuery: true,
+    sentOnDowngrade: false
+  },
+  origin: {
+    explanation: "Sends only the origin (scheme, host, and port) on every request, same-origin or cross-origin, including on a downgrade. The path and query string are always stripped.",
+    leaksPathAndQuery: false,
+    sentOnDowngrade: true
+  },
+  "origin-when-cross-origin": {
+    explanation: "Sends the full URL for same-origin requests, but only the origin for cross-origin requests. Still sends the origin on a downgrade.",
+    leaksPathAndQuery: true,
+    sentOnDowngrade: true
+  },
+  "same-origin": {
+    explanation: "Sends the full URL for same-origin requests, and no Referer header at all for cross-origin requests.",
+    leaksPathAndQuery: true,
+    sentOnDowngrade: false
+  },
+  "strict-origin": {
+    explanation: "Sends only the origin, and only when the security level stays the same or improves (HTTPS to HTTPS, or HTTP to anything). Nothing is sent on a downgrade from HTTPS to HTTP.",
+    leaksPathAndQuery: false,
+    sentOnDowngrade: false
+  },
+  "strict-origin-when-cross-origin": {
+    explanation: "Sends the full URL for same-origin requests, only the origin for cross-origin requests at the same or better security level, and nothing at all on a downgrade. This is the current browser default when no policy is set.",
+    leaksPathAndQuery: true,
+    sentOnDowngrade: false
+  },
+  "unsafe-url": {
+    explanation: "Always sends the full URL, including path and query string, on every request, even on a downgrade from HTTPS to HTTP. Generally discouraged: query strings can carry session tokens or other sensitive data that then leaks to third-party destinations and to the network on an insecure connection.",
+    leaksPathAndQuery: true,
+    sentOnDowngrade: true
+  }
+};
+function buildReferrerPolicy(policies) {
+  const list = Array.isArray(policies) ? policies : [policies];
+  const trimmed = list.map((p) => typeof p === "string" ? p.trim() : "").filter((p) => p !== "");
+  if (trimmed.length === 0) {
+    return { error: "At least one policy value is required" };
+  }
+  const entries = [];
+  for (const value of trimmed) {
+    if (!REFERRER_POLICY_VALUES.includes(value)) {
+      return { error: `'${value}' is not a valid Referrer-Policy value. Valid values: ${REFERRER_POLICY_VALUES.join(", ")}` };
+    }
+    entries.push({ value, ..._REFERRER_POLICY_INFO[value] });
+  }
+  const warnings = [];
+  const last = entries[entries.length - 1];
+  if (last.value === "unsafe-url") {
+    warnings.push("unsafe-url sends the full URL, including query strings, on every request, even over an insecure downgrade. Prefer strict-origin-when-cross-origin unless you have a specific reason to leak full URLs.");
+  }
+  if (entries.length > 1 && entries.some((e, i) => i !== entries.length - 1 && e.value === last.value)) {
+    warnings.push("The same policy value appears more than once in the fallback chain, which has no effect beyond the first occurrence.");
+  }
+  const header = entries.map((e) => e.value).join(", ");
+  const snippet = `Referrer-Policy: ${header}`;
+  const metaTag = `<meta name="referrer" content="${last.value}">`;
+  return { header, headerName: "Referrer-Policy", snippet, metaTag, policies: entries, warnings };
+}
 function isValidIpv6HexGroup(g) {
   return /^[0-9a-fA-F]{1,4}$/.test(g);
 }
@@ -1904,4 +1984,4 @@ function parseIpv6Address(input) {
   };
 }
 
-export { DNS_RECORD_TYPES, HTTP_HEADERS, STATUS_CODES, buildCacheControl, buildDnsQueryUrl, buildGeoUrl, buildMapUrl, countryCodeToFlag, formatCoordinates, formatTtl, getByCategory, getHeader, getHeadersByCategory, getStatusByCategory, getStatusCode, isClientError, isServerError, isSuccess, isValidIp, isValidIpv4, isValidIpv6, network_exports, parseDnsResponse, parseGeoResponse, parseHar, parseIpv6Address, parseUserAgent, searchHeaders, searchStatusCodes, statusCodeToText, typeNumberToLabel, validateDomain, validateHeaderName, validateHeaderValue, validateRobotsTxt, validateSitemap };
+export { DNS_RECORD_TYPES, HTTP_HEADERS, REFERRER_POLICY_VALUES, STATUS_CODES, buildCacheControl, buildDnsQueryUrl, buildGeoUrl, buildMapUrl, buildReferrerPolicy, countryCodeToFlag, formatCoordinates, formatTtl, getByCategory, getHeader, getHeadersByCategory, getStatusByCategory, getStatusCode, isClientError, isServerError, isSuccess, isValidIp, isValidIpv4, isValidIpv6, network_exports, parseDnsResponse, parseGeoResponse, parseHar, parseIpv6Address, parseUserAgent, searchHeaders, searchStatusCodes, statusCodeToText, typeNumberToLabel, validateDomain, validateHeaderName, validateHeaderValue, validateRobotsTxt, validateSitemap };

package/dist/{chunk-ZPQOE7KD.js → chunk-7AJRK57W.js}

@@ -26,6 +26,7 @@ __export(units_exports, {
   calculateLoan: () => calculateLoan,
   calculateMarginMarkup: () => calculateMarginMarkup,
   calculatePercentageChange: () => calculatePercentageChange,
+  calculateRoi: () => calculateRoi,
   calculateRuleOf72: () => calculateRuleOf72,
   calculateSavingsGoal: () => calculateSavingsGoal,
   calculateSimpleInterest: () => calculateSimpleInterest,
@@ -1809,5 +1810,32 @@ function calculateSavingsGoal(input) {
     finalBalance: round4(goalAmount)
   };
 }
+function calculateRoi(input) {
+  const { initialValue, finalValue, years } = input;
+  if (!Number.isFinite(initialValue) || initialValue <= 0) {
+    return { error: "initialValue must be a finite number greater than zero" };
+  }
+  if (!Number.isFinite(finalValue) || finalValue < 0) {
+    return { error: "finalValue must be a finite, non-negative number" };
+  }
+  const round4 = (n) => Math.round(n * 1e4) / 1e4;
+  const profit = finalValue - initialValue;
+  const roiPercent = profit / initialValue * 100;
+  const result = {
+    initialValue: round4(initialValue),
+    finalValue: round4(finalValue),
+    profit: round4(profit),
+    roiPercent: round4(roiPercent)
+  };
+  if (years !== void 0) {
+    if (!Number.isFinite(years) || years <= 0) {
+      return { error: "years must be a finite number greater than zero when provided" };
+    }
+    const annualizedReturnPercent = (Math.pow(finalValue / initialValue, 1 / years) - 1) * 100;
+    result.years = round4(years);
+    result.annualizedReturnPercent = round4(annualizedReturnPercent);
+  }
+  return result;
+}
 
-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, calculateBreakEven, calculateCompoundInterest, calculateDiscount, calculateEmi, calculateLoan, calculateMarginMarkup, calculatePercentageChange, calculateRuleOf72, calculateSavingsGoal, calculateSimpleInterest, calculateTax, calculateTimeValue, calculateTipSplit, calculateVideoBitrate, 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 };
+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, calculateBreakEven, calculateCompoundInterest, calculateDiscount, calculateEmi, calculateLoan, calculateMarginMarkup, calculatePercentageChange, calculateRoi, calculateRuleOf72, calculateSavingsGoal, calculateSimpleInterest, calculateTax, calculateTimeValue, calculateTipSplit, calculateVideoBitrate, 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 };