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

package/src/graphql.types.ts

@@ -0,0 +1,185 @@
+/** Compile-only contract checks. The coordinator runs these with noCheck=false. */
+import type * as G from "./graphql.ts";
+import type * as Stream from "effect/Stream";
+import type {
+  FixtureSchema,
+  ProjectNotFound,
+  ServicesUnavailable,
+  Unauthorized,
+  PageInfoUnavailable,
+} from "./graphql.fixture.ts";
+
+type Assert<T extends true> = T;
+type Assignable<A, B> = [A] extends [B] ? true : false;
+type Equal<A, B> = Assignable<A, B> extends true ? Assignable<B, A> : false;
+
+type IdentitySelection = {
+  project: { where: { id: "p1" }; select: { id: true } };
+};
+type DetailedSelection = {
+  project: {
+    where: { id: "p1" };
+    select: {
+      id: true;
+      services: { select: { edges: { node: { id: true } } } };
+    };
+  };
+};
+type AliasSelection = {
+  __alias: {
+    production: { project: { where: { id: "p1" }; select: { id: true } } };
+  };
+};
+type SearchSelection = {
+  search: {
+    where: { text: "prod" };
+    select: {
+      __typename: true;
+      __on: { Project: { name: true }; Service: { status: true } };
+    };
+  };
+};
+
+type Identity = G.Result<FixtureSchema, "Query!", IdentitySelection>;
+type _Identity = Assert<Equal<Identity, { project: { id: string } | null }>>;
+type _UnselectedFieldsAbsent = Assert<
+  Equal<keyof NonNullable<Identity["project"]>, "id">
+>;
+
+type Alias = G.Result<FixtureSchema, "Query!", AliasSelection>;
+type _Alias = Assert<Equal<Alias, { production: { id: string } | null }>>;
+
+type Search = G.Result<FixtureSchema, "Query!", SearchSelection>;
+type _Union = Assert<
+  Equal<
+    Search["search"][number],
+    | { __typename: "Project"; name: string }
+    | { __typename: "Service"; status: "ACTIVE" | "ARCHIVED" }
+  >
+>;
+
+type IdentityErrors = G.Errors<FixtureSchema, "Query", IdentitySelection>;
+type DetailedErrors = G.Errors<FixtureSchema, "Query", DetailedSelection>;
+type _RootErrorIncluded = Assert<Assignable<ProjectNotFound, IdentityErrors>>;
+type _GlobalErrorIncluded = Assert<Assignable<Unauthorized, IdentityErrors>>;
+type _NestedErrorIncluded = Assert<
+  Assignable<ServicesUnavailable, DetailedErrors>
+>;
+type _UnselectedErrorExcluded = Assert<
+  Equal<Extract<IdentityErrors, { _tag: "ServicesUnavailable" }>, never>
+>;
+
+type ConditionalRoot = G.Result<
+  FixtureSchema,
+  "Query!",
+  {
+    ping: { $include: boolean; select: true };
+  }
+>;
+type _ConditionalRoot = Assert<Equal<ConditionalRoot, { ping?: boolean }>>;
+type ConditionalNested = G.Result<
+  FixtureSchema,
+  "Query!",
+  {
+    project: {
+      where: { id: string };
+      select: {
+        id: true;
+        name: { $skip: boolean; select: true };
+      };
+    };
+  }
+>;
+type _ConditionalNested = Assert<
+  Equal<
+    ConditionalNested,
+    {
+      project: { id: string; name?: string } | null;
+    }
+  >
+>;
+type ConditionalAlias = G.Result<
+  FixtureSchema,
+  "Query!",
+  {
+    __alias: { healthy: { ping: { $include: boolean; select: true } } };
+  }
+>;
+type _ConditionalAlias = Assert<Equal<ConditionalAlias, { healthy?: boolean }>>;
+
+type MergedInterface = G.Result<
+  FixtureSchema,
+  "Node!",
+  {
+    __typename: true;
+    parent: { id: true };
+    __on: { Project: { parent: { name: true } } };
+  }
+>;
+type _MergedInterface = Assert<
+  Equal<
+    Extract<MergedInterface, { __typename: "Project" }>["parent"],
+    { id: string; name: string } | null
+  >
+>;
+
+// These assignments exercise user-facing argument and nested selection validation.
+const validSelection: G.Selection<FixtureSchema, "Query"> = {
+  project: {
+    where: { id: "p1" },
+    select: {
+      services: {
+        where: { first: 10 },
+        select: { edges: { node: { id: true } } },
+      },
+    },
+  },
+};
+const missingArgument: G.Selection<FixtureSchema, "Query"> = {
+  // @ts-expect-error Required GraphQL field arguments cannot be omitted.
+  project: { select: { id: true } },
+};
+const wrongArgument: G.Selection<FixtureSchema, "Query"> = {
+  // @ts-expect-error GraphQL argument types follow the schema.
+  project: { where: { id: 42 }, select: { id: true } },
+};
+const unknownField: G.Selection<FixtureSchema, "Query"> = {
+  // @ts-expect-error Unknown nested fields cannot be selected.
+  project: { where: { id: "p1" }, select: { invented: true } },
+};
+// @ts-expect-error Fields returning objects require a projection.
+const noProjection: G.Selection<FixtureSchema, "Query"> = { project: true };
+
+void [
+  validSelection,
+  missingArgument,
+  wrongArgument,
+  unknownField,
+  noProjection,
+];
+
+// Named operations retain projection and pagination constraints during inference.
+declare const inferredClient: ReturnType<
+  typeof G.makeClient<FixtureSchema, never>
+>;
+
+// @ts-expect-error An object-returning operation always requires a projection.
+inferredClient.operation("query", "project")({ id: "p1" });
+// @ts-expect-error Non-connection object queries do not expose pages.
+inferredClient.operation("query", "project").pages;
+// @ts-expect-error Scalar queries do not expose connection pagination.
+inferredClient.operation("query", "ping").items;
+// @ts-expect-error Mutations cannot be paginated.
+inferredClient.operation("mutation", "editProject").pages;
+
+const selectivePages = inferredClient
+  .operation("query", "services")
+  .pages({}, { edges: { node: { id: true } } });
+type PageErrors = Stream.Error<typeof selectivePages>;
+type PageIssues =
+  Extract<PageErrors, G.GraphQLFailure> extends G.GraphQLFailure<infer E>
+    ? E
+    : never;
+type _HiddenPaginationErrorIncluded = Assert<
+  Assignable<PageInfoUnavailable, PageIssues>
+>;

