National Pizza Magistrate

    jin-time

    1.2.5 • Public • Published

    $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 ; ++) m.toISOString() ; console.timeEnd('test')
    // 150ms

    Speed of iso8601 parsing:

    console.time('test') ; for( var i = 0 ; i < 10000 ; ++) 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 ; ++) t.toISOString() ; console.timeEnd('test')
    // 470ms

    Speed of iso8601 parsing:

    console.time('test') ; for( var i = 0 ; i < 10000 ; ++) 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 ; ++) m.toString() ; console.timeEnd('test')
    // 180ms

    Speed of iso8601 parsing:

    console.time('test') ; for( var i = 0 ; i < 10000 ; ++) $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

    Install

    npm i jin-time

    DownloadsWeekly Downloads

    3

    Version

    1.2.5

    License

    MIT

    Last publish

    Collaborators

    • jin