@bitakit/core 0.1.2 → 0.2.1

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.
Files changed (157) hide show
  1. package/README.md +44 -207
  2. package/discovery/index.d.ts +1 -41
  3. package/discovery/index.mjs +1 -4
  4. package/dist/actions/action-list.d.ts +4 -0
  5. package/dist/actions/action-list.js +58 -16
  6. package/dist/actions/action.d.ts +2 -0
  7. package/dist/actions/action.js +4 -0
  8. package/dist/actions/brand.d.ts +21 -0
  9. package/dist/actions/brand.js +36 -0
  10. package/dist/actions/core.d.ts +4 -3
  11. package/dist/actions/core.js +4 -2
  12. package/dist/actions/execution.d.ts +2 -2
  13. package/dist/actions/execution.js +61 -9
  14. package/dist/actions/feedback.d.ts +2 -0
  15. package/dist/actions/feedback.js +8 -0
  16. package/dist/actions/groups.js +5 -1
  17. package/dist/actions/instance-bindings.js +3 -2
  18. package/dist/actions/interceptors.d.ts +9 -3
  19. package/dist/actions/interceptors.js +31 -3
  20. package/dist/actions/navigation.d.ts +2 -1
  21. package/dist/actions/navigation.js +10 -5
  22. package/dist/actions/reference.js +10 -5
  23. package/dist/actions/types.d.ts +9 -1
  24. package/dist/app/access.d.ts +4 -4
  25. package/dist/app/access.js +33 -71
  26. package/dist/app/action-access.d.ts +2 -2
  27. package/dist/app/action-access.js +6 -4
  28. package/dist/app/service-error.d.ts +2 -2
  29. package/dist/app/service-error.js +10 -6
  30. package/dist/app/types.d.ts +76 -33
  31. package/dist/config-service.d.ts +30 -6
  32. package/dist/config-service.js +25 -9
  33. package/dist/configuration.d.ts +6 -3
  34. package/dist/configuration.js +8 -6
  35. package/dist/contracts.d.ts +4 -2
  36. package/dist/contracts.js +3 -3
  37. package/dist/contribution-origin.d.ts +4 -1
  38. package/dist/contribution-origin.js +14 -1
  39. package/dist/contributions/action.d.ts +26 -0
  40. package/dist/contributions/action.js +171 -0
  41. package/dist/contributions/host.d.ts +14 -11
  42. package/dist/contributions/index.d.ts +1 -26
  43. package/dist/contributions/index.js +1 -18
  44. package/dist/conventions.d.ts +8 -4
  45. package/dist/conventions.js +12 -31
  46. package/dist/core.d.ts +41 -18
  47. package/dist/core.js +25 -13
  48. package/dist/definitions.d.ts +272 -306
  49. package/dist/definitions.js +28 -56
  50. package/dist/destinations.d.ts +25 -0
  51. package/dist/destinations.js +21 -0
  52. package/dist/discovered.d.ts +52 -21
  53. package/dist/discovered.js +89 -35
  54. package/dist/events/define.d.ts +43 -0
  55. package/dist/events/define.js +17 -0
  56. package/dist/events/service.d.ts +35 -8
  57. package/dist/events/service.js +184 -42
  58. package/dist/events/types.d.ts +29 -9
  59. package/dist/inspection/inventory.d.ts +86 -0
  60. package/dist/inspection/inventory.js +132 -0
  61. package/dist/interceptors/define.d.ts +76 -0
  62. package/dist/interceptors/define.js +23 -0
  63. package/dist/interceptors/service-observers.d.ts +6 -3
  64. package/dist/interceptors/service-observers.js +13 -10
  65. package/dist/lifecycle/cleanup.d.ts +5 -0
  66. package/dist/lifecycle/cleanup.js +41 -0
  67. package/dist/lifecycle/controller.d.ts +82 -0
  68. package/dist/lifecycle/controller.js +276 -0
  69. package/dist/lifecycle/reconcile.d.ts +19 -0
  70. package/dist/lifecycle/reconcile.js +68 -0
  71. package/dist/lifecycle/state.d.ts +53 -0
  72. package/dist/lifecycle/state.js +86 -0
  73. package/dist/names.d.ts +10 -0
  74. package/dist/names.js +1 -0
  75. package/dist/pages.d.ts +39 -6
  76. package/dist/pages.js +93 -11
  77. package/dist/presentation.d.ts +9 -0
  78. package/dist/runtime.d.ts +166 -28
  79. package/dist/runtime.js +1485 -248
  80. package/dist/schema.d.ts +13 -0
  81. package/dist/schema.js +38 -0
  82. package/dist/scope.d.ts +59 -4
  83. package/dist/scope.js +133 -11
  84. package/dist/service-key.d.ts +33 -14
  85. package/dist/service-key.js +21 -5
  86. package/dist/service-names.d.ts +39 -0
  87. package/dist/service-names.js +175 -0
  88. package/dist/services.d.ts +24 -5
  89. package/dist/services.js +230 -37
  90. package/dist/settings/access.d.ts +19 -0
  91. package/dist/settings/access.js +78 -0
  92. package/dist/settings/define.d.ts +97 -0
  93. package/dist/settings/define.js +83 -0
  94. package/dist/settings/storage.d.ts +45 -0
  95. package/dist/settings/storage.js +102 -0
  96. package/dist/settings/store.d.ts +74 -0
  97. package/dist/settings/store.js +345 -0
  98. package/dist/slots/action-placement.d.ts +47 -0
  99. package/dist/slots/action-placement.js +1 -0
  100. package/dist/slots/define.d.ts +52 -0
  101. package/dist/slots/define.js +12 -0
  102. package/dist/slots/normalize.d.ts +7 -0
  103. package/dist/slots/normalize.js +36 -0
  104. package/dist/slots/runtime.d.ts +43 -0
  105. package/dist/slots/runtime.js +348 -0
  106. package/dist/slots/types.d.ts +113 -0
  107. package/dist/slots/types.js +1 -0
  108. package/dist/startup-error.d.ts +21 -0
  109. package/dist/startup-error.js +29 -0
  110. package/dist/store.d.ts +24 -0
  111. package/dist/store.js +40 -0
  112. package/dist/translation.d.ts +9 -4
  113. package/dist/translation.js +2 -3
  114. package/examples/todos/actions/create.mjs +1 -3
  115. package/examples/todos/actions/delete.mjs +3 -10
  116. package/examples/todos/actions/list.mjs +1 -3
  117. package/examples/todos/events.mjs +5 -0
  118. package/examples/todos/plugin.mjs +4 -2
  119. package/examples/todos/services/tasks.mjs +14 -20
  120. package/examples/todos.mjs +8 -7
  121. package/package.json +36 -9
  122. package/testing/index.d.ts +59 -0
  123. package/testing/index.mjs +150 -0
  124. package/assets/bitakit-banner.png +0 -0
  125. package/discovery/entries.mjs +0 -124
  126. package/discovery/generate.mjs +0 -321
  127. package/discovery/host.mjs +0 -12
  128. package/discovery/modules.mjs +0 -13
  129. package/discovery/packages.mjs +0 -57
  130. package/discovery/watch.mjs +0 -23
  131. package/dist/app/service-aliases.d.ts +0 -4
  132. package/dist/app/service-aliases.js +0 -14
  133. package/dist/contributions/command.d.ts +0 -8
  134. package/dist/contributions/command.js +0 -59
  135. package/dist/contributions/dialog.d.ts +0 -8
  136. package/dist/contributions/dialog.js +0 -18
  137. package/dist/contributions/form.d.ts +0 -10
  138. package/dist/contributions/form.js +0 -67
  139. package/dist/contributions/native.d.ts +0 -11
  140. package/dist/contributions/native.js +0 -87
  141. package/dist/contributions/shared.d.ts +0 -19
  142. package/dist/contributions/shared.js +0 -48
  143. package/dist/contributions/stateful-action.d.ts +0 -29
  144. package/dist/contributions/stateful-action.js +0 -33
  145. package/dist/events/action-setup.d.ts +0 -19
  146. package/dist/events/action-setup.js +0 -24
  147. package/dist/interceptors/service.d.ts +0 -37
  148. package/dist/interceptors/service.js +0 -7
  149. package/dist/replacements.d.ts +0 -22
  150. package/dist/replacements.js +0 -54
  151. package/dist/validation.d.ts +0 -2
  152. package/dist/validation.js +0 -16
  153. package/docs/auth.md +0 -106
  154. package/docs/events.md +0 -157
  155. package/docs/file-contributions.md +0 -174
  156. package/docs/reference.md +0 -404
  157. package/docs/todo-tutorial.md +0 -88
