node-datetime

©Nobuyori Takahashi < voltrue2@yahoo.com >

An extended Date object for javascript.

1. Handles offests by days and hours.

2. Built-in formatting function.

3. Time based value calculation.

Installation

Installation via npm

npm install node-datetime

Use node-datetime in browser

In order to use node-datetime in browser, you will need to load the script as shown below:

The browser script file is located at: node-datetime/release/browser/node_datetime.js.

Add the script to your HTML

The "src" path must be according to your server setup.

<scripttype="text/javascript" src="./node_datetime.js"></script>

window.DateTime

When you add the script to your HTML page correctly, window.DateTime object will be accessible as a global object.

The object is the equivalent of var datetime = require('node-datetime'); in node.js version.

---

Backward Compatibilty Break Warning

From version 1.0.0, certain APIs have changed their behavior.

.now()

This API used to return a fixed timestamp in milliseconds meaning that it was returning the timestamp of the instance of datetime.

Now .now() returns a calculated current timestamp in milliseconds with time offset if given.

Example:

You could get current time of the past, for exmaple.

vardatetime=require('node-datetime');varpast='2015-01-01 00:00:00';varpastDateTime=datetime.create(past);// get the current timestamp of the pastsetTimeout(function(){varpastNow=pastDateTime.now();// this would be 1420038010000console.log(pastNow);// this would be 2015-01-01 00:00:10console.log(newDate(1420038010000));},1000);

.getTime()

This API is the same as former .now(). It returns the timestamp of datetime object.

Example:

vardatetime=require('node-datetime');varpast='2015-01-01 00:00:00';varpastDateTime=datetime.create(past);// get the current timestamp of the pastsetTimeout(function(){varpastTime=pastDateTime.getTime();// this would be 1420038000000console.log(pastNow);// this would be 2015-01-01 00:00:00console.log(newDate(1420038000000));},1000);

API

.setPeriod(periodNames [array])

Replaces the default period names (AM and PM).

datetime.setPeriod([ 'Ante Meridiem', 'Post Meridiem' ]);

.setWeekNames(listOfWeekNames [array])

Replaces the default week names with custom names.

NOTE you may have nulls in your custom week name array to keep some of the default names:

datetime.setWeekNames([
'My Custom Monday',
// keep the default name
null,
...
]);

.setShortWeekNames(listOfShortWeekNames [array])

NOTE you may have nulls in your custom name array to keep some of the default names:

datetime.setShortWeekNames([
'My Custom Name',
// keep the default name
null,
...
]);

.setMonthNames(listOfMonthNames [array])

NOTE you may have nulls in your custom name array to keep some of the default names:

datetime.setMonthNames([
'My Custom Name',
// keep the default name
null,
...
]);

.setShortMonthNames(listOfShortMonthNames [array])

NOTE you may have nulls in your custom name array to keep some of the default names:

datetime.setShortMonthNames([
'My Custom Name',
// keep the default name
null,
...
]);

.create(time [*mix], defaultFormat [*string])

Returns an instance of DateTime object.

time can be a YYYY-MM-DD HH:MM:SS style string, javascript Date object, or timestamp such as Date.now().

Example:

vardatetime=require('node-datetime');vardt=datetime.create();varformatted=dt.format('m/d/Y H:M:S');// e.g. 04/28/2015 21:13:09

.setOffsetInDays(offsetDays [number])

Sets a shared offset in days.

If this is set, all instances of DateTime object will have the given offset in days.

This can be individually overridden.

.setOffsetInHourss(offsetHours [number])

Sets a shared offset in hours.

If this is set, all instances of DateTime object will have the given offset in hours.

This can be individually overridden.

.setDefaultFormat(defaultFormat [string])

Sets a shared default format.

If this is set, all instances of DateTime object will have the given format as default.

This can be individually overridden.

DateTime Object

Methods

.format(format [*string])

Returns a formatted date time string.

If default format is set and the format string is not passed to .format(), default format will be used.

Example With Format:

vardatetime=require('node-datetime');vardt=datetime.create('2015-04-30 09:52:00');varformattedDate=dt.format('m/d/y H:M');console.log(formattedDate);// 04/30/15 09:52

Example With Default Format:

vardatetime=require('node-datetime');vardt=datetime.create('2015-04-30 14:30:00','Y/m/d H:I');varformattedDate=dt.format();console.log(formattedDate);// 2015/04/30 02:30

Formatting rules

Format	Meaning
y	The last 2 digit of the year
Y	Year
m	Month with leading 0
n	Shortened name of a month
f	Full name of a month
d	Date with leading 0
D	Formatted date (1th, 2nd, 3rd, 4th...)
H	Hours with leading 0 in 24 hours format
I	Hours with leading 0 in 12 hours format
M	Minutes with leading 0
S	Seconds with leading 0
N	Milliseconds with leading 0
p	Period (AM or PM)
w	Shortened name of the week day
W	Full name of the week day

.offsetInDays(offset [number])

Offests the date.

NOTE: By giving more than 30 days or 365 days, it can exceed current year or month.

Example:

var datetime = require('node-datetime');
var dt = datetime.create();
// 1 day in the future
dt.offsetInDays(1);

var datetime = require('node-datetime');
var dt = datetime.create();
// 1 day in the past
dt.offsetInDays(-1);

.offsetInHours(offset [number])

Offests the hours.

NOTE: By giving more than 24 hours, it can exceed current date and so on.

Example:

var datetime = require('node-datetime');
var dt = datetime.create();
// 1 hour in the future
dt.offsetInHours(1);

var datetime = require('node-datetime');
var dt = datetime.create();
// 1 hour in the past
dt.offsetInHours(-1);

.now()

Returns a unix timestamp in milliseconds.

NOTE: The method automatically calculates the offset time.

.getTime()

Returns a fixed unix timestamp in milliseconds.

.epoch()

Returns a fixed unix timestamp in seconds.

.getDatesInRange(date [mix])

Returns an array of DateTime objects within the given range in days.

NOTE: date can be either DateTime or Date.

Example:

vardatetime=require('node-datetime');vardt=datetime.create('2015-01-01');vardates=dt.getDatesInRange(datetime.create('2015-01-10'));// dates = [ ... ];// dates will contain instances of DateTime object from 2015-01-01 to 2015-01-10

.geHoursInRange(date [mix])

Returns an array of DateTime objects within the given range in hours.

NOTE: date can be either DateTime or Date.

Example:

vardatetime=require('node-datetime');vardt=datetime.create('2015-01-01 00:00:00');vardates=dt.getDatesInRange(datetime.create('2015-01-02 00:00:00'));// dates = [ ... ];// dates will contain instances of DateTime object from 2015-01-01 00:00:00 to 2015-01-02 00:00:00

.createTimedNumber(conf [object])

Returns an instance of TimedNumber that changes its value over time.

conf:

{"max": 10,// maximum value"min": 0,// minimum value"interval": 60000,// value increments/decrements every "interval""step": 1,// at every interval, the value increments/decrements by "step""type": "inc",// either "inc" for incrementing type of "dec" for decrementing type"init": 10// initial value to start with"lastUpdate": null// an optional time stamp to control the last update state}

Usage Example:

TimedNumber that recovers its value by 1 every 1 second.

vardatetime=require('node-datetime');varconfig={max: 10,min: 0,interval: 1000,step: 1,type: 'inc',init: 0};vartd=datetime.createTimedNumber(config);setTimeout(function(){varvalue=td.getValue();// value should be 1},1000);

vardatetime=require('node-datetime');varconfig={max: 10,min: 0,interval: 1000,step: 1,type: 'inc',init: 10};vartd=datetime.createTimedNumber(config);td.dec(5);setTimeout(function(){varvalue=td.getValue();// value should be 6},1000);

TimedNumber Class

.getValue()

Returns the current value.

.inc(incrementValue [number])

Increments the current value by incrementValue.

Returns true if successful.

.dec(decrementValue [number])

Decrements the current value by decrementValue.

Returns true if successful.

.reset()

Resets the state of TimedNumber object to its initial state.

.getMaxValue()

Returns maximum value.

.getMinValue()

Returns minimum value.

.getInterval()

Returns the interval for every update in milliseconds.

.getStep()

Returns the value of step for every update.

.toObject()

Returns a JSON format of TimedNumber object.

You can reconstruct exact same timed number object from this JSON object.

Example:

vardatetime=require('node-datetime');varconfig={max: 10,min: 0,interval: 1000,step: 1,type: 'inc',init: 10};vartimedNumber=datetime.createTimedNumber(conf);// do thingstimedNumber.dec(3);// store it in database as JSONvarjson=timedNumber.toOjbect();// read json back from the database and reconstruct timed number objectvartimedNumber2=datetime.createTimedNumber(json);// timedNumber2 will have the same state as timedNumber

.createTimedState(conf)

Returns an instance of TimedState object that changes its state over time.

conf:

{
states: [ 'A', 'B', 'C' ... ] // an array of states to represent the order of states
interval: 1000 // interval in milliseconds for the state to change
init: 0 // initial position of the states array
loop: false // if true, the states will loop }

Example:

vardatetime=require('node-datetime');varconf={states: ['one','two','three'],interval: 1000,init: 0,loop: false};// create the TimedState object that changes its state every 1 second from 'one' and it stops at 'three'varts=datetime.createTimedState(conf);

TimedState Class

.getState()

Returns the current state.

.forward(position [*number])

Forces the state to move forward by the given number. If no position is given, it will move forward by one.

.backward(position [*number])

Forces the state to move backward by the given number, If no position is given, it will move backward by one.

.getStates()

Returns the state array.

.getInterval()

Returns the interval in milliseconds

.reset()

Resets the state to its initial state.

.toObject()

Returns a JSON format of TimedState object.

You can reconstruct exact same timed number object from this JSON object.