@johnhenry/graceholder 0.0.0-stage → 0.1.0

package/src/adapters/apollo.js

@@ -0,0 +1,48 @@
+// Apollo Client link backed by a graceholder world. `@apollo/client` is an optional peer
+// dependency and is imported only here.
+import { ApolloLink, Observable } from "@apollo/client";
+import { resolveWorld, seedOf, latencyFor } from "./shared.js";
+
+/**
+ * A terminating link: it answers every operation from a world and never forwards.
+ * Place it last in the link chain, in place of `HttpLink`.
+ */
+export class GraceholderLink extends ApolloLink {
+  /** @param {import("./apollo.js").GraceholderLinkOptions} [options] */
+  constructor(options = {}) {
+    super();
+    this.world = resolveWorld(options);
+    this._seed = seedOf(this.world);
+    this._latency = options.latency;
+    this._delay = options.delay;
+  }
+
+  request(operation) {
+    const { query, variables, operationName } = operation;
+    const ms = latencyFor(this._latency, this._seed, { query, operationName, variables });
+    return new Observable((observer) => {
+      let closed = false;
+      let timer;
+      const answer = () => {
+        if (closed) return;
+        // the document goes to the world as is: it accepts a DocumentNode
+        const result = this.world.query(query, { variables, operationName });
+        observer.next(result);
+        observer.complete();
+      };
+      if (this._delay) {
+        Promise.resolve(this._delay(ms)).then(answer);
+      } else if (ms > 0) {
+        timer = setTimeout(answer, ms);
+      } else {
+        answer();
+      }
+      return () => {
+        closed = true;
+        if (timer !== undefined) clearTimeout(timer);
+      };
+    });
+  }
+}
+
+export { GraceholderLink as default };

package/src/adapters/fetch.d.ts

@@ -0,0 +1,15 @@
+import type { World } from "../index.js";
+import type { AdapterOptions } from "./shared.js";
+
+export interface CreateFetchOptions extends AdapterOptions {
+  /** Which requests the world answers. Default: URL paths ending in `/graphql`. A string is an exact path or URL. */
+  match?: string | RegExp | ((url: URL, request: { method: string }) => boolean);
+  /** Where non-matching requests go. Default `globalThis.fetch`. */
+  fallback?: typeof fetch;
+}
+
+export type GraceholderFetch = typeof fetch & { readonly world: World };
+
+/** A fetch-compatible function: GraphQL requests are answered by a world, everything else passes through. */
+export declare function createFetch(options?: CreateFetchOptions): GraceholderFetch;
+export default createFetch;

package/src/adapters/fetch.js

