jin-time

$jin.time

Small, simple, powerfull, and fast TypeScript/JavaScript library for proper date/time/duration/range arithmetic.

Installation

Direct

<script src="http://nin-jin.github.io/time/time2.js"></script>
<script>
	alert( $jin.time.moment() ) // alerts current time
</script>

Or get typescript sources from repository: https://github.com/nin-jin/pms-jin/tree/master/time

NPM

npm install jin-time

var time = require( 'jin-time' )
console.log( time.moment().toString() ) // 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 = new Date ; console.time('test') ; for( var i = 0 ; i < 100000 ; ++i ) m.toISOString() ; console.timeEnd('test')
// 150ms

Speed of iso8601 parsing:

console.time('test') ; for( var i = 0 ; i < 10000 ; ++i ) new Date( '2015-07-20T07:48:28.338+03:00' ) ; console.timeEnd('test')
// 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 = moment() ; console.time('test') ; for( var i = 0 ; i < 100000 ; ++i ) t.toISOString() ; console.timeEnd('test')
// 470ms

Speed of iso8601 parsing:

console.time('test') ; for( var i = 0 ; i < 10000 ; ++i ) moment( '2015-07-20T07:48:28.338+03:00' ) ; console.timeEnd('test')
// 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 = $jin.time.moment() ; console.time('test') ; for( var i = 0 ; i < 100000 ; ++i ) m.toString() ; console.timeEnd('test')
// 180ms

Speed of iso8601 parsing:

console.time('test') ; for( var i = 0 ; i < 10000 ; ++i ) $jin.time.moment( '2015-07-20T07:48:28.338+03:00' ) ; console.timeEnd('test')
// 65ms

API

Moments

Creating

// current time in current time zone
$jin.time.moment()

// by timestamp
$jin.time.moment( 1437316165000 )

// by native Date
$jin.time.moment( new Date )

// by iso8601 string
$jin.time.moment( '2015-07-19T17:27:58.065+03:00' ) // full time
$jin.time.moment( '2015-07-19T17:27:58.065' ) // time without offset (non local!)
$jin.time.moment( '2015-07-19' ) // date without time (non 00:00:00)

// by components
$jin.time.moment({
	year : 2015 ,
	month : 6 , // 0 - January
	day : 18 , // 0 - first day of month
	hour : 17 ,
	minute : 27 ,
	second : 58.65 , // fractional, no property "millisecond"
	offset : { // this is $jin.time.duration
		hour : 3 ,
		minute : 0 ,
	} ,
})

// by list of components
$jin.time.moment([ 2015 , 6 , 18 , 17 , 27 , 58.65 , [ 3 , 0 ]])

Getters

// component value (undefined by default)
var moment = $jin.time.moment()
moment.year // number
moment.month // 0 .. 11
moment.day // 0 .. 30
moment.hour // 0 .. 23
moment.minute // 0 .. 59
moment.second // 0 .. 59 (fractional)
moment.offset // $jin.time.duration

// day of week
$jin.time.moment().weekDay // 0 - sunday , 6 - saturday

// timestamp
$jin.time.moment().valueOf() // Date.now()

// native Date
$jin.time.moment().native // new Date

// iso8601
$jin.time.moment().toString() // ( new Date ).toISOString()
$jin.time.moment().toJSON() // ( new Date ).toISOString()

Arithmetic

// create moment by normalize one
$jin.time.moment( '2015-07-35' ).normal // $jin.time.moment( '2015-08-04' )

// create moment by merge one moment with another
$jin.time.moment( '2015-07-19' ).merge({ month : 7 , day : 4 }) // $jin.time.moment( '2015-08-04' )

// create moment by shift one by duration
$jin.time.moment( '2015-07-19' ).shift( 'P16D' ) // $jin.time.moment( '2015-08-04' )

// create moment by shift one to offset
$jin.time.moment( '2015-07-19T19:24+03:00' ).toOffset( 'Z' ) // $jin.time.moment( '2015-07-19T16:24+00:00' )

Serialization

