{"id":15388916,"url":"https://github.com/killercodemonkey/datetime-periods","last_synced_at":"2025-10-25T04:37:23.464Z","repository":{"id":34291628,"uuid":"174738691","full_name":"KillerCodeMonkey/datetime-periods","owner":"KillerCodeMonkey","description":"Generates a valid list of years down to seconds for a date and min/max date","archived":false,"fork":false,"pushed_at":"2025-03-25T13:04:04.000Z","size":1535,"stargazers_count":2,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-25T14:21:59.751Z","etag":null,"topics":["browser","dates","datetime","generator","javascript","node","nodejs","periods","picker","range","validation"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KillerCodeMonkey.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"custom":["https://www.paypal.me/bengtler","https://www.buymeacoffee.com/bengtler"]}},"created_at":"2019-03-09T19:43:25.000Z","updated_at":"2025-03-25T13:02:13.000Z","dependencies_parsed_at":"2024-11-08T12:03:25.604Z","dependency_job_id":"fa4036ed-6fdd-4f04-a3a6-b4fa8cbe18f2","html_url":"https://github.com/KillerCodeMonkey/datetime-periods","commit_stats":{"total_commits":207,"total_committers":4,"mean_commits":51.75,"dds":"0.33333333333333337","last_synced_commit":"009bf241595ff9edf4b8ee8534437975175e70fe"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KillerCodeMonkey%2Fdatetime-periods","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KillerCodeMonkey%2Fdatetime-periods/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KillerCodeMonkey%2Fdatetime-periods/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KillerCodeMonkey%2Fdatetime-periods/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KillerCodeMonkey","download_url":"https://codeload.github.com/KillerCodeMonkey/datetime-periods/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249128905,"owners_count":21217241,"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","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":["browser","dates","datetime","generator","javascript","node","nodejs","periods","picker","range","validation"],"created_at":"2024-10-01T14:58:35.927Z","updated_at":"2025-10-25T04:37:18.424Z","avatar_url":"https://github.com/KillerCodeMonkey.png","language":"TypeScript","readme":"# datetime-periods\r\n[![Build Status](https://github.com/KillerCodeMonkey/datetime-periods/workflows/CI/badge.svg)](https://github.com/KillerCodeMonkey/datetime-periods/actions/)\r\n\r\nGet a valid list of years down to seconds for a date and min and max date.\r\n\r\nYou ever wanted to create a simple date time picker or wanted to show the user available dates or only the days?\r\n\r\nIt is a zero dependecy lib for browser and node environments.\r\n\r\n## Donate/Support\r\n\r\nIf you like my work, feel free to support it. Donations to the project are always welcomed :)\r\n\r\nPayPal: [PayPal.Me/bengtler](https://paypal.me/bengtler)\r\n\r\n\u003ca href=\"https://www.buymeacoffee.com/bengtler\" target=\"_blank\"\u003e\u003cimg src=\"https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png\" alt=\"Buy Me A Coffee\" style=\"height: auto !important;width: auto !important;\" \u003e\u003c/a\u003e\r\n\r\n## Installation\r\n\r\n-   `npm install datetime-periods`\r\n-   `yarn add datetime-periods`\r\n\r\n## Usage\r\n\r\n### Script tag\r\n\r\nIf you want to use datetime-periods via script tag, you should use the `datetime-periods.umd.js`. After the script is loaded you can access the methods through the global `datetimePeriods`.\r\n\r\n```html\r\n\u003chtml\u003e\r\n  \u003chead\u003e\r\n    \u003cscript src=\"../lib/datetime-periods.umd.js\"\u003e\u003c/script\u003e\r\n    \u003cscript\u003e\r\n      // functions are stored globally on the window object\r\n      console.log('window.datetimePeriods:', window.datetimePeriods)\r\n    \u003c/script\u003e\r\n  \u003c/head\u003e\r\n  \u003cbody\u003e\r\n  \u003c/body\u003e\r\n\u003c/html\u003e\r\n```\r\n\r\n### ESModules or Typescript\r\n\r\nJust import the methods you need from the package.\r\n\r\n```typescript\r\nimport { getDateTimeObject } from 'datetime-periods'\r\nimport * as dateTimePeriods from 'datetime-periods'\r\n\r\n```\r\n\r\n### Node and require\r\n\r\nJust `require` the methods you need from the package.\r\n\r\n```typescript\r\nconst getDateTimeObject = require('datetime-periods').getDateTimeObject\r\nconst dateTimePeriods = require('datetime-periods')\r\n```\r\n\r\n### Example\r\n\r\nSome simple and easy to use examples can be found in the `example` folder in the repo.\r\n\r\nThere is also a plain JavaScript [example page](https://killercodemonkey.github.io/datetime-periods/example).\r\n\r\nOr use [RunKit](https://npm.runkit.com/datetime-periods) to try it out!\r\n\r\n## Methods\r\n\r\n### getDateTimeObject(date: Date)\r\n\r\nTransforms a date in an object respresentation.\r\n\r\n**Result value**:\r\n\r\n```typescript\r\n// DateTimeObject interface\r\n{\r\n  year: number\r\n  month: number // (1-12)\r\n  day: number\r\n  hour: number\r\n  minute: number\r\n  second: number\r\n  tzOffset: number\r\n}\r\n```\r\n\r\nExample:\r\n\r\n```typescript\r\nimport { getDateTimeObject } from 'datetime-periods'\r\n\r\nconst dateTimeObject = getDateTimeObject(new Date())\r\n\r\nconsole.log(dateTimeObject)\r\n```\r\n\r\nOutput:\r\n\r\n```json\r\n{\r\n  \"day\": 14,\r\n  \"hour\": 13,​\r\n  \"minute\": 15,\r\n  \"month\": 3​,\r\n  \"second\": 15,\r\n  \"tzOffset\": -60​,\r\n  \"year\": 2019\r\n}\r\n```\r\n\r\n### getDaysInMonth(year: number, month: number)\r\n\r\nReturns the day count of a month and year. The month is based on numbers from 1 (january) to 12 (december).\r\n\r\nExample:\r\n```typescript\r\nimport { getDaysInMonth } from 'datetime-periods'\r\n\r\nconst daysInFebruary2019 = getDaysInMonth(2, 2019)\r\n\r\nconsole.log(daysInFebruary2019)\r\n```\r\nOutput:\r\n```typescript\r\n28\r\n```\r\n\r\n### getDateTimePeriods(value: Date, min: Date (optional), max: Date (optional), needed: NeededPeriods (optional))\r\n\r\nThis method contains the main functionality of the lib. The other methods are only internally used, but maybe someone finds them useful :).\r\n\r\nIt generates a data structure of valid years, months, days, hours, minutes and seconds for a given date and an optional min and max date. In addition to that it returns all the calculation dates as object representation.\r\n\r\nIf only some period values are interesting, it is possible to only retrieve, years, months, ... . Therefore use the `needed` parameter and pass an object of the values you do not need. This periods keys will be an empty array.\r\n\r\n```typescript\r\ngetDateTimePeriods(new Date(), undefined, undefined, {\r\n  days: false\r\n  years: false\r\n})\r\n```\r\n\r\n**Result value**\r\n```typescript\r\n{\r\n  value: DateTimeObject // validated value as object\r\n  originalValue: DateTimeObject // original value as object\r\n  originalValueChanged: boolean // indicator if original has changed\r\n  max: DateTimeObject // max date as object\r\n  min: DateTimeObject // min date as object\r\n  periods: {\r\n    days: number[] // available days\r\n    hours: number[] // available hours\r\n    minutes: number[] // available minutes\r\n    months: number[] // available months\r\n    seconds: number[] // available seconds\r\n    years: number[] // available years\r\n  }\r\n}\r\n```\r\n\r\nExample:\r\n\r\n```typescript\r\nimport { getDateTimePeriods } from 'datetime-periods'\r\n\r\nconst value = new Date()\r\n\r\nconst min = new Date()\r\nmin.setFullYear(value.getFullYear() - 5)\r\n\r\nconst max = new Date()\r\nmax.setFullYear(value.getFullYear() + 5)\r\n\r\nconst result = getDateTimePeriods(value, min, max)\r\n\r\nconsole.log(result)\r\n```\r\n\r\nOutput:\r\n```json\r\n{\r\n  \"value\": {\r\n    \"year\": 2019,\r\n    \"month\": 3,\r\n    \"day\": 14,\r\n    \"hour\": 14,\r\n    \"minute\": 40,\r\n    \"second\": 21,\r\n    \"tzOffset\": -60\r\n  },\r\n  \"originalValue\": {\r\n    \"year\": 2019,\r\n    \"month\": 3,\r\n    \"day\": 14,\r\n    \"hour\": 14,\r\n    \"minute\": 40,\r\n    \"second\": 21,\r\n    \"tzOffset\": -60\r\n  },\r\n  \"originalValueChanged\": false,\r\n  \"max\": {\r\n    \"year\": 2024,\r\n    \"month\": 1,\r\n    \"day\": 1,\r\n    \"hour\": 1,\r\n    \"minute\": 0,\r\n    \"second\": 2,\r\n    \"tzOffset\": -60\r\n  },\r\n  \"min\": {\r\n    \"year\": 2014,\r\n    \"month\": 3,\r\n    \"day\": 14,\r\n    \"hour\": 14,\r\n    \"minute\": 40,\r\n    \"second\": 21,\r\n    \"tzOffset\": -60\r\n  },\r\n  \"periods\": {\r\n    \"days\": [\r\n      1,\r\n      2,\r\n      3,\r\n      ...\r\n      28,\r\n      29,\r\n      30,\r\n      31\r\n    ],\r\n    \"hours\": [\r\n      0,\r\n      1,\r\n      2,\r\n      ...\r\n      21,\r\n      22,\r\n      23\r\n    ],\r\n    \"minutes\": [\r\n      0,\r\n      1,\r\n      2,\r\n      3,\r\n      ...\r\n      56,\r\n      57,\r\n      58,\r\n      59\r\n    ],\r\n    \"months\": [\r\n      1,\r\n      2,\r\n      3,\r\n      ...\r\n      10,\r\n      11,\r\n      12\r\n    ],\r\n    \"seconds\": [\r\n      0,\r\n      1,\r\n      2,\r\n      ...\r\n      57,\r\n      58,\r\n      59\r\n    ],\r\n    \"years\": [\r\n      2014,\r\n      2015,\r\n      2016,\r\n      ...\r\n      2022,\r\n      2023,\r\n      2024\r\n    ]\r\n  }\r\n}\r\n```\r\n\r\n#### Default min and max values\r\n\r\n-   min: `value - 100 years`\r\n-   max: `value + 100 years`\r\n\r\n#### Special cases\r\n\r\nLeading to a `console.warn`!\r\n\r\n-   `min \u003e max`: min and max are fall back to the default\r\n-   `value \u003c min`: value is set to min, sets `originalValueChanged` to `true`\r\n-   `value \u003e max`: value is set to max, sets `originalValueChanged` to `true`\r\n","funding_links":["https://www.paypal.me/bengtler","https://www.buymeacoffee.com/bengtler","https://paypal.me/bengtler"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkillercodemonkey%2Fdatetime-periods","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkillercodemonkey%2Fdatetime-periods","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkillercodemonkey%2Fdatetime-periods/lists"}