@bitakit/core 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (158) hide show
  1. package/README.md +47 -161
  2. package/assets/bitakit-logo-dark.svg +11 -0
  3. package/assets/bitakit-logo.svg +11 -0
  4. package/discovery/index.d.ts +1 -41
  5. package/discovery/index.mjs +1 -4
  6. package/dist/actions/action-list.d.ts +4 -0
  7. package/dist/actions/action-list.js +58 -16
  8. package/dist/actions/action.d.ts +2 -0
  9. package/dist/actions/action.js +4 -0
  10. package/dist/actions/brand.d.ts +21 -0
  11. package/dist/actions/brand.js +36 -0
  12. package/dist/actions/core.d.ts +4 -3
  13. package/dist/actions/core.js +4 -2
  14. package/dist/actions/execution.d.ts +2 -2
  15. package/dist/actions/execution.js +61 -9
  16. package/dist/actions/feedback.d.ts +2 -0
  17. package/dist/actions/feedback.js +8 -0
  18. package/dist/actions/groups.js +5 -1
  19. package/dist/actions/instance-bindings.js +3 -2
  20. package/dist/actions/interceptors.d.ts +9 -3
  21. package/dist/actions/interceptors.js +31 -3
  22. package/dist/actions/navigation.d.ts +2 -1
  23. package/dist/actions/navigation.js +10 -5
  24. package/dist/actions/reference.js +10 -5
  25. package/dist/actions/types.d.ts +9 -1
  26. package/dist/app/access.d.ts +4 -4
  27. package/dist/app/access.js +33 -71
  28. package/dist/app/action-access.d.ts +2 -2
  29. package/dist/app/action-access.js +6 -4
  30. package/dist/app/service-error.d.ts +2 -2
  31. package/dist/app/service-error.js +10 -6
  32. package/dist/app/types.d.ts +76 -33
  33. package/dist/config-service.d.ts +30 -6
  34. package/dist/config-service.js +25 -9
  35. package/dist/configuration.d.ts +6 -3
  36. package/dist/configuration.js +8 -6
  37. package/dist/contracts.d.ts +4 -2
  38. package/dist/contracts.js +3 -3
  39. package/dist/contribution-origin.d.ts +4 -1
  40. package/dist/contribution-origin.js +14 -1
  41. package/dist/contributions/action.d.ts +26 -0
  42. package/dist/contributions/action.js +171 -0
  43. package/dist/contributions/host.d.ts +14 -11
  44. package/dist/contributions/index.d.ts +1 -26
  45. package/dist/contributions/index.js +1 -18
  46. package/dist/conventions.d.ts +8 -4
  47. package/dist/conventions.js +12 -31
  48. package/dist/core.d.ts +41 -18
  49. package/dist/core.js +25 -13
  50. package/dist/definitions.d.ts +272 -306
  51. package/dist/definitions.js +28 -56
  52. package/dist/destinations.d.ts +25 -0
  53. package/dist/destinations.js +21 -0
  54. package/dist/discovered.d.ts +52 -21
  55. package/dist/discovered.js +89 -35
  56. package/dist/events/define.d.ts +43 -0
  57. package/dist/events/define.js +17 -0
  58. package/dist/events/service.d.ts +35 -8
  59. package/dist/events/service.js +184 -42
  60. package/dist/events/types.d.ts +29 -9
  61. package/dist/inspection/inventory.d.ts +86 -0
  62. package/dist/inspection/inventory.js +132 -0
  63. package/dist/interceptors/define.d.ts +76 -0
  64. package/dist/interceptors/define.js +23 -0
  65. package/dist/interceptors/service-observers.d.ts +6 -3
  66. package/dist/interceptors/service-observers.js +13 -10
  67. package/dist/lifecycle/cleanup.d.ts +5 -0
  68. package/dist/lifecycle/cleanup.js +41 -0
  69. package/dist/lifecycle/controller.d.ts +82 -0
  70. package/dist/lifecycle/controller.js +276 -0
  71. package/dist/lifecycle/reconcile.d.ts +19 -0
  72. package/dist/lifecycle/reconcile.js +68 -0
  73. package/dist/lifecycle/state.d.ts +53 -0
  74. package/dist/lifecycle/state.js +86 -0
  75. package/dist/names.d.ts +10 -0
  76. package/dist/names.js +1 -0
  77. package/dist/pages.d.ts +39 -6
  78. package/dist/pages.js +93 -11
  79. package/dist/presentation.d.ts +9 -0
  80. package/dist/runtime.d.ts +166 -28
  81. package/dist/runtime.js +1485 -248
  82. package/dist/schema.d.ts +13 -0
  83. package/dist/schema.js +38 -0
  84. package/dist/scope.d.ts +59 -4
  85. package/dist/scope.js +133 -11
  86. package/dist/service-key.d.ts +33 -14
  87. package/dist/service-key.js +21 -5
  88. package/dist/service-names.d.ts +39 -0
  89. package/dist/service-names.js +175 -0
  90. package/dist/services.d.ts +24 -5
  91. package/dist/services.js +230 -37
  92. package/dist/settings/access.d.ts +19 -0
  93. package/dist/settings/access.js +78 -0
  94. package/dist/settings/define.d.ts +97 -0
  95. package/dist/settings/define.js +83 -0
  96. package/dist/settings/storage.d.ts +45 -0
  97. package/dist/settings/storage.js +102 -0
  98. package/dist/settings/store.d.ts +74 -0
  99. package/dist/settings/store.js +345 -0
  100. package/dist/slots/action-placement.d.ts +47 -0
  101. package/dist/slots/action-placement.js +1 -0
  102. package/dist/slots/define.d.ts +52 -0
  103. package/dist/slots/define.js +12 -0
  104. package/dist/slots/normalize.d.ts +7 -0
  105. package/dist/slots/normalize.js +36 -0
  106. package/dist/slots/runtime.d.ts +43 -0
  107. package/dist/slots/runtime.js +348 -0
  108. package/dist/slots/types.d.ts +113 -0
  109. package/dist/slots/types.js +1 -0
  110. package/dist/startup-error.d.ts +21 -0
  111. package/dist/startup-error.js +29 -0
  112. package/dist/store.d.ts +24 -0
  113. package/dist/store.js +40 -0
  114. package/dist/translation.d.ts +9 -4
  115. package/dist/translation.js +2 -3
  116. package/examples/todos/actions/create.mjs +1 -3
  117. package/examples/todos/actions/delete.mjs +3 -10
  118. package/examples/todos/actions/list.mjs +1 -3
  119. package/examples/todos/events.mjs +5 -0
  120. package/examples/todos/plugin.mjs +4 -2
  121. package/examples/todos/services/tasks.mjs +14 -20
  122. package/examples/todos.mjs +8 -7
  123. package/package.json +37 -9
  124. package/testing/index.d.ts +59 -0
  125. package/testing/index.mjs +150 -0
  126. package/discovery/entries.mjs +0 -124
  127. package/discovery/generate.mjs +0 -321
  128. package/discovery/host.mjs +0 -12
  129. package/discovery/modules.mjs +0 -13
  130. package/discovery/packages.mjs +0 -57
  131. package/discovery/watch.mjs +0 -23
  132. package/dist/app/service-aliases.d.ts +0 -4
  133. package/dist/app/service-aliases.js +0 -14
  134. package/dist/contributions/command.d.ts +0 -8
  135. package/dist/contributions/command.js +0 -59
  136. package/dist/contributions/dialog.d.ts +0 -8
  137. package/dist/contributions/dialog.js +0 -18
  138. package/dist/contributions/form.d.ts +0 -10
  139. package/dist/contributions/form.js +0 -67
  140. package/dist/contributions/native.d.ts +0 -11
  141. package/dist/contributions/native.js +0 -87
  142. package/dist/contributions/shared.d.ts +0 -19
  143. package/dist/contributions/shared.js +0 -48
  144. package/dist/contributions/stateful-action.d.ts +0 -29
  145. package/dist/contributions/stateful-action.js +0 -33
  146. package/dist/events/action-setup.d.ts +0 -19
  147. package/dist/events/action-setup.js +0 -24
  148. package/dist/interceptors/service.d.ts +0 -37
  149. package/dist/interceptors/service.js +0 -7
  150. package/dist/replacements.d.ts +0 -22
  151. package/dist/replacements.js +0 -54
  152. package/dist/validation.d.ts +0 -2
  153. package/dist/validation.js +0 -16
  154. package/docs/auth.md +0 -106
  155. package/docs/events.md +0 -157
  156. package/docs/file-contributions.md +0 -174
  157. package/docs/reference.md +0 -404
  158. package/docs/todo-tutorial.md +0 -88
