@johnhenry/graceholder 0.0.0-stage → 0.1.0

package/src/index.d.ts

@@ -0,0 +1,507 @@
+import type { DocumentNode, GraphQLError, GraphQLSchema, IntrospectionQuery } from "graphql";
+import type { ResultOf, ItemOf } from "./typed.js";
+
+export type { ResultOf, ItemOf };
+
+/** Key-scheme version literal (frozen at 1.0.0). */
+export declare const KEY_SCHEME: "gh1";
+
+/** A schema for schema mode: SDL text, a parsed SDL document, an introspection result, or a graphql-js schema. */
+export type SchemaInput = string | DocumentNode | GraphQLSchema | IntrospectionQuery | { data: IntrospectionQuery };
+/** Edge-case modes (docs/design.md section 16, Scenarios). Combine them in an array. */
+export type Scenario = "empty" | "huge" | "nulls" | "unicode" | "boundary" | "errors";
+/** The scenario names, in the order a set is normalised to. */
+export declare const SCENARIOS: readonly Scenario[];
+
+export interface ScenarioOptions {
+  /** Share of eligible fields that fail under the `errors` scenario, from 0 to 1. Default 0.25. */
+  errorRate?: number;
+}
+
+/** A GraphQL error in JSON form (what the `errors` scenario returns). */
+export interface ResultError {
+  message: string;
+  locations?: Array<{ line: number; column: number }>;
+  path?: Array<string | number>;
+  extensions?: Record<string, unknown>;
+}
+
+export interface Options {
+  /** Default `"graceholder"`. Numbers are stringified (`String(n)`). */
+  seed?: string | number;
+  /** Variables for the operation. */
+  variables?: Record<string, unknown>;
+  operationName?: string;
+  /** Default `"en"`, the only locale in this release; others throw `unknown-locale`. */
+  locale?: string;
+  /** Default constant `"2025-01-01T00:00:00.000Z"`; the clock is never read. */
+  anchorDate?: string | Date;
+  /** `"throw"` (default) throws a {@link GraceholderError}; `"result"` returns `{ data, errors }`. */
+  errors?: "throw" | "result";
+  /** Side-car spec keyed by path pattern (`users.name`, `*.status`, `**.createdAt`, `@User.email`). */
+  spec?: Spec;
+  /** Make a spec path that matches no field an error (`unused-spec-path`) instead of a reported decision. */
+  strict?: boolean;
+  /**
+   * Vocabulary packs to enable, by registered name or as objects imported from
+   * `@johnhenry/graceholder/packs/<name>`. Default none. Packs add coherent geo, commerce, finance and
+   * (fictional) health data; see docs/api.md. Pass `["geo"]` only after `registerPack(geo)`.
+   */
+  packs?: Array<string | Pack>;
+  /**
+   * `"svg"` makes image, avatar, thumbnail, picture, photo and logo fields deterministic inline SVG data
+   * URIs (initials avatars, geometric placeholders) instead of example URLs. Default `"url"`.
+   */
+  images?: "url" | "svg";
+  /**
+   * `"realistic"` makes popularity-like fields (views, likes, followers, sales, ...) heavy-tailed and
+   * turns fields named like `salesHistory { date value }` into time series. Default `"uniform"` (the 0.x behaviour).
+   */
+  distributions?: "uniform" | "realistic";
+  /**
+   * Schema mode: the query is validated against this schema, and enums, nullability, custom scalars,
+   * lists and unions/interfaces come from it instead of from name heuristics.
+   */
+  schema?: SchemaInput;
+  /**
+   * Edge-case mode(s), one name or an array: `empty`, `huge`, `nulls`, `unicode`, `boundary`, `errors`.
+   * Applies to every field unless a spec entry sets its own `scenario`. Default none (output unchanged).
+   */
+  scenario?: Scenario | Scenario[] | "none";
+  scenarioOptions?: ScenarioOptions;
+}
+
+/** Distribution names accepted by the `dist` argument of `int`, `float` and `money`. */
+export type Distribution = "uniform" | "normal" | "lognormal" | "zipf" | "powerlaw";
+
+/** A vocabulary pack: frozen tables plus the generators and name rules that use them. */
+export interface Pack {
+  readonly name: string;
+  readonly version: number;
+  readonly vocab: Readonly<Record<string, readonly unknown[]>>;
+  /** SDL scalar type of generators whose output is not a String. */
+  readonly types?: Readonly<Record<string, "Int" | "Float" | "Boolean" | "DateTime" | "String">>;
+  generators(vocab: Record<string, any>, base: Record<string, (ctx: any) => unknown>): Record<string, (ctx: any) => unknown>;
+  rules?(ctx: { tokens: string[]; first: string; last: string; kind: string; typeName: string; list: boolean }): { sdl: string; gen: string; args?: Record<string, unknown>; nullable?: boolean } | null;
+  inherit?(typeName: string): boolean;
+}
+
+/** Make a pack addressable by name in `options.packs`. Registering the same pack twice is fine. */
+export declare function registerPack(pack: Pack): Pack;
+/** Names of the packs registered so far. */
+export declare function registeredPacks(): string[];
+
+export type Count = number | [number, number] | { min: number; max: number };
+
+export interface FieldSpec {
+  list?: boolean;
+  one?: boolean;
+  count?: Count;
+  gen?: string | { name: string; args?: Record<string, unknown> };
+  pattern?: string;
+  pick?: Array<unknown | { value: unknown; weight: number }>;
+  nullRate?: number;
+  derive?: { from: string };
+  type?: string;
+  seed?: string | number;
+  /** Identifying argument name(s); several names form a composite key. */
+  key?: string | string[];
+  /** Draw members of a nested collection from the type pool. */
+  shared?: boolean;
+  /** Do not share the type pool: entities are owned by their parent. */
+  own?: boolean;
+  /** Scenario(s) for this field only (replacing the global ones); `"none"` or `[]` opts the field out. */
+  scenario?: Scenario | Scenario[] | "none";
+}
+
+export type MutationOp = "create" | "update" | "delete";
+
+/** How mutations are read (docs/design.md section 16, World); used by a world only. */
+export interface MutationSpec {
+  /** Extra verbs: the first word of a mutation field name. */
+  verbs?: Record<string, MutationOp>;
+  /** Per mutation field: what it does, which type it affects, where its id and input are. */
+  fields?: Record<string, { op: MutationOp; type?: string; idArg?: string; input?: string; read?: string }>;
+  /** `"Post.authorId": "User"` makes a created Post belong to that User's `posts`-like collections. */
+  relations?: Record<string, string>;
+  /** Where created entities go: the end of finite collections and the start of endless ones by default. */
+  position?: "start" | "end";
+}
+
+export type Spec = { [path: string]: FieldSpec | { poolSize?: number; endlessTotal?: number } | MutationSpec } & {
+  $options?: { poolSize?: number; endlessTotal?: number };
+  $mutations?: MutationSpec;
+};
+
+export type Data = Record<string, unknown>;
+
+export interface ResultMode<D = Data> {
+  data?: D;
+  errors?: readonly GraphQLError[] | ResultError[];
+}
+
+/**
+ * Generate data for a query. Synchronous; same inputs give byte-identical output.
+ *
+ * When `query` is a string literal the result is typed from the query text (see {@link ResultOf}:
+ * selection sets, aliases, lists, nested lists, fragments, unions, connections and scalar types by
+ * field name). A `string` that is not a literal, or a parsed document, gives `Record<string, unknown>`.
+ */
+export declare function graceholder<Q extends string>(query: Q, options?: Options & { errors?: "throw" }): ResultOf<Q>;
+export declare function graceholder<Q extends string>(query: Q, options: Options & { errors: "result" }): ResultMode<ResultOf<Q>>;
+export declare function graceholder(query: DocumentNode, options?: Options & { errors?: "throw" }): Data;
+export declare function graceholder(query: DocumentNode, options: Options & { errors: "result" }): ResultMode;
+export declare function graceholder(query: string | DocumentNode, options: Options): Data | ResultMode;
+
+export interface Decision {
+  path: string;
+  field: string;
+  kind: "list" | "object" | "scalar" | "arg" | "type" | "count" | "null" | "key" | "seed" | "unused" | "nullable";
+  value: unknown;
+  source: "directive" | "spec" | "heuristic" | "default" | "schema";
+  rule?: string;
+}
+
+export interface InferResult {
+  sdl: string;
+  decisions: Decision[];
+  /** The selected operation and the fragments it uses. */
+  document: DocumentNode;
+}
+
+/** Infer the SDL (and the decisions behind it) from a query alone. */
+export declare function inferSchema(
+  query: string | DocumentNode,
+  spec?: Spec,
+  options?: Pick<Options, "operationName" | "variables" | "strict" | "packs" | "images" | "distributions" | "schema" | "scenario">,
+): InferResult;
+
+export type ErrorCode =
+  | "unknown-directive"
+  | "unknown-generator"
+  | "bad-generator-args"
+  | "conflicting-shape"
+  | "bad-operation"
+  | "bad-options"
+  | "bad-cursor"
+  | "bad-arguments"
+  | "unknown-locale"
+  | "bad-spec"
+  | "bad-directive"
+  | "bad-derive"
+  | "conflicting-overrides"
+  | "unused-spec-path"
+  | "bad-suggestion"
+  | "bad-pack"
+  | "unknown-pack"
+  | "bad-schema"
+  | "schema-conflict"
+  | "bad-samples"
+  | "unsupported"
+  | "bad-mutation"
+  | "bad-path"
+  | "not-found"
+  | "graphql"
+  | "internal";
+
+export declare class GraceholderError extends Error {
+  code: ErrorCode;
+  path?: string;
+  hint?: string;
+  /** For `graphql` errors, every underlying GraphQL error. */
+  errors?: readonly GraphQLError[] | ResultError[];
+  /** For `graphql` errors raised by the `errors` scenario, the partial data. */
+  data?: Data | null;
+  constructor(code: ErrorCode, message: string, extra?: { path?: string; hint?: string; cause?: unknown });
+}
+
+/** Version tag at the top of the suggestSpec prompt. */
+export declare const SUGGEST_PROMPT_VERSION: string;
+
+/** The prompt `suggestSpec` sends (query, inferred SDL and decisions, spec grammar, generator names). */
+export declare function buildSuggestPrompt(query: string, spec?: Spec, options?: Pick<Options, "packs" | "distributions" | "images">): string;
+
+/**
+ * Authoring-time helper: ask an injected model for a spec, validate it against the query, and offer
+ * one repair round. The core never calls it and imports no LLM SDK.
+ * @throws {GraceholderError} `bad-suggestion` when the reply is still invalid after the repair round
+ */
+export declare function suggestSpec(
+  query: string,
+  opts: { llm: (prompt: string) => Promise<string>; spec?: Spec } & Pick<Options, "packs" | "distributions" | "images">,
+): Promise<Spec>;
+
+export type WorldEntry =
+  | { op: "pin"; type: string; key: string; fields: Record<string, unknown> }
+  | { op: "create"; type: string; key: string; fields: Record<string, unknown>; rel?: Array<{ ownerType: string; ownerKey: string }>; mutation?: string }
+  | { op: "update"; type: string; key: string; fields: Record<string, unknown>; rel?: Array<{ ownerType: string; ownerKey: string }>; mutation?: string }
+  | { op: "delete"; type: string; key: string; mutation?: string };
+
+export interface ExportedWorld {
+  seed: string | number;
+  spec?: Spec;
+  anchorDate: string;
+  locale: string;
+  /** Present only when the world was created with these options; packs are exported by name (use `registerPack` before replaying). */
+  packs?: string[];
+  images?: "url" | "svg";
+  distributions?: "uniform" | "realistic";
+  scenario?: Scenario[];
+  scenarioOptions?: ScenarioOptions;
+  log: WorldEntry[];
+}
+
+export interface WorldOptions {
+  seed?: string | number;
+  spec?: Spec;
+  anchorDate?: string | Date;
+  locale?: string;
+  strict?: boolean;
+  /** Same meaning as in {@link Options}; they apply to every query of the world. */
+  packs?: Array<string | Pack>;
+  images?: "url" | "svg";
+  distributions?: "uniform" | "realistic";
+  /** Schema mode for the world's queries. */
+  schema?: SchemaInput;
+  scenario?: Scenario | Scenario[] | "none";
+  scenarioOptions?: ScenarioOptions;
+  /** A log from `world.export()`; replayed at creation. */
+  log?: WorldEntry[];
+}
+
+export interface WorldResult<D = Data> {
+  data?: D | null;
+  errors?: Array<{ message: string; locations?: Array<{ line: number; column: number }>; path?: Array<string | number>; extensions?: Record<string, unknown> }>;
+}
+
+export interface World {
+  /** Run a query or a mutation. Never throws for a bad operation: failures come back as `errors`. */
+  query<Q extends string>(query: Q, options?: { variables?: Record<string, unknown>; operationName?: string }): WorldResult<ResultOf<Q>>;
+  query(query: DocumentNode, options?: { variables?: Record<string, unknown>; operationName?: string }): WorldResult;
+  /** The root collection of a query as a lazy iterable (see {@link stream}); reflects pins and mutations when each window is generated. */
+  stream<Q extends string, F extends string | undefined = undefined>(query: Q, options?: Omit<StreamOptions, keyof Options> & Pick<Options, "variables" | "operationName"> & { field?: F }): Stream<ItemOf<Q, F>>;
+  stream(query: string | DocumentNode, options?: Omit<StreamOptions, keyof Options> & Pick<Options, "variables" | "operationName">): Stream;
+  /** Override fields of the entity `"Type:key"`. */
+  pin(ref: string, fields: Record<string, unknown>): World;
+  export(): ExportedWorld;
+  reset(): World;
+  /** Like the top-level {@link explain}, for this world. */
+  explain(query: string | DocumentNode, path: string | Array<string | number>, options?: Omit<Options, "errors" | "seed" | "spec" | "anchorDate" | "locale">): Explanation;
+}
+
+/** A persistent, deterministic world shared across queries. */
+export declare function createWorld(options?: WorldOptions): World;
+
+export interface SpecFromSamplesOptions {
+  /** Schema mode: enums (and their frequencies), nullability, scalar types and list-ness come from the schema. */
+  schema?: SchemaInput;
+  /**
+   * Allow enum-like sets of string values to be copied into the spec as `pick`. `true` allows every
+   * field; an array allows only the listed field paths. Default `false`: free text is never copied.
+   */
+  allowValues?: boolean | string[];
+  /** Largest number of distinct values that counts as an enumeration (default 12). */
+  maxEnum?: number;
+  /** Dates are learned as days before this anchor (default: the library's default anchor). */
+  anchorDate?: string | Date;
+  operationName?: string;
+  variables?: Record<string, unknown>;
+}
+
+export interface SampleNote {
+  path: string;
+  kind: "withheld" | "kept-heuristic" | "skipped";
+  message: string;
+}
+
+/**
+ * Infer a side-car spec from one or more real responses to a query. Deterministic; the result is a plain
+ * object to commit. Never copies free text; see `allowValues`.
+ * @throws {GraceholderError} `bad-samples` when a sample does not fit the query (or the schema)
+ */
+export declare function specFromSamples(
+  query: string | DocumentNode,
+  samples: Data | { data: Data } | Array<Data | { data: Data }>,
+  opts?: SpecFromSamplesOptions,
+): Spec;
+
+/** Like {@link specFromSamples}, and also returns notes about what was withheld or left to the heuristics. */
+export declare function analyzeSamples(
+  query: string | DocumentNode,
+  samples: Data | { data: Data } | Array<Data | { data: Data }>,
+  opts?: SpecFromSamplesOptions,
+): { spec: Spec; notes: SampleNote[] };
+
+// ---- bulk generation (docs/design.md section 19) -------------------------------------------------
+
+export interface StreamOptions extends Omit<Options, "errors"> {
+  /** How many items to yield. Required unless the collection has a declared size (`@count`, or a spec `count`). */
+  count?: number;
+  /** Index of the first item (default 0): item k equals item k of `field(offset: k, first: 1)`. */
+  offset?: number;
+  /** Items generated per window (default 500, at most 10000). Never changes the output. */
+  chunkSize?: number;
+  /** Response key of the root collection to stream; default the first root list or connection. */
+  field?: string;
+}
+
+/** A lazily generated collection: a sync and an async iterable, iterable any number of times. */
+export interface Stream<T = Record<string, any>> extends Iterable<T>, AsyncIterable<T> {
+  /** Response key of the streamed root field. */
+  readonly field: string;
+  /** The items in windows of at most `chunkSize`. */
+  chunks(): Generator<T[]>;
+}
+
+/** The root collection of a query as a lazy iterable of items, with bounded memory. */
+export declare function stream<Q extends string, F extends string | undefined = undefined>(query: Q, options?: StreamOptions & { field?: F }): Stream<ItemOf<Q, F>>;
+export declare function stream<T = Record<string, any>>(query: string | DocumentNode, options?: StreamOptions): Stream<T>;
+
+/** One compact JSON document per item, each followed by a newline. A sync source gives a sync generator. */
+export declare function toNDJSON(source: Iterable<unknown>): Generator<string>;
+export declare function toNDJSON(source: AsyncIterable<unknown>): AsyncGenerator<string>;
+
+export interface CsvOptions {
+  /** One character, default `","`. */
+  delimiter?: string;
+  /** Line ending, default `"\r\n"` (RFC 4180). */
+  eol?: "\r\n" | "\n" | "\r";
+  /** Write the header line (default true). */
+  header?: boolean;
+  /** Column paths to write, in order (default: every flattened path). */
+  columns?: string[];
+  /** `"json"` (default) writes a list as one JSON cell; `"explode"` writes one row per element. */
+  lists?: "json" | "explode";
+  /** Explode only these list paths (implies exploding); other lists stay JSON. */
+  explode?: string[];
+}
+/** CSV with flattened column paths (`address.city`). */
+export declare function toCSV(source: Iterable<unknown>, options?: CsvOptions): Generator<string>;
+export declare function toCSV(source: AsyncIterable<unknown>, options?: CsvOptions): AsyncGenerator<string>;
+
+export interface SqlOptions extends StreamOptions {
+  /** Default `"postgres"`. */
+  dialect?: "postgres" | "sqlite";
+  /** Write CREATE TABLE statements (default true). */
+  ddl?: boolean;
+  /** Write DROP TABLE IF EXISTS before the CREATE statements (default false). */
+  dropExisting?: boolean;
+  /** Wrap the script in BEGIN/COMMIT (default true). */
+  transaction?: boolean;
+  /** `"snake"` (default) turns `BlogPost`/`createdAt` into `blog_post`/`created_at`; `"preserve"` keeps the names. */
+  names?: "snake" | "preserve";
+  tablePrefix?: string;
+  /** Table name per entity type, overriding `names`. */
+  tableNames?: Record<string, string>;
+  /** Write the preamble (BEGIN and DDL); default true. */
+  header?: boolean;
+  /** Write the closing COMMIT; default true. */
+  footer?: boolean;
+}
+
+export interface SqlTable {
+  type: string;
+  table: string;
+  primaryKey: string;
+  columns: Array<{ name: string; type: string; references?: string }>;
+}
+
+export interface SqlWriter {
+  dialect: "postgres" | "sqlite";
+  /** BEGIN, optional DROPs, CREATE TABLEs and foreign keys. */
+  header(): string;
+  /** INSERTs for items `[from, to)` (absolute indexes); call in order, earlier items are replayed silently. */
+  rows(from?: number, to?: number): Generator<string>;
+  /** COMMIT (empty when `transaction` is false). */
+  footer(): string;
+  /** The planned tables, in creation order. */
+  tables(): SqlTable[];
+}
+
+/** A resumable SQL writer for a query or a {@link Stream}. */
+export declare function sqlWriter(source: string | DocumentNode | Stream, options?: SqlOptions): SqlWriter;
+/** SQL (DDL, INSERTs, COMMIT) for the root collection of a query and everything under it, as statements. */
+export declare function toSQL(source: string | DocumentNode | Stream, options?: SqlOptions): Generator<string>;
+
+// ---- explain (docs/design.md section 20) ---------------------------------------------------------
+
+/** A key as the library builds it for a value: the exact string (fields are separated by U+001F), its parts and its XXH64 hash. */
+export interface ExplainedKey {
+  string: string;
+  parts: string[];
+  hash: string;
+}
+
+export interface ExplainedStep {
+  path: string;
+  field: string;
+  /** `list`, `edges`, `nodes`, `connection` (a collection) or `entity` (a singular field). */
+  via: string;
+  mode?: "args" | "root" | "pool" | "owned" | "inherited" | "connection-member";
+  index?: number;
+  /** The entity key (a list member, or the entity a singular field refers to). */
+  key?: string;
+  /** Drawn from the shared pool of the type (true) or owned by its parent (false). */
+  shared?: boolean;
+  size?: number;
+  window?: { start: number; total: number | null; endless: boolean };
+  countKey?: string;
+  declaredCount?: unknown;
+  note?: string;
+}
+
+export interface ExplainedCandidate {
+  source: "directive" | "spec" | "heuristic" | "schema";
+  /** For a spec candidate: the spec key and how it matched (`exact`, `*`, `**` or `@Type`). */
+  entry?: string;
+  matches?: string;
+  rule?: string;
+  value?: unknown;
+  description?: string;
+  /** True for the candidate that decided the property. */
+  wins: boolean;
+}
+
+/** What `explain` reports for a value (docs/api.md, explain). Every field is plain JSON. */
+export interface Explanation {
+  path: string;
+  /** The value in the output (absent when the path is `unavailable` or the field failed). */
+  value?: unknown;
+  kind: "scalar" | "scalar-list" | "list-element" | "object" | "list" | "connection" | "item" | "connection-member" | "unavailable";
+  /** For `unavailable`: the first null or failed value on the way, and why. */
+  blockedAt?: string;
+  because?: string;
+  by?: Record<string, unknown>;
+  error?: { message: string; extensions?: Record<string, unknown> };
+  field?: { name: string; alias?: string; parentType: string; path: string; type: string; list: boolean; nullable: boolean };
+  entity?: { identity: string; type: string; key: string; shared?: boolean; how: ExplainedStep[]; note?: string };
+  collection?: { size: number; window?: { start: number; total: number | null; endless: boolean }; declaredCount?: unknown; countKey?: string; members?: string };
+  key?: ExplainedKey;
+  generator?: { name: string; args: Record<string, unknown>; outputType: string };
+  rule?: { id: string; source: string; description?: string; pack?: string };
+  listRule?: { id: string; source: string; description?: string; isList: boolean };
+  decisions?: Array<{ kind: string; value: unknown; source: string; rule?: string }>;
+  precedence?: Array<{ property: string; winner: string | undefined; candidates: ExplainedCandidate[] }>;
+  persona?: { type: string; key: string; inherited?: boolean; slots?: Array<{ name: string; key: string }>; pinned?: Record<string, string> };
+  derivation?: { kind: "derive" | "count.of" | "order"; [k: string]: unknown };
+  nullRate?: { rate: number; draw: number; key: string; hit: boolean };
+  scenario?: { names: Scenario[]; source: "option" | "spec"; effect: string };
+  pin?: { entity: string; field?: string; kind: "pin" | "created" | "updated" | "deleted"; value: unknown };
+  /** The seed in effect and where it came from (`option`, `default`, `directive`, `spec`, `operation directive`, or an enclosing field). */
+  seed?: { value: string; source: string; at?: string };
+  /** For Relay machinery (`totalCount`, `cursor`, paging info), which has no generator of its own. */
+  special?: { name: string; description: string };
+  summary: string;
+}
+
+/**
+ * Explain why the value at `path` looks the way it does: its key string, generator and arguments, the rule,
+ * spec entry or directive that decided it (with the precedence), the persona slots or derivation inputs,
+ * the entity it belongs to, the scenario effect and any pin. The query is run once with a read-only trace:
+ * explaining never changes an output.
+ *
+ * `path` uses response keys (aliases) and zero-based list indexes: `users.3.email` or `["users", 3, "email"]`.
+ * Pass `{ world }` to explain a value of a world (pins and mutations are taken into account).
+ * @throws {GraceholderError} `bad-path` when the path names nothing in the result
+ */
+export declare function explain(query: string | DocumentNode, path: string | Array<string | number>, options?: Omit<Options, "errors"> & { world?: World }): Explanation;

