Updated npmignore to exclude additional files that don't belong in th…

…e npm package. Added type qualifier to most type and interface imports to improve tree-shaking. Updated README format with additional package details + new badge format. Upgraded dependencies to latest including @toreda/log and @toreda/types.
toreda · Jan 5, 2022 · 0b87fe8 · 0b87fe8
1 parent f379e2a
commit 0b87fe8
Show file tree

Hide file tree

Showing 49 changed files with 1,151 additions and 1,114 deletions.
diff --git a/.npmignore b/.npmignore
@@ -1,19 +1,20 @@
-demo
-node_modules
-tests
-docs
-*.code-workspace
-coverage
-yarn-debug.log
-yarn-error.log
-test-report.xml
+.eslintrc.js
+.gitattributes
 .github
-.vscode
-sonar-project.properties
 .prettierrc.js
-.eslintrc.js
+.vscode
+*.code-workspace
+coverage/
+demo/
+docs/
+examples/
 gulpfile.ts
 jest.config.js
+node_modules
+sonar-project.properties
+src/
+test-report.xml
+tests
 tsconfig.json
-./src/
-examples/
+yarn-debug.log
+yarn-error.log
diff --git a/README.md b/README.md
@@ -1,30 +1,96 @@
 
 [![Toreda](https://content.toreda.com/logo/toreda-logo.png)](https://www.toreda.com)
 
+[![CI](https://img.shields.io/github/workflow/status/toreda/time/CI?style=for-the-badge)](https://github.com/toreda/time/actions) [![Coverage](https://img.shields.io/sonar/coverage/toreda_time?server=https%3A%2F%2Fsonarcloud.io&style=for-the-badge)](https://sonarcloud.io/project/activity?graph=coverage&id=toreda_time) [![Sonar Quality Gate](https://img.shields.io/sonar/quality_gate/toreda_time?server=https%3A%2F%2Fsonarcloud.io&style=for-the-badge)](https://sonarcloud.io/dashboard?id=toreda_time)
+
+[![GitHub package.json version (branch)](https://img.shields.io/github/package-json/v/toreda/time/master?style=for-the-badge)](https://github.com/toreda/time/releases/latest) [![GitHub Release Date](https://img.shields.io/github/release-date/toreda/time?style=for-the-badge)](https://github.com/toreda/time/releases/latest) [![GitHub issues](https://img.shields.io/github/issues/toreda/time?style=for-the-badge)](https://github.com/toreda/time/issues)
+
+ [![license](https://img.shields.io/github/license/toreda/time?style=for-the-badge)](https://github.com/toreda/time/blob/master/LICENSE)
+
+&nbsp;
 # `@toreda/time`
+Fast &amp; easy time math and time unit conversions.
 
-![CI](https://github.com/toreda/time/workflows/CI/badge.svg?branch=master) [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=toreda_time&metric=coverage)](https://sonarcloud.io/dashboard?id=toreda_time) [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=toreda_time&metric=alert_status)](https://sonarcloud.io/dashboard?id=toreda_time)
+&nbsp;
 
-Helpers for common time &amp; timer functionality.
+## 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) &amp; convert to other time units.
+  * Convert `DateTime` strings to `Unix Timestamp`.
 
 &nbsp;
 
-# Install
-`@toreda/time` is available as an [NPM package](https://www.npmjs.com/package/@toreda/time).
+## 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.
 
 &nbsp;
 
-**Install with yarn:**
+# 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
 ```
 
-**or Install with NPM:**
+### NPM Install
 ```bash
 npm install @toreda/time
 ```
 
 &nbsp;
+# 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 &amp; 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```
+
+&nbsp;
+
 # Usage
 
 ## Time Objects
@@ -127,10 +193,12 @@ console.log('is valid: ' + timeValid(undefined));
 # Legal
 
 ## License
-
 [MIT](LICENSE) &copy; Toreda, Inc.
 
+
 ## Copyright
-Copyright &copy; 2019 - 2021 Toreda, Inc. All Rights Reserved.
+Copyright &copy; 2019 - 2022 Toreda, Inc. All Rights Reserved.
+
 
-https://www.toreda.com
+## Website
+Toreda's company website can be found at [toreda.com](https://www.toreda.com)
diff --git a/docs/assets/main.js b/docs/assets/main.js
diff --git a/docs/assets/search.js b/docs/assets/search.js
diff --git a/docs/classes/Defaults.html b/docs/classes/Defaults.html
diff --git a/docs/classes/TimeData.html b/docs/classes/TimeData.html
diff --git a/docs/classes/TimerActive.html b/docs/classes/TimerActive.html
diff --git a/docs/classes/TimerCallbackGroup.html b/docs/classes/TimerCallbackGroup.html
diff --git a/docs/classes/TimerPassive.html b/docs/classes/TimerPassive.html
diff --git a/docs/enums/TimeConstants.html b/docs/enums/TimeConstants.html
diff --git a/docs/index.html b/docs/index.html
diff --git a/docs/interfaces/Time.html b/docs/interfaces/Time.html
diff --git a/docs/interfaces/TimeUnitLabel.html b/docs/interfaces/TimeUnitLabel.html
diff --git a/docs/interfaces/Timer.html b/docs/interfaces/Timer.html
diff --git a/docs/interfaces/TimerOptions.html b/docs/interfaces/TimerOptions.html
@@ -0,0 +1,3 @@
+<!DOCTYPE html><html class="default"><head><meta charSet="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>TimerOptions | @toreda/time</title><meta name="description" content="Documentation for @toreda/time"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="../assets/style.css"/><link rel="stylesheet" href="../assets/highlight.css"/><script async src="../assets/search.js" id="search-script"></script></head><body><script>document.body.classList.add(localStorage.getItem("tsd-theme") || "os")</script><header><div class="tsd-page-toolbar"><div class="container"><div class="table-wrap"><div class="table-cell" id="tsd-search" data-base=".."><div class="field"><label for="tsd-search-field" class="tsd-widget search no-caption">Search</label><input type="text" id="tsd-search-field"/></div><ul class="results"><li class="state loading">Preparing search index...</li><li class="state failure">The search index is not available</li></ul><a href="../index.html" class="title">@toreda/time</a></div><div class="table-cell" id="tsd-widgets"><div id="tsd-filter"><a href="#" class="tsd-widget options no-caption" data-toggle="options">Options</a><div class="tsd-filter-group"><div class="tsd-select" id="tsd-filter-visibility"><span class="tsd-select-label">All</span><ul class="tsd-select-list"><li data-value="public">Public</li><li data-value="protected">Public/Protected</li><li data-value="private" class="selected">All</li></ul></div> <input type="checkbox" id="tsd-filter-inherited" checked/><label class="tsd-widget" for="tsd-filter-inherited">Inherited</label><input type="checkbox" id="tsd-filter-externals" checked/><label class="tsd-widget" for="tsd-filter-externals">Externals</label></div></div><a href="#" class="tsd-widget menu no-caption" data-toggle="menu">Menu</a></div></div></div></div><div class="tsd-page-title"><div class="container"><ul class="tsd-breadcrumb"><li><a href="../modules.html">@toreda/time</a></li><li><a href="TimerOptions.html">TimerOptions</a></li></ul><h1>Interface TimerOptions</h1></div></div></header><div class="container container-main"><div class="row"><div class="col-8 col-content"><section class="tsd-panel tsd-comment"><div class="tsd-comment tsd-typography"><div class="lead">
+<p>Configuration options provided to timer constructors.</p>
+</div></div></section><section class="tsd-panel tsd-hierarchy"><h3>Hierarchy</h3><ul class="tsd-hierarchy"><li><span class="target">TimerOptions</span></li></ul></section><section class="tsd-panel-group tsd-index-group"><h2>Index</h2><section class="tsd-panel tsd-index-panel"><div class="tsd-index-content"><section class="tsd-index-section "><h3>Properties</h3><ul class="tsd-index-list"><li class="tsd-kind-property tsd-parent-kind-interface"><a href="TimerOptions.html#limitDuration" class="tsd-kind-icon">limit<wbr/>Duration</a></li><li class="tsd-kind-property tsd-parent-kind-interface"><a href="TimerOptions.html#timeLimit" class="tsd-kind-icon">time<wbr/>Limit</a></li></ul></section></div></section></section><section class="tsd-panel-group tsd-member-group "><h2>Properties</h2><section class="tsd-panel tsd-member tsd-kind-property tsd-parent-kind-interface"><a id="limitDuration" class="tsd-anchor"></a><h3><span class="tsd-flag ts-flagOptional">Optional</span> limit<wbr/>Duration</h3><div class="tsd-signature tsd-kind-icon">limit<wbr/>Duration<span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">boolean</span></div><aside class="tsd-sources"><ul><li>Defined in <a href="https://github.com/toreda/time/blob/f379e2a/src/timer/options.ts#L7">timer/options.ts:7</a></li></ul></aside></section><section class="tsd-panel tsd-member tsd-kind-property tsd-parent-kind-interface"><a id="timeLimit" class="tsd-anchor"></a><h3><span class="tsd-flag ts-flagOptional">Optional</span> time<wbr/>Limit</h3><div class="tsd-signature tsd-kind-icon">time<wbr/>Limit<span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">number</span></div><aside class="tsd-sources"><ul><li>Defined in <a href="https://github.com/toreda/time/blob/f379e2a/src/timer/options.ts#L8">timer/options.ts:8</a></li></ul></aside></section></section></div><div class="col-4 col-menu menu-sticky-wrap menu-highlight"><nav class="tsd-navigation primary"><ul><li class=""><a href="../modules.html">Exports</a></li></ul></nav><nav class="tsd-navigation secondary menu-sticky"><ul><li class="current tsd-kind-interface"><a href="TimerOptions.html" class="tsd-kind-icon">Timer<wbr/>Options</a><ul><li class="tsd-kind-property tsd-parent-kind-interface"><a href="TimerOptions.html#limitDuration" class="tsd-kind-icon">limit<wbr/>Duration</a></li><li class="tsd-kind-property tsd-parent-kind-interface"><a href="TimerOptions.html#timeLimit" class="tsd-kind-icon">time<wbr/>Limit</a></li></ul></li></ul></nav></div></div></div><footer class="with-border-bottom"><div class="container"><h2>Legend</h2><div class="tsd-legend-group"><ul class="tsd-legend"><li class="tsd-kind-constructor tsd-parent-kind-class"><span class="tsd-kind-icon">Constructor</span></li><li class="tsd-kind-property tsd-parent-kind-class"><span class="tsd-kind-icon">Property</span></li><li class="tsd-kind-method tsd-parent-kind-class"><span class="tsd-kind-icon">Method</span></li></ul><ul class="tsd-legend"><li class="tsd-kind-property tsd-parent-kind-interface"><span class="tsd-kind-icon">Property</span></li><li class="tsd-kind-method tsd-parent-kind-interface"><span class="tsd-kind-icon">Method</span></li></ul><ul class="tsd-legend"><li class="tsd-kind-property tsd-parent-kind-class tsd-is-private"><span class="tsd-kind-icon">Private property</span></li><li class="tsd-kind-method tsd-parent-kind-class tsd-is-private"><span class="tsd-kind-icon">Private method</span></li></ul><ul class="tsd-legend"><li class="tsd-kind-property tsd-parent-kind-class tsd-is-static"><span class="tsd-kind-icon">Static property</span></li></ul></div><h2>Settings</h2><p>Theme <select id="theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></p></div></footer><div class="container tsd-generator"><p>Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></div><div class="overlay"></div><script src="../assets/main.js"></script></body></html>
diff --git a/docs/modules.html b/docs/modules.html
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
 	"name": "@toreda/time",
-	"version": "0.1.1",
+	"version": "0.1.2",
 	"description": "Simple, small footprint library for common time operations and converting between units of time. ",
 	"main": "./dist/index",
 	"typings": "./dist/index.d.ts",
@@ -23,11 +23,8 @@
 	},
 	"keywords": [
 		"time",
-		"time functions",
-		"time helpers",
 		"timestamp",
-		"timestamps",
-		"date and time",
+		"date",
 		"moment",
 		"moment.js",
 		"typescript",
@@ -38,38 +35,38 @@
 	"bugs": {
 		"url": "https://github.com/toreda/time/issues"
 	},
+	"resolutions": {
+		"glob-parent": "^5.1.2"
+	},
 	"prettier": "@toreda/prettier-config",
 	"homepage": "https://github.com/toreda/time#readme",
 	"devDependencies": {
-		"@swc/core": "^1.2.105",
-		"@swc/wasm": "^1.2.103",
-		"@toreda/build-tools": "^0.5.5",
+		"@toreda/build-tools": "^0.6.4",
 		"@toreda/eslint-config": "^2.2.0",
 		"@toreda/prettier-config": "^1.0.1",
-		"@toreda/types": "^2.3.0",
-		"@types/jest": "^27.0.2",
-		"@types/node": "^16.11.6",
-		"@typescript-eslint/eslint-plugin": "^5.1.0",
-		"@typescript-eslint/parser": "^5.1.0",
-		"bufferutil": "^4.0.5",
-		"eslint": "^8.1.0",
+		"@toreda/types": "^2.6.0",
+		"@types/jest": "^27.4.0",
+		"@types/node": "^17.0.8",
+		"@typescript-eslint/eslint-plugin": "^5.9.0",
+		"@typescript-eslint/parser": "^5.9.0",
+		"eslint": "^8.6.0",
 		"eslint-config-prettier": "^8.3.0",
 		"eslint-plugin-prettier": "^4.0.0",
 		"gulp": "^4.0.2",
 		"gulp-typescript": "^6.0.0-alpha.1",
-		"jest": "^27.3.1",
+		"jest": "^27.4.6",
 		"jest-sonar-reporter": "^2.0.0",
 		"madge": "^5.0.1",
 		"mockdate": "^3.0.5",
-		"prettier": "^2.4.1",
-		"ts-jest": "^27.0.7",
+		"prettier": "^2.5.1",
+		"ts-jest": "^27.1.2",
 		"ts-loader": "^9.2.6",
 		"ts-node": "^10.4.0",
-		"typedoc": "^0.22.4",
-		"typescript": "^4.4.4"
+		"typedoc": "^0.22.10",
+		"typescript": "^4.5.4"
 	},
 	"dependencies": {
-		"@toreda/log": "^0.6.4",
-		"@toreda/strong-types": "^0.26.0"
+		"@toreda/log": "^0.6.12",
+		"@toreda/strong-types": "^0.28.2"
 	}
 }
diff --git a/src/days.ts b/src/days.ts
@@ -1,4 +1,4 @@
-import {Time} from './time';
+import type {Time} from './time';
 import {timeMake} from './time/make';
 
 /**

diff --git a/src/hours.ts b/src/hours.ts
@@ -1,4 +1,4 @@
-import {Time} from './time';
+import type {Time} from './time';
 import {timeMake} from './time/make';
 
 /**

diff --git a/src/index.ts b/src/index.ts
@@ -8,7 +8,6 @@ export {seconds} from './seconds';
 export {Time} from './time';
 export {timeCheckMethods} from './time/check/methods';
 export {timeCheckType} from './time/check/type';
-export {timeValid} from './time/valid';
 export {TimeConstants} from './time/constants';
 export {timeConversions} from './time/conversions';
 export {timeConvert, canConvert} from './time/convert';
@@ -23,6 +22,7 @@ export {TimerCallback} from './timer/callback';
 export {TimerCallbackGroup} from './timer/callback/group';
 export {TimerCallbackSync} from './timer/callback/sync';
 export {TimerEventId} from './timer/event/id';
+export {TimerOptions} from './timer/options';
 export {TimerPassive} from './timer/passive';
 export {timeSince} from './time/since';
 export {TimeUnit} from './time/unit';
@@ -31,6 +31,7 @@ export {timeUnitLabels} from './time/unit/labels';
 export {timeUnits} from './time/units';
 export {timeUnitSupported} from './time/unit/supported';
 export {timeUntil} from './time/until';
+export {timeValid} from './time/valid';
 export {unixTimestampNow} from './unix/timestamp/now';
 export {weeks} from './weeks';
 export {years} from './years';
diff --git a/src/microseconds.ts b/src/microseconds.ts
@@ -1,4 +1,4 @@
-import {Time} from './time';
+import type {Time} from './time';
 import {timeMake} from './time/make';
 
 /**

diff --git a/src/milliseconds.ts b/src/milliseconds.ts
@@ -1,4 +1,4 @@
-import {Time} from './time';
+import type {Time} from './time';
 import {timeMake} from './time/make';
 
 /**

diff --git a/src/minutes.ts b/src/minutes.ts
@@ -1,8 +1,8 @@
-import {Time} from './time';
+import type {Time} from './time';
 import {timeMake} from './time/make';
 
 /**
- * Create Time object in 'minutes'
+ * Create Time object using minutes.
  * @param initial		Object's initial value (in minutes).
  * @returns				Time object
  *

diff --git a/src/months.ts b/src/months.ts
@@ -1,9 +1,9 @@
 import {Log} from '@toreda/log';
-import {Time} from './time';
+import type {Time} from './time';
 import {timeMake} from './time/make';
 
 /**
- * Create Time object in 'months'
+ * Create Time object with months as time unit.
  * @param initial		Object's initial value (in months).
  * @returns				Time object
  *

diff --git a/src/seconds.ts b/src/seconds.ts
@@ -1,4 +1,4 @@
-import {Time} from './time';
+import type {Time} from './time';
 import {timeMake} from './time/make';
 
 /**

diff --git a/src/time.ts b/src/time.ts
@@ -1,4 +1,4 @@
-import {TimeUnit} from './time/unit';
+import type {TimeUnit} from './time/unit';
 
 /**
  * Properties required for all Time objects.

diff --git a/src/time/check/methods.ts b/src/time/check/methods.ts
@@ -1,4 +1,4 @@
-import {Time} from '../../time';
+import type {Time} from '../../time';
 import {timeMethods} from '../methods';
 
 /**

diff --git a/src/time/check/type.ts b/src/time/check/type.ts
@@ -1,4 +1,4 @@
-import {Time} from '../../time';
+import type {Time} from '../../time';
 
 /**
  * Check whether provided object is a Time object.

diff --git a/src/time/conversions.ts b/src/time/conversions.ts
@@ -1,5 +1,5 @@
 import {TimeConstants} from './constants';
-import {TimeUnit} from './unit';
+import type {TimeUnit} from './unit';
 
 export const timeConversions: Record<TimeUnit, Record<TimeUnit, number>> = {
 	m: {

diff --git a/src/time/convert.ts b/src/time/convert.ts
@@ -1,5 +1,5 @@
 import {Defaults} from '../defaults';
-import {TimeUnit} from './unit';
+import type {TimeUnit} from './unit';
 import {timeConversions} from './conversions';
 import {timeUnitSupported} from './unit/supported';
 

diff --git a/src/time/make.ts b/src/time/make.ts
@@ -1,8 +1,8 @@
 import {Defaults} from '../defaults';
 import {Log} from '@toreda/log';
-import {Time} from '../time';
+import type {Time} from '../time';
 import {TimeData} from './data';
-import {TimeUnit} from './unit';
+import type {TimeUnit} from './unit';
 import {timeCheckType} from './check/type';
 import {timeConvert} from './convert';
 import {timeNow} from './now';

diff --git a/src/time/now.ts b/src/time/now.ts
@@ -1,6 +1,6 @@
 import {Defaults} from '../defaults';
-import {Time} from '../time';
-import {TimeUnit} from './unit';
+import type {Time} from '../time';
+import type {TimeUnit} from './unit';
 import {timeMake} from './make';
 
 /**

diff --git a/src/time/now/offset.ts b/src/time/now/offset.ts
@@ -1,4 +1,4 @@
-import {Time} from '../../time';
+import type {Time} from '../../time';
 import {timeNow} from '../now';
 
 export function timeNowOffset(offset: number | Time): Time {

diff --git a/src/time/since.ts b/src/time/since.ts
@@ -1,4 +1,4 @@
-import {Time} from '../time';
+import type {Time} from '../time';
 import {timeNow} from './now';
 
 export function timeSince(time: Time | number): Time {

diff --git a/src/time/unit/label.ts b/src/time/unit/label.ts
@@ -1,4 +1,4 @@
-import {TimeUnit} from '../unit';
+import type {TimeUnit} from '../unit';
 
 /**
  * @category Time Units

diff --git a/src/time/unit/labels.ts b/src/time/unit/labels.ts
@@ -1,6 +1,11 @@
-import {TimeUnit} from '../unit';
-import {TimeUnitLabel} from './label';
+import type {TimeUnit} from '../unit';
+import type {TimeUnitLabel} from './label';
 
+/**
+ * Labels for each time unit including singular and plurals.
+ *
+ * @category Time Units
+ */
 export const timeUnitLabels: Record<TimeUnit, TimeUnitLabel> = {
 	m: {
 		timeUnit: 'm',