lambdajson-js 1.0.0 → 1.0.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.
Files changed (3) hide show
  1. package/README.md +5 -292
  2. package/package.json +1 -1
  3. 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 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
- ---
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 "./src/js-compiler.js";
8
+ import { compile } from 'lambdajson-js';
30
9
 
31
- // A minimal LambdaJSON program
32
10
  const program = {
33
- "$sum": "#"
11
+ $sum: ['#', 2]
34
12
  };
35
-
36
13
  const f = compile(program);
37
14
 
38
- // f is a pure function from input -> output
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lambdajson-js",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
4
  "description": "LambdaJSON to JavaScript function compiler",
5
5
  "type": "module",
6
6
  "main": "./src/js-compiler.js",
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
-