@bitakit/core 0.1.2 → 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.
Files changed (157) hide show
  1. package/README.md +44 -207
  2. package/discovery/index.d.ts +1 -41
  3. package/discovery/index.mjs +1 -4
  4. package/dist/actions/action-list.d.ts +4 -0
  5. package/dist/actions/action-list.js +58 -16
  6. package/dist/actions/action.d.ts +2 -0
  7. package/dist/actions/action.js +4 -0
  8. package/dist/actions/brand.d.ts +21 -0
  9. package/dist/actions/brand.js +36 -0
  10. package/dist/actions/core.d.ts +4 -3
  11. package/dist/actions/core.js +4 -2
  12. package/dist/actions/execution.d.ts +2 -2
  13. package/dist/actions/execution.js +61 -9
  14. package/dist/actions/feedback.d.ts +2 -0
  15. package/dist/actions/feedback.js +8 -0
  16. package/dist/actions/groups.js +5 -1
  17. package/dist/actions/instance-bindings.js +3 -2
  18. package/dist/actions/interceptors.d.ts +9 -3
  19. package/dist/actions/interceptors.js +31 -3
  20. package/dist/actions/navigation.d.ts +2 -1
  21. package/dist/actions/navigation.js +10 -5
  22. package/dist/actions/reference.js +10 -5
  23. package/dist/actions/types.d.ts +9 -1
  24. package/dist/app/access.d.ts +4 -4
  25. package/dist/app/access.js +33 -71
  26. package/dist/app/action-access.d.ts +2 -2
  27. package/dist/app/action-access.js +6 -4
  28. package/dist/app/service-error.d.ts +2 -2
  29. package/dist/app/service-error.js +10 -6
  30. package/dist/app/types.d.ts +76 -33
  31. package/dist/config-service.d.ts +30 -6
  32. package/dist/config-service.js +25 -9
  33. package/dist/configuration.d.ts +6 -3
  34. package/dist/configuration.js +8 -6
  35. package/dist/contracts.d.ts +4 -2
  36. package/dist/contracts.js +3 -3
  37. package/dist/contribution-origin.d.ts +4 -1
  38. package/dist/contribution-origin.js +14 -1
  39. package/dist/contributions/action.d.ts +26 -0
  40. package/dist/contributions/action.js +171 -0
  41. package/dist/contributions/host.d.ts +14 -11
  42. package/dist/contributions/index.d.ts +1 -26
  43. package/dist/contributions/index.js +1 -18
  44. package/dist/conventions.d.ts +8 -4
  45. package/dist/conventions.js +12 -31
  46. package/dist/core.d.ts +41 -18
  47. package/dist/core.js +25 -13
  48. package/dist/definitions.d.ts +272 -306
  49. package/dist/definitions.js +28 -56
  50. package/dist/destinations.d.ts +25 -0
  51. package/dist/destinations.js +21 -0
  52. package/dist/discovered.d.ts +52 -21
  53. package/dist/discovered.js +89 -35
  54. package/dist/events/define.d.ts +43 -0
  55. package/dist/events/define.js +17 -0
  56. package/dist/events/service.d.ts +35 -8
  57. package/dist/events/service.js +184 -42
  58. package/dist/events/types.d.ts +29 -9
  59. package/dist/inspection/inventory.d.ts +86 -0
  60. package/dist/inspection/inventory.js +132 -0
  61. package/dist/interceptors/define.d.ts +76 -0
  62. package/dist/interceptors/define.js +23 -0
  63. package/dist/interceptors/service-observers.d.ts +6 -3
  64. package/dist/interceptors/service-observers.js +13 -10
  65. package/dist/lifecycle/cleanup.d.ts +5 -0
  66. package/dist/lifecycle/cleanup.js +41 -0
  67. package/dist/lifecycle/controller.d.ts +82 -0
  68. package/dist/lifecycle/controller.js +276 -0
  69. package/dist/lifecycle/reconcile.d.ts +19 -0
  70. package/dist/lifecycle/reconcile.js +68 -0
  71. package/dist/lifecycle/state.d.ts +53 -0
  72. package/dist/lifecycle/state.js +86 -0
  73. package/dist/names.d.ts +10 -0
  74. package/dist/names.js +1 -0
  75. package/dist/pages.d.ts +39 -6
  76. package/dist/pages.js +93 -11
  77. package/dist/presentation.d.ts +9 -0
  78. package/dist/runtime.d.ts +166 -28
  79. package/dist/runtime.js +1485 -248
  80. package/dist/schema.d.ts +13 -0
  81. package/dist/schema.js +38 -0
  82. package/dist/scope.d.ts +59 -4
  83. package/dist/scope.js +133 -11
  84. package/dist/service-key.d.ts +33 -14
  85. package/dist/service-key.js +21 -5
  86. package/dist/service-names.d.ts +39 -0
  87. package/dist/service-names.js +175 -0
  88. package/dist/services.d.ts +24 -5
  89. package/dist/services.js +230 -37
  90. package/dist/settings/access.d.ts +19 -0
  91. package/dist/settings/access.js +78 -0
  92. package/dist/settings/define.d.ts +97 -0
  93. package/dist/settings/define.js +83 -0
  94. package/dist/settings/storage.d.ts +45 -0
  95. package/dist/settings/storage.js +102 -0
  96. package/dist/settings/store.d.ts +74 -0
  97. package/dist/settings/store.js +345 -0
  98. package/dist/slots/action-placement.d.ts +47 -0
  99. package/dist/slots/action-placement.js +1 -0
  100. package/dist/slots/define.d.ts +52 -0
  101. package/dist/slots/define.js +12 -0
  102. package/dist/slots/normalize.d.ts +7 -0
  103. package/dist/slots/normalize.js +36 -0
  104. package/dist/slots/runtime.d.ts +43 -0
  105. package/dist/slots/runtime.js +348 -0
  106. package/dist/slots/types.d.ts +113 -0
  107. package/dist/slots/types.js +1 -0
  108. package/dist/startup-error.d.ts +21 -0
  109. package/dist/startup-error.js +29 -0
  110. package/dist/store.d.ts +24 -0
  111. package/dist/store.js +40 -0
  112. package/dist/translation.d.ts +9 -4
  113. package/dist/translation.js +2 -3
  114. package/examples/todos/actions/create.mjs +1 -3
  115. package/examples/todos/actions/delete.mjs +3 -10
  116. package/examples/todos/actions/list.mjs +1 -3
  117. package/examples/todos/events.mjs +5 -0
  118. package/examples/todos/plugin.mjs +4 -2
  119. package/examples/todos/services/tasks.mjs +14 -20
  120. package/examples/todos.mjs +8 -7
  121. package/package.json +36 -9
  122. package/testing/index.d.ts +59 -0
  123. package/testing/index.mjs +150 -0
  124. package/assets/bitakit-banner.png +0 -0
  125. package/discovery/entries.mjs +0 -124
  126. package/discovery/generate.mjs +0 -321
  127. package/discovery/host.mjs +0 -12
  128. package/discovery/modules.mjs +0 -13
  129. package/discovery/packages.mjs +0 -57
  130. package/discovery/watch.mjs +0 -23
  131. package/dist/app/service-aliases.d.ts +0 -4
  132. package/dist/app/service-aliases.js +0 -14
  133. package/dist/contributions/command.d.ts +0 -8
  134. package/dist/contributions/command.js +0 -59
  135. package/dist/contributions/dialog.d.ts +0 -8
  136. package/dist/contributions/dialog.js +0 -18
  137. package/dist/contributions/form.d.ts +0 -10
  138. package/dist/contributions/form.js +0 -67
  139. package/dist/contributions/native.d.ts +0 -11
  140. package/dist/contributions/native.js +0 -87
  141. package/dist/contributions/shared.d.ts +0 -19
  142. package/dist/contributions/shared.js +0 -48
  143. package/dist/contributions/stateful-action.d.ts +0 -29
  144. package/dist/contributions/stateful-action.js +0 -33
  145. package/dist/events/action-setup.d.ts +0 -19
  146. package/dist/events/action-setup.js +0 -24
  147. package/dist/interceptors/service.d.ts +0 -37
  148. package/dist/interceptors/service.js +0 -7
  149. package/dist/replacements.d.ts +0 -22
  150. package/dist/replacements.js +0 -54
  151. package/dist/validation.d.ts +0 -2
  152. package/dist/validation.js +0 -16
  153. package/docs/auth.md +0 -106
  154. package/docs/events.md +0 -157
  155. package/docs/file-contributions.md +0 -174
  156. package/docs/reference.md +0 -404
  157. package/docs/todo-tutorial.md +0 -88
