stratus-db 0.3.0 → 0.4.0

package/README.md

@@ -57,7 +57,8 @@ Gateway's 403 Forbidden for a brand-new key, which works within a minute or two
 - Catalog: `listDbs({deleted})`, `dbByName(name)`, `dbRecord(id)`, `createDb({name, primaryKey})`,
   `renameDb(id, name)`, `deleteDb(id)`.
 - A database: `status(id)`, `transact(id, {tx, retract, delete, txId, match})`, `query(id, q)`,
-  `queryAll(id, q)` (async iterator), `pull(id, pks, {asOf})` (and `asOf: t` in a query: the database as it stood after t), `requestIndex(id, att)`,
+  `queryAll(id, q)` (async iterator), `pull(id, pks, {asOf})` (and `asOf: t` in a query: the database as it stood after t), `requestIndex(id, att, {required})` (att an attribute, or an array of 2 to 8 for a
+  multi-attribute index: queried by tuples, `["=", ["a", "b"], [x, y]]`; docs/query.md),
   `awaitIndex(id, att)`, `dropIndex(id, att)`, `history(id, {from, limit})`, `historyAll`,
   `fork(id, {t, name})` (a new database, this one as of t), `excise(id, {rows,
   attributes})` (erasure: rows and {pk, att} out of the state, indexes, history and forks),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stratus-db",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "The stratus-db service from JavaScript: typed JSON over fetch, no dependencies.",
   "homepage": "https://stratus-db.com",
   "license": "Apache-2.0",

package/stratus-db.js

@@ -15,7 +15,7 @@
 // "Authorization: Bearer <key>".
 
 /** The client's version: package.json's, which release-js.yml checks against it. */
-export const VERSION = "0.3.0";
+export const VERSION = "0.4.0";
 
 const USER_AGENT = `stratus-db-js/${VERSION}`;
 const IN_NODE = typeof process !== "undefined" && process.versions != null && process.versions.node != null;
@@ -529,6 +529,15 @@ function queryString(params) {
 
 function attName(att) { return att instanceof Keyword ? att.fullName : String(att).replace(/^:/, ""); }
 
+// An index's name: an attribute's, or a multi-attribute index's (an array) joined by commas -
+// how the status keys it, and the DELETE path names it.
+function indexName(att) { return Array.isArray(att) ? att.map(attName).join(",") : attName(att); }
+
+// The DELETE path of an index: each name's parts encoded, its slashes and commas kept.
+function indexPath(att) {
+  return indexName(att).split(",").map((n) => n.split("/").map(encodeURIComponent).join("/")).join(",");
+}
+
 /** A client of the stratus service at opts.url (see the module's comment for opts). */
 export function connect(opts) {
   return new Client(opts);
@@ -703,18 +712,26 @@ export class Client {
     return (Client.ok(await this.callDb(id, "POST", "/pull", asOf === undefined ? { pks } : { pks, "as-of": asOf }))).rows;
   }
 
-  /** Requests a value index on att: { att, state } ("building" until a checkpoint builds it). */
-  async requestIndex(id, att) {
-    return Client.ok(await this.callDb(id, "POST", "/indexes", { att: attName(att) }));
+  /**
+   * Requests a value index on att: { att, state } ("building" until a checkpoint builds it).
+   * att is an attribute, or an array of 2 to 8 for a multi-attribute index (its rows keyed by
+   * the tuple of their values; queried by tuple predicates), with { required }: the attributes
+   * a row needs a value of to be in it.
+   */
+  async requestIndex(id, att, { required } = {}) {
+    const body = { att: Array.isArray(att) ? att.map(attName) : attName(att) };
+    if (required !== undefined) body.required = required.map(attName);
+    return Client.ok(await this.callDb(id, "POST", "/indexes", body));
   }
 
+  /** Drops att's index (an attribute, or a multi-attribute index's array). */
   async dropIndex(id, att) {
-    return Client.ok(await this.callDb(id, "DELETE", `/indexes/${attName(att).split("/").map(encodeURIComponent).join("/")}`));
+    return Client.ok(await this.callDb(id, "DELETE", `/indexes/${indexPath(att)}`));
   }
 
   /** Waits until att's index is ready (rejects if it failed, or after timeoutMs). */
   async awaitIndex(id, att, { timeoutMs = 60000, intervalMs = 200 } = {}) {
-    const name = attName(att);
+    const name = indexName(att);
     const deadline = Date.now() + timeoutMs;
     for (;;) {
       const s = await this.status(id);