@open-pioneer/runtime 2.0.1 → 2.1.0
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 +59 -0
- package/DeclaredService.d.ts +34 -5
- package/index.d.ts +1 -1
- package/package.json +4 -4
- package/react-integration/hooks.js.map +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,64 @@
|
|
|
1
1
|
# @open-pioneer/runtime
|
|
2
2
|
|
|
3
|
+
## 2.1.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 80cd62d: Improve TypeScript integration for service classes.
|
|
8
|
+
|
|
9
|
+
Add a way for a service class to specify its interface name directly.
|
|
10
|
+
Usually services used across package boundaries split their public interface and their implementation such as this:
|
|
11
|
+
|
|
12
|
+
```ts
|
|
13
|
+
// Exported from package
|
|
14
|
+
interface MyService extends DeclaredService<"my-package.SomeInterface"> {
|
|
15
|
+
method(): void;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
// In an implementation file, usually private.
|
|
19
|
+
class MyServiceImpl implements MyService {
|
|
20
|
+
method(): void {
|
|
21
|
+
// ...
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Until now, there was no way for a service class to declare its interface directly.
|
|
27
|
+
This could be convenient within a package, or with a group of tightly coupled packages:
|
|
28
|
+
|
|
29
|
+
```ts
|
|
30
|
+
// Error: Type 'MyServiceImpl' has no properties in common with type 'DeclaredService<"my-package.InterfaceName">'.
|
|
31
|
+
class MyServiceImpl implements DeclaredService<"my-package.InterfaceName"> {
|
|
32
|
+
method() {}
|
|
33
|
+
}
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
From now on, you can write this instead:
|
|
37
|
+
|
|
38
|
+
```ts
|
|
39
|
+
class MyServiceImpl {
|
|
40
|
+
// Tells TypeScript which interface name must be used.
|
|
41
|
+
// See documentation of `DECLARE_SERVICE_INTERFACE` for more details.
|
|
42
|
+
declare [DECLARE_SERVICE_INTERFACE]: "my-package.InterfaceName";
|
|
43
|
+
|
|
44
|
+
method(): void {
|
|
45
|
+
// ...
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
### Patch Changes
|
|
51
|
+
|
|
52
|
+
- @open-pioneer/runtime-react-support@1.0.0
|
|
53
|
+
|
|
54
|
+
## 2.0.2
|
|
55
|
+
|
|
56
|
+
### Patch Changes
|
|
57
|
+
|
|
58
|
+
- Updated dependencies [11b1428]
|
|
59
|
+
- @open-pioneer/core@1.2.1
|
|
60
|
+
- @open-pioneer/runtime-react-support@1.0.0
|
|
61
|
+
|
|
3
62
|
## 2.0.1
|
|
4
63
|
|
|
5
64
|
### Patch Changes
|
package/DeclaredService.d.ts
CHANGED
|
@@ -5,6 +5,10 @@ declare const ERROR: unique symbol;
|
|
|
5
5
|
*
|
|
6
6
|
* By using this base interface, you can ensure that users of your interface use the correct interface name.
|
|
7
7
|
*
|
|
8
|
+
* Note that this interface is a type level marker only.
|
|
9
|
+
* It has no real associated methods or properties and it is not necessary to implement anything
|
|
10
|
+
* to use this interface in a class.
|
|
11
|
+
*
|
|
8
12
|
* @example
|
|
9
13
|
* ```ts
|
|
10
14
|
* // MyLogger should be referenced via "my-package.Logger"
|
|
@@ -30,9 +34,34 @@ export interface DeclaredService<InterfaceName extends string> {
|
|
|
30
34
|
[INTERNAL_ASSOCIATED_SERVICE_METADATA]?: ServiceMetadata<InterfaceName>;
|
|
31
35
|
}
|
|
32
36
|
/**
|
|
33
|
-
*
|
|
37
|
+
* Helper symbol to declare a service's interface name when not using a separate interface.
|
|
38
|
+
*
|
|
39
|
+
* > NOTE: This symbol does not exist at runtime. Declaring a service interface is compile time only!
|
|
40
|
+
*
|
|
41
|
+
* @example
|
|
42
|
+
*
|
|
43
|
+
* ```ts
|
|
44
|
+
* class MyServiceImpl {
|
|
45
|
+
* // Add this line to your class.
|
|
46
|
+
* // It declares (at compile time) that the service class must be used via the given interface name.
|
|
47
|
+
* // Note that the property is not really present at runtime.
|
|
48
|
+
* declare [DECLARE_SERVICE_INTERFACE]: "my-package.MyInterface";
|
|
49
|
+
*
|
|
50
|
+
* method(): void {
|
|
51
|
+
* throw new Error("Method not implemented.");
|
|
52
|
+
* }
|
|
53
|
+
* }
|
|
54
|
+
* ```
|
|
55
|
+
*/
|
|
56
|
+
declare const DECLARE_SERVICE_INTERFACE: unique symbol;
|
|
57
|
+
export { type DECLARE_SERVICE_INTERFACE };
|
|
58
|
+
/**
|
|
59
|
+
* Given a type implementing {@link DeclaredService} or using {@link DECLARE_SERVICE_INTERFACE},
|
|
60
|
+
* this type will produce the interface name associated with the service type.
|
|
34
61
|
*/
|
|
35
|
-
export type AssociatedInterfaceName<T
|
|
62
|
+
export type AssociatedInterfaceName<T> = T extends DeclaredService<infer InterfaceName> ? InterfaceName : T extends {
|
|
63
|
+
[DECLARE_SERVICE_INTERFACE]: string & infer InterfaceName;
|
|
64
|
+
} ? InterfaceName : never;
|
|
36
65
|
/**
|
|
37
66
|
* This helper type produces the expected `interfaceName` (a string parameter) for the given service type.
|
|
38
67
|
*
|
|
@@ -40,13 +69,13 @@ export type AssociatedInterfaceName<T extends DeclaredService<string>> = T exten
|
|
|
40
69
|
* 2. If `ServiceType` implements {@link DeclaredService}, it will enforce the associated interface name.
|
|
41
70
|
* 3. Otherwise, a compile time error is generated.
|
|
42
71
|
*/
|
|
43
|
-
export type InterfaceNameForServiceType<ServiceType> =
|
|
72
|
+
export type InterfaceNameForServiceType<ServiceType> = IsUnknown<ServiceType> extends true ? string : AssociatedInterfaceName<ServiceType> extends never ? {
|
|
44
73
|
[ERROR]: "TypeScript integration was not set up properly for this service. Make sure the service's TypeScript interface extends 'DeclaredService'.";
|
|
45
|
-
}
|
|
74
|
+
} : AssociatedInterfaceName<ServiceType>;
|
|
46
75
|
/**
|
|
47
76
|
* @internal
|
|
48
77
|
*/
|
|
49
78
|
interface ServiceMetadata<InterfaceName> {
|
|
50
79
|
interfaceName: InterfaceName;
|
|
51
80
|
}
|
|
52
|
-
|
|
81
|
+
type IsUnknown<T> = unknown extends T ? ([T] extends [null] ? false : true) : false;
|
package/index.d.ts
CHANGED
|
@@ -2,4 +2,4 @@ export * from "./api";
|
|
|
2
2
|
export { type PackageIntl } from "./i18n";
|
|
3
3
|
export { type ApplicationElement, type ApplicationElementConstructor, type ApplicationProperties, type ApplicationConfig, type CustomElementOptions, type ConfigContext, createCustomElement } from "./CustomElement";
|
|
4
4
|
export * from "./Service";
|
|
5
|
-
export { type DeclaredService, type AssociatedInterfaceName, type InterfaceNameForServiceType } from "./DeclaredService";
|
|
5
|
+
export { type DeclaredService, type AssociatedInterfaceName, type InterfaceNameForServiceType, type DECLARE_SERVICE_INTERFACE } from "./DeclaredService";
|
package/package.json
CHANGED
|
@@ -1,16 +1,16 @@
|
|
|
1
1
|
{
|
|
2
2
|
"type": "module",
|
|
3
3
|
"name": "@open-pioneer/runtime",
|
|
4
|
-
"version": "2.0
|
|
4
|
+
"version": "2.1.0",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"peerDependencies": {
|
|
7
7
|
"@formatjs/intl": "^2.9.9",
|
|
8
8
|
"react": "^18.2.0",
|
|
9
9
|
"react-dom": "^18.2.0",
|
|
10
|
-
"@open-pioneer/core": "^1.2.0",
|
|
11
10
|
"@open-pioneer/base-theme": "^0.2.0",
|
|
12
|
-
"@open-pioneer/
|
|
13
|
-
"@open-pioneer/
|
|
11
|
+
"@open-pioneer/chakra-integration": "^1.1.1",
|
|
12
|
+
"@open-pioneer/core": "^1.2.1",
|
|
13
|
+
"@open-pioneer/runtime-react-support": "^1.0.0"
|
|
14
14
|
},
|
|
15
15
|
"exports": {
|
|
16
16
|
"./package.json": "./package.json",
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"hooks.js","sources":["hooks.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2023 Open Pioneer project (https://github.com/open-pioneer)\n// SPDX-License-Identifier: Apache-2.0\nimport { useContext, useMemo } from \"react\";\nimport { Error } from \"@open-pioneer/core\";\nimport {\n PackageContext as PackageContext,\n PackageContextMethods\n} from \"@open-pioneer/runtime-react-support\";\nimport { ErrorId } from \"../errors\";\nimport { PackageIntl } from \"../i18n\";\nimport { InterfaceNameForServiceType } from \"../DeclaredService\";\n\n/*\n\n IMPORTANT\n =========\n\n The functions in this file are part of the public API.\n They are imported by code generated during separate package generation via:\n\n import { hookName } from '@open-pioneer/runtime/react-integration'\n\n The matching exports are in the neighboring `index.ts`.\n The interfaces of these hooks must remain stable so that already published packages can continue to work in the future.\n\n See also the implementation of @open-pioneer/build-package.\n\n*/\n\nexport interface UseServiceOptions {\n /** An additional qualifier to disambiguate service instances that implement the same interface. */\n qualifier?: string;\n}\n\n/**\n * Returns a service that implements the given interface.\n * Receives the package name of the importing package as a string.\n *\n * This is an internal hook that is typically called indirectly via the hook\n * provided from `\"open-pioneer:react-hooks\"`.\n *\n * @private\n */\nexport function useServiceInternal<ServiceType = unknown>(\n packageName: string,\n interfaceName: InterfaceNameForServiceType<ServiceType>,\n options?: UseServiceOptions\n): ServiceType;\nexport function useServiceInternal(\n packageName: string,\n interfaceName:
|
|
1
|
+
{"version":3,"file":"hooks.js","sources":["hooks.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2023 Open Pioneer project (https://github.com/open-pioneer)\n// SPDX-License-Identifier: Apache-2.0\nimport { useContext, useMemo } from \"react\";\nimport { Error } from \"@open-pioneer/core\";\nimport {\n PackageContext as PackageContext,\n PackageContextMethods\n} from \"@open-pioneer/runtime-react-support\";\nimport { ErrorId } from \"../errors\";\nimport { PackageIntl } from \"../i18n\";\nimport { InterfaceNameForServiceType } from \"../DeclaredService\";\n\n/*\n\n IMPORTANT\n =========\n\n The functions in this file are part of the public API.\n They are imported by code generated during separate package generation via:\n\n import { hookName } from '@open-pioneer/runtime/react-integration'\n\n The matching exports are in the neighboring `index.ts`.\n The interfaces of these hooks must remain stable so that already published packages can continue to work in the future.\n\n See also the implementation of @open-pioneer/build-package.\n\n*/\n\nexport interface UseServiceOptions {\n /** An additional qualifier to disambiguate service instances that implement the same interface. */\n qualifier?: string;\n}\n\n/**\n * Returns a service that implements the given interface.\n * Receives the package name of the importing package as a string.\n *\n * This is an internal hook that is typically called indirectly via the hook\n * provided from `\"open-pioneer:react-hooks\"`.\n *\n * @private\n */\nexport function useServiceInternal<ServiceType = unknown>(\n packageName: string,\n interfaceName: InterfaceNameForServiceType<ServiceType>,\n options?: UseServiceOptions\n): ServiceType;\nexport function useServiceInternal(\n packageName: string,\n // eslint-disable-next-line @typescript-eslint/no-explicit-any\n interfaceName: any,\n options?: UseServiceOptions\n): unknown {\n const context = useContext(PackageContext);\n const service = useMemo(\n () =>\n checkContext(\"useService\", context).getService(\n packageName,\n interfaceName,\n options ?? {}\n ),\n [context, packageName, interfaceName, options]\n );\n return service;\n}\n\n/**\n * Returns all services that implement the given interface.\n * Receives the package name of the importing package as a string.\n *\n * This is an internal hook that is typically called indirectly via the hook\n * provided from `\"open-pioneer:react-hooks\"`.\n *\n * @private\n */\nexport function useServicesInternal<ServiceType = unknown>(\n packageName: string,\n interfaceName: InterfaceNameForServiceType<ServiceType>,\n options?: UseServiceOptions\n): ServiceType[];\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function useServicesInternal(packageName: string, interfaceName: any): unknown[] {\n const context = useContext(PackageContext);\n const services = useMemo(\n () => checkContext(\"useServices\", context).getServices(packageName, interfaceName),\n [context, packageName, interfaceName]\n );\n return services;\n}\n\n/**\n * Returns the properties for the given package.\n *\n * This is an internal hook that is typically called indirectly via the hook\n * provided from `\"open-pioneer:react-hooks\"`.\n *\n * @private\n */\nexport function usePropertiesInternal(packageName: string): Readonly<Record<string, unknown>> {\n const context = useContext(PackageContext);\n return checkContext(\"useProperties\", context).getProperties(packageName);\n}\n\n/**\n * Returns the i18n object for the given package.\n *\n * This is an internal hook that is typically called indirectly via the hook\n * provided from `\"open-pioneer:react-hooks\"`.\n *\n * @private\n */\nexport function useIntlInternal(packageName: string): PackageIntl {\n const context = useContext(PackageContext);\n return checkContext(\"useIntl\", context).getIntl(packageName);\n}\n\nfunction checkContext(\n hookName: string,\n contextData: PackageContextMethods | null\n): PackageContextMethods {\n if (!contextData) {\n throw new Error(\n ErrorId.INTERNAL,\n `\"Failed to access package context from '${hookName}': react integration was not set up properly.`\n );\n }\n return contextData;\n}\n"],"names":[],"mappings":";;;;;AAgDgB,SAAA,kBAAA,CACZ,WAEA,EAAA,aAAA,EACA,OACO,EAAA;AACP,EAAM,MAAA,OAAA,GAAU,WAAW,cAAc,CAAA,CAAA;AACzC,EAAA,MAAM,OAAU,GAAA,OAAA;AAAA,IACZ,MACI,YAAA,CAAa,YAAc,EAAA,OAAO,CAAE,CAAA,UAAA;AAAA,MAChC,WAAA;AAAA,MACA,aAAA;AAAA,MACA,WAAW,EAAC;AAAA,KAChB;AAAA,IACJ,CAAC,OAAA,EAAS,WAAa,EAAA,aAAA,EAAe,OAAO,CAAA;AAAA,GACjD,CAAA;AACA,EAAO,OAAA,OAAA,CAAA;AACX,CAAA;AAiBgB,SAAA,mBAAA,CAAoB,aAAqB,aAA+B,EAAA;AACpF,EAAM,MAAA,OAAA,GAAU,WAAW,cAAc,CAAA,CAAA;AACzC,EAAA,MAAM,QAAW,GAAA,OAAA;AAAA,IACb,MAAM,YAAa,CAAA,aAAA,EAAe,OAAO,CAAE,CAAA,WAAA,CAAY,aAAa,aAAa,CAAA;AAAA,IACjF,CAAC,OAAS,EAAA,WAAA,EAAa,aAAa,CAAA;AAAA,GACxC,CAAA;AACA,EAAO,OAAA,QAAA,CAAA;AACX,CAAA;AAUO,SAAS,sBAAsB,WAAwD,EAAA;AAC1F,EAAM,MAAA,OAAA,GAAU,WAAW,cAAc,CAAA,CAAA;AACzC,EAAA,OAAO,YAAa,CAAA,eAAA,EAAiB,OAAO,CAAA,CAAE,cAAc,WAAW,CAAA,CAAA;AAC3E,CAAA;AAUO,SAAS,gBAAgB,WAAkC,EAAA;AAC9D,EAAM,MAAA,OAAA,GAAU,WAAW,cAAc,CAAA,CAAA;AACzC,EAAA,OAAO,YAAa,CAAA,SAAA,EAAW,OAAO,CAAA,CAAE,QAAQ,WAAW,CAAA,CAAA;AAC/D,CAAA;AAEA,SAAS,YAAA,CACL,UACA,WACqB,EAAA;AACrB,EAAA,IAAI,CAAC,WAAa,EAAA;AACd,IAAA,MAAM,IAAI,KAAA;AAAA,MACN,OAAQ,CAAA,QAAA;AAAA,MACR,2CAA2C,QAAQ,CAAA,6CAAA,CAAA;AAAA,KACvD,CAAA;AAAA,GACJ;AACA,EAAO,OAAA,WAAA,CAAA;AACX;;;;"}
|