What is the difference between Document and document in JavaScript?

Question

I am currently building an API for JavaScript, predominantly using Visual Studio 2010 and JetBrains WebStorm (brilliant if you're looking for a bulletproof JavaScript IDE).

Whilst looking through the intellisense list in Visual Studio (trying to familiarize myself with the JavaScript API), I noticed that both Document and document exist.

1. What is the difference between Document and document?
2. What is document an instance of (if any) ?
3. How does one use Document (as it is not a function, therefore, not constructable)?
4. Most importantly, What is the harm in "monkey-patching" Document to make it constructable?

The rationale behind these questions is that I want to create some objects that fit into my API (for example; Document, HTMLElement etc.), but as these appear to already exist in some respect, I'm not confident that I should be overwriting their native implementation.

Answer 1

What is the difference between Document and document?

document (or window.document) is a reference to the document contained in the window. (spec)

Document is the DOM interface for documents, which is exposed on the global object. (spec, spec)

How does one use Document (as it is not a function, therefore, not constructable)?

It's a host object and does not need to follow the EcmaScript spec - yet that does not mean it's not a function. It may differ from browser to browser as well. Yet it is not intended to be called (if you try it you'll get a NOT_SUPPORTED_ERR), there are other methods to instantiate/obtain new documents. What you can still use it for is

> document instanceof Document
true
> Document.prototype
DocumentPrototype {
    adoptNode: Function
    constructor: Document
    createAttribute: Function
    …
    querySelector: Function
    querySelectorAll: Function
}
|- NodePrototype
|- Object

so you could extend its prototype and use those methods on all XMLDocuments/HTMLDocuments in your app (but only if you know what’s wrong with extending the DOM).

Most importantly, what is the harm in "monkey-patching" Document to make it constructable?

I'm not sure how you would do that. Overwriting it could harm every script that expects it to work as above (unless you fix the prototype property of your new function). And maybe the Document property of window is non-writable in some environments, so you could harm yourself.