npm package: @guigaib/lib
Description: General purpose library
Author: GuiGaIb
Latest version: 0.4.1

# @guigaib/lib

## Table of Contents

- [Introduction](#introduction)
- [Installation](#installation)
- [Usage](#usage)
- [Components](#components)
- [Usage Examples](#usage-examples)
  - [Debouncer](#debouncer)
  - [Error Handling](#error-handling)
- [License](#license)

## Introduction

@guigaib/lib is a collection of utility TypeScript code designed to handle common tasks, including environment variables, debouncing, and error handling.

## Installation

Install the library using your favorite package manager:
npm install @guigaib/lib
or
yarn add @guigaib/lib

## Usage

Import the relevant modules and use them directly within your TypeScript project.
See the `exports` section in `the package.json` to better understand how modules are exported.

## Components

### MyEnv

MyEnv is a small Node.js utility for reading environment variables. It supports caching, default values, transformations, masking, and error handling, and can be used either with static methods or instance methods (each has its own cache).

> **Note** This library treats empty strings as if they were unset environment variables. Keep that in mind if you rely on empty strings as valid values.

#### Features

- Get or require environment variables.
- Default values and warnings if a variable isn’t set.
- Transformers (e.g., convert "true" to true, parse numbers, etc.).
- Masking sensitive values in logs.
- Per-instance or global (static) caches.
- Treat empty strings as undefined.

#### Usage

##### 1. Quick Start: require Example

```js
import { MyEnv } from "@guigaib/lib/env";

// Forcing a variable to exist:
const myToken = MyEnv.require("TOKEN");
// If TOKEN is missing or empty, it throws an EnvError.
```

##### 2. Providing a Default Value

```js
const myPort = MyEnv.require("PORT", { defaultValue: 8080 });
// If PORT is unset or empty, returns 8080 instead of throwing.
```

##### 3. Using a Transformer

```ts
const debugMode = MyEnv.require("DEBUG", {
  transformer: (v) => v === "true",
});
// If process.env.DEBUG === "true", returns true; if empty, throws because no fallback value was provided.
```

##### 4. Masking Values in Logs

```js
const secretVal = MyEnv.require("SECRET_KEY", {
  maskValue: true,
  defaultValue: "masked",
});
// If SECRET_KEY isn't set, logs: Using default value "****" for environment variable "SECRET_KEY"
```

##### 5. Distinguishing Static vs. Instance Methods

```js
const instance = new MyEnv();
instance.require("TOKEN"); // uses instance cache
MyEnv.require("TOKEN"); // uses static (global) cache
```

##### 6. `get` vs. `require`

- `get(varName, options?)`:
  Returns a **raw string** or `undefined` if the variable is unset/empty. You can optionally skip the cache by passing { force: true }.

### Debouncer

A convenient utility for rate-limiting or postponing function calls:

- Configurable timeout in milliseconds
- Callback for handling debounced executions and errors
- Ideal for expensive or frequency-limited operations

### Error Handling

Custom error framework with typed classes:

- ConfigError, ValidationError, and EnvError for specific contexts
- Maintain consistent error messages
- Optionally enforce error codes and extended validation

## Usage Examples

### Debouncer

```ts
import { Debouncer } from "@guigaib/lib";

const debouncer = Debouncer.getInstance({
  timeoutMs: 3000,
  onTimeout: () => {
    console.log("Operation completed");
  },
});
debouncer.delay();
```

### Error Handling

```ts
import { ConfigError } from "@guigaib/lib";

try {
  throw new ConfigError("Something went wrong");
} catch (error) {
  console.error(error);
}
```

## License

This project is available under the MIT License.