@guinetik/utilities-ts

Pure, dependency-free TypeScript primitives for Guinetik projects. The package contains no UI, DOM, storage, or network code, so the same functions can power dashboard widgets, servers, and command-line tools.

Modules

• time: timezone-aware civil time and 12/24-hour clock formatting
• units: measurement conversion with widget-ready labels and symbols
• dates: timezone-free calendar arithmetic, differences, ages, and business days
• percent: common percentage questions, changes, and reversals
• numbers: bases 2–36, Roman numerals, angles, primes, factors, GCD, and LCM
• bytes: decimal/IEC byte conversion, readable formatting, and transfer-time estimates
• text: case conversion, slugs, text statistics, and line sorting/deduplication
• finance: discounts, tips, bill splitting, interest, loans, and 2026 Brazilian IRPF estimation
• network: IPv4 parsing, CIDR ranges, subnet masks, and address counts
• math: Fibonacci and common geometry formulas (number theory is in numbers)
• timezones: timezone offsets, local date/time formatting, and overlapping meeting windows
• cooking: Brazilian kitchen measures, recipe scaling, volume/mass conversion, and oven temperatures

Examples

import {
  addCalendarDate,
  calendarDifference,
  convertNumberBase,
  convertUnit,
  percentChange,
} from '@guinetik/utilities-ts';

convertUnit(72, 'fahrenheit', 'celsius');
// 22.22222222222222

addCalendarDate('2024-01-31', { months: 1 });
// { year: 2024, month: 2, day: 29 }

calendarDifference('2020-05-10', '2026-07-14');
// { sign: 1, years: 6, months: 2, days: 4 }

percentChange(80, 100);
// 25

convertNumberBase('FFFFFFFFFFFFFFFF', 16, 10);
// '18446744073709551615'

formatBytes(1_536, { system: 'binary' });
// '1.5 KiB'

slugify('Déjà vu: A café!');
// 'deja-vu-a-cafe'

Unit conversions deliberately do not round their results. Presentation code decides the appropriate precision. US customary and Imperial volume units have distinct identifiers such as us-gallon and imperial-gallon because they are different measurements.

Calendar functions use a CalendarDate or strict YYYY-MM-DD string instead of local Date operations. This keeps results deterministic across timezones and makes end-of-month behavior explicit.

Development

npm test
npm run build