Skip to content

Confusing documentation or bad implementation for util.isObject #743

Closed
Closed
Confusing documentation or bad implementation for util.isObject#743
Labels
docIssues and PRs related to Node.js documentation.utilIssues and PRs related to the built-in util module.

Description

@seishun
seishun
opened on Feb 6, 2015

The documentation for util.isObject states:

Returns true if the given "object" is strictly an Object. false otherwise.

What exactly does "strictly an Object" mean? That the type of the argument is Object? Nope:

> var f = function(){}
undefined
> util.isObject(f)
false

Or maybe it does an instanceof check? That also isn't the case:

> var o = Object.create(null)
undefined
> o instanceof Object
false
> util.isObject(o)
true

Does it check that the [[Class]] internal property is "Object"? Also no:

> Object.prototype.toString.call(JSON)
'[object JSON]'
> util.isObject(JSON)
true

Either the docs should be updated to clarify the behavior, or the implementation should be fixed. I would vote for the latter, otherwise the function name is confusing.

Activity

  1. seishun
    added
    utilIssues and PRs related to the built-in util module.
    docIssues and PRs related to Node.js documentation.
    on Feb 6, 2015

  2. cjihrig commented on Feb 6, 2015

    @cjihrig
    cjihrig
    on Feb 6, 2015
    Contributor

    It checks arg !== null && typeof arg === 'object' to be exact.

    EDIT: I think "strictly" is thrown in there because typeof returns 'object' for null.

  3. vkurchatkin commented on Feb 6, 2015

    @vkurchatkin
    vkurchatkin
    on Feb 6, 2015
    Contributor

    yeah, the wording is really confusing

  4. cjihrig commented on Feb 6, 2015

    @cjihrig
    cjihrig
    on Feb 6, 2015
    Contributor

    Would this work for you:

    Returns true if object is not null and typeof object evaluates to 'object'. false otherwise.

  5. seishun commented on Feb 6, 2015

    @seishun
    seishun
    on Feb 6, 2015
    ContributorAuthor

    Kinda, but it's generally a bad sign when the documentation basically rephrases the source code. It would be better to change the implementation to check whether Type(arg) is Object, to be consistent with the other util.is* functions.

  6. ceejbot commented on Feb 12, 2015

    @ceejbot
    ceejbot
    on Feb 12, 2015

    The implementation does check whether typeof arg is object, and in the case of a function, it isn't. Both the underscore and lodash implementations of isObject() have additional checks to return true when the argument is a function, since that's the expected behavior. So I also think changing the implementation is more useful than changing the docs here.

  7. ceejbot commented on Feb 12, 2015

    @ceejbot
    ceejbot
    on Feb 12, 2015

    (Util is frozen, I note, so doc change it'll have to be.)

  8. vkurchatkin commented on Feb 12, 2015

    @vkurchatkin
    vkurchatkin
    on Feb 12, 2015
    Contributor

    @ceejbot it's not about util being frozen, but about semver. Bumping major version because of isObject one-liner is kind of funny

  9. seishun commented on Feb 12, 2015

    @seishun
    seishun
    on Feb 12, 2015
    ContributorAuthor

    Util is frozen

    The documentation for util.isObject doesn't state that it returns false for functions, so I would consider it a bug fix. Besides, util.isObject didn't even officially exist before io.js v1.0.0, so it's unlikely a lot of people are relying on this broken behavior.

  10. targos commented on Feb 12, 2015

    @targos
    targos
    on Feb 12, 2015
    Member

    I do not think that the expected behavior for everyone is to return true for functions. There is util.isFunction for that. util.isObject can be used to check function arguments and the common case is to differentiate functions from plain objects.
    IMO if there is a "bug" to fix, it is in the doc.

  11. seishun commented on Feb 12, 2015

    @seishun
    seishun
    on Feb 12, 2015
    ContributorAuthor

    @targos

    I do not think that the expected behavior for everyone is to return true for functions.

    It's the expected behavior for anyone who knows what an object is.

    There is util.isFunction for that.

    util.isPrimitive returns true for all primitives, util.isString returns true just for strings. It's the same thing with objects and functions.

    util.isObject can be used to check function arguments and the common case is to differentiate functions from plain objects.

    That's what util.isFunction is for.

  12. ceejbot
    added a commit that references this issue on Feb 12, 2015

    util: fixed behavior of isObject()

    b0ed45b

  13. trevnorris commented on Feb 12, 2015

    @trevnorris
    trevnorris
    on Feb 12, 2015
    Contributor

    IMO the docs should change to explain that an Object is anything that isn't a primitive. Though that probably doesn't clear up a lot.

  14. Fishrock123
    added a commit that references this issue on Mar 31, 2015

    doc: fix util.isObject documentation

    245ba1d

  15. Fishrock123 commented on Mar 31, 2015

    @Fishrock123
    Fishrock123
    on Mar 31, 2015
    Contributor

    Fixed by a doc fix in 245ba1d

    See later comments in #822 (comment) for doc vs functionality part.

  16. Fishrock123
    closed this as completedon Mar 31, 2015
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    docIssues and PRs related to Node.js documentation.utilIssues and PRs related to the built-in util module.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions