{"id":16783020,"url":"https://github.com/voltrue2/node-datetime","last_synced_at":"2025-09-10T23:43:23.150Z","repository":{"id":31168893,"uuid":"34729096","full_name":"voltrue2/node-datetime","owner":"voltrue2","description":"An extended Date object for javascript.  It handles offsets by days and hours and formatting etc.","archived":false,"fork":false,"pushed_at":"2021-03-24T21:15:50.000Z","size":46,"stargazers_count":7,"open_issues_count":1,"forks_count":5,"subscribers_count":4,"default_branch":"develop","last_synced_at":"2025-08-14T21:39:57.697Z","etag":null,"topics":["datetime","javascript","timestamp"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/voltrue2.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-04-28T12:28:25.000Z","updated_at":"2023-08-22T19:27:47.000Z","dependencies_parsed_at":"2022-09-08T15:21:46.113Z","dependency_job_id":null,"html_url":"https://github.com/voltrue2/node-datetime","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/voltrue2/node-datetime","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voltrue2%2Fnode-datetime","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voltrue2%2Fnode-datetime/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voltrue2%2Fnode-datetime/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voltrue2%2Fnode-datetime/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/voltrue2","download_url":"https://codeload.github.com/voltrue2/node-datetime/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voltrue2%2Fnode-datetime/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274549295,"owners_count":25306358,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-10T02:00:12.551Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["datetime","javascript","timestamp"],"created_at":"2024-10-13T07:48:46.829Z","updated_at":"2025-09-10T23:43:23.097Z","avatar_url":"https://github.com/voltrue2.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# node-datetime\n\n©Nobuyori Takahashi \u003c \u003cvoltrue2@yahoo.com\u003e \u003e\n\nAn extended Date object for javascript.\n\n1. Handles offests by days and hours.\n\n2. Built-in formatting function.\n\n3. Time based value calculation.\n\n## Installation\n\n# Installation via npm\n\n`npm install node-datetime`\n\n# Use node-datetime in browser\n\nIn order to use `node-datetime` in browser, you will need to load the script as shown below:\n\nThe browser script file is located at: `node-datetime/release/browser/node_datetime.js`.\n\n## Add the script to your HTML\n\nThe \"src\" path must be according to your server setup.\n\n```html\n\u003cscript type=\"text/javascript\" src=\"./node_datetime.js\"\u003e\u003c/script\u003e\n```\n\n## window.DateTime\n\nWhen you add the script to your HTML page correctly, `window.DateTime` object will be accessible as a global object.\n\nThe object is the equivalent of `var datetime = require('node-datetime');` in node.js version.\n\n***\n\n# Backward Compatibilty Break Warning\n\nFrom version `1.0.0`, certain APIs have changed their behavior.\n\n### .now()\n\nThis API used to return a fixed timestamp in milliseconds meaning that it was returning the timestamp of the instance of `datetime`.\n\nNow `.now()` returns a calculated current timestamp in milliseconds with time offset if given.\n\n**Example**:\n\nYou could get current time of the past, for exmaple.\n\n```javascript\nvar datetime = require('node-datetime');\nvar past = '2015-01-01 00:00:00';\nvar pastDateTime = datetime.create(past);\n// get the current timestamp of the past\nsetTimeout(function () {\n\tvar pastNow = pastDateTime.now();\n\t// this would be 1420038010000\n\tconsole.log(pastNow);\n\t// this would be 2015-01-01 00:00:10\n\tconsole.log(new Date(1420038010000));\n}, 1000);\n```\n\n### .getTime()\n\nThis API is the same as former `.now()`. It returns the timestamp of `datetime` object.\n\n**Example**:\n\n\n```javascript\nvar datetime = require('node-datetime');\nvar past = '2015-01-01 00:00:00';\nvar pastDateTime = datetime.create(past);\n// get the current timestamp of the past\nsetTimeout(function () {\n        var pastTime = pastDateTime.getTime();\n        // this would be 1420038000000\n        console.log(pastNow);\n        // this would be 2015-01-01 00:00:00\n        console.log(new Date(1420038000000));\n}, 1000);\n```\n\n## API\n\n### .setPeriod(periodNames [array])\n\nReplaces the default period names (AM and PM).\n\n```\ndatetime.setPeriod([ 'Ante Meridiem', 'Post Meridiem' ]);\n```\n\n### .setWeekNames(listOfWeekNames [array])\n\nReplaces the default week names with custom names.\n\n**NOTE** you may have nulls in your custom week name array to keep some of the default names:\n\n```\ndatetime.setWeekNames([\n\t'My Custom Monday',\n\t// keep the default name\n\tnull,\n\t...\n]);\n```\n\n### .setShortWeekNames(listOfShortWeekNames [array])\n\n**NOTE** you may have nulls in your custom name array to keep some of the default names:\n\n```\ndatetime.setShortWeekNames([\n\t'My Custom Name',\n\t// keep the default name\n\tnull,\n\t...\n]);\n```\n\n### .setMonthNames(listOfMonthNames [array])\n\n**NOTE** you may have nulls in your custom name array to keep some of the default names:\n\n```\ndatetime.setMonthNames([\n\t'My Custom Name',\n\t// keep the default name\n\tnull,\n\t...\n]);\n```\n\n### .setShortMonthNames(listOfShortMonthNames [array])\n\n**NOTE** you may have nulls in your custom name array to keep some of the default names:\n\n```\ndatetime.setShortMonthNames([\n\t'My Custom Name',\n\t// keep the default name\n\tnull,\n\t...\n]);\n```\n\n#### .create(time [*mix], defaultFormat [*string])\n\nReturns an instance of DateTime object.\n\n`time` can be a `YYYY-MM-DD HH:MM:SS` style string, javascript Date object, or timestamp such as `Date.now()`.\n\nExample:\n\n```javascript\nvar datetime = require('node-datetime');\nvar dt = datetime.create();\nvar formatted = dt.format('m/d/Y H:M:S');\n// e.g. 04/28/2015 21:13:09\n```\n\n#### .setOffsetInDays(offsetDays [number])\n\nSets a shared offset in days.\n\nIf this is set, all instances of DateTime object will have the given offset in days.\n\nThis can be individually overridden.\n\n#### .setOffsetInHourss(offsetHours [number])\n\nSets a shared offset in hours.\n\nIf this is set, all instances of DateTime object will have the given offset in hours.\n\nThis can be individually overridden.\n\n#### .setDefaultFormat(defaultFormat [string])\n\nSets a shared default format.\n\nIf this is set, all instances of DateTime object will have the given format as default.\n\nThis can be individually overridden.\n\n## DateTime Object\n\n### Methods\n\n#### .format(format [*string])\n\nReturns a formatted date time string.\n\nIf default format is set and the format string is not passed to `.format()`, default format will be used.\n\nExample With Format:\n\n```javascript\nvar datetime = require('node-datetime');\nvar dt = datetime.create('2015-04-30 09:52:00');\nvar formattedDate = dt.format('m/d/y H:M');\nconsole.log(formattedDate);\n// 04/30/15 09:52\n```\n\nExample With Default Format:\n\n```javascript\nvar datetime = require('node-datetime');\nvar dt = datetime.create('2015-04-30 14:30:00', 'Y/m/d H:I');\nvar formattedDate = dt.format();\nconsole.log(formattedDate);\n// 2015/04/30 02:30\n```\n\n#### Formatting rules\n\n|Format|Meaning|\n|---|---|\n|y|The last 2 digit of the year|\n|Y|Year|\n|m|Month with leading 0|\n|n|Shortened name of a month|\n|f|Full name of a month|\n|d|Date with leading 0|\n|D|Formatted date (1th, 2nd, 3rd, 4th...)|\n|H|Hours with leading 0 in 24 hours format|\n|I|Hours with leading 0 in 12 hours format|\n|M|Minutes with leading 0|\n|S|Seconds with leading 0|\n|N|Milliseconds with leading 0|\n|p|Period (AM or PM)|\n|w|Shortened name of the week day|\n|W|Full name of the week day|\n\n#### .offsetInDays(offset [number])\n\nOffests the date.\n\n**NOTE**: By giving more than 30 days or 365 days, it can exceed current year or month.\n\nExample:\n\n```javascripript\nvar datetime = require('node-datetime');\nvar dt = datetime.create();\n// 1 day in the future\ndt.offsetInDays(1);\n```\n\n```javascripript\nvar datetime = require('node-datetime');\nvar dt = datetime.create();\n// 1 day in the past\ndt.offsetInDays(-1);\n```\n\n#### .offsetInHours(offset [number])\n\nOffests the hours.\n\n**NOTE**: By giving more than 24 hours, it can exceed current date and so on.\n\nExample:\n\n```javascripript\nvar datetime = require('node-datetime');\nvar dt = datetime.create();\n// 1 hour in the future\ndt.offsetInHours(1);\n```\n\n```javascripript\nvar datetime = require('node-datetime');\nvar dt = datetime.create();\n// 1 hour in the past\ndt.offsetInHours(-1);\n```\n\n#### .now()\n\nReturns a unix timestamp in milliseconds.\n\n**NOTE:** The method automatically calculates the offset time.\n\n#### .getTime()\n\nReturns a fixed unix timestamp in milliseconds.\n\n#### .epoch()\n\nReturns a fixed unix timestamp in seconds.\n\n#### .getDatesInRange(date [mix])\n\nReturns an array of DateTime objects within the given range in days.\n\n**NOTE**: `date` can be either DateTime or Date.\n\nExample:\n\n```javascript\nvar datetime = require('node-datetime');\nvar dt = datetime.create('2015-01-01');\nvar dates = dt.getDatesInRange(datetime.create('2015-01-10'));\n// dates = [ ... ];\n// dates will contain instances of DateTime object from 2015-01-01 to 2015-01-10\n````\n\n#### .geHoursInRange(date [mix])\n\nReturns an array of DateTime objects within the given range in hours.\n\n**NOTE**: `date` can be either DateTime or Date.\n\nExample:\n\n```javascript\nvar datetime = require('node-datetime');\nvar dt = datetime.create('2015-01-01 00:00:00');\nvar dates = dt.getDatesInRange(datetime.create('2015-01-02 00:00:00'));\n// dates = [ ... ];\n// dates will contain instances of DateTime object from 2015-01-01 00:00:00 to 2015-01-02 00:00:00\n````\n\n#### .createTimedNumber(conf [object])\n\nReturns an instance of TimedNumber that changes its value over time.\n\nconf:\n\n```javascript\n{\n    \"max\": 10, // maximum value\n    \"min\": 0, // minimum value\n    \"interval\": 60000, // value increments/decrements every \"interval\"\n    \"step\": 1, // at every interval, the value increments/decrements by \"step\"\n    \"type\": \"inc\", // either \"inc\" for incrementing type of \"dec\" for decrementing type\n    \"init\": 10 // initial value to start with\n    \"lastUpdate\": null // an optional time stamp to control the last update state\n}\n```\n\nUsage Example:\n\nTimedNumber that recovers its value by 1 every 1 second.\n\n```javascript\nvar datetime = require('node-datetime');\nvar config = {\n        max: 10,\n        min: 0,\n        interval: 1000,\n        step: 1,\n        type: 'inc',\n        init: 0\n};\nvar td = datetime.createTimedNumber(config);\nsetTimeout(function () {\n        var value = td.getValue();\n        // value should be 1\n}, 1000);\n```\n\n```javascript\nvar datetime = require('node-datetime');\nvar config = {\n        max: 10,\n        min: 0,\n        interval: 1000,\n        step: 1,\n        type: 'inc',\n        init: 10\n};\nvar td = datetime.createTimedNumber(config);\ntd.dec(5);\nsetTimeout(function () {\n        var value = td.getValue();\n        // value should be 6\n}, 1000);\n```\n\n### TimedNumber Class\n\n#### .getValue()\n\nReturns the current value.\n\n#### .inc(incrementValue [number])\n\nIncrements the current value by incrementValue.\n\nReturns `true` if successful.\n\n#### .dec(decrementValue [number])\n\nDecrements the current value by decrementValue.\n\nReturns `true` if successful.\n\n#### .reset()\n\nResets the state of `TimedNumber` object to its initial state.\n\n#### .getMaxValue()\n\nReturns maximum value.\n\n#### .getMinValue()\n\nReturns minimum value.\n\n#### .getInterval()\n\nReturns the interval for every update in milliseconds.\n\n#### .getStep()\n\nReturns the value of step for every update.\n\n#### .toObject()\n\nReturns a JSON format of `TimedNumber` object.\n\nYou can reconstruct exact same timed number object from this JSON object.\n\nExample:\n\n```javascript\nvar datetime = require('node-datetime');\nvar config = {\n        max: 10,\n        min: 0,\n        interval: 1000,\n        step: 1,\n        type: 'inc',\n        init: 10\n};\nvar timedNumber = datetime.createTimedNumber(conf);\n// do things\ntimedNumber.dec(3);\n// store it in database as JSON\nvar json = timedNumber.toOjbect();\n// read json back from the database and reconstruct timed number object\nvar timedNumber2 = datetime.createTimedNumber(json);\n// timedNumber2 will have the same state as timedNumber\n```\n\n### .createTimedState(conf)\n\nReturns an instance of TimedState object that changes its state over time.\n\nconf:\n\n```\n{\n\tstates: [ 'A', 'B', 'C' ... ] // an array of states to represent the order of states\n\tinterval: 1000 // interval in milliseconds for the state to change\n\tinit: 0 // initial position of the states array\n\tloop: false // if true, the states will loop  \n}\n``` \n\nExample:\n\n```javascript\nvar datetime = require('node-datetime');\nvar conf = {\n\tstates: [ 'one', 'two', 'three' ],\n\tinterval: 1000,\n\tinit: 0,\n\tloop: false\n};\n// create the TimedState object  that changes its state every 1 second from 'one' and it stops at 'three'\nvar ts = datetime.createTimedState(conf);\n```\n\n### TimedState Class\n\n#### .getState()\n\nReturns the current state.\n\n#### .forward(position [*number])\n\nForces the state to move forward by the given number. If no position is given, it will move forward by one.\n\n#### .backward(position [*number])\n\nForces the state to move backward by the given number, If no position is given, it will move backward by one.\n\n#### .getStates()\n\nReturns the state array.\n\n#### .getInterval()\n\nReturns the interval in milliseconds\n\n#### .reset()\n\nResets the state to its initial state.\n\n#### .toObject()\n\nReturns a JSON format of `TimedState` object.\n\nYou can reconstruct exact same timed number object from this JSON object.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoltrue2%2Fnode-datetime","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvoltrue2%2Fnode-datetime","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoltrue2%2Fnode-datetime/lists"}