Skip to content
⚡️ Fast parsing, formatting and timezone manipulations for dates
C++ JavaScript Python
Branch: master
Clone or download

Latest commit

Latest commit 436e920 Jan 15, 2018


Type Name Latest commit message Commit time
Failed to load latest commit information.
cctz @ 0a5cc50 update cctz to 0a5cc500 Jun 20, 2017
src fix: typo Jan 14, 2018
.editorconfig Initial commit Nov 26, 2016
.gitignore Initial commit Nov 26, 2016
.gitmodules Initial commit Nov 26, 2016
.npmignore 🦄 Dec 3, 2016
.travis.yml add Node.JS 8 to .travis.yml Jun 20, 2017
bench.js clean up benchmark Mar 8, 2017
index.js floor timestamp from Mar 8, 2017
package.json 1.7.7 Jun 20, 2017 Merge pull request #14 from floatdrop/floor-now Mar 8, 2017
test.js fix crash on unknown timezone in tz helper Mar 17, 2017

node-cctz Build Status

CCTZ is a C++ library for translating between absolute and civil times using the rules of a time zone.


You will need C++11 compatible compiler to build this binding. For most systems this will work:

$ npm install --save cctz

If you have Ubuntu 12.04, then install clang-3.4 and set-up environment:

$ sudo apt-get install clang-3.4
$ export CXX=clang++
$ export npm_config_clang=1


const {convert, format, CivilTime} = require('cctz');

const unix = convert(new CivilTime(2015, 9, 22, 9), 'America/Los_Angeles');
console.log(format('Talk starts at %T %z (%Z)', unix, 'America/New_York'));

// => Talk starts at 12:00:00 -0400 (EDT)


convert(time, timezone)

Converts CivilTime to unix timestamp and vice versa.


Type: CivilTime or number

If time is CivilTime, then method returns Unix timestamp (without fractional part). Otherwise returns CivilTime.


Type: TimeZone or string

TimeZone objcet, that represents target timezone for converting.

format(format, unix, [timezone])

Returns formatted unix timestamp according to timezone.


Type: string

Format of output. See strftime documentation and Google CCTZ sources for syntax.


Type: number

Unix timestamp in seconds (can have fractional part).


Type: TimeZone or string Default: local timezone

TimeZone objcet, that represents target timezone for formatting.

parse(format, input, [timezone])

Parses input string according to format string (assuming input in timezone).

Returns unix timestamp or undefined if parsing failed.


Type: string

Format of input argument. See strftime documentation and Google CCTZ sources for syntax.


Type: string

Input string to parse.


Type: TimeZone or string
Default: Timezone from input or local timezone

Timezone, that should be used in parse. Timezone can be part of input:

cctz.parse('%Y-%m-%d %H:%M:%S %Ez', '2015-09-22 09:35:12+03:00');


Alias for cctz.load_time_zone

Use this method instead new TimeZone – because it caches TimeZone objects inside.

Returns TimeZone object.


Type: string

Timezone name, that should be loaded from /usr/share/zoneinfo.


Alias for Math.floor( / 1000)

Returns unix timestamp in seconds. All methods can accept timestamp with fractional milliseconds (if you need such accuracy).


Holder for cctz::civil_second with getters and setters for properties.

CivilTime(year = 1970, month = 1, day = 1, hour = 0, minute = 0, second = 0)

Creates CivilTime object with next properties:

  • year – getter and setter
  • month – getter and setter [1:12]
  • day – getter and setter [1:31]
  • hour – getter and setter [0:23]
  • minute – getter and setter [0:59]
  • second – getter and setter [0:59]
  • yearday – only getter [1:356]
  • weekday – only getter [0:6]

Tip: Fastest way to add amount of time is to add number of seconds to unix timestamp.


Returns new CivilTime object with start of year.


Returns new CivilTime object with start of month.


Returns new CivilTime object with start of day.


Returns new CivilTime object with start of hour.


Returns cloned CivilTime object.


Holder for cctz::time_zone.


Creates new object with TimeZone.


Returns cctz::absolute_lookup object.


Returns cctz::civil_lookup object.

Name of TimeZone.


Format              (cctz) x 532,683 ops/sec ±2.80% (78 runs sampled)
                    (Date) x 191,400 ops/sec ±2.59% (81 runs sampled)
                (date-fns) x  91,772 ops/sec ±1.58% (85 runs sampled)
                  (moment) x  56,508 ops/sec ±6.35% (76 runs sampled)

Parse               (cctz) x 1,105,353 ops/sec ±0.59% (86 runs sampled)
                    (Date) x 1,200,218 ops/sec ±2.00% (82 runs sampled)
                (date-fns) x   249,225 ops/sec ±5.00% (77 runs sampled)
                  (moment) x    23,905 ops/sec ±1.91% (80 runs sampled)

Add hour            (cctz) x 6,123,083 ops/sec ±5.39% (82 runs sampled)
                    (Date) x 3,604,915 ops/sec ±1.13% (69 runs sampled)
                (date-fns) x 3,211,900 ops/sec ±2.28% (81 runs sampled)
                  (moment) x   590,854 ops/sec ±8.48% (72 runs sampled)

Convert Ut->Time    (cctz) x 653,305 ops/sec ±9.33% (68 runs sampled)
                  (moment) x 144,580 ops/sec ±2.18% (83 runs sampled)

Convert Time->Ut    (cctz) x 987,437 ops/sec ±11.68% (70 runs sampled)
                  (moment) x 154,492 ops/sec ±3.54% (82 runs sampled)

Run npm i and then npm run bench.


MIT © Vsevolod Strukchinsky

You can’t perform that action at this time.