package/README.md CHANGED
@@ -1,60 +1,12 @@
1
- # BitaKit Core
2
-
3
- **Give your application a shared home for plugins, services, and actions.**
4
-
5
- `@bitakit/core` coordinates how features start, work together, and stop. It runs
6
- without React, a browser, or a particular router. Your application still owns its
7
- pages, interface, business rules, and data storage.
8
-
9
- BitaKit is a composition layer alongside frameworks such as Next.js and TanStack
10
- Start, not a replacement for them. Its explicit plugin, service, and action
11
- conventions give people and AI coding assistants a shared structure to work with.
12
-
13
- ## Designed for typed composition
14
-
15
- - **Typed contracts:** shared service keys connect providers and consumers; action definitions carry inputs, results and custom state.
16
- - **Inferred application APIs:** discovery generates ActionMap, ServiceMap and ConfigMap from supported contributions.
17
- - **Typed notifications:** the workspace EventMap connects known event names to their payloads.
18
- - **Names beside implementations:** the workspace `exposeAs` service option supplies the typed app-facing name directly; discovery defaults it from the file.
19
- - **Flexible authoring:** flat and nested contribution files resolve to the same logical paths; explicit composition remains available.
20
- - **Owned lifecycle:** one runtime coordinates dependencies, registrations and cleanup.
21
-
22
- Unknown action IDs remain allowed unless strict mode is enabled. External data still
23
- needs runtime validation. See the [type-safety guide](../../apps/docs/content/docs/concepts/type-safety.mdx)
24
- and [Core learning path](../../apps/docs/content/docs/concepts/index.mdx) for examples and boundaries.
25
-
26
- ## How the pieces fit
1
+ <p align="center">
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
+ </p>
27
4
 