@@ -1,60 +1,32 @@
1
- import { statefulAction } from './contributions/stateful-action.js';
2
- import { URLAction } from '@bitakit/core/actions';
3
- export function defineService(definition) {
4
- return definition;
5
- }
6
- export function defineInterceptor(definition) {
7
- return definition;
8
- }
9
- /** Explicit Action discriminator; the legacy defineInterceptor helper remains supported. */
10
- export function defineActionInterceptor(definition) {
11
- return { ...definition, kind: 'action' };
12
- }
13
- export function defineProvider(definition) {
14
- return definition;
15
- }
16
- export function defineFormAction(definition) {
17
- return { ...definition, kind: 'form' };
18
- }
19
- export function defineDialogAction(definition) {
20
- return { ...definition, kind: 'dialog' };
21
- }
22
- /** Navigation retains native link semantics and programmatic URLAction execution. */
23
- export function defineURLAction(definition) {
24
- return {
25
- ...definition,
26
- kind: 'native',
27
- load: () => new URLAction({ href: definition.href, title: definition.title ?? '' }),
28
- };
29
- }
30
- export function defineAction(definition) {
31
- if (definition === undefined)
32
- return statefulAction();
33
- const { unavailable, ...action } = definition;
34
- if (unavailable &&
35
- action.metadata != null &&
36
- (typeof action.metadata !== 'object' || Array.isArray(action.metadata)))
37
- throw new Error('Unavailable messages require object metadata.');
38
- return {
39
- ...action,
40
- kind: 'action',
41
- metadata: unavailable
42
- ? {
43
- ...action.metadata,
44
- foundationUnavailableKey: unavailable.messageKey,
45
- }
46
- : action.metadata,
47
- };
48
- }
49
- export function defineSetup(setup) {
50
- return setup;
51
- }
52
- export function defineView(view) {
53
- return view;
54
- }
55
- export function definePage(page) {
56
- return page;
1
+ export function defineService(create, options = {}) {
2
+ if (typeof create !== 'function')
3
+ throw new Error('defineService expects a factory function: defineService((context) => instance).');
4
+ return { ...options, kind: 'service', create };
5
+ }
6
+ export function isServiceDefinition(value) {
7
+ return !!value && typeof value === 'object' && value.kind === 'service';
8
+ }
9
+ /** The dialog of an action in object form, whichever way it was declared. */
10
+ export function dialogOf(spec) {
11
+ const dialog = spec.dialog;
12
+ if (!dialog)
13
+ return undefined;
14
+ if (typeof dialog === 'object' && dialog !== null && 'component' in dialog)
15
+ return { size: spec.dialogSize, ...dialog };
16
+ return { component: dialog, size: spec.dialogSize };
17
+ }
18
+ export function defineAction(spec) {
19
+ if (!spec || typeof spec !== 'object')
20
+ throw new Error('defineAction expects an object.');
21
+ if (spec.dialog && spec.execute)
22
+ throw new Error('An action opens a dialog or runs execute, not both. Run logic from inside the dialog.');
23
+ return { ...spec, kind: 'action' };
24
+ }
25
+ export function isActionSpec(value) {
26
+ return !!value && typeof value === 'object' && value.kind === 'action';
57
27
  }
58
28
  export function definePlugin(plugin) {
29
+ if (!plugin || typeof plugin.id !== 'string' || !plugin.id)
30
+ throw new Error('definePlugin needs an id, for example definePlugin({ id: "todos", ... }).');
59
31
  return plugin;
60
32
  }
@@ -0,0 +1,25 @@
1
+ /**
2
+ * What a navigation Action leads to, so search and overviews can say what a result is and which
3
+ * plugin owns it. Derived from existing registrations; developers never declare it.
4
+ */
5
+ export type DestinationKind = 'plugin' | 'page' | 'settings';
6
+ export type Destination = Readonly<{
7
+ kind: DestinationKind;
8
+ /** The owning plugin; absent when the application itself owns the destination. */
9
+ plugin?: string;
10
+ }>;
11
+ /**
12
+ * Action metadata for integrations that project their own registrations into the ActionList,
13
+ * such as settings sections. They already know the owner, so it is carried, not guessed.
14
+ */
15
+ export declare function destinationMetadata({ kind, plugin }: Destination): {
16
+ foundationDestination: Readonly<{
17
+ kind: DestinationKind;
18
+ plugin: string;
19
+ } | {
20
+ kind: DestinationKind;
21
+ plugin?: undefined;
22
+ }>;
23
+ };
24
+ /** The destination an integration projected into Action metadata, if it is well-formed. */
25
+ export declare function projectedDestination(metadata: unknown): Destination | undefined;
@@ -0,0 +1,21 @@
1
+ const kinds = ['plugin', 'page', 'settings'];
2
+ const field = 'foundationDestination';
3
+ /**
4
+ * Action metadata for integrations that project their own registrations into the ActionList,
5
+ * such as settings sections. They already know the owner, so it is carried, not guessed.
6
+ */
7
+ export function destinationMetadata({ kind, plugin }) {
8
+ return { [field]: Object.freeze(plugin ? { kind, plugin } : { kind }) };
9
+ }
10
+ /** The destination an integration projected into Action metadata, if it is well-formed. */
11
+ export function projectedDestination(metadata) {
12
+ const value = metadata && typeof metadata === 'object'
13
+ ? metadata[field]
14
+ : undefined;
15
+ if (!value || typeof value !== 'object')
16
+ return undefined;
17
+ const { kind, plugin } = value;
18
+ if (typeof kind !== 'string' || !kinds.includes(kind))
19
+ return undefined;
20
+ return { kind: kind, ...(typeof plugin === 'string' ? { plugin } : {}) };
21
+ }
@@ -1,46 +1,77 @@
1
- import { type Contribution, type ServiceDefinition, type InterceptorEntry, type ActionEntry } from './definitions.js';
2
- import type { PublicServiceKeys } from './app/types.js';
1
+ import { type Contribution, type ServiceDefinition, type ActionEntry } from './definitions.js';
2
+ import { type ResolvedSlotDefinition, type SlotEntry } from './slots/define.js';
3
+ import type { ContractName } from './service-key.js';
4
+ import { type InterceptorSpec } from './interceptors/define.js';
5
+ import { type CancelableOf, type EventsDefinition, type EventsOf } from './events/define.js';
3
6
  import { type ConfigValues, type ConfigDefinition } from './config-service.js';
7
+ import { type SettingsDefinition, type SettingsOf } from './settings/define.js';
4
8
  export type DiscoveredFile<T = unknown, P extends string = string> = {
5
9
  value: T;
6
10
  path: P;
7
11
  source: string;
8
12
  };
9
13
  export declare function discoveredFile<T, const P extends string>(value: T, path: P, source: string): DiscoveredFile<T, P>;
10
- export declare function discoverActions(files: readonly DiscoveredFile[], moduleId?: string, conventions?: boolean): Contribution[];
14
+ export declare function discoverActions(files: readonly DiscoveredFile[], moduleId?: string): Contribution[];
11
15
  export declare function discoverServices(files: readonly DiscoveredFile[], moduleId?: string): ServiceDefinition[];
12
- /** Compatibility projection. New generated hosts carry names directly on discovered services. */
13
- export declare function discoverPublicServices(files: readonly DiscoveredFile[], moduleId?: string): PublicServiceKeys;
14
- export declare function discoverInterceptors(files: readonly DiscoveredFile[]): InterceptorEntry[];
16
+ /** Slot leaves use the same record/path expansion as Actions and services. Explicit IDs are absolute. */
17
+ export declare function discoverSlots(files: readonly DiscoveredFile[], moduleId?: string): ResolvedSlotDefinition[];
18
+ export declare function discoverInterceptors(files: readonly DiscoveredFile[]): InterceptorSpec[];
19
+ /** The one `events.ts` of a module. */
20
+ export declare function discoverEvents(files: readonly DiscoveredFile[]): EventsDefinition | undefined;
21
+ /** The one `settings.ts` of a module. */
22
+ export declare function discoverSettings(files: readonly DiscoveredFile[]): SettingsDefinition | undefined;
15
23
  /** File assembly rejects overlapping leaves; intentional overrides happen later in ConfigService. */
16
24
  export declare function discoverConfig(files: readonly DiscoveredFile[]): ConfigValues | ConfigDefinition;
17
25
  type Join<A extends string, B extends string> = A extends '' ? B : B extends '' ? A : `${A}.${B}`;
18
26
  type UnionToIntersection<U> = (U extends unknown ? (value: U) => void : never) extends (value: infer I) => void ? I : never;
19
- type ActionTree<T, P extends string> = T extends (...args: any[]) => any ? {} : T extends abstract new (...args: any[]) => any ? {} : T extends {
20
- kind: string;
27
+ /** `ActionMap` entries of an Action, or of a nested record of Actions under path `P`. */
28
+ export type ActionTree<T, P extends string> = T extends {
29
+ kind: 'action';
21
30
  } ? ActionEntry<T, P> : T extends {
22
31
  execute: (...args: any[]) => any;
23
32
  } ? ActionEntry<T & {
24
33
  kind: 'action';
34
+ }, P> : T extends {
35
+ href: string;
36
+ } | {
37
+ dialog: unknown;
38
+ } ? ActionEntry<T & {
39
+ kind: 'action';
25
40
  }, P> : T extends object ? UnionToIntersection<{
26
41
  [K in keyof T & string]: ActionTree<T[K], Join<P, K>>;
27
42
  }[keyof T & string]> : {};
28
- export type DiscoveredActionEntry<F, Module extends string = '', Conventions extends boolean = true> = F extends DiscoveredFile<infer T, infer P> ? ActionTree<T, Conventions extends false ? never : Join<Module, P>> : {};
29
- type ServiceTree<T, P extends string, Public extends boolean = false> = T extends {
43
+ export type DiscoveredActionEntry<F, Module extends string = '', _Conventions extends boolean = true> = F extends DiscoveredFile<infer T, infer P> ? ActionTree<T, Join<Module, P>> : {};
44
+ type ServiceInstance<T> = T extends {
30
45
  create: (...args: any[]) => infer R;
46
+ } ? R : T extends (...args: any[]) => infer R ? R : never;
47
+ type ServiceId<T, P extends string> = T extends {
48
+ id: infer Id extends string;
49
+ } ? Id : P;
50
+ type ServiceAlias<T, R> = (T extends {
51
+ exposeAs: infer A extends string;
31
52
  } ? {
32
- [K in Public extends true ? T extends {
33
- exposeAs: infer Name extends string;
34
- } ? Name : T extends {
35
- id: infer ID extends string;
36
- } ? ID : P : T extends {
37
- id: infer ID extends string;
38
- } ? ID : P]: R;
39
- } : T extends object ? UnionToIntersection<{
40
- [K in keyof T & string]: ServiceTree<T[K], Join<P, K>, Public>;
41
- }[keyof T & string]> : {};
53
+ readonly [K in A]: R;
54
+ } : {}) & (T extends {
55
+ provides: infer Key;
56
+ } ? string extends ContractName<Key> ? {} : {
57
+ readonly [K in ContractName<Key>]: R;
58
+ } : {});
59
+ type ServiceTree<T, P extends string> = [ServiceInstance<T>] extends [never] ? T extends object ? UnionToIntersection<{
60
+ [K in keyof T & string]: ServiceTree<T[K], Join<P, K>>;
61
+ }[keyof T & string]> : {} : {
62
+ readonly [K in ServiceId<T, P>]: ServiceInstance<T>;
63
+ } & ServiceAlias<T, ServiceInstance<T>>;
42
64
  export type DiscoveredServiceEntry<F, Module extends string = ''> = F extends DiscoveredFile<infer T, infer P> ? ServiceTree<T, Join<Module, P>> : {};
43
- export type DiscoveredPublicServiceEntry<F> = F extends DiscoveredFile<infer T, infer P> ? ServiceTree<T, P, true> : {};
65
+ export type SlotTree<T, P extends string> = T extends {
66
+ kind: 'slot';
67
+ } ? SlotEntry<T, P> : T extends object ? [keyof T & string] extends [never] ? {} : UnionToIntersection<{
68
+ [K in keyof T & string]: SlotTree<T[K], Join<P, K>>;
69
+ }[keyof T & string]> : {};
70
+ export type DiscoveredSlotEntry<F, Module extends string = ''> = F extends DiscoveredFile<infer T, infer P> ? SlotTree<T, Join<Module, P>> : {};
71
+ export type DiscoveredEventsEntry<F, Module extends string> = F extends DiscoveredFile<infer T, any> ? EventsOf<T, Module> : {};
72
+ export type DiscoveredCancelableEntry<F, Module extends string> = F extends DiscoveredFile<infer T, any> ? CancelableOf<T, Module> : {};
73
+ /** `SettingsMap` entries of one `settings.ts`; pass '' as Module for the app. */
74
+ export type DiscoveredSettingsEntry<F, Module extends string> = F extends DiscoveredFile<infer T, any> ? SettingsOf<T, Module> : {};
44
75
  type ConfigOutput<T> = T extends ConfigDefinition<infer V> ? V : T extends readonly unknown[] ? T : T extends object ? {
45
76
  [K in keyof T]: ConfigOutput<T[K]>;
46
77
  } : T;
@@ -1,21 +1,26 @@
1
- import { setContributionPath } from './contribution-origin.js';
2
- import { defineAction, } from './definitions.js';
1
+ import { setContributionPath, setContributionSource } from './contribution-origin.js';
2
+ import { defineAction, defineService, isActionSpec, isServiceDefinition, } from './definitions.js';
3
3
  import { resolveContribution } from './conventions.js';
4
- import { serviceKey } from './service-key.js';
4
+ import { actionIdPattern } from './conventions.js';
5
+ import { isSlotDefinition } from './slots/define.js';
6
+ import { BitaKitStartupError } from './startup-error.js';
7
+ import { defineInterceptor } from './interceptors/define.js';
8
+ import { isEventsDefinition, } from './events/define.js';
5
9
  import { isConfigDefinition, isConfigObject, } from './config-service.js';
10
+ import { isSettingsDefinition, } from './settings/define.js';
6
11
  export function discoveredFile(value, path, source) {
7
12
  return { value, path, source };
8
13
  }
9
- function expand(files, leaf, arrays = false) {
14
+ function expand(files, leaf, arrays = false, failure = (message, _source) => new Error(message)) {
10
15
  const results = [];
11
16
  const seen = new Map();
12
17
  function visit(value, segments, source) {
13
18
  if (leaf(value)) {
14
19
  const key = segments.join('.');
15
20
  if (!key)
16
- throw new Error(`Collection needs named entries: ${source}`);
21
+ throw failure(`Collection needs named entries: ${source}`, source);
17
22
  if (seen.has(key))
18
- throw new Error(`Duplicate contribution "${key}": ${seen.get(key)} and ${source}`);
23
+ throw failure(`Duplicate contribution "${key}": ${seen.get(key)} and ${source}`, source);
19
24
  seen.set(key, source);
20
25
  results.push({ value, path: segments, source });
21
26
  return;
@@ -25,7 +30,7 @@ function expand(files, leaf, arrays = false) {
25
30
  return;
26
31
  }
27
32
  if (!isConfigObject(value))
28
- throw new Error(`Invalid contribution in ${source}`);
33
+ throw failure(`Invalid contribution in ${source}: ${typeof value === 'function' ? 'class and factory exports are no longer discovered; export defineAction({ ... }) or defineService((context) => ...)' : 'expected a define* result or a record of them'}.`, source);
29
34
  for (const [key, entry] of Object.entries(value))
30
35
  visit(entry, [...segments, ...key.split('.')], source);
31
36
  }
@@ -33,43 +38,92 @@ function expand(files, leaf, arrays = false) {
33
38
  visit(file.value, file.path ? file.path.split('.') : [], file.source);
34
39
  return results;
35
40
  }
36
- export function discoverActions(files, moduleId = '', conventions = true) {
37
- return expand(files, (value) => typeof value === 'function' ||
38
- (!!value &&
39
- typeof value === 'object' &&
40
- ('kind' in value || typeof value.execute === 'function'))).map(({ value, path }) => {
41
- const definition = typeof value === 'object' && !value.kind ? defineAction(value) : value;
42
- const resolved = resolveContribution(definition, [moduleId, ...path].filter(Boolean).join('.'), conventions);
43
- setContributionPath(resolved, path);
41
+ const isActionLike = (value) => isActionSpec(value) ||
42
+ (!!value &&
43
+ typeof value === 'object' &&
44
+ !Array.isArray(value) &&
45
+ ('execute' in value || 'href' in value || 'dialog' in value) &&
46
+ !('create' in value) &&
47
+ !('kind' in value));
48
+ export function discoverActions(files, moduleId = '') {
49
+ return expand(files, isActionLike).map(({ value, path, source }) => {
50
+ const spec = isActionSpec(value) ? value : defineAction(value);
51
+ const resolved = resolveContribution(spec, [moduleId, ...path].filter(Boolean).join('.'));
52
+ setContributionPath(resolved, path, source);
44
53
  return resolved;
45
54
  });
46
55
  }
56
+ const isServiceLike = (value) => isServiceDefinition(value) || typeof value === 'function';
47
57
  export function discoverServices(files, moduleId = '') {
48
- return expand(files, (value) => !!value && typeof value.create === 'function').map(({ value, path }) => ({
49
- ...value,
50
- id: value.id ?? [moduleId, ...path].filter(Boolean).join('.'),
51
- exposeAs: value.exposeAs ?? value.id ?? path.join('.'),
52
- }));
58
+ return expand(files, isServiceLike).map(({ value, path, source }) => {
59
+ const service = isServiceDefinition(value)
60
+ ? value
61
+ : defineService(value);
62
+ const definition = {
63
+ ...service,
64
+ id: service.id ?? [moduleId, ...path].filter(Boolean).join('.'),
65
+ };
66
+ setContributionSource(definition, source);
67
+ return definition;
68
+ });
53
69
  }
54
- /** Compatibility projection. New generated hosts carry names directly on discovered services. */
55
- export function discoverPublicServices(files, moduleId = '') {
56
- const aliases = Object.create(null);
57
- const sources = new Map();
58
- for (const { value, path, source } of expand(files, (value) => !!value && typeof value.create === 'function')) {
59
- const name = value.exposeAs ?? value.id ?? path.join('.');
60
- if (sources.has(name))
61
- throw new Error(`Duplicate public service "${name}": ${sources.get(name)} and ${source}`);
62
- sources.set(name, source);
63
- aliases[name] = serviceKey(value.id ?? [moduleId, ...path].filter(Boolean).join('.'));
64
- }
65
- return aliases;
70
+ /** Slot leaves use the same record/path expansion as Actions and services. Explicit IDs are absolute. */
71
+ export function discoverSlots(files, moduleId = '') {
72
+ const seen = new Map();
73
+ return expand(files, isSlotDefinition, false, (message, source) => new BitaKitStartupError(message, moduleId || 'app', { source, app: !moduleId })).map(({ value, path, source }) => {
74
+ const id = value.id ?? [moduleId, ...path].filter(Boolean).join('.');
75
+ if (typeof id !== 'string' || !actionIdPattern.test(id))
76
+ throw new BitaKitStartupError(`Invalid slot ID "${id}" in ${source}.`, moduleId || 'app', {
77
+ source,
78
+ app: !moduleId,
79
+ });
80
+ if (seen.has(id))
81
+ throw new BitaKitStartupError(`Duplicate slot "${id}": ${seen.get(id)} and ${source}.`, moduleId || 'app', { source, app: !moduleId });
82
+ seen.set(id, source);
83
+ const definition = Object.freeze({ ...value, id });
84
+ setContributionPath(definition, path, source);
85
+ return definition;
86
+ });
66
87
  }
67
88
  export function discoverInterceptors(files) {
68
89
  return expand(files, (value) => typeof value === 'function' ||
69
90
  (!!value &&
70
- (value.kind === 'service' ||
71
- typeof value.create === 'function' ||
72
- typeof value.before === 'function')), true).map(({ value }) => (typeof value === 'function' ? { before: value } : value));
91
+ typeof value === 'object' &&
92
+ !Array.isArray(value) &&
93
+ (value.kind === 'interceptor' ||
94
+ typeof value.before === 'function' ||
95
+ typeof value.after === 'function' ||
96
+ typeof value.onError === 'function')), true).map(({ value, source }) => {
97
+ const spec = typeof value === 'function'
98
+ ? defineInterceptor({ before: value })
99
+ : value.kind === 'interceptor'
100
+ ? { ...value }
101
+ : defineInterceptor(value);
102
+ setContributionSource(spec, source);
103
+ return spec;
104
+ });
105
+ }
106
+ /** The one `events.ts` of a module. */
107
+ export function discoverEvents(files) {
108
+ if (!files.length)
109
+ return undefined;
110
+ if (files.length > 1)
111
+ throw new Error(`A module declares its events in one file: ${files.map((file) => file.source).join(', ')}`);
112
+ const [file] = files;
113
+ if (!isEventsDefinition(file.value))
114
+ throw new Error(`${file.source} must default-export defineEvents({ ... }).`);
115
+ return file.value;
116
+ }
117
+ /** The one `settings.ts` of a module. */
118
+ export function discoverSettings(files) {
119
+ if (!files.length)
120
+ return undefined;
121
+ if (files.length > 1)
122
+ throw new Error(`A module declares its settings in one file: ${files.map((file) => file.source).join(', ')}`);
123
+ const [file] = files;
124
+ if (!isSettingsDefinition(file.value))
125
+ throw new Error(`${file.source} must default-export defineSettings({ ... }).`);
126
+ return file.value;
73
127
  }
74
128
  /** File assembly rejects overlapping leaves; intentional overrides happen later in ConfigService. */
75
129
  export function discoverConfig(files) {
@@ -0,0 +1,43 @@
1
+ declare const eventType: unique symbol;
2
+ /** One declared event: its payload type and whether it can be cancelled. */
3
+ export type EventSpec<Data = unknown, Cancelable extends boolean = false> = {
4
+ readonly cancelable: Cancelable;
5
+ readonly schema?: {
6
+ parse(input: unknown): Data;
7
+ };
8
+ readonly [eventType]?: Data;
9
+ };
10
+ /** `event<{ id: number }>()` or `event<{ id: number }>({ cancelable: true })`. */
11
+ export declare function event<Data = undefined>(options: {
12
+ cancelable: true;
13
+ schema?: {
14
+ parse(input: unknown): Data;
15
+ };
16
+ }): EventSpec<Data, true>;
17
+ export declare function event<Data = undefined>(options?: {
18
+ cancelable?: false;
19
+ schema?: {
20
+ parse(input: unknown): Data;
21
+ };
22
+ }): EventSpec<Data, false>;
23
+ export type EventsDefinition<Specs extends Record<string, EventSpec<any, boolean>> = Record<string, EventSpec<any, boolean>>> = {
24
+ readonly kind: 'events';
25
+ readonly events: Specs;
26
+ };
27
+ /**
28
+ * Declares a plugin's events in `events.ts`. Names are prefixed with the plugin ID, so
29
+ * `changed` in plugin `todos` is emitted and observed as `todos.changed`. Only the declaring
30
+ * plugin may emit them.
31
+ */
32
+ export declare function defineEvents<const Specs extends Record<string, EventSpec<any, boolean>>>(events: Specs): EventsDefinition<Specs>;
33
+ export declare function isEventsDefinition(value: unknown): value is EventsDefinition;
34
+ type DataOf<S> = S extends EventSpec<infer Data, any> ? Data : never;
35
+ /** `EventMap` entries of one declaration under a plugin prefix. */
36
+ export type EventsOf<D, Plugin extends string> = D extends EventsDefinition<infer Specs> ? {
37
+ [K in keyof Specs & string as `${Plugin}.${K}`]: DataOf<Specs[K]>;
38
+ } : {};
39
+ /** `CancelableEventMap` entries of one declaration. */
40
+ export type CancelableOf<D, Plugin extends string> = D extends EventsDefinition<infer Specs> ? {
41
+ [K in keyof Specs & string as Specs[K] extends EventSpec<any, true> ? `${Plugin}.${K}` : never]: true;
42
+ } : {};
43
+ export {};
@@ -0,0 +1,17 @@
1
+ export function event(options) {
2
+ return { cancelable: options?.cancelable ?? false, schema: options?.schema };
3
+ }
4
+ /**
5
+ * Declares a plugin's events in `events.ts`. Names are prefixed with the plugin ID, so
6
+ * `changed` in plugin `todos` is emitted and observed as `todos.changed`. Only the declaring
7
+ * plugin may emit them.
8
+ */
9
+ export function defineEvents(events) {
10
+ for (const name of Object.keys(events))
11
+ if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(name))
12
+ throw new Error(`Invalid event name "${name}". Use letters, digits, "_" or "-" without dots.`);
13
+ return { kind: 'events', events };
14
+ }
15
+ export function isEventsDefinition(value) {
16
+ return !!value && typeof value === 'object' && value.kind === 'events';
17
+ }
@@ -1,18 +1,45 @@
1
- import type { Events, EventErrorHandler } from './types.js';
2
- /** One bus per runtime. Mitt owns dispatch; Foundation owns lifetimes and error reporting. */
1
+ import type { Events, EventErrorHandler, BitaKitEvent } from './types.js';
2
+ import type { EventsDefinition } from './define.js';
3
+ /**
4
+ * One bus per runtime. Delivery is synchronous and ordered; async handlers are awaited only
5
+ * for error reporting, or fully for cancelable events. Declared namespaces belong to the
6
+ * plugin that declared them: nobody else may emit into them.
7
+ */
3
8
  export declare class EventService implements Events {
4
9
  private onError;
5
- private bus;
10
+ private exact;
11
+ private prefixes;
6
12
  private subscriptions;
13
+ private observers;
14
+ private declared;
15
+ private reserved;
7
16
  constructor(onError?: EventErrorHandler);
8
- emit: Events['emit'];
9
- watch: Events['watch'];
10
- /** Diagnostics for lifecycle tests; counts watch calls, not individual event names. */
17
+ /** Registers a plugin's `events.ts`; its names live under `<plugin>.`. */
18
+ declare(plugin: string, definition: EventsDefinition): void;
19
+ /** Release a stopped owner’s declaration without removing other owners’ listeners. */
20
+ undeclare(plugin: string): void;
21
+ /** The plugin that declared the namespace of an event name, if any. */
22
+ ownerOf(name: string): string | undefined;
23
+ isCancelable(name: string): boolean;
24
+ /** Reserves a runtime-owned namespace and returns its private publishing capability. */
25
+ reserve(namespace: string): (name: string, data: unknown) => void;
26
+ emit: Events["emit"];
27
+ private dispatch;
28
+ private emitCancelable;
29
+ private listenersFor;
30
+ private report;
31
+ on: Events["on"];
32
+ /** Diagnostics only: receives every event after delivery. It cannot change or stop delivery. */
33
+ observe(listener: (event: BitaKitEvent) => void): () => void;
34
+ /** Diagnostics for lifecycle tests; counts `on` calls, not individual event names. */
11
35
  get subscriptionCount(): number;
12
36
  clear(): void;
13
37
  }
14
- /** A scoped view shares the bus and releases callback references on disposal. */
15
- export declare function createEventScope(events: Events): {
38
+ /**
39
+ * A scoped view for one module: releases its listeners on disposal and may emit only into
40
+ * namespaces it owns or that nobody declared.
41
+ */
42
+ export declare function createEventScope(events: EventService, owner?: string): {
16
43
  events: Events;
17
44
  dispose(): void;
18
45
  };