@johnhenry/graceholder 0.0.0-stage → 0.0.0

package/src/bulk/stream.js

@@ -0,0 +1,55 @@
+// stream(): the root collection of a query as a lazy sync and async iterable.
+import { planStream, windows } from "./plan.js";
+
+/**
+ * A lazily generated collection. Iterating generates one window of items at a time, so memory stays
+ * bounded however many items are consumed. Every iteration starts again at the first item.
+ */
+export class Stream {
+  /**
+   * @param {any} query
+   * @param {any} options
+   * @param {any} [world]
+   */
+  constructor(query, options, world) {
+    this.plan = planStream(query, options, world);
+    /** what toSQL needs to plan the same stream again with entity keys */
+    this.config = { query, options, world };
+  }
+
+  /** The response key of the streamed root field. */
+  get field() {
+    return this.plan.key;
+  }
+
+  /** Windows of items (arrays of at most `chunkSize`), lazily. */
+  *chunks() {
+    for (const w of windows(this.plan)) yield w.items;
+  }
+
+  *[Symbol.iterator]() {
+    for (const w of windows(this.plan)) yield* w.items;
+  }
+
+  async *[Symbol.asyncIterator]() {
+    for (const w of windows(this.plan)) {
+      for (const item of w.items) yield item;
+      await Promise.resolve(); // let other work run between windows
+    }
+  }
+}
+
+/**
+ * The root collection of a query as a lazy iterable of items. Item k equals item k of the windowed
+ * query `field(offset: k, first: 1)`.
+ * @param {any} query
+ * @param {any} [options]
+ */
+export function stream(query, options = {}) {
+  return new Stream(query, options, undefined);
+}
+
+/** Used by createWorld().stream. */
+export function streamWorld(query, options, world) {
+  return new Stream(query, options, world);
+}

package/src/cursor.js

@@ -0,0 +1,25 @@
+// Opaque, stable cursors: base64url("gc1:" + index), unpadded (docs/design.md 3.4). FROZEN at 1.0.0.
+import { GraceholderError } from "./errors.js";
+
+const PREFIX = "gc1:";
+
+export function encodeCursor(index) {
+  return btoa(PREFIX + index).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+/** @returns {number} the non-negative integer index inside the cursor */
+export function decodeCursor(cursor) {
+  const bad = () => new GraceholderError("bad-cursor", `invalid cursor ${JSON.stringify(cursor)}`, { hint: "use a cursor returned by graceholder" });
+  if (typeof cursor !== "string" || !/^[A-Za-z0-9_-]+$/.test(cursor)) throw bad();
+  let text;
+  try {
+    const b64 = cursor.replace(/-/g, "+").replace(/_/g, "/");
+    text = atob(b64 + "=".repeat((4 - (b64.length % 4)) % 4));
+  } catch {
+    throw bad();
+  }
+  if (!text.startsWith(PREFIX) || !/^[0-9]+$/.test(text.slice(PREFIX.length))) throw bad();
+  const n = Number(text.slice(PREFIX.length));
+  if (!Number.isSafeInteger(n)) throw bad();
+  return n;
+}