@bitakit/core 0.1.2 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (157) hide show
  1. package/README.md +44 -207
  2. package/discovery/index.d.ts +1 -41
  3. package/discovery/index.mjs +1 -4
  4. package/dist/actions/action-list.d.ts +4 -0
  5. package/dist/actions/action-list.js +58 -16
  6. package/dist/actions/action.d.ts +2 -0
  7. package/dist/actions/action.js +4 -0
  8. package/dist/actions/brand.d.ts +21 -0
  9. package/dist/actions/brand.js +36 -0
  10. package/dist/actions/core.d.ts +4 -3
  11. package/dist/actions/core.js +4 -2
  12. package/dist/actions/execution.d.ts +2 -2
  13. package/dist/actions/execution.js +61 -9
  14. package/dist/actions/feedback.d.ts +2 -0
  15. package/dist/actions/feedback.js +8 -0
  16. package/dist/actions/groups.js +5 -1
  17. package/dist/actions/instance-bindings.js +3 -2
  18. package/dist/actions/interceptors.d.ts +9 -3
  19. package/dist/actions/interceptors.js +31 -3
  20. package/dist/actions/navigation.d.ts +2 -1
  21. package/dist/actions/navigation.js +10 -5
  22. package/dist/actions/reference.js +10 -5
  23. package/dist/actions/types.d.ts +9 -1
  24. package/dist/app/access.d.ts +4 -4
  25. package/dist/app/access.js +33 -71
  26. package/dist/app/action-access.d.ts +2 -2
  27. package/dist/app/action-access.js +6 -4
  28. package/dist/app/service-error.d.ts +2 -2
  29. package/dist/app/service-error.js +10 -6
  30. package/dist/app/types.d.ts +76 -33
  31. package/dist/config-service.d.ts +30 -6
  32. package/dist/config-service.js +25 -9
  33. package/dist/configuration.d.ts +6 -3
  34. package/dist/configuration.js +8 -6
  35. package/dist/contracts.d.ts +4 -2
  36. package/dist/contracts.js +3 -3
  37. package/dist/contribution-origin.d.ts +4 -1
  38. package/dist/contribution-origin.js +14 -1
  39. package/dist/contributions/action.d.ts +26 -0
  40. package/dist/contributions/action.js +171 -0
  41. package/dist/contributions/host.d.ts +14 -11
  42. package/dist/contributions/index.d.ts +1 -26
  43. package/dist/contributions/index.js +1 -18
  44. package/dist/conventions.d.ts +8 -4
  45. package/dist/conventions.js +12 -31
  46. package/dist/core.d.ts +41 -18
  47. package/dist/core.js +25 -13
  48. package/dist/definitions.d.ts +272 -306
  49. package/dist/definitions.js +28 -56
  50. package/dist/destinations.d.ts +25 -0
  51. package/dist/destinations.js +21 -0
  52. package/dist/discovered.d.ts +52 -21
  53. package/dist/discovered.js +89 -35
  54. package/dist/events/define.d.ts +43 -0
  55. package/dist/events/define.js +17 -0
  56. package/dist/events/service.d.ts +35 -8
  57. package/dist/events/service.js +184 -42
  58. package/dist/events/types.d.ts +29 -9
  59. package/dist/inspection/inventory.d.ts +86 -0
  60. package/dist/inspection/inventory.js +132 -0
  61. package/dist/interceptors/define.d.ts +76 -0
  62. package/dist/interceptors/define.js +23 -0
  63. package/dist/interceptors/service-observers.d.ts +6 -3
  64. package/dist/interceptors/service-observers.js +13 -10
  65. package/dist/lifecycle/cleanup.d.ts +5 -0
  66. package/dist/lifecycle/cleanup.js +41 -0
  67. package/dist/lifecycle/controller.d.ts +82 -0
  68. package/dist/lifecycle/controller.js +276 -0
  69. package/dist/lifecycle/reconcile.d.ts +19 -0
  70. package/dist/lifecycle/reconcile.js +68 -0
  71. package/dist/lifecycle/state.d.ts +53 -0
  72. package/dist/lifecycle/state.js +86 -0
  73. package/dist/names.d.ts +10 -0
  74. package/dist/names.js +1 -0
  75. package/dist/pages.d.ts +39 -6
  76. package/dist/pages.js +93 -11
  77. package/dist/presentation.d.ts +9 -0
  78. package/dist/runtime.d.ts +166 -28
  79. package/dist/runtime.js +1485 -248
  80. package/dist/schema.d.ts +13 -0
  81. package/dist/schema.js +38 -0
  82. package/dist/scope.d.ts +59 -4
  83. package/dist/scope.js +133 -11
  84. package/dist/service-key.d.ts +33 -14
  85. package/dist/service-key.js +21 -5
  86. package/dist/service-names.d.ts +39 -0
  87. package/dist/service-names.js +175 -0
  88. package/dist/services.d.ts +24 -5
  89. package/dist/services.js +230 -37
  90. package/dist/settings/access.d.ts +19 -0
  91. package/dist/settings/access.js +78 -0
  92. package/dist/settings/define.d.ts +97 -0
  93. package/dist/settings/define.js +83 -0
  94. package/dist/settings/storage.d.ts +45 -0
  95. package/dist/settings/storage.js +102 -0
  96. package/dist/settings/store.d.ts +74 -0
  97. package/dist/settings/store.js +345 -0
  98. package/dist/slots/action-placement.d.ts +47 -0
  99. package/dist/slots/action-placement.js +1 -0
  100. package/dist/slots/define.d.ts +52 -0
  101. package/dist/slots/define.js +12 -0
  102. package/dist/slots/normalize.d.ts +7 -0
  103. package/dist/slots/normalize.js +36 -0
  104. package/dist/slots/runtime.d.ts +43 -0
  105. package/dist/slots/runtime.js +348 -0
  106. package/dist/slots/types.d.ts +113 -0
  107. package/dist/slots/types.js +1 -0
  108. package/dist/startup-error.d.ts +21 -0
  109. package/dist/startup-error.js +29 -0
  110. package/dist/store.d.ts +24 -0
  111. package/dist/store.js +40 -0
  112. package/dist/translation.d.ts +9 -4
  113. package/dist/translation.js +2 -3
  114. package/examples/todos/actions/create.mjs +1 -3
  115. package/examples/todos/actions/delete.mjs +3 -10
  116. package/examples/todos/actions/list.mjs +1 -3
  117. package/examples/todos/events.mjs +5 -0
  118. package/examples/todos/plugin.mjs +4 -2
  119. package/examples/todos/services/tasks.mjs +14 -20
  120. package/examples/todos.mjs +8 -7
  121. package/package.json +36 -9
  122. package/testing/index.d.ts +59 -0
  123. package/testing/index.mjs +150 -0
  124. package/assets/bitakit-banner.png +0 -0
  125. package/discovery/entries.mjs +0 -124
  126. package/discovery/generate.mjs +0 -321
  127. package/discovery/host.mjs +0 -12
  128. package/discovery/modules.mjs +0 -13
  129. package/discovery/packages.mjs +0 -57
  130. package/discovery/watch.mjs +0 -23
  131. package/dist/app/service-aliases.d.ts +0 -4
  132. package/dist/app/service-aliases.js +0 -14
  133. package/dist/contributions/command.d.ts +0 -8
  134. package/dist/contributions/command.js +0 -59
  135. package/dist/contributions/dialog.d.ts +0 -8
  136. package/dist/contributions/dialog.js +0 -18
  137. package/dist/contributions/form.d.ts +0 -10
  138. package/dist/contributions/form.js +0 -67
  139. package/dist/contributions/native.d.ts +0 -11
  140. package/dist/contributions/native.js +0 -87
  141. package/dist/contributions/shared.d.ts +0 -19
  142. package/dist/contributions/shared.js +0 -48
  143. package/dist/contributions/stateful-action.d.ts +0 -29
  144. package/dist/contributions/stateful-action.js +0 -33
  145. package/dist/events/action-setup.d.ts +0 -19
  146. package/dist/events/action-setup.js +0 -24
  147. package/dist/interceptors/service.d.ts +0 -37
  148. package/dist/interceptors/service.js +0 -7
  149. package/dist/replacements.d.ts +0 -22
  150. package/dist/replacements.js +0 -54
  151. package/dist/validation.d.ts +0 -2
  152. package/dist/validation.js +0 -16
  153. package/docs/auth.md +0 -106
  154. package/docs/events.md +0 -157
  155. package/docs/file-contributions.md +0 -174
  156. package/docs/reference.md +0 -404
  157. package/docs/todo-tutorial.md +0 -88
