https://github.com/toreda/time
TypeScript helpers for common time & timer functionality.
https://github.com/toreda/time
Last synced: 10 days ago
JSON representation
TypeScript helpers for common time & timer functionality.
- Host: GitHub
- URL: https://github.com/toreda/time
- Owner: toreda
- License: mit
- Created: 2021-06-19T02:49:06.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2025-01-20T04:33:10.000Z (4 months ago)
- Last Synced: 2025-05-12T21:08:31.264Z (10 days ago)
- Language: TypeScript
- Size: 766 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://www.toreda.com)
[](https://github.com/toreda/time/actions) [](https://sonarcloud.io/project/activity?graph=coverage&id=toreda_time) [](https://sonarcloud.io/dashboard?id=toreda_time)
[](https://github.com/toreda/time/releases/latest) [](https://github.com/toreda/time/releases/latest) [](https://github.com/toreda/time/issues)
[](https://github.com/toreda/time/blob/master/LICENSE)
# `@toreda/time`
Fast & easy time math and time unit conversions.
## Use Cases
* **Time since date**
* Get seconds or any other time unit since `date`, `datetime`, `timestamp`, or `unix timestamp`.
* **Time until date**
* Get seconds or other time unit until `date`, `datetime`, `timestamp`, or `unix timestamp`.
* **Now**
* Get current timestamp (now) in seconds or other time unit.
* **Now (with offset)`**
* Get current timestamp (now) with an offset in the past or future.
* **DateTime Parsing**
* Parse strings as `DateTime` strings.
* Convert to any other time unit.
* **Unix Timestamps**
* Parse `Unix Timstamps` (seconds) & convert to other time units.
* Convert `DateTime` strings to `Unix Timestamp`.
## Highlights
* **TypeScript Native**
* All types included with package.
* No separate `@types` package eliminates sync issues between types and the library.
* **Minimalist**
* Small set of library functions for time calculations.
* Get what you need without extra bloat.
* **Lightweight**
* **`253 kB`** unpacked.
* **Modern Alternative**
* Modern replacement for the excellent [`moment.js`](https://momentjs.com/docs/#/-project-status/) (no longer maintained).
* **Tree-Shaking**
* Package optimizations helps modern bundlers drop unused code.
# Install
## `npmjs.org`
## NPM Package
`@toreda/time` is available as an [NPM package](https://www.npmjs.com/package/@toreda/time).
### Yarn Install (preferred)
```bash
yarn add @toreda/time
```
### NPM Install
```bash
npm install @toreda/time
```
# Source Code
`@toreda/time` source files can be downloaded directly from the public [Github repo](https://github.com/toreda/time).
## Branches
* `master` branch
* Latest release & stable code.
* Use for production builds.
* `develop` branch
* All completed but unreleased features pending release.
* Generally stable, but not guaranteed.
* Not suitable for production builds.
## Git Clone (ssh)
```bash
[email protected]:toreda/time.git
```
## Git Clone (https)
```bash
https://github.com/toreda/time.git
```
## Download Zip (https)
Download the current master branch as a zip file
```https://github.com/toreda/time/archive/refs/heads/master.zip```
# Usage
## Time Objects
**Create Time object**
```typescript
import type {Time} from '@toreda/time';
import {timeMake} from '@toreda/time';
// Create time object in unit 'seconds' with value 0.
const time = timeMake('s', ,0);
```
**Set Time**
```typescript
// Set time using a Unix Timestamp (in seconds)
time.set(1635577204);
// Set using ISO-8601 string
time.set('2021-10-30T06:13:33+00:00');
```
**Set current time (now)**
```typescript
// Set Time to current time.
time.setNow();
```
## Timestamps
### Unix Timestamp
**Create unix timestamp**
```typescript
import {unixTimestampNow} from '@toreda/time';
// Returns current unix timestamp in seconds at time of call.
const now = unixTimestampNow();
```
**Set current time using Unix Timestamp**
```typescript
import type {Time} from '@toreda/time';
import {timeMake, unixTimestampNow} from '@toreda/time';
const now = unixTimestampNow();
const time = timeMake('s');
time.set(now);
```
## Validation
**Check if string is a valid & supported time unit**
```typescript
import {timeUnitSupported} from '@toreda/time';
// Outputs: 'supported: true'
console.info('supported: ' + timeUnitSupported('s'));
// Outputs: 'supported: true'
console.info('supported: ' + timeUnitSupported('w'));
// Outputs: 'supported: false'
console.info('supported: ' + timeUnitSupported());
// Outputs: 'supported: false'
console.info('supported: ' + timeUnitSupported({}));
// Outputs: 'supported: false'
console.info('supported: ' + timeUnitSupported('???'));
```
**Check if object is a Time object**
```typescript
import {timeValid, timeNow} from '@toreda/time';
const now = timeNow();
// Outputs `is valid: true`
console.log('is valid: ' + timeValid(time));
// Outputs `is valid: false`
console.log('is valid: ' + timeValid({}));
// Outputs `is valid: false`
console.log('is valid: ' + timeValid(null));
// Outputs `is valid: false`
console.log('is valid: ' + timeValid(undefined));
```
# Source Code
`@toreda/time` is an open source package provided under the MIT License. Download, clone, or check the complete project source [here on Github](https://www.npmjs.com/package/@toreda/time). We welcome bug reports, comments, and pull requests.
# Legal
## License
[MIT](LICENSE) © Toreda, Inc.
## Copyright
Copyright © 2019 - 2022 Toreda, Inc. All Rights Reserved.
## Website
Toreda's company website can be found at [toreda.com](https://www.toreda.com)