1 | # node-datetime
|
2 |
|
3 | ©Nobuyori Takahashi < <voltrue2@yahoo.com> >
|
4 |
|
5 | An extended Date object for javascript.
|
6 |
|
7 | 1. Handles offests by days and hours.
|
8 |
|
9 | 2. Built-in formatting function.
|
10 |
|
11 | 3. Time based value calculation.
|
12 |
|
13 | ## Installation
|
14 |
|
15 | # Installation via npm
|
16 |
|
17 | `npm node-datetime`
|
18 |
|
19 | # Use node-datetime in browser
|
20 |
|
21 | In order to use `node-datetime` in browser, you will need to load the script as shown below:
|
22 |
|
23 | The browser script file is located at: `node-datetime/release/browser/node_datetime.js`.
|
24 |
|
25 | ## Add the script to your HTML
|
26 |
|
27 | The "src" path must be according to your server setup.
|
28 |
|
29 | ```html
|
30 | <script type="text/javascript" src="./node_datetime.js"></script>
|
31 | ```
|
32 |
|
33 | ## window.DateTime
|
34 |
|
35 | When you add the script to your HTML page correctly, `window.DateTime` object will be accessible as a global object.
|
36 |
|
37 | The object is the equivalent of `var datetime = require('node-datetime');` in node.js version.
|
38 |
|
39 | ***
|
40 |
|
41 | # Backward Compatibilty Break Warning
|
42 |
|
43 | From version `1.0.0`, certain APIs have changed their behavior.
|
44 |
|
45 | ### .now()
|
46 |
|
47 | This API used to return a fixed timestamp in milliseconds meaning that it was returning the timestamp of the instance of `datetime`.
|
48 |
|
49 | Now `.now()` returns a calculated current timestamp in milliseconds with time offset if given.
|
50 |
|
51 | **Example**:
|
52 |
|
53 | You could get current time of the past, for exmaple.
|
54 |
|
55 | ```javascript
|
56 | var datetime = require('node-datetime');
|
57 | var past = '2015-01-01 00:00:00';
|
58 | var pastDateTime = datetime.create(past);
|
59 | // get the current timestamp of the past
|
60 | setTimeout(function () {
|
61 | var pastNow = pastDateTime.now();
|
62 | // this would be 1420038010000
|
63 | console.log(pastNow);
|
64 | // this would be 2015-01-01 00:00:10
|
65 | console.log(new Date(1420038010000));
|
66 | }, 1000);
|
67 | ```
|
68 |
|
69 | ### .getTime()
|
70 |
|
71 | This API is the same as former `.now()`. It returns the timestamp of `datetime` object.
|
72 |
|
73 | **Example**:
|
74 |
|
75 |
|
76 | ```javascript
|
77 | var datetime = require('node-datetime');
|
78 | var past = '2015-01-01 00:00:00';
|
79 | var pastDateTime = datetime.create(past);
|
80 | // get the current timestamp of the past
|
81 | setTimeout(function () {
|
82 | var pastTime = pastDateTime.getTime();
|
83 | // this would be 1420038000000
|
84 | console.log(pastNow);
|
85 | // this would be 2015-01-01 00:00:00
|
86 | console.log(new Date(1420038000000));
|
87 | }, 1000);
|
88 | ```
|
89 |
|
90 | ## API
|
91 |
|
92 | ### .setPeriod(periodNames [array])
|
93 |
|
94 | Replaces the default period names (AM and PM).
|
95 |
|
96 | ```
|
97 | datetime.setPeriod([ 'Ante Meridiem', 'Post Meridiem' ]);
|
98 | ```
|
99 |
|
100 | ### .setWeekNames(listOfWeekNames [array])
|
101 |
|
102 | Replaces the default week names with custom names.
|
103 |
|
104 | **NOTE** you may have nulls in your custom week name array to keep some of the default names:
|
105 |
|
106 | ```
|
107 | datetime.setWeekNames([
|
108 | 'My Custom Monday',
|
109 | // keep the default name
|
110 | null,
|
111 | ...
|
112 | ]);
|
113 | ```
|
114 |
|
115 | ### .setShortWeekNames(listOfShortWeekNames [array])
|
116 |
|
117 | **NOTE** you may have nulls in your custom name array to keep some of the default names:
|
118 |
|
119 | ```
|
120 | datetime.setShortWeekNames([
|
121 | 'My Custom Name',
|
122 | // keep the default name
|
123 | null,
|
124 | ...
|
125 | ]);
|
126 | ```
|
127 |
|
128 | ### .setMonthNames(listOfMonthNames [array])
|
129 |
|
130 | **NOTE** you may have nulls in your custom name array to keep some of the default names:
|
131 |
|
132 | ```
|
133 | datetime.setMonthNames([
|
134 | 'My Custom Name',
|
135 | // keep the default name
|
136 | null,
|
137 | ...
|
138 | ]);
|
139 | ```
|
140 |
|
141 | ### .setShortMonthNames(listOfShortMonthNames [array])
|
142 |
|
143 | **NOTE** you may have nulls in your custom name array to keep some of the default names:
|
144 |
|
145 | ```
|
146 | datetime.setShortMonthNames([
|
147 | 'My Custom Name',
|
148 | // keep the default name
|
149 | null,
|
150 | ...
|
151 | ]);
|
152 | ```
|
153 |
|
154 | #### .create(time [*mix], defaultFormat [*string])
|
155 |
|
156 | Returns an instance of DateTime object.
|
157 |
|
158 | `time` can be a `YYYY-MM-DD HH:MM:SS` style string, javascript Date object, or timestamp such as `Date.now()`.
|
159 |
|
160 | Example:
|
161 |
|
162 | ```javascript
|
163 | var datetime = require('node-datetime');
|
164 | var dt = datetime.create();
|
165 | var formatted = dt.format('m/d/Y H:M:S');
|
166 | // e.g. 04/28/2015 21:13:09
|
167 | ```
|
168 |
|
169 | #### .setOffsetInDays(offsetDays [number])
|
170 |
|
171 | Sets a shared offset in days.
|
172 |
|
173 | If this is set, all instances of DateTime object will have the given offset in days.
|
174 |
|
175 | This can be individually overridden.
|
176 |
|
177 | #### .setOffsetInHourss(offsetHours [number])
|
178 |
|
179 | Sets a shared offset in hours.
|
180 |
|
181 | If this is set, all instances of DateTime object will have the given offset in hours.
|
182 |
|
183 | This can be individually overridden.
|
184 |
|
185 | #### .setDefaultFormat(defaultFormat [string])
|
186 |
|
187 | Sets a shared default format.
|
188 |
|
189 | If this is set, all instances of DateTime object will have the given format as default.
|
190 |
|
191 | This can be individually overridden.
|
192 |
|
193 | ## DateTime Object
|
194 |
|
195 | ### Methods
|
196 |
|
197 | #### .format(format [*string])
|
198 |
|
199 | Returns a formatted date time string.
|
200 |
|
201 | If default format is set and the format string is not passed to `.format()`, default format will be used.
|
202 |
|
203 | Example With Format:
|
204 |
|
205 | ```javascript
|
206 | var datetime = require('node-datetime');
|
207 | var dt = datetime.create('2015-04-30 09:52:00');
|
208 | var formattedDate = dt.format('m/d/y H:M');
|
209 | console.log(formattedDate);
|
210 | // 04/30/15 09:52
|
211 | ```
|
212 |
|
213 | Example With Default Format:
|
214 |
|
215 | ```javascript
|
216 | var datetime = require('node-datetime');
|
217 | var dt = datetime.create('2015-04-30 14:30:00', 'Y/m/d H:I');
|
218 | var formattedDate = dt.format();
|
219 | console.log(formattedDate);
|
220 | // 2015/04/30 02:30
|
221 | ```
|
222 |
|
223 | #### Formatting rules
|
224 |
|
225 | |Format|Meaning|
|
226 | |---|---|
|
227 | |y|The last 2 digit of the year|
|
228 | |Y|Year|
|
229 | |m|Month with leading 0|
|
230 | |n|Shortened name of a month|
|
231 | |f|Full name of a month|
|
232 | |d|Date with leading 0|
|
233 | |D|Formatted date (1th, 2nd, 3rd, 4th...)|
|
234 | |H|Hours with leading 0 in 24 hours format|
|
235 | |I|Hours with leading 0 in 12 hours format|
|
236 | |M|Minutes with leading 0|
|
237 | |S|Seconds with leading 0|
|
238 | |N|Milliseconds with leading 0|
|
239 | |p|Period (AM or PM)|
|
240 | |w|Shortened name of the week day|
|
241 | |W|Full name of the week day|
|
242 |
|
243 | #### .offsetInDays(offset [number])
|
244 |
|
245 | Offests the date.
|
246 |
|
247 | **NOTE**: By giving more than 30 days or 365 days, it can exceed current year or month.
|
248 |
|
249 | Example:
|
250 |
|
251 | ```javascripript
|
252 | var datetime = require('node-datetime');
|
253 | var dt = datetime.create();
|
254 | // 1 day in the future
|
255 | dt.offsetInDays(1);
|
256 | ```
|
257 |
|
258 | ```javascripript
|
259 | var datetime = require('node-datetime');
|
260 | var dt = datetime.create();
|
261 | // 1 day in the past
|
262 | dt.offsetInDays(-1);
|
263 | ```
|
264 |
|
265 | #### .offsetInHours(offset [number])
|
266 |
|
267 | Offests the hours.
|
268 |
|
269 | **NOTE**: By giving more than 24 hours, it can exceed current date and so on.
|
270 |
|
271 | Example:
|
272 |
|
273 | ```javascripript
|
274 | var datetime = require('node-datetime');
|
275 | var dt = datetime.create();
|
276 | // 1 hour in the future
|
277 | dt.offsetInHours(1);
|
278 | ```
|
279 |
|
280 | ```javascripript
|
281 | var datetime = require('node-datetime');
|
282 | var dt = datetime.create();
|
283 | // 1 hour in the past
|
284 | dt.offsetInHours(-1);
|
285 | ```
|
286 |
|
287 | #### .now()
|
288 |
|
289 | Returns a unix timestamp in milliseconds.
|
290 |
|
291 | **NOTE:** The method automatically calculates the offset time.
|
292 |
|
293 | #### .getTime()
|
294 |
|
295 | Returns a fixed unix timestamp in milliseconds.
|
296 |
|
297 | #### .epoch()
|
298 |
|
299 | Returns a fixed unix timestamp in seconds.
|
300 |
|
301 | #### .getDatesInRange(date [mix])
|
302 |
|
303 | Returns an array of DateTime objects within the given range in days.
|
304 |
|
305 | **NOTE**: `date` can be either DateTime or Date.
|
306 |
|
307 | Example:
|
308 |
|
309 | ```javascript
|
310 | var datetime = require('node-datetime');
|
311 | var dt = datetime.create('2015-01-01');
|
312 | var dates = dt.getDatesInRange(datetime.create('2015-01-10'));
|
313 | // dates = [ ... ];
|
314 | // dates will contain instances of DateTime object from 2015-01-01 to 2015-01-10
|
315 | ````
|
316 |
|
317 | #### .geHoursInRange(date [mix])
|
318 |
|
319 | Returns an array of DateTime objects within the given range in hours.
|
320 |
|
321 | **NOTE**: `date` can be either DateTime or Date.
|
322 |
|
323 | Example:
|
324 |
|
325 | ```javascript
|
326 | var datetime = require('node-datetime');
|
327 | var dt = datetime.create('2015-01-01 00:00:00');
|
328 | var dates = dt.getDatesInRange(datetime.create('2015-01-02 00:00:00'));
|
329 | // dates = [ ... ];
|
330 | // dates will contain instances of DateTime object from 2015-01-01 00:00:00 to 2015-01-02 00:00:00
|
331 | ````
|
332 |
|
333 | #### .createTimedNumber(conf [object])
|
334 |
|
335 | Returns an instance of TimedNumber that changes its value over time.
|
336 |
|
337 | conf:
|
338 |
|
339 | ```javascript
|
340 | {
|
341 | "max": 10, // maximum value
|
342 | "min": 0, // minimum value
|
343 | "interval": 60000, // value increments/decrements every "interval"
|
344 | "step": 1, // at every interval, the value increments/decrements by "step"
|
345 | "type": "inc", // either "inc" for incrementing type of "dec" for decrementing type
|
346 | "init": 10 // initial value to start with
|
347 | "lastUpdate": null // an optional time stamp to control the last update state
|
348 | }
|
349 | ```
|
350 |
|
351 | Usage Example:
|
352 |
|
353 | TimedNumber that recovers its value by 1 every 1 second.
|
354 |
|
355 | ```javascript
|
356 | var datetime = require('node-datetime');
|
357 | var config = {
|
358 | max: 10,
|
359 | min: 0,
|
360 | interval: 1000,
|
361 | step: 1,
|
362 | type: 'inc',
|
363 | init: 0
|
364 | };
|
365 | var td = datetime.createTimedNumber(config);
|
366 | setTimeout(function () {
|
367 | var value = td.getValue();
|
368 | // value should be 1
|
369 | }, 1000);
|
370 | ```
|
371 |
|
372 | ```javascript
|
373 | var datetime = require('node-datetime');
|
374 | var config = {
|
375 | max: 10,
|
376 | min: 0,
|
377 | interval: 1000,
|
378 | step: 1,
|
379 | type: 'inc',
|
380 | init: 10
|
381 | };
|
382 | var td = datetime.createTimedNumber(config);
|
383 | td.dec(5);
|
384 | setTimeout(function () {
|
385 | var value = td.getValue();
|
386 | // value should be 6
|
387 | }, 1000);
|
388 | ```
|
389 |
|
390 | ### TimedNumber Class
|
391 |
|
392 | #### .getValue()
|
393 |
|
394 | Returns the current value.
|
395 |
|
396 | #### .inc(incrementValue [number])
|
397 |
|
398 | Increments the current value by incrementValue.
|
399 |
|
400 | Returns `true` if successful.
|
401 |
|
402 | #### .dec(decrementValue [number])
|
403 |
|
404 | Decrements the current value by decrementValue.
|
405 |
|
406 | Returns `true` if successful.
|
407 |
|
408 | #### .reset()
|
409 |
|
410 | Resets the state of `TimedNumber` object to its initial state.
|
411 |
|
412 | #### .getMaxValue()
|
413 |
|
414 | Returns maximum value.
|
415 |
|
416 | #### .getMinValue()
|
417 |
|
418 | Returns minimum value.
|
419 |
|
420 | #### .getInterval()
|
421 |
|
422 | Returns the interval for every update in milliseconds.
|
423 |
|
424 | #### .getStep()
|
425 |
|
426 | Returns the value of step for every update.
|
427 |
|
428 | #### .toObject()
|
429 |
|
430 | Returns a JSON format of `TimedNumber` object.
|
431 |
|
432 | You can reconstruct exact same timed number object from this JSON object.
|
433 |
|
434 | Example:
|
435 |
|
436 | ```javascript
|
437 | var datetime = require('node-datetime');
|
438 | var config = {
|
439 | max: 10,
|
440 | min: 0,
|
441 | interval: 1000,
|
442 | step: 1,
|
443 | type: 'inc',
|
444 | init: 10
|
445 | };
|
446 | var timedNumber = datetime.createTimedNumber(conf);
|
447 | // do things
|
448 | timedNumber.dec(3);
|
449 | // store it in database as JSON
|
450 | var json = timedNumber.toOjbect();
|
451 | // read json back from the database and reconstruct timed number object
|
452 | var timedNumber2 = datetime.createTimedNumber(json);
|
453 | // timedNumber2 will have the same state as timedNumber
|
454 | ```
|
455 |
|
456 | ### .createTimedState(conf)
|
457 |
|
458 | Returns an instance of TimedState object that changes its state over time.
|
459 |
|
460 | conf:
|
461 |
|
462 | ```
|
463 | {
|
464 | states: [ 'A', 'B', 'C' ... ] // an array of states to represent the order of states
|
465 | interval: 1000 // interval in milliseconds for the state to change
|
466 | init: 0 // initial position of the states array
|
467 | loop: false // if true, the states will loop
|
468 | }
|
469 | ```
|
470 |
|
471 | Example:
|
472 |
|
473 | ```javascript
|
474 | var datetime = require('node-datetime');
|
475 | var conf = {
|
476 | states: [ 'one', 'two', 'three' ],
|
477 | interval: 1000,
|
478 | init: 0,
|
479 | loop: false
|
480 | };
|
481 | // create the TimedState object that changes its state every 1 second from 'one' and it stops at 'three'
|
482 | var ts = datetime.createTimedState(conf);
|
483 | ```
|
484 |
|
485 | ### TimedState Class
|
486 |
|
487 | #### .getState()
|
488 |
|
489 | Returns the current state.
|
490 |
|
491 | #### .forward(position [*number])
|
492 |
|
493 | Forces the state to move forward by the given number. If no position is given, it will move forward by one.
|
494 |
|
495 | #### .backward(position [*number])
|
496 |
|
497 | Forces the state to move backward by the given number, If no position is given, it will move backward by one.
|
498 |
|
499 | #### .getStates()
|
500 |
|
501 | Returns the state array.
|
502 |
|
503 | #### .getInterval()
|
504 |
|
505 | Returns the interval in milliseconds
|
506 |
|
507 | #### .reset()
|
508 |
|
509 | Resets the state to its initial state.
|
510 |
|
511 | #### .toObject()
|
512 |
|
513 | Returns a JSON format of `TimedState` object.
|
514 |
|
515 | You can reconstruct exact same timed number object from this JSON object.
|
516 |
|