From beb9269841b49152588a2604414216738ea56e88 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Fri, 4 Sep 2020 17:40:57 +0200
Subject: [PATCH] core-api: docs for ApiFactoryRegistry and do not override
 same scope

---
 .../src/apis/ApiFactoryRegistry.test.ts       |  4 ++++
 .../core-api/src/apis/ApiFactoryRegistry.ts   | 22 +++++++++++++++----
 2 files changed, 22 insertions(+), 4 deletions(-)

diff --git a/packages/core-api/src/apis/ApiFactoryRegistry.test.ts b/packages/core-api/src/apis/ApiFactoryRegistry.test.ts
index 43370f41a7..8b4818ac53 100644
--- a/packages/core-api/src/apis/ApiFactoryRegistry.test.ts
+++ b/packages/core-api/src/apis/ApiFactoryRegistry.test.ts
@@ -42,12 +42,16 @@ describe('ApiFactoryRegistry', () => {
     const registry = new ApiFactoryRegistry();
     expect(registry.register('default', aFactory1)).toBe(true);
     expect(registry.get(aRef)).toBe(aFactory1);
+    expect(registry.register('default', aFactory2)).toBe(false);
+    expect(registry.get(aRef)).toBe(aFactory1);
     expect(registry.register('app', aFactory2)).toBe(true);
     expect(registry.get(aRef)).toBe(aFactory2);
     expect(registry.register('default', aFactory1)).toBe(false);
     expect(registry.get(aRef)).toBe(aFactory2);
     expect(registry.register('static', aFactory1)).toBe(true);
     expect(registry.get(aRef)).toBe(aFactory1);
+    expect(registry.register('static', aFactory2)).toBe(false);
+    expect(registry.get(aRef)).toBe(aFactory2);
     expect(registry.register('app', aFactory2)).toBe(false);
     expect(registry.get(aRef)).toBe(aFactory1);
     expect(registry.getAllApis()).toEqual(new Set([aRef]));
diff --git a/packages/core-api/src/apis/ApiFactoryRegistry.ts b/packages/core-api/src/apis/ApiFactoryRegistry.ts
index 9d75944d8b..fa52249e25 100644
--- a/packages/core-api/src/apis/ApiFactoryRegistry.ts
+++ b/packages/core-api/src/apis/ApiFactoryRegistry.ts
@@ -34,24 +34,38 @@ enum ScopeLevels {
 }
 
 type FactoryTuple = {
-  level: number;
+  priority: number;
   factory: AnyApiFactory;
 };
 
+/**
+ * ApiFactoryRegistry is an ApiFactoryHolder implementation that enables
+ * registration of API Factories with different scope.
+ *
+ * Each scope has an assigned priority, where factories registered with
+ * higher priority scopes override ones with lower priority.
+ */
 export class ApiFactoryRegistry implements ApiFactoryHolder {
   private readonly factories = new Map<AnyApiRef, FactoryTuple>();
 
+  /**
+   * Register a new API factory. Returns true if the factory was added
+   * to the registry.
+   *
+   * A factory will not be added to the registry if there is already
+   * an existing factory with the same or higher priority.
+   */
   register<Api, Deps extends { [name in string]: unknown }>(
     scope: ApiFactoryScope,
     factory: ApiFactory<Api, Deps>,
   ) {
-    const level = ScopeLevels[scope];
+    const priority = ScopeLevels[scope];
     const existing = this.factories.get(factory.implements);
-    if (existing && existing.level > level) {
+    if (existing && existing.priority > priority) {
       return false;
     }
 
-    this.factories.set(factory.implements, { level, factory });
+    this.factories.set(factory.implements, { priority, factory });
     return true;
   }