@niscorp/prism 0.3.1 → 0.3.3

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/dist/index.js CHANGED
@@ -1,6 +1,6 @@
1
- export { MAPPING_OPS, getConfigJsonSchema, getNodeJsonSchema, getProfileJsonSchema } from './chunk-GK4CIKKT.js';
2
- import { PrismError, ErrorCode, ConfigSchema, isWithNode, isRenameKeysNode, isConstNode, isSumNode, isAvgNode, isCountNode, isMinNode, isMaxNode, isPluckNode, isTakeNode, isDropNode, isMatchNode, isFlatMapNode, isJsonObject, isRefNode, parseJsonPath, isVarNode, isPlainObject, OPTIONAL_FIELDS_KEY, isGetNode, isMapNode, isFilterNode, isReduceNode, isSliceNode, isFlattenNode, isUniqueNode, isSortByNode, isAddNode, isSubNode, isMulNode, isDivNode, isRoundNode, isModNode, isToNumberNode, isJoinNode, isToStringNode, isInterpolateNode, isFillNode, isTrimNode, isLowerNode, isUpperNode, isSplitNode, isReplaceNode, isEqNode, isNeqNode, isGtNode, isGteNode, isLtNode, isLteNode, isEmptyNode, isStartsWithNode, isEndsWithNode, isContainsNode, isNotNode, isAndNode, isOrNode, isMergeNode, isCoalesceNode, isCaseNode, isEntriesOfNode, isKeyByNode, isGroupByNode, isKeysNode, isValuesNode, isFromEntriesNode, isPickNode, isOmitNode, isTypeNode, isLengthNode, isHasNode, isUpdateNode, isAssertNode, isWalkNode, isDateNode, isDateAddNode, isDateDiffNode, isLocaleDateNode, isLocaleMoneyNode, isLocaleNumberNode, parseJsonPathCached, getByPath, isJsonArray } from './chunk-WKS4OCKN.js';
3
- export { ConfigSchema, ErrorCode, NodeSchema, OP_KEYS, PrismError } from './chunk-WKS4OCKN.js';
1
+ export { MAPPING_OPS, getConfigJsonSchema, getNodeJsonSchema, getProfileJsonSchema } from './chunk-VNGBVDUM.js';
2
+ import { PrismError, ErrorCode, ConfigSchema, isWithNode, isRenameKeysNode, isConstNode, isSumNode, isAvgNode, isCountNode, isMinNode, isMaxNode, isPluckNode, isTakeNode, isDropNode, isMatchNode, isFlatMapNode, isJsonObject, takeOrigin, formOf, isRefNode, parseJsonPath, isVarNode, isPlainObject, OPTIONAL_FIELDS_KEY, isGetNode, isMapNode, isFilterNode, isReduceNode, isSliceNode, isFlattenNode, isUniqueNode, isSortByNode, isAddNode, isSubNode, isMulNode, isDivNode, isRoundNode, isModNode, isToNumberNode, isJoinNode, isToStringNode, isInterpolateNode, isFillNode, isTrimNode, isLowerNode, isUpperNode, isSplitNode, isReplaceNode, isEqNode, isNeqNode, isGtNode, isGteNode, isLtNode, isLteNode, isEmptyNode, isStartsWithNode, isEndsWithNode, isContainsNode, isNotNode, isAndNode, isOrNode, isMergeNode, isCoalesceNode, isCaseNode, isEntriesOfNode, isKeyByNode, isGroupByNode, isKeysNode, isValuesNode, isFromEntriesNode, isPickNode, isOmitNode, isTypeNode, isLengthNode, isHasNode, isUpdateNode, isAssertNode, isWalkNode, isDateNode, isDateAddNode, isDateDiffNode, isLocaleDateNode, isLocaleMoneyNode, isLocaleNumberNode, failAt, clip, parseJsonPathCached, getByPath, whereStopped, jsonPathUpTo, isJsonArray, INDEX_TEXT, describeValue } from './chunk-OL4CCYWX.js';
3
+ export { ConfigSchema, ErrorCode, NodeSchema, OP_KEYS, PrismError } from './chunk-OL4CCYWX.js';
4
4
  import { exceedsDepth, depthRefusal } from '@niscorp/strata';
5
5
  import dayjs from 'dayjs';
6
6
  import utc from 'dayjs/plugin/utc.js';
@@ -23,7 +23,31 @@ var explainOne = (issue, prefix) => {
23
23
  }
24
24
  return bestDepth <= here.length ? [{ path: here, message: "Not a Prism node: no op matches, and it is not a plain value." }] : best;
25
25
  };
26
- var explainIssues = (issues) => issues.flatMap((i) => explainOne(i, []));
26
+ var valueAt = (value, path) => path.reduce((at, key) => typeof at === "object" && at !== null ? Reflect.get(at, key) : void 0, value);
27
+ var opOf = (value, path) => {
28
+ const last = path[path.length - 1];
29
+ if (typeof last === "string" && last.startsWith("$") && formOf(last) === void 0) return void 0;
30
+ const here = valueAt(value, path);
31
+ if (typeof here === "object" && here !== null && !Array.isArray(here)) {
32
+ const ops = Object.keys(here).filter((key) => formOf(key) !== void 0);
33
+ if (ops.length === 1) return ops[0];
34
+ }
35
+ for (const back of [1, 2]) {
36
+ const i = path.length - back;
37
+ const key = path[i];
38
+ if (typeof key !== "string" || formOf(key) === void 0) continue;
39
+ const holder = valueAt(value, path.slice(0, i));
40
+ if (typeof holder === "object" && holder !== null && Object.keys(holder).length === 1) return key;
41
+ }
42
+ return void 0;
43
+ };
44
+ var withForm = (explained, value) => {
45
+ const op = opOf(value, explained.path);
46
+ const form = op === void 0 ? void 0 : formOf(op);
47
+ return form === void 0 ? explained : { ...explained, message: `${explained.message.replace(/\.$/, "")}. Form: ${form}` };
48
+ };
49
+ var explainIssues = (issues, value) => issues.flatMap((i) => explainOne(i, [])).map((explained) => withForm(explained, value));
50
+ var issuesText = (explained) => explained.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ");
27
51
 
28
52
  // src/sugar/rewriters.ts
