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.

Answer 2

1. Document is the prototype definition for the document object of the global scope witch means that the Document's prototype is share with his instance (document). like Window is the prototype definition for the window object.
2. The Document is native prototype object and you can't create instances of it, only one instance is created when the page is created (again, like the window) just like a single tone object.
3. I don't think that to override the Document will be a good practice.

My suggestion is to use a namespace for your API and create your Document and HTMLElement etc inside your api namespace, for example:

var api = {
    Document: { /* your implementation */ },
    HTMLElement: { /* your implementation */ }
    //...
};

var myDocument = new api.Document();

More then that, you can inherit the real Document prototype and use it in your own object like so:

api.Document = function(){ /* your implementation */ }
api.Document.prototype = Document.prototype;

var myDocument = new api.Document();

Hope this is help and I understood you question...