@open-pioneer/runtime 0.1.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,14 @@
1
1
  # @open-pioneer/runtime
2
2
 
3
+ ## 0.1.2
4
+
5
+ ### Patch Changes
6
+
7
+ - a40f12d: Update build-package tool. TypeScript declaration files should now be available.
8
+ - Updated dependencies [a40f12d]
9
+ - @open-pioneer/chakra-integration@0.1.2
10
+ - @open-pioneer/core@0.1.2
11
+
3
12
  ## 0.1.1
4
13
 
5
14
  ### Patch Changes
@@ -0,0 +1,111 @@
1
+ import { ComponentType } from "react";
2
+ import { ApplicationMetadata } from "./metadata";
3
+ import { ApiMethods } from "./api";
4
+ import { PropertiesRegistry } from "./PropertiesRegistry";
5
+ /**
6
+ * Options for the {@link createCustomElement} function.
7
+ */
8
+ export interface CustomElementOptions {
9
+ /**
10
+ * Rendered UI component.
11
+ */
12
+ component?: ComponentType<Record<string, string>>;
13
+ /**
14
+ * Application metadata (packages, services etc.).
15
+ * This is usually autogenerated by importing the virtual `"open-pioneer:app"` module.
16
+ */
17
+ appMetadata?: ApplicationMetadata;
18
+ /**
19
+ * Application defined configuration.
20
+ * All instances of the web component will share this static configuration.
21
+ *
22
+ * These will override default properties of the application's packages.
23
+ */
24
+ config?: ApplicationConfig;
25
+ /**
26
+ * Function to provide additional application defined configuration parameters.
27
+ *
28
+ * Compared to {@link config}, this function receives a context object
29
+ * that allows the developer to provide dynamic properties on a per-application basis.
30
+ *
31
+ * Parameters returned by this function take precedence over the ones defined by {@link config}.
32
+ */
33
+ resolveConfig?(ctx: ConfigContext): Promise<ApplicationConfig | undefined>;
34
+ /**
35
+ * Whether the shadow root element is accessible from the outside.
36
+ * Defaults to `false` in production mode and `true` during development to make testing easier.
37
+ */
38
+ openShadowRoot?: boolean;
39
+ }
40
+ /**
41
+ * A context object that is passed to the `resolveProperties` function.
42
+ */
43
+ export interface ConfigContext {
44
+ /**
45
+ * Returns an attribute from the application's root node.
46
+ */
47
+ getAttribute(name: string): string | undefined;
48
+ }
49
+ /**
50
+ * Runtime application configuration.
51
+ */
52
+ export interface ApplicationConfig {
53
+ /**
54
+ * Set this value to a locale string (e.g. "en") to for the application's locale.
55
+ * The default behavior is to choose an appropriate locale for the current user based
56
+ * on the browser's settings.
57
+ *
58
+ * The locale must be supported by the application.
59
+ */
60
+ locale?: string | undefined;
61
+ /**
62
+ * Properties specified here will override default properties of the application's packages.
63
+ */
64
+ properties?: ApplicationProperties | undefined;
65
+ }
66
+ /**
67
+ * Allows the application to override default properties in all packages.
68
+ */
69
+ export interface RawApplicationProperties {
70
+ /**
71
+ * Key: the name of the package.
72
+ * Value: A record of configuration properties (key/value pairs).
73
+ *
74
+ * Properties will override default property values in the package.
75
+ */
76
+ [packageName: string]: Record<string, unknown>;
77
+ }
78
+ /**
79
+ * Allows the application to override default properties in all packages.
80
+ *
81
+ * Properties are typed when the package contains type definitions for them.
82
+ */
83
+ export type ApplicationProperties = RawApplicationProperties & Partial<PropertiesRegistry>;
84
+ /**
85
+ * The interface implemented by web components produced via {@link createCustomElement}.
86
+ */
87
+ export interface ApplicationElement extends HTMLElement {
88
+ /** Resolves to the element's API when the application has started. */
89
+ when(): Promise<ApiMethods>;
90
+ }
91
+ /**
92
+ * The class returned by a call to {@link createCustomElement}.
93
+ */
94
+ export interface ApplicationElementConstructor {
95
+ new (): ApplicationElement;
96
+ }
97
+ /**
98
+ * Creates a new custom element class (web component) that can be registered within a DOM.
99
+ *
100
+ * @example
101
+ * ```ts
102
+ * import * as appMetadata from "open-pioneer:app";
103
+ *
104
+ * const CustomElementClazz = createCustomElement({
105
+ * component: <div>Hello World!</div>,
106
+ * appMetadata
107
+ * });
108
+ * customElements.define("sample-element", CustomElementClazz);
109
+ * ```
110
+ */
111
+ export declare function createCustomElement(options: CustomElementOptions): ApplicationElementConstructor;
@@ -0,0 +1,19 @@
1
+ /**
2
+ * Maps a package name to its supported properties.
3
+ *
4
+ * By default, properties for all packages are untyped (as Record<string, unknown>).
5
+ *
6
+ * @example
7
+ *
8
+ * ```ts
9
+ * declare module "@open-pioneer/runtime" {
10
+ * interface PropertiesRegistry {
11
+ * // Declares that properties for the "logging" package must
12
+ * // conform to the type on the right when overridden by an app.
13
+ * "logging": Partial<LoggingProperties>
14
+ * }
15
+ * }
16
+ * ```
17
+ */
18
+ export interface PropertiesRegistry {
19
+ }
package/Service.d.ts ADDED
@@ -0,0 +1,63 @@
1
+ import { PackageIntl } from "./i18n";
2
+ /** Lifecycle hooks supported by the service interface. */
3
+ export interface ServiceLifecycleHooks {
4
+ /**
5
+ * Destroys the component.
6
+ * Should clean up all resources used by the component.
7
+ */
8
+ destroy?(): void;
9
+ toString(): string;
10
+ }
11
+ export type Service<Interface extends {} = {}> = ServiceLifecycleHooks & Interface;
12
+ /**
13
+ * Represents metadata for an injected reference.
14
+ */
15
+ export interface ReferenceMeta {
16
+ /**
17
+ * The unique service id of the injected service.
18
+ */
19
+ serviceId: string;
20
+ }
21
+ /**
22
+ * Contains metadata about injected references.
23
+ * The key for the reference metadata is the reference's name.
24
+ */
25
+ export type ReferencesMeta<References extends {}> = {
26
+ [referenceName in keyof References]: References[referenceName] extends any[] ? ReferenceMeta[] : ReferenceMeta;
27
+ };
28
+ /**
29
+ * Options passed to a service's constructor.
30
+ */
31
+ export type ServiceOptions<References extends {} = {}> = {
32
+ /**
33
+ * References to other services.
34
+ * These are injected by the runtime and match the declared references of the service.
35
+ */
36
+ references: References;
37
+ /**
38
+ * Metadata about the injected references.
39
+ * The object contains one entry for every reference injected via `references` (under the same key).
40
+ *
41
+ * If a single service has been injected, `referencesMeta[key]` will be of type {@link ReferenceMeta}.
42
+ * If multiple services have been injected, an array of {@link ReferenceMeta} will be provided instead,
43
+ * where the indices match the order in the injected references array.
44
+ */
45
+ referencesMeta: ReferencesMeta<References>;
46
+ /**
47
+ * Configuration properties.
48
+ *
49
+ * Default values are taken from the package's configuration, but these can be overridden
50
+ * by the application.
51
+ */
52
+ properties: Record<string, unknown>;
53
+ /**
54
+ * A reference to the shared i18n object of the current package.
55
+ */
56
+ intl: PackageIntl;
57
+ };
58
+ /**
59
+ * A service constructor returns a service instance when calling `new`.
60
+ */
61
+ export type ServiceConstructor<References extends {} = {}, Interface extends {} = {}> = {
62
+ new (options: ServiceOptions<References>): Service<Interface>;
63
+ };
@@ -0,0 +1,25 @@
1
+ /**
2
+ * Maps a registered interface name to a service type.
3
+ * The interface can be reopened by client packages to add additional registrations.
4
+ *
5
+ * @example
6
+ *
7
+ * ```ts
8
+ * declare module "@open-pioneer/runtime" {
9
+ * interface ServiceRegistry {
10
+ * // Associates the interface name with the TypeScript interface
11
+ * "logging.LogService": Logger;
12
+ * }
13
+ * }
14
+ * ```
15
+ */
16
+ export interface ServiceRegistry {
17
+ }
18
+ /**
19
+ * A well known interface name registered with the {@link ServiceRegistry}.
20
+ */
21
+ export type InterfaceName = keyof ServiceRegistry;
22
+ /**
23
+ * Returns the registered service type for the given interface name.
24
+ */
25
+ export type ServiceType<I extends InterfaceName> = ServiceRegistry[I];
package/api.d.ts ADDED
@@ -0,0 +1,76 @@
1
+ export type ApiMethod = (...args: any[]) => any;
2
+ /**
3
+ * A record of exposed functions.
4
+ */
5
+ export type ApiMethods = Record<string, ApiMethod>;
6
+ /**
7
+ * Provides a set of methods to the application's web component API.
8
+ */
9
+ export interface ApiExtension {
10
+ /**
11
+ * Returns a set of methods that will be added to the web component's API.
12
+ */
13
+ getApiMethods(): Promise<ApiMethods>;
14
+ }
15
+ /**
16
+ * A service provided by the system.
17
+ * Used by the runtime to assemble the public facing API.
18
+ */
19
+ export interface ApiService {
20
+ /**
21
+ * Called by the runtime to gather methods that should be available from the web component's API.
22
+ */
23
+ getApi(): Promise<ApiMethods>;
24
+ }
25
+ /**
26
+ * A service provided by the system, useful for accessing values that are global to the application.
27
+ */
28
+ export interface ApplicationContext {
29
+ /**
30
+ * The web component's host element.
31
+ * This dom node can be accessed by the host site.
32
+ */
33
+ getHostElement(): HTMLElement;
34
+ /**
35
+ * The current web component's shadow root.
36
+ */
37
+ getShadowRoot(): ShadowRoot;
38
+ /**
39
+ * The node containing the rest of the application _inside_ the current web component's shadow dom.
40
+ */
41
+ getApplicationContainer(): HTMLElement;
42
+ /**
43
+ * Returns the current locale of the application.
44
+ *
45
+ * E.g. `"de-DE"`
46
+ */
47
+ getLocale(): string;
48
+ /**
49
+ * Returns the locales supported by the application, i.e.
50
+ * the locales that have associated i18n messages.
51
+ *
52
+ * For example: `["de", "en"]`
53
+ */
54
+ getSupportedLocales(): readonly string[];
55
+ }
56
+ /**
57
+ * Implementing this interface allows a service to be notified on certain
58
+ * application-wide lifecycle events.
59
+ */
60
+ export interface ApplicationLifecycleListener {
61
+ /**
62
+ * Called after all services required by the application have been started.
63
+ */
64
+ afterApplicationStart?(): void;
65
+ /**
66
+ * Called during the application shutdown just before services will be destroyed.
67
+ */
68
+ beforeApplicationStop?(): void;
69
+ }
70
+ declare module "./ServiceRegistry" {
71
+ interface ServiceRegistry {
72
+ "runtime.ApiService": ApiService;
73
+ "runtime.ApplicationContext": ApplicationContext;
74
+ "runtime.ApplicationLifecycleListener": ApplicationLifecycleListener;
75
+ }
76
+ }
@@ -0,0 +1,11 @@
1
+ import { ServiceOptions } from "../Service";
2
+ import { ApiExtension, ApiMethod, ApiService } from "../api";
3
+ interface References {
4
+ providers: ApiExtension[];
5
+ }
6
+ export declare class ApiServiceImpl implements ApiService {
7
+ private readonly providers;
8
+ constructor(options: ServiceOptions<References>);
9
+ getApi(): Promise<Record<string, ApiMethod>>;
10
+ }
11
+ export {};
@@ -0,0 +1,18 @@
1
+ import { ApplicationContext } from "../api";
2
+ import { ServiceOptions } from "../Service";
3
+ export interface ApplicationContextProperties {
4
+ host: HTMLElement;
5
+ shadowRoot: ShadowRoot;
6
+ container: HTMLElement;
7
+ locale: string;
8
+ supportedLocales: string[];
9
+ }
10
+ export declare class ApplicationContextImpl implements ApplicationContext {
11
+ #private;
12
+ constructor(options: ServiceOptions, properties: ApplicationContextProperties);
13
+ getHostElement(): HTMLElement;
14
+ getShadowRoot(): ShadowRoot;
15
+ getApplicationContainer(): HTMLElement;
16
+ getLocale(): string;
17
+ getSupportedLocales(): readonly string[];
18
+ }
@@ -0,0 +1,12 @@
1
+ import { ServiceOptions } from "../Service";
2
+ import { ServiceType } from "../ServiceRegistry";
3
+ interface References {
4
+ listeners: ServiceType<"runtime.ApplicationLifecycleListener">[];
5
+ }
6
+ export declare class ApplicationLifecycleEventService {
7
+ #private;
8
+ constructor(options: ServiceOptions<References>);
9
+ /** @internal */
10
+ emitLifecycleEvent(event: "after-start" | "before-stop"): void;
11
+ }
12
+ export {};
@@ -0,0 +1,20 @@
1
+ import { PackageRepr } from "../service-layer/PackageRepr";
2
+ import { ApplicationContextProperties } from "./ApplicationContextImpl";
3
+ export declare const RUNTIME_PACKAGE_NAME = "@open-pioneer/runtime";
4
+ export declare const RUNTIME_API_EXTENSION = "integration.ApiExtension";
5
+ export declare const RUNTIME_API_SERVICE = "runtime.ApiService";
6
+ export declare const RUNTIME_APPLICATION_CONTEXT = "runtime.ApplicationContext";
7
+ export declare const RUNTIME_APPLICATION_LIFECYCLE_EVENT_SERVICE = "runtime.ApplicationLifecycleEventService";
8
+ export declare const RUNTIME_AUTO_START = "runtime.AutoStart";
9
+ export type BuiltinPackageProperties = ApplicationContextProperties;
10
+ /**
11
+ * Creates the builtin package containing the builtin services.
12
+ *
13
+ * The runtime package should not use services in the `build.config.mjs`
14
+ * for a clean bootstrapping procedure (it will be instantiated without
15
+ * generated application metadata in tests).
16
+ *
17
+ * This function is called as part of the service layer startup.
18
+ * The package produced here is always part of the application.
19
+ */
20
+ export declare function createBuiltinPackage(properties: BuiltinPackageProperties): PackageRepr;
package/errors.d.ts ADDED
@@ -0,0 +1,17 @@
1
+ export declare enum ErrorId {
2
+ INVALID_METADATA = "runtime:invalid-metadata",
3
+ INVALID_PROPERTY_NAME = "runtime:invalid-property-name",
4
+ REQUIRED_PROPERTY = "runtime:required-property",
5
+ NOT_MOUNTED = "runtime:element-not-mounted",
6
+ UNSUPPORTED_LOCALE = "runtime:unsupported-locale",
7
+ CONFIG_RESOLUTION_FAILED = "runtime:config-resolution-failed",
8
+ INTERFACE_NOT_FOUND = "runtime:interface-not-found",
9
+ AMBIGUOUS_DEPENDENCY = "runtime:ambiguous-dependency",
10
+ UNDECLARED_DEPENDENCY = "runtime:undeclared-dependency",
11
+ SERVICE_CONSTRUCTION_FAILED = "runtime:service-construction-failed",
12
+ SERVICE_DESTRUCTION_FAILED = "runtime:service-destruction-failed",
13
+ DUPLICATE_INTERFACE = "runtime:duplicate-interface",
14
+ DEPENDENCY_CYCLE = "runtime:dependency-cycle",
15
+ DUPLICATE_API_METHODS = "runtime:duplicate-api-methods",
16
+ INTERNAL = "runtime:internal-error"
17
+ }
package/i18n.d.ts ADDED
@@ -0,0 +1,42 @@
1
+ import { IntlFormatters, IntlShape } from "@formatjs/intl";
2
+ import { ApplicationMetadata } from "./metadata";
3
+ /**
4
+ * Represents i18n info for the entire application.
5
+ * Currently not exposed to user code.
6
+ */
7
+ export interface AppI18n {
8
+ /** Chosen locale */
9
+ readonly locale: string;
10
+ /** Supported locales from app metadata. */
11
+ readonly supportedLocales: string[];
12
+ /** Given the package name, constructs a package i18n instance. */
13
+ createPackageI18n(packageName: string): PackageIntl;
14
+ }
15
+ /**
16
+ * Gives access to the package's i18n messages for the current locale.
17
+ *
18
+ * See also https://formatjs.io/docs/intl
19
+ */
20
+ export type PackageIntl = Pick<IntlShape, "locale" | "timeZone"> & IntlFormatters<string>;
21
+ /**
22
+ * Initializes the application's locale and fetches the appropriate i18n messages.
23
+ */
24
+ export declare function initI18n(appMetadata: ApplicationMetadata | undefined, forcedLocale: string | undefined): Promise<AppI18n>;
25
+ /** Creates an empty i18n instance, e.g. for tests. */
26
+ export declare function createEmptyI18n(locale?: string): PackageIntl;
27
+ export interface LocalePickResult {
28
+ /** The actual locale (e.g. en-US) for number and date formatting etc. */
29
+ locale: string;
30
+ /**
31
+ * The locale identifier to load messages for. E.g. "en".
32
+ */
33
+ messageLocale: string;
34
+ }
35
+ /**
36
+ * Picks a locale for the app. Exported for tests.
37
+ *
38
+ * @param forcedLocale Optional forced locale (must be satisfied)
39
+ * @param appLocales Locales the app has i18n messages for (e.g. "en", "de")
40
+ * @param userLocales Locales requested by the user's browser
41
+ */
42
+ export declare function pickLocale(forcedLocale: string | undefined, appLocales: string[], userLocales: string[]): LocalePickResult;
package/index.d.ts ADDED
@@ -0,0 +1,6 @@
1
+ export * from "./api";
2
+ export { type PackageIntl } from "./i18n";
3
+ export { type ApplicationElement, type ApplicationElementConstructor, type ApplicationProperties, type ApplicationConfig, type CustomElementOptions, type ConfigContext, type RawApplicationProperties, createCustomElement } from "./CustomElement";
4
+ export * from "./Service";
5
+ export * from "./ServiceRegistry";
6
+ export * from "./PropertiesRegistry";
@@ -0,0 +1,23 @@
1
+ import { Resource } from "@open-pioneer/core";
2
+ export interface ObservableBox<T> {
3
+ /** The current value. */
4
+ readonly value: T;
5
+ /**
6
+ * Changes the current value.
7
+ *
8
+ * Note that this function is only present during development to facilitate hot reloading.
9
+ */
10
+ setValue?(value: T): void;
11
+ /**
12
+ * Register a listener callback that will be invoked
13
+ * when the value changes.
14
+ *
15
+ * Note that this function is only present during development to facilitate hot reloading.
16
+ */
17
+ on?(event: "changed", listener: () => void): Resource;
18
+ }
19
+ /**
20
+ * Returns a boxed value.
21
+ * In development node, the box value can be changed and observed.
22
+ */
23
+ export declare function createBox<T>(value: T): ObservableBox<T>;
@@ -0,0 +1,115 @@
1
+ import { ServiceConstructor } from "../Service";
2
+ import { ObservableBox } from "./ObservableBox";
3
+ /**
4
+ * Application metadata.
5
+ * Typically generated by the build system.
6
+ */
7
+ export interface ApplicationMetadata {
8
+ /**
9
+ * Package metadata.
10
+ * Metadata structures contain information about services
11
+ * that are needed during runtime.
12
+ *
13
+ * Services provided by packages in this attribute will be started
14
+ * as necessary and can be referenced during runtime.
15
+ */
16
+ packages?: Record<string, PackageMetadata>;
17
+ /**
18
+ * Styles for UI component.
19
+ */
20
+ styles?: ObservableBox<string>;
21
+ /**
22
+ * Locales supported by the application.
23
+ */
24
+ locales?: string[];
25
+ /**
26
+ * Loads messages for the given locale.
27
+ * @returns A record of packageName -> (messageId, messageTemplate) entries.
28
+ */
29
+ loadMessages?: (locale: string) => Promise<Record<string, Record<string, string>>>;
30
+ }
31
+ /**
32
+ * Describes a package to the runtime.
33
+ */
34
+ export interface PackageMetadata {
35
+ /** The globally unique name of the package. */
36
+ name: string;
37
+ /**
38
+ * Collection of services defined in the package.
39
+ *
40
+ * Key: unique service name within the package.
41
+ * Value: service metadata.
42
+ */
43
+ services?: Record<string, ServiceMetadata>;
44
+ /**
45
+ * Metadata about the UI Components contained in this package.
46
+ */
47
+ ui?: UiMetadata;
48
+ /**
49
+ * Metadata about properties of this package.
50
+ */
51
+ properties?: Record<string, PropertyMetadata>;
52
+ }
53
+ /**
54
+ * Describes a service to the runtime.
55
+ */
56
+ export interface ServiceMetadata {
57
+ /** The unique name of the service in its package. */
58
+ name: string;
59
+ /** Service constructor responsible for creating a new instance. */
60
+ clazz: ServiceConstructor<any>;
61
+ /**
62
+ * Collection of references to other services.
63
+ * The runtime will inject the required services when possible
64
+ * or provide a diagnostic if not.
65
+ *
66
+ * Key: reference name.
67
+ * Value: reference metadata.
68
+ */
69
+ references?: Record<string, InterfaceReferenceMetadata>;
70
+ /**
71
+ * Lists interfaces provided by this service.
72
+ */
73
+ provides?: ProvidedInterfaceMetadata[];
74
+ }
75
+ /**
76
+ * Describes a service reference to the runtime.
77
+ */
78
+ export interface InterfaceReferenceMetadata {
79
+ /** The name of the referenced interface. */
80
+ name: string;
81
+ /** Additional qualifier to disambiguate interface requirements. */
82
+ qualifier?: string | undefined;
83
+ /** Inject all implementations as an array instead of a specific one. */
84
+ all?: boolean;
85
+ }
86
+ /**
87
+ * Describes a provided interface to the runtime.
88
+ */
89
+ export interface ProvidedInterfaceMetadata {
90
+ /** The name of the provided interface. */
91
+ name: string;
92
+ /** Additional qualifier for disambiguation of multiple interface implementations. */
93
+ qualifier?: string | undefined;
94
+ }
95
+ /**
96
+ * Describes the UI to the runtime.
97
+ */
98
+ export interface UiMetadata {
99
+ /**
100
+ * List of interface names required by the UI.
101
+ * Interfaces in this list can be used by calling the `useService` hook
102
+ * from a react component.
103
+ */
104
+ references?: InterfaceReferenceMetadata[];
105
+ }
106
+ /**
107
+ * Metadata about a single property in a package.
108
+ */
109
+ export interface PropertyMetadata {
110
+ /** Default json value defined by the package. */
111
+ value: unknown;
112
+ /** Whether the property must be specified by the application. */
113
+ required?: boolean;
114
+ }
115
+ export { type ObservableBox, createBox } from "./ObservableBox";
package/package.json CHANGED
@@ -1,25 +1,28 @@
1
1
  {
2
2
  "type": "module",
3
3
  "name": "@open-pioneer/runtime",
4
- "version": "0.1.1",
4
+ "version": "0.1.2",
5
5
  "license": "Apache-2.0",
6
6
  "dependencies": {
7
7
  "@formatjs/intl": "^2.7.2",
8
8
  "react": "^18.2.0",
9
9
  "react-dom": "^18.2.0",
10
- "@open-pioneer/chakra-integration": "^0.1.1",
11
- "@open-pioneer/core": "^0.1.1"
10
+ "@open-pioneer/chakra-integration": "^0.1.2",
11
+ "@open-pioneer/core": "^0.1.2"
12
12
  },
13
13
  "exports": {
14
14
  "./package.json": "./package.json",
15
15
  ".": {
16
- "import": "./index.js"
16
+ "import": "./index.js",
17
+ "types": "./index.d.ts"
17
18
  },
18
19
  "./metadata": {
19
- "import": "./metadata/index.js"
20
+ "import": "./metadata/index.js",
21
+ "types": "./metadata/index.d.ts"
20
22
  },
21
23
  "./react-integration": {
22
- "import": "./react-integration/index.js"
24
+ "import": "./react-integration/index.js",
25
+ "types": "./react-integration/index.d.ts"
23
26
  }
24
27
  },
25
28
  "openPioneerFramework": {
@@ -0,0 +1,11 @@
1
+ /// <reference types="react" />
2
+ import { PackageIntl } from "../i18n";
3
+ import { Service } from "../Service";
4
+ import { UseServiceOptions } from "./hooks";
5
+ export interface PackageContextMethods {
6
+ getService: (packageName: string, interfaceName: string, options: UseServiceOptions) => Service;
7
+ getServices: (packageName: string, interfaceName: string) => Service[];
8
+ getProperties: (packageName: string) => Readonly<Record<string, unknown>>;
9
+ getIntl(packageName: string): PackageIntl;
10
+ }
11
+ export declare const PackageContext: import("react").Context<PackageContextMethods | null>;
@@ -0,0 +1,20 @@
1
+ import { ComponentType } from "react";
2
+ import { ServiceLayer } from "../service-layer/ServiceLayer";
3
+ import { PackageRepr } from "../service-layer/PackageRepr";
4
+ export interface ReactIntegrationOptions {
5
+ packages: Map<string, PackageRepr>;
6
+ serviceLayer: ServiceLayer;
7
+ rootNode: HTMLDivElement;
8
+ container: Node;
9
+ }
10
+ export declare class ReactIntegration {
11
+ private containerNode;
12
+ private packages;
13
+ private serviceLayer;
14
+ private root;
15
+ private packageContext;
16
+ constructor(options: ReactIntegrationOptions);
17
+ render(Component: ComponentType, props: Record<string, unknown>): void;
18
+ destroy(): void;
19
+ private getPackage;
20
+ }
@@ -0,0 +1,46 @@
1
+ import { InterfaceName, ServiceType } from "../ServiceRegistry";
2
+ import { PackageIntl } from "../i18n";
3
+ export interface UseServiceOptions {
4
+ /** An additional qualifier to disambiguate service instances that implement the same interface. */
5
+ qualifier?: string;
6
+ }
7
+ /**
8
+ * Returns a service that implements the given interface.
9
+ * Receives the package name of the importing package as a string.
10
+ *
11
+ * This is an internal hook that is typically called indirectly via the hook
12
+ * provided from `"open-pioneer:react-hooks"`.
13
+ *
14
+ * @private
15
+ */
16
+ export declare function useServiceInternal<Interface extends InterfaceName>(packageName: string, interfaceName: Interface, options?: UseServiceOptions): ServiceType<Interface>;
17
+ export declare function useServiceInternal(packageName: string, interfaceName: string, options?: UseServiceOptions): unknown;
18
+ /**
19
+ * Returns all services that implement the given interface.
20
+ * Receives the package name of the importing package as a string.
21
+ *
22
+ * This is an internal hook that is typically called indirectly via the hook
23
+ * provided from `"open-pioneer:react-hooks"`.
24
+ *
25
+ * @private
26
+ */
27
+ export declare function useServicesInternal<Interface extends InterfaceName>(packageName: string, interfaceName: Interface): ServiceType<Interface>[];
28
+ export declare function useServicesInternal(packageName: string, interfaceName: string): unknown[];
29
+ /**
30
+ * Returns the properties for the given package.
31
+ *
32
+ * This is an internal hook that is typically called indirectly via the hook
33
+ * provided from `"open-pioneer:react-hooks"`.
34
+ *
35
+ * @private
36
+ */
37
+ export declare function usePropertiesInternal(packageName: string): Readonly<Record<string, unknown>>;
38
+ /**
39
+ * Returns the i18n object for the given package.
40
+ *
41
+ * This is an internal hook that is typically called indirectly via the hook
42
+ * provided from `"open-pioneer:react-hooks"`.
43
+ *
44
+ * @private
45
+ */
46
+ export declare function useIntlInternal(packageName: string): PackageIntl;
@@ -0,0 +1,2 @@
1
+ export { useServiceInternal, useServicesInternal, usePropertiesInternal, useIntlInternal, type UseServiceOptions } from "./hooks";
2
+ export { PackageContext, type PackageContextMethods } from "./PackageContext";
@@ -0,0 +1,22 @@
1
+ import { InterfaceReferenceMetadata } from "../metadata";
2
+ /**
3
+ * Describes the implementation of an interface.
4
+ */
5
+ export interface InterfaceSpec {
6
+ interfaceName: string;
7
+ qualifier?: string | undefined;
8
+ }
9
+ export declare function renderInterfaceSpec({ interfaceName, qualifier }: InterfaceSpec): string;
10
+ export interface SingleImplementationSpec extends InterfaceSpec {
11
+ all?: undefined;
12
+ }
13
+ export interface AllImplementationsSpec extends Pick<InterfaceSpec, "interfaceName"> {
14
+ all: true;
15
+ }
16
+ /**
17
+ * Describes a reference to one or more implementations of an interface.
18
+ */
19
+ export type ReferenceSpec = SingleImplementationSpec | AllImplementationsSpec;
20
+ export declare function parseReferenceSpec(metadata: InterfaceReferenceMetadata): ReferenceSpec;
21
+ export declare function isSingleImplementationSpec(spec: ReferenceSpec): spec is SingleImplementationSpec;
22
+ export declare function isAllImplementationsSpec(spec: ReferenceSpec): spec is AllImplementationsSpec;
@@ -0,0 +1,27 @@
1
+ import { ApplicationProperties } from "../CustomElement";
2
+ import { PackageIntl, AppI18n } from "../i18n";
3
+ import { PackageMetadata } from "../metadata";
4
+ import { ReferenceSpec } from "./InterfaceSpec";
5
+ import { ServiceRepr } from "./ServiceRepr";
6
+ export interface PackageReprOptions {
7
+ name: string;
8
+ intl: PackageIntl;
9
+ services?: ServiceRepr[];
10
+ uiReferences?: ReferenceSpec[];
11
+ properties?: Record<string, unknown>;
12
+ }
13
+ export declare class PackageRepr {
14
+ static create(data: PackageMetadata, i18n: PackageIntl, customProperties?: Record<string, unknown>): PackageRepr;
15
+ /** Package name */
16
+ readonly name: string;
17
+ /** Services defined by the package */
18
+ readonly services: readonly ServiceRepr[];
19
+ /** Interfaces required by UI components. */
20
+ readonly uiReferences: readonly Readonly<ReferenceSpec>[];
21
+ /** Resolved (perhaps customized) package properties. */
22
+ readonly properties: Readonly<Record<string, unknown>>;
23
+ /** Locale-dependant i18n messages. */
24
+ readonly intl: PackageIntl;
25
+ constructor(options: PackageReprOptions);
26
+ }
27
+ export declare function createPackages(packages: Record<string, PackageMetadata>, i18n: AppI18n, customProperties?: ApplicationProperties): PackageRepr[];
@@ -0,0 +1,61 @@
1
+ import { PackageRepr } from "./PackageRepr";
2
+ import { ServiceLookupResult, ServicesLookupResult } from "./ServiceLookup";
3
+ import { InterfaceSpec, ReferenceSpec } from "./InterfaceSpec";
4
+ export type DynamicLookupResult = ServiceLookupResult | UndeclaredDependency;
5
+ export interface UndeclaredDependency {
6
+ type: "undeclared";
7
+ }
8
+ export declare class ServiceLayer {
9
+ private allServices;
10
+ private requiredServices;
11
+ private serviceLookup;
12
+ private serviceDependencies;
13
+ private declaredDependencies;
14
+ private state;
15
+ /**
16
+ * Constructs a new service layer instance.
17
+ * Requires the application's set of packages (from which services are taken)
18
+ * and an optional set of forced references (interfaces whose implementing services will be started unconditionally).
19
+ *
20
+ * In its current form, the service layer will start only forced references and references needed by the UI (and their dependencies).
21
+ */
22
+ constructor(packages: readonly PackageRepr[], forcedReferences?: ReferenceSpec[]);
23
+ destroy(): void;
24
+ start(): void;
25
+ /**
26
+ * Returns a service implementing the given interface.
27
+ * Checks that the given package actually declared a dependency on that interface
28
+ * to enforce coding guidelines.
29
+ *
30
+ * @param packageName the name of the package requesting the import
31
+ * @param spec the interface specifier
32
+ * @param options advanced options to customize lookup
33
+ * @throws if the service layer is not in 'started' state or if no service implements the interface.
34
+ */
35
+ getService(packageName: string, spec: InterfaceSpec, options?: {
36
+ ignoreDeclarationCheck?: boolean;
37
+ }): ServiceLookupResult | UndeclaredDependency;
38
+ /**
39
+ * Returns all services implementing the given interface.
40
+ * Requires that the dependency on all implementations has been declared in the package.
41
+ *
42
+ * @param packageName the name of the package requesting the import
43
+ * @param interfaceName the interface name
44
+ *
45
+ * @throws if the service layer is not in 'started'.
46
+ */
47
+ getServices(packageName: string, interfaceName: string): ServicesLookupResult | UndeclaredDependency;
48
+ /**
49
+ * Initializes the given service and its dependencies.
50
+ * Dependencies are initialized before the service that requires them.
51
+ */
52
+ private createService;
53
+ /**
54
+ * Destroys the given service and its dependencies.
55
+ * The dependencies are destroyed after the service.
56
+ */
57
+ private destroyService;
58
+ private isDeclaredDependency;
59
+ private getReference;
60
+ private getServiceDeps;
61
+ }
@@ -0,0 +1,46 @@
1
+ import { InterfaceSpec, ReferenceSpec } from "./InterfaceSpec";
2
+ import { ServiceRepr } from "./ServiceRepr";
3
+ export type ReadonlyServiceLookup = Pick<ServiceLookup, "lookup" | "lookupOne" | "lookupAll" | "serviceCount">;
4
+ export interface Unimplemented {
5
+ type: "unimplemented";
6
+ }
7
+ export interface Ambiguous {
8
+ type: "ambiguous";
9
+ choices: AmbiguousChoice[];
10
+ }
11
+ export type AmbiguousChoice = [serviceId: string, qualifier: string | undefined];
12
+ export interface Found<T> {
13
+ type: "found";
14
+ value: T;
15
+ }
16
+ export type ServiceLookupResult = Unimplemented | Ambiguous | Found<ServiceRepr>;
17
+ export type ServicesLookupResult = Found<ServiceRepr[]>;
18
+ export declare class ServiceLookup {
19
+ private services;
20
+ private _count;
21
+ /**
22
+ * Returns the total number of registered services.
23
+ */
24
+ get serviceCount(): number;
25
+ /**
26
+ * Attempts to register the given service as an implementation of `interfaceName`.
27
+ * Throws if the registration did not complete successfully.
28
+ *
29
+ * All services should be registered before any lookups are attempted.
30
+ */
31
+ register(service: ServiceRepr, { interfaceName, qualifier }: InterfaceSpec): void;
32
+ /**
33
+ * Attempts to find the service(s) required by the given reference spec.
34
+ */
35
+ lookup(ref: ReferenceSpec): ServiceLookupResult | ServicesLookupResult;
36
+ /**
37
+ * Attempts to find a service implementing the given interface.
38
+ */
39
+ lookupOne({ interfaceName, qualifier }: InterfaceSpec): ServiceLookupResult;
40
+ /**
41
+ * Returns all services implementing the given interface.
42
+ */
43
+ lookupAll(interfaceName: string): ServicesLookupResult;
44
+ private ensureInterfaceEntry;
45
+ }
46
+ export declare function renderAmbiguousServiceChoices(choices: AmbiguousChoice[], max?: number): string;
@@ -0,0 +1,94 @@
1
+ import { ServiceMetadata } from "../metadata";
2
+ import { Service, ServiceConstructor, ServiceOptions } from "../Service";
3
+ import { InterfaceSpec, ReferenceSpec } from "./InterfaceSpec";
4
+ import { PackageIntl } from "../i18n";
5
+ export type ServiceState = "not-constructed" | "constructing" | "constructed" | "destroyed";
6
+ export type ServiceDependency = ReferenceSpec & {
7
+ referenceName: string;
8
+ };
9
+ export interface ConstructorFactory {
10
+ type: "class";
11
+ clazz: ServiceConstructor<any>;
12
+ }
13
+ export interface FunctionFactory {
14
+ type: "function";
15
+ create: (options: ServiceOptions) => Service;
16
+ }
17
+ export type ServiceFactory = ConstructorFactory | FunctionFactory;
18
+ export interface ServiceReprOptions {
19
+ name: string;
20
+ packageName: string;
21
+ factory: ServiceFactory;
22
+ intl: PackageIntl;
23
+ dependencies?: ServiceDependency[];
24
+ interfaces?: InterfaceSpec[];
25
+ properties?: Record<string, unknown>;
26
+ }
27
+ /**
28
+ * Represents metadata and state of a service in the runtime.
29
+ * `this.instance` is the actual service instance (when constructed).
30
+ */
31
+ export declare class ServiceRepr {
32
+ static create(packageName: string, data: ServiceMetadata, intl: PackageIntl, properties?: Record<string, unknown>): ServiceRepr;
33
+ /** Unique id of this service. Contains the package name and the service name. */
34
+ readonly id: string;
35
+ /** Name of this service in it's package. */
36
+ readonly name: string;
37
+ /** Name of the parent package. */
38
+ readonly packageName: string;
39
+ /** Locale-dependant i18n messages. */
40
+ readonly intl: PackageIntl;
41
+ /** Service properties made available via the service's constructor. */
42
+ readonly properties: Readonly<Record<string, unknown>>;
43
+ /** Dependencies required by the service constructor. */
44
+ readonly dependencies: readonly ServiceDependency[];
45
+ /** Interfaces provided by the service. */
46
+ readonly interfaces: readonly Readonly<InterfaceSpec>[];
47
+ /** Number of references to this service. */
48
+ private _useCount;
49
+ /** Service factory to construct an instance. */
50
+ private factory;
51
+ /** Current state of this service. "constructed" -> instance is available. */
52
+ private _state;
53
+ /** Service instance, once constructed. */
54
+ private _instance;
55
+ constructor(options: ServiceReprOptions);
56
+ /** Returns the current service instance or undefined if the service has not been constructed. */
57
+ get instance(): Service | undefined;
58
+ /** Returns the current state of the service. */
59
+ get state(): ServiceState;
60
+ /** Returns the current reference count. */
61
+ get useCount(): number;
62
+ /**
63
+ * Same as `instance`, but throws when the instance has not been constructed.
64
+ */
65
+ getInstanceOrThrow(): import("../Service").ServiceLifecycleHooks;
66
+ /**
67
+ * Called before `create()` to place the service into the `constructing` state,
68
+ * which is currently used to detect cycles.
69
+ */
70
+ beforeCreate(): void;
71
+ /**
72
+ * Instantiates the service by invoking the service constructor
73
+ * with the given `options`.
74
+ *
75
+ * The service's use count is initialized to `1`, so every `create()`
76
+ * should be paired with a `removeRef()`.
77
+ *
78
+ * `destroy()` can be invoked once the final `removeRef()` has returned zero.
79
+ */
80
+ create(options: Pick<ServiceOptions, "references" | "referencesMeta">): import("../Service").ServiceLifecycleHooks;
81
+ destroy(): void;
82
+ /**
83
+ * Adds a use to the service's use count.
84
+ * References to a service are tracked: it should only be destroyed when it is no longer being used.
85
+ */
86
+ addRef(): number;
87
+ /**
88
+ * Removes a use from the service's use count.
89
+ * Returns the new use count.
90
+ */
91
+ removeRef(): number;
92
+ }
93
+ export declare function createConstructorFactory<T extends {}>(clazz: ServiceConstructor<T>): ConstructorFactory;
94
+ export declare function createFunctionFactory(create: (options: ServiceOptions) => Service): FunctionFactory;
@@ -0,0 +1,42 @@
1
+ import { ReferenceSpec } from "./InterfaceSpec";
2
+ import { ReadonlyServiceLookup } from "./ServiceLookup";
3
+ import { ServiceRepr } from "./ServiceRepr";
4
+ export interface DependencyOptions {
5
+ /**
6
+ * All services known to the service layer.
7
+ */
8
+ services?: readonly ServiceRepr[];
9
+ /**
10
+ * References that must be satisfied by the services.
11
+ */
12
+ requiredReferences?: readonly RequiredReference[];
13
+ }
14
+ export type RequiredReference = UIDependency | FrameworkDependency;
15
+ export type UIDependency = {
16
+ type: "ui";
17
+ packageName: string;
18
+ } & ReferenceSpec;
19
+ export type FrameworkDependency = {
20
+ type: "framework";
21
+ } & ReferenceSpec;
22
+ export type ComputedServiceDependencies = Record<string, ServiceRepr | ServiceRepr[]>;
23
+ export interface VerifyDependenciesResult {
24
+ /**
25
+ * Precomputed dependencies for every service.
26
+ *
27
+ * Key: service id.
28
+ */
29
+ serviceDependencies: Map<string, ComputedServiceDependencies>;
30
+ /**
31
+ * Index structure mapping interface names to service instances.
32
+ */
33
+ serviceLookup: ReadonlyServiceLookup;
34
+ }
35
+ /**
36
+ * Visits all services and ensures that their dependencies can be satisfied by each other without a cycle.
37
+ *
38
+ * Throws an error if a cycle is detected or if a required service is never implemented.
39
+ *
40
+ * @returns an object containing the service index and precomputed dependency information
41
+ */
42
+ export declare function verifyDependencies(options: DependencyOptions): VerifyDependenciesResult;