package/src/json-patch.ts

@@ -1,10 +1,11 @@
 /**
  * JSON Patch (RFC 6902) Implementation
  *
- * Provides a unified spec patching system for all SDKs. Patches are applied to
- * generated intermediary specs (Smithy models, OpenAPI docs, …) before code
- * generation to add typed error shapes, rename operations, mark nullable
- * fields, etc. Ported from the distilled repo's `core/json-patch`.
+ * Provides a unified spec patching system for all SDKs. Patches apply in
+ * `convert` so `.generated-specs` is the patched Smithy model. generate does
+ * not patch. Prefer `operationNaming: "verbNoun"` for operationId renames —
+ * JSON pointers at `/paths/~1foo/operationId` go stale when upstream prefixes
+ * paths.
  *
  * Pure functions only — callers load patch files themselves (the generators
  * use Effect's FileSystem) and hand the parsed operations to `applyPatch`.
@@ -45,19 +46,44 @@ export function parseJsonPointer(pointer: string): string[] {
 }
 
 /** Get a value at a JSON Pointer path. */
+/**
+ * The target location of a patch operation is absent from the document —
+ * spec drift (renamed/removed upstream), not a malformed patch.
+ */
+export class StaleTargetError extends Error {
+  override readonly name = "StaleTargetError";
+}
+
 export function getValueAtPath(obj: unknown, pointer: string): unknown {
   const segments = parseJsonPointer(pointer);
   let current: unknown = obj;
 
   for (const segment of segments) {
-    if (current === null || typeof current !== "object") {
-      throw new Error(`Cannot traverse path ${pointer}: not an object`);
+    if (
+      current === null ||
+      current === undefined ||
+      typeof current !== "object"
+    ) {
+      throw new StaleTargetError(
+        `JSON pointer ${pointer} missing (at '${segment}'): not an object`,
+      );
     }
     if (Array.isArray(current)) {
       const index = segment === "-" ? current.length : parseInt(segment, 10);
+      if (index < 0 || index >= current.length) {
+        throw new StaleTargetError(
+          `JSON pointer ${pointer} missing index '${segment}'`,
+        );
+      }
       current = current[index];
     } else {
-      current = (current as Record<string, unknown>)[segment];
+      const record = current as Record<string, unknown>;
+      if (!Object.prototype.hasOwnProperty.call(record, segment)) {
+        throw new StaleTargetError(
+          `JSON pointer ${pointer} missing key '${segment}'`,
+        );
+      }
+      current = record[segment];
     }
   }
 
@@ -80,7 +106,9 @@ export function setValueAtPath(
   for (let i = 0; i < segments.length - 1; i++) {
     const segment = segments[i]!;
     if (current === null || typeof current !== "object") {
-      throw new Error(`Cannot traverse path ${pointer}: not an object`);
+      throw new StaleTargetError(
+        `Cannot traverse path ${pointer}: not an object`,
+      );
     }
     if (Array.isArray(current)) {
       current = current[parseInt(segment, 10)];
@@ -91,7 +119,7 @@ export function setValueAtPath(
 
   const lastSegment = segments[segments.length - 1]!;
   if (current === null || typeof current !== "object") {
-    throw new Error(
+    throw new StaleTargetError(
       `Cannot set value at path ${pointer}: parent is not an object`,
     );
   }
@@ -119,7 +147,9 @@ export function removeValueAtPath(obj: unknown, pointer: string): void {
   for (let i = 0; i < segments.length - 1; i++) {
     const segment = segments[i]!;
     if (current === null || typeof current !== "object") {
-      throw new Error(`Cannot traverse path ${pointer}: not an object`);
+      throw new StaleTargetError(
+        `Cannot traverse path ${pointer}: not an object`,
+      );
     }
     if (Array.isArray(current)) {
       current = current[parseInt(segment, 10)];
@@ -130,15 +160,28 @@ export function removeValueAtPath(obj: unknown, pointer: string): void {
 
   const lastSegment = segments[segments.length - 1]!;
   if (current === null || typeof current !== "object") {
-    throw new Error(
+    throw new StaleTargetError(
       `Cannot remove at path ${pointer}: parent is not an object`,
     );
   }
 
+  // RFC 6902 §4.2: the target location MUST exist.
   if (Array.isArray(current)) {
-    current.splice(parseInt(lastSegment, 10), 1);
+    const index = parseInt(lastSegment, 10);
+    if (Number.isNaN(index) || index < 0 || index >= current.length) {
+      throw new StaleTargetError(
+        `JSON pointer ${pointer} missing index '${lastSegment}'`,
+      );
+    }
+    current.splice(index, 1);
   } else {
-    delete (current as Record<string, unknown>)[lastSegment];
+    const record = current as Record<string, unknown>;
+    if (!Object.prototype.hasOwnProperty.call(record, lastSegment)) {
+      throw new StaleTargetError(
+        `JSON pointer ${pointer} missing key '${lastSegment}'`,
+      );
+    }
+    delete record[lastSegment];
   }
 }
 
@@ -158,16 +201,21 @@ export function applyOperation(
     case "remove":
       removeValueAtPath(obj, operation.path);
       break;
-    case "replace":
-      // For replace, the path must exist
-      getValueAtPath(obj, operation.path); // throws if doesn't exist
+    case "replace": {
+      const existing = getValueAtPath(obj, operation.path);
+      if (existing === undefined) {
+        throw new StaleTargetError(
+          `JSON pointer ${operation.path} does not exist`,
+        );
+      }
       setValueAtPath(obj, operation.path, operation.value);
       break;
+    }
     case "move": {
       if (!operation.from) throw new Error("move operation requires 'from'");
       const moveValue = getValueAtPath(obj, operation.from);
       if (moveValue === undefined) {
-        throw new Error(
+        throw new StaleTargetError(
           `Cannot move from path ${operation.from}: not an object`,
         );
       }
@@ -207,16 +255,25 @@ export function applyPatch(obj: unknown, patch: JsonPatch): void {
 }
 
 /**
- * Whether a per-operation failure is caused by the target location being
- * absent from the spec (i.e. spec drift — the operation/shape the patch
- * targets was renamed or removed upstream) as opposed to a malformed patch.
- * Stale targets should be skipped with a warning rather than aborting the
- * whole generate; a patch that only adds an error to an operation that no
- * longer exists is harmless to drop.
+ * Whether a per-operation failure is a {@link StaleTargetError} (the
+ * operation/shape the patch targets was renamed or removed upstream) as
+ * opposed to a malformed patch. Accepts the thrown value or its message.
+ * Convert fails the run on these by default (`onStalePatch: "fail"`);
+ * `"warn"` restores skip-and-continue.
  */
-export function isStaleTargetError(message: string): boolean {
+export function isStaleTargetError(error: unknown): boolean {
+  if (error instanceof StaleTargetError) return true;
+  const message =
+    typeof error === "string"
+      ? error
+      : error instanceof Error
+        ? error.message
+        : "";
   return (
     message.includes("not an object") ||
-    message.includes("parent is not an object")
+    message.includes("parent is not an object") ||
+    message.includes("missing key") ||
+    message.includes("missing index") ||
+    message.includes("does not exist")
   );
 }

package/src/pagination.ts

@@ -5,6 +5,8 @@
  * - Page-based: page/per_page with a page number that advances
  * - Cursor-based: cursor/limit with an opaque next-cursor string
  * - Token-based (AWS style): NextToken/MaxResults continuation tokens
+ * - Relay (GraphQL connections): after/first with a `pageInfo` block whose
+ *   `hasNextPage` — not the cursor — marks the end
  * - Single: one-shot list endpoints that still expose the paginated surface
  *
  * Each SDK stores a {@link PaginatedTrait} on its operations (sourced from the
@@ -31,6 +33,33 @@ export const getPath = (obj: unknown, path: string): unknown => {
   return current;
 };
 
+/**
+ * Collect the items a dot-separated path selects, flattening arrays as it
+ * goes. Unlike {@link getPath} (which walks a single value and is used for
+ * cursors/tokens), every segment here fans out over whatever the previous one
+ * produced, so a path may cross a list:
+ *
+ * - `"items"` on `{ items: [a, b] }` → `[a, b]` (the common flat case)
+ * - `"edges.node"` on a Relay connection → every edge's `node`
+ *
+ * `null`/`undefined` links are dropped rather than propagated, so a partially
+ * null page yields the items it does have instead of nothing.
+ */
+export const getItems = (obj: unknown, path: string): readonly unknown[] => {
+  let current: unknown[] = [obj];
+  for (const part of path.split(".")) {
+    const next: unknown[] = [];
+    for (const value of current) {
+      if (value == null || typeof value !== "object") continue;
+      const child = (value as Record<string, unknown>)[part];
+      if (Array.isArray(child)) next.push(...child);
+      else if (child != null) next.push(child);
+    }
+    current = next;
+  }
+  return current;
+};
+
 // ============================================================================
 // Pagination Trait
 // ============================================================================
@@ -38,15 +67,26 @@ export const getPath = (obj: unknown, path: string): unknown => {
 /** Pagination trait describing how to navigate between pages. */
 export interface PaginatedTrait {
   /** Pagination strategy */
-  readonly mode?: "token" | "page" | "cursor" | "single";
+  readonly mode?: "token" | "page" | "cursor" | "relay" | "single";
   /** The name of the input member containing the page/cursor token */
   readonly inputToken?: string;
   /** The path to the output member containing the next page/cursor token */
   readonly outputToken?: string;
-  /** The path to the output member containing the paginated items */
+  /**
+   * The path to the output member containing the paginated items. Segments
+   * may cross arrays — `"edges.node"` walks every edge and collects its
+   * `node` (see {@link getItems}).
+   */
   readonly items?: string;
   /** The name of the input member that limits page size */
   readonly pageSize?: string;
+  /**
+   * Relay extension: the path to the boolean that says whether another page
+   * exists (`"pageInfo.hasNextPage"`). Relay connections keep returning the
+   * last page's `endCursor` after the end, so the cursor alone can't
+   * terminate traversal — see {@link paginateRelay}.
+   */
+  readonly hasNextPage?: string;
 }
 
 export type PaginationStrategy = <
@@ -261,6 +301,91 @@ export const paginateToken = <
   );
 };
 
+// ============================================================================
+// Relay Pagination (GraphQL connections)
+// ============================================================================
+
+/**
+ * Stream of pages over a Relay connection — pass `pageInfo.endCursor` back as
+ * `after` for as long as `pageInfo.hasNextPage` is true.
+ *
+ * Relay is cursor pagination with one twist that breaks
+ * {@link paginateCursor}: the terminal page still carries an `endCursor` (it
+ * points at the last edge, not at "nothing left"). Only `hasNextPage`
+ * distinguishes "more to fetch" from "that was everything", so this strategy
+ * reads the boolean and treats the cursor as a pure position marker. A
+ * connection that omits `pageInfo` entirely (or returns an empty page) also
+ * terminates, so a malformed response can't spin forever.
+ */
+export const paginateRelay = <
+  Input extends Record<string, unknown>,
+  Output,
+  E,
+  R,
+>(
+  operation: (input: Input) => Effect.Effect<Output, E, R>,
+  input: Input,
+  pagination: PaginatedTrait,
+): Stream.Stream<Output, E, R> => {
+  const inputToken = pagination.inputToken;
+  const outputToken = pagination.outputToken;
+  if (!inputToken || !outputToken) {
+    return missingPaginationConfig(
+      "Relay pagination requires inputToken and outputToken",
+    );
+  }
+  // `pageInfo.endCursor` → `pageInfo.hasNextPage` when the trait doesn't say.
+  const hasNextPath =
+    pagination.hasNextPage ??
+    `${outputToken.split(".").slice(0, -1).concat("hasNextPage").join(".")}`;
+
+  type State = { cursor: string | undefined; done: boolean };
+  const startCursor =
+    typeof input[inputToken] === "string"
+      ? (input[inputToken] as string)
+      : undefined;
+
+  return Stream.unfold({ cursor: startCursor, done: false } as State, (state) =>
+    Effect.gen(function* () {
+      if (state.done) return undefined;
+
+      const requestPayload = {
+        ...input,
+        ...(state.cursor ? { [inputToken]: state.cursor } : {}),
+      } as Input;
+
+      const response = yield* operation(requestPayload);
+
+      const nextCursor = getPath(response, outputToken) as
+        | string
+        | null
+        | undefined;
+      const hasNext = getPath(response, hasNextPath) === true;
+      // An empty page means the connection is exhausted regardless of what
+      // `hasNextPage` claims — re-requesting the same cursor would loop.
+      const emptyPage =
+        pagination.items !== undefined &&
+        getItems(response, pagination.items).length === 0;
+      // A connection that keeps returning the same `endCursor` with
+      // `hasNextPage: true` (Railway `projects` has done this) would
+      // otherwise paginate forever.
+      const stuckCursor =
+        state.cursor !== undefined &&
+        nextCursor !== undefined &&
+        nextCursor !== null &&
+        nextCursor === state.cursor;
+
+      const nextState: State = {
+        cursor: nextCursor ?? undefined,
+        done:
+          !hasNext || isTerminalToken(nextCursor) || emptyPage || stuckCursor,
+      };
+
+      return [response, nextState] as const;
+    }),
+  );
+};
+
 /**
  * Shared default pagination dispatcher for SDKs that use generic
  * token/cursor/page traversal.
@@ -277,6 +402,8 @@ export const paginateWithDefaults: PaginationStrategy = (
       return paginatePageNumber(operation, input, pagination);
     case "cursor":
       return paginateCursor(operation, input, pagination);
+    case "relay":
+      return paginateRelay(operation, input, pagination);
     case "single":
       return paginateSingle(operation, input, pagination);
     case "token":
@@ -293,7 +420,8 @@ export const paginateWithDefaults: PaginationStrategy = (
  * Extracts individual items from a page stream.
  *
  * @param pages - A stream of page responses
- * @param itemsPath - Dot-separated path to the items array in the page
+ * @param itemsPath - Dot-separated path to the items in the page; segments may
+ *   cross arrays (see {@link getItems})
  * @returns A Stream of individual items
  */
 export const extractItems = <Output, Item, E, R>(
@@ -301,8 +429,7 @@ export const extractItems = <Output, Item, E, R>(
   itemsPath: string,
 ): Stream.Stream<Item, E, R> =>
   pages.pipe(
-    Stream.flatMap((page) => {
-      const items = getPath(page, itemsPath) as readonly Item[] | undefined;
-      return Stream.fromIterable(items ?? []);
-    }),
+    Stream.flatMap((page) =>
+      Stream.fromIterable(getItems(page, itemsPath) as readonly Item[]),
+    ),
   );

package/src/protocol-http.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, test } from "bun:test";
+import { buildRequest, mapKeys } from "./protocol-http.ts";
+import * as S from "./schema.ts";
+import * as T from "./trait.ts";
+
+/**
+ * `T.StringEncoded()`: the member's TS type stays natural (boolean) but the
+ * wire carries its string spelling, for APIs that document the field as the
+ * enum `"true" | "false"` rather than a JSON boolean.
+ */
+const JsonInput = S.Struct({
+  flag: S.optional(S.Boolean.pipe(T.Body("flag"), T.StringEncoded())),
+  plain: S.optional(S.Boolean.pipe(T.Body("plain"))),
+  nullable: S.optional(
+    S.NullOr(S.Boolean).pipe(T.Body("nullable"), T.StringEncoded()),
+  ),
+  flags: S.optional(
+    S.Array(S.Boolean).pipe(T.Body("flags"), T.StringEncoded()),
+  ),
+}).pipe(T.Http({ method: "POST", uri: "/things" }));
+
+const jsonBodyOf = (input: unknown): unknown => {
+  const request = buildRequest({
+    input,
+    inputAst: JsonInput.ast,
+    baseUrl: "https://example.test",
+  });
+  const body = request.body as { readonly body?: string };
+  return JSON.parse(body.body ?? "{}");
+};
+
+describe("StringEncoded members", () => {
+  test("booleans serialize as their string spelling", () => {
+    expect(jsonBodyOf({ flag: true, plain: true })).toEqual({
+      flag: "true",
+      plain: true,
+    });
+    expect(jsonBodyOf({ flag: false, plain: false })).toEqual({
+      flag: "false",
+      plain: false,
+    });
+  });
+
+  test("a list stringifies element-wise", () => {
+    expect(jsonBodyOf({ flags: [true, false] })).toEqual({
+      flags: ["true", "false"],
+    });
+  });
+
+  test("null stays null and an omitted member stays omitted", () => {
+    expect(jsonBodyOf({ nullable: null })).toEqual({ nullable: null });
+    expect(jsonBodyOf({})).toEqual({});
+  });
+});
+
+describe("UnionCases decoding", () => {
+  const cases = [
+    ["id", "type", "zoneName"],
+    ["id", "type", "accountName"],
+  ];
+  const merged = {
+    id: "1",
+    type: "account",
+    zoneName: "zone-a",
+    accountName: "acct-a",
+  };
+  const decode = (schema: S.Schema<unknown>, value: unknown) =>
+    mapKeys(schema.ast, value, "decode");
+
+  test("the discriminator picks the case key sets cannot tell apart", () => {
+    const schema = S.Unknown.pipe(
+      T.UnionCases(cases, { key: "type", values: ["zone", "account"] }),
+    );
+    expect(decode(schema, merged)).toEqual({
+      id: "1",
+      type: "account",
+      accountName: "acct-a",
+    });
+    expect(decode(schema, { ...merged, type: "zone" })).toEqual({
+      id: "1",
+      type: "zone",
+      zoneName: "zone-a",
+    });
+  });
+
+  test("an unknown tag falls back to key-set scoring", () => {
+    const schema = S.Unknown.pipe(
+      T.UnionCases(cases, { key: "type", values: ["zone", "account"] }),
+    );
+    expect(
+      decode(schema, { ...merged, type: "other", accountName: null }),
+    ).toEqual({
+      id: "1",
+      type: "other",
+      zoneName: "zone-a",
+    });
+  });
+
+  test("without a discriminator the best-explaining case wins", () => {
+    const schema = S.Unknown.pipe(T.UnionCases(cases));
+    expect(decode(schema, { ...merged, zoneName: null })).toEqual({
+      id: "1",
+      type: "account",
+      accountName: "acct-a",
+    });
+  });
+});