ENSv2 Find Domain Ordering Support

apps/ensapi/src/graphql-api/lib/find-domains.ts

@@ -1,4 +1,4 @@
-import { and, eq, like, Param, sql } from "drizzle-orm";
+import { and, asc, desc, eq, like, Param, type SQL, sql } from "drizzle-orm";
 import { alias, unionAll } from "drizzle-orm/pg-core";
 import type { Address } from "viem";
 
@@ -13,6 +13,8 @@ import {
   parsePartialInterpretedName,
 } from "@ensnode/ensnode-sdk";
 
+import type { DomainsOrderBy } from "@/graphql-api/schema/domain";
+import type { OrderDirection } from "@/graphql-api/schema/order-direction";
 import { db } from "@/lib/db";
 import { makeLogger } from "@/lib/logger";
 
@@ -98,9 +100,15 @@ export function findDomains({ name, owner }: DomainFilter) {
   const v1HeadDomain = alias(schema.v1Domain, "v1HeadDomain");
   const v2HeadDomain = alias(schema.v2Domain, "v2HeadDomain");
 
-  // join on leafId (the autocomplete result), filter by owner and partial
-  const v1Domains = db
-    .select({ id: sql<DomainId>`${schema.v1Domain.id}`.as("id") })
+  // Base subqueries: extract unified structure from v1 and v2 domains
+  // Returns {id, ownerId, leafLabelHash, headLabelHash} for each matching domain
+  const v1DomainsBase = db
+    .select({
+      id: sql<DomainId>`${schema.v1Domain.id}`.as("id"),
+      ownerId: schema.v1Domain.ownerId,
+      leafLabelHash: schema.v1Domain.labelHash,
+      headLabelHash: v1HeadDomain.labelHash,
+    })
     .from(schema.v1Domain)
     .innerJoin(
       v1DomainsByLabelHashPathQuery,
@@ -118,28 +126,78 @@ export function findDomains({ name, owner }: DomainFilter) {
       ),
     );
 
-  // join on leafId (the autocomplete result), filter by owner and partial
-  const v2Domains = db
-    .select({ id: sql<DomainId>`${schema.v2Domain.id}`.as("id") })
+  const v2DomainsBase = db
+    .select({
+      id: sql<DomainId>`${schema.v2Domain.id}`.as("id"),
+      ownerId: schema.v2Domain.ownerId,
+      leafLabelHash: schema.v2Domain.labelHash,
+      headLabelHash: v2HeadDomain.labelHash,
+    })
     .from(schema.v2Domain)
     .innerJoin(
       v2DomainsByLabelHashPathQuery,
       eq(schema.v2Domain.id, v2DomainsByLabelHashPathQuery.leafId),
     )
-    .innerJoin(v2HeadDomain, eq(v2HeadDomain.id, v2DomainsByLabelHashPathQuery.headId))
-    .leftJoin(schema.label, eq(schema.label.labelHash, v2HeadDomain.labelHash))
+    .innerJoin(v2HeadDomain, eq(v2HeadDomain.id, v2DomainsByLabelHashPathQuery.headId));
+
+  // Union v1 and v2 base queries into a single CTE
+  const domainsBase = db.$with("domainsBase").as(unionAll(v1DomainsBase, v2DomainsBase));
+
+  // alias for head label (for partial matching) and leaf label (for NAME ordering)
+  const headLabel = alias(schema.label, "headLabel");
+  const leafLabel = alias(schema.label, "leafLabel");
+
+  // subquery for latest registration per domain (highest index)
+  // TODO: replace this with a JOIN against the latest registration lookup table after
+  // https://github.com/namehash/ensnode/issues/1594
+  const latestRegistration = db
+    .select({
+      domainId: schema.registration.domainId,
+      start: schema.registration.start,
+      expiry: schema.registration.expiry,
+    })
+    .from(schema.registration)
+    .where(
+      eq(
+        schema.registration.index,
+        db
+          .select({ maxIndex: sql<number>`MAX(${schema.registration.index})` })
+          .from(schema.registration)
+          .where(eq(schema.registration.domainId, schema.registration.domainId)),
+      ),
+    )
+    .as("latestRegistration");
+
+  // Apply shared joins and filters on the unified domain base
+  const domains = db
+    .with(domainsBase)
+    .select({
+      id: domainsBase.id,
+      // for NAME ordering
+      leafLabelValue: sql<string | null>`${leafLabel.interpreted}`.as("leafLabelValue"),
+      // for REGISTRATION_TIMESTAMP ordering
+      registrationStart: sql<bigint | null>`${latestRegistration.start}`.as("registrationStart"),
+      // for REGISTRATION_EXPIRY ordering
+      registrationExpiry: sql<bigint | null>`${latestRegistration.expiry}`.as("registrationExpiry"),
+    })
+    .from(domainsBase)
+    // join head label for partial matching
+    .leftJoin(headLabel, eq(headLabel.labelHash, domainsBase.headLabelHash))
+    // join leaf label for NAME ordering
+    .leftJoin(leafLabel, eq(leafLabel.labelHash, domainsBase.leafLabelHash))
+    // join latest registration for timestamp/expiry ordering
+    .leftJoin(latestRegistration, eq(latestRegistration.domainId, domainsBase.id))
     .where(
       and(
-        owner ? eq(schema.v2Domain.ownerId, owner) : undefined,
+        owner ? eq(domainsBase.ownerId, owner) : undefined,
         // TODO: determine if it's necessary to additionally escape user input for LIKE operator
         // Note: if label is NULL (unlabeled domain), LIKE returns NULL and filters out the row.
         // This is intentional - we can't match partial text against unknown labels.
         partial ? like(schema.label.interpreted, `${partial}%`) : undefined,
       ),
     );
 
-  // union the two subqueries and return
-  return db.$with("domains").as(unionAll(v1Domains, v2Domains));
+  return db.$with("domains").as(domains);
 }
 
 /**
@@ -299,3 +357,40 @@ function v2DomainsByLabelHashPath(labelHashPath: LabelHashPath) {
     )
     .as("v2_path");
 }
+
+/**
+ * Build ORDER BY clauses for a findDomains result.
+ *
+ * @param domains - The findDomains CTE result
+ * @param orderBy - The field to order by (defaults to NAME)
+ * @param orderDir - The direction to order ("ASC" or "DESC", defaults to "ASC")
+ * @param inverted - Whether the relay pagination is inverted (backward pagination)
+ * @returns Array of SQL order expressions
+ */
+export function orderFindDomains(
+  domains: ReturnType<typeof findDomains>,
+  orderBy: typeof DomainsOrderBy.$inferType | undefined | null,
+  orderDir: typeof OrderDirection.$inferType | undefined | null,
+  inverted: boolean,
+): SQL[] {
+  // Combine user's orderDir with relay's inverted (XOR logic)
+  // inverted flips the sort for backward pagination, so we flip it back
+  const effectiveDesc = (orderDir === "DESC") !== inverted;
+
+  const orderColumn = {
+    NAME: domains.leafLabelValue,
+    REGISTRATION_TIMESTAMP: domains.registrationStart,
+    REGISTRATION_EXPIRY: domains.registrationExpiry,
+  }[orderBy ?? "NAME"];
+
+  // Use NULLS LAST for ascending, NULLS FIRST for descending
+  // This keeps unregistered domains at the end when sorting by registration fields
+  const primaryOrder = effectiveDesc
+    ? sql`${orderColumn} DESC NULLS FIRST`
+    : sql`${orderColumn} ASC NULLS LAST`;
+
+  // Always include id as tiebreaker for stable ordering
+  const tiebreaker = effectiveDesc ? desc(domains.id) : asc(domains.id);
+
+  return [primaryOrder, tiebreaker];
+}

