open-index/open-npm huggingface dataset:
npm package: @fimbul-works/process-signals
Description: A tiny TypeScript utility for handling process signals and graceful shutdowns
Author: FimbulWorks
Latest version: 1.0.0

# @fimbul-works/process-signals

A tiny TypeScript utility for handling process signals and graceful shutdowns.

[![npm version](https://badge.fury.io/js/%40fimbul-works%2Fprocess-signals.svg)](https://www.npmjs.com/package/@fimbul-works/process-signals)
[![TypeScript](https://badges.frapsoft.com/typescript/code/typescript.svg?v=101)](https://github.com/microsoft/TypeScript)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

- 🛡️ Handles both signals (`SIGTERM`, `SIGINT`, etc.) and unhandled errors (`uncaughtException`, `unhandledRejection`)
- 🔍 Written in TypeScript with full type definitions
- 📦 Tiny footprint with zero dependencies

## Installation

```bash
npm install @fimbul-works/process-signals
```

## Quick Start

### Graceful Shutdown
The easiest way to ensure your app cleans up before exiting. It handles common termination signals and unhandled errors.

```ts
import { shutdownGracefully } from '@fimbul-works/process-signals';

shutdownGracefully(async (value) => {
  if (value instanceof Error) {
    console.error('Unhandled error:', value);
  }
  console.log('Shutting down...');
  await db.disconnect();
  await server.close();
  console.log('Cleanup complete.');
});
```

### Listen for a Signal
If you just want to wait for the first signal to occur.

```ts
import { listenForSignal } from '@fimbul-works/process-signals';

const { signal, value } = await listenForSignal(['SIGINT', 'SIGTERM']);
console.log(`Received ${signal}`);
```

## API

### `shutdownGracefully(handler)`
Sets up a global listener for common shutdown signals (`SIGINT`, `SIGTERM`, `SIGQUIT`, `SIGHUP`) and unhandled errors (`uncaughtException`, `unhandledRejection`).

- **handler**: `(value: unknown) => Promise<void>`
  - An async function that runs before the process exits.
  - Receives the signal name or the error object that triggered the shutdown.
- **Returns**: `Promise<never>`
  - This promise never settles. The function terminates the process with code `0` (success) or `1` (error/exception) after the handler finishes.

### `listenForSignal(signals?)`
Listens for the first occurrence of any provided signals and resolves.

- **signals**: `string[]` (Optional)
  - Array of signals to listen for. Defaults to `["SIGINT", "SIGTERM", "SIGQUIT", "SIGHUP"]`.
- **Returns**: `Promise<{ signal: string, value: unknown }>`
  - `signal`: The name of the signal that was caught.
  - `value`: The value provided by the runtime (e.g., the error object for exceptions).

## License

MIT License - See [LICENSE](LICENSE) file for details.

---

Built with ⚡ by [FimbulWorks](https://github.com/fimbul-works)
npm package: @fimbul-works/zodenv
Description: A tiny TypeScript utility for parsing and validating environment variables using Zod.
Author: FimbulWorks
Latest version: 1.1.0

# @fimbul-works/zodenv

A tiny TypeScript utility for parsing and validating environment variables using [Zod](https://github.com/colinhacks/zod).

[![npm version](https://badge.fury.io/js/%40fimbul-works%2Fzodenv.svg)](https://www.npmjs.com/package/@fimbul-works/zodenv)
[![TypeScript](https://badges.frapsoft.com/typescript/code/typescript.svg?v=101)](https://github.com/microsoft/TypeScript)

## Features

- 🎯 **Type-safe environment validation** using Zod schemas
- 📝 **Clear error messages** with detailed validation feedback
- 🚀 **Zero configuration** - works out of the box with `process.env`
- 🔄 **Configurable** - throw errors, exit the process, or stay silent
- 🔍 **TypeScript first** - full type inference from your schemas

## Installation

```bash
npm install @fimbul-works/zodenv zod picocolors
```

## Quick Start

```ts
import { z } from "zod";
import { parseEnv } from "@fimbul-works/zodenv";

const env = parseEnv(
  z.object({
    NODE_ENV: z.enum(["development", "test", "production"]),
    PORT: z.string().default("3000"),
    DEBUG: z.boolean().optional(),
  }),
);

console.log(env.NODE_ENV); // fully typed!
console.log(env.PORT);     // string (default: "3000")
```

If validation fails, you’ll see a nicely formatted error:

```
Invalid Environment Configuration:
NODE_ENV: "staging"
  Invalid option: expected one of "development"|"test"|"production"
```

## Options

`parseEnv(schema, options?)`

| Option        | Type                     | Default       | Description                                          |
| ------------- | ------------------------ | ------------- | ---------------------------------------------------- |
| `env`         | `Record<string,unknown>` | `process.env` | Source of variables                                  |
| `exitOnError` | `boolean`                | `true`        | Whether to call `process.exit` on validation failure |
| `exitCode`    | `number`                 | `1`           | Exit code when `exitOnError` is `true`               |
| `colors`      | `boolean`                | `true`        | Enable/disable colored error output                  |

## Custom Error Handling

If you’d rather throw errors instead of exiting:

```ts
const env = parseEnv(schema, { exitOnError: false });

try {
  // ...
} catch (err) {
  console.error("Environment validation failed", err);
}
```

## Using in Tests

You can pass a custom `env` object for isolation:

```ts
const env = parseEnv(
  schema,
  { env: { NODE_ENV: "test", PORT: "4000" }, exitOnError: false }
);
```

## License

MIT License - See [LICENSE](LICENSE) file for details.

---

Built with ⚡ by [FimbulWorks](https://github.com/fimbul-works)