@distilled.cloud/core 0.30.3 → 1.0.0-rc.10

package/src/codegen/graph.ts

@@ -0,0 +1,151 @@
+/**
+ * Shared shape-graph utilities for the SDK generators (dev-time only).
+ *
+ * Works over plain Smithy-JSON shape maps (`{ "ns#Name": { type, members,
+ * … } }`). Providers supply the shape map and (optionally) a custom
+ * dependency extractor; reachability, topological ordering, and cycle
+ * analysis are generic.
+ */
+import { isPrelude } from "./naming.ts";
+
+export type ShapeMap = Record<string, any>;
+
+/**
+ * Direct dependencies of a shape: structure/union member targets, list
+ * member, map key/value. Operations/services are not traversed here —
+ * providers seed reachability from operation I/O explicitly.
+ */
+export const shapeDeps = (def: any): string[] => {
+  if (!def) return [];
+  if (def.type === "structure" || def.type === "union") {
+    return Object.values(def.members ?? {}).map((m: any) => m.target);
+  }
+  if (def.type === "list") return [def.member.target];
+  if (def.type === "map") {
+    return def.key ? [def.key.target, def.value.target] : [def.value.target];
+  }
+  return [];
+};
+
+/**
+ * Every shape reachable from `roots` through `deps`, excluding prelude
+ * shapes and ids missing from the map.
+ */
+export const reachableFrom = (
+  shapes: ShapeMap,
+  roots: Iterable<string>,
+  deps: (def: any) => string[] = shapeDeps,
+): Set<string> => {
+  const reachable = new Set<string>();
+  const visit = (id: string) => {
+    if (isPrelude(id) || reachable.has(id) || !shapes[id]) return;
+    reachable.add(id);
+    for (const dep of deps(shapes[id])) visit(dep);
+  };
+  for (const r of roots) visit(r);
+  return reachable;
+};
+
+/**
+ * Dependencies-first topological order over `ids`. Cycles are tolerated:
+ * a back-edge is simply skipped, so mutually-recursive shapes come out in
+ * discovery order and emitters break the cycle with `S.suspend` at
+ * forward references (see {@link forwardRef}).
+ */
+export const topoOrder = (
+  shapes: ShapeMap,
+  ids: Iterable<string>,
+  deps: (def: any) => string[] = shapeDeps,
+): string[] => {
+  const order: string[] = [];
+  const done = new Set<string>();
+  const stack = new Set<string>();
+  const walk = (id: string) => {
+    if (done.has(id) || stack.has(id) || isPrelude(id) || !shapes[id]) return;
+    stack.add(id);
+    for (const dep of deps(shapes[id])) walk(dep);
+    stack.delete(id);
+    done.add(id);
+    order.push(id);
+  };
+  for (const id of ids) walk(id);
+  return order;
+};
+
+/** Position index for {@link forwardRef} decisions. */
+export const orderIndex = (order: readonly string[]): Map<string, number> => {
+  const indexOf = new Map<string, number>();
+  order.forEach((id, i) => indexOf.set(id, i));
+  return indexOf;
+};
+
+/**
+ * Whether a reference from the shape at `selfIdx` to `target` points
+ * forward in emission order (including into a cycle) and therefore needs
+ * `S.suspend(() => …)` to defer evaluation.
+ */
+export const isForwardRef = (
+  indexOf: ReadonlyMap<string, number>,
+  target: string,
+  selfIdx: number,
+): boolean => {
+  const ti = indexOf.get(target);
+  return ti !== undefined && ti > selfIdx;
+};
+
+/**
+ * All shape ids that participate in a dependency cycle (Tarjan SCC —
+ * components of size > 1, plus direct self-loops). Used by generators
+ * that must know cyclicity independent of emission position (e.g. to add
+ * an explicit `S.Schema<T>` return type on suspended thunks and break
+ * circular type inference).
+ */
+export const cyclicShapeIds = (
+  shapes: ShapeMap,
+  ids: Iterable<string>,
+  deps: (def: any) => string[] = shapeDeps,
+): Set<string> => {
+  const idSet = new Set(ids);
+  const index = new Map<string, number>();
+  const low = new Map<string, number>();
+  const onStack = new Set<string>();
+  const stack: string[] = [];
+  const cyclic = new Set<string>();
+  let counter = 0;
+
+  const strongConnect = (v: string) => {
+    index.set(v, counter);
+    low.set(v, counter);
+    counter++;
+    stack.push(v);
+    onStack.add(v);
+
+    for (const w of deps(shapes[v])) {
+      if (!idSet.has(w) || !shapes[w]) continue;
+      if (!index.has(w)) {
+        strongConnect(w);
+        low.set(v, Math.min(low.get(v)!, low.get(w)!));
+      } else if (onStack.has(w)) {
+        low.set(v, Math.min(low.get(v)!, index.get(w)!));
+      }
+    }
+
+    if (low.get(v) === index.get(v)) {
+      const component: string[] = [];
+      let w: string;
+      do {
+        w = stack.pop()!;
+        onStack.delete(w);
+        component.push(w);
+      } while (w !== v);
+      if (component.length > 1 || deps(shapes[v]).some((d) => d === v)) {
+        for (const c of component) cyclic.add(c);
+      }
+    }
+  };
+
+  for (const id of idSet) {
+    if (!index.has(id) && shapes[id]) strongConnect(id);
+  }
+  return cyclic;
+};

