stratus-db 0.3.0 → 0.5.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),
@@ -65,6 +66,14 @@ Gateway's 403 Forbidden for a brand-new key, which works within a minute or two
 - Keys (with a key reaching every database): `listKeys()`, `createKey({name, scope})`,
   `revokeKey(keyId)`.
 - Codec: `encode`, `decode` (typed-JSON text), `toJSONValue`, `fromJSONValue`.
+- `rowId(n)`: a row named by its row id.
+
+**Keys and row ids.** A primary key is a UUID (`squuid()`), a string or an integer (a long:
+past 2^53, pass a `BigInt`). Every row also carries `"stratus/id"`, a row id the database assigns
+when the row is made. `transact` answers `{ t, pks, ids }`. Where a key goes - `pull`, `delete`,
+a row's key attribute - `rowId(n)` names a row by its id; a bare integer is always a primary key.
+Queries return rows in row id order (the order they were made), `{ order: "desc" }` newest first;
+`next` is a row id.
 
 Queries: docs/query.md ("JSON"). Requests go to `<url>/v1/dbs/<id>/...` with `Authorization:
 Bearer <apiKey>`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stratus-db",
-  "version": "0.3.0",
+  "version": "0.5.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.5.0";
 
 const USER_AGENT = `stratus-db-js/${VERSION}`;
 const IN_NODE = typeof process !== "undefined" && process.versions != null && process.versions.node != null;
@@ -269,6 +269,13 @@ export const localDate = (text) => LocalDate.parse(text);
 export const double = (v) => new Double(v);
 export const list = (...items) => List.from(items);
 
+/**
+ * A row id, tagged: { "stratus/id": n }. Every row carries its row id (row["stratus/id"]), a
+ * long the database assigns when the row is made; a command or a pull names a row by it where a
+ * bare integer would be a primary key.
+ */
+export const rowId = (n) => ({ "stratus/id": n });
+
 // ------------------------------------------------------------------ Typed JSON
 // Typed JSON (docs/json.md): stratus's encoding, MongoDB Extended JSON v2's tags where they
 // mean the same and stratus's own where it has none. encode/decode work on JSON text;
@@ -529,6 +536,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);
@@ -664,9 +680,11 @@ export class Client {
   }
 
   /**
-   * Transacts: { t, pks, duplicate? }. tx: rows (each with its primary key: squuid()),
-   * retract: rows of attributes to remove, delete: primary keys, txId: makes a retry safe,
-   * match: rows whose attributes must hold those values now (else a 409 "conflict").
+   * Transacts: { t, pks, ids, duplicate? } - pks and ids are tx's rows' primary keys and row ids,
+   * in order. tx: rows (each with its primary key: squuid(); or naming its row by rowId(n) in
+   * the key's place), retract: rows of attributes to remove, delete: primary keys (or rowId(n)),
+   * txId: makes a retry safe, match: rows whose attributes must hold those values now (else a
+   * 409 "conflict").
    */
   async transact(id, { tx, retract, delete: del, txId, match }) {
     const body = {};
@@ -678,7 +696,11 @@ export class Client {
     return Client.ok(await this.callDb(id, "POST", "/transact", body));
   }
 
-  /** One page of query q (docs/query.md, "JSON"): { rows, next, t }. */
+  /**
+   * One page of query q (docs/query.md, "JSON"): { rows, next, t } - rows in row id order (the
+   * order they were made; { order: "desc" }: newest first), next the cursor (a row id) to pass
+   * as after.
+   */
   async query(id, q = {}) {
     const { asOf, ...rest } = q;
     return Client.ok(await this.callDb(id, "POST", "/query", asOf === undefined ? rest : { ...rest, "as-of": asOf }));
@@ -696,25 +718,33 @@ export class Client {
   }
 
   /**
-   * The rows of primary keys pks, in order (null where there is none); { asOf: t } reads them as
-   * they stood after transaction t.
+   * The rows of pks (primary keys, or rowId(n)), in order (null where there is none); { asOf: t }
+   * reads them as they stood after transaction t.
    */
   async pull(id, pks, { asOf } = {}) {
     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);