JSPM

@oxog/kairos

1.1.0
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 2
  • Score
    100M100P100Q39757F
  • License MIT

Revolutionary zero-dependency JavaScript date/time library with modular architecture and dynamic holiday system

Package Exports

  • @oxog/kairos
  • @oxog/kairos/plugins/business/fiscal
  • @oxog/kairos/plugins/business/workday
  • @oxog/kairos/plugins/calendar/calendar
  • @oxog/kairos/plugins/duration/duration
  • @oxog/kairos/plugins/fiscal/fiscal
  • @oxog/kairos/plugins/format/tokens
  • @oxog/kairos/plugins/holiday/calculators/custom
  • @oxog/kairos/plugins/holiday/calculators/easter
  • @oxog/kairos/plugins/holiday/calculators/fixed
  • @oxog/kairos/plugins/holiday/calculators/lunar
  • @oxog/kairos/plugins/holiday/calculators/nth-weekday
  • @oxog/kairos/plugins/holiday/calculators/relative
  • @oxog/kairos/plugins/holiday/engine
  • @oxog/kairos/plugins/holiday/holiday
  • @oxog/kairos/plugins/locale/de-DE
  • @oxog/kairos/plugins/locale/en-US
  • @oxog/kairos/plugins/locale/es-ES
  • @oxog/kairos/plugins/locale/fr-FR
  • @oxog/kairos/plugins/locale/it-IT
  • @oxog/kairos/plugins/locale/ja-JP
  • @oxog/kairos/plugins/locale/pt-BR
  • @oxog/kairos/plugins/locale/ru-RU
  • @oxog/kairos/plugins/locale/tr-TR
  • @oxog/kairos/plugins/locale/zh-CN
  • @oxog/kairos/plugins/parse/flexible
  • @oxog/kairos/plugins/parse/iso
  • @oxog/kairos/plugins/parse/rfc2822
  • @oxog/kairos/plugins/parse/unix
  • @oxog/kairos/plugins/range/range
  • @oxog/kairos/plugins/relative/relative-time
  • @oxog/kairos/plugins/timezone/timezone

Readme

Kairos

npm version Build Status Coverage Status Bundle Size License TypeScript Tree-Shaking

A lightweight, zero-dependency JavaScript library for date and time manipulation with a powerful plugin architecture, comprehensive holiday support for 10+ locales, and business day calculations.

๐ŸŒŸ Key Features

๐ŸŽ‰ Advanced Holiday System

  • 10+ Locales with built-in holiday support:
    • ๐Ÿ‡บ๐Ÿ‡ธ United States - Federal holidays + 50 state holidays
    • ๐Ÿ‡ฉ๐Ÿ‡ช Germany - National + 16 Lรคnder holidays
    • ๐Ÿ‡ซ๐Ÿ‡ท France - National + regional holidays
    • ๐Ÿ‡ช๐Ÿ‡ธ Spain - National + autonomous communities
    • ๐Ÿ‡ฎ๐Ÿ‡น Italy - National + regional observances
    • ๐Ÿ‡ง๐Ÿ‡ท Brazil - Federal + state holidays
    • ๐Ÿ‡ท๐Ÿ‡บ Russia - Federal + regional holidays
    • ๐Ÿ‡จ๐Ÿ‡ณ China - Traditional lunar + modern holidays
    • ๐Ÿ‡ฏ๐Ÿ‡ต Japan - National + Golden Week holidays
    • ๐Ÿ‡น๐Ÿ‡ท Turkey - National + religious holidays
  • Dynamic Holiday Calculation - Easter-based, lunar calendar, nth weekday rules
  • Regional Holidays - State/province specific holidays
  • Business Day Calculations - Holiday-aware business day operations
  • Custom Holiday Rules - Define your own holiday calculation logic

๐Ÿš€ Core Features

  • Zero Dependencies - Completely self-contained with no external requirements
  • Plugin Architecture - Load only what you need, tree-shaking friendly
  • Immutable API - All operations return new instances
  • TypeScript Support - Full type definitions included
  • Cross-Platform - Works in Node.js 14+ and modern browsers
  • Lightweight - Core ~25KB, all plugins ~190KB minified + gzipped
  • Comprehensive Testing - 95%+ code coverage with 400+ tests

Quick Start

npm install @oxog/kairos
const kairos = require('@oxog/kairos');
const holidayEngine = require('@oxog/kairos/plugins/holiday/engine');
const localeUS = require('@oxog/kairos/plugins/locale/en-US');

// Setup with holiday support
kairos.use([holidayEngine, localeUS]);

// Current date/time
const now = kairos();

// Parse dates
const date = kairos('2024-12-25');

