@distilled.cloud/core 1.0.0-rc.12 → 1.0.0-rc.13

package/src/graphql.types.ts

@@ -1,185 +1,114 @@
-/** 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";
+/** Compile-only: Query.fn unwraps Query/Effect fields on the returned plan. */
+import type { PlanError, Query, QueryError, UnwrapPlan } from "./query.ts";
+import { mapQuery } from "./graphql.ts";
 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;
+  itemsQuery,
+  GraphQLFailure,
+  GraphQLTransportError,
+  UnknownGraphQLError,
+} from "./graphql.ts";
+import type * as Effect from "effect/Effect";
+import type * as Stream from "effect/Stream";
 
-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 Plan = {
+  readonly email: Query<string>;
+  readonly projects: Query<ReadonlyArray<{ name: string; stars: number }>>;
+  readonly flag: Effect.Effect<boolean>;
 };
-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 Unwrapped = UnwrapPlan<Plan>;
+type Assert<T extends true> = T;
+type Equal<Left, Right> = [Left] extends [Right]
+  ? [Right] extends [Left]
+    ? true
+    : false
+  : false;
 
-type Search = G.Result<FixtureSchema, "Query!", SearchSelection>;
-type _Union = Assert<
-  Equal<
-    Search["search"][number],
-    | { __typename: "Project"; name: string }
-    | { __typename: "Service"; status: "ACTIVE" | "ARCHIVED" }
-  >
+type _Email = Assert<Equal<Unwrapped["email"], string>>;
+type _Projects = Assert<
+  Equal<Unwrapped["projects"], ReadonlyArray<{ name: string; stars: number }>>
 >;
+type _Flag = Assert<Equal<Unwrapped["flag"], boolean>>;
 
-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>
+// ── Errors ──────────────────────────────────────────────────────────────────
+declare class NotFound {
+  readonly _tag: "NotFound";
+  readonly message: string;
+}
+declare class RateLimited {
+  readonly _tag: "RateLimited";
+  readonly message: string;
+}
+declare const project: Query<
+  { name: string; services: ReadonlyArray<{ name: string }> },
+  NotFound | RateLimited
 >;
+declare const me: Query<{ email: string }, RateLimited>;
+declare const lookup: Effect.Effect<number, "lookup-failed">;
+
+type ErrorPlan = {
+  readonly name: typeof project.name;
+  readonly services: Query<ReadonlyArray<string>, NotFound>;
+  readonly email: typeof me.email;
+  readonly lookup: typeof lookup;
+};
 
-type ConditionalRoot = G.Result<
-  FixtureSchema,
-  "Query!",
-  {
-    ping: { $include: boolean; select: true };
-  }
+type _FieldsKeepRootErrors = Assert<
+  Equal<(typeof project.name)["errorType"], NotFound | RateLimited>
 >;
-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 _PlanError = Assert<
+  Equal<PlanError<ErrorPlan>, NotFound | RateLimited | "lookup-failed">
 >;
-type _ConditionalNested = Assert<
+type _NoErrors = Assert<Equal<PlanError<{ literal: 1 }>, never>>;
+type _QueryError = Assert<
   Equal<
-    ConditionalNested,
-    {
-      project: { id: string; name?: string } | null;
-    }
+    Exclude<
+      QueryError<NotFound>,
+      | GraphQLFailure<NotFound | UnknownGraphQLError>
+      | UnknownGraphQLError
+      | GraphQLTransportError
+    >,
+    NotFound
   >
 >;
-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<
+// ── Pagination ──────────────────────────────────────────────────────────────
+declare const services: Query<ReadonlyArray<{ name: string }>, NotFound>;
+type PagedItems = ReturnType<typeof itemsQuery<{ name: string }, NotFound>>;
+type _ItemsValue = Assert<Equal<Stream.Success<PagedItems>, { name: string }>>;
+type _ItemsError = Assert<
   Equal<
-    Extract<MergedInterface, { __typename: "Project" }>["parent"],
-    { id: string; name: string } | null
+    Extract<
+      Stream.Error<PagedItems>,
+      { _tag: "NotFound" | "GraphQLPaginationError" }
+    >["_tag"],
+    "NotFound" | "GraphQLPaginationError"
   >
 >;
+export type _Services = typeof services;
 
-// 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>
+// ── Nullability ─────────────────────────────────────────────────────────────
+declare const nullable: Query<{
+  owner: { name: string; tags: ReadonlyArray<string> | null } | null;
+}>;
+type _NullParent = Assert<
+  Equal<UnwrapPlan<typeof nullable.owner.name>, string | null>
 >;
 
