@lucy/liblucy 0.5.6 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/lucy.wasm +0 -0
- package/liblucy.d.ts +59 -3
- package/liblucy.mjs +146 -59
- package/main-browser.js +25 -0
- package/main-node.mjs +11 -0
- package/package.json +9 -19
- package/readme.md +68 -3
- package/dist/liblucy-debug-browser.mjs +0 -2566
- package/dist/liblucy-debug-node.mjs +0 -2569
- package/dist/liblucy-debug.wasm +0 -0
- package/dist/liblucy-release-browser.mjs +0 -16
- package/dist/liblucy-release-node.mjs +0 -19
- package/dist/liblucy-release.wasm +0 -0
- package/main-browser-dev.js +0 -8
- package/main-browser-prod.js +0 -8
- package/main-node-dev.mjs +0 -8
- package/main-node-prod.mjs +0 -8
package/dist/lucy.wasm
ADDED
|
Binary file
|
package/liblucy.d.ts
CHANGED
|
@@ -1,11 +1,67 @@
|
|
|
1
1
|
declare namespace LibLucy {
|
|
2
|
-
interface
|
|
3
|
-
|
|
2
|
+
interface CompileOptions {
|
|
3
|
+
/**
|
|
4
|
+
* What to compile to: 'js', the default, for a JavaScript module and
|
|
5
|
+
* its declarations, or 'ts' for the two as one TypeScript module.
|
|
6
|
+
*/
|
|
7
|
+
format?: 'js' | 'ts';
|
|
8
|
+
/**
|
|
9
|
+
* @deprecated The declarations are always produced. This does nothing.
|
|
10
|
+
*/
|
|
11
|
+
dts?: boolean;
|
|
4
12
|
}
|
|
5
13
|
|
|
14
|
+
interface CompileResult {
|
|
15
|
+
/** The compiled JavaScript module. */
|
|
16
|
+
js: string;
|
|
17
|
+
/** The module's TypeScript declarations (.d.ts). */
|
|
18
|
+
dts: string;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
interface TypeScriptCompileResult {
|
|
22
|
+
/**
|
|
23
|
+
* The compiled TypeScript module: the JavaScript with its types in it.
|
|
24
|
+
* Its syntax is erasable, so Node can run it as it is.
|
|
25
|
+
*/
|
|
26
|
+
ts: string;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/** An error or warning from the compiler. */
|
|
30
|
+
interface Diagnostic {
|
|
31
|
+
severity: 'error' | 'warning';
|
|
32
|
+
/** The message alone, such as 'Unexpected identifier'. */
|
|
33
|
+
message: string;
|
|
34
|
+
/** The line (counting from 1) of an error. 0 for warnings. */
|
|
35
|
+
line: number;
|
|
36
|
+
/** The column of an error. 0 for warnings. */
|
|
37
|
+
column: number;
|
|
38
|
+
/** The diagnostic as lucyc prints it, with ANSI colours. */
|
|
39
|
+
text: string;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/** What compile throws when the source doesn't compile. */
|
|
43
|
+
interface CompileError extends Error {
|
|
44
|
+
message: 'Compiler error';
|
|
45
|
+
/** The errors and warnings, in the order the compiler reported them. */
|
|
46
|
+
diagnostics: Diagnostic[];
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/** Resolves when dist/lucy.wasm is loaded and compile can be called. */
|
|
6
50
|
export const ready: Promise<void>;
|
|
7
51
|
|
|
8
|
-
|
|
52
|
+
/**
|
|
53
|
+
* Compile Lucy source to a JavaScript module of plain state machines: one
|
|
54
|
+
* exported factory per machine, which returns a machine with `state`,
|
|
55
|
+
* `context`, `send`, `subscribe`, `start` and `stop`.
|
|
56
|
+
*
|
|
57
|
+
* Prints the compile's errors and warnings to the console as lucyc does:
|
|
58
|
+
* errors with console.error, warnings with console.log, one call each.
|
|
59
|
+
* Throws a CompileError if the source doesn't compile, after printing
|
|
60
|
+
* them.
|
|
61
|
+
*/
|
|
62
|
+
export function compile(source: string, filename: string, options?: CompileOptions & { format?: 'js' }): CompileResult;
|
|
63
|
+
/** The same, to TypeScript. */
|
|
64
|
+
export function compile(source: string, filename: string, options: CompileOptions & { format: 'ts' }): TypeScriptCompileResult;
|
|
9
65
|
}
|
|
10
66
|
|
|
11
67
|
export = LibLucy;
|
package/liblucy.mjs
CHANGED
|
@@ -1,77 +1,164 @@
|
|
|
1
|
-
//
|
|
1
|
+
// The JavaScript side of dist/lucy.wasm: compile() on top of the C API in
|
|
2
|
+
// src/core/lucy.h. main-node.mjs and main-browser.js load the module and
|
|
3
|
+
// pass its instance here.
|
|
4
|
+
//
|
|
5
|
+
// The module imports nothing and exports its memory, malloc and free, and
|
|
6
|
+
// the lucy_* functions. Strings cross as NUL-terminated UTF-8 in that
|
|
7
|
+
// memory. It grows when malloc needs more, which replaces memory.buffer,
|
|
8
|
+
// so views of it are made fresh after every call into the module.
|
|
2
9
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
const Module = await moduleReady;
|
|
10
|
+
const encoder = new TextEncoder();
|
|
11
|
+
const decoder = new TextDecoder();
|
|
6
12
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
13
|
+
/**
|
|
14
|
+
* @param instance {WebAssembly.Instance} an instance of dist/lucy.wasm.
|
|
15
|
+
* @param options {{ print?: (text: string) => void, printErr?: (text: string) => void }}
|
|
16
|
+
* where compile prints diagnostics: lucyc's stdout and stderr, by
|
|
17
|
+
* default console.log and console.error.
|
|
18
|
+
* @returns the compile function.
|
|
19
|
+
*/
|
|
20
|
+
export function createCompiler(instance, {
|
|
21
|
+
print = console.log,
|
|
22
|
+
printErr = console.error
|
|
23
|
+
} = {}) {
|
|
24
|
+
const wasm = instance.exports;
|
|
25
|
+
// A reactor module's constructors run in _initialize, once, before any
|
|
26
|
+
// other call. lucy.wasm has none today, but that could change.
|
|
27
|
+
wasm._initialize?.();
|
|
14
28
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
29
|
+
// The module's memory as bytes. Make a new view after every call into the
|
|
30
|
+
// module: if the memory grew, the old one is empty.
|
|
31
|
+
function bytes() {
|
|
32
|
+
return new Uint8Array(wasm.memory.buffer);
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
// A NUL-terminated UTF-8 copy of str in the module's memory, which the
|
|
36
|
+
// caller must free.
|
|
37
|
+
function writeString(str) {
|
|
38
|
+
const encoded = encoder.encode(str);
|
|
39
|
+
// Pointers come back as signed 32-bit numbers; >>> 0 keeps one above
|
|
40
|
+
// 2 GB positive.
|
|
41
|
+
const ptr = wasm.malloc(encoded.length + 1) >>> 0;
|
|
42
|
+
// malloc returns 0 when the memory can't grow enough. Writing the
|
|
43
|
+
// string there would overwrite the start of memory.
|
|
44
|
+
if(ptr === 0) {
|
|
45
|
+
throw new Error('Out of memory');
|
|
46
|
+
}
|
|
47
|
+
const heap = bytes();
|
|
48
|
+
heap.set(encoded, ptr);
|
|
49
|
+
heap[ptr + encoded.length] = 0;
|
|
50
|
+
return ptr;
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
// The NUL-terminated string at ptr. NULL reads as ''.
|
|
54
|
+
function readString(ptr) {
|
|
55
|
+
ptr >>>= 0;
|
|
56
|
+
if(ptr === 0) {
|
|
57
|
+
return '';
|
|
58
|
+
}
|
|
59
|
+
const heap = bytes();
|
|
60
|
+
return decoder.decode(heap.subarray(ptr, heap.indexOf(0, ptr)));
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
// The result's errors and warnings, as plain objects.
|
|
64
|
+
function readDiagnostics(result) {
|
|
65
|
+
const diagnostics = [];
|
|
66
|
+
const count = wasm.lucy_result_diagnostic_count(result) >>> 0;
|
|
67
|
+
for(let i = 0; i < count; i++) {
|
|
68
|
+
const diagnostic = wasm.lucy_result_diagnostic(result, i);
|
|
69
|
+
diagnostics.push({
|
|
70
|
+
severity: wasm.lucy_diagnostic_severity(diagnostic) === 0 ? 'error' : 'warning',
|
|
71
|
+
message: readString(wasm.lucy_diagnostic_message(diagnostic)),
|
|
72
|
+
line: wasm.lucy_diagnostic_line(diagnostic),
|
|
73
|
+
column: wasm.lucy_diagnostic_column(diagnostic),
|
|
74
|
+
text: readString(wasm.lucy_diagnostic_text(diagnostic))
|
|
75
|
+
});
|
|
76
|
+
}
|
|
77
|
+
return diagnostics;
|
|
78
|
+
}
|
|
21
79
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
80
|
+
// Print the result's errors and warnings as lucyc does: errors to
|
|
81
|
+
// printErr, and the warnings lucyc prints to stdout to print. The text
|
|
82
|
+
// ends in a newline, which console.log and console.error add themselves.
|
|
83
|
+
function printDiagnostics(result) {
|
|
84
|
+
const count = wasm.lucy_result_diagnostic_count(result) >>> 0;
|
|
85
|
+
for(let i = 0; i < count; i++) {
|
|
86
|
+
const diagnostic = wasm.lucy_result_diagnostic(result, i);
|
|
87
|
+
const text = readString(wasm.lucy_diagnostic_text(diagnostic));
|
|
88
|
+
// 1 is LUCY_STREAM_STDOUT.
|
|
89
|
+
const write = wasm.lucy_diagnostic_stream(diagnostic) === 1 ? print : printErr;
|
|
90
|
+
write(text.endsWith('\n') ? text.slice(0, -1) : text);
|
|
29
91
|
}
|
|
30
|
-
return ret;
|
|
31
92
|
}
|
|
32
93
|
|
|
33
94
|
/**
|
|
34
|
-
* Compile Lucy source a module of
|
|
95
|
+
* Compile Lucy source to a module of plain JavaScript state machines.
|
|
35
96
|
* @param source {String} the input Lucy source.
|
|
36
97
|
* @param filename {String} the name of the Lucy file.
|
|
37
|
-
* @param options {
|
|
38
|
-
* @returns {
|
|
98
|
+
* @param options {{ format?: 'js' | 'ts' }}
|
|
99
|
+
* @returns {{ js: string, dts: string } | { ts: string }} The compiled
|
|
100
|
+
* JavaScript module and its TypeScript declarations, or with the 'ts'
|
|
101
|
+
* format the two as one TypeScript module.
|
|
102
|
+
* @throws {Error} 'Compiler error' if the source doesn't compile, with the
|
|
103
|
+
* errors and warnings in its diagnostics property.
|
|
39
104
|
*/
|
|
40
|
-
function
|
|
41
|
-
useRemote: false
|
|
42
|
-
}) {
|
|
105
|
+
function compile(source, filename, options = {}) {
|
|
43
106
|
if(!source || !filename) {
|
|
44
107
|
throw new Error('Source and filename are both required.');
|
|
45
108
|
}
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
109
|
+
|
|
110
|
+
// Read the options before allocating anything, so that bad options
|
|
111
|
+
// can't throw with memory still allocated.
|
|
112
|
+
const format = options.format ?? 'js';
|
|
113
|
+
if(format !== 'js' && format !== 'ts') {
|
|
114
|
+
throw new Error(`Unknown format '${format}'. Use 'js' or 'ts'.`);
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
const srcPtr = writeString(source);
|
|
118
|
+
let fnPtr;
|
|
119
|
+
try {
|
|
120
|
+
fnPtr = writeString(filename);
|
|
121
|
+
} catch(err) {
|
|
122
|
+
wasm.free(srcPtr);
|
|
123
|
+
throw err;
|
|
124
|
+
}
|
|
125
|
+
let result = 0;
|
|
126
|
+
let out = null;
|
|
127
|
+
let diagnostics = null;
|
|
128
|
+
try {
|
|
129
|
+
result = wasm.lucy_result_create();
|
|
130
|
+
// 1 is LUCY_FORMAT_TS.
|
|
131
|
+
wasm.lucy_result_set_format(result, format === 'ts' ? 1 : 0);
|
|
132
|
+
wasm.lucy_compile(result, srcPtr, fnPtr);
|
|
133
|
+
|
|
134
|
+
// The compiler doesn't print; this prints what lucyc would.
|
|
135
|
+
printDiagnostics(result);
|
|
136
|
+
|
|
137
|
+
if(wasm.lucy_result_success(result)) {
|
|
138
|
+
out = format === 'ts' ? {
|
|
139
|
+
ts: readString(wasm.lucy_result_ts(result))
|
|
140
|
+
} : {
|
|
141
|
+
js: readString(wasm.lucy_result_js(result)),
|
|
142
|
+
dts: readString(wasm.lucy_result_dts(result))
|
|
143
|
+
};
|
|
144
|
+
} else {
|
|
145
|
+
diagnostics = readDiagnostics(result);
|
|
65
146
|
}
|
|
66
|
-
|
|
67
|
-
|
|
147
|
+
} finally {
|
|
148
|
+
// Free everything, even if the module trapped. Destroying NULL does
|
|
149
|
+
// nothing.
|
|
150
|
+
wasm.lucy_result_destroy(result);
|
|
151
|
+
wasm.free(fnPtr);
|
|
152
|
+
wasm.free(srcPtr);
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
if(out === null) {
|
|
156
|
+
const err = new Error('Compiler error');
|
|
157
|
+
err.diagnostics = diagnostics;
|
|
158
|
+
throw err;
|
|
68
159
|
}
|
|
69
|
-
|
|
70
|
-
let err = new Error('Compiler error');
|
|
71
|
-
throw err;
|
|
160
|
+
return out;
|
|
72
161
|
}
|
|
73
162
|
|
|
74
|
-
return
|
|
75
|
-
|
|
76
|
-
};
|
|
77
|
-
}
|
|
163
|
+
return compile;
|
|
164
|
+
}
|
package/main-browser.js
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
// liblucy for browsers (and bundlers, which recognise the new URL(...,
|
|
2
|
+
// import.meta.url) below): fetches dist/lucy.wasm next to this file.
|
|
3
|
+
import { createCompiler } from './liblucy.mjs';
|
|
4
|
+
|
|
5
|
+
const url = new URL('./dist/lucy.wasm', import.meta.url);
|
|
6
|
+
|
|
7
|
+
async function instantiate() {
|
|
8
|
+
const response = await fetch(url);
|
|
9
|
+
if(!response.ok) {
|
|
10
|
+
throw new Error(`Couldn't fetch ${url}: ${response.status}`);
|
|
11
|
+
}
|
|
12
|
+
// Streaming compiles while the bytes download, but only works when the
|
|
13
|
+
// server sends the file as application/wasm.
|
|
14
|
+
if(WebAssembly.instantiateStreaming &&
|
|
15
|
+
response.headers.get('Content-Type') === 'application/wasm') {
|
|
16
|
+
return (await WebAssembly.instantiateStreaming(response)).instance;
|
|
17
|
+
}
|
|
18
|
+
return (await WebAssembly.instantiate(await response.arrayBuffer())).instance;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
export let compile;
|
|
22
|
+
|
|
23
|
+
export let ready = instantiate().then(instance => {
|
|
24
|
+
compile = createCompiler(instance);
|
|
25
|
+
});
|
package/main-node.mjs
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
// liblucy for Node.js: loads dist/lucy.wasm from disk.
|
|
2
|
+
import { readFile } from 'node:fs/promises';
|
|
3
|
+
import { createCompiler } from './liblucy.mjs';
|
|
4
|
+
|
|
5
|
+
export let compile;
|
|
6
|
+
|
|
7
|
+
export let ready = readFile(new URL('./dist/lucy.wasm', import.meta.url))
|
|
8
|
+
.then(bytes => WebAssembly.instantiate(bytes))
|
|
9
|
+
.then(({ instance }) => {
|
|
10
|
+
compile = createCompiler(instance);
|
|
11
|
+
});
|
package/package.json
CHANGED
|
@@ -1,37 +1,27 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@lucy/liblucy",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.7.0",
|
|
4
4
|
"description": "The Lucy compiler project.",
|
|
5
5
|
"exports": {
|
|
6
6
|
".": {
|
|
7
|
-
"node":
|
|
8
|
-
|
|
9
|
-
"production": "./main-node-prod.mjs",
|
|
10
|
-
"import": "./main-node-prod.mjs"
|
|
11
|
-
},
|
|
12
|
-
"browser": {
|
|
13
|
-
"development": "./main-browser-dev.js",
|
|
14
|
-
"production": "./main-browser-prod.js",
|
|
15
|
-
"import": "./main-browser-prod.js"
|
|
16
|
-
}
|
|
7
|
+
"node": "./main-node.mjs",
|
|
8
|
+
"browser": "./main-browser.js"
|
|
17
9
|
}
|
|
18
10
|
},
|
|
19
11
|
"types": "./liblucy.d.ts",
|
|
20
12
|
"files": [
|
|
21
|
-
"dist",
|
|
13
|
+
"dist/lucy.wasm",
|
|
22
14
|
"liblucy.mjs",
|
|
23
15
|
"liblucy.d.ts",
|
|
24
|
-
"main-node
|
|
25
|
-
"main-
|
|
26
|
-
"main-browser-dev.js",
|
|
27
|
-
"main-browser-prod.js"
|
|
16
|
+
"main-node.mjs",
|
|
17
|
+
"main-browser.js"
|
|
28
18
|
],
|
|
29
19
|
"scripts": {
|
|
30
20
|
"test": "make test"
|
|
31
21
|
},
|
|
32
22
|
"repository": {
|
|
33
23
|
"type": "git",
|
|
34
|
-
"url": "git+https://github.com/
|
|
24
|
+
"url": "git+https://github.com/lucydsl/liblucy.git"
|
|
35
25
|
},
|
|
36
26
|
"keywords": [
|
|
37
27
|
"Lucy",
|
|
@@ -41,7 +31,7 @@
|
|
|
41
31
|
"author": "Matthew Phillips <matthew@matthewphillips.info>",
|
|
42
32
|
"license": "BSD-2-Clause",
|
|
43
33
|
"bugs": {
|
|
44
|
-
"url": "https://github.com/
|
|
34
|
+
"url": "https://github.com/lucydsl/liblucy/issues"
|
|
45
35
|
},
|
|
46
|
-
"homepage": "https://github.com/
|
|
36
|
+
"homepage": "https://github.com/lucydsl/liblucy#readme"
|
|
47
37
|
}
|
package/readme.md
CHANGED
|
@@ -1,11 +1,76 @@
|
|
|
1
1
|
# liblucy
|
|
2
2
|
|
|
3
|
-
__liblucy__ is the core piece of [Lucy](https://
|
|
3
|
+
__liblucy__ is the core piece of [Lucy](https://lucy.spooky.click/) the DSL. It contains the core compiler that is compiled to wasm for usage in JavaScript environments such as Node.js. It also includes the CLI compiler, `lucyc`.
|
|
4
|
+
|
|
5
|
+
## Output
|
|
6
|
+
|
|
7
|
+
The compiler turns a Lucy file into a module of plain JavaScript state machines, with no runtime library: one exported factory per machine (`createLight` for `machine light`, a default export for the file's unnamed machine), each a small set of ordinary functions for just what that machine does.
|
|
8
|
+
|
|
9
|
+
```js
|
|
10
|
+
import createMachine from './toggle.js';
|
|
11
|
+
|
|
12
|
+
const machine = createMachine({ context: { count: 0 } });
|
|
13
|
+
machine.subscribe(m => render(m.state, m.context));
|
|
14
|
+
machine.start();
|
|
15
|
+
machine.send('toggle');
|
|
16
|
+
machine.send({ type: 'set', data: 5 });
|
|
17
|
+
console.log(machine.state, machine.context);
|
|
18
|
+
machine.stop();
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
- `createMachine({ context, actions, guards, assigns, delays, services })`: the options supply what the Lucy source names with `:symbols`, each called as `(context, event)`; a `services` entry returns a promise for `invoke(:name)` and an unstarted machine for `spawn(:name)`. Only the options a machine uses are read.
|
|
22
|
+
- `state` is the current state's name, or a dotted path such as `'red.walk'` inside a nested machine. `context` is a plain object, replaced (not mutated) by each `assign`. `done` becomes `true` when a final state is entered.
|
|
23
|
+
- `send(event)` takes a type or an `{ type, data }` object and runs the transition at once. `subscribe(listener)` calls the listener with the machine after each change and returns an unsubscribe function. `start()` enters the initial state (entry actions, timers, invokes) and returns the machine; `stop()` clears timers, drops pending invokes, stops invoked and spawned children, and clears the listeners.
|
|
24
|
+
- Every module comes with a `.d.ts` that types each factory's options and the machine it returns: `lucyc --out-file toggle.js` writes `toggle.d.ts` beside it, and `compile()` returns it as `dts`.
|
|
25
|
+
- `lucyc --ts` (and `compile(source, filename, { format: 'ts' })`, which returns `ts`) compiles to one TypeScript module instead: the same code with those types in it. Its syntax is erasable, so Node runs it as it is. The types are those of the factories; the code inside them is marked `// @ts-nocheck`, as it is generated and uses `any` for the events.
|
|
26
|
+
|
|
27
|
+
## Typed events
|
|
28
|
+
|
|
29
|
+
A machine can declare its events, and the type of the data each carries:
|
|
30
|
+
|
|
31
|
+
```lucy
|
|
32
|
+
use './types' { User }
|
|
33
|
+
|
|
34
|
+
machine session {
|
|
35
|
+
event login(User)
|
|
36
|
+
event rename(string)
|
|
37
|
+
event logout
|
|
38
|
+
|
|
39
|
+
initial state anonymous {
|
|
40
|
+
login => assign(user) => active
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
state active {
|
|
44
|
+
rename => assign(name)
|
|
45
|
+
logout => anonymous
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
- A type is a single name: one imported with `use`, or one TypeScript already knows (`string`, `number`, `MouseEvent`). Give any other type (`string[]`, a union) a name in a `.ts` file and import it. A name used as an event's type is imported as a type only: the JavaScript leaves it out and the `.d.ts` has `import type`.
|
|
51
|
+
- The type is that of the event's `data`: `machine.send({ type: 'login', data: user })`.
|
|
52
|
+
- Events are declared in a top-level `machine { }` block, for that machine and the machines nested in its states. An event has one type, whichever state handles it.
|
|
53
|
+
- The declarations change nothing in the JavaScript. The compiler warns about a transition on an event the machine doesn't declare, a declared event no state handles, `assign(key)` on an event declared without data, and `send(child, event)` to a machine spawned from the same file that doesn't declare `event`. A machine that declares no events is not checked.
|
|
54
|
+
- In the `.d.ts`, the machine's events become `SessionEvents` (by name, so `SessionEvents['login']` types the event parameter of an imported guard or action) and their union `SessionEvent`. `send` takes a `SessionEvent`, or the name alone for an event without data. What the options supply is typed with the events it is used on, and the `context` passed in has to be able to hold the data that `assign(key)` stores.
|
|
4
55
|
|
|
5
56
|
## Contributing
|
|
6
57
|
|
|
7
|
-
See the [contributing page](https://
|
|
58
|
+
See the [contributing page](https://lucy.spooky.click/docs/contributing/) for information on how to build liblucy and the workflow for making changes.
|
|
8
59
|
|
|
9
60
|
## License
|
|
10
61
|
|
|
11
|
-
BSD-2-Clause
|
|
62
|
+
BSD-2-Clause
|
|
63
|
+
## Building
|
|
64
|
+
|
|
65
|
+
The wasm module, `dist/lucy.wasm`, is built with clang from [wasi-sdk](https://github.com/WebAssembly/wasi-sdk), statically linking wasi-libc. It imports nothing, and `liblucy.mjs` drives it through the standard WebAssembly API, with `main-node.mjs` and `main-browser.js` loading it. `scripts/get_wasi_sdk` downloads the pinned wasi-sdk release into `~/.cache/wasi-sdk`, where the Makefile looks for it (set `WASI_SDK` to use another copy):
|
|
66
|
+
|
|
67
|
+
```sh
|
|
68
|
+
scripts/get_wasi_sdk
|
|
69
|
+
make all
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
The native compiler, `bin/lucyc`, only needs a C17 compiler: `make bin/lucyc`. Run the tests with `make test`. The code builds without warnings under the strict set in the Makefile; `make WERROR=1 ...` makes them errors, as CI does.
|
|
73
|
+
|
|
74
|
+
`src/README.md` describes how the sources are laid out and the conventions they follow.
|
|
75
|
+
|
|
76
|
+
`make test-sanitize` checks for memory errors and leaks: it runs the tests, and every `.lucy` file under `test/`, through native builds with AddressSanitizer and UndefinedBehaviorSanitizer. It needs GCC or Clang on Linux.
|