$jin.time
Small, simple, powerfull, and fast TypeScript/JavaScript library for proper date/time/duration/range arithmetic.
Installation
Direct
Or get typescript sources from repository: https://github.com/nin-jin/pms-jin/tree/master/time
NPM
npm install jin-time
var time = console // logs current time
Comparison
Native Date
- instance is timestamp representation (forever have time and timezone)
- instance is mutable object
- inconsistent, poor api
- zero lib size, but very large client code
- fastest
Speed of iso8601 serialization:
var m = ; console ; for var i = 0 ; i < 100000 ; ++i m ; console// 150ms
Speed of iso8601 parsing:
console ; for var i = 0 ; i < 10000 ; ++i '2015-07-20T07:48:28.338+03:00' ; console// 13ms
MomentJS
- instance is wrapper around native Date instance
- instance is timestamp representation (forever have time and timezone)
- instance is mutable object
- large lib size (100kb core + plugins)
- slow
- too more specific features, but some basics supports only by plugins
Speed of iso8601 serialization:
var m = ; console ; for var i = 0 ; i < 100000 ; ++i t ; console// 470ms
Speed of iso8601 parsing:
console ; for var i = 0 ; i < 10000 ; ++i ; console// 440ms
$jin.time
- all time components stores separately
- instance is immmutable object
- cool consistent core, but some needed features not implemented yet
- small lib size (35kb)
- fast
Speed of iso8601 serialization:
var m = $jintime ; console ; for var i = 0 ; i < 100000 ; ++i m ; console// 180ms
Speed of iso8601 parsing:
console ; for var i = 0 ; i < 10000 ; ++i $jintime ; console// 65ms
API
Moments
Creating
// current time in current time zone$jintime // by timestamp$jintime // by native Date$jintime // by iso8601 string$jintime // full time$jintime // time without offset (non local!)$jintime // date without time (non 00:00:00) // by components$jintime // by list of components$jintime
Getters
// component value (undefined by default)var moment = $jintimemomentyear // numbermomentmonth // 0 .. 11momentday // 0 .. 30momenthour // 0 .. 23momentminute // 0 .. 59momentsecond // 0 .. 59 (fractional)momentoffset // $jin.time.duration // day of week$jintimeweekDay // 0 - sunday , 6 - saturday // timestamp$jintime // Date.now() // native Date$jintimenative // new Date // iso8601$jintime // ( new Date ).toISOString()$jintime // ( new Date ).toISOString()
Arithmetic
// create moment by normalize one$jintimenormal // $jin.time.moment( '2015-08-04' ) // create moment by merge one moment with another$jintime // $jin.time.moment( '2015-08-04' ) // create moment by shift one by duration$jintime // $jin.time.moment( '2015-08-04' ) // create moment by shift one to offset$jintime // $jin.time.moment( '2015-07-19T16:24+00:00' )
Serialization
$jintime // "2015-07-20 07:22 (Monday)"
Mnemonics:
- single letter for numbers: M - month number, D - day of month.
- uppercase letters for dates, lowercase for times: M - month number , m - minutes number
- repeated letters for define register count: YYYY - full year, YY - shot year, MM - padded month number
- words for word representation: Month - month name, WeekDay - day of week name
- shortcuts: WD - short day of week, Mon - short month name.
Durations
Creating
// zero duration$jintime // by milliseconds count$jintime // 60 seconds (non 1 minute!) // by iso8601 string$jintime // all components are optional$jintime // zero duration // by components$jintime // by list of components$jintime
Getters
//component value (0 by default)var dur = $jintimedurduryear // numberdurmonth // numberdurday // numberdurhour // numberdurminute // numberdursecond // number (fractional) // duration in milliseconds$jintime // 60000 // iso8601$jintime // PT1M$jintime // PT1M
Arithmetic
// create duration as summ of one and another$jintime // $jin.time.duration( 'PT2H2M' ) // create duration as substract of another from one// attention! can produce negative values that is not compatible with iso8601$jintime // $jin.time.duration( 'PT-1M' )
Ranges
Creating
// by iso8601 string$jintime // by two moments$jintime // by two start moment and duration$jintime // by two end moment and duration // by components$jintime$jintime$jintime // by list of components$jintime$jintime$jintime
Getters
// component value (third are calculated by defined two)$jintimeend // $jin.time.moment( '2016' )$jintimestart // $jin.time.moment( '2015' )$jintimeduration // $jin.time.duration( 'PT31536000S' ) // iso8601$jintime // '2015-01/P1MT'$jintime // '2015-01/P1MT'
Localization
To add some language support use typescript subclassing:
timemoment_class static monthLong = 'Январь' 'Февраль' 'Март' 'Апрель' 'Май' 'Июнь' 'Июль' 'Август' 'Сентябрь' 'Октябрь' 'Ноябрь' 'Декабрь' static monthShort = 'Янв' 'Фев' 'Мар' 'Апр' 'Май' 'Июн' 'Июл' 'Авг' 'Сен' 'Окт' 'Ноя' 'Дек' static weekDayLong = 'Воскресенье' 'Понедельник' 'Вторник' 'Среда' 'Четверг' 'Пятница' 'Суббота' static weekDayShort = 'Вс' 'Пн' 'Вт' 'Ср' 'Чт' 'Пт' 'Сб' $jintimemoment'ru' = moment_class_rumake
Then you can use it:
$jintimemoment'ru' // "2015-07-20 (Пн)"
To Do
- Parsing by patterns
- Repeating intervals support
- Better localization