@niscorp/vex 0.2.2 → 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 (36) hide show
  1. package/CHANGELOG.md +121 -0
  2. package/DESIGN.md +66 -3
  3. package/DOCS.md +156 -12
  4. package/dist/adapters/express/index.cjs +102 -17
  5. package/dist/adapters/express/index.cjs.map +1 -1
  6. package/dist/adapters/express/index.d.cts +2 -2
  7. package/dist/adapters/express/index.d.ts +2 -2
  8. package/dist/adapters/express/index.js +2 -2
  9. package/dist/adapters/hono/index.cjs +121 -22
  10. package/dist/adapters/hono/index.cjs.map +1 -1
  11. package/dist/adapters/hono/index.d.cts +2 -2
  12. package/dist/adapters/hono/index.d.ts +2 -2
  13. package/dist/adapters/hono/index.js +21 -7
  14. package/dist/adapters/hono/index.js.map +1 -1
  15. package/dist/agent/index.cjs +2 -0
  16. package/dist/agent/index.cjs.map +1 -1
  17. package/dist/agent/index.d.cts +1 -1
  18. package/dist/agent/index.d.ts +1 -1
  19. package/dist/agent/index.js +1 -1
  20. package/dist/{chunk-HF25Q53I.js → chunk-H4BHW76Q.js} +6 -3
  21. package/dist/chunk-H4BHW76Q.js.map +1 -0
  22. package/dist/{chunk-HCEH55PP.js → chunk-IQM4SQE2.js} +123 -21
  23. package/dist/chunk-IQM4SQE2.js.map +1 -0
  24. package/dist/{handler-Cql8SJ3F.d.cts → handler-BGCL6_Si.d.ts} +3 -2
  25. package/dist/{handler-mICf9ins.d.ts → handler-CMrjTXNx.d.cts} +3 -2
  26. package/dist/index.cjs +163 -35
  27. package/dist/index.cjs.map +1 -1
  28. package/dist/index.d.cts +3 -3
  29. package/dist/index.d.ts +3 -3
  30. package/dist/index.js +44 -22
  31. package/dist/index.js.map +1 -1
  32. package/dist/{types-BRvMB6IM.d.cts → types-Bi-Lg86b.d.cts} +48 -2
  33. package/dist/{types-BRvMB6IM.d.ts → types-Bi-Lg86b.d.ts} +48 -2
  34. package/package.json +5 -5
  35. package/dist/chunk-HCEH55PP.js.map +0 -1
  36. package/dist/chunk-HF25Q53I.js.map +0 -1
@@ -1,5 +1,5 @@
1
- import { a as QueryEngine, ak as ScopeValues } from '../../types-BRvMB6IM.cjs';
2
- import { V as VexHandlerConfig } from '../../handler-Cql8SJ3F.cjs';
1
+ import { a as QueryEngine, al as ScopeValues } from '../../types-Bi-Lg86b.cjs';
2
+ import { V as VexHandlerConfig } from '../../handler-CMrjTXNx.cjs';
3
3
  import 'zod';
4
4
  import '@niscorp/prism';
5
5
  import '@niscorp/strata';
@@ -1,5 +1,5 @@
1
- import { a as QueryEngine, ak as ScopeValues } from '../../types-BRvMB6IM.js';
2
- import { V as VexHandlerConfig } from '../../handler-mICf9ins.js';
1
+ import { a as QueryEngine, al as ScopeValues } from '../../types-Bi-Lg86b.js';
2
+ import { V as VexHandlerConfig } from '../../handler-BGCL6_Si.js';
3
3
  import 'zod';
4
4
  import '@niscorp/prism';
5
5
  import '@niscorp/strata';
@@ -1,5 +1,5 @@
1
- import { handleDiscovery, handleQuery, handleFingerprintPatch, handleFingerprintDelete } from '../../chunk-HCEH55PP.js';
2
- import '../../chunk-HF25Q53I.js';
1
+ import { handleDiscovery, handleQuery, handleFingerprintPatch, handleFingerprintDelete } from '../../chunk-IQM4SQE2.js';
2
+ import '../../chunk-H4BHW76Q.js';
3
3
 
