# stime

> Time package for easy time manipulation

Latest version **1.1.1** (published 2022-03-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install stime
pnpm add stime
yarn add stime
bun add stime
```

## 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.1.1 |
| Published | 2022-03-01 |
| First published | 2020-06-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 74.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Terence Jefferies |
| Maintainers | terencejefferies |
| Keywords | time, date |

## Links

- npm: https://www.npmjs.com/package/stime
- Repository: https://github.com/TerenceJefferies/STime
- Homepage: https://github.com/TerenceJefferies/STime#readme
- Issues: https://github.com/TerenceJefferies/STime/issues
- npm.io page: https://npm.io/package/stime

## 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.1.1 (latest) — 2022-03-01
- 1.0.0 — 2020-06-27
- 0.4.0 — 2020-06-21
- 0.3.0 — 2020-06-20
- 0.2.0 — 2020-06-19
- 0.0.5 — 2020-06-19
- 0.0.1 — 2020-06-19

## README

![Test](https://github.com/TerenceJefferies/STime/workflows/Test/badge.svg)

# Simple Time (STime)

STime is a simple javascript library used to generate and manipulate date/time. STime is designed to have a simple, readable API that is as pleasing to the eye as it is useful.

## Installation

`npm install stime`

## Basic Usage

### Using in a script

STime does not require any additional calls or instansiation to use, simply call the STime library after installation:

```javascript
const stime = require('stime');
```

### Getting the current date/time

The current time returned from any of the generator methods is a Time, more information about how to interact with a time can be found in the **Interacting with time** section.

```javascript
const stime = require('stime');
const time = stime.now();
```

### Creating an instance of time in the future or past

A builder is provided to create a date at a particular date/time from the current date/time, this can be accessed in the following way:

```javascript
const stime = require('stime');
stime.create(7).days().from().now(); // An instance of time 7 days from today
```

A number of options are available for use with the builder, depending which stage you are at:

| Stage | Available options | Example |  
| ----- | ------ | ------ |
| Creation | `days` `months` `years` `hours` `minutes` `seconds` |  `stime.create(7).hours()` |
| Units | `from` `before` | `stime.create(7).days().before()` |
| Direction | `now` `time` | `stime.create(6).hours().after().now()` |

### Getting the difference between two times

A [difference](docs/classes/_stime_.stime.md#difference) method is available in STime. This method takes two times and will report the difference between those two times.

**Example**

```javascript
const stime = require('stime');
const timeOne = stime.fromDate(new Date('01-01-2020 15:00:00'));
const timeTwo = stime.fromDate(new Date('01-05-2020 15:00:00'));
stime.difference(timeOne, timeTwo).getTotalDays(); // 4
```

### Creating a date from a native date

To allow for the greatest level of flexibility, STime offers a mechanism to get a time from a native javascript date.

```javascript
const stime = require('stime');
stime.fromDate(new Date('01-01-2020 14:00:00')); // A time at the specified date
```

### Interacting with time

| Method | Return value |
| ------ | ------------ |
| [getDay](docs/classes/_time_.time.md#getday) | The current day as an integer |
| [getHours](docs/classes/_time_.time.md#gethours) | The current hour as an integer |
| [getMinutes](docs/classes/_time_.time.md#getminutes) | The current minute as an integer |
| [getSeconds](docs/classes/_time_.time.md#getseconds) | The current second as an integer |
| [getYear](docs/classes/_time_.time.md#getyear) | The current year as an integer |
| [getMonth](docs/classes/_time_.time.md#getmonth) | The current month as an integer |
| [toTimestamp](docs/classes/_time_.time.md#toTimestamp) | Convert the time instance to a unix timestamp |
| [format](docs/classes/_time_.time.md#format) | Format a time into a particular format |

**Example**

```javascript
const stime = require('stime');
const time = stime.now();
time.getDay(); // Todays day of the month
```

### Formatting a time

**Available Formats**

| Character(s) | Result | Example |
| ------------ | ------ | ------- |
| `YYYY` | Four-digit year | `2020` |
| `YY` | Two-digit year | `20` |
| `MMMM` | Full month name | `January` |
| `MMM` | Three character month name | `Jan` |
| `MM` | Month number with leading zeros | `01` |
| `M` | Month number without leading zeros | `1` |
| `DD` | Day number with leading zeros | `03` |
| `D` | Day number without leading zeros | `3` |
| `HH` | Hour with leading zeros | `07` |
| `H` | Hour without leading zeros | `7` |
| `II` | Minutes with leading zeros | `08` |
| `I` | Minutes without leading zeros | `8` |
| `SS` | Seconds with leading zeros | `09` |
| `S` | Seconds without leading zeros | `9` |

**Example**

```javascript
const stime = require('stime');
stime.now().format('DD/MM/YYYY'); // 01/12/2020
```

### Parsing time from a string

| Character(s) | Result | Example |
| ------------ | ------ | ------- |
| `YYYY` | Four-digit year | `2020` |
| `MMMM` | Full month name | `January` |
| `MMM` | Three character month name | `Jan` |
| `MM` | Month number with leading zeros | `01` |
| `M` | Month number without leading zeros | `1` |
| `DD` | Day number with leading zeros | `03` |
| `D` | Day number without leading zeros | `3` |
| `HH` | Hour with leading zeros | `07` |
| `H` | Hour without leading zeros | `7` |
| `II` | Minutes with leading zeros | `08` |
| `I` | Minutes without leading zeros | `8` |
| `SS` | Seconds with leading zeros | `09` |
| `S` | Seconds without leading zeros | `9` |

**Example**

```javascript
const stime = require('stime');
stime.parse('13/01/2000', 'DD/MM/YYYY').getYear(); // 2000
```

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