@bitakit/core 0.2.2 → 0.2.3
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 +13 -13
- package/dist/app/types.d.ts +3 -1
- package/dist/runtime.js +3 -1
- package/package.json +1 -1
- package/testing/index.d.ts +17 -0
- package/testing/index.mjs +74 -4
package/README.md
CHANGED
|
@@ -44,19 +44,19 @@ resolve within a repository checkout and follow the branch viewed on GitHub. Run
|
|
|
44
44
|
`npm run dev:docs` from the repository root to read the rendered handbook at
|
|
45
45
|
`http://localhost:3002/docs`. A public documentation address is not configured yet.
|
|
46
46
|
|
|
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 | [Plugin manager](../../apps/docs/content/docs/plugin-management.mdx)
|
|
56
|
-
| Activate a trusted package catalog
|
|
57
|
-
| Authentication contract
|
|
58
|
-
| Test a plugin folder
|
|
59
|
-
| Standalone example
|
|
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
60
|
|
|
61
61
|
Plugins are trusted application code. Core is not a sandbox, package installer or remote
|
|
62
62
|
marketplace. Services own state and resources; the host owns routing, persistence providers
|
package/dist/app/types.d.ts
CHANGED
|
@@ -58,7 +58,9 @@ export type PublicEventsOf<Plugins extends readonly Plugin[]> = [Plugins[number]
|
|
|
58
58
|
events: infer E;
|
|
59
59
|
} ? EventsOf<E, Id> : {} : never>;
|
|
60
60
|
/** `CancelableEventMap` entries of manually composed or installed package plugins. */
|
|
61
|
-
export type PublicCancelableOf<Plugins extends readonly Plugin[]> = [Plugins[number]] extends [
|
|
61
|
+
export type PublicCancelableOf<Plugins extends readonly Plugin[]> = [Plugins[number]] extends [
|
|
62
|
+
never
|
|
63
|
+
] ? {} : Intersection<Plugins[number] extends infer P ? P extends {
|
|
62
64
|
id: infer Id extends string;
|
|
63
65
|
events: infer E;
|
|
64
66
|
} ? CancelableOf<E, Id> : {} : never>;
|
package/dist/runtime.js
CHANGED
|
@@ -895,7 +895,9 @@ export class BitaKitRuntime {
|
|
|
895
895
|
});
|
|
896
896
|
}
|
|
897
897
|
connectTranslation() {
|
|
898
|
-
const i18n = this.hasService('i18n')
|
|
898
|
+
const i18n = this.hasService('i18n')
|
|
899
|
+
? getService(this.services, translationService)
|
|
900
|
+
: undefined;
|
|
899
901
|
if (!i18n)
|
|
900
902
|
return;
|
|
901
903
|
this.setTranslations(i18n.translate);
|
package/package.json
CHANGED
package/testing/index.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import type {
|
|
2
|
+
AuthService,
|
|
2
3
|
EventService,
|
|
3
4
|
BitaKitApp,
|
|
4
5
|
BitaKitEvent,
|
|
@@ -57,3 +58,19 @@ export function mountPlugin(
|
|
|
57
58
|
configOverrides?: Readonly<Record<string, Record<string, unknown>>>;
|
|
58
59
|
},
|
|
59
60
|
): Promise<MountedPlugin>;
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* Checks an `auth` provider against the AuthService contract, for the provider's own tests:
|
|
64
|
+
* a stable snapshot, working subscribe/unsubscribe, a string `user.id` after `signIn`, an
|
|
65
|
+
* awaited `signOut` that clears the user, and valid optional `paths` and `signIn`. Rejects with
|
|
66
|
+
* the first broken rule.
|
|
67
|
+
*/
|
|
68
|
+
export function assertAuthContract(
|
|
69
|
+
service: AuthService,
|
|
70
|
+
options: {
|
|
71
|
+
/** Signs a test user in through the provider's own login. Called twice. */
|
|
72
|
+
signIn(): Promise<unknown>;
|
|
73
|
+
/** Milliseconds to wait for a pending session or a sign-in to settle (default 2000). */
|
|
74
|
+
timeout?: number;
|
|
75
|
+
},
|
|
76
|
+
): Promise<void>;
|
package/testing/index.mjs
CHANGED
|
@@ -13,6 +13,7 @@ import {
|
|
|
13
13
|
discoverServices,
|
|
14
14
|
discoverSlots,
|
|
15
15
|
discoveredFile,
|
|
16
|
+
configureAuthPaths,
|
|
16
17
|
} from '../dist/core.js';
|
|
17
18
|
|
|
18
19
|
/** The plugin ID a package declares (`bitakit.id`), or one derived from its name. */
|
|
@@ -104,9 +105,7 @@ export async function mountPlugin(directory = 'src', options = {}) {
|
|
|
104
105
|
const plugin = await loadPlugin(directory, options.id);
|
|
105
106
|
const { id } = plugin;
|
|
106
107
|
const others = await Promise.all(
|
|
107
|
-
(options.plugins ?? []).map((other) =>
|
|
108
|
-
typeof other === 'string' ? loadPlugin(other) : other,
|
|
109
|
-
),
|
|
108
|
+
(options.plugins ?? []).map((other) => (typeof other === 'string' ? loadPlugin(other) : other)),
|
|
110
109
|
);
|
|
111
110
|
const runtime = createRuntime(
|
|
112
111
|
{ plugins: [plugin, ...others], configOverrides: options.configOverrides },
|
|
@@ -129,7 +128,9 @@ export async function mountPlugin(directory = 'src', options = {}) {
|
|
|
129
128
|
runtime.mount();
|
|
130
129
|
await runtime.ready;
|
|
131
130
|
} catch (error) {
|
|
132
|
-
try {
|
|
131
|
+
try {
|
|
132
|
+
await release();
|
|
133
|
+
} catch (cleanupError) {
|
|
133
134
|
throw new AggregateError([error, cleanupError], 'Plugin startup and cleanup failed.');
|
|
134
135
|
}
|
|
135
136
|
throw error;
|
|
@@ -148,3 +149,72 @@ export async function mountPlugin(directory = 'src', options = {}) {
|
|
|
148
149
|
[Symbol.asyncDispose]: release,
|
|
149
150
|
};
|
|
150
151
|
}
|
|
152
|
+
|
|
153
|
+
const settle = () => new Promise((resolve) => setTimeout(resolve, 0));
|
|
154
|
+
|
|
155
|
+
/** Waits until `ready()` holds, failing with `message` after `timeout` milliseconds. */
|
|
156
|
+
async function until(ready, message, timeout) {
|
|
157
|
+
const deadline = Date.now() + timeout;
|
|
158
|
+
while (!ready()) {
|
|
159
|
+
if (Date.now() > deadline) throw new Error(`auth contract: ${message}`);
|
|
160
|
+
await new Promise((resolve) => setTimeout(resolve, 5));
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
/**
|
|
165
|
+
* Checks an `auth` provider against the AuthService contract, for the provider's own tests:
|
|
166
|
+
* a stable snapshot, working subscribe/unsubscribe, a string `user.id` after `signIn`, an
|
|
167
|
+
* awaited `signOut` that clears the user, and valid optional `paths`/`signIn`. `signIn` drives
|
|
168
|
+
* the provider's own login. Rejects with the first broken rule.
|
|
169
|
+
*/
|
|
170
|
+
export async function assertAuthContract(service, { signIn, timeout = 2000 }) {
|
|
171
|
+
const fail = (rule) => {
|
|
172
|
+
throw new Error(`auth contract: ${rule}`);
|
|
173
|
+
};
|
|
174
|
+
for (const method of ['getSnapshot', 'subscribe', 'signOut'])
|
|
175
|
+
if (typeof service?.[method] !== 'function') fail(`${method}() is missing.`);
|
|
176
|
+
if (service.signIn !== undefined && typeof service.signIn !== 'function')
|
|
177
|
+
fail('signIn must be a function when present.');
|
|
178
|
+
if (service.paths !== undefined) {
|
|
179
|
+
try {
|
|
180
|
+
configureAuthPaths(service.paths);
|
|
181
|
+
} catch (error) {
|
|
182
|
+
fail(`paths are invalid: ${error.message}`);
|
|
183
|
+
}
|
|
184
|
+
}
|
|
185
|
+
await until(() => !service.getSnapshot().pending, 'the snapshot stays pending.', timeout);
|
|
186
|
+
const initial = service.getSnapshot();
|
|
187
|
+
for (const key of ['user', 'pending', 'error'])
|
|
188
|
+
if (!(key in initial)) fail(`the snapshot has no "${key}".`);
|
|
189
|
+
if (service.getSnapshot() !== initial)
|
|
190
|
+
fail('getSnapshot() must return the same object until it changes.');
|
|
191
|
+
if (initial.user !== null && !initial.error) await service.signOut();
|
|
192
|
+
|
|
193
|
+
let notified = 0;
|
|
194
|
+
const unsubscribe = service.subscribe(() => notified++);
|
|
195
|
+
if (typeof unsubscribe !== 'function') fail('subscribe() must return an unsubscribe function.');
|
|
196
|
+
await signIn();
|
|
197
|
+
await until(() => service.getSnapshot().user !== null, 'no user after signIn.', timeout);
|
|
198
|
+
const signedIn = service.getSnapshot();
|
|
199
|
+
if (typeof signedIn.user.id !== 'string' || !signedIn.user.id)
|
|
200
|
+
fail('user.id must be a non-empty string.');
|
|
201
|
+
if (signedIn.pending) fail('pending must be false once the user is known.');
|
|
202
|
+
if (signedIn.error) fail('a signed-in snapshot must not carry an error.');
|
|
203
|
+
if (signedIn === initial) fail('the snapshot must be a new object after a change.');
|
|
204
|
+
if (service.getSnapshot() !== signedIn) fail('the signed-in snapshot must be stable.');
|
|
205
|
+
if (notified === 0) fail('subscribe() listeners must be called when the session changes.');
|
|
206
|
+
|
|
207
|
+
const result = service.signOut();
|
|
208
|
+
if (typeof result?.then !== 'function') fail('signOut() must return a promise.');
|
|
209
|
+
await result;
|
|
210
|
+
const signedOut = service.getSnapshot();
|
|
211
|
+
if (signedOut.user !== null) fail('signOut() must resolve after the user is cleared.');
|
|
212
|
+
if (signedOut.pending) fail('pending must be false after signOut().');
|
|
213
|
+
|
|
214
|
+
unsubscribe();
|
|
215
|
+
const after = notified;
|
|
216
|
+
await signIn();
|
|
217
|
+
await settle();
|
|
218
|
+
if (notified !== after) fail('listeners must not be called after unsubscribe.');
|
|
219
|
+
await service.signOut();
|
|
220
|
+
}
|