diff --git a/npmextra.json b/npmextra.json index 336ff93..5024bc9 100644 --- a/npmextra.json +++ b/npmextra.json @@ -14,12 +14,24 @@ "githost": "code.foss.global", "gitscope": "push.rocks", "gitrepo": "npmextra", - "description": "do more with npm", + "description": "Enhances npm with additional configuration and tool management capabilities, including a key-value store for project setups.", "npmPackagename": "@push.rocks/npmextra", - "license": "MIT" + "license": "MIT", + "keywords": [ + "npm", + "configuration management", + "tool management", + "key-value store", + "project setup", + "npm scripts", + "typescript", + "environment setup", + "dependencies management", + "npm package enhancement" + ] } }, - "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 ba26a7b..d2d084f 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,7 @@ "name": "@push.rocks/npmextra", "version": "5.0.12", "private": false, - "description": "do more with npm", + "description": "Enhances npm with additional configuration and tool management capabilities, including a key-value store for project setups.", "main": "dist_ts/index.js", "typings": "dist_ts/index.d.ts", "scripts": { @@ -52,5 +52,17 @@ "browserslist": [ "last 1 chrome versions" ], - "type": "module" -} + "type": "module", + "keywords": [ + "npm", + "configuration management", + "tool management", + "key-value store", + "project setup", + "npm scripts", + "typescript", + "environment setup", + "dependencies management", + "npm package enhancement" + ] +} \ No newline at end of file diff --git a/readme.hints.md b/readme.hints.md new file mode 100644 index 0000000..e69de29 diff --git a/readme.md b/readme.md index 65f2c3f..da71db8 100644 --- a/readme.md +++ b/readme.md @@ -1,70 +1,129 @@ # @push.rocks/npmextra -do more with npm +Enhances npm with additional configuration and tool management capabilities. -## Availabililty and Links -* [npmjs.org (npm package)](https://www.npmjs.com/package/@push.rocks/npmextra) -* [gitlab.com (source)](https://gitlab.com/push.rocks/npmextra) -* [github.com (source mirror)](https://github.com/push.rocks/npmextra) -* [docs (typedoc)](https://push.rocks.gitlab.io/npmextra/) +## Install +To install `@push.rocks/npmextra`, use the following npm command: -## Status for master +```bash +npm install @push.rocks/npmextra --save +``` -Status Category | Status Badge --- | -- -GitLab Pipelines | [![pipeline status](https://gitlab.com/push.rocks/npmextra/badges/master/pipeline.svg)](https://lossless.cloud) -GitLab Pipline Test Coverage | [![coverage report](https://gitlab.com/push.rocks/npmextra/badges/master/coverage.svg)](https://lossless.cloud) -npm | [![npm downloads per month](https://badgen.net/npm/dy/@push.rocks/npmextra)](https://lossless.cloud) -Snyk | [![Known Vulnerabilities](https://badgen.net/snyk/push.rocks/npmextra)](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/npmextra)](https://lossless.cloud) -PackagePhobia (package size on registry) | [![PackagePhobia](https://badgen.net/packagephobia/publish/@push.rocks/npmextra)](https://lossless.cloud) -BundlePhobia (total size when bundled) | [![BundlePhobia](https://badgen.net/bundlephobia/minzip/@push.rocks/npmextra)](https://lossless.cloud) +This package is available on [npm](https://www.npmjs.com/package/@push.rocks/npmextra) and can be installed into your project as a dependency to enhance npm with additional configuration and tool management capabilities. ## Usage +`@push.rocks/npmextra` is designed to supplement npm functionalities with enhanced configuration and tool management. It facilitates managing project configurations and tool setups in a consolidated manner, enabling a smoother workflow and maintenance process. Below are detailed use cases and examples implemented with ESM syntax and TypeScript. -Use TypeScript for best in class instellisense. +### Initial Setup and Configuration +To start using npmextra in your project, first include it in your project with an import statement: -## Using npmextra for managing toolconfigs +```typescript +import { Npmextra } from '@push.rocks/npmextra'; +``` -The main purpose of npmextra is to configure different tools using one npmextra.json. This way complex setups avoid additional complexity caused by too many configuration files. +Instantiate the `Npmextra` class optionally with a custom path to your project's working directory. If no path is provided, the current working directory (`process.cwd()`) is used. -npmextra.json +```typescript +const npmExtraInstance = new Npmextra('/path/to/your/project'); +``` + +### Managing Tool Configurations with `npmextra.json` +`@push.rocks/npmextra` excels in unifying tool configurations through a single `npmextra.json` file. Instead of scattering configurations across multiple files, `@push.rocks/npmextra` enables you to define tool-specific settings within this centralized configuration file. + +#### Creating and Utilizing `npmextra.json` + +Create a `npmextra.json` in your project root with the following structure: ```json { - "sometool": { - "defaultKey1": "awesomeValueFromConfig" + "toolname": { + "setting1": "value1", + "setting2": "value2" } } ``` -```typescript -import { Npmextra } from 'npmextra'; +For example, to configure a hypothetical tool named `toolname`, define its settings as shown above. -let myNpmExtra = new Npmextra('my/path/to/cwd'); // cwd argument is optional -mergedData = myNpmExtra.dataFor('sometool', { - // gets merged with whatever is in the configfile - defaultKey1: 'defaultValue1', // so this will get overwritten with "awesomeValueFromConfig" - defaultKey2: 'defaultValue2', // this one will pass through unaltered +#### Accessing Configuration in Your Project + +With the configuration defined, you can easily access these settings in your TypeScript code as follows: + +```typescript +// import the npmextra module +import { Npmextra } from '@push.rocks/npmextra'; + +// create an instance pointing at the current directory +const npmExtraInstance = new Npmextra(); + +// retrieve the configuration for 'toolname', merging defaults with any found in npmextra.json +const toolConfig = npmExtraInstance.dataFor('toolname', { + defaultKey1: 'defaultValue1', + defaultKey2: 'defaultValue2' }); + +// toolConfig now contains the merged settings from npmextra.json and provided defaults +console.log(toolConfig); ``` -### Tools that already use the config feature of npmextra +### Key-Value Store Management +`@push.rocks/npmextra` also includes a Key-Value Store (KeyValueStore) functionality enabling persistent storage of key-value pairs between script executions. -- [npmts](https://www.npmjs.com/package/npmts) -- [npmci](https://www.npmjs.com/package/npmci) -- [npmdocker](https://www.npmjs.com/package/npmdocker) +#### Setting Up KeyValueStore -## Using the KeyValueStore +To utilize the KeyValueStore, create an instance specifying its scope (e.g., 'userHomeDir') and a unique identity for your application or tool: -## Contribution +```typescript +import { KeyValueStore } from '@push.rocks/npmextra'; -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). :) +const kvStore = new KeyValueStore<'userHomeDir'>('userHomeDir', 'myUniqueAppName'); +``` -For further information read the linked docs at the top of this readme. +You can then use the `writeKey`, `readKey`, `writeAll`, and `readAll` methods to manage your store respectively. -## 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) +#### Example: Storing and Retrieving Data + +```typescript +// Write a single key-value pair +await kvStore.writeKey('username', 'johnDoe'); + +// Read a single key +const username = await kvStore.readKey('username'); +console.log(username); // Outputs: johnDoe + +// Write multiple key-value pairs +await kvStore.writeAll({ + email: 'john@example.com', + isAdmin: true +}); + +// Read all key-value pairs +const allData = await kvStore.readAll(); +console.log(allData); // Outputs the entire store's contents +``` + +### Integrating with Tools +`@push.rocks/npmextra` seamlessly integrates with numerous tools, enabling them to leverage `npmextra.json` for configuration purposes. Tools such as `npmts`, `npmci`, and `npmdocker` are already utilizing this feature for enhanced configuration management. + +For tool developers, integrating with `npmextra` requires reading the tool-specific configuration from `npmextra.json` and adjusting the tool's behavior based on these settings. This creates a unified and streamlined configuration process across different tools used within a project. + +### Conclusion +By centralizing configuration management and offering a versatile key-value store, `@push.rocks/npmextra` significantly simplifies the setup and management of tools and settings in modern JavaScript and TypeScript projects. Whether you're managing project-wide configurations or need persistent storage for key-value pairs, `@push.rocks/npmextra` provides an efficient and streamlined solution. + +## License and Legal Information + +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. + +**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. + +### 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. diff --git a/ts/00_commitinfo_data.ts b/ts/00_commitinfo_data.ts index e542bf1..366f4b0 100644 --- a/ts/00_commitinfo_data.ts +++ b/ts/00_commitinfo_data.ts @@ -3,6 +3,6 @@ */ export const commitinfo = { name: '@push.rocks/npmextra', - version: '5.0.12', - description: 'do more with npm' + version: '5.0.13', + description: 'Enhances npm with additional configuration and tool management capabilities, including a key-value store for project setups.' }