spice-js 2.7.40 → 2.7.41

package/build/index.js

@@ -1,7 +1,7 @@
 "use strict";
 
 exports.__esModule = true;
-exports.status = exports.default = exports.addTask = exports.Storage = exports.SpiceModel = exports.SpiceEventDriver = exports.SpiceCache = exports.SocketEventDriver = exports.Serializer = exports.RestHelper = exports.ResourceReloader = exports.ResourceLifecycleTriggered = exports.MapType = exports.MailFile = exports.MailDebug = exports.Mail = exports.LocalStorage = exports.EventDebugger = exports.Event = exports.DebugStorage = exports.DataType = exports.Crypt = exports.AI = void 0;
+exports.status = exports.default = exports.addTask = exports.Storage = exports.SpiceModel = exports.SpiceEventDriver = exports.SpiceCache = exports.SocketEventDriver = exports.Serializer = exports.RestHelper = exports.ResourceReloader = exports.ResourceLifecycleTriggered = exports.MapType = exports.MailFile = exports.MailDebug = exports.Mail = exports.LocalStorage = exports.IndexKeys = exports.EventDebugger = exports.Event = exports.DebugStorage = exports.DataType = exports.Crypt = exports.AI = void 0;
 var _Event = _interopRequireDefault(require("./events/Event"));
 exports.Event = _Event.default;
 var _EventDebugger = _interopRequireDefault(require("./events/providers/EventDebugger"));
@@ -20,6 +20,8 @@ var _Serializer = _interopRequireDefault(require("./utility/Serializer"));
 exports.Serializer = _Serializer.default;
 var _RestHelper = _interopRequireDefault(require("./utility/RestHelper"));
 exports.RestHelper = _RestHelper.default;
+var _IndexKeys = _interopRequireDefault(require("./utility/IndexKeys"));
+exports.IndexKeys = _IndexKeys.default;
 var _ResourceReloader = _interopRequireDefault(require("./utility/ResourceReloader"));
 exports.ResourceReloader = _ResourceReloader.default;
 var _Status = _interopRequireDefault(require("./utility/Status"));

package/build/models/SpiceModel.js

