@push.rocks/npmextra NPM

@push.rocks/npmextra

Enhances npm with additional configuration and tool management capabilities.

Install

To install @push.rocks/npmextra, use the following npm command:

npm install @push.rocks/npmextra --save

This package is available on npm 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.

Initial Setup and Configuration

To start using npmextra in your project, first include it in your project with an import statement:

import { Npmextra } from '@push.rocks/npmextra';

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.

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:

{
  "toolname": {
    "setting1": "value1",
    "setting2": "value2"
  }
}

For example, to configure a hypothetical tool named toolname, define its settings as shown above.

Accessing Configuration in Your Project

With the configuration defined, you can easily access these settings in your TypeScript code as follows:

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

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.

Setting Up KeyValueStore

To utilize the KeyValueStore, create an instance specifying its scope (e.g., 'userHomeDir') and a unique identity for your application or tool:

import { KeyValueStore } from '@push.rocks/npmextra';

const kvStore = new KeyValueStore<'userHomeDir'>('userHomeDir', 'myUniqueAppName');

You can then use the writeKey, readKey, writeAll, and readAll methods to manage your store respectively.

Example: Storing and Retrieving Data

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

@push.rocks/npmextra v5.0.13