@@ -1,11 +1,22 @@
1
1
  import { ActionStatus } from './state.js';
2
- export function createExecutor(setPending, owners, environment, get, resolve, update, lifecycle) {
2
+ import { CANCEL } from './interceptors.js';
3
+ const isThenable = (value) => !!value && typeof value.then === 'function';
4
+ const keyOf = (action, input) => action.concurrency !== 'per-input'
5
+ ? '*'
6
+ : action.concurrencyKey
7
+ ? action.concurrencyKey(input)
8
+ : typeof input === 'object' && input !== null
9
+ ? JSON.stringify(input)
10
+ : String(input);
11
+ export function createExecutor(setPending, owners, environment, get, resolve, update, lifecycle, running) {
3
12
  return async function execute(id, input) {
4
13
  const owner = owners.get(id);
14
+ const controller = new AbortController();
5
15
  const context = Object.freeze({
6
16
  id,
7
17
  input,
8
18
  environment,
19
+ signal: controller.signal,
9
20
  get: () => (owners.get(id) === owner ? get(id) : undefined),
10
21
  update: (patch) => owners.get(id) === owner && update(id, patch),
11
22
  });
@@ -21,19 +32,46 @@ export function createExecutor(setPending, owners, environment, get, resolve, up
21
32
  return skip('hidden');
22
33
  if (!action.enabled)
23
34
  return skip('disabled');
24
- if (action.pending)
25
- return skip('pending');
26
35
  if (!action.execute)
27
36
  return skip('no-handler');
37
+ const key = keyOf(action, input);
38
+ let runs = running.get(id);
39
+ if (!runs)
40
+ running.set(id, (runs = new Map()));
41
+ const previous = runs.get(key);
42
+ if (previous) {
43
+ if (action.concurrency !== 'latest')
44
+ return skip('pending');
45
+ previous.abort();
46
+ }
47
+ runs.set(key, controller);
48
+ let pending = false;
49
+ const markPending = () => {
50
+ if (pending)
51
+ return;
52
+ pending = true;
53
+ setPending(id, key, true, ActionStatus.Pending);
54
+ };
28
55
  let status = action.status;
29
56
  let failure = action.error;
30
- setPending(id, true, ActionStatus.Pending);
31
57
  lifecycle.emit({ id, context, phase: 'started' });
32
58
  try {
33
- if (lifecycle.hasInterceptors && !(await lifecycle.allow(context)))
34
- return skip('intercepted');
59
+ if (lifecycle.hasInterceptors) {
60
+ // Interceptors may wait (a confirmation); the action shows pending only then.
61
+ let verdict = lifecycle.allow(context);
62
+ if (isThenable(verdict)) {
63
+ markPending();
64
+ verdict = await verdict;
65
+ }
66
+ if (verdict === CANCEL)
67
+ return skip('cancelled');
68
+ if (!verdict)
69
+ return skip('intercepted');
70
+ }
35
71
  if (owners.get(id) !== owner)
36
72
  return skip('replaced');
73
+ if (controller.signal.aborted)
74
+ return skip('cancelled');
37
75
  const current = resolve(id, input);
38
76
  if (!current?.visible)
39
77
  return skip('hidden');
@@ -42,7 +80,11 @@ export function createExecutor(setPending, owners, environment, get, resolve, up
42
80
  if (!current.execute)
43
81
  return skip('no-handler');
44
82
  // The handler's return value travels to the caller; it is never stored in action state.
45
- const value = await current.execute(context);
83
+ let value = current.execute(context);
84
+ if (isThenable(value)) {
85
+ markPending();
86
+ value = await value;
87
+ }
46
88
  status = ActionStatus.Succeeded;
47
89
  failure = undefined;
48
90
  const result = { status: 'completed', value };
@@ -56,8 +98,18 @@ export function createExecutor(setPending, owners, environment, get, resolve, up
56
98
  throw error;
57
99
  }
58
100
  finally {
59
- if (owners.get(id) === owner && get(id)) {
60
- setPending(id, false, status, failure);
101
+ // A run superseded by a newer `latest` run no longer owns its key: it must not clear the
102
+ // pending flag or publish its outcome as the action's current state.
103
+ const current = runs.get(key) === controller;
104
+ if (current)
105
+ runs.delete(key);
106
+ if (!runs.size)
107
+ running.delete(id);
108
+ if (current && owners.get(id) === owner && get(id)) {
109
+ if (pending)
110
+ setPending(id, key, false, status, failure);
111
+ else if (status !== get(id).status || failure !== get(id).error)
112
+ setPending(id, key, false, status, failure);
61
113
  }
62
114
  }
63
115
  };
@@ -15,3 +15,5 @@ export declare class ActionFailure extends Error {
15
15
  readonly feedback: string | false;
16
16
  constructor(feedback: string | false, cause: unknown);
17
17
  }
18
+ /** Recognizes failures from any copy of this package (see brand.ts). */
19
+ export declare function isActionFailure(error: unknown): error is ActionFailure;
@@ -1,3 +1,4 @@
1
+ import { brand, isBrandedInstance } from './brand.js';
1
2
  /** Feedback callbacks cannot turn a successful operation into a failed operation. */
2
3
  export function evaluateFeedback(feedback, context) {
3
4
  try {
@@ -13,9 +14,16 @@ export function evaluateFeedback(feedback, context) {
13
14
  /** Carries only the selected display message; the original error remains in cause. */
14
15
  export class ActionFailure extends Error {
15
16
  feedback;
17
+ static {
18
+ brand(this, 'failure');
19
+ }
16
20
  constructor(feedback, cause) {
17
21
  super(feedback || 'Action failed.', { cause });
18
22
  this.feedback = feedback;
19
23
  this.name = 'ActionFailure';
20
24
  }
21
25
  }
26
+ /** Recognizes failures from any copy of this package (see brand.ts). */
27
+ export function isActionFailure(error) {
28
+ return isBrandedInstance(error, ActionFailure, 'failure');
29
+ }
@@ -1,7 +1,11 @@
1
+ import { brand, isBrandedInstance } from './brand.js';
1
2
  /** A typed extension point. The same group can be rendered in different places. */
2
3
  export class ActionGroup {
3
4
  id;
4
5
  title;
6
+ static {
7
+ brand(this, 'group');
8
+ }
5
9
  constructor(id, title) {
6
10
  this.id = id;
7
11
  this.title = title;
@@ -13,7 +17,7 @@ export class ActionGroup {
13
17
  export function freezeGroups(groups = []) {
14
18
  const ids = new Set();
15
19
  for (const group of groups) {
16
- if (!(group instanceof ActionGroup) || ids.has(group.id))
20
+ if (!isBrandedInstance(group, ActionGroup, 'group') || ids.has(group.id))
17
21
  throw new Error('Invalid or duplicate action group.');
18
22
  ids.add(group.id);
19
23
  }
@@ -1,5 +1,6 @@
1
1
  import { Action } from './action.js';
2
2
  import { NavigationHost } from './navigation.js';
3
+ import { isBrandedInstance } from './brand.js';
3
4
  /** Owns subscriptions to class instances and external services. */
4
5
  export class InstanceBindings {
5
6
  environment;
@@ -13,7 +14,7 @@ export class InstanceBindings {
13
14
  attach(id, action, registration) {
14
15
  {
15
16
  const host = this.environment;
16
- if (host instanceof NavigationHost)
17
+ if (isBrandedInstance(host, NavigationHost, 'navigation'))
17
18
  action.bindNavigation((href) => host.go(href));
18
19
  }
19
20
  const entry = {
@@ -63,7 +64,7 @@ export class InstanceBindings {
63
64
  mount(navigate) {
64
65
  this.mounted = true;
65
66
  this.navigate = navigate;
66
- const unbind = this.environment instanceof NavigationHost && navigate
67
+ const unbind = isBrandedInstance(this.environment, NavigationHost, 'navigation') && navigate
67
68
  ? this.environment.bind(navigate)
68
69
  : undefined;
69
70
  const cleanup = () => {
@@ -1,7 +1,9 @@
1
1
  import type { ActionContext, ExecutionResult } from './types.js';
2
+ /** Returned by `before` to skip with reason "cancelled" (the user declined a confirmation). */
3
+ export declare const CANCEL: unique symbol;
2
4
  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
+ /** Returning false cancels execution (reason "intercepted"); CANCEL skips with reason "cancelled". */
6
+ before(context: ActionContext): boolean | void | typeof CANCEL | Promise<boolean | void | typeof CANCEL>;
5
7
  };
6
8
  export type ExecutionEvent = Readonly<{
7
9
  id: string;
@@ -17,7 +19,11 @@ export declare class ExecutionLifecycle {
17
19
  private observers;
18
20
  use(interceptor: ActionInterceptor): () => void;
19
21
  subscribe(listener: (event: ExecutionEvent) => void): () => void;
20
- allow(context: ActionContext): Promise<boolean>;
22
+ /**
23
+ * True to proceed, false when intercepted, CANCEL when a confirmation was declined. Stays
24
+ * synchronous while every hook answers synchronously, so sync actions never show pending.
25
+ */
26
+ allow(context: ActionContext): boolean | typeof CANCEL | Promise<boolean | typeof CANCEL>;
21
27
  get hasInterceptors(): boolean;
22
28
  emit(event: Omit<ExecutionEvent, 'timestamp'>): void;
23
29
  clear(): void;
@@ -1,3 +1,5 @@
1
+ /** Returned by `before` to skip with reason "cancelled" (the user declined a confirmation). */
2
+ export const CANCEL = Symbol.for('bitakit.core.cancel');
1
3
  /** Interceptors gate commands; observers cannot change their outcome. */
2
4
  export class ExecutionLifecycle {
3
5
  interceptors = new Set();
@@ -14,10 +16,36 @@ export class ExecutionLifecycle {
14
16
  this.observers.delete(listener);
15
17
  };
16
18
  }
17
- async allow(context) {
18
- for (const interceptor of [...this.interceptors]) {
19
- if ((await interceptor.before(context)) === false)
19
+ /**
20
+ * True to proceed, false when intercepted, CANCEL when a confirmation was declined. Stays
21
+ * synchronous while every hook answers synchronously, so sync actions never show pending.
22
+ */
23
+ allow(context) {
24
+ const pending = [...this.interceptors];
25
+ const finish = async (first, rest) => {
26
+ const verdict = await first;
27
+ if (verdict === false)
20
28
  return false;
29
+ if (verdict === CANCEL)
30
+ return CANCEL;
31
+ for (const interceptor of rest) {
32
+ const next = await interceptor.before(context);
33
+ if (next === false)
34
+ return false;
35
+ if (next === CANCEL)
36
+ return CANCEL;
37
+ }
38
+ return true;
39
+ };
40
+ while (pending.length) {
41
+ const interceptor = pending.shift();
42
+ const verdict = interceptor.before(context);
43
+ if (verdict && typeof verdict.then === 'function')
44
+ return finish(verdict, pending);
45
+ if (verdict === false)
46
+ return false;
47
+ if (verdict === CANCEL)
48
+ return CANCEL;
21
49
  }
22
50
  return true;
23
51
  }
@@ -8,5 +8,6 @@ export declare class NavigationHost {
8
8
  }
9
9
  /** Only root-relative paths, hashes and explicit http(s) URLs are supported. */
10
10
  export declare function safeHref(href: string | undefined): string | undefined;
11
- export declare function navigate(context: ActionContext): void;
11
+ /** Navigates to `href`, or to the registration's current href; the registration must still exist. */
12
+ export declare function navigate(context: ActionContext, href?: string): void;
12
13
  export {};
@@ -1,5 +1,9 @@
1
+ import { brand, isBrandedInstance } from './brand.js';
1
2
  /** A per-list adapter. Bind once at the application boundary, not per action. */
2
3
  export class NavigationHost {
4
+ static {
5
+ brand(this, 'navigation');
6
+ }
3
7
  navigate;
4
8
  bind(navigate) {
5
9
  this.navigate = navigate;
@@ -30,13 +34,14 @@ export function safeHref(href) {
30
34
  return undefined;
31
35
  }
32
36
  }
33
- export function navigate(context) {
37
+ /** Navigates to `href`, or to the registration's current href; the registration must still exist. */
38
+ export function navigate(context, href) {
34
39
  const current = context.get();
35
- const href = safeHref(current?.href);
36
- if (!href)
40
+ const target = current ? safeHref(href ?? current.href) : undefined;
41
+ if (!target)
37
42
  throw new Error('Invalid navigation target.');
38
- if (!(context.environment instanceof NavigationHost))
43
+ if (!isBrandedInstance(context.environment, NavigationHost, 'navigation'))
39
44
  throw new Error('A NavigationHost is required.');
40
45
  // This dispatches navigation. Completion does NOT mean the next route has loaded.
41
- context.environment.go(href);
46
+ context.environment.go(target);
42
47
  }
@@ -5,7 +5,7 @@ export function resolveActionId(target, list) {
5
5
  return target;
6
6
  const owner = owners.get(target);
7
7
  if (!owner || owner.list !== list)
8
- throw new Error('The Action reference belongs to a different Foundation instance.');
8
+ throw new Error('The Action reference belongs to a different BitaKit instance.');
9
9
  return owner.id;
10
10
  }
11
11
  /** Internal reference creation. Child paths provide namespaces without another Action registry. */
@@ -13,11 +13,14 @@ export function createActionReference(list, id, children) {
13
13
  const target = Object.create(null);
14
14
  Object.defineProperties(target, {
15
15
  id: { value: id, configurable: true },
16
- execute: { configurable: true, value: (input) => {
16
+ execute: {
17
+ configurable: true,
18
+ value: (input) => {
17
19
  if (list.get(id)?.internal)
18
20
  throw new Error(`Internal Action "${id}" is not publicly accessible.`);
19
21
  return list.execute(id, input);
20
- } },
22
+ },
23
+ },
21
24
  });
22
25
  const reference = new Proxy(target, {
23
26
  get(target, name, receiver) {
@@ -28,8 +31,10 @@ export function createActionReference(list, id, children) {
28
31
  return children.get(name);
29
32
  },
30
33
  ownKeys: children.keys,
31
- getOwnPropertyDescriptor: (target, name) => Reflect.getOwnPropertyDescriptor(target, name)
32
- ?? (typeof name === 'string' && children.keys().includes(name) ? { enumerable: true, configurable: true } : undefined),
34
+ getOwnPropertyDescriptor: (target, name) => Reflect.getOwnPropertyDescriptor(target, name) ??
35
+ (typeof name === 'string' && children.keys().includes(name)
36
+ ? { enumerable: true, configurable: true }
37
+ : undefined),
33
38
  set: () => false,
34
39
  defineProperty: () => false,
35
40
  deleteProperty: () => false,
@@ -42,6 +42,10 @@ export interface ActionDefinition extends RegistrationOptions {
42
42
  internal?: boolean;
43
43
  /** Opaque, immutable host metadata. The core never interprets it. */
44
44
  metadata?: unknown;
45
+ /** `exclusive` (default) skips while running; `per-input` tracks each input; `latest` aborts the previous run. */
46
+ concurrency?: 'exclusive' | 'per-input' | 'latest';
47
+ /** Key for `per-input` pending when the input is not a primitive. */
48
+ concurrencyKey?: (input: any) => string;
45
49
  }
46
50
  export type ActionPresentation = Partial<Pick<ActionDefinition, 'title' | 'description' | 'tooltip' | 'icon' | 'href' | 'enabled' | 'visible' | 'checked' | 'value' | 'variant'>>;
47
51
  export type ActionPatch = Partial<Omit<ActionDefinition, 'id'>>;
@@ -49,6 +53,8 @@ export type ActionSnapshot = Readonly<Omit<ActionDefinition, 'enabled' | 'visibl
49
53
  enabled: boolean;
50
54
  visible: boolean;
51
55
  pending: boolean;
56
+ /** Inputs currently running, by concurrency key; `*` for exclusive actions. */
57
+ pendingKeys: readonly string[];
52
58
  status: ActionStatus;
53
59
  error?: unknown;
54
60
  state: unknown;
@@ -61,6 +67,8 @@ export interface ActionContext<Input = unknown> {
61
67
  get(): ActionSnapshot | undefined;
62
68
  /** Optional host dependency injection, owned by this list (never global). */
63
69
  readonly environment: unknown;
70
+ /** Aborts when the registration is disposed or a newer `latest` run supersedes this one. */
71
+ readonly signal: AbortSignal;
64
72
  /** Updates only this registration, even if the handler finishes after replacement. */
65
73
  update(patch: ActionPatch): boolean;
66
74
  }
@@ -78,7 +86,7 @@ export type ExecutionResult<Value = unknown> = {
78
86
  value: Value;
79
87
  } | {
80
88
  status: 'skipped';
81
- reason: 'missing' | 'disabled' | 'hidden' | 'pending' | 'no-handler' | 'intercepted' | 'replaced';
89
+ reason: 'missing' | 'disabled' | 'hidden' | 'pending' | 'no-handler' | 'intercepted' | 'cancelled' | 'replaced';
82
90
  };
83
91
  /**
84
92
  * Registry of known action IDs with their input and result types. Build tooling augments it
@@ -1,4 +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;
1
+ import type { BitaKitRuntime } from '../runtime.js';
2
+ import type { BitaKitApp } from './types.js';
3
+ /** Projects the runtime onto the app facade. Nothing is copied; every read is live. */
4
+ export declare function createBitaKitApp(runtime: BitaKitRuntime): BitaKitApp;
@@ -1,75 +1,36 @@
1
- import { FoundationServiceError } from './service-error.js';
1
+ import { BitaKitServiceError } from './service-error.js';
2
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)
3
+ /** Projects the runtime onto the app facade. Nothing is copied; every read is live. */
4
+ export function createBitaKitApp(runtime) {
5
+ // Before mount every service read explains that the runtime is not ready yet.
6
+ const services = new Proxy(Object.create(null), {
7
+ get(_target, name, receiver) {
8
+ if (typeof name !== 'string' || name === 'then' || name === 'toJSON')
33
9
  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', 'events', '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
- }
10
+ const tree = runtime.servicesIfMounted();
11
+ if (!tree)
12
+ throw new BitaKitServiceError(name, 'not-ready');
13
+ return Reflect.get(tree, name, receiver);
14
+ },
15
+ has: (_target, name) => {
16
+ const tree = runtime.servicesIfMounted();
17
+ return !!tree && typeof name === 'string' && name in tree;
18
+ },
19
+ ownKeys: () => {
20
+ const tree = runtime.servicesIfMounted();
21
+ return tree ? Reflect.ownKeys(tree) : [];
22
+ },
23
+ getOwnPropertyDescriptor: (_target, name) => {
24
+ const tree = runtime.servicesIfMounted();
25
+ return tree ? Reflect.getOwnPropertyDescriptor(tree, name) : undefined;
26
+ },
27
+ set: () => false,
28
+ defineProperty: () => false,
29
+ deleteProperty: () => false,
30
+ });
70
31
  return Object.freeze({
71
- ...extensions,
72
- events: runtime.events,
32
+ // The facade cannot emit: only the declaring plugin emits, through its scoped bus.
33
+ events: Object.freeze({ on: runtime.events.on.bind(runtime.events) }),
73
34
  actions: createActionAccess(runtime.actions),
74
35
  get config() {
75
36
  return Object.freeze(Object.fromEntries(runtime.modules.map((module) => [
@@ -77,10 +38,11 @@ export function createFoundationApp(runtime) {
77
38
  runtime.configuration.plugin(module.id).snapshot(),
78
39
  ])));
79
40
  },
80
- services: project(tree, false),
41
+ services,
42
+ settings: runtime.settingsAccess,
81
43
  get ready() {
82
44
  return runtime.isReady();
83
45
  },
84
- optional: Object.freeze({ services: project(tree, true) }),
46
+ has: (service) => runtime.isServiceReady(service),
85
47
  });
86
48
  }
@@ -1,4 +1,4 @@
1
1
  import type { ActionList } from '../actions/action-list.js';
2
- import type { FoundationActions } from './types.js';
2
+ import type { BitaKitActions } from './types.js';
3
3
  /** Projects dotted IDs onto stable handles; enumeration reads only current public registrations. */
4
- export declare function createActionAccess(list: ActionList): FoundationActions;
4
+ export declare function createActionAccess(list: ActionList): BitaKitActions;
@@ -8,10 +8,12 @@ export function createActionAccess(list) {
8
8
  return cached;
9
9
  const prefix = path ? `${path}.` : '';
10
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),
11
+ get: (name) => at(`${prefix}${name}`),
12
+ keys: () => [
13
+ ...new Set(Object.values(list.getState().actions)
14
+ .filter((action) => !action.internal && action.id.startsWith(prefix))
15
+ .map((action) => action.id.slice(prefix.length).split('.')[0])),
16
+ ].filter(Boolean),
15
17
  });
16
18
  references.set(path, reference);
17
19
  return reference;
@@ -1,8 +1,8 @@
1
1
  /** Structured diagnostics for unavailable public services, without guessing installation state. */
2
- export declare class FoundationServiceError extends Error {
2
+ export declare class BitaKitServiceError extends Error {
3
3
  readonly service: string;
4
4
  readonly reason: 'not-ready' | 'missing' | 'unregistered';
5
5
  readonly plugin?: string | undefined;
6
- readonly code = "FOUNDATION_SERVICE_UNAVAILABLE";
6
+ readonly code = "BITAKIT_SERVICE_UNAVAILABLE";
7
7
  constructor(service: string, reason: 'not-ready' | 'missing' | 'unregistered', plugin?: string | undefined);
8
8
  }
@@ -1,19 +1,23 @@
1
1
  /** Structured diagnostics for unavailable public services, without guessing installation state. */
2
- export class FoundationServiceError extends Error {
2
+ export class BitaKitServiceError extends Error {
3
3
  service;
4
4
  reason;
5
5
  plugin;
6
- code = 'FOUNDATION_SERVICE_UNAVAILABLE';
6
+ code = 'BITAKIT_SERVICE_UNAVAILABLE';
7
7
  constructor(service, reason, plugin) {
8
8
  const detail = reason === 'not-ready'
9
- ? 'The Foundation runtime is not mounted. Read optional services or wait for app.ready.'
9
+ ? 'The BitaKit runtime is not mounted. Read optional services or wait for app.ready.'
10
10
  : reason === 'missing'
11
- ? `Plugin "${plugin}" does not provide its declared service. Check its service configuration.`
11
+ ? plugin
12
+ ? `Plugin "${plugin}" does not provide its declared service. Check its service configuration.`
13
+ : // The service tree knows the declaration but not its owner: usually a read during
14
+ // creation, before the declared service exists (creation order follows `requires`).
15
+ `It is declared but has not been created. A service that reads it while it is being created must list it in requires: ["${service}"]; otherwise check that its plugin started without errors.`
12
16
  : 'No active plugin exposes this service. Check that the providing plugin is included and enabled.';
13
- super(`Foundation service "${service}" is unavailable. ${detail}`);
17
+ super(`BitaKit service "${service}" is unavailable. ${detail}`);
14
18
  this.service = service;
15
19
  this.reason = reason;
16
20
  this.plugin = plugin;
17
- this.name = 'FoundationServiceError';
21
+ this.name = 'BitaKitServiceError';
18
22
  }
19
23
  }