Add 'Choose the Appropriate WebIDL Construct for Data and Behavior'

Author: marcoscaceres

index.bs

@@ -1525,6 +1525,132 @@ the interaction with garbage collection.
 
 <h2 id="api-surface">JavaScript API Surface Concerns</h2>
 
+<h3>Choose the Appropriate WebIDL Construct for Data and Behavior (Dictionaries, Interfaces, and Namespaces)</h3>
+
+Web APIs commonly pass around data and functionality using WebIDL. As a specification author, decide carefully whether
+to use a dictionary, an interface, or in rare cases, a namespace.
+
+The goal is to ensure ergonomic, consistent APIs that feel natural to Web developers while avoiding pitfalls like "fake classes" or classes that provide no functionality.
+
+Each construct has its own pros and cons, discussed below.
+
+<h4>Use Dictionaries for “Configuration” or “Input-Only” Data</h4>
+
+Choose a dictionary when the part of the API represents data that is transient or you need a configuration-style object or "options bag".
+
+Dictionaries are ideal for when the data doesn't get stored or mutated; it's just used it at the time of the call.
+
+For example, the `ShareData` member from Web Share:
+
+```WebIDL
+dictionary ShareData {
+  USVString title;
+  USVString text;
+  USVString url;
+};
+```
+
+And how it's commonly used:
+
+<pre class="highlight">
+const data = { "text": "Text being shared" };
+await navigator.share(data);
+</pre>
+
+Dictionaries are easily extensible and makes it easy to add optional fields later as needed.
+Members of a dictionary are optional by default, but can be marked as `required` if needed.
+
+Dictionaries are also highly idiomatic (i.e., natural to use in JavaScript). Passing `{ ... }` inline is the most natural way to supply configuration in JavaScript.
+
+Dictionaries, because of how they are treated by user agents, are also relatively future-proof; accommodating new members gracefully, without breaking older code.
+
+Dictionaries are best used for objects that don't need to be distigusied by type in their lifecycle (i.e., `instanceof` checks are mostly meaningless because it's always `Object`).
+
+A key thing to know about dictionries is that they are "passed by value" to methods (i.e., they are copied) and that browsers engines strip unknown members when converting from JavaScript objects to a WebIDL reprensentation.
+This means that if a developer changing the value after it is passed into an API has no effect.
+
+Again, taking the `ShareData` dictinary as an example:
+
+```JS
+const data = {
+    "text": "Text being shared",
+    // Not in the dictionary, so removed by the browser
+    "whatever": 123,
+};
+navigator.share(data);
+
+// Changing this after calling .share() has no effect
+data.text = "New text";
+```
+
+<h4>Choose an Interface for Functionality, State, and Identity</h4>
+
+Intefaces are roughly equivalent to classes in JavaScript. Choose and an interface when a specificaiton need object with data that might also have — or eventually gain — methods, computed or readonly properties, or internal state or "slots".
+
+Unlike dictrionaries, interfaces:
+
+ * provide the ability to check object's identity (i.e., one can check if  it is an `instanceof` a particular class on the global scope),
+ * can have need read-only properties,
+ * can have state,
+ * can exhibit side-effects on assignment.
+
+Defining an interface also exposes it on the global scope, allowing for the specification of static methods. For example, the `canParse()` static method of the URL interface. 
+
+```JS
+if (URL.canParse(someURL)) {
+    // Do stuff...
+}
+```
+
+If the interface can holds data that is useful when serialized (e.g., `GeolocationPosition`), consider adding a `toJSON()` default method. Alternatively, if it holds binary data, one can add .toBlob() an so on.
+
+This makes object natural to use with APIs. For example:
+
+```JS
+const position = await new Promise((resolve, reject) => {
+    navigator.geolocation.getCurrentPosition(resolve, reject);
+});
+
+// Prepare the fetch request options
+const options = {
+    method: 'POST',
+    headers: {
+    'Content-Type': 'application/json'
+    },
+    // .stringify() calls .toJSON() automatically
+    position
+};
+```
+
+If warrented by the use cases, give the interface a constructor. Be mindful to not just add a constructor if a class has no state. Doing so is considered by practice by effectively creaeting a fake class.
+(see `DOMParser` or `DOMImplementation` as bad examples).
+
+In such cases, prefer a static method on an existing object or, if absolutely necessary, mint a new namespace.
+
+<h4>Choose a namespace to Avoid “Fake Classes” for Behavior-Only Utilities</h4>
+
+A namespace is correct if everything is purely static and lacks a prototype (like the `Math`, `Intl`, `Atomics`, `Console` objects in JS).
+
+If you only have one or two small static functions, a whole new namespace may be overkill. Attaching them to an existing object might be more idiomatic.
+
+Conversely, a namespace that grows too large or too broad may need better organization or separate logical partitions.
+
+<h4>"Pseudo-namespaces"</h4>
+
+As WebIDL interfaces can have attributes, it is possible to create "pseudo-namespaces" by leveraging non-contructable interface as attributes.
+
+A common example are all the attributes attaches to the navigator object. The navigator object has an interface definition (`Navigator`), which iteself contains other
+atttributes that gives access to further functionality through interface instances.
+
+For example:
+
+* `navigator.credentials` - The `CredentialsContainer` interface of the Credentials Management API.
+* `navigator.geolocation` - The `Geolocation` interface of the Geolocation specification.
+* `navigator.permissions` - The `Permissions` interface of the Permissions specification.
+
+Psudo-namespaces are useful for when, as a spec author, you need access to "this" particular instance
+(e.g., where the properties of one instance may different from those of another browsing context).
+
 <h3 id="attributes-like-data">Attributes should behave like data properties</h3>
 
 [[!WEBIDL]] attributes should act like simple JavaScript object properties.