push.rocks/npmextra
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(core): update

Browse Source
This commit is contained in:
Philipp Kunz
2024-06-12 20:10:19 +02:00
parent b342602ca0
commit 2ca82fb28b
5 changed files with 265 additions and 271 deletions
Download Patch File Download Diff File Expand all files Collapse all files

235
readme.md
View File

@@ -1,5 +1,5 @@
# @push.rocks/npmextra
Enhances npm with additional configuration and tool management capabilities.
Enhances npm with additional configuration and tool management capabilities, including a key-value store for project setups.
## Install
To install `@push.rocks/npmextra`, use the following npm command:
@@ -11,7 +11,7 @@ npm install @push.rocks/npmextra --save
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.
`@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:
@@ -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.
`@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.
#### Creating and Utilizing `npmextra.json`
@@ -49,13 +49,13 @@ For example, to configure a hypothetical tool named `toolname`, define its setti
With the configuration defined, you can easily access these settings in your TypeScript code as follows:
```typescript
// import the npmextra module
// Import the npmextra module
import { Npmextra } from '@push.rocks/npmextra';
// create an instance pointing at the current directory
// 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
// Retrieve the configuration for 'toolname', merging defaults with any found in npmextra.json
const toolConfig = npmExtraInstance.dataFor('toolname', {
defaultKey1: 'defaultValue1',
defaultKey2: 'defaultValue2'
@@ -102,12 +102,227 @@ 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.
`@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`.
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.
#### Example: Tool Integration
### 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.
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.
#### Example: Mandatory Keys and Custom Paths
```typescript
import { KeyValueStore } from '@push.rocks/npmextra';
interface CustomData {
key1: string;
key2: number;
key3?: boolean;
}
const kvStore = new KeyValueStore<CustomData>({
typeArg: 'custom',
identityArg: 'customApp',
customPath: '/custom/path/to/store.json',
mandatoryKeys: ['key1', 'key2']
});
// Ensure all mandatory keys are present
const missingKeys = await kvStore.getMissingMandatoryKeys();
if (missingKeys.length) {
console.log(`Missing mandatory keys: ${missingKeys.join(', ')}`);
}
// Use the KeyValueStore
await kvStore.writeKey('key1', 'value1');
await kvStore.writeKey('key2', 123);
const key1Value = await kvStore.readKey('key1');
const allData = await kvStore.readAll();
console.log(key1Value); // Outputs: value1
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.
#### Example: AppData Usage
```typescript
import { AppData } from '@push.rocks/npmextra';
interface AppSettings {
settingA: string;
settingB: number;
nestedSetting: {
innerSetting: boolean;
}
}
const appDataInstance = await AppData.createAndInit<AppSettings>({
dirPath: '/custom/path/to/appdata',
requiredKeys: ['settingA', 'settingB'],
envMapping: {
settingA: 'MY_ENV_A',
settingB: 'hard:42',
nestedSetting: {
innerSetting: 'MY_ENV_INNER'
}
}
});
const appDataKvStore = await appDataInstance.getKvStore();
// Writing values
await appDataKvStore.writeKey('settingA', 'exampleValue');
await appDataKvStore.writeKey('settingB', 100);
await appDataKvStore.writeKey('nestedSetting', { innerSetting: true });
// Reading values
const settingA = await appDataKvStore.readKey('settingA');
const allSettings = await appDataKvStore.readAll();
console.log(settingA); // Outputs: 'exampleValue'
console.log(allSettings); // Outputs: { settingA: 'exampleValue', settingB: 100, nestedSetting: { innerSetting: true } }
```
### 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.
#### Example: Error Handling in KeyValueStore
```typescript
import { KeyValueStore } from '@push.rocks/npmextra';
const kvStore = new KeyValueStore('userHomeDir', 'errorHandlingApp');
try {
await kvStore.writeKey('importantKey', 'importantValue');
const value = await kvStore.readKey('importantKey');
console.log(value); // Outputs: importantValue
} catch (error) {
console.error('Error managing key-value store:', error);
}
```
#### Debugging Configuration Issues in `npmextra.json`
To debug configuration issues, you can utilize conditional logging and checks:
```typescript
import { Npmextra } from '@push.rocks/npmextra';
const npmExtraInstance = new Npmextra();
const toolConfig = npmExtraInstance.dataFor('toolname', {
configKey1: 'defaultValue1',
configKey2: 'defaultValue2'
});
if (!toolConfig.configKey1) {
console.error('configKey1 is missing in npmextra.json');
}
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
```typescript
import { expect, tap } from '@push.rocks/tapbundle';
import { Npmextra } from '@push.rocks/npmextra';
let npmExtraInstance: Npmextra;
tap.test('should create an instance of Npmextra', async () => {
npmExtraInstance = new Npmextra();
expect(npmExtraInstance).toBeInstanceOf(Npmextra);
});
tap.test('should load configuration from npmextra.json', async () => {
const config = npmExtraInstance.dataFor('toolname', {
defaultKey1: 'defaultValue1',
});
expect(config).toHaveProperty('defaultKey1');
});
tap.start();
```
#### Example: Testing `KeyValueStore` Class
```typescript
import { expect, tap } from '@push.rocks/tapbundle';
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');
expect(kvStore).toBeInstanceOf(KeyValueStore);
});
tap.test('should write and read back a value', async () => {
await kvStore.writeKey('key1', 'value1');
const result = await kvStore.readKey('key1');
expect(result).toEqual('value1');
});
tap.test('should write and read back multiple values', async () => {
await kvStore.writeAll({ key1: 'updatedValue1', key2: 2 });
const result = await kvStore.readAll();
expect(result).toEqual({ key1: 'updatedValue1', key2: 2 });
});
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.
## License and Legal Information