@bitakit/core 0.1.1 → 0.2.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/README.md +47 -161
- package/assets/bitakit-logo-dark.svg +11 -0
- package/assets/bitakit-logo.svg +11 -0
- 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 +37 -9
- package/testing/index.d.ts +59 -0
- package/testing/index.mjs +150 -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
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
import { defineContract } from '../service-key.js';
|
|
2
|
+
/**
|
|
3
|
+
* The storage contract. Browser storage is the default; a host persists settings on a server
|
|
4
|
+
* with one service: `defineService(() => ({ load, save }), { provides: settingsStorage })`.
|
|
5
|
+
*/
|
|
6
|
+
export const settingsStorage = defineContract('settings.storage').of();
|
|
7
|
+
/** The slot a value lives in, or undefined when the scope has no owner yet. */
|
|
8
|
+
export function settingsOwner(context) {
|
|
9
|
+
switch (context.scope) {
|
|
10
|
+
case 'device':
|
|
11
|
+
return 'device';
|
|
12
|
+
case 'user':
|
|
13
|
+
return `user:${context.userId ?? 'anonymous'}`;
|
|
14
|
+
case 'organization':
|
|
15
|
+
return context.organizationId ? `organization:${context.organizationId}` : undefined;
|
|
16
|
+
}
|
|
17
|
+
}
|
|
18
|
+
const noOrganization = () => new Error('This setting belongs to an organization, but none is active.');
|
|
19
|
+
/** In-memory storage for tests and servers without persistence. `initial` seeds values by key. */
|
|
20
|
+
export function createMemorySettingsStorage(initial = {}) {
|
|
21
|
+
const data = new Map();
|
|
22
|
+
const slot = (key, context) => {
|
|
23
|
+
const owner = settingsOwner(context);
|
|
24
|
+
return owner ? `${owner}/${key}` : undefined;
|
|
25
|
+
};
|
|
26
|
+
return {
|
|
27
|
+
data,
|
|
28
|
+
load(key, context) {
|
|
29
|
+
const id = slot(key, context);
|
|
30
|
+
if (!id)
|
|
31
|
+
return { value: undefined, writable: false };
|
|
32
|
+
return { value: data.has(id) ? data.get(id) : initial[key], writable: true };
|
|
33
|
+
},
|
|
34
|
+
save(key, value, context) {
|
|
35
|
+
const id = slot(key, context);
|
|
36
|
+
if (!id)
|
|
37
|
+
throw noOrganization();
|
|
38
|
+
data.set(id, value);
|
|
39
|
+
},
|
|
40
|
+
reset(key, context) {
|
|
41
|
+
const id = slot(key, context);
|
|
42
|
+
if (!id)
|
|
43
|
+
throw noOrganization();
|
|
44
|
+
data.delete(id);
|
|
45
|
+
return { value: initial[key], writable: true };
|
|
46
|
+
},
|
|
47
|
+
};
|
|
48
|
+
}
|
|
49
|
+
function browserStore() {
|
|
50
|
+
try {
|
|
51
|
+
const store = globalThis.localStorage;
|
|
52
|
+
if (!store)
|
|
53
|
+
return undefined;
|
|
54
|
+
const probe = '__bitakit_settings__';
|
|
55
|
+
store.setItem(probe, '1');
|
|
56
|
+
store.removeItem(probe);
|
|
57
|
+
return store;
|
|
58
|
+
}
|
|
59
|
+
catch {
|
|
60
|
+
return undefined;
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
/** Browser storage keyed by scope owner; falls back to memory where no storage exists. */
|
|
64
|
+
export function createLocalSettingsStorage(options = {}) {
|
|
65
|
+
const store = options.store ?? browserStore();
|
|
66
|
+
if (!store)
|
|
67
|
+
return createMemorySettingsStorage();
|
|
68
|
+
const prefix = options.prefix ?? 'bitakit.settings.';
|
|
69
|
+
const slot = (key, context) => {
|
|
70
|
+
const owner = settingsOwner(context);
|
|
71
|
+
return owner ? `${prefix}${owner}/${key}` : undefined;
|
|
72
|
+
};
|
|
73
|
+
return {
|
|
74
|
+
load(key, context) {
|
|
75
|
+
const id = slot(key, context);
|
|
76
|
+
if (!id)
|
|
77
|
+
return { value: undefined, writable: false };
|
|
78
|
+
const raw = store.getItem(id);
|
|
79
|
+
if (raw === null)
|
|
80
|
+
return { value: undefined, writable: true };
|
|
81
|
+
try {
|
|
82
|
+
return { value: JSON.parse(raw), writable: true };
|
|
83
|
+
}
|
|
84
|
+
catch {
|
|
85
|
+
return { value: undefined, writable: true };
|
|
86
|
+
}
|
|
87
|
+
},
|
|
88
|
+
save(key, value, context) {
|
|
89
|
+
const id = slot(key, context);
|
|
90
|
+
if (!id)
|
|
91
|
+
throw noOrganization();
|
|
92
|
+
store.setItem(id, JSON.stringify(value));
|
|
93
|
+
},
|
|
94
|
+
reset(key, context) {
|
|
95
|
+
const id = slot(key, context);
|
|
96
|
+
if (!id)
|
|
97
|
+
throw noOrganization();
|
|
98
|
+
store.removeItem(id);
|
|
99
|
+
return { value: undefined, writable: true };
|
|
100
|
+
},
|
|
101
|
+
};
|
|
102
|
+
}
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
import { type SettingSpec } from './define.js';
|
|
2
|
+
import type { SettingsContext, SettingsStorage } from './storage.js';
|
|
3
|
+
export type SettingState<T = unknown> = Readonly<{
|
|
4
|
+
value: T;
|
|
5
|
+
/** A stored value (or the confirmed absence of one) has been loaded for the current identity. */
|
|
6
|
+
ready: boolean;
|
|
7
|
+
writable: boolean;
|
|
8
|
+
/** A write is queued or in flight. */
|
|
9
|
+
pending: boolean;
|
|
10
|
+
error?: string;
|
|
11
|
+
}>;
|
|
12
|
+
/** "saved" once confirmed, "superseded" when a newer value replaced this one before it was sent, "cancelled" when the identity changed. */
|
|
13
|
+
export type SaveResult = 'saved' | 'superseded' | 'cancelled';
|
|
14
|
+
export type SettingsIdentity = {
|
|
15
|
+
readonly userId?: string;
|
|
16
|
+
readonly organizationId?: string;
|
|
17
|
+
};
|
|
18
|
+
export type SettingEntry = {
|
|
19
|
+
readonly key: string;
|
|
20
|
+
readonly plugin: string;
|
|
21
|
+
readonly name: string;
|
|
22
|
+
readonly spec: SettingSpec<any>;
|
|
23
|
+
};
|
|
24
|
+
/**
|
|
25
|
+
* The one owner of setting values: loads them per identity, queues writes (one in flight per
|
|
26
|
+
* key, newer values replace queued ones) and notifies subscribers. Headless; `useSetting`
|
|
27
|
+
* and the `settings` context are views onto it.
|
|
28
|
+
*/
|
|
29
|
+
export declare class SettingsStore {
|
|
30
|
+
private readonly storage;
|
|
31
|
+
private readonly slots;
|
|
32
|
+
private readonly listeners;
|
|
33
|
+
private identity;
|
|
34
|
+
private generation;
|
|
35
|
+
private active;
|
|
36
|
+
constructor(entries: readonly SettingEntry[], storage: () => SettingsStorage);
|
|
37
|
+
/** Reconcile declarations while keeping retained values and pending reads isolated by slot identity. */
|
|
38
|
+
replace(entries: readonly SettingEntry[]): void;
|
|
39
|
+
/** Every declared setting, in declaration order. */
|
|
40
|
+
entries(): readonly SettingEntry[];
|
|
41
|
+
has(key: string): boolean;
|
|
42
|
+
definition(key: string): SettingEntry;
|
|
43
|
+
get isActive(): boolean;
|
|
44
|
+
get currentIdentity(): SettingsIdentity;
|
|
45
|
+
/** The storage context of one key under the current identity. */
|
|
46
|
+
context(key: string): SettingsContext;
|
|
47
|
+
state<T = unknown>(key: string): SettingState<T>;
|
|
48
|
+
/** The state before anything loaded; stable per key, for server snapshots. */
|
|
49
|
+
initialState<T = unknown>(key: string): SettingState<T>;
|
|
50
|
+
get<T = unknown>(key: string): T;
|
|
51
|
+
/** Validates a value against the declaration without storing it. */
|
|
52
|
+
parse<T = unknown>(key: string, value: unknown): T;
|
|
53
|
+
/** Subscribes to one key, or to every change when only a listener is given. */
|
|
54
|
+
subscribe(listener: () => void): () => void;
|
|
55
|
+
subscribe(key: string, listener: () => void): () => void;
|
|
56
|
+
/** Loads every value for an identity. Queued writes of the previous identity resolve "cancelled". */
|
|
57
|
+
activate(identity?: SettingsIdentity): Promise<void>;
|
|
58
|
+
/** Keeps the last values but marks nothing ready or writable until the next activation. */
|
|
59
|
+
deactivate(): void;
|
|
60
|
+
/** Reloads one key, or every key, for the current identity. */
|
|
61
|
+
refresh(key?: string): Promise<void>;
|
|
62
|
+
/** Validates and queues a write; rejects only on validation or this value's own storage failure. */
|
|
63
|
+
set(key: string, value: unknown): Promise<SaveResult>;
|
|
64
|
+
/** Removes the stored value (`storage.reset`) or, without it, saves the default. */
|
|
65
|
+
reset(key: string): Promise<SaveResult>;
|
|
66
|
+
private slot;
|
|
67
|
+
private writable;
|
|
68
|
+
private publish;
|
|
69
|
+
private cancel;
|
|
70
|
+
private loadAll;
|
|
71
|
+
private load;
|
|
72
|
+
private enqueue;
|
|
73
|
+
private drain;
|
|
74
|
+
}
|
|
@@ -0,0 +1,345 @@
|
|
|
1
|
+
import { parseSetting } from './define.js';
|
|
2
|
+
import { schemaErrorMessage } from '../schema.js';
|
|
3
|
+
const message = (error, fallback) => schemaErrorMessage(error, fallback);
|
|
4
|
+
/** Starts storage work synchronously and turns a synchronous throw into a rejection. */
|
|
5
|
+
function attempt(run) {
|
|
6
|
+
try {
|
|
7
|
+
return Promise.resolve(run());
|
|
8
|
+
}
|
|
9
|
+
catch (error) {
|
|
10
|
+
return Promise.reject(error);
|
|
11
|
+
}
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* The one owner of setting values: loads them per identity, queues writes (one in flight per
|
|
15
|
+
* key, newer values replace queued ones) and notifies subscribers. Headless; `useSetting`
|
|
16
|
+
* and the `settings` context are views onto it.
|
|
17
|
+
*/
|
|
18
|
+
export class SettingsStore {
|
|
19
|
+
storage;
|
|
20
|
+
slots = new Map();
|
|
21
|
+
listeners = new Set();
|
|
22
|
+
identity = Object.freeze({});
|
|
23
|
+
generation = 0;
|
|
24
|
+
active = false;
|
|
25
|
+
constructor(entries, storage) {
|
|
26
|
+
this.storage = storage;
|
|
27
|
+
for (const entry of entries) {
|
|
28
|
+
if (this.slots.has(entry.key))
|
|
29
|
+
throw new Error(`Duplicate setting "${entry.key}".`);
|
|
30
|
+
const initial = Object.freeze({
|
|
31
|
+
value: entry.spec.default,
|
|
32
|
+
ready: false,
|
|
33
|
+
writable: false,
|
|
34
|
+
pending: false,
|
|
35
|
+
});
|
|
36
|
+
this.slots.set(entry.key, {
|
|
37
|
+
entry,
|
|
38
|
+
state: initial,
|
|
39
|
+
initial,
|
|
40
|
+
loadToken: 0,
|
|
41
|
+
flying: false,
|
|
42
|
+
superseded: [],
|
|
43
|
+
listeners: new Set(),
|
|
44
|
+
});
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
/** Reconcile declarations while keeping retained values and pending reads isolated by slot identity. */
|
|
48
|
+
replace(entries) {
|
|
49
|
+
const next = new SettingsStore(entries, this.storage);
|
|
50
|
+
for (const [key, slot] of this.slots)
|
|
51
|
+
if (!next.slots.has(key)) {
|
|
52
|
+
this.cancel(slot);
|
|
53
|
+
slot.loadToken++;
|
|
54
|
+
this.slots.delete(key);
|
|
55
|
+
}
|
|
56
|
+
const added = [];
|
|
57
|
+
for (const [key, slot] of next.slots)
|
|
58
|
+
if (!this.slots.has(key)) {
|
|
59
|
+
this.slots.set(key, slot);
|
|
60
|
+
added.push(slot);
|
|
61
|
+
}
|
|
62
|
+
if (this.active)
|
|
63
|
+
void this.loadAll(added, this.generation);
|
|
64
|
+
}
|
|
65
|
+
/** Every declared setting, in declaration order. */
|
|
66
|
+
entries() {
|
|
67
|
+
return [...this.slots.values()].map((slot) => slot.entry);
|
|
68
|
+
}
|
|
69
|
+
has(key) {
|
|
70
|
+
return this.slots.has(key);
|
|
71
|
+
}
|
|
72
|
+
definition(key) {
|
|
73
|
+
return this.slot(key).entry;
|
|
74
|
+
}
|
|
75
|
+
get isActive() {
|
|
76
|
+
return this.active;
|
|
77
|
+
}
|
|
78
|
+
get currentIdentity() {
|
|
79
|
+
return this.identity;
|
|
80
|
+
}
|
|
81
|
+
/** The storage context of one key under the current identity. */
|
|
82
|
+
context(key) {
|
|
83
|
+
const { scope } = this.slot(key).entry.spec;
|
|
84
|
+
return Object.freeze({
|
|
85
|
+
scope,
|
|
86
|
+
userId: this.identity.userId,
|
|
87
|
+
organizationId: this.identity.organizationId,
|
|
88
|
+
});
|
|
89
|
+
}
|
|
90
|
+
state(key) {
|
|
91
|
+
return this.slot(key).state;
|
|
92
|
+
}
|
|
93
|
+
/** The state before anything loaded; stable per key, for server snapshots. */
|
|
94
|
+
initialState(key) {
|
|
95
|
+
return this.slot(key).initial;
|
|
96
|
+
}
|
|
97
|
+
get(key) {
|
|
98
|
+
return this.state(key).value;
|
|
99
|
+
}
|
|
100
|
+
/** Validates a value against the declaration without storing it. */
|
|
101
|
+
parse(key, value) {
|
|
102
|
+
const { spec } = this.slot(key).entry;
|
|
103
|
+
return parseSetting(spec, value, key);
|
|
104
|
+
}
|
|
105
|
+
subscribe(keyOrListener, maybe) {
|
|
106
|
+
if (typeof keyOrListener === 'function') {
|
|
107
|
+
this.listeners.add(keyOrListener);
|
|
108
|
+
return () => {
|
|
109
|
+
this.listeners.delete(keyOrListener);
|
|
110
|
+
};
|
|
111
|
+
}
|
|
112
|
+
const listener = maybe;
|
|
113
|
+
const slot = this.slot(keyOrListener);
|
|
114
|
+
slot.listeners.add(listener);
|
|
115
|
+
return () => {
|
|
116
|
+
slot.listeners.delete(listener);
|
|
117
|
+
};
|
|
118
|
+
}
|
|
119
|
+
/** Loads every value for an identity. Queued writes of the previous identity resolve "cancelled". */
|
|
120
|
+
async activate(identity = {}) {
|
|
121
|
+
this.active = true;
|
|
122
|
+
this.identity = Object.freeze({
|
|
123
|
+
userId: identity.userId,
|
|
124
|
+
organizationId: identity.organizationId,
|
|
125
|
+
});
|
|
126
|
+
const generation = ++this.generation;
|
|
127
|
+
const slots = [...this.slots.values()];
|
|
128
|
+
for (const slot of slots) {
|
|
129
|
+
this.cancel(slot);
|
|
130
|
+
this.publish(slot, slot.initial);
|
|
131
|
+
}
|
|
132
|
+
await this.loadAll(slots, generation);
|
|
133
|
+
}
|
|
134
|
+
/** Keeps the last values but marks nothing ready or writable until the next activation. */
|
|
135
|
+
deactivate() {
|
|
136
|
+
this.active = false;
|
|
137
|
+
++this.generation;
|
|
138
|
+
for (const slot of this.slots.values()) {
|
|
139
|
+
this.cancel(slot);
|
|
140
|
+
this.publish(slot, {
|
|
141
|
+
value: slot.state.value,
|
|
142
|
+
ready: false,
|
|
143
|
+
writable: false,
|
|
144
|
+
pending: false,
|
|
145
|
+
});
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
/** Reloads one key, or every key, for the current identity. */
|
|
149
|
+
async refresh(key) {
|
|
150
|
+
if (!this.active)
|
|
151
|
+
return;
|
|
152
|
+
const slots = key ? [this.slot(key)] : [...this.slots.values()];
|
|
153
|
+
await this.loadAll(slots.filter((slot) => !slot.state.pending), this.generation);
|
|
154
|
+
}
|
|
155
|
+
/** Validates and queues a write; rejects only on validation or this value's own storage failure. */
|
|
156
|
+
set(key, value) {
|
|
157
|
+
try {
|
|
158
|
+
const slot = this.writable(key);
|
|
159
|
+
return this.enqueue(slot, { kind: 'save', value: this.parse(key, value) });
|
|
160
|
+
}
|
|
161
|
+
catch (error) {
|
|
162
|
+
return Promise.reject(error);
|
|
163
|
+
}
|
|
164
|
+
}
|
|
165
|
+
/** Removes the stored value (`storage.reset`) or, without it, saves the default. */
|
|
166
|
+
reset(key) {
|
|
167
|
+
try {
|
|
168
|
+
return this.enqueue(this.writable(key), { kind: 'reset' });
|
|
169
|
+
}
|
|
170
|
+
catch (error) {
|
|
171
|
+
return Promise.reject(error);
|
|
172
|
+
}
|
|
173
|
+
}
|
|
174
|
+
slot(key) {
|
|
175
|
+
const slot = this.slots.get(key);
|
|
176
|
+
if (!slot) {
|
|
177
|
+
const plugin = key.includes('.') ? `plugin "${key.slice(0, key.indexOf('.'))}"` : 'the app';
|
|
178
|
+
throw new Error(`Unknown setting "${key}". Declare it in settings.ts of ${plugin}.`);
|
|
179
|
+
}
|
|
180
|
+
return slot;
|
|
181
|
+
}
|
|
182
|
+
writable(key) {
|
|
183
|
+
const slot = this.slot(key);
|
|
184
|
+
if (!this.active || !slot.state.ready)
|
|
185
|
+
throw new Error(`Setting "${key}" is not loaded yet.`);
|
|
186
|
+
if (!slot.state.writable)
|
|
187
|
+
throw new Error(`Setting "${key}" is read-only.`);
|
|
188
|
+
return slot;
|
|
189
|
+
}
|
|
190
|
+
publish(slot, state) {
|
|
191
|
+
slot.state = Object.freeze({ ...state });
|
|
192
|
+
for (const listener of slot.listeners)
|
|
193
|
+
listener();
|
|
194
|
+
for (const listener of this.listeners)
|
|
195
|
+
listener();
|
|
196
|
+
}
|
|
197
|
+
cancel(slot) {
|
|
198
|
+
const queued = slot.queued;
|
|
199
|
+
slot.queued = undefined;
|
|
200
|
+
queued?.waiters.forEach((waiter) => waiter.resolve('cancelled'));
|
|
201
|
+
slot.superseded.splice(0).forEach((waiter) => waiter.resolve('superseded'));
|
|
202
|
+
}
|
|
203
|
+
async loadAll(slots, generation) {
|
|
204
|
+
if (!slots.length)
|
|
205
|
+
return;
|
|
206
|
+
let storage;
|
|
207
|
+
try {
|
|
208
|
+
storage = this.storage();
|
|
209
|
+
}
|
|
210
|
+
catch (error) {
|
|
211
|
+
if (generation !== this.generation)
|
|
212
|
+
return;
|
|
213
|
+
for (const slot of slots)
|
|
214
|
+
this.publish(slot, { ...slot.initial, error: message(error, 'Loading failed.') });
|
|
215
|
+
return;
|
|
216
|
+
}
|
|
217
|
+
const requests = slots.map((slot) => ({
|
|
218
|
+
key: slot.entry.key,
|
|
219
|
+
context: this.context(slot.entry.key),
|
|
220
|
+
}));
|
|
221
|
+
const loadMany = storage.loadMany;
|
|
222
|
+
if (!loadMany) {
|
|
223
|
+
await Promise.all(slots.map((slot) => this.load(slot, generation, storage)));
|
|
224
|
+
return;
|
|
225
|
+
}
|
|
226
|
+
const batch = attempt(() => loadMany.call(storage, requests));
|
|
227
|
+
await Promise.all(slots.map((slot, index) => this.load(slot, generation, storage, batch.then((results) => Object.hasOwn(results, slot.entry.key)
|
|
228
|
+
? results[slot.entry.key]
|
|
229
|
+
: storage.load(slot.entry.key, requests[index].context)))));
|
|
230
|
+
}
|
|
231
|
+
async load(slot, generation, storage, request) {
|
|
232
|
+
const token = ++slot.loadToken;
|
|
233
|
+
const fresh = () => generation === this.generation &&
|
|
234
|
+
slot.loadToken === token &&
|
|
235
|
+
this.slots.get(slot.entry.key) === slot;
|
|
236
|
+
const { key, spec } = slot.entry;
|
|
237
|
+
try {
|
|
238
|
+
const stored = await (request ?? attempt(() => storage.load(key, this.context(key))));
|
|
239
|
+
if (!fresh())
|
|
240
|
+
return;
|
|
241
|
+
let value = spec.default;
|
|
242
|
+
let error;
|
|
243
|
+
try {
|
|
244
|
+
value = stored.value === undefined ? spec.default : parseSetting(spec, stored.value, key);
|
|
245
|
+
}
|
|
246
|
+
catch (failure) {
|
|
247
|
+
error = message(failure, 'The stored value is invalid.');
|
|
248
|
+
}
|
|
249
|
+
this.publish(slot, { value, ready: true, writable: stored.writable, pending: false, error });
|
|
250
|
+
}
|
|
251
|
+
catch (failure) {
|
|
252
|
+
if (!fresh())
|
|
253
|
+
return;
|
|
254
|
+
this.publish(slot, { ...slot.initial, error: message(failure, 'Loading failed.') });
|
|
255
|
+
}
|
|
256
|
+
}
|
|
257
|
+
enqueue(slot, write) {
|
|
258
|
+
return new Promise((resolve, reject) => {
|
|
259
|
+
if (slot.queued)
|
|
260
|
+
slot.superseded.push(...slot.queued.waiters);
|
|
261
|
+
slot.queued = { write, waiters: [{ resolve, reject }] };
|
|
262
|
+
this.publish(slot, { ...slot.state, pending: true, error: undefined });
|
|
263
|
+
if (!slot.flying)
|
|
264
|
+
void this.drain(slot, this.generation);
|
|
265
|
+
});
|
|
266
|
+
}
|
|
267
|
+
async drain(slot, generation) {
|
|
268
|
+
slot.flying = true;
|
|
269
|
+
const { key, spec } = slot.entry;
|
|
270
|
+
while (slot.queued && generation === this.generation) {
|
|
271
|
+
const { write, waiters } = slot.queued;
|
|
272
|
+
slot.queued = undefined;
|
|
273
|
+
// A load that is still in flight must not overwrite the value this write confirms.
|
|
274
|
+
slot.loadToken++;
|
|
275
|
+
const context = this.context(key);
|
|
276
|
+
const { writable } = slot.state;
|
|
277
|
+
let stored;
|
|
278
|
+
let failure;
|
|
279
|
+
try {
|
|
280
|
+
const storage = this.storage();
|
|
281
|
+
stored =
|
|
282
|
+
write.kind === 'save'
|
|
283
|
+
? await attempt(() => storage.save(key, write.value, context)).then(() => ({
|
|
284
|
+
value: write.value,
|
|
285
|
+
writable,
|
|
286
|
+
}))
|
|
287
|
+
: storage.reset
|
|
288
|
+
? await attempt(() => storage.reset(key, context))
|
|
289
|
+
: await attempt(() => storage.save(key, spec.default, context)).then(() => ({
|
|
290
|
+
value: spec.default,
|
|
291
|
+
writable,
|
|
292
|
+
}));
|
|
293
|
+
}
|
|
294
|
+
catch (error) {
|
|
295
|
+
failure = { error };
|
|
296
|
+
}
|
|
297
|
+
if (generation !== this.generation || this.slots.get(key) !== slot) {
|
|
298
|
+
waiters.forEach((waiter) => failure ? waiter.reject(failure.error) : waiter.resolve('cancelled'));
|
|
299
|
+
break;
|
|
300
|
+
}
|
|
301
|
+
if (failure) {
|
|
302
|
+
this.publish(slot, {
|
|
303
|
+
...slot.state,
|
|
304
|
+
pending: !!slot.queued,
|
|
305
|
+
error: message(failure.error, 'Saving failed.'),
|
|
306
|
+
});
|
|
307
|
+
const { error } = failure;
|
|
308
|
+
waiters.forEach((waiter) => waiter.reject(error));
|
|
309
|
+
continue;
|
|
310
|
+
}
|
|
311
|
+
let value = slot.state.value;
|
|
312
|
+
try {
|
|
313
|
+
value = stored.value === undefined ? spec.default : parseSetting(spec, stored.value, key);
|
|
314
|
+
}
|
|
315
|
+
catch (error) {
|
|
316
|
+
failure = { error };
|
|
317
|
+
}
|
|
318
|
+
if (failure) {
|
|
319
|
+
this.publish(slot, {
|
|
320
|
+
...slot.state,
|
|
321
|
+
pending: !!slot.queued,
|
|
322
|
+
error: message(failure.error, 'The stored value is invalid.'),
|
|
323
|
+
});
|
|
324
|
+
const { error } = failure;
|
|
325
|
+
waiters.forEach((waiter) => waiter.reject(error));
|
|
326
|
+
continue;
|
|
327
|
+
}
|
|
328
|
+
this.publish(slot, {
|
|
329
|
+
value,
|
|
330
|
+
ready: true,
|
|
331
|
+
writable: stored.writable,
|
|
332
|
+
pending: !!slot.queued,
|
|
333
|
+
error: undefined,
|
|
334
|
+
});
|
|
335
|
+
waiters.forEach((waiter) => waiter.resolve('saved'));
|
|
336
|
+
}
|
|
337
|
+
slot.flying = false;
|
|
338
|
+
// Activation may queue a new identity's write while this generation is still saving.
|
|
339
|
+
// Its enqueue could not start a drain until the old storage call released the slot.
|
|
340
|
+
if (slot.queued)
|
|
341
|
+
void this.drain(slot, this.generation);
|
|
342
|
+
else
|
|
343
|
+
slot.superseded.splice(0).forEach((waiter) => waiter.resolve('superseded'));
|
|
344
|
+
}
|
|
345
|
+
}
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
import type { SlotMap } from '../presentation.js';
|
|
2
|
+
import type { SlotPayload } from './define.js';
|
|
3
|
+
import type { SlotAvailability } from './types.js';
|
|
4
|
+
type Names = Extract<keyof SlotMap, string>;
|
|
5
|
+
type ActionNames = {
|
|
6
|
+
[N in Names]: SlotMap[N] extends {
|
|
7
|
+
accepts: 'actions';
|
|
8
|
+
} ? N : never;
|
|
9
|
+
}[Names];
|
|
10
|
+
type Key<Name extends string> = Name extends Names ? SlotMap[Name] extends {
|
|
11
|
+
policy: 'keyed';
|
|
12
|
+
} ? {
|
|
13
|
+
key: string;
|
|
14
|
+
} : {
|
|
15
|
+
key?: string;
|
|
16
|
+
} : {
|
|
17
|
+
key?: string;
|
|
18
|
+
};
|
|
19
|
+
type PlainNames = {
|
|
20
|
+
[N in ActionNames]: SlotMap[N] extends {
|
|
21
|
+
policy: 'keyed';
|
|
22
|
+
} ? never : N;
|
|
23
|
+
}[ActionNames];
|
|
24
|
+
type Placement<Name extends string, Input> = {
|
|
25
|
+
slot: Name;
|
|
26
|
+
/** Evaluated for each outlet occurrence, never at Action registration. */
|
|
27
|
+
input?: (context: {
|
|
28
|
+
payload: Name extends Names ? SlotPayload<Name> : unknown;
|
|
29
|
+
}) => Input;
|
|
30
|
+
order?: number;
|
|
31
|
+
availability?: SlotAvailability;
|
|
32
|
+
} & Key<Name>;
|
|
33
|
+
/** Generated SlotMap checks names and contextual payloads. Manual apps may augment it too. */
|
|
34
|
+
export type ActionSlotPlacement<Input = unknown> = [Names] extends [never] ? string | Placement<string, Input> : PlainNames | {
|
|
35
|
+
[N in ActionNames]: Placement<N, Input>;
|
|
36
|
+
}[ActionNames];
|
|
37
|
+
/** Runtime implementation erases consumer-generated names after public authoring checks. */
|
|
38
|
+
export type RuntimeActionPlacement = string | {
|
|
39
|
+
slot: string;
|
|
40
|
+
input?: (context: {
|
|
41
|
+
payload: any;
|
|
42
|
+
}) => unknown;
|
|
43
|
+
order?: number;
|
|
44
|
+
key?: string;
|
|
45
|
+
availability?: SlotAvailability;
|
|
46
|
+
};
|
|
47
|
+
export {};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
import type { InputSchema, SchemaOutput, EffectiveActionId } from '../definitions.js';
|
|
2
|
+
import type { SlotMap } from '../presentation.js';
|
|
3
|
+
export type SlotPolicy = 'list' | 'single' | 'keyed';
|
|
4
|
+
/** Payload is supplied by the owner; schema describes contributed data, not UI. */
|
|
5
|
+
export type SlotOptions = {
|
|
6
|
+
id?: string;
|
|
7
|
+
policy?: SlotPolicy;
|
|
8
|
+
payload?: InputSchema<any>;
|
|
9
|
+
} & ({
|
|
10
|
+
accepts: 'actions' | 'component';
|
|
11
|
+
schema?: never;
|
|
12
|
+
} | {
|
|
13
|
+
accepts: 'data';
|
|
14
|
+
schema: InputSchema<any>;
|
|
15
|
+
});
|
|
16
|
+
export type SlotDefinition = Readonly<SlotOptions & {
|
|
17
|
+
kind: 'slot';
|
|
18
|
+
policy: SlotPolicy;
|
|
19
|
+
/** Duplicate declarations, single occupants and duplicate keys never silently replace. */
|
|
20
|
+
conflict: 'error';
|
|
21
|
+
}>;
|
|
22
|
+
export type SlotDefinitions = Readonly<{
|
|
23
|
+
[name: string]: SlotDefinition | SlotDefinitions;
|
|
24
|
+
}>;
|
|
25
|
+
export type ResolvedSlotDefinition = SlotDefinition & {
|
|
26
|
+
readonly id: string;
|
|
27
|
+
};
|
|
28
|
+
export type OwnedSlotDefinition = ResolvedSlotDefinition & {
|
|
29
|
+
readonly plugin: string;
|
|
30
|
+
};
|
|
31
|
+
/** Declares a headless extension point. Attachment and rendering are separate operations. */
|
|
32
|
+
export declare function defineSlot<const T extends SlotOptions>(options: T): Readonly<T & {
|
|
33
|
+
kind: 'slot';
|
|
34
|
+
policy: T extends {
|
|
35
|
+
policy: infer P;
|
|
36
|
+
} ? P : 'list';
|
|
37
|
+
conflict: 'error';
|
|
38
|
+
}>;
|
|
39
|
+
export declare function isSlotDefinition(value: unknown): value is SlotDefinition;
|
|
40
|
+
/** Accept a generated name or a definition directly (manual composition needs no augmentation). */
|
|
41
|
+
type DefinitionOf<T> = T extends keyof SlotMap ? SlotMap[T] : T;
|
|
42
|
+
export type SlotPayload<T> = DefinitionOf<T> extends {
|
|
43
|
+
payload: infer S;
|
|
44
|
+
} ? SchemaOutput<S> : undefined;
|
|
45
|
+
export type SlotData<T> = DefinitionOf<T> extends {
|
|
46
|
+
accepts: 'data';
|
|
47
|
+
schema: infer S;
|
|
48
|
+
} ? SchemaOutput<S> : never;
|
|
49
|
+
export type SlotEntry<T, Path extends string> = T extends SlotDefinition ? {
|
|
50
|
+
readonly [K in EffectiveActionId<T, Path>]: T;
|
|
51
|
+
} : {};
|
|
52
|
+
export {};
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/** Declares a headless extension point. Attachment and rendering are separate operations. */
|
|
2
|
+
export function defineSlot(options) {
|
|
3
|
+
return Object.freeze({
|
|
4
|
+
...options,
|
|
5
|
+
kind: 'slot',
|
|
6
|
+
policy: options.policy ?? 'list',
|
|
7
|
+
conflict: 'error',
|
|
8
|
+
});
|
|
9
|
+
}
|
|
10
|
+
export function isSlotDefinition(value) {
|
|
11
|
+
return !!value && typeof value === 'object' && value.kind === 'slot';
|
|
12
|
+
}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
import type { Plugin } from '../definitions.js';
|
|
2
|
+
import type { OwnedSlotDefinition } from './define.js';
|
|
3
|
+
/** Composition and Discovery converge here; there is no mutable declaration registry. */
|
|
4
|
+
export declare function normalizeSlots(module: Plugin, appId: string): readonly OwnedSlotDefinition[];
|
|
5
|
+
export declare function validateSlotDeclarations(modules: readonly {
|
|
6
|
+
slots: readonly OwnedSlotDefinition[];
|
|
7
|
+
}[], appId: string): void;
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import { contributionSource, preserveContributionPath } from '../contribution-origin.js';
|
|
2
|
+
import { discoveredFile, discoverSlots } from '../discovered.js';
|
|
3
|
+
import { BitaKitStartupError } from '../startup-error.js';
|
|
4
|
+
/** Composition and Discovery converge here; there is no mutable declaration registry. */
|
|
5
|
+
export function normalizeSlots(module, appId) {
|
|
6
|
+
const source = `slots of ${module.id}`;
|
|
7
|
+
const files = Array.isArray(module.slots)
|
|
8
|
+
? module.slots.map((slot, index) => {
|
|
9
|
+
if (!slot.id)
|
|
10
|
+
throw new BitaKitStartupError('A slot in an array needs an id. Prefer a named record.', module.id, { app: module.id === appId });
|
|
11
|
+
return discoveredFile(slot, String(index), contributionSource(slot) ?? source);
|
|
12
|
+
})
|
|
13
|
+
: [discoveredFile(module.slots ?? {}, '', source)];
|
|
14
|
+
try {
|
|
15
|
+
return Object.freeze(discoverSlots(files, module.id === appId ? '' : module.id).map((slot) => preserveContributionPath(slot, Object.freeze({ ...slot, plugin: module.id }))));
|
|
16
|
+
}
|
|
17
|
+
catch (error) {
|
|
18
|
+
if (error instanceof BitaKitStartupError)
|
|
19
|
+
throw new BitaKitStartupError(error.message, module.id, {
|
|
20
|
+
cause: error,
|
|
21
|
+
source: error.source,
|
|
22
|
+
app: module.id === appId,
|
|
23
|
+
});
|
|
24
|
+
throw error;
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
export function validateSlotDeclarations(modules, appId) {
|
|
28
|
+
const seen = new Map();
|
|
29
|
+
for (const module of modules)
|
|
30
|
+
for (const slot of module.slots) {
|
|
31
|
+
const previous = seen.get(slot.id);
|
|
32
|
+
if (previous)
|
|
33
|
+
throw new BitaKitStartupError(`Duplicate slot "${slot.id}": ${contributionSource(previous) ?? previous.plugin} and ${contributionSource(slot) ?? slot.plugin}.`, slot.plugin, { source: contributionSource(slot), app: slot.plugin === appId });
|
|
34
|
+
seen.set(slot.id, slot);
|
|
35
|
+
}
|
|
36
|
+
}
|