4
4
  // src/adapters/express/index.ts
5
5
  var fingerprintFromBody = (body) => {
@@ -355,6 +355,7 @@ var computeSchemaFingerprint = (schema) => {
355
355
  };
356
356
 
357
357
  // src/errors.ts
358
+ var VEX_ERROR = /* @__PURE__ */ Symbol.for("@niscorp/vex:VexError");
358
359
  var VexError = class extends Error {
359
360
  code;
360
361
  details;
@@ -365,6 +366,8 @@ var VexError = class extends Error {
365
366
  this.details = details;
366
367
  }
367
368
  };
369
+ Object.defineProperty(VexError.prototype, VEX_ERROR, { value: true });
370
+ var isVexError = (err) => err instanceof VexError || err instanceof Error && Reflect.get(err, VEX_ERROR) === true;
368
371
 
369
372
  // src/engine/optional.ts
370
373
  var refuseOptional = (where) => {
@@ -643,13 +646,21 @@ var LookupSchema = zod.z.object({
643
646
  where: FilterSchema.describe("Bounds the lookup \u2014 should match at most one row")
644
647
  }).strict()
645
648
  }).strict().describe("Scalar subquery: reads one value from another table at write time; read scope rules apply");
649
+ var ReturnedSchema = zod.z.object({
650
+ $returned: FieldPathSchema.describe(
651
+ "`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."
652
+ )
653
+ }).strict().describe(
654
+ "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`."
655
+ );
646
656
  var ValueSchema = zod.z.union([
647
657
  zod.z.string(),
648
658
  zod.z.number(),
649
659
  zod.z.boolean(),
650
660
  zod.z.null(),
651
661
  zod.z.object({ $context: zod.z.string() }).strict(),
652
- LookupSchema
662
+ LookupSchema,
663
+ ReturnedSchema
653
664
  ]);
654
665
  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" });
