@niscorp/vex 0.2.0 → 0.2.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.
Files changed (37) hide show
  1. package/CHANGELOG.md +161 -0
  2. package/DESIGN.md +78 -3
  3. package/DOCS.md +167 -14
  4. package/README.md +2 -1
  5. package/dist/adapters/express/index.cjs +241 -19
  6. package/dist/adapters/express/index.cjs.map +1 -1
  7. package/dist/adapters/express/index.d.cts +2 -2
  8. package/dist/adapters/express/index.d.ts +2 -2
  9. package/dist/adapters/express/index.js +2 -2
  10. package/dist/adapters/hono/index.cjs +260 -24
  11. package/dist/adapters/hono/index.cjs.map +1 -1
  12. package/dist/adapters/hono/index.d.cts +2 -2
  13. package/dist/adapters/hono/index.d.ts +2 -2
  14. package/dist/adapters/hono/index.js +21 -7
  15. package/dist/adapters/hono/index.js.map +1 -1
  16. package/dist/agent/index.cjs +2 -0
  17. package/dist/agent/index.cjs.map +1 -1
  18. package/dist/agent/index.d.cts +1 -1
  19. package/dist/agent/index.d.ts +1 -1
  20. package/dist/agent/index.js +1 -1
  21. package/dist/{chunk-HF25Q53I.js → chunk-H4BHW76Q.js} +6 -3
  22. package/dist/chunk-H4BHW76Q.js.map +1 -0
  23. package/dist/{chunk-5CBKESBJ.js → chunk-IQM4SQE2.js} +279 -29
  24. package/dist/chunk-IQM4SQE2.js.map +1 -0
  25. package/dist/{handler-Cql8SJ3F.d.cts → handler-BGCL6_Si.d.ts} +3 -2
  26. package/dist/{handler-mICf9ins.d.ts → handler-CMrjTXNx.d.cts} +3 -2
  27. package/dist/index.cjs +320 -57
  28. package/dist/index.cjs.map +1 -1
  29. package/dist/index.d.cts +3 -3
  30. package/dist/index.d.ts +3 -3
  31. package/dist/index.js +45 -37
  32. package/dist/index.js.map +1 -1
  33. package/dist/{types-BRvMB6IM.d.cts → types-Bi-Lg86b.d.cts} +48 -2
  34. package/dist/{types-BRvMB6IM.d.ts → types-Bi-Lg86b.d.ts} +48 -2
  35. package/package.json +9 -8
  36. package/dist/chunk-5CBKESBJ.js.map +0 -1
  37. package/dist/chunk-HF25Q53I.js.map +0 -1
package/dist/index.cjs CHANGED
@@ -1,7 +1,6 @@
1
1
  'use strict';
2
2
 
3
3
  var zod = require('zod');
4
- var crypto = require('crypto');
5
4
  var strata = require('@niscorp/strata');
6
5
  var prism = require('@niscorp/prism');
7
6
  var postgres = require('@niscorp/strata/postgres');
@@ -175,6 +174,7 @@ var QuerySchema = zod.z.lazy(
175
174
  );
176
175
 
177
176
  // src/errors.ts
177
+ var VEX_ERROR = /* @__PURE__ */ Symbol.for("@niscorp/vex:VexError");
178
178
  var VexError = class extends Error {
179
179
  code;
180
180
  details;
@@ -185,6 +185,8 @@ var VexError = class extends Error {
185
185
  this.details = details;
186
186
  }
187
187
  };
188
+ Object.defineProperty(VexError.prototype, VEX_ERROR, { value: true });
189
+ var isVexError = (err) => err instanceof VexError || err instanceof Error && Reflect.get(err, VEX_ERROR) === true;
188
190
 
189
191
  // src/engine/optional.ts
190
192
  var gateKeys = (key) => Array.isArray(key) ? key : [key];
@@ -1302,6 +1304,155 @@ var createMemoryCache = () => {
1302
1304
  };
1303
1305
  return { get, set, delete: del, clear, keys, entries };
1304
1306
  };
