0
# Object Inspector
1

2
Tree-view inspector for JavaScript objects that displays data in an expandable hierarchical structure, similar to console.log output. Supports all JavaScript data types including objects, arrays, functions, primitives, and special values.
3

4
## Capabilities
5

6
### ObjectInspector Component
7

8
Main component for inspecting JavaScript objects in a tree structure with expandable nodes.
9

10
```typescript { .api }
11
/**
12
 * Tree-view inspector for JavaScript objects
13
 * @param props - ObjectInspector configuration props
14
 * @returns React element displaying the object tree
15
 */
16
function ObjectInspector(props: ObjectInspectorProps): React.ReactElement;
17

18
interface ObjectInspectorProps {
19
  /** The JavaScript object to inspect - supports any data type */
20
  data: any;
21
  /** Optional name for the root node - displays as "name: ObjectPreview" */
22
  name?: string;
23
  /** Initial expansion level - 0 means collapsed, 1 expands first level, etc. */
24
  expandLevel?: number;
25
  /** 
26
   * Paths to expand on initialization - JSONPath-style strings or array
27
   * Examples: "$", "$.foo", "$.foo.bar", ["$", "$.foo", "$.foo.bar"]
28
   * Supports wildcards: "$.*" expands all first-level properties
29
   */
30
  expandPaths?: string | string[];
31
  /** Show non-enumerable properties (dimmed) - default false */
32
  showNonenumerable?: boolean;
33
  /** 
34
   * Sort object keys - true for alphabetical, function for custom sorting
35
   * Does not affect array indices
36
   */
37
  sortObjectKeys?: boolean | ((a: string, b: string) => number);
38
  /** 
39
   * Custom node renderer function - receives depth, name, data, isNonenumerable
40
   * Default renders ObjectRootLabel for depth 0, ObjectLabel for others
41
   */
42
  nodeRenderer?: (props: NodeRendererProps) => React.ReactElement;
43
  /** Theme configuration - preset string or custom theme object */
44
  theme?: string | ThemeObject;
45
}
46
```
47

48
**Usage Examples:**
49

50
```typescript
51
import React from "react";
52
import { ObjectInspector } from "react-inspector";
53

54
// Basic object inspection
55
const data = {
56
  name: "Alice",
57
  age: 30,
58
  hobbies: ["reading", "coding"],
59
  address: { city: "New York", zip: "10001" }
60
};
61

62
function BasicExample() {
63
  return <ObjectInspector data={data} />;
64
}
65

66
// Expanded object with custom root name
67
function ExpandedExample() {
68
  return (
69
    <ObjectInspector 
70
      data={data} 
71
      name="user"
72
      expandLevel={2}
73
    />
74
  );
75
}
76

77
// Show non-enumerable properties and sort keys
78
function AdvancedExample() {
79
  return (
80
    <ObjectInspector 
81
      data={data}
82
      showNonenumerable={true}
83
      sortObjectKeys={true}
84
    />
85
  );
86
}
87

88
// Custom expansion paths
89
function CustomExpansionExample() {
90
  return (
91
    <ObjectInspector 
92
      data={data}
93
      expandPaths={["$", "$.address"]}
94
    />
95
  );
96
}
97
```
98

99
### Node Renderer Customization
100

101
Custom node renderers allow complete control over how tree nodes are displayed.
102

103
```typescript { .api }
104
interface NodeRendererProps {
105
  /** Current depth in the tree (0 = root) */
106
  depth: number;
107
  /** Property name, array index, or special keys like "__proto__" */
108
  name: string | number;
109
  /** The data value at this node */
110
  data: any;
111
  /** Whether this property is non-enumerable (affects styling) */
112
  isNonenumerable?: boolean;
113
  /** Whether this node is currently expanded */
114
  expanded?: boolean;
115
}
116

117
/**
118
 * Default node renderer used by ObjectInspector
119
 * @param props - Node rendering properties
120
 * @returns React element for the tree node
121
 */
122
function defaultNodeRenderer(props: NodeRendererProps): React.ReactElement;
123
```
124

