lambdajson-js 3.1.2 → 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,20 @@ 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
+
42
+ ## Changes in 3.2.0
43
+
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.
45
+ * `infer`: new problem codes `missing-property` (a required key is absent) and `unknown-property` (a key where `additionalProperties` is `false`), reported only when the argument's type is exact (`additionalProperties: false`, as for object literals).
46
+ * `infer`: items of an array literal are checked against the declared `items`/`prefixItems`.
47
+ * Programs that passed before may now report these errors; each newly reported problem is a mismatch between the argument and the declared signature.
48
+
35
49
  ## Changes in 3.1.2
36
50
 
37
51
  * `infer`: after an impossible path the walk continues with any value, so the problem isn't reported a second time where the value is used.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lambdajson-js",
3
- "version": "3.1.2",
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)) {
@@ -169,10 +171,49 @@ function createEngine(prims, report) {
169
171
  return [{ type: itemOf(array), path }];
170
172
  }
171
173
 
172
- function check(expected, actual, path, what) {
174
+ function check(expected, actual, path, what, value) {
173
175
  if (disjoint(actual, expected)) {
174
176
  error('type-mismatch', path, `${what} is ${describe(actual)}, expected ${describe(expected)}`);
177
+ return;
175
178
  }
179
+ const e = members(expected);
180
+ const a = members(nonNull(actual));
181
+ if (e.length !== 1 || a.length !== 1 || isAny(e[0]) || isAny(a[0])) return;
182
+ if (e[0].type === 'object' && a[0].type === 'object') checkObject(e[0], a[0], path, what, value);
183
+ else if (e[0].type === 'array' && a[0].type === 'array') checkArray(e[0], a[0], path, what, value);
184
+ }
185
+
186
+ const has = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
187
+
188
+ /** Compares the properties both types know; keys are compared only when the argument's type is exact. */
189
+ function checkObject(expected, actual, path, what, value) {
190
+ const expectedProps = expected.properties ?? {};
191
+ const actualProps = actual.properties ?? {};
192
+ const exact = actual.additionalProperties === false;
193
+ const literal = isPlainObject(value);
194
+ const at = k => literal && has(value, k) ? pointer(path, k) : path;
195
+ for (const k of expected.required ?? []) {
196
+ if (exact && !has(actualProps, k)) error('missing-property', path, `${what} has no '${k}', which is required`);
197
+ }
198
+ for (const [k, type] of Object.entries(actualProps)) {
199
+ // an optional property may be missing, which is not a mismatch
200
+ if (!(actual.required ?? []).includes(k)) continue;
201
+ const target = has(expectedProps, k) ? expectedProps[k] : expected.additionalProperties;
202
+ if (target === false) {
203
+ if (exact) error('unknown-property', at(k), `${what} has '${k}', which is not a property of the expected object (declared: ${Object.keys(expectedProps).join(', ') || 'none'})`);
204
+ } else if (target !== undefined) {
205
+ check(target, type, at(k), `${what}.${k}`, literal ? value[k] : undefined);
206
+ }
207
+ }
208
+ }
209
+
210
+ /** Compares the items of an array literal. */
211
+ function checkArray(expected, actual, path, what, value) {
212
+ if (!isArray(value) || actual.prefixItems === undefined) return;
213
+ actual.prefixItems.forEach((type, i) => {
214
+ const target = expected.prefixItems?.[i] ?? expected.items;
215
+ if (target && target !== false) check(target, type, pointer(path, i), `${what}[${i}]`, value[i]);
216
+ });
176
217
  }
177
218
 
178
219
  function checkTakes(expected, arg, value, path) {
@@ -181,7 +222,7 @@ function createEngine(prims, report) {
181
222
  if (disjoint(arg, ARRAY)) return;
182
223
  for (const operand of operands(value, arg, path)) check(expected.items, operand.type, operand.path, 'an item');
183
224
  } else {
184
- check(expected, arg, path, 'the argument');
225
+ check(expected, arg, path, 'the argument', value);
185
226
  }
186
227
  }
187
228
 
@@ -200,7 +241,7 @@ function createEngine(prims, report) {
200
241
  }
201
242
  // an untyped argument may be a lambda of `as`: bind its names to any value
202
243
  types[k] = tree(takes[k] === undefined && value.as !== undefined ? bind(env, value.as) : env, v, argPath);
203
- if (takes[k] !== undefined) check(toType(takes[k]), types[k], argPath, `'${k}'`);
244
+ if (takes[k] !== undefined) check(toType(takes[k]), types[k], argPath, `'${k}'`, v);
204
245
  }
205
246
  for (const spec of prim.params) {
206
247
  const name = spec.replace(/(=#|\?)$/, '');
@@ -255,6 +296,7 @@ function createEngine(prims, report) {
255
296
 
256
297
  const FORMS = {
257
298
  $literal: (env, value) => literalType(value),
299
+ $template: (env, value, path) => template(env, value, path),
258
300
  $: (env, value, path) => {
259
301
  tree({ ...env, input: ANY }, value, path);
260
302
  return FUNCTION;
@@ -279,6 +321,59 @@ function createEngine(prims, report) {
279
321
  FORMS[key] = (env, value, path) => { ordering(env, value, path); return BOOLEAN; };
280
322
  }
281
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
+
282
377
  function logic(env, value, path, empty) {
283
378
  const types = isArray(value) ? args(env, value, path) : [itemOf(tree(env, value, path))];
284
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');