{"id":48237490,"url":"https://github.com/fezcode/homo-sapiens-time","last_synced_at":"2026-04-04T20:07:50.639Z","repository":{"id":57266417,"uuid":"460631254","full_name":"fezcode/homo-sapiens-time","owner":"fezcode","description":"A simple time utility.","archived":false,"fork":false,"pushed_at":"2022-02-25T22:55:48.000Z","size":82,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-09T07:59:07.369Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/fezcode.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2022-02-17T22:38:09.000Z","updated_at":"2022-09-05T19:04:41.000Z","dependencies_parsed_at":"2022-08-25T03:41:01.738Z","dependency_job_id":null,"html_url":"https://github.com/fezcode/homo-sapiens-time","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/fezcode/homo-sapiens-time","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fezcode%2Fhomo-sapiens-time","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fezcode%2Fhomo-sapiens-time/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fezcode%2Fhomo-sapiens-time/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fezcode%2Fhomo-sapiens-time/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fezcode","download_url":"https://codeload.github.com/fezcode/homo-sapiens-time/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fezcode%2Fhomo-sapiens-time/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31411904,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T19:29:44.979Z","status":"ssl_error","status_checked_at":"2026-04-04T19:29:11.535Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2026-04-04T20:07:50.172Z","updated_at":"2026-04-04T20:07:50.634Z","avatar_url":"https://github.com/fezcode.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Homo Sapiens Time\n\nA simple time utility for Node.js\n\nHuman-style time descriptions to milliseconds and vice versa.\n\n_Quite a Simple One_\n\n## Installation\n```bash\nnpm install homo-sapiens-time\n#or\nyarn add homo-sapiens-time\n```\n\n## Usage\n#### Node\n```js\nconst hst = require(\"homo-sapiens-time\")\n```\n#### HTML/JS\n```html\n\u003cscript type=\"text/javascript\" src=\"homo-sapiens-time.js\"\u003e \u003c/script\u003e\n\u003cdiv id=\"message\"\u003e \u003c/div\u003e\n\u003cscript\u003e \n    var x = msToTimeString(31557601000, {auto: false, units: ['seconds', 'year'], sortUnits: true}); \n    document.getElementById(\"message\").innerHTML=x;\n\u003c/script\u003e\n```\n\n## Description\nThere are three main functions.\n\n- `msToTimeString`\n- `timeStringToMs`\n- `impreciseDurationAddedToNow`\n\nDefined time units are not as precise as calendar. \n| Unit          | Milliseconds | Equivalent To |\n|---------------|--------------|---------------|\n| 1 year        | 31557600000  | 365.25 days   |     \n| 1 month       | 2629800000   | 30.4375 days  |      \n| 1 week        | 604800000    | 7 days        |     \n| 1 day         | 86400000     | 24 hours      |     \n| 1 hour        | 3600000      | 60 minutes    |    \n| 1 minute      | 60000        | 60 seconds    |     \n| 1 seconds     | 1000         | 1000 ms       |     \n| 1 millisecond | 1            | 1 ms          |  \n\n## Time String Format\nA single **time part** consists of the following format:\n- Positive or Negative Integer\n- Time Unit\n\nThere can only be one or zero spaces between each part.\n**Time part** can repeat as much as needed.\n\nAll available time units are: \n\n| Plural        | Singular     | Short | Maps To|\n|---------------|--------------|-------|:------:|\n| years         | year         | y     | 'y'    |     \n| months        | month        | mo    | 'mo'   |      \n| weeks         | week         | w     | 'w'    |     \n| days          | day          | d     | 'd'    |     \n| hours         | hour         | h     | 'h'    |    \n| minutes       | minute       | m     | 'm'    |     \n| seconds       | second       | s     | 's'    |     \n| milliseconds  | millisecond  | ms    | 'ms'   |     \n\nPlural, singular or short version of unit doesn't affect calculation,\nit just affects printed text. Integer value is not checked for plural or singular units either.\n\n### Example\n\n- \"1year\" = \"1 year\" = \"1 y\"\n- \"2 year 3 months\"\n- \"31557601000 milliseconds\"\n- \"1year -6 month\" = \"6 months\"\n\n-----------------------\n\n## 1. msToTimeString\n\n### Summary\nThis function takes `ms` and converts it to string that consists of given units.\n\nThis method has FIFO execution for `units` which means order of units matter.\nFor example, if `ms` is given as the first value of `units` array then result will be same as `ms` parameter's value since `ms` in `units` will consume all value.\n\nThis function will detect any unit type typos given and will suggestions. For example:\n`msToTimeString(31557601000, {auto: false, units: ['seconds', 'yeer']})` will produce\n```text\nError! Given unit `yeer` is not valid.\n           Did you mean `year`?\n```\nString similarity function is taken from [David from StackOverflow](https://stackoverflow.com/a/36566052).\nThanks David. 👍\n\n### Parameters\n\n##### 1.1 `ms`\nNumber containing time in milliseconds.\n\n##### 1.2 `opts`\n```JS\nopts = {\n    auto: boolean,\n    units: array of string,\n    showEmpty: boolean,\n    sortUnits: boolean\n}\n```\n##### 1.2.1 `opts.auto` \n\nwhen set to `true` units will be overwritten as `['year','month','week','day','hour','minute','seconds','ms']`\n\n##### 1.2.2 `opts.units`\nany valid set of time units. Following are the available units:\n```JS\nconst units = {\n    years : 'y',\n    year : 'y',\n    y : 'y',\n\n    months : 'mo',\n    month : 'mo',\n    mo : 'mo',\n\n    weeks: 'w',\n    week: 'w',\n    w: 'w',\n\n    days: 'd',\n    day: 'd',\n    d: 'd',\n\n    hours: 'h',\n    hour: 'h',\n    h: 'h',\n\n    minutes: 'm',\n    minute: 'm',\n    m: 'm',\n\n    seconds : 's',\n    second : 's',\n    s : 's',\n\n    milliseconds : 'ms',\n    millisecond : 'ms',\n    ms : 'ms'\n}\n```\n\u003e Default value is `['year','month','week','day','hour','minute','second','ms']` if `auto` is `true` else `['hour','minute','second']`.\n\n##### 1.2.3 `opts.showEmpty`\nwhen set to `true`, if a unit with no value exists in the result, it will be written regardless. \n\n\u003e Default value is `false`.\n\n##### 1.2.4 `opts.sortUnits`\nSince order of `opts.units` matters, you can sort units to make longer time units (like year being longer than month) to have higher priority.\nPriority: `y \u003e mo \u003e w \u003e d \u003e h \u003e m \u003e s \u003e ms`\nUnits with higher priority will be closer to beginning of array.\n\n\u003e Default value is `false`.\n\n##### Return\nReturns time string in **Time String Format** or `null` if any error occurred.\n\n#### Examples\n```JS\nmsToTimeString(31557601000, {auto: false, units: ['seconds', 'year'], sortUnits: true}) == '1 year 1 seconds'\nmsToTimeString(31557601001, {auto : true, units: [ 'year', 'month' ], showEmpty: false}) == '1 year 1 seconds 1 ms'\nmsToTimeString(74580249002, {auto: true}) == '2 year 4 month 1 week 3 day 22 hour 44 minute 9 second 2 ms'\n\n```\n\n## 2. timeStringToMs\n### Summary\nTakes a time string similar to ones produced in `msToTimeString` and converts it to milliseconds.\n\n### Parameters\n\n##### 1. `str`:\nString containing time in **Time String Format**.\n\n##### Return\nReturns ms converted from `str`.\n\n#### Examples\n```JS\ntimeStringToMs(\"1 year -6 month\") == timeStringToMs(\"6 month\")\ntimeStringToMs(\"2 years 4 months 10 days 22 hours 44 minutes 9 seconds 2 ms\") == 74580249002\ntimeStringToMs(\"1 year 1 month 1 week 1 day 1 hour -1 hour -1 day -1mo -1y\") == timeStringToMs(\"1 week\")\ntimeStringToMs(\"1 week\") == timeStringToMs(\"7 days\")\n```\n\n## 3. impreciseDurationAddedToNow\n\n### Summary\n\nThis method adds given time string `str` to `Date.now()` value.\nTime string must be in **Time String Format**.\n\nInternally calls `timeStringToMs` to convert `str` to ms.\n\n### Parameters\n\n##### 1. `str`:\nString containing time in **Time String Format**.\n\n\n##### Return\nMillisecond value of `Date.now() + timeStringToMs(str)`.\n\n## Notes\n\u003e This library is perfect for durations. Since it is not precise I highly **recommend being careful** about using\n\u003e it for precise calendar operations.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffezcode%2Fhomo-sapiens-time","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffezcode%2Fhomo-sapiens-time","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffezcode%2Fhomo-sapiens-time/lists"}