ldx
Version:
Enhancing logging developer experience
230 lines (145 loc) • 4.45 kB
Markdown
# LDX - Logging Developer Experience
A lightweight tool to enhance your development workflow by processing command output with customizable transformations.
## Features
- **Custom static transformations**: Define string patterns in your command output and replace them with custom messages.
- **Custom dynamic transformations**: Supports function-based transformations
- **Easy Integration**: Works seamlessly with any command-line tool or script.
- **Developer-Friendly**: Improves readability and reduces noise in logs.
## Installation
To install LDX globally, run:
```bash
pnpm install -g ldx
```
Alternatively, you can install it locally in your project:
```bash
pnpm install --save-dev ldx
```
## Usage
### 1. Create a Configuration File
Create a `ldx.config.js` file in your project's root directory. This file defines the patterns and transformations for your command output.
Example:
```js
module.exports = {
// Simple string replacement
"Test match 1": "✅ Test match 1 processed",
// Function-based processing
"Function match": (line) => `Processed: ${line}`,
};
```
### 2. Run Commands with LDX
Use LDX to run your commands and transform their output:
```bash
ldx <your-command>
```
For example:
```bash
ldx pnpm run dev
```
## Configuration Options
### String Matching
```js
module.exports = {
"String contained in output line": "Replacement text for the entire line"
}
```
### Function Processing
```js
module.exports = {
"String contained in output line": (line) => {
// Custom processing logic
return `Formatted: ${line}`;
}
}
```
## Requirements
- Node.js >= 18.0.0
## Error Handling
LDX provides clear error messages for common issues:
### Missing Configuration File
If `ldx.config.js` is not found in your project root:
```text
Oops, no ldx.config.js file found!
```
**Solution**: Create a `ldx.config.js` file in your project root. You can copy `ldx.config.example.js` as a starting point.
### Invalid Configuration
If your configuration has invalid values:
```text
LDX: Configuration error - Invalid value type for key "myKey". Expected string or function, got number.
```
**Solution**: Ensure all configuration values are either strings or functions.
### Empty Configuration
If your configuration object is empty:
```text
LDX: Configuration error - Configuration cannot be empty.
```
**Solution**: Add at least one pattern-transformation pair to your configuration.
### Command Not Found
If the command you're trying to run doesn't exist:
```text
Error executing command: Failed to start command: spawn xyz ENOENT
```
**Solution**: Verify the command exists and is in your PATH.
### Function Processing Errors
If a transformer function throws an error, LDX will:
1. Log a warning: `LDX: provided function errored: <error message>`
2. Output the original unprocessed line (to prevent data loss)
**Solution**: Add try-catch blocks in your transformer functions for graceful error handling.
## Testing
Run tests with:
```bash
pnpm test
```
## Usage examples
### Basic Usage
```bash
ldx echo "Testing LDX tool"
```
### With package manager scripts
```bash
ldx pnpm run dev
```
### With complex commands
```bash
ldx docker-compose up
```
## Development
1. Clone the repository
2. Install dependencies:
```bash
pnpm i
```
3. Make changes
4. Run tests:
```bash
pnpm test
```
## Releasing
This project uses [standard-version](https://github.com/conventional-changelog/standard-version) for automated versioning and changelog generation based on [Conventional Commits](https://www.conventionalcommits.org/).
### Commit Message Format
```text
<type>(<scope>): <description>
[optional body]
[optional footer(s)]
```
Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`, `ci`, `build`
Examples:
```bash
git commit -m "feat: add support for regex patterns"
git commit -m "fix: handle empty lines in output"
git commit -m "docs: update configuration examples"
```
### Creating a Release
```bash
# Automatic version bump based on commits (recommended)
pnpm release
# Specific version bumps
pnpm release:patch # 1.0.2 -> 1.0.3
pnpm release:minor # 1.0.2 -> 1.1.0
pnpm release:major # 1.0.2 -> 2.0.0
```
After running the release command:
```bash
git push --follow-tags origin main && npm publish
```
## Contributing
Contributions are welcome! Please open issues or pull requests in this repo.