runtime-api: translate REST query strings to LuaCollectionQuery

This commit is contained in:
Zef Hemel
2026-05-14 16:04:50 +02:00
parent 1d39ba38ec
commit f8d02e4a78
2 changed files with 334 additions and 0 deletions
+167
View File
@@ -0,0 +1,167 @@
import { expect, test } from "vitest";
import {
translateListRequest,
serializeLuaValue,
type Filter,
} from "./translate_query.ts";
test("serializeLuaValue: numbers, booleans, null, strings", () => {
expect(serializeLuaValue("42")).toBe("42");
expect(serializeLuaValue("-3.14")).toBe("-3.14");
expect(serializeLuaValue("true")).toBe("true");
expect(serializeLuaValue("false")).toBe("false");
expect(serializeLuaValue("null")).toBe("nil");
expect(serializeLuaValue("hello")).toBe('"hello"');
expect(serializeLuaValue('a"b\nc')).toBe('"a\\"b\\nc"');
});
test("serializeLuaValue: explicit type prefix overrides inference", () => {
expect(serializeLuaValue("num:42")).toBe("42");
expect(serializeLuaValue("str:42")).toBe('"42"');
expect(serializeLuaValue("bool:true")).toBe("true");
});
test("translateListRequest: equality filter", () => {
const out = translateListRequest({
tag: "task",
filters: [{ field: "done", op: "eq", value: "false" }],
order: [],
limit: 100,
offset: 0,
});
expect(out.equivalentLua).toBe(
`from _it = index.tag("task") where _it.done == false limit 100`,
);
});
test("translateListRequest: every operator emits expected source", () => {
const cases: Array<[Filter["op"], string, string]> = [
["ne", "5", "_it.f ~= 5"],
["gt", "5", "_it.f > 5"],
["gte", "5", "_it.f >= 5"],
["lt", "5", "_it.f < 5"],
["lte", "5", "_it.f <= 5"],
["startsWith", "Hi", `string.sub(_it.f, 1, #"Hi") == "Hi"`],
["contains", "x", `string.find(_it.f, "x", 1, true) ~= nil`],
];
for (const [op, raw, expectedClause] of cases) {
const out = translateListRequest({
tag: "x",
filters: [{ field: "f", op, value: raw }],
order: [],
limit: 10,
offset: 0,
});
expect(out.equivalentLua).toContain(expectedClause);
}
});
test("translateListRequest: in operator expands to or-chain", () => {
const out = translateListRequest({
tag: "x",
filters: [{ field: "status", op: "in", value: "a,b,c" }],
order: [],
limit: 10,
offset: 0,
});
expect(out.equivalentLua).toContain(
`(_it.status == "a") or (_it.status == "b") or (_it.status == "c")`,
);
});
test("translateListRequest: multiple filters are AND-ed", () => {
const out = translateListRequest({
tag: "task",
filters: [
{ field: "done", op: "eq", value: "false" },
{ field: "priority", op: "gte", value: "2" },
],
order: [],
limit: 50,
offset: 0,
});
expect(out.equivalentLua).toContain(
`where (_it.done == false) and (_it.priority >= 2)`,
);
});
test("translateListRequest: ordering, offset, select", () => {
const out = translateListRequest({
tag: "page",
filters: [],
order: [
{ field: "lastModified", desc: true },
{ field: "name", desc: false },
],
limit: 10,
offset: 20,
select: ["name", "lastModified"],
});
expect(out.equivalentLua).toContain(
"order by _it.lastModified desc, _it.name",
);
expect(out.equivalentLua).toContain("limit 10, 20");
expect(out.equivalentLua).toContain(
"select { name = _it.name, lastModified = _it.lastModified }",
);
});
test("translateListRequest: dotted field paths allowed", () => {
const out = translateListRequest({
tag: "page",
filters: [{ field: "meta.author", op: "eq", value: "alice" }],
order: [],
limit: 10,
offset: 0,
});
expect(out.equivalentLua).toContain(`_it.meta.author == "alice"`);
});
test("translateListRequest rejects bad field paths", () => {
expect(() =>
translateListRequest({
tag: "x",
filters: [{ field: "1bad", op: "eq", value: "v" }],
order: [],
limit: 10,
offset: 0,
}),
).toThrow(/bad_field/);
expect(() =>
translateListRequest({
tag: "x",
filters: [{ field: "a; drop", op: "eq", value: "v" }],
order: [],
limit: 10,
offset: 0,
}),
).toThrow(/bad_field/);
});
test("translateListRequest: empty in-list rejected", () => {
expect(() =>
translateListRequest({
tag: "x",
filters: [{ field: "f", op: "in", value: "" }],
order: [],
limit: 10,
offset: 0,
}),
).toThrow(/bad_query/);
});
test("translateListRequest: result also produces a LuaCollectionQuery", () => {
const out = translateListRequest({
tag: "task",
filters: [{ field: "done", op: "eq", value: "false" }],
order: [{ field: "priority", desc: true }],
limit: 5,
offset: 0,
});
expect(out.query.limit).toBe(5);
expect(out.query.offset).toBe(0);
expect(out.query.where).toBeDefined();
expect(out.query.orderBy).toHaveLength(1);
expect(out.query.objectVariable).toBe("_it");
});
+167
View File
@@ -0,0 +1,167 @@
import { parseExpressionString } from "../space_lua/parse.ts";
import type {
LuaCollectionQuery,
LuaOrderBy,
} from "../space_lua/query_collection.ts";
import type { LuaExpression } from "../space_lua/ast.ts";
export type FilterOp =
| "eq"
| "ne"
| "gt"
| "gte"
| "lt"
| "lte"
| "in"
| "contains"
| "startsWith";
export type FilterValue = string;
export type Filter = { field: string; op: FilterOp; value: FilterValue };
export type OrderKey = { field: string; desc: boolean };
export type ListRequest = {
tag: string;
filters: Filter[];
order: OrderKey[];
limit: number;
offset: number;
select?: string[];
};
export type TranslatedQuery = {
query: LuaCollectionQuery;
equivalentLua: string;
};
const FIELD_PATH_RE = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/;
export class TranslationError extends Error {
constructor(
public code: string,
public cause: string,
) {
super(`${code}: ${cause}`);
}
}
function validateField(field: string): string {
if (!FIELD_PATH_RE.test(field)) {
throw new TranslationError("bad_field", `invalid field path: ${field}`);
}
return field;
}
export function serializeLuaValue(raw: FilterValue): string {
if (raw.startsWith("num:")) return String(Number(raw.slice(4)));
if (raw.startsWith("str:")) return JSON.stringify(raw.slice(4));
if (raw.startsWith("bool:"))
return raw.slice(5) === "true" ? "true" : "false";
if (/^-?\d+(\.\d+)?$/.test(raw)) return raw;
if (raw === "true" || raw === "false") return raw;
if (raw === "null") return "nil";
return JSON.stringify(raw);
}
function clauseFor(filter: Filter): string {
const f = `_it.${validateField(filter.field)}`;
switch (filter.op) {
case "eq":
return `${f} == ${serializeLuaValue(filter.value)}`;
case "ne":
return `${f} ~= ${serializeLuaValue(filter.value)}`;
case "gt":
return `${f} > ${serializeLuaValue(filter.value)}`;
case "gte":
return `${f} >= ${serializeLuaValue(filter.value)}`;
case "lt":
return `${f} < ${serializeLuaValue(filter.value)}`;
case "lte":
return `${f} <= ${serializeLuaValue(filter.value)}`;
case "startsWith": {
const lit = serializeLuaValue(filter.value);
return `string.sub(${f}, 1, #${lit}) == ${lit}`;
}
case "contains": {
const lit = serializeLuaValue(filter.value);
return `string.find(${f}, ${lit}, 1, true) ~= nil`;
}
case "in": {
const parts = filter.value
.split(",")
.map((p) => p.trim())
.filter(Boolean);
if (parts.length === 0) {
throw new TranslationError(
"bad_query",
"in operator requires at least one value",
);
}
return parts.map((p) => `(${f} == ${serializeLuaValue(p)})`).join(" or ");
}
}
throw new TranslationError(
"unknown_operator",
`unknown operator: ${(filter as any).op}`,
);
}
export function translateListRequest(req: ListRequest): TranslatedQuery {
const tag = req.tag;
if (!tag) throw new TranslationError("bad_query", "tag is required");
// Defensive coercion: callers serializing across the bridge may end up
// with `null` here when no filters/order are present.
const filters = req.filters ?? [];
const order = req.order ?? [];
const rawClauses = filters.map((f) => clauseFor(f));
const whereClauses = rawClauses.map((c) => `(${c})`);
const whereStr =
rawClauses.length === 0
? ""
: rawClauses.length === 1
? rawClauses[0]
: whereClauses.join(" and ");
const orderStr = order
.map((o) => `_it.${validateField(o.field)}${o.desc ? " desc" : ""}`)
.join(", ");
const selectStr = req.select
? `{ ${req.select.map((f) => `${validateField(f)} = _it.${f}`).join(", ")} }`
: "";
const parts: string[] = [`from _it = index.tag(${JSON.stringify(tag)})`];
if (whereStr) parts.push(`where ${whereStr}`);
if (orderStr) parts.push(`order by ${orderStr}`);
if (selectStr) parts.push(`select ${selectStr}`);
parts.push(
req.offset > 0 ? `limit ${req.limit}, ${req.offset}` : `limit ${req.limit}`,
);
const equivalentLua = parts.join(" ");
const query: LuaCollectionQuery = {
objectVariable: "_it",
limit: req.limit,
offset: req.offset,
};
if (whereStr) {
query.where = parseExpressionString(
whereClauses.length === 1 ? whereClauses[0].slice(1, -1) : whereStr,
) as LuaExpression;
}
if (order.length) {
query.orderBy = order.map<LuaOrderBy>((o) => ({
expr: parseExpressionString(`_it.${o.field}`) as LuaExpression,
desc: o.desc,
}));
}
if (req.select?.length) {
query.select = parseExpressionString(selectStr) as LuaExpression;
}
return { query, equivalentLua };
}