package/src/index.js

@@ -0,0 +1,62 @@
+// @johnhenry/graceholder: consistently repeatable generated data from a GraphQL query.
+// Design: docs/design.md. Every value is a pure function of a key (section 2).
+import { infer } from "./infer.js";
+import { GraceholderError } from "./errors.js";
+import { generateResult } from "./generate.js";
+import { KEY_SCHEME } from "./key.js";
+import { registerPack, registeredPacks } from "./pack-registry.js";
+import { realismOptions } from "./generate.js";
+import { ScenarioError, SCENARIOS, globalScenarios } from "./scenario.js";
+
+export { GraceholderError, KEY_SCHEME, registerPack, registeredPacks, SCENARIOS };
+export { createWorld } from "./world.js";
+export { explain } from "./explain.js";
+export { stream } from "./bulk/stream.js";
+export { toNDJSON } from "./bulk/ndjson.js";
+export { toCSV } from "./bulk/csv.js";
+export { toSQL, sqlWriter } from "./bulk/sql.js";
+export { suggestSpec, buildSuggestPrompt, SUGGEST_PROMPT_VERSION } from "./suggest.js";
+export { specFromSamples, analyzeSamples } from "./learn.js";
+
+/**
+ * Generate data for a query. Synchronous and deterministic.
+ * @param {string|import("graphql").DocumentNode} query
+ * @param {import("./index.js").Options} [options]
+ */
+export function graceholder(query, options = {}) {
+  const mode = options.errors ?? "throw";
+  try {
+    const result = generateResult(query, options);
+    if (result.errors?.length && result.errors.every((e) => e.originalError instanceof ScenarioError)) {
+      // the errors scenario: a partial result. Scenario errors are plain JSON, in the usual GraphQL response shape.
+      const errors = result.errors.map((e) => e.toJSON());
+      if (mode === "result") return { data: result.data ?? null, errors };
+      throw new GraceholderError("graphql", errors[0].message, { cause: result.errors[0], errors, data: result.data ?? null });
+    }
+    if (result.errors?.length) {
+      // an error raised by one of our resolvers (bad cursor, bad arguments) keeps its own code
+      const own = result.errors.find((e) => e.originalError instanceof GraceholderError);
+      if (own) throw own.originalError;
+      throw new GraceholderError("graphql", result.errors[0].message, { cause: result.errors[0], errors: result.errors });
+    }
+    const data = result.data;
+    return mode === "result" ? { data } : data;
+  } catch (e) {
+    if (mode === "result" && e instanceof GraceholderError && e.code === "graphql") {
+      return { errors: e.errors ?? [e.cause ?? e] };
+    }
+    throw e;
+  }
+}
+
+/**
+ * Infer the SDL and the decisions behind it, without generating data.
+ * @param {string|import("graphql").DocumentNode} query
+ * @param {Record<string, any>} [spec] side-car spec (section 5.2)
+ * @param {{ operationName?: string, variables?: Record<string, unknown>, strict?: boolean, distributions?: "uniform"|"realistic", packs?: any[], images?: "url"|"svg", schema?: any, scenario?: string|string[] }} [options]
+ */
+export function inferSchema(query, spec, options = {}) {
+  const realism = realismOptions(options);
+  const { sdl, decisions, document } = infer(query, { scenario: globalScenarios(options.scenario), operationName: options.operationName, variables: options.variables, strict: options.strict, spec, schema: options.schema, packs: realism.packs, realistic: realism.realistic });
+  return { sdl, decisions, document };
+}