@@ -0,0 +1,150 @@
+// A fetch-compatible function that answers GraphQL requests from a graceholder world. It uses
+// only web-standard globals (Request, Response, URL, Headers), no optional dependency.
+import { parse } from "graphql";
+import { resolveWorld, seedOf, latencyFor, wait } from "./shared.js";
+
+const JSON_HEADERS = { "content-type": "application/json; charset=utf-8" };
+
+const respond = (status, body, extra) => new Response(JSON.stringify(body), { status, headers: { ...JSON_HEADERS, ...extra } });
+const badRequest = (message, status = 400, code = "bad-request") => respond(status, { errors: [{ message, extensions: { code } }] });
+
+// relative URLs resolve against the page when it has an http(s) origin (not about:blank, not a file)
+const base = () => (typeof location !== "undefined" && /^https?:/.test(location.href) ? location.href : "http://localhost/");
+
+function toUrl(input) {
+  const raw = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+  try {
+    return new URL(raw, base());
+  } catch {
+    return null;
+  }
+}
+
+function makeMatcher(match) {
+  if (match === undefined) return (url) => url.pathname.replace(/\/+$/, "").endsWith("/graphql");
+  if (typeof match === "string") return (url) => url.pathname === match || url.href === match;
+  if (match instanceof RegExp) return (url) => match.test(url.href);
+  if (typeof match === "function") return match;
+  throw new TypeError("match must be a string, a RegExp or a function (url, { method }) => boolean");
+}
+
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+
+/** Normalise one GraphQL-over-HTTP request object. @returns {{ error: Response } | { query: string, variables?: object, operationName?: string }} */
+function readOperation(raw) {
+  if (!isObject(raw)) return { error: badRequest("A GraphQL request must be a JSON object.") };
+  if (typeof raw.query !== "string" || raw.query === "") return { error: badRequest("Must provide a query string.") };
+  let variables = raw.variables;
+  if (typeof variables === "string") {
+    try {
+      variables = JSON.parse(variables);
+    } catch {
+      return { error: badRequest("Variables are invalid JSON.") };
+    }
+  }
+  if (variables !== undefined && variables !== null && !isObject(variables)) return { error: badRequest("Variables must be a JSON object.") };
+  const operationName = raw.operationName ?? undefined;
+  if (operationName !== undefined && typeof operationName !== "string") return { error: badRequest("operationName must be a string.") };
+  return { query: raw.query, variables: variables ?? undefined, operationName };
+}
+
+/** The kind of the operation that would run, or undefined when the document does not parse. */
+function operationKind({ query, operationName }) {
+  try {
+    const ops = parse(query).definitions.filter((d) => d.kind === "OperationDefinition");
+    const op = operationName ? ops.find((d) => d.name?.value === operationName) : ops.length === 1 ? ops[0] : undefined;
+    return op?.operation;
+  } catch {
+    return undefined;
+  }
+}
+
+const abortError = (signal) => signal.reason ?? new DOMException("This operation was aborted", "AbortError");
+
+/** Wait for `ms`, rejecting if `signal` aborts first. */
+function waitOrAbort(ms, delay, signal) {
+  if (!signal) return wait(ms, delay);
+  if (signal.aborted) return Promise.reject(abortError(signal));
+  return new Promise((resolve, reject) => {
+    const onAbort = () => reject(abortError(signal));
+    signal.addEventListener("abort", onAbort, { once: true });
+    wait(ms, delay).then(
+      () => {
+        signal.removeEventListener("abort", onAbort);
+        resolve();
+      },
+      reject,
+    );
+  });
+}
+
+/**
+ * @param {import("./fetch.js").CreateFetchOptions} [options]
+ * @returns {typeof fetch & { world: import("../index.js").World }}
+ */
+export function createFetch(options = {}) {
+  const world = resolveWorld(options);
+  const seed = seedOf(world);
+  const matches = makeMatcher(options.match);
+
+  const fetchLike = async function graceholderFetch(input, init) {
+    const url = toUrl(input);
+    const method = (init?.method ?? (typeof input === "object" && input && "method" in input ? input.method : "GET")).toUpperCase();
+    if (!url || !matches(url, { method })) {
+      const next = options.fallback ?? globalThis.fetch;
+      if (typeof next !== "function") throw new TypeError("graceholder fetch: no fallback and no globalThis.fetch");
+      return next(input, init);
+    }
+    const signal = init?.signal ?? (typeof input === "object" && input && "signal" in input ? input.signal : undefined);
+
+    let payload;
+    let isMutationAllowed = true;
+    if (method === "GET" || method === "HEAD") {
+      isMutationAllowed = false;
+      const p = url.searchParams;
+      payload = { query: p.get("query") ?? undefined, variables: p.get("variables") ?? undefined, operationName: p.get("operationName") ?? undefined };
+    } else if (method === "POST") {
+      let text;
+      if (init?.body !== undefined && init.body !== null) text = typeof init.body === "string" ? init.body : await new Response(init.body).text();
+      else if (typeof input === "object" && input && "clone" in input) text = await input.clone().text();
+      else text = "";
+      const type = new Headers(init?.headers ?? (typeof input === "object" && input && "headers" in input ? input.headers : undefined)).get("content-type") ?? "";
+      if (/application\/graphql\b/i.test(type)) {
+        payload = { query: text };
+      } else {
+        try {
+          payload = JSON.parse(text);
+        } catch {
+          return badRequest("POST body is not valid JSON.");
+        }
+      }
+    } else {
+      return badRequest(`GraphQL answers GET and POST, not ${method}.`, 405, "method-not-allowed");
+    }
+
+    const batched = Array.isArray(payload);
+    if (batched && payload.length === 0) return badRequest("A batch must not be empty.");
+    const items = batched ? payload : [payload];
+
+    const outcomes = [];
+    for (const item of items) {
+      const op = readOperation(item);
+      if (op.error) {
+        if (!batched) return op.error;
+        outcomes.push({ errors: [{ message: "Invalid request in batch.", extensions: { code: "bad-request" } }] });
+        continue;
+      }
+      if (!isMutationAllowed && operationKind(op) === "mutation") {
+        return badRequest("Mutations must be sent with POST.", 405, "method-not-allowed");
+      }
+      const ms = latencyFor(options.latency, seed, op);
+      await waitOrAbort(ms, options.delay, signal);
+      outcomes.push(world.query(op.query, { variables: op.variables, operationName: op.operationName }));
+    }
+    return respond(200, batched ? outcomes : outcomes[0]);
+  };
+  fetchLike.world = world;
+  return fetchLike;
+}
+
+export { createFetch as default };