$jin.time.moment().toString( 'YYYY-MM-DD hh:mm (WeekDay)' ) // "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
$jin.time.duration()

// by milliseconds count
$jin.time.duration( 60000 ) // 60 seconds (non 1 minute!)

// by iso8601 string
$jin.time.duration( 'P1Y2M3DT4H5M6.7S' ) // all components are optional
$jin.time.duration( 'PT' ) // zero duration

// by components
$jin.time.duration({
	year : 1 ,
	month : 2 ,
	day : 3 ,
	hour : 4 ,
	minute : 5 ,
	second : 6.7 ,
})

// by list of components
$jin.time.duration([ 1 , 2 , 3 , 4 , 5 , 6.7 ])

Getters

//component value (0 by default)
var dur = $jin.time.duration()
durdur.year // number
dur.month // number
dur.day // number
dur.hour // number
dur.minute // number
dur.second // number (fractional)

// duration in milliseconds
$jin.time.duration( 'PT1M' ).valueOf() // 60000

// iso8601
$jin.time.duration( 'PT1M0S' ).toString() // PT1M
$jin.time.duration( 'PT1M0S' ).toJSON() // PT1M

Arithmetic

// create duration as summ of one and another
$jin.time.duration( 'PT1h' ).summ( 'PT1h1m' ) // $jin.time.duration( 'PT2H2M' )

// create duration as substract of another from one
// attention! can produce negative values that is not compatible with iso8601
$jin.time.duration( 'PT1h' ).sub( 'PT1h1m' ) // $jin.time.duration( 'PT-1M' )

Ranges

Creating

// by iso8601 string
$jin.time.range( '2015-07-19/2015-08-02' ) // by two moments
$jin.time.range( '2015-07-19/P14D' ) // by two start moment and duration
$jin.time.range( 'P14D/2015-08-02' ) // by two end moment and duration

// by components
$jin.time.range({
	start : '2015-07-19' ,
	end : '2015-08-02' ,
})
$jin.time.range({
	start : '2015-07-19' ,
	duration : 'P14D' ,
})
$jin.time.range({
	duration : 'P14D' ,
	end : '2015-08-02' ,
})

// by list of components
$jin.time.range([ '2015-07-19' , '2015-08-02' ])
$jin.time.range([ '2015-07-19' , null , 'P14D' ])
$jin.time.range([ null , '2015-08-02' , 'P14D' ])

Getters

// component value (third are calculated by defined two)
$jin.time.range( '2015/P1Y' ).end // $jin.time.moment( '2016' )
$jin.time.range( 'P1Y/2016' ).start // $jin.time.moment( '2015' )
$jin.time.range( '2015/2016' ).duration // $jin.time.duration( 'PT31536000S' )

// iso8601
$jin.time.range( '2015-01/P1M' ).toString() // '2015-01/P1MT'
$jin.time.range( '2015-01/P1M' ).toJSON() // '2015-01/P1MT'

Localization

To add some language support use typescript subclassing:

class moment_class_ru extends $jin.time.moment_class {
	static monthLong = [ 'Январь', 'Февраль', 'Март', 'Апрель', 'Май', 'Июнь', 'Июль', 'Август', 'Сентябрь', 'Октябрь', 'Ноябрь', 'Декабрь' ]
	static monthShort = [ 'Янв', 'Фев', 'Мар', 'Апр', 'Май', 'Июн', 'Июл', 'Авг', 'Сен', 'Окт', 'Ноя', 'Дек' ]
	static weekDayLong = [ 'Воскресенье', 'Понедельник', 'Вторник', 'Среда', 'Четверг', 'Пятница', 'Суббота' ]
	static weekDayShort = [ 'Вс', 'Пн', 'Вт', 'Ср', 'Чт', 'Пт', 'Сб' ]
}
$jin.time.moment['ru'] = moment_class_ru.make.bind( moment_class_ru )

Then you can use it:

$jin.time.moment['ru']().toString( 'YYYY-MM-DD (WD)' ) // "2015-07-20 (Пн)"

To Do

• Parsing by patterns
• Repeating intervals support
• Better localization