28
- Imagine a **To-do plugin** that lets someone add a task:
29
-
30
- ```text
31
- Application — chooses which plugins to use
32
- │
33
- ▼
34
- BitaKit Core — starts plugins and checks their dependencies
35
- │
36
- └── To-do plugin — groups one feature's contributions
37
- ├── Service: holds tasks and provides add/list operations
38
- └── Action: calls the service to add a task
39
-
40
- Button or server code
41
- │ executes "todos.create"
42
- ▼
43
- Action ──calls──▶ To-do service ──returns──▶ Task
44
-
45
- Application UI displays the result; Core does not render it.
46
- ```
47
-
48
- | Concept | What it does | In this example |
49
- | ---------------- | ------------------------------------------------------------------- | ------------------------------------------------- |
50
- | **Plugin** | Bundles the parts of a feature. | The To-do feature. |
51
- | **Service** | Owns reusable behavior and, when needed, state or resources. | Stores tasks and exposes `create()` and `list()`. |
52
- | **Action** | Provides a named operation that application code or UI can execute. | `todos.create` adds a task through the service. |
53
- | **Core runtime** | Coordinates dependencies, registrations, startup, and cleanup. | Creates the service and registers the action. |
5
+ # BitaKit Core
54
6
 
55
- Core manages the lifecycle of plugin-created services. A service that acquires
56
- resources can supply disposal logic. Core does not automatically save data to a
57
- database or subscribe your UI to service changes.
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.
58
10
 
