docs: update readme

Author: usefulthink

src/2.0/2.0.md

@@ -22,24 +22,102 @@ import { setOptions, importLibrary } from "@googlemaps/js-api-loader";
 const { Map } = await importLibrary("maps");
 ```
 
-Since wrapping all code working with the maps API into async functions can be
-problematic, we also provide an API that can be used in a synchronous context:
+## Synchronous API (TBD)
 
-```ts
-import {
-  getImportedLibrary,
-  isLibraryImported,
-} from "@googlemaps/js-api-loader";
-
-try {
-  // getImportedLibrary throws an Error when the library hasn't been loaded yet
-  // (otherwise the destructuring of the result wouldn't work)
-  const { Map } = getImportedLibrary("maps");
-} catch (err) {}
-
-// when guarded by isLibraryImported, it's guaranteed to not throw
-if (isLibraryImported("maps")) {
-  const { Map } = getImportedLibrary("maps");
+### Motivation
+
+There are a lot of situations where the `importLibrary` function doesn't
+work well, since using an async function or promises isn't always a viable
+option.
+
+Currently, the only alternative to `importLibrary` is to use the global
+`google.maps` namespaces. An additional synchronous API is intended to
+provide an alternative way to using the global namespaces while solving some
+of the problems that come with using them.
+
+Any synchronous access to the libraries requires developers to make sure the
+libraries have already been loaded when the corresponding code is executed.
+In practice, this is rarely a big issue.
+
+The exact shape of the synchronous API is to be determined, it could be a
+simple Map instance `libraries` or a pair of has/get functions to check for and
+retrieve loaded libraries.
+
+### Example 1: helper classes
+
+Imagine some service class that uses the `places` library and the
+`PlacesService` to do it's thing.
+
+#### global namespace
+
+This is how it would be written with the global `google.maps` namespace:
+
+```tsx
+class PlacesHelper {
+  private service: google.maps.places.PlacesService;
+
+  constructor() {
+    if (!google.maps.places.PlacesService)
+      throw new Error("maps api or places library missing");
+
+    this.service = new google.maps.places.PlacesService();
+  }
+
+  // ...
+}
+```
+
+This has two drawbacks:
+
+- having to write out `google.maps.places` for all classes (and
+  types, but that's a seperate issue) adds a lot of "noise" to the code
+- references to the global namespace can't really be minified, and
+  due to the late loading of the API, a global assignment to a shorthand
+  name isn't really possible.
+
+#### importLibrary
+
+Since in a constructor, we can't `await` the result of `importLibrary`, the
+only way to do this is using the `.then()` function, which drastically
+changes the semantics of the code:
+
+```tsx
+class PlacesHelper {
+  private service: google.maps.places.PlacesService | null = null;
+
+  constructor() {
+    importLibrary("places").then(
+      ({ PlacesService }) => (this.service = new PlacesService())
+    );
+  }
+}
+```
+
+Here, the service has to be declared as optional (`| null`) in typescript,
+and every other method of the class has to somehow deal with the fact that
+the service might not yet have been initialized. Even if the library is
+already loaded, it won't be returned until the queued mircotasks and the
+handlers for the awaited Promise are executed.
+This can even have cascading effects on all classes calling methods of this
+class.
+
+#### proposed sync API
+
+A synchronous API would allow us to write the same code we used for
+global namespaces, but without the readability problems and without global
+namespaces:
+
+```tsx
+class PlacesHelper {
+  private service: google.maps.places.PlacesService = null;
+
+  constructor() {
+    if (!isLibraryImported("places"))
+      throw new Error("maps api or places library missing");
+
+    const { PlacesService } = getImportedLibrary("places");
+    this.service = new PlacesService();
+  }
 }
 ```