// Format dates
console.log(date.format('MMMM D, YYYY')); // December 25, 2024

// Check holidays
console.log(date.isHoliday()); // true
console.log(date.getHolidayName()); // "Christmas Day"

// Date arithmetic
const tomorrow = date.add(1, 'day');
const lastWeek = date.subtract(1, 'week');

// Comparisons
console.log(date.isBefore(tomorrow)); // true
console.log(date.isAfter(lastWeek)); // true

Core API

Creating Instances

kairos(); // Current date/time
kairos('2024-06-15'); // ISO string
kairos(1718460600000); // Unix timestamp (ms)
kairos([2024, 5, 15]); // Array [year, month, day]
kairos({ year: 2024, month: 6 }); // Object

Manipulation

const date = kairos('2024-06-15');

date.add(1, 'day'); // Add time
date.subtract(2, 'hours'); // Subtract time
date.startOf('month'); // Beginning of month
date.endOf('year'); // End of year
date.clone(); // Create copy

Comparison

const date1 = kairos('2024-06-15');
const date2 = kairos('2024-06-20');

date1.isBefore(date2); // true
date1.isAfter(date2); // false
date1.isSame(date2, 'month'); // true
date1.isBetween(start, end); // Check if between
date1.diff(date2, 'days'); // -5

Display

const date = kairos('2024-06-15 14:30:00');

date.format('YYYY-MM-DD'); // 2024-06-15
date.format('MMM D, YYYY h:mm A'); // Jun 15, 2024 2:30 PM
date.toISOString(); // 2024-06-15T14:30:00.000Z
date.valueOf(); // Unix timestamp (ms)
date.toDate(); // JavaScript Date object

Plugins

๐ŸŽŠ Holiday Support & Business Days

const holidayEngine = require('@oxog/kairos/plugins/holiday/engine');
const businessPlugin = require('@oxog/kairos/plugins/business/workday');
const localeUS = require('@oxog/kairos/plugins/locale/en-US');
const localeFR = require('@oxog/kairos/plugins/locale/fr-FR');

kairos.use([holidayEngine, businessPlugin, localeUS, localeFR]);

// Check holidays
const christmas = kairos('2024-12-25');
christmas.isHoliday(); // true
christmas.getHolidayName(); // "Christmas Day"

// Get holidays for a year
const holidays2024 = kairos.getHolidays(2024);
// Returns array of holiday dates with names

// Business days with holiday awareness
const date = kairos('2024-12-24');
date.isBusinessDay(); // false (Christmas Eve)
date.nextBusinessDay(); // Skips holidays & weekends
date.addBusinessDays(5); // Holiday-aware calculation

// Locale-specific holidays
kairos.locale('fr-FR');
const bastilleDay = kairos('2024-07-14');
bastilleDay.isHoliday(); // true (Fรชte Nationale)

// Regional holidays
const spanishHolidays = kairos.getSpanishHolidays('cataluna');
// Returns Catalonia-specific holidays

Duration

const durationPlugin = require('@oxog/kairos/plugins/duration/duration');
kairos.use(durationPlugin);

const duration = kairos.duration({ hours: 2, minutes: 30 });
duration.asMinutes(); // 150
duration.humanize(); // "3 hours"
duration.toISOString(); // "PT2H30M"

Range

const rangePlugin = require('@oxog/kairos/plugins/range/range');
kairos.use(rangePlugin);

const range = kairos.range(start, end);
range.contains(date); // Check if date in range
range.overlaps(otherRange); // Check overlap
range.duration(); // Get duration

Relative Time

const relativePlugin = require('@oxog/kairos/plugins/relative/relative');
kairos.use(relativePlugin);

const past = kairos().subtract(2, 'hours');
past.fromNow(); // "2 hours ago"
past.from(reference); // Relative to reference
past.calendar(); // "Today at 2:30 PM"

Timezone

const timezonePlugin = require('@oxog/kairos/plugins/timezone/timezone');
kairos.use(timezonePlugin);

const local = kairos();
const utc = local.utc(); // Convert to UTC
utc.local(); // Back to local
local.utcOffset(); // Offset in minutes

๐ŸŒ Localization (10 Languages)