59
11
  ## Install
60
12
 
@@ -62,121 +14,55 @@ database or subscribe your UI to service changes.
62
14
  npm install @bitakit/core
63
15
  ```
64
16
 
65
- The example below uses Node.js and no UI. For a React application, bindings live
66
- in `@bitakit/ui`; framework-specific integration lives in `@bitakit/next` or
67
- `@bitakit/tanstack`. Those packages are separate from Core and are being prepared
68
- for publication. TanStack support is experimental.
69
-
70
- ## Try a To-do plugin
71
-
72
- Follow the [To-do tutorial](docs/todo-tutorial.md) to run three actions: create a
73
- task, list tasks, and delete a task. Each action lives in its own file:
74
-
75
- ```text
76
- examples/
77
- ├── todos.mjs # Starts the runtime and executes the actions
78
- └── todos/
79
- ├── plugin.mjs # Groups the service and actions
80
- ├── services/
81
- │ └── tasks.mjs # In-memory task operations
82
- └── actions/
83
- ├── create.mjs # todos.create
84
- ├── list.mjs # todos.list
85
- └── delete.mjs # todos.delete
86
- ```
87
-
88
- The plugin uses explicit imports, so no framework or discovery setup is required.
89
- The script creates three tasks, lists them, deletes the second, and lists the two
90
- remaining tasks. Stopping the runtime releases its registrations. Data stays in
91
- memory and is lost on restart.
92
-
93
- With a configured framework adapter, contribution files can instead live under
94
- `src/plugins/todos/services` and `src/plugins/todos/actions`. Its build integration
95
- generates registration and types. Installing Core alone does not scan folders.
96
- See [file contributions](docs/file-contributions.md) for the exact conventions.
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.
97
21
 
98
- ## React to events
22
+ ## Start with one service
99
23
 
100
- The following API is available in the workspace and is not yet part of the
101
- published Core 0.1.0 release. Each runtime owns one event service. Services emit
102
- notifications after updating their data; actions declare `events` and `onEvent`.
103
-
104
- With file discovery configured, IDs can be omitted:
24
+ In a discovery-enabled app, create `src/plugins/counter/services/value.ts`:
105
25
 
106
26
  ```ts
107
- // src/services/todos.ts
108
27
  import { defineService } from '@bitakit/core';
109
28
 
110
- export default defineService({
111
- create({ events }) {
112
- let items: { id: number; title: string }[] = [];
113
- let nextId = 1;
114
- return {
115
- list: () => [...items],
116
- add(title: string) {
117
- const todo = { id: nextId++, title };
118
- items.push(todo);
119
- events.emit('todos.changed', { kind: 'added', id: todo.id });
120
- },
121
- remove(id: number) {
122
- items = items.filter((todo) => todo.id !== id);
123
- events.emit('todos.changed', { kind: 'removed', id });
124
- },
125
- };
126
- },
127
- });
128
- ```
129
-
130
- ```ts
131
- // src/actions/todos/delete.ts
132
- import { defineAction } from '@bitakit/core';
133
-
134
- export default defineAction<number>({
135
- requires: ['todos'],
136
- events: ['todos.changed'],
137
- setup({ services, action }) {
138
- action.enabled = services.todos.list().length > 0;
139
- },
140
- onEvent(event, { services, action }) {
141
- action.enabled = services.todos.list().length > 0;
142
- },
143
- 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 })) };
144
32
  });
