From f1ecda411a11b6de34b1aadfa3fd71ae3dd4cf86 Mon Sep 17 00:00:00 2001 From: Philipp Kunz Date: Wed, 12 Jun 2024 20:18:27 +0200 Subject: [PATCH] fix(core): update --- npmextra.json | 8 +++- package.json | 10 +++-- readme.md | 81 ++++++++++++---------------------------- ts/00_commitinfo_data.ts | 4 +- 4 files changed, 39 insertions(+), 64 deletions(-) diff --git a/npmextra.json b/npmextra.json index 590a2ec..ac3724b 100644 --- a/npmextra.json +++ b/npmextra.json @@ -14,7 +14,7 @@ "githost": "code.foss.global", "gitscope": "push.rocks", "gitrepo": "npmextra", - "description": "Enhances npm with additional configuration and tool management capabilities, including a key-value store for project setups.", + "description": "A utility to enhance npm with additional configuration, tool management capabilities, and a key-value store for project setups.", "npmPackagename": "@push.rocks/npmextra", "license": "MIT", "keywords": [ @@ -26,7 +26,11 @@ "typescript", "environment setup", "dependencies management", - "npm package enhancement" + "npm package enhancement", + "automation", + "async operations", + "app configuration", + "smart file handling" ] } }, diff --git a/package.json b/package.json index 6999351..50292e6 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,7 @@ "name": "@push.rocks/npmextra", "version": "5.0.15", "private": false, - "description": "Enhances npm with additional configuration and tool management capabilities, including a key-value store for project setups.", + "description": "A utility to enhance npm with additional configuration, tool management capabilities, and a key-value store for project setups.", "main": "dist_ts/index.js", "typings": "dist_ts/index.d.ts", "scripts": { @@ -62,6 +62,10 @@ "typescript", "environment setup", "dependencies management", - "npm package enhancement" + "npm package enhancement", + "automation", + "async operations", + "app configuration", + "smart file handling" ] -} +} \ No newline at end of file diff --git a/readme.md b/readme.md index 6b90610..7f94943 100644 --- a/readme.md +++ b/readme.md @@ -14,7 +14,7 @@ This package is available on [npm](https://www.npmjs.com/package/@push.rocks/npm `@push.rocks/npmextra` is designed to supplement npm functionalities with enhanced configuration and tool management. It facilitates the management of 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: +To start using `npmextra` in your project, first include it with an import statement: ```typescript import { Npmextra } from '@push.rocks/npmextra'; @@ -27,7 +27,7 @@ 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, which can then be accessed programmatically. +`@push.rocks/npmextra` excels in unifying tool configurations through a single `npmextra.json` file. Instead of scattering configurations across multiple files, `npmextra` enables you to define tool-specific settings within this centralized configuration file, which can then be accessed programmatically. #### Creating and Utilizing `npmextra.json` @@ -56,9 +56,9 @@ import { Npmextra } from '@push.rocks/npmextra'; 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' +const toolConfig = npmExtraInstance.dataFor<{ setting1: string, setting2: string }>('toolname', { + setting1: 'defaultValue1', + setting2: 'defaultValue2' }); // toolConfig now contains the merged settings from npmextra.json and provided defaults @@ -75,7 +75,10 @@ To utilize the KeyValueStore, create an instance specifying its scope (e.g., 'us ```typescript import { KeyValueStore } from '@push.rocks/npmextra'; -const kvStore = new KeyValueStore<'userHomeDir'>('userHomeDir', 'myUniqueAppName'); +const kvStore = new KeyValueStore<'userHomeDir'>({ + typeArg: 'userHomeDir', + identityArg: 'myUniqueAppName' +}); ``` You can then use the `writeKey`, `readKey`, `writeAll`, and `readAll` methods to manage your store respectively. @@ -101,57 +104,14 @@ 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. Below is an example of integrating a fictional tool named `toolname` with `npmextra`. +### Advanced Key-Value Store Management -#### Example: Tool Integration - -Imagine you have a custom tool called `toolname` that requires specific configurations. Here's how you might configure and use it with `npmextra`: - -1. Define the configuration in `npmextra.json`: - -```json -{ - "toolname": { - "configKey1": "configValue1", - "configKey2": "configValue2", - } -} -``` - -2. Access the configuration within your tool: - -```typescript -// Import npmextra -import { Npmextra } from '@push.rocks/npmextra'; - -class ToolName { - config: any; - - constructor() { - const npmExtraInstance = new Npmextra(); - this.config = npmExtraInstance.dataFor('toolname', { - configKey1: 'defaultValue1', - configKey2: 'defaultValue2' - }); - } - - run() { - // Utilize the configuration - console.log(this.config.configKey1); // Outputs: configValue1 - console.log(this.config.configKey2); // Outputs: configValue2 - } -} - -const toolInstance = new ToolName(); -toolInstance.run(); -``` - -### Advanced Key-Value Store Usage -In addition to basic read/write operations, `@push.rocks/npmextra`’s `KeyValueStore` supports advanced usage scenarios, such as mandatory keys and custom file paths. +In addition to basic read/write operations, `npmextra`’s `KeyValueStore` supports advanced scenarios like mandatory keys and custom file paths. #### Example: Mandatory Keys and Custom Paths +Consider a scenario where your application requires specific keys to be present in the KeyValueStore. You can define mandatory keys and use a custom path for your store like this: + ```typescript import { KeyValueStore } from '@push.rocks/npmextra'; @@ -186,7 +146,8 @@ console.log(allData); // Outputs: { key1: 'value1', key2: 123 } ``` ### Combining AppData and KeyValueStore -The `AppData` class extends the functionality of `KeyValueStore` by integrating environmental variables and specifying additional configurations. + +The `AppData` class extends the functionality of `KeyValueStore` by integrating environmental variables, specifying additional configurations, and providing a more structured approach to data management. #### Example: AppData Usage @@ -229,7 +190,8 @@ console.log(allSettings); // Outputs: { settingA: 'exampleValue', settingB: 100, ``` ### Error Handling and Debugging -Proper error handling ensures that your integrations with `npmextra` are robust and stable. Below are some strategies for error handling and debugging potential issues. + +Proper error handling ensures your integrations with `npmextra` are robust and stable. Below are some strategies for error handling and debugging potential issues. #### Example: Error Handling in KeyValueStore @@ -268,6 +230,7 @@ console.log(toolConfig); ``` ### Integration Tests + Writing tests ensures that your integration with `npmextra` works as expected. Below are examples of integration tests for both `Npmextra` and `KeyValueStore`. #### Example: Testing `Npmextra` Class @@ -302,7 +265,10 @@ import { KeyValueStore } from '@push.rocks/npmextra'; let kvStore: KeyValueStore<{ key1: string, key2: number }>; tap.test('should create a KeyValueStore instance', async () => { - kvStore = new KeyValueStore('userHomeDir', 'testApp'); + kvStore = new KeyValueStore({ + typeArg: 'userHomeDir', + identityArg: 'testApp' + }); expect(kvStore).toBeInstanceOf(KeyValueStore); }); @@ -322,7 +288,8 @@ tap.start(); ``` ### Summary -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. Leveraging these robust features will ensure your project is well-configured and maintainable. + +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, `npmextra` provides an efficient and streamlined solution. Leveraging these robust features will ensure your project is well-configured and maintainable. ## License and Legal Information diff --git a/ts/00_commitinfo_data.ts b/ts/00_commitinfo_data.ts index 47f3138..7771b19 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.15', - description: 'Enhances npm with additional configuration and tool management capabilities, including a key-value store for project setups.' + version: '5.0.16', + description: 'A utility to enhance npm with additional configuration, tool management capabilities, and a key-value store for project setups.' }