diff --git a/npmextra.json b/npmextra.json index 603670a..6664998 100644 --- a/npmextra.json +++ b/npmextra.json @@ -9,12 +9,21 @@ "githost": "code.foss.global", "gitscope": "push.rocks", "gitrepo": "smarttime", - "description": "handle time in smart ways", + "description": "Provides utilities for advanced time handling including cron jobs, timestamps, intervals, and more.", "npmPackagename": "@push.rocks/smarttime", - "license": "MIT" + "license": "MIT", + "keywords": [ + "time handling", + "cron jobs", + "timestamps", + "time intervals", + "date operations", + "time formatting", + "scheduling" + ] } }, - "tsdocs": { + "tsdoc": { "legal": "\n## License and Legal Information\n\nThis repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. \n\n**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.\n\n### Trademarks\n\nThis project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.\n\n### Company Information\n\nTask Venture Capital GmbH \nRegistered at District court Bremen HRB 35230 HB, Germany\n\nFor any legal inquiries or if you require further information, please contact us via email at hello@task.vc.\n\nBy using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.\n" } } \ No newline at end of file diff --git a/package.json b/package.json index 9467b1d..d839826 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,7 @@ "name": "@push.rocks/smarttime", "private": false, "version": "4.0.6", - "description": "handle time in smart ways", + "description": "Provides utilities for advanced time handling including cron jobs, timestamps, intervals, and more.", "main": "dist_ts/index.js", "typings": "dist_ts/index.d.ts", "author": "Lossless GmbH", @@ -13,15 +13,15 @@ "buildDocs": "tsdoc" }, "devDependencies": { - "@git.zone/tsbuild": "^2.1.66", - "@git.zone/tsbundle": "^2.0.8", + "@git.zone/tsbuild": "^2.1.72", + "@git.zone/tsbundle": "^2.0.15", "@git.zone/tsrun": "^1.2.44", - "@git.zone/tstest": "^1.0.77", + "@git.zone/tstest": "^1.0.86", "@push.rocks/tapbundle": "^5.0.15", - "@types/node": "^20.8.7" + "@types/node": "^20.11.19" }, "dependencies": { - "@push.rocks/lik": "^6.0.5", + "@push.rocks/lik": "^6.0.12", "@push.rocks/smartdelay": "^3.0.5", "@push.rocks/smartpromise": "^4.0.3", "croner": "^7.0.3", @@ -44,5 +44,14 @@ "browserslist": [ "last 1 chrome versions" ], - "type": "module" -} + "type": "module", + "keywords": [ + "time handling", + "cron jobs", + "timestamps", + "time intervals", + "date operations", + "time formatting", + "scheduling" + ] +} \ No newline at end of file diff --git a/readme.hints.md b/readme.hints.md new file mode 100644 index 0000000..0519ecb --- /dev/null +++ b/readme.hints.md @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/readme.md b/readme.md index 37e7e66..9539fee 100644 --- a/readme.md +++ b/readme.md @@ -1,61 +1,147 @@ # @push.rocks/smarttime handle time in smart ways -## Availabililty and Links -* [npmjs.org (npm package)](https://www.npmjs.com/package/@push.rocks/smarttime) -* [gitlab.com (source)](https://gitlab.com/push.rocks/smarttime) -* [github.com (source mirror)](https://github.com/push.rocks/smarttime) -* [docs (typedoc)](https://push.rocks.gitlab.io/smarttime/) +## Install +To install `@push.rocks/smarttime`, use the following npm command: -## Status for master +```bash +npm install @push.rocks/smarttime --save +``` -Status Category | Status Badge --- | -- -GitLab Pipelines | [![pipeline status](https://gitlab.com/push.rocks/smarttime/badges/master/pipeline.svg)](https://lossless.cloud) -GitLab Pipline Test Coverage | [![coverage report](https://gitlab.com/push.rocks/smarttime/badges/master/coverage.svg)](https://lossless.cloud) -npm | [![npm downloads per month](https://badgen.net/npm/dy/@push.rocks/smarttime)](https://lossless.cloud) -Snyk | [![Known Vulnerabilities](https://badgen.net/snyk/push.rocks/smarttime)](https://lossless.cloud) -TypeScript Support | [![TypeScript](https://badgen.net/badge/TypeScript/>=%203.x/blue?icon=typescript)](https://lossless.cloud) -node Support | [![node](https://img.shields.io/badge/node->=%2010.x.x-blue.svg)](https://nodejs.org/dist/latest-v10.x/docs/api/) -Code Style | [![Code Style](https://badgen.net/badge/style/prettier/purple)](https://lossless.cloud) -PackagePhobia (total standalone install weight) | [![PackagePhobia](https://badgen.net/packagephobia/install/@push.rocks/smarttime)](https://lossless.cloud) -PackagePhobia (package size on registry) | [![PackagePhobia](https://badgen.net/packagephobia/publish/@push.rocks/smarttime)](https://lossless.cloud) -BundlePhobia (total size when bundled) | [![BundlePhobia](https://badgen.net/bundlephobia/minzip/@push.rocks/smarttime)](https://lossless.cloud) +This will add `@push.rocks/smarttime` to your project's dependencies. ## Usage -Use TypeScript for best in class instellisense. +`@push.rocks/smarttime` provides a comprehensive toolkit for handling various aspects of time manipulation, scheduling, and comparison in a TypeScript project. The following sections will guide you through the capabilities of this package, showcasing how to use its classes and functions effectively. -Smarttime offers smart ways to deal with time. +### Handling Time Units and Calculations -### class CronManager +#### Working with Units +```typescript +import { units, getMilliSecondsFromUnits } from '@push.rocks/smarttime'; -This class provides scheduling of functions with a cron syntax +// Define a duration using a combination of time units +let durationInMilliseconds = getMilliSecondsFromUnits({ + years: 1, + months: 2, + weeks: 3, + days: 4, + hours: 5, + minutes: 6, + seconds: 7 +}); + +console.log(`Duration in milliseconds: ${durationInMilliseconds}`); +``` + +In the example above, we specify a complex duration made up of various time units using the `getMilliSecondsFromUnits` function. This is quite useful for calculations where you need to define durations in a more human-readable format. + +### Scheduling with CronManager + +`@push.rocks/smarttime` includes a powerful scheduling tool called `CronManager`, which allows you to schedule tasks using cron syntax. + +#### Creating and Starting a CronManager +```typescript +import { CronManager } from '@push.rocks/smarttime'; + +const cronManager = new CronManager(); + +// Adding a cron job that runs every minute +cronManager.addCronjob('* * * * *', async () => { + console.log('This task runs every minute.'); +}); + +// Starting the CronManager +cronManager.start(); +``` + +The example demonstrates how to create a `CronManager`, add a cron job that runs every minute, and start the scheduling. You can add multiple cron jobs to a single manager, each with its own scheduling and task. + +### Working with Extended Date Class + +The `ExtendedDate` class extends the native JavaScript `Date` object, providing additional functionality for handling dates in various formats and zones. + +#### Creating ExtendedDate Instances +```typescript +import { ExtendedDate } from '@push.rocks/smarttime'; + +// Creating a date from a European format string +const dateFromEuroString = ExtendedDate.fromEuropeanDate('31.12.2023'); +console.log(dateFromEuroString.toString()); + +// Creating a date from a hyphed date string +const dateFromHyphedString = ExtendedDate.fromHyphedDate('2023-12-31'); +console.log(dateFromHyphedString.toString()); +``` + +#### Checking if a Date is Today +```typescript +import { ExtendedDate } from '@push.rocks/smarttime'; + +const someDate = new ExtendedDate(); +console.log(`Is someDate today? ${someDate.isToday()}`); +``` + +Using `ExtendedDate`, you can also easily check if a given date is today. This simplifies certain date comparisons that are common in web and application development. + +### High-Resolution Time Measurement +For performance testing and high-resolution time tracking, `@push.rocks/smarttime` provides the `HrtMeasurement` class. ```typescript -import { CronManager } from '@pushrocks/smarrtime'; -const cronManagerInstance = new CronManager(); -cronManagerInstance.addCronjob('* * * * * *', async () => { - console.log('hello'); // will log 'hello' to console once every second; +import { HrtMeasurement } from '@push.rocks/smarttime'; + +const hrtMeasurement = new HrtMeasurement(); +hrtMeasurement.start(); +// Simulate some operations... +setTimeout(() => { + hrtMeasurement.stop(); + console.log(`Operation took ${hrtMeasurement.milliSeconds} milliseconds.`); +}, 1000); +``` + +This class allows you to measure the duration of operations in your code with high precision, offering both milliseconds and nanoseconds resolutions. + +### Interval and Timer functionalities + +`@push.rocks/smarttime` includes classes for managing intervals and timers with enhanced control, such as pause, resume, and reset capabilities. + +#### Using the Timer class +```typescript +import { Timer } from '@push.rocks/smarttime'; + +const timer = new Timer(5000); // A 5-second timer +timer.start(); + +timer.completed.then(() => { + console.log('Timer completed!'); }); -cronManagerInstance.start(); + +// Resetting the timer +timer.reset(); +timer.start(); ``` -### class ExtendedDate +The `Timer` class allows for asynchronous waiting in a more object-oriented manner. In the example, a `Timer` is created for five seconds, started, and then reset for demonstration purposes. -This class offers static functions to create zone specific JavaScript dates from European formated time strings. +### Conclusion -```TypeScript -import { ExtendedDate } from '@pushrocks/smarttime' -const myDate: Date = ExtendedDate.fromEuropeanDate('8.6.2018') -``` +`@push.rocks/smarttime` offers an extensive toolkit for dealing with time in JavaScript and TypeScript applications. Whether you need precise timing, scheduled tasks, or extended date functionalities, this package provides a suite of tools designed to handle time in smart and efficient ways. The examples provided herein demonstrate the core functionalities, aiming to help you integrate time-related features into your projects with ease. -## Contribution +## License and Legal Information -We are always happy for code contributions. If you are not the code contributing type that is ok. Still, maintaining Open Source repositories takes considerable time and thought. If you like the quality of what we do and our modules are useful to you we would appreciate a little monthly contribution: You can [contribute one time](https://lossless.link/contribute-onetime) or [contribute monthly](https://lossless.link/contribute). :) +This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. -For further information read the linked docs at the top of this readme. +**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file. -## Legal -> MIT licensed | **©** [Task Venture Capital GmbH](https://task.vc) -| By using this npm module you agree to our [privacy policy](https://lossless.gmbH/privacy) +### Trademarks + +This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH. + +### Company Information + +Task Venture Capital GmbH +Registered at District court Bremen HRB 35230 HB, Germany + +For any legal inquiries or if you require further information, please contact us via email at hello@task.vc. + +By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.