145
33
  ```
146
34
 
147
- Here discovery supplies `todos` and `todos.delete` from the paths (with no explicit
148
- app namespace). Plugin contributions also receive their plugin namespace. Provide
149
- an explicit `id` when you need a custom identity. Direct imports without discovery,
150
- including the Node tutorial above, still need explicit IDs.
151
-
152
- `events: ['todos.loaded', 'todos.changed']` calls `onEvent` for
153
- **each** matching event. Handlers receive `{ type, data }` and can be synchronous or
154
- asynchronous. Core owns subscriptions created in action `setup` and service
155
- `create`, including cleanup after failed setup. No manual unsubscribe is needed.
156
- For dynamic subscriptions, `setup` still offers `events.watch`. React components use `useWatchEvent` from `@bitakit/ui`.
157
-
158
- See [events and action setup](docs/events.md) for payload typing, errors, async
159
- cancellation, and the distinction from observable-service `watch`.
160
-
161
- ## What belongs outside Core?
162
-
163
- - **React rendering:** the UI bindings and your visual components.
164
- - **Routes and navigation:** your application's router and its BitaKit adapter.
165
- - **Settings:** the separate App Preferences package.
166
- - **Email, authentication, and persistence:** optional integrations or your own services.
167
-
168
- Plugins are trusted application code. Core is not a sandbox or a remote plugin marketplace.
169
-
170
- ## Go deeper
171
-
172
- - [Runnable To-do example](examples/todos.mjs)
173
- - [Core reference](docs/reference.md): configuration, typed services, actions, lifecycle, and advanced integration.
174
- - [File contributions and configuration](docs/file-contributions.md): discovery and folder conventions.
175
- - [Source repository](https://github.com/mvavesal/bitakit)
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.
176
64
 
177
65
  ## License
178
66
 
179
- [MIT](LICENSE). Third-party dependencies retain their own licenses.
180
-
181
- See [client authentication](docs/auth.md) for the shared provider contract, externally
182
- configured login/logout paths, UI bindings and an adapter template (workspace APIs).
67
+ [MIT](https://github.com/mvavesal/bitakit/blob/main/LICENSE). Third-party dependencies retain
68
+ their own licenses.
@@ -0,0 +1,11 @@
1
+ <svg width="300" height="130" viewBox="0 0 300 130" fill="none" xmlns="http://www.w3.org/2000/svg">
2
+ <g clip-path="url(#clip0_2271_10)">
3
+ <path d="M6 30H15V76C15 81.2667 16.3333 85.3667 19 88.3C21.7333 91.1667 25.4667 92.6 30.2 92.6C35.1333 92.6 39 91.2 41.8 88.4C44.6 85.5333 46 81.4 46 76C46 70.8667 44.4667 66.8333 41.4 63.9C38.4 60.9 34.4333 59.4 29.5 59.4C25.3 59.4 21.6667 60.6 18.6 63V54C22.2667 52 26.2333 51 30.5 51C37.5667 51 43.4 53.3 48 57.9C52.6667 62.4333 55 68.4667 55 76C55 83.9333 52.5667 90.1 47.7 94.5C42.9 98.8333 36.8333 101 29.5 101C22.5 101 16.8333 98.7333 12.5 94.2C8.16667 89.6667 6 83.6 6 76V30ZM78.4727 100H69.6727V60.4H61.4727L65.4727 52H78.4727V100ZM69.2727 42C68.406 40.8667 67.9727 39.6333 67.9727 38.3C67.9727 36.9667 68.406 35.7667 69.2727 34.7C70.1393 33.5667 71.4727 33 73.2727 33C75.0727 33 76.406 33.5667 77.2727 34.7C78.1393 35.7667 78.5727 36.9667 78.5727 38.3C78.5727 39.6333 78.1393 40.8667 77.2727 42C76.406 43.0667 75.0727 43.6 73.2727 43.6C71.4727 43.6 70.1393 43.0667 69.2727 42ZM86.8398 60.4L104.74 42.5V52H118.24V60.4H104.74V81C104.74 83.3333 105.107 85.2667 105.84 86.8C106.64 88.3333 107.773 89.4333 109.24 90.1C110.707 90.7 112.073 91.1 113.34 91.3C114.673 91.5 116.307 91.6 118.24 91.6V100C110.573 100 104.907 98.5333 101.24 95.6C97.5732 92.6667 95.7398 87.8 95.7398 81V60.4H86.8398ZM154.477 71.8V80.8C151.944 78.8667 148.844 77.9 145.177 77.9C142.044 77.9 139.611 78.5333 137.877 79.8C136.144 81 135.277 82.7333 135.277 85C135.277 89.4 138.544 91.6 145.077 91.6H158.277V72.5C158.277 64.4333 154.344 60.4 146.477 60.4H130.477V52H146.977C153.444 52 158.411 53.6 161.877 56.8C165.344 60 167.077 64.6 167.077 70.6V100H144.777C139.111 100 134.611 98.7333 131.277 96.2C127.944 93.6667 126.277 89.9667 126.277 85.1C126.277 80.2333 128.044 76.5333 131.577 74C135.111 71.4667 139.544 70.2 144.877 70.2C147.877 70.2 151.077 70.7333 154.477 71.8Z" fill="white"/>
4
+ <path d="M205.67 52H215.37L203.27 72.9C211.47 75.1 215.57 81.7333 215.57 92.8V100H206.77V92.7C206.77 88.2333 205.437 84.8 202.77 82.4C200.17 79.9333 196.437 78.7 191.57 78.7C190.037 78.7 188.47 78.8 186.87 79V100H178.07V30H186.87V71.1C189.67 70.7 192.47 70.7 195.27 71.1L205.67 52ZM239.117 100H230.317V60.4H222.117L226.117 52H239.117V100ZM229.917 42C229.051 40.8667 228.617 39.6333 228.617 38.3C228.617 36.9667 229.051 35.7667 229.917 34.7C230.784 33.5667 232.117 33 233.917 33C235.717 33 237.051 33.5667 237.917 34.7C238.784 35.7667 239.217 36.9667 239.217 38.3C239.217 39.6333 238.784 40.8667 237.917 42C237.051 43.0667 235.717 43.6 233.917 43.6C232.117 43.6 230.784 43.0667 229.917 42ZM247.484 60.4L265.384 42.5V52H278.884V60.4H265.384V81C265.384 83.3333 265.751 85.2667 266.484 86.8C267.284 88.3333 268.418 89.4333 269.884 90.1C271.351 90.7 272.718 91.1 273.984 91.3C275.318 91.5 276.951 91.6 278.884 91.6V100C271.218 100 265.551 98.5333 261.884 95.6C258.218 92.6667 256.384 87.8 256.384 81V60.4H247.484Z" fill="#EBB759"/>
5
+ </g>
6
+ <defs>
7
+ <clipPath id="clip0_2271_10">
8
+ <rect width="300" height="130" fill="white"/>
9
+ </clipPath>
10
+ </defs>
11
+ </svg>
@@ -0,0 +1,11 @@
1
+ <svg width="300" height="130" viewBox="0 0 300 130" fill="none" xmlns="http://www.w3.org/2000/svg">
2
+ <g clip-path="url(#clip0_2269_3)">
3
+ <path d="M6 30H15V76C15 81.2667 16.3333 85.3667 19 88.3C21.7333 91.1667 25.4667 92.6 30.2 92.6C35.1333 92.6 39 91.2 41.8 88.4C44.6 85.5333 46 81.4 46 76C46 70.8667 44.4667 66.8333 41.4 63.9C38.4 60.9 34.4333 59.4 29.5 59.4C25.3 59.4 21.6667 60.6 18.6 63V54C22.2667 52 26.2333 51 30.5 51C37.5667 51 43.4 53.3 48 57.9C52.6667 62.4333 55 68.4667 55 76C55 83.9333 52.5667 90.1 47.7 94.5C42.9 98.8333 36.8333 101 29.5 101C22.5 101 16.8333 98.7333 12.5 94.2C8.16667 89.6667 6 83.6 6 76V30ZM78.4727 100H69.6727V60.4H61.4727L65.4727 52H78.4727V100ZM69.2727 42C68.406 40.8667 67.9727 39.6333 67.9727 38.3C67.9727 36.9667 68.406 35.7667 69.2727 34.7C70.1393 33.5667 71.4727 33 73.2727 33C75.0727 33 76.406 33.5667 77.2727 34.7C78.1393 35.7667 78.5727 36.9667 78.5727 38.3C78.5727 39.6333 78.1393 40.8667 77.2727 42C76.406 43.0667 75.0727 43.6 73.2727 43.6C71.4727 43.6 70.1393 43.0667 69.2727 42ZM86.8398 60.4L104.74 42.5V52H118.24V60.4H104.74V81C104.74 83.3333 105.107 85.2667 105.84 86.8C106.64 88.3333 107.773 89.4333 109.24 90.1C110.707 90.7 112.073 91.1 113.34 91.3C114.673 91.5 116.307 91.6 118.24 91.6V100C110.573 100 104.907 98.5333 101.24 95.6C97.5732 92.6667 95.7398 87.8 95.7398 81V60.4H86.8398ZM154.477 71.8V80.8C151.944 78.8667 148.844 77.9 145.177 77.9C142.044 77.9 139.611 78.5333 137.877 79.8C136.144 81 135.277 82.7333 135.277 85C135.277 89.4 138.544 91.6 145.077 91.6H158.277V72.5C158.277 64.4333 154.344 60.4 146.477 60.4H130.477V52H146.977C153.444 52 158.411 53.6 161.877 56.8C165.344 60 167.077 64.6 167.077 70.6V100H144.777C139.111 100 134.611 98.7333 131.277 96.2C127.944 93.6667 126.277 89.9667 126.277 85.1C126.277 80.2333 128.044 76.5333 131.577 74C135.111 71.4667 139.544 70.2 144.877 70.2C147.877 70.2 151.077 70.7333 154.477 71.8Z" fill="#122F4D"/>
4
+ <path d="M205.67 52H215.37L203.27 72.9C211.47 75.1 215.57 81.7333 215.57 92.8V100H206.77V92.7C206.77 88.2333 205.437 84.8 202.77 82.4C200.17 79.9333 196.437 78.7 191.57 78.7C190.037 78.7 188.47 78.8 186.87 79V100H178.07V30H186.87V71.1C189.67 70.7 192.47 70.7 195.27 71.1L205.67 52ZM239.117 100H230.317V60.4H222.117L226.117 52H239.117V100ZM229.917 42C229.051 40.8667 228.617 39.6333 228.617 38.3C228.617 36.9667 229.051 35.7667 229.917 34.7C230.784 33.5667 232.117 33 233.917 33C235.717 33 237.051 33.5667 237.917 34.7C238.784 35.7667 239.217 36.9667 239.217 38.3C239.217 39.6333 238.784 40.8667 237.917 42C237.051 43.0667 235.717 43.6 233.917 43.6C232.117 43.6 230.784 43.0667 229.917 42ZM247.484 60.4L265.384 42.5V52H278.884V60.4H265.384V81C265.384 83.3333 265.751 85.2667 266.484 86.8C267.284 88.3333 268.418 89.4333 269.884 90.1C271.351 90.7 272.718 91.1 273.984 91.3C275.318 91.5 276.951 91.6 278.884 91.6V100C271.218 100 265.551 98.5333 261.884 95.6C258.218 92.6667 256.384 87.8 256.384 81V60.4H247.484Z" fill="#EBB759"/>
5
+ </g>
6
+ <defs>
7
+ <clipPath id="clip0_2269_3">
8
+ <rect width="300" height="130" fill="white"/>
9
+ </clipPath>
10
+ </defs>
11
+ </svg>
@@ -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>;