@bitakit/core 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +382 -0
- package/discovery/entries.mjs +124 -0
- package/discovery/generate.mjs +327 -0
- package/discovery/host.mjs +12 -0
- package/discovery/index.d.ts +41 -0
- package/discovery/index.mjs +4 -0
- package/discovery/modules.mjs +13 -0
- package/discovery/packages.mjs +57 -0
- package/discovery/watch.mjs +23 -0
- package/dist/actions/action-list.d.ts +69 -0
- package/dist/actions/action-list.js +247 -0
- package/dist/actions/action.d.ts +96 -0
- package/dist/actions/action.js +145 -0
- package/dist/actions/base/url-action.d.ts +8 -0
- package/dist/actions/base/url-action.js +15 -0
- package/dist/actions/core.d.ts +14 -0
- package/dist/actions/core.js +8 -0
- package/dist/actions/dependencies.d.ts +8 -0
- package/dist/actions/dependencies.js +34 -0
- package/dist/actions/execution.d.ts +4 -0
- package/dist/actions/execution.js +64 -0
- package/dist/actions/feedback.d.ts +17 -0
- package/dist/actions/feedback.js +21 -0
- package/dist/actions/groups.d.ts +13 -0
- package/dist/actions/groups.js +21 -0
- package/dist/actions/instance-bindings.d.ts +16 -0
- package/dist/actions/instance-bindings.js +93 -0
- package/dist/actions/interceptors.d.ts +24 -0
- package/dist/actions/interceptors.js +42 -0
- package/dist/actions/navigation.d.ts +12 -0
- package/dist/actions/navigation.js +42 -0
- package/dist/actions/reference.d.ts +17 -0
- package/dist/actions/reference.js +39 -0
- package/dist/actions/state.d.ts +11 -0
- package/dist/actions/state.js +8 -0
- package/dist/actions/types.d.ts +99 -0
- package/dist/actions/types.js +1 -0
- package/dist/app/access.d.ts +4 -0
- package/dist/app/access.js +85 -0
- package/dist/app/action-access.d.ts +4 -0
- package/dist/app/action-access.js +20 -0
- package/dist/app/service-error.d.ts +8 -0
- package/dist/app/service-error.js +19 -0
- package/dist/app/types.d.ts +47 -0
- package/dist/app/types.js +1 -0
- package/dist/config-service.d.ts +49 -0
- package/dist/config-service.js +83 -0
- package/dist/configuration.d.ts +4 -0
- package/dist/configuration.js +42 -0
- package/dist/confirmation.d.ts +14 -0
- package/dist/confirmation.js +26 -0
- package/dist/contracts.d.ts +27 -0
- package/dist/contracts.js +3 -0
- package/dist/contribution-origin.d.ts +3 -0
- package/dist/contribution-origin.js +13 -0
- package/dist/contributions/command.d.ts +8 -0
- package/dist/contributions/command.js +50 -0
- package/dist/contributions/dialog.d.ts +8 -0
- package/dist/contributions/dialog.js +18 -0
- package/dist/contributions/form.d.ts +10 -0
- package/dist/contributions/form.js +67 -0
- package/dist/contributions/host.d.ts +40 -0
- package/dist/contributions/host.js +1 -0
- package/dist/contributions/index.d.ts +26 -0
- package/dist/contributions/index.js +18 -0
- package/dist/contributions/native.d.ts +11 -0
- package/dist/contributions/native.js +87 -0
- package/dist/contributions/shared.d.ts +19 -0
- package/dist/contributions/shared.js +48 -0
- package/dist/contributions/stateful-action.d.ts +29 -0
- package/dist/contributions/stateful-action.js +33 -0
- package/dist/conventions.d.ts +4 -0
- package/dist/conventions.js +38 -0
- package/dist/core.d.ts +21 -0
- package/dist/core.js +18 -0
- package/dist/definitions.d.ts +356 -0
- package/dist/definitions.js +60 -0
- package/dist/discovered.d.ts +49 -0
- package/dist/discovered.js +120 -0
- package/dist/interceptors/service-observers.d.ts +3 -0
- package/dist/interceptors/service-observers.js +80 -0
- package/dist/interceptors/service.d.ts +37 -0
- package/dist/interceptors/service.js +7 -0
- package/dist/messages.d.ts +9 -0
- package/dist/messages.js +21 -0
- package/dist/metadata.d.ts +3 -0
- package/dist/metadata.js +13 -0
- package/dist/pages.d.ts +8 -0
- package/dist/pages.js +22 -0
- package/dist/presentation.d.ts +4 -0
- package/dist/presentation.js +1 -0
- package/dist/replacements.d.ts +22 -0
- package/dist/replacements.js +54 -0
- package/dist/runtime.d.ts +88 -0
- package/dist/runtime.js +445 -0
- package/dist/scope.d.ts +34 -0
- package/dist/scope.js +78 -0
- package/dist/service-key.d.ts +13 -0
- package/dist/service-key.js +14 -0
- package/dist/services.d.ts +6 -0
- package/dist/services.js +53 -0
- package/dist/translation.d.ts +13 -0
- package/dist/translation.js +43 -0
- package/dist/validation.d.ts +2 -0
- package/dist/validation.js +16 -0
- package/docs/file-contributions.md +161 -0
- package/package.json +48 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
/** Feedback callbacks cannot turn a successful operation into a failed operation. */
|
|
2
|
+
export function evaluateFeedback(feedback, context) {
|
|
3
|
+
try {
|
|
4
|
+
const result = typeof feedback === 'function' ? feedback(context) : feedback;
|
|
5
|
+
if (result === false)
|
|
6
|
+
return false;
|
|
7
|
+
return typeof result === 'string' ? { message: result } : (result ?? {});
|
|
8
|
+
}
|
|
9
|
+
catch {
|
|
10
|
+
return {};
|
|
11
|
+
}
|
|
12
|
+
}
|
|
13
|
+
/** Carries only the selected display message; the original error remains in cause. */
|
|
14
|
+
export class ActionFailure extends Error {
|
|
15
|
+
feedback;
|
|
16
|
+
constructor(feedback, cause) {
|
|
17
|
+
super(feedback || 'Action failed.', { cause });
|
|
18
|
+
this.feedback = feedback;
|
|
19
|
+
this.name = 'ActionFailure';
|
|
20
|
+
}
|
|
21
|
+
}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
/** A typed extension point. The same group can be rendered in different places. */
|
|
2
|
+
export declare class ActionGroup<Input = unknown> {
|
|
3
|
+
readonly id: string;
|
|
4
|
+
readonly title?: string | undefined;
|
|
5
|
+
readonly inputType: Input;
|
|
6
|
+
constructor(id: string, title?: string | undefined);
|
|
7
|
+
}
|
|
8
|
+
export type RegistrationOptions = {
|
|
9
|
+
groups?: readonly ActionGroup<any>[];
|
|
10
|
+
order?: number;
|
|
11
|
+
dividerBefore?: boolean;
|
|
12
|
+
};
|
|
13
|
+
export declare function freezeGroups(groups?: readonly ActionGroup<any>[]): readonly ActionGroup<any>[];
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
/** A typed extension point. The same group can be rendered in different places. */
|
|
2
|
+
export class ActionGroup {
|
|
3
|
+
id;
|
|
4
|
+
title;
|
|
5
|
+
constructor(id, title) {
|
|
6
|
+
this.id = id;
|
|
7
|
+
this.title = title;
|
|
8
|
+
if (!/^[a-zA-Z0-9][a-zA-Z0-9._:/-]*$/.test(id))
|
|
9
|
+
throw new Error('Invalid action group ID.');
|
|
10
|
+
Object.freeze(this);
|
|
11
|
+
}
|
|
12
|
+
}
|
|
13
|
+
export function freezeGroups(groups = []) {
|
|
14
|
+
const ids = new Set();
|
|
15
|
+
for (const group of groups) {
|
|
16
|
+
if (!(group instanceof ActionGroup) || ids.has(group.id))
|
|
17
|
+
throw new Error('Invalid or duplicate action group.');
|
|
18
|
+
ids.add(group.id);
|
|
19
|
+
}
|
|
20
|
+
return Object.freeze([...groups]);
|
|
21
|
+
}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import { Action } from './action.js';
|
|
2
|
+
import type { ActionPatch, ActionRegistration } from './types.js';
|
|
3
|
+
/** Owns subscriptions to class instances and external services. */
|
|
4
|
+
export declare class InstanceBindings {
|
|
5
|
+
private environment;
|
|
6
|
+
private entries;
|
|
7
|
+
private mounted;
|
|
8
|
+
private synchronizing;
|
|
9
|
+
private navigate?;
|
|
10
|
+
constructor(environment: unknown);
|
|
11
|
+
attach(id: string, action: Action<any, any>, registration: ActionRegistration): () => void;
|
|
12
|
+
apply(id: string, patch: ActionPatch): void;
|
|
13
|
+
private connect;
|
|
14
|
+
mount(navigate?: (href: string) => void): () => void;
|
|
15
|
+
dispose(): void;
|
|
16
|
+
}
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
import { Action } from './action.js';
|
|
2
|
+
import { NavigationHost } from './navigation.js';
|
|
3
|
+
/** Owns subscriptions to class instances and external services. */
|
|
4
|
+
export class InstanceBindings {
|
|
5
|
+
environment;
|
|
6
|
+
entries = new Map();
|
|
7
|
+
mounted = false;
|
|
8
|
+
synchronizing = false;
|
|
9
|
+
navigate;
|
|
10
|
+
constructor(environment) {
|
|
11
|
+
this.environment = environment;
|
|
12
|
+
}
|
|
13
|
+
attach(id, action, registration) {
|
|
14
|
+
{
|
|
15
|
+
const host = this.environment;
|
|
16
|
+
if (host instanceof NavigationHost)
|
|
17
|
+
action.bindNavigation((href) => host.go(href));
|
|
18
|
+
}
|
|
19
|
+
const entry = {
|
|
20
|
+
action,
|
|
21
|
+
unsubscribe: action.subscribe(() => {
|
|
22
|
+
if (!this.synchronizing)
|
|
23
|
+
registration.update(action.snapshot());
|
|
24
|
+
}),
|
|
25
|
+
};
|
|
26
|
+
this.entries.set(id, entry);
|
|
27
|
+
try {
|
|
28
|
+
if (this.mounted)
|
|
29
|
+
this.connect(entry);
|
|
30
|
+
}
|
|
31
|
+
catch (error) {
|
|
32
|
+
entry.unsubscribe();
|
|
33
|
+
this.entries.delete(id);
|
|
34
|
+
registration.unregister();
|
|
35
|
+
throw error;
|
|
36
|
+
}
|
|
37
|
+
return () => {
|
|
38
|
+
if (this.entries.get(id) !== entry)
|
|
39
|
+
return;
|
|
40
|
+
entry.disconnect?.();
|
|
41
|
+
entry.unsubscribe();
|
|
42
|
+
this.entries.delete(id);
|
|
43
|
+
registration.unregister();
|
|
44
|
+
};
|
|
45
|
+
}
|
|
46
|
+
apply(id, patch) {
|
|
47
|
+
const entry = this.entries.get(id);
|
|
48
|
+
if (!entry || this.synchronizing)
|
|
49
|
+
return;
|
|
50
|
+
this.synchronizing = true;
|
|
51
|
+
try {
|
|
52
|
+
Object.assign(entry.action, patch);
|
|
53
|
+
}
|
|
54
|
+
finally {
|
|
55
|
+
this.synchronizing = false;
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
connect(entry) {
|
|
59
|
+
if (this.navigate)
|
|
60
|
+
entry.action.bindNavigation(this.navigate);
|
|
61
|
+
entry.disconnect = entry.action.connect() || undefined;
|
|
62
|
+
}
|
|
63
|
+
mount(navigate) {
|
|
64
|
+
this.mounted = true;
|
|
65
|
+
this.navigate = navigate;
|
|
66
|
+
const unbind = this.environment instanceof NavigationHost && navigate
|
|
67
|
+
? this.environment.bind(navigate)
|
|
68
|
+
: undefined;
|
|
69
|
+
const cleanup = () => {
|
|
70
|
+
this.mounted = false;
|
|
71
|
+
unbind?.();
|
|
72
|
+
this.entries.forEach((entry) => {
|
|
73
|
+
entry.disconnect?.();
|
|
74
|
+
entry.disconnect = undefined;
|
|
75
|
+
});
|
|
76
|
+
};
|
|
77
|
+
try {
|
|
78
|
+
this.entries.forEach((entry) => this.connect(entry));
|
|
79
|
+
}
|
|
80
|
+
catch (error) {
|
|
81
|
+
cleanup();
|
|
82
|
+
throw error;
|
|
83
|
+
}
|
|
84
|
+
return cleanup;
|
|
85
|
+
}
|
|
86
|
+
dispose() {
|
|
87
|
+
this.entries.forEach((entry) => {
|
|
88
|
+
entry.disconnect?.();
|
|
89
|
+
entry.unsubscribe();
|
|
90
|
+
});
|
|
91
|
+
this.entries.clear();
|
|
92
|
+
}
|
|
93
|
+
}
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import type { ActionContext, ExecutionResult } from './types.js';
|
|
2
|
+
export type ActionInterceptor = {
|
|
3
|
+
/** Returning false cancels execution. Errors also prevent the handler from running. */
|
|
4
|
+
before(context: ActionContext): boolean | void | Promise<boolean | void>;
|
|
5
|
+
};
|
|
6
|
+
export type ExecutionEvent = Readonly<{
|
|
7
|
+
id: string;
|
|
8
|
+
phase: 'started' | 'completed' | 'skipped' | 'failed';
|
|
9
|
+
timestamp: number;
|
|
10
|
+
context: ActionContext;
|
|
11
|
+
result?: ExecutionResult;
|
|
12
|
+
error?: unknown;
|
|
13
|
+
}>;
|
|
14
|
+
/** Interceptors gate commands; observers cannot change their outcome. */
|
|
15
|
+
export declare class ExecutionLifecycle {
|
|
16
|
+
private interceptors;
|
|
17
|
+
private observers;
|
|
18
|
+
use(interceptor: ActionInterceptor): () => void;
|
|
19
|
+
subscribe(listener: (event: ExecutionEvent) => void): () => void;
|
|
20
|
+
allow(context: ActionContext): Promise<boolean>;
|
|
21
|
+
get hasInterceptors(): boolean;
|
|
22
|
+
emit(event: Omit<ExecutionEvent, 'timestamp'>): void;
|
|
23
|
+
clear(): void;
|
|
24
|
+
}
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
/** Interceptors gate commands; observers cannot change their outcome. */
|
|
2
|
+
export class ExecutionLifecycle {
|
|
3
|
+
interceptors = new Set();
|
|
4
|
+
observers = new Set();
|
|
5
|
+
use(interceptor) {
|
|
6
|
+
this.interceptors.add(interceptor);
|
|
7
|
+
return () => {
|
|
8
|
+
this.interceptors.delete(interceptor);
|
|
9
|
+
};
|
|
10
|
+
}
|
|
11
|
+
subscribe(listener) {
|
|
12
|
+
this.observers.add(listener);
|
|
13
|
+
return () => {
|
|
14
|
+
this.observers.delete(listener);
|
|
15
|
+
};
|
|
16
|
+
}
|
|
17
|
+
async allow(context) {
|
|
18
|
+
for (const interceptor of [...this.interceptors]) {
|
|
19
|
+
if ((await interceptor.before(context)) === false)
|
|
20
|
+
return false;
|
|
21
|
+
}
|
|
22
|
+
return true;
|
|
23
|
+
}
|
|
24
|
+
get hasInterceptors() {
|
|
25
|
+
return this.interceptors.size > 0;
|
|
26
|
+
}
|
|
27
|
+
emit(event) {
|
|
28
|
+
const snapshot = Object.freeze({ ...event, timestamp: Date.now() });
|
|
29
|
+
for (const listener of this.observers) {
|
|
30
|
+
try {
|
|
31
|
+
listener(snapshot);
|
|
32
|
+
}
|
|
33
|
+
catch {
|
|
34
|
+
/* Diagnostics must not fail a successful mutation. */
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
clear() {
|
|
39
|
+
this.interceptors.clear();
|
|
40
|
+
this.observers.clear();
|
|
41
|
+
}
|
|
42
|
+
}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import type { ActionContext } from './core.js';
|
|
2
|
+
type Navigation = (href: string) => void;
|
|
3
|
+
/** A per-list adapter. Bind once at the application boundary, not per action. */
|
|
4
|
+
export declare class NavigationHost {
|
|
5
|
+
private navigate?;
|
|
6
|
+
bind(navigate: Navigation): () => void;
|
|
7
|
+
go(href: string): void;
|
|
8
|
+
}
|
|
9
|
+
/** Only root-relative paths, hashes and explicit http(s) URLs are supported. */
|
|
10
|
+
export declare function safeHref(href: string | undefined): string | undefined;
|
|
11
|
+
export declare function navigate(context: ActionContext): void;
|
|
12
|
+
export {};
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
/** A per-list adapter. Bind once at the application boundary, not per action. */
|
|
2
|
+
export class NavigationHost {
|
|
3
|
+
navigate;
|
|
4
|
+
bind(navigate) {
|
|
5
|
+
this.navigate = navigate;
|
|
6
|
+
return () => {
|
|
7
|
+
if (this.navigate === navigate)
|
|
8
|
+
this.navigate = undefined;
|
|
9
|
+
};
|
|
10
|
+
}
|
|
11
|
+
go(href) {
|
|
12
|
+
if (!this.navigate)
|
|
13
|
+
throw new Error('Navigation is not mounted.');
|
|
14
|
+
this.navigate(href);
|
|
15
|
+
}
|
|
16
|
+
}
|
|
17
|
+
/** Only root-relative paths, hashes and explicit http(s) URLs are supported. */
|
|
18
|
+
export function safeHref(href) {
|
|
19
|
+
if (!href || /[\u0000-\u0020\u007f\\]/.test(href))
|
|
20
|
+
return undefined;
|
|
21
|
+
if (href.startsWith('#') || (href.startsWith('/') && !href.startsWith('//')))
|
|
22
|
+
return href;
|
|
23
|
+
try {
|
|
24
|
+
const url = new URL(href);
|
|
25
|
+
return ['http:', 'https:'].includes(url.protocol) && !url.username && !url.password
|
|
26
|
+
? href
|
|
27
|
+
: undefined;
|
|
28
|
+
}
|
|
29
|
+
catch {
|
|
30
|
+
return undefined;
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
export function navigate(context) {
|
|
34
|
+
const current = context.get();
|
|
35
|
+
const href = safeHref(current?.href);
|
|
36
|
+
if (!href)
|
|
37
|
+
throw new Error('Invalid navigation target.');
|
|
38
|
+
if (!(context.environment instanceof NavigationHost))
|
|
39
|
+
throw new Error('A NavigationHost is required.');
|
|
40
|
+
// This dispatches navigation. Completion does NOT mean the next route has loaded.
|
|
41
|
+
context.environment.go(href);
|
|
42
|
+
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import type { ActionList } from './action-list.js';
|
|
2
|
+
import type { ActionInput, ActionResult, ExecutionResult } from './types.js';
|
|
3
|
+
declare const referenceType: unique symbol;
|
|
4
|
+
/** A typed handle to an existing registration; it stores no Action state. */
|
|
5
|
+
export interface ActionReference<Id extends string = string> {
|
|
6
|
+
readonly [referenceType]: Id;
|
|
7
|
+
readonly id: Id;
|
|
8
|
+
execute(input?: ActionInput<Id>): Promise<ExecutionResult<ActionResult<Id>>>;
|
|
9
|
+
}
|
|
10
|
+
/** UI bindings reuse the current list and reject references from another app instance. */
|
|
11
|
+
export declare function resolveActionId<Id extends string>(target: Id | ActionReference<Id>, list: ActionList): Id;
|
|
12
|
+
/** Internal reference creation. Child paths provide namespaces without another Action registry. */
|
|
13
|
+
export declare function createActionReference(list: ActionList, id: string, children: {
|
|
14
|
+
get(name: string): object;
|
|
15
|
+
keys(): string[];
|
|
16
|
+
}): ActionReference;
|
|
17
|
+
export {};
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
const owners = new WeakMap();
|
|
2
|
+
/** UI bindings reuse the current list and reject references from another app instance. */
|
|
3
|
+
export function resolveActionId(target, list) {
|
|
4
|
+
if (typeof target === 'string')
|
|
5
|
+
return target;
|
|
6
|
+
const owner = owners.get(target);
|
|
7
|
+
if (!owner || owner.list !== list)
|
|
8
|
+
throw new Error('The Action reference belongs to a different Foundation instance.');
|
|
9
|
+
return owner.id;
|
|
10
|
+
}
|
|
11
|
+
/** Internal reference creation. Child paths provide namespaces without another Action registry. */
|
|
12
|
+
export function createActionReference(list, id, children) {
|
|
13
|
+
const target = Object.create(null);
|
|
14
|
+
Object.defineProperties(target, {
|
|
15
|
+
id: { value: id, configurable: true },
|
|
16
|
+
execute: { configurable: true, value: (input) => {
|
|
17
|
+
if (list.get(id)?.internal)
|
|
18
|
+
throw new Error(`Internal Action "${id}" is not publicly accessible.`);
|
|
19
|
+
return list.execute(id, input);
|
|
20
|
+
} },
|
|
21
|
+
});
|
|
22
|
+
const reference = new Proxy(target, {
|
|
23
|
+
get(target, name, receiver) {
|
|
24
|
+
if (Object.hasOwn(target, name))
|
|
25
|
+
return Reflect.get(target, name, receiver);
|
|
26
|
+
if (typeof name !== 'string' || name === 'then' || name === 'toJSON')
|
|
27
|
+
return undefined;
|
|
28
|
+
return children.get(name);
|
|
29
|
+
},
|
|
30
|
+
ownKeys: children.keys,
|
|
31
|
+
getOwnPropertyDescriptor: (target, name) => Reflect.getOwnPropertyDescriptor(target, name)
|
|
32
|
+
?? (typeof name === 'string' && children.keys().includes(name) ? { enumerable: true, configurable: true } : undefined),
|
|
33
|
+
set: () => false,
|
|
34
|
+
defineProperty: () => false,
|
|
35
|
+
deleteProperty: () => false,
|
|
36
|
+
});
|
|
37
|
+
owners.set(reference, { list, id });
|
|
38
|
+
return reference;
|
|
39
|
+
}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/** Runtime-owned lifecycle status, separate from invocation results and custom state. */
|
|
2
|
+
export declare enum ActionStatus {
|
|
3
|
+
Idle = "idle",
|
|
4
|
+
Pending = "pending",
|
|
5
|
+
Succeeded = "succeeded",
|
|
6
|
+
Failed = "failed"
|
|
7
|
+
}
|
|
8
|
+
/** Custom state is read-only to consumers; updates publish through the existing ActionList. */
|
|
9
|
+
export type ActionStateValue<Id extends string> = Id extends keyof import('./types.js').ActionMap ? import('./types.js').ActionMap[Id] extends {
|
|
10
|
+
state: infer State;
|
|
11
|
+
} ? Readonly<State> : unknown : unknown;
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/** Runtime-owned lifecycle status, separate from invocation results and custom state. */
|
|
2
|
+
export var ActionStatus;
|
|
3
|
+
(function (ActionStatus) {
|
|
4
|
+
ActionStatus["Idle"] = "idle";
|
|
5
|
+
ActionStatus["Pending"] = "pending";
|
|
6
|
+
ActionStatus["Succeeded"] = "succeeded";
|
|
7
|
+
ActionStatus["Failed"] = "failed";
|
|
8
|
+
})(ActionStatus || (ActionStatus = {}));
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
import type { ActionStatus } from './state.js';
|
|
2
|
+
import type { PresentationType } from '../presentation.js';
|
|
3
|
+
import type { RegistrationOptions } from './groups.js';
|
|
4
|
+
export type ActionIcon = PresentationType<'icon'>;
|
|
5
|
+
/** The returned value becomes `value` of the completed execution result. */
|
|
6
|
+
export type ActionHandler<Input = unknown, Result = unknown> = (context: ActionContext<Input>) => Result | Promise<Result>;
|
|
7
|
+
/** Declarative keyboard binding; browser adapters own parsing, scopes and presentation. */
|
|
8
|
+
export type ActionShortcut<Input = unknown> = Readonly<{
|
|
9
|
+
keys: string;
|
|
10
|
+
scope?: string;
|
|
11
|
+
allowInInputs?: boolean;
|
|
12
|
+
}> & (undefined extends Input ? {
|
|
13
|
+
input?: Input;
|
|
14
|
+
} : {
|
|
15
|
+
input: Input;
|
|
16
|
+
});
|
|
17
|
+
export interface ActionDefinition extends RegistrationOptions {
|
|
18
|
+
/** Prefer namespaced IDs, e.g. "course.save". Unique within one list. */
|
|
19
|
+
id: string;
|
|
20
|
+
title: string;
|
|
21
|
+
description?: string;
|
|
22
|
+
tooltip?: string;
|
|
23
|
+
shortcut?: ActionShortcut;
|
|
24
|
+
variant?: 'default' | 'destructive';
|
|
25
|
+
resolve?: (input: unknown) => ActionPresentation;
|
|
26
|
+
icon?: ActionIcon;
|
|
27
|
+
href?: string;
|
|
28
|
+
enabled?: boolean;
|
|
29
|
+
/** All referenced actions must be enabled. Missing actions and cycles disable this action. */
|
|
30
|
+
dependsOn?: readonly string[];
|
|
31
|
+
visible?: boolean;
|
|
32
|
+
checked?: boolean;
|
|
33
|
+
value?: unknown;
|
|
34
|
+
/** Cloned for each registration; updated only through the existing snapshot store. */
|
|
35
|
+
initialState?: object;
|
|
36
|
+
state?: unknown;
|
|
37
|
+
execute?: ActionHandler;
|
|
38
|
+
/**
|
|
39
|
+
* Executable and subscribable by ID, but excluded from enumeration such as `useActions()`
|
|
40
|
+
* and group views. Used for helper registrations that must not surface as commands.
|
|
41
|
+
*/
|
|
42
|
+
internal?: boolean;
|
|
43
|
+
/** Opaque, immutable host metadata. The core never interprets it. */
|
|
44
|
+
metadata?: unknown;
|
|
45
|
+
}
|
|
46
|
+
export type ActionPresentation = Partial<Pick<ActionDefinition, 'title' | 'description' | 'tooltip' | 'icon' | 'href' | 'enabled' | 'visible' | 'checked' | 'value' | 'variant'>>;
|
|
47
|
+
export type ActionPatch = Partial<Omit<ActionDefinition, 'id'>>;
|
|
48
|
+
export type ActionSnapshot = Readonly<Omit<ActionDefinition, 'enabled' | 'visible'> & {
|
|
49
|
+
enabled: boolean;
|
|
50
|
+
visible: boolean;
|
|
51
|
+
pending: boolean;
|
|
52
|
+
status: ActionStatus;
|
|
53
|
+
error?: unknown;
|
|
54
|
+
state: unknown;
|
|
55
|
+
}>;
|
|
56
|
+
export interface ActionContext<Input = unknown> {
|
|
57
|
+
readonly id: string;
|
|
58
|
+
/** Per-invocation input. The handler validates it; it is never stored in action state. */
|
|
59
|
+
readonly input: Input;
|
|
60
|
+
/** Current snapshot of this registration; undefined after removal/replacement. */
|
|
61
|
+
get(): ActionSnapshot | undefined;
|
|
62
|
+
/** Optional host dependency injection, owned by this list (never global). */
|
|
63
|
+
readonly environment: unknown;
|
|
64
|
+
/** Updates only this registration, even if the handler finishes after replacement. */
|
|
65
|
+
update(patch: ActionPatch): boolean;
|
|
66
|
+
}
|
|
67
|
+
export interface ActionRegistration {
|
|
68
|
+
update(patch: ActionPatch): boolean;
|
|
69
|
+
/** Idempotent. Cannot remove a newer registration of the same ID. */
|
|
70
|
+
unregister(): void;
|
|
71
|
+
}
|
|
72
|
+
export type ExecutionResult<Value = unknown> = {
|
|
73
|
+
status: 'completed';
|
|
74
|
+
value: Value;
|
|
75
|
+
} | {
|
|
76
|
+
status: 'skipped';
|
|
77
|
+
reason: 'missing' | 'disabled' | 'hidden' | 'pending' | 'no-handler' | 'intercepted' | 'replaced';
|
|
78
|
+
};
|
|
79
|
+
/**
|
|
80
|
+
* Registry of known action IDs with their input and result types. Build tooling augments it
|
|
81
|
+
* from discovered definitions; explicit hosts and packages may augment it themselves:
|
|
82
|
+
* `declare module '@bitakit/core' { interface ActionMap { 'users.invite': { input: X; result: Y } } }`
|
|
83
|
+
*/
|
|
84
|
+
export interface ActionMap {
|
|
85
|
+
}
|
|
86
|
+
/** Augment with `{ strict: true }` to reject action IDs that are not part of ActionMap. */
|
|
87
|
+
export interface ActionMapOptions {
|
|
88
|
+
}
|
|
89
|
+
export type KnownActionId = Extract<keyof ActionMap, string>;
|
|
90
|
+
/** Known IDs autocomplete; unknown strings stay allowed unless strict mode is enabled. */
|
|
91
|
+
export type ActionId = ActionMapOptions extends {
|
|
92
|
+
strict: true;
|
|
93
|
+
} ? KnownActionId : KnownActionId | (string & {});
|
|
94
|
+
export type ActionInput<Id extends string = string> = Id extends KnownActionId ? ActionMap[Id] extends {
|
|
95
|
+
input: infer Input;
|
|
96
|
+
} ? Input : unknown : unknown;
|
|
97
|
+
export type ActionResult<Id extends string = string> = Id extends KnownActionId ? ActionMap[Id] extends {
|
|
98
|
+
result: infer Result;
|
|
99
|
+
} ? Result : unknown : unknown;
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
import type { FoundationRuntime } from '../runtime.js';
|
|
2
|
+
import type { FoundationApp } from './types.js';
|
|
3
|
+
/** Projects public service paths onto the existing container, with no cached instances. */
|
|
4
|
+
export declare function createFoundationApp(runtime: FoundationRuntime): FoundationApp;
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
import { FoundationServiceError } from './service-error.js';
|
|
2
|
+
import { createActionAccess } from './action-access.js';
|
|
3
|
+
/** Projects public service paths onto the existing container, with no cached instances. */
|
|
4
|
+
export function createFoundationApp(runtime) {
|
|
5
|
+
const tree = new Map();
|
|
6
|
+
for (const plugin of runtime.modules) {
|
|
7
|
+
for (const [name, key] of Object.entries(plugin.publicServices ?? {})) {
|
|
8
|
+
const segments = name.split('.');
|
|
9
|
+
let branch = tree;
|
|
10
|
+
for (const [index, segment] of segments.entries()) {
|
|
11
|
+
const existing = branch.get(segment);
|
|
12
|
+
if (!segment ||
|
|
13
|
+
['then', 'toJSON', '__proto__'].includes(segment) ||
|
|
14
|
+
(existing && (!(existing instanceof Map) || index === segments.length - 1))) {
|
|
15
|
+
const owner = existing && !(existing instanceof Map)
|
|
16
|
+
? ` (already exposed by "${existing.plugin}")`
|
|
17
|
+
: '';
|
|
18
|
+
throw new Error(`Duplicate or reserved public service path "${name}" in plugin "${plugin.id}"${owner}.`);
|
|
19
|
+
}
|
|
20
|
+
if (index === segments.length - 1)
|
|
21
|
+
branch.set(segment, { key, plugin: plugin.id });
|
|
22
|
+
else {
|
|
23
|
+
if (!existing)
|
|
24
|
+
branch.set(segment, new Map());
|
|
25
|
+
branch = branch.get(segment);
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
const read = (name, source, optional) => {
|
|
31
|
+
if (!runtime.isReady()) {
|
|
32
|
+
if (optional)
|
|
33
|
+
return undefined;
|
|
34
|
+
throw new FoundationServiceError(name, 'not-ready', source.plugin);
|
|
35
|
+
}
|
|
36
|
+
if (!Object.hasOwn(runtime.services, source.key)) {
|
|
37
|
+
if (optional)
|
|
38
|
+
return undefined;
|
|
39
|
+
throw new FoundationServiceError(name, 'missing', source.plugin);
|
|
40
|
+
}
|
|
41
|
+
return runtime.services[source.key];
|
|
42
|
+
};
|
|
43
|
+
const project = (branch, optional, prefix = '') => {
|
|
44
|
+
const target = Object.create(null);
|
|
45
|
+
for (const [segment, source] of branch) {
|
|
46
|
+
const name = prefix ? `${prefix}.${segment}` : segment;
|
|
47
|
+
Object.defineProperty(target, segment, source instanceof Map
|
|
48
|
+
? { enumerable: true, value: project(source, optional, name) }
|
|
49
|
+
: { enumerable: true, get: () => read(name, source, optional) });
|
|
50
|
+
}
|
|
51
|
+
return new Proxy(Object.freeze(target), {
|
|
52
|
+
get(target, name, receiver) {
|
|
53
|
+
if (Object.hasOwn(target, name))
|
|
54
|
+
return Reflect.get(target, name, receiver);
|
|
55
|
+
if (typeof name === 'symbol' || name === 'then' || name === 'toJSON' || optional)
|
|
56
|
+
return undefined;
|
|
57
|
+
throw new FoundationServiceError(prefix ? `${prefix}.${name}` : name, 'unregistered');
|
|
58
|
+
},
|
|
59
|
+
});
|
|
60
|
+
};
|
|
61
|
+
const extensions = {};
|
|
62
|
+
for (const plugin of runtime.modules) {
|
|
63
|
+
for (const [name, create] of Object.entries(plugin.appExtensions ?? {})) {
|
|
64
|
+
if (Object.hasOwn(extensions, name) ||
|
|
65
|
+
['actions', 'config', 'services', 'ready', 'optional'].includes(name))
|
|
66
|
+
throw new Error(`Duplicate app extension "${name}" in plugin "${plugin.id}".`);
|
|
67
|
+
extensions[name] = create(runtime);
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
return Object.freeze({
|
|
71
|
+
...extensions,
|
|
72
|
+
actions: createActionAccess(runtime.actions),
|
|
73
|
+
get config() {
|
|
74
|
+
return Object.freeze(Object.fromEntries(runtime.modules.map((module) => [
|
|
75
|
+
module.id,
|
|
76
|
+
runtime.configuration.plugin(module.id).snapshot(),
|
|
77
|
+
])));
|
|
78
|
+
},
|
|
79
|
+
services: project(tree, false),
|
|
80
|
+
get ready() {
|
|
81
|
+
return runtime.isReady();
|
|
82
|
+
},
|
|
83
|
+
optional: Object.freeze({ services: project(tree, true) }),
|
|
84
|
+
});
|
|
85
|
+
}
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
import type { ActionList } from '../actions/action-list.js';
|
|
2
|
+
import type { FoundationActions } from './types.js';
|
|
3
|
+
/** Projects dotted IDs onto stable handles; enumeration reads only current public registrations. */
|
|
4
|
+
export declare function createActionAccess(list: ActionList): FoundationActions;
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import { createActionReference } from '../actions/reference.js';
|
|
2
|
+
/** Projects dotted IDs onto stable handles; enumeration reads only current public registrations. */
|
|
3
|
+
export function createActionAccess(list) {
|
|
4
|
+
const references = new Map();
|
|
5
|
+
const at = (path) => {
|
|
6
|
+
const cached = references.get(path);
|
|
7
|
+
if (cached)
|
|
8
|
+
return cached;
|
|
9
|
+
const prefix = path ? `${path}.` : '';
|
|
10
|
+
const reference = createActionReference(list, path, {
|
|
11
|
+
get: name => at(`${prefix}${name}`),
|
|
12
|
+
keys: () => [...new Set(Object.values(list.getState().actions)
|
|
13
|
+
.filter(action => !action.internal && action.id.startsWith(prefix))
|
|
14
|
+
.map(action => action.id.slice(prefix.length).split('.')[0]))].filter(Boolean),
|
|
15
|
+
});
|
|
16
|
+
references.set(path, reference);
|
|
17
|
+
return reference;
|
|
18
|
+
};
|
|
19
|
+
return at('');
|
|
20
|
+
}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/** Structured diagnostics for unavailable public services, without guessing installation state. */
|
|
2
|
+
export declare class FoundationServiceError extends Error {
|
|
3
|
+
readonly service: string;
|
|
4
|
+
readonly reason: 'not-ready' | 'missing' | 'unregistered';
|
|
5
|
+
readonly plugin?: string | undefined;
|
|
6
|
+
readonly code = "FOUNDATION_SERVICE_UNAVAILABLE";
|
|
7
|
+
constructor(service: string, reason: 'not-ready' | 'missing' | 'unregistered', plugin?: string | undefined);
|
|
8
|
+
}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
/** Structured diagnostics for unavailable public services, without guessing installation state. */
|
|
2
|
+
export class FoundationServiceError extends Error {
|
|
3
|
+
service;
|
|
4
|
+
reason;
|
|
5
|
+
plugin;
|
|
6
|
+
code = 'FOUNDATION_SERVICE_UNAVAILABLE';
|
|
7
|
+
constructor(service, reason, plugin) {
|
|
8
|
+
const detail = reason === 'not-ready'
|
|
9
|
+
? 'The Foundation runtime is not mounted. Read optional services or wait for app.ready.'
|
|
10
|
+
: reason === 'missing'
|
|
11
|
+
? `Plugin "${plugin}" does not provide its declared service. Check its service configuration.`
|
|
12
|
+
: 'No active plugin exposes this service. Check that the providing plugin is included and enabled.';
|
|
13
|
+
super(`Foundation service "${service}" is unavailable. ${detail}`);
|
|
14
|
+
this.service = service;
|
|
15
|
+
this.reason = reason;
|
|
16
|
+
this.plugin = plugin;
|
|
17
|
+
this.name = 'FoundationServiceError';
|
|
18
|
+
}
|
|
19
|
+
}
|