@niscorp/vex 0.2.2 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. package/CHANGELOG.md +172 -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
@@ -354,6 +354,7 @@ var computeSchemaFingerprint = (schema) => {
354
354
  };
355
355
 
356
356
  // src/errors.ts
357
+ var VEX_ERROR = /* @__PURE__ */ Symbol.for("@niscorp/vex:VexError");
357
358
  var VexError = class extends Error {
358
359
  code;
359
360
  details;
@@ -364,6 +365,8 @@ var VexError = class extends Error {
364
365
  this.details = details;
365
366
  }
366
367
  };
368
+ Object.defineProperty(VexError.prototype, VEX_ERROR, { value: true });
369
+ var isVexError = (err) => err instanceof VexError || err instanceof Error && Reflect.get(err, VEX_ERROR) === true;
367
370
 
368
371
  // src/engine/optional.ts
369
372
  var refuseOptional = (where) => {
@@ -642,13 +645,21 @@ var LookupSchema = zod.z.object({
642
645
  where: FilterSchema.describe("Bounds the lookup \u2014 should match at most one row")
643
646
  }).strict()
644
647
  }).strict().describe("Scalar subquery: reads one value from another table at write time; read scope rules apply");
648
+ var ReturnedSchema = zod.z.object({
649
+ $returned: FieldPathSchema.describe(
650
+ "`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."
651
+ )
652
+ }).strict().describe(
653
+ "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`."
654
+ );
645
655
  var ValueSchema = zod.z.union([
646
656
  zod.z.string(),
647
657
  zod.z.number(),
648
658
  zod.z.boolean(),
649
659
  zod.z.null(),
650
660
  zod.z.object({ $context: zod.z.string() }).strict(),
651
- LookupSchema
661
+ LookupSchema,
662
+ ReturnedSchema
652
663
  ]);
653
664
  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" });
