open-index/open-npm huggingface dataset:
npm package: @pfeiferio/check-primitives
Description: Minimal strict runtime primitive checks for JavaScript and TypeScript
Author: Pascal Pfeifer
Latest version: 1.0.1

# @pfeiferio/check-primitives

Minimal, strict runtime type checks for JavaScript / TypeScript.

This package provides **primitive validation helpers** that:

- do not coerce values
- throw deterministic errors
- are framework-agnostic
- are designed for infrastructure and boundary validation

## Installation

```bash
npm install @pfeiferio/check-primitives
````

## Usage

### Checks (return value or throw)

```ts
import {checkString, checkNumber} from '@pfeiferio/check-primitives'

const name = checkString(input.name)
const age = checkNumber(input.age)
```

### Assertions (type narrowing)

```ts
import {assertObject, assertString} from '@pfeiferio/check-primitives'

assertObject(payload)
assertString(payload.name)

// payload is now typed safely
```

## Included checks

* `checkString`
* `checkNumber` (finite only)
* `checkBoolean`
* `checkArray`
* `checkObject` (plain object)
* `checkFunction`
* `checkNull`
* `checkUndefined`

Each check has a corresponding `assert*` variant.

## Errors

All checks throw a `ValidationError` with a stable error code.

```ts
try {
  checkNumber(value)
} catch (err) {
  if (err instanceof ValidationError) {
    console.log(err.code)
  }
}
```

## Philosophy

This package intentionally does **not** include:

* format validation
* length or range constraints
* coercion or defaults
* schemas or DSLs

It is meant to be used as a **low-level building block**.

## License

MIT
npm package: @pfeiferio/ctx
Description: Minimal, type-safe execution context utilities for Node.js based on AsyncLocalStorage
Author: Pascal Pfeifer
Latest version: 1.0.0

# @pfeiferio/ctx

Minimal utilities for **execution-scoped context** in Node.js using `AsyncLocalStorage`.

`@pfeiferio/ctx` lets you safely create, access and bind logic to an asynchronous execution context — without passing state through every function.

---

## Features

* Execution-scoped context via `AsyncLocalStorage`
* Fully type-safe & generic
* Context guards (`bindToCurrentContext`)
* Works with sync **and** async code
* No dependencies

---

## Installation

```bash
npm install @pfeiferio/ctx
```

---

## Core Concepts

A **context** is data that is bound to the current asynchronous execution flow.

Typical use cases:

* request / job scoped state
* authentication or tenant data
* correlation IDs
* logging & tracing

---

## Defining a Context

```ts
type RequestContext = {
  requestId: string
  userId?: string
}
```

---

## Running Code in a Context

```ts
import { runWithContext } from '@pfeiferio/ctx'

await runWithContext<RequestContext>(
  {
    requestId: 'req-123',
    userId: 'u-42',
  },
  async () => {
    // all code here shares the same context
  }
)
```

---

## Accessing the Current Context

```ts
import { getContext } from '@pfeiferio/ctx'

const ctx = getContext<RequestContext>()

if (ctx) {
  console.log(ctx.requestId)
}
```

`getContext` returns `undefined` when called outside a context.

---

## Binding Logic to a Context

`bindToCurrentContext` ensures a function can only execute
inside the context it was created in.

```ts
import { bindToCurrentContext } from '@pfeiferio/ctx'

const sendResponse = bindToCurrentContext<
  RequestContext,
  [string],
  void
>((message) => {
  console.log('response:', message)
})
```

Later:

```ts
sendResponse('ok')      // executed (same context)
sendResponse('invalid') // no-op if context changed
```

---

## Example: Request-Scoped Logger

```ts
type LogContext = {
  requestId: string
}

const log = (msg: string) => {
  const ctx = getContext<LogContext>()
  console.log(`[${ctx?.requestId ?? 'global'}]`, msg)
}

await runWithContext<LogContext>(
  { requestId: 'req-99' },
  async () => {
    log('start')
    await doSomethingAsync()
    log('done')
  }
)
```

---

## Example: Context Guard

```ts
const guardedFn = bindToCurrentContext<
  unknown,
  [],
  void