1307
+
1308
+ // src/utils/sha256.ts
1309
+ var ROUND_CONSTANTS = new Uint32Array([
1310
+ 1116352408,
1311
+ 1899447441,
1312
+ 3049323471,
1313
+ 3921009573,
1314
+ 961987163,
1315
+ 1508970993,
1316
+ 2453635748,
1317
+ 2870763221,
1318
+ 3624381080,
1319
+ 310598401,
1320
+ 607225278,
1321
+ 1426881987,
1322
+ 1925078388,
1323
+ 2162078206,
1324
+ 2614888103,
1325
+ 3248222580,
1326
+ 3835390401,
1327
+ 4022224774,
1328
+ 264347078,
1329
+ 604807628,
1330
+ 770255983,
1331
+ 1249150122,
1332
+ 1555081692,
1333
+ 1996064986,
1334
+ 2554220882,
1335
+ 2821834349,
1336
+ 2952996808,
1337
+ 3210313671,
1338
+ 3336571891,
1339
+ 3584528711,
1340
+ 113926993,
1341
+ 338241895,
1342
+ 666307205,
1343
+ 773529912,
1344
+ 1294757372,
1345
+ 1396182291,
1346
+ 1695183700,
1347
+ 1986661051,
1348
+ 2177026350,
1349
+ 2456956037,
1350
+ 2730485921,
1351
+ 2820302411,
1352
+ 3259730800,
1353
+ 3345764771,
1354
+ 3516065817,
1355
+ 3600352804,
1356
+ 4094571909,
1357
+ 275423344,
1358
+ 430227734,
1359
+ 506948616,
1360
+ 659060556,
1361
+ 883997877,
1362
+ 958139571,
1363
+ 1322822218,
1364
+ 1537002063,
1365
+ 1747873779,
1366
+ 1955562222,
1367
+ 2024104815,
1368
+ 2227730452,
1369
+ 2361852424,
1370
+ 2428436474,
1371
+ 2756734187,
1372
+ 3204031479,
1373
+ 3329325298
1374
+ ]);
1375
+ var BLOCK_BYTES = 64;
1376
+ var rotateRight = (word, bits) => word >>> bits | word << 32 - bits;
1377
+ var wordHex = (word) => (word >>> 0).toString(16).padStart(8, "0");
1378
+ var sha256Hex = (text) => {
1379
+ const bytes = new TextEncoder().encode(text);
1380
+ const padded = new Uint8Array(Math.ceil((bytes.length + 9) / BLOCK_BYTES) * BLOCK_BYTES);
1381
+ padded.set(bytes);
1382
+ padded[bytes.length] = 128;
1383
+ const view = new DataView(padded.buffer);
1384
+ const bitLength = bytes.length * 8;
1385
+ view.setUint32(padded.length - 8, Math.floor(bitLength / 4294967296));
1386
+ view.setUint32(padded.length - 4, bitLength >>> 0);
1387
+ let h0 = 1779033703;
1388
+ let h1 = 3144134277;
1389
+ let h2 = 1013904242;
1390
+ let h3 = 2773480762;
1391
+ let h4 = 1359893119;
1392
+ let h5 = 2600822924;
1393
+ let h6 = 528734635;
1394
+ let h7 = 1541459225;
1395
+ const schedule = new Uint32Array(64);
1396
+ for (let offset = 0; offset < padded.length; offset += BLOCK_BYTES) {
1397
+ for (let i = 0; i < 16; i += 1) schedule[i] = view.getUint32(offset + i * 4);
1398
+ for (let i = 16; i < 64; i += 1) {
1399
+ const w15 = schedule[i - 15] ?? 0;
1400
+ const w2 = schedule[i - 2] ?? 0;
1401
+ const s0 = rotateRight(w15, 7) ^ rotateRight(w15, 18) ^ w15 >>> 3;
1402
+ const s1 = rotateRight(w2, 17) ^ rotateRight(w2, 19) ^ w2 >>> 10;
1403
+ schedule[i] = (schedule[i - 16] ?? 0) + s0 + (schedule[i - 7] ?? 0) + s1;
1404
+ }
1405
+ let a = h0;
1406
+ let b = h1;
1407
+ let c = h2;
1408
+ let d = h3;
1409
+ let e = h4;
1410
+ let f = h5;
1411
+ let g = h6;
1412
+ let h = h7;
1413
+ for (let i = 0; i < 64; i += 1) {
1414
+ const sum1 = rotateRight(e, 6) ^ rotateRight(e, 11) ^ rotateRight(e, 25);
1415
+ const choice = e & f ^ ~e & g;
1416
+ const temp1 = h + sum1 + choice + (ROUND_CONSTANTS[i] ?? 0) + (schedule[i] ?? 0) | 0;
1417
+ const sum0 = rotateRight(a, 2) ^ rotateRight(a, 13) ^ rotateRight(a, 22);
1418
+ const majority = a & b ^ a & c ^ b & c;
1419
+ const temp2 = sum0 + majority | 0;
1420
+ h = g;
1421
+ g = f;
1422
+ f = e;
1423
+ e = d + temp1 | 0;
1424
+ d = c;
1425
+ c = b;
1426
+ b = a;
1427
+ a = temp1 + temp2 | 0;
1428
+ }
1429
+ h0 = h0 + a | 0;
1430
+ h1 = h1 + b | 0;
1431
+ h2 = h2 + c | 0;
1432
+ h3 = h3 + d | 0;
1433
+ h4 = h4 + e | 0;
1434
+ h5 = h5 + f | 0;
1435
+ h6 = h6 + g | 0;
1436
+ h7 = h7 + h | 0;
1437
+ }
1438
+ return wordHex(h0) + wordHex(h1) + wordHex(h2) + wordHex(h3) + wordHex(h4) + wordHex(h5) + wordHex(h6) + wordHex(h7);
1439
+ };
1440
+
1441
+ // src/utils/canonical.ts
1442
+ var canonical = (value) => {
1443
+ if (Array.isArray(value)) return value.map(canonical);
1444
+ if (value !== null && typeof value === "object" && !(value instanceof Date)) {
1445
+ const sorted = {};
1446
+ for (const [key, inner] of Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) sorted[key] = canonical(inner);
1447
+ return sorted;
1448
+ }
1449
+ return value;
1450
+ };
1451
+ var canonicalText = (value) => JSON.stringify(canonical(value)) ?? "undefined";
1452
+ var hashText = (text) => sha256Hex(text);
1453
+ var canonicalHash = (value) => hashText(canonicalText(value));
1454
+
1455
+ // src/cache/hash.ts
1305
1456
  var isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
