@runic-artifex/svelte 0.1.0-preview.14.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/LICENSE +22 -0
- package/README.md +127 -0
- package/dist/bridge.svelte.d.ts +18 -0
- package/dist/bridge.svelte.js +147 -0
- package/dist/context.svelte.d.ts +9 -0
- package/dist/context.svelte.js +21 -0
- package/dist/effect-action.svelte.d.ts +22 -0
- package/dist/effect-action.svelte.js +99 -0
- package/dist/effect-bridge.svelte.d.ts +19 -0
- package/dist/effect-bridge.svelte.js +46 -0
- package/dist/index.d.ts +5 -0
- package/dist/index.js +5 -0
- package/dist/translations/context.svelte.d.ts +15 -0
- package/dist/translations/context.svelte.js +25 -0
- package/dist/translations/index.d.ts +2 -0
- package/dist/translations/index.js +2 -0
- package/dist/translations/locale.svelte.d.ts +35 -0
- package/dist/translations/locale.svelte.js +65 -0
- package/dist/types.d.ts +49 -0
- package/dist/types.js +1 -0
- package/package.json +52 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Runic Artifex contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
22
|
+
|
package/README.md
ADDED
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
# `@runic-artifex/svelte`
|
|
2
|
+
|
|
3
|
+
Svelte 5-only projection and lifecycle support for a Runic Toolkit Application
|
|
4
|
+
Bridge controller.
|
|
5
|
+
|
|
6
|
+
## Runic Translations locale state
|
|
7
|
+
|
|
8
|
+
Translation support is isolated in `@runic-artifex/svelte/translations`. It
|
|
9
|
+
consumes the structural `LocaleSource` emitted by Runic Translations and does
|
|
10
|
+
not make the generated catalog a runtime dependency.
|
|
11
|
+
|
|
12
|
+
Create one typed context in an application module:
|
|
13
|
+
|
|
14
|
+
```ts
|
|
15
|
+
// src/lib/locale-context.ts
|
|
16
|
+
import { createLocaleContext } from "@runic-artifex/svelte/translations";
|
|
17
|
+
|
|
18
|
+
export type AppLocale = "en" | "de";
|
|
19
|
+
export const localeContext = createLocaleContext<AppLocale>();
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Create one locale source per browser root or SSR component tree and provide it
|
|
23
|
+
from the root layout. `createLocaleSource` is generated for the catalog:
|
|
24
|
+
|
|
25
|
+
```svelte
|
|
26
|
+
<script lang="ts">
|
|
27
|
+
import { createLocaleSource } from "virtual:runic-translations/app/runtime";
|
|
28
|
+
import { localeContext } from "$lib/locale-context";
|
|
29
|
+
|
|
30
|
+
let { data, children } = $props();
|
|
31
|
+
const source = createLocaleSource({ initialLocale: data.locale });
|
|
32
|
+
localeContext.provide(source);
|
|
33
|
+
</script>
|
|
34
|
+
|
|
35
|
+
{@render children()}
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Message options read reactive rune state, so a source notification invalidates
|
|
39
|
+
the rendered call without a reload:
|
|
40
|
+
|
|
41
|
+
```svelte
|
|
42
|
+
<script lang="ts">
|
|
43
|
+
import { m } from "virtual:runic-translations/app";
|
|
44
|
+
import { localeContext } from "$lib/locale-context";
|
|
45
|
+
|
|
46
|
+
const locale = localeContext.use();
|
|
47
|
+
</script>
|
|
48
|
+
|
|
49
|
+
<h1>{m["Common.Hello"]({ name: "Ada" }, locale.messageOptions)}</h1>
|
|
50
|
+
<button onclick={() => locale.setLocale("de")}>Deutsch</button>
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
`locale.setLocale` writes a mutable source by default. Pass `requestLocale`
|
|
54
|
+
when navigation or an application setting is authoritative instead. The state
|
|
55
|
+
refreshes from the source after that callback completes; the callback should
|
|
56
|
+
therefore update the source directly or complete the navigation that does so.
|
|
57
|
+
|
|
58
|
+
Providers subscribe during component initialization, including SSR, and
|
|
59
|
+
unsubscribe in `onDestroy`. Context makes each render request-scoped; no global
|
|
60
|
+
generated resolver is configured. Nested providers shadow their parent and
|
|
61
|
+
dispose only their own subscription. Pass `dispose: false` only when the caller
|
|
62
|
+
owns a longer-lived state. Hydration is deterministic when the client source is
|
|
63
|
+
initialized from the locale returned by the root server load.
|
|
64
|
+
|
|
65
|
+
Explicit `{ locale }` message options remain authoritative on the server. The
|
|
66
|
+
adapter deliberately has no cookie, URL, or router behavior; SvelteKit support
|
|
67
|
+
lives in `@runic-artifex/sveltekit/translations`.
|
|
68
|
+
|
|
69
|
+
## Application Bridge
|
|
70
|
+
|
|
71
|
+
Create the typed context once in an application module, provide it in the root
|
|
72
|
+
layout/component, and consume the same context below that boundary. State uses
|
|
73
|
+
Svelte 5 runes and immutable snapshots use `$state.raw`.
|
|
74
|
+
|
|
75
|
+
The first mount starts the controller, initializes its authoritative snapshot,
|
|
76
|
+
and announces `uiReady` followed by `uiRendered`. Repeated starts do not repeat
|
|
77
|
+
those lifecycle messages, and unmount performs idempotent disposal.
|
|
78
|
+
|
|
79
|
+
The integration never parses the protocol and never creates a second Effect
|
|
80
|
+
runtime. It owns only Svelte lifecycle and projection concerns.
|
|
81
|
+
|
|
82
|
+
## Opt-in Effect workflows
|
|
83
|
+
|
|
84
|
+
Use `createEffectSvelteApplicationBridge` with an Effect-aware Application
|
|
85
|
+
Bridge controller when a UI workflow benefits from typed failures, composition,
|
|
86
|
+
structured concurrency, or interruption. The existing Promise methods remain
|
|
87
|
+
available for ordinary event handlers.
|
|
88
|
+
|
|
89
|
+
The enhanced bridge exposes:
|
|
90
|
+
|
|
91
|
+
- `effects`, containing the typed `initialize`, `dispatch`, `cancel`, reconnect,
|
|
92
|
+
lifecycle, and event Stream programs;
|
|
93
|
+
- `run` and `runExit`, which execute a composed program in the controller's
|
|
94
|
+
existing `ManagedRuntime`;
|
|
95
|
+
- `createAction`, which projects one latest-wins Fiber into Svelte-native
|
|
96
|
+
`status`, `value`, `error`, `cause`, and `exit` state.
|
|
97
|
+
|
|
98
|
+
An action interrupts its previous invocation before starting another. Disposing
|
|
99
|
+
the root bridge interrupts every action it created. Fiber interruption only
|
|
100
|
+
stops the frontend workflow; backend operation cancellation remains the
|
|
101
|
+
explicit `cancel(operationId)` protocol operation.
|
|
102
|
+
|
|
103
|
+
```ts
|
|
104
|
+
import { Effect } from "effect";
|
|
105
|
+
import { createEffectSvelteApplicationBridge } from "@runic-artifex/svelte";
|
|
106
|
+
|
|
107
|
+
const bridge = createEffectSvelteApplicationBridge(controller);
|
|
108
|
+
const install = bridge.createAction((command, effects) =>
|
|
109
|
+
effects.dispatch(command).pipe(
|
|
110
|
+
Effect.retry({ times: 2 }),
|
|
111
|
+
)
|
|
112
|
+
);
|
|
113
|
+
|
|
114
|
+
// Components can use install.running, install.value, and install.error.
|
|
115
|
+
void install.run({ _tag: "StartInstallation", selectionId });
|
|
116
|
+
|
|
117
|
+
// Simple calls stay simple.
|
|
118
|
+
await bridge.dispatch({ _tag: "Navigate", target: "Summary" });
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
Keep transient presentation state in Svelte runes. Put substantial Effect
|
|
122
|
+
programs in framework-neutral TypeScript modules and use actions only to project
|
|
123
|
+
their lifecycle into the component tree.
|
|
124
|
+
|
|
125
|
+
If the host uses Runic Flow, embed the relevant process state in the application's
|
|
126
|
+
named snapshot and project it with `reduce`. Flow remains backend-only; this
|
|
127
|
+
package neither imports Flow vocabulary nor creates a competing state runtime.
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import type { ApplicationBridgeController, ApplicationBridgeStatus, SvelteApplicationBridgeOptions } from "./types.js";
|
|
2
|
+
export declare class SvelteApplicationBridge<Command, Receipt, HostEvent, Snapshot, Failure = unknown> {
|
|
3
|
+
#private;
|
|
4
|
+
snapshot: Snapshot | undefined;
|
|
5
|
+
lastEvent: HostEvent | undefined;
|
|
6
|
+
error: Failure | undefined;
|
|
7
|
+
status: ApplicationBridgeStatus;
|
|
8
|
+
constructor(controller: ApplicationBridgeController<Command, Receipt, HostEvent, Snapshot, Failure>, options?: SvelteApplicationBridgeOptions<HostEvent, Snapshot>);
|
|
9
|
+
start(): Promise<Snapshot>;
|
|
10
|
+
dispatch(command: Command): Promise<Receipt>;
|
|
11
|
+
cancel(operationId: string): Promise<void>;
|
|
12
|
+
reconnect(): Promise<Snapshot>;
|
|
13
|
+
uiReady(): Promise<void>;
|
|
14
|
+
uiRendered(): Promise<void>;
|
|
15
|
+
clearError(): void;
|
|
16
|
+
dispose(): Promise<void>;
|
|
17
|
+
}
|
|
18
|
+
export declare function createSvelteApplicationBridge<Command, Receipt, HostEvent, Snapshot, Failure = unknown>(controller: ApplicationBridgeController<Command, Receipt, HostEvent, Snapshot, Failure>, options?: SvelteApplicationBridgeOptions<HostEvent, Snapshot>): SvelteApplicationBridge<Command, Receipt, HostEvent, Snapshot, Failure>;
|
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
export class SvelteApplicationBridge {
|
|
2
|
+
snapshot = $state.raw(undefined);
|
|
3
|
+
lastEvent = $state.raw(undefined);
|
|
4
|
+
error = $state.raw(undefined);
|
|
5
|
+
status = $state("idle");
|
|
6
|
+
#controller;
|
|
7
|
+
#reduce;
|
|
8
|
+
#observer;
|
|
9
|
+
#inspectSnapshot;
|
|
10
|
+
#unsubscribe;
|
|
11
|
+
#start;
|
|
12
|
+
constructor(controller, options = {}) {
|
|
13
|
+
this.#controller = controller;
|
|
14
|
+
this.#reduce = options.reduce;
|
|
15
|
+
this.#observer = options.observer;
|
|
16
|
+
this.#inspectSnapshot = options.inspectSnapshot;
|
|
17
|
+
}
|
|
18
|
+
start() {
|
|
19
|
+
if (this.status === "disposed")
|
|
20
|
+
return Promise.reject(new Error("The Svelte Application Bridge is disposed."));
|
|
21
|
+
if (this.#start)
|
|
22
|
+
return this.#start;
|
|
23
|
+
this.status = "connecting";
|
|
24
|
+
this.error = undefined;
|
|
25
|
+
this.#reportConnection("connecting");
|
|
26
|
+
this.#unsubscribe ??= this.#controller.subscribe((event) => {
|
|
27
|
+
this.lastEvent = event;
|
|
28
|
+
this.snapshot = this.#reduce?.(this.snapshot, event) ?? this.snapshot;
|
|
29
|
+
this.#observer?.trace({ kind: "event", label: tagOf(event) });
|
|
30
|
+
this.#reportConnection("connected");
|
|
31
|
+
}, (failure) => this.#fail(failure));
|
|
32
|
+
this.#start = this.#controller.initialize()
|
|
33
|
+
.then(async (snapshot) => {
|
|
34
|
+
this.snapshot = snapshot;
|
|
35
|
+
this.status = "connected";
|
|
36
|
+
this.#reportSnapshot(snapshot, "connected");
|
|
37
|
+
await this.#controller.uiReady();
|
|
38
|
+
await this.#controller.uiRendered();
|
|
39
|
+
this.#observer?.trace({ kind: "connection", label: "ui-rendered" });
|
|
40
|
+
return snapshot;
|
|
41
|
+
})
|
|
42
|
+
.catch((failure) => {
|
|
43
|
+
this.#start = undefined;
|
|
44
|
+
this.#fail(failure);
|
|
45
|
+
throw failure;
|
|
46
|
+
});
|
|
47
|
+
return this.#start;
|
|
48
|
+
}
|
|
49
|
+
async dispatch(command) {
|
|
50
|
+
this.#observer?.trace({ kind: "command", label: tagOf(command) });
|
|
51
|
+
try {
|
|
52
|
+
const receipt = await this.#controller.dispatch(command);
|
|
53
|
+
this.#observer?.trace({ kind: "receipt", label: tagOf(receipt) });
|
|
54
|
+
return receipt;
|
|
55
|
+
}
|
|
56
|
+
catch (failure) {
|
|
57
|
+
this.#failUnknown(failure);
|
|
58
|
+
throw failure;
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
async cancel(operationId) {
|
|
62
|
+
this.#observer?.trace({ kind: "operation", label: "CancelOperation", detail: { operationId } });
|
|
63
|
+
try {
|
|
64
|
+
await this.#controller.cancel(operationId);
|
|
65
|
+
}
|
|
66
|
+
catch (failure) {
|
|
67
|
+
this.#failUnknown(failure);
|
|
68
|
+
throw failure;
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
async reconnect() {
|
|
72
|
+
this.status = "reconnecting";
|
|
73
|
+
this.error = undefined;
|
|
74
|
+
this.#reportConnection("connecting");
|
|
75
|
+
try {
|
|
76
|
+
const snapshot = await this.#controller.reconnect();
|
|
77
|
+
this.snapshot = snapshot;
|
|
78
|
+
this.status = "connected";
|
|
79
|
+
this.#reportSnapshot(snapshot, "connected");
|
|
80
|
+
return snapshot;
|
|
81
|
+
}
|
|
82
|
+
catch (failure) {
|
|
83
|
+
this.#failUnknown(failure);
|
|
84
|
+
throw failure;
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
uiReady() {
|
|
88
|
+
return this.#controller.uiReady();
|
|
89
|
+
}
|
|
90
|
+
uiRendered() {
|
|
91
|
+
return this.#controller.uiRendered();
|
|
92
|
+
}
|
|
93
|
+
clearError() {
|
|
94
|
+
this.error = undefined;
|
|
95
|
+
if (this.status === "error")
|
|
96
|
+
this.status = this.snapshot === undefined ? "idle" : "connected";
|
|
97
|
+
}
|
|
98
|
+
async dispose() {
|
|
99
|
+
if (this.status === "disposed")
|
|
100
|
+
return;
|
|
101
|
+
this.#unsubscribe?.();
|
|
102
|
+
this.#unsubscribe = undefined;
|
|
103
|
+
await this.#controller.dispose();
|
|
104
|
+
this.status = "disposed";
|
|
105
|
+
this.#reportConnection("closed");
|
|
106
|
+
}
|
|
107
|
+
#fail(failure) {
|
|
108
|
+
this.error = failure;
|
|
109
|
+
this.status = "error";
|
|
110
|
+
this.#observer?.trace({ kind: "error", label: errorLabel(failure) });
|
|
111
|
+
this.#reportConnection("disconnected");
|
|
112
|
+
}
|
|
113
|
+
#failUnknown(failure) {
|
|
114
|
+
// Promise does not encode its rejection type; the controller contract does.
|
|
115
|
+
this.#fail(failure);
|
|
116
|
+
}
|
|
117
|
+
#reportSnapshot(snapshot, state) {
|
|
118
|
+
const inspected = this.#inspectSnapshot?.(snapshot) ?? {};
|
|
119
|
+
this.#observer?.state({
|
|
120
|
+
connection: {
|
|
121
|
+
state,
|
|
122
|
+
transport: "application-bridge",
|
|
123
|
+
...inspected,
|
|
124
|
+
},
|
|
125
|
+
});
|
|
126
|
+
}
|
|
127
|
+
#reportConnection(state) {
|
|
128
|
+
this.#observer?.state({ connection: { state, transport: "application-bridge" } });
|
|
129
|
+
this.#observer?.trace({ kind: "connection", label: state });
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
export function createSvelteApplicationBridge(controller, options = {}) {
|
|
133
|
+
return new SvelteApplicationBridge(controller, options);
|
|
134
|
+
}
|
|
135
|
+
function tagOf(value) {
|
|
136
|
+
if (typeof value === "object" && value !== null && "_tag" in value) {
|
|
137
|
+
const tag = value._tag;
|
|
138
|
+
if (typeof tag === "string" && tag.length > 0)
|
|
139
|
+
return tag.slice(0, 128);
|
|
140
|
+
}
|
|
141
|
+
return "Unknown";
|
|
142
|
+
}
|
|
143
|
+
function errorLabel(failure) {
|
|
144
|
+
if (typeof failure === "object" && failure !== null && "_tag" in failure)
|
|
145
|
+
return tagOf(failure);
|
|
146
|
+
return failure instanceof Error ? failure.name.slice(0, 128) : "ApplicationBridgeError";
|
|
147
|
+
}
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
import type { SvelteApplicationBridge } from "./bridge.svelte.js";
|
|
2
|
+
export interface ApplicationBridgeContext<Command, Receipt, HostEvent, Snapshot, Failure = unknown> {
|
|
3
|
+
provide(bridge: SvelteApplicationBridge<Command, Receipt, HostEvent, Snapshot, Failure>, options?: Readonly<{
|
|
4
|
+
start?: boolean;
|
|
5
|
+
dispose?: boolean;
|
|
6
|
+
}>): SvelteApplicationBridge<Command, Receipt, HostEvent, Snapshot, Failure>;
|
|
7
|
+
use(): SvelteApplicationBridge<Command, Receipt, HostEvent, Snapshot, Failure>;
|
|
8
|
+
}
|
|
9
|
+
export declare function createApplicationBridgeContext<Command, Receipt, HostEvent, Snapshot, Failure = unknown>(): ApplicationBridgeContext<Command, Receipt, HostEvent, Snapshot, Failure>;
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import { createContext, onMount } from "svelte";
|
|
2
|
+
export function createApplicationBridgeContext() {
|
|
3
|
+
const [use, set] = createContext();
|
|
4
|
+
return {
|
|
5
|
+
provide(bridge, options = {}) {
|
|
6
|
+
set(bridge);
|
|
7
|
+
const shouldStart = options.start ?? true;
|
|
8
|
+
const shouldDispose = options.dispose ?? true;
|
|
9
|
+
onMount(() => {
|
|
10
|
+
if (shouldStart)
|
|
11
|
+
void bridge.start();
|
|
12
|
+
return () => {
|
|
13
|
+
if (shouldDispose)
|
|
14
|
+
void bridge.dispose();
|
|
15
|
+
};
|
|
16
|
+
});
|
|
17
|
+
return bridge;
|
|
18
|
+
},
|
|
19
|
+
use,
|
|
20
|
+
};
|
|
21
|
+
}
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import { Cause, Effect, Exit } from "effect";
|
|
2
|
+
import type { EffectActionStatus, EffectRunner } from "./types.js";
|
|
3
|
+
/**
|
|
4
|
+
* Projects one latest-wins Effect workflow into Svelte-native reactive state.
|
|
5
|
+
* The supplied runner owns the Fiber; this class never creates an Effect runtime.
|
|
6
|
+
*/
|
|
7
|
+
export declare class SvelteEffectAction<Input, Success, Failure, Requirements> {
|
|
8
|
+
#private;
|
|
9
|
+
status: EffectActionStatus;
|
|
10
|
+
value: Success | undefined;
|
|
11
|
+
error: Failure | undefined;
|
|
12
|
+
cause: Cause.Cause<Failure> | undefined;
|
|
13
|
+
exit: Exit.Exit<Success, Failure> | undefined;
|
|
14
|
+
constructor(runner: EffectRunner<Requirements>, program: (input: Input) => Effect.Effect<Success, Failure, Requirements>, onDispose?: () => void);
|
|
15
|
+
get running(): boolean;
|
|
16
|
+
/** Runs the workflow, interrupting an older invocation owned by this action. */
|
|
17
|
+
run(input: Input): Promise<Exit.Exit<Success, Failure>>;
|
|
18
|
+
/** Interrupts the current frontend workflow without implying backend cancellation. */
|
|
19
|
+
interrupt(): Promise<Exit.Exit<Success, Failure> | undefined>;
|
|
20
|
+
reset(): void;
|
|
21
|
+
dispose(): Promise<void>;
|
|
22
|
+
}
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
import { Cause, Effect, Exit, Option } from "effect";
|
|
2
|
+
/**
|
|
3
|
+
* Projects one latest-wins Effect workflow into Svelte-native reactive state.
|
|
4
|
+
* The supplied runner owns the Fiber; this class never creates an Effect runtime.
|
|
5
|
+
*/
|
|
6
|
+
export class SvelteEffectAction {
|
|
7
|
+
status = $state("idle");
|
|
8
|
+
value = $state.raw(undefined);
|
|
9
|
+
error = $state.raw(undefined);
|
|
10
|
+
cause = $state.raw(undefined);
|
|
11
|
+
exit = $state.raw(undefined);
|
|
12
|
+
#runner;
|
|
13
|
+
#program;
|
|
14
|
+
#onDispose;
|
|
15
|
+
#fiber;
|
|
16
|
+
#generation = 0;
|
|
17
|
+
#disposed = false;
|
|
18
|
+
constructor(runner, program, onDispose) {
|
|
19
|
+
this.#runner = runner;
|
|
20
|
+
this.#program = program;
|
|
21
|
+
this.#onDispose = onDispose;
|
|
22
|
+
}
|
|
23
|
+
get running() {
|
|
24
|
+
return this.status === "running";
|
|
25
|
+
}
|
|
26
|
+
/** Runs the workflow, interrupting an older invocation owned by this action. */
|
|
27
|
+
async run(input) {
|
|
28
|
+
if (this.#disposed)
|
|
29
|
+
throw new Error("The Svelte Effect action is disposed.");
|
|
30
|
+
const generation = ++this.#generation;
|
|
31
|
+
const previous = this.#fiber;
|
|
32
|
+
if (previous !== undefined)
|
|
33
|
+
await this.#runner.interrupt(previous);
|
|
34
|
+
if (this.#disposed || generation !== this.#generation) {
|
|
35
|
+
throw new Error("The Svelte Effect action was disposed before it could start.");
|
|
36
|
+
}
|
|
37
|
+
this.status = "running";
|
|
38
|
+
this.value = undefined;
|
|
39
|
+
this.error = undefined;
|
|
40
|
+
this.cause = undefined;
|
|
41
|
+
this.exit = undefined;
|
|
42
|
+
const fiber = this.#runner.fork(Effect.suspend(() => this.#program(input)));
|
|
43
|
+
this.#fiber = fiber;
|
|
44
|
+
const exit = await this.#runner.await(fiber);
|
|
45
|
+
if (generation === this.#generation && !this.#disposed) {
|
|
46
|
+
this.#fiber = undefined;
|
|
47
|
+
this.#apply(exit);
|
|
48
|
+
}
|
|
49
|
+
return exit;
|
|
50
|
+
}
|
|
51
|
+
/** Interrupts the current frontend workflow without implying backend cancellation. */
|
|
52
|
+
async interrupt() {
|
|
53
|
+
if (this.#disposed)
|
|
54
|
+
return undefined;
|
|
55
|
+
const fiber = this.#fiber;
|
|
56
|
+
if (fiber === undefined)
|
|
57
|
+
return this.exit;
|
|
58
|
+
++this.#generation;
|
|
59
|
+
this.#fiber = undefined;
|
|
60
|
+
const exit = await this.#runner.interrupt(fiber);
|
|
61
|
+
if (!this.#disposed)
|
|
62
|
+
this.#apply(exit);
|
|
63
|
+
return exit;
|
|
64
|
+
}
|
|
65
|
+
reset() {
|
|
66
|
+
if (this.#disposed)
|
|
67
|
+
throw new Error("The Svelte Effect action is disposed.");
|
|
68
|
+
if (this.#fiber !== undefined)
|
|
69
|
+
throw new Error("A running Svelte Effect action cannot be reset.");
|
|
70
|
+
this.status = "idle";
|
|
71
|
+
this.value = undefined;
|
|
72
|
+
this.error = undefined;
|
|
73
|
+
this.cause = undefined;
|
|
74
|
+
this.exit = undefined;
|
|
75
|
+
}
|
|
76
|
+
async dispose() {
|
|
77
|
+
if (this.#disposed)
|
|
78
|
+
return;
|
|
79
|
+
this.#disposed = true;
|
|
80
|
+
++this.#generation;
|
|
81
|
+
const fiber = this.#fiber;
|
|
82
|
+
this.#fiber = undefined;
|
|
83
|
+
if (fiber !== undefined)
|
|
84
|
+
await this.#runner.interrupt(fiber);
|
|
85
|
+
this.status = "disposed";
|
|
86
|
+
this.#onDispose?.();
|
|
87
|
+
}
|
|
88
|
+
#apply(exit) {
|
|
89
|
+
this.exit = exit;
|
|
90
|
+
if (Exit.isSuccess(exit)) {
|
|
91
|
+
this.value = exit.value;
|
|
92
|
+
this.status = "success";
|
|
93
|
+
return;
|
|
94
|
+
}
|
|
95
|
+
this.cause = exit.cause;
|
|
96
|
+
this.error = Option.getOrUndefined(Cause.failureOption(exit.cause));
|
|
97
|
+
this.status = Cause.isInterruptedOnly(exit.cause) ? "interrupted" : "failure";
|
|
98
|
+
}
|
|
99
|
+
}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import type { Effect, Exit } from "effect";
|
|
2
|
+
import { SvelteApplicationBridge } from "./bridge.svelte.js";
|
|
3
|
+
import { SvelteEffectAction } from "./effect-action.svelte.js";
|
|
4
|
+
import type { ApplicationBridgeEffects, EffectApplicationBridgeController, SvelteApplicationBridgeOptions } from "./types.js";
|
|
5
|
+
/** Opt-in Effect surface backed by the Application Bridge's owned runtime. */
|
|
6
|
+
export declare class EffectSvelteApplicationBridge<Command, Receipt, HostEvent, Snapshot, Failure, Requirements> extends SvelteApplicationBridge<Command, Receipt, HostEvent, Snapshot, Failure> {
|
|
7
|
+
#private;
|
|
8
|
+
readonly effects: ApplicationBridgeEffects<Command, Receipt, HostEvent, Snapshot, Failure, Requirements>;
|
|
9
|
+
constructor(controller: EffectApplicationBridgeController<Command, Receipt, HostEvent, Snapshot, Failure, Requirements>, options?: SvelteApplicationBridgeOptions<HostEvent, Snapshot>);
|
|
10
|
+
run<A, E>(program: Effect.Effect<A, E, Requirements>): Promise<A>;
|
|
11
|
+
runExit<A, E>(program: Effect.Effect<A, E, Requirements>): Promise<Exit.Exit<A, E>>;
|
|
12
|
+
/**
|
|
13
|
+
* Creates a latest-wins action whose Fiber is interrupted when superseded or
|
|
14
|
+
* when this application bridge is disposed.
|
|
15
|
+
*/
|
|
16
|
+
createAction<Input, Success, Error>(program: (input: Input, effects: ApplicationBridgeEffects<Command, Receipt, HostEvent, Snapshot, Failure, Requirements>) => Effect.Effect<Success, Error, Requirements>): SvelteEffectAction<Input, Success, Error, Requirements>;
|
|
17
|
+
dispose(): Promise<void>;
|
|
18
|
+
}
|
|
19
|
+
export declare function createEffectSvelteApplicationBridge<Command, Receipt, HostEvent, Snapshot, Failure, Requirements>(controller: EffectApplicationBridgeController<Command, Receipt, HostEvent, Snapshot, Failure, Requirements>, options?: SvelteApplicationBridgeOptions<HostEvent, Snapshot>): EffectSvelteApplicationBridge<Command, Receipt, HostEvent, Snapshot, Failure, Requirements>;
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import { SvelteApplicationBridge } from "./bridge.svelte.js";
|
|
2
|
+
import { SvelteEffectAction } from "./effect-action.svelte.js";
|
|
3
|
+
/** Opt-in Effect surface backed by the Application Bridge's owned runtime. */
|
|
4
|
+
export class EffectSvelteApplicationBridge extends SvelteApplicationBridge {
|
|
5
|
+
effects;
|
|
6
|
+
#effectController;
|
|
7
|
+
#actions = [];
|
|
8
|
+
constructor(controller, options = {}) {
|
|
9
|
+
super(controller, options);
|
|
10
|
+
this.#effectController = controller;
|
|
11
|
+
this.effects = controller.effects;
|
|
12
|
+
}
|
|
13
|
+
run(program) {
|
|
14
|
+
return this.#effectController.run(program);
|
|
15
|
+
}
|
|
16
|
+
runExit(program) {
|
|
17
|
+
return this.#effectController.runExit(program);
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* Creates a latest-wins action whose Fiber is interrupted when superseded or
|
|
21
|
+
* when this application bridge is disposed.
|
|
22
|
+
*/
|
|
23
|
+
createAction(program) {
|
|
24
|
+
if (this.status === "disposed")
|
|
25
|
+
throw new Error("The Svelte Application Bridge is disposed.");
|
|
26
|
+
let action;
|
|
27
|
+
action = new SvelteEffectAction(this.#effectController, (input) => program(input, this.effects), () => {
|
|
28
|
+
const index = this.#actions.indexOf(action);
|
|
29
|
+
if (index >= 0)
|
|
30
|
+
this.#actions.splice(index, 1);
|
|
31
|
+
});
|
|
32
|
+
this.#actions.push(action);
|
|
33
|
+
return action;
|
|
34
|
+
}
|
|
35
|
+
async dispose() {
|
|
36
|
+
if (this.status === "disposed")
|
|
37
|
+
return;
|
|
38
|
+
const actions = [...this.#actions];
|
|
39
|
+
this.#actions.length = 0;
|
|
40
|
+
await Promise.all(actions.map((action) => action.dispose()));
|
|
41
|
+
await super.dispose();
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
export function createEffectSvelteApplicationBridge(controller, options = {}) {
|
|
45
|
+
return new EffectSvelteApplicationBridge(controller, options);
|
|
46
|
+
}
|
package/dist/index.d.ts
ADDED
package/dist/index.js
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
import { type LocaleSource, type SvelteLocale, type SvelteLocaleOptions } from "./locale.svelte.js";
|
|
2
|
+
export interface LocaleContext<Locale extends string> {
|
|
3
|
+
provide(source: LocaleSource<Locale>, options?: SvelteLocaleOptions<Locale> & Readonly<{
|
|
4
|
+
dispose?: boolean;
|
|
5
|
+
}>): SvelteLocale<Locale>;
|
|
6
|
+
provideState(state: SvelteLocale<Locale>, options?: Readonly<{
|
|
7
|
+
dispose?: boolean;
|
|
8
|
+
}>): SvelteLocale<Locale>;
|
|
9
|
+
use(): SvelteLocale<Locale>;
|
|
10
|
+
}
|
|
11
|
+
/**
|
|
12
|
+
* Creates an application-owned typed context. Call this once in a normal module,
|
|
13
|
+
* then provide it from a layout/component and consume it below that boundary.
|
|
14
|
+
*/
|
|
15
|
+
export declare function createLocaleContext<Locale extends string = string>(): LocaleContext<Locale>;
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
import { createContext, onDestroy } from "svelte";
|
|
2
|
+
import { createSvelteLocale, } from "./locale.svelte.js";
|
|
3
|
+
/**
|
|
4
|
+
* Creates an application-owned typed context. Call this once in a normal module,
|
|
5
|
+
* then provide it from a layout/component and consume it below that boundary.
|
|
6
|
+
*/
|
|
7
|
+
export function createLocaleContext() {
|
|
8
|
+
const [use, set] = createContext();
|
|
9
|
+
function provideState(state, options = {}) {
|
|
10
|
+
set(state);
|
|
11
|
+
onDestroy(() => {
|
|
12
|
+
if (options.dispose ?? true)
|
|
13
|
+
state.dispose();
|
|
14
|
+
});
|
|
15
|
+
return state;
|
|
16
|
+
}
|
|
17
|
+
return {
|
|
18
|
+
provide(source, options = {}) {
|
|
19
|
+
const state = createSvelteLocale(source, options);
|
|
20
|
+
return provideState(state, options);
|
|
21
|
+
},
|
|
22
|
+
provideState,
|
|
23
|
+
use,
|
|
24
|
+
};
|
|
25
|
+
}
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Structural copy of the framework-neutral Runic Translations locale contract.
|
|
3
|
+
* Keeping this structural avoids making generated translations a runtime
|
|
4
|
+
* dependency of the Svelte adapter.
|
|
5
|
+
*/
|
|
6
|
+
export interface LocaleSource<Locale extends string = string> {
|
|
7
|
+
getLocale(): Locale;
|
|
8
|
+
subscribe(listener: (locale: Locale) => void): () => void;
|
|
9
|
+
}
|
|
10
|
+
export interface MutableLocaleSource<Locale extends string = string> extends LocaleSource<Locale> {
|
|
11
|
+
setLocale(locale: Locale): void;
|
|
12
|
+
}
|
|
13
|
+
export interface SvelteLocaleOptions<Locale extends string> {
|
|
14
|
+
/**
|
|
15
|
+
* Requests a locale change when the source itself is not authoritative.
|
|
16
|
+
* A SvelteKit application normally uses this to navigate to a localized URL;
|
|
17
|
+
* the navigation then updates the source.
|
|
18
|
+
*/
|
|
19
|
+
readonly requestLocale?: (locale: Locale) => void | Promise<void>;
|
|
20
|
+
}
|
|
21
|
+
export declare class SvelteLocale<Locale extends string = string> {
|
|
22
|
+
#private;
|
|
23
|
+
constructor(source: LocaleSource<Locale>, options?: SvelteLocaleOptions<Locale>);
|
|
24
|
+
get locale(): Locale;
|
|
25
|
+
get disposed(): boolean;
|
|
26
|
+
/** A fresh object suitable for the generated message function's options argument. */
|
|
27
|
+
get messageOptions(): Readonly<{
|
|
28
|
+
locale: Locale;
|
|
29
|
+
}>;
|
|
30
|
+
/** Pulls the authoritative value after an external settings or navigation change. */
|
|
31
|
+
refresh(): Locale;
|
|
32
|
+
setLocale(locale: Locale): Promise<void>;
|
|
33
|
+
dispose(): void;
|
|
34
|
+
}
|
|
35
|
+
export declare function createSvelteLocale<Locale extends string>(source: LocaleSource<Locale>, options?: SvelteLocaleOptions<Locale>): SvelteLocale<Locale>;
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
export class SvelteLocale {
|
|
2
|
+
#locale;
|
|
3
|
+
#disposed = $state(false);
|
|
4
|
+
#source;
|
|
5
|
+
#requestLocale;
|
|
6
|
+
#unsubscribe;
|
|
7
|
+
constructor(source, options = {}) {
|
|
8
|
+
this.#source = source;
|
|
9
|
+
this.#requestLocale = options.requestLocale;
|
|
10
|
+
this.#locale = $state.raw(source.getLocale());
|
|
11
|
+
this.#unsubscribe = source.subscribe((locale) => {
|
|
12
|
+
if (!this.#disposed)
|
|
13
|
+
this.#locale = locale;
|
|
14
|
+
});
|
|
15
|
+
}
|
|
16
|
+
get locale() {
|
|
17
|
+
return this.#locale;
|
|
18
|
+
}
|
|
19
|
+
get disposed() {
|
|
20
|
+
return this.#disposed;
|
|
21
|
+
}
|
|
22
|
+
/** A fresh object suitable for the generated message function's options argument. */
|
|
23
|
+
get messageOptions() {
|
|
24
|
+
return { locale: this.#locale };
|
|
25
|
+
}
|
|
26
|
+
/** Pulls the authoritative value after an external settings or navigation change. */
|
|
27
|
+
refresh() {
|
|
28
|
+
this.#assertActive();
|
|
29
|
+
this.#locale = this.#source.getLocale();
|
|
30
|
+
return this.#locale;
|
|
31
|
+
}
|
|
32
|
+
async setLocale(locale) {
|
|
33
|
+
this.#assertActive();
|
|
34
|
+
if (this.#requestLocale) {
|
|
35
|
+
await this.#requestLocale(locale);
|
|
36
|
+
}
|
|
37
|
+
else if (isMutableLocaleSource(this.#source)) {
|
|
38
|
+
this.#source.setLocale(locale);
|
|
39
|
+
}
|
|
40
|
+
else {
|
|
41
|
+
throw new Error("This locale source is read-only. Provide requestLocale to change it through application settings or navigation.");
|
|
42
|
+
}
|
|
43
|
+
// Navigation can replace and dispose the providing layout before its
|
|
44
|
+
// Promise settles. The destination owns the next locale state in that case.
|
|
45
|
+
if (!this.#disposed)
|
|
46
|
+
this.refresh();
|
|
47
|
+
}
|
|
48
|
+
dispose() {
|
|
49
|
+
if (this.#disposed)
|
|
50
|
+
return;
|
|
51
|
+
this.#disposed = true;
|
|
52
|
+
this.#unsubscribe?.();
|
|
53
|
+
this.#unsubscribe = undefined;
|
|
54
|
+
}
|
|
55
|
+
#assertActive() {
|
|
56
|
+
if (this.#disposed)
|
|
57
|
+
throw new Error("The Svelte locale state is disposed.");
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
export function createSvelteLocale(source, options = {}) {
|
|
61
|
+
return new SvelteLocale(source, options);
|
|
62
|
+
}
|
|
63
|
+
function isMutableLocaleSource(source) {
|
|
64
|
+
return "setLocale" in source && typeof source.setLocale === "function";
|
|
65
|
+
}
|
package/dist/types.d.ts
ADDED
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
import type { Effect, Exit, Fiber, Stream } from "effect";
|
|
2
|
+
export interface ApplicationBridgeController<Command, Receipt, HostEvent, Snapshot, Failure = unknown> {
|
|
3
|
+
initialize(): Promise<Snapshot>;
|
|
4
|
+
dispatch(command: Command): Promise<Receipt>;
|
|
5
|
+
cancel(operationId: string): Promise<void>;
|
|
6
|
+
reconnect(): Promise<Snapshot>;
|
|
7
|
+
uiReady(): Promise<void>;
|
|
8
|
+
uiRendered(): Promise<void>;
|
|
9
|
+
subscribe(onEvent: (event: HostEvent) => void, onError?: (error: Failure) => void): () => void;
|
|
10
|
+
dispose(): Promise<void>;
|
|
11
|
+
}
|
|
12
|
+
export interface ApplicationBridgeEffects<Command, Receipt, HostEvent, Snapshot, Failure, Requirements> {
|
|
13
|
+
readonly initialize: Effect.Effect<Snapshot, Failure, Requirements>;
|
|
14
|
+
readonly dispatch: (command: Command) => Effect.Effect<Receipt, Failure, Requirements>;
|
|
15
|
+
readonly cancel: (operationId: string) => Effect.Effect<void, Failure, Requirements>;
|
|
16
|
+
readonly reconnect: Effect.Effect<Snapshot, Failure, Requirements>;
|
|
17
|
+
readonly uiReady: Effect.Effect<void, Failure, Requirements>;
|
|
18
|
+
readonly uiRendered: Effect.Effect<void, Failure, Requirements>;
|
|
19
|
+
readonly events: Stream.Stream<HostEvent, Failure, Requirements>;
|
|
20
|
+
}
|
|
21
|
+
export interface EffectRunner<Requirements> {
|
|
22
|
+
run<A, E>(program: Effect.Effect<A, E, Requirements>): Promise<A>;
|
|
23
|
+
runExit<A, E>(program: Effect.Effect<A, E, Requirements>): Promise<Exit.Exit<A, E>>;
|
|
24
|
+
fork<A, E>(program: Effect.Effect<A, E, Requirements>): Fiber.RuntimeFiber<A, E>;
|
|
25
|
+
await<A, E>(fiber: Fiber.RuntimeFiber<A, E>): Promise<Exit.Exit<A, E>>;
|
|
26
|
+
interrupt<A, E>(fiber: Fiber.RuntimeFiber<A, E>): Promise<Exit.Exit<A, E>>;
|
|
27
|
+
}
|
|
28
|
+
export interface EffectApplicationBridgeController<Command, Receipt, HostEvent, Snapshot, Failure, Requirements> extends ApplicationBridgeController<Command, Receipt, HostEvent, Snapshot, Failure>, EffectRunner<Requirements> {
|
|
29
|
+
readonly effects: ApplicationBridgeEffects<Command, Receipt, HostEvent, Snapshot, Failure, Requirements>;
|
|
30
|
+
}
|
|
31
|
+
export type ApplicationBridgeStatus = "idle" | "connecting" | "connected" | "reconnecting" | "error" | "disposed";
|
|
32
|
+
export type EffectActionStatus = "idle" | "running" | "success" | "failure" | "interrupted" | "disposed";
|
|
33
|
+
export interface ApplicationBridgeObserver {
|
|
34
|
+
state(state: Readonly<Record<string, unknown>>): void;
|
|
35
|
+
trace(entry: Readonly<{
|
|
36
|
+
kind: "command" | "receipt" | "event" | "operation" | "connection" | "error";
|
|
37
|
+
label: string;
|
|
38
|
+
detail?: Readonly<Record<string, unknown>>;
|
|
39
|
+
}>): void;
|
|
40
|
+
}
|
|
41
|
+
export interface SvelteApplicationBridgeOptions<HostEvent, Snapshot> {
|
|
42
|
+
readonly reduce?: (snapshot: Snapshot | undefined, event: HostEvent) => Snapshot | undefined;
|
|
43
|
+
readonly observer?: ApplicationBridgeObserver;
|
|
44
|
+
readonly inspectSnapshot?: (snapshot: Snapshot) => Readonly<{
|
|
45
|
+
sessionId?: string;
|
|
46
|
+
revision?: number;
|
|
47
|
+
sequence?: number;
|
|
48
|
+
}>;
|
|
49
|
+
}
|
package/dist/types.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
package/package.json
ADDED
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@runic-artifex/svelte",
|
|
3
|
+
"version": "0.1.0-preview.14.1",
|
|
4
|
+
"description": "Svelte 5 integration for the Runic Toolkit Application Bridge",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"svelte": "./dist/index.js",
|
|
8
|
+
"types": "./dist/index.d.ts",
|
|
9
|
+
"exports": {
|
|
10
|
+
".": {
|
|
11
|
+
"types": "./dist/index.d.ts",
|
|
12
|
+
"svelte": "./dist/index.js",
|
|
13
|
+
"import": "./dist/index.js"
|
|
14
|
+
},
|
|
15
|
+
"./translations": {
|
|
16
|
+
"types": "./dist/translations/index.d.ts",
|
|
17
|
+
"svelte": "./dist/translations/index.js",
|
|
18
|
+
"import": "./dist/translations/index.js"
|
|
19
|
+
}
|
|
20
|
+
},
|
|
21
|
+
"files": [
|
|
22
|
+
"dist",
|
|
23
|
+
"README.md",
|
|
24
|
+
"LICENSE"
|
|
25
|
+
],
|
|
26
|
+
"scripts": {
|
|
27
|
+
"build": "svelte-package -i src -o dist",
|
|
28
|
+
"check": "svelte-check --tsconfig ./tsconfig.json",
|
|
29
|
+
"test": "npm run build && vitest run",
|
|
30
|
+
"pack:check": "npm pack --dry-run"
|
|
31
|
+
},
|
|
32
|
+
"peerDependencies": {
|
|
33
|
+
"@runic-artifex/application-bridge": ">=0.1.0-preview <1",
|
|
34
|
+
"effect": ">=3.22.1 <4",
|
|
35
|
+
"svelte": ">=5.40.0 <6"
|
|
36
|
+
},
|
|
37
|
+
"peerDependenciesMeta": {
|
|
38
|
+
"@runic-artifex/application-bridge": {
|
|
39
|
+
"optional": true
|
|
40
|
+
}
|
|
41
|
+
},
|
|
42
|
+
"publishConfig": {
|
|
43
|
+
"access": "public",
|
|
44
|
+
"registry": "https://registry.npmjs.org"
|
|
45
|
+
},
|
|
46
|
+
"repository": {
|
|
47
|
+
"type": "git",
|
|
48
|
+
"url": "git+https://github.com/Runic-Artifex/runic-svelte.git",
|
|
49
|
+
"directory": "packages/svelte"
|
|
50
|
+
},
|
|
51
|
+
"gitHead": "2af64cebad10b58da4599b67d9eaf4bffc874511"
|
|
52
|
+
}
|