@@ -7,6 +7,7 @@ var _ResourceLifecycleTriggered = _interopRequireDefault(require("../events/even
 var _Security = require("../utility/Security");
 var _fix = require("../utility/fix");
 var _propertyDefaults = require("../utility/propertyDefaults");
+var _IndexKeys = require("../utility/IndexKeys");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 function _extends() { return _extends = Object.assign ? Object.assign.bind() : function (n) { for (var e = 1; e < arguments.length; e++) { var t = arguments[e]; for (var r in t) { ({}).hasOwnProperty.call(t, r) && (n[r] = t[r]); } } return n; }, _extends.apply(null, arguments); }
 function asyncGeneratorStep(n, t, e, r, o, a, c) { try { var i = n[a](c), u = i.value; } catch (n) { return void e(n); } i.done ? t(u) : Promise.resolve(u).then(r, o); }
@@ -775,7 +776,13 @@ class SpiceModel {
     return {
       scan_consistency: scanConsistency,
       consistent_with: args.consistent_with,
-      scan_wait: args.scan_wait
+      scan_wait: args.scan_wait,
+      // With scan_wait: read without waiting when the index is not current in time, instead of
+      // failing. For reads where a slightly stale answer is better than an error.
+      scan_wait_fallback: args.scan_wait_fallback,
+      // Shows up as clientContextID in system:completed_requests, so a slow statement can be
+      // traced back to the route or job that ran it.
+      client_context_id: args.client_context_id
     };
   }
   requiresFreshQuery(args) {
@@ -1468,15 +1475,17 @@ class SpiceModel {
           // Build JOIN/NEST from the mapped keyspaces
           args._join = _this10.createJoinSection(mappedNestings);
 
-          // WHERE
+          // WHERE. The caller's query is parenthesised so a top-level OR cannot swallow the live
+          // condition, which has to stay a top-level conjunct for the partial indexes to apply.
           var query = "";
-          var deletedCondition = "(`" + _this10.type + "`.deleted = false OR `" + _this10.type + "`.deleted IS MISSING)";
+          var deletedCondition = (0, _IndexKeys.liveCondition)(_this10.type);
           if (args.is_full_text === "true" || args.is_custom_query === "true") {
             query = args.query || "";
           } else if (args.filters) {
-            query = _this10.makeQueryFromFilter(args.filters);
+            var filterQuery = _this10.makeQueryFromFilter(args.filters);
+            query = filterQuery ? "(" + filterQuery + ") AND " + deletedCondition : deletedCondition;
           } else if (args.query) {
-            query = args.query + " AND " + deletedCondition;
+            query = "(" + args.query + ") AND " + deletedCondition;
           } else {
             query = deletedCondition;
           }
@@ -1485,7 +1494,8 @@ class SpiceModel {
           // LIMIT/OFFSET/SORT
           args.limit = Number(args.limit) || undefined;
           args.offset = Number(args.offset) || 0;
-          args.sort = args.sort ? args.sort.split(",").map(item => item.includes(".") ? item : "`" + _this10.type + "`." + _this10.formatSortComponent(item)).join(",") : "`" + _this10.type + "`.created_at DESC";
+          var joinAliases = (mappedNestings || []).map(nesting => nesting.alias);
+          args.sort = (0, _IndexKeys.orderByClause)(args.sort, _this10.type, joinAliases) || "`" + _this10.type + "`.`created_at` DESC";
           if (args.skip_hooks !== true) {
             yield _this10.run_hook(_this10, "list", "before");
           }

package/build/utility/IndexKeys.js

@@ -0,0 +1,163 @@
+"use strict";
+
+/**
+ * One definition of the live (not soft-deleted) predicate and of how a sort becomes ORDER BY
+ * terms and index keys. SpiceModel builds queries with it and the application's index planner
+ * builds indexes with it, so a query and the index meant to serve it can never drift apart.
+ *
+ * Couchbase cannot scan an index backwards and a plain ascending key puts MISSING and NULL first,
+ * so `ASC NULLS LAST` (what the UI sends) is expressed as `IFMISSINGORNULL(f, {})`: an empty
+ * object sorts after every scalar and array, which is exactly "empties last".
+ */
+exports.__esModule = true;
+exports.default = exports.LIVE_INDEX_CONDITION = void 0;
+exports.fieldIndexExpression = fieldIndexExpression;
+exports.liveCondition = liveCondition;
+exports.orderByClause = orderByClause;
+exports.orderByTerms = orderByTerms;
+exports.parseSort = parseSort;
+exports.sortIndexKeys = sortIndexKeys;
+exports.usesSentinel = usesSentinel;
+function _extends() { return _extends = Object.assign ? Object.assign.bind() : function (n) { for (var e = 1; e < arguments.length; e++) { var t = arguments[e]; for (var r in t) { ({}).hasOwnProperty.call(t, r) && (n[r] = t[r]); } } return n; }, _extends.apply(null, arguments); }
+var SEGMENT = /^[A-Za-z0-9_$-]+$/;
+var ITEM = /^(\S+?)(?:\s+(ASC|DESC))?(?:\s+NULLS\s+(FIRST|LAST))?$/i;
+var SENTINEL = "{}";
+function quoteSegment(segment) {
+  return "`" + segment + "`";
+}
+
+/** `deleted` = false or MISSING passes; true or NULL does not. No OR, so it can never be split
+ * into a UnionScan, and partial indexes can use the exact same text as their condition. */
+function liveCondition(alias) {
+  var field = alias ? quoteSegment(alias) + ".`deleted`" : "`deleted`";
+  return "IFMISSING(" + field + ", false) = false";
+}
+
+/** The partial-index condition every managed list index carries. */
+var LIVE_INDEX_CONDITION = exports.LIVE_INDEX_CONDITION = liveCondition();
+function parsePath(raw) {
+  var segments = String(raw).replace(/`/g, "").split(".");
+  if (segments.length === 0 || !segments.every(segment => SEGMENT.test(segment))) {
+    return null;
+  }
+  return segments;
+}
+function parseItem(item) {
+  if (item && typeof item === "object") {
+    var _ref, _item$property, _ref2, _item$order;
+    var _path = parsePath((_ref = (_item$property = item.property) != null ? _item$property : item.field) != null ? _ref : "");
+    if (!_path) return null;
+    var direction = String((_ref2 = (_item$order = item.order) != null ? _item$order : item.direction) != null ? _ref2 : "ASC").toUpperCase() === "DESC" ? "DESC" : "ASC";
+    var nulls = item.nulls ? String(item.nulls).toUpperCase() : undefined;
+    return {
+      path: _path,
+      direction,
+      nulls: nulls === "FIRST" || nulls === "LAST" ? nulls : undefined
+    };
+  }
+  var text = String(item != null ? item : "").trim().replace(/\s+/g, " ");
+  if (!text) return null;
+  var match = ITEM.exec(text);
+  if (!match) return null;
+  var path = parsePath(match[1]);
+  if (!path) return null;
+  return {
+    path,
+    direction: (match[2] || "ASC").toUpperCase(),
+    nulls: match[3] ? match[3].toUpperCase() : undefined
+  };
+}
+
+/**
+ * Parses `"a DESC NULLS LAST, b"`, `[{ property, order }]` or an array of strings into
+ * `[{ path, direction, nulls }]`. Items that are not a plain field path with an optional
+ * direction and nulls clause are dropped: the sort is interpolated into the statement and was
+ * never injection-checked.
+ */
+function parseSort(sort) {
+  if (sort === undefined || sort === null || sort === "") return [];
+  var items = Array.isArray(sort) ? sort : String(sort).split(",");
+  var parsed = [];
+  for (var item of items) {
+    var result = parseItem(item);
+    if (result) {
+      parsed.push(result);
+    } else if (String(item != null ? item : "").trim() !== "") {
+      console.warn("[spice] ignoring unsupported sort item: " + JSON.stringify(item));
+    }
+  }
+  return parsed;
+}
+
+/** Whether the item needs the empties-placement expression instead of the plain field. */
+function usesSentinel(item) {
+  return item.direction === "ASC" && item.nulls === "LAST" || item.direction === "DESC" && item.nulls === "FIRST";
+}
+function fieldReference(path, alias) {
+  var quoted = path.map(quoteSegment).join(".");
+  return alias ? quoteSegment(alias) + "." + quoted : quoted;
+}
+function sortExpression(item, alias) {
+  var field = fieldReference(item.path, alias);
+  return usesSentinel(item) ? "IFMISSINGORNULL(" + field + ", " + SENTINEL + ")" : field;
+}
+
+/**
+ * ORDER BY terms for parsed items. `alias` qualifies local fields; a path whose first segment is
+ * in `joinAliases` already names a joined keyspace and is left as is. A first segment equal to
+ * the alias is treated as an explicit qualification of a local field.
+ */
+function orderByTerms(items, alias, joinAliases) {
+  if (joinAliases === void 0) {
+    joinAliases = [];
+  }
+  var joins = new Set(joinAliases);
+  return items.map(item => {
+    var path = item.path;
+    var qualifier = alias;
+    if (path.length > 1 && path[0] === alias) {
+      path = path.slice(1);
+    } else if (path.length > 1 && joins.has(path[0])) {
+      qualifier = undefined;
+    }
+    return sortExpression(_extends({}, item, {
+      path
+    }), qualifier) + " " + item.direction;
+  });
+}
+function orderByClause(sort, alias, joinAliases) {
+  if (joinAliases === void 0) {
+    joinAliases = [];
+  }
+  return orderByTerms(parseSort(sort), alias, joinAliases).join(", ");
+}
+
+/**
+ * Index keys for parsed items, unqualified, in sort order: `{ expr, desc, field, sentinel }`.
+ * `field` is the plain dotted path, which the planner also adds as a trailing key for every
+ * sentinel key so a flipped header sort is still covered by the same index.
+ */
+function sortIndexKeys(items) {
+  return items.map(item => ({
+    expr: sortExpression(item),
+    desc: item.direction === "DESC",
+    field: item.path.join("."),
+    sentinel: usesSentinel(item)
+  }));
+}
+
+/** An unqualified, backtick-quoted reference to a dotted field path, as an index key. */
+function fieldIndexExpression(fieldPath) {
+  var path = parsePath(fieldPath);
+  return path ? fieldReference(path) : null;
+}
+var _default = exports.default = {
+  liveCondition,
+  LIVE_INDEX_CONDITION,
+  parseSort,
+  usesSentinel,
+  orderByTerms,
+  orderByClause,
+  sortIndexKeys,
+  fieldIndexExpression
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spice-js",
-  "version": "2.7.40",
+  "version": "2.7.41",
   "description": "spice",
   "main": "build/index.js",
   "repository": {

package/src/index.js

@@ -27,6 +27,8 @@ export { default as Serializer } from "./utility/Serializer";
 
 export { default as RestHelper } from "./utility/RestHelper";
 
+export { default as IndexKeys } from "./utility/IndexKeys";
+
 export { default as ResourceReloader } from "./utility/ResourceReloader";
 import Status from "./utility/Status";
 export { default as Mail } from "./mail/Mail";

package/src/models/SpiceModel.js

@@ -7,6 +7,7 @@ import ResourceLifecycleTriggered from "../events/events/ResourceLifecycleTrigge
 import { hasSQLInjection } from "../utility/Security";
 import { fixCollection } from "../utility/fix";
 import { applyPropertyDefaults } from "../utility/propertyDefaults";
+import { liveCondition, orderByClause } from "../utility/IndexKeys";
 
 var SDate = require("sonover-date"),
   UUID = require("uuid"),
@@ -849,6 +850,12 @@ export default class SpiceModel {
       scan_consistency: scanConsistency,
       consistent_with: args.consistent_with,
       scan_wait: args.scan_wait,
+      // With scan_wait: read without waiting when the index is not current in time, instead of
+      // failing. For reads where a slightly stale answer is better than an error.
+      scan_wait_fallback: args.scan_wait_fallback,
+      // Shows up as clientContextID in system:completed_requests, so a slow statement can be
+      // traced back to the route or job that ran it.
+      client_context_id: args.client_context_id,
     };
   }
 
@@ -1628,15 +1635,17 @@ export default class SpiceModel {
       // Build JOIN/NEST from the mapped keyspaces
       args._join = this.createJoinSection(mappedNestings);
 
-      // WHERE
+      // WHERE. The caller's query is parenthesised so a top-level OR cannot swallow the live
+      // condition, which has to stay a top-level conjunct for the partial indexes to apply.
       let query = "";
-      const deletedCondition = `(\`${this.type}\`.deleted = false OR \`${this.type}\`.deleted IS MISSING)`;
+      const deletedCondition = liveCondition(this.type);
       if (args.is_full_text === "true" || args.is_custom_query === "true") {
         query = args.query || "";
       } else if (args.filters) {
-        query = this.makeQueryFromFilter(args.filters);
+        const filterQuery = this.makeQueryFromFilter(args.filters);
+        query = filterQuery ? `(${filterQuery}) AND ${deletedCondition}` : deletedCondition;
       } else if (args.query) {
-        query = `${args.query} AND ${deletedCondition}`;
+        query = `(${args.query}) AND ${deletedCondition}`;
       } else {
         query = deletedCondition;
       }
@@ -1646,17 +1655,10 @@ export default class SpiceModel {
       // LIMIT/OFFSET/SORT
       args.limit = Number(args.limit) || undefined;
       args.offset = Number(args.offset) || 0;
+      const joinAliases = (mappedNestings || []).map((nesting) => nesting.alias);
       args.sort =
-        args.sort ?
-          args.sort
-            .split(",")
-            .map((item) =>
-              item.includes(".") ? item : (
-                `\`${this.type}\`.${this.formatSortComponent(item)}`
-              ),
-            )
-            .join(",")
-        : `\`${this.type}\`.created_at DESC`;
+        orderByClause(args.sort, this.type, joinAliases) ||
+        `\`${this.type}\`.\`created_at\` DESC`;
 
       if (args.skip_hooks !== true) {
         await this.run_hook(this, "list", "before");

package/src/utility/IndexKeys.js

@@ -0,0 +1,149 @@
+"use strict";
+
+/**
+ * One definition of the live (not soft-deleted) predicate and of how a sort becomes ORDER BY
+ * terms and index keys. SpiceModel builds queries with it and the application's index planner
+ * builds indexes with it, so a query and the index meant to serve it can never drift apart.
+ *
+ * Couchbase cannot scan an index backwards and a plain ascending key puts MISSING and NULL first,
+ * so `ASC NULLS LAST` (what the UI sends) is expressed as `IFMISSINGORNULL(f, {})`: an empty
+ * object sorts after every scalar and array, which is exactly "empties last".
+ */
+
+const SEGMENT = /^[A-Za-z0-9_$-]+$/;
+const ITEM = /^(\S+?)(?:\s+(ASC|DESC))?(?:\s+NULLS\s+(FIRST|LAST))?$/i;
+const SENTINEL = "{}";
+
+function quoteSegment(segment) {
+  return `\`${segment}\``;
+}
+
+/** `deleted` = false or MISSING passes; true or NULL does not. No OR, so it can never be split
+ * into a UnionScan, and partial indexes can use the exact same text as their condition. */
+export function liveCondition(alias) {
+  const field = alias ? `${quoteSegment(alias)}.\`deleted\`` : "`deleted`";
+  return `IFMISSING(${field}, false) = false`;
+}
+
+/** The partial-index condition every managed list index carries. */
+export const LIVE_INDEX_CONDITION = liveCondition();
+
+function parsePath(raw) {
+  const segments = String(raw).replace(/`/g, "").split(".");
+  if (segments.length === 0 || !segments.every((segment) => SEGMENT.test(segment))) {
+    return null;
+  }
+  return segments;
+}
+
+function parseItem(item) {
+  if (item && typeof item === "object") {
+    const path = parsePath(item.property ?? item.field ?? "");
+    if (!path) return null;
+    const direction = String(item.order ?? item.direction ?? "ASC").toUpperCase() === "DESC" ? "DESC" : "ASC";
+    const nulls = item.nulls ? String(item.nulls).toUpperCase() : undefined;
+    return { path, direction, nulls: nulls === "FIRST" || nulls === "LAST" ? nulls : undefined };
+  }
+
+  const text = String(item ?? "").trim().replace(/\s+/g, " ");
+  if (!text) return null;
+  const match = ITEM.exec(text);
+  if (!match) return null;
+  const path = parsePath(match[1]);
+  if (!path) return null;
+  return {
+    path,
+    direction: (match[2] || "ASC").toUpperCase(),
+    nulls: match[3] ? match[3].toUpperCase() : undefined,
+  };
+}
+
+/**
+ * Parses `"a DESC NULLS LAST, b"`, `[{ property, order }]` or an array of strings into
+ * `[{ path, direction, nulls }]`. Items that are not a plain field path with an optional
+ * direction and nulls clause are dropped: the sort is interpolated into the statement and was
+ * never injection-checked.
+ */
+export function parseSort(sort) {
+  if (sort === undefined || sort === null || sort === "") return [];
+  const items = Array.isArray(sort) ? sort : String(sort).split(",");
+  const parsed = [];
+  for (const item of items) {
+    const result = parseItem(item);
+    if (result) {
+      parsed.push(result);
+    } else if (String(item ?? "").trim() !== "") {
+      console.warn(`[spice] ignoring unsupported sort item: ${JSON.stringify(item)}`);
+    }
+  }
+  return parsed;
+}
+
+/** Whether the item needs the empties-placement expression instead of the plain field. */
+export function usesSentinel(item) {
+  return (item.direction === "ASC" && item.nulls === "LAST") || (item.direction === "DESC" && item.nulls === "FIRST");
+}
+
+function fieldReference(path, alias) {
+  const quoted = path.map(quoteSegment).join(".");
+  return alias ? `${quoteSegment(alias)}.${quoted}` : quoted;
+}
+
+function sortExpression(item, alias) {
+  const field = fieldReference(item.path, alias);
+  return usesSentinel(item) ? `IFMISSINGORNULL(${field}, ${SENTINEL})` : field;
+}
+
+/**
+ * ORDER BY terms for parsed items. `alias` qualifies local fields; a path whose first segment is
+ * in `joinAliases` already names a joined keyspace and is left as is. A first segment equal to
+ * the alias is treated as an explicit qualification of a local field.
+ */
+export function orderByTerms(items, alias, joinAliases = []) {
+  const joins = new Set(joinAliases);
+  return items.map((item) => {
+    let path = item.path;
+    let qualifier = alias;
+    if (path.length > 1 && path[0] === alias) {
+      path = path.slice(1);
+    } else if (path.length > 1 && joins.has(path[0])) {
+      qualifier = undefined;
+    }
+    return `${sortExpression({ ...item, path }, qualifier)} ${item.direction}`;
+  });
+}
+
+export function orderByClause(sort, alias, joinAliases = []) {
+  return orderByTerms(parseSort(sort), alias, joinAliases).join(", ");
+}
+
+/**
+ * Index keys for parsed items, unqualified, in sort order: `{ expr, desc, field, sentinel }`.
+ * `field` is the plain dotted path, which the planner also adds as a trailing key for every
+ * sentinel key so a flipped header sort is still covered by the same index.
+ */
+export function sortIndexKeys(items) {
+  return items.map((item) => ({
+    expr: sortExpression(item),
+    desc: item.direction === "DESC",
+    field: item.path.join("."),
+    sentinel: usesSentinel(item),
+  }));
+}
+
+/** An unqualified, backtick-quoted reference to a dotted field path, as an index key. */
+export function fieldIndexExpression(fieldPath) {
+  const path = parsePath(fieldPath);
+  return path ? fieldReference(path) : null;
+}
+
+export default {
+  liveCondition,
+  LIVE_INDEX_CONDITION,
+  parseSort,
+  usesSentinel,
+  orderByTerms,
+  orderByClause,
+  sortIndexKeys,
+  fieldIndexExpression,
+};

package/tests/models/SpiceModel.list-query.test.js

@@ -0,0 +1,58 @@
+const { createTestModel } = require("../helpers/modelFactory");
+
+const LIVE = "IFMISSING(`application`.`deleted`, false) = false";
+
+function stubSearch(model) {
+  model.database.search = jest.fn(async () => ({ data: [], total: null }));
+  return model.database.search;
+}
+
+async function listWith(args) {
+  const model = createTestModel({ type: "application" });
+  const search = stubSearch(model);
+  await model.list({ skip_hooks: true, skip_serialize: true, ...args });
+  const [, , query, , , sort, , , , options] = search.mock.calls[0];
+  return { query, sort, options };
+}
+
+describe("SpiceModel list query shape", () => {
+  test("a bare list filters on the live condition and sorts newest first", async () => {
+    const { query, sort } = await listWith({});
+    expect(query).toBe(LIVE);
+    expect(sort).toBe("`application`.`created_at` DESC");
+  });
+
+  test("a caller query with a top-level OR is parenthesised before the live condition", async () => {
+    const { query } = await listWith({ query: "status = 'a' OR status = 'b'" });
+    expect(query).toBe(`(status = 'a' OR status = 'b') AND ${LIVE}`);
+  });
+
+  test("the filters path also excludes soft-deleted records", async () => {
+    const { query } = await listWith({ filters: { status: ["open"] } });
+    expect(query).toBe(`( status LIKE 'open') AND ${LIVE}`);
+  });
+
+  test("custom queries are passed through untouched", async () => {
+    const model = createTestModel({ type: "application" });
+    model.database.query = jest.fn(async () => ({ data: [] }));
+    await model.list({ is_custom_query: "true", ids: ["x"], query: "SELECT 1", skip_hooks: true, skip_serialize: true });
+    expect(model.database.query.mock.calls[0][0]).toBe("SELECT 1");
+  });
+
+  test("a multi-column UI sort becomes index-matching ORDER BY terms", async () => {
+    const { sort } = await listWith({ sort: "priority DESC NULLS LAST, due_at ASC NULLS LAST" });
+    expect(sort).toBe("`application`.`priority` DESC, IFMISSINGORNULL(`application`.`due_at`, {}) ASC");
+  });
+
+  test("an unparseable sort falls back to the default instead of reaching the statement", async () => {
+    const warn = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const { sort } = await listWith({ sort: "created_at; DELETE" });
+    expect(sort).toBe("`application`.`created_at` DESC");
+    warn.mockRestore();
+  });
+
+  test("the client context id is forwarded to the driver", async () => {
+    const { options } = await listWith({ client_context_id: "scheduler.due" });
+    expect(options.client_context_id).toBe("scheduler.due");
+  });
+});

package/tests/utility/IndexKeys.test.js

@@ -0,0 +1,67 @@
+const {
+  liveCondition,
+  LIVE_INDEX_CONDITION,
+  parseSort,
+  orderByClause,
+  sortIndexKeys,
+  fieldIndexExpression,
+} = require("../../src/utility/IndexKeys");
+
+describe("IndexKeys", () => {
+  test("live condition has no OR and matches the partial index text", () => {
+    expect(liveCondition("app")).toBe("IFMISSING(`app`.`deleted`, false) = false");
+    expect(LIVE_INDEX_CONDITION).toBe("IFMISSING(`deleted`, false) = false");
+    expect(liveCondition("app")).not.toMatch(/\bOR\b/);
+  });
+
+  test("parses multi-column sorts, trimming items the old split left padded", () => {
+    expect(parseSort("priority DESC NULLS LAST, due_at ASC NULLS LAST,name")).toEqual([
+      { path: ["priority"], direction: "DESC", nulls: "LAST" },
+      { path: ["due_at"], direction: "ASC", nulls: "LAST" },
+      { path: ["name"], direction: "ASC", nulls: undefined },
+    ]);
+  });
+
+  test("accepts the saved { property, order } shape", () => {
+    expect(parseSort([{ property: "status", order: "DESC" }])).toEqual([
+      { path: ["status"], direction: "DESC", nulls: undefined },
+    ]);
+  });
+
+  test("drops items that are not a plain field path", () => {
+    const warn = jest.spyOn(console, "warn").mockImplementation(() => {});
+    expect(parseSort("name; DROP INDEX x, LOWER(name) ASC, created_at DESC")).toEqual([
+      { path: ["created_at"], direction: "DESC", nulls: undefined },
+    ]);
+    expect(warn).toHaveBeenCalledTimes(2);
+    warn.mockRestore();
+  });
+
+  test.each([
+    ["f DESC", "`t`.`f` DESC", { expr: "`f`", desc: true, sentinel: false }],
+    ["f DESC NULLS LAST", "`t`.`f` DESC", { expr: "`f`", desc: true, sentinel: false }],
+    ["f ASC NULLS LAST", "IFMISSINGORNULL(`t`.`f`, {}) ASC", { expr: "IFMISSINGORNULL(`f`, {})", desc: false, sentinel: true }],
+    ["f ASC", "`t`.`f` ASC", { expr: "`f`", desc: false, sentinel: false }],
+    ["f ASC NULLS FIRST", "`t`.`f` ASC", { expr: "`f`", desc: false, sentinel: false }],
+    ["f DESC NULLS FIRST", "IFMISSINGORNULL(`t`.`f`, {}) DESC", { expr: "IFMISSINGORNULL(`f`, {})", desc: true, sentinel: true }],
+  ])("%s orders as %s and indexes as %o", (sort, orderBy, key) => {
+    expect(orderByClause(sort, "t")).toBe(orderBy);
+    expect(sortIndexKeys(parseSort(sort))[0]).toEqual({ ...key, field: "f" });
+  });
+
+  test("qualifies local paths, strips an explicit alias and leaves joined aliases alone", () => {
+    expect(orderByClause("address.city ASC, t.created_at DESC, owner.name DESC", "t", ["owner"])).toBe(
+      "`t`.`address`.`city` ASC, `t`.`created_at` DESC, `owner`.`name` DESC",
+    );
+  });
+
+  test("an empty sort produces no clause so the caller can apply its default", () => {
+    expect(orderByClause("", "t")).toBe("");
+    expect(orderByClause(undefined, "t")).toBe("");
+  });
+
+  test("field index expressions are quoted paths and reject anything else", () => {
+    expect(fieldIndexExpression("address.city")).toBe("`address`.`city`");
+    expect(fieldIndexExpression("lower(name)")).toBeNull();
+  });
+});