654
665
  var OnConflictSchema = zod.z.object({
@@ -746,17 +757,23 @@ var walkFilter = (filter, schema, sig) => {
746
757
  };
747
758
  var isLookupRef = (v) => v !== null && typeof v === "object" && !Array.isArray(v) && "$lookup" in v;
748
759
  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 ?? {} } : {};
760
+ var positionsSetBy = (m) => {
761
+ const positions = (cols, insertOnly = false) => Object.entries(cols ?? {}).map(([column, value]) => ({ column, value, insertOnly }));
762
+ if (m.op === "insert" || m.op === "insertEach") return [...positions(m.values), ...positions(m.onConflict?.set)];
763
+ if (m.op === "update") return positions(m.set);
764
+ if (m.op === "upsert") return [...positions(m.columns), ...positions(m.insert, true)];
765
+ return [];
766
+ };
749
767
  var collectMutationContext = (def, schema) => {
750
768
  const sig = {};
751
769
  const list = Array.isArray(def) ? def : [def];
752
770
  for (const m of list) {
753
- for (const [col, v] of Object.entries(columnsOf(m))) {
771
+ for (const { column: col, value: v, insertOnly } of positionsSetBy(m)) {
754
772
  if (isLookupRef(v)) {
755
773
  walkFilter(v.$lookup.where, schema, sig);
756
774
  continue;
757
775
  }
758
776
  if (!isContextRef(v)) continue;
759
- const insertOnly = m.op === "upsert" && m.insert !== void 0 && col in m.insert;
760
777
  addField(sig, v.$context, { ...columnInfo(`${m.table}.${col}`, schema), ...insertOnly ? { note: "insert only" } : {} });
761
778
  }
762
779
  if (m.op === "update" || m.op === "delete") walkFilter(m.where, schema, sig);
@@ -794,8 +811,7 @@ var mutationEffect = (def) => {
794
811
  };
795
812
  var requiredContextKeys = (m) => {
796
813
  const keys = /* @__PURE__ */ new Set();
797
- const cols = m.op === "insert" || m.op === "insertEach" ? { ...m.values, ...m.onConflict?.set ?? {} } : m.op === "update" ? m.set : {};
798
- for (const v of Object.values(cols)) {
814
+ for (const { value: v } of positionsSetBy(m)) {
799
815
  if (isContextRef(v)) keys.add(v.$context);
800
816
  else if (isLookupRef(v)) {
801
817
  const sub = {};
@@ -811,10 +827,41 @@ var requiredContextKeys = (m) => {
811
827
  }
812
828
  return [...keys].sort();
813
829
  };
830
+ var isReturnedRef = (v) => v !== null && typeof v === "object" && !Array.isArray(v) && "$returned" in v && typeof v.$returned === "string";
831
+ var returnedIn = (list, at) => {
832
+ const refs = /* @__PURE__ */ new Map();
833
+ const issues = [];
834
+ const m = list[at];
835
+ if (m === void 0) return { refs, issues };
836
+ const judged = /* @__PURE__ */ new Set();
837
+ for (const { value: v } of positionsSetBy(m)) {
838
+ if (!isReturnedRef(v) || judged.has(v.$returned)) continue;
839
+ judged.add(v.$returned);
840
+ const dot = v.$returned.indexOf(".");
841
+ const table = v.$returned.slice(0, dot);
842
+ const column = v.$returned.slice(dot + 1);
843
+ const reads = `${m.op} on "${m.table}" reads "${v.$returned}"`;
844
+ const earlier = list.flatMap((s, i) => i < at && s.table === table ? [{ s, i }] : []);
845
+ const source = earlier[0];
846
+ if (source === void 0) {
847
+ issues.push(`${reads}, and no earlier statement writes "${table}" \u2014 put the statement that writes it before this one, in the same batch`);
848
+ } else if (earlier.length > 1) {
849
+ issues.push(`${reads}, and ${earlier.length} earlier statements write "${table}" \u2014 a reference cannot tell them apart`);
850
+ } else if (source.s.op === "insertEach") {
851
+ issues.push(`${reads} from an insertEach, which writes a row per element \u2014 there is no one row to read`);
852
+ } else if (source.s.op === "insert" && source.s.onConflict !== void 0 && source.s.onConflict.set === void 0) {
853
+ issues.push(`${reads} from an insert that does nothing on conflict, which then returns no row \u2014 give its onConflict a \`set\``);
854
+ } else {
855
+ refs.set(v.$returned, { statement: source.i, table, column });
856
+ }
857
+ }
858
+ return { refs, issues };
859
+ };
814
860
 
815
861
  // src/mutations/engine.ts
816
862
  var isLookup = (v) => v !== null && typeof v === "object" && !Array.isArray(v) && "$lookup" in v;
817
863
  var isItemRef = (v) => v !== null && typeof v === "object" && !Array.isArray(v) && "$item" in v;
864
+ var isReturned = (v) => v !== null && typeof v === "object" && !Array.isArray(v) && "$returned" in v;
818
865
  var collectLookups = (m) => {
819
866
  const out = [];
820
867
  const scan = (cols) => {
@@ -912,6 +959,13 @@ var assertWritableColumns = (m, schema) => {
912
959
  if (m.onConflict.where !== void 0) assertFilterColumns(m.onConflict.where, m.table, schema, "onConflict");
913
960
  }
914
961
  };
962
+ var assertReturnedColumns = (refs, schema) => {
963
+ for (const [ref, source] of refs) {
964
+ if (findEntity(source.table, schema)?.fields.some((f) => f.name === source.column) !== true) {
965
+ throw new VexError("invalid_dsl", `Unknown column "${ref}" in $returned.`);
966
+ }
967
+ }
968
+ };
915
969
  var readMatchesFor = (table, policy) => {
916
970
  const rule = policy.entities[table];
917
971
  if (rule === void 0) {
@@ -1020,7 +1074,8 @@ var newCtx = () => ({
1020
1074
  resolvedPaths: /* @__PURE__ */ new Map(),
1021
1075
  aliasMap: /* @__PURE__ */ new Map(),
1022
1076
  paramSlots: [],
1023
- paramCounter: { value: 0 }
1077
+ paramCounter: { value: 0 },
1078
+ returned: /* @__PURE__ */ new Map()
1024
1079
  });
1025
1080
  var indexFilterFields = (filter, aliasMap) => {
1026
1081
  for (const path of filterColumns(filter)) aliasMap.set(path, path);
@@ -1031,13 +1086,19 @@ var compileValue = (v, ctx) => {
1031
1086
  const where = compileFilter(v.$lookup.where, ctx);
1032
1087
  return `(SELECT ${v.$lookup.field} FROM ${v.$lookup.from} WHERE ${where})`;
1033
1088
  }
1089
+ if (isReturned(v)) {
1090
+ ctx.paramCounter.value += 1;
1091
+ ctx.returned.set(ctx.paramSlots.length, v.$returned);
1092
+ ctx.paramSlots.push({ key: v.$returned, kind: "context", type: "string" });
1093
+ return `$${ctx.paramCounter.value}`;
1094
+ }
1034
1095
  return compileFieldOrValue(v, ctx);
1035
1096
  };
1036
1097
  var compileColumnValue = (table, column, v, ctx, schema) => {
1037
1098
  const before = ctx.paramSlots.length;
1038
1099
  const sql = compileValue(v, ctx);
1039
1100
  const json = findEntity(table, schema)?.fields.find((f) => f.name === column)?.normalizedType === "json";
1040
- if (json && typeof v === "object" && v !== null && "$context" in v) {
1101
+ if (json && typeof v === "object" && v !== null && ("$context" in v || "$returned" in v)) {
1041
1102
  const slot = ctx.paramSlots[before];
1042
1103
  if (slot !== void 0) ctx.paramSlots[before] = { ...slot, encode: "json" };
1043
1104
  }
@@ -1068,7 +1129,7 @@ var compileMutation = (m, schema) => {
1068
1129
  const entries = Object.entries(m.values);
1069
1130
  const cols = entries.map(([c]) => c);
1070
1131
  const vals = entries.map(([c, v]) => compileColumnValue(m.table, c, v, ctx, schema));
1071
- return { sql: `INSERT INTO ${m.table} (${cols.join(", ")}) VALUES (${vals.join(", ")})${compileConflict(m, ctx, schema)} RETURNING *`, slots: ctx.paramSlots };
1132
+ return { sql: `INSERT INTO ${m.table} (${cols.join(", ")}) VALUES (${vals.join(", ")})${compileConflict(m, ctx, schema)} RETURNING *`, slots: ctx.paramSlots, returned: ctx.returned };
1072
1133
  }
1073
1134
  if (m.op === "insertEach") {
1074
1135
  const entity = findEntity(m.table, schema);
@@ -1082,25 +1143,26 @@ var compileMutation = (m, schema) => {
1082
1143
  const raw = `(item.value->>${quoteLiteral(v.$item)})`;
1083
1144
  return cast === void 0 ? raw : `${raw}::${cast}`;
1084
1145
  }
1085
- return compileValue(v, ctx);
1146
+ return isReturned(v) ? compileColumnValue(m.table, col, v, ctx, schema) : compileValue(v, ctx);
1086
1147
  });
1087
1148
  ctx.paramCounter.value += 1;
1088
1149
  ctx.paramSlots.push({ key: m.items.$context, kind: "context", type: "json" });
1089
1150
  const source = `jsonb_array_elements($${ctx.paramCounter.value}::jsonb) AS item`;
1090
1151
  return {
1091
1152
  sql: `INSERT INTO ${m.table} (${cols.join(", ")}) SELECT ${exprs.join(", ")} FROM ${source}${compileConflict(m, ctx, schema)} RETURNING *`,
1092
- slots: ctx.paramSlots
1153
+ slots: ctx.paramSlots,
1154
+ returned: ctx.returned
1093
1155
  };
1094
1156
  }
1095
1157
  if (m.op === "update") {
1096
1158
  const sets = Object.entries(m.set).map(([c, v]) => `${c} = ${compileColumnValue(m.table, c, v, ctx, schema)}`);
1097
1159
  indexFilterFields(m.where, ctx.aliasMap);
1098
1160
  const where2 = compileFilter(m.where, ctx);
1099
- return { sql: `UPDATE ${m.table} SET ${sets.join(", ")} WHERE ${where2} RETURNING *`, slots: ctx.paramSlots };
1161
+ return { sql: `UPDATE ${m.table} SET ${sets.join(", ")} WHERE ${where2} RETURNING *`, slots: ctx.paramSlots, returned: ctx.returned };
1100
1162
  }
1101
1163
  indexFilterFields(m.where, ctx.aliasMap);
1102
1164
  const where = compileFilter(m.where, ctx);
1103
- return { sql: `DELETE FROM ${m.table} WHERE ${where} RETURNING *`, slots: ctx.paramSlots };
1165
+ return { sql: `DELETE FROM ${m.table} WHERE ${where} RETURNING *`, slots: ctx.paramSlots, returned: ctx.returned };
1104
1166
  };
1105
1167
  var SUGAR = {
1106
1168
  upsert: (m, context) => {
@@ -1115,24 +1177,47 @@ var desugarMutation = (m, context) => {
1115
1177
  var executeWrites = async (client, def, mctx) => {
1116
1178
  const parsed = MutationDefinitionSchema.parse(def);
1117
1179
  const entries = Array.isArray(parsed) ? parsed : [parsed];
1118
- const compiled = entries.map((entry) => {
1119
- const core = desugarMutation(entry, mctx.context);
1180
+ const cores = entries.map((entry) => desugarMutation(entry, mctx.context));
1181
+ const compiled = cores.map((core, at) => {
1120
1182
  const missing = requiredContextKeys(core).filter((k) => mctx.context[k] === void 0);
1121
1183
  if (missing.length > 0) {
1122
1184
  throw new VexError("missing_context", `Mutation is missing context: ${missing.join(", ")}.`, {
1123
1185
  expected: collectMutationContext(parsed, mctx.schema)
1124
1186
  });
1125
1187
  }
1188
+ const returned = returnedIn(cores, at);
1189
+ if (returned.issues.length > 0) throw new VexError("invalid_dsl", `${returned.issues.join("; ")}.`);
1126
1190
  const m = scopeMutation(core, mctx.policy);
1127
1191
  assertWritableColumns(m, mctx.schema);
1192
+ assertReturnedColumns(returned.refs, mctx.schema);
1128
1193
  const statement = compileMutation(m, mctx.schema);
1129
1194
  requireScope({ paramSlots: statement.slots }, mctx.scope);
1130
- return { ...statement, table: m.table, op: m.op === "insertEach" ? "insert" : m.op };
1195
+ const reads = [...statement.returned].map(([slot, ref]) => {
1196
+ const source = returned.refs.get(ref);
1197
+ if (source === void 0) throw new VexError("invalid_dsl", `"${ref}" names no earlier statement of the batch.`);
1198
+ return { slot, ref, source };
1199
+ });
1200
+ return { ...statement, reads, table: m.table, op: m.op === "insertEach" ? "insert" : m.op };
1131
1201
  });
1132
1202
  const runAll = async (q) => {
1133
1203
  const results = [];
1134
1204
  for (const c of compiled) {
1135
1205
  const params = await resolveParams(c.slots, mctx.context, mctx.scope);
1206
+ for (const read of c.reads) {
1207
+ const rows = results[read.source.statement]?.rows ?? [];
1208
+ const row = rows[0];
1209
+ if (rows.length !== 1 || row === void 0) {
1210
+ throw new VexError(
1211
+ "execution_error",
1212
+ `"${read.ref}" needs exactly one row from statement ${read.source.statement + 1} of the batch, which wrote ${rows.length}. Nothing was written.`,
1213
+ { returned: read.ref, rows: rows.length }
1214
+ );
1215
+ }
1216
+ if (!(read.source.column in row)) {
1217
+ 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 });
1218
+ }
1219
+ params[read.slot] = row[read.source.column];
1220
+ }
1136
1221
  const bound = params.map((value, i) => {
1137
1222
  if (c.slots[i]?.encode === "json") return value !== null && typeof value === "object" ? JSON.stringify(value) : value;
1138
1223
  if (c.slots[i]?.type !== "json") return value;
@@ -1430,11 +1515,11 @@ var runQuery = async (config, body, scope, probe, live) => {
1430
1515
  }
1431
1516
  return { status: 200, body: response };
1432
1517
  } catch (err) {
1433
- if (err instanceof VexError && err.code === "missing_scope") {
1518
+ if (isVexError(err) && err.code === "missing_scope") {
1434
1519
  console.error("[vex] refused a statement the host did not scope:", err.message);
1435
1520
  return { status: 500, body: { error: "missing_scope", message: "The server did not supply the scope this request needs." } };
1436
1521
  }
1437
- if (err instanceof VexError) {
1522
+ if (isVexError(err)) {
1438
1523
  const status = err.code === "fingerprint_protected" ? 409 : err.code === "cache_miss" ? 404 : 400;
1439
1524
  return {
1440
1525
  status,