@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.
- package/README.md +44 -207
- package/discovery/index.d.ts +1 -41
- package/discovery/index.mjs +1 -4
- package/dist/actions/action-list.d.ts +4 -0
- package/dist/actions/action-list.js +58 -16
- package/dist/actions/action.d.ts +2 -0
- package/dist/actions/action.js +4 -0
- package/dist/actions/brand.d.ts +21 -0
- package/dist/actions/brand.js +36 -0
- package/dist/actions/core.d.ts +4 -3
- package/dist/actions/core.js +4 -2
- package/dist/actions/execution.d.ts +2 -2
- package/dist/actions/execution.js +61 -9
- package/dist/actions/feedback.d.ts +2 -0
- package/dist/actions/feedback.js +8 -0
- package/dist/actions/groups.js +5 -1
- package/dist/actions/instance-bindings.js +3 -2
- package/dist/actions/interceptors.d.ts +9 -3
- package/dist/actions/interceptors.js +31 -3
- package/dist/actions/navigation.d.ts +2 -1
- package/dist/actions/navigation.js +10 -5
- package/dist/actions/reference.js +10 -5
- package/dist/actions/types.d.ts +9 -1
- package/dist/app/access.d.ts +4 -4
- package/dist/app/access.js +33 -71
- package/dist/app/action-access.d.ts +2 -2
- package/dist/app/action-access.js +6 -4
- package/dist/app/service-error.d.ts +2 -2
- package/dist/app/service-error.js +10 -6
- package/dist/app/types.d.ts +76 -33
- package/dist/config-service.d.ts +30 -6
- package/dist/config-service.js +25 -9
- package/dist/configuration.d.ts +6 -3
- package/dist/configuration.js +8 -6
- package/dist/contracts.d.ts +4 -2
- package/dist/contracts.js +3 -3
- package/dist/contribution-origin.d.ts +4 -1
- package/dist/contribution-origin.js +14 -1
- package/dist/contributions/action.d.ts +26 -0
- package/dist/contributions/action.js +171 -0
- package/dist/contributions/host.d.ts +14 -11
- package/dist/contributions/index.d.ts +1 -26
- package/dist/contributions/index.js +1 -18
- package/dist/conventions.d.ts +8 -4
- package/dist/conventions.js +12 -31
- package/dist/core.d.ts +41 -18
- package/dist/core.js +25 -13
- package/dist/definitions.d.ts +272 -306
- package/dist/definitions.js +28 -56
- package/dist/destinations.d.ts +25 -0
- package/dist/destinations.js +21 -0
- package/dist/discovered.d.ts +52 -21
- package/dist/discovered.js +89 -35
- package/dist/events/define.d.ts +43 -0
- package/dist/events/define.js +17 -0
- package/dist/events/service.d.ts +35 -8
- package/dist/events/service.js +184 -42
- package/dist/events/types.d.ts +29 -9
- package/dist/inspection/inventory.d.ts +86 -0
- package/dist/inspection/inventory.js +132 -0
- package/dist/interceptors/define.d.ts +76 -0
- package/dist/interceptors/define.js +23 -0
- package/dist/interceptors/service-observers.d.ts +6 -3
- package/dist/interceptors/service-observers.js +13 -10
- package/dist/lifecycle/cleanup.d.ts +5 -0
- package/dist/lifecycle/cleanup.js +41 -0
- package/dist/lifecycle/controller.d.ts +82 -0
- package/dist/lifecycle/controller.js +276 -0
- package/dist/lifecycle/reconcile.d.ts +19 -0
- package/dist/lifecycle/reconcile.js +68 -0
- package/dist/lifecycle/state.d.ts +53 -0
- package/dist/lifecycle/state.js +86 -0
- package/dist/names.d.ts +10 -0
- package/dist/names.js +1 -0
- package/dist/pages.d.ts +39 -6
- package/dist/pages.js +93 -11
- package/dist/presentation.d.ts +9 -0
- package/dist/runtime.d.ts +166 -28
- package/dist/runtime.js +1485 -248
- package/dist/schema.d.ts +13 -0
- package/dist/schema.js +38 -0
- package/dist/scope.d.ts +59 -4
- package/dist/scope.js +133 -11
- package/dist/service-key.d.ts +33 -14
- package/dist/service-key.js +21 -5
- package/dist/service-names.d.ts +39 -0
- package/dist/service-names.js +175 -0
- package/dist/services.d.ts +24 -5
- package/dist/services.js +230 -37
- package/dist/settings/access.d.ts +19 -0
- package/dist/settings/access.js +78 -0
- package/dist/settings/define.d.ts +97 -0
- package/dist/settings/define.js +83 -0
- package/dist/settings/storage.d.ts +45 -0
- package/dist/settings/storage.js +102 -0
- package/dist/settings/store.d.ts +74 -0
- package/dist/settings/store.js +345 -0
- package/dist/slots/action-placement.d.ts +47 -0
- package/dist/slots/action-placement.js +1 -0
- package/dist/slots/define.d.ts +52 -0
- package/dist/slots/define.js +12 -0
- package/dist/slots/normalize.d.ts +7 -0
- package/dist/slots/normalize.js +36 -0
- package/dist/slots/runtime.d.ts +43 -0
- package/dist/slots/runtime.js +348 -0
- package/dist/slots/types.d.ts +113 -0
- package/dist/slots/types.js +1 -0
- package/dist/startup-error.d.ts +21 -0
- package/dist/startup-error.js +29 -0
- package/dist/store.d.ts +24 -0
- package/dist/store.js +40 -0
- package/dist/translation.d.ts +9 -4
- package/dist/translation.js +2 -3
- package/examples/todos/actions/create.mjs +1 -3
- package/examples/todos/actions/delete.mjs +3 -10
- package/examples/todos/actions/list.mjs +1 -3
- package/examples/todos/events.mjs +5 -0
- package/examples/todos/plugin.mjs +4 -2
- package/examples/todos/services/tasks.mjs +14 -20
- package/examples/todos.mjs +8 -7
- package/package.json +36 -9
- package/testing/index.d.ts +59 -0
- package/testing/index.mjs +150 -0
- package/assets/bitakit-banner.png +0 -0
- package/discovery/entries.mjs +0 -124
- package/discovery/generate.mjs +0 -321
- package/discovery/host.mjs +0 -12
- package/discovery/modules.mjs +0 -13
- package/discovery/packages.mjs +0 -57
- package/discovery/watch.mjs +0 -23
- package/dist/app/service-aliases.d.ts +0 -4
- package/dist/app/service-aliases.js +0 -14
- package/dist/contributions/command.d.ts +0 -8
- package/dist/contributions/command.js +0 -59
- package/dist/contributions/dialog.d.ts +0 -8
- package/dist/contributions/dialog.js +0 -18
- package/dist/contributions/form.d.ts +0 -10
- package/dist/contributions/form.js +0 -67
- package/dist/contributions/native.d.ts +0 -11
- package/dist/contributions/native.js +0 -87
- package/dist/contributions/shared.d.ts +0 -19
- package/dist/contributions/shared.js +0 -48
- package/dist/contributions/stateful-action.d.ts +0 -29
- package/dist/contributions/stateful-action.js +0 -33
- package/dist/events/action-setup.d.ts +0 -19
- package/dist/events/action-setup.js +0 -24
- package/dist/interceptors/service.d.ts +0 -37
- package/dist/interceptors/service.js +0 -7
- package/dist/replacements.d.ts +0 -22
- package/dist/replacements.js +0 -54
- package/dist/validation.d.ts +0 -2
- package/dist/validation.js +0 -16
- package/docs/auth.md +0 -106
- package/docs/events.md +0 -157
- package/docs/file-contributions.md +0 -174
- package/docs/reference.md +0 -404
- package/docs/todo-tutorial.md +0 -88
package/dist/events/service.js
CHANGED
|
@@ -1,88 +1,230 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
1
|
+
/**
|
|
2
|
+
* One bus per runtime. Delivery is synchronous and ordered; async handlers are awaited only
|
|
3
|
+
* for error reporting, or fully for cancelable events. Declared namespaces belong to the
|
|
4
|
+
* plugin that declared them: nobody else may emit into them.
|
|
5
|
+
*/
|
|
3
6
|
export class EventService {
|
|
4
7
|
onError;
|
|
5
|
-
|
|
8
|
+
exact = new Map();
|
|
9
|
+
prefixes = new Map();
|
|
6
10
|
subscriptions = new Set();
|
|
11
|
+
observers = new Set();
|
|
12
|
+
declared = new Map();
|
|
13
|
+
reserved = new Set();
|
|
7
14
|
constructor(onError = (error, event) => {
|
|
8
15
|
console.error(`Event handler failed for "${event.type}".`, error);
|
|
9
16
|
}) {
|
|
10
17
|
this.onError = onError;
|
|
11
18
|
}
|
|
12
|
-
|
|
13
|
-
|
|
19
|
+
/** Registers a plugin's `events.ts`; its names live under `<plugin>.`. */
|
|
20
|
+
declare(plugin, definition) {
|
|
21
|
+
if (this.reserved.has(plugin))
|
|
22
|
+
throw new Error(`Event namespace "${plugin}" is reserved by the runtime.`);
|
|
23
|
+
const existing = this.declared.get(plugin);
|
|
24
|
+
if (existing)
|
|
25
|
+
throw new Error(`Plugin "${plugin}" declares its events twice. Keep one events.ts.`);
|
|
26
|
+
const cancelable = new Set();
|
|
27
|
+
const schemas = new Map();
|
|
28
|
+
for (const [name, spec] of Object.entries(definition.events)) {
|
|
29
|
+
if (spec.cancelable)
|
|
30
|
+
cancelable.add(`${plugin}.${name}`);
|
|
31
|
+
if (spec.schema)
|
|
32
|
+
schemas.set(`${plugin}.${name}`, spec.schema);
|
|
33
|
+
}
|
|
34
|
+
this.declared.set(plugin, { plugin, cancelable, schemas });
|
|
35
|
+
}
|
|
36
|
+
/** Release a stopped owner’s declaration without removing other owners’ listeners. */
|
|
37
|
+
undeclare(plugin) {
|
|
38
|
+
this.declared.delete(plugin);
|
|
39
|
+
}
|
|
40
|
+
/** The plugin that declared the namespace of an event name, if any. */
|
|
41
|
+
ownerOf(name) {
|
|
42
|
+
const prefix = name.split('.')[0];
|
|
43
|
+
return this.declared.has(prefix) ? prefix : undefined;
|
|
44
|
+
}
|
|
45
|
+
isCancelable(name) {
|
|
46
|
+
return this.declared.get(name.split('.')[0])?.cancelable.has(name) ?? false;
|
|
47
|
+
}
|
|
48
|
+
/** Reserves a runtime-owned namespace and returns its private publishing capability. */
|
|
49
|
+
reserve(namespace) {
|
|
50
|
+
if (this.declared.has(namespace) || this.reserved.has(namespace))
|
|
51
|
+
throw new Error(`Event namespace "${namespace}" is already owned.`);
|
|
52
|
+
this.reserved.add(namespace);
|
|
53
|
+
return (name, data) => {
|
|
54
|
+
if (!name.startsWith(`${namespace}.`))
|
|
55
|
+
throw new Error('Event is outside the reserved namespace.');
|
|
56
|
+
this.dispatch(name, data);
|
|
57
|
+
};
|
|
58
|
+
}
|
|
59
|
+
emit = ((name, data) => {
|
|
60
|
+
if (this.reserved.has(name.split('.')[0]))
|
|
61
|
+
throw new Error(`Event "${name}" is emitted only by the runtime.`);
|
|
62
|
+
return this.dispatch(name, data);
|
|
63
|
+
});
|
|
64
|
+
dispatch = (name, data) => {
|
|
65
|
+
const schema = this.declared.get(name.split('.')[0])?.schemas.get(name);
|
|
66
|
+
if (this.isCancelable(name)) {
|
|
67
|
+
// Cancelable emits return a promise, so an invalid payload rejects it instead of throwing.
|
|
68
|
+
let checked;
|
|
69
|
+
try {
|
|
70
|
+
checked = schema ? schema.parse(data) : data;
|
|
71
|
+
}
|
|
72
|
+
catch (error) {
|
|
73
|
+
return Promise.reject(error);
|
|
74
|
+
}
|
|
75
|
+
return this.emitCancelable(name, checked);
|
|
76
|
+
}
|
|
77
|
+
const payload = schema ? schema.parse(data) : data;
|
|
78
|
+
const event = Object.freeze({ type: name, data: payload });
|
|
79
|
+
for (const listener of this.listenersFor(name)) {
|
|
80
|
+
try {
|
|
81
|
+
const result = listener(event);
|
|
82
|
+
if (result && typeof result.then === 'function')
|
|
83
|
+
void result.catch((error) => this.report(error, event));
|
|
84
|
+
}
|
|
85
|
+
catch (error) {
|
|
86
|
+
this.report(error, event);
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
for (const observer of this.observers) {
|
|
90
|
+
try {
|
|
91
|
+
observer(event);
|
|
92
|
+
}
|
|
93
|
+
catch (error) {
|
|
94
|
+
console.error('Event observer failed.', error);
|
|
95
|
+
}
|
|
96
|
+
}
|
|
14
97
|
};
|
|
15
|
-
|
|
98
|
+
async emitCancelable(name, data) {
|
|
99
|
+
let cancelled = false;
|
|
100
|
+
const event = Object.freeze({
|
|
101
|
+
type: name,
|
|
102
|
+
data,
|
|
103
|
+
cancel: () => {
|
|
104
|
+
cancelled = true;
|
|
105
|
+
},
|
|
106
|
+
get cancelled() {
|
|
107
|
+
return cancelled;
|
|
108
|
+
},
|
|
109
|
+
});
|
|
110
|
+
const pending = [];
|
|
111
|
+
for (const listener of this.listenersFor(name)) {
|
|
112
|
+
try {
|
|
113
|
+
const result = listener(event);
|
|
114
|
+
if (result && typeof result.then === 'function')
|
|
115
|
+
pending.push(result.catch((error) => this.report(error, event)));
|
|
116
|
+
}
|
|
117
|
+
catch (error) {
|
|
118
|
+
this.report(error, event);
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
await Promise.all(pending);
|
|
122
|
+
for (const observer of this.observers) {
|
|
123
|
+
try {
|
|
124
|
+
observer(event);
|
|
125
|
+
}
|
|
126
|
+
catch (error) {
|
|
127
|
+
console.error('Event observer failed.', error);
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
return !cancelled;
|
|
131
|
+
}
|
|
132
|
+
listenersFor(name) {
|
|
133
|
+
const result = [...(this.exact.get(name) ?? [])];
|
|
134
|
+
for (const [prefix, listeners] of this.prefixes)
|
|
135
|
+
if (name.startsWith(prefix))
|
|
136
|
+
result.push(...listeners);
|
|
137
|
+
return result;
|
|
138
|
+
}
|
|
139
|
+
report(error, event) {
|
|
140
|
+
try {
|
|
141
|
+
this.onError(error, event);
|
|
142
|
+
}
|
|
143
|
+
catch (reportError) {
|
|
144
|
+
console.error('Event error reporter failed.', reportError);
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
on = ((names, handler) => {
|
|
16
148
|
const controller = new AbortController();
|
|
17
149
|
const keys = [...new Set(typeof names === 'string' ? [names] : names)];
|
|
18
|
-
// Prefix keys to keep mitt's wildcard private; event names are always literal.
|
|
19
150
|
const invoke = (event) => {
|
|
20
151
|
if (controller.signal.aborted)
|
|
21
152
|
return;
|
|
22
|
-
|
|
23
|
-
try {
|
|
24
|
-
this.onError(error, event);
|
|
25
|
-
}
|
|
26
|
-
catch (reportError) {
|
|
27
|
-
console.error('Event error reporter failed.', reportError);
|
|
28
|
-
}
|
|
29
|
-
};
|
|
30
|
-
try {
|
|
31
|
-
const result = handler(event, { signal: controller.signal });
|
|
32
|
-
if (result)
|
|
33
|
-
void Promise.resolve(result).catch(report);
|
|
34
|
-
}
|
|
35
|
-
catch (error) {
|
|
36
|
-
report(error);
|
|
37
|
-
}
|
|
153
|
+
return handler(event, { signal: controller.signal });
|
|
38
154
|
};
|
|
39
|
-
|
|
40
|
-
this.
|
|
155
|
+
const targets = keys.map((key) => key.endsWith('.*')
|
|
156
|
+
? { map: this.prefixes, key: key.slice(0, -1) }
|
|
157
|
+
: key === '*'
|
|
158
|
+
? { map: this.prefixes, key: '' }
|
|
159
|
+
: { map: this.exact, key });
|
|
160
|
+
for (const { map, key } of targets) {
|
|
161
|
+
let set = map.get(key);
|
|
162
|
+
if (!set)
|
|
163
|
+
map.set(key, (set = new Set()));
|
|
164
|
+
set.add(invoke);
|
|
165
|
+
}
|
|
41
166
|
const unsubscribe = () => {
|
|
42
167
|
if (controller.signal.aborted)
|
|
43
168
|
return;
|
|
44
|
-
for (const key of
|
|
45
|
-
const
|
|
46
|
-
|
|
47
|
-
if (!
|
|
48
|
-
|
|
169
|
+
for (const { map, key } of targets) {
|
|
170
|
+
const set = map.get(key);
|
|
171
|
+
set?.delete(invoke);
|
|
172
|
+
if (set && !set.size)
|
|
173
|
+
map.delete(key);
|
|
49
174
|
}
|
|
50
175
|
this.subscriptions.delete(unsubscribe);
|
|
51
176
|
controller.abort();
|
|
52
177
|
};
|
|
53
178
|
this.subscriptions.add(unsubscribe);
|
|
54
179
|
return unsubscribe;
|
|
55
|
-
};
|
|
56
|
-
/** Diagnostics
|
|
180
|
+
});
|
|
181
|
+
/** Diagnostics only: receives every event after delivery. It cannot change or stop delivery. */
|
|
182
|
+
observe(listener) {
|
|
183
|
+
this.observers.add(listener);
|
|
184
|
+
return () => {
|
|
185
|
+
this.observers.delete(listener);
|
|
186
|
+
};
|
|
187
|
+
}
|
|
188
|
+
/** Diagnostics for lifecycle tests; counts `on` calls, not individual event names. */
|
|
57
189
|
get subscriptionCount() {
|
|
58
190
|
return this.subscriptions.size;
|
|
59
191
|
}
|
|
60
192
|
clear() {
|
|
61
193
|
for (const unsubscribe of [...this.subscriptions])
|
|
62
194
|
unsubscribe();
|
|
63
|
-
this.
|
|
195
|
+
this.exact.clear();
|
|
196
|
+
this.prefixes.clear();
|
|
197
|
+
this.observers.clear();
|
|
198
|
+
this.declared.clear();
|
|
64
199
|
}
|
|
65
200
|
}
|
|
66
|
-
/**
|
|
67
|
-
|
|
201
|
+
/**
|
|
202
|
+
* A scoped view for one module: releases its listeners on disposal and may emit only into
|
|
203
|
+
* namespaces it owns or that nobody declared.
|
|
204
|
+
*/
|
|
205
|
+
export function createEventScope(events, owner) {
|
|
68
206
|
let active = true;
|
|
69
207
|
const cleanups = new Set();
|
|
70
208
|
const scoped = {
|
|
71
|
-
emit: (name, ...data) => {
|
|
72
|
-
if (active)
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
209
|
+
emit: ((name, ...data) => {
|
|
210
|
+
if (!active)
|
|
211
|
+
return undefined;
|
|
212
|
+
const declaredBy = events.ownerOf(name);
|
|
213
|
+
if (owner !== undefined && declaredBy !== undefined && declaredBy !== owner)
|
|
214
|
+
throw new Error(`"${owner}" cannot emit "${name}": that event belongs to plugin "${declaredBy}". Only the declaring plugin emits its events; listen with events.on instead.`);
|
|
215
|
+
return events.emit(name, ...data);
|
|
216
|
+
}),
|
|
217
|
+
on: ((names, handler) => {
|
|
76
218
|
if (!active)
|
|
77
219
|
throw new Error('Event scope is no longer active.');
|
|
78
|
-
const unsubscribe = events.
|
|
220
|
+
const unsubscribe = events.on(names, handler);
|
|
79
221
|
const release = () => {
|
|
80
222
|
cleanups.delete(release);
|
|
81
223
|
unsubscribe();
|
|
82
224
|
};
|
|
83
225
|
cleanups.add(release);
|
|
84
226
|
return release;
|
|
85
|
-
},
|
|
227
|
+
}),
|
|
86
228
|
};
|
|
87
229
|
return {
|
|
88
230
|
events: scoped,
|
package/dist/events/types.d.ts
CHANGED
|
@@ -1,19 +1,39 @@
|
|
|
1
|
-
|
|
1
|
+
import type { GeneratedName } from '../names.js';
|
|
2
|
+
/** Event names and payloads. Generated from every plugin's `events.ts`; may also be augmented by hand. */
|
|
2
3
|
export interface EventMap {
|
|
3
4
|
}
|
|
4
|
-
|
|
5
|
+
/** Events whose `emit` waits for the handlers and returns whether none cancelled. */
|
|
6
|
+
export interface CancelableEventMap {
|
|
7
|
+
}
|
|
8
|
+
export type KnownEventName = Extract<keyof EventMap, string>;
|
|
9
|
+
/** A declared event name; strict generated apps reject unknown names. */
|
|
10
|
+
export type EventName = GeneratedName<KnownEventName>;
|
|
11
|
+
type PatternOf<Name extends string> = Name extends `${infer Prefix}.${string}` ? `${Prefix}.*` : never;
|
|
12
|
+
/** What a listener selects: an event, a `<prefix>.*` pattern of declared events, or `*`. */
|
|
13
|
+
export type EventSelector = EventName | PatternOf<KnownEventName> | '*';
|
|
5
14
|
export type EventData<Name extends string> = Name extends keyof EventMap ? EventMap[Name] : unknown;
|
|
6
|
-
|
|
15
|
+
/** `todos.*` matches every declared `todos.<name>` event. */
|
|
16
|
+
export type EventsMatching<Pattern extends string> = Pattern extends `${infer Prefix}.*` ? Extract<keyof EventMap, `${Prefix}.${string}`> extends never ? string : Extract<keyof EventMap, `${Prefix}.${string}`> : Pattern;
|
|
17
|
+
export type BitaKitEvent<Name extends string = string> = Name extends string ? Readonly<{
|
|
7
18
|
type: Name;
|
|
8
19
|
data: EventData<Name>;
|
|
20
|
+
/** Present on cancelable events: stops the operation that asked. */
|
|
21
|
+
cancel?: (reason?: string) => void;
|
|
22
|
+
cancelled?: boolean;
|
|
9
23
|
}> : never;
|
|
10
|
-
export type EventHandler<Name extends string = string> = (event:
|
|
24
|
+
export type EventHandler<Name extends string = string> = (event: BitaKitEvent<EventsMatching<Name>>, context: {
|
|
11
25
|
signal: AbortSignal;
|
|
12
26
|
}) => void | Promise<void>;
|
|
13
|
-
export type EventErrorHandler = (error: unknown, event:
|
|
27
|
+
export type EventErrorHandler = (error: unknown, event: BitaKitEvent) => void;
|
|
28
|
+
export type EmitResult<Name extends string> = Name extends keyof CancelableEventMap ? Promise<boolean> : void;
|
|
29
|
+
type EmitArguments<Name extends string> = undefined extends EventData<Name> ? [data?: EventData<Name>] : [data: EventData<Name>];
|
|
14
30
|
export interface Events {
|
|
15
|
-
/** Each matching event invokes the handler once. Returns
|
|
16
|
-
|
|
17
|
-
/**
|
|
18
|
-
|
|
31
|
+
/** Each matching event invokes the handler once. Returns the unsubscribe function. */
|
|
32
|
+
on<const Name extends EventSelector>(names: Name | readonly Name[], handler: EventHandler<Name>): () => void;
|
|
33
|
+
/**
|
|
34
|
+
* Synchronous delivery; async handlers are observed for errors, not awaited. A cancelable
|
|
35
|
+
* event waits for its handlers and resolves to false when one of them cancelled.
|
|
36
|
+
*/
|
|
37
|
+
emit<Name extends EventName>(name: Name, ...data: EmitArguments<Name>): EmitResult<Name>;
|
|
19
38
|
}
|
|
39
|
+
export {};
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
import type { PluginMetadata } from '../definitions.js';
|
|
2
|
+
import type { LifecyclePhase, LifecycleSnapshot } from '../lifecycle/state.js';
|
|
3
|
+
import type { BitaKitRuntime } from '../runtime.js';
|
|
4
|
+
export type InventoryKind = 'service' | 'action' | 'event' | 'page' | 'setting' | 'slot' | 'widget' | 'provider' | 'config' | 'interceptor';
|
|
5
|
+
export type InventoryDeclaration = Readonly<{
|
|
6
|
+
kind: InventoryKind;
|
|
7
|
+
id: string | null;
|
|
8
|
+
source: string | null;
|
|
9
|
+
resolution: 'resolved' | 'file';
|
|
10
|
+
}>;
|
|
11
|
+
export type InventoryMetadata = Readonly<Pick<PluginMetadata, 'name' | 'description' | 'version' | 'license' | 'homepage' | 'tags' | 'coverImage'> & {
|
|
12
|
+
author?: string;
|
|
13
|
+
support?: string;
|
|
14
|
+
}>;
|
|
15
|
+
export type InventoryPlugin = Readonly<{
|
|
16
|
+
/** Stable inventory key; an unresolved package uses its export specifier. */
|
|
17
|
+
id: string;
|
|
18
|
+
pluginId: string | null;
|
|
19
|
+
enabled: boolean | null;
|
|
20
|
+
source: Readonly<{
|
|
21
|
+
kind: 'runtime' | 'file' | 'package';
|
|
22
|
+
path: string | null;
|
|
23
|
+
}>;
|
|
24
|
+
metadata: InventoryMetadata;
|
|
25
|
+
dependencies: readonly string[] | null;
|
|
26
|
+
declarations: readonly InventoryDeclaration[] | null;
|
|
27
|
+
}>;
|
|
28
|
+
export type InventoryLive = Readonly<{
|
|
29
|
+
revision: number;
|
|
30
|
+
phase: LifecyclePhase;
|
|
31
|
+
cleanup: LifecycleSnapshot['cleanup'];
|
|
32
|
+
operation: LifecycleSnapshot['operation'];
|
|
33
|
+
plugins: readonly Readonly<{
|
|
34
|
+
id: string;
|
|
35
|
+
phase: LifecyclePhase;
|
|
36
|
+
since: number;
|
|
37
|
+
}>[];
|
|
38
|
+
services: readonly Readonly<{
|
|
39
|
+
id: string;
|
|
40
|
+
plugin: string;
|
|
41
|
+
phase: LifecyclePhase;
|
|
42
|
+
since: number;
|
|
43
|
+
}>[];
|
|
44
|
+
actions: readonly Readonly<{
|
|
45
|
+
id: string;
|
|
46
|
+
plugin: string | null;
|
|
47
|
+
enabled: boolean;
|
|
48
|
+
visible: boolean;
|
|
49
|
+
pending: boolean;
|
|
50
|
+
}>[];
|
|
51
|
+
slots: readonly Readonly<{
|
|
52
|
+
id: string;
|
|
53
|
+
plugin: string;
|
|
54
|
+
phase: LifecyclePhase;
|
|
55
|
+
count: number;
|
|
56
|
+
/** Headless inspection cannot observe React outlet instances or contextual rendering. */
|
|
57
|
+
mountedOutlets: null;
|
|
58
|
+
visibleCount: null;
|
|
59
|
+
renderFailures: null;
|
|
60
|
+
}>[];
|
|
61
|
+
}>;
|
|
62
|
+
export type RuntimeInventory = Readonly<{
|
|
63
|
+
version: 1;
|
|
64
|
+
static: Readonly<{
|
|
65
|
+
plugins: readonly InventoryPlugin[];
|
|
66
|
+
}>;
|
|
67
|
+
/** Null means there is no running process to inspect, never an empty/healthy runtime. */
|
|
68
|
+
live: InventoryLive | null;
|
|
69
|
+
}>;
|
|
70
|
+
/** Public declaration metadata only; no icons, functions, defaults, credentials or arbitrary fields. */
|
|
71
|
+
export declare function inventoryMetadata(metadata?: PluginMetadata): InventoryMetadata;
|
|
72
|
+
/** Both static tooling and runtime readers produce this versioned, serializable envelope. */
|
|
73
|
+
export declare function createInventory(plugins: readonly InventoryPlugin[], live?: InventoryLive | null): RuntimeInventory;
|
|
74
|
+
export declare function inspectRuntime(runtime: BitaKitRuntime): RuntimeInventory;
|
|
75
|
+
/** Stable read snapshots for React/external-store consumers; this caches diagnostics, never app values. */
|
|
76
|
+
export declare function observeRuntimeInventory(runtime: BitaKitRuntime): {
|
|
77
|
+
get: () => Readonly<{
|
|
78
|
+
version: 1;
|
|
79
|
+
static: Readonly<{
|
|
80
|
+
plugins: readonly InventoryPlugin[];
|
|
81
|
+
}>;
|
|
82
|
+
/** Null means there is no running process to inspect, never an empty/healthy runtime. */
|
|
83
|
+
live: InventoryLive | null;
|
|
84
|
+
}>;
|
|
85
|
+
subscribe: (listener: () => void) => () => void;
|
|
86
|
+
};
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
import { contributionSource } from '../contribution-origin.js';
|
|
2
|
+
/** Public declaration metadata only; no icons, functions, defaults, credentials or arbitrary fields. */
|
|
3
|
+
export function inventoryMetadata(metadata = {}) {
|
|
4
|
+
const result = {};
|
|
5
|
+
for (const key of [
|
|
6
|
+
'name',
|
|
7
|
+
'description',
|
|
8
|
+
'version',
|
|
9
|
+
'license',
|
|
10
|
+
'homepage',
|
|
11
|
+
'coverImage',
|
|
12
|
+
])
|
|
13
|
+
if (typeof metadata[key] === 'string')
|
|
14
|
+
result[key] = metadata[key];
|
|
15
|
+
const author = typeof metadata.author === 'string' ? metadata.author : metadata.author?.name;
|
|
16
|
+
const support = typeof metadata.bugs === 'string' ? metadata.bugs : metadata.bugs?.url;
|
|
17
|
+
if (author)
|
|
18
|
+
result.author = author;
|
|
19
|
+
if (support)
|
|
20
|
+
result.support = support;
|
|
21
|
+
if (metadata.tags)
|
|
22
|
+
result.tags = Object.freeze([...metadata.tags]);
|
|
23
|
+
return Object.freeze(result);
|
|
24
|
+
}
|
|
25
|
+
/** Both static tooling and runtime readers produce this versioned, serializable envelope. */
|
|
26
|
+
export function createInventory(plugins, live = null) {
|
|
27
|
+
return Object.freeze({
|
|
28
|
+
version: 1,
|
|
29
|
+
static: Object.freeze({ plugins: Object.freeze([...plugins]) }),
|
|
30
|
+
live,
|
|
31
|
+
});
|
|
32
|
+
}
|
|
33
|
+
export function inspectRuntime(runtime) {
|
|
34
|
+
const entry = (kind, id, value) => Object.freeze({
|
|
35
|
+
kind,
|
|
36
|
+
id,
|
|
37
|
+
source: value ? (contributionSource(value) ?? null) : null,
|
|
38
|
+
resolution: 'resolved',
|
|
39
|
+
});
|
|
40
|
+
const lifecycle = runtime.lifecycle.get();
|
|
41
|
+
return createInventory([
|
|
42
|
+
...runtime.modules.map((module) => Object.freeze({
|
|
43
|
+
id: module.id,
|
|
44
|
+
pluginId: module.id,
|
|
45
|
+
enabled: true,
|
|
46
|
+
source: Object.freeze({ kind: 'runtime', path: null }),
|
|
47
|
+
metadata: inventoryMetadata(module.metadata),
|
|
48
|
+
dependencies: Object.freeze([...(module.dependencies ?? [])]),
|
|
49
|
+
declarations: Object.freeze([
|
|
50
|
+
...module.services.map((value) => entry('service', value.id, value)),
|
|
51
|
+
...module.actions
|
|
52
|
+
.filter((value) => !value.internal)
|
|
53
|
+
.map((value) => entry('action', value.id, value)),
|
|
54
|
+
...module.pages.map((value) => entry('page', value.path, value)),
|
|
55
|
+
...module.slots.map((value) => entry('slot', value.id, value)),
|
|
56
|
+
...module.views.map((value) => entry('widget', value.slot, value)),
|
|
57
|
+
...module.providers.map((value) => entry('provider', value.id, value)),
|
|
58
|
+
...Object.keys(module.events?.events ?? {}).map((name) => entry('event', `${module.id}.${name}`)),
|
|
59
|
+
...Object.keys(module.settings?.settings ?? {}).map((name) => entry('setting', module.id === (runtime.config.appId ?? 'app') ? name : `${module.id}.${name}`)),
|
|
60
|
+
...(module.config ? [entry('config', module.id)] : []),
|
|
61
|
+
...(module.interceptors ?? []).map((value, index) => entry('interceptor', `${module.id}:${index}`, value)),
|
|
62
|
+
]),
|
|
63
|
+
})),
|
|
64
|
+
...(runtime.config.plugins ?? [])
|
|
65
|
+
.filter((plugin) => !runtime.modules.some((module) => module.id === plugin.id))
|
|
66
|
+
.map((plugin) => Object.freeze({
|
|
67
|
+
id: plugin.id,
|
|
68
|
+
pluginId: plugin.id,
|
|
69
|
+
enabled: false,
|
|
70
|
+
source: Object.freeze({ kind: 'runtime', path: null }),
|
|
71
|
+
metadata: inventoryMetadata(plugin.metadata),
|
|
72
|
+
dependencies: Object.freeze([...(plugin.dependencies ?? [])]),
|
|
73
|
+
declarations: null,
|
|
74
|
+
})),
|
|
75
|
+
], Object.freeze({
|
|
76
|
+
revision: runtime.getRevision(),
|
|
77
|
+
phase: lifecycle.phase,
|
|
78
|
+
cleanup: lifecycle.cleanup,
|
|
79
|
+
operation: lifecycle.operation,
|
|
80
|
+
plugins: Object.freeze(lifecycle.plugins.map(({ id, phase, since }) => Object.freeze({ id, phase, since }))),
|
|
81
|
+
services: Object.freeze(lifecycle.services.map(({ id, plugin, phase, since }) => Object.freeze({ id, plugin, phase, since }))),
|
|
82
|
+
actions: Object.freeze(Object.values(runtime.actions.getState().actions)
|
|
83
|
+
.filter((value) => !value.internal)
|
|
84
|
+
.map(({ id, enabled, visible, pending }) => Object.freeze({
|
|
85
|
+
id,
|
|
86
|
+
plugin: runtime.actionOwner(id) ?? null,
|
|
87
|
+
enabled,
|
|
88
|
+
visible,
|
|
89
|
+
pending,
|
|
90
|
+
}))),
|
|
91
|
+
slots: Object.freeze(runtime.modules.flatMap((module) => module.slots.map((slot) => {
|
|
92
|
+
const { id, phase, items } = runtime.slots.get(slot.id);
|
|
93
|
+
return Object.freeze({
|
|
94
|
+
id,
|
|
95
|
+
plugin: module.id,
|
|
96
|
+
phase,
|
|
97
|
+
count: items.length,
|
|
98
|
+
mountedOutlets: null,
|
|
99
|
+
visibleCount: null,
|
|
100
|
+
renderFailures: null,
|
|
101
|
+
});
|
|
102
|
+
}))),
|
|
103
|
+
}));
|
|
104
|
+
}
|
|
105
|
+
/** Stable read snapshots for React/external-store consumers; this caches diagnostics, never app values. */
|
|
106
|
+
export function observeRuntimeInventory(runtime) {
|
|
107
|
+
let previous = [], snapshot;
|
|
108
|
+
const get = () => {
|
|
109
|
+
const inputs = [
|
|
110
|
+
runtime.modules,
|
|
111
|
+
runtime.lifecycle.get(),
|
|
112
|
+
runtime.actions.getState(),
|
|
113
|
+
...runtime.modules.flatMap((module) => module.slots.map((slot) => runtime.slots.get(slot.id))),
|
|
114
|
+
];
|
|
115
|
+
if (!snapshot ||
|
|
116
|
+
inputs.length !== previous.length ||
|
|
117
|
+
inputs.some((value, index) => value !== previous[index])) {
|
|
118
|
+
previous = inputs;
|
|
119
|
+
snapshot = inspectRuntime(runtime);
|
|
120
|
+
}
|
|
121
|
+
return snapshot;
|
|
122
|
+
};
|
|
123
|
+
const subscribe = (listener) => {
|
|
124
|
+
const off = [
|
|
125
|
+
runtime.lifecycle.subscribe(listener),
|
|
126
|
+
runtime.actions.subscribe(listener),
|
|
127
|
+
runtime.events.on('runtime.slot', listener),
|
|
128
|
+
];
|
|
129
|
+
return () => off.forEach((release) => release());
|
|
130
|
+
};
|
|
131
|
+
return { get, subscribe };
|
|
132
|
+
}
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
import type { ActionContext } from '../actions/types.js';
|
|
2
|
+
import type { ConfigContext } from '../config-service.js';
|
|
3
|
+
import type { Services, Translator } from '../definitions.js';
|
|
4
|
+
import type { BitaKitApp } from '../app/types.js';
|
|
5
|
+
import type { ServiceMap } from '../definitions.js';
|
|
6
|
+
/** Exact IDs, `todos.*` for one plugin, `*` for everything. */
|
|
7
|
+
export type InterceptorTarget = string | readonly string[];
|
|
8
|
+
export type ActionInterceptorContext = ActionContext & {
|
|
9
|
+
services: Services;
|
|
10
|
+
config: ConfigContext;
|
|
11
|
+
app: BitaKitApp;
|
|
12
|
+
translate: Translator;
|
|
13
|
+
};
|
|
14
|
+
/** Returning `false` cancels the action (skipped with reason "intercepted"). */
|
|
15
|
+
export type ActionInterceptorSpec = {
|
|
16
|
+
readonly kind?: 'interceptor';
|
|
17
|
+
action: InterceptorTarget;
|
|
18
|
+
service?: never;
|
|
19
|
+
method?: never;
|
|
20
|
+
order?: number;
|
|
21
|
+
/** `plugin` (default) limits matching to the interceptor's own plugin; `global` sees every plugin. */
|
|
22
|
+
scope?: 'plugin' | 'global';
|
|
23
|
+
requires?: readonly string[];
|
|
24
|
+
before?(context: ActionInterceptorContext): boolean | void | Promise<boolean | void>;
|
|
25
|
+
after?(context: ActionInterceptorContext & {
|
|
26
|
+
readonly result: unknown;
|
|
27
|
+
}): void | Promise<void>;
|
|
28
|
+
onError?(context: ActionInterceptorContext & {
|
|
29
|
+
readonly error: unknown;
|
|
30
|
+
}): void | Promise<void>;
|
|
31
|
+
};
|
|
32
|
+
type Methods<S> = {
|
|
33
|
+
[K in keyof S & string]: S[K] extends (...args: any[]) => any ? K : never;
|
|
34
|
+
}[keyof S & string];
|
|
35
|
+
type ServiceOf<Name extends string> = Name extends keyof ServiceMap ? NonNullable<ServiceMap[Name]> : Record<string, (...args: any[]) => unknown>;
|
|
36
|
+
type MethodOf<Name extends string, Key extends string> = Key extends keyof ServiceOf<Name> ? Extract<ServiceOf<Name>[Key], (...args: any[]) => any> : (...args: any[]) => unknown;
|
|
37
|
+
export type ServiceCall<Name extends string = string, Key extends string = string> = {
|
|
38
|
+
readonly service: Name;
|
|
39
|
+
readonly method: Key;
|
|
40
|
+
readonly args: Readonly<Parameters<MethodOf<Name, Key>>>;
|
|
41
|
+
};
|
|
42
|
+
/** Observes one method or every public method of a service. Hooks never change the outcome. */
|
|
43
|
+
export type ServiceInterceptorSpec<Name extends string = string, Key extends string = string> = {
|
|
44
|
+
readonly kind?: 'interceptor';
|
|
45
|
+
service: Name | readonly string[];
|
|
46
|
+
method?: Key;
|
|
47
|
+
action?: never;
|
|
48
|
+
scope?: never;
|
|
49
|
+
requires?: never;
|
|
50
|
+
order?: number;
|
|
51
|
+
before?(call: ServiceCall<Name, Key>): void;
|
|
52
|
+
after?(call: ServiceCall<Name, Key> & {
|
|
53
|
+
readonly result: Awaited<ReturnType<MethodOf<Name, Key>>>;
|
|
54
|
+
}): void;
|
|
55
|
+
onError?(call: ServiceCall<Name, Key> & {
|
|
56
|
+
readonly error: unknown;
|
|
57
|
+
}): void;
|
|
58
|
+
};
|
|
59
|
+
export type InterceptorSpec = (ActionInterceptorSpec | ServiceInterceptorSpec<any, any>) & {
|
|
60
|
+
readonly kind: 'interceptor';
|
|
61
|
+
};
|
|
62
|
+
/**
|
|
63
|
+
* One helper for both targets. `action` gates and observes actions; `service` observes service
|
|
64
|
+
* methods. A definition without a target observes every action of its own plugin.
|
|
65
|
+
*/
|
|
66
|
+
export declare function defineInterceptor(spec: ActionInterceptorSpec): InterceptorSpec;
|
|
67
|
+
export declare function defineInterceptor<const Name extends string, const Key extends Methods<ServiceOf<Name>> = Methods<ServiceOf<Name>>>(spec: ServiceInterceptorSpec<Name, Key>): InterceptorSpec;
|
|
68
|
+
export declare function defineInterceptor(spec: Omit<ActionInterceptorSpec, 'action'> & {
|
|
69
|
+
action?: undefined;
|
|
70
|
+
}): InterceptorSpec;
|
|
71
|
+
export declare function isServiceInterceptor(spec: object): spec is ServiceInterceptorSpec & {
|
|
72
|
+
kind: 'interceptor';
|
|
73
|
+
};
|
|
74
|
+
/** Glob matching for action IDs and service names: exact, `prefix.*`, or `*`. */
|
|
75
|
+
export declare function matchesTarget(target: InterceptorTarget, id: string): boolean;
|
|
76
|
+
export {};
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
export function defineInterceptor(spec) {
|
|
2
|
+
if (!spec || typeof spec !== 'object')
|
|
3
|
+
throw new Error('defineInterceptor expects an object.');
|
|
4
|
+
if ('action' in spec &&
|
|
5
|
+
spec.action !== undefined &&
|
|
6
|
+
'service' in spec &&
|
|
7
|
+
spec.service !== undefined)
|
|
8
|
+
throw new Error('An interceptor targets either actions or a service, not both. Export an array with one entry for each.');
|
|
9
|
+
const resolved = 'service' in spec && spec.service !== undefined ? spec : { action: '*', ...spec };
|
|
10
|
+
return { ...resolved, kind: 'interceptor' };
|
|
11
|
+
}
|
|
12
|
+
export function isServiceInterceptor(spec) {
|
|
13
|
+
return 'service' in spec && spec.service !== undefined;
|
|
14
|
+
}
|
|
15
|
+
/** Glob matching for action IDs and service names: exact, `prefix.*`, or `*`. */
|
|
16
|
+
export function matchesTarget(target, id) {
|
|
17
|
+
const patterns = typeof target === 'string' ? [target] : target;
|
|
18
|
+
return patterns.some((pattern) => pattern === '*'
|
|
19
|
+
? true
|
|
20
|
+
: pattern.endsWith('.*')
|
|
21
|
+
? id.startsWith(pattern.slice(0, -1))
|
|
22
|
+
: pattern === id);
|
|
23
|
+
}
|
|
@@ -1,3 +1,6 @@
|
|
|
1
|
-
import type
|
|
2
|
-
/**
|
|
3
|
-
|
|
1
|
+
import { type InterceptorSpec } from './define.js';
|
|
2
|
+
/**
|
|
3
|
+
* Wraps service instances whose ID or alias matches an interceptor's `service` target. All
|
|
4
|
+
* container consumers receive the same wrapper; frozen instances are supported.
|
|
5
|
+
*/
|
|
6
|
+
export declare function serviceObserver(interceptors: readonly InterceptorSpec[], namesOf: (id: string) => readonly string[]): (id: string, instance: any, active: () => boolean) => any;
|