{"id":15314413,"url":"https://github.com/barelyhuman/range","last_synced_at":"2025-04-15T02:13:29.697Z","repository":{"id":43596486,"uuid":"494420963","full_name":"barelyhuman/range","owner":"barelyhuman","description":"availability ranges as a tiny little library","archived":false,"fork":false,"pushed_at":"2023-10-30T05:46:12.000Z","size":183,"stargazers_count":4,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-15T02:13:11.903Z","etag":null,"topics":[],"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/barelyhuman.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":"2022-05-20T10:29:56.000Z","updated_at":"2023-12-29T07:32:33.000Z","dependencies_parsed_at":"2022-09-16T07:50:37.105Z","dependency_job_id":null,"html_url":"https://github.com/barelyhuman/range","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barelyhuman%2Frange","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barelyhuman%2Frange/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barelyhuman%2Frange/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barelyhuman%2Frange/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/barelyhuman","download_url":"https://codeload.github.com/barelyhuman/range/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248991558,"owners_count":21194894,"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":[],"created_at":"2024-10-01T08:45:24.985Z","updated_at":"2025-04-15T02:13:29.666Z","avatar_url":"https://github.com/barelyhuman.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/range.png\" height=\"64\"\u003e\n\u003cp align=\"center\"\u003eavailability ranges as a tiny little library\u003c/p\u003e\n\n[![CI](https://github.com/barelyhuman/range/actions/workflows/ci.yml/badge.svg)](https://github.com/barelyhuman/range/actions/workflows/ci.yml)\n\n**NOTE**: Still adding more and more cases and fixes, feel free to raise issues as you find them\n\nWhen working with date based bookings and orders, it's mostly preferred to have the\nranges and checks on the DB by using a timeseries database or by simplifying query by setting up good database schemas. Still, sometimes you need the date based checks on the application layer as well and this library was built to help with that.\n\nAlso, I wanted to build one.\n\n## Highlights\n\n- Tiny (upto _543B_ minified)\n- Zero Deps\n\n## Who is this for?\n\nThis is for others to build libraries on top of, you can use this as is but it's written in a way that there are close to no abstractions on the prototypes and can be scaled or masked as needed.\n\n## Usage\n\n```sh\n# install\nnpm i @barelyhuman/range\n```\n\n```js\n// esm\nimport { createRange } from '@barelyhuman/range'\n```\n\n```js\n// cjs\nconst { createRange } = require('@barelyhuman/range')\n```\n\n## Example\n\nYou can find more such examples in the [`tests`](/tests/) files.\n\nThe below goes through most of the API\n\n```js\nimport { createRange } from '@barelyhuman/range'\n\n// decide the start and end of the range\nconst start = new Date()\nconst end = new Date()\n\n// start of day\nstart.setHours(0, 0, 0, 0)\n\n// end of the next day\nend.setDate(end.getDate() + 1)\nend.setHours(23, 59, 59, 0)\n\n// create a range object out of it\nconst range = createRange(start, end)\n\n// decide what part of the range to be blocked\nconst blockStart = new Date(start)\nconst blockEnd = new Date(start)\n\nblockStart.setHours(10, 0, 0, 0)\nblockEnd.setHours(18, 0, 0, 0)\n\nrange.beforeChange(({ available }) =\u003e {\n  // triggered before a change is done to the ranges\n  // `available` is the ranges before the change is done\n})\n\nrange.afterChange(({ available, effectedRanges, changed }) =\u003e {\n  // only triggered  **if** a range is changed\n  // `changed` is always true here\n})\n\n// attempt a block on the range\n// should break the original range of today-00:00:00 - tomorrow-23:59:59\n// into 2 parts\n// [today-00:00:00,today-10:00:00] and [today-18:00:00,tomorrow-23:59:59]\nconst blocked = range.block(blockStart, blockEnd)\n\n// `blocked.changed` will be true if a range was changed / effected\nassert.ok(blocked.changed)\n// `blocked.effectedRanges` is an array of the ranges that were effected\nassert.equal(blocked.effectedRanges.length, 1)\n\n// you can be verbose and check if the split up ranges are valid.\nassert.equal(range.available[0].start.valueOf(), start.valueOf())\nassert.equal(range.available[0].end.valueOf(), blockStart.valueOf())\n\nassert.equal(range.available[1].start.valueOf(), blockEnd.valueOf())\nassert.equal(range.available[1].end.valueOf(), end.valueOf())\n```\n\n## Inclusions\n\u003csub\u003e\u003csup\u003esince \u003ccode\u003ev0.1.4\u003c/code\u003e\u003c/sup\u003e\u003c/sub\u003e\n\nThe library allows modifying the comaprison and blocking mechanism by passing in inclusion patterns. \n`[]` include both `start` and `end` into the comparison and also in the blocking\nex:\nIf you have a date range from 12:30AM - 2:30AM it can be represented as so \n\n```md\nRANGE: 00:30:00 - 02:30:00\n```\n\n\nBy default, the inclusivity is to include both start and end so if you create a block for let's say 1:00AM - 1:30AM \nthe ranges would split to \n\n```md\nRANGE: 00:30:00-00:59:00\nRANGE: 01:31:00-02:30:00\n```\nWhich, means I can no longer overlap on 1:00 or 1:30 , this is the default behaviour when working with booking type systems.\n\nIf I wish to allow there to be overlaps on the blocking times then I can just send `()` exclusion flags to it and \nthe ranges would be like so.\n\n```md\nRANGE: 00:30:00-01:00:00\nRANGE: 01:30:00-02:30:00\n```\n\na.k.a, I can overlap on the `1:00` and `1:30` minutes while using another blocker\n\n\n**Possible flags**\n- `[]` - include both\n- `(]` - exclude start, include end\n- `[)` - include start, exclude end\n- `()` - exclude both\n\n**Example**\n```js\nconst range = createRange(rangeStart, rangeEnd)\nrange.block(blockStart, blockEnd, '[]')\n```\n\n\n## License\n\n[MIT](/license)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbarelyhuman%2Frange","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbarelyhuman%2Frange","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbarelyhuman%2Frange/lists"}