apps/ensapi/src/graphql-api/schema/account.ts

@@ -6,15 +6,19 @@ import * as schema from "@ensnode/ensnode-schema";
 import type { DomainId, PermissionsUserId } from "@ensnode/ensnode-sdk";
 
 import { builder } from "@/graphql-api/builder";
-import { findDomains } from "@/graphql-api/lib/find-domains";
+import { findDomains, orderFindDomains } from "@/graphql-api/lib/find-domains";
 import { getModelId } from "@/graphql-api/lib/get-model-id";
 import { rejectAnyErrors } from "@/graphql-api/lib/reject-any-errors";
 import { AccountIdInput } from "@/graphql-api/schema/account-id";
 import { AccountRegistryPermissionsRef } from "@/graphql-api/schema/account-registries-permissions";
 import { AccountResolverPermissionsRef } from "@/graphql-api/schema/account-resolver-permissions";
 import { DEFAULT_CONNECTION_ARGS } from "@/graphql-api/schema/constants";
 import { cursors } from "@/graphql-api/schema/cursors";
-import { AccountDomainsWhereInput, DomainInterfaceRef } from "@/graphql-api/schema/domain";
+import {
+  AccountDomainsWhereInput,
+  DomainInterfaceRef,
+  DomainsOrderInput,
+} from "@/graphql-api/schema/domain";
 import { PermissionsUserRef } from "@/graphql-api/schema/permissions";
 import { db } from "@/lib/db";
 