125
**Custom Node Renderer Example:**
126

127
```typescript
128
import React from "react";
129
import { 
130
  ObjectInspector, 
131
  ObjectRootLabel, 
132
  ObjectLabel,
133
  ObjectName,
134
  ObjectValue 
135
} from "react-inspector";
136

137
function customNodeRenderer({ depth, name, data, isNonenumerable }) {
138
  if (depth === 0) {
139
    return <ObjectRootLabel name={name} data={data} />;
140
  }
141
  
142
  // Custom styling for functions
143
  if (typeof data === 'function') {
144
    return (
145
      <span style={{ color: 'purple' }}>
146
        <ObjectName name={name} dimmed={isNonenumerable} />
147
        <span>: </span>
148
        <ObjectValue object={data} />
149
        <span> 🚀</span>
150
      </span>
151
    );
152
  }
153
  
154
  return <ObjectLabel name={name} data={data} isNonenumerable={isNonenumerable} />;
155
}
156

157
function CustomRendererExample() {
158
  return (
159
    <ObjectInspector 
160
      data={{ fn: () => "hello", value: 42 }}
161
      nodeRenderer={customNodeRenderer}
162
    />
163
  );
164
}
165
```
166

167
### Expansion Path Syntax
168

169
ObjectInspector supports JSONPath-style expansion paths for controlling which nodes are initially expanded.
170

171
**Path Examples:**
172

173
- `"$"` - Expand root node
174
- `"$.foo"` - Expand the "foo" property
175
- `"$.foo.bar"` - Expand the "bar" property within "foo"
176
- `"$.1"` - Expand array index 1
177
- `"$.*"` - Expand all first-level properties (wildcard)
178
- `["$", "$.foo", "$.foo.bar"]` - Expand multiple specific paths
179

180
**Important Notes:**
181
- Paths are merged with `expandLevel` - both are applied
182
- To expand a nested path completely, include all parent paths
183
- Wildcards only work for one level at a time
184

185
```typescript
186
// Expand specific nested paths
187
<ObjectInspector 
188
  data={complexData}
189
  expandPaths={[
190
    "$",              // Root
191
    "$.users",        // Users array
192
    "$.users.0",      // First user
193
    "$.config.*"      // All config properties
194
  ]}
195
/>
196
```
197

198
### Object Key Sorting
199

200
Control how object properties are ordered in the tree display.
201

202
```typescript { .api }
203
// Boolean sorting - alphabetical order (excludes arrays)
204
sortObjectKeys: true
205

206
// Custom sorting function
207
sortObjectKeys: (a: string, b: string) => number
208

209
// Examples:
210
// Reverse alphabetical
211
sortObjectKeys: (a, b) => b.localeCompare(a)
212

213
// Length-based sorting
214
sortObjectKeys: (a, b) => a.length - b.length
215

216
// Case-insensitive
217
sortObjectKeys: (a, b) => a.toLowerCase().localeCompare(b.toLowerCase())
218
```
219

220
### Data Type Support
221

222
ObjectInspector handles all JavaScript data types appropriately:
223

224
**Primitives:**
225
- `string` - Quoted strings
226
- `number` - Numeric values  
227
- `boolean` - true/false
228
- `null` - null value
229
- `undefined` - undefined value
230
- `symbol` - Symbol representation
231
- `bigint` - BigInt values with 'n' suffix
232

233
**Objects:**
234
- `Object` - Expandable object properties
235
- `Array` - Expandable array elements with indices
236
- `Date` - Date string representation
237
- `RegExp` - Regex literal format
238
- `Function` - Function signature with ƒ prefix
239
- `Map/Set` - Iterable entries
240
- `Buffer` - Buffer representation (Node.js)
241

242
**Special Handling:**
243
- Non-enumerable properties appear dimmed when `showNonenumerable` is true
244
- Circular references are handled safely
245
- Prototype chain accessible via `__proto__` property
246
- Empty objects/arrays display appropriate previews