29
53
  var rewriteSum = (node, recurse) => ({
@@ -180,12 +204,14 @@ var desugar = (node) => {
180
204
  // src/engine/budget.ts
181
205
  var DEFAULT_LIMITS = { maxSteps: 1e6, maxStringLength: 1e6, maxValues: 1e6 };
182
206
  var createBudget = (limits) => ({ limits: { ...DEFAULT_LIMITS, ...limits }, steps: 0, sizes: /* @__PURE__ */ new WeakMap() });
183
- var refuse = (what, limit) => {
184
- throw new PrismError(`Evaluation stopped: ${what} (limit ${limit})`, ErrorCode.BUDGET, { details: { limit } });
207
+ var refuse = (what, limit, node) => {
208
+ const message = `Evaluation stopped: ${what} (limit ${limit}).`;
209
+ if (typeof node === "object" && node !== null) return failAt(message, ErrorCode.BUDGET, { details: { limit } }, { node, form: false });
210
+ throw new PrismError(message, ErrorCode.BUDGET, { details: { limit } });
185
211
  };
186
- var spendStep = (budget) => {
212
+ var spendStep = (budget, node) => {
187
213
  budget.steps += 1;
188
- if (budget.steps > budget.limits.maxSteps) refuse("it evaluated too many nodes", budget.limits.maxSteps);
214
+ if (budget.steps > budget.limits.maxSteps) refuse("it evaluated too many nodes", budget.limits.maxSteps, node);
189
215
  };
190
216
  var sizeOf = (value, budget) => {
191
217
  if (value === null || typeof value !== "object") return 1;
@@ -199,14 +225,14 @@ var sizeOf = (value, budget) => {
199
225
  budget.sizes.set(value, size);
200
226
  return size;
201
227
  };
202
- var measureString = (value, budget) => {
203
- if (typeof value === "string" && value.length > budget.limits.maxStringLength) refuse(`a string of ${value.length} characters`, budget.limits.maxStringLength);
228
+ var measureString = (value, budget, node) => {
229
+ if (typeof value === "string" && value.length > budget.limits.maxStringLength) refuse(`a string of ${value.length} characters`, budget.limits.maxStringLength, node);
204
230
  };
205
- var measure = (value, budget) => {
231
+ var measure = (value, budget, node) => {
206
232
  if (budget === void 0) return;
207
- measureString(value, budget);
233
+ measureString(value, budget, node);
208
234
  if (value !== null && typeof value === "object" && sizeOf(value, budget) > budget.limits.maxValues) {
209
- refuse("a result holding too many values", budget.limits.maxValues);
235
+ refuse("a result with too many values", budget.limits.maxValues, node);
210
236
  }
211
237
  };
212
238
 
@@ -217,8 +243,15 @@ var opRef = (node, context, _evaluate) => {
217
243
  const attached = Reflect.get(node, SEGMENTS_KEY);
218
244
  const segments = isSegmentsArray(attached) ? attached : parseJsonPathCached(node.$ref);
219
245
  const resolved = getByPath(context.source, segments);
220
- if (resolved === void 0)
221
- throw new PrismError("Path not found", ErrorCode.MISSING_PATH, { op: "$ref", path: node.$ref });
246
+ if (resolved === void 0) {
247
+ const steps = segments.map((s) => s.type === "key" ? s.key : s.index);
248
+ return failAt("Path not found.", ErrorCode.MISSING_PATH, { op: "$ref", path: node.$ref }, {
249
+ node,
250
+ op: "$ref",
251
+ form: false,
252
+ detail: () => `$ref ${JSON.stringify(node.$ref)} ${whereStopped(context.source, steps, (count) => jsonPathUpTo(segments, count))}`
253
+ });
254
+ }
222
255
  return resolved;
223
256
  };
224
257
  var copyOf = (value) => {
@@ -231,33 +264,50 @@ var copyOf = (value) => {
231
264
  var opConst = (node, context, _evaluate) => context.kept === true ? copyOf(node.$const) : node.$const;
232
265
  var opVar = (node, context, _evaluate) => {
233
266
  const value = context.vars[node.$var];
234
- if (value === void 0)
235
- throw new PrismError(`Variable not found: ${node.$var}`, ErrorCode.VAR_NOT_FOUND, { op: "$var", path: node.$var });
267
+ if (value === void 0) {
268
+ const names = Object.keys(context.vars).filter((name) => !name.startsWith("__"));
269
+ const scope = names.length === 0 ? "No variable is in scope here." : `In scope: ${names.join(", ")}.`;
270
+ return failAt(`Variable not found: ${node.$var}. ${scope}`, ErrorCode.VAR_NOT_FOUND, { op: "$var", path: node.$var }, { node, op: "$var", form: false });
271
+ }
236
272
  return value;
237
273
  };
274
+ var getStopped = (node, root, count, context, evaluate2) => {
275
+ const unbudgeted = { ...context, budget: void 0 };
276
+ const steps = node.$get.path.slice(0, count).map((segment) => {
277
+ const evaluated = typeof segment === "object" && segment !== null ? evaluate2(segment, unbudgeted) : segment;
278
+ return typeof evaluated === "number" ? evaluated : String(evaluated);
279
+ });
280
+ return `$get.path ${JSON.stringify(steps)} ${whereStopped(root, steps, (upTo) => upTo === 0 ? "from" : JSON.stringify(steps.slice(0, upTo)), true)}`;
281
+ };
238
282
  var opGet = (node, context, evaluate2) => {
239
283
  const { from, path, fallback } = node.$get;
240
- let current2 = evaluate2(from, context);
241
- for (const segment of path) {
284
+ const root = evaluate2(from, context);
285
+ let current2 = root;
286
+ for (let i = 0; i < path.length; i++) {
287
+ const segment = path[i];
242
288
  const evaluated = typeof segment === "object" && segment !== null ? evaluate2(segment, context) : segment;
243
289
  if (typeof evaluated === "number") {
244
290
  if (!isJsonArray(current2)) {
245
291
  if (fallback !== void 0) return evaluate2(fallback, context);
246
- throw new PrismError("Expected array for index access", ErrorCode.TYPE, { op: "$get" });
292
+ return failAt(getStopped(node, root, i + 1, context, evaluate2), ErrorCode.TYPE, { op: "$get" }, { node, op: "$get", field: "path", form: true });
247
293
  }
248
294
  current2 = current2[evaluated];
249
295
  } else {
250
296
  const key = String(evaluated);
297
+ if (isJsonArray(current2) && INDEX_TEXT.test(key)) {
298
+ current2 = current2[Number(key)];
299
+ continue;
300
+ }
251
301
  if (!isJsonObject(current2)) {
252
302
  if (fallback !== void 0) return evaluate2(fallback, context);
253
- throw new PrismError("Expected object for key access", ErrorCode.TYPE, { op: "$get" });
303
+ return failAt(getStopped(node, root, i + 1, context, evaluate2), ErrorCode.TYPE, { op: "$get" }, { node, op: "$get", field: "path", form: true });
254
304
  }
255
305
  current2 = current2[key];
256
306
  }
257
307
  }
258
308
  if (current2 === void 0) {
259
309
  if (fallback !== void 0) return evaluate2(fallback, context);
260
- throw new PrismError("Path not found", ErrorCode.MISSING_PATH, { op: "$get" });
310
+ return failAt("Path not found.", ErrorCode.MISSING_PATH, { op: "$get" }, { node, op: "$get", field: "path", form: true, detail: () => getStopped(node, root, path.length, context, evaluate2) });
261
311
  }
262
312
  return current2;
263
313
  };
@@ -266,7 +316,7 @@ var opWith = (node, context, evaluate2) => {
266
316
  const extendedVars = { ...context.vars };
267
317
  for (const [name, expr] of Object.entries(declarations)) {
268
318
  extendedVars[name] = evaluate2(expr, context);
269
- measure(extendedVars[name] ?? null, context.budget);
319
+ measure(extendedVars[name] ?? null, context.budget, node);
270
320
  }
271
321
  return evaluate2(value, { ...context, vars: extendedVars });
272
322
  };
@@ -289,15 +339,26 @@ var loopScope = (context) => {
289
339
  return { scope: { ...context, vars }, vars };
290
340
  };
291
341
 
342
+ // src/ops/refuse.ts
343
+ var writtenNote = (written) => isPlainObject(written) ? ` That object was written in the program as ${clip(JSON.stringify(written), 60)}, and an object without a "$" key builds an object; put the node itself there.` : "";
344
+ var TEXT_LIKE = "text, a number, true, false or null";
345
+ var isTextLike = (value) => value === null || typeof value !== "object";
346
+ var refuseType = ({ node, op, field, needs, got, written, contextOp }) => failAt(
347
+ `${field === void 0 ? op : `${op}.${field}`} needs ${needs}, but got ${describeValue(got)}.${writtenNote(written)}`,
348
+ ErrorCode.TYPE,
349
+ { op: contextOp ?? op },
350
+ { node, op, ...field === void 0 ? {} : { field }, form: true }
351
+ );
352
+
292
353
  // src/ops/array.ops.ts
293
- var requireArray = (value, op) => {
354
+ var requireArray = (value, node, op, field, written) => {
294
355
  if (!isJsonArray(value))
295
- throw new PrismError(`Expected array for ${op}`, ErrorCode.TYPE, { op });
356
+ return refuseType({ node, op, ...field === void 0 ? {} : { field }, needs: "a list", got: value, written, contextOp: field === void 0 ? op : `${op}.${field}` });
296
357
  return value;
297
358
  };
298
359
  var opMap = (node, context, evaluate2) => {
299
360
  const { over, as, body } = node.$map;
300
- const input = requireArray(evaluate2(over, context), "$map.over");
361
+ const input = requireArray(evaluate2(over, context), node, "$map", "over", over);
301
362
  const result = [];
302
363
  const { scope, vars } = loopScope(context);
303
364
  for (const item of input) {
@@ -308,7 +369,7 @@ var opMap = (node, context, evaluate2) => {
308
369
  };
309
370
  var opFilter = (node, context, evaluate2) => {
310
371
  const { over, as, when } = node.$filter;
311
- const input = requireArray(evaluate2(over, context), "$filter.over");
372
+ const input = requireArray(evaluate2(over, context), node, "$filter", "over", over);
312
373
  const result = [];
313
374
  const { scope, vars } = loopScope(context);
314
375
  for (const item of input) {
@@ -320,14 +381,14 @@ var opFilter = (node, context, evaluate2) => {
320
381
  };
321
382
  var opReduce = (node, context, evaluate2) => {
322
383
  const { over, as, acc: accName = "acc", init, body } = node.$reduce;
323
- const input = requireArray(evaluate2(over, context), "$reduce.over");
384
+ const input = requireArray(evaluate2(over, context), node, "$reduce", "over", over);
324
385
  let accumulator = evaluate2(init, context);
325
386
  const { scope, vars } = loopScope(context);
326
387
  for (const item of input) {
327
388
  vars[as] = item;
328
389
  vars[accName] = accumulator;
329
390
  accumulator = evaluate2(body, scope);
330
- measure(accumulator, context.budget);
391
+ measure(accumulator, context.budget, node);
331
392
  }
332
393
  return accumulator;
333
394
  };
@@ -336,10 +397,10 @@ var opSlice = (node, context, evaluate2) => {
336
397
  const input = evaluate2(from, context);
337
398
  if (typeof input === "string") return input.slice(start, end);
338
399
  if (isJsonArray(input)) return input.slice(start, end);
339
- throw new PrismError("Expected array or string for $slice", ErrorCode.TYPE, { op: "$slice" });
400
+ return refuseType({ node, op: "$slice", field: "from", needs: "a list or text", got: input, written: from, contextOp: "$slice" });
340
401
  };
341
402
  var opFlatten = (node, context, evaluate2) => {
342
- const input = requireArray(evaluate2(node.$flatten, context), "$flatten");
403
+ const input = requireArray(evaluate2(node.$flatten, context), node, "$flatten", void 0, node.$flatten);
343
404
  const result = [];
344
405
  for (const item of input) {
345
406
  if (isJsonArray(item)) result.push(...item);
@@ -348,7 +409,7 @@ var opFlatten = (node, context, evaluate2) => {
348
409
  return result;
349
410
  };
350
411
  var opUnique = (node, context, evaluate2) => {
351
- const input = requireArray(evaluate2(node.$unique, context), "$unique");
412
+ const input = requireArray(evaluate2(node.$unique, context), node, "$unique", void 0, node.$unique);
352
413
  const seen = /* @__PURE__ */ new Set();
353
414
  const result = [];
354
415
  for (const item of input) {
@@ -360,12 +421,13 @@ var opUnique = (node, context, evaluate2) => {
360
421
  }
361
422
  return result;
362
423
  };
363
- var sortKey = (key) => {
424
+ var sortKey = (key, node) => {
364
425
  if (key !== null && typeof key === "object") {
365
- throw new PrismError(
366
- `$sortBy.by answered ${Array.isArray(key) ? "a list" : "an object"}; a sort key is a string or a number. To sort by two keys, sort by the second and then by the first: the sort keeps the order of equal items.`,
426
+ return failAt(
427
+ `$sortBy.by answered ${describeValue(key)}; a sort key is a string or a number. To sort by two keys, sort by the second and then by the first: the sort keeps the order of equal items.`,
367
428
  ErrorCode.TYPE,
368
- { op: "$sortBy" }
429
+ { op: "$sortBy" },
430
+ { node, op: "$sortBy", field: "by", form: true }
369
431
  );
370
432
  }
371
433
  return key;
@@ -374,11 +436,11 @@ var NULL_KIND = 3;
374
436
  var kindOf = (key) => key === null ? NULL_KIND : typeof key === "number" ? 0 : typeof key === "string" ? 1 : 2;
375
437
  var opSortBy = (node, context, evaluate2) => {
376
438
  const { over, as, by, dir = "asc" } = node.$sortBy;
377
- const input = requireArray(evaluate2(over, context), "$sortBy.over");
439
+ const input = requireArray(evaluate2(over, context), node, "$sortBy", "over", over);
378
440
  const { scope, vars } = loopScope(context);
379
441
  const keyed = input.map((item) => {
380
442
  vars[as] = item;
381
- return { item, key: sortKey(evaluate2(by, scope)) };
443
+ return { item, key: sortKey(evaluate2(by, scope), node) };
382
444
  });
383
445
  keyed.sort((a, b) => {
384
446
  const kindA = kindOf(a.key);
@@ -391,33 +453,41 @@ var opSortBy = (node, context, evaluate2) => {
391
453
  };
392
454
 
393
455
  // src/ops/math.ops.ts
394
- var requireNumbers = (node, context, evaluate2, op) => {
395
- const a = evaluate2(node[0], context);
396
- const b = evaluate2(node[1], context);
397
- if (typeof a !== "number" || typeof b !== "number")
398
- throw new PrismError(`Expected numbers for ${op}`, ErrorCode.TYPE, { op });
456
+ var requireNumbers = (node, pair, context, evaluate2, op) => {
457
+ const a = evaluate2(pair[0], context);
458
+ const b = evaluate2(pair[1], context);
459
+ if (typeof a !== "number" || typeof b !== "number") {
460
+ const wrong = typeof a === "number" ? 1 : 0;
461
+ return failAt(
462
+ `${op} needs two numbers, but got ${describeValue(a)} and ${describeValue(b)}.${writtenNote(pair[wrong])}`,
463
+ ErrorCode.TYPE,
464
+ { op },
465
+ { node, op, field: String(wrong), form: true }
466
+ );
467
+ }
399
468
  return [a, b];
400
469
  };
470
+ var refuseZero = (node, op) => failAt(`Division by zero: the second value of ${op} is 0.`, ErrorCode.DIVISION_BY_ZERO, { op }, { node, op, field: "1", form: false });
401
471
  var opAdd = (node, context, evaluate2) => {
402
- const [a, b] = requireNumbers(node.$add, context, evaluate2, "$add");
472
+ const [a, b] = requireNumbers(node, node.$add, context, evaluate2, "$add");
403
473
  return a + b;
404
474
  };
405
475
  var opSub = (node, context, evaluate2) => {
406
- const [a, b] = requireNumbers(node.$sub, context, evaluate2, "$sub");
476
+ const [a, b] = requireNumbers(node, node.$sub, context, evaluate2, "$sub");
407
477
  return a - b;
408
478
  };
409
479
  var opMul = (node, context, evaluate2) => {
410
- const [a, b] = requireNumbers(node.$mul, context, evaluate2, "$mul");
480
+ const [a, b] = requireNumbers(node, node.$mul, context, evaluate2, "$mul");
411
481
  return a * b;
412
482
  };
413
483
  var opDiv = (node, context, evaluate2) => {
414
- const [a, b] = requireNumbers(node.$div, context, evaluate2, "$div");
415
- if (b === 0) throw new PrismError("Division by zero", ErrorCode.DIVISION_BY_ZERO, { op: "$div" });
484
+ const [a, b] = requireNumbers(node, node.$div, context, evaluate2, "$div");
485
+ if (b === 0) return refuseZero(node, "$div");
416
486
  return a / b;
417
487
  };
418
488
  var opMod = (node, context, evaluate2) => {
419
- const [a, b] = requireNumbers(node.$mod, context, evaluate2, "$mod");
420
- if (b === 0) throw new PrismError("Division by zero", ErrorCode.DIVISION_BY_ZERO, { op: "$mod" });
489
+ const [a, b] = requireNumbers(node, node.$mod, context, evaluate2, "$mod");
490
+ if (b === 0) return refuseZero(node, "$mod");
421
491
  const remainder = a % b;
422
492
  if (remainder === 0) return 0;
423
493
  return remainder < 0 !== b < 0 ? remainder + b : remainder;
@@ -425,19 +495,12 @@ var opMod = (node, context, evaluate2) => {
425
495
  var ROUNDING = { nearest: Math.round, floor: Math.floor, ceil: Math.ceil };
426
496
  var opRound = (node, context, evaluate2) => {
427
497
  const value = evaluate2(node.$round.value, context);
428
- if (typeof value !== "number")
429
- throw new PrismError("Expected number for $round", ErrorCode.TYPE, { op: "$round" });
498
+ if (typeof value !== "number") return refuseType({ node, op: "$round", field: "value", needs: "a number", got: value, written: node.$round.value });
430
499
  const digits = node.$round.digits ?? 0;
431
500
  const factor = Math.pow(10, digits);
432
501
  return ROUNDING[node.$round.mode ?? "nearest"](value * factor) / factor;
433
502
  };
434
503
  var NUMERIC_TEXT = /^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/;
435
- var whatIs = (value) => {
436
- if (typeof value === "string") return JSON.stringify(value.slice(0, 40));
437
- if (value === null) return "null";
438
- if (Array.isArray(value)) return "a list";
439
- return typeof value === "object" ? "an object" : String(value);
440
- };
441
504
  var opToNumber = (node, context, evaluate2) => {
442
505
  const value = evaluate2(node.$toNumber.value, context);
443
506
  if (typeof value === "number") return value;
@@ -447,14 +510,22 @@ var opToNumber = (node, context, evaluate2) => {
447
510
  if (Number.isFinite(parsed)) return parsed;
448
511
  }
449
512
  if (node.$toNumber.fallback !== void 0) return evaluate2(node.$toNumber.fallback, context);
450
- throw new PrismError(`Expected a number or numeric text for $toNumber, got ${whatIs(value)}`, ErrorCode.TYPE, { op: "$toNumber" });
513
+ return refuseType({ node, op: "$toNumber", field: "value", needs: "a number or numeric text", got: value, written: node.$toNumber.value, contextOp: "$toNumber" });
451
514
  };
452
515
 
453
516
  // src/ops/string.ops.ts
454
517
  var opJoin = (node, context, evaluate2) => {
455
518
  const { parts, sep = "" } = node.$join;
456
519
  const list = evaluate2(parts, context);
457
- if (!Array.isArray(list)) throw new PrismError("Expected $join.parts to evaluate to an array", ErrorCode.TYPE, { op: "$join" });
520
+ if (!Array.isArray(list)) return refuseType({ node, op: "$join", field: "parts", needs: "a list", got: list, written: parts });
521
+ const wrong = list.findIndex((part) => !isTextLike(part));
522
+ if (wrong !== -1)
523
+ return failAt(
524
+ `$join.parts needs items that are ${TEXT_LIKE}, but item ${wrong} is ${describeValue(list[wrong])}.${Array.isArray(parts) ? writtenNote(parts[wrong]) : ""}`,
525
+ ErrorCode.TYPE,
526
+ { op: "$join" },
527
+ { node, op: "$join", field: "parts", form: true }
528
+ );
458
529
  return list.map((p) => String(p ?? "")).join(sep);
459
530
  };
460
531
  var opToString = (node, context, evaluate2) => {
@@ -466,12 +537,18 @@ var opToString = (node, context, evaluate2) => {
466
537
  var opInterpolate = (node, context, evaluate2) => {
467
538
  const { template, values: valuesNode } = node.$interpolate;
468
539
  const values = evaluate2(valuesNode, context);
469
- if (!isJsonObject(values))
470
- throw new PrismError("Expected object for $interpolate.values", ErrorCode.TYPE, { op: "$interpolate" });
471
- return template.replace(
472
- /\{\{(\w+)\}\}/g,
473
- (_match, key) => String(values[key] ?? "")
474
- );
540
+ if (!isJsonObject(values)) return refuseType({ node, op: "$interpolate", field: "values", needs: "an object", got: values, written: valuesNode });
541
+ return template.replace(/\{\{(\w+)\}\}/g, (_match, key) => {
542
+ const value = values[key] ?? "";
543
+ if (!isTextLike(value))
544
+ return failAt(
545
+ `$interpolate.values needs ${TEXT_LIKE} for {{${key}}}, but "${key}" is ${describeValue(value)}.`,
546
+ ErrorCode.TYPE,
547
+ { op: "$interpolate" },
548
+ { node, op: "$interpolate", field: "values", form: true }
549
+ );
550
+ return String(value);
551
+ });
475
552
  };
476
553
  var fillOne = (value) => {
477
554
  if (value === null || typeof value !== "object" || Array.isArray(value)) return value;
@@ -487,32 +564,27 @@ var fillOne = (value) => {
487
564
  var opFill = (node, context, evaluate2) => fillOne(evaluate2(node.$fill, context));
488
565
  var opTrim = (node, context, evaluate2) => {
489
566
  const value = evaluate2(node.$trim, context);
490
- if (typeof value !== "string")
491
- throw new PrismError("Expected string for $trim", ErrorCode.TYPE, { op: "$trim" });
567
+ if (typeof value !== "string") return refuseType({ node, op: "$trim", needs: "text", got: value, written: node.$trim });
492
568
  return value.trim();
493
569
  };
494
570
  var opLower = (node, context, evaluate2) => {
495
571
  const value = evaluate2(node.$lower, context);
496
- if (typeof value !== "string")
497
- throw new PrismError("Expected string for $lower", ErrorCode.TYPE, { op: "$lower" });
572
+ if (typeof value !== "string") return refuseType({ node, op: "$lower", needs: "text", got: value, written: node.$lower });
498
573
  return value.toLowerCase();
499
574
  };
500
575
  var opUpper = (node, context, evaluate2) => {
501
576
  const value = evaluate2(node.$upper, context);
502
- if (typeof value !== "string")
503
- throw new PrismError("Expected string for $upper", ErrorCode.TYPE, { op: "$upper" });
577
+ if (typeof value !== "string") return refuseType({ node, op: "$upper", needs: "text", got: value, written: node.$upper });
504
578
  return value.toUpperCase();
505
579
  };
506
580
  var opSplit = (node, context, evaluate2) => {
507
581
  const value = evaluate2(node.$split.value, context);
508
- if (typeof value !== "string")
509
- throw new PrismError("Expected string for $split", ErrorCode.TYPE, { op: "$split" });
582
+ if (typeof value !== "string") return refuseType({ node, op: "$split", field: "value", needs: "text", got: value, written: node.$split.value });
510
583
  return value.split(node.$split.sep);
511
584
  };
512
585
  var opReplace = (node, context, evaluate2) => {
513
586
  const value = evaluate2(node.$replace.value, context);
514
- if (typeof value !== "string")
515
- throw new PrismError("Expected string for $replace", ErrorCode.TYPE, { op: "$replace" });
587
+ if (typeof value !== "string") return refuseType({ node, op: "$replace", field: "value", needs: "text", got: value, written: node.$replace.value });
516
588
  const { search, replacement, all } = node.$replace;
517
589
  return all === true ? value.replaceAll(search, replacement) : value.replace(search, replacement);
518
590
  };
@@ -528,18 +600,25 @@ var opNeq = (node, context, evaluate2) => {
528
600
  const b = evaluate2(node.$neq[1], context);
529
601
  return !jsonEqual(a, b);
530
602
  };
531
- var compareOp = (pair, context, evaluate2, op, test) => {
603
+ var compareOp = (node, pair, context, evaluate2, op, test) => {
532
604
  const a = evaluate2(pair[0], context);
533
605
  const b = evaluate2(pair[1], context);
534
606
  const cmp = compare(a, b);
535
- if (cmp === void 0)
536
- throw new PrismError(`Cannot compare values for ${op}`, ErrorCode.TYPE, { op });
607
+ if (cmp === void 0) {
608
+ const wrong = typeof a === "number" || typeof a === "string" ? 1 : 0;
609
+ return failAt(
610
+ `${op} needs two numbers or two texts, but got ${describeValue(a)} and ${describeValue(b)}.${writtenNote(pair[wrong])}`,
611
+ ErrorCode.TYPE,
612
+ { op },
613
+ { node, op, field: String(wrong), form: true }
614
+ );
615
+ }
537
616
  return test(cmp);
538
617
  };
539
- var opGt = (node, ctx, ev) => compareOp(node.$gt, ctx, ev, "$gt", (c) => c > 0);
540
- var opGte = (node, ctx, ev) => compareOp(node.$gte, ctx, ev, "$gte", (c) => c >= 0);
541
- var opLt = (node, ctx, ev) => compareOp(node.$lt, ctx, ev, "$lt", (c) => c < 0);
542
- var opLte = (node, ctx, ev) => compareOp(node.$lte, ctx, ev, "$lte", (c) => c <= 0);
618
+ var opGt = (node, ctx, ev) => compareOp(node, node.$gt, ctx, ev, "$gt", (c) => c > 0);
619
+ var opGte = (node, ctx, ev) => compareOp(node, node.$gte, ctx, ev, "$gte", (c) => c >= 0);
620
+ var opLt = (node, ctx, ev) => compareOp(node, node.$lt, ctx, ev, "$lt", (c) => c < 0);
621
+ var opLte = (node, ctx, ev) => compareOp(node, node.$lte, ctx, ev, "$lte", (c) => c <= 0);
543
622
  var opEmpty = (node, context, evaluate2) => {
544
623
  const value = evaluate2(node.$empty, context);
545
624
  if (value === null || value === void 0) return true;
@@ -551,22 +630,22 @@ var opEmpty = (node, context, evaluate2) => {
551
630
  var opStartsWith = (node, context, evaluate2) => {
552
631
  const value = evaluate2(node.$startsWith.value, context);
553
632
  const prefix = evaluate2(node.$startsWith.prefix, context);
554
- if (typeof value !== "string" || typeof prefix !== "string")
555
- throw new PrismError("Expected strings for $startsWith", ErrorCode.TYPE, { op: "$startsWith" });
633
+ if (typeof value !== "string") return refuseType({ node, op: "$startsWith", field: "value", needs: "text", got: value, written: node.$startsWith.value });
634
+ if (typeof prefix !== "string") return refuseType({ node, op: "$startsWith", field: "prefix", needs: "text", got: prefix, written: node.$startsWith.prefix });
556
635
  return value.startsWith(prefix);
557
636
  };
558
637
  var opEndsWith = (node, context, evaluate2) => {
559
638
  const value = evaluate2(node.$endsWith.value, context);
560
639
  const suffix = evaluate2(node.$endsWith.suffix, context);
561
- if (typeof value !== "string" || typeof suffix !== "string")
562
- throw new PrismError("Expected strings for $endsWith", ErrorCode.TYPE, { op: "$endsWith" });
640
+ if (typeof value !== "string") return refuseType({ node, op: "$endsWith", field: "value", needs: "text", got: value, written: node.$endsWith.value });
641
+ if (typeof suffix !== "string") return refuseType({ node, op: "$endsWith", field: "suffix", needs: "text", got: suffix, written: node.$endsWith.suffix });
563
642
  return value.endsWith(suffix);
564
643
  };
565
644
  var opContains = (node, context, evaluate2) => {
566
645
  const value = evaluate2(node.$contains.value, context);
567
646
  const search = evaluate2(node.$contains.search, context);
568
- if (typeof value !== "string" || typeof search !== "string")
569
- throw new PrismError("Expected strings for $contains", ErrorCode.TYPE, { op: "$contains" });
647
+ if (typeof value !== "string") return refuseType({ node, op: "$contains", field: "value", needs: "text", got: value, written: node.$contains.value });
648
+ if (typeof search !== "string") return refuseType({ node, op: "$contains", field: "search", needs: "text", got: search, written: node.$contains.search });
570
649
  return value.includes(search);
571
650
  };
572
651
 
@@ -592,10 +671,10 @@ var opOr = (node, context, evaluate2) => {
592
671
  // src/ops/structure.ops.ts
593
672
  var opMerge = (node, context, evaluate2) => {
594
673
  const result = {};
595
- for (const part of node.$merge) {
674
+ for (let index = 0; index < node.$merge.length; index++) {
675
+ const part = node.$merge[index];
596
676
  const evaluated = evaluate2(part, context);
597
- if (!isJsonObject(evaluated))
598
- throw new PrismError("Expected object for $merge element", ErrorCode.TYPE, { op: "$merge" });
677
+ if (!isJsonObject(evaluated)) return refuseType({ node, op: "$merge", field: String(index), needs: "an object", got: evaluated, written: part, contextOp: "$merge" });
599
678
  Object.assign(result, evaluated);
600
679
  }
601
680
  return result;
@@ -617,20 +696,19 @@ var opCase = (node, context, evaluate2) => {
617
696
  };
618
697
  var opEntriesOf = (node, context, evaluate2) => {
619
698
  const value = evaluate2(node.$entriesOf, context);
620
- if (!isJsonObject(value))
621
- throw new PrismError("Expected object for $entriesOf", ErrorCode.TYPE, { op: "$entriesOf" });
699
+ if (!isJsonObject(value)) return refuseType({ node, op: "$entriesOf", needs: "an object", got: value, written: node.$entriesOf });
622
700
  return Object.entries(value).map(([k, v]) => [k, v]);
623
701
  };
624
702
  var opKeyBy = (node, context, evaluate2) => {
625
703
  const { over, as, key: keyExpr } = node.$keyBy;
626
704
  const input = evaluate2(over, context);
627
- if (!isJsonArray(input))
628
- throw new PrismError("Expected array for $keyBy.over", ErrorCode.TYPE, { op: "$keyBy" });
705
+ if (!isJsonArray(input)) return refuseType({ node, op: "$keyBy", field: "over", needs: "a list", got: input, written: over, contextOp: "$keyBy" });
629
706
  const result = {};
630
707
  const { scope, vars } = loopScope(context);
631
708
  for (const item of input) {
632
709
  vars[as] = item;
633
710
  const key = evaluate2(keyExpr, scope);
711
+ if (!isTextLike(key)) return refuseType({ node, op: "$keyBy", field: "key", needs: TEXT_LIKE, got: key, written: keyExpr, contextOp: "$keyBy" });
634
712
  result[String(key)] = item;
635
713
  }
636
714
  return result;
@@ -638,13 +716,14 @@ var opKeyBy = (node, context, evaluate2) => {
638
716
  var opGroupBy = (node, context, evaluate2) => {
639
717
  const { over, as, key: keyExpr } = node.$groupBy;
640
718
  const input = evaluate2(over, context);
641
- if (!isJsonArray(input))
642
- throw new PrismError("Expected array for $groupBy.over", ErrorCode.TYPE, { op: "$groupBy" });
719
+ if (!isJsonArray(input)) return refuseType({ node, op: "$groupBy", field: "over", needs: "a list", got: input, written: over, contextOp: "$groupBy" });
643
720
  const result = {};
644
721
  const { scope, vars } = loopScope(context);
645
722
  for (const item of input) {
646
723
  vars[as] = item;
647
- const key = String(evaluate2(keyExpr, scope));
724
+ const value = evaluate2(keyExpr, scope);
725
+ if (!isTextLike(value)) return refuseType({ node, op: "$groupBy", field: "key", needs: TEXT_LIKE, got: value, written: keyExpr, contextOp: "$groupBy" });
726
+ const key = String(value);
648
727
  if (!result[key]) result[key] = [];
649
728
  result[key].push(item);
650
729
  }
@@ -654,32 +733,29 @@ var opGroupBy = (node, context, evaluate2) => {
654
733
  // src/ops/object.ops.ts
655
734
  var opKeys = (node, context, evaluate2) => {
656
735
  const value = evaluate2(node.$keys, context);
657
- if (!isJsonObject(value))
658
- throw new PrismError("Expected object for $keys", ErrorCode.TYPE, { op: "$keys" });
736
+ if (!isJsonObject(value)) return refuseType({ node, op: "$keys", needs: "an object", got: value, written: node.$keys });
659
737
  return Object.keys(value);
660
738
  };
661
739
  var opValues = (node, context, evaluate2) => {
662
740
  const value = evaluate2(node.$values, context);
663
- if (!isJsonObject(value))
664
- throw new PrismError("Expected object for $values", ErrorCode.TYPE, { op: "$values" });
741
+ if (!isJsonObject(value)) return refuseType({ node, op: "$values", needs: "an object", got: value, written: node.$values });
665
742
  return Object.values(value);
666
743
  };
667
744
  var opFromEntries = (node, context, evaluate2) => {
668
745
  const value = evaluate2(node.$fromEntries, context);
669
- if (!isJsonArray(value))
670
- throw new PrismError("Expected array for $fromEntries", ErrorCode.TYPE, { op: "$fromEntries" });
746
+ if (!isJsonArray(value)) return refuseType({ node, op: "$fromEntries", needs: "a list of [key, value] pairs", got: value, written: node.$fromEntries });
671
747
  const result = {};
672
- for (const entry of value) {
748
+ for (let index = 0; index < value.length; index++) {
749
+ const entry = value[index];
673
750
  if (!isJsonArray(entry) || entry.length < 2)
674
- throw new PrismError("Expected [key, value] pairs for $fromEntries", ErrorCode.TYPE, { op: "$fromEntries" });
751
+ return failAt(`$fromEntries needs a list of [key, value] pairs, but item ${index} is ${describeValue(entry)}.`, ErrorCode.TYPE, { op: "$fromEntries" }, { node, op: "$fromEntries", form: true });
675
752
  result[String(entry[0])] = entry[1];
676
753
  }
677
754
  return result;
678
755
  };
679
756
  var opPick = (node, context, evaluate2) => {
680
757
  const value = evaluate2(node.$pick.from, context);
681
- if (!isJsonObject(value))
682
- throw new PrismError("Expected object for $pick", ErrorCode.TYPE, { op: "$pick" });
758
+ if (!isJsonObject(value)) return refuseType({ node, op: "$pick", field: "from", needs: "an object", got: value, written: node.$pick.from, contextOp: "$pick" });
683
759
  const result = {};
684
760
  for (const key of node.$pick.keys) {
685
761
  if (key in value) result[key] = value[key];
@@ -688,8 +764,7 @@ var opPick = (node, context, evaluate2) => {
688
764
  };
689
765
  var opOmit = (node, context, evaluate2) => {
690
766
  const value = evaluate2(node.$omit.from, context);
691
- if (!isJsonObject(value))
692
- throw new PrismError("Expected object for $omit", ErrorCode.TYPE, { op: "$omit" });
767
+ if (!isJsonObject(value)) return refuseType({ node, op: "$omit", field: "from", needs: "an object", got: value, written: node.$omit.from, contextOp: "$omit" });
693
768
  const keysToOmit = new Set(node.$omit.keys);
694
769
  const result = {};
695
770
  for (const [k, v] of Object.entries(value)) {
@@ -707,7 +782,7 @@ var opLength = (node, context, evaluate2) => {
707
782
  const value = evaluate2(node.$length, context);
708
783
  if (typeof value === "string") return value.length;
709
784
  if (isJsonArray(value)) return value.length;
710
- throw new PrismError("Expected array or string for $length", ErrorCode.TYPE, { op: "$length" });
785
+ return refuseType({ node, op: "$length", needs: "a list or text", got: value, written: node.$length });
711
786
  };
712
787
 
713
788
  // src/ops/transform.ops.ts
@@ -727,7 +802,7 @@ var has = (value, path) => {
727
802
  var opHas = (node, context, evaluate2) => has(evaluate2(node.$has.from, context), node.$has.path);
728
803
  var opRenameKeys = (node, context, evaluate2) => {
729
804
  const value = evaluate2(node.$renameKeys.from, context);
730
- if (!isJsonObject(value)) throw new PrismError("Expected object for $renameKeys", ErrorCode.TYPE, { op: "$renameKeys" });
805
+ if (!isJsonObject(value)) return refuseType({ node, op: "$renameKeys", field: "from", needs: "an object", got: value, written: node.$renameKeys.from, contextOp: "$renameKeys" });
731
806
  const { map } = node.$renameKeys;
732
807
  const renamedTo = new Set(Object.entries(map).filter(([from]) => Object.prototype.hasOwnProperty.call(value, from)).map(([, to]) => to));
733
808
  const result = {};
@@ -746,23 +821,23 @@ var current = (value, path) => {
746
821
  }
747
822
  return at;
748
823
  };
749
- var setIn = (value, path, next, full) => {
824
+ var setIn = (value, path, next, full, node) => {
750
825
  const [head, ...rest] = path;
751
826
  if (head === void 0) return next;
752
827
  if (typeof head === "number") {
753
828
  if (!isJsonArray(value) || head >= value.length) {
754
- throw new PrismError(`No array item at ${full.join(".")}`, ErrorCode.MISSING_PATH, { op: "$update", path: full.join(".") });
829
+ return failAt(`No array item at ${full.join(".")}: the value there is ${describeValue(value)}.`, ErrorCode.MISSING_PATH, { op: "$update", path: full.join(".") }, { node, op: "$update", field: "path", form: false });
755
830
  }
756
- return value.map((item, i) => i === head ? setIn(item, rest, next, full) : item);
831
+ return value.map((item, i) => i === head ? setIn(item, rest, next, full, node) : item);
757
832
  }
758
833
  const base = isJsonObject(value) ? value : {};
759
- return { ...base, [head]: setIn(base[head] ?? null, rest, next, full) };
834
+ return { ...base, [head]: setIn(base[head] ?? null, rest, next, full, node) };
760
835
  };
761
836
  var opUpdate = (node, context, evaluate2) => {
762
837
  const { from, path, value, as } = node.$update;
763
838
  const source = evaluate2(from, context);
764
839
  const next = evaluate2(value, { ...context, vars: { ...context.vars, [as ?? "current"]: current(source, path) } });
765
- return setIn(source, path, next, path);
840
+ return setIn(source, path, next, path, node);
766
841
  };
767
842
  var opAssert = (node, context, evaluate2) => {
768
843
  if (!evaluate2(node.$assert.when, context)) throw new PrismError(node.$assert.message, ErrorCode.ASSERT, { op: "$assert" });
@@ -789,32 +864,32 @@ var opWalk = (node, context, evaluate2) => {
789
864
  dayjs.extend(utc);
790
865
  var DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
791
866
  var isDateOnly = (value) => typeof value === "string" && DATE_ONLY.test(value);
792
- var parseDate = (value, op) => {
867
+ var parseDate = (value, node, op, field, written, contextOp) => {
793
868
  if (typeof value !== "string" && typeof value !== "number")
794
- throw new PrismError(`Expected string or number for ${op}`, ErrorCode.TYPE, { op });
869
+ return refuseType({ node, op, field, needs: "a date, as text or a number", got: value, written, contextOp });
795
870
  const d = isDateOnly(value) ? dayjs.utc(value) : dayjs(value);
796
871
  if (!d.isValid())
797
- throw new PrismError(`Invalid date for ${op}: ${String(value)}`, ErrorCode.DATE_INVALID, { op });
872
+ return failAt(`Invalid date for ${contextOp}: ${clip(String(value), 60)}`, ErrorCode.DATE_INVALID, { op: contextOp }, { node, op, field, form: false });
798
873
  return d;
799
874
  };
800
875
  var opDate = (node, context, evaluate2) => {
801
876
  const value = evaluate2(node.$date.value, context);
802
- const d = parseDate(value, "$date");
877
+ const d = parseDate(value, node, "$date", "value", node.$date.value, "$date");
803
878
  const instance = node.$date.utc ? d.utc() : d;
804
879
  if (node.$date.format) return instance.format(node.$date.format);
805
880
  return instance.toISOString();
806
881
  };
807
882
  var opDateAdd = (node, context, evaluate2) => {
808
883
  const value = evaluate2(node.$dateAdd.date, context);
809
- const d = parseDate(value, "$dateAdd");
884
+ const d = parseDate(value, node, "$dateAdd", "date", node.$dateAdd.date, "$dateAdd");
810
885
  const moved = d.add(node.$dateAdd.amount, node.$dateAdd.unit);
811
886
  return isDateOnly(value) ? moved.format("YYYY-MM-DD") : moved.toISOString();
812
887
  };
813
888
  var opDateDiff = (node, context, evaluate2) => {
814
889
  const from = evaluate2(node.$dateDiff.from, context);
815
890
  const to = evaluate2(node.$dateDiff.to, context);
816
- const fromDate = parseDate(from, "$dateDiff.from");
817
- const toDate = parseDate(to, "$dateDiff.to");
891
+ const fromDate = parseDate(from, node, "$dateDiff", "from", node.$dateDiff.from, "$dateDiff.from");
892
+ const toDate = parseDate(to, node, "$dateDiff", "to", node.$dateDiff.to, "$dateDiff.to");
818
893
  return toDate.diff(fromDate, node.$dateDiff.unit);
819
894
  };
820
895
 
@@ -822,9 +897,9 @@ var opDateDiff = (node, context, evaluate2) => {
822
897
  var DATE_FORMATTERS = /* @__PURE__ */ new Map();
823
898
  var NUMBER_FORMATTERS = /* @__PURE__ */ new Map();
824
899
  var DATE_ONLY2 = /^\d{4}-\d{2}-\d{2}$/;
825
- var localeOf = (value, op) => {
900
+ var localeOf = (value, node, op, written) => {
826
901
  if (typeof value !== "string" || value.trim() === "")
827
- throw new PrismError(`${op} needs a locale tag (e.g. "de-AT")`, ErrorCode.TYPE, { op });
902
+ return refuseType({ node, op, field: "locale", needs: 'a locale tag such as "de-AT"', got: value, written, contextOp: op });
828
903
  return value;
829
904
  };
830
905
  var isBlank = (value) => value === null || value === void 0 || value === "";
@@ -833,16 +908,16 @@ var fallbackOf = (raw, context, evaluate2) => {
833
908
  const resolved = evaluate2(raw, context);
834
909
  return resolved === null || resolved === void 0 ? "" : resolved;
835
910
  };
836
- var numberOf = (value, op) => {
911
+ var numberOf = (value, node, op, written) => {
837
912
  const parsed = typeof value === "number" ? value : Number(value);
838
- if (!Number.isFinite(parsed)) throw new PrismError(`${op} expected a number, got ${JSON.stringify(value)}`, ErrorCode.TYPE, { op });
913
+ if (!Number.isFinite(parsed)) return refuseType({ node, op, field: "value", needs: "a number or numeric text", got: value, written, contextOp: op });
839
914
  return parsed;
840
915
  };
841
916
  var opLocaleDate = (node, context, evaluate2) => {
842
917
  const spec = node.$localeDate;
843
918
  const value = evaluate2(spec.value, context);
844
919
  if (isBlank(value)) return fallbackOf(spec.fallback, context, evaluate2);
845
- const locale = localeOf(evaluate2(spec.locale, context), "$localeDate");
920
+ const locale = localeOf(evaluate2(spec.locale, context), node, "$localeDate", spec.locale);
846
921
  const authored = spec.options ?? { dateStyle: "medium" };
847
922
  const dateOnly = typeof value === "string" && DATE_ONLY2.test(value);
848
923
  const options = {
@@ -851,7 +926,7 @@ var opLocaleDate = (node, context, evaluate2) => {
851
926
  };
852
927
  const parsed = typeof value === "number" ? new Date(value) : new Date(String(value));
853
928
  if (Number.isNaN(parsed.getTime()))
854
- throw new PrismError(`Invalid date for $localeDate: ${String(value)}`, ErrorCode.DATE_INVALID, { op: "$localeDate" });
929
+ return failAt(`Invalid date for $localeDate: ${clip(String(value), 60)}`, ErrorCode.DATE_INVALID, { op: "$localeDate" }, { node, op: "$localeDate", field: "value", form: false });
855
930
  const key = `${locale}\0${JSON.stringify(options)}`;
856
931
  let formatter = DATE_FORMATTERS.get(key);
857
932
  if (formatter === void 0) {
@@ -877,12 +952,12 @@ var opLocaleMoney = (node, context, evaluate2) => {
877
952
  const spec = node.$localeMoney;
878
953
  const value = evaluate2(spec.value, context);
879
954
  if (isBlank(value)) return fallbackOf(spec.fallback, context, evaluate2);
880
- const locale = localeOf(evaluate2(spec.locale, context), "$localeMoney");
955
+ const locale = localeOf(evaluate2(spec.locale, context), node, "$localeMoney", spec.locale);
881
956
  const rawCurrency = evaluate2(spec.currency, context);
882
957
  if (typeof rawCurrency !== "string" || rawCurrency.trim() === "")
883
- throw new PrismError("$localeMoney needs an ISO-4217 currency code", ErrorCode.TYPE, { op: "$localeMoney" });
958
+ return refuseType({ node, op: "$localeMoney", field: "currency", needs: 'an ISO-4217 currency code such as "EUR"', got: rawCurrency, written: spec.currency, contextOp: "$localeMoney" });
884
959
  const currency = rawCurrency.toUpperCase();
885
- const amount = numberOf(value, "$localeMoney");
960
+ const amount = numberOf(value, node, "$localeMoney", spec.value);
886
961
  const major = spec.minorUnits === false ? amount : amount / minorUnitDivisor(locale, currency);
887
962
  const options = {
888
963
  style: "currency",
@@ -905,7 +980,7 @@ var opLocaleNumber = (node, context, evaluate2) => {
905
980
  const spec = node.$localeNumber;
906
981
  const value = evaluate2(spec.value, context);
907
982
  if (isBlank(value)) return fallbackOf(spec.fallback, context, evaluate2);
908
- const locale = localeOf(evaluate2(spec.locale, context), "$localeNumber");
983
+ const locale = localeOf(evaluate2(spec.locale, context), node, "$localeNumber", spec.locale);
909
984
  const options = {
910
985
  style: spec.style ?? "decimal",
911
986
  ...spec.digits === void 0 ? {} : { maximumFractionDigits: spec.digits },
@@ -918,7 +993,7 @@ var opLocaleNumber = (node, context, evaluate2) => {
918
993
  formatter = new Intl.NumberFormat(locale, options);
919
994
  NUMBER_FORMATTERS.set(key, formatter);
920
995
  }
921
- return formatter.format(numberOf(value, "$localeNumber"));
996
+ return formatter.format(numberOf(value, node, "$localeNumber", spec.value));
922
997
  };
923
998
 
924
999
  // src/engine/optimize.ts
@@ -1107,15 +1182,88 @@ var annotateNode = (node) => {
1107
1182
  };
1108
1183
  var rehydrate = (core) => annotateNode(core);
1109
1184
 
1185
+ // src/engine/place.ts
1186
+ var findPath = (tree, matches) => {
1187
+ const at = [];
1188
+ const walk2 = (value) => {
1189
+ if (matches(value)) return true;
1190
+ if (value === null || typeof value !== "object") return false;
1191
+ for (const [key, child] of Object.entries(value)) {
1192
+ at.push(key);
1193
+ if (walk2(child)) return true;
1194
+ at.pop();
1195
+ }
1196
+ return false;
1197
+ };
1198
+ return walk2(tree) ? at : void 0;
1199
+ };
1200
+ var soleOpOf = (node) => {
1201
+ if (!isJsonObject(node)) return void 0;
1202
+ const keys = Object.keys(node);
1203
+ return keys.length === 1 && keys[0] !== void 0 && keys[0].startsWith("$") ? keys[0] : void 0;
1204
+ };
1205
+ var MARK = "\0prism-field:";
1206
+ var authorPosition = (authored, treePath) => {
1207
+ const path = [];
1208
+ let node = authored;
1209
+ let rest = treePath;
1210
+ let sugar;
1211
+ while (rest.length > 0) {
1212
+ const [key] = rest;
1213
+ if (key !== void 0 && typeof node === "object" && node !== null && Object.prototype.hasOwnProperty.call(node, key)) {
1214
+ path.push(key);
1215
+ node = Reflect.get(node, key);
1216
+ rest = rest.slice(1);
1217
+ sugar = void 0;
1218
+ continue;
1219
+ }
1220
+ const op = soleOpOf(node);
1221
+ if (op === void 0 || !isJsonObject(node)) return void 0;
1222
+ const fields = node[op];
1223
+ const names = isJsonObject(fields) ? Object.keys(fields) : [];
1224
+ const rewritten = desugar({ [op]: Object.fromEntries(names.map((name) => [name, `${MARK}${name}`])) });
1225
+ const landed = names.map((name) => ({ name, at: findPath(rewritten, (value) => value === `${MARK}${name}`) })).find(({ at }) => at !== void 0 && at.every((segment, i) => rest[i] === segment));
1226
+ if (landed?.at === void 0 || !isJsonObject(fields)) return { path: [...path, op], sugar: op };
1227
+ path.push(op, landed.name);
1228
+ node = fields[landed.name];
1229
+ rest = rest.slice(landed.at.length);
1230
+ sugar = op;
1231
+ }
1232
+ return sugar === void 0 ? { path } : { path, sugar };
1233
+ };
1234
+ var pathText = (path) => path.length === 0 ? "(root)" : path.join(".");
1235
+ var placeError = (error, tree, authored) => {
1236
+ if (!(error instanceof PrismError)) return;
1237
+ const origin = takeOrigin(error);
1238
+ if (origin === void 0) return;
1239
+ const parts = [error.message];
1240
+ if (origin.detail !== void 0) parts.push(origin.detail());
1241
+ const tail = [origin.op, origin.field].filter((part) => part !== void 0);
1242
+ let formOp = origin.op;
1243
+ const nodePath = findPath(tree, (value) => value === origin.node);
1244
+ if (nodePath !== void 0) {
1245
+ const treePath = [...nodePath, ...tail];
1246
+ const position = authored === void 0 ? { path: treePath } : authorPosition(authored, treePath) ?? { path: treePath };
1247
+ if (position.sugar === void 0) parts.push(`At ${pathText(position.path)}.`);
1248
+ else {
1249
+ parts.push(`At ${pathText(position.path)}, in the ${origin.op ?? "node"} that ${position.sugar} runs as.`);
1250
+ formOp = position.sugar;
1251
+ }
1252
+ }
1253
+ const form = origin.form && formOp !== void 0 ? formOf(formOp) : void 0;
1254
+ if (form !== void 0) parts.push(`Form: ${form}`);
1255
+ error.message = parts.join(" ");
1256
+ };
1257
+
1110
1258
  // src/engine/evaluate.ts
1111
1259
  var HANDLER_KEY2 = "__op";
1112
1260
  var isAttachedFn = (value) => typeof value === "function";
1113
1261
  var evaluateNode = (node, context) => {
1114
1262
  const { budget } = context;
1115
1263
  if (budget === void 0) return evaluateUnbudgeted(node, context);
1116
- spendStep(budget);
1264
+ spendStep(budget, node);
1117
1265
  const out = evaluateUnbudgeted(node, context);
1118
- measureString(out, budget);
1266
+ measureString(out, budget, node);
1119
1267
  return out;
1120
1268
  };
1121
1269
  var evaluateUnbudgeted = (node, context) => {
@@ -1215,41 +1363,66 @@ var evaluateUnbudgeted = (node, context) => {
1215
1363
  if (isLocaleMoneyNode(obj)) return opLocaleMoney(obj, context, evaluateNode);
1216
1364
  if (isLocaleNumberNode(obj)) return opLocaleNumber(obj, context, evaluateNode);
1217
1365
  const unknownKeys = Object.keys(obj).filter((k) => k.startsWith("$"));
1218
- throw new PrismError("Unsupported node shape", ErrorCode.NODE_SHAPE, {
1219
- details: { keys: unknownKeys, preview: JSON.stringify(obj).slice(0, 100) }
1220
- });
1366
+ const preview = JSON.stringify(obj).slice(0, 100);
1367
+ return failAt(
1368
+ `No op answers this node: ${clip(JSON.stringify(obj), 100)} (keys: ${unknownKeys.join(", ")}). The tree did not go through the schema.`,
1369
+ ErrorCode.NODE_SHAPE,
1370
+ { details: { keys: unknownKeys, preview } },
1371
+ { node: obj, form: false }
1372
+ );
1221
1373
  };
1222
- var isJsonValue = (value) => {
1223
- if (value === null || typeof value === "string" || typeof value === "boolean") return true;
1224
- if (typeof value === "number") return Number.isFinite(value);
1225
- if (Array.isArray(value)) return value.every(isJsonValue);
1226
- if (typeof value !== "object") return false;
1374
+ var notJson = (value, at) => {
1375
+ if (value === null || typeof value === "string" || typeof value === "boolean") return void 0;
1376
+ if (typeof value === "number") return Number.isFinite(value) ? void 0 : `${at} is ${value}`;
1377
+ if (Array.isArray(value)) {
1378
+ for (const index of Object.keys(value)) {
1379
+ const found = notJson(value[Number(index)], `${at}[${index}]`);
1380
+ if (found !== void 0) return found;
1381
+ }
1382
+ return void 0;
1383
+ }
1384
+ if (typeof value !== "object") return `${at} is ${value === void 0 ? "undefined" : `a ${typeof value}`}`;
1227
1385
  const proto = Object.getPrototypeOf(value);
1228
- return (proto === Object.prototype || proto === null) && Object.values(value).every(isJsonValue);
1386
+ if (proto !== Object.prototype && proto !== null) {
1387
+ const tag = Object.prototype.toString.call(value).slice(8, -1);
1388
+ return `${at} is ${tag === "Object" ? "an instance of a class" : `a ${tag}`}`;
1389
+ }
1390
+ for (const [key, inner] of Object.entries(value)) {
1391
+ const found = notJson(inner, `${at}.${key}`);
1392
+ if (found !== void 0) return found;
1393
+ }
1394
+ return void 0;
1229
1395
  };
1230
1396
  var checked = (config) => {
1231
- if (exceedsDepth(config)) throw new PrismError("Invalid config", ErrorCode.SCHEMA, { details: { issues: [{ path: "root", message: depthRefusal() }] } });
1397
+ if (exceedsDepth(config)) throw new PrismError(`Invalid config: ${depthRefusal()}`, ErrorCode.SCHEMA, { details: { issues: [{ path: "root", message: depthRefusal() }] } });
1232
1398
  const parsed = ConfigSchema.safeParse(config);
1233
1399
  if (!parsed.success) {
1234
- const issues = explainIssues(parsed.error.issues).map((i) => ({ path: i.path.join(".") || "root", message: i.message }));
1235
- throw new PrismError("Invalid config", ErrorCode.SCHEMA, { details: { issues } });
1400
+ const explained = explainIssues(parsed.error.issues, config);
1401
+ const issues = explained.map((i) => ({ path: i.path.join(".") || "root", message: i.message }));
1402
+ throw new PrismError(`Invalid config: ${issuesText(explained)}`, ErrorCode.SCHEMA, { details: { issues } });
1236
1403
  }
1237
1404
  return desugar(parsed.data);
1238
1405
  };
1239
- var run = (tree, source, limits, kept) => {
1406
+ var run = (tree, source, limits, kept, authored) => {
1240
1407
  const budget = createBudget(limits);
1241
- const result = evaluateNode(tree, kept ? { source, vars: {}, budget, kept } : { source, vars: {}, budget });
1242
- measure(result, budget);
1243
- return result;
1408
+ try {
1409
+ const result = evaluateNode(tree, kept ? { source, vars: {}, budget, kept } : { source, vars: {}, budget });
1410
+ measure(result, budget);
1411
+ return result;
1412
+ } catch (error) {
1413
+ placeError(error, tree, authored);
1414
+ throw error;
1415
+ }
1244
1416
  };
1245
1417
  var keptTrees = /* @__PURE__ */ new WeakMap();
1246
1418
  var evaluate = (config, source, options) => {
1247
1419
  if (options?.check === "always") {
1248
- if (!isJsonValue(source)) throw new PrismError("The source must be plain JSON.", ErrorCode.TYPE);
1249
- return run(checked(config), source, options.limits, false);
1420
+ const wrong = notJson(source, "source");
1421
+ if (wrong !== void 0) throw new PrismError(`The source must be plain JSON: ${wrong}.`, ErrorCode.TYPE);
1422
+ return run(checked(config), source, options.limits, false, config);
1250
1423
  }
1251
1424
  const input = source;
1252
- if (typeof config !== "object" || config === null) return run(checked(config), input, options?.limits, false);
1425
+ if (typeof config !== "object" || config === null) return run(checked(config), input, options?.limits, false, config);
1253
1426
  let kept = keptTrees.get(config);
1254
1427
  if (kept === void 0) {
1255
1428
  kept = { tree: checked(config), optimized: false };
@@ -1258,7 +1431,7 @@ var evaluate = (config, source, options) => {
1258
1431
  kept.tree = optimize(kept.tree, evaluateNode).node;
1259
1432
  kept.optimized = true;
1260
1433
  }
1261
- return run(kept.tree, input, options?.limits, true);
1434
+ return run(kept.tree, input, options?.limits, true, config);
1262
1435
  };
1263
1436
  var evaluateSafe = (config, source, options) => {
1264
1437
  try {
@@ -1303,8 +1476,7 @@ var compile = async (config, options) => {
1303
1476
  if (exceedsDepth(config)) throw new PrismError(`Invalid config: ${depthRefusal()}`, ErrorCode.SCHEMA);
1304
1477
  const parsed = ConfigSchema.safeParse(config);
1305
1478
  if (!parsed.success) {
1306
- const issues = explainIssues(parsed.error.issues).map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ");
1307
- throw new PrismError(`Invalid config: ${issues}`, ErrorCode.SCHEMA);
1479
+ throw new PrismError(`Invalid config: ${issuesText(explainIssues(parsed.error.issues, config))}`, ErrorCode.SCHEMA);
1308
1480
  }
1309
1481
  const desugared = desugar(parsed.data);
1310
1482
  const { node: core, stats: optimizations } = optimize(desugared, evaluateNode);
@@ -1351,9 +1523,14 @@ var execute = (ir, source, limits) => {
1351
1523
  hydrated.add(core);
1352
1524
  }
1353
1525
  const budget = createBudget(limits);
1354
- const result = evaluateNode(core, { source, vars: {}, budget });
1355
- measure(result, budget);
1356
- return result;
1526
+ try {
1527
+ const result = evaluateNode(core, { source, vars: {}, budget });
1528
+ measure(result, budget);
1529
+ return result;
1530
+ } catch (error) {
1531
+ placeError(error, core);
1532
+ throw error;
1533
+ }
1357
1534
  };
1358
1535
  var validate = (config) => {
1359
1536
  if (exceedsDepth(config)) return { ok: false, issues: [{ path: [], message: depthRefusal() }] };
@@ -1361,7 +1538,7 @@ var validate = (config) => {
1361
1538
  if (!parsed.success) {
1362
1539
  return {
1363
1540
  ok: false,
1364
- issues: explainIssues(parsed.error.issues)
1541
+ issues: explainIssues(parsed.error.issues, config)
1365
1542
  };
1366
1543
  }
1367
1544
  return { ok: true, data: parsed.data };