spice-couchbase 2.0.60 → 2.0.62

package/build/index.auto-optimize.test.js

@@ -0,0 +1,578 @@
+"use strict";
+
+function asyncGeneratorStep(gen, resolve, reject, _next, _throw, key, arg) { try { var info = gen[key](arg); var value = info.value; } catch (error) { reject(error); return; } if (info.done) { resolve(value); } else { Promise.resolve(value).then(_next, _throw); } }
+
+function _asyncToGenerator(fn) { return function () { var self = this, args = arguments; return new Promise(function (resolve, reject) { var gen = fn.apply(self, args); function _next(value) { asyncGeneratorStep(gen, resolve, reject, _next, _throw, "next", value); } function _throw(err) { asyncGeneratorStep(gen, resolve, reject, _next, _throw, "throw", err); } _next(undefined); }); }; }
+
+function ownKeys(object, enumerableOnly) { var keys = Object.keys(object); if (Object.getOwnPropertySymbols) { var symbols = Object.getOwnPropertySymbols(object); if (enumerableOnly) symbols = symbols.filter(function (sym) { return Object.getOwnPropertyDescriptor(object, sym).enumerable; }); keys.push.apply(keys, symbols); } return keys; }
+
+function _objectSpread(target) { for (var i = 1; i < arguments.length; i++) { var source = arguments[i] != null ? arguments[i] : {}; if (i % 2) { ownKeys(Object(source), true).forEach(function (key) { _defineProperty(target, key, source[key]); }); } else if (Object.getOwnPropertyDescriptors) { Object.defineProperties(target, Object.getOwnPropertyDescriptors(source)); } else { ownKeys(Object(source)).forEach(function (key) { Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key)); }); } } return target; }
+
+function _defineProperty(obj, key, value) { if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
+
+var assert = require("node:assert/strict");
+
+var fs = require("node:fs");
+
+var path = require("node:path");
+
+var vm = require("node:vm");
+
+var {
+  test
+} = require("node:test");
+
+var {
+  buildCoveringIndex,
+  buildCoveringIndexDefinition
+} = require("./utility");
+
+var keyspace = {
+  bucket: "saturn",
+  scope: "test",
+  collection: "users"
+};
+var lookupQuery = "SELECT name, email FROM users WHERE status = 'active'";
+
+function existingIndex(index_key) {
+  var overrides = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+  return _objectSpread({
+    name: "legacy_covering_index",
+    using: "gsi",
+    state: "online",
+    index_key
+  }, overrides);
+}
+
+function executionScope() {
+  var indexes = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : [];
+  var {
+    inventoryError,
+    inventoryResponse,
+    plan
+  } = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+  var calls = [];
+  return {
+    calls,
+
+    query(statement, options) {
+      return _asyncToGenerator(function* () {
+        calls.push({
+          statement,
+          options
+        });
+
+        if (statement.startsWith("EXPLAIN ")) {
+          return {
+            rows: [plan || {
+              "#operator": "Fetch"
+            }]
+          };
+        }
+
+        if (statement.includes("FROM system:indexes")) {
+          if (inventoryError) throw inventoryError;
+          return inventoryResponse === undefined ? {
+            rows: indexes
+          } : inventoryResponse;
+        }
+
+        return {
+          rows: []
+        };
+      })();
+    }
+
+  };
+}
+
+function createStatements(scope) {
+  return scope.calls.filter((_ref) => {
+    var {
+      statement
+    } = _ref;
+    return statement.startsWith("CREATE INDEX ");
+  });
+} // Isolate optimizer state and time without connecting to Couchbase or sleeping.
+// Each load is a fresh module: its own seen-set, cooldown and policy.
+
+
+function loadDriver(durationMs) {
+  var env = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+  var tick = BigInt(0);
+  var module = {
+    exports: {}
+  };
+  vm.runInNewContext(fs.readFileSync(path.join(__dirname, "index.js"), "utf8"), {
+    require,
+    module,
+    console,
+    process: {
+      env,
+      hrtime: {
+        bigint: () => {
+          var current = tick;
+          tick += BigInt(durationMs) * BigInt(1000000);
+          return current;
+        }
+      }
+    }
+  });
+  return module.exports;
+}
+
+function instanceOf(Database) {
+  var db = Object.create(Database.prototype);
+  db.bucket = "saturn";
+  db.scope_name = "test";
+  db.collection_name = "users";
+  db.cluster = {
+    query: function () {
+      var _query = _asyncToGenerator(function* () {
+        return {
+          rows: []
+        };
+      });
+
+      function query() {
+        return _query.apply(this, arguments);
+      }
+
+      return query;
+    }()
+  };
+  return db;
+} // Opted in wholesale: per-resource resolution has its own tests further down.
+
+
+function createDatabase(durationMs) {
+  var env = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+  var db = instanceOf(loadDriver(durationMs, env));
+  db.auto_optimize = true;
+  return db;
+}
+
+test("auto-optimization only starts above the default 3-second threshold",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  for (var duration of [1001, 2999, 3000, 3001]) {
+    var db = createDatabase(duration);
+    var optimizations = 0;
+    db.optimize =
+    /*#__PURE__*/
+    _asyncToGenerator(function* () {
+      optimizations += 1;
+    });
+    yield db.query("SELECT name FROM users WHERE status = 'active'");
+    assert.equal(optimizations, duration > 3000 ? 1 : 0, "".concat(duration, "ms"));
+  }
+}));
+test("the explicit slow-query threshold override remains supported",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var db = createDatabase(5001, {
+    SPICE_COUCHBASE_SLOW_QUERY_MS: "5000"
+  });
+  var optimizations = 0;
+  db.optimize =
+  /*#__PURE__*/
+  _asyncToGenerator(function* () {
+    optimizations += 1;
+  });
+  yield db.query("SELECT name FROM users WHERE status = 'active'");
+  assert.equal(optimizations, 1);
+}));
+test("Fetch plans for full-document projections never create indexes",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var _loop = function* _loop(projection) {
+    var db = createDatabase(0);
+    var statements = [];
+    var query = "SELECT ".concat(projection, " FROM users WHERE status = 'active' ORDER BY created_at DESC");
+    yield db.optimize(query, {
+      query: function () {
+        var _query2 = _asyncToGenerator(function* (statement) {
+          statements.push(statement);
+          return {
+            rows: [{
+              "#operator": "Fetch"
+            }]
+          };
+        });
+
+        function query(_x) {
+          return _query2.apply(this, arguments);
+        }
+
+        return query;
+      }()
+    });
+    assert.deepEqual(statements, ["EXPLAIN ".concat(query)]);
+  };
+
+  for (var projection of ["*", "users.*", "`users`.*", "(`users`).*, META(`users`).id AS id"]) {
+    yield* _loop(projection);
+  }
+}));
+test("Fetch plans for explicit fields still create a covering index",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var db = createDatabase(0);
+  var scope = executionScope();
+  yield db.optimize("SELECT name FROM users WHERE status = 'active'", scope);
+  assert.equal(scope.calls.length, 3);
+  assert.match(scope.calls[1].statement, /FROM system:indexes/);
+  assert.equal(JSON.stringify(scope.calls[1].options.parameters), JSON.stringify(keyspace));
+  assert.match(scope.calls[2].statement, /^CREATE INDEX `adv_covered_/);
+  assert.match(scope.calls[2].statement, /`status`, `name`/);
+}));
+test("reordered selected columns and changed literals generate identical DDL", () => {
+  var original = buildCoveringIndex(lookupQuery, keyspace);
+  var reordered = buildCoveringIndex("SELECT email, name FROM users WHERE status = 'pending'", keyspace);
+  assert.equal(original, reordered);
+});
+test("adding explicit ascending order cannot rename an identical definition", () => {
+  var base = "SELECT status, created_at FROM users WHERE status = 'pending'";
+  assert.equal(buildCoveringIndex(base, keyspace), buildCoveringIndex("".concat(base, " ORDER BY created_at ASC"), keyspace));
+});
+test("genuinely different access-key order and direction keep distinct definitions", () => {
+  var base = "SELECT name, email FROM users WHERE status = 'active'";
+  var asc = buildCoveringIndex("".concat(base, " ORDER BY name, email"), keyspace);
+  var desc = buildCoveringIndex("".concat(base, " ORDER BY name DESC, email"), keyspace);
+  var reordered = buildCoveringIndex("".concat(base, " ORDER BY email, name"), keyspace);
+  assert.notEqual(asc, desc);
+  assert.notEqual(asc, reordered);
+  assert.notEqual(asc.match(/adv_covered_\w+/)[0], reordered.match(/adv_covered_\w+/)[0]);
+});
+test("case-distinct document fields are not collapsed", () => {
+  var statement = buildCoveringIndex("SELECT Name, name, Status, status FROM users ORDER BY Name DESC", keyspace);
+  assert.match(statement, /`Name` DESC/);
+  assert.match(statement, /`name`/);
+  assert.match(statement, /`Status`/);
+  assert.match(statement, /`status`/);
+  assert.doesNotMatch(statement, /`name` DESC/);
+});
+
+var _loop2 = function _loop2(state) {
+  test("an existing ".concat(state, " index with reordered projection keys prevents creation"),
+  /*#__PURE__*/
+  _asyncToGenerator(function* () {
+    var scope = executionScope([existingIndex(["`deleted` INCLUDE MISSING", "`status`", "`name`", "`email`"], {
+      state
+    })]);
+    yield createDatabase(0).optimize(lookupQuery, scope);
+    assert.equal(scope.calls.length, 2);
+    assert.equal(createStatements(scope).length, 0);
+  }));
+};
+
+for (var state of ["online", "deferred", "pending", "building", "offline"]) {
+  _loop2(state);
+}
+
+test("a wider existing index covers a projection subset without another index",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var scope = executionScope([existingIndex(["`deleted` INCLUDE MISSING", "`status`", "`name`", "`phone`", "`email` DESC"])]);
+  yield createDatabase(0).optimize(lookupQuery, scope);
+  assert.equal(createStatements(scope).length, 0);
+}));
+test("catalog key formatting, explicit ASC and attribute order are normalized",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  for (var leadingKey of ["((`deleted`)) ASC INCLUDE MISSING", "deleted INCLUDE MISSING ASC"]) {
+    var scope = executionScope([existingIndex([leadingKey, "(status) ASC", "`name`", "email ASC"])]);
+    yield createDatabase(0).optimize(lookupQuery, scope);
+    assert.equal(createStatements(scope).length, 0, leadingKey);
+  }
+}));
+var incompatibleIndexes = [["missing a projection field", existingIndex(["`deleted` INCLUDE MISSING", "`status`", "`name`"])], ["different access prefix", existingIndex(["`deleted` INCLUDE MISSING", "`name`", "`status`", "`email`"])], ["missing-leading-key exclusion", existingIndex(["`deleted`", "`status`", "`name`", "`email`"])], ["case-distinct field", existingIndex(["`deleted` INCLUDE MISSING", "`status`", "`Name`", "`email`"])], ["expression instead of the field", existingIndex(["`deleted` INCLUDE MISSING", "`status`", "LOWER(`name`)", "`email`"])], ["array key", existingIndex(["`deleted` INCLUDE MISSING", "`status`", "`name`", "`email`", "DISTINCT ARRAY v FOR v IN tags END"])], ["partial index", existingIndex(["`deleted` INCLUDE MISSING", "`status`", "`name`", "`email`"], {
+  condition: "(`status` = 'pending')"
+})], ["primary index", existingIndex([], {
+  is_primary: true
+})]];
+
+var _loop3 = function _loop3(reason, index) {
+  test("does not mistake ".concat(reason, " for a compatible covering index"),
+  /*#__PURE__*/
+  _asyncToGenerator(function* () {
+    var scope = executionScope([index]);
+    yield createDatabase(0).optimize(lookupQuery, scope);
+    assert.equal(createStatements(scope).length, 1);
+  }));
+};
+
+for (var [reason, index] of incompatibleIndexes) {
+  _loop3(reason, index);
+}
+
+test("existing opposite sort direction does not satisfy the requested sort",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var query = "".concat(lookupQuery, " ORDER BY created_at DESC");
+  var scope = executionScope([existingIndex(["`deleted` INCLUDE MISSING", "`status`", "`created_at`", "`name`", "`email`"])]);
+  yield createDatabase(0).optimize(query, scope);
+  assert.equal(createStatements(scope).length, 1);
+  assert.match(createStatements(scope)[0].statement, /`created_at` DESC/);
+}));
+test("same generated name is never recreated even if its keys are unavailable",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var candidate = buildCoveringIndexDefinition(lookupQuery, keyspace);
+  var scope = executionScope([{
+    name: candidate.name,
+    state: "building"
+  }]);
+  yield createDatabase(0).optimize(lookupQuery, scope);
+  assert.equal(createStatements(scope).length, 0);
+}));
+test("catalog failure or incomplete results prevent creation and trigger cooldown",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var _loop4 = function* _loop4(options) {
+    var db = createDatabase(3001);
+    var scope = executionScope([], options);
+    yield db.optimize(lookupQuery, scope);
+    assert.equal(createStatements(scope).length, 0);
+    var retries = 0;
+    db.optimize =
+    /*#__PURE__*/
+    _asyncToGenerator(function* () {
+      retries++;
+    });
+    yield db.query("SELECT email FROM users WHERE status = 'pending'");
+    assert.equal(retries, 0);
+  };
+
+  for (var options of [{
+    inventoryError: new Error("query service unavailable")
+  }, {
+    inventoryResponse: {}
+  }, {
+    inventoryResponse: {
+      rows: [],
+      meta: {
+        warnings: [{
+          message: "partial inventory"
+        }]
+      }
+    }
+  }]) {
+    yield* _loop4(options);
+  }
+}));
+test("already-covered plans need neither an inventory lookup nor creation",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var scope = executionScope([], {
+    plan: {
+      "#operator": "IndexScan3"
+    }
+  });
+  yield createDatabase(0).optimize(lookupQuery, scope);
+  assert.equal(scope.calls.length, 1);
+}));
+test("a default collection uses default names in its inventory lookup",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var db = createDatabase(0);
+  db.scope_name = undefined;
+  db.collection_name = undefined;
+  var scope = executionScope();
+  yield db.optimize("SELECT name FROM saturn WHERE status = 'active'", scope);
+  assert.equal(JSON.stringify(scope.calls[1].options.parameters), JSON.stringify({
+    bucket: "saturn",
+    scope: "_default",
+    collection: "_default"
+  }));
+  assert.match(createStatements(scope)[0].statement, /`saturn`\.`_default`\.`_default`/);
+})); // ---- Per-resource opt-in for auto cover indexing ----
+// Nothing decided at instance level: resolution falls through to the call,
+// the application policy and the static lists.
+
+function createUnconfiguredDatabase() {
+  var env = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  return instanceOf(loadDriver(3001, env));
+}
+
+function optimizationsFor(_x2, _x3) {
+  return _optimizationsFor.apply(this, arguments);
+}
+
+function _optimizationsFor() {
+  _optimizationsFor = _asyncToGenerator(function* (db, statement) {
+    var optimizations = 0;
+    db.optimize =
+    /*#__PURE__*/
+    _asyncToGenerator(function* () {
+      optimizations += 1;
+    });
+
+    for (var _len = arguments.length, queryArgs = new Array(_len > 2 ? _len - 2 : 0), _key = 2; _key < _len; _key++) {
+      queryArgs[_key - 2] = arguments[_key];
+    }
+
+    yield db.query(statement, ...queryArgs);
+    return optimizations;
+  });
+  return _optimizationsFor.apply(this, arguments);
+}
+
+var slowLookup = "SELECT name FROM users WHERE status = 'active'";
+var EVERY_RESOURCE = {
+  SPICE_COUCHBASE_OPTIMIZE_RESOURCES: "*"
+};
+test("no resource is auto-indexed unless something opts it in",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  assert.equal((yield optimizationsFor(createUnconfiguredDatabase(), slowLookup)), 0);
+  assert.equal((yield optimizationsFor(createUnconfiguredDatabase({
+    SPICE_COUCHBASE_OPTIMIZE_RESOURCES: ""
+  }), slowLookup)), 0);
+}));
+test("SPICE_COUCHBASE_OPTIMIZE_RESOURCES enables the instance's collection, case-insensitively",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var env = {
+    SPICE_COUCHBASE_OPTIMIZE_RESOURCES: " Users ,audit_log,, `sessions` "
+  };
+  assert.equal((yield optimizationsFor(createUnconfiguredDatabase(env), slowLookup)), 1);
+  var sessions = createUnconfiguredDatabase(env);
+  sessions.collection_name = "sessions";
+  assert.equal((yield optimizationsFor(sessions, "SELECT id FROM sessions")), 1);
+  var orders = createUnconfiguredDatabase(env);
+  orders.collection_name = "orders";
+  assert.equal((yield optimizationsFor(orders, "SELECT total FROM orders WHERE status = 'paid'")), 0);
+}));
+test("a wildcard restores auto indexing for every resource",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var db = createUnconfiguredDatabase(EVERY_RESOURCE);
+  db.collection_name = "anything";
+  assert.equal((yield optimizationsFor(db, "SELECT a FROM anything WHERE b = 1")), 1);
+}));
+test("legacy bucket mode resolves the resource from the type literal the driver adds",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var env = {
+    SPICE_COUCHBASE_OPTIMIZE_RESOURCES: "audit_log"
+  };
+
+  for (var [type, expected] of [["audit_log", 1], ["users", 0]]) {
+    var db = createUnconfiguredDatabase(env);
+    db.collection_name = "_default";
+    db.scope_name = "_default";
+    assert.equal((yield optimizationsFor(db, "SELECT actor FROM `saturn` WHERE type = '".concat(type, "' AND deleted = false"))), expected, type);
+  }
+}));
+test("a fully qualified or aliased FROM keyspace matches on its last segment",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var env = {
+    SPICE_COUCHBASE_OPTIMIZE_RESOURCES: "logs"
+  };
+
+  for (var statement of ["SELECT level FROM `default`:`saturn`.`app`.`logs` WHERE level = 'error'", "SELECT l.level FROM saturn.app.logs AS l WHERE l.level = 'error'", "SELECT u.name FROM users AS u JOIN `logs` AS l ON l.user_id = META(u).id"]) {
+    var db = createUnconfiguredDatabase(env);
+    db.collection_name = "_default";
+    assert.equal((yield optimizationsFor(db, statement)), 1, statement);
+  }
+}));
+test("connection or constructor lists work without the environment variable",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var db = createUnconfiguredDatabase();
+  db.enabled_resources = new Set(["users"]);
+  assert.equal((yield optimizationsFor(db, slowLookup)), 1);
+}));
+test("an explicit instance setting overrides every resource list",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var on = createUnconfiguredDatabase();
+  on.auto_optimize = true;
+  assert.equal((yield optimizationsFor(on, slowLookup)), 1);
+  var off = createUnconfiguredDatabase(EVERY_RESOURCE);
+  off.auto_optimize = false;
+  assert.equal((yield optimizationsFor(off, slowLookup)), 0);
+}));
+test("a single call can opt in or out through query options",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  assert.equal((yield optimizationsFor(createUnconfiguredDatabase(), slowLookup, {
+    auto_optimize: true
+  })), 1);
+  assert.equal((yield optimizationsFor(createUnconfiguredDatabase(EVERY_RESOURCE), slowLookup, {
+    auto_optimize: false
+  })), 0);
+  assert.equal((yield optimizationsFor(createUnconfiguredDatabase(EVERY_RESOURCE), slowLookup, "cluster", {
+    optimize: false
+  })), 0); // The scan-consistency shorthand is not an opt-in or opt-out.
+
+  assert.equal((yield optimizationsFor(createUnconfiguredDatabase(EVERY_RESOURCE), slowLookup, "cluster", true)), 1);
+  assert.equal((yield optimizationsFor(createUnconfiguredDatabase(), slowLookup, "cluster", true)), 0);
+}));
+test("an application policy decides per resource and sees the statement context",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var Database = loadDriver(3001);
+  var seen = [];
+  Database.setAutoOptimizePolicy((resource, context) => {
+    seen.push([resource, context]);
+    return resource === "users";
+  });
+  assert.equal(Database.getAutoOptimizePolicy().length, 2);
+  var users = instanceOf(Database);
+  users.connection_name = "default";
+  assert.equal((yield optimizationsFor(users, slowLookup)), 1); // Objects cross the vm boundary, so compare by value rather than prototype.
+
+  assert.equal(JSON.stringify(seen[0]), JSON.stringify(["users", {
+    query: slowLookup,
+    connection: "default",
+    collection: "users"
+  }]));
+  var orders = instanceOf(Database);
+  orders.collection_name = "orders";
+  assert.equal((yield optimizationsFor(orders, "SELECT total FROM orders WHERE status = 'paid'")), 0);
+}));
+test("a policy that returns undefined defers to the static lists",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  for (var [env, expected] of [[{
+    SPICE_COUCHBASE_OPTIMIZE_RESOURCES: "users"
+  }, 1], [{}, 0]]) {
+    var Database = loadDriver(3001, env);
+    Database.setAutoOptimizePolicy(() => undefined);
+    assert.equal((yield optimizationsFor(instanceOf(Database), slowLookup)), expected);
+  }
+}));
+test("an explicit policy refusal wins over the wildcard, and a throwing policy counts as a refusal",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  for (var policy of [() => false, () => {
+    throw new Error("settings unavailable");
+  }]) {
+    var Database = loadDriver(3001, EVERY_RESOURCE);
+    Database.setAutoOptimizePolicy(policy);
+    assert.equal((yield optimizationsFor(instanceOf(Database), slowLookup)), 0);
+  }
+}));
+test("the policy can be cleared and must be a function",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var Database = loadDriver(3001, EVERY_RESOURCE);
+  Database.setAutoOptimizePolicy(() => false);
+  Database.setAutoOptimizePolicy(null);
+  assert.equal(Database.getAutoOptimizePolicy(), null);
+  assert.equal((yield optimizationsFor(instanceOf(Database), slowLookup)), 1);
+  assert.throws(() => Database.setAutoOptimizePolicy("users"), {
+    name: "TypeError"
+  });
+}));
+test("a declined statement is not remembered as already optimised",
+/*#__PURE__*/
+_asyncToGenerator(function* () {
+  var db = createUnconfiguredDatabase();
+  assert.equal((yield optimizationsFor(db, slowLookup)), 0);
+  db.auto_optimize = true;
+  assert.equal((yield optimizationsFor(db, slowLookup)), 1);
+}));