0
# is-plain-obj
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: is-plain-obj
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install is-plain-obj`
10

11
## Core Imports
12

13
```javascript
14
import isPlainObject from 'is-plain-obj';
15
```
16

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

19
## Basic Usage
20

21
```javascript
22
import isPlainObject from 'is-plain-obj';
23

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

29
// Non-plain objects return false
30
isPlainObject([1, 2, 3]);              // => false
31
isPlainObject(new Date());             // => false
32
isPlainObject(Math);                   // => false
33
isPlainObject(null);                   // => false
34
```
35

36
## Capabilities
37

38
### Plain Object Detection
39

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

42
```typescript { .api }
43
/**
44
 * Check if a value is a plain object.
45
 * 
46
 * An object is plain if it's created by either `{}`, `new Object()`, or `Object.create(null)`.
47
 * Works correctly across different JavaScript execution contexts (realms).
48
 *
49
 * @param value - The value to check
50
 * @returns True if the value is a plain object, false otherwise
51
 */
52
function isPlainObject<Value>(value: unknown): value is Record<PropertyKey, Value>;
53
```
54

55
**Parameters:**
56
- `value` (unknown): The value to test
57

58
**Returns:**
59
- `boolean`: `true` if the value is a plain object, `false` otherwise
60
- **TypeScript**: Acts as a type predicate, narrowing the type to `Record<PropertyKey, Value>`
61

62
**Usage Examples:**
63

64
```javascript
65
import isPlainObject from 'is-plain-obj';
66
import {runInNewContext} from 'node:vm';
67

68
// Plain objects (return true)
69
isPlainObject({});                     // => true
70
isPlainObject({foo: 'bar'});          // => true
71
isPlainObject({constructor: Object}); // => true
72
isPlainObject({valueOf: 0});          // => true
73
isPlainObject(new Object());          // => true
74
isPlainObject(Object.create(null));   // => true
75

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

79
// Non-plain objects (return false)
80
isPlainObject(['foo', 'bar']);        // => false
81
isPlainObject(new Date());            // => false
82
isPlainObject(new Map());             // => false
83
isPlainObject(Math);                  // => false
84
isPlainObject(JSON);                  // => false
85
isPlainObject(() => {});              // => false
86
isPlainObject(/regex/);               // => false
87

88
// Primitives (return false)
89
isPlainObject(null);                  // => false
90
isPlainObject(undefined);             // => false
91
isPlainObject('string');              // => false
92
isPlainObject(42);                    // => false
93
isPlainObject(true);                  // => false
94

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

99
// Arguments object (return false)
100
(function() {
101
  isPlainObject(arguments);           // => false
102
})();
103

104
// Objects with custom prototypes (return false)
105
isPlainObject(Object.create({}));     // => false
106
```
107

108
## Types
109

110
```typescript { .api }
111
/**
112
 * Generic type parameter representing the type of values in the plain object
113
 */
114
type Value = unknown;
115
```
116

117
**Built-in TypeScript Types Used:**
118
- `PropertyKey`: Built-in type representing `string | number | symbol`  
119
- `Record<K, T>`: Built-in utility type representing an object with keys of type K and values of type T
120

121
## Implementation Details
122

123
The function uses several techniques to ensure accurate detection:
124

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

134
## Error Handling
135

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