README.md

 

@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 (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.

Yarn Install (preferred)

yarn add @toreda/time

NPM Install

npm install @toreda/time

 

Source Code

@toreda/time source files can be downloaded directly from the public Github repo.

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)

git@github.com:toreda/time.git

Git Clone (https)

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

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

// 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)

// Set Time to current time.
time.setNow();

Timestamps

Unix Timestamp

Create unix timestamp

import {unixTimestampNow} from '@toreda/time';

// Returns current unix timestamp in seconds at time of call.
const now = unixTimestampNow();

Set current time using Unix Timestamp

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

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

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. We welcome bug reports, comments, and pull requests.

 

Legal

License

MIT © Toreda, Inc.

Copyright

Copyright © 2019 - 2022 Toreda, Inc. All Rights Reserved.

Website

Toreda's company website can be found at toreda.com