lambdajson-js 3.2.0 → 3.3.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 CHANGED
@@ -32,6 +32,13 @@ and the errors and warnings (impossible paths, possibly missing operands, mismat
32
32
  comparisons, unbound variables) found from the type of the input, without running the program.
33
33
  See the language documentation.
34
34
 
35
+ ## Changes in 3.3.0
36
+
37
+ * New primitive `$template`: `{ "$template": { "with": { name: expression }, "mapping": … } }` returns `mapping` as data, a mapping to run later, with the names bound by `with` filled in. A string equal to `"@name"` (or `"@name.path"`) is replaced by the value, an object key equal to `"@name"` by the value as a string; `#` paths, `$` keys and names `with` doesn't bind (lambda parameters, `$let` variables) stay as written. The mapping is never evaluated.
38
+ * A substituted value is escaped (a string starting with `#`, `@` or `\` gets a backslash, recursively), so a computed value is never read as an expression by the later run. Keys that would be read as a call or an escape (a substituted key, or a key of a substituted object, starting with `$` or `\`) are escaped too. Nothing is escaped inside the argument of `$literal`, where values are taken as they are.
39
+ * A substituted key must be a string, number or boolean (`invalid-template-key` at run time otherwise).
40
+ * `infer`: the result type is the filled mapping as a literal, each hole typed by its bound expression; `with` is inferred as usual (a wrong path is reported at its place); a bound name the mapping never uses is the warning `unused-template-name`.
41
+
35
42
  ## Changes in 3.2.0
36
43
 
37
44
  * `infer`: the argument of a typed function is checked property by property, recursively. A property whose type is definitely disjoint from the declared one (wrong kind, literal outside `enum`/`const`) is a `type-mismatch` naming its path (`the argument.entityType is 5, expected string`). `any`, unknown and overlapping properties are not reported; optional properties of the argument type are skipped.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lambdajson-js",
3
- "version": "3.2.0",
3
+ "version": "3.3.0",
4
4
  "description": "LambdaJSON to JavaScript function compiler",
5
5
  "type": "module",
6
6
  "main": "./src/js-compiler.js",
package/src/infer.js CHANGED
@@ -1,6 +1,7 @@
1
1
  import { isArray, isEqual, isPlainObject, isString, mapValues, toPath } from 'lodash-es';
2
2
  import { primitives as builtins } from './primitives.js';
3
3
  import { lint } from './js-compiler.js';
4
+ import { isLiteralCall, occurrence, protectKey, protectString } from './template.js';
4
5
  import {
5
6
  ANY, ARRAY, BOOLEAN, FUNCTION, NULL, NUMBER, OBJECT, STRING,
6
7
  arrayOf, describe, disjoint, isAny, isNullable, itemOf, literalType, members, nonNull, normalize,
@@ -43,6 +44,7 @@ function createEngine(prims, report) {
43
44
  const warning = (code, path, message) => report('warning', code, path, message);
44
45
 
45
46
  function tree(env, node, path) {
47
+ if (env.quote && (isString(node) || isPlainObject(node))) return quoted(env, node, path);
46
48
  if (isString(node)) return string(env, node, path);
47
49
  if (isArray(node)) return tuple(node.map((n, i) => tree(env, n, pointer(path, i))));
48
50
  if (isPlainObject(node)) {
@@ -294,6 +296,7 @@ function createEngine(prims, report) {
294
296
 
295
297
  const FORMS = {
296
298
  $literal: (env, value) => literalType(value),
299
+ $template: (env, value, path) => template(env, value, path),
297
300
  $: (env, value, path) => {
298
301
  tree({ ...env, input: ANY }, value, path);
299
302
  return FUNCTION;
@@ -318,6 +321,59 @@ function createEngine(prims, report) {
318
321
  FORMS[key] = (env, value, path) => { ordering(env, value, path); return BOOLEAN; };
319
322
  }
320
323
 
324
+ /**
325
+ * `$template`: `with` is inferred as usual; the mapping is then walked in quote mode (see `tree`),
326
+ * so its type is the filled mapping as a literal, each hole typed by its bound expression.
327
+ * The mapping runs later against another input, so it is not checked here.
328
+ */
329
+ function template(env, { with: bindings = {}, mapping }, path) {
330
+ const types = {};
331
+ for (const [name, expression] of Object.entries(bindings)) types[name] = tree(env, expression, pointer(path, 'with', name));
332
+ const quote = { types, used: new Set(), literal: false };
333
+ const result = tree({ ...env, quote }, mapping, pointer(path, 'mapping'));
334
+ for (const name of Object.keys(types)) {
335
+ if (!quote.used.has(name)) warning('unused-template-name', pointer(path, 'with', name), `'${name}' is bound but the mapping never uses '@${name}'`);
336
+ }
337
+ return result;
338
+ }
339
+
340
+ const protectType = t => {
341
+ if (typeof t.const === 'string') return { ...t, const: protectString(t.const) };
342
+ if (t.prefixItems) return { ...t, prefixItems: t.prefixItems.map(protectType) };
343
+ if (t.properties) return { ...t, properties: mapValues(t.properties, protectType) };
344
+ return t;
345
+ };
346
+
347
+ /** Quote mode: a string or an object is data, except the holes. */
348
+ function quoted(env, node, path) {
349
+ const { quote } = env;
350
+ const hole = text => {
351
+ const found = isString(text) ? occurrence(text) : undefined;
352
+ if (found && has(quote.types, found.name)) quote.used.add(found.name);
353
+ return found && has(quote.types, found.name) ? found : undefined;
354
+ };
355
+ if (isString(node)) {
356
+ const found = hole(node);
357
+ if (!found) return literalType(node);
358
+ const t = walkPath(quote.types[found.name], found.path === undefined ? [] : toPath(found.path), message => error('unknown-path', path, message));
359
+ return quote.literal ? t : protectType(t);
360
+ }
361
+ const inner = quote.literal || isLiteralCall(node) ? { ...env, quote: { ...quote, literal: true } } : env;
362
+ const properties = {};
363
+ let exact = true;
364
+ for (const [key, item] of Object.entries(node)) {
365
+ const found = hole(key);
366
+ let name = key;
367
+ if (found) {
368
+ const { const: value } = quote.types[found.name];
369
+ if (['string', 'number', 'boolean'].includes(typeof value)) name = inner.quote.literal ? String(value) : protectKey(String(value));
370
+ else exact = false;
371
+ }
372
+ properties[name] = tree(inner, item, pointer(path, key));
373
+ }
374
+ return exact ? { type: 'object', properties, required: Object.keys(properties), additionalProperties: false } : OBJECT;
375
+ }
376
+
321
377
  function logic(env, value, path, empty) {
322
378
  const types = isArray(value) ? args(env, value, path) : [itemOf(tree(env, value, path))];
323
379
  return orAny(union(...types, ...(types.length === 0 ? [literalType(empty)] : [])));
@@ -1,5 +1,6 @@
1
1
  import { get, isArray, isPlainObject, isString, map, mapValues, zipObject } from 'lodash-es'
2
2
  import { primitives, LambdaJSONRuntimeError } from './primitives.js';
3
+ import { isLiteralCall, occurrence, protect, protectKey } from './template.js';
3
4
 
4
5
  export {
5
6
  compile,
@@ -81,6 +82,8 @@ const pointer = (path, key) => `${path}/${String(key).replace(/~/g, '~0').replac
81
82
  const fail = (code, path, message) => { throw new LambdaJSONError(code, path, message); };
82
83
 
83
84
  function compileTree(scope, tree, path) {
85
+ if (scope.quote) return compileQuoted(scope, tree, path);
86
+
84
87
  if (isString(tree)) { return compileString(scope, tree, path); }
85
88
 
86
89
  if (isArray(tree)) { return compileArray(scope, tree, path); }
@@ -164,6 +167,10 @@ function specialContext(scope, key, path) {
164
167
  compile: (tree, ...steps) => compileTree(scope, tree, steps.reduce(pointer, path)),
165
168
  fail: (message, ...steps) => fail('invalid-arguments', steps.reduce(pointer, path), `${key}: ${message}`),
166
169
  warn: (code, message, ...steps) => scope.warn(code, steps.reduce(pointer, path), message),
170
+ quote: (tree, names, invalidKey, ...steps) => {
171
+ const f = compileTree({ ...scope, quote: { names, literal: false, invalidKey } }, tree, steps.reduce(pointer, path));
172
+ return bound => f({ bound });
173
+ },
167
174
  path
168
175
  };
169
176
  }
@@ -280,6 +287,42 @@ function compileObject(scope, obj, path) {
280
287
  return x => mapValues(funks, f => f(x));
281
288
  }
282
289
 
290
+ /**
291
+ * Quote mode (`$template`): the tree is data, so nothing is evaluated, except the holes, the names
292
+ * bound by `with`. The functions take `{ bound }`, the values of those names. Arrays recurse as usual.
293
+ */
294
+ function compileQuoted(scope, tree, path) {
295
+ const { names, literal } = scope.quote;
296
+ const hole = text => {
297
+ const found = isString(text) ? occurrence(text) : undefined;
298
+ return found && names.has(found.name) ? found : undefined;
299
+ };
300
+ if (isArray(tree)) return compileArray(scope, tree, path);
301
+ if (isPlainObject(tree)) {
302
+ const inner = literal || isLiteralCall(tree) ? { ...scope, quote: { ...scope.quote, literal: true } } : scope;
303
+ const entries = Object.entries(tree).map(([key, item]) => {
304
+ const found = hole(key);
305
+ const value = compileTree(inner, item, pointer(path, key));
306
+ if (!found) return [() => key, value];
307
+ const { invalidKey } = scope.quote;
308
+ return [({ bound }) => {
309
+ const name = bound[found.name];
310
+ if (!['string', 'number', 'boolean'].includes(typeof name)) invalidKey(name);
311
+ return inner.quote.literal ? String(name) : protectKey(String(name));
312
+ }, value];
313
+ });
314
+ return x => {
315
+ const object = {};
316
+ for (const [key, value] of entries) object[key(x)] = value(x);
317
+ return object;
318
+ };
319
+ }
320
+ const found = hole(tree);
321
+ if (!found) return () => tree;
322
+ const read = found.path === undefined ? ({ bound }) => bound[found.name] : ({ bound }) => get(bound[found.name], found.path);
323
+ return literal ? read : x => protect(read(x));
324
+ }
325
+
283
326
  function compileString(scope, str, path) {
284
327
  if (str.startsWith('\\')) {
285
328
  const value = str.slice(1);
package/src/primitives.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import { printf } from 'fast-printf';
2
- import { concat, divide, every, filter, find, first, get, groupBy, gt, gte, includes, isArray, isEqual, isNil, join, keyBy, keys, lt, lte, map, mapValues, max, merge, min, multiply,
2
+ import { concat, divide, every, filter, find, first, get, groupBy, gt, gte, includes, isArray, isEqual, isNil, isPlainObject, join, keyBy, keys, lt, lte, map, mapValues, max, merge, min, multiply,
3
3
  omit, orderBy, pick, reduce, round, some, split, subtract, sum, tail, take, takeWhile, uniqWith, values, zipObject, zipWith } from 'lodash-es'
4
4
 
5
5
  /**
@@ -80,6 +80,19 @@ const sort = direction => named(['by?', 'collection=#', 'as?'], ({ by, collectio
80
80
  const primitiveTable = {
81
81
  $let: true,
82
82
  $literal: special(value => () => value),
83
+ $template: special((argument, { compile, quote, fail, path }) => {
84
+ if (!isPlainObject(argument) || !('mapping' in argument) || Object.keys(argument).some(k => k !== 'mapping' && k !== 'with')) {
85
+ fail('takes { with?, mapping }');
86
+ }
87
+ if ('with' in argument && !isPlainObject(argument.with)) fail('with is an object of expressions', 'with');
88
+ const bound = mapValues(argument.with ?? {}, (expression, name) => compile(expression, 'with', name));
89
+ const invalidKey = value => {
90
+ const got = value === null ? 'null' : isArray(value) ? 'an array' : typeof value;
91
+ throw new LambdaJSONRuntimeError('invalid-template-key', path, `a name used as an object key must be a string, number or boolean, got ${got}`);
92
+ };
93
+ const filled = quote(argument.mapping, new Set(Object.keys(bound)), invalidKey, 'mapping');
94
+ return x => filled(mapValues(bound, f => f(x)));
95
+ }, { description: '$template: { with?, mapping }, the mapping as data with the names of `with` filled in' }),
83
96
  $: f => x => v => f({ ...x, input: v }),
84
97
  $in: f => x => f(x),
85
98
  $return: f => x => f(x),
@@ -203,7 +216,7 @@ const numbers = 'array<number>';
203
216
  const container = { anyOf: [{ type: 'object' }, { type: 'array' }] };
204
217
 
205
218
  const signatures = {
206
- $literal: sig('any', 'any'), $: sig('any', 'function'), $in: sig('any', 'any'), $return: sig('any', 'any'),
219
+ $literal: sig('any', 'any'), $template: sig({ with: 'object', mapping: 'any' }, 'any'), $: sig('any', 'function'), $in: sig('any', 'any'), $return: sig('any', 'any'),
207
220
  $apply: sig({ fn: 'function', to: 'any', as: 'names' }, 'any'),
208
221
  $pipeline: sig('array<function>', 'any'),
209
222
  $if: sig('array', 'any'), $cond: sig('array', 'any'), $and: sig('array', 'any'), $or: sig('array', 'any'),
@@ -0,0 +1,31 @@
1
+ import { isPlainObject } from 'lodash-es';
2
+
3
+ /**
4
+ * Support of `$template`, a mapping returned as data with the names bound by `with` filled in.
5
+ * The compiler and `infer` walk the mapping in "quote" mode; these are the rules they share.
6
+ */
7
+
8
+ const NAMED = /^@([^.]+)(?:\.(.+))?$/;
9
+
10
+ /** `"@name"` or `"@name.path"` as { name, path }, or undefined for any other string. */
11
+ export const occurrence = text => {
12
+ const [, name, path] = NAMED.exec(text) ?? [];
13
+ return name === undefined ? undefined : { name, path };
14
+ };
15
+
16
+ /** A string that would be read as an expression gets a leading backslash. */
17
+ export const protectString = value => /^[#@\\]/.test(value) ? `\\${value}` : value;
18
+
19
+ /** A key that would be read as a call (`$`) or as an escape (`\`) gets a leading backslash. */
20
+ export const protectKey = key => /^[$\\]/.test(key) ? `\\${key}` : key;
21
+
22
+ export const protect = value => typeof value === 'string'
23
+ ? protectString(value)
24
+ : Array.isArray(value)
25
+ ? value.map(protect)
26
+ : isPlainObject(value)
27
+ ? Object.fromEntries(Object.entries(value).map(([key, item]) => [protectKey(key), protect(item)]))
28
+ : value;
29
+
30
+ /** The arguments of a `{ "$literal": … }` call are values: nothing in them is read as an expression. */
31
+ export const isLiteralCall = mapping => isPlainObject(mapping) && Object.hasOwn(mapping, '$literal');