1306
1457
  var normalizeShape = (shape) => {
1307
1458
  if (shape === null) return "null";
@@ -1323,25 +1474,25 @@ var normalizeShape = (shape) => {
1323
1474
  if (typeof shape === "boolean") return "boolean";
1324
1475
  return "unknown";
1325
1476
  };
1326
- var mintFingerprint = () => `fp_${crypto.createHash("sha256").update(`${Date.now()}:${Math.random()}`).digest("hex").slice(0, 16)}`;
1477
+ var mintFingerprint = () => `fp_${hashText(`${Date.now()}:${Math.random()}`).slice(0, 16)}`;
1327
1478
  var computeRequestHash = (request) => {
1328
1479
  const identity = {
1329
1480
  intent: request.intent ?? null,
1330
1481
  shape: normalizeShape(request.shape),
1331
1482
  contextKeys: Object.keys(request.context ?? {}).sort()
1332
1483
  };
1333
- return crypto.createHash("sha256").update(JSON.stringify(identity)).digest("hex");
1484
+ return hashText(JSON.stringify(identity));
1334
1485
  };
1335
- var canonical = (value) => {
1336
- if (Array.isArray(value)) return value.map(canonical);
1486
+ var canonical2 = (value) => {
1487
+ if (Array.isArray(value)) return value.map(canonical2);
1337
1488
  if (isRecord(value)) {
1338
1489
  const out = {};
1339
- for (const key of Object.keys(value).sort()) out[key] = canonical(value[key]);
1490
+ for (const key of Object.keys(value).sort()) out[key] = canonical2(value[key]);
1340
1491
  return out;
1341
1492
  }
1342
1493
  return value;
1343
1494
  };
1344
- var computePolicyKey = (policy) => policy === void 0 ? "none" : crypto.createHash("sha256").update(JSON.stringify(canonical(policy))).digest("hex").slice(0, 16);
1495
+ var computePolicyKey = (policy) => policy === void 0 ? "none" : hashText(JSON.stringify(canonical2(policy))).slice(0, 16);
1345
1496
  var computeSchemaFingerprint = (schema) => {
1346
1497
  const byName = (a, b) => a.name.localeCompare(b.name);
1347
1498
  const stable = {
@@ -1371,7 +1522,7 @@ var computeSchemaFingerprint = (schema) => {
1371
1522
  }))
1372
1523
  }))
1373
1524
  };
1374
- return crypto.createHash("sha256").update(JSON.stringify(stable)).digest("hex");
1525
+ return hashText(JSON.stringify(stable));
1375
1526
  };
1376
1527
 
1377
1528
  // src/cache/util.ts
@@ -1403,18 +1554,6 @@ var sweepCache = async (cache, options) => {
1403
1554
  }
1404
1555
  return evicted;
1405
1556
  };
1406
- var canonical2 = (value) => {
1407
- if (Array.isArray(value)) return value.map(canonical2);
1408
- if (value !== null && typeof value === "object" && !(value instanceof Date)) {
1409
- const sorted = {};
1410
- for (const [key, inner] of Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) sorted[key] = canonical2(inner);
1411
- return sorted;
1412
- }
1413
- return value;
1414
- };
1415
- var canonicalText = (value) => JSON.stringify(canonical2(value)) ?? "undefined";
1416
- var hashText = (text) => crypto.createHash("sha256").update(text).digest("hex");
1417
- var canonicalHash = (value) => hashText(canonicalText(value));
1418
1557
 
1419
1558
  // src/engine/live.ts
1420
1559
  var DEFAULT_TTL_MS = 6e4;
@@ -1632,6 +1771,7 @@ var createQueryEngine = (engineConfig) => {
1632
1771
  const maxNestingDepth = engineConfig.config?.maxNestingDepth ?? DEFAULT_MAX_NESTING_DEPTH;
1633
1772
  const defaultLimit = engineConfig.config?.defaultLimit ?? DEFAULT_LIMIT;
1634
1773
  const maxLimit = engineConfig.config?.maxLimit ?? DEFAULT_MAX_LIMIT;
1774
+ const capAuthored = engineConfig.config?.capAuthored ?? false;
1635
1775
  const rejectCartesianProducts = engineConfig.config?.rejectCartesianProducts ?? true;
1636
1776
  const warnUnindexedFilters = engineConfig.config?.warnUnindexedFilters ?? true;
1637
1777
  const rejectUnindexedFilters = engineConfig.config?.rejectUnindexedFilters ?? false;
@@ -1690,13 +1830,16 @@ var createQueryEngine = (engineConfig) => {
1690
1830
  }
1691
1831
  return cachedSchema;
1692
1832
  };
1693
- const runPipeline = (dsl, policyOverride) => {
1833
+ const runPipeline = (dsl, policyOverride, seeded = false) => {
1694
1834
  const schema = ensureSchema();
1695
1835
  let processedDsl = dsl;
1836
+ let engineLimit;
1696
1837
  if (processedDsl.limit === void 0) {
1697
1838
  processedDsl = { ...processedDsl, limit: defaultLimit };
1698
- } else if (processedDsl.limit > maxLimit) {
1839
+ engineLimit = defaultLimit;
1840
+ } else if (processedDsl.limit > maxLimit && (capAuthored || !seeded)) {
1699
1841
  processedDsl = { ...processedDsl, limit: maxLimit };
1842
+ engineLimit = maxLimit;
1700
1843
  }
1701
1844
  const entities = discoverEntities(processedDsl);
1702
1845
  const activePolicy = policyOverride ?? scopePolicy;
@@ -1712,7 +1855,18 @@ var createQueryEngine = (engineConfig) => {
1712
1855
  );
1713
1856
  }
1714
1857
  const compiled = adapter.compile(resolved);
1715
- return { compiled, warnings: analysis.warnings };
1858
+ return { compiled, warnings: analysis.warnings, ...engineLimit !== void 0 ? { engineLimit } : {} };
1859
+ };
1860
+ const cutSaid = /* @__PURE__ */ new Set();
1861
+ const cutNote = (engineLimit, stated, rowCount, shape, fingerprint) => {
1862
+ if (engineLimit === void 0 || rowCount !== engineLimit) return void 0;
1863
+ if (shape !== void 0 && !Array.isArray(shape)) return void 0;
1864
+ const note = stated === void 0 ? `This list states no limit, so it ran with the engine's defaultLimit of ${engineLimit}, and exactly ${engineLimit} rows came back \u2014 it may have been cut. State a \`limit\`.` : `This query asks for ${stated} rows, the engine's maxLimit is ${engineLimit}, and exactly ${engineLimit} came back \u2014 the list may have been cut. Raise \`maxLimit\` to read more.`;
1865
+ if (fingerprint !== void 0 && !cutSaid.has(fingerprint)) {
1866
+ cutSaid.add(fingerprint);
1867
+ console.warn(`[vex] "${fingerprint}": ${note}`);
1868
+ }
1869
+ return note;
1716
1870
  };