-// @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>
+// ── Query.map on objects ────────────────────────────────────────────────────
+declare const service: Query<{
+  name: string;
+  stars: number;
+  latestDeployment: { id: string; status: string } | null;
+  tags: ReadonlyArray<{ label: string }>;
+}>;
+const deployment = service.latestDeployment.pipe(
+  mapQuery((d) => ({ id: d.id, status: d.status })),
+);
+type _ObjectMap = Assert<
+  Equal<UnwrapPlan<typeof deployment>, { id: string; status: string } | null>
 >;
+const popular = service.stars.pipe(mapQuery((stars) => stars > 5));
+type _ScalarMap = Assert<Equal<UnwrapPlan<typeof popular>, boolean>>;
+const labels = service.tags.pipe(mapQuery((tag) => tag.label));
+type _ListMap = Assert<Equal<UnwrapPlan<typeof labels>, ReadonlyArray<string>>>;

package/src/index.ts

@@ -0,0 +1,26 @@
+/**
+ * `@distilled.cloud/core` — the runtime shared by every distilled SDK.
+ *
+ * ```ts
+ * import { ResponseValidation, Retry } from "@distilled.cloud/core";
+ *
+ * program.pipe(Effect.provide(ResponseValidation.strict));
+ * ```
+ *
+ * Each namespace is also importable on its own subpath
+ * (`@distilled.cloud/core/response-validation`, …); generated SDKs use the
+ * subpaths. Code generation (`codegen/*`) and test helpers (`testing`) stay
+ * subpath-only.
+ */
+export * as API from "./api.ts";
+export * as Category from "./category.ts";
+export * as Errors from "./errors.ts";
+export * as GraphQL from "./graphql.ts";
+export * as Pagination from "./pagination.ts";
+export * as ProtocolHttp from "./protocol-http.ts";
+export * as ProtocolRest from "./protocol-rest.ts";
+export { Query } from "./query.ts";
+export * as ResponseValidation from "./response-validation.ts";
+export * as Retry from "./retry.ts";
+export * as RetryAfter from "./retry-after.ts";
+export * as Trait from "./trait.ts";

package/src/pagination.test.ts