655
666
  var OnConflictSchema = zod.z.object({
@@ -747,17 +758,23 @@ var walkFilter = (filter, schema, sig) => {
747
758
  };
748
759
  var isLookupRef = (v) => v !== null && typeof v === "object" && !Array.isArray(v) && "$lookup" in v;
749
760
  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 ?? {} } : {};
761
+ var positionsSetBy = (m) => {
762
+ const positions = (cols, insertOnly = false) => Object.entries(cols ?? {}).map(([column, value]) => ({ column, value, insertOnly }));
763
+ if (m.op === "insert" || m.op === "insertEach") return [...positions(m.values), ...positions(m.onConflict?.set)];
764
+ if (m.op === "update") return positions(m.set);
765
+ if (m.op === "upsert") return [...positions(m.columns), ...positions(m.insert, true)];
766
+ return [];
767
+ };
750
768
  var collectMutationContext = (def, schema) => {
751
769
  const sig = {};
752
770
  const list = Array.isArray(def) ? def : [def];
753
771
  for (const m of list) {
754
- for (const [col, v] of Object.entries(columnsOf(m))) {
772
+ for (const { column: col, value: v, insertOnly } of positionsSetBy(m)) {
755
773
  if (isLookupRef(v)) {
756
774
  walkFilter(v.$lookup.where, schema, sig);
757
775
  continue;
758
776
  }
759
777
  if (!isContextRef(v)) continue;
760
- const insertOnly = m.op === "upsert" && m.insert !== void 0 && col in m.insert;
761
778
  addField(sig, v.$context, { ...columnInfo(`${m.table}.${col}`, schema), ...insertOnly ? { note: "insert only" } : {} });
762
779
  }
763
780
  if (m.op === "update" || m.op === "delete") walkFilter(m.where, schema, sig);
@@ -795,8 +812,7 @@ var mutationEffect = (def) => {
795
812
  };
796
813
  var requiredContextKeys = (m) => {
797
814
  const keys = /* @__PURE__ */ new Set();
798
- const cols = m.op === "insert" || m.op === "insertEach" ? { ...m.values, ...m.onConflict?.set ?? {} } : m.op === "update" ? m.set : {};
799
- for (const v of Object.values(cols)) {
815
+ for (const { value: v } of positionsSetBy(m)) {
800
816
  if (isContextRef(v)) keys.add(v.$context);
801
817
  else if (isLookupRef(v)) {
802
818
  const sub = {};
@@ -812,10 +828,41 @@ var requiredContextKeys = (m) => {
812
828
  }
813
829
  return [...keys].sort();
814
830
  };
831
+ var isReturnedRef = (v) => v !== null && typeof v === "object" && !Array.isArray(v) && "$returned" in v && typeof v.$returned === "string";
832
+ var returnedIn = (list, at) => {
833
+ const refs = /* @__PURE__ */ new Map();
834
+ const issues = [];
835
+ const m = list[at];
836
+ if (m === void 0) return { refs, issues };
837
+ const judged = /* @__PURE__ */ new Set();
838
+ for (const { value: v } of positionsSetBy(m)) {
839
+ if (!isReturnedRef(v) || judged.has(v.$returned)) continue;
840
+ judged.add(v.$returned);
841
+ const dot = v.$returned.indexOf(".");
842
+ const table = v.$returned.slice(0, dot);
843
+ const column = v.$returned.slice(dot + 1);
844
+ const reads = `${m.op} on "${m.table}" reads "${v.$returned}"`;
845
+ const earlier = list.flatMap((s, i) => i < at && s.table === table ? [{ s, i }] : []);
846
+ const source = earlier[0];
847
+ if (source === void 0) {
848
+ issues.push(`${reads}, and no earlier statement writes "${table}" \u2014 put the statement that writes it before this one, in the same batch`);
849
+ } else if (earlier.length > 1) {
850
+ issues.push(`${reads}, and ${earlier.length} earlier statements write "${table}" \u2014 a reference cannot tell them apart`);
851
+ } else if (source.s.op === "insertEach") {
852
+ issues.push(`${reads} from an insertEach, which writes a row per element \u2014 there is no one row to read`);
853
+ } else if (source.s.op === "insert" && source.s.onConflict !== void 0 && source.s.onConflict.set === void 0) {
854
+ issues.push(`${reads} from an insert that does nothing on conflict, which then returns no row \u2014 give its onConflict a \`set\``);
855
+ } else {
856
+ refs.set(v.$returned, { statement: source.i, table, column });
857
+ }
858
+ }
859
+ return { refs, issues };
860
+ };
815
861
 
816
862
  // src/mutations/engine.ts
817
863
  var isLookup = (v) => v !== null && typeof v === "object" && !Array.isArray(v) && "$lookup" in v;
818
864
  var isItemRef = (v) => v !== null && typeof v === "object" && !Array.isArray(v) && "$item" in v;
865
+ var isReturned = (v) => v !== null && typeof v === "object" && !Array.isArray(v) && "$returned" in v;
819
866
  var collectLookups = (m) => {
820
867
  const out = [];
821
868
  const scan = (cols) => {
@@ -913,6 +960,13 @@ var assertWritableColumns = (m, schema) => {
913
960
  if (m.onConflict.where !== void 0) assertFilterColumns(m.onConflict.where, m.table, schema, "onConflict");
914
961
  }
915
962
  };
963
+ var assertReturnedColumns = (refs, schema) => {
964
+ for (const [ref, source] of refs) {
965
+ if (findEntity(source.table, schema)?.fields.some((f) => f.name === source.column) !== true) {
966
+ throw new VexError("invalid_dsl", `Unknown column "${ref}" in $returned.`);
967
+ }
968
+ }
969
+ };
916
970
  var readMatchesFor = (table, policy) => {
917
971
  const rule = policy.entities[table];
918
972
  if (rule === void 0) {
@@ -1021,7 +1075,8 @@ var newCtx = () => ({
1021
1075
  resolvedPaths: /* @__PURE__ */ new Map(),
1022
1076
  aliasMap: /* @__PURE__ */ new Map(),
1023
1077
  paramSlots: [],
1024
- paramCounter: { value: 0 }
1078
+ paramCounter: { value: 0 },
1079
+ returned: /* @__PURE__ */ new Map()
1025
1080
  });
1026
1081
  var indexFilterFields = (filter, aliasMap) => {
1027
1082
  for (const path of filterColumns(filter)) aliasMap.set(path, path);
@@ -1032,13 +1087,19 @@ var compileValue = (v, ctx) => {
1032
1087
  const where = compileFilter(v.$lookup.where, ctx);
1033
1088
  return `(SELECT ${v.$lookup.field} FROM ${v.$lookup.from} WHERE ${where})`;
1034
1089
  }
1090
+ if (isReturned(v)) {
1091
+ ctx.paramCounter.value += 1;
1092
+ ctx.returned.set(ctx.paramSlots.length, v.$returned);
1093
+ ctx.paramSlots.push({ key: v.$returned, kind: "context", type: "string" });
1094
+ return `$${ctx.paramCounter.value}`;
1095
+ }
1035
1096
  return compileFieldOrValue(v, ctx);
1036
1097
  };
1037
1098
  var compileColumnValue = (table, column, v, ctx, schema) => {
1038
1099
  const before = ctx.paramSlots.length;
1039
1100
  const sql = compileValue(v, ctx);
1040
1101
  const json = findEntity(table, schema)?.fields.find((f) => f.name === column)?.normalizedType === "json";
1041
- if (json && typeof v === "object" && v !== null && "$context" in v) {
1102
+ if (json && typeof v === "object" && v !== null && ("$context" in v || "$returned" in v)) {
1042
1103
  const slot = ctx.paramSlots[before];
1043
1104
  if (slot !== void 0) ctx.paramSlots[before] = { ...slot, encode: "json" };
1044
1105
  }
@@ -1069,7 +1130,7 @@ var compileMutation = (m, schema) => {
1069
1130
  const entries = Object.entries(m.values);
1070
1131
  const cols = entries.map(([c]) => c);
1071
1132
  const vals = entries.map(([c, v]) => compileColumnValue(m.table, c, v, ctx, schema));
1072
- return { sql: `INSERT INTO ${m.table} (${cols.join(", ")}) VALUES (${vals.join(", ")})${compileConflict(m, ctx, schema)} RETURNING *`, slots: ctx.paramSlots };
1133
+ return { sql: `INSERT INTO ${m.table} (${cols.join(", ")}) VALUES (${vals.join(", ")})${compileConflict(m, ctx, schema)} RETURNING *`, slots: ctx.paramSlots, returned: ctx.returned };
1073
1134
  }
1074
1135
  if (m.op === "insertEach") {
1075
1136
  const entity = findEntity(m.table, schema);
@@ -1083,25 +1144,26 @@ var compileMutation = (m, schema) => {
1083
1144
  const raw = `(item.value->>${quoteLiteral(v.$item)})`;
1084
1145
  return cast === void 0 ? raw : `${raw}::${cast}`;
1085
1146
  }
1086
- return compileValue(v, ctx);
1147
+ return isReturned(v) ? compileColumnValue(m.table, col, v, ctx, schema) : compileValue(v, ctx);
1087
1148
  });
1088
1149
  ctx.paramCounter.value += 1;
1089
1150
  ctx.paramSlots.push({ key: m.items.$context, kind: "context", type: "json" });
1090
1151
  const source = `jsonb_array_elements($${ctx.paramCounter.value}::jsonb) AS item`;
1091
1152
  return {
1092
1153
  sql: `INSERT INTO ${m.table} (${cols.join(", ")}) SELECT ${exprs.join(", ")} FROM ${source}${compileConflict(m, ctx, schema)} RETURNING *`,
1093
- slots: ctx.paramSlots
1154
+ slots: ctx.paramSlots,
1155
+ returned: ctx.returned
1094
1156
  };
1095
1157
  }
1096
1158
  if (m.op === "update") {
1097
1159
  const sets = Object.entries(m.set).map(([c, v]) => `${c} = ${compileColumnValue(m.table, c, v, ctx, schema)}`);
1098
1160
  indexFilterFields(m.where, ctx.aliasMap);
1099
1161
  const where2 = compileFilter(m.where, ctx);
1100
- return { sql: `UPDATE ${m.table} SET ${sets.join(", ")} WHERE ${where2} RETURNING *`, slots: ctx.paramSlots };
1162
+ return { sql: `UPDATE ${m.table} SET ${sets.join(", ")} WHERE ${where2} RETURNING *`, slots: ctx.paramSlots, returned: ctx.returned };
1101
1163
  }
1102
1164
  indexFilterFields(m.where, ctx.aliasMap);
1103
1165
  const where = compileFilter(m.where, ctx);
1104
- return { sql: `DELETE FROM ${m.table} WHERE ${where} RETURNING *`, slots: ctx.paramSlots };
1166
+ return { sql: `DELETE FROM ${m.table} WHERE ${where} RETURNING *`, slots: ctx.paramSlots, returned: ctx.returned };
1105
1167
  };
1106
1168
  var SUGAR = {
1107
1169
  upsert: (m, context) => {
@@ -1116,24 +1178,47 @@ var desugarMutation = (m, context) => {
1116
1178
  var executeWrites = async (client, def, mctx) => {
1117
1179
  const parsed = MutationDefinitionSchema.parse(def);
1118
1180
  const entries = Array.isArray(parsed) ? parsed : [parsed];
1119
- const compiled = entries.map((entry) => {
1120
- const core = desugarMutation(entry, mctx.context);
1181
+ const cores = entries.map((entry) => desugarMutation(entry, mctx.context));
1182
+ const compiled = cores.map((core, at) => {
1121
1183
  const missing = requiredContextKeys(core).filter((k) => mctx.context[k] === void 0);
1122
1184
  if (missing.length > 0) {
1123
1185
  throw new VexError("missing_context", `Mutation is missing context: ${missing.join(", ")}.`, {
1124
1186
  expected: collectMutationContext(parsed, mctx.schema)
1125
1187
  });
1126
1188
  }
1189
+ const returned = returnedIn(cores, at);
1190
+ if (returned.issues.length > 0) throw new VexError("invalid_dsl", `${returned.issues.join("; ")}.`);
1127
1191
  const m = scopeMutation(core, mctx.policy);
1128
1192
  assertWritableColumns(m, mctx.schema);
1193
+ assertReturnedColumns(returned.refs, mctx.schema);
1129
1194
  const statement = compileMutation(m, mctx.schema);
1130
1195
  requireScope({ paramSlots: statement.slots }, mctx.scope);
1131
- return { ...statement, table: m.table, op: m.op === "insertEach" ? "insert" : m.op };
1196
+ const reads = [...statement.returned].map(([slot, ref]) => {
1197
+ const source = returned.refs.get(ref);
1198
+ if (source === void 0) throw new VexError("invalid_dsl", `"${ref}" names no earlier statement of the batch.`);
1199
+ return { slot, ref, source };
1200
+ });
1201
+ return { ...statement, reads, table: m.table, op: m.op === "insertEach" ? "insert" : m.op };
1132
1202
  });
1133
1203
  const runAll = async (q) => {
1134
1204
  const results = [];
1135
1205
  for (const c of compiled) {
1136
1206
  const params = await resolveParams(c.slots, mctx.context, mctx.scope);
1207
+ for (const read of c.reads) {
1208
+ const rows = results[read.source.statement]?.rows ?? [];
1209
+ const row = rows[0];
1210
+ if (rows.length !== 1 || row === void 0) {
1211
+ throw new VexError(
1212
+ "execution_error",
1213
+ `"${read.ref}" needs exactly one row from statement ${read.source.statement + 1} of the batch, which wrote ${rows.length}. Nothing was written.`,
1214
+ { returned: read.ref, rows: rows.length }
1215
+ );
1216
+ }
1217
+ if (!(read.source.column in row)) {
1218
+ 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 });
1219
+ }
1220
+ params[read.slot] = row[read.source.column];
1221
+ }
1137
1222
  const bound = params.map((value, i) => {
1138
1223
  if (c.slots[i]?.encode === "json") return value !== null && typeof value === "object" ? JSON.stringify(value) : value;
1139
1224
  if (c.slots[i]?.type !== "json") return value;
@@ -1431,11 +1516,11 @@ var runQuery = async (config, body, scope, probe, live) => {
1431
1516
  }
1432
1517
  return { status: 200, body: response };
1433
1518
  } catch (err) {
1434
- if (err instanceof VexError && err.code === "missing_scope") {
1519
+ if (isVexError(err) && err.code === "missing_scope") {
1435
1520
  console.error("[vex] refused a statement the host did not scope:", err.message);
1436
1521
  return { status: 500, body: { error: "missing_scope", message: "The server did not supply the scope this request needs." } };
1437
1522
  }
1438
- if (err instanceof VexError) {
1523
+ if (isVexError(err)) {
1439
1524
  const status = err.code === "fingerprint_protected" ? 409 : err.code === "cache_miss" ? 404 : 400;
1440
1525
  return {
1441
1526
  status,
@@ -1500,8 +1585,18 @@ var fingerprintFromBody = (body) => {
1500
1585
  const fp = body["fingerprint"];
1501
1586
  return typeof fp === "string" && fp.length > 0 ? fp : void 0;
1502
1587
  };
1588
+ var NOT_JSON = { error: "invalid_request", message: "Body must be JSON" };
1503
1589
  var vex = (config) => {
1504
1590
  const app = new hono.Hono();
1591
+ const jsonBodyOf = async (c) => {
1592
+ try {
1593
+ const body = await c.req.json();
1594
+ return { parsed: true, body };
1595
+ } catch (err) {
1596
+ if (err instanceof SyntaxError) return { parsed: false };
1597
+ throw err;
1598
+ }
1599
+ };
1505
1600
  const requestConfig = async (c) => {
1506
1601
  const policy = config.getPolicy ? await config.getPolicy(c) : void 0;
1507
1602
  const mutationPolicy = policy ?? config.mutations?.policy;
@@ -1529,12 +1624,15 @@ var vex = (config) => {
1529
1624
  app.get("/", async (c) => c.json(await handleDiscovery(await requestConfig(c))));
1530
1625
  app.post("/", async (c) => {
1531
1626
  const scope = config.getScope ? await config.getScope(c) : {};
1532
- const body = await c.req.json();
1533
- const result = await handleQuery(await requestConfig(c), body, scope, liveOf(c.env));
1627
+ const read = await jsonBodyOf(c);
1628
+ if (!read.parsed) return c.json(NOT_JSON, 400);
1629
+ const result = await handleQuery(await requestConfig(c), read.body, scope, liveOf(c.env));
1534
1630
  return c.json(result.body, result.status);
1535
1631
  });
1536
1632
  app.patch("/", async (c) => {
1537
- const body = await c.req.json();
1633
+ const read = await jsonBodyOf(c);
1634
+ if (!read.parsed) return c.json(NOT_JSON, 400);
1635
+ const body = read.body;
1538
1636
  const fingerprint = fingerprintFromBody(body);
1539
1637
  if (fingerprint === void 0) {
1540
1638
  return c.json({ error: "invalid_request", message: "Body must include { fingerprint }" }, 400);
@@ -1546,8 +1644,9 @@ var vex = (config) => {
1546
1644
  return c.json(result.body, result.status);
1547
1645
  });
1548
1646
  app.delete("/", async (c) => {
1549
- const body = await c.req.json();
1550
- const fingerprint = fingerprintFromBody(body);
1647
+ const read = await jsonBodyOf(c);
1648
+ if (!read.parsed) return c.json(NOT_JSON, 400);
1649
+ const fingerprint = fingerprintFromBody(read.body);
1551
1650
  if (fingerprint === void 0) {
1552
1651
  return c.json({ error: "invalid_request", message: "Body must include { fingerprint }" }, 400);
1553
1652
  }