>(() => {
  console.log('safe execution')
})

// calling outside the context → no-op
guardedFn()
```

---

## API

### `runWithContext<T, R>(ctx: T, fn: () => R): R`

Runs `fn` inside a new execution context.

---

### `getContext<T>(): T | undefined`

Returns the current context or `undefined`.

---

### `bindToCurrentContext<T, Args, R>(fn: (...args: Args) => R)`

Binds a function to the current execution context.

---

## Design Goals

* explicit over implicit
* runtime safety over magic
* no global mutable state exposure
* minimal surface area

---

## Non-Goals

* framework integration
* request lifecycle management
* cross-process context propagation

---

## License

MIT
npm package: @pfeiferio/custom-base
Description: Custom base encoding and decoding for numbers and BigInts using arbitrary charsets
Author: Pascal Pfeifer
Latest version: 1.0.1

# @pfeiferio/custom-base

Custom base encoding and decoding for numbers and BigInts using arbitrary charsets.

This library allows you to encode and decode numeric values using **any character set**.
It supports both JavaScript `number` and `bigint` types and is fully ESM-based with no dependencies.

---

## Features

- Encode / decode `number` and `bigint`
- Arbitrary custom charsets
- Built-in presets (base2, base16, base42, base128)
- Cached and validated charset handling
- Zero dependencies
- Native Node.js test runner

---

## Installation

```bash
npm install @pfeiferio/custom-base
````

---

## Usage

### Encoding and decoding numbers

```js
import { encodeNumber, decodeNumber, presets } from '@pfeiferio/custom-base'

const encoded = encodeNumber(255, presets.base16)
const decoded = decodeNumber(encoded, presets.base16)

console.log(encoded) // "ff"
console.log(decoded) // 255
```

---

### Encoding and decoding BigInts

```js
import { encodeBigInt, decodeBigInt, presets } from '@pfeiferio/custom-base'

const value = 12345678901234567890n

const encoded = encodeBigInt(value, presets.base42)
const decoded = decodeBigInt(encoded, presets.base42)

console.log(decoded === value) // true
```

---

### Custom charsets

You can provide your own charset as a string:

```js
import { encodeNumber } from '@pfeiferio/custom-base'

const charset = 'ABCDEFG123456'
const encoded = encodeNumber(1337, charset)
```

---

### Charset normalization

Internally, charsets are compiled, validated and cached.
You can normalize inputs manually if needed:

```js
import { ensureCharset, presets } from '@pfeiferio/custom-base'

const charset = ensureCharset(presets.base2)
```

The returned `Charset` object is immutable and guaranteed to be valid.

---

## Presets

```js
import { presets } from '@pfeiferio/custom-base'

presets.base2
presets.base16
presets.base42
presets.base128
```

All presets are non-standard and provided purely for convenience.

---

## Node.js Support

* Node.js ≥ 18
* ESM only

---

## License

MIT
npm package: @pfeiferio/dotpath-utils
Description: Low-level utilities for working with nested objects and dot-notation paths, including mixed object/array structures and sparse arrays
Author: Pascal Pfeifer
Latest version: 1.0.0

# @pfeiferio/dotpath-utils

Utility functions for working with nested objects and dot notation paths.

The package provides low-level helpers to get, set and transform values using dot notation paths.
It supports mixed object/array structures and handles sparse arrays correctly.

## Requirements

- Node.js >= 18
- ESM-only package

## Installation

```bash
npm install @pfeiferio/dotpath-utils
````

or

```bash
yarn add @pfeiferio/dotpath-utils
```

## Usage

### Importing the Functions

```js
import {
  getValueByPath,
  setMultipleValuesByPaths,
  setValueByPath,
  toDotNotation,
  toNestedObject
} from '@pfeiferio/dotpath-utils'
```

### Functions

#### `getValueByPath`

Retrieves a value from an object at a given dot notation path.
Returns `undefined` if the path does not exist or if the input is not an object.

```js
const obj = {a: {b: {c: 42}}}
getValueByPath(obj, 'a.b.c') // 42
```

#### `setMultipleValuesByPaths`

Sets multiple values in an object or array at given dot notation paths.

```js
const pathsAndValues = {
  '0.1.0.0': 5,
  '0.1.0.3': 6
}

