lambdajson-js 1.0.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Benjamin Batistić
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.
package/README.md ADDED
@@ -0,0 +1,304 @@
1
+ # LambdaJSON
2
+
3
+ LambdaJSON is a pure, JSON-based programming language.
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
+ ---
16
+
17
+ ## Quick start
18
+
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
+ ```js
29
+ import { compile } from "./src/js-compiler.js";
30
+
31
+ // A minimal LambdaJSON program
32
+ const program = {
33
+ "$sum": "#"
34
+ };
35
+
36
+ const f = compile(program);
37
+
38
+ // f is a pure function from input -> output
39
+ console.log(f([1, 2 ,3])); // => 1 + 2 + 3 = 6
40
+ ```
41
+
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 ADDED
@@ -0,0 +1,50 @@
1
+ {
2
+ "name": "lambdajson-js",
3
+ "version": "1.0.0",
4
+ "description": "LambdaJSON to JavaScript function compiler",
5
+ "type": "module",
6
+ "main": "./src/js-compiler.js",
7
+ "module": "./src/js-compiler.js",
8
+ "files": [
9
+ "src",
10
+ "src/README.md",
11
+ "LICENSE"
12
+ ],
13
+ "exports": {
14
+ ".": {
15
+ "import": "./src/js-compiler.js"
16
+ },
17
+ "./package.json": "./package.json"
18
+ },
19
+ "keywords": [
20
+ "lambdajson",
21
+ "json",
22
+ "compiler",
23
+ "transpiler",
24
+ "javascript"
25
+ ],
26
+ "homepage": "https://github.com/benokit/json-programming-language#readme",
27
+ "bugs": {
28
+ "url": "https://github.com/benokit/json-programming-language/issues"
29
+ },
30
+ "repository": {
31
+ "type": "git",
32
+ "url": "git+https://github.com/benokit/json-programming-language.git"
33
+ },
34
+ "license": "MIT",
35
+ "author": "Benjamin Batistic",
36
+ "scripts": {
37
+ "test": "mocha"
38
+ },
39
+ "dependencies": {
40
+ "fast-printf": "^1.6.10",
41
+ "lodash-es": "^4.17.21"
42
+ },
43
+ "devDependencies": {
44
+ "@eslint/js": "^9.39.1",
45
+ "chai": "^6.2.1",
46
+ "esbuild": "^0.27.0",
47
+ "globals": "^16.5.0",
48
+ "mocha": "^11.7.5"
49
+ }
50
+ }
package/src/README.md ADDED
@@ -0,0 +1,17 @@
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
+
@@ -0,0 +1,124 @@
1
+ import { isObject, isString, map, get, find, mapValues, isArray, every } from 'lodash-es'
2
+ import { primitives } from './primitives.js';
3
+
4
+ export {
5
+ compile
6
+ }
7
+
8
+ /**
9
+ * Converts program written in pure json
10
+ * @param {object} program
11
+ * @param {object} extendedPrimitives
12
+ * @returns {function}
13
+ */
14
+ function compile(program, extendedPrimitives = {}) {
15
+ const f = compileTree({ ...primitives, ...extendedPrimitives }, program);
16
+ return input => f({input});
17
+ }
18
+
19
+ function compileTree(primitives, tree) {
20
+ if (isString(tree)) { return compileString(tree); }
21
+
22
+ if (isArray(tree)) { return compileArray(primitives, tree) }
23
+
24
+ if (isObject(tree)) {
25
+ return isPrimitive(primitives, tree) ? compilePrimitive(primitives, tree) :
26
+ isFunction(tree) ? compileFunction(primitives, tree) : compileObject(primitives, tree);
27
+ }
28
+
29
+ return () => tree;
30
+ }
31
+
32
+ const varsDeclarationKey = '$let';
33
+
34
+ function compilePrimitive(primitives, tree) {
35
+ const keys = Object.keys(tree);
36
+ const getLocalVars = compileVars(primitives, tree[varsDeclarationKey]);
37
+ const primitiveKey = find(keys, k => k !== varsDeclarationKey);
38
+ const f = primitives[primitiveKey](parsePrimitiveArgs(primitives, tree[primitiveKey]));
39
+ return ({ vars, input }) => {
40
+ const extendedVars = { ...vars, ...getLocalVars({ vars, input }) };
41
+ return f({ vars: extendedVars, input });
42
+ }
43
+ }
44
+
45
+ function compileFunction(primitives, tree) {
46
+ const keys = Object.keys(tree);
47
+ const getLocalVars = compileVars(primitives, tree[varsDeclarationKey]);
48
+ const functionKey = find(keys, k => k !== varsDeclarationKey);
49
+ const arg = compileTree(primitives, tree[functionKey]);
50
+ return ({ vars, input }) => {
51
+ const extendedVars = { ...vars, ...getLocalVars({ vars, input }) };
52
+ const f = extendedVars[functionKey];
53
+ return f({ vars: extendedVars, input: arg({ vars: extendedVars, input })});
54
+ }
55
+ }
56
+
57
+ function parsePrimitiveArgs(primitives, tree) {
58
+ if (isString(tree)) { return compileString(tree); }
59
+
60
+ if (isArray(tree)) { return compileArray(primitives, tree) }
61
+
62
+ if (isObject(tree)) {
63
+ return hasPrimitiveProperties(tree) ? mapValues(tree, n => compileTree(primitives, n)) : compileTree(primitives, tree);
64
+ }
65
+
66
+ return () => tree;
67
+ }
68
+
69
+ function isPrimitive(primitives, tree) {
70
+ const ks = Object.keys(tree);
71
+ return ks.length > 0 && ks.length <= 2 && every(ks, k => !!primitives[k]);
72
+ }
73
+
74
+ function isFunction(tree) {
75
+ const ks = Object.keys(tree);
76
+ return ks.length > 0 && ks.length <= 2 && every(ks, k => k.startsWith('$'));
77
+ }
78
+
79
+ function hasPrimitiveProperties(tree) {
80
+ return Object.keys(tree)[0]?.startsWith('_');
81
+ }
82
+
83
+ function compileArray(primitives, tree) {
84
+ const funks = map(tree, n => compileTree(primitives, n), primitives);
85
+ return x => map(funks, f => f(x));
86
+ }
87
+
88
+ function compileVars(primitives, obj) {
89
+ const funks = mapValues(obj, n => compileTree(primitives, n));
90
+ return ({vars, input}) => {
91
+ const localVars = {};
92
+ const extendedVars = { ...vars };
93
+ for (const key in funks) {
94
+ localVars[key] = key.startsWith('$')
95
+ ? funks[key]
96
+ : funks[key]({ vars: extendedVars, input });
97
+ extendedVars[key] = localVars[key];
98
+ }
99
+ return localVars;
100
+ }
101
+ }
102
+
103
+ function compileObject(primitives, obj) {
104
+ const funks = mapValues(obj, n => compileTree(primitives, n));
105
+ return x => mapValues(funks, funk => funk(x));
106
+ }
107
+
108
+ function compileString(str) {
109
+ if (str === '#') {
110
+ return ({ input }) => input;
111
+ }
112
+ if (str.startsWith('#')) {
113
+ str = str.slice(1);
114
+ str = /^\d/.test(str) ? `[${str[0]}]` + str.slice(1) : str;
115
+ str = str.startsWith('.') ? str.slice(1) : str;
116
+ const pointer = str;
117
+ return ({ input }) => get(input, pointer);
118
+ }
119
+ if (str.startsWith('@')) {
120
+ const pointer = str.slice(1);
121
+ return ({ vars }) => get(vars, pointer);
122
+ }
123
+ return () => str;
124
+ }
@@ -0,0 +1,58 @@
1
+ import { printf } from 'fast-printf';
2
+ import { concat, divide, eq, filter, first, groupBy, gt, gte, join, keyBy, lt, lte, map, mapValues, multiply,
3
+ reduce, split, subtract, sum, tail, take, takeWhile, values, zipWith } from 'lodash-es'
4
+
5
+ const input = ({ input }) => input
6
+
7
+ export const primitives = {
8
+ $let: true,
9
+ $: f => x => v => f({ ...x, input: v}),
10
+ $in: f => x => f(x),
11
+ $return: f => x => f(x),
12
+ $apply: ({ _fn, _to = input }) => x => _fn({ ...x, input: _to(x)}),
13
+ $pipeline: f => x => reduce(f(x), (a, g) => g(a), x.input),
14
+ $conditional: ({ _if, _then, _else }) => x => _if(x) ? _then(x) : _else(x),
15
+ $eq: f => x => eq(...f(x)),
16
+ $neq: f => x => !eq(...f(x)),
17
+ $negate: f => x => !f(x),
18
+ $lt: f => x => lt(...f(x)),
19
+ $lte: f => x => lte(...f(x)),
20
+ $gt: f => x => gt(...f(x)),
21
+ $gte: f => x => gte(...f(x)),
22
+ $map: ({ _fn, _over = input }) => x => map(_over(x), v => _fn({ ...x, input: v })),
23
+ $mapValues: ({ _fn, _of = input }) => x => mapValues(_of(x), v => _fn({ ...x, input: v })),
24
+ $sum: f => x => sum(f(x)),
25
+ $subtract: f => x => subtract(...f(x)),
26
+ $multiply: f => x => multiply(...f(x)),
27
+ $divide: f => x => divide(...f(x)),
28
+ $filter: ({ _predicate, _collection = input }) => x => filter(_collection(x), v => _predicate({ ...x, input: v })),
29
+ $head: f => x => first(f(x)),
30
+ $tail: f => x => tail(f(x)),
31
+ $concat: f => x => concat(...f(x)),
32
+ $group: ({ _by, _collection = input }) => x => groupBy(_collection(x), v => _by({...x, input: v})),
33
+ $toDictionary: ({ _by, _collection = input }) => x => keyBy(_collection(x), v => _by({...x, input: v})),
34
+ $values: f => x => values(f(x)),
35
+ $split: ({ _separator, _string = input }) => x => split(_string(x), _separator(x)),
36
+ $match: ({ _pattern, _string = input }) => x => _string(x).match(_pattern(x)),
37
+ $join: ({ _separator, _strings = input }) => x => join(_strings(x), _separator(x)),
38
+ $printf: ({ _template, _args = input}) => x => printf(_template(x), ..._args(x)),
39
+ $take: ({ _while, _count, _from = input }) => x => {
40
+ let y = _from(x);
41
+ y = _while ? takeWhile(y, v => _while({ ...x, input: v })) : y
42
+ y = _count ? take(y, _count(x)) : y
43
+ return y;
44
+ },
45
+ $zip: ({ _with, _sequences = input }) => {
46
+ const combinator = _with ? (x, v) => _with({...x, input: v}) : (x, v) => v;
47
+ return x => {
48
+ const [as, bs] = _sequences(x);
49
+ return zipWith(as, bs, (a, b) => combinator(x, [a, b]));
50
+ }
51
+ },
52
+ $fold: ({ _with, _init, _collection = input }) => {
53
+ const aggregator = (x, v) => _with({...x, input: v});
54
+ return _init
55
+ ? x => reduce(_collection(x), (a, v) => aggregator(x, [a, v]), _init(x))
56
+ : x => reduce(_collection(x), (a, v) => aggregator(x, [a, v]));
57
+ }
58
+ }