package/README.md CHANGED
@@ -1,31 +1,12 @@
1
1
  <p align="center">
2
- <img src="https://cdn.jsdelivr.net/npm/@bitakit/core@0.1.2/assets/bitakit-banner.png" alt="BitaKit — Your app. Your building blocks. An AI-friendly composition layer for modern applications." width="1024">
2
+ <img src="https://raw.githubusercontent.com/mvavesal/bitakit/main/docs/assets/readme/bitakit-banner.png" alt="BitaKit — Your app. Your building blocks. An AI-friendly composition layer for modern applications." width="1024">
3
3
  </p>
4
4
 
5
5
  # BitaKit Core
6
6
 
7
- **Build bigger apps from smaller, pluggable features — together with your team and AI.**
8
-
9
- BitaKit gives **developers and AI coding assistants a shared structure** for building
10
- applications. Organize a feature into a plugin, put reusable behavior in services,
11
- and expose operations through actions. Each piece has a clear home, a clear role,
12
- and typed connections to the rest of your app.
13
-
14
- **Keep Next.js, TanStack Start, or your own stack.** BitaKit adds feature organization
15
- and shared lifecycle management alongside your framework. You keep control of your
16
- routes, UI, business rules, and data.
17
-
18
- ## Contents
19
-
20
- - [Install](#install)
21
- - [Why add BitaKit?](#why-add-bitakit)
22
- - [How the pieces fit](#how-the-pieces-fit)
23
- - [Try a To-do plugin](#try-a-to-do-plugin)
24
- - [Type safety that follows your feature](#type-safety-that-follows-your-feature)
25
- - [React to events](#react-to-events)
26
- - [What belongs outside Core?](#what-belongs-outside-core)
27
- - [Go deeper](#go-deeper)
28
- - [License](#license)
7
+ Framework-independent plugins, services, Actions, events, settings and lifecycle management.
8
+ Core works in Node.js and the browser without React or a router. React bindings, discovery,
9
+ visual plugins and provider integrations are separate packages.
29
10
 
30
11
  ## Install
31
12
 
@@ -33,199 +14,55 @@ routes, UI, business rules, and data.
33
14
  npm install @bitakit/core
34
15
  ```
35
16
 
36
- Core works in **Node.js and the browser**, without React or a router.
37
-
38
- Starting a new application? Let the generator connect the packages for you:
39
-
40
- ```sh
41
- npx @bitakit/create-app my-app
42
- ```
43
-
44
- The generator requires Node.js 24 or newer. Choose Next.js or experimental TanStack
45
- Start, then select the optional features you want. React bindings and framework
46
- adapters are available as separate packages.
47
-
48
- ## Why add BitaKit?
49
-
50
- Your framework handles pages and rendering. As an app grows, you also need a clear
51
- way to organize features, share behavior, connect dependencies, and clean up resources.
52
- BitaKit gives those pieces a common structure.
53
-
54
- - **Smaller pieces. Clearer ownership.** Keep a feature's services and actions together
55
- in a plugin. Teams can work on focused parts of the app with explicit connections
56
- between them.
57
- - **A shared language for humans and AI.** Predictable files and typed contracts make
58
- it easier to describe a change, give an AI assistant focused context, and review
59
- its work. The same conventions guide both developers and coding assistants.
60
- - **Pluggable features.** Compose the capabilities your app needs. Add a plugin,
61
- configure its defaults, or replace supported contributions through the same APIs.
62
- - **Less repeated wiring.** With discovery configured, file paths supply names and
63
- generated types. Core handles startup, dependencies, registration, and cleanup.
64
- - **Type-safe connections.** Service methods, action inputs and results, and known
65
- event payloads carry their types to callers. Your editor helps you connect the pieces.
66
- - **Your stack stays yours.** Start with headless Core. Add React bindings, settings,
67
- an app shell, or provider integrations when they help your product.
68
-
69
- **Room to grow.** As your app and team grow, keep changes focused on small features
70
- with explicit dependencies. This is about scaling your codebase and collaboration;
71
- performance and infrastructure remain choices for your application.
72
-
73
- ## How the pieces fit
74
-
75
- Imagine a **To-do plugin** that lets someone add a task:
76
-
77
- ```text
78
- Application — chooses which plugins to use
79
- │
80
- ▼
81
- BitaKit Core — starts plugins and checks their dependencies
82
- │
83
- └── To-do plugin — groups one feature's contributions
84
- ├── Service: holds tasks and provides add/list operations
85
- └── Action: calls the service to add a task
86
-
87
- Button or server code
88
- │ executes "todos.create"
89
- ▼
90
- Action ──calls──▶ To-do service ──returns──▶ Task
91
-
92
- Application UI displays the result; Core does not render it.
93
- ```
94
-
95
- | Concept | What it does | In this example |
96
- | ---------------- | ------------------------------------------------------------------- | ------------------------------------------------- |
97
- | **Plugin** | Bundles the parts of a feature. | The To-do feature. |
98
- | **Service** | Owns reusable behavior and, when needed, state or resources. | Stores tasks and exposes `create()` and `list()`. |
99
- | **Action** | Provides a named operation that application code or UI can execute. | `todos.create` adds a task through the service. |
100
- | **Core runtime** | Coordinates dependencies, registrations, startup, and cleanup. | Creates the service and registers the action. |
101
-
102
- Core manages the lifecycle of plugin-created services. A service that acquires
103
- resources can supply disposal logic. Core does not automatically save data to a
104
- database or subscribe your UI to service changes.
105
-
106
- ## Try a To-do plugin
107
-
108
- Follow the [To-do tutorial](https://cdn.jsdelivr.net/npm/@bitakit/core@0.1.2/docs/todo-tutorial.md) to run three actions: create a
109
- task, list tasks, and delete a task. Each action lives in its own file:
110
-
111
- ```text
112
- examples/
113
- ├── todos.mjs # Starts the runtime and executes the actions
114
- └── todos/
115
- ├── plugin.mjs # Groups the service and actions
116
- ├── services/
117
- │ └── tasks.mjs # In-memory task operations
118
- └── actions/
119
- ├── create.mjs # todos.create
120
- ├── list.mjs # todos.list
121
- └── delete.mjs # todos.delete
122
- ```
123
-
124
- The plugin uses explicit imports, so no framework or discovery setup is required.
125
- The script creates three tasks, lists them, deletes the second, and lists the two
126
- remaining tasks. Stopping the runtime releases its registrations. Data stays in
127
- memory and is lost on restart.
128
-
129
- With a configured framework adapter, contribution files can instead live under
130
- `src/plugins/todos/services` and `src/plugins/todos/actions`. Its build integration
131
- generates registration and types. Installing Core alone does not scan folders.
132
- See [file contributions](https://cdn.jsdelivr.net/npm/@bitakit/core@0.1.2/docs/file-contributions.md) for the exact conventions.
133
-
134
- ## Type safety that follows your feature
135
-
136
- Define a service once, then use its method types wherever you call it. Discovery
137
- connects supported files to typed service access, action IDs, and configuration.
138
- Shared service keys let separate packages agree on the same contract.
17
+ For a new application, `npx @bitakit/create-app my-app` connects the packages for you
18
+ (Node.js 24 or newer). The handbook describes the 0.2 API in this checkout; use matching
19
+ package versions or the [local package workflow](../../apps/docs/content/docs/local-development.mdx)
20
+ when trying unpublished changes.
139
21
 
140
- Use `exposeAs` when you want a custom public service name; otherwise discovery uses
141
- the file path. Known event names and payloads are connected through `EventMap`.
22
+ ## Start with one service
142
23
 
143
- Unknown action IDs remain allowed unless strict mode is enabled. TypeScript checks
144
- code; validate external data and authorize requests at your application boundaries.
145
- See the [type-safety guide](https://cdn.jsdelivr.net/npm/@bitakit/core@0.1.2/docs/reference.md)
146
- for examples.
147
-
148
- ## React to events
149
-
150
- Available since Core 0.1.1, each runtime owns one event service. Services emit
151
- notifications after updating their data; actions declare `events` and `onEvent`.
152
-
153
- With file discovery configured, IDs can be omitted:
24
+ In a discovery-enabled app, create `src/plugins/counter/services/value.ts`:
154
25
 
155
26
  ```ts
156
- // src/services/todos.ts
157
27
  import { defineService } from '@bitakit/core';
158
28
 
159
- export default defineService({
160
- create({ events }) {
161
- let items: { id: number; title: string }[] = [];
162
- let nextId = 1;
163
- return {
164
- list: () => [...items],
165
- add(title: string) {
166
- const todo = { id: nextId++, title };
167
- items.push(todo);
168
- events.emit('todos.changed', { kind: 'added', id: todo.id });
169
- },
170
- remove(id: number) {
171
- items = items.filter((todo) => todo.id !== id);
172
- events.emit('todos.changed', { kind: 'removed', id });
173
- },
174
- };
175
- },
176
- });
177
- ```
178
-
179
- ```ts
180
- // src/actions/todos/delete.ts
181
- import { defineAction } from '@bitakit/core';
182
-
183
- export default defineAction<number>({
184
- requires: ['todos'],
185
- events: ['todos.changed'],
186
- setup({ services, action }) {
187
- action.enabled = services.todos.list().length > 0;
188
- },
189
- onEvent(event, { services, action }) {
190
- action.enabled = services.todos.list().length > 0;
191
- },
192
- execute: ({ services, input }) => services.todos.remove(input),
29
+ export default defineService(({ store }) => {
30
+ const state = store({ count: 0 });
31
+ return { state, increment: () => state.set((s) => ({ count: s.count + 1 })) };
193
32
  });
194
33
  ```
195
34
 
196
- Here discovery supplies `todos` and `todos.delete` from the paths (with no explicit
197
- app namespace). Plugin contributions also receive their plugin namespace. Provide
198
- an explicit `id` when you need a custom identity. Direct imports without discovery,
199
- including the Node tutorial above, still need explicit IDs.
200
-
201
- `events: ['todos.loaded', 'todos.changed']` calls `onEvent` for
202
- **each** matching event. Handlers receive `{ type, data }` and can be synchronous or
203
- asynchronous. Core owns subscriptions created in action `setup` and service
204
- `create`, including cleanup after failed setup. No manual unsubscribe is needed.
205
- For dynamic subscriptions, `setup` still offers `events.watch`. React components use `useWatchEvent` from `@bitakit/ui`.
206
-
207
- See [events and action setup](https://cdn.jsdelivr.net/npm/@bitakit/core@0.1.2/docs/events.md) for payload typing, errors, async
208
- cancellation, and the distinction from observable-service `watch`.
209
-
210
- ## What belongs outside Core?
211
-
212
- - **React rendering:** the UI bindings and your visual components.
213
- - **Routes and navigation:** your application's router and its BitaKit adapter.
214
- - **Settings:** the separate App Preferences package.
215
- - **Email, authentication, and persistence:** optional integrations or your own services.
216
-
217
- Plugins are trusted application code. Core is not a sandbox or a remote plugin marketplace.
218
-
219
- ## Go deeper
220
-
221
- - [Runnable To-do example](https://cdn.jsdelivr.net/npm/@bitakit/core@0.1.2/examples/todos.mjs)
222
- - [Core reference](https://cdn.jsdelivr.net/npm/@bitakit/core@0.1.2/docs/reference.md): configuration, typed services, actions, lifecycle, and advanced integration.
223
- - [File contributions and configuration](https://cdn.jsdelivr.net/npm/@bitakit/core@0.1.2/docs/file-contributions.md): discovery and folder conventions.
224
- - [npm package](https://www.npmjs.com/package/@bitakit/core)
35
+ Discovery names it `counter.value`. Continue with the
36
+ [Counter learning path](../../apps/docs/content/docs/concepts/index.mdx)
37
+ to add an Action and a page. Installing Core alone does not scan folders or render UI.
38
+ For a headless program, follow [manual composition](../../apps/docs/content/docs/concepts/manual-composition.mdx).
39
+
40
+ ## Developer handbook
41
+
42
+ The handbook is maintained once in the documentation website's source. The links below
43
+ resolve within a repository checkout and follow the branch viewed on GitHub. Run
44
+ `npm run dev:docs` from the repository root to read the rendered handbook at
45
+ `http://localhost:3002/docs`. A public documentation address is not configured yet.
46
+
47
+ | Topic | Guide |
48
+ | --- | --- |
49
+ | Services and cleanup | [Service reference](../../apps/docs/content/docs/reference/services.mdx) |
50
+ | Actions and React bindings | [Action reference](../../apps/docs/content/docs/reference/actions.mdx) |
51
+ | Events and interception | [Events](../../apps/docs/content/docs/concepts/events.mdx), [Interceptors](../../apps/docs/content/docs/concepts/interceptors.mdx) |
52
+ | Files and developer configuration | [Discovery](../../apps/docs/content/docs/concepts/discovery.mdx), [Configuration](../../apps/docs/content/docs/concepts/configuration.mdx) |
53
+ | Extension points and preferences | [Slots](../../apps/docs/content/docs/reference/slots.mdx), [Settings](../../apps/docs/content/docs/reference/settings.mdx) |
54
+ | Runtime updates and diagnostics | [Runtime management](../../apps/docs/content/docs/concepts/runtime-management.mdx) |
55
+ | Enable, disable, add and remove plugins | [Plugin manager](../../apps/docs/content/docs/plugin-management.mdx) |
56
+ | Activate a trusted package catalog | [Package manager](../../apps/docs/content/docs/package-management.mdx) |
57
+ | Authentication contract | [Client authentication](../../apps/docs/content/docs/reference/authentication.mdx) |
58
+ | Test a plugin folder | [Testing](../../apps/docs/content/docs/reference/testing.mdx) |
59
+ | Standalone example | [To-do walkthrough](../../apps/docs/content/docs/concepts/tutorial.mdx); runnable JavaScript files in `examples/` |
60
+
61
+ Plugins are trusted application code. Core is not a sandbox, package installer or remote
62
+ marketplace. Services own state and resources; the host owns routing, persistence providers
63
+ and server authorization.
225
64
 
226
65
  ## License
227
66
 
228
- [MIT](https://cdn.jsdelivr.net/npm/@bitakit/core@0.1.2/LICENSE). Third-party dependencies retain their own licenses.
229
-
230
- See [client authentication](https://cdn.jsdelivr.net/npm/@bitakit/core@0.1.2/docs/auth.md) for the shared provider contract, externally
231
- configured login/logout paths, UI bindings and an adapter template.
67
+ [MIT](https://github.com/mvavesal/bitakit/blob/main/LICENSE). Third-party dependencies retain
68
+ their own licenses.
@@ -1,41 +1 @@
1
- /** An integration-defined contribution kind: folder inside each module root plus its normalizer. */
2
- export type ContributionKindSpec = {
3
- /** Kind name used in `contributions`, e.g. "settings.renderers". */
4
- name: string;
5
- /** Folder that identifies the kind inside every module root, e.g. "renderers". */
6
- directory: string;
7
- /** Module exporting the runtime normalizer; imported by the generated client file. */
8
- from: string;
9
- /** Normalizer export: (files, moduleId) => values. It validates and names source files in errors. */
10
- normalize: string;
11
- /** Optional package-owned type map populated from discovered files and module IDs. */
12
- types?: { entry: string; map: string };
13
- };
14
- export type DiscoveryConfig = {
15
- /** Installed opt-in packages are included by default; false disables all, or select by package name. */
16
- packages?: false | Readonly<Record<string, boolean>>;
17
- directory?: string;
18
- /** Contribution kinds provided by optional integrations. Discovery emits imports only. */
19
- kinds?: readonly ContributionKindSpec[];
20
- services?: false | { directory?: string };
21
- configs?: false | { directory?: string };
22
- configOverrides?: Record<string, Record<string, unknown>>;
23
- actions?:
24
- | false
25
- | { directory?: string; overrides?: Record<string, { enabled?: boolean; visible?: boolean }> };
26
- providers?: { directory?: string; enabled?: readonly string[] };
27
- interceptors?: { directory?: string; enabled?: readonly string[] };
28
- groups?: readonly string[];
29
- conventions?: boolean;
30
- plugins?: {
31
- directory: string;
32
- autoEnable?: boolean;
33
- overrides?: Record<string, { enabled: boolean }>;
34
- };
35
- };
36
- export function defineFoundation(config: DiscoveryConfig): DiscoveryConfig;
37
- export function generateFoundation(root: string): Promise<void>;
38
- export function watchFoundation(root: string, onError?: (error: unknown) => void): () => void;
39
-
40
- /** Generates contributions and the host compiler reference without framework imports. */
41
- export function generateFoundationHost(root: string): Promise<void>;
1
+ export * from '@bitakit/discovery';
@@ -1,4 +1 @@
1
- export { generateFoundation } from './generate.mjs';
2
- export { watchFoundation } from './watch.mjs';
3
- export const defineFoundation = (config) => config;
4
- export { generateFoundationHost } from './host.mjs';
1
+ export * from '@bitakit/discovery';
@@ -16,6 +16,7 @@ export declare function createActionList(initialActions?: readonly (ActionDefini
16
16
  enabled: boolean;
17
17
  visible: boolean;
18
18
  pending: boolean;
19
+ pendingKeys: readonly string[];
19
20
  status: ActionStatus;
20
21
  error?: unknown;
21
22
  state: unknown;
@@ -27,6 +28,7 @@ export declare function createActionList(initialActions?: readonly (ActionDefini
27
28
  id: string;
28
29
  groups: readonly import("./groups.js").ActionGroup<any>[] | undefined;
29
30
  pending: boolean;
31
+ pendingKeys: readonly string[];
30
32
  execute: import("./types.js").ActionHandler<unknown, unknown> | undefined;
31
33
  resolve: ((input: unknown) => import("./types.js").ActionPresentation) | undefined;
32
34
  enabled: boolean;
@@ -42,6 +44,8 @@ export declare function createActionList(initialActions?: readonly (ActionDefini
42
44
  state: unknown;
43
45
  internal?: boolean;
44
46
  metadata?: unknown;
47
+ concurrency?: "exclusive" | "per-input" | "latest";
48
+ concurrencyKey?: (input: any) => string;
45
49
  order?: number;
46
50
  dividerBefore?: boolean;
47
51
  status: ActionStatus;
@@ -6,6 +6,7 @@ import { createStore } from 'zustand/vanilla';
6
6
  import { NavigationHost, safeHref } from './navigation.js';
7
7
  import { InstanceBindings } from './instance-bindings.js';
8
8
  import { Action } from './action.js';
9
+ import { isBrandedInstance } from './brand.js';
9
10
  import { affectedActions, dependencyEnabled, freezeDependencies } from './dependencies.js';
10
11
  /** No global state. This can also be used outside React. */
11
12
  export function createActionList(initialActions = [], options = {}) {
@@ -51,26 +52,57 @@ export function createActionList(initialActions = [], options = {}) {
51
52
  return false;
52
53
  }
53
54
  };
55
+ // Unbound snapshots evaluate function-valued presentation without input; bound reads refine it.
56
+ const unbound = (action) => {
57
+ try {
58
+ return action.resolve?.(undefined) ?? {};
59
+ }
60
+ catch {
61
+ return {};
62
+ }
63
+ };
54
64
  for (const action of Object.values(definitions)) {
55
- next[action.id] =
56
- !affected.has(action.id) && previous[action.id]
57
- ? previous[action.id]
58
- : Object.freeze({
59
- ...action,
60
- ...options.project?.(action),
61
- enabled: action.enabled &&
62
- (action.dependsOn ?? []).every((id) => dependencyEnabled(id, definitions, prerequisiteEnabled, new Set([action.id]), cache)),
63
- });
65
+ if (!affected.has(action.id) && previous[action.id]) {
66
+ next[action.id] = previous[action.id];
67
+ continue;
68
+ }
69
+ const presentation = unbound(action);
70
+ const merged = {
71
+ ...action,
72
+ ...presentation,
73
+ id: action.id,
74
+ groups: action.groups,
75
+ resolve: action.resolve,
76
+ execute: action.execute,
77
+ };
78
+ next[action.id] = Object.freeze({
79
+ ...merged,
80
+ ...options.project?.(merged),
81
+ enabled: action.enabled &&
82
+ (presentation.enabled ?? true) &&
83
+ (action.dependsOn ?? []).every((id) => dependencyEnabled(id, definitions, prerequisiteEnabled, new Set([action.id]), cache)),
84
+ visible: action.visible && (presentation.visible ?? true),
85
+ });
64
86
  }
65
87
  store.setState({ actions: next });
66
88
  }
67
- function setPending(id, pending, status, error) {
89
+ const running = new Map();
90
+ function setPending(id, key, pending, status, error) {
68
91
  const action = source(id);
69
92
  if (!action)
70
93
  return;
94
+ const pendingKeys = pending
95
+ ? [...new Set([...action.pendingKeys, key])]
96
+ : action.pendingKeys.filter((item) => item !== key);
71
97
  definitions = {
72
98
  ...definitions,
73
- [id]: Object.freeze({ ...action, pending, status: status ?? action.status, error }),
99
+ [id]: Object.freeze({
100
+ ...action,
101
+ pending: pendingKeys.length > 0,
102
+ pendingKeys: Object.freeze(pendingKeys),
103
+ status: status ?? action.status,
104
+ error,
105
+ }),
74
106
  };
75
107
  publish(id);
76
108
  }
@@ -89,6 +121,7 @@ export function createActionList(initialActions = [], options = {}) {
89
121
  id: action.id,
90
122
  groups: action.groups,
91
123
  pending: action.pending,
124
+ pendingKeys: action.pendingKeys,
92
125
  execute: action.execute,
93
126
  resolve: action.resolve,
94
127
  enabled: dependencyEnabled(id, definitions, (item) => item.enabled &&
@@ -109,6 +142,7 @@ export function createActionList(initialActions = [], options = {}) {
109
142
  ...patch,
110
143
  id,
111
144
  pending: current.pending,
145
+ pendingKeys: current.pendingKeys,
112
146
  status: current.status,
113
147
  error: current.error,
114
148
  groups: freezeGroups(patch.groups ?? current.groups),
@@ -117,7 +151,7 @@ export function createActionList(initialActions = [], options = {}) {
117
151
  visible: patch.visible ?? current.visible,
118
152
  });
119
153
  if (next.href !== undefined && !safeHref(next.href))
120
- throw new Error('Invalid navigation target.');
154
+ throw new Error(`Action "${id}" has an invalid navigation target: ${String(next.href)}`);
121
155
  options.validate?.(next, store.getState().actions);
122
156
  bindings.apply(id, patch);
123
157
  definitions = { ...definitions, [id]: next };
@@ -125,7 +159,7 @@ export function createActionList(initialActions = [], options = {}) {
125
159
  return true;
126
160
  }
127
161
  function register(definition, placement = {}) {
128
- if (definition instanceof Action) {
162
+ if (definition instanceof Action || isBrandedInstance(definition, Action, 'action')) {
129
163
  if (!definition.id)
130
164
  throw new Error('Use add(id, action) for an action without an ID.');
131
165
  return add(definition.id, definition, placement);
@@ -133,7 +167,7 @@ export function createActionList(initialActions = [], options = {}) {
133
167
  if (disposed)
134
168
  throw new Error('Action list has been disposed.');
135
169
  if (!/^[a-zA-Z0-9][a-zA-Z0-9._:/-]*$/.test(definition.id)) {
136
- throw new Error('Action IDs must be nonempty and contain letters, numbers, dots, underscores, colons, slashes or hyphens.');
170
+ throw new Error(`Invalid action ID "${definition.id}". Use letters, numbers, dots, underscores, colons, slashes or hyphens.`);
137
171
  }
138
172
  const { id } = definition;
139
173
  if (owners.has(id))
@@ -147,6 +181,7 @@ export function createActionList(initialActions = [], options = {}) {
147
181
  enabled: definition.enabled ?? true,
148
182
  visible: definition.visible ?? true,
149
183
  pending: false,
184
+ pendingKeys: Object.freeze([]),
150
185
  status: ActionStatus.Idle,
151
186
  state: definition.initialState === undefined
152
187
  ? undefined
@@ -154,7 +189,7 @@ export function createActionList(initialActions = [], options = {}) {
154
189
  error: undefined,
155
190
  });
156
191
  if (action.href !== undefined && !safeHref(action.href))
157
- throw new Error('Invalid navigation target.');
192
+ throw new Error(`Action "${id}" has an invalid navigation target: ${String(action.href)}`);
158
193
  options.validate?.(action, store.getState().actions);
159
194
  owners.set(id, owner);
160
195
  definitions = { ...definitions, [id]: action };
@@ -182,6 +217,9 @@ export function createActionList(initialActions = [], options = {}) {
182
217
  const next = { ...definitions };
183
218
  delete next[id];
184
219
  definitions = next;
220
+ for (const controller of running.get(id)?.values() ?? [])
221
+ controller.abort();
222
+ running.delete(id);
185
223
  try {
186
224
  release(owner);
187
225
  }
@@ -205,7 +243,7 @@ export function createActionList(initialActions = [], options = {}) {
205
243
  unregister: bindings.attach(id, action, registration),
206
244
  };
207
245
  }
208
- const execute = createExecutor(setPending, owners, environment, get, resolve, update, lifecycle);
246
+ const execute = createExecutor(setPending, owners, environment, get, resolve, update, lifecycle, running);
209
247
  function dispose() {
210
248
  if (disposed)
211
249
  return;
@@ -225,6 +263,10 @@ export function createActionList(initialActions = [], options = {}) {
225
263
  errors.push(error);
226
264
  }
227
265
  }
266
+ for (const runs of running.values())
267
+ for (const controller of runs.values())
268
+ controller.abort();
269
+ running.clear();
228
270
  lifecycle.clear();
229
271
  owners.clear();
230
272
  placements.clear();
@@ -89,6 +89,8 @@ export declare class Action<Input = void, Result = unknown> {
89
89
  state?: unknown;
90
90
  internal?: boolean | undefined;
91
91
  metadata?: unknown;
92
+ concurrency?: "exclusive" | "per-input" | "latest" | undefined;
93
+ concurrencyKey?: ((input: any) => string) | undefined;
92
94
  groups?: readonly import("./groups.js").ActionGroup<any>[] | undefined;
93
95
  order?: number | undefined;
94
96
  dividerBefore?: boolean | undefined;
@@ -1,6 +1,10 @@
1
1
  import { safeHref } from './navigation.js';
2
+ import { brand } from './brand.js';
2
3
  /** Reusable behavior and observable presentation state. No registration or UI. */
3
4
  export class Action {
5
+ static {
6
+ brand(this, 'action');
7
+ }
4
8
  id;
5
9
  /**
6
10
  * Opt-in feedback for runtime-registered class actions. Undefined keeps the raw error for the
@@ -0,0 +1,21 @@
1
+ /**
2
+ * Identity checks that survive duplicate package copies. A linked plugin (npm link, `file:`) or a
3
+ * mismatched version can load a second copy of this package; `instanceof` then fails for values
4
+ * created by the other copy. Each class marks its prototype with a global symbol instead.
5
+ */
6
+ declare const brands: {
7
+ readonly action: symbol;
8
+ readonly group: symbol;
9
+ readonly failure: symbol;
10
+ readonly navigation: symbol;
11
+ };
12
+ export type Brand = keyof typeof brands;
13
+ /** Marks a class prototype; subclasses inherit the marker through the prototype chain. */
14
+ export declare function brand(target: {
15
+ prototype: object;
16
+ }, name: Brand): void;
17
+ /** True for instances of `Class` from this copy, or branded instances from another copy. */
18
+ export declare function isBrandedInstance<T>(value: unknown, Class: abstract new (...args: any[]) => T, name: Brand): value is T;
19
+ /** True when a constructor's prototype chain carries the marker, from any package copy. */
20
+ export declare function isBrandedClass(value: unknown, name: Brand): boolean;
21
+ export {};
@@ -0,0 +1,36 @@
1
+ /**
2
+ * Identity checks that survive duplicate package copies. A linked plugin (npm link, `file:`) or a
3
+ * mismatched version can load a second copy of this package; `instanceof` then fails for values
4
+ * created by the other copy. Each class marks its prototype with a global symbol instead.
5
+ */
6
+ const brands = {
7
+ action: Symbol.for('bitakit.core.Action'),
8
+ group: Symbol.for('bitakit.core.ActionGroup'),
9
+ failure: Symbol.for('bitakit.core.ActionFailure'),
10
+ navigation: Symbol.for('bitakit.core.NavigationHost'),
11
+ };
12
+ /** Marks a class prototype; subclasses inherit the marker through the prototype chain. */
13
+ export function brand(target, name) {
14
+ Object.defineProperty(target.prototype, brands[name], { value: true });
15
+ }
16
+ let warned = false;
17
+ /** True for instances of `Class` from this copy, or branded instances from another copy. */
18
+ export function isBrandedInstance(value, Class, name) {
19
+ if (value instanceof Class)
20
+ return true;
21
+ if (typeof value !== 'object' || value === null || value[brands[name]] !== true)
22
+ return false;
23
+ if (!warned) {
24
+ warned = true;
25
+ console.warn('[bitakit] Found a value created by a second copy of @bitakit/core. Declare @bitakit/core ' +
26
+ 'as a peerDependency in plugin packages and keep one installed version.');
27
+ }
28
+ return true;
29
+ }
30
+ /** True when a constructor's prototype chain carries the marker, from any package copy. */
31
+ export function isBrandedClass(value, name) {
32
+ return (typeof value === 'function' &&
33
+ typeof value.prototype === 'object' &&
34
+ value.prototype !== null &&
35
+ value.prototype[brands[name]] === true);
36
+ }
@@ -5,10 +5,11 @@ export { createActionList } from './action-list.js';
5
5
  export type { ActionList } from './action-list.js';
6
6
  export type * from './types.js';
7
7
  export { URLAction } from './base/url-action.js';
8
- export { NavigationHost, safeHref } from './navigation.js';
8
+ export { NavigationHost, safeHref, navigate } from './navigation.js';
9
9
  export { ActionGroup } from './groups.js';
10
10
  export type { RegistrationOptions } from './groups.js';
11
- export type { ActionInterceptor, ExecutionEvent } from './interceptors.js';
12
- export { ActionFailure } from './feedback.js';
11
+ export { CANCEL, type ActionInterceptor, type ExecutionEvent } from './interceptors.js';
12
+ export { ActionFailure, isActionFailure } from './feedback.js';
13
+ export { isBrandedInstance, isBrandedClass, type Brand } from './brand.js';
13
14
  export type { Feedback, FeedbackMessage, FeedbackResult, MessageValues } from './feedback.js';
14
15
  export { ActionStatus, type ActionStateValue } from './state.js';
@@ -2,7 +2,9 @@ export { Action } from './action.js';
2
2
  export { resolveActionId } from './reference.js';
3
3
  export { createActionList } from './action-list.js';
4
4
  export { URLAction } from './base/url-action.js';
5
- export { NavigationHost, safeHref } from './navigation.js';
5
+ export { NavigationHost, safeHref, navigate } from './navigation.js';
6
6
  export { ActionGroup } from './groups.js';
7
- export { ActionFailure } from './feedback.js';
7
+ export { CANCEL } from './interceptors.js';
8
+ export { ActionFailure, isActionFailure } from './feedback.js';
9
+ export { isBrandedInstance, isBrandedClass } from './brand.js';
8
10
  export { ActionStatus } from './state.js';
@@ -1,4 +1,4 @@
1
1
  import { ActionStatus } from './state.js';
2
2
  import type { ActionSnapshot, ActionPatch, ExecutionResult } from './types.js';
3
- import type { ExecutionLifecycle } from './interceptors.js';
4
- export declare function createExecutor(setPending: (id: string, pending: boolean, status?: ActionStatus, error?: unknown) => void, owners: Map<string, symbol>, environment: unknown, get: (id: string) => ActionSnapshot | undefined, resolve: (id: string, input?: unknown) => ActionSnapshot | undefined, update: (id: string, patch: ActionPatch) => boolean, lifecycle: ExecutionLifecycle): (id: string, input?: unknown) => Promise<ExecutionResult>;
3
+ import { type ExecutionLifecycle } from './interceptors.js';
4
+ export declare function createExecutor(setPending: (id: string, key: string, pending: boolean, status?: ActionStatus, error?: unknown) => void, owners: Map<string, symbol>, environment: unknown, get: (id: string) => ActionSnapshot | undefined, resolve: (id: string, input?: unknown) => ActionSnapshot | undefined, update: (id: string, patch: ActionPatch) => boolean, lifecycle: ExecutionLifecycle, running: Map<string, Map<string, AbortController>>): (id: string, input?: unknown) => Promise<ExecutionResult>;