@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.
- package/README.md +44 -207
- package/discovery/index.d.ts +1 -41
- package/discovery/index.mjs +1 -4
- package/dist/actions/action-list.d.ts +4 -0
- package/dist/actions/action-list.js +58 -16
- package/dist/actions/action.d.ts +2 -0
- package/dist/actions/action.js +4 -0
- package/dist/actions/brand.d.ts +21 -0
- package/dist/actions/brand.js +36 -0
- package/dist/actions/core.d.ts +4 -3
- package/dist/actions/core.js +4 -2
- package/dist/actions/execution.d.ts +2 -2
- package/dist/actions/execution.js +61 -9
- package/dist/actions/feedback.d.ts +2 -0
- package/dist/actions/feedback.js +8 -0
- package/dist/actions/groups.js +5 -1
- package/dist/actions/instance-bindings.js +3 -2
- package/dist/actions/interceptors.d.ts +9 -3
- package/dist/actions/interceptors.js +31 -3
- package/dist/actions/navigation.d.ts +2 -1
- package/dist/actions/navigation.js +10 -5
- package/dist/actions/reference.js +10 -5
- package/dist/actions/types.d.ts +9 -1
- package/dist/app/access.d.ts +4 -4
- package/dist/app/access.js +33 -71
- package/dist/app/action-access.d.ts +2 -2
- package/dist/app/action-access.js +6 -4
- package/dist/app/service-error.d.ts +2 -2
- package/dist/app/service-error.js +10 -6
- package/dist/app/types.d.ts +76 -33
- package/dist/config-service.d.ts +30 -6
- package/dist/config-service.js +25 -9
- package/dist/configuration.d.ts +6 -3
- package/dist/configuration.js +8 -6
- package/dist/contracts.d.ts +4 -2
- package/dist/contracts.js +3 -3
- package/dist/contribution-origin.d.ts +4 -1
- package/dist/contribution-origin.js +14 -1
- package/dist/contributions/action.d.ts +26 -0
- package/dist/contributions/action.js +171 -0
- package/dist/contributions/host.d.ts +14 -11
- package/dist/contributions/index.d.ts +1 -26
- package/dist/contributions/index.js +1 -18
- package/dist/conventions.d.ts +8 -4
- package/dist/conventions.js +12 -31
- package/dist/core.d.ts +41 -18
- package/dist/core.js +25 -13
- package/dist/definitions.d.ts +272 -306
- package/dist/definitions.js +28 -56
- package/dist/destinations.d.ts +25 -0
- package/dist/destinations.js +21 -0
- package/dist/discovered.d.ts +52 -21
- package/dist/discovered.js +89 -35
- package/dist/events/define.d.ts +43 -0
- package/dist/events/define.js +17 -0
- package/dist/events/service.d.ts +35 -8
- package/dist/events/service.js +184 -42
- package/dist/events/types.d.ts +29 -9
- package/dist/inspection/inventory.d.ts +86 -0
- package/dist/inspection/inventory.js +132 -0
- package/dist/interceptors/define.d.ts +76 -0
- package/dist/interceptors/define.js +23 -0
- package/dist/interceptors/service-observers.d.ts +6 -3
- package/dist/interceptors/service-observers.js +13 -10
- package/dist/lifecycle/cleanup.d.ts +5 -0
- package/dist/lifecycle/cleanup.js +41 -0
- package/dist/lifecycle/controller.d.ts +82 -0
- package/dist/lifecycle/controller.js +276 -0
- package/dist/lifecycle/reconcile.d.ts +19 -0
- package/dist/lifecycle/reconcile.js +68 -0
- package/dist/lifecycle/state.d.ts +53 -0
- package/dist/lifecycle/state.js +86 -0
- package/dist/names.d.ts +10 -0
- package/dist/names.js +1 -0
- package/dist/pages.d.ts +39 -6
- package/dist/pages.js +93 -11
- package/dist/presentation.d.ts +9 -0
- package/dist/runtime.d.ts +166 -28
- package/dist/runtime.js +1485 -248
- package/dist/schema.d.ts +13 -0
- package/dist/schema.js +38 -0
- package/dist/scope.d.ts +59 -4
- package/dist/scope.js +133 -11
- package/dist/service-key.d.ts +33 -14
- package/dist/service-key.js +21 -5
- package/dist/service-names.d.ts +39 -0
- package/dist/service-names.js +175 -0
- package/dist/services.d.ts +24 -5
- package/dist/services.js +230 -37
- package/dist/settings/access.d.ts +19 -0
- package/dist/settings/access.js +78 -0
- package/dist/settings/define.d.ts +97 -0
- package/dist/settings/define.js +83 -0
- package/dist/settings/storage.d.ts +45 -0
- package/dist/settings/storage.js +102 -0
- package/dist/settings/store.d.ts +74 -0
- package/dist/settings/store.js +345 -0
- package/dist/slots/action-placement.d.ts +47 -0
- package/dist/slots/action-placement.js +1 -0
- package/dist/slots/define.d.ts +52 -0
- package/dist/slots/define.js +12 -0
- package/dist/slots/normalize.d.ts +7 -0
- package/dist/slots/normalize.js +36 -0
- package/dist/slots/runtime.d.ts +43 -0
- package/dist/slots/runtime.js +348 -0
- package/dist/slots/types.d.ts +113 -0
- package/dist/slots/types.js +1 -0
- package/dist/startup-error.d.ts +21 -0
- package/dist/startup-error.js +29 -0
- package/dist/store.d.ts +24 -0
- package/dist/store.js +40 -0
- package/dist/translation.d.ts +9 -4
- package/dist/translation.js +2 -3
- package/examples/todos/actions/create.mjs +1 -3
- package/examples/todos/actions/delete.mjs +3 -10
- package/examples/todos/actions/list.mjs +1 -3
- package/examples/todos/events.mjs +5 -0
- package/examples/todos/plugin.mjs +4 -2
- package/examples/todos/services/tasks.mjs +14 -20
- package/examples/todos.mjs +8 -7
- package/package.json +36 -9
- package/testing/index.d.ts +59 -0
- package/testing/index.mjs +150 -0
- package/assets/bitakit-banner.png +0 -0
- package/discovery/entries.mjs +0 -124
- package/discovery/generate.mjs +0 -321
- package/discovery/host.mjs +0 -12
- package/discovery/modules.mjs +0 -13
- package/discovery/packages.mjs +0 -57
- package/discovery/watch.mjs +0 -23
- package/dist/app/service-aliases.d.ts +0 -4
- package/dist/app/service-aliases.js +0 -14
- package/dist/contributions/command.d.ts +0 -8
- package/dist/contributions/command.js +0 -59
- package/dist/contributions/dialog.d.ts +0 -8
- package/dist/contributions/dialog.js +0 -18
- package/dist/contributions/form.d.ts +0 -10
- package/dist/contributions/form.js +0 -67
- package/dist/contributions/native.d.ts +0 -11
- package/dist/contributions/native.js +0 -87
- package/dist/contributions/shared.d.ts +0 -19
- package/dist/contributions/shared.js +0 -48
- package/dist/contributions/stateful-action.d.ts +0 -29
- package/dist/contributions/stateful-action.js +0 -33
- package/dist/events/action-setup.d.ts +0 -19
- package/dist/events/action-setup.js +0 -24
- package/dist/interceptors/service.d.ts +0 -37
- package/dist/interceptors/service.js +0 -7
- package/dist/replacements.d.ts +0 -22
- package/dist/replacements.js +0 -54
- package/dist/validation.d.ts +0 -2
- package/dist/validation.js +0 -16
- package/docs/auth.md +0 -106
- package/docs/events.md +0 -157
- package/docs/file-contributions.md +0 -174
- package/docs/reference.md +0 -404
- package/docs/todo-tutorial.md +0 -88
package/README.md
CHANGED
|
@@ -1,31 +1,12 @@
|
|
|
1
1
|
<p align="center">
|
|
2
|
-
<img src="https://
|
|
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
|
-
|
|
8
|
-
|
|
9
|
-
|
|
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
|
-
|
|
37
|
-
|
|
38
|
-
|
|
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
|
-
|
|
141
|
-
the file path. Known event names and payloads are connected through `EventMap`.
|
|
22
|
+
## Start with one service
|
|
142
23
|
|
|
143
|
-
|
|
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
|
-
|
|
161
|
-
|
|
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
|
-
|
|
197
|
-
|
|
198
|
-
an
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
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://
|
|
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.
|
package/discovery/index.d.ts
CHANGED
|
@@ -1,41 +1 @@
|
|
|
1
|
-
|
|
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';
|
package/discovery/index.mjs
CHANGED
|
@@ -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
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
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
|
-
|
|
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({
|
|
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(
|
|
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(
|
|
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(
|
|
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();
|
package/dist/actions/action.d.ts
CHANGED
|
@@ -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;
|
package/dist/actions/action.js
CHANGED
|
@@ -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
|
+
}
|
package/dist/actions/core.d.ts
CHANGED
|
@@ -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
|
|
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';
|
package/dist/actions/core.js
CHANGED
|
@@ -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 {
|
|
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
|
|
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>;
|