@guigaib/lib

Table of Contents

• Introduction
• Installation
• Usage
• Components
• Usage Examples
  • Debouncer
  • Error Handling
• 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

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

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

3. Using a Transformer

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

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

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

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

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

Error Handling

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.