1717
1871
  const compile2 = (dsl) => runPipeline(pruneOptional(dsl, "all")).compiled;
1718
1872
  const test = async (dsl, scopeValues) => {
@@ -1760,6 +1914,7 @@ var createQueryEngine = (engineConfig) => {
1760
1914
  ...entry.intent !== void 0 ? { intent: entry.intent } : {},
1761
1915
  ...entry.shape !== void 0 ? { shape: entry.shape } : {},
1762
1916
  ...entry.refresh !== void 0 ? { refresh: entry.refresh } : {},
1917
+ seeded: entry.protected === true && entry.requestHash === void 0,
1763
1918
  hit: true,
1764
1919
  replaced: false
1765
1920
  };
@@ -1804,7 +1959,7 @@ var createQueryEngine = (engineConfig) => {
1804
1959
  try {
1805
1960
  return await generateDsl(validRequest, agentSchema, callerOf(policy, scope, agentSchema.entities.map((e) => e.name)));
1806
1961
  } catch (err) {
1807
- if (err instanceof VexError && err.code === "unsatisfiable") {
1962
+ if (isVexError(err) && err.code === "unsatisfiable") {
1808
1963
  const now = Date.now();
1809
1964
  await cache.set(negKey, {
1810
1965
  kind: "unsatisfiable",
@@ -1860,7 +2015,7 @@ var createQueryEngine = (engineConfig) => {
1860
2015
  }
1861
2016
  if (mappingMs !== void 0) emit({ type: "query.mapped", mappingMs });
1862
2017
  }
1863
- return { result, executionMs, mappingMs, mappedIr };
2018
+ return { result, rowCount: rows.length, executionMs, mappingMs, mappedIr };
1864
2019
  };
1865
2020
  const execute = async (request, options) => {
1866
2021
  if (strata.exceedsDepth(request)) throw new VexError("invalid_request", `Invalid request: ${strata.depthRefusal()}`);
@@ -1909,7 +2064,7 @@ var createQueryEngine = (engineConfig) => {
1909
2064
  }
1910
2065
  const presence = presenceOf(validRequest.context);
1911
2066
  const shaped = pruneOptional(applySortContext(dsl, validRequest.context), presence);
1912
- const { compiled, warnings } = runPipeline(shaped, activePolicy);
2067
+ const { compiled, warnings, engineLimit } = runPipeline(shaped, activePolicy, cached.seeded === true);
1913
2068
  noteVariant(cached.fingerprint, presenceSignature(dsl, presence), warnings);
1914
2069
  emit({ type: "query.sql", sql: compiled.sql, warnings });
1915
2070
  requireScope(compiled, scope);
@@ -1944,14 +2099,18 @@ var createQueryEngine = (engineConfig) => {
1944
2099
  const executionMs2 = Date.now() - execStart;
1945
2100
  emit({ type: "query.rows", count: rows.length, executionMs: executionMs2 });
1946
2101
  const result2 = shapeRows(rows);
1947
- const meta = {
1948
- cache: {
1949
- hit: cached.hit,
1950
- fingerprint: cached.fingerprint,
1951
- intent: cached.intent ?? validRequest.intent
1952
- },
1953
- context: buildContextContract(compiled, optionalKeysOf(dsl)),
1954
- warnings: warnings.length > 0 ? warnings : void 0
2102
+ const metaOf = (rowCount2) => {
2103
+ const cut2 = cutNote(engineLimit, shaped.limit, rowCount2, shape, validRequest.fingerprint);
2104
+ const said2 = cut2 === void 0 ? warnings : [...warnings, cut2];
2105
+ return {
2106
+ cache: {
2107
+ hit: cached.hit,
2108
+ fingerprint: cached.fingerprint,
2109
+ intent: cached.intent ?? validRequest.intent
2110
+ },
2111
+ context: buildContextContract(compiled, optionalKeysOf(dsl)),
2112
+ warnings: said2.length > 0 ? said2 : void 0
2113
+ };
1955
2114
  };
1956
2115
  const { signal, onChange } = options ?? {};
1957
2116
  if (signal !== void 0 && onChange !== void 0) {
@@ -1962,20 +2121,22 @@ var createQueryEngine = (engineConfig) => {
1962
2121
  const nextHash = canonicalHash(nextResult);
1963
2122
  if (nextHash === lastHash) return;
1964
2123
  lastHash = nextHash;
1965
- onChange({ result: nextResult, meta });
2124
+ onChange({ result: nextResult, meta: metaOf(next.length) });
1966
2125
  }
1967
2126
  }, signal);
1968
2127
  }
1969
2128
  emit({ type: "query.done", totalMs: Date.now() - t0 });
1970
- return { result: result2, meta: { ...meta, timing: { executionMs: executionMs2 } } };
2129
+ return { result: result2, meta: { ...metaOf(rows.length), timing: { executionMs: executionMs2 } } };
1971
2130
  }
1972
- const { result, executionMs, mappingMs, mappedIr } = await executeAndMap(
2131
+ const { result, rowCount, executionMs, mappingMs, mappedIr } = await executeAndMap(
1973
2132
  compiled,
1974
2133
  effectiveRequest,
1975
2134
  cached.cachedIr,
1976
2135
  context,
1977
2136
  scope
1978
2137
  );
2138
+ const cut = cutNote(engineLimit, shaped.limit, rowCount, effectiveRequest.shape, validRequest.fingerprint);
2139
+ const said = cut === void 0 ? warnings : [...warnings, cut];
1979
2140
  if (!cached.hit) {
1980
2141
  const now = Date.now();
1981
2142
  const entry = {
@@ -2007,7 +2168,7 @@ var createQueryEngine = (engineConfig) => {
2007
2168
  executionMs,
2008
2169
  ...mappingMs !== void 0 ? { mappingMs } : {}
2009
2170
  },
2010
- warnings: warnings.length > 0 ? warnings : void 0
2171
+ warnings: said.length > 0 ? said : void 0
2011
2172
  }
2012
2173
  };
2013
2174
  };
@@ -2767,9 +2928,8 @@ var createPostgresAdapter = (config) => {
2767
2928
  return enforcement;
2768
2929
  };
2769
2930
  const execute = async (query, params) => {
2770
- const { transaction } = pool;
2771
2931
  const limit = perStatementMs;
2772
- const result = limit === void 0 || transaction === void 0 ? await pool.query(query.sql, params) : await transaction(async (tx) => {
2932
+ const result = limit === void 0 || pool.transaction === void 0 ? await pool.query(query.sql, params) : await pool.transaction(async (tx) => {
2773
2933
  await tx.query(`SET LOCAL statement_timeout = ${limit}`);
2774
2934
  return tx.query(query.sql, params);
2775
2935
  });
@@ -2816,13 +2976,21 @@ var LookupSchema = zod.z.object({
2816
2976
  where: FilterSchema.describe("Bounds the lookup \u2014 should match at most one row")
2817
2977
  }).strict()
2818
2978
  }).strict().describe("Scalar subquery: reads one value from another table at write time; read scope rules apply");
2979
+ var ReturnedSchema = zod.z.object({
2980
+ $returned: FieldPathSchema.describe(
2981
+ "`table.column`: `table` is written by exactly one earlier statement of this batch; `column` is a column of that table, including one the database generated."
2982
+ )
2983
+ }).strict().describe(
2984
+ "A column of the one row an earlier statement of this batch (an insert, update, upsert or delete) returned \u2014 how a later row gets an id the database generated. That statement must return exactly one row; none (its `where` matched no row, or scope kept the row back) or several fails the whole batch and nothing is written. Allowed only as the value of a column a statement sets; never inside a `where`, a `$lookup` or `items`, and never naming an `insertEach` or an `insert` whose `onConflict` has no `set`."
2985
+ );
2819
2986
  var ValueSchema = zod.z.union([
2820
2987
  zod.z.string(),
2821
2988
  zod.z.number(),
2822
2989
  zod.z.boolean(),
2823
2990
  zod.z.null(),
2824
2991
  zod.z.object({ $context: zod.z.string() }).strict(),
2825
- LookupSchema
2992
+ LookupSchema,
2993
+ ReturnedSchema
2826
2994
  ]);
2827
2995
  var Columns = zod.z.record(zod.z.string(), ValueSchema).refine((r) => Object.keys(r).length > 0, { message: "a write must set at least one column" });
2828
2996
  var OnConflictSchema = zod.z.object({
@@ -3215,17 +3383,23 @@ var walkFilter = (filter, schema, sig) => {
3215
3383
  };
3216
3384
  var isLookupRef = (v) => v !== null && typeof v === "object" && !Array.isArray(v) && "$lookup" in v;
3217
3385
  var columnsOf = (m) => m.op === "insert" || m.op === "insertEach" ? { ...m.values, ...m.onConflict?.set ?? {} } : m.op === "update" ? m.set : m.op === "upsert" ? { ...m.columns, ...m.insert ?? {} } : {};
3386
+ var positionsSetBy = (m) => {
3387
+ const positions = (cols, insertOnly = false) => Object.entries(cols ?? {}).map(([column, value]) => ({ column, value, insertOnly }));
3388
+ if (m.op === "insert" || m.op === "insertEach") return [...positions(m.values), ...positions(m.onConflict?.set)];
3389
+ if (m.op === "update") return positions(m.set);
3390
+ if (m.op === "upsert") return [...positions(m.columns), ...positions(m.insert, true)];
3391
+ return [];
3392
+ };
3218
3393
  var collectMutationContext = (def, schema) => {
3219
3394
  const sig = {};
3220
3395
  const list = Array.isArray(def) ? def : [def];
3221
3396
  for (const m of list) {
3222
- for (const [col, v] of Object.entries(columnsOf(m))) {
3397
+ for (const { column: col, value: v, insertOnly } of positionsSetBy(m)) {
3223
3398
  if (isLookupRef(v)) {
3224
3399
  walkFilter(v.$lookup.where, schema, sig);
3225
3400
  continue;
3226
3401
  }
3227
3402
  if (!isContextRef(v)) continue;
3228
- const insertOnly = m.op === "upsert" && m.insert !== void 0 && col in m.insert;
3229
3403
  addField(sig, v.$context, { ...columnInfo(`${m.table}.${col}`, schema), ...insertOnly ? { note: "insert only" } : {} });
3230
3404
  }
3231
3405
  if (m.op === "update" || m.op === "delete") walkFilter(m.where, schema, sig);
@@ -3263,8 +3437,7 @@ var mutationEffect = (def) => {
3263
3437
  };
3264
3438
  var requiredContextKeys = (m) => {
3265
3439
  const keys = /* @__PURE__ */ new Set();
3266
- const cols = m.op === "insert" || m.op === "insertEach" ? { ...m.values, ...m.onConflict?.set ?? {} } : m.op === "update" ? m.set : {};
3267
- for (const v of Object.values(cols)) {
3440
+ for (const { value: v } of positionsSetBy(m)) {
3268
3441
  if (isContextRef(v)) keys.add(v.$context);
3269
3442
  else if (isLookupRef(v)) {
3270
3443
  const sub = {};
@@ -3286,9 +3459,40 @@ var findOptional = (value) => {
3286
3459
  if ("optional" in value) return true;
3287
3460
  return Object.values(value).some(findOptional);
3288
3461
  };
3462
+ var isReturnedRef = (v) => v !== null && typeof v === "object" && !Array.isArray(v) && "$returned" in v && typeof v.$returned === "string";
3463
+ var returnedIn = (list, at) => {
3464
+ const refs = /* @__PURE__ */ new Map();
3465
+ const issues = [];
3466
+ const m = list[at];
3467
+ if (m === void 0) return { refs, issues };
3468
+ const judged = /* @__PURE__ */ new Set();
3469
+ for (const { value: v } of positionsSetBy(m)) {
3470
+ if (!isReturnedRef(v) || judged.has(v.$returned)) continue;
3471
+ judged.add(v.$returned);
3472
+ const dot = v.$returned.indexOf(".");
3473
+ const table = v.$returned.slice(0, dot);
3474
+ const column = v.$returned.slice(dot + 1);
3475
+ const reads = `${m.op} on "${m.table}" reads "${v.$returned}"`;
3476
+ const earlier = list.flatMap((s, i) => i < at && s.table === table ? [{ s, i }] : []);
3477
+ const source = earlier[0];
3478
+ if (source === void 0) {
3479
+ issues.push(`${reads}, and no earlier statement writes "${table}" \u2014 put the statement that writes it before this one, in the same batch`);
3480
+ } else if (earlier.length > 1) {
3481
+ issues.push(`${reads}, and ${earlier.length} earlier statements write "${table}" \u2014 a reference cannot tell them apart`);
3482
+ } else if (source.s.op === "insertEach") {
3483
+ issues.push(`${reads} from an insertEach, which writes a row per element \u2014 there is no one row to read`);
3484
+ } else if (source.s.op === "insert" && source.s.onConflict !== void 0 && source.s.onConflict.set === void 0) {
3485
+ issues.push(`${reads} from an insert that does nothing on conflict, which then returns no row \u2014 give its onConflict a \`set\``);
3486
+ } else {
3487
+ refs.set(v.$returned, { statement: source.i, table, column });
3488
+ }
3489
+ }
3490
+ return { refs, issues };
3491
+ };
3289
3492
  var lintMutation = (def) => {
3290
3493
  const issues = [];
3291
3494
  const list = Array.isArray(def) ? def : [def];
3495
+ list.forEach((_m, at) => issues.push(...returnedIn(list, at).issues));
3292
3496
  for (const m of list) {
3293
3497
  if (findOptional(m)) {
3294
3498
  issues.push(`${m.op} on "${m.table}" contains an optional condition \u2014 a write's bounds cannot depend on what the caller chose to send`);
@@ -3346,6 +3550,7 @@ var seedCache = async (cache, entries) => {
3346
3550
  // src/mutations/engine.ts
3347
3551
  var isLookup = (v) => v !== null && typeof v === "object" && !Array.isArray(v) && "$lookup" in v;
3348
3552
  var isItemRef = (v) => v !== null && typeof v === "object" && !Array.isArray(v) && "$item" in v;
3553
+ var isReturned = (v) => v !== null && typeof v === "object" && !Array.isArray(v) && "$returned" in v;
3349
3554
  var collectLookups = (m) => {
3350
3555
  const out = [];
3351
3556
  const scan = (cols) => {
@@ -3443,6 +3648,13 @@ var assertWritableColumns = (m, schema) => {
3443
3648
  if (m.onConflict.where !== void 0) assertFilterColumns(m.onConflict.where, m.table, schema, "onConflict");
3444
3649
  }
3445
3650
  };
3651
+ var assertReturnedColumns = (refs, schema) => {
3652
+ for (const [ref, source] of refs) {
3653
+ if (findEntity2(source.table, schema)?.fields.some((f) => f.name === source.column) !== true) {
3654
+ throw new VexError("invalid_dsl", `Unknown column "${ref}" in $returned.`);
3655
+ }
3656
+ }
3657
+ };
3446
3658
  var readMatchesFor = (table, policy) => {
3447
3659
  const rule = policy.entities[table];
3448
3660
  if (rule === void 0) {
@@ -3551,7 +3763,8 @@ var newCtx = () => ({
3551
3763
  resolvedPaths: /* @__PURE__ */ new Map(),
3552
3764
  aliasMap: /* @__PURE__ */ new Map(),
3553
3765
  paramSlots: [],
3554
- paramCounter: { value: 0 }
3766
+ paramCounter: { value: 0 },
3767
+ returned: /* @__PURE__ */ new Map()
3555
3768
  });
3556
3769
  var indexFilterFields = (filter, aliasMap) => {
3557
3770
  for (const path of filterColumns(filter)) aliasMap.set(path, path);
@@ -3562,13 +3775,19 @@ var compileValue = (v, ctx) => {
3562
3775
  const where = compileFilter(v.$lookup.where, ctx);
3563
3776
  return `(SELECT ${v.$lookup.field} FROM ${v.$lookup.from} WHERE ${where})`;
3564
3777
  }
3778
+ if (isReturned(v)) {
3779
+ ctx.paramCounter.value += 1;
3780
+ ctx.returned.set(ctx.paramSlots.length, v.$returned);
3781
+ ctx.paramSlots.push({ key: v.$returned, kind: "context", type: "string" });
3782
+ return `$${ctx.paramCounter.value}`;
3783
+ }
3565
3784
  return compileFieldOrValue(v, ctx);
3566
3785
  };
3567
3786
  var compileColumnValue = (table, column, v, ctx, schema) => {
3568
3787
  const before = ctx.paramSlots.length;
3569
3788
  const sql = compileValue(v, ctx);
3570
3789
  const json = findEntity2(table, schema)?.fields.find((f) => f.name === column)?.normalizedType === "json";
3571
- if (json && typeof v === "object" && v !== null && "$context" in v) {
3790
+ if (json && typeof v === "object" && v !== null && ("$context" in v || "$returned" in v)) {
3572
3791
  const slot = ctx.paramSlots[before];
3573
3792
  if (slot !== void 0) ctx.paramSlots[before] = { ...slot, encode: "json" };
3574
3793
  }
@@ -3599,7 +3818,7 @@ var compileMutation = (m, schema) => {
3599
3818
  const entries = Object.entries(m.values);
3600
3819
  const cols = entries.map(([c]) => c);
3601
3820
  const vals = entries.map(([c, v]) => compileColumnValue(m.table, c, v, ctx, schema));
3602
- return { sql: `INSERT INTO ${m.table} (${cols.join(", ")}) VALUES (${vals.join(", ")})${compileConflict(m, ctx, schema)} RETURNING *`, slots: ctx.paramSlots };
3821
+ return { sql: `INSERT INTO ${m.table} (${cols.join(", ")}) VALUES (${vals.join(", ")})${compileConflict(m, ctx, schema)} RETURNING *`, slots: ctx.paramSlots, returned: ctx.returned };
3603
3822
  }
3604
3823
  if (m.op === "insertEach") {
3605
3824
  const entity = findEntity2(m.table, schema);
@@ -3613,25 +3832,26 @@ var compileMutation = (m, schema) => {
3613
3832
  const raw = `(item.value->>${quoteLiteral(v.$item)})`;
3614
3833
  return cast === void 0 ? raw : `${raw}::${cast}`;
3615
3834
  }
3616
- return compileValue(v, ctx);
3835
+ return isReturned(v) ? compileColumnValue(m.table, col, v, ctx, schema) : compileValue(v, ctx);
3617
3836
  });
3618
3837
  ctx.paramCounter.value += 1;
3619
3838
  ctx.paramSlots.push({ key: m.items.$context, kind: "context", type: "json" });
3620
3839
  const source = `jsonb_array_elements($${ctx.paramCounter.value}::jsonb) AS item`;
3621
3840
  return {
3622
3841
  sql: `INSERT INTO ${m.table} (${cols.join(", ")}) SELECT ${exprs.join(", ")} FROM ${source}${compileConflict(m, ctx, schema)} RETURNING *`,
3623
- slots: ctx.paramSlots
3842
+ slots: ctx.paramSlots,
3843
+ returned: ctx.returned
3624
3844
  };
3625
3845
  }
3626
3846
  if (m.op === "update") {
3627
3847
  const sets = Object.entries(m.set).map(([c, v]) => `${c} = ${compileColumnValue(m.table, c, v, ctx, schema)}`);
3628
3848
  indexFilterFields(m.where, ctx.aliasMap);
3629
3849
  const where2 = compileFilter(m.where, ctx);
3630
- return { sql: `UPDATE ${m.table} SET ${sets.join(", ")} WHERE ${where2} RETURNING *`, slots: ctx.paramSlots };
3850
+ return { sql: `UPDATE ${m.table} SET ${sets.join(", ")} WHERE ${where2} RETURNING *`, slots: ctx.paramSlots, returned: ctx.returned };
3631
3851
  }
3632
3852
  indexFilterFields(m.where, ctx.aliasMap);
3633
3853
  const where = compileFilter(m.where, ctx);
3634
- return { sql: `DELETE FROM ${m.table} WHERE ${where} RETURNING *`, slots: ctx.paramSlots };
3854
+ return { sql: `DELETE FROM ${m.table} WHERE ${where} RETURNING *`, slots: ctx.paramSlots, returned: ctx.returned };
3635
3855
  };
3636
3856
  var SUGAR = {
3637
3857
  upsert: (m, context) => {
@@ -3643,27 +3863,69 @@ var desugarMutation = (m, context) => {
3643
3863
  const rewrite = SUGAR[m.op];
3644
3864
  return rewrite === void 0 ? m : rewrite(m, context);
3645
3865
  };
3866
+ var mutationMisfits = (def, schema) => {
3867
+ const reasons = [];
3868
+ const list = Array.isArray(def) ? def : [def];
3869
+ for (const [at, entry] of list.entries()) {
3870
+ const asked = [
3871
+ // keyed, an upsert is an update; unkeyed, an insert
3872
+ ...(entry.op === "upsert" ? [{ [entry.key]: 0 }, {}] : [{}]).map((context) => () => assertWritableColumns(desugarMutation(entry, context), schema)),
3873
+ () => assertReturnedColumns(returnedIn(list, at).refs, schema)
3874
+ ];
3875
+ for (const ask of asked) {
3876
+ try {
3877
+ ask();
3878
+ } catch (error) {
3879
+ reasons.push(error instanceof Error ? error.message : String(error));
3880
+ }
3881
+ }
3882
+ }
3883
+ return reasons;
3884
+ };
3646
3885
  var executeWrites = async (client, def, mctx) => {
3647
3886
  const parsed = MutationDefinitionSchema.parse(def);
3648
3887
  const entries = Array.isArray(parsed) ? parsed : [parsed];
3649
- const compiled = entries.map((entry) => {
3650
- const core = desugarMutation(entry, mctx.context);
3888
+ const cores = entries.map((entry) => desugarMutation(entry, mctx.context));
3889
+ const compiled = cores.map((core, at) => {
3651
3890
  const missing = requiredContextKeys(core).filter((k) => mctx.context[k] === void 0);
3652
3891
  if (missing.length > 0) {
3653
3892
  throw new VexError("missing_context", `Mutation is missing context: ${missing.join(", ")}.`, {
3654
3893
  expected: collectMutationContext(parsed, mctx.schema)
3655
3894
  });
3656
3895
  }
3896
+ const returned = returnedIn(cores, at);
3897
+ if (returned.issues.length > 0) throw new VexError("invalid_dsl", `${returned.issues.join("; ")}.`);
3657
3898
  const m = scopeMutation(core, mctx.policy);
3658
3899
  assertWritableColumns(m, mctx.schema);
3900
+ assertReturnedColumns(returned.refs, mctx.schema);
3659
3901
  const statement = compileMutation(m, mctx.schema);
3660
3902
  requireScope({ paramSlots: statement.slots }, mctx.scope);
3661
- return { ...statement, table: m.table, op: m.op === "insertEach" ? "insert" : m.op };
3903
+ const reads = [...statement.returned].map(([slot, ref]) => {
3904
+ const source = returned.refs.get(ref);
3905
+ if (source === void 0) throw new VexError("invalid_dsl", `"${ref}" names no earlier statement of the batch.`);
3906
+ return { slot, ref, source };
3907
+ });
3908
+ return { ...statement, reads, table: m.table, op: m.op === "insertEach" ? "insert" : m.op };
3662
3909
  });
3663
3910
  const runAll = async (q) => {
3664
3911
  const results = [];
3665
3912
  for (const c of compiled) {
3666
3913
  const params = await resolveParams(c.slots, mctx.context, mctx.scope);
3914
+ for (const read of c.reads) {
3915
+ const rows = results[read.source.statement]?.rows ?? [];
3916
+ const row = rows[0];
3917
+ if (rows.length !== 1 || row === void 0) {
3918
+ throw new VexError(
3919
+ "execution_error",
3920
+ `"${read.ref}" needs exactly one row from statement ${read.source.statement + 1} of the batch, which wrote ${rows.length}. Nothing was written.`,
3921
+ { returned: read.ref, rows: rows.length }
3922
+ );
3923
+ }
3924
+ if (!(read.source.column in row)) {
3925
+ throw new VexError("execution_error", `"${read.ref}": the row statement ${read.source.statement + 1} returned has no "${read.source.column}" key. Nothing was written.`, { returned: read.ref });
3926
+ }
3927
+ params[read.slot] = row[read.source.column];
3928
+ }
3667
3929
  const bound = params.map((value, i) => {
3668
3930
  if (c.slots[i]?.encode === "json") return value !== null && typeof value === "object" ? JSON.stringify(value) : value;
3669
3931
  if (c.slots[i]?.type !== "json") return value;
@@ -3962,11 +4224,11 @@ var runQuery = async (config, body, scope, probe, live) => {
3962
4224
  }
3963
4225
  return { status: 200, body: response };
3964
4226
  } catch (err) {
3965
- if (err instanceof VexError && err.code === "missing_scope") {
4227
+ if (isVexError(err) && err.code === "missing_scope") {
3966
4228
  console.error("[vex] refused a statement the host did not scope:", err.message);
3967
4229
  return { status: 500, body: { error: "missing_scope", message: "The server did not supply the scope this request needs." } };
3968
4230
  }
3969
- if (err instanceof VexError) {
4231
+ if (isVexError(err)) {
3970
4232
  const status = err.code === "fingerprint_protected" ? 409 : err.code === "cache_miss" ? 404 : 400;
3971
4233
  return {
3972
4234
  status,
@@ -4058,6 +4320,7 @@ exports.lintMutation = lintMutation;
4058
4320
  exports.mergeScopePolicies = mergeScopePolicies;
4059
4321
  exports.mintFingerprint = mintFingerprint;
4060
4322
  exports.mutationEffect = mutationEffect;
4323
+ exports.mutationMisfits = mutationMisfits;
4061
4324
  exports.normalizeShape = normalizeShape;
4062
4325
  exports.optionalKeysOf = optionalKeysOf;
4063
4326
  exports.presenceOf = presenceOf;