spice-couchbase 2.0.60 → 2.0.62

package/build/index.js

@@ -24,6 +24,11 @@ var {
   QueryScanConsistency
 } = require("couchbase");
 
+var {
+  parseResourceList,
+  extractStatementResources
+} = require("./utility");
+
 if (!Promise.allSettled) {
   Promise.allSettled = promises => Promise.all(promises.map((promise, i) => promise.then(value => ({
     status: "fulfilled",
@@ -35,13 +40,13 @@ if (!Promise.allSettled) {
 } // Couchbase lookupIn has a limit of 16 operations per call
 
 
-var LOOKUP_IN_MAX_SPECS = 16; // Auto-optimisation guard rails. `query()` fires `optimize()` (an EXPLAIN plus
-// a possible CREATE INDEX) for any statement slower than SLOW_QUERY_MS. When
+var LOOKUP_IN_MAX_SPECS = 16; // Auto-optimisation guard rails. `query()` fires `optimize()` (an EXPLAIN,
+// index inventory check, and possible CREATE INDEX) above SLOW_QUERY_MS. When
 // the cluster is degraded every statement is slow, so without limits each
 // query spawned two more heavy ones and deepened the outage. These caps make it
 // a bounded, once-per-statement background task that backs off on failure.
 
-var SLOW_QUERY_MS = Number(process.env.SPICE_COUCHBASE_SLOW_QUERY_MS || 1000);
+var SLOW_QUERY_MS = Number(process.env.SPICE_COUCHBASE_SLOW_QUERY_MS || 3000);
 var AUTO_OPTIMIZE_ENABLED = !["0", "false", "no", "off"].includes(String((_process$env$SPICE_CO = process.env.SPICE_COUCHBASE_AUTO_OPTIMIZE) !== null && _process$env$SPICE_CO !== void 0 ? _process$env$SPICE_CO : "true").trim().toLowerCase());
 var OPTIMIZE_MAX_INFLIGHT = Number(process.env.SPICE_COUCHBASE_OPTIMIZE_MAX_INFLIGHT || 1);
 var OPTIMIZE_FAILURE_COOLDOWN_MS = Number(process.env.SPICE_COUCHBASE_OPTIMIZE_COOLDOWN_MS || 5 * 60 * 1000); // Statements already optimised in this process. Bounded so it cannot grow
@@ -52,7 +57,35 @@ var optimizeState = {
   inFlight: 0,
   seen: new Set(),
   cooldownUntil: 0
-};
+}; // Auto cover indexing is opt-in per resource. A resource is the collection a
+// Database instance serves (scoped deployments) or the `type = '...'` literal
+// legacy bucket mode adds to every statement; raw statements also count their
+// FROM / JOIN keyspaces. Names are case-insensitive. A slow statement is
+// optimised when, in order of precedence:
+//   1. the call says so:        query_options.auto_optimize (true / false)
+//   2. the instance says so:    constructor option or connection config
+//                               `auto_optimize` (true / false)
+//   3. the application policy:  Database.setAutoOptimizePolicy(fn), where
+//                               fn(resource, context) returns true / false, or
+//                               undefined to defer to the static lists
+//   4. a static list names a resource it touches: comma-separated
+//      SPICE_COUCHBASE_OPTIMIZE_RESOURCES (`*` = every resource, which is the
+//      pre-2.0.62 behaviour), or connection config / constructor option
+//      `auto_optimize_resources`.
+
+var OPTIMIZE_ENABLED_RESOURCES = parseResourceList(process.env.SPICE_COUCHBASE_OPTIMIZE_RESOURCES);
+var autoOptimizePolicy = null;
+
+function requestedAutoOptimize(query_options) {
+  var _query_options$auto_o;
+
+  if (!query_options || typeof query_options !== "object" || Array.isArray(query_options)) {
+    return undefined;
+  }
+
+  var value = (_query_options$auto_o = query_options.auto_optimize) !== null && _query_options$auto_o !== void 0 ? _query_options$auto_o : query_options.optimize;
+  return typeof value === "boolean" ? value : undefined;
+}
 
 function shouldOptimize(query) {
   if (!AUTO_OPTIMIZE_ENABLED) return false;
@@ -124,7 +157,9 @@ module.exports = class Database {
       collection,
       scope,
       query_scope = "cluster",
-      auto_create_collection
+      auto_create_collection,
+      auto_optimize,
+      auto_optimize_resources
     } = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
 
     if (connection) {
@@ -163,8 +198,93 @@ module.exports = class Database {
         this.upsertCollection();
       }
 
-      this.use_bucket_name = spice.config.database.connections[this.connection_name].scope == undefined;
+      this.use_bucket_name = spice.config.database.connections[this.connection_name].scope == undefined; // Auto cover indexing. See OPTIMIZE_ENABLED_RESOURCES for precedence.
+
+      var configured_auto_optimize = auto_optimize !== null && auto_optimize !== void 0 ? auto_optimize : this.db_config.auto_optimize;
+      this.auto_optimize = typeof configured_auto_optimize === "boolean" ? configured_auto_optimize : undefined;
+      this.enabled_resources = parseResourceList([...parseResourceList(this.db_config.auto_optimize_resources), ...parseResourceList(auto_optimize_resources)]);
+    }
+  }
+  /**
+   * Lets the application decide per resource whether slow statements may
+   * create covering indexes, e.g. from a per-resource setting an operator
+   * toggles at runtime. `policy(resource, { query, connection, collection })`
+   * returns true or false, or undefined to defer to the static lists. It is
+   * synchronous because it runs on the query path. Pass null to clear.
+   */
+
+
+  static setAutoOptimizePolicy(policy) {
+    if (policy !== null && policy !== undefined && typeof policy !== "function") {
+      throw new TypeError("Auto-optimize policy must be a function or null");
+    }
+
+    autoOptimizePolicy = policy || null;
+  }
+
+  static getAutoOptimizePolicy() {
+    return autoOptimizePolicy;
+  }
+  /**
+   * Resources a statement touches, plus this instance's collection: that is
+   * the keyspace `optimize()` would create the index on.
+   */
+
+
+  statementResources(query) {
+    var resources = extractStatementResources(query);
+
+    if (this.collection_name && this.collection_name !== "_default") {
+      resources.add(String(this.collection_name).toLowerCase());
+    }
+
+    return resources;
+  }
+  /**
+   * True when a slow statement may create a covering index. See
+   * OPTIMIZE_ENABLED_RESOURCES for the order of precedence.
+   */
+
+
+  shouldAutoOptimize(query) {
+    var query_options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+    var requested = requestedAutoOptimize(query_options);
+    if (requested !== undefined) return requested;
+    if (typeof this.auto_optimize === "boolean") return this.auto_optimize;
+    var resources = this.statementResources(query);
+
+    if (typeof autoOptimizePolicy === "function" && resources.size > 0) {
+      var deferred = false;
+
+      for (var resource of resources) {
+        var verdict = void 0;
+
+        try {
+          verdict = autoOptimizePolicy(resource, {
+            query,
+            connection: this.connection_name,
+            collection: this.collection_name
+          });
+        } catch (e) {
+          // A broken policy must not create indexes nobody asked for.
+          verdict = false;
+        }
+
+        if (verdict === true) return true;
+        if (verdict === undefined || verdict === null) deferred = true;
+      }
+
+      if (!deferred) return false;
+    }
+
+    var enabled = new Set([...OPTIMIZE_ENABLED_RESOURCES, ...(this.enabled_resources || [])]);
+    if (enabled.has("*")) return true;
+
+    for (var _resource of resources) {
+      if (enabled.has(_resource)) return true;
     }
+
+    return false;
   }
 
   setGlobalConnectionObject(collection) {
@@ -904,10 +1024,11 @@ module.exports = class Database {
       optimizeState.inFlight += 1;
 
       try {
-        var _explainResponse$rows;
+        var _explainResponse$rows, _indexResponse$meta, _indexResponse$meta$w;
 
         var {
-          buildCoveringIndex
+          buildCoveringIndexDefinition,
+          indexSatisfiesCoveringDefinition
         } = require("./utility"); // 1. Run EXPLAIN to get the query plan
 
 
@@ -922,15 +1043,34 @@ module.exports = class Database {
         } // 3. Build covering index from the query
 
 
-        var indexStatement = buildCoveringIndex(query, {
+        var candidate = buildCoveringIndexDefinition(query, {
           bucket: _this19.bucket,
           scope: _this19.scope_name,
           collection: _this19.collection_name
-        }); // 4. Execute the index creation if we got a valid statement
+        });
+        if (!candidate) return; // EXPLAIN only describes the chosen plan. An equivalent or wider index
+        // may already exist under an older name, or still be deferred/building.
+        // Include both catalog representations of the default collection.
+
+        var indexResponse = yield exec_scope.query("SELECT RAW i FROM system:indexes AS i\n         WHERE i.namespace_id = 'default'\n           AND ((i.bucket_id = $bucket AND i.scope_id = $scope AND i.keyspace_id = $collection)\n             OR ($scope = '_default' AND $collection = '_default'\n               AND i.bucket_id IS MISSING AND i.scope_id IS MISSING AND i.keyspace_id = $bucket))", {
+          parameters: {
+            bucket: candidate.bucket,
+            scope: candidate.scope,
+            collection: candidate.collection
+          }
+        }); // A failed or incomplete inventory is not evidence that no index exists.
 
-        if (indexStatement) {
-          yield exec_scope.query(indexStatement);
+        if (!Array.isArray(indexResponse === null || indexResponse === void 0 ? void 0 : indexResponse.rows) || (indexResponse === null || indexResponse === void 0 ? void 0 : (_indexResponse$meta = indexResponse.meta) === null || _indexResponse$meta === void 0 ? void 0 : (_indexResponse$meta$w = _indexResponse$meta.warnings) === null || _indexResponse$meta$w === void 0 ? void 0 : _indexResponse$meta$w.length)) {
+          throw new Error("Cannot verify existing indexes before auto-optimization");
         }
+
+        if (indexResponse.rows.some(index => index.name === candidate.name || indexSatisfiesCoveringDefinition(index, candidate))) {
+          return;
+        } // Identical definitions use the same name across processes. Couchbase's
+        // per-keyspace name uniqueness also prevents a concurrent duplicate.
+
+
+        yield exec_scope.query(candidate.statement);
       } catch (e) {
         // A failure here (timeout, index already exists, cluster busy) almost
         // always means the cluster is struggling. Stop adding EXPLAIN and
@@ -973,7 +1113,7 @@ module.exports = class Database {
       var durationInMilliseconds = (endTime - startTime) / BigInt(1000000); // Optimise slow statements in the background, subject to the guard rails
       // declared at the top of this file. Never awaited, never allowed to reject.
 
-      if (durationInMilliseconds > SLOW_QUERY_MS && shouldOptimize(sanitizedQuery)) {
+      if (durationInMilliseconds > SLOW_QUERY_MS && _this20.shouldAutoOptimize(sanitizedQuery, query_options) && shouldOptimize(sanitizedQuery)) {
         _this20.optimize(sanitizedQuery, exec_scope).catch(() => {});
       }
 

package/build/utility.js

@@ -235,7 +235,7 @@ function buildOrderDirectionMap(orderByIndexFields) {
     direction
   } of orderByIndexFields) {
     if (direction === "DESC") {
-      directionMap.set(name.toLowerCase(), direction);
+      directionMap.set(name, direction);
     }
   }
 
@@ -243,14 +243,9 @@ function buildOrderDirectionMap(orderByIndexFields) {
 }
 
 function formatIndexField(field, orderDirectionMap) {
-  var direction = orderDirectionMap.get(field.toLowerCase());
+  var direction = orderDirectionMap.get(field);
   return "`".concat(field, "`").concat(direction ? " ".concat(direction) : "");
 }
-
-function formatIndexKey(field, orderDirectionMap) {
-  var direction = orderDirectionMap.get(field.toLowerCase());
-  return "".concat(field).concat(direction ? " ".concat(direction) : "");
-}
 /**
  * Splits SELECT clause by commas, respecting parentheses
  * @param {string} clause - The SELECT clause content
@@ -284,21 +279,8 @@ function splitSelectClause(clause) {
 
   return parts;
 }
-
-function hasQualifiedWildcardProjection(query) {
-  var selectMatch = query.match(/\bSELECT\b([\s\S]+?)\bFROM\b/i);
-
-  if (!selectMatch) {
-    return false;
-  }
-
-  return splitSelectClause(selectMatch[1].trim()).some(part => {
-    var trimmedPart = part.trim();
-    return /^\(\s*`?\w+`?\s*\)\s*\.\s*\*$/.test(trimmedPart) || /^`?\w+`?\s*\.\s*\*$/.test(trimmedPart);
-  });
-}
 /**
- * Builds a covering or fallback non-covering index CREATE statement from a query
+ * Builds a covering index CREATE statement from a query
  * @param {string} query - The N1QL query to analyze
  * @param {Object} options - Configuration options
  * @param {string} options.bucket - The bucket name
@@ -309,6 +291,14 @@ function hasQualifiedWildcardProjection(query) {
 
 
 function buildCoveringIndex(query, options) {
+  var _ref, _buildCoveringIndexDe;
+
+  return (_ref = (_buildCoveringIndexDe = buildCoveringIndexDefinition(query, options)) === null || _buildCoveringIndexDe === void 0 ? void 0 : _buildCoveringIndexDe.statement) !== null && _ref !== void 0 ? _ref : null;
+} // Keep the access keys separate from projection-only keys so an older, wider
+// index can satisfy the same request without depending on its generated name.
+
+
+function buildCoveringIndexDefinition(query, options) {
   var {
     bucket,
     scope = "_default",
@@ -321,9 +311,10 @@ function buildCoveringIndex(query, options) {
 
 
   var selectFields = extractSelectFields(query);
-  var isNonCoveringFallback = selectFields === null && hasQualifiedWildcardProjection(query);
 
-  if (selectFields === null && !isNonCoveringFallback) {
+  if (selectFields === null) {
+    // Full-document projections cannot be covered by the extracted fields.
+    // Skip them instead of creating a non-covering fallback index.
     return null;
   } // Extract fields from WHERE clause
 
@@ -336,42 +327,36 @@ function buildCoveringIndex(query, options) {
   var orderDirectionMap = buildOrderDirectionMap(orderByIndexFields);
   var orderByFields = orderByIndexFields.map(field => field.name); // Remove 'deleted' from whereFields as it will be added first with INCLUDE MISSING
 
-  var filteredWhereFields = whereFields.filter(f => f.toLowerCase() !== "deleted"); // Track fields already added to avoid duplicates
+  var filteredWhereFields = whereFields.filter(f => f !== "deleted"); // Track fields already added to avoid duplicates
 
-  var addedFields = new Set(filteredWhereFields.map(f => f.toLowerCase())); // Filter GROUP BY fields (remove duplicates from WHERE, remove deleted)
+  var addedFields = new Set(filteredWhereFields); // Filter GROUP BY fields (remove duplicates from WHERE, remove deleted)
 
   var filteredGroupByFields = groupByFields.filter(f => {
-    var lower = f.toLowerCase();
-
-    if (addedFields.has(lower) || lower === "deleted") {
+    if (addedFields.has(f) || f === "deleted") {
       return false;
     }
 
-    addedFields.add(lower);
+    addedFields.add(f);
     return true;
   }); // Filter ORDER BY fields (remove duplicates from WHERE and GROUP BY, remove deleted)
 
   var filteredOrderByFields = orderByFields.filter(f => {
-    var lower = f.toLowerCase();
-
-    if (addedFields.has(lower) || lower === "deleted") {
+    if (addedFields.has(f) || f === "deleted") {
       return false;
     }
 
-    addedFields.add(lower);
+    addedFields.add(f);
     return true;
   }); // Filter SELECT fields (remove duplicates from WHERE, GROUP BY, and ORDER BY, remove deleted)
 
-  var selectFieldsFiltered = (selectFields || []).filter(f => {
-    var lower = f.toLowerCase();
-
-    if (addedFields.has(lower) || lower === "deleted") {
+  var selectFieldsFiltered = selectFields.filter(f => {
+    if (addedFields.has(f) || f === "deleted") {
       return false;
     }
 
-    addedFields.add(lower);
+    addedFields.add(f);
     return true;
-  }); // All fields for the index: WHERE -> GROUP BY -> ORDER BY -> SELECT
+  }).sort(); // Projection order has no effect on coverage. Keep access-key order intact.
 
   var allFields = [...filteredWhereFields, ...filteredGroupByFields, ...filteredOrderByFields, ...selectFieldsFiltered];
 
@@ -381,22 +366,145 @@ function buildCoveringIndex(query, options) {
   } // Build the field list with deleted INCLUDE MISSING first
 
 
-  var fieldList = ["`deleted` INCLUDE MISSING", ...allFields.map(f => formatIndexField(f, orderDirectionMap))].join(", "); // Generate unique index name based on bucket, scope, collection, and fields
-  // This ensures multiple queries covered by the same index get the same hash
+  var keys = ["`deleted` INCLUDE MISSING", ...allFields.map(f => formatIndexField(f, orderDirectionMap))]; // Hash the actual ordered definition, not query syntax. In particular, an
+  // explicit ORDER BY ... ASC must not rename an otherwise identical index.
 
-  var indexFieldsKey = allFields.map(field => formatIndexKey(field, orderDirectionMap)).sort().join(",");
-  var orderFieldsKey = orderByIndexFields.map(field => formatIndexKey(field.name, orderDirectionMap)).join(",");
-  var indexMode = isNonCoveringFallback ? "noncovered" : "covered";
-  var indexKey = "".concat(bucket, "|").concat(scope, "|").concat(collection, "|mode:").concat(indexMode, "|fields:").concat(indexFieldsKey, "|order:").concat(orderFieldsKey);
+  var indexKey = JSON.stringify([bucket, scope, collection, keys]);
   var hash = generateHash(indexKey);
-  var indexName = "adv_".concat(indexMode, "_").concat(hash); // Build the CREATE INDEX statement
+  var indexName = "adv_covered_".concat(hash); // Build the CREATE INDEX statement
+
+  var quote = identifier => "`".concat(identifier.replace(/`/g, "``"), "`");
+
+  var indexStatement = "CREATE INDEX `".concat(indexName, "` ON `default`:").concat(quote(bucket), ".").concat(quote(scope), ".").concat(quote(collection), "(").concat(keys.join(", "), ")");
+  return {
+    name: indexName,
+    statement: indexStatement,
+    keys,
+    accessKeyCount: 1 + filteredWhereFields.length + filteredGroupByFields.length + filteredOrderByFields.length,
+    bucket,
+    scope,
+    collection
+  };
+} // Only compare simple scalar keys. Do not treat expressions, array indexes,
+// partial indexes, or case-distinct document fields as equivalent.
+
+
+function normalizeIndexKey(key) {
+  if (typeof key !== "string") return null;
+  var match = key.trim().match(/^(\(*[\t-\r \xA0\u1680\u2000-\u200A\u2028\u2029\u202F\u205F\u3000\uFEFF]*(?:`(?:[\0-_a-\uFFFF]|``)+`|[A-Z_a-z][0-9A-Z_a-z]*)[\t-\r \xA0\u1680\u2000-\u200A\u2028\u2029\u202F\u205F\u3000\uFEFF]*\)*)([\s\S]*?)$/);
+  if (!match) return null;
+  var expression = match[1].trim();
+
+  while (expression.startsWith("(") && expression.endsWith(")")) {
+    expression = expression.slice(1, -1).trim();
+  }
+
+  var identifier = expression.match(/^(?:`((?:[^`]|``)+)`|([A-Za-z_]\w*))$/);
+  if (!identifier) return null;
+  var attributes = match[2].trim().toUpperCase();
+
+  if (!/^(?:(?:ASC|DESC)(?:\s+INCLUDE\s+MISSING)?|INCLUDE\s+MISSING(?:\s+(?:ASC|DESC))?)?$/.test(attributes)) {
+    return null;
+  }
+
+  return {
+    field: identifier[1] !== undefined ? identifier[1].replace(/``/g, "`") : identifier[2],
+    direction: /\bDESC\b/.test(attributes) ? "DESC" : "ASC",
+    includeMissing: /\bINCLUDE\s+MISSING\b/.test(attributes)
+  };
+} // Call with indexes from the candidate's exact bucket/scope/collection. State
+// is deliberately not filtered: a matching deferred/building index is already
+// committed work, even though EXPLAIN cannot use it yet.
+
+
+function indexSatisfiesCoveringDefinition(index, candidate) {
+  if (index.is_primary || index.condition || index.using !== "gsi" || !Array.isArray(index.index_key)) {
+    return false;
+  }
+
+  var existingKeys = index.index_key.map(normalizeIndexKey);
+  var requiredKeys = candidate.keys.map(normalizeIndexKey);
+  if (existingKeys.some(key => !key) || requiredKeys.some(key => !key)) return false;
+
+  for (var i = 0; i < candidate.accessKeyCount; i++) {
+    var existing = existingKeys[i];
+    var required = requiredKeys[i];
+    if (!existing || existing.field !== required.field || existing.direction !== required.direction || existing.includeMissing !== required.includeMissing) return false;
+  }
+
+  var existingFields = new Set(existingKeys.map(key => key.field));
+  return requiredKeys.slice(candidate.accessKeyCount).every(key => existingFields.has(key.field));
+}
+/**
+ * Normalizes an exemption list into a Set of lower-case resource names.
+ * Accepts an array, a Set, or a comma-separated string (the env var form).
+ * Surrounding whitespace and backticks are ignored; empty entries are dropped.
+ * @param {string|string[]|Set<string>} value
+ * @returns {Set<string>}
+ */
+
+
+function parseResourceList(value) {
+  var names = new Set();
+  var items = [];
+
+  if (Array.isArray(value) || value instanceof Set) {
+    items = [...value];
+  } else if (typeof value === "string") {
+    items = value.split(",");
+  }
+
+  for (var item of items) {
+    if (typeof item !== "string") continue;
+    var name = item.trim().replace(/^`+|`+$/g, "").trim().toLowerCase();
+    if (name) names.add(name);
+  }
+
+  return names;
+}
+/**
+ * Extracts the resource names a statement touches, lower-cased:
+ * - the last path segment of every FROM / JOIN keyspace, unquoted, so
+ *   `default`:`bucket`.`scope`.`users` and users both yield "users";
+ * - every `type = '...'` literal, which is how legacy bucket-mode
+ *   deployments distinguish resources that share one keyspace.
+ * Only simple identifiers are recognised; subqueries and expressions are skipped.
+ * @param {string} query
+ * @returns {Set<string>}
+ */
+
+
+function extractStatementResources(query) {
+  var names = new Set();
+  if (typeof query !== "string") return names;
+  var identifier = "(?:`(?:[^`]|``)+`|[A-Za-z_][\\w$-]*)";
+  var keyspacePattern = new RegExp("\\b(?:FROM|JOIN)\\s+(".concat(identifier, "(?:\\s*[.:]\\s*").concat(identifier, ")*)"), "gi");
+  var segmentPattern = new RegExp(identifier, "g");
+
+  for (var match of query.matchAll(keyspacePattern)) {
+    var segments = match[1].match(segmentPattern) || [];
+    var last = (segments[segments.length - 1] || "").trim();
+    var name = last.startsWith("`") ? last.slice(1, -1).replace(/``/g, "`") : last;
+    if (name) names.add(name.toLowerCase());
+  }
+
+  var typePattern = /(?:`type`|\btype)\s*=\s*'((?:[^']|'')*)'/gi;
+
+  for (var _match of query.matchAll(typePattern)) {
+    var _name = _match[1].replace(/''/g, "'").trim();
+
+    if (_name) names.add(_name.toLowerCase());
+  }
 
-  var indexStatement = "CREATE INDEX `".concat(indexName, "` ON `default`:`").concat(bucket, "`.`").concat(scope, "`.`").concat(collection, "`(").concat(fieldList, ")");
-  return indexStatement;
+  return names;
 }
 
 module.exports = {
   buildCoveringIndex,
+  buildCoveringIndexDefinition,
+  indexSatisfiesCoveringDefinition,
+  parseResourceList,
+  extractStatementResources,
   extractWhereFields,
   extractSelectFields,
   extractGroupByFields,

package/build/utility.test.js

@@ -8,7 +8,9 @@ var {
   extractSelectFields,
   extractGroupByFields,
   extractOrderByFields,
-  generateHash
+  generateHash,
+  parseResourceList,
+  extractStatementResources
 } = require("./utility"); // Test utilities
 
 
@@ -504,21 +506,21 @@ test("returns null when missing bucket option", () => {
   });
   assert.strictEqual(result, null);
 });
-test("returns null when missing scope option", () => {
+test("uses the default scope when scope option is missing", () => {
   var query = "SELECT name FROM users WHERE status = 'active'";
   var result = buildCoveringIndex(query, {
     bucket: "test",
     collection: "users"
   });
-  assert.strictEqual(result, null);
+  assert.ok(result.includes("`test`.`_default`.`users`"));
 });
-test("returns null when missing collection option", () => {
+test("uses the default collection when collection option is missing", () => {
   var query = "SELECT name FROM users WHERE status = 'active'";
   var result = buildCoveringIndex(query, {
     bucket: "test",
     scope: "scope"
   });
-  assert.strictEqual(result, null);
+  assert.ok(result.includes("`test`.`scope`.`_default`"));
 });
 test("generates unique index name from query hash", () => {
   var query1 = "SELECT name FROM users WHERE status = 'active'";
@@ -825,6 +827,52 @@ test("field order: WHERE -> GROUP BY -> ORDER BY -> SELECT", () => {
 
   assert.ok(createdAtIndex < emailIndex); // ORDER BY before SELECT
 }); // ============================================
+// Tests for parseResourceList / extractStatementResources
+// ============================================
+
+console.log("\n--- parseResourceList tests ---");
+test("parses a comma-separated string, trimming, unquoting and lower-casing", () => {
+  var result = parseResourceList(" Users, `Audit_Log` ,, sessions ");
+  assert.deepStrictEqual([...result].sort(), ["audit_log", "sessions", "users"]);
+});
+test("accepts arrays and Sets and ignores non-strings", () => {
+  assert.deepStrictEqual([...parseResourceList(["Users", 42, null, " logs "])].sort(), ["logs", "users"]);
+  assert.deepStrictEqual([...parseResourceList(new Set(["A", "b"]))].sort(), ["a", "b"]);
+});
+test("returns an empty set for undefined, empty or unsupported input", () => {
+  assert.strictEqual(parseResourceList(undefined).size, 0);
+  assert.strictEqual(parseResourceList("").size, 0);
+  assert.strictEqual(parseResourceList(", ,").size, 0);
+  assert.strictEqual(parseResourceList({
+    users: true
+  }).size, 0);
+});
+console.log("\n--- extractStatementResources tests ---");
+test("extracts a bare FROM keyspace", () => {
+  assert.deepStrictEqual([...extractStatementResources("SELECT name FROM users WHERE x = 1")], ["users"]);
+});
+test("extracts the last segment of a qualified or quoted keyspace", () => {
+  assert.deepStrictEqual([...extractStatementResources("SELECT name FROM `default`:`saturn`.`app`.`Users` AS u")], ["users"]);
+  assert.deepStrictEqual([...extractStatementResources("SELECT name FROM saturn.app.logs")], ["logs"]);
+});
+test("extracts JOIN keyspaces alongside FROM", () => {
+  var result = extractStatementResources("SELECT u.name FROM users AS u JOIN `orders` AS o ON o.user_id = META(u).id");
+  assert.deepStrictEqual([...result].sort(), ["orders", "users"]);
+});
+test("extracts type literals used by legacy bucket mode", () => {
+  var result = extractStatementResources("SELECT actor FROM `saturn` WHERE type = 'Audit_Log' AND deleted = false");
+  assert.deepStrictEqual([...result].sort(), ["audit_log", "saturn"]);
+  assert.ok(extractStatementResources("SELECT a FROM b WHERE `type`='x'").has("x"));
+  assert.ok(extractStatementResources("SELECT a FROM b WHERE type = 'it''s'").has("it's"));
+});
+test("does not treat META() arguments, subqueries or column names as keyspaces", () => {
+  var result = extractStatementResources("SELECT META(`users`).id AS id, from_date FROM (SELECT * FROM users) AS sub WHERE status = 'from'");
+  assert.deepStrictEqual([...result], ["users"]);
+});
+test("handles non-string input", () => {
+  assert.strictEqual(extractStatementResources(undefined).size, 0);
+  assert.strictEqual(extractStatementResources(null).size, 0);
+}); // ============================================
 // Summary
 // ============================================
 

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "spice-couchbase",
-  "version": "2.0.60",
+  "version": "2.0.62",
   "description": "",
   "main": "build/index.js",
   "scripts": {
     "test": "node src/utility.test.js",
+    "test:auto-optimize": "node --test src/index.auto-optimize.test.js",
     "test:query-consistency": "node src/index.query-consistency.test.js",
     "test:count-query": "node src/index.count-query.test.js"
   },