package/src/adapters/shared.d.ts

@@ -0,0 +1,14 @@
+import type { World, WorldOptions } from "../index.js";
+
+/** Simulated latency in milliseconds: fixed, or drawn from [min, max] by the seed and the request. */
+export type Latency = number | [number, number] | { min: number; max: number } | false;
+
+/** Options every adapter shares: a ready `world`, or world options from which one is created. */
+export interface AdapterOptions extends WorldOptions {
+  /** Answer from this world (mutations then persist in it). Wins over the world options. */
+  world?: World;
+  /** Default none. Deterministic: a pure function of the seed and the request. */
+  latency?: Latency;
+  /** Replaces `setTimeout` for the wait; receives the milliseconds. Use it in tests. */
+  delay?: (ms: number) => void | Promise<void>;
+}

package/src/adapters/shared.js

@@ -0,0 +1,65 @@
+// Pieces shared by the client adapters (docs/design.md section 16, Adapters). Nothing here
+// imports an optional peer dependency.
+import { print } from "graphql";
+import { createWorld } from "../world.js";
+import { keyStream } from "../key.js";
+
+const ADAPTER_KEYS = new Set(["world", "latency", "delay", "match", "fallback"]);
+
+/**
+ * The world an adapter answers from: the given `world`, or a new one built from the remaining
+ * options (seed, spec, anchorDate, locale, strict, log, ...).
+ */
+export function resolveWorld(options = {}) {
+  if (options.world) {
+    if (typeof options.world.query !== "function") throw new TypeError("adapter option `world` must come from createWorld()");
+    return options.world;
+  }
+  const worldOptions = {};
+  for (const [k, v] of Object.entries(options)) if (!ADAPTER_KEYS.has(k)) worldOptions[k] = v;
+  return createWorld(worldOptions);
+}
+
+/** The seed that keys latency: the world's own seed, so a world and its adapter agree. */
+export function seedOf(world) {
+  return world.export().seed;
+}
+
+const toRange = (latency) => {
+  if (latency === undefined || latency === false || latency === null) return null;
+  if (typeof latency === "number") return [latency, latency];
+  if (Array.isArray(latency)) return [latency[0], latency[1]];
+  if (typeof latency === "object") return [latency.min, latency.max];
+  throw new TypeError("latency must be a number, [min, max] or { min, max }");
+};
+
+/**
+ * Milliseconds of simulated latency for one request. It is a pure function of the seed and the
+ * request (operation name, query text, variables): the same request always waits the same time.
+ * @returns {number} 0 when latency is off
+ */
+export function latencyFor(latency, seed, { query, operationName, variables }) {
+  const range = toRange(latency);
+  if (!range) return 0;
+  const [lo, hi] = range;
+  if (!Number.isSafeInteger(lo) || !Number.isSafeInteger(hi) || lo < 0 || hi < lo) {
+    throw new RangeError("latency needs non-negative integers with min <= max");
+  }
+  if (lo === hi) return lo;
+  const text = typeof query === "string" ? query : print(query);
+  return keyStream({
+    seed,
+    scope: "a",
+    typeName: "$adapter",
+    entityKey: operationName ?? "",
+    fieldName: "latency",
+    subKeys: [text, JSON.stringify(variables ?? {})],
+  }).int(lo, hi);
+}
+
+/** Wait `ms` (the injected `delay`, or setTimeout). Resolves at once for 0. */
+export function wait(ms, delay) {
+  if (delay) return Promise.resolve(delay(ms));
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/adapters/urql.d.ts

@@ -0,0 +1,8 @@
+import type { Exchange } from "@urql/core";
+import type { AdapterOptions } from "./shared.js";
+
+export type GraceholderExchangeOptions = AdapterOptions;
+
+/** An exchange that answers queries and mutations from a graceholder world; it replaces `fetchExchange`. */
+export declare function graceholderExchange(options?: GraceholderExchangeOptions): Exchange;
+export default graceholderExchange;

package/src/adapters/urql.js

@@ -0,0 +1,53 @@
+// urql exchange backed by a graceholder world. `@urql/core` and `wonka` are optional peer
+// dependencies and are imported only here.
+import { makeResult } from "@urql/core";
+import { pipe, share, filter, mergeMap, merge, fromPromise, takeUntil } from "wonka";
+import { resolveWorld, seedOf, latencyFor, wait } from "./shared.js";
+
+const answers = (op) => op.kind === "query" || op.kind === "mutation";
+
+function operationNameOf(operation) {
+  const def = operation.query.definitions.find((d) => d.kind === "OperationDefinition");
+  return def?.name?.value;
+}
+
+/**
+ * An exchange that answers query and mutation operations from a world.
+ *
+ * It terminates those operations, so it takes the place of `fetchExchange`: put it last, after
+ * `cacheExchange` (and after `mapExchange`, `authExchange` and the like, which do not apply to
+ * a backend that is not there). Subscriptions are passed to `forward`, so an exchange for
+ * them may follow it. Keeping `fetchExchange` after it is harmless: it never sees a query or a
+ * mutation.
+ */
+export function graceholderExchange(options = {}) {
+  const world = resolveWorld(options);
+  const seed = seedOf(world);
+
+  return ({ forward }) =>
+    (ops$) => {
+      const shared$ = share(ops$);
+      const handled$ = pipe(
+        shared$,
+        filter(answers),
+        mergeMap((operation) => {
+          const variables = operation.variables ?? undefined;
+          const operationName = operationNameOf(operation);
+          const ms = latencyFor(options.latency, seed, { query: operation.query, operationName, variables });
+          // a teardown with the same key cancels the answer that is still waiting
+          const teardown$ = pipe(
+            shared$,
+            filter((o) => o.kind === "teardown" && o.key === operation.key),
+          );
+          const result$ = fromPromise(
+            wait(ms, options.delay).then(() => makeResult(operation, world.query(operation.query, { variables, operationName }))),
+          );
+          return pipe(result$, takeUntil(teardown$));
+        }),
+      );
+      const forwarded$ = forward(pipe(shared$, filter((op) => !answers(op))));
+      return merge([handled$, forwarded$]);
+    };
+}
+
+export { graceholderExchange as default };

package/src/anchor.js

@@ -0,0 +1,13 @@
+// The constant default anchor and its parsing (docs/design.md 6.4). The clock is never read.
+import { GraceholderError } from "./errors.js";
+
+export const DEFAULT_ANCHOR = "2025-01-01T00:00:00.000Z";
+
+/** @param {string|Date} anchorDate @returns {number} milliseconds since the epoch */
+export function anchorMs(anchorDate) {
+  const ms = anchorDate instanceof Date ? anchorDate.getTime() : typeof anchorDate === "string" ? Date.parse(anchorDate) : NaN;
+  if (!Number.isFinite(ms)) {
+    throw new GraceholderError("bad-options", `anchorDate must be an ISO date string or a Date, got ${String(anchorDate)}`);
+  }
+  return ms;
+}

package/src/args.js

@@ -0,0 +1,41 @@
+// Argument handling: canonical JSON, identifying arguments and collection keys
+// (docs/design.md 3.1, 3.3). FROZEN at 1.0.0.
+
+export const PAGING_ARGS = new Set(["first", "last", "after", "before", "offset", "limit", "skip", "take", "page", "pageSize", "perPage", "cursor"]);
+/** Identifying argument names, in priority order. */
+export const ID_ARGS = ["id", "key", "slug", "uuid", "email", "username", "handle", "sku"];
+const COMPOSITE_SEP = "\x1e";
+
+export function canonicalJson(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  const keys = Object.keys(value).filter((k) => value[k] !== undefined).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(",")}}`;
+}
+
+const keyText = (v) => (typeof v === "string" ? v : canonicalJson(v));
+
+/**
+ * The entity key selected by identifying arguments, or undefined.
+ * @param {Record<string, any>} args
+ * @param {string[]} [keyArgs] explicit (possibly composite) identifying argument names
+ */
+export function entityKeyFromArgs(args, keyArgs) {
+  if (keyArgs && keyArgs.length) {
+    const parts = [];
+    for (const name of [...keyArgs].sort()) {
+      if (args[name] === undefined || args[name] === null) return undefined;
+      parts.push(keyText(args[name]));
+    }
+    return parts.join(COMPOSITE_SEP);
+  }
+  for (const name of ID_ARGS) if (args[name] !== undefined && args[name] !== null) return keyText(args[name]);
+  return undefined;
+}
+
+/** Canonical JSON of the non-paging arguments, or "" when there are none. */
+export function argsKeyOf(args) {
+  const rest = {};
+  for (const [k, v] of Object.entries(args)) if (!PAGING_ARGS.has(k) && v !== undefined) rest[k] = v;
+  return Object.keys(rest).length ? canonicalJson(rest) : "";
+}

package/src/bulk/csv.js

@@ -0,0 +1,118 @@
+// CSV (RFC 4180) with flattened column paths. See docs/api.md "toCSV".
+import { GraceholderError } from "../errors.js";
+import { isAsync, isSync } from "./source.js";
+import { shapeOfDocument, shapeOfValue } from "./shape.js";
+
+const bad = (msg) => new GraceholderError("bad-options", msg);
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
+/**
+ * The ordered column paths of a shape (`address.city`, `tags`, `posts` for a JSON-encoded list).
+ * @param {import("./shape.js").ShapeNode} node
+ * @param {{ explode: (path: string) => boolean, prefix?: string }} options
+ * @returns {string[]}
+ */
+export function columnsOf(node, { explode, prefix = "" }) {
+  const out = [];
+  for (const f of node.fields.values()) {
+    const path = prefix + f.key;
+    const exploded = f.list && explode(path);
+    if (f.kind === "object" && (!f.list || exploded)) out.push(...columnsOf(/** @type {any} */ (f.node), { explode, prefix: `${path}.` }));
+    else out.push(path);
+  }
+  return out;
+}
+
+/** Rows (maps of column path to value) for one item; a non-exploded item is exactly one row. */
+function rowsOf(node, obj, explode, prefix) {
+  /** @type {Map<string, any>[]} */
+  let rows = [new Map()];
+  const cross = (subRows) => (rows = rows.flatMap((r) => subRows.map((s) => new Map([...r, ...s]))));
+  for (const f of node.fields.values()) {
+    const path = prefix + f.key;
+    const v = obj == null ? null : obj[f.key];
+    const exploded = f.list && explode(path);
+    if (f.kind === "object" && (!f.list || exploded)) {
+      const blank = () => new Map(columnsOf(f.node, { explode, prefix: `${path}.` }).map((c) => [c, null]));
+      if (!f.list) {
+        cross(isObject(v) ? rowsOf(f.node, v, explode, `${path}.`) : [blank()]);
+      } else {
+        const subs = Array.isArray(v) ? v.flatMap((e) => rowsOf(f.node, e, explode, `${path}.`)) : [];
+        cross(subs.length ? subs : [blank()]);
+      }
+    } else if (f.list && exploded) {
+      const values = Array.isArray(v) && v.length ? v : [null];
+      cross(values.map((e) => new Map([[path, e]])));
+    } else {
+      cross([new Map([[path, v === undefined ? null : v]])]);
+    }
+  }
+  return rows;
+}
+
+function cell(value, delimiter) {
+  if (value === null || value === undefined) return "";
+  const text = typeof value === "string" ? value : typeof value === "object" ? JSON.stringify(value) : String(value);
+  if (text === "") return '""'; // an empty string is not a null
+  return text.includes(delimiter) || /["\r\n]/.test(text) ? `"${text.replaceAll('"', '""')}"` : text;
+}
+
+/**
+ * @param {any} source items, for example a `stream()` (an iterable or an async iterable)
+ * @param {{ delimiter?: string, eol?: string, header?: boolean, columns?: string[], lists?: "json"|"explode", explode?: string[] }} [options]
+ * @returns {Generator<string>|AsyncGenerator<string>} the header line, then one or more lines per item
+ */
+export function toCSV(source, options = {}) {
+  const delimiter = options.delimiter ?? ",";
+  const eol = options.eol ?? "\r\n";
+  const header = options.header ?? true;
+  if (typeof delimiter !== "string" || delimiter.length !== 1 || /["\r\n]/.test(delimiter)) throw bad(`delimiter must be one character other than a quote or a line break, got ${JSON.stringify(delimiter)}`);
+  if (typeof eol !== "string" || !/^(\r\n|\n|\r)$/.test(eol)) throw bad('eol must be "\\r\\n", "\\n" or "\\r"');
+  const lists = options.lists ?? "json";
+  if (lists !== "json" && lists !== "explode") throw bad(`lists must be "json" or "explode", got ${JSON.stringify(lists)}`);
+  if (options.columns !== undefined && (!Array.isArray(options.columns) || !options.columns.every((c) => typeof c === "string"))) throw bad("columns must be an array of column paths");
+  if (options.explode !== undefined && (!Array.isArray(options.explode) || !options.explode.every((c) => typeof c === "string"))) throw bad("explode must be an array of list paths");
+  if (!isSync(source) && !isAsync(source)) throw bad("the source must be an iterable or an async iterable of items, for example a stream()");
+  // `explode` names the lists to explode; `lists: "explode"` alone explodes every list
+  const wanted = options.explode ? new Set(options.explode) : null;
+  const explode = wanted ? (path) => wanted.has(path) : lists === "explode" ? () => true : () => false;
+
+  // a stream knows its shape; any other source is sampled from its first item
+  /** @type {any} */
+  let shape = source?.plan ? shapeOfDocument(source.plan.inferred.document, source.plan.inferred.model, source.plan.inferred.rootType ?? "Query") : null;
+  /** @type {string[]} */
+  // @ts-ignore assigned by begin() before any row is written
+  let columns = options.columns;
+  const line = (cells) => `${cells.map((c) => cell(c, delimiter)).join(delimiter)}${eol}`;
+  const begin = (sample) => {
+    shape ??= shapeOfValue(sample);
+    columns ??= columnsOf(/** @type {any} */ (shape), { explode });
+    return header ? [line(columns)] : [];
+  };
+  const rowLines = (item) => {
+    const obj = isObject(item) ? item : { value: item };
+    return rowsOf(shape, obj, explode, "").map((r) => line(columns.map((c) => r.get(c) ?? null)));
+  };
+  let started = false;
+  const step = (item) => {
+    const out = [];
+    if (!started) {
+      started = true;
+      out.push(...begin(isObject(item) ? item : { value: item }));
+    }
+    out.push(...rowLines(item));
+    return out;
+  };
+  const finish = () => (started ? [] : begin({}));
+
+  if (isSync(source)) {
+    return (function* () {
+      for (const item of source) yield* step(item);
+      yield* finish();
+    })();
+  }
+  return (async function* () {
+    for await (const item of source) yield* step(item);
+    yield* finish();
+  })();
+}

package/src/bulk/ndjson.js

@@ -0,0 +1,10 @@
+// Newline-delimited JSON: one compact JSON document per item, each followed by "\n".
+import { mapSource } from "./source.js";
+
+/**
+ * @param {Iterable<any>|AsyncIterable<any>} source items, for example a `stream()`
+ * @returns {Generator<string>|AsyncGenerator<string>} lines (strings ending in "\n"); join them or pipe them to a writable
+ */
+export function toNDJSON(source) {
+  return mapSource(source, (item) => `${JSON.stringify(item === undefined ? null : item)}\n`);
+}