setMultipleValuesByPaths([], pathsAndValues)
// → [ [ <empty>, [ [5, <empty>, <empty>, 6] ] ] ]
```

#### `setValueByPath`

Sets a value in an object at a given dot notation path.

```js
const obj = {}
setValueByPath(obj, 'a.b.c', 42)
// → { a: { b: { c: 42 } } }
```

#### `toDotNotation`

Converts a nested object or array to dot notation.

```js
toDotNotation({a: {b: {c: 42}}})
// → { 'a.b.c': 42 }
```

#### `toNestedObject`

Converts a dot notation path and value into a nested object or array.

```js
toNestedObject('a.b.c', 42)
// → { a: { b: { c: 42 } } }
```

## Tests

Tests are implemented using Node.js built-in test runner.

```bash
npm test
```
npm package: @pfeiferio/ipv4
Description: A strict, well-tested IPv4 address and network utility library for Node.js
Author: Pascal Pfeifer
Latest version: 1.1.0

# @pfeiferio/ipv4

![npm](https://img.shields.io/npm/v/@pfeiferio/ipv4)
![types](https://img.shields.io/npm/types/@pfeiferio/ipv4)
![license](https://img.shields.io/npm/l/@pfeiferio/ipv4)
![downloads](https://img.shields.io/npm/dm/@pfeiferio/ipv4)
![node](https://img.shields.io/node/v/@pfeiferio/ipv4)

Strict and well-tested IPv4 address and network utilities for Node.js.

* ESM only
* Node.js ≥ 18
* TypeScript-first
* No dependencies
* Full test coverage

---

## Installation

```bash
npm install @pfeiferio/ipv4
```

---

## Basic Usage

```js
import { ipV4 } from '@pfeiferio/ipv4'

const ip = ipV4('192.168.1.10/24')

ip.address            // "192.168.1.10"
ip.prefix             // 24
ip.addressWithCidr    // "192.168.1.10/24"
ip.toInteger()        // 3232235786
```

Default prefix is `/32`.

---

## IPv4Address examples

### Create addresses

```js
ipV4('1.1.1.1')
ipV4('1.1.1.1/32')
ipV4(3232235777)
```

### Prefix handling (immutable)

```js
const ip = ipV4('10.0.0.1')
const withPrefix = ip.withPrefix(16)

ip.addressWithCidr        // "10.0.0.1/32"
withPrefix.addressWithCidr // "10.0.0.1/16"
```

### Address comparison

```js
ip.equals(ipV4('10.0.0.1/32'))        // true
ip.isSameAddress(ipV4('10.0.0.1/8'))  // true
```

### Navigation

```js
ipV4('1.1.1.1').next().address   // "1.1.1.2"
ipV4('1.1.1.1').prev().address   // "1.1.1.0"
```

---

## IPv4Network examples

### Create networks

```js
const net = ipV4('192.168.1.10/24').network()

net.addressWithCidr   // "192.168.1.0/24"
net.size              // 256
net.hostCount         // 254
```

### Network helpers

```js
net.firstHost.address   // "192.168.1.1"
net.lastHost.address    // "192.168.1.254"
net.broadcast.address   // "192.168.1.255"
```

### Containment & relations

```js
net.contains('192.168.1.42')                 // true
net.overlaps('192.168.1.128/25')             // true
net.containsNetwork('192.168.1.128/25')      // true
net.isSubnetOf('192.168.0.0/16')              // true
net.isSupernetOf('192.168.1.128/25')          // true
```

---

## Iteration

### Usable hosts

```js
for (const host of net.hosts()) {
  console.log(host.address)
}
```

### All addresses

```js
for (const addr of net.addresses()) {
  console.log(addr.address)
}
```

---

## Utilities

```js
import { ipToInt, intToIp } from '@pfeiferio/ipv4'

