lambdajson-js 1.0.0 → 1.1.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/README.md +5 -292
- package/package.json +1 -1
- package/src/js-compiler.js +16 -2
- package/src/primitives.js +1 -0
- package/src/README.md +0 -17
package/README.md
CHANGED
|
@@ -1,304 +1,17 @@
|
|
|
1
|
-
# LambdaJSON
|
|
1
|
+
# LambdaJSON to JavaScript compiler
|
|
2
2
|
|
|
3
|
-
LambdaJSON is a
|
|
4
|
-
Programs are JSON values that represent execution trees and compile to deterministic JavaScript functions.
|
|
5
|
-
|
|
6
|
-
Because programs are just data, they can be:
|
|
7
|
-
|
|
8
|
-
- safely transported over HTTP,
|
|
9
|
-
- stored in databases,
|
|
10
|
-
- versioned and diffed as JSON,
|
|
11
|
-
- executed on the server with a controlled set of primitive functions.
|
|
12
|
-
|
|
13
|
-
This makes LambdaJSON useful for server-driven business rules, dynamic workflows, and “logic as data” scenarios.
|
|
14
|
-
|
|
15
|
-
---
|
|
3
|
+
LambdaJSON is a JSON based pure functional programming language: [https://github.com/benokit/json-programming-language/tree/main](https://github.com/benokit/json-programming-language/tree/main)
|
|
16
4
|
|
|
17
5
|
## Quick start
|
|
18
6
|
|
|
19
|
-
Install dependencies and run tests:
|
|
20
|
-
|
|
21
|
-
```bash
|
|
22
|
-
npm install
|
|
23
|
-
npm test
|
|
24
|
-
```
|
|
25
|
-
|
|
26
|
-
Use the JS compiler directly:
|
|
27
|
-
|
|
28
7
|
```js
|
|
29
|
-
import { compile } from
|
|
8
|
+
import { compile } from 'lambdajson-js';
|
|
30
9
|
|
|
31
|
-
// A minimal LambdaJSON program
|
|
32
10
|
const program = {
|
|
33
|
-
|
|
11
|
+
$sum: ['#', 2]
|
|
34
12
|
};
|
|
35
|
-
|
|
36
13
|
const f = compile(program);
|
|
37
14
|
|
|
38
|
-
|
|
39
|
-
console.log(f([1, 2 ,3])); // => 1 + 2 + 3 = 6
|
|
15
|
+
console.log(f(1)); // => 3
|
|
40
16
|
```
|
|
41
17
|
|
|
42
|
-
---
|
|
43
|
-
|
|
44
|
-
## Core language model
|
|
45
|
-
|
|
46
|
-
### Data model
|
|
47
|
-
|
|
48
|
-
LambdaJSON programs are plain JSON values. They are built from standard JSON types:
|
|
49
|
-
|
|
50
|
-
* `string`
|
|
51
|
-
* `number`
|
|
52
|
-
* `boolean`
|
|
53
|
-
* `array`
|
|
54
|
-
* `object`
|
|
55
|
-
|
|
56
|
-
On top of that, LambdaJSON defines **conventions on property names and string suffixes** which give these values operational semantics.
|
|
57
|
-
|
|
58
|
-
### Property name conventions
|
|
59
|
-
|
|
60
|
-
* **Primitive or user-defined function call**
|
|
61
|
-
|
|
62
|
-
A property whose name begins with `$` (for example `$sum`, `$return`) denotes a function call:
|
|
63
|
-
|
|
64
|
-
* It must correspond either to:
|
|
65
|
-
* a **primitive function** (one of the provided primitives), or
|
|
66
|
-
* a **locally declared function** in a preceding `$let` block.
|
|
67
|
-
* The value associated with this property is the argument(s) to the function.
|
|
68
|
-
|
|
69
|
-
* **Local bindings**
|
|
70
|
-
|
|
71
|
-
Special property `$let` is reserved for **local variable and function declarations** and must appear in the same object together with a function call.
|
|
72
|
-
|
|
73
|
-
* **Function configuration**
|
|
74
|
-
|
|
75
|
-
A property whose name ends with `_` (for example `_with`) must correspond to a **configuration property** of the function called in the same object.
|
|
76
|
-
|
|
77
|
-
The exact set of supported config properties is defined per primitive (see `src/primitives.js`).
|
|
78
|
-
|
|
79
|
-
### String value conventions
|
|
80
|
-
|
|
81
|
-
String values are interpreted according to their prefix:
|
|
82
|
-
|
|
83
|
-
* **`@` — local variable reference**
|
|
84
|
-
|
|
85
|
-
A string starting with `@` is a reference to a variable declared in a preceding `$let` block anywhere up in the execution tree.
|
|
86
|
-
The substring following `@` is treated as a dotted path into the bound value.
|
|
87
|
-
|
|
88
|
-
Example: `"@address.street.number"`.
|
|
89
|
-
|
|
90
|
-
* **`#` — input reference**
|
|
91
|
-
|
|
92
|
-
A string starting with `#` refers to the function input.
|
|
93
|
-
The substring following `#` is interpreted as a dotted path into the input object.
|
|
94
|
-
|
|
95
|
-
Example (object input): `"#.name"`
|
|
96
|
-
Example (array input, index 0–9): `"#0.name"`.
|
|
97
|
-
|
|
98
|
-
* **other strings** are treated as literal values.
|
|
99
|
-
|
|
100
|
-
### Evaluation rules (informal)
|
|
101
|
-
|
|
102
|
-
* **Numbers / booleans**
|
|
103
|
-
Evaluated as themselves.
|
|
104
|
-
|
|
105
|
-
* **Arrays**
|
|
106
|
-
Each element is evaluated; the result is an array of evaluated elements.
|
|
107
|
-
|
|
108
|
-
* **Objects**
|
|
109
|
-
|
|
110
|
-
* If any property name starts with `$`, the object is treated as a **function call node**:
|
|
111
|
-
|
|
112
|
-
* the corresponding primitive or user-defined function is executed.
|
|
113
|
-
* additional `_`-prefixed properties in the value associated with the function property provide configuration.
|
|
114
|
-
* `$let` may provide local declarations.
|
|
115
|
-
* Otherwise, each property is evaluated independently and the resulting object with evaluated properties is returned.
|
|
116
|
-
|
|
117
|
-
Programs are thus **direct representations of execution trees**: each object with a `$…` property represents one node in the tree.
|
|
118
|
-
|
|
119
|
-
---
|
|
120
|
-
|
|
121
|
-
## Examples
|
|
122
|
-
|
|
123
|
-
### 1. Pure expression: sum of two inputs
|
|
124
|
-
|
|
125
|
-
Compute `input.a + input.b` using the `$sum` primitive and `$return`:
|
|
126
|
-
|
|
127
|
-
```json
|
|
128
|
-
{
|
|
129
|
-
"$sum": ["#.a", "#.b"]
|
|
130
|
-
}
|
|
131
|
-
```
|
|
132
|
-
|
|
133
|
-
Compiled to JS and invoked:
|
|
134
|
-
|
|
135
|
-
```js
|
|
136
|
-
const program = {
|
|
137
|
-
"$sum": ["#.a", "#.b"]
|
|
138
|
-
};
|
|
139
|
-
|
|
140
|
-
const f = compile(program);
|
|
141
|
-
|
|
142
|
-
f({ a: 2, b: 3 }); // => 5
|
|
143
|
-
```
|
|
144
|
-
|
|
145
|
-
---
|
|
146
|
-
|
|
147
|
-
### 2. Using `$let` and local variables
|
|
148
|
-
|
|
149
|
-
Bind an intermediate value and reuse it twice:
|
|
150
|
-
|
|
151
|
-
```json
|
|
152
|
-
{
|
|
153
|
-
"$let": {
|
|
154
|
-
"base": {
|
|
155
|
-
"$sum": [1, 2]
|
|
156
|
-
}
|
|
157
|
-
},
|
|
158
|
-
"$sum": ["@base", "@base"]
|
|
159
|
-
}
|
|
160
|
-
```
|
|
161
|
-
|
|
162
|
-
Explanation:
|
|
163
|
-
|
|
164
|
-
* `$let.base` defines a local variable `base` with value `1 + 2 = 3`.
|
|
165
|
-
* returned value is `base + base = 6`.
|
|
166
|
-
|
|
167
|
-
---
|
|
168
|
-
|
|
169
|
-
### 3. Mapping over an input array
|
|
170
|
-
|
|
171
|
-
Assuming a primitive that can map a function over an array (e.g. `$map`) and a primitive `$sum`, we can increment each value in the input array by 1:
|
|
172
|
-
|
|
173
|
-
```json
|
|
174
|
-
{
|
|
175
|
-
"$map": {
|
|
176
|
-
"_fn": {
|
|
177
|
-
"$sum": ["#.value", 1]
|
|
178
|
-
},
|
|
179
|
-
"_over": "#"
|
|
180
|
-
}
|
|
181
|
-
}
|
|
182
|
-
```
|
|
183
|
-
|
|
184
|
-
Intended meaning (in JS-ish pseudocode):
|
|
185
|
-
|
|
186
|
-
```js
|
|
187
|
-
input.map(value => value + 1)
|
|
188
|
-
```
|
|
189
|
-
|
|
190
|
-
---
|
|
191
|
-
|
|
192
|
-
### 4. Nested objects and input paths
|
|
193
|
-
|
|
194
|
-
Picking and transforming fields from an input object:
|
|
195
|
-
|
|
196
|
-
```json
|
|
197
|
-
{
|
|
198
|
-
"fullName": {
|
|
199
|
-
"$join": {
|
|
200
|
-
"_separator": " ",
|
|
201
|
-
"_strings": ["#.firstName", "#.lastName"]
|
|
202
|
-
}
|
|
203
|
-
},
|
|
204
|
-
"streetNumber": "#.address.street.number",
|
|
205
|
-
"tags": ["vip", "#.segment"]
|
|
206
|
-
}
|
|
207
|
-
```
|
|
208
|
-
|
|
209
|
-
On input
|
|
210
|
-
|
|
211
|
-
```json
|
|
212
|
-
{
|
|
213
|
-
"firstName": "Ada",
|
|
214
|
-
"lastName": "Lovelace",
|
|
215
|
-
"address": { "street": { "number": 42 } },
|
|
216
|
-
"segment": "premium"
|
|
217
|
-
}
|
|
218
|
-
```
|
|
219
|
-
|
|
220
|
-
the program evaluates to:
|
|
221
|
-
|
|
222
|
-
```json
|
|
223
|
-
{
|
|
224
|
-
"fullName": "Ada Lovelace",
|
|
225
|
-
"streetNumber": 42,
|
|
226
|
-
"tags": ["vip", "premium"]
|
|
227
|
-
}
|
|
228
|
-
```
|
|
229
|
-
|
|
230
|
-
---
|
|
231
|
-
|
|
232
|
-
## Custom primitives
|
|
233
|
-
|
|
234
|
-
You can extend LambdaJSON by adding custom primitives and passing them to the compiler.
|
|
235
|
-
|
|
236
|
-
Example primitive: `$multiply`, taking two arguments:
|
|
237
|
-
|
|
238
|
-
```js
|
|
239
|
-
const multiply = f => x => {
|
|
240
|
-
const [x, y] = f(x);
|
|
241
|
-
return x * y;
|
|
242
|
-
};
|
|
243
|
-
|
|
244
|
-
const customPrimitives = {
|
|
245
|
-
"$multiply": multiply
|
|
246
|
-
};
|
|
247
|
-
|
|
248
|
-
const program = {
|
|
249
|
-
"$return": {
|
|
250
|
-
"$multiply": [2, 3]
|
|
251
|
-
}
|
|
252
|
-
};
|
|
253
|
-
|
|
254
|
-
const f = compile(program, customPrimitives);
|
|
255
|
-
f([2, 3]); // => 6
|
|
256
|
-
```
|
|
257
|
-
|
|
258
|
-
---
|
|
259
|
-
|
|
260
|
-
## JS compiler
|
|
261
|
-
|
|
262
|
-
The JS compiler:
|
|
263
|
-
|
|
264
|
-
* lives in [`src/js-compiler.js`](./src/js-compiler.js),
|
|
265
|
-
* takes a program (parsed JSON) and a set of primitives,
|
|
266
|
-
* returns a JavaScript function `(input) => output`.
|
|
267
|
-
|
|
268
|
-
High-level API:
|
|
269
|
-
|
|
270
|
-
```js
|
|
271
|
-
import { compile } from "./src/js-compiler.js";
|
|
272
|
-
import { primitives } from "./src/primitives.js";
|
|
273
|
-
|
|
274
|
-
const program = ...;
|
|
275
|
-
const customPrimitives = ...
|
|
276
|
-
const f = compile(program, customPrimitives);
|
|
277
|
-
const result = f(input);
|
|
278
|
-
```
|
|
279
|
-
|
|
280
|
-
---
|
|
281
|
-
|
|
282
|
-
## Testing
|
|
283
|
-
|
|
284
|
-
Tests are in [`test/test-js-compiler.js`](./test/test-js-compiler.js).
|
|
285
|
-
|
|
286
|
-
Run them with:
|
|
287
|
-
|
|
288
|
-
```bash
|
|
289
|
-
npm test
|
|
290
|
-
```
|
|
291
|
-
|
|
292
|
-
Those tests include more involved examples of LambdaJSON programs and their expected outputs; they’re a good reference for the current feature set.
|
|
293
|
-
|
|
294
|
-
---
|
|
295
|
-
|
|
296
|
-
## Status
|
|
297
|
-
|
|
298
|
-
Experimental. The language, primitives, and compiler API may change without notice.
|
|
299
|
-
|
|
300
|
-
---
|
|
301
|
-
|
|
302
|
-
## License
|
|
303
|
-
|
|
304
|
-
MIT
|
package/package.json
CHANGED
package/src/js-compiler.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { isObject, isString, map, get, find, mapValues, isArray, every } from 'lodash-es'
|
|
1
|
+
import { isObject, isString, map, get, find, mapValues, isArray, every, has } from 'lodash-es'
|
|
2
2
|
import { primitives } from './primitives.js';
|
|
3
3
|
|
|
4
4
|
export {
|
|
@@ -30,8 +30,12 @@ function compileTree(primitives, tree) {
|
|
|
30
30
|
}
|
|
31
31
|
|
|
32
32
|
const varsDeclarationKey = '$let';
|
|
33
|
+
const valueDeclarationKey = '$value';
|
|
33
34
|
|
|
34
35
|
function compilePrimitive(primitives, tree) {
|
|
36
|
+
if (has(tree, valueDeclarationKey)) {
|
|
37
|
+
return _ => tree[valueDeclarationKey];
|
|
38
|
+
}
|
|
35
39
|
const keys = Object.keys(tree);
|
|
36
40
|
const getLocalVars = compileVars(primitives, tree[varsDeclarationKey]);
|
|
37
41
|
const primitiveKey = find(keys, k => k !== varsDeclarationKey);
|
|
@@ -102,10 +106,20 @@ function compileVars(primitives, obj) {
|
|
|
102
106
|
|
|
103
107
|
function compileObject(primitives, obj) {
|
|
104
108
|
const funks = mapValues(obj, n => compileTree(primitives, n));
|
|
105
|
-
return x =>
|
|
109
|
+
return x => {
|
|
110
|
+
const result = {};
|
|
111
|
+
for (const key in funks) {
|
|
112
|
+
const pKey = key.startsWith('\\') ? key.slice(1) : key;
|
|
113
|
+
result[pKey] = funks[key](x);
|
|
114
|
+
}
|
|
115
|
+
return result;
|
|
116
|
+
};
|
|
106
117
|
}
|
|
107
118
|
|
|
108
119
|
function compileString(str) {
|
|
120
|
+
if (str.startsWith('\\')) {
|
|
121
|
+
return () => str.slice(1);
|
|
122
|
+
}
|
|
109
123
|
if (str === '#') {
|
|
110
124
|
return ({ input }) => input;
|
|
111
125
|
}
|
package/src/primitives.js
CHANGED
package/src/README.md
DELETED
|
@@ -1,17 +0,0 @@
|
|
|
1
|
-
# LambdaJSON to JavaScript compiler
|
|
2
|
-
|
|
3
|
-
LambdaJSON is a JSON based pure functional programming language: [https://github.com/benokit/json-programming-language/tree/main](https://github.com/benokit/json-programming-language/tree/main)
|
|
4
|
-
|
|
5
|
-
## Quick start
|
|
6
|
-
|
|
7
|
-
```js
|
|
8
|
-
import { compile } from 'lambdajson-js';
|
|
9
|
-
|
|
10
|
-
const program = {
|
|
11
|
-
$sum: ['#', 2]
|
|
12
|
-
};
|
|
13
|
-
const f = compile(program);
|
|
14
|
-
|
|
15
|
-
console.log(f(1)); // => 3
|
|
16
|
-
```
|
|
17
|
-
|