@@ -0,0 +1,191 @@
+import { describe, expect, test } from "bun:test";
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+import {
+  extractItems,
+  paginateCursor,
+  type PaginatedTrait,
+} from "./pagination.ts";
+
+const pagination: PaginatedTrait = {
+  mode: "cursor",
+  inputToken: "cursor",
+  outputToken: "pagination.cursor",
+  items: "items",
+  pageSize: "limit",
+};
+
+type Page = {
+  items?: number[];
+  pagination?: { cursor?: string | null };
+};
+
+type Scenario = {
+  name: string;
+  start?: string;
+  pages: Page[];
+  cursors: Array<string | undefined>;
+};
+
+const scenarios: Scenario[] = [
+  {
+    name: "advances normally until the cursor is omitted",
+    pages: [
+      { items: [1], pagination: { cursor: "a" } },
+      { items: [2], pagination: { cursor: "b" } },
+      { items: [3] },
+    ],
+    cursors: [undefined, "a", "b"],
+  },
+  ...([null, ""] as const).map((cursor) => ({
+    name: `terminates on ${JSON.stringify(cursor)}`,
+    pages: [
+      { items: [1], pagination: { cursor: "a" } },
+      { items: [2], pagination: { cursor } },
+    ],
+    cursors: [undefined, "a"],
+  })),
+  {
+    name: "terminates on an empty page echoing the requested cursor",
+    pages: [
+      { items: [1], pagination: { cursor: "a" } },
+      { items: [], pagination: { cursor: "a" } },
+    ],
+    cursors: [undefined, "a"],
+  },
+  {
+    name: "emits a nonempty page before stopping on a repeated cursor",
+    pages: [
+      { items: [1], pagination: { cursor: "a" } },
+      { items: [2], pagination: { cursor: "a" } },
+    ],
+    cursors: [undefined, "a"],
+  },
+  {
+    name: "terminates when the first response echoes the initial cursor",
+    start: "initial",
+    pages: [{ items: [1], pagination: { cursor: "initial" } }],
+    cursors: ["initial"],
+  },
+  {
+    name: "terminates a multi-cursor cycle",
+    pages: [
+      { items: [1], pagination: { cursor: "a" } },
+      { items: [2], pagination: { cursor: "b" } },
+      { items: [3], pagination: { cursor: "a" } },
+    ],
+    cursors: [undefined, "a", "b"],
+  },
+  {
+    name: "terminates a cycle returning to the initial cursor",
+    start: "initial",
+    pages: [
+      { items: [1], pagination: { cursor: "a" } },
+      { items: [2], pagination: { cursor: "initial" } },
+    ],
+    cursors: ["initial", "a"],
+  },
+  {
+    name: "preserves empty and sparse pages whose cursors advance",
+    pages: [
+      { items: [], pagination: { cursor: "a" } },
+      { pagination: { cursor: "b" } },
+      { items: [1], pagination: { cursor: "c" } },
+      { items: [], pagination: { cursor: "d" } },
+      { items: [2] },
+    ],
+    cursors: [undefined, "a", "b", "c", "d"],
+  },
+];
+
+const fixture = ({ pages, start }: Scenario) => {
+  const requests: Array<{ cursor?: string; limit: number }> = [];
+  const input = { ...(start === undefined ? {} : { cursor: start }), limit: 1 };
+  const stream = paginateCursor(
+    (request) =>
+      Effect.sync(() => {
+        const page = pages[requests.length];
+        requests.push(request);
+        if (!page)
+          throw new Error("Paginator made an unexpected extra request");
+        return page;
+      }),
+    input,
+    pagination,
+  );
+  return { stream, requests, input };
+};
+
+const collect = <A>(stream: Stream.Stream<A>) =>
+  Stream.runCollect(stream).pipe(Effect.timeout("1 second"));
+
+describe("cursor pagination", () => {
+  test.each(scenarios)("$name", (scenario) =>
+    Effect.runPromise(
+      Effect.gen(function* () {
+        const { stream, requests, input } = fixture(scenario);
+        const pages = yield* collect(stream);
+        expect(Array.from(pages)).toEqual(scenario.pages);
+        expect(requests.map((request) => request.cursor)).toEqual(
+          scenario.cursors,
+        );
+        expect(requests.every((request) => request.limit === 1)).toBe(true);
+        expect(input.cursor).toBe(scenario.start);
+      }),
+    ),
+  );
+
+  test.each(scenarios)("item extraction: $name", (scenario) =>
+    Effect.runPromise(
+      Effect.gen(function* () {
+        const { stream, requests } = fixture(scenario);
+        const items = yield* collect(
+          extractItems<Page, number, never, never>(stream, "items"),
+        );
+        expect(Array.from(items)).toEqual(
+          scenario.pages.flatMap((page) => page.items ?? []),
+        );
+        expect(requests.map((request) => request.cursor)).toEqual(
+          scenario.cursors,
+        );
+      }),
+    ),
+  );
+
+  test("cursor history is isolated across repeated and concurrent stream runs", () =>
+    Effect.runPromise(
+      Effect.gen(function* () {
+        let calls = 0;
+        const pages: Page[] = [
+          { items: [1], pagination: { cursor: "a" } },
+          { items: [2], pagination: { cursor: "b" } },
+          { items: [], pagination: { cursor: "b" } },
+        ];
+        const stream = paginateCursor(
+          (input: { cursor?: string }) =>
+            Effect.sync(() => {
+              if (++calls > 12)
+                throw new Error("Paginator exceeded the request bound");
+              return pages[
+                input.cursor === "a" ? 1 : input.cursor === "b" ? 2 : 0
+              ]!;
+            }),
+          {},
+          pagination,
+        );
+        expect(Array.from(yield* collect(stream))).toEqual(pages);
+        expect(Array.from(yield* collect(stream))).toEqual(pages);
+        const concurrent = yield* Effect.all(
+          [collect(stream), collect(stream)],
+          {
+            concurrency: "unbounded",
+          },
+        );
+        expect(concurrent.map((result) => Array.from(result))).toEqual([
+          pages,
+          pages,
+        ]);
+        expect(calls).toBe(12);
+      }),
+    ));
+});

package/src/pagination.ts

@@ -199,7 +199,8 @@ export const paginatePageNumber = <
 
 /**
  * Stream of pages using cursor-based pagination — follow `outputToken`
- * cursors until one comes back absent.
+ * cursors until one comes back absent or repeats a previously requested cursor.
+ * Empty pages still advance when they return a new cursor.
  */
 export const paginateCursor = <
   Input extends Record<string, unknown>,
@@ -224,30 +225,39 @@ export const paginateCursor = <
       ? (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 nextState: State = {
-        cursor: nextCursor ?? undefined,
-        done: isTerminalToken(nextCursor),
-      };
-
-      return [response, nextState] as const;
-    }),
-  );
+  return Stream.suspend(() => {
+    // Cursor history belongs to this traversal, not to the reusable stream.
+    const requestedCursors = new Set<string>();
+    return Stream.unfold(
+      { cursor: startCursor, done: false } as State,
+      (state) =>
+        Effect.gen(function* () {
+          if (state.done) return undefined;
+          if (state.cursor !== undefined) requestedCursors.add(state.cursor);
+
+          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 nextState: State = {
+            cursor: nextCursor ?? undefined,
+            done:
+              isTerminalToken(nextCursor) ||
+              (nextCursor != null && requestedCursors.has(nextCursor)),
+          };
+
+          return [response, nextState] as const;
+        }),
+    );
+  });
 };
 
 // ============================================================================