stratus-db 0.4.0 → 0.5.0

package/README.md

@@ -66,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.4.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.4.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;
@@ -673,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 = {};
@@ -687,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 }));
@@ -705,8 +718,8 @@ 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;