@bitakit/core 0.3.0 → 0.3.2
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/AGENTS.md +58 -2
- package/README.md +61 -18
- package/dist/actions/execution.js +4 -0
- package/dist/contributions/action.d.ts +0 -5
- package/dist/contributions/action.js +21 -1
- package/dist/contributions/host.d.ts +3 -0
- package/dist/core.d.ts +4 -0
- package/dist/core.js +1 -0
- package/dist/definitions.d.ts +10 -0
- package/dist/events/service.d.ts +14 -0
- package/dist/events/service.js +109 -39
- package/dist/events/types.d.ts +5 -1
- package/dist/inspection/inventory.d.ts +1 -1
- package/dist/operation-error.d.ts +75 -0
- package/dist/operation-error.js +123 -0
- package/dist/remote.d.ts +60 -0
- package/dist/remote.js +156 -0
- package/dist/request-context.d.ts +62 -0
- package/dist/request-context.js +2 -0
- package/dist/runtime-mode.d.ts +35 -0
- package/dist/runtime-mode.js +6 -0
- package/dist/runtime.d.ts +17 -1
- package/dist/runtime.js +118 -50
- package/dist/server/access.d.ts +31 -0
- package/dist/server/access.js +109 -0
- package/dist/server/compile.d.ts +59 -0
- package/dist/server/compile.js +211 -0
- package/dist/server/contributions.d.ts +13 -0
- package/dist/server/contributions.js +17 -0
- package/dist/server/create-server.d.ts +15 -0
- package/dist/server/create-server.js +132 -0
- package/dist/server/define.d.ts +40 -0
- package/dist/server/define.js +15 -0
- package/dist/server/fetch-handler.d.ts +17 -0
- package/dist/server/fetch-handler.js +139 -0
- package/dist/server/index.d.ts +22 -0
- package/dist/server/index.js +21 -0
- package/dist/server/kernel.d.ts +44 -0
- package/dist/server/kernel.js +278 -0
- package/dist/server/types.d.ts +208 -0
- package/dist/server/types.js +1 -0
- package/dist/server/validate.d.ts +31 -0
- package/dist/server/validate.js +60 -0
- package/dist/services.d.ts +5 -1
- package/dist/services.js +5 -1
- package/dist/settings/access.d.ts +5 -2
- package/dist/settings/access.js +7 -4
- package/dist/settings/server.d.ts +28 -0
- package/dist/settings/server.js +94 -0
- package/package.json +7 -3
- package/testing/index.d.ts +104 -0
- package/testing/index.mjs +349 -14
package/AGENTS.md
CHANGED
|
@@ -10,6 +10,8 @@ rarely call the runtime directly: files in `src/plugins/<id>/` are discovered, a
|
|
|
10
10
|
|
|
11
11
|
## The define helpers (import from `@bitakit/core`)
|
|
12
12
|
|
|
13
|
+
Files under `server/` import the same helpers from `@bitakit/core/server` (see below).
|
|
14
|
+
|
|
13
15
|
| File (in a plugin) | Helper | ID |
|
|
14
16
|
| ------------------------ | -------------------------------------------------------------- | ------------------ |
|
|
15
17
|
| `services/<name>.ts` | `defineService(({ store, events, settings, onStart }) => ...)` | `<plugin>.<name>` |
|
|
@@ -24,6 +26,47 @@ rarely call the runtime directly: files in `src/plugins/<id>/` are discovered, a
|
|
|
24
26
|
|
|
25
27
|
The app declares its base roles once in `src/roles.ts` with `defineRoles({ ... }, { customRoles })`.
|
|
26
28
|
|
|
29
|
+
## The server half (`@bitakit/core/server`)
|
|
30
|
+
|
|
31
|
+
A plugin's `server/` folder runs only on the server and is never bundled for the browser.
|
|
32
|
+
|
|
33
|
+
| File (in a plugin) | Helper (from `@bitakit/core/server`) | ID |
|
|
34
|
+
| ------------------------------- | -------------------------------------------------------------- | ------------------------------------- |
|
|
35
|
+
| `server/actions/<name>.ts` | `defineAction({ access, expose?, input?, output?, execute })` | `<plugin>.<name>`, `server:` in tools |
|
|
36
|
+
| `server/services/<name>.ts` | `defineService(() => ...)`: one instance for the whole process | `<plugin>.<name>` (server services) |
|
|
37
|
+
| `server/interceptors/<name>.ts` | `defineInterceptor({ action: '<plugin>.*', before, after })` | — |
|
|
38
|
+
| `server/contributions/<dir>/…` | Files of a contribution kind declared with `runtime: 'server'` | — |
|
|
39
|
+
|
|
40
|
+
- `access` is required: `'public'`, `'user'`, `'organization'` or
|
|
41
|
+
`{ permission: { resource: ['operation'] } }`. `expose: true` publishes the operation over
|
|
42
|
+
HTTP and in the client's typed `remote` (`remote.<plugin>.<name>(input)` in client Actions
|
|
43
|
+
and services); without it the operation is callable only in-process (`server.as(request)`).
|
|
44
|
+
- `execute({ id, input, ctx, services, config, events, settings, signal })`: `ctx` is the frozen,
|
|
45
|
+
verified identity (`requestId`, `signal`, plus `user`, `organization`, `member`, `can()` by
|
|
46
|
+
access). Filter every query by `ctx.user.id` or `ctx.organization.id`; server services take
|
|
47
|
+
`ctx` or the owner ID as a method argument and never hold per-user state.
|
|
48
|
+
- Identity comes from one app service with `provides: requestContext` (`resolve(request)` →
|
|
49
|
+
`{ user, organization?, member?, reason?, can? }`). It returns an organization only for a
|
|
50
|
+
verified, active membership; `can` grants only by answering exactly `true`. Without a provider
|
|
51
|
+
the server refuses to start while a non-public operation exists.
|
|
52
|
+
- Throw `OperationError(code, safeMessage, { issues?, reason? })` for expected failures (codes
|
|
53
|
+
`BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `CONFLICT`, `TOO_MANY_REQUESTS`, ...);
|
|
54
|
+
anything else answers 500 with a `requestId` and is logged. `remote` rejects with the same
|
|
55
|
+
`OperationError` (also exported from `@bitakit/core`, with `isOperationError`), and an Action's
|
|
56
|
+
default failure message shows its `safeMessage`.
|
|
57
|
+
- On the server, settings load per request: `await settings.<plugin>.<name>.load()` (in an
|
|
58
|
+
operation; `load(ctx)` elsewhere) through a `settings.storage` provider; `get()` throws.
|
|
59
|
+
`store()` is process-wide. Events reach in-process listeners with `{ signal, ctx }` and never
|
|
60
|
+
the browser. Interceptor `before` sees validated input; returning `false` rejects the call
|
|
61
|
+
(`FORBIDDEN`, reason `INTERCEPTED`). Client interceptors never match server Actions.
|
|
62
|
+
- The route: `export const POST = fetchHandler(server)` with `server` from the generated
|
|
63
|
+
`src/bitakit.gen.server.ts` (Next.js: `src/app/api/rpc/[...path]/route.ts`). It accepts only
|
|
64
|
+
`POST <endpoint>/<operation id>` with JSON from the app's origin (`trustedOrigins` for exact
|
|
65
|
+
others), up to 1 MiB; `server.endpoint` (default `/api/rpc`) comes from `bitakit.config.ts`
|
|
66
|
+
`server.endpoint`.
|
|
67
|
+
- Reserved name segments (`then`, `catch`, `finally`, `subscribe`, `toJSON`, `valueOf`,
|
|
68
|
+
`toString`, `constructor`, `prototype`) cannot name a server Action.
|
|
69
|
+
|
|
27
70
|
## Roles and permissions
|
|
28
71
|
|
|
29
72
|
- Core holds only the vocabulary: `definePermissions`, `defineRoles`, the composed catalog and
|
|
@@ -57,13 +100,25 @@ The app declares its base roles once in `src/roles.ts` with `defineRoles({ ... }
|
|
|
57
100
|
one plugin under Node (no browser); `plugin.execute(id, input)` resolves to the outcome
|
|
58
101
|
(`completed` or `skipped`) and rejects on failure; `plugin.events.recorded` lists emitted events.
|
|
59
102
|
|
|
103
|
+
`mountServer(folder, { plugins?, services?, configOverrides?, kinds?, app? })` boots a folder's
|
|
104
|
+
server half (shared files plus `server/`, loaded with the app's tsconfig `paths`);
|
|
105
|
+
`mounted.as(identity({ user, organization, member, permissions, reason }))` calls every
|
|
106
|
+
operation, also private ones, with the same checks as over HTTP. A test `requestContext`
|
|
107
|
+
provider answers it and replaces the folder's own. Test each exposed operation as a member, a
|
|
108
|
+
member of another organization and signed out (`user: null`). `mountPlugin(folder, { remote })`
|
|
109
|
+
connects a client half to `mounted.as(...)` or a stub. `mountServer` needs
|
|
110
|
+
`@bitakit/discovery` 0.3.1 or later.
|
|
111
|
+
|
|
60
112
|
## Rules
|
|
61
113
|
|
|
62
114
|
- One `defineAction` shape; state belongs in a service `store()`, replaced with `state.set`.
|
|
63
115
|
- Reading a missing service throws; list other plugins' services in `requires`, or check
|
|
64
116
|
`app.has(name)` for optional ones.
|
|
65
117
|
- Only the declaring plugin emits its events; others listen.
|
|
66
|
-
- `enabled`, `visible` and interceptors are client rules; authorize
|
|
118
|
+
- `enabled`, `visible` and interceptors are client rules; authorize in the server operation's
|
|
119
|
+
`access` and filter its data by `ctx`.
|
|
120
|
+
- Browser code never imports `server/` files, `@bitakit/core/server` or
|
|
121
|
+
`src/bitakit.gen.server.ts`; server code never imports React or `ui/` (`bitakit doctor` checks).
|
|
67
122
|
|
|
68
123
|
## Identifier compatibility and integration contexts
|
|
69
124
|
|
|
@@ -106,7 +161,8 @@ Origin records may carry `metadataLocation` for diagnostics. Rebinding a definit
|
|
|
106
161
|
existing `metadataWarnings`. The runtime's application module has local origin; unknown
|
|
107
162
|
replacement plugins remain unknown. Static inventory may include `selected` and
|
|
108
163
|
`diagnostics.identityConflicts`; physical record keys are not portable package identities.
|
|
109
|
-
The optional `@bitakit/core/testing` entry requires Discovery 0.2.5 or later
|
|
164
|
+
The optional `@bitakit/core/testing` entry requires Discovery 0.2.5 or later; `mountServer`
|
|
165
|
+
needs 0.3.1 or later.
|
|
110
166
|
|
|
111
167
|
### Complete cohort replacement
|
|
112
168
|
|
package/README.md
CHANGED
|
@@ -5,8 +5,9 @@
|
|
|
5
5
|
# BitaKit Core
|
|
6
6
|
|
|
7
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.
|
|
9
|
-
|
|
8
|
+
Core works in Node.js and the browser without React or a router. Its `@bitakit/core/server`
|
|
9
|
+
entry runs plugins' server halves. React bindings, discovery, visual plugins and provider
|
|
10
|
+
integrations are separate packages.
|
|
10
11
|
|
|
11
12
|
## Install
|
|
12
13
|
|
|
@@ -15,7 +16,7 @@ npm install @bitakit/core
|
|
|
15
16
|
```
|
|
16
17
|
|
|
17
18
|
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.
|
|
19
|
+
(Node.js 24 or newer). The handbook describes the 0.3 API in this checkout; use matching
|
|
19
20
|
package versions or the [local package workflow](../../apps/docs/content/docs/local-development.mdx)
|
|
20
21
|
when trying unpublished changes.
|
|
21
22
|
|
|
@@ -37,6 +38,31 @@ Discovery names it `counter.value`. Continue with the
|
|
|
37
38
|
to add an Action and a page. Installing Core alone does not scan folders or render UI.
|
|
38
39
|
For a headless program, follow [manual composition](../../apps/docs/content/docs/concepts/manual-composition.mdx).
|
|
39
40
|
|
|
41
|
+
## The server half
|
|
42
|
+
|
|
43
|
+
A plugin's `server/` folder holds code that runs only on the server. An operation is a server
|
|
44
|
+
Action, written with the same `defineAction` imported from `@bitakit/core/server`:
|
|
45
|
+
|
|
46
|
+
```ts
|
|
47
|
+
// src/plugins/counter/server/actions/save.ts
|
|
48
|
+
import { defineAction } from '@bitakit/core/server';
|
|
49
|
+
import { z } from 'zod';
|
|
50
|
+
|
|
51
|
+
export default defineAction({
|
|
52
|
+
access: 'user', // required: 'public', 'user', 'organization' or { permission }
|
|
53
|
+
expose: true, // callable from the browser as remote.counter.save(input)
|
|
54
|
+
input: z.object({ count: z.number().int() }),
|
|
55
|
+
execute: ({ input, ctx }) => ({ userId: ctx.user.id, count: input.count }),
|
|
56
|
+
});
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Discovery writes `src/bitakit.gen.server.ts`; one route serves every exposed operation
|
|
60
|
+
(`export const POST = fetchHandler(server)`), and client Actions and services call them through
|
|
61
|
+
the typed `remote`. Identity comes from one app service with `provides: requestContext`.
|
|
62
|
+
`@bitakit/core/testing` boots a server half with `mountServer` and calls it as different people
|
|
63
|
+
with `identity(...)`. See [The server half](../../apps/docs/content/docs/concepts/server.mdx)
|
|
64
|
+
and the [Server reference](../../apps/docs/content/docs/reference/server.mdx).
|
|
65
|
+
|
|
40
66
|
## Developer handbook
|
|
41
67
|
|
|
42
68
|
The handbook is maintained once in the documentation website's source. The links below
|
|
@@ -44,23 +70,40 @@ resolve within a repository checkout and follow the branch viewed on GitHub. Run
|
|
|
44
70
|
`npm run dev:docs` from the repository root to read the rendered handbook at
|
|
45
71
|
`http://localhost:3002/docs`. A public documentation address is not configured yet.
|
|
46
72
|
|
|
47
|
-
| Topic
|
|
48
|
-
|
|
|
49
|
-
| Services and cleanup
|
|
50
|
-
| Actions and React bindings
|
|
51
|
-
| Events and interception
|
|
52
|
-
| Files and developer configuration
|
|
53
|
-
| Extension points and preferences
|
|
54
|
-
| Runtime updates and diagnostics
|
|
55
|
-
| Enable, disable, add and remove plugins
|
|
56
|
-
| Activate a trusted package catalog
|
|
57
|
-
| Authentication contract
|
|
58
|
-
|
|
|
59
|
-
|
|
|
73
|
+
| Topic | Guide |
|
|
74
|
+
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
75
|
+
| Services and cleanup | [Service reference](../../apps/docs/content/docs/reference/services.mdx) |
|
|
76
|
+
| Actions and React bindings | [Action reference](../../apps/docs/content/docs/reference/actions.mdx) |
|
|
77
|
+
| Events and interception | [Events](../../apps/docs/content/docs/concepts/events.mdx), [Interceptors](../../apps/docs/content/docs/concepts/interceptors.mdx) |
|
|
78
|
+
| Files and developer configuration | [Discovery](../../apps/docs/content/docs/concepts/discovery.mdx), [Configuration](../../apps/docs/content/docs/concepts/configuration.mdx) |
|
|
79
|
+
| Extension points and preferences | [Slots](../../apps/docs/content/docs/reference/slots.mdx), [Settings](../../apps/docs/content/docs/reference/settings.mdx) |
|
|
80
|
+
| Runtime updates and diagnostics | [Runtime management](../../apps/docs/content/docs/concepts/runtime-management.mdx) |
|
|
81
|
+
| Enable, disable, add and remove plugins | [Plugin manager](../../apps/docs/content/docs/plugin-management.mdx) |
|
|
82
|
+
| Activate a trusted package catalog | [Package manager](../../apps/docs/content/docs/package-management.mdx) |
|
|
83
|
+
| Authentication contract | [Client authentication](../../apps/docs/content/docs/reference/authentication.mdx) |
|
|
84
|
+
| Server operations and the request context | [The server half](../../apps/docs/content/docs/concepts/server.mdx), [Server reference](../../apps/docs/content/docs/reference/server.mdx) |
|
|
85
|
+
| Test a plugin folder or its server half | [Testing](../../apps/docs/content/docs/reference/testing.mdx) |
|
|
86
|
+
| Standalone example | [To-do walkthrough](../../apps/docs/content/docs/concepts/tutorial.mdx); runnable JavaScript files in `examples/` |
|
|
60
87
|
|
|
61
88
|
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
|
-
|
|
89
|
+
marketplace. Services own state and resources; the host owns routing, persistence providers and
|
|
90
|
+
its authentication. Server operations declare who may call them (`access`); the app's
|
|
91
|
+
`requestContext` provider verifies the caller, and Core never decides roles itself.
|
|
92
|
+
|
|
93
|
+
## Source responsibilities: the server half
|
|
94
|
+
|
|
95
|
+
- `src/server/index.ts`: the `@bitakit/core/server` entry; `define.ts` gives the root helpers
|
|
96
|
+
their server types.
|
|
97
|
+
- `src/server/create-server.ts`: the lazy `Server` handle and the process-wide live-kernel
|
|
98
|
+
registry (`instance`, `stamp`); `kernel.ts`: one call (lookup, access, validation,
|
|
99
|
+
interceptors, execute, output, errors); `compile.ts`: the frozen operation table built at boot;
|
|
100
|
+
`access.ts`: identity normalization and access rules; `validate.ts`: schema checks.
|
|
101
|
+
- `src/server/fetch-handler.ts`: the built-in JSON transport; `contributions.ts`: `contributionsOf`.
|
|
102
|
+
- `src/remote.ts`: the client's `remote`, `ServerActionMap`/`ServerServiceMap` and the reserved
|
|
103
|
+
name segments; `src/operation-error.ts`: the request-error model; `src/request-context.ts`: the
|
|
104
|
+
`requestContext` contract and `ctx` types; `src/runtime-mode.ts` and `src/settings/server.ts`:
|
|
105
|
+
the runtime's server mode and per-request settings.
|
|
106
|
+
- `testing/index.mjs`: `mountPlugin`, `mountServer`, `identity`, `assertAuthContract`.
|
|
64
107
|
|
|
65
108
|
## Metadata and provenance
|
|
66
109
|
|
|
@@ -93,6 +93,10 @@ export function createExecutor(setPending, owners, environment, get, resolve, up
|
|
|
93
93
|
return result;
|
|
94
94
|
}
|
|
95
95
|
catch (error) {
|
|
96
|
+
// A run whose signal was aborted (a newer `latest` run took over, or its registration went
|
|
97
|
+
// away) usually rejects with that abort. It was stopped on purpose: not a failure to report.
|
|
98
|
+
if (controller.signal.aborted)
|
|
99
|
+
return skip('cancelled');
|
|
96
100
|
status = ActionStatus.Failed;
|
|
97
101
|
failure = error;
|
|
98
102
|
lifecycle.emit({ id, context, phase: 'failed', error });
|
|
@@ -18,9 +18,4 @@ export type Adapted = {
|
|
|
18
18
|
};
|
|
19
19
|
/** Configuration caps: false wins over any reactive result; true never bypasses guards. */
|
|
20
20
|
export declare function cap(presentation: ActionPresentation, override: Override): ActionPresentation;
|
|
21
|
-
/**
|
|
22
|
-
* The one adapter: static fields register as-is, function-valued fields are evaluated per
|
|
23
|
-
* input in `resolve`, `href` executes as navigation, `dialog` opens the host dialog and
|
|
24
|
-
* `execute` runs with validation, feedback and the shared execution guards.
|
|
25
|
-
*/
|
|
26
21
|
export declare function adaptAction(resolved: ResolvedContribution, host: ContributionHost, config: ConfigContext, events: Events, available?: () => boolean): Adapted;
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { CANCEL, navigate } from '@bitakit/core/actions';
|
|
2
2
|
import { ActionFailure } from '../actions/feedback.js';
|
|
3
3
|
import { isThenable, validate, validateSync } from '../schema.js';
|
|
4
|
+
import { contributionPath } from '../contribution-origin.js';
|
|
4
5
|
const dynamicKeys = [
|
|
5
6
|
'title',
|
|
6
7
|
'description',
|
|
@@ -28,7 +29,17 @@ export function cap(presentation, override) {
|
|
|
28
29
|
* input in `resolve`, `href` executes as navigation, `dialog` opens the host dialog and
|
|
29
30
|
* `execute` runs with validation, feedback and the shared execution guards.
|
|
30
31
|
*/
|
|
32
|
+
/** Fields only a server Action has; in a client Action they would silently not apply. */
|
|
33
|
+
const serverFields = ['access', 'expose', 'output'];
|
|
34
|
+
function rejectServerFields(resolved) {
|
|
35
|
+
const field = serverFields.find((name) => resolved[name] !== undefined);
|
|
36
|
+
if (!field)
|
|
37
|
+
return;
|
|
38
|
+
const path = (contributionPath(resolved) ?? resolved.id.split('.')).join('/');
|
|
39
|
+
throw new Error(`\`${field}\` is a server field. This file is the button; put the operation, with \`expose: true\`, in server/actions/${path}.ts and call it with remote.${resolved.id}().`);
|
|
40
|
+
}
|
|
31
41
|
export function adaptAction(resolved, host, config, events, available = () => true) {
|
|
42
|
+
rejectServerFields(resolved);
|
|
32
43
|
const override = host.override(resolved.id);
|
|
33
44
|
// Only `false` caps apply to the definition; `true` never bypasses the action's own guards.
|
|
34
45
|
const definition = override
|
|
@@ -101,6 +112,7 @@ export function adaptAction(resolved, host, config, events, available = () => tr
|
|
|
101
112
|
settings: host.app.settings,
|
|
102
113
|
app: host.app,
|
|
103
114
|
events,
|
|
115
|
+
remote: host.remote,
|
|
104
116
|
};
|
|
105
117
|
let result;
|
|
106
118
|
try {
|
|
@@ -158,7 +170,15 @@ export function adaptAction(resolved, host, config, events, available = () => tr
|
|
|
158
170
|
const request = evaluate(definition.confirm, context.input);
|
|
159
171
|
if (!request)
|
|
160
172
|
return undefined;
|
|
161
|
-
const
|
|
173
|
+
const { title, description, ...rest } = typeof request === 'string' ? { title: request, description: '' } : request;
|
|
174
|
+
// Like an Action's title: the text itself as a catalog key, then `<id>.confirm.title`
|
|
175
|
+
// and `.description`, then the literal.
|
|
176
|
+
const text = (value, part) => host.text(value, host.text(`${definition.id}.confirm.${part}`, value));
|
|
177
|
+
const accepted = await host.confirm({
|
|
178
|
+
...rest,
|
|
179
|
+
title: text(title, 'title'),
|
|
180
|
+
description: description ? text(description, 'description') : description,
|
|
181
|
+
});
|
|
162
182
|
return accepted ? undefined : CANCEL;
|
|
163
183
|
}
|
|
164
184
|
: undefined;
|
|
@@ -3,6 +3,7 @@ import type { Feedback, MessageValues } from '../actions/feedback.js';
|
|
|
3
3
|
import type { ResolvedContribution, Services, Translator } from '../definitions.js';
|
|
4
4
|
import type { BitaKitApp } from '../app/types.js';
|
|
5
5
|
import type { Confirmation } from '../confirmation.js';
|
|
6
|
+
import type { Remote } from '../remote.js';
|
|
6
7
|
export type FeedbackOutcome = {
|
|
7
8
|
message: string | false;
|
|
8
9
|
closeDialog: boolean;
|
|
@@ -25,6 +26,8 @@ export interface ContributionHost {
|
|
|
25
26
|
readonly app: BitaKitApp;
|
|
26
27
|
readonly actions: ActionList;
|
|
27
28
|
readonly services: Services;
|
|
29
|
+
/** The exposed server operations, passed to `execute` as `remote`. */
|
|
30
|
+
readonly remote: Remote;
|
|
28
31
|
translator(): Translator;
|
|
29
32
|
title(definition: ResolvedContribution): string;
|
|
30
33
|
description(definition: ResolvedContribution): string | undefined;
|
package/dist/core.d.ts
CHANGED
|
@@ -23,6 +23,10 @@ export { BitaKitServiceError } from './app/service-error.js';
|
|
|
23
23
|
export { resolveBitaKitConfig, type BitaKitOverrides } from './configuration.js';
|
|
24
24
|
export { BitaKitRuntime, createRuntime, type DialogState, type NormalizedPlugin, } from './runtime.js';
|
|
25
25
|
export { BitaKitStartupError, isBitaKitStartupError } from './startup-error.js';
|
|
26
|
+
export { OperationError, isOperationError, type OperationErrorCode, type OperationErrorReason, type OperationErrorJSON, type OperationIssue, } from './operation-error.js';
|
|
27
|
+
export type { ServerActionMap, ServerServiceMap, Remote, RemoteConfig, RemoteCallOptions, OperationFunction, } from './remote.js';
|
|
28
|
+
export type { RuntimeMode, RuntimeOptions } from './runtime-mode.js';
|
|
29
|
+
export type { Access, PermissionRequest, RequestContext, PublicContext, UserContext, OrganizationContext, } from './request-context.js';
|
|
26
30
|
export type { Cleanup } from './lifecycle/cleanup.js';
|
|
27
31
|
export type { LifecyclePhase, LifecycleFailure, LifecycleEntry, LifecycleSnapshot, LifecycleState, } from './lifecycle/state.js';
|
|
28
32
|
export { RuntimeController, createRuntimeController, describeStartupFailure, failedPluginClosure, pluginExposesService, } from './lifecycle/controller.js';
|
package/dist/core.js
CHANGED
|
@@ -15,6 +15,7 @@ export { BitaKitServiceError } from './app/service-error.js';
|
|
|
15
15
|
export { resolveBitaKitConfig } from './configuration.js';
|
|
16
16
|
export { BitaKitRuntime, createRuntime, } from './runtime.js';
|
|
17
17
|
export { BitaKitStartupError, isBitaKitStartupError } from './startup-error.js';
|
|
18
|
+
export { OperationError, isOperationError, } from './operation-error.js';
|
|
18
19
|
export { RuntimeController, createRuntimeController, describeStartupFailure, failedPluginClosure, pluginExposesService, } from './lifecycle/controller.js';
|
|
19
20
|
export { PluginScope, scopeModule, scopePlugins, scopeModules, scopeTranslation, scopeLifecycle, } from './scope.js';
|
|
20
21
|
export { mergePluginMessages } from './messages.js';
|
package/dist/definitions.d.ts
CHANGED
|
@@ -14,6 +14,7 @@ import type { InterceptorSpec } from './interceptors/define.js';
|
|
|
14
14
|
import type { Confirmation } from './confirmation.js';
|
|
15
15
|
import type { Cleanup } from './lifecycle/cleanup.js';
|
|
16
16
|
import type { SlotDefinition, SlotDefinitions } from './slots/define.js';
|
|
17
|
+
import type { Remote, RemoteConfig } from './remote.js';
|
|
17
18
|
/** Service IDs and aliases with their instance types. Generated from discovery; augmentable by hand. */
|
|
18
19
|
export interface ServiceMap {
|
|
19
20
|
}
|
|
@@ -26,6 +27,8 @@ export type ServiceContext = {
|
|
|
26
27
|
services: Services;
|
|
27
28
|
config: ConfigContext;
|
|
28
29
|
events: Events;
|
|
30
|
+
/** The exposed server operations: `await remote.todos.add(input)` (see `Remote`). */
|
|
31
|
+
remote: Remote;
|
|
29
32
|
/** Typed setting handles: `settings.todos.pageSize.get()`. */
|
|
30
33
|
settings: SettingsAccess;
|
|
31
34
|
/** Observable state; actions and `useServiceState` follow it automatically. */
|
|
@@ -84,6 +87,8 @@ export type ExecuteContext<Input = unknown> = ActionContext<Input> & {
|
|
|
84
87
|
settings: SettingsAccess;
|
|
85
88
|
app: BitaKitApp;
|
|
86
89
|
events: Events;
|
|
90
|
+
/** The exposed server operations: `await remote.todos.add(input)` (see `Remote`). */
|
|
91
|
+
remote: Remote;
|
|
87
92
|
/** Aborts when the registration is disposed, or when a newer `latest` run supersedes this one. */
|
|
88
93
|
signal: AbortSignal;
|
|
89
94
|
};
|
|
@@ -354,6 +359,11 @@ export type BitaKitRuntimeConfig = Omit<Plugin, 'id' | 'dependencies' | 'parent'
|
|
|
354
359
|
bundle?: string;
|
|
355
360
|
/** Host-known bundle labels. A plugin's membership claim does not add entries here. */
|
|
356
361
|
knownBundles?: readonly import('./inspection/plugin-origin.js').PluginBundle[];
|
|
362
|
+
/**
|
|
363
|
+
* The exposed server operations and their endpoint, generated into the client config. Without
|
|
364
|
+
* it every `remote` call rejects with SERVICE_UNAVAILABLE.
|
|
365
|
+
*/
|
|
366
|
+
remote?: RemoteConfig;
|
|
357
367
|
};
|
|
358
368
|
/** A literal string wins; a widened `string` or a missing value falls back. */
|
|
359
369
|
type LiteralOr<Value, Fallback> = [NonNullable<Value>] extends [string] ? string extends NonNullable<Value> ? Fallback : NonNullable<Value> : Fallback;
|
package/dist/events/service.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import type { Events, EventErrorHandler, BitaKitEvent } from './types.js';
|
|
2
2
|
import type { EventsDefinition } from './define.js';
|
|
3
|
+
import type { RequestContext } from '../request-context.js';
|
|
3
4
|
/**
|
|
4
5
|
* One bus per runtime. Delivery is synchronous and ordered; async handlers are awaited only
|
|
5
6
|
* for error reporting, or fully for cancelable events. Declared namespaces belong to the
|
|
@@ -14,11 +15,15 @@ export declare class EventService implements Events {
|
|
|
14
15
|
private declared;
|
|
15
16
|
private reserved;
|
|
16
17
|
private reservedEvents;
|
|
18
|
+
private lookupCache?;
|
|
17
19
|
constructor(onError?: EventErrorHandler);
|
|
18
20
|
/** Registers a plugin's `events.ts`; its names live under `<plugin>.`. */
|
|
19
21
|
declare(plugin: string, definition: EventsDefinition): void;
|
|
20
22
|
/** Release a stopped owner’s declaration without removing other owners’ listeners. */
|
|
21
23
|
undeclare(plugin: string): void;
|
|
24
|
+
private get lookup();
|
|
25
|
+
/** The declared or reserved namespace a (case-folded) namespace reference names. */
|
|
26
|
+
private namespace;
|
|
22
27
|
/** The plugin that declared the namespace of an event name, if any. */
|
|
23
28
|
ownerOf(name: string): string | undefined;
|
|
24
29
|
resolve(name: string): string;
|
|
@@ -26,9 +31,16 @@ export declare class EventService implements Events {
|
|
|
26
31
|
/** Reserves a runtime-owned namespace and returns its private publishing capability. */
|
|
27
32
|
reserve(namespace: string): (name: string, data: unknown) => void;
|
|
28
33
|
emit: Events["emit"];
|
|
34
|
+
/**
|
|
35
|
+
* Emits on behalf of a server call: listeners receive `ctx` as `{ signal, ctx }`. It is never
|
|
36
|
+
* part of the event object. `undefined` behaves exactly like `emit`.
|
|
37
|
+
*/
|
|
38
|
+
emitWithContext(ctx: RequestContext | undefined, name: string, data?: unknown): void | Promise<boolean>;
|
|
29
39
|
private dispatch;
|
|
30
40
|
private emitCancelable;
|
|
41
|
+
/** Exact listeners (in subscription order), then prefix listeners; each listener once. */
|
|
31
42
|
private listenersFor;
|
|
43
|
+
private indexExact;
|
|
32
44
|
private report;
|
|
33
45
|
on: Events["on"];
|
|
34
46
|
/** Diagnostics only: receives every event after delivery. It cannot change or stop delivery. */
|
|
@@ -43,5 +55,7 @@ export declare class EventService implements Events {
|
|
|
43
55
|
*/
|
|
44
56
|
export declare function createEventScope(events: EventService, owner?: string): {
|
|
45
57
|
events: Events;
|
|
58
|
+
/** The same view whose `emit` hands a server call's `ctx` to listeners. */
|
|
59
|
+
withContext: (ctx: RequestContext) => Events;
|
|
46
60
|
dispose(): void;
|
|
47
61
|
};
|