ipToInt('192.168.1.1')   // 3232235777
intToIp(3232235777)      // "192.168.1.1"
```

---

## Design notes

* Prefix defaults to `/32`
* Network addresses are always normalized
* No implicit magic
* `/0`, `/31`, `/32` handled correctly

---

## License

MIT
npm package: @pfeiferio/konfi
Description: Strict JSON-based configuration loader with interpolation and merging
Author: Pascal Pfeifer
Latest version: 1.0.0

# @pfeiferio/konfi

A strict, predictable JSON-based configuration loader with interpolation and merging.

`konfi` is designed for **application startup configuration**, not runtime templating.
It focuses on deterministic behavior, explicit merging, and safe value resolution.

---

## Features

- JSON configuration files
- Recursive config merging
- Value interpolation with fixpoint resolution
- Environment variable support
- Deterministic, testable behavior
- No magic defaults, no global state
- Zero dependencies

---

## Installation

```bash
npm install @pfeiferio/konfi
````

---

## Basic Usage

```ts
import { readConfig } from '@pfeiferio/konfi'

const config = readConfig('./config.json')
```

---

## Typed Configuration (TypeScript)

`konfi` supports fully typed configuration using generics.

```ts
import { readConfig, readConfigs } from '@pfeiferio/konfi'

interface AppConfig {
  server: {
    host: string
    port: number
  }
  database: {
    url: string
  }
}

const config = readConfig<AppConfig>('./config.json')

// fully typed
config.server.host
config.server.port

```

---

## Configuration Files

A configuration file is plain JSON.

```json
{
  "server": {
    "host": "localhost",
    "port": 8080
  }
}
```

Nested structures are preserved.

---

## Interpolation

Values may reference other config values or environment variables.

```json
{
  "baseUrl": "http://${server.host}:${server.port}",
  "server": {
    "host": "localhost",
    "port": 8080
  }
}
```

Result:

```js
{
  baseUrl: "http://localhost:8080",
  server: {
    host: "localhost",
    port: 8080
  }
}
```

### Environment Variables

```json
{
  "db": {
    "password": "${env.DB_PASSWORD}"
  }
}
```

---

## Multiple Config Files

You can load and merge multiple config files in order:

```ts
import { readConfigs } from '@pfeiferio/konfi'

const config = readConfigs([
  './config.base.json',
  './config.prod.json'
])
```

Later files override earlier ones using strict merge rules.

---

## Merge Semantics

* Plain objects are merged recursively
* Arrays are overwritten
* Primitives overwrite previous values
* Inputs are never mutated

This makes configuration behavior explicit and predictable.

---

## Error Handling

* Invalid JSON throws immediately
* Circular or unresolved interpolation fails deterministically
* No silent fallbacks

Configuration errors are intended to surface **at startup**, not at runtime.

---

## Design Goals

* Explicit configuration
* Deterministic startup behavior
* No implicit defaults
* Easy to reason about
* Suitable for backend and service configuration

`konfi` is **not**:

* a template engine
* a dotenv replacement
* a runtime configuration system

---

## License

MIT
npm package: @pfeiferio/message-resolver
Description: Context-based message resolution with priority selectors
Author: Pascal Pfeifer
Latest version: 1.0.0

# @pfeiferio/message-resolver

Resolve messages deterministically based on structured selectors and ordered priorities.

`@pfeiferio/message-resolver` is a small utility for selecting the **best matching message**
from a set of candidates using attribute-based selectors and an explicit priority order.

It is designed for applications that need **predictable message resolution logic**
without introducing a full rule engine or i18n framework.

---

## Features

* Attribute-based selectors (e.g. `[type=email][scope=register]`)
* Deterministic priority resolution
* Fast selector matching using bit masks
* Optional placeholder replacement
* No side effects, no global state

---

## Installation

```bash
npm install @pfeiferio/message-resolver
```

---

## Basic usage

### Define messages

