@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.
- package/CHANGELOG.md +121 -0
- package/DESIGN.md +66 -3
- package/DOCS.md +156 -12
- package/dist/adapters/express/index.cjs +102 -17
- package/dist/adapters/express/index.cjs.map +1 -1
- package/dist/adapters/express/index.d.cts +2 -2
- package/dist/adapters/express/index.d.ts +2 -2
- package/dist/adapters/express/index.js +2 -2
- package/dist/adapters/hono/index.cjs +121 -22
- package/dist/adapters/hono/index.cjs.map +1 -1
- package/dist/adapters/hono/index.d.cts +2 -2
- package/dist/adapters/hono/index.d.ts +2 -2
- package/dist/adapters/hono/index.js +21 -7
- package/dist/adapters/hono/index.js.map +1 -1
- package/dist/agent/index.cjs +2 -0
- package/dist/agent/index.cjs.map +1 -1
- package/dist/agent/index.d.cts +1 -1
- package/dist/agent/index.d.ts +1 -1
- package/dist/agent/index.js +1 -1
- package/dist/{chunk-HF25Q53I.js → chunk-H4BHW76Q.js} +6 -3
- package/dist/chunk-H4BHW76Q.js.map +1 -0
- package/dist/{chunk-HCEH55PP.js → chunk-IQM4SQE2.js} +123 -21
- package/dist/chunk-IQM4SQE2.js.map +1 -0
- package/dist/{handler-Cql8SJ3F.d.cts → handler-BGCL6_Si.d.ts} +3 -2
- package/dist/{handler-mICf9ins.d.ts → handler-CMrjTXNx.d.cts} +3 -2
- package/dist/index.cjs +163 -35
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +3 -3
- package/dist/index.d.ts +3 -3
- package/dist/index.js +44 -22
- package/dist/index.js.map +1 -1
- package/dist/{types-BRvMB6IM.d.cts → types-Bi-Lg86b.d.cts} +48 -2
- package/dist/{types-BRvMB6IM.d.ts → types-Bi-Lg86b.d.ts} +48 -2
- package/package.json +5 -5
- package/dist/chunk-HCEH55PP.js.map +0 -1
- 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
|
|
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
|
|
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
|
|
1119
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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,
|