# timeline-builder

> Compare and merge date ranges and create a timeline

Latest version **1.0.0** (published 2024-02-11) · MIT license · 0 weekly downloads

## Install

```sh
npm install timeline-builder
pnpm add timeline-builder
yarn add timeline-builder
bun add timeline-builder
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2024-02-11 |
| First published | 2023-02-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 10.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Dime Software |
| Maintainers | hendrik.bulens..gmail.com |
| Keywords | timeline, daterange, buffering, buffer, merge, datecompare |

## Links

- npm: https://www.npmjs.com/package/timeline-builder
- Repository: https://github.com/dimesoftware/timeline-builder
- Homepage: https://github.com/dimesoftware/timeline-builder#readme
- Issues: https://github.com/dimesoftware/timeline-builder/issues
- npm.io page: https://npm.io/package/timeline-builder

## Alternatives

- [@js-joda/timezone](https://npm.io/package/@js-joda/timezone.md) — 383.4K weekly downloads
- [chartjs-adapter-moment](https://npm.io/package/chartjs-adapter-moment.md) — 210.8K weekly downloads
- [strftime](https://npm.io/package/strftime.md) — 171.2K weekly downloads
- [vue-flatpickr-component](https://npm.io/package/vue-flatpickr-component.md) — 115.8K weekly downloads
- [timepicker](https://npm.io/package/timepicker.md) — 51.0K weekly downloads

## Recent versions

- 1.0.0 (latest) — 2024-02-11
- 0.0.1 (alpha.1) — 2023-02-19
- 1.0.0-rc1 — 2023-09-21
- 0.0.11 — 2023-02-22
- 0.0.10 — 2023-02-22
- 0.0.9 — 2023-02-22
- 0.0.8 — 2023-02-21
- 0.0.7 — 2023-02-21
- 0.0.6 — 2023-02-21
- 0.0.5 — 2023-02-19
- 0.0.4 — 2023-02-19
- 0.0.3 — 2023-02-19
- 0.0.2 — 2023-02-19

## README

<p align="center">
    <img src="https://github.com/dimesoftware/timelinebuilderjs/raw/master/assets/logo.png" height="300">
</p>

<p align="center">
    <a href="https://www.npmjs.com/package/timeline-builder"> 
        <img src="https://img.shields.io/npm/v/timeline-builder?style=flat-square" />
    </a>
    <img src="https://img.shields.io/npm/l/timeline-builder?style=flat-square" />
    <img src="https://img.shields.io/badge/PRs-welcome-green.svg?style=flat-square" />
    <img src="https://github.com/dimesoftware/timeline-builder/actions/workflows/ci.yml/badge.svg?branch=master" />
</p>

<h1 align="center">Timeline builder</h1>

A timeline builder that stores an array of the date ranges that have been buffered by your application, as to reduce the amount of data your backend should load.

```javascript
const timeline = new Timeline();
timeline.add(new Date(2023, 0, 1), new Date(2023, 0, 3));
timeline.add(new Date(2023, 0, 2), new Date(2023, 0, 6));

console.log(timeline);

// Output:
// [
//  DateRange {
//    start: 2023-01-01
//    end: 2023-01-06
//  }
// ]
```

Check out this [code sample](https://stackblitz.com/edit/js-yilpbp?file=index.js) to see it in action.

## Install

<a href="https://www.npmjs.com/package/timeline-builder"> 
  <img src="https://img.shields.io/npm/v/timeline-builder?style=flat-square" />
</a>

<br />

Add the `timeline-builder` package with npm:

```
npm install timeline-builder
```

or with yarn

```
yarn add timeline-builder
```

This library is written in TypeScript and has no dependencies.

## Usage

### Building the timeline

Instantiate the builder, that will keep the collection in memory:

```javascript
const timeline = new Timeline();
```

There are two ways to fill up the timeline.

- Using plain date objects:
  
  ```javascript
  timeline.add(new Date(2023, 0, 1), new Date(2023, 0, 3));
  timeline.add(new Date(2023, 0, 2), new Date(2023, 0, 6));
  ```

- Using a `DateRange` object, which is essentially a composition of a start date and end date object:

  ```javascript
  timeline.addRange(new DateRange(new Date(2023, 0, 2), new Date(2023, 0, 6)));
  ```

  The `DateRange` class is used internally to compare overlapping ranges and merge them into one reconciled range.
  
### Timeline actions

The following methods can be executed on the timeline:

- `contains(start,end)`: checks if the range overlaps with the timeline
- `containsAll(start, end)`: checks if the range is entirely within the timeline
- `toList`: creates a reconciled flat list of the timeline
- `clear`: clears the timeline
- `count`: a distinct count of the unique date ranges in the timeline

## Tests

Unit tests are located in the `test` directory. Jest is used as the library. 
Run the tests by running `yarn test`.

## License

MIT

---
_Source: https://npm.io/package/timeline-builder · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._