// Available locales with comprehensive holiday support
const localeUS = require('@oxog/kairos/plugins/locale/en-US'); // ๐Ÿ‡บ๐Ÿ‡ธ United States
const localeUK = require('@oxog/kairos/plugins/locale/en-GB'); // ๐Ÿ‡ฌ๐Ÿ‡ง United Kingdom
const localeDE = require('@oxog/kairos/plugins/locale/de-DE'); // ๐Ÿ‡ฉ๐Ÿ‡ช Germany
const localeFR = require('@oxog/kairos/plugins/locale/fr-FR'); // ๐Ÿ‡ซ๐Ÿ‡ท France
const localeES = require('@oxog/kairos/plugins/locale/es-ES'); // ๐Ÿ‡ช๐Ÿ‡ธ Spain
const localeIT = require('@oxog/kairos/plugins/locale/it-IT'); // ๐Ÿ‡ฎ๐Ÿ‡น Italy
const localePT = require('@oxog/kairos/plugins/locale/pt-BR'); // ๐Ÿ‡ง๐Ÿ‡ท Brazil
const localeRU = require('@oxog/kairos/plugins/locale/ru-RU'); // ๐Ÿ‡ท๐Ÿ‡บ Russia
const localeCN = require('@oxog/kairos/plugins/locale/zh-CN'); // ๐Ÿ‡จ๐Ÿ‡ณ China
const localeJP = require('@oxog/kairos/plugins/locale/ja-JP'); // ๐Ÿ‡ฏ๐Ÿ‡ต Japan
const localeTR = require('@oxog/kairos/plugins/locale/tr-TR'); // ๐Ÿ‡น๐Ÿ‡ท Turkey

// Load and use locales
kairos.use([localeFR, localeES, localeIT]);

// Switch between locales dynamically
kairos.setLocale('fr-FR');
const date = kairos('2024-07-14');
date.format('LLLL'); // "dimanche 14 juillet 2024 00:00"
date.isHoliday(); // true (Fรชte Nationale)

// Each locale includes:
// โœ“ Translated month/weekday names
// โœ“ Date/time formatting patterns
// โœ“ National holidays with local names
// โœ“ Regional/state holidays
// โœ“ Religious and cultural observances

Format Tokens

Token Output Description
YYYY 2024 4-digit year
YY 24 2-digit year
MM 01-12 Month (padded)
M 1-12 Month
MMMM January Month name
MMM Jan Month short
DD 01-31 Day (padded)
D 1-31 Day
dddd Monday Weekday name
ddd Mon Weekday short
HH 00-23 Hour (24h, padded)
H 0-23 Hour (24h)
hh 01-12 Hour (12h, padded)
h 1-12 Hour (12h)
mm 00-59 Minutes (padded)
m 0-59 Minutes
ss 00-59 Seconds (padded)
s 0-59 Seconds
SSS 000-999 Milliseconds
A AM/PM Meridiem
a am/pm Meridiem (lowercase)
Z +00:00 Timezone offset

TypeScript

Kairos includes full TypeScript definitions with complete holiday support:

import kairos, { Kairos, HolidayRule, HolidayInfo } from '@oxog/kairos';
import holidayEngine from '@oxog/kairos/plugins/holiday/engine';
import localeUS from '@oxog/kairos/plugins/locale/en-US';

kairos.use([holidayEngine, localeUS]);

const date: Kairos = kairos('2024-12-25');
const isHoliday: boolean = date.isHoliday();
const holidayName: string | null = date.getHolidayName();
const holidays: HolidayInfo[] = kairos.getHolidays(2024);

Browser Usage

<script src="https://unpkg.com/@oxog/kairos/dist/kairos.min.js"></script>
<script>
  const date = kairos('2024-06-15');
  console.log(date.format('MMMM D, YYYY'));
</script>

Examples

See the examples/ directory for detailed usage examples:

  • 01-fundamentals.js - Core concepts and basic operations
  • 02-comparison-queries.js - Date comparisons and queries
  • 03-formatting-display.js - Formatting options
  • 04-business-calendar.js - Business day calculations with holiday awareness
  • 05-durations-ranges.js - Duration and range operations
  • 06-localization.js - Multi-locale support with 10+ languages
  • 07-timezone-utc.js - Timezone handling
  • 08-parsing-validation.js - Parsing strategies
  • 09-relative-time.js - Human-readable time
  • 10-advanced-plugins.js - Complex scenarios
  • test-new-locales.js - Testing all available locales

๐ŸŽฏ Performance & Quality

Kairos is optimized for performance and reliability:

  • Intelligent caching for repeated operations (LRU cache for holidays)
  • Minimal object creation to reduce memory pressure
  • Efficient algorithms for date calculations
  • Tree-shaking support for smaller bundles
  • 95%+ code coverage with comprehensive test suite
  • Cross-platform testing on Windows, macOS, and Linux
  • Performance benchmarks to prevent regressions

Testing

npm test           # Run all tests
npm run test:unit  # Unit tests only
npm run test:perf  # Performance tests
npm run coverage   # Coverage report

License

MIT

Contributing

See CONTRIBUTING.md for guidelines.

Support