```js
const messages = {
  '[type=email]': {
    email: 'email error'
  },
  '[scope=register]': {
    email: 'register email error'
  }
}
```

### Define priority order

```js
const priorities = ['type', 'scope']
```

The order defines the relative priority of selector attributes.
Attributes listed later have higher priority.

---

### Create a resolver

```js
import { MessageResolver } from '@pfeiferio/message-resolver'

const resolver = new MessageResolver(messages, priorities)
```

---

## Resolving messages

```js
const result = resolver.find(
  { type: 'email', scope: 'register' },
  'email'
)

console.log(result.message)
// → "register email error"
```
If no message matches, `find()` returns `null`.


If multiple selectors match, the resolver chooses the message
with the **highest priority based on the configured order**.

---

## Selector semantics

Selectors use a simple attribute syntax:

```txt
[type=email][scope=register]
```

A selector matches if **all attributes** are present in the identifier object.

```js
selector.test({ type: 'email', scope: 'register' }) // true
selector.test({ type: 'email' })                    // false
```

---

## Placeholder interpolation (optional)

`@pfeiferio/message-resolver` does not perform placeholder interpolation by itself.

If a resolved message contains placeholders, they can be interpolated explicitly
using a separate library such as `@pfeiferio/string-interpolate`.

```js
import { interpolate } from '@pfeiferio/string-interpolate'

const result = resolver.find({ type: 'email' }, 'email')
const message = interpolate(result.message, { type: 'email' })
```

Unresolved placeholders are left untouched.

---

## What this package is *not*

* ❌ Not a message broker
* ❌ Not a logger
* ❌ Not an i18n framework
* ❌ Not a rule engine

This package focuses on **deterministic message resolution only**.

---

## Mental model

> Given a set of messages and a context,
> resolve exactly one message in a predictable way.

---

## License

MIT
npm package: @pfeiferio/object-utils
Description: Small, predictable utilities for working with plain JavaScript objects
Author: Pascal Pfeifer
Latest version: 1.1.1

# @pfeiferio/object-utils

Small, predictable utility functions for working with plain JavaScript objects.

This package provides a minimal set of helpers for **object inspection and deep merging** with strict, explicit behavior and zero dependencies.

---

## Installation

```bash
npm install @pfeiferio/object-utils
````

---

## Usage

```ts
import {
  isObject,
  isPlainObject,
  mergeObjects
} from '@pfeiferio/object-utils'
```

---

## `isObject(value)`

Checks whether a value is a **non-null object**, excluding arrays.

```ts
isObject({})        // true
isObject([])        // false
isObject(null)      // false
isObject('string')  // false
```

This is a safe alternative to `typeof value === 'object'`.

---

## `isPlainObject(value)`

Checks whether a value is a **plain object**.

A plain object is defined as:

* created via object literal (`{}`)
* or `Object.create(null)`

```ts
isPlainObject({})                  // true
isPlainObject(Object.create(null)) // true

isPlainObject([])                  // false
isPlainObject(new Date())          // false
isPlainObject(null)                // false
```

Useful for merge logic and configuration handling.

---

## `mergeObjects(a, b)`

Deeply merges two values.

* **Only plain objects** are merged recursively
* All other values **overwrite**
* Inputs are **never mutated**

```ts
mergeObjects(
  { server: { host: 'example.com' } },
  { server: { port: 80 } }
)
// → { server: { host: 'example.com', port: 80 } }
```

### Overwrite behavior

```ts
mergeObjects(
  { a: { b: 1 } },
  { a: 2 }
)
// → { a: 2 }
```

```ts
mergeObjects(
  { list: [1, 2] },
  { list: [3] }
)
// → { list: [3] }
```

### Non-plain values always win

```ts
mergeObjects(
  { a: { b: 1 } },
  null
)
// → null
```

---

## Design Principles

* Explicit semantics
* No array merging
* No mutation
* Predictable results
* Suitable for configuration and business logic

This package intentionally avoids:

* implicit deep cloning
* class instance merging
* array merging heuristics

---

## License

MIT