Skip to content

util: add maxObjectProperties option to inspect - #65242

Open
watson wants to merge 1 commit into
nodejs:mainfrom
watson:support-max-props-in-util-inspect
Open

util: add maxObjectProperties option to inspect#65242
watson wants to merge 1 commit into
nodejs:mainfrom
watson:support-max-props-in-util-inspect

Conversation

@watson

@watson watson commented Aug 12, 2026

Copy link
Copy Markdown
Member

Add maxObjectProperties to util.inspect so callers can cap how many named properties are formatted per inspected value, independently from maxArrayLength.

The default is Infinity, so existing output is unchanged unless the option is set. Own string and symbol properties are shown before user-defined prototype properties. Entries governed by maxArrayLength and built-in metadata such as [byteLength], [buffer], and [BYTES_PER_ELEMENT] do not count toward the limit. Omitted properties are not evaluated, so getters and [util.inspect.custom] on truncated keys are skipped. The limit is applied before sorted. Assertion errors pass maxObjectProperties: Infinity explicitly so changes to inspect.defaultOptions do not affect assertion diffs.

Examples

Regular object

const obj = { first: 1, second: 2, third: 3 };
util.inspect(obj);
// '{ first: 1, second: 2, third: 3 }'
util.inspect(obj, { maxObjectProperties: 2 });
// '{ first: 1, second: 2, ... 1 more property }'

Array with custom properties

Array indices are governed by maxArrayLength; named properties on the array use maxObjectProperties:

const arr = [1, 2];
arr.first = 3;
arr.second = 4;
util.inspect(arr);
// '[ 1, 2, first: 3, second: 4 ]'
util.inspect(arr, { maxArrayLength: 1, maxObjectProperties: 1 });
// '[ 1, ... 1 more item, first: 3, ... 1 more property ]'

Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or

(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or

(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.

(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.

@nodejs-github-bot

Copy link
Copy Markdown
Collaborator

Review requested:

  • @nodejs/performance

@nodejs-github-bot nodejs-github-bot added assert Issues and PRs related to the assert subsystem. needs-ci PRs that need a full CI run. util Issues and PRs related to the built-in util module. labels Aug 12, 2026
@watson
watson force-pushed the support-max-props-in-util-inspect branch from 90f87b9 to 0282eb8 Compare August 12, 2026 12:09
Add a maxObjectProperties option to util.inspect that caps the number of
named properties included in formatted output. The limit applies
independently from maxArrayLength and defaults to Infinity, preserving
existing behavior.

Own string and symbol properties are included before user-defined
prototype properties. Array, Map, Set, and WeakSet entries governed by
maxArrayLength, as well as built-in metadata entries such as
[byteLength], [buffer], and [BYTES_PER_ELEMENT], do not consume the
property budget. The limit is applied before sorted, and omitted
properties are not evaluated (including getters and
[util.inspect.custom]).

Prototype property collection is deferred so truncated properties are
discarded before their values are formatted. Assertion errors pass
maxObjectProperties: Infinity explicitly so changes to
inspect.defaultOptions do not affect diff output.

Signed-off-by: Thomas Watson <w@tson.dk>
@watson
watson force-pushed the support-max-props-in-util-inspect branch from 0282eb8 to c01faf8 Compare August 12, 2026 12:16
@watson
watson marked this pull request as ready for review August 12, 2026 12:22
@BridgeAR
BridgeAR self-requested a review August 12, 2026 13:06
@codecov

codecov Bot commented Aug 12, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 98.80952% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 90.32%. Comparing base (00f0f8c) to head (c01faf8).
⚠️ Report is 2 commits behind head on main.

Files with missing lines Patch % Lines
lib/internal/util/inspect.js 98.79% 1 Missing ⚠️
Additional details and impacted files
@@           Coverage Diff           @@
##             main   #65242   +/-   ##
=======================================
  Coverage   90.31%   90.32%           
=======================================
  Files         760      760           
  Lines      248637   248689   +52     
  Branches    46942    46950    +8     
=======================================
+ Hits       224556   224624   +68     
- Misses      15475    15476    +1     
+ Partials     8606     8589   -17     
Files with missing lines Coverage Δ
lib/internal/assert/assertion_error.js 95.98% <100.00%> (+<0.01%) ⬆️
lib/internal/util/inspect.js 96.98% <98.79%> (+0.05%) ⬆️

... and 29 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

assert Issues and PRs related to the assert subsystem. needs-ci PRs that need a full CI run. util Issues and PRs related to the built-in util module.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants