From c1369c2cf457c1230cb6fc336cb37de8a5ba4f0d Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Fri, 13 Jan 2023 17:40:46 +0100
Subject: [PATCH] backend-plugin-api: update API report + fixes

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
---
 packages/backend-plugin-api/api-report.md     | 151 ++++++++++++++----
 .../src/services/system/types.ts              |  24 +--
 2 files changed, 133 insertions(+), 42 deletions(-)

diff --git a/packages/backend-plugin-api/api-report.md b/packages/backend-plugin-api/api-report.md
index 33190277c9..59338fdf42 100644
--- a/packages/backend-plugin-api/api-report.md
+++ b/packages/backend-plugin-api/api-report.md
@@ -126,22 +126,86 @@ export function createExtensionPoint<T>(
   config: ExtensionPointConfig,
 ): ExtensionPoint<T>;
 
-// @public (undocumented)
+// @public
 export function createServiceFactory<
   TService,
-  TScope extends 'root' | 'plugin',
   TImpl extends TService,
   TDeps extends {
     [name in string]: ServiceRef<unknown>;
   },
-  TOpts extends [options?: object] = [],
+  TOpts extends object | undefined = undefined,
+>(
+  config: RootServiceFactoryConfig<TService, TImpl, TDeps>,
+): () => ServiceFactory<TService>;
+
+// @public
+export function createServiceFactory<
+  TService,
+  TImpl extends TService,
+  TDeps extends {
+    [name in string]: ServiceRef<unknown>;
+  },
+  TOpts extends object | undefined = undefined,
+>(
+  config: (options?: TOpts) => RootServiceFactoryConfig<TService, TImpl, TDeps>,
+): (options?: TOpts) => ServiceFactory<TService>;
+
+// @public
+export function createServiceFactory<
+  TService,
+  TImpl extends TService,
+  TDeps extends {
+    [name in string]: ServiceRef<unknown>;
+  },
+  TOpts extends object | undefined = undefined,
+>(
+  config: (options: TOpts) => RootServiceFactoryConfig<TService, TImpl, TDeps>,
+): (options: TOpts) => ServiceFactory<TService>;
+
+// @public
+export function createServiceFactory<
+  TService,
+  TImpl extends TService,
+  TDeps extends {
+    [name in string]: ServiceRef<unknown>;
+  },
+  TContext = undefined,
+  TOpts extends object | undefined = undefined,
+>(
+  config: PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>,
+): () => ServiceFactory<TService>;
+
+// @public
+export function createServiceFactory<
+  TService,
+  TImpl extends TService,
+  TDeps extends {
+    [name in string]: ServiceRef<unknown>;
+  },
+  TContext = undefined,
+  TOpts extends object | undefined = undefined,
+>(
+  config: (
+    options?: TOpts,
+  ) => PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>,
+): (options?: TOpts) => ServiceFactory<TService>;
+
+// @public
+export function createServiceFactory<
+  TService,
+  TImpl extends TService,
+  TDeps extends {
+    [name in string]: ServiceRef<unknown>;
+  },
+  TContext = undefined,
+  TOpts extends object | undefined = undefined,
 >(
   config:
-    | ServiceFactoryConfig<TService, TScope, TImpl, TDeps>
+    | PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>
     | ((
-        ...options: TOpts
-      ) => ServiceFactoryConfig<TService, TScope, TImpl, TDeps>),
-): (...params: TOpts) => ServiceFactory<TService>;
+        options: TOpts,
+      ) => PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>),
+): (options: TOpts) => ServiceFactory<TService>;
 
 // @public
 export function createServiceRef<TService>(
@@ -229,6 +293,30 @@ export interface PluginMetadataService {
   getId(): string;
 }
 
+// @public (undocumented)
+export interface PluginServiceFactoryConfig<
+  TService,
+  TContext,
+  TImpl extends TService,
+  TDeps extends {
+    [name in string]: ServiceRef<unknown>;
+  },
+> {
+  // (undocumented)
+  createRootContext?(
+    deps: ServiceRefsToInstances<TDeps, 'root'>,
+  ): Promise<TContext>;
+  // (undocumented)
+  deps: TDeps;
+  // (undocumented)
+  factory(
+    deps: ServiceRefsToInstances<TDeps>,
+    context: TContext,
+  ): Promise<TImpl>;
+  // (undocumented)
+  service: ServiceRef<TService, 'plugin'>;
+}
+
 // @public
 export type ReadTreeOptions = {
   filter?(
@@ -284,6 +372,22 @@ export interface RootLifecycleService extends LifecycleService {}
 // @public (undocumented)
 export interface RootLoggerService extends LoggerService {}
 
+// @public (undocumented)
+export interface RootServiceFactoryConfig<
+  TService,
+  TImpl extends TService,
+  TDeps extends {
+    [name in string]: ServiceRef<unknown>;
+  },
+> {
+  // (undocumented)
+  deps: TDeps;
+  // (undocumented)
+  factory(deps: ServiceRefsToInstances<TDeps, 'root'>): Promise<TImpl>;
+  // (undocumented)
+  service: ServiceRef<TService, 'root'>;
+}
+
 // @public (undocumented)
 export interface SchedulerService extends PluginTaskScheduler {}
 
@@ -323,36 +427,17 @@ export type ServiceFactory<TService = unknown> =
       deps: {
         [key in string]: ServiceRef<unknown>;
       };
-      factory(deps: {
+      createRootContext?(deps: {
         [key in string]: unknown;
-      }): Promise<
-        (deps: {
+      }): Promise<unknown>;
+      factory(
+        deps: {
           [key in string]: unknown;
-        }) => Promise<TService>
-      >;
+        },
+        context: unknown,
+      ): Promise<TService>;
     };
 
-// @public (undocumented)
-export interface ServiceFactoryConfig<
-  TService,
-  TScope extends 'root' | 'plugin',
-  TImpl extends TService,
-  TDeps extends {
-    [name in string]: ServiceRef<unknown>;
-  },
-> {
-  // (undocumented)
-  deps: TDeps;
-  // (undocumented)
-  factory(
-    deps: ServiceRefsToInstances<TDeps, 'root'>,
-  ): TScope extends 'root'
-    ? Promise<TImpl>
-    : Promise<(deps: ServiceRefsToInstances<TDeps>) => Promise<TImpl>>;
-  // (undocumented)
-  service: ServiceRef<TService, TScope>;
-}
-
 // @public
 export type ServiceFactoryOrFunction<TService = unknown> =
   | ServiceFactory<TService>
diff --git a/packages/backend-plugin-api/src/services/system/types.ts b/packages/backend-plugin-api/src/services/system/types.ts
index 618ef1b7b6..f4489b168b 100644
--- a/packages/backend-plugin-api/src/services/system/types.ts
+++ b/packages/backend-plugin-api/src/services/system/types.ts
@@ -166,10 +166,10 @@ export interface PluginServiceFactoryConfig<
 }
 
 /**
- * Creates a root scoped service factory.
+ * Creates a root scoped service factory without options.
  *
  * @public
- * @param config
+ * @param config - The service factory configuration.
  */
 export function createServiceFactory<
   TService,
@@ -183,7 +183,7 @@ export function createServiceFactory<
  * Creates a root scoped service factory with optional options.
  *
  * @public
- * @param config
+ * @param config - The service factory configuration.
  */
 export function createServiceFactory<
   TService,
@@ -194,10 +194,10 @@ export function createServiceFactory<
   config: (options?: TOpts) => RootServiceFactoryConfig<TService, TImpl, TDeps>,
 ): (options?: TOpts) => ServiceFactory<TService>;
 /**
- * Creates a plugin scoped service factory with required options.
+ * Creates a root scoped service factory with required options.
  *
  * @public
- * @param config
+ * @param config - The service factory configuration.
  */
 export function createServiceFactory<
   TService,
@@ -208,10 +208,10 @@ export function createServiceFactory<
   config: (options: TOpts) => RootServiceFactoryConfig<TService, TImpl, TDeps>,
 ): (options: TOpts) => ServiceFactory<TService>;
 /**
- * Creates a plugin scoped service factory with optional options.
+ * Creates a plugin scoped service factory without options.
  *
  * @public
- * @param config
+ * @param config - The service factory configuration.
  */
 export function createServiceFactory<
   TService,
@@ -223,10 +223,10 @@ export function createServiceFactory<
   config: PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>,
 ): () => ServiceFactory<TService>;
 /**
- * Creates a plugin scoped service factory with required options.
+ * Creates a plugin scoped service factory with optional options.
  *
  * @public
- * @param config
+ * @param config - The service factory configuration.
  */
 export function createServiceFactory<
   TService,
@@ -239,6 +239,12 @@ export function createServiceFactory<
     options?: TOpts,
   ) => PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>,
 ): (options?: TOpts) => ServiceFactory<TService>;
+/**
+ * Creates a plugin scoped service factory with required options.
+ *
+ * @public
+ * @param config - The service factory configuration.
+ */
 export function createServiceFactory<
   TService,
   TImpl extends TService,