datevolt

A complete, lightweight, zero-dependency JavaScript date library with a familiar chainable API. Built with React Native CLI in mind (Android + iOS, Hermes & JSC), and works just as well in Node.js and browsers.

Why datevolt?

Most date libraries are either too heavy for mobile apps or too minimal to be useful. datevolt hits the middle ground — full-featured, tiny footprint, no dependencies, and no native modules.

| Feature | datevolt | |---|---| | Size (gzipped) | ~8 KB | | Size (minified) | ~25 KB | | Dependencies | 0 | | Tree-shakeable | ✅ | | Immutable .clone() | ✅ | | React Native (Hermes + JSC) | ✅ | | Node.js | ✅ | | Browser | ✅ | | Chainable API | ✅ | | Built-in i18n | ✅ |

No Intl dependency. No native modules. No configuration. Just install and use.

Installation

# npm
npm install datevolt

# yarn
yarn add datevolt

Quick Start

const datevolt = require('datevolt');
// or
import datevolt from 'datevolt';

datevolt().format('YYYY-MM-DD HH:mm:ss')             // "2024-06-15 14:30:00"
datevolt('2024-06-15').format('dddd, MMMM D, YYYY')  // "Saturday, June 15, 2024"
datevolt().add(7, 'days').format('DD MMM YYYY')       // "22 Jun 2024"
datevolt('2024-01-01').fromNow()                      // "6 months ago"
datevolt('2024-06-15').diff('2024-01-01', 'days')     // 166
datevolt('2024-06-15').isBefore('2024-12-31')         // true

React Native

Works out of the box — no extra setup, no metro config changes needed.

import datevolt from 'datevolt';

const DateDisplay = () => {
  const [today] = React.useState(datevolt().format('LL'));
  return <Text>{today}</Text>; // "June 15, 2024"
};

Tested on Android (Hermes) and iOS (JSC). Pure JavaScript — no native bridge needed.

API Reference

Parsing

datevolt()                                            // now
datevolt('2024-06-15')                                // ISO date (local midnight)
datevolt('2024-06-15T10:30:00')                       // ISO datetime
datevolt('2024-06-15T10:30:00Z')                      // UTC
datevolt('2024-06-15T10:30:00+05:30')                 // with offset
datevolt('15/06/2024', 'DD/MM/YYYY')                  // custom format
datevolt('15/06/2024', ['DD/MM/YYYY', 'YYYY-MM-DD'])  // multiple formats
datevolt([2024, 5, 15])                               // array [Y, M(0-based), D]
datevolt([2024, 5, 15, 14, 30, 0, 0])                // array with time
datevolt({ year: 2024, month: 5, day: 15 })           // object
datevolt(1718438400000)                               // unix milliseconds
datevolt.unix(1718438400)                             // unix seconds
datevolt.utc('2024-06-15T10:30:00')                   // UTC mode

// Validation
datevolt('2024-06-15').isValid()    // true
datevolt('not-a-date').isValid()    // false

Get & Set

const d = datevolt('2024-06-15T14:30:45.123');

d.year()         // 2024   →  d.year(2025)
d.month()        // 5      →  d.month(0)     (0-based, Jan = 0)
d.date()         // 15     →  d.date(1)
d.day()          // 6      →  d.day(1)       (0 = Sun, 6 = Sat)
d.hour()         // 14     →  d.hour(9)
d.minute()       // 30     →  d.minute(0)
d.second()       // 45     →  d.second(0)
d.millisecond()  // 123

d.quarter()      // 2
d.dayOfYear()    // 167
d.daysInMonth()  // 30
d.week()         // ISO week number
d.isoWeek()
d.isoWeekday()   // 1 = Mon ... 7 = Sun
d.weeksInYear()

// Generic
d.get('year')        // 2024
d.set('year', 2025)  // chainable

Manipulate

datevolt().add(7, 'days')
datevolt().add(1, 'month')
datevolt().add(2, 'years')
datevolt().add(3, 'hours')
datevolt().add(30, 'minutes')
datevolt().add({ days: 1, hours: 2, minutes: 30 })  // object form

datevolt().subtract(1, 'week')
datevolt().subtract(3, 'months')

// Chainable
datevolt('2024-01-01').add(1, 'year').subtract(3, 'months').startOf('month')

// startOf / endOf
datevolt().startOf('year')     // Jan 1, 00:00:00.000
datevolt().startOf('month')    // 1st of month, 00:00:00.000
datevolt().startOf('week')
datevolt().startOf('day')
datevolt().startOf('hour')
datevolt().startOf('quarter')
datevolt().startOf('isoWeek')

datevolt().endOf('year')       // Dec 31, 23:59:59.999
datevolt().endOf('month')      // last day, 23:59:59.999

datevolt().clone()             // immutable copy

Format

datevolt().format('YYYY-MM-DD')              // "2024-06-15"
datevolt().format('YYYY-MM-DD HH:mm:ss')     // "2024-06-15 14:30:45"
datevolt().format('dddd, MMMM D, YYYY')      // "Saturday, June 15, 2024"
datevolt().format('MMM Do, YYYY')            // "Jun 15th, 2024"
datevolt().format('h:mm A')                  // "2:30 PM"
datevolt().format('[Today is] dddd')         // "Today is Saturday"
datevolt().format('L')                       // "06/15/2024"
datevolt().format('LL')                      // "June 15, 2024"
datevolt().format('LLL')                     // "June 15, 2024 2:30 PM"
datevolt().format('LLLL')                    // "Saturday, June 15, 2024 2:30 PM"

Format Tokens

