A comprehensive, functional datetime library for JavaScript/TypeScript with immutable data structures, real IANA timezone database support, and a plugin system.
- 🚀 Functional Programming: Pure functions and immutable data structures
- 🌍 Real Timezone Database: Full IANA timezone support with automatic DST detection
- 🕐 DST Handling: Accurate daylight saving time transitions and calculations
- 📅 Calendar Arithmetic: Safe date/time arithmetic with overflow handling
- 🎨 Formatting System: Comprehensive token-based formatting with locale support
- ⏱️ Duration Operations: Monoid operations and humanization
- 🔄 Recurrence Generators: Flexible recurring date/time patterns
- 🔌 Plugin System: Extensible architecture for custom functionality
- 📦 TypeScript: Full TypeScript support with comprehensive type definitions
- 🌐 Zero Dependencies: Uses built-in Intl API for timezone data
import ream from 'ream.js';
// Create dates
const date = ream('2023-07-15T14:30:45.123Z');
const now = ream();
// Chain operations
const result = date
.add(1, 'days')
.subtract(2, 'hours')
.tz('America/New_York')
.format('YYYY-MM-DD HH:mm:ss');
// Use generators
const monthly = everyMonth()(date);
const firstMonth = monthly.next().value;
const secondMonth = monthly.next().value;
// Use plugins
const extended = extend(relativePlugin)(date);
console.log(extended.fromNow()); // "2 hours ago"
-
Instant: Point in time (epoch milliseconds)
-
Duration: Time span with monoid operations
-
PlainDate: Calendar date without timezone
-
PlainTime: Time of day without timezone
-
PlainDateTime: Combined date and time
-
ZDT: Zoned DateTime with functor operations
For complete API documentation, see the REAM.md specification.
# Install dependencies
npm install
# Run tests
npm test
# Build the library
npm run build
# Watch mode for development
npm run watch:test
Real Timezone Database Support
ream.js includes comprehensive support for real IANA timezone data using the built-in JavaScript Intl API:
import ream, { getTimezoneInfo, isDST, isValidTimezone } from 'ream.js';
// Real timezone information
const tzInfo = getTimezoneInfo('America/New_York', instant(Date.now()));
console.log(tzInfo);
// {
// name: 'America/New_York',
// offsetMinutes: -240, // EDT (UTC-4) or -300 (EST, UTC-5)
// dst: true, // true during daylight saving time
// abbreviation: 'EDT' // timezone abbreviation
// }
// Enhanced ReamDate with timezone methods
const date = ream('2023-07-15T14:30:00', 'America/New_York');
console.log(date.timezone().name); // 'America/New_York'
console.log(date.timezone().abbreviation); // 'EDT'
console.log(date.isDST()); // true
console.log(date.offset()); // -240
// Timezone validation and utilities
console.log(isValidTimezone('America/New_York')); // true
console.log(isDST('Europe/London')); // depends on current date
// Convert between timezones
const utcDate = ream('2023-07-15T16:30:00Z');
const nyDate = utcDate.tz('America/New_York');
const londonDate = utcDate.tz('Europe/London');
- ✅ Real IANA timezone data (no external dependencies)
- ✅ Automatic DST detection and handling
- ✅ Timezone abbreviations (EST, EDT, GMT, BST, etc.)
- ✅ Timezone validation
- ✅ Support for all IANA timezone identifiers
- ✅ Works in browsers and Node.js
See TIMEZONE_FEATURES.md for comprehensive documentation.
This library uses automated npm publishing via GitHub Actions. To publish a new version:
- Update the version in package.json
- Create a new GitHub release with a tag matching the version (e.g., v1.0.1)
- The GitHub Action will automatically run tests and publish to npm
Setup NPM Publishing (for maintainers)
- Create an npm account and generate an access token
- Add the token as a GitHub secret named NPM_TOKEN
- Ensure the package name in package.json is available on npm
MIT
.png)
18 hours ago
2
