Proto-list Utility

Common errors

• TypeError: Cannot read properties of undefined (reading 'someProp')

  cause This error often occurs when `ProtoList.get()` or direct property access attempts to retrieve a property that simply does not exist in any object within the prototype chain.
  fix Ensure that the property you are trying to access actually exists in one of the objects added to the `ProtoList`. `ProtoList` does not throw an error for non-existent properties but returns `undefined` (like standard object property access). This error would typically indicate you're trying to use `undefined` as if it were an object.

• Unexpected property resolution order or missing properties when using Object.assign or spread operator

  cause Attempting to merge a `ProtoList` instance with other objects using `Object.assign` or the spread operator (`{ ...myProtoList }`) will not flatten its internal prototype chain. These operations only copy enumerable own properties directly from the `ProtoList` instance, not the properties inherited through its managed prototype chain.
  fix If you need a flattened object representing the resolved configuration, you must iterate through the keys you care about or implement a custom flattening logic that uses `ProtoList.get()` for each key. For example, `Object.keys(defaults).reduce((acc, key) => ({ ...acc, [key]: config.get(key) }), {});`

Warnings

• gotcha Understanding the core mechanism: `proto-list` works by dynamically constructing a prototype chain from the objects you add. When you access a property on the `ProtoList` instance (either directly or via `.get()`), it traverses this internal prototype chain until it finds the property. This is different from merging objects or using a simple Map.
  Fix: Thoroughly review the library's source or documentation to grasp how property lookups and the internal prototype chain are managed. Be aware that methods like `Object.keys()` on the `ProtoList` instance itself will not reflect the aggregated properties from its internal chain, but rather only its own direct properties and methods.
• gotcha The library directly manipulates JavaScript's prototype chain. Developers unfamiliar with prototype-based inheritance or those accustomed to class-based patterns might find its behavior counter-intuitive. Unexpected behavior can occur if the objects added to the list contain getters/setters or methods that rely on a specific `this` context that might be altered by the chain traversal.
  Fix: Test thoroughly when adding complex objects or objects with non-plain data (e.g., getters, methods). Ensure that the prototype chain manipulation aligns with expected object behavior and avoid assumptions about `this` binding unless explicitly handled.
• deprecated The package was last published 11 years ago, making it an extremely mature but potentially unmaintained library. While stable and used by critical projects like npm, it may not receive updates for new JavaScript features, security vulnerabilities, or modern ecosystem changes.
  Fix: Use with caution and consider the implications of relying on a long-unmaintained package. For new projects, evaluate modern alternatives that achieve similar layered configuration or prototype-like behavior with more active development and community support. Regularly check for known vulnerabilities in `npm audit`.

Install

• npm install proto-list npm
• yarn add proto-list yarn
• pnpm add proto-list pnpm

Imports

• ProtoList
  wrong:

  import { ProtoList } from 'proto-list';

  correct:

  import ProtoList from 'proto-list';

  The 'proto-list' package exports the ProtoList class as its default export, even though it's typically used like a named class. Direct default import is the correct ESM pattern, while older CommonJS would use `require('proto-list')` to get the class constructor.
• ProtoList (CommonJS)

  const ProtoList = require('proto-list');

  For older Node.js environments or CommonJS modules, use the `require` syntax. The package does not offer named exports for CJS.

Quickstart

This quickstart demonstrates how to create a `ProtoList` instance, add multiple configuration layers (objects) with varying priorities, and retrieve values using both the `.get()` method and direct property access, illustrating the prototype chain resolution.

import ProtoList from 'proto-list';

// Create a new ProtoList instance
const config = new ProtoList();

// Add configuration layers (objects) to the list
const defaults = { cache: true, loglevel: 'info', timeout: 5000 };
const userConfig = { loglevel: 'verbose', registry: 'https://registry.npmjs.org/' };
const projectConfig = { timeout: 10000, private: true };

config.add(defaults, 'defaults'); // Add the base defaults layer
config.add(userConfig, 'user');   // Add user-specific overrides
config.add(projectConfig, 'project'); // Add project-specific overrides

console.log('Cache setting:', config.get('cache'));       // Should be 'true' from defaults
console.log('Log Level:', config.get('loglevel'));     // Should be 'verbose' from userConfig (overrides defaults)
console.log('Timeout:', config.get('timeout'));         // Should be '10000' from projectConfig (overrides user/defaults)
console.log('Registry:', config.get('registry'));       // Should be 'https://registry.npmjs.org/' from userConfig
console.log('Private:', config.get('private'));         // Should be 'true' from projectConfig

// Demonstrating direct property access (falls through prototype chain)
console.log('Direct access for cache:', config.cache); // Accesses the property via the internal prototype chain

// The .get() method and direct property access use the same prototype chain lookup logic.