Confusing documentation or bad implementation for util.isObject

[seishun]

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.

[cjihrig]

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

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

[vkurchatkin]

yeah, the wording is really confusing

[cjihrig]

Would this work for you:

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

[seishun]

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.

[ceejbot]

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.

[ceejbot]

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

[vkurchatkin]

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

[seishun]

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.

[targos]

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.

[seishun]

@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.

[trevnorris]

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.

[Fishrock123]

Fixed by a doc fix in 245ba1d

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