{"id":15979,"library":"caseless","title":"Caseless Object Access","description":"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.","status":"maintenance","version":"0.12.0","language":"javascript","source_language":"en","source_url":"https://github.com/mikeal/caseless","tags":["javascript","headers","http","caseless"],"install":[{"cmd":"npm install caseless","lang":"bash","label":"npm"},{"cmd":"yarn add caseless","lang":"bash","label":"yarn"},{"cmd":"pnpm add caseless","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { caseless } from 'caseless';","symbol":"caseless","correct":"import caseless from 'caseless';"},{"note":"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.","wrong":"const { caseless } = require('caseless');","symbol":"caseless (CommonJS)","correct":"const caseless = require('caseless');"},{"note":"Caseless is a factory function, not a class constructor. It should be called directly without the `new` keyword.","wrong":"const c = new caseless(myObject);","symbol":"Instance creation","correct":"const c = caseless(myObject);"}],"quickstart":{"code":"import caseless from 'caseless';\n\nconst myHeaders = {};\nconst caselessProxy = caseless(myHeaders);\n\n// Set a header with specific casing\ncaselessProxy.set('X-Request-ID', 'abc-123');\ncaselessProxy.set('Content-Type', 'application/json');\n\n// Get a header using any casing\nconsole.log(caselessProxy.get('x-request-id')); // Expected: 'abc-123'\nconsole.log(caselessProxy.get('content-type')); // Expected: 'application/json'\n\n// Check if a header exists and retrieve its preserved casing\nconsole.log(caselessProxy.has('content-type')); // Expected: 'Content-Type'\n\n// Demonstrate the clobber=false behavior for appending values\ncaselessProxy.set('Accept', 'application/xml');\ncaselessProxy.set('accept', 'application/json', false); // Append without clobbering\nconsole.log(caselessProxy.get('accept')); // Expected: 'application/xml,application/json'\n\nconsole.log('Original headers object:', myHeaders);","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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()`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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);`.","cause":"Attempting to import `caseless` as a named export (`import { caseless } from 'caseless'`) or calling `new caseless()` when it is a factory function.","error":"TypeError: caseless is not a function"},{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'set') or similar when calling methods on a caseless instance."}],"ecosystem":"npm"}