@distilled.cloud/core 1.0.0-rc.2 → 1.0.0-rc.4

package/src/errors.ts

@@ -33,7 +33,7 @@ export const DurationSchema = Schema.declare<Duration.Duration>(
 /**
  * Unauthorized - Authentication failure (401).
  */
-export class Unauthorized extends Schema.TaggedErrorClass<Unauthorized>()(
+export class Unauthorized extends Schema.TaggedError<Unauthorized>()(
   "Unauthorized",
   { message: Schema.String },
 ).pipe(Category.withAuthError) {}
@@ -41,37 +41,35 @@ export class Unauthorized extends Schema.TaggedErrorClass<Unauthorized>()(
 /**
  * Forbidden - Access denied (403).
  */
-export class Forbidden extends Schema.TaggedErrorClass<Forbidden>()(
-  "Forbidden",
-  { message: Schema.String },
-).pipe(Category.withAuthError) {}
+export class Forbidden extends Schema.TaggedError<Forbidden>()("Forbidden", {
+  message: Schema.String,
+}).pipe(Category.withAuthError) {}
 
 /**
  * NotFound - Resource not found (404).
  */
-export class NotFound extends Schema.TaggedErrorClass<NotFound>()("NotFound", {
+export class NotFound extends Schema.TaggedError<NotFound>()("NotFound", {
   message: Schema.String,
 }).pipe(Category.withNotFoundError) {}
 
 /**
  * BadRequest - Invalid request (400).
  */
-export class BadRequest extends Schema.TaggedErrorClass<BadRequest>()(
-  "BadRequest",
-  { message: Schema.String },
-).pipe(Category.withBadRequestError) {}
+export class BadRequest extends Schema.TaggedError<BadRequest>()("BadRequest", {
+  message: Schema.String,
+}).pipe(Category.withBadRequestError) {}
 
 /**
  * Conflict - Resource conflict (409).
  */
-export class Conflict extends Schema.TaggedErrorClass<Conflict>()("Conflict", {
+export class Conflict extends Schema.TaggedError<Conflict>()("Conflict", {
   message: Schema.String,
 }).pipe(Category.withConflictError) {}
 
 /**
  * UnprocessableEntity - Validation error (422).
  */
-export class UnprocessableEntity extends Schema.TaggedErrorClass<UnprocessableEntity>()(
+export class UnprocessableEntity extends Schema.TaggedError<UnprocessableEntity>()(
   "UnprocessableEntity",
   { message: Schema.String },
 ).pipe(Category.withBadRequestError) {}
@@ -79,7 +77,7 @@ export class UnprocessableEntity extends Schema.TaggedErrorClass<UnprocessableEn
 /**
  * TooManyRequests - Rate limited (429).
  */
-export class TooManyRequests extends Schema.TaggedErrorClass<TooManyRequests>()(
+export class TooManyRequests extends Schema.TaggedError<TooManyRequests>()(
   "TooManyRequests",
   {
     message: Schema.String,
@@ -93,7 +91,7 @@ export class TooManyRequests extends Schema.TaggedErrorClass<TooManyRequests>()(
 /**
  * Locked - Resource locked (423).
  */
-export class Locked extends Schema.TaggedErrorClass<Locked>()("Locked", {
+export class Locked extends Schema.TaggedError<Locked>()("Locked", {
   message: Schema.String,
   retryAfter: Schema.optional(DurationSchema),
 }).pipe(Category.withLockedError, Category.withRetryable()) {}
@@ -106,7 +104,7 @@ export class Locked extends Schema.TaggedErrorClass<Locked>()("Locked", {
  * 200 envelope carrying `{ code: 10002, message: "An unknown error has
  * occurred" }` for transient backend failures on some endpoints).
  */
-export class InternalServerError extends Schema.TaggedErrorClass<InternalServerError>()(
+export class InternalServerError extends Schema.TaggedError<InternalServerError>()(
   "InternalServerError",
   {
     message: Schema.String,
@@ -118,18 +116,15 @@ export class InternalServerError extends Schema.TaggedErrorClass<InternalServerE
 /**
  * BadGateway - Bad gateway (502).
  */
-export class BadGateway extends Schema.TaggedErrorClass<BadGateway>()(
-  "BadGateway",
-  {
-    message: Schema.String,
-    retryAfter: Schema.optional(DurationSchema),
-  },
-).pipe(Category.withServerError, Category.withRetryable()) {}
+export class BadGateway extends Schema.TaggedError<BadGateway>()("BadGateway", {
+  message: Schema.String,
+  retryAfter: Schema.optional(DurationSchema),
+}).pipe(Category.withServerError, Category.withRetryable()) {}
 
 /**
  * ServiceUnavailable - Service unavailable (503).
  */
-export class ServiceUnavailable extends Schema.TaggedErrorClass<ServiceUnavailable>()(
+export class ServiceUnavailable extends Schema.TaggedError<ServiceUnavailable>()(
   "ServiceUnavailable",
   {
     message: Schema.String,
@@ -140,7 +135,7 @@ export class ServiceUnavailable extends Schema.TaggedErrorClass<ServiceUnavailab
 /**
  * GatewayTimeout - Gateway timeout (504).
  */
-export class GatewayTimeout extends Schema.TaggedErrorClass<GatewayTimeout>()(
+export class GatewayTimeout extends Schema.TaggedError<GatewayTimeout>()(
   "GatewayTimeout",
   {
     message: Schema.String,
@@ -151,7 +146,7 @@ export class GatewayTimeout extends Schema.TaggedErrorClass<GatewayTimeout>()(
 /**
  * Configuration error - missing or invalid configuration.
  */
-export class ConfigError extends Schema.TaggedErrorClass<ConfigError>()(
+export class ConfigError extends Schema.TaggedError<ConfigError>()(
   "ConfigError",
   { message: Schema.String },
 ).pipe(Category.withConfigurationError) {}

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,82 @@ 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;
+
+      const nextState: State = {
+        cursor: nextCursor ?? undefined,
+        done: !hasNext || isTerminalToken(nextCursor) || emptyPage,
+      };
+
+      return [response, nextState] as const;
+    }),
+  );
+};
+
 /**
  * Shared default pagination dispatcher for SDKs that use generic
  * token/cursor/page traversal.
@@ -277,6 +393,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 +411,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 +420,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.ts

@@ -616,9 +616,17 @@ export const buildRequest = ({
       request = request.pipe(HttpClientRequest.bodyJsonUnsafe(rawBody));
     }
   } else if (
-    !BODYLESS.has(http.method) &&
-    (Object.keys(body).length > 0 ||
-      (hasBodyMembers && http.method !== "DELETE"))
+    // A GET/HEAD sends a body only when body members actually carry values.
+    // Some APIs really do document GET-with-body: MongoDB Atlas's
+    // `…/lineItems:search` declares a `requestBody` on `get`, and AWS EFS's
+    // DescribeAccountPreferences takes `{ MaxResults, NextToken }` on a GET.
+    // Suppressing it outright dropped those members silently — the request
+    // succeeded, unfiltered, with nothing on the wire to show why.
+    //
+    // The `{}`-when-empty rule below stays limited to methods that expect a
+    // body, so a bodyless method with nothing set still sends nothing.
+    Object.keys(body).length > 0 ||
+    (hasBodyMembers && !BODYLESS.has(http.method) && http.method !== "DELETE")
   ) {
     // Send `{}` rather than no body when the schema declares body members —
     // some endpoints reject a missing JSON body outright.

package/src/schema.ts

@@ -48,6 +48,6 @@ export const Null: any = S.Null;
 export const Void: any = S.Void;
 export const Any: any = S.Any;
 
-// NOTE: `Schema` / `Codec` (types) and `TaggedErrorClass` are intentionally NOT
+// NOTE: `Schema` / `Codec` (types) and `TaggedError` are intentionally NOT
 // overridden — they flow through `export *` with real types so cast targets and
 // typed error classes stay precise.