CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-is-plain-obj

Check if a value is a plain object

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

is-plain-obj

is-plain-obj is a lightweight utility that checks if a value is a plain object. A plain object is one created by {}, new Object(), or Object.create(null). This package provides cross-realm detection, making it reliable across different JavaScript execution contexts.

Package Information

  • Package Name: is-plain-obj
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install is-plain-obj

Core Imports

import isPlainObject from 'is-plain-obj';

Note: This package is ES Module only and does not support CommonJS (require()).

Basic Usage

import isPlainObject from 'is-plain-obj';

// Plain objects return true
isPlainObject({foo: 'bar'});           // => true
isPlainObject(new Object());           // => true
isPlainObject(Object.create(null));    // => true

// Non-plain objects return false
isPlainObject([1, 2, 3]);              // => false
isPlainObject(new Date());             // => false
isPlainObject(Math);                   // => false
isPlainObject(null);                   // => false

Capabilities

Plain Object Detection

Determines whether a value is a plain object using prototype chain analysis.

/**
 * Check if a value is a plain object.
 * 
 * An object is plain if it's created by either `{}`, `new Object()`, or `Object.create(null)`.
 * Works correctly across different JavaScript execution contexts (realms).
 *
 * @param value - The value to check
 * @returns True if the value is a plain object, false otherwise
 */
function isPlainObject<Value>(value: unknown): value is Record<PropertyKey, Value>;

Parameters:

  • value (unknown): The value to test

Returns:

  • boolean: true if the value is a plain object, false otherwise
  • TypeScript: Acts as a type predicate, narrowing the type to Record<PropertyKey, Value>

Usage Examples:

import isPlainObject from 'is-plain-obj';
import {runInNewContext} from 'node:vm';

// Plain objects (return true)
isPlainObject({});                     // => true
isPlainObject({foo: 'bar'});          // => true
isPlainObject({constructor: Object}); // => true
isPlainObject({valueOf: 0});          // => true
isPlainObject(new Object());          // => true
isPlainObject(Object.create(null));   // => true

// Cross-realm support
isPlainObject(runInNewContext('({})'));  // => true

// Non-plain objects (return false)
isPlainObject(['foo', 'bar']);        // => false
isPlainObject(new Date());            // => false
isPlainObject(new Map());             // => false
isPlainObject(Math);                  // => false
isPlainObject(JSON);                  // => false
isPlainObject(() => {});              // => false
isPlainObject(/regex/);               // => false

// Primitives (return false)
isPlainObject(null);                  // => false
isPlainObject(undefined);             // => false
isPlainObject('string');              // => false
isPlainObject(42);                    // => false
isPlainObject(true);                  // => false

// Class instances (return false)
class CustomClass {}
isPlainObject(new CustomClass());     // => false

// Arguments object (return false)
(function() {
  isPlainObject(arguments);           // => false
})();

// Objects with custom prototypes (return false)
isPlainObject(Object.create({}));     // => false

Types

/**
 * Generic type parameter representing the type of values in the plain object
 */
type Value = unknown;

Built-in TypeScript Types Used:

  • PropertyKey: Built-in type representing string | number | symbol
  • Record<K, T>: Built-in utility type representing an object with keys of type K and values of type T

Implementation Details

The function uses several techniques to ensure accurate detection:

  1. Type Check: First checks if the value is an object and not null
  2. Prototype Analysis: Uses Object.getPrototypeOf() to examine the prototype chain
  3. Plain Object Criteria: Accepts objects with:
    • null prototype (from Object.create(null))
    • Object.prototype as prototype (from {} or new Object())
    • Objects whose prototype's prototype is null (handles cross-realm scenarios)
  4. Symbol Exclusion: Rejects objects with Symbol.toStringTag or Symbol.iterator
  5. Cross-Realm Support: Works correctly across different JavaScript execution contexts

Error Handling

This function does not throw errors. It safely handles all input types and returns a boolean result for any value passed to it.

docs

index.md

tile.json