@@ -64,6 +68,7 @@ AccountRef.implement({
       type: DomainInterfaceRef,
       args: {
         where: t.arg({ type: AccountDomainsWhereInput, required: false }),
+        order: t.arg({ type: DomainsOrderInput }),
       },
       resolve: (parent, args, context) =>
         resolveCursorConnection(
@@ -72,6 +77,14 @@ AccountRef.implement({
             // construct query for relevant domains
             const domains = findDomains({ ...args.where, owner: parent.id });
 
+            // build order clauses
+            const orderClauses = orderFindDomains(
+              domains,
+              args.order?.by,
+              args.order?.dir,
+              inverted,
+            );
+
             // execute with pagination constraints
             const results = await db
               .with(domains)
@@ -83,7 +96,7 @@ AccountRef.implement({
                   after ? gt(domains.id, cursors.decode<DomainId>(after)) : undefined,
                 ),
               )
-              .orderBy(inverted ? desc(domains.id) : asc(domains.id))
+              .orderBy(...orderClauses)
               .limit(limit);
 
             // provide full Domain entities via dataloader

apps/ensapi/src/graphql-api/schema/domain.ts

@@ -17,6 +17,7 @@ import { rejectAnyErrors } from "@/graphql-api/lib/reject-any-errors";
 import { AccountRef } from "@/graphql-api/schema/account";
 import { DEFAULT_CONNECTION_ARGS } from "@/graphql-api/schema/constants";
 import { cursors } from "@/graphql-api/schema/cursors";
+import { OrderDirection } from "@/graphql-api/schema/order-direction";
 import { RegistrationInterfaceRef } from "@/graphql-api/schema/registration";
 import { RegistryRef } from "@/graphql-api/schema/registry";
 import { ResolverRef } from "@/graphql-api/schema/resolver";
@@ -331,3 +332,22 @@ export const AccountDomainsWhereInput = builder.inputType("AccountDomainsWhereIn
     name: t.string({ required: true }),
   }),
 });
+
+//////////////////////
+// Ordering
+//////////////////////
+
+export const DomainsOrderBy = builder.enumType("DomainsOrderBy", {
+  description: "Fields by which domains can be ordered",
+  values: ["NAME", "REGISTRATION_TIMESTAMP", "REGISTRATION_EXPIRY"] as const,
+});
+
+export type DomainsOrderByValue = typeof DomainsOrderBy.$inferType;
+
+export const DomainsOrderInput = builder.inputType("DomainsOrderInput", {
+  description: "Ordering options for domains query",
+  fields: (t) => ({
+    by: t.field({ type: DomainsOrderBy, required: true }),
+    dir: t.field({ type: OrderDirection, defaultValue: "ASC" }),
+  }),
+});

apps/ensapi/src/graphql-api/schema/order-direction.ts

@@ -0,0 +1,8 @@
+import { builder } from "@/graphql-api/builder";
+
+export const OrderDirection = builder.enumType("OrderDirection", {
+  description: "Sort direction",
+  values: ["ASC", "DESC"] as const,
+});
+
+export type OrderDirectionValue = typeof OrderDirection.$inferType;

apps/ensapi/src/graphql-api/schema/query.ts

@@ -1,7 +1,7 @@
 import config from "@/config";
 
 import { type ResolveCursorConnectionArgs, resolveCursorConnection } from "@pothos/plugin-relay";
-import { and, asc, desc, gt, lt } from "drizzle-orm";
+import { and, gt, lt } from "drizzle-orm";
 
 import {
   type DomainId,
@@ -16,7 +16,7 @@ import {
 } from "@ensnode/ensnode-sdk";
 
 import { builder } from "@/graphql-api/builder";
-import { findDomains } from "@/graphql-api/lib/find-domains";
+import { findDomains, orderFindDomains } from "@/graphql-api/lib/find-domains";
 import { getDomainIdByInterpretedName } from "@/graphql-api/lib/get-domain-by-fqdn";
 import { rejectAnyErrors } from "@/graphql-api/lib/reject-any-errors";
 import { AccountRef } from "@/graphql-api/schema/account";
@@ -26,6 +26,7 @@ import { cursors } from "@/graphql-api/schema/cursors";
 import {
   DomainIdInput,
   DomainInterfaceRef,
+  DomainsOrderInput,
   DomainsWhereInput,
   ENSv1DomainRef,
   ENSv2DomainRef,
@@ -50,6 +51,7 @@ builder.queryType({
         type: DomainInterfaceRef,
         args: {
           where: t.arg({ type: DomainsWhereInput, required: true }),
+          order: t.arg({ type: DomainsOrderInput }),
         },
         resolve: (parent, args, context) =>
           resolveCursorConnection(
@@ -58,6 +60,14 @@ builder.queryType({
               // construct query for relevant domains
               const domains = findDomains(args.where);
 
+              // build order clauses
+              const orderClauses = orderFindDomains(
+                domains,
+                args.order?.by,
+                args.order?.dir,
+                inverted,
+              );
+
               // execute with pagination constraints
               const results = await db
                 .with(domains)
@@ -69,7 +79,7 @@ builder.queryType({
                     after ? gt(domains.id, cursors.decode<DomainId>(after)) : undefined,
                   ),
                 )
-                .orderBy(inverted ? desc(domains.id) : asc(domains.id))
+                .orderBy(...orderClauses)
                 .limit(limit);
 
               // provide full Domain entities via dataloader