package/src/codegen/graphql-client.test.ts

@@ -0,0 +1,386 @@
+import { describe, expect, test } from "bun:test";
+import { buildSchema, introspectionFromSchema, parse, validate } from "graphql";
+import { compile } from "../graphql.ts";
+import { fixtureSDL } from "../graphql.fixture.ts";
+import { applyOperation } from "../json-patch.ts";
+import {
+  convertGraphQLClient,
+  generateGraphQLClient,
+  graphqlTypeString,
+  validateGraphQLModel,
+} from "./graphql-client.ts";
+
+const named = (name: string, kind = "OBJECT") => ({ kind, name });
+const required = (ofType: object) => ({ kind: "NON_NULL", ofType });
+const list = (ofType: object) => ({ kind: "LIST", ofType });
+const field = (name: string, type: object, args: object[] = []) => ({
+  name,
+  type,
+  args,
+});
+const fixture = {
+  queryType: { name: "Query" },
+  mutationType: { name: "Mutation" },
+  types: [
+    { kind: "SCALAR", name: "String" },
+    { kind: "SCALAR", name: "Int" },
+    { kind: "SCALAR", name: "JSON" },
+    {
+      kind: "ENUM",
+      name: "Status",
+      enumValues: [{ name: "ACTIVE" }, { name: "OLD", isDeprecated: true }],
+    },
+    {
+      kind: "INPUT_OBJECT",
+      name: "Filter",
+      inputFields: [
+        {
+          name: "status",
+          type: named("Status", "ENUM"),
+          defaultValue: "ACTIVE",
+        },
+      ],
+    },
+    {
+      kind: "OBJECT",
+      name: "Query",
+      fields: [
+        field("project", required(named("Project")), [
+          { name: "id", type: required(named("String", "SCALAR")) },
+        ]),
+        field("search", list(named("Search", "UNION"))),
+      ],
+    },
+    {
+      kind: "OBJECT",
+      name: "Mutation",
+      fields: [
+        field("projectCreate", named("Project"), [
+          { name: "filter", type: named("Filter", "INPUT_OBJECT") },
+        ]),
+      ],
+    },
+    {
+      kind: "OBJECT",
+      name: "Project",
+      interfaces: [named("Node", "INTERFACE")],
+      fields: [
+        field("id", required(named("String", "SCALAR"))),
+        field("children", required(list(required(named("Project")))), [
+          {
+            name: "first",
+            type: required(named("Int", "SCALAR")),
+            defaultValue: "20",
+          },
+          { name: "filter", type: named("Filter", "INPUT_OBJECT") },
+        ]),
+        {
+          ...field("legacy", named("String", "SCALAR")),
+          isDeprecated: true,
+          deprecationReason: "Use id",
+        },
+      ],
+    },
+    {
+      kind: "OBJECT",
+      name: "Service",
+      fields: [field("id", required(named("String", "SCALAR")))],
+    },
+    {
+      kind: "INTERFACE",
+      name: "Node",
+      fields: [field("id", required(named("String", "SCALAR")))],
+      possibleTypes: [named("Project")],
+    },
+    {
+      kind: "UNION",
+      name: "Search",
+      possibleTypes: [named("Project"), named("Service")],
+    },
+  ],
+};
+
+const options = {
+  transportImport: "./transport.ts",
+  requirementsImport: "./transport.ts",
+  requirementsType: "Requirements",
+  operationAliases: { createProject: "projectCreate" },
+};
+
+describe("GraphQL-native compiler", () => {
+  test("root helpers allocate safe unique names without hiding schema operations", () => {
+    const source = buildSchema(`
+      type Query {
+        query: String report: String schema: String transport: String G: String
+        catchTags: String delete: String Scalars: String Selection: String
+        same: String mutationSame: String
+      }
+      type Mutation { same: String }
+    `);
+    const model = convertGraphQLClient(introspectionFromSchema(source));
+    const output = generateGraphQLClient(model, {
+      ...options,
+      operationAliases: {
+        default: "delete",
+        deleteField: "delete",
+        transport: "report",
+        readReport: "report",
+      },
+    });
+    expect(output).toContain(
+      'export const queryQuery = client.operation("query", "query");',
+    );
+    expect(output).toContain(
+      'export const queryReport = client.operation("query", "report");',
+    );
+    expect(output).toContain(
+      'export const queryTransport = client.operation("query", "transport");',
+    );
+    expect(output).toContain(
+      'export const queryDelete = client.operation("query", "delete");',
+    );
+    expect(output).toContain(
+      'export const queryScalars = client.operation("query", "Scalars");',
+    );
+    expect(output).toContain(
+      'export const mutationSame2 = client.operation("mutation", "same");',
+    );
+    expect(output).toContain("export const deleteField = queryDelete;");
+    expect(output).toContain("export const readReport = queryReport;");
+    expect(output).not.toContain("export const default =");
+    expect(
+      [...output.matchAll(/export const ([A-Za-z_$][\w$]*) =/g)].map(
+        (match) => match[1],
+      ),
+    ).toEqual(expect.arrayContaining(["query", "report", "queryCatchTags"]));
+    const declarations = [
+      ...output.matchAll(/export (?:const|class|type) ([A-Za-z_$][\w$]*)/g),
+    ].map((match) => match[1]);
+    expect(new Set(declarations).size).toBe(declarations.length);
+    expect(output.match(/client\.operation\(/g)).toHaveLength(12);
+    expect(() =>
+      new Bun.Transpiler({ loader: "ts" }).transformSync(output),
+    ).not.toThrow();
+    expect(
+      generateGraphQLClient(model, {
+        ...options,
+        operationAliases: {
+          default: "delete",
+          deleteField: "delete",
+          transport: "report",
+          readReport: "report",
+        },
+      }),
+    ).toBe(output);
+  });
+
+  test("schema type names and patched error tags cannot shadow generated support symbols", () => {
+    const model = convertGraphQLClient(
+      introspectionFromSchema(
+        buildSchema(`
+      type Query { data: Schema }
+      type Schema { selection: Selection }
+      type Selection { id: ID! }
+    `),
+      ),
+    );
+    for (const tag of ["Schema", "catchTags", "class"]) {
+      applyOperation(model, {
+        op: "add",
+        path: `/errors/${tag}`,
+        value: { matchers: [{ code: tag }] },
+      });
+      applyOperation(model, {
+        op: "add",
+        path: "/types/Query/fields/data/errors/-",
+        value: tag,
+      });
+    }
+    const output = generateGraphQLClient(model, options);
+    expect(output).toContain(
+      'export class SchemaError extends S.TaggedError<SchemaError>()("Schema", G.errorFields)',
+    );
+    expect(output).toContain(
+      'export class catchTagsError extends S.TaggedError<catchTagsError>()("catchTags", G.errorFields)',
+    );
+    expect(output).toContain(
+      'export class classError extends S.TaggedError<classError>()("class", G.errorFields)',
+    );
+    expect(output).toContain('"Schema": SchemaError;');
+    expect(output).toContain('"Schema": {');
+    expect(output).toContain('"Selection": {');
+    expect(() =>
+      new Bun.Transpiler({ loader: "ts" }).transformSync(output),
+    ).not.toThrow();
+  });
+
+  test("real introspection round-trips abstract fragments, recursive selections and defaulted required arguments", () => {
+    const schema = buildSchema(
+      fixtureSDL.replaceAll("first: Int = 20", "first: Int! = 20"),
+    );
+    const model = convertGraphQLClient(introspectionFromSchema(schema));
+    const compiled = compile(model, "query", {
+      node: {
+        where: { id: "node-id" },
+        select: {
+          id: true,
+          __typename: true,
+          __on: {
+            Project: {
+              services: { select: { edges: { node: { id: true } } } },
+            },
+            Service: { status: true, project: { parent: { name: true } } },
+          },
+        },
+      },
+      search: {
+        where: { text: "query" },
+        select: {
+          __typename: true,
+          __on: { Project: { name: true }, Service: { status: true } },
+        },
+      },
+    });
+    expect(validate(schema, parse(compiled.query))).toEqual([]);
+    expect(compiled.query).not.toContain("first:");
+    expect(model.types.Project!.fields!.services!.args.first).toEqual({
+      type: "Int!",
+      defaultValue: "20",
+    });
+    expect(model.types.ProjectFilter!.inputFields!.statuses).toEqual({
+      type: "[Status!]",
+      defaultValue: "[ACTIVE]",
+    });
+    const output = generateGraphQLClient(model, options);
+    expect(output).toContain('"first"?: Scalars["Int"]');
+    expect(output).toContain('"Node": "Project" | "Service"');
+    expect(output).toContain('"SearchResult": "Project" | "Service"');
+  });
+
+  test("required input fields with defaults are omittable but other required fields stay required", () => {
+    const schema = buildSchema(`
+      input Paging { limit: Int! = 20, owner: ID!, statuses: [String!]! = [] }
+      type Query { names(paging: Paging!): [String!]! }
+    `);
+    const model = convertGraphQLClient(introspectionFromSchema(schema));
+    const output = generateGraphQLClient(model, options);
+    expect(output).toContain('"limit"?: Scalars["Int"]');
+    expect(output).toContain('"owner": Scalars["ID"]');
+    expect(output).toContain('"statuses"?: ReadonlyArray<Scalars["String"]>');
+    const compiled = compile(model, "query", {
+      names: { where: { paging: { owner: "account" } } },
+    });
+    expect(Object.values(compiled.variables)).toEqual([{ owner: "account" }]);
+    expect(validate(schema, parse(compiled.query))).toEqual([]);
+    expect(() =>
+      compile(model, "query", { names: { where: { paging: {} } } }),
+    ).toThrow("owner is required");
+  });
+
+  test("provider scalar overrides stay aligned in runtime metadata and generated scalar types", () => {
+    const schema = buildSchema(
+      `scalar DateTime scalar JSON type Query { date: DateTime! blob: JSON! }`,
+    );
+    const model = convertGraphQLClient(introspectionFromSchema(schema), {
+      scalars: { DateTime: "string" },
+    });
+    const output = generateGraphQLClient(model, options);
+    expect(model.types.DateTime!.scalar).toBe("string");
+    expect(model.types.JSON!.scalar).toBe("unknown");
+    expect(output).toContain('"DateTime": string;');
+    expect(output).toContain('"JSON": unknown;');
+    expect(
+      validate(
+        schema,
+        parse(compile(model, "query", { date: true, blob: true }).query),
+      ),
+    ).toEqual([]);
+  });
+
+  test("preserves nested required arguments, defaults, recursion, union/interface members and deprecated fields", () => {
+    const model = convertGraphQLClient({ data: { __schema: fixture } });
+    expect(model.types.Project!.fields!.children).toEqual({
+      type: "[Project!]!",
+      args: {
+        first: { type: "Int!", defaultValue: "20" },
+        filter: { type: "Filter" },
+      },
+      errors: [],
+    });
+    expect(model.types.Project!.interfaces).toEqual(["Node"]);
+    expect(model.types.Node!.possibleTypes).toEqual(["Project"]);
+    expect(model.types.Search!.possibleTypes).toEqual(["Project", "Service"]);
+    expect(model.types.Project!.fields!.legacy!.deprecated).toBe("Use id");
+    expect(model.types.Status!.enumValues).toEqual(["ACTIVE", "OLD"]);
+    expect(model.types.Filter!.inputFields!.status!.defaultValue).toBe(
+      "ACTIVE",
+    );
+    expect(model.types.JSON!.scalar).toBe("unknown");
+    validateGraphQLModel(model);
+  });
+
+  test("field errors patch the one model used by emitted type unions and runtime classification", () => {
+    const model = convertGraphQLClient(fixture);
+    applyOperation(model, {
+      op: "add",
+      path: "/errors/ChildrenUnavailable",
+      value: {
+        category: "server",
+        matchers: [{ code: "CHILDREN_UNAVAILABLE" }],
+      },
+    });
+    applyOperation(model, {
+      op: "add",
+      path: "/types/Project/fields/children/errors/-",
+      value: "ChildrenUnavailable",
+    });
+    const output = generateGraphQLClient(model, options);
+    expect(output).toContain(
+      '"children": G.Field<{ "first"?: Scalars["Int"]; "filter"?: Inputs["Filter"] | null }, "[Project!]!", "ChildrenUnavailable">;',
+    );
+    expect(output).toContain(
+      'export class ChildrenUnavailable extends S.TaggedError<ChildrenUnavailable>()("ChildrenUnavailable", G.errorFields).pipe(Category.withServerError)',
+    );
+    expect(output).toContain('"errors":["ChildrenUnavailable"]');
+    expect(output).toContain('"matchers":[{"code":"CHILDREN_UNAVAILABLE"}]');
+    expect(output).toContain(
+      'export const projectCreate = client.operation("mutation", "projectCreate");',
+    );
+    expect(output).toContain("export const createProject = projectCreate;");
+  });
+
+  test("generation has no fixed depth projection or artificial output optionality", () => {
+    const output = generateGraphQLClient(
+      convertGraphQLClient(fixture),
+      options,
+    );
+    expect(output).toContain('"Project": {');
+    expect(output).toContain('"Search": "Project" | "Service";');
+    expect(output).toContain('"Node": "Project";');
+    expect(output).toContain('"id": G.Field<{  }, "String!", never>;');
+    expect(output).not.toContain('"id"?: G.Field');
+    expect(output).not.toContain("maxDepth");
+  });
+
+  test("unknown coordinates, incomplete references and stale patches fail immediately", () => {
+    const model = convertGraphQLClient(fixture);
+    applyOperation(model, {
+      op: "add",
+      path: "/types/Project/fields/children/errors/-",
+      value: "MissingError",
+    });
+    expect(() => validateGraphQLModel(model)).toThrow(
+      "Project.children: unknown GraphQL error MissingError",
+    );
+    expect(() => graphqlTypeString({ kind: "NON_NULL" })).toThrow(
+      "Incomplete GraphQL NON_NULL",
+    );
+    expect(() =>
+      applyOperation(model, {
+        op: "replace",
+        path: "/types/Project/fields/removed/errors",
+        value: [],
+      }),
+    ).toThrow();
+  });
+});