Caseless Object Access

0.12.0 · maintenance · verified Tue Apr 21

Caseless is a JavaScript utility library designed to simplify interaction with objects, particularly HTTP headers, by providing caseless property access while preserving the original casing of the first-set key. This allows developers to retrieve or check for properties like 'Content-Type' using 'content-type' without explicit case manipulation. The current stable version is 0.12.0, indicating a mature, focused API that has likely been stable for some time, rather than undergoing rapid, frequent updates. Its primary differentiator is the unique combination of caseless lookup with the preservation of the original key casing, which is critical for scenarios where the exact string representation of a header might matter for display or specific protocol interpretations, even if its semantic meaning is case-insensitive. The library wraps a standard JavaScript object, adding a thin layer of caseless semantics without mutating the underlying data structure in unexpected ways.

Common errors

```
TypeError: caseless is not a function
```
cause Attempting to import `caseless` as a named export (`import { caseless } from 'caseless'`) or calling `new caseless()` when it is a factory function.

fix Use a default import (`import caseless from 'caseless';`) for ESM or `const caseless = require('caseless');` for CommonJS, then call it as a function: `const c = caseless(myObject);`.
```
TypeError: Cannot read properties of undefined (reading 'set') or similar when calling methods on a caseless instance.
```
cause The `caseless` instance was not correctly created or assigned. This often happens if `caseless(myObject)` was not called, or its return value was not captured.

fix Verify that `const c = caseless(myObject);` was successfully executed and that you are calling methods like `c.set()` or `c.get()` on the `c` variable.

Warnings

gotcha The `set` method accepts an optional third parameter `clobber`. If set to `false` (default is `true`), subsequent calls to `set` for an existing key will append the new value as a comma-separated string instead of overwriting the original value. This behavior is specific and might be unexpected if not explicitly handled.
Fix: Always explicitly define the `clobber` parameter in `set(key, value, clobber)` if you require a specific behavior regarding overwriting or appending values, especially when dealing with multi-valued HTTP headers.
gotcha The library is a factory function that returns a proxy object. It does not operate directly on the passed object in place, nor does it return a new object clone. Operations like `set`, `get`, `has` are performed via the caseless wrapper, which then reflects changes on the original object.
Fix: Ensure you use the return value of `caseless(myObject)` (e.g., `const c = caseless(myObject)`) for all caseless operations. The original `myObject` will be modified by calls to `c.set()`.

Install

npm install caseless npm
yarn add caseless yarn
pnpm add caseless pnpm

Imports

caseless
wrong:
```
import { caseless } from 'caseless';
```
correct:
```
import caseless from 'caseless';
```
The library primarily offers a default export which is a factory function. Attempting to destructure it as a named export will result in an error.
caseless (CommonJS)
wrong:
```
const { caseless } = require('caseless');
```
correct:
```
const caseless = require('caseless');
```
For CommonJS environments, the module's main export is the factory function itself. Incorrectly trying to access it as a property of the required module will fail.
Instance creation
wrong:
```
const c = new caseless(myObject);
```
correct:
```
const c = caseless(myObject);
```
Caseless is a factory function, not a class constructor. It should be called directly without the `new` keyword.

Quickstart

This quickstart demonstrates how to initialize caseless with a plain object, set and get properties using caseless access, check for property existence while preserving original casing, and showcases the `clobber` option for appending values to existing properties.

import caseless from 'caseless';

const myHeaders = {};
const caselessProxy = caseless(myHeaders);

// Set a header with specific casing
caselessProxy.set('X-Request-ID', 'abc-123');
caselessProxy.set('Content-Type', 'application/json');

// Get a header using any casing
console.log(caselessProxy.get('x-request-id')); // Expected: 'abc-123'
console.log(caselessProxy.get('content-type')); // Expected: 'application/json'

// Check if a header exists and retrieve its preserved casing
console.log(caselessProxy.has('content-type')); // Expected: 'Content-Type'

// Demonstrate the clobber=false behavior for appending values
caselessProxy.set('Accept', 'application/xml');
caselessProxy.set('accept', 'application/json', false); // Append without clobbering
console.log(caselessProxy.get('accept')); // Expected: 'application/xml,application/json'

console.log('Original headers object:', myHeaders);

view raw JSON →