| Token | Output | Description | |-------|--------|-------------| | YYYY | 2024 | Full year | | YY | 24 | 2-digit year | | MMMM | June | Full month name | | MMM | Jun | Short month | | MM | 06 | Month (2-digit) | | M | 6 | Month | | DD | 15 | Day (2-digit) | | Do | 15th | Ordinal day | | D | 15 | Day | | dddd | Saturday | Full weekday | | ddd | Sat | Short weekday | | HH | 14 | 24-hour | | h | 2 | 12-hour | | mm | 30 | Minutes | | ss | 45 | Seconds | | SSS | 123 | Milliseconds | | A | PM | AM/PM | | Z | +05:30 | UTC offset | | X | 1718438400 | Unix seconds | | x | 1718438400000 | Unix ms | | Q | 2 | Quarter |

Relative Time

datevolt('2024-01-01').fromNow()               // "6 months ago"
datevolt().add(2, 'hours').fromNow()           // "in 2 hours"
datevolt().subtract(3, 'days').fromNow(true)   // "3 days" (no suffix)

datevolt('2024-01-01').from('2024-06-15')      // "6 months ago"
datevolt().add(5, 'minutes').toNow()           // "in 5 minutes"
datevolt('2024-01-01').to('2024-06-15')        // "in 6 months"

Calendar

datevolt().calendar()                     // "Today at 2:30 PM"
datevolt().add(1, 'day').calendar()       // "Tomorrow at 2:30 PM"
datevolt().subtract(1, 'day').calendar()  // "Yesterday at 2:30 PM"
datevolt().add(3, 'days').calendar()      // "Tuesday at 2:30 PM"
datevolt().subtract(7, 'days').calendar() // "06/08/2024"

Diff

datevolt('2024-06-15').diff('2024-01-01', 'days')              // 166
datevolt('2024-06-15').diff('2024-01-01', 'months')            // 5
datevolt('2024-06-15').diff('2020-01-01', 'years')             // 4
datevolt('2024-06-15T12:00').diff('2024-06-15T10:00', 'hours') // 2
datevolt('2024-06-15').diff('2024-01-01', 'days', true)        // 166.xxx (float)

Query & Comparison

datevolt('2024-01-01').isBefore('2024-06-15')                         // true
datevolt('2024-06-15').isAfter('2024-01-01')                          // true
datevolt('2024-06-15T10:00').isSame('2024-06-15T18:00', 'day')        // true
datevolt('2024-01-01').isSameOrBefore('2024-01-01')                   // true
datevolt('2024-06-15').isSameOrAfter('2024-06-15')                    // true
datevolt('2024-03-15').isBetween('2024-01-01', '2024-12-31')          // true
datevolt('2024-01-01').isBetween('2024-01-01', '2024-12-31', null, '[]') // inclusive

datevolt('2024-06-15').isLeapYear()  // true
datevolt().isDST()                   // true/false
datevolt.isMoment(datevolt())        // true
datevolt.isDate(new Date())          // true

UTC & Timezone

// UTC mode
datevolt.utc('2024-06-15T10:30:00').format('HH:mm')  // always UTC hours
datevolt.utc().isUTC()    // true
datevolt.utc().local()    // switch back to local

// UTC offset
datevolt().utcOffset()            // offset in minutes
datevolt().utcOffset('+05:30')    // set by string
datevolt().utcOffset(330)         // set by minutes
datevolt().utcOffset(0, true)     // keep local time, change offset

Duration

const d = datevolt.duration(2, 'days');
d.asDays()     // 2
d.asHours()    // 48
d.asMinutes()  // 2880

datevolt.duration({ hours: 1, minutes: 30 }).asMinutes()  // 90
datevolt.duration('P1Y2M3DT4H5M6S')                       // ISO 8601 duration

datevolt.duration(1, 'day').humanize()       // "a day"
datevolt.duration(1, 'day').humanize(true)   // "in a day"

d.years() / d.months() / d.days() / d.hours() / d.minutes() / d.seconds()
d.add(1, 'hour').subtract(30, 'minutes')
d.clone()
d.toISOString()  // "P2D"

// Pass duration directly into add()
datevolt().add(datevolt.duration(2, 'hours'))

datevolt.isDuration(d)  // true

Locale (i18n)

7 built-in locales: en, hi, es, fr, de, ar, ja

// Set global locale
datevolt.locale('hi');
datevolt().format('MMMM D, YYYY');  // "जून 15, 2024"

// Per-instance locale
datevolt().locale('es').format('MMMM');  // "junio"

// List all available
datevolt.locales();  // ['en', 'hi', 'es', 'fr', 'de', 'ar', 'ja']

// Define a custom locale
datevolt.defineLocale('mr', {
  name: 'mr',
  months: ['जानेवारी', 'फेब्रुवारी', 'मार्च', ...],
  // ...
});

// Access locale data
datevolt.localeData('en').months
datevolt().localeData()

Static Methods

datevolt.max(a, b, c)         // returns the latest date
datevolt.min(a, b, c)         // returns the earliest date
datevolt.invalid()            // returns an invalid datevolt instance
datevolt.normalizeUnits('y')  // 'year'
datevolt.version              // '1.0.1'
datevolt.fn                   // prototype — use for plugins

Familiar API

If you've used any chainable date library before, datevolt will feel right at home. The API follows widely adopted conventions in the JavaScript date ecosystem — parse, format, add, subtract, diff, fromNow, and more — all chainable and consistent.

// Switching from another date library? It's usually just a one-line change:
// const datevolt = require('datevolt');
// Then use it the same way you always have.

License

MIT © shaikh-saqlain