Skip to content

The open alternative to Salesforce, designed for AI.

fix(server): make cursor pagination exhaustive for any orderBy (#24354)

Félix Malfaitff132325ce22
diff --git a/packages/twenty-server/src/engine/api/common/common-query-runners/common-find-many-query-runner.service.ts b/packages/twenty-server/src/engine/api/common/common-query-runners/common-find-many-query-runner.service.ts
index ba5ae18fbcb..6c96d510598 100644
--- a/packages/twenty-server/src/engine/api/common/common-query-runners/common-find-many-query-runner.service.ts
+++ b/packages/twenty-server/src/engine/api/common/common-query-runners/common-find-many-query-runner.service.ts
@@ -37,16 +37,16 @@ import { getPageInfo } from 'src/engine/api/common/utils/get-page-info.util';
import { ProcessAggregateHelper } from 'src/engine/api/graphql/graphql-query-runner/helpers/process-aggregate.helper';
import { type ReadRecordQueryBuilder } from 'src/engine/api/graphql/graphql-query-runner/types/record-query-builder.type';
import { buildColumnsToSelect } from 'src/engine/api/graphql/graphql-query-runner/utils/build-columns-to-select';
+import { buildOrderByColumnsToSelect } from 'src/engine/api/graphql/graphql-query-runner/utils/build-order-by-columns-to-select';
import { getCursor } from 'src/engine/api/graphql/graphql-query-runner/utils/cursors.util';
import { computeCursorArgFilter } from 'src/engine/api/utils/compute-cursor-arg-filter.utils';
import {
- countRelationFieldsInOrderBy,
- hasRelationFieldInOrderBy,
-} from 'src/engine/api/utils/validate-and-get-order-by.utils';
+ buildOrderByFromLeaves,
+ resolveOrderByLeaves,
+} from 'src/engine/api/utils/resolve-order-by-leaves.utils';
import { WorkspaceAuthContext } from 'src/engine/core-modules/auth/types/workspace-auth-context.type';
import { FlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/types/flat-entity-maps.type';
import { FlatFieldMetadata } from 'src/engine/metadata-modules/flat-field-metadata/types/flat-field-metadata.type';
-import { buildFieldMapsFromFlatObjectMetadata } from 'src/engine/metadata-modules/flat-field-metadata/utils/build-field-maps-from-flat-object-metadata.util';
import { FlatObjectMetadata } from 'src/engine/metadata-modules/flat-object-metadata/types/flat-object-metadata.type';
@Injectable()
@@ -91,49 +91,41 @@ export class CommonFindManyQueryRunnerService extends CommonBaseQueryRunnerServi
appliedFilters,
);
- const orderByWithIdCondition = [
- ...(args.orderBy ?? []),
- { id: OrderByDirection.AscNullsFirst },
- ] as ObjectRecordOrderBy;
+ // Normalizing to deduplicated leaves makes the appended id tie-breaker
+ // yield to a caller-provided id ordering, and guarantees the SQL scan
+ // order and the keyset conditions derive from the same list
+ const orderByWithIdCondition = buildOrderByFromLeaves(
+ resolveOrderByLeaves({
+ orderBy: [
+ ...(args.orderBy ?? []),
+ { id: OrderByDirection.AscNullsFirst },
+ ] as ObjectRecordOrderBy,
+ flatObjectMetadata,
+ flatFieldMetadataMaps,
+ strictValidation: true,
+ }),
+ );
const isForwardPagination = !isDefined(args.before);
const cursor = getCursor(args);
if (cursor) {
- const { fieldIdByName } = buildFieldMapsFromFlatObjectMetadata(
- flatFieldMetadataMaps,
- flatObjectMetadata,
- );
-
- if (
- hasRelationFieldInOrderBy(
- args.orderBy ?? [],
- flatFieldMetadataMaps,
- fieldIdByName,
- )
- ) {
- // Not throwing exception because still used on record show page
- /* throw new GraphqlQueryRunnerException(
- 'Cursor-based pagination is not supported with relation field ordering. Use offset pagination instead.',
- GraphqlQueryRunnerExceptionCode.INVALID_CURSOR,
- { userFriendlyMessage: STANDARD_ERROR_MESSAGE },
- ); */
- }
-
- const cursorArgFilter = computeCursorArgFilter(
+ const cursorArgFilter = computeCursorArgFilter({
cursor,
- orderByWithIdCondition,
+ orderBy: orderByWithIdCondition,
flatObjectMetadata,
flatFieldMetadataMaps,
isForwardPagination,
- );
+ });
- appliedFilters = (args.filter && Object.keys(args.filter).length > 0
- ? {
- and: [args.filter, { or: cursorArgFilter }],
- }
- : { or: cursorArgFilter }) as unknown as ObjectRecordFilter;
+ if (cursorArgFilter.length > 0) {
+ appliedFilters = (args.filter && Object.keys(args.filter).length > 0
+ ? {
+ and: [args.filter, { or: cursorArgFilter }],
+ }
+ : { or: cursorArgFilter }) as unknown as ObjectRecordFilter;
+ }
}
commonQueryParser.applyFilterToBuilder(
@@ -159,13 +151,22 @@ export class CommonFindManyQueryRunnerService extends CommonBaseQueryRunnerServi
const limit = args.first ?? args.last ?? QUERY_MAX_RECORDS;
- const columnsToSelect = buildColumnsToSelect({
- select: args.selectedFieldsResult.select,
- relations: args.selectedFieldsResult.relations,
- flatObjectMetadata,
- flatObjectMetadataMaps,
- flatFieldMetadataMaps,
- });
+ const columnsToSelect = {
+ ...buildColumnsToSelect({
+ select: args.selectedFieldsResult.select,
+ relations: args.selectedFieldsResult.relations,
+ flatObjectMetadata,
+ flatObjectMetadataMaps,
+ flatFieldMetadataMaps,
+ }),
+ // Order columns must be hydrated onto the records even when not requested:
+ // cursor encoding reads the sort values from them (issue #24333)
+ ...buildOrderByColumnsToSelect({
+ orderBy: args.orderBy,
+ flatObjectMetadata,
+ flatFieldMetadataMaps,
+ }),
+ };
queryBuilder.setFindOptions({ select: columnsToSelect });
@@ -361,16 +362,11 @@ export class CommonFindManyQueryRunnerService extends CommonBaseQueryRunnerServi
const { flatObjectMetadata, flatFieldMetadataMaps } = queryRunnerContext;
- const { fieldIdByName } = buildFieldMapsFromFlatObjectMetadata(
- flatFieldMetadataMaps,
+ const orderByRelationCount = resolveOrderByLeaves({
+ orderBy: args.orderBy ?? [],
flatObjectMetadata,
- );
-
- const orderByRelationCount = countRelationFieldsInOrderBy(
- args.orderBy ?? [],
flatFieldMetadataMaps,
- fieldIdByName,
- );
+ }).filter((leaf) => leaf.kind === 'relation').length;
return baseComplexity + orderByRelationCount;
}
diff --git a/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/graphql-query-filter/graphql-query-filter-field.parser.ts b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/graphql-query-filter/graphql-query-filter-field.parser.ts
index 5fc0c168d9e..deecfeea4e9 100644
--- a/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/graphql-query-filter/graphql-query-filter-field.parser.ts
+++ b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/graphql-query-filter/graphql-query-filter-field.parser.ts
@@ -10,6 +10,7 @@ import {
GraphqlQueryRunnerExceptionCode,
} from 'src/engine/api/graphql/graphql-query-runner/errors/graphql-query-runner.exception';
import { addRelationJoinAliasToQueryBuilder } from 'src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/utils/add-relation-join-alias.util';
+import { assertFieldIsReadableOrThrow } from 'src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/utils/assert-field-is-readable-or-throw.util';
import { resolveFilterKeyFieldMetadata } from 'src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/utils/resolve-filter-key-field-metadata.util';
import { assertArrayOperatorValueIsNonEmptyArray } from 'src/engine/api/graphql/graphql-query-runner/utils/assert-array-operator-value-is-non-empty-array.util';
import { computeWhereConditionParts } from 'src/engine/api/graphql/graphql-query-runner/utils/compute-where-condition-parts';
@@ -83,16 +84,19 @@ export class GraphqlQueryFilterFieldParser {
const objectPermissions =
outerQueryBuilder.objectRecordsPermissions[this.flatObjectMetadata.id];
- if (
- objectPermissions?.canReadObjectRecords === false ||
- objectPermissions?.restrictedFields[fieldMetadata.id]?.canRead === false
- ) {
+ if (objectPermissions?.canReadObjectRecords === false) {
throw new PermissionsException(
PermissionsExceptionMessage.PERMISSION_DENIED,
PermissionsExceptionCode.PERMISSION_DENIED,
);
}
+ assertFieldIsReadableOrThrow({
+ objectsPermissions: outerQueryBuilder.objectRecordsPermissions,
+ objectMetadataId: this.flatObjectMetadata.id,
+ fieldMetadataId: fieldMetadata.id,
+ });
+
if (
isReferencedByFieldName &&
isMorphOrRelationFlatFieldMetadata(fieldMetadata) &&
diff --git a/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/graphql-query-order/__tests__/parse-composite-field-for-order.util.spec.ts b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/graphql-query-order/__tests__/parse-composite-field-for-order.util.spec.ts
index cc763598fcd..9195aaeaecc 100644
--- a/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/graphql-query-order/__tests__/parse-composite-field-for-order.util.spec.ts
+++ b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/graphql-query-order/__tests__/parse-composite-field-for-order.util.spec.ts
@@ -124,7 +124,7 @@ describe('parseCompositeFieldForOrder', () => {
});
describe('pagination direction handling', () => {
- it('should reverse order direction for backward pagination', () => {
+ it('should reverse order direction and nulls placement for backward pagination', () => {
const fieldMetadata = {
type: FieldMetadataType.FULL_NAME,
name: 'name',
@@ -140,7 +140,7 @@ describe('parseCompositeFieldForOrder', () => {
expect(result).toEqual({
'person.nameFirstName': {
order: 'DESC',
- nulls: 'NULLS FIRST',
+ nulls: 'NULLS LAST',
useLower: true,
castToText: false,
},
diff --git a/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/graphql-query-order/graphql-query-order.parser.ts b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/graphql-query-order/graphql-query-order.parser.ts
index 5af7e1510cb..f04080bb3b3 100644
--- a/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/graphql-query-order/graphql-query-order.parser.ts
+++ b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/graphql-query-order/graphql-query-order.parser.ts
@@ -1,4 +1,5 @@
import { isObject } from 'class-validator';
+import { type ObjectsPermissions } from 'twenty-shared/types';
import { isDefined } from 'twenty-shared/utils';
import { type ObjectRecordOrderBy } from 'src/engine/api/graphql/workspace-query-builder/interfaces/object-record.interface';
@@ -8,6 +9,7 @@ import {
GraphqlQueryRunnerException,
GraphqlQueryRunnerExceptionCode,
} from 'src/engine/api/graphql/graphql-query-runner/errors/graphql-query-runner.exception';
+import { assertFieldIsReadableOrThrow } from 'src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/utils/assert-field-is-readable-or-throw.util';
import {
buildOrderByColumnExpression,
shouldCastToText,
@@ -60,6 +62,7 @@ export class GraphqlQueryOrderFieldParser {
orderBy: ObjectRecordOrderBy,
objectNameSingular: string,
isForwardPagination = true,
+ objectsPermissions?: ObjectsPermissions,
): ParseOrderByResult {
const orderByConditions: Record<string, OrderByClause> = {};
const relationJoins: RelationJoinInfo[] = [];
@@ -85,6 +88,12 @@ export class GraphqlQueryOrderFieldParser {
);
}
+ assertFieldIsReadableOrThrow({
+ objectsPermissions,
+ objectMetadataId: this.flatObjectMetadata.id,
+ fieldMetadataId: fieldMetadata.id,
+ });
+
// Only treat as relation if accessed by relation name (not FK like companyId)
if (
isAccessedByRelationName &&
@@ -102,6 +111,7 @@ export class GraphqlQueryOrderFieldParser {
fieldMetadata,
orderByDirection: orderByDirection as Record<string, unknown>,
isForwardPagination,
+ objectsPermissions,
});
if (relationOrderResult) {
@@ -165,10 +175,12 @@ export class GraphqlQueryOrderFieldParser {
fieldMetadata,
orderByDirection,
isForwardPagination,
+ objectsPermissions,
}: {
fieldMetadata: FlatFieldMetadata;
orderByDirection: Record<string, unknown>;
isForwardPagination: boolean;
+ objectsPermissions?: ObjectsPermissions;
}): {
orderBy: Record<string, OrderByClause>;
joinInfo: RelationJoinInfo;
@@ -218,6 +230,12 @@ export class GraphqlQueryOrderFieldParser {
return null;
}
+ assertFieldIsReadableOrThrow({
+ objectsPermissions,
+ objectMetadataId: targetObjectMetadata.id,
+ fieldMetadataId: nestedFieldMetadata.id,
+ });
+
const joinAlias = fieldMetadata.name;
const joinInfo: RelationJoinInfo = {
diff --git a/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/graphql-query-order/utils/__tests__/convert-order-by-to-find-options-order.spec.ts b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/graphql-query-order/utils/__tests__/convert-order-by-to-find-options-order.spec.ts
new file mode 100644
index 00000000000..7778d18c1ca
--- /dev/null
+++ b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/graphql-query-order/utils/__tests__/convert-order-by-to-find-options-order.spec.ts
@@ -0,0 +1,37 @@
+import { OrderByDirection } from 'twenty-shared/types';
+
+import { convertOrderByToFindOptionsOrder } from 'src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/graphql-query-order/utils/convert-order-by-to-find-options-order';
+
+describe('convertOrderByToFindOptionsOrder', () => {
+ it.each([
+ [OrderByDirection.AscNullsFirst, 'ASC', 'NULLS FIRST'],
+ [OrderByDirection.AscNullsLast, 'ASC', 'NULLS LAST'],
+ [OrderByDirection.DescNullsFirst, 'DESC', 'NULLS FIRST'],
+ [OrderByDirection.DescNullsLast, 'DESC', 'NULLS LAST'],
+ ])(
+ 'should keep %s as-is for forward pagination',
+ (direction, order, nulls) => {
+ expect(convertOrderByToFindOptionsOrder(direction, true)).toEqual({
+ order,
+ nulls,
+ });
+ },
+ );
+
+ // The backward scan is the exact reverse of the requested order, so the NULLS
+ // placement reverses along with the direction
+ it.each([
+ [OrderByDirection.AscNullsFirst, 'DESC', 'NULLS LAST'],
+ [OrderByDirection.AscNullsLast, 'DESC', 'NULLS FIRST'],
+ [OrderByDirection.DescNullsFirst, 'ASC', 'NULLS LAST'],
+ [OrderByDirection.DescNullsLast, 'ASC', 'NULLS FIRST'],
+ ])(
+ 'should fully reverse %s for backward pagination',
+ (direction, order, nulls) => {
+ expect(convertOrderByToFindOptionsOrder(direction, false)).toEqual({
+ order,
+ nulls,
+ });
+ },
+ );
+});
diff --git a/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/graphql-query-order/utils/convert-order-by-to-find-options-order.ts b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/graphql-query-order/utils/convert-order-by-to-find-options-order.ts
index 6e205c4a349..4ba985757eb 100644
--- a/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/graphql-query-order/utils/convert-order-by-to-find-options-order.ts
+++ b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/graphql-query-order/utils/convert-order-by-to-find-options-order.ts
@@ -1,42 +1,35 @@
-import { OrderByDirection } from 'twenty-shared/types';
+import { type OrderByDirection } from 'twenty-shared/types';
import { STANDARD_ERROR_MESSAGE } from 'src/engine/api/common/common-query-runners/errors/standard-error-message.constant';
import {
GraphqlQueryRunnerException,
GraphqlQueryRunnerExceptionCode,
} from 'src/engine/api/graphql/graphql-query-runner/errors/graphql-query-runner.exception';
+import { isOrderByDirection } from 'src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/graphql-query-order/utils/is-order-by-direction.util';
import { type OrderByClause } from 'src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/graphql-query-order/graphql-query-order.parser';
+import { getEffectiveScanOrder } from 'src/engine/api/utils/get-effective-scan-order.utils';
+// Derives ORDER BY from the same scan-order primitive the keyset cursor
+// conditions use, so the SQL scan and the WHERE continuation cannot disagree
export const convertOrderByToFindOptionsOrder = (
direction: OrderByDirection,
isForwardPagination = true,
): OrderByClause => {
- switch (direction) {
- case OrderByDirection.AscNullsFirst:
- return {
- order: isForwardPagination ? 'ASC' : 'DESC',
- nulls: 'NULLS FIRST',
- };
- case OrderByDirection.AscNullsLast:
- return {
- order: isForwardPagination ? 'ASC' : 'DESC',
- nulls: 'NULLS LAST',
- };
- case OrderByDirection.DescNullsFirst:
- return {
- order: isForwardPagination ? 'DESC' : 'ASC',
- nulls: 'NULLS FIRST',
- };
- case OrderByDirection.DescNullsLast:
- return {
- order: isForwardPagination ? 'DESC' : 'ASC',
- nulls: 'NULLS LAST',
- };
- default:
- throw new GraphqlQueryRunnerException(
- `Invalid direction: ${direction}`,
- GraphqlQueryRunnerExceptionCode.INVALID_DIRECTION,
- { userFriendlyMessage: STANDARD_ERROR_MESSAGE },
- );
+ if (!isOrderByDirection(direction)) {
+ throw new GraphqlQueryRunnerException(
+ `Invalid direction: ${direction}`,
+ GraphqlQueryRunnerExceptionCode.INVALID_DIRECTION,
+ { userFriendlyMessage: STANDARD_ERROR_MESSAGE },
+ );
}
+
+ const { isAscending, areNullsScannedLast } = getEffectiveScanOrder(
+ direction,
+ isForwardPagination,
+ );
+
+ return {
+ order: isAscending ? 'ASC' : 'DESC',
+ nulls: areNullsScannedLast ? 'NULLS LAST' : 'NULLS FIRST',
+ };
};
diff --git a/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/graphql-query.parser.ts b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/graphql-query.parser.ts
index 23fe9c13d78..ed08003862d 100644
--- a/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/graphql-query.parser.ts
+++ b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/graphql-query.parser.ts
@@ -129,6 +129,7 @@ export class GraphqlQueryParser {
orderBy as ObjectRecordOrderBy,
objectNameSingular,
isForwardPagination,
+ queryBuilder.objectRecordsPermissions,
);
for (const joinInfo of parseResult.relationJoins) {
diff --git a/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/utils/assert-field-is-readable-or-throw.util.ts b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/utils/assert-field-is-readable-or-throw.util.ts
new file mode 100644
index 00000000000..565812a674b
--- /dev/null
+++ b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/utils/assert-field-is-readable-or-throw.util.ts
@@ -0,0 +1,29 @@
+import { type ObjectsPermissions } from 'twenty-shared/types';
+
+import {
+ PermissionsException,
+ PermissionsExceptionCode,
+ PermissionsExceptionMessage,
+} from 'src/engine/metadata-modules/permissions/permissions.exception';
+
+// Filtering or ordering by a non-readable field would leak its values (orderBy
+// additionally embeds them into pagination cursors)
+export const assertFieldIsReadableOrThrow = ({
+ objectsPermissions,
+ objectMetadataId,
+ fieldMetadataId,
+}: {
+ objectsPermissions: ObjectsPermissions | undefined;
+ objectMetadataId: string;
+ fieldMetadataId: string;
+}): void => {
+ if (
+ objectsPermissions?.[objectMetadataId]?.restrictedFields[fieldMetadataId]
+ ?.canRead === false
+ ) {
+ throw new PermissionsException(
+ PermissionsExceptionMessage.PERMISSION_DENIED,
+ PermissionsExceptionCode.PERMISSION_DENIED,
+ );
+ }
+};
diff --git a/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/utils/__tests__/build-order-by-columns-to-select.spec.ts b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/utils/__tests__/build-order-by-columns-to-select.spec.ts
new file mode 100644
index 00000000000..df03356b74c
--- /dev/null
+++ b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/utils/__tests__/build-order-by-columns-to-select.spec.ts
@@ -0,0 +1,157 @@
+import {
+ FieldMetadataType,
+ OrderByDirection,
+ RelationType,
+} from 'twenty-shared/types';
+
+import { buildOrderByColumnsToSelect } from 'src/engine/api/graphql/graphql-query-runner/utils/build-order-by-columns-to-select';
+import { type FlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/types/flat-entity-maps.type';
+import { type FlatFieldMetadata } from 'src/engine/metadata-modules/flat-field-metadata/types/flat-field-metadata.type';
+import { type FlatObjectMetadata } from 'src/engine/metadata-modules/flat-object-metadata/types/flat-object-metadata.type';
+
+const buildMockField = (
+ id: string,
+ name: string,
+ type: FieldMetadataType,
+ overrides: Partial<FlatFieldMetadata> = {},
+): FlatFieldMetadata =>
+ ({
+ id,
+ universalIdentifier: id,
+ name,
+ type,
+ objectMetadataId: 'obj-id',
+ workspaceId: 'ws-id',
+ label: name,
+ isNullable: true,
+ ...overrides,
+ }) as unknown as FlatFieldMetadata;
+
+const closeDateField = buildMockField(
+ 'closedate-id',
+ 'closeDate',
+ FieldMetadataType.DATE_TIME,
+);
+const fullNameField = buildMockField(
+ 'fullname-id',
+ 'name',
+ FieldMetadataType.FULL_NAME,
+);
+const companyField = buildMockField(
+ 'company-id',
+ 'company',
+ FieldMetadataType.RELATION,
+ { settings: { relationType: RelationType.MANY_TO_ONE } },
+);
+const ownerField = buildMockField(
+ 'owner-id',
+ 'owner',
+ FieldMetadataType.MORPH_RELATION,
+ { settings: { relationType: RelationType.MANY_TO_ONE } },
+);
+
+const flatFieldMetadataMaps: FlatEntityMaps<FlatFieldMetadata> = {
+ byUniversalIdentifier: {
+ 'closedate-id': closeDateField,
+ 'fullname-id': fullNameField,
+ 'company-id': companyField,
+ 'owner-id': ownerField,
+ },
+ universalIdentifierById: {
+ 'closedate-id': 'closedate-id',
+ 'fullname-id': 'fullname-id',
+ 'company-id': 'company-id',
+ 'owner-id': 'owner-id',
+ },
+ universalIdentifiersByApplicationId: {},
+};
+
+const flatObjectMetadata = {
+ id: 'obj-id',
+ universalIdentifier: 'obj-id',
+ nameSingular: 'opportunity',
+ fieldIds: ['closedate-id', 'fullname-id', 'company-id', 'owner-id'],
+} as unknown as FlatObjectMetadata;
+
+describe('buildOrderByColumnsToSelect', () => {
+ it('should select the column of a scalar orderBy field', () => {
+ const result = buildOrderByColumnsToSelect({
+ orderBy: [{ closeDate: OrderByDirection.AscNullsLast }],
+ flatObjectMetadata,
+ flatFieldMetadataMaps,
+ });
+
+ expect(result).toEqual({ closeDate: true });
+ });
+
+ it('should expand composite orderBy fields to their flat sub-field columns', () => {
+ const result = buildOrderByColumnsToSelect({
+ orderBy: [
+ {
+ name: {
+ firstName: OrderByDirection.AscNullsLast,
+ lastName: OrderByDirection.DescNullsLast,
+ },
+ },
+ ],
+ flatObjectMetadata,
+ flatFieldMetadataMaps,
+ });
+
+ expect(result).toEqual({ nameFirstName: true, nameLastName: true });
+ });
+
+ it('should skip relation orderBy fields accessed by relation name', () => {
+ const result = buildOrderByColumnsToSelect({
+ orderBy: [
+ { company: { name: OrderByDirection.AscNullsLast } },
+ { closeDate: OrderByDirection.AscNullsLast },
+ ],
+ flatObjectMetadata,
+ flatFieldMetadataMaps,
+ });
+
+ expect(result).toEqual({ closeDate: true });
+ });
+
+ it('should skip morph relation orderBy fields like relation ones', () => {
+ const result = buildOrderByColumnsToSelect({
+ orderBy: [
+ { owner: { name: OrderByDirection.AscNullsLast } },
+ { closeDate: OrderByDirection.AscNullsLast },
+ ],
+ flatObjectMetadata,
+ flatFieldMetadataMaps,
+ });
+
+ expect(result).toEqual({ closeDate: true });
+ });
+
+ it('should select the join column when ordering by the foreign key', () => {
+ const result = buildOrderByColumnsToSelect({
+ orderBy: [{ companyId: OrderByDirection.AscNullsLast }],
+ flatObjectMetadata,
+ flatFieldMetadataMaps,
+ });
+
+ expect(result).toEqual({ companyId: true });
+ });
+
+ it('should skip unknown fields and handle undefined orderBy', () => {
+ expect(
+ buildOrderByColumnsToSelect({
+ orderBy: [{ unknownField: OrderByDirection.AscNullsLast }],
+ flatObjectMetadata,
+ flatFieldMetadataMaps,
+ }),
+ ).toEqual({});
+
+ expect(
+ buildOrderByColumnsToSelect({
+ orderBy: undefined,
+ flatObjectMetadata,
+ flatFieldMetadataMaps,
+ }),
+ ).toEqual({});
+ });
+});
diff --git a/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/utils/__tests__/cursors.util.spec.ts b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/utils/__tests__/cursors.util.spec.ts
index 28f18e72648..a2a5b6ee319 100644
--- a/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/utils/__tests__/cursors.util.spec.ts
+++ b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/utils/__tests__/cursors.util.spec.ts
@@ -1,4 +1,8 @@
-import { FieldMetadataType, OrderByDirection } from 'twenty-shared/types';
+import {
+ FieldMetadataType,
+ OrderByDirection,
+ RelationType,
+} from 'twenty-shared/types';
import { type ObjectRecordOrderBy } from 'src/engine/api/graphql/workspace-query-builder/interfaces/object-record.interface';
@@ -11,12 +15,14 @@ const buildMockField = (
id: string,
name: string,
type: FieldMetadataType,
+ overrides: Partial<FlatFieldMetadata> = {},
): FlatFieldMetadata =>
({
id,
universalIdentifier: id,
name,
type,
+ ...overrides,
objectMetadataId: 'obj-id',
workspaceId: 'ws-id',
label: name,
@@ -37,15 +43,23 @@ const fullNameField = buildMockField(
'fullName',
FieldMetadataType.FULL_NAME,
);
+const companyField = buildMockField(
+ 'company-id',
+ 'company',
+ FieldMetadataType.RELATION,
+ { settings: { relationType: RelationType.MANY_TO_ONE } },
+);
const flatFieldMetadataMaps: FlatEntityMaps<FlatFieldMetadata> = {
byUniversalIdentifier: {
'name-id': nameField,
'fullname-id': fullNameField,
+ 'company-id': companyField,
},
universalIdentifierById: {
'name-id': 'name-id',
'fullname-id': 'fullname-id',
+ 'company-id': 'company-id',
},
universalIdentifiersByApplicationId: {},
};
@@ -67,7 +81,7 @@ const flatObjectMetadata: FlatObjectMetadata = {
icon: 'Icon123',
createdAt: new Date(),
updatedAt: new Date(),
- fieldIds: ['name-id', 'fullname-id'],
+ fieldIds: ['name-id', 'fullname-id', 'company-id'],
indexMetadataIds: [],
viewIds: [],
applicationId: null,
@@ -170,6 +184,38 @@ describe('encodeCursor', () => {
expect(decoded).toEqual({ name: 'John', id: 'abc' });
});
+ it('should preserve null sort values in the cursor', () => {
+ const record = { id: 'abc', name: null };
+ const orderBy = [{ name: OrderByDirection.AscNullsLast }];
+
+ const decoded = decodeCursor(callEncodeCursor(record, orderBy));
+
+ expect(decoded).toEqual({ name: null, id: 'abc' });
+ });
+
+ it('should not embed related records for relation orderBy entries', () => {
+ const record = {
+ id: 'abc',
+ company: { id: 'company-1', name: 'Acme' },
+ };
+ const orderBy = [
+ { company: { name: OrderByDirection.AscNullsLast } },
+ ] as Parameters<typeof encodeCursor>[0]['order'];
+
+ const decoded = decodeCursor(callEncodeCursor(record, orderBy));
+
+ expect(decoded).toEqual({ id: 'abc' });
+ });
+
+ it('should encode join column values when ordering by the foreign key', () => {
+ const record = { id: 'abc', companyId: 'company-1' };
+ const orderBy = [{ companyId: OrderByDirection.AscNullsLast }];
+
+ const decoded = decodeCursor(callEncodeCursor(record, orderBy));
+
+ expect(decoded).toEqual({ companyId: 'company-1', id: 'abc' });
+ });
+
it('should handle undefined orderBy', () => {
const record = { id: 'abc', name: 'John' };
diff --git a/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/utils/build-order-by-columns-to-select.ts b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/utils/build-order-by-columns-to-select.ts
new file mode 100644
index 00000000000..f6f0fc8a363
--- /dev/null
+++ b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/utils/build-order-by-columns-to-select.ts
@@ -0,0 +1,40 @@
+import { type ObjectRecordOrderBy } from 'src/engine/api/graphql/workspace-query-builder/interfaces/object-record.interface';
+
+import {
+ checkIfLeafCanCarryCursorValue,
+ resolveOrderByLeaves,
+} from 'src/engine/api/utils/resolve-order-by-leaves.utils';
+import { computeCompositeColumnName } from 'src/engine/metadata-modules/field-metadata/utils/compute-column-name.util';
+import { type FlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/types/flat-entity-maps.type';
+import { type FlatFieldMetadata } from 'src/engine/metadata-modules/flat-field-metadata/types/flat-field-metadata.type';
+import { type FlatObjectMetadata } from 'src/engine/metadata-modules/flat-object-metadata/types/flat-object-metadata.type';
+
+// Cursor encoding reads orderBy values from the hydrated record, so every column the
+// query is ordered by must be selected even when the client did not request it.
+// Otherwise the cursor silently degrades to an id-only cursor and pagination skips
+// records (see issue #24333).
+export const buildOrderByColumnsToSelect = ({
+ orderBy,
+ flatObjectMetadata,
+ flatFieldMetadataMaps,
+}: {
+ orderBy: ObjectRecordOrderBy | undefined;
+ flatObjectMetadata: FlatObjectMetadata;
+ flatFieldMetadataMaps: FlatEntityMaps<FlatFieldMetadata>;
+}): Record<string, boolean> => {
+ const columnsToSelect: Record<string, boolean> = {};
+
+ for (const leaf of resolveOrderByLeaves({
+ orderBy,
+ flatObjectMetadata,
+ flatFieldMetadataMaps,
+ }).filter(checkIfLeafCanCarryCursorValue)) {
+ columnsToSelect[
+ leaf.kind === 'composite'
+ ? computeCompositeColumnName(leaf.path[0], leaf.compositeProperty)
+ : leaf.path[0]
+ ] = true;
+ }
+
+ return columnsToSelect;
+};
diff --git a/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/utils/cursors.util.ts b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/utils/cursors.util.ts
index f6f734f336e..a85500d1cdf 100644
--- a/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/utils/cursors.util.ts
+++ b/packages/twenty-server/src/engine/api/graphql/graphql-query-runner/utils/cursors.util.ts
@@ -1,5 +1,5 @@
import { type ObjectRecord } from 'twenty-shared/types';
-import { isDefined, isPlainObject } from 'twenty-shared/utils';
+import { isPlainObject } from 'twenty-shared/utils';
import { type ObjectRecordOrderBy } from 'src/engine/api/graphql/workspace-query-builder/interfaces/object-record.interface';
import { type FindManyResolverArgs } from 'src/engine/api/graphql/workspace-resolver-builder/interfaces/workspace-resolvers-builder.interface';
@@ -9,11 +9,12 @@ import {
CommonQueryRunnerExceptionCode,
} from 'src/engine/api/common/common-query-runners/errors/common-query-runner.exception';
import { STANDARD_ERROR_MESSAGE } from 'src/engine/api/common/common-query-runners/errors/standard-error-message.constant';
-import { isCompositeFieldMetadataType } from 'src/engine/metadata-modules/field-metadata/utils/is-composite-field-metadata-type.util';
+import {
+ checkIfLeafCanCarryCursorValue,
+ resolveOrderByLeaves,
+} from 'src/engine/api/utils/resolve-order-by-leaves.utils';
import { type FlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/types/flat-entity-maps.type';
-import { findFlatEntityByIdInFlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/utils/find-flat-entity-by-id-in-flat-entity-maps.util';
import { type FlatFieldMetadata } from 'src/engine/metadata-modules/flat-field-metadata/types/flat-field-metadata.type';
-import { buildFieldMapsFromFlatObjectMetadata } from 'src/engine/metadata-modules/flat-field-metadata/utils/build-field-maps-from-flat-object-metadata.util';
import { type FlatObjectMetadata } from 'src/engine/metadata-modules/flat-object-metadata/types/flat-object-metadata.type';
export interface CursorData {
@@ -44,50 +45,31 @@ export const encodeCursor = <T extends ObjectRecord = ObjectRecord>({
flatObjectMetadata: FlatObjectMetadata;
flatFieldMetadataMaps: FlatEntityMaps<FlatFieldMetadata>;
}): string => {
- const { fieldIdByName } = buildFieldMapsFromFlatObjectMetadata(
- flatFieldMetadataMaps,
- flatObjectMetadata,
- );
-
// oxlint-disable-next-line typescript/no-explicit-any
const orderByValues: Record<string, any> = {};
- for (const orderByEntry of order ?? []) {
- for (const [key, value] of Object.entries(orderByEntry)) {
- const fieldMetadataId = fieldIdByName[key];
- const fieldMetadata = findFlatEntityByIdInFlatEntityMaps({
- flatEntityMaps: flatFieldMetadataMaps,
- flatEntityId: fieldMetadataId,
- });
-
- if (!isDefined(fieldMetadata)) {
- continue;
- }
-
- if (
- isCompositeFieldMetadataType(fieldMetadata.type) &&
- isPlainObject(value) &&
- isDefined(value)
- ) {
- const compositeOrderByKeys = Object.keys(
- value as Record<string, unknown>,
- );
- const existingCompositeValue: Record<string, unknown> =
- orderByValues[key] ?? {};
- const recordCompositeValue = objectRecord[key] as
- | Record<string, unknown>
- | null
- | undefined;
+ for (const leaf of resolveOrderByLeaves({
+ orderBy: order,
+ flatObjectMetadata,
+ flatFieldMetadataMaps,
+ }).filter(checkIfLeafCanCarryCursorValue)) {
+ // Read the ordered value along the leaf's path (a null or missing
+ // container makes the value undefined, which JSON serialization drops)
+ const [rootKey, ...nestedKeys] = leaf.path;
+ let leafValue: unknown = objectRecord[rootKey];
+
+ for (const key of nestedKeys) {
+ leafValue = isPlainObject(leafValue) ? leafValue[key] : undefined;
+ }
- for (const subKey of compositeOrderByKeys) {
- existingCompositeValue[subKey] = recordCompositeValue?.[subKey];
- }
+ // Write it back under the same path
+ let container = orderByValues;
- orderByValues[key] = existingCompositeValue;
- } else {
- orderByValues[key] = objectRecord[key];
- }
+ for (const key of leaf.path.slice(0, -1)) {
+ container[key] = isPlainObject(container[key]) ? container[key] : {};
+ container = container[key];
}
+ container[leaf.path[leaf.path.length - 1]] = leafValue;
}
const cursorData: CursorData = {
diff --git a/packages/twenty-server/src/engine/api/graphql/workspace-query-builder/interfaces/object-record.interface.ts b/packages/twenty-server/src/engine/api/graphql/workspace-query-builder/interfaces/object-record.interface.ts
index e22b41819ff..d81dd735a58 100644
--- a/packages/twenty-server/src/engine/api/graphql/workspace-query-builder/interfaces/object-record.interface.ts
+++ b/packages/twenty-server/src/engine/api/graphql/workspace-query-builder/interfaces/object-record.interface.ts
@@ -37,7 +37,11 @@ export type ObjectRecordOrderBy = Array<
ObjectRecordOrderByForScalarField | ObjectRecordOrderByForCompositeField
>;
-export type ObjectRecordCursorLeafScalarValue = string | number | boolean;
+export type ObjectRecordCursorLeafScalarValue =
+ | string
+ | number
+ | boolean
+ | null;
export type ObjectRecordCursorLeafCompositeValue = Record<
string,
ObjectRecordCursorLeafScalarValue
diff --git a/packages/twenty-server/src/engine/api/utils/__tests__/__snapshots__/build-cursor-composite-field-where-condition.utils.spec.ts.snap b/packages/twenty-server/src/engine/api/utils/__tests__/__snapshots__/build-cursor-composite-field-where-condition.utils.spec.ts.snap
deleted file mode 100644
index 706417ed43b..00000000000
--- a/packages/twenty-server/src/engine/api/utils/__tests__/__snapshots__/build-cursor-composite-field-where-condition.utils.spec.ts.snap
+++ /dev/null
@@ -1,343 +0,0 @@
-// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
-
-exports[`buildCompositeFieldWhereCondition multiple properties cases should match snapshots for address composite field - both ascending, forward pagination: multiple properties - address composite field - both ascending, forward pagination 1`] = `
-{
- "or": [
- {
- "address": {
- "addressStreet1": {
- "gt": "123 Main St",
- },
- },
- },
- {
- "and": [
- {
- "address": {
- "addressStreet1": {
- "eq": "123 Main St",
- },
- },
- },
- {
- "address": {
- "addressStreet2": {
- "gt": "Apt 4B",
- },
- },
- },
- ],
- },
- {
- "and": [
- {
- "address": {
- "addressStreet1": {
- "eq": "123 Main St",
- },
- },
- },
- {
- "address": {
- "addressStreet2": {
- "eq": "Apt 4B",
- },
- },
- },
- {
- "address": {
- "addressCity": {
- "gt": "New York",
- },
- },
- },
- ],
- },
- {
- "and": [
- {
- "address": {
- "addressStreet1": {
- "eq": "123 Main St",
- },
- },
- },
- {
- "address": {
- "addressStreet2": {
- "eq": "Apt 4B",
- },
- },
- },
- {
- "address": {
- "addressCity": {
- "eq": "New York",
- },
- },
- },
- {
- "address": {
- "addressPostcode": {
- "gt": "10001",
- },
- },
- },
- ],
- },
- {
- "and": [
- {
- "address": {
- "addressStreet1": {
- "eq": "123 Main St",
- },
- },
- },
- {
- "address": {
- "addressStreet2": {
- "eq": "Apt 4B",
- },
- },
- },
- {
- "address": {
- "addressCity": {
- "eq": "New York",
- },
- },
- },
- {
- "address": {
- "addressPostcode": {
- "eq": "10001",
- },
- },
- },
- {
- "address": {
- "addressState": {
- "gt": "NY",
- },
- },
- },
- ],
- },
- {
- "and": [
- {
- "address": {
- "addressStreet1": {
- "eq": "123 Main St",
- },
- },
- },
- {
- "address": {
- "addressStreet2": {
- "eq": "Apt 4B",
- },
- },
- },
- {
- "address": {
- "addressCity": {
- "eq": "New York",
- },
- },
- },
- {
- "address": {
- "addressPostcode": {
- "eq": "10001",
- },
- },
- },
- {
- "address": {
- "addressState": {
- "eq": "NY",
- },
- },
- },
- {
- "address": {
- "addressCountry": {
- "gt": "USA",
- },
- },
- },
- ],
- },
- ],
-}
-`;
-
-exports[`buildCompositeFieldWhereCondition multiple properties cases should match snapshots for two properties - both ascending, backward pagination: multiple properties - two properties - both ascending, backward pagination 1`] = `
-{
- "or": [
- {
- "name": {
- "firstName": {
- "lt": "John",
- },
- },
- },
- {
- "and": [
- {
- "name": {
- "firstName": {
- "eq": "John",
- },
- },
- },
- {
- "name": {
- "lastName": {
- "lt": "Doe",
- },
- },
- },
- ],
- },
- ],
-}
-`;
-
-exports[`buildCompositeFieldWhereCondition multiple properties cases should match snapshots for two properties - both ascending, forward pagination: multiple properties - two properties - both ascending, forward pagination 1`] = `
-{
- "or": [
- {
- "name": {
- "firstName": {
- "gt": "John",
- },
- },
- },
- {
- "and": [
- {
- "name": {
- "firstName": {
- "eq": "John",
- },
- },
- },
- {
- "name": {
- "lastName": {
- "gt": "Doe",
- },
- },
- },
- ],
- },
- ],
-}
-`;
-
-exports[`buildCompositeFieldWhereCondition multiple properties cases should match snapshots for two properties - both descending, forward pagination: multiple properties - two properties - both descending, forward pagination 1`] = `
-{
- "or": [
- {
- "name": {
- "firstName": {
- "lt": "John",
- },
- },
- },
- {
- "and": [
- {
- "name": {
- "firstName": {
- "eq": "John",
- },
- },
- },
- {
- "name": {
- "lastName": {
- "lt": "Doe",
- },
- },
- },
- ],
- },
- ],
-}
-`;
-
-exports[`buildCompositeFieldWhereCondition multiple properties cases should match snapshots for two properties - mixed ordering, forward pagination: multiple properties - two properties - mixed ordering, forward pagination 1`] = `
-{
- "or": [
- {
- "name": {
- "firstName": {
- "gt": "John",
- },
- },
- },
- {
- "and": [
- {
- "name": {
- "firstName": {
- "eq": "John",
- },
- },
- },
- {
- "name": {
- "lastName": {
- "lt": "Doe",
- },
- },
- },
- ],
- },
- ],
-}
-`;
-
-exports[`buildCompositeFieldWhereCondition single property cases should match snapshot for ascending order with backward pagination: single property - ascending order with backward pagination 1`] = `
-{
- "person": {
- "firstName": {
- "lt": "John",
- },
- },
-}
-`;
-
-exports[`buildCompositeFieldWhereCondition single property cases should match snapshot for ascending order with forward pagination: single property - ascending order with forward pagination 1`] = `
-{
- "person": {
- "firstName": {
- "gt": "John",
- },
- },
-}
-`;
-
-exports[`buildCompositeFieldWhereCondition single property cases should match snapshot for descending order with backward pagination: single property - descending order with backward pagination 1`] = `
-{
- "person": {
- "firstName": {
- "gt": "John",
- },
- },
-}
-`;
-
-exports[`buildCompositeFieldWhereCondition single property cases should match snapshot for descending order with forward pagination: single property - descending order with forward pagination 1`] = `
-{
- "person": {
- "firstName": {
- "lt": "John",
- },
- },
-}
-`;
diff --git a/packages/twenty-server/src/engine/api/utils/__tests__/build-cursor-composite-field-where-condition.utils.spec.ts b/packages/twenty-server/src/engine/api/utils/__tests__/build-cursor-composite-field-where-condition.utils.spec.ts
deleted file mode 100644
index 2c499c0214d..00000000000
--- a/packages/twenty-server/src/engine/api/utils/__tests__/build-cursor-composite-field-where-condition.utils.spec.ts
+++ /dev/null
@@ -1,355 +0,0 @@
-import { type EachTestingContext } from 'twenty-shared/testing';
-import { FieldMetadataType, OrderByDirection } from 'twenty-shared/types';
-
-import { type ObjectRecordOrderBy } from 'src/engine/api/graphql/workspace-query-builder/interfaces/object-record.interface';
-
-import { buildCursorCompositeFieldWhereCondition } from 'src/engine/api/utils/build-cursor-composite-field-where-condition.utils';
-
-describe('buildCompositeFieldWhereCondition', () => {
- describe('eq operator cases', () => {
- it('should handle eq operator', () => {
- const result = buildCursorCompositeFieldWhereCondition({
- fieldType: FieldMetadataType.FULL_NAME,
- fieldKey: 'name',
- orderBy: [
- {
- name: {
- firstName: OrderByDirection.AscNullsLast,
- lastName: OrderByDirection.AscNullsLast,
- },
- },
- ],
- cursorValue: { firstName: 'John', lastName: 'Doe' },
- isForwardPagination: true,
- isEqualityCondition: true,
- });
-
- expect(result).toEqual({
- name: {
- firstName: {
- eq: 'John',
- },
- lastName: {
- eq: 'Doe',
- },
- },
- });
- });
- });
-
- describe('single property cases', () => {
- const singlePropertyTestCases: EachTestingContext<{
- description: string;
- fieldType: FieldMetadataType;
- fieldKey: string;
- orderBy: ObjectRecordOrderBy;
- value: { [key: string]: any };
- isForwardPagination: boolean;
- operator?: string;
- expectedOperator: string;
- }>[] = [
- {
- title: 'ascending order with forward pagination',
- context: {
- description: 'ascending order with forward pagination',
- fieldType: FieldMetadataType.FULL_NAME,
- fieldKey: 'person',
- orderBy: [{ person: { firstName: OrderByDirection.AscNullsLast } }],
- value: { firstName: 'John' },
- isForwardPagination: true,
- operator: undefined,
- expectedOperator: 'gt',
- },
- },
- {
- title: 'ascending order with backward pagination',
- context: {
- description: 'ascending order with backward pagination',
- fieldType: FieldMetadataType.FULL_NAME,
- fieldKey: 'person',
- orderBy: [{ person: { firstName: OrderByDirection.AscNullsLast } }],
- value: { firstName: 'John' },
- isForwardPagination: false,
- operator: undefined,
- expectedOperator: 'lt',
- },
- },
- {
- title: 'descending order with forward pagination',
- context: {
- description: 'descending order with forward pagination',
- fieldType: FieldMetadataType.FULL_NAME,
- fieldKey: 'person',
- orderBy: [{ person: { firstName: OrderByDirection.DescNullsLast } }],
- value: { firstName: 'John' },
- isForwardPagination: true,
- operator: undefined,
- expectedOperator: 'lt',
- },
- },
- {
- title: 'descending order with backward pagination',
- context: {
- description: 'descending order with backward pagination',
- fieldType: FieldMetadataType.FULL_NAME,
- fieldKey: 'person',
- orderBy: [{ person: { firstName: OrderByDirection.DescNullsLast } }],
- value: { firstName: 'John' },
- isForwardPagination: false,
- operator: undefined,
- expectedOperator: 'gt',
- },
- },
- ];
-
- test.each(singlePropertyTestCases)(
- 'should handle $description',
- ({ context }) => {
- const {
- fieldType,
- fieldKey,
- orderBy,
- value,
- isForwardPagination,
- expectedOperator,
- } = context;
-
- const result = buildCursorCompositeFieldWhereCondition({
- fieldType,
- fieldKey,
- orderBy,
- cursorValue: value,
- isForwardPagination,
- });
-
- expect(result).toEqual({
- [fieldKey]: {
- firstName: {
- [expectedOperator]: value.firstName,
- },
- },
- });
- },
- );
-
- test.each(singlePropertyTestCases)(
- 'should match snapshot for $title',
- ({ context }) => {
- const {
- fieldType,
- fieldKey,
- orderBy,
- value,
- isForwardPagination,
- description,
- } = context;
-
- const result = buildCursorCompositeFieldWhereCondition({
- fieldType,
- fieldKey,
- orderBy,
- cursorValue: value,
- isForwardPagination,
- });
-
- expect(result).toMatchSnapshot(`single property - ${description}`);
- },
- );
- });
-
- describe('multiple properties cases', () => {
- const multiplePropertiesTestCases: EachTestingContext<{
- description: string;
- fieldType: FieldMetadataType;
- fieldKey: string;
- orderBy: ObjectRecordOrderBy;
- value: { [key: string]: any };
- isForwardPagination: boolean;
- }>[] = [
- {
- title: 'two properties - both ascending, forward pagination',
- context: {
- description: 'two properties - both ascending, forward pagination',
- fieldType: FieldMetadataType.FULL_NAME,
- fieldKey: 'name',
- orderBy: [
- {
- name: {
- firstName: OrderByDirection.AscNullsLast,
- lastName: OrderByDirection.AscNullsLast,
- },
- },
- ],
- value: { firstName: 'John', lastName: 'Doe' },
- isForwardPagination: true,
- },
- },
- {
- title: 'two properties - both ascending, backward pagination',
- context: {
- description: 'two properties - both ascending, backward pagination',
- fieldType: FieldMetadataType.FULL_NAME,
- fieldKey: 'name',
- orderBy: [
- {
- name: {
- firstName: OrderByDirection.AscNullsLast,
- lastName: OrderByDirection.AscNullsLast,
- },
- },
- ],
- value: { firstName: 'John', lastName: 'Doe' },
- isForwardPagination: false,
- },
- },
- {
- title: 'two properties - mixed ordering, forward pagination',
- context: {
- description: 'two properties - mixed ordering, forward pagination',
- fieldType: FieldMetadataType.FULL_NAME,
- fieldKey: 'name',
- orderBy: [
- {
- name: {
- firstName: OrderByDirection.AscNullsLast,
- lastName: OrderByDirection.DescNullsLast,
- },
- },
- ],
- value: { firstName: 'John', lastName: 'Doe' },
- isForwardPagination: true,
- },
- },
- {
- title: 'two properties - both descending, forward pagination',
- context: {
- description: 'two properties - both descending, forward pagination',
- fieldType: FieldMetadataType.FULL_NAME,
- fieldKey: 'name',
- orderBy: [
- {
- name: {
- firstName: OrderByDirection.DescNullsLast,
- lastName: OrderByDirection.DescNullsLast,
- },
- },
- ],
- value: { firstName: 'John', lastName: 'Doe' },
- isForwardPagination: true,
- },
- },
- {
- title: 'address composite field - both ascending, forward pagination',
- context: {
- description:
- 'address composite field - both ascending, forward pagination',
- fieldType: FieldMetadataType.ADDRESS,
- fieldKey: 'address',
- orderBy: [
- {
- address: {
- addressStreet1: OrderByDirection.AscNullsLast,
- addressStreet2: OrderByDirection.AscNullsLast,
- addressCity: OrderByDirection.AscNullsLast,
- addressState: OrderByDirection.AscNullsLast,
- addressCountry: OrderByDirection.AscNullsLast,
- addressPostcode: OrderByDirection.AscNullsLast,
- },
- },
- ],
- value: {
- addressStreet1: '123 Main St',
- addressStreet2: 'Apt 4B',
- addressCity: 'New York',
- addressState: 'NY',
- addressCountry: 'USA',
- addressPostcode: '10001',
- },
- isForwardPagination: true,
- },
- },
- ];
-
- test.each(multiplePropertiesTestCases)(
- 'should handle $title',
- ({ context }) => {
- const { fieldType, fieldKey, orderBy, value, isForwardPagination } =
- context;
- const result = buildCursorCompositeFieldWhereCondition({
- fieldType,
- fieldKey,
- orderBy,
- cursorValue: value,
- isForwardPagination,
- });
-
- expect(result).toHaveProperty('or');
- const orConditions = result.or;
-
- expect(Array.isArray(orConditions)).toBe(true);
-
- const propertiesWithValues = Object.keys(value).length;
-
- expect(orConditions).toHaveLength(propertiesWithValues);
-
- expect(orConditions[0]).toHaveProperty(fieldKey);
-
- for (const [index, orCondition] of orConditions.slice(1).entries()) {
- expect(orCondition).toHaveProperty('and');
- expect(Array.isArray(orCondition.and)).toBe(true);
- expect(orCondition.and).toHaveLength(index + 2);
- }
- },
- );
-
- test.each(multiplePropertiesTestCases)(
- 'should match snapshots for $title',
- ({ context }) => {
- const {
- fieldType,
- fieldKey,
- orderBy,
- value,
- isForwardPagination,
- description,
- } = context;
-
- const result = buildCursorCompositeFieldWhereCondition({
- fieldType,
- fieldKey,
- orderBy,
- cursorValue: value,
- isForwardPagination,
- });
-
- expect(result).toMatchSnapshot(`multiple properties - ${description}`);
- },
- );
- });
-
- describe('error cases', () => {
- it('should throw error for invalid composite type', () => {
- expect(() =>
- buildCursorCompositeFieldWhereCondition({
- fieldType: FieldMetadataType.TEXT,
- fieldKey: 'person',
- orderBy: [{ person: { firstName: OrderByDirection.AscNullsLast } }],
- cursorValue: { firstName: 'John' },
- isForwardPagination: true,
- }),
- ).toThrow('Composite type definition not found for type: TEXT');
- });
-
- it('should throw error for invalid cursor with missing order by', () => {
- expect(() =>
- buildCursorCompositeFieldWhereCondition({
- fieldType: FieldMetadataType.FULL_NAME,
- fieldKey: 'person',
- orderBy: [],
- cursorValue: { firstName: 'John' },
- isForwardPagination: true,
- }),
- ).toThrow('Invalid cursor');
- });
- });
-});
diff --git a/packages/twenty-server/src/engine/api/utils/__tests__/compute-cursor-arg-filter.utils.spec.ts b/packages/twenty-server/src/engine/api/utils/__tests__/compute-cursor-arg-filter.utils.spec.ts
index 27f48881535..1fbae5aa757 100644
--- a/packages/twenty-server/src/engine/api/utils/__tests__/compute-cursor-arg-filter.utils.spec.ts
+++ b/packages/twenty-server/src/engine/api/utils/__tests__/compute-cursor-arg-filter.utils.spec.ts
@@ -55,6 +55,22 @@ describe('computeCursorArgFilter', () => {
label: 'Full Name',
});
+ const idField = createMockField({
+ id: 'id-id',
+ type: FieldMetadataType.UUID,
+ name: 'id',
+ label: 'Id',
+ isNullable: false,
+ });
+
+ const closeDateField = createMockField({
+ id: 'closedate-id',
+ type: FieldMetadataType.DATE_TIME,
+ name: 'closeDate',
+ label: 'Close Date',
+ isNullable: true,
+ });
+
const buildFlatFieldMetadataMaps = (
fields: FlatFieldMetadata[],
): FlatEntityMaps<FlatFieldMetadata> => ({
@@ -81,6 +97,8 @@ describe('computeCursorArgFilter', () => {
nameField,
ageField,
fullNameField,
+ idField,
+ closeDateField,
]);
const flatObjectMetadata: FlatObjectMetadata = {
@@ -100,7 +118,7 @@ describe('computeCursorArgFilter', () => {
createdAt: new Date(),
updatedAt: new Date(),
universalIdentifier: objectMetadataId,
- fieldIds: ['name-id', 'age-id', 'fullname-id'],
+ fieldIds: ['name-id', 'age-id', 'fullname-id', 'id-id', 'closedate-id'],
indexMetadataIds: [],
viewIds: [],
applicationId: null,
@@ -108,13 +126,13 @@ describe('computeCursorArgFilter', () => {
describe('basic cursor filtering', () => {
it('should return empty array when cursor is empty', () => {
- const result = computeCursorArgFilter(
- {},
- [],
+ const result = computeCursorArgFilter({
+ cursor: {},
+ orderBy: [],
flatObjectMetadata,
flatFieldMetadataMaps,
- true,
- );
+ isForwardPagination: true,
+ });
expect(result).toEqual([]);
});
@@ -123,13 +141,13 @@ describe('computeCursorArgFilter', () => {
const cursor = { name: 'John' };
const orderBy = [{ name: OrderByDirection.AscNullsLast }];
- const result = computeCursorArgFilter(
+ const result = computeCursorArgFilter({
cursor,
orderBy,
flatObjectMetadata,
flatFieldMetadataMaps,
- true,
- );
+ isForwardPagination: true,
+ });
expect(result).toEqual([{ name: { gt: 'John' } }]);
});
@@ -138,13 +156,13 @@ describe('computeCursorArgFilter', () => {
const cursor = { name: 'John' };
const orderBy = [{ name: OrderByDirection.AscNullsLast }];
- const result = computeCursorArgFilter(
+ const result = computeCursorArgFilter({
cursor,
orderBy,
flatObjectMetadata,
flatFieldMetadataMaps,
- false,
- );
+ isForwardPagination: false,
+ });
expect(result).toEqual([{ name: { lt: 'John' } }]);
});
@@ -158,17 +176,22 @@ describe('computeCursorArgFilter', () => {
{ age: OrderByDirection.DescNullsLast },
];
- const result = computeCursorArgFilter(
+ const result = computeCursorArgFilter({
cursor,
orderBy,
flatObjectMetadata,
flatFieldMetadataMaps,
- true,
- );
+ isForwardPagination: true,
+ });
expect(result).toEqual([
{ name: { gt: 'John' } },
- { and: [{ name: { eq: 'John' } }, { age: { lt: 30 } }] },
+ {
+ and: [
+ { name: { eq: 'John' } },
+ { or: [{ age: { lt: 30 } }, { age: { is: 'NULL' } }] },
+ ],
+ },
]);
});
});
@@ -187,35 +210,31 @@ describe('computeCursorArgFilter', () => {
},
];
- const result = computeCursorArgFilter(
+ const result = computeCursorArgFilter({
cursor,
orderBy,
flatObjectMetadata,
flatFieldMetadataMaps,
- true,
- );
+ isForwardPagination: true,
+ });
expect(result).toEqual([
{
- or: [
+ fullName: {
+ firstName: { gt: 'John' },
+ },
+ },
+ {
+ and: [
{
fullName: {
- firstName: { gt: 'John' },
+ firstName: { eq: 'John' },
},
},
{
- and: [
- {
- fullName: {
- firstName: { eq: 'John' },
- },
- },
- {
- fullName: {
- lastName: { gt: 'Doe' },
- },
- },
- ],
+ fullName: {
+ lastName: { gt: 'Doe' },
+ },
},
],
},
@@ -234,13 +253,13 @@ describe('computeCursorArgFilter', () => {
},
];
- const result = computeCursorArgFilter(
+ const result = computeCursorArgFilter({
cursor,
orderBy,
flatObjectMetadata,
flatFieldMetadataMaps,
- true,
- );
+ isForwardPagination: true,
+ });
expect(result).toEqual([
{
@@ -265,13 +284,13 @@ describe('computeCursorArgFilter', () => {
},
];
- const result = computeCursorArgFilter(
+ const result = computeCursorArgFilter({
cursor,
orderBy,
flatObjectMetadata,
flatFieldMetadataMaps,
- true,
- );
+ isForwardPagination: true,
+ });
expect(result).toEqual([
{
@@ -309,35 +328,31 @@ describe('computeCursorArgFilter', () => {
},
];
- const result = computeCursorArgFilter(
+ const result = computeCursorArgFilter({
cursor,
orderBy,
flatObjectMetadata,
flatFieldMetadataMaps,
- false,
- );
+ isForwardPagination: false,
+ });
expect(result).toEqual([
{
- or: [
+ fullName: {
+ firstName: { lt: 'John' },
+ },
+ },
+ {
+ and: [
{
fullName: {
- firstName: { lt: 'John' },
+ firstName: { eq: 'John' },
},
},
{
- and: [
- {
- fullName: {
- firstName: { eq: 'John' },
- },
- },
- {
- fullName: {
- lastName: { lt: 'Doe' },
- },
- },
- ],
+ fullName: {
+ lastName: { lt: 'Doe' },
+ },
},
],
},
@@ -351,13 +366,13 @@ describe('computeCursorArgFilter', () => {
const orderBy = [{ invalidField: OrderByDirection.AscNullsLast }];
expect(() =>
- computeCursorArgFilter(
+ computeCursorArgFilter({
cursor,
orderBy,
flatObjectMetadata,
flatFieldMetadataMaps,
- true,
- ),
+ isForwardPagination: true,
+ }),
).toThrow(GraphqlQueryRunnerException);
});
@@ -366,14 +381,193 @@ describe('computeCursorArgFilter', () => {
const orderBy = [{ age: OrderByDirection.AscNullsLast }];
expect(() =>
- computeCursorArgFilter(
+ computeCursorArgFilter({
cursor,
orderBy,
flatObjectMetadata,
flatFieldMetadataMaps,
- true,
- ),
+ isForwardPagination: true,
+ }),
).toThrow(GraphqlQueryRunnerException);
});
});
+
+ describe('null-aware filtering on nullable fields', () => {
+ it('should include the NULL block when nulls are scanned after the cursor', () => {
+ const cursor = { closeDate: '2026-01-01T00:00:00Z' };
+ const orderBy = [{ closeDate: OrderByDirection.AscNullsLast }];
+
+ const result = computeCursorArgFilter({
+ cursor,
+ orderBy,
+ flatObjectMetadata,
+ flatFieldMetadataMaps,
+ isForwardPagination: true,
+ });
+
+ expect(result).toEqual([
+ {
+ or: [
+ { closeDate: { gt: '2026-01-01T00:00:00Z' } },
+ { closeDate: { is: 'NULL' } },
+ ],
+ },
+ ]);
+ });
+
+ it('should not include the NULL block when nulls are scanned before the cursor', () => {
+ const cursor = { closeDate: '2026-01-01T00:00:00Z' };
+ const orderBy = [{ closeDate: OrderByDirection.AscNullsFirst }];
+
+ const result = computeCursorArgFilter({
+ cursor,
+ orderBy,
+ flatObjectMetadata,
+ flatFieldMetadataMaps,
+ isForwardPagination: true,
+ });
+
+ expect(result).toEqual([{ closeDate: { gt: '2026-01-01T00:00:00Z' } }]);
+ });
+
+ it('should continue on tie-breaking keys when the cursor sits in a trailing NULL block', () => {
+ const cursor = { closeDate: null, id: 'uuid-1' };
+ const orderBy = [
+ { closeDate: OrderByDirection.AscNullsLast },
+ { id: OrderByDirection.AscNullsFirst },
+ ];
+
+ const result = computeCursorArgFilter({
+ cursor,
+ orderBy,
+ flatObjectMetadata,
+ flatFieldMetadataMaps,
+ isForwardPagination: true,
+ });
+
+ expect(result).toEqual([
+ {
+ and: [{ closeDate: { is: 'NULL' } }, { id: { gt: 'uuid-1' } }],
+ },
+ ]);
+ });
+
+ it('should advance into the non-null region when the cursor sits in a leading NULL block', () => {
+ const cursor = { closeDate: null, id: 'uuid-1' };
+ const orderBy = [
+ { closeDate: OrderByDirection.AscNullsFirst },
+ { id: OrderByDirection.AscNullsFirst },
+ ];
+
+ const result = computeCursorArgFilter({
+ cursor,
+ orderBy,
+ flatObjectMetadata,
+ flatFieldMetadataMaps,
+ isForwardPagination: true,
+ });
+
+ expect(result).toEqual([
+ { closeDate: { is: 'NOT_NULL' } },
+ {
+ and: [{ closeDate: { is: 'NULL' } }, { id: { gt: 'uuid-1' } }],
+ },
+ ]);
+ });
+
+ it('should swap the NULL block side for backward pagination', () => {
+ const cursor = { closeDate: '2026-01-01T00:00:00Z' };
+ const orderBy = [{ closeDate: OrderByDirection.AscNullsFirst }];
+
+ const result = computeCursorArgFilter({
+ cursor,
+ orderBy,
+ flatObjectMetadata,
+ flatFieldMetadataMaps,
+ isForwardPagination: false,
+ });
+
+ expect(result).toEqual([
+ {
+ or: [
+ { closeDate: { lt: '2026-01-01T00:00:00Z' } },
+ { closeDate: { is: 'NULL' } },
+ ],
+ },
+ ]);
+ });
+
+ it('should not add a NULL block for fields with a null-equivalent default', () => {
+ const cursor = { name: 'John' };
+ const orderBy = [{ name: OrderByDirection.AscNullsLast }];
+
+ const result = computeCursorArgFilter({
+ cursor,
+ orderBy,
+ flatObjectMetadata,
+ flatFieldMetadataMaps,
+ isForwardPagination: true,
+ });
+
+ expect(result).toEqual([{ name: { gt: 'John' } }]);
+ });
+ });
+
+ describe('cursor and orderBy mismatch guard', () => {
+ it('should throw when the cursor is missing the value of an orderBy scalar field', () => {
+ const cursor = { id: 'uuid-1' };
+ const orderBy = [
+ { closeDate: OrderByDirection.AscNullsLast },
+ { id: OrderByDirection.AscNullsFirst },
+ ];
+
+ expect(() =>
+ computeCursorArgFilter({
+ cursor,
+ orderBy,
+ flatObjectMetadata,
+ flatFieldMetadataMaps,
+ isForwardPagination: true,
+ }),
+ ).toThrow('Cursor is missing the value for orderBy field "closeDate"');
+ });
+
+ it('should throw when the cursor is missing an ordered composite sub-field', () => {
+ const cursor = { id: 'uuid-1' };
+ const orderBy = [
+ { fullName: { firstName: OrderByDirection.AscNullsLast } },
+ { id: OrderByDirection.AscNullsFirst },
+ ];
+
+ expect(() =>
+ computeCursorArgFilter({
+ cursor,
+ orderBy,
+ flatObjectMetadata,
+ flatFieldMetadataMaps,
+ isForwardPagination: true,
+ }),
+ ).toThrow(
+ 'Cursor is missing the value for orderBy field "fullName.firstName"',
+ );
+ });
+
+ it('should accept a null cursor value as covering its orderBy field', () => {
+ const cursor = { closeDate: null, id: 'uuid-1' };
+ const orderBy = [
+ { closeDate: OrderByDirection.AscNullsLast },
+ { id: OrderByDirection.AscNullsFirst },
+ ];
+
+ expect(() =>
+ computeCursorArgFilter({
+ cursor,
+ orderBy,
+ flatObjectMetadata,
+ flatFieldMetadataMaps,
+ isForwardPagination: true,
+ }),
+ ).not.toThrow();
+ });
+ });
});
diff --git a/packages/twenty-server/src/engine/api/utils/__tests__/resolve-order-by-leaves.utils.spec.ts b/packages/twenty-server/src/engine/api/utils/__tests__/resolve-order-by-leaves.utils.spec.ts
new file mode 100644
index 00000000000..8b87265d907
--- /dev/null
+++ b/packages/twenty-server/src/engine/api/utils/__tests__/resolve-order-by-leaves.utils.spec.ts
@@ -0,0 +1,277 @@
+import { FieldMetadataType, OrderByDirection } from 'twenty-shared/types';
+
+import { GraphqlQueryRunnerException } from 'src/engine/api/graphql/graphql-query-runner/errors/graphql-query-runner.exception';
+import {
+ buildOrderByFromLeaves,
+ checkIfLeafCanCarryCursorValue,
+ getCursorValueForLeaf,
+ resolveOrderByLeaves,
+} from 'src/engine/api/utils/resolve-order-by-leaves.utils';
+import { type FlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/types/flat-entity-maps.type';
+import { type FlatFieldMetadata } from 'src/engine/metadata-modules/flat-field-metadata/types/flat-field-metadata.type';
+import { type FlatObjectMetadata } from 'src/engine/metadata-modules/flat-object-metadata/types/flat-object-metadata.type';
+
+describe('resolveOrderByLeaves', () => {
+ const workspaceId = 'workspace-id';
+ const objectMetadataId = 'object-id';
+
+ const createMockField = (
+ overrides: Partial<FlatFieldMetadata> & {
+ id: string;
+ name: string;
+ type: FieldMetadataType;
+ },
+ ): FlatFieldMetadata =>
+ ({
+ workspaceId,
+ objectMetadataId,
+ isNullable: true,
+ createdAt: new Date(),
+ updatedAt: new Date(),
+ universalIdentifier: overrides.id,
+ label: overrides.name,
+ ...overrides,
+ }) as FlatFieldMetadata;
+
+ const idField = createMockField({
+ id: 'id-id',
+ type: FieldMetadataType.UUID,
+ name: 'id',
+ isNullable: false,
+ });
+
+ const closeDateField = createMockField({
+ id: 'closedate-id',
+ type: FieldMetadataType.DATE_TIME,
+ name: 'closeDate',
+ });
+
+ const fullNameField = createMockField({
+ id: 'fullname-id',
+ type: FieldMetadataType.FULL_NAME,
+ name: 'fullName',
+ });
+
+ const linksField = createMockField({
+ id: 'links-id',
+ type: FieldMetadataType.LINKS,
+ name: 'domainName',
+ });
+
+ const companyField = createMockField({
+ id: 'company-id',
+ type: FieldMetadataType.RELATION,
+ name: 'company',
+ relationTargetObjectMetadataId: 'company-object-id',
+ settings: {
+ relationType: 'MANY_TO_ONE',
+ joinColumnName: 'companyId',
+ // oxlint-disable-next-line typescript/no-explicit-any
+ } as any,
+ });
+
+ const fields = [
+ idField,
+ closeDateField,
+ fullNameField,
+ linksField,
+ companyField,
+ ];
+
+ const flatFieldMetadataMaps: FlatEntityMaps<FlatFieldMetadata> = {
+ byUniversalIdentifier: Object.fromEntries(
+ fields.map((field) => [field.universalIdentifier, field]),
+ ),
+ universalIdentifierById: Object.fromEntries(
+ fields.map((field) => [field.id, field.universalIdentifier]),
+ ),
+ universalIdentifiersByApplicationId: {},
+ };
+
+ const flatObjectMetadata = {
+ id: objectMetadataId,
+ workspaceId,
+ nameSingular: 'opportunity',
+ fieldIds: fields.map((field) => field.id),
+ } as unknown as FlatObjectMetadata;
+
+ const resolve = (
+ // oxlint-disable-next-line typescript/no-explicit-any
+ orderBy: any,
+ strictValidation = false,
+ ) =>
+ resolveOrderByLeaves({
+ orderBy,
+ flatObjectMetadata,
+ flatFieldMetadataMaps,
+ strictValidation,
+ });
+
+ it('should flatten scalar, composite and relation entries into leaves with their own direction', () => {
+ const leaves = resolve([
+ { closeDate: OrderByDirection.DescNullsLast },
+ {
+ fullName: {
+ firstName: OrderByDirection.AscNullsLast,
+ lastName: OrderByDirection.DescNullsFirst,
+ },
+ },
+ { company: { name: OrderByDirection.AscNullsLast } },
+ { companyId: OrderByDirection.AscNullsFirst },
+ ]);
+
+ expect(
+ leaves.map(({ path, direction, kind }) => ({ path, direction, kind })),
+ ).toEqual([
+ {
+ path: ['closeDate'],
+ direction: OrderByDirection.DescNullsLast,
+ kind: 'scalar',
+ },
+ {
+ path: ['fullName', 'firstName'],
+ direction: OrderByDirection.AscNullsLast,
+ kind: 'composite',
+ },
+ {
+ path: ['fullName', 'lastName'],
+ direction: OrderByDirection.DescNullsFirst,
+ kind: 'composite',
+ },
+ {
+ path: ['company', 'name'],
+ direction: OrderByDirection.AscNullsLast,
+ kind: 'relation',
+ },
+ {
+ path: ['companyId'],
+ direction: OrderByDirection.AscNullsFirst,
+ kind: 'scalar',
+ },
+ ]);
+ });
+
+ it('should keep the first occurrence when a leaf is duplicated', () => {
+ const leaves = resolve([
+ { closeDate: OrderByDirection.AscNullsLast },
+ { closeDate: OrderByDirection.DescNullsFirst },
+ ]);
+
+ expect(leaves).toHaveLength(1);
+ expect(leaves[0].direction).toBe(OrderByDirection.AscNullsLast);
+ });
+
+ it('should let a caller-provided id ordering win over the appended tie-breaker', () => {
+ const leaves = resolve([
+ { id: OrderByDirection.DescNullsLast },
+ { id: OrderByDirection.AscNullsFirst },
+ ]);
+
+ expect(leaves).toHaveLength(1);
+ expect(leaves[0].direction).toBe(OrderByDirection.DescNullsLast);
+ });
+
+ it('should rebuild the canonical orderBy from the leaves', () => {
+ const leaves = resolve([
+ {
+ fullName: {
+ firstName: OrderByDirection.AscNullsLast,
+ lastName: OrderByDirection.AscNullsLast,
+ },
+ },
+ { company: { name: OrderByDirection.DescNullsLast } },
+ { id: OrderByDirection.AscNullsFirst },
+ ]);
+
+ expect(buildOrderByFromLeaves(leaves)).toEqual([
+ { fullName: { firstName: OrderByDirection.AscNullsLast } },
+ { fullName: { lastName: OrderByDirection.AscNullsLast } },
+ { company: { name: OrderByDirection.DescNullsLast } },
+ { id: OrderByDirection.AscNullsFirst },
+ ]);
+ });
+
+ it('should flatten a relation entry ordered by a composite target field', () => {
+ const leaves = resolve([
+ { company: { name: { firstName: OrderByDirection.AscNullsLast } } },
+ { company: { name: { lastName: OrderByDirection.AscNullsLast } } },
+ ]);
+
+ expect(leaves.map(({ path }) => path)).toEqual([
+ ['company', 'name', 'firstName'],
+ ['company', 'name', 'lastName'],
+ ]);
+ expect(buildOrderByFromLeaves(leaves)).toEqual([
+ { company: { name: { firstName: OrderByDirection.AscNullsLast } } },
+ { company: { name: { lastName: OrderByDirection.AscNullsLast } } },
+ ]);
+ });
+
+ it('should skip unknown fields when lenient and throw when strict', () => {
+ expect(resolve([{ unknownField: OrderByDirection.AscNullsLast }])).toEqual(
+ [],
+ );
+
+ expect(() =>
+ resolve([{ unknownField: OrderByDirection.AscNullsLast }], true),
+ ).toThrow(GraphqlQueryRunnerException);
+ });
+
+ it('should reject malformed entries in strict mode', () => {
+ expect(() => resolve([{ closeDate: { nested: 'value' } }], true)).toThrow(
+ 'requires a direction value',
+ );
+ expect(() =>
+ resolve([{ fullName: OrderByDirection.AscNullsLast }], true),
+ ).toThrow('requires subfield ordering');
+ expect(() =>
+ resolve(
+ [{ fullName: { unknownSub: OrderByDirection.AscNullsLast } }],
+ true,
+ ),
+ ).toThrow('not found for composite field');
+ expect(() =>
+ resolve([{ company: OrderByDirection.AscNullsLast }], true),
+ ).toThrow('requires nested field ordering');
+ });
+
+ it('should exclude relation and RAW_JSON leaves from cursor use', () => {
+ const leaves = resolve([
+ { company: { name: OrderByDirection.AscNullsLast } },
+ { domainName: { primaryLinkUrl: OrderByDirection.AscNullsLast } },
+ { domainName: { secondaryLinks: OrderByDirection.AscNullsLast } },
+ { id: OrderByDirection.AscNullsFirst },
+ ]);
+
+ expect(
+ leaves
+ .filter(checkIfLeafCanCarryCursorValue)
+ .map(({ path }) => path.join('.')),
+ ).toEqual(['domainName.primaryLinkUrl', 'id']);
+ });
+
+ describe('getCursorValueForLeaf', () => {
+ const firstNameLeaf = resolve([
+ { fullName: { firstName: OrderByDirection.AscNullsLast } },
+ ])[0];
+
+ it('should read nested values, including null', () => {
+ expect(
+ getCursorValueForLeaf(
+ { fullName: { firstName: 'Ada' } },
+ firstNameLeaf,
+ ),
+ ).toBe('Ada');
+ expect(
+ getCursorValueForLeaf({ fullName: { firstName: null } }, firstNameLeaf),
+ ).toBeNull();
+ expect(getCursorValueForLeaf({}, firstNameLeaf)).toBeUndefined();
+ });
+
+ it('should fall back to legacy dotted cursor keys', () => {
+ expect(
+ getCursorValueForLeaf({ 'fullName.firstName': 'Ada' }, firstNameLeaf),
+ ).toBe('Ada');
+ });
+ });
+});
diff --git a/packages/twenty-server/src/engine/api/utils/build-cursor-composite-field-where-condition.utils.ts b/packages/twenty-server/src/engine/api/utils/build-cursor-composite-field-where-condition.utils.ts
deleted file mode 100644
index 959f784ef7d..00000000000
--- a/packages/twenty-server/src/engine/api/utils/build-cursor-composite-field-where-condition.utils.ts
+++ /dev/null
@@ -1,144 +0,0 @@
-import {
- FieldMetadataType,
- type ObjectRecord,
- compositeTypeDefinitions,
-} from 'twenty-shared/types';
-import { isDefined } from 'twenty-shared/utils';
-
-import {
- type ObjectRecordCursorLeafCompositeValue,
- type ObjectRecordFilter,
- type ObjectRecordOrderBy,
-} from 'src/engine/api/graphql/workspace-query-builder/interfaces/object-record.interface';
-
-import { STANDARD_ERROR_MESSAGE } from 'src/engine/api/common/common-query-runners/errors/standard-error-message.constant';
-import {
- GraphqlQueryRunnerException,
- GraphqlQueryRunnerExceptionCode,
-} from 'src/engine/api/graphql/graphql-query-runner/errors/graphql-query-runner.exception';
-import { buildCursorCumulativeWhereCondition } from 'src/engine/api/utils/build-cursor-cumulative-where-conditions.utils';
-import { computeOperator } from 'src/engine/api/utils/compute-operator.utils';
-import { isAscendingOrder } from 'src/engine/api/utils/is-ascending-order.utils';
-import { validateAndGetOrderByForCompositeField } from 'src/engine/api/utils/validate-and-get-order-by.utils';
-
-type BuildCursorCompositeFieldWhereConditionParams = {
- fieldType: FieldMetadataType;
- fieldKey: keyof ObjectRecord;
- orderBy: ObjectRecordOrderBy;
- cursorValue: ObjectRecordCursorLeafCompositeValue;
- isForwardPagination: boolean;
- isEqualityCondition?: boolean;
-};
-
-export const buildCursorCompositeFieldWhereCondition = ({
- fieldType,
- fieldKey,
- orderBy,
- cursorValue,
- isForwardPagination,
- isEqualityCondition = false,
-}: BuildCursorCompositeFieldWhereConditionParams): Record<
- string,
- ObjectRecordFilter
-> => {
- const compositeType = compositeTypeDefinitions.get(fieldType);
-
- if (!compositeType) {
- throw new GraphqlQueryRunnerException(
- `Composite type definition not found for type: ${fieldType}`,
- GraphqlQueryRunnerExceptionCode.INVALID_CURSOR,
- { userFriendlyMessage: STANDARD_ERROR_MESSAGE },
- );
- }
-
- const fieldOrderBy = validateAndGetOrderByForCompositeField(
- fieldKey,
- orderBy,
- );
-
- const compositeFieldProperties = compositeType.properties.filter(
- (property) =>
- property.type !== FieldMetadataType.RAW_JSON &&
- cursorValue[property.name] !== undefined,
- );
-
- if (compositeFieldProperties.length === 0) {
- return {};
- }
-
- const cursorEntries = compositeFieldProperties
- .map((property) => {
- if (cursorValue[property.name] === undefined) {
- return null;
- }
-
- return {
- [property.name]: cursorValue[property.name],
- };
- })
- .filter(isDefined);
-
- if (isEqualityCondition) {
- const result = cursorEntries.reduce<Record<string, ObjectRecordFilter>>(
- (acc, cursorEntry) => {
- const [cursorKey, cursorValue] = Object.entries(cursorEntry)[0];
-
- return {
- ...acc,
- [cursorKey]: {
- eq: cursorValue,
- },
- };
- },
- {},
- );
-
- return {
- [fieldKey]: result,
- };
- }
-
- const orConditions = buildCursorCumulativeWhereCondition({
- cursorEntries,
- buildEqualityCondition: ({ cursorKey, cursorValue }) => ({
- [fieldKey]: {
- [cursorKey]: {
- eq: cursorValue,
- },
- },
- }),
- buildMainCondition: ({ cursorKey, cursorValue }) => {
- const orderByDirection = fieldOrderBy[fieldKey]?.[cursorKey];
-
- if (!isDefined(orderByDirection)) {
- throw new GraphqlQueryRunnerException(
- 'Invalid cursor',
- GraphqlQueryRunnerExceptionCode.INVALID_CURSOR,
- { userFriendlyMessage: STANDARD_ERROR_MESSAGE },
- );
- }
-
- const isAscending = isAscendingOrder(orderByDirection);
- const computedOperator = computeOperator(
- isAscending,
- isForwardPagination,
- );
-
- return {
- [fieldKey]: {
- [cursorKey]: {
- [computedOperator]: cursorValue,
- },
- },
- };
- },
- });
-
- if (orConditions.length === 1) {
- return orConditions[0];
- }
-
- return {
- or: orConditions,
- };
-};
diff --git a/packages/twenty-server/src/engine/api/utils/build-cursor-cumulative-where-conditions.utils.ts b/packages/twenty-server/src/engine/api/utils/build-cursor-cumulative-where-conditions.utils.ts
deleted file mode 100644
index d3097336977..00000000000
--- a/packages/twenty-server/src/engine/api/utils/build-cursor-cumulative-where-conditions.utils.ts
+++ /dev/null
@@ -1,74 +0,0 @@
-import {
- type ObjectRecordCursorLeafCompositeValue,
- type ObjectRecordCursorLeafScalarValue,
- type ObjectRecordFilter,
-} from 'src/engine/api/graphql/workspace-query-builder/interfaces/object-record.interface';
-
-type BuildCursorConditionParams<CursorValue> = {
- cursorKey: string;
- cursorValue: CursorValue;
-};
-
-type ReturnType = Array<ObjectRecordFilter | { and: ObjectRecordFilter[] }>;
-
-type CursorEntry<CursorValue> = Record<string, CursorValue>;
-
-type BuildCursorCumulativeWhereConditionsParams<CursorValue> = {
- cursorEntries: CursorEntry<CursorValue>[];
- buildEqualityCondition: ({
- cursorKey,
- cursorValue,
- }: BuildCursorConditionParams<CursorValue>) => ObjectRecordFilter;
- buildMainCondition: ({
- cursorKey,
- cursorValue,
- }: BuildCursorConditionParams<CursorValue>) => ObjectRecordFilter;
-};
-
-export const buildCursorCumulativeWhereCondition = <
- CursorValue extends
- | ObjectRecordCursorLeafCompositeValue
- | ObjectRecordCursorLeafScalarValue,
->({
- cursorEntries,
- buildEqualityCondition,
- buildMainCondition,
-}: BuildCursorCumulativeWhereConditionsParams<CursorValue>): ReturnType => {
- return cursorEntries.map((cursorEntry, index) => {
- const [currentCursorKey, currentCursorValue] =
- Object.entries(cursorEntry)[0];
- const andConditions: ObjectRecordFilter[] = [];
-
- for (
- let subConditionIndex = 0;
- subConditionIndex < index;
- subConditionIndex++
- ) {
- const previousCursorEntry = cursorEntries[subConditionIndex];
- const [previousCursorKey, previousCursorValue] =
- Object.entries(previousCursorEntry)[0];
-
- andConditions.push(
- buildEqualityCondition({
- cursorKey: previousCursorKey,
- cursorValue: previousCursorValue,
- }),
- );
- }
-
- andConditions.push(
- buildMainCondition({
- cursorKey: currentCursorKey,
- cursorValue: currentCursorValue,
- }),
- );
-
- if (andConditions.length === 1) {
- return andConditions[0];
- }
-
- return {
- and: andConditions,
- };
- });
-};
diff --git a/packages/twenty-server/src/engine/api/utils/build-cursor-keyset-condition.utils.ts b/packages/twenty-server/src/engine/api/utils/build-cursor-keyset-condition.utils.ts
new file mode 100644
index 00000000000..c55ad23f3c1
--- /dev/null
+++ b/packages/twenty-server/src/engine/api/utils/build-cursor-keyset-condition.utils.ts
@@ -0,0 +1,86 @@
+import {
+ type FieldMetadataType,
+ type OrderByDirection,
+} from 'twenty-shared/types';
+import { isDefined } from 'twenty-shared/utils';
+
+import { findPostgresDefaultNullEquivalentValue } from 'src/engine/api/common/common-args-processors/data-arg-processor/utils/find-postgres-default-null-equivalent-value.util';
+import { getEffectiveScanOrder } from 'src/engine/api/utils/get-effective-scan-order.utils';
+
+// Columns of these types are created NOT NULL with a Postgres default (e.g. ''
+// for TEXT), so they never hold SQL NULL and need no NULL-continuation branch
+export const checkIfColumnHasNullEquivalentDefault = (
+ fieldType: FieldMetadataType,
+ compositeSubFieldKey?: string,
+): boolean =>
+ isDefined(
+ findPostgresDefaultNullEquivalentValue(
+ 'NULL',
+ fieldType,
+ compositeSubFieldKey,
+ ),
+ );
+
+type BuildCursorKeysetConditionParams = {
+ cursorValue: unknown;
+ orderByDirection: OrderByDirection;
+ isForwardPagination: boolean;
+ isEqualityCondition: boolean;
+ canFieldHoldNullValue: boolean;
+ // Wraps a leaf filter (e.g. { gt: value }) into the field's filter path
+ buildLeafCondition: (
+ leafFilter: Record<string, unknown>,
+ ) => Record<string, unknown>;
+ // Overridable for fields whose NULL block is better matched through another
+ // column (e.g. a relation's join column)
+ buildNullCheckCondition?: (isNull: boolean) => Record<string, unknown>;
+};
+
+// The single home of the null-aware keyset algebra shared by scalar, composite
+// and relation orderBy keys. Returns null when no row can sort strictly after
+// the cursor on this key alone (cursor inside the trailing NULL block): the
+// caller must then drop the or-branch and rely on the tie-breaking keys.
+// Equality conditions always exist, which the overloads make visible to callers.
+export function buildCursorKeysetCondition(
+ params: BuildCursorKeysetConditionParams & { isEqualityCondition: true },
+): Record<string, unknown>;
+export function buildCursorKeysetCondition(
+ params: BuildCursorKeysetConditionParams,
+): Record<string, unknown> | null;
+export function buildCursorKeysetCondition({
+ cursorValue,
+ orderByDirection,
+ isForwardPagination,
+ isEqualityCondition,
+ canFieldHoldNullValue,
+ buildLeafCondition,
+ buildNullCheckCondition = (isNull) =>
+ buildLeafCondition({ is: isNull ? 'NULL' : 'NOT_NULL' }),
+}: BuildCursorKeysetConditionParams): Record<string, unknown> | null {
+ if (isEqualityCondition) {
+ return cursorValue === null
+ ? buildNullCheckCondition(true)
+ : buildLeafCondition({ eq: cursorValue });
+ }
+
+ const { isAscending, areNullsScannedLast } = getEffectiveScanOrder(
+ orderByDirection,
+ isForwardPagination,
+ );
+
+ if (cursorValue === null) {
+ // Inside the leading NULL block only the tie-breaking keys can advance the
+ // scan; inside the trailing one nothing sorts after on this key at all
+ return areNullsScannedLast ? null : buildNullCheckCondition(false);
+ }
+
+ const mainCondition = buildLeafCondition({
+ [isAscending ? 'gt' : 'lt']: cursorValue,
+ });
+
+ if (areNullsScannedLast && canFieldHoldNullValue) {
+ return { or: [mainCondition, buildNullCheckCondition(true)] };
+ }
+
+ return mainCondition;
+}
diff --git a/packages/twenty-server/src/engine/api/utils/build-cursor-leaf-where-condition.utils.ts b/packages/twenty-server/src/engine/api/utils/build-cursor-leaf-where-condition.utils.ts
new file mode 100644
index 00000000000..18eee33265b
--- /dev/null
+++ b/packages/twenty-server/src/engine/api/utils/build-cursor-leaf-where-condition.utils.ts
@@ -0,0 +1,60 @@
+import {
+ buildCursorKeysetCondition,
+ checkIfColumnHasNullEquivalentDefault,
+} from 'src/engine/api/utils/build-cursor-keyset-condition.utils';
+import { type OrderByLeaf } from 'src/engine/api/utils/resolve-order-by-leaves.utils';
+
+// Composite sub-columns are NOT NULL whenever their type defines a Postgres
+// null-equivalent default; scalar columns additionally honor field nullability.
+const checkIfLeafCanHoldNullValue = (leaf: OrderByLeaf): boolean => {
+ switch (leaf.kind) {
+ case 'composite':
+ return !checkIfColumnHasNullEquivalentDefault(
+ leaf.fieldMetadata.type,
+ leaf.compositeProperty.name,
+ );
+ case 'scalar':
+ return (
+ leaf.fieldMetadata.isNullable !== false &&
+ !checkIfColumnHasNullEquivalentDefault(leaf.fieldMetadata.type)
+ );
+ // A LEFT JOIN can always produce NULLs, whatever the target column's type
+ case 'relation':
+ return true;
+ }
+};
+
+type BuildCursorLeafWhereConditionParams = {
+ leaf: OrderByLeaf;
+ cursorValue: unknown;
+ isForwardPagination: boolean;
+ isEqualityCondition: boolean;
+};
+
+// The leaf's path is also its filter nesting: { name: { firstName: { gt: v } } }
+// resolves against the same column the ordering uses.
+export function buildCursorLeafWhereCondition(
+ params: BuildCursorLeafWhereConditionParams & { isEqualityCondition: true },
+): Record<string, unknown>;
+export function buildCursorLeafWhereCondition(
+ params: BuildCursorLeafWhereConditionParams,
+): Record<string, unknown> | null;
+export function buildCursorLeafWhereCondition({
+ leaf,
+ cursorValue,
+ isForwardPagination,
+ isEqualityCondition,
+}: BuildCursorLeafWhereConditionParams): Record<string, unknown> | null {
+ return buildCursorKeysetCondition({
+ cursorValue,
+ orderByDirection: leaf.direction,
+ isForwardPagination,
+ isEqualityCondition,
+ canFieldHoldNullValue: checkIfLeafCanHoldNullValue(leaf),
+ buildLeafCondition: (leafFilter) =>
+ leaf.path.reduceRight<Record<string, unknown>>(
+ (nested, key) => ({ [key]: nested }),
+ leafFilter,
+ ),
+ });
+}
diff --git a/packages/twenty-server/src/engine/api/utils/build-cursor-where-condition.utils.ts b/packages/twenty-server/src/engine/api/utils/build-cursor-where-condition.utils.ts
deleted file mode 100644
index 95f1326cf12..00000000000
--- a/packages/twenty-server/src/engine/api/utils/build-cursor-where-condition.utils.ts
+++ /dev/null
@@ -1,116 +0,0 @@
-import { type ObjectRecord } from 'twenty-shared/types';
-import { isDefined } from 'twenty-shared/utils';
-
-import {
- type ObjectRecordCursorLeafCompositeValue,
- type ObjectRecordCursorLeafScalarValue,
- type ObjectRecordOrderBy,
-} from 'src/engine/api/graphql/workspace-query-builder/interfaces/object-record.interface';
-
-import { STANDARD_ERROR_MESSAGE } from 'src/engine/api/common/common-query-runners/errors/standard-error-message.constant';
-import {
- GraphqlQueryRunnerException,
- GraphqlQueryRunnerExceptionCode,
-} from 'src/engine/api/graphql/graphql-query-runner/errors/graphql-query-runner.exception';
-import { buildCursorCompositeFieldWhereCondition } from 'src/engine/api/utils/build-cursor-composite-field-where-condition.utils';
-import { computeOperator } from 'src/engine/api/utils/compute-operator.utils';
-import { isAscendingOrder } from 'src/engine/api/utils/is-ascending-order.utils';
-import { validateAndGetOrderByForScalarField } from 'src/engine/api/utils/validate-and-get-order-by.utils';
-import { isCompositeFieldMetadataType } from 'src/engine/metadata-modules/field-metadata/utils/is-composite-field-metadata-type.util';
-import { type FlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/types/flat-entity-maps.type';
-import { findFlatEntityByIdInFlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/utils/find-flat-entity-by-id-in-flat-entity-maps.util';
-import { type FlatFieldMetadata } from 'src/engine/metadata-modules/flat-field-metadata/types/flat-field-metadata.type';
-import { buildFieldMapsFromFlatObjectMetadata } from 'src/engine/metadata-modules/flat-field-metadata/utils/build-field-maps-from-flat-object-metadata.util';
-import { type FlatObjectMetadata } from 'src/engine/metadata-modules/flat-object-metadata/types/flat-object-metadata.type';
-
-type BuildCursorWhereConditionParams = {
- cursorKey: string;
- cursorValue:
- | ObjectRecordCursorLeafScalarValue
- | ObjectRecordCursorLeafCompositeValue;
- flatObjectMetadata: FlatObjectMetadata;
- flatFieldMetadataMaps: FlatEntityMaps<FlatFieldMetadata>;
- orderBy: ObjectRecordOrderBy;
- isForwardPagination: boolean;
- isEqualityCondition?: boolean;
-};
-
-export const buildCursorWhereCondition = ({
- cursorKey,
- cursorValue,
- flatObjectMetadata,
- flatFieldMetadataMaps,
- orderBy,
- isForwardPagination,
- isEqualityCondition = false,
-}: BuildCursorWhereConditionParams): Record<string, unknown> => {
- const { fieldIdByName } = buildFieldMapsFromFlatObjectMetadata(
- flatFieldMetadataMaps,
- flatObjectMetadata,
- );
-
- const [fieldKey, ...subFieldPath] = cursorKey.split('.');
- const compositeSubFieldKey = subFieldPath.join('.');
- const fieldMetadataKey = fieldKey as keyof ObjectRecord;
- const fieldMetadataId = fieldIdByName[fieldMetadataKey];
-
- const fieldMetadata = findFlatEntityByIdInFlatEntityMaps({
- flatEntityMaps: flatFieldMetadataMaps,
- flatEntityId: fieldMetadataId,
- });
-
- if (!fieldMetadata) {
- throw new GraphqlQueryRunnerException(
- `Field metadata not found for key: ${String(cursorKey)}`,
- GraphqlQueryRunnerExceptionCode.INVALID_CURSOR,
- { userFriendlyMessage: STANDARD_ERROR_MESSAGE },
- );
- }
-
- if (isCompositeFieldMetadataType(fieldMetadata.type)) {
- if (compositeSubFieldKey.length > 0) {
- return buildCursorCompositeFieldWhereCondition({
- fieldType: fieldMetadata.type,
- fieldKey: fieldMetadataKey,
- orderBy,
- cursorValue: {
- [compositeSubFieldKey]: cursorValue,
- } as ObjectRecordCursorLeafCompositeValue,
- isForwardPagination,
- isEqualityCondition,
- });
- }
-
- return buildCursorCompositeFieldWhereCondition({
- fieldType: fieldMetadata.type,
- fieldKey: fieldMetadataKey,
- orderBy,
- cursorValue: cursorValue as ObjectRecordCursorLeafCompositeValue,
- isForwardPagination,
- isEqualityCondition,
- });
- }
-
- if (isEqualityCondition) {
- return { [fieldMetadataKey]: { eq: cursorValue } };
- }
-
- const keyOrderBy = validateAndGetOrderByForScalarField(
- fieldMetadataKey,
- orderBy,
- );
- const orderByDirection = keyOrderBy[fieldMetadataKey];
-
- if (!isDefined(orderByDirection)) {
- throw new GraphqlQueryRunnerException(
- 'Invalid cursor',
- GraphqlQueryRunnerExceptionCode.INVALID_CURSOR,
- { userFriendlyMessage: STANDARD_ERROR_MESSAGE },
- );
- }
-
- const isAscending = isAscendingOrder(orderByDirection);
- const computedOperator = computeOperator(isAscending, isForwardPagination);
-
- return { [fieldMetadataKey]: { [computedOperator]: cursorValue } };
-};
diff --git a/packages/twenty-server/src/engine/api/utils/compute-cursor-arg-filter.utils.ts b/packages/twenty-server/src/engine/api/utils/compute-cursor-arg-filter.utils.ts
index 04289618e6d..9e5527f427e 100644
--- a/packages/twenty-server/src/engine/api/utils/compute-cursor-arg-filter.utils.ts
+++ b/packages/twenty-server/src/engine/api/utils/compute-cursor-arg-filter.utils.ts
@@ -2,63 +2,102 @@ import { isDefined } from 'twenty-shared/utils';
import {
type ObjectRecordCursor,
- type ObjectRecordCursorLeafCompositeValue,
- type ObjectRecordCursorLeafScalarValue,
type ObjectRecordFilter,
type ObjectRecordOrderBy,
} from 'src/engine/api/graphql/workspace-query-builder/interfaces/object-record.interface';
-import { buildCursorCumulativeWhereCondition } from 'src/engine/api/utils/build-cursor-cumulative-where-conditions.utils';
-import { buildCursorWhereCondition } from 'src/engine/api/utils/build-cursor-where-condition.utils';
+import { STANDARD_ERROR_MESSAGE } from 'src/engine/api/common/common-query-runners/errors/standard-error-message.constant';
+import {
+ GraphqlQueryRunnerException,
+ GraphqlQueryRunnerExceptionCode,
+} from 'src/engine/api/graphql/graphql-query-runner/errors/graphql-query-runner.exception';
+import { buildCursorLeafWhereCondition } from 'src/engine/api/utils/build-cursor-leaf-where-condition.utils';
+import {
+ checkIfLeafCanCarryCursorValue,
+ getCursorValueForLeaf,
+ resolveOrderByLeaves,
+} from 'src/engine/api/utils/resolve-order-by-leaves.utils';
import { type FlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/types/flat-entity-maps.type';
import { type FlatFieldMetadata } from 'src/engine/metadata-modules/flat-field-metadata/types/flat-field-metadata.type';
import { type FlatObjectMetadata } from 'src/engine/metadata-modules/flat-object-metadata/types/flat-object-metadata.type';
-export const computeCursorArgFilter = (
- cursor: ObjectRecordCursor,
- orderBy: ObjectRecordOrderBy,
- flatObjectMetadata: FlatObjectMetadata,
- flatFieldMetadataMaps: FlatEntityMaps<FlatFieldMetadata>,
- isForwardPagination = true,
-): ObjectRecordFilter[] => {
- const cursorEntries = Object.entries(cursor)
- .map(([key, value]) => {
- if (value === undefined) {
- return null;
- }
+type ComputeCursorArgFilterParams = {
+ cursor: ObjectRecordCursor;
+ orderBy: ObjectRecordOrderBy;
+ flatObjectMetadata: FlatObjectMetadata;
+ flatFieldMetadataMaps: FlatEntityMaps<FlatFieldMetadata>;
+ isForwardPagination: boolean;
+};
- return {
- [key]: value,
- };
- })
- .filter(isDefined);
+// Builds the cumulative keyset conditions continuing a scan from a cursor:
+// (k1 after v1) OR (k1 = v1 AND k2 after v2) OR ... over the ordered leaves.
+// A keyset cursor can only continue the scan if it carries a value for every
+// leaf of the requested ordering: a cursor generated under another orderBy (or
+// by a version that failed to capture a sort value) must fail loudly, because
+// continuing on the remaining leaves silently skips records (issue #24333).
+export const computeCursorArgFilter = ({
+ cursor,
+ orderBy,
+ flatObjectMetadata,
+ flatFieldMetadataMaps,
+ isForwardPagination,
+}: ComputeCursorArgFilterParams): ObjectRecordFilter[] => {
+ const leaves = resolveOrderByLeaves({
+ orderBy,
+ flatObjectMetadata,
+ flatFieldMetadataMaps,
+ strictValidation: true,
+ }).filter(checkIfLeafCanCarryCursorValue);
- if (cursorEntries.length === 0) {
- return [];
- }
+ const leavesWithCursorValues = leaves.map((leaf) => {
+ const cursorValue = getCursorValueForLeaf(cursor, leaf);
- return buildCursorCumulativeWhereCondition<
- ObjectRecordCursorLeafCompositeValue | ObjectRecordCursorLeafScalarValue
- >({
- cursorEntries,
- buildEqualityCondition: ({ cursorKey, cursorValue }) =>
- buildCursorWhereCondition({
- cursorKey,
- cursorValue,
- flatObjectMetadata,
- flatFieldMetadataMaps,
- orderBy,
- isForwardPagination: true,
- isEqualityCondition: true,
- }),
- buildMainCondition: ({ cursorKey, cursorValue }) =>
- buildCursorWhereCondition({
- cursorKey,
+ if (cursorValue === undefined) {
+ throw new GraphqlQueryRunnerException(
+ `Cursor is missing the value for orderBy field "${leaf.path.join('.')}": it was encoded for a different orderBy. Restart pagination without a cursor.`,
+ GraphqlQueryRunnerExceptionCode.INVALID_CURSOR,
+ { userFriendlyMessage: STANDARD_ERROR_MESSAGE },
+ );
+ }
+
+ return { leaf, cursorValue };
+ });
+
+ // Each equality condition is reused by every later branch: compute them once
+ const equalityConditions = leavesWithCursorValues.map(
+ ({ leaf, cursorValue }) =>
+ buildCursorLeafWhereCondition({
+ leaf,
cursorValue,
- flatObjectMetadata,
- flatFieldMetadataMaps,
- orderBy,
isForwardPagination,
+ isEqualityCondition: true,
}),
+ );
+
+ return leavesWithCursorValues.flatMap(({ leaf, cursorValue }, index) => {
+ const mainCondition = buildCursorLeafWhereCondition({
+ leaf,
+ cursorValue,
+ isForwardPagination,
+ isEqualityCondition: false,
+ });
+
+ // A null main condition means no row can sort strictly after the cursor on
+ // this leaf alone (e.g. inside a trailing NULL block): only the tie-breaking
+ // leaves of the following branches can advance the scan
+ if (!isDefined(mainCondition)) {
+ return [];
+ }
+
+ const andConditions = [
+ ...equalityConditions.slice(0, index),
+ mainCondition,
+ ] as ObjectRecordFilter[];
+
+ if (andConditions.length === 1) {
+ return [andConditions[0]];
+ }
+
+ return [{ and: andConditions } as unknown as ObjectRecordFilter];
});
};
diff --git a/packages/twenty-server/src/engine/api/utils/compute-operator.utils.ts b/packages/twenty-server/src/engine/api/utils/compute-operator.utils.ts
deleted file mode 100644
index 288d7491d63..00000000000
--- a/packages/twenty-server/src/engine/api/utils/compute-operator.utils.ts
+++ /dev/null
@@ -1,12 +0,0 @@
-export const computeOperator = (
- isAscending: boolean,
- isForwardPagination: boolean,
-): string => {
- return isAscending
- ? isForwardPagination
- ? 'gt'
- : 'lt'
- : isForwardPagination
- ? 'lt'
- : 'gt';
-};
diff --git a/packages/twenty-server/src/engine/api/utils/get-effective-scan-order.utils.ts b/packages/twenty-server/src/engine/api/utils/get-effective-scan-order.utils.ts
new file mode 100644
index 00000000000..2d0085703ad
--- /dev/null
+++ b/packages/twenty-server/src/engine/api/utils/get-effective-scan-order.utils.ts
@@ -0,0 +1,29 @@
+import { OrderByDirection } from 'twenty-shared/types';
+
+import { isAscendingOrder } from 'src/engine/api/utils/is-ascending-order.utils';
+
+export type EffectiveScanOrder = {
+ isAscending: boolean;
+ areNullsScannedLast: boolean;
+};
+
+// The single definition of the scan a paginated query performs: backward
+// pagination scans the exact reverse of the requested order, which flips both
+// the direction and the side the NULL block sits on. Both the SQL ORDER BY and
+// the keyset WHERE conditions must derive from this so they cannot disagree —
+// their prior independent encodings are how issue #24333 happened.
+export const getEffectiveScanOrder = (
+ direction: OrderByDirection,
+ isForwardPagination: boolean,
+): EffectiveScanOrder => {
+ const areNullsPresentedLast =
+ direction === OrderByDirection.AscNullsLast ||
+ direction === OrderByDirection.DescNullsLast;
+
+ return {
+ isAscending: isAscendingOrder(direction) === isForwardPagination,
+ areNullsScannedLast: isForwardPagination
+ ? areNullsPresentedLast
+ : !areNullsPresentedLast,
+ };
+};
diff --git a/packages/twenty-server/src/engine/api/utils/resolve-order-by-leaves.utils.ts b/packages/twenty-server/src/engine/api/utils/resolve-order-by-leaves.utils.ts
new file mode 100644
index 00000000000..c6d70634c13
--- /dev/null
+++ b/packages/twenty-server/src/engine/api/utils/resolve-order-by-leaves.utils.ts
@@ -0,0 +1,276 @@
+import {
+ type CompositeProperty,
+ FieldMetadataType,
+ type OrderByDirection,
+ compositeTypeDefinitions,
+} from 'twenty-shared/types';
+import { isDefined, isNonEmptyArray, isPlainObject } from 'twenty-shared/utils';
+
+import { type ObjectRecordOrderBy } from 'src/engine/api/graphql/workspace-query-builder/interfaces/object-record.interface';
+
+import { STANDARD_ERROR_MESSAGE } from 'src/engine/api/common/common-query-runners/errors/standard-error-message.constant';
+import {
+ GraphqlQueryRunnerException,
+ GraphqlQueryRunnerExceptionCode,
+} from 'src/engine/api/graphql/graphql-query-runner/errors/graphql-query-runner.exception';
+import { isOrderByDirection } from 'src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/graphql-query-order/utils/is-order-by-direction.util';
+import { resolveFilterKeyFieldMetadata } from 'src/engine/api/graphql/graphql-query-runner/graphql-query-parsers/utils/resolve-filter-key-field-metadata.util';
+import { isCompositeFieldMetadataType } from 'src/engine/metadata-modules/field-metadata/utils/is-composite-field-metadata-type.util';
+import { type FlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/types/flat-entity-maps.type';
+import { type FlatFieldMetadata } from 'src/engine/metadata-modules/flat-field-metadata/types/flat-field-metadata.type';
+import { buildFieldMapsFromFlatObjectMetadata } from 'src/engine/metadata-modules/flat-field-metadata/utils/build-field-maps-from-flat-object-metadata.util';
+import { isMorphOrRelationFlatFieldMetadata } from 'src/engine/metadata-modules/flat-field-metadata/utils/is-morph-or-relation-flat-field-metadata.util';
+import { type FlatObjectMetadata } from 'src/engine/metadata-modules/flat-object-metadata/types/flat-object-metadata.type';
+
+export type OrderByLeaf = {
+ // Path of the ordered value from the record root, e.g. ['closeDate'],
+ // ['name', 'firstName'] or ['company', 'name']. It is at once the cursor
+ // value path and the filter nesting of the keyset conditions.
+ path: string[];
+ direction: OrderByDirection;
+ fieldMetadata: FlatFieldMetadata;
+} & (
+ | // Scalar columns, including join columns addressed directly (e.g. companyId)
+ { kind: 'scalar' }
+ | { kind: 'composite'; compositeProperty: CompositeProperty }
+ | { kind: 'relation' }
+);
+
+// RAW_JSON sub-fields can be ordered by in SQL but take no part in cursors;
+// relation values live on a joined alias and are carried by cursors only once
+// the relation cursor continuation supports them.
+export const checkIfLeafCanCarryCursorValue = (leaf: OrderByLeaf): boolean => {
+ switch (leaf.kind) {
+ case 'relation':
+ return false;
+ case 'composite':
+ return leaf.compositeProperty.type !== FieldMetadataType.RAW_JSON;
+ case 'scalar':
+ return true;
+ }
+};
+
+const throwInvalidOrderByInput = (message: string): never => {
+ throw new GraphqlQueryRunnerException(
+ message,
+ GraphqlQueryRunnerExceptionCode.INVALID_QUERY_INPUT,
+ { userFriendlyMessage: STANDARD_ERROR_MESSAGE },
+ );
+};
+
+// Flattens the nested value of a relation orderBy entry into its leaf paths,
+// e.g. { name: 'AscNullsLast' } -> [['name']] and, for a composite target
+// field, { name: { firstName: 'AscNullsLast' } } -> [['name', 'firstName']].
+const flattenNestedOrderByValue = (
+ value: Record<string, unknown>,
+): Array<{ path: string[]; direction: OrderByDirection }> =>
+ Object.entries(value).flatMap(([key, nestedValue]) => {
+ if (isPlainObject(nestedValue)) {
+ return flattenNestedOrderByValue(nestedValue).map(
+ ({ path, direction }) => ({ path: [key, ...path], direction }),
+ );
+ }
+
+ // The SQL order parser silently ignores relation entries whose nested
+ // value is not a direction; mirror that here so both stay aligned
+ return isOrderByDirection(nestedValue)
+ ? [{ path: [key], direction: nestedValue }]
+ : [];
+ });
+
+// Single source of truth for walking an orderBy: every entry is flattened into
+// ordered leaves that carry their own direction, so the SQL ordering, column
+// selection, cursor encoding, cursor validation and keyset conditions all
+// consume the same list and cannot drift apart. Duplicated leaves keep their
+// first occurrence, which lets callers append the id tie-breaker untouched: a
+// caller-provided id ordering wins over the appended default.
+// Strict validation rejects unknown or malformed entries the way the SQL order
+// parser does; the lenient mode skips them instead, for callers that re-walk an
+// already-validated orderBy against another object (e.g. nested connections).
+export const resolveOrderByLeaves = ({
+ orderBy,
+ flatObjectMetadata,
+ flatFieldMetadataMaps,
+ strictValidation = false,
+}: {
+ orderBy: ObjectRecordOrderBy | undefined;
+ flatObjectMetadata: FlatObjectMetadata;
+ flatFieldMetadataMaps: FlatEntityMaps<FlatFieldMetadata>;
+ strictValidation?: boolean;
+}): OrderByLeaf[] => {
+ if (!isDefined(orderBy) || !isNonEmptyArray(orderBy)) {
+ return [];
+ }
+
+ const { fieldIdByName, fieldIdByJoinColumnName } =
+ buildFieldMapsFromFlatObjectMetadata(
+ flatFieldMetadataMaps,
+ flatObjectMetadata,
+ );
+
+ const leaves: OrderByLeaf[] = [];
+ const seenPaths = new Set<string>();
+
+ const pushLeaf = (leaf: OrderByLeaf): void => {
+ const pathKey = leaf.path.join('.');
+
+ if (seenPaths.has(pathKey)) {
+ return;
+ }
+ seenPaths.add(pathKey);
+ leaves.push(leaf);
+ };
+
+ for (const orderByEntry of orderBy) {
+ for (const [fieldName, orderByValue] of Object.entries(orderByEntry)) {
+ const { fieldMetadata, isReferencedByFieldName } =
+ resolveFilterKeyFieldMetadata({
+ filterKey: fieldName,
+ fieldIdByName,
+ fieldIdByJoinColumnName,
+ flatFieldMetadataMaps,
+ });
+
+ if (!isDefined(fieldMetadata)) {
+ if (strictValidation) {
+ throw new GraphqlQueryRunnerException(
+ `Field "${fieldName}" does not exist or is not sortable`,
+ GraphqlQueryRunnerExceptionCode.FIELD_NOT_FOUND,
+ { userFriendlyMessage: STANDARD_ERROR_MESSAGE },
+ );
+ }
+ continue;
+ }
+
+ if (
+ isReferencedByFieldName &&
+ isMorphOrRelationFlatFieldMetadata(fieldMetadata)
+ ) {
+ if (!isPlainObject(orderByValue)) {
+ if (strictValidation) {
+ throwInvalidOrderByInput(
+ `Relation field "${fieldName}" requires nested field ordering (e.g., { ${fieldName}: { fieldName: 'AscNullsFirst' } })`,
+ );
+ }
+ continue;
+ }
+
+ for (const { path, direction } of flattenNestedOrderByValue(
+ orderByValue,
+ )) {
+ pushLeaf({
+ kind: 'relation',
+ path: [fieldName, ...path],
+ direction,
+ fieldMetadata,
+ });
+ }
+ continue;
+ }
+
+ if (
+ isReferencedByFieldName &&
+ isCompositeFieldMetadataType(fieldMetadata.type)
+ ) {
+ if (!isPlainObject(orderByValue)) {
+ if (strictValidation) {
+ throwInvalidOrderByInput(
+ `Composite field "${fieldName}" requires subfield ordering (e.g., { ${fieldName}: { subFieldName: 'AscNullsFirst' } })`,
+ );
+ }
+ continue;
+ }
+
+ const compositeType = compositeTypeDefinitions.get(fieldMetadata.type);
+
+ for (const [propertyName, direction] of Object.entries(orderByValue)) {
+ const compositeProperty = compositeType?.properties.find(
+ (property) => property.name === propertyName,
+ );
+
+ if (!isDefined(compositeProperty)) {
+ if (strictValidation) {
+ throwInvalidOrderByInput(
+ `Sub field "${propertyName}" not found for composite field "${fieldName}"`,
+ );
+ }
+ continue;
+ }
+
+ if (!isOrderByDirection(direction)) {
+ if (strictValidation) {
+ throwInvalidOrderByInput(
+ `Composite sub field "${fieldName}.${propertyName}" requires a direction value (AscNullsFirst, AscNullsLast, DescNullsFirst, DescNullsLast)`,
+ );
+ }
+ continue;
+ }
+
+ pushLeaf({
+ kind: 'composite',
+ path: [fieldName, propertyName],
+ direction,
+ fieldMetadata,
+ compositeProperty,
+ });
+ }
+ continue;
+ }
+
+ if (!isOrderByDirection(orderByValue)) {
+ if (strictValidation) {
+ throwInvalidOrderByInput(
+ `Scalar field "${fieldName}" requires a direction value (AscNullsFirst, AscNullsLast, DescNullsFirst, DescNullsLast)`,
+ );
+ }
+ continue;
+ }
+
+ pushLeaf({
+ kind: 'scalar',
+ path: [fieldName],
+ direction: orderByValue,
+ fieldMetadata,
+ });
+ }
+ }
+
+ return leaves;
+};
+
+// Rebuilds the canonical orderBy the SQL order parser consumes, one entry per
+// leaf, so the scan order and the keyset conditions derive from the same
+// deduplicated list.
+export const buildOrderByFromLeaves = (
+ leaves: OrderByLeaf[],
+): ObjectRecordOrderBy =>
+ leaves.map(
+ ({ path, direction }) =>
+ path.reduceRight<unknown>(
+ (nested, key) => ({ [key]: nested }),
+ direction,
+ ) as ObjectRecordOrderBy[number],
+ );
+
+// Reads the leaf's value out of a decoded cursor. Composite values of legacy
+// cursors were carried under dotted keys (e.g. "name.firstName").
+export const getCursorValueForLeaf = (
+ cursor: Record<string, unknown>,
+ leaf: OrderByLeaf,
+): unknown => {
+ let value: unknown = cursor;
+
+ for (const key of leaf.path) {
+ if (!isPlainObject(value)) {
+ value = undefined;
+ break;
+ }
+ value = value[key];
+ }
+
+ if (value === undefined && leaf.path.length > 1) {
+ return cursor[leaf.path.join('.')];
+ }
+
+ return value;
+};
diff --git a/packages/twenty-server/src/engine/api/utils/validate-and-get-order-by.utils.ts b/packages/twenty-server/src/engine/api/utils/validate-and-get-order-by.utils.ts
deleted file mode 100644
index eb94ac13feb..00000000000
--- a/packages/twenty-server/src/engine/api/utils/validate-and-get-order-by.utils.ts
+++ /dev/null
@@ -1,141 +0,0 @@
-import {
- FieldMetadataType,
- type ObjectRecord,
- type ObjectRecordOrderByForCompositeField,
- type ObjectRecordOrderByForScalarField,
- OrderByDirection,
-} from 'twenty-shared/types';
-import { isDefined } from 'twenty-shared/utils';
-
-import { type ObjectRecordOrderBy } from 'src/engine/api/graphql/workspace-query-builder/interfaces/object-record.interface';
-
-import { STANDARD_ERROR_MESSAGE } from 'src/engine/api/common/common-query-runners/errors/standard-error-message.constant';
-import {
- GraphqlQueryRunnerException,
- GraphqlQueryRunnerExceptionCode,
-} from 'src/engine/api/graphql/graphql-query-runner/errors/graphql-query-runner.exception';
-import { type FlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/types/flat-entity-maps.type';
-import { findFlatEntityByIdInFlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/utils/find-flat-entity-by-id-in-flat-entity-maps.util';
-import { type FlatFieldMetadata } from 'src/engine/metadata-modules/flat-field-metadata/types/flat-field-metadata.type';
-
-const isOrderByDirection = (value: unknown): value is OrderByDirection => {
- return Object.values(OrderByDirection).includes(value as OrderByDirection);
-};
-
-const isOrderByForScalarField = (
- orderByLeaf: Record<string, unknown>,
- key: keyof ObjectRecord,
-): orderByLeaf is ObjectRecordOrderByForScalarField => {
- const value = orderByLeaf[key as string];
-
- return isDefined(value) && isOrderByDirection(value);
-};
-
-const isOrderByForCompositeField = (
- orderByLeaf: Record<string, unknown>,
- key: keyof ObjectRecord,
-): orderByLeaf is ObjectRecordOrderByForCompositeField => {
- const value = orderByLeaf[key as string];
-
- return (
- isDefined(value) &&
- typeof value === 'object' &&
- value !== null &&
- !isOrderByDirection(value) &&
- Object.values(value as Record<string, unknown>).every(isOrderByDirection)
- );
-};
-
-export const validateAndGetOrderByForScalarField = (
- key: keyof ObjectRecord,
- orderBy: ObjectRecordOrderBy,
-): ObjectRecordOrderByForScalarField => {
- const keyOrderBy = orderBy.find((order) => key in order);
-
- if (!isDefined(keyOrderBy)) {
- throw new GraphqlQueryRunnerException(
- 'Invalid cursor',
- GraphqlQueryRunnerExceptionCode.INVALID_CURSOR,
- { userFriendlyMessage: STANDARD_ERROR_MESSAGE },
- );
- }
-
- if (!isOrderByForScalarField(keyOrderBy, key)) {
- throw new GraphqlQueryRunnerException(
- 'Expected non-composite field order by',
- GraphqlQueryRunnerExceptionCode.INVALID_CURSOR,
- { userFriendlyMessage: STANDARD_ERROR_MESSAGE },
- );
- }
-
- return keyOrderBy;
-};
-
-export const validateAndGetOrderByForCompositeField = (
- key: keyof ObjectRecord,
- orderBy: ObjectRecordOrderBy,
-): ObjectRecordOrderByForCompositeField => {
- const matchingOrderBys = orderBy.filter((order) => key in order);
-
- if (matchingOrderBys.length === 0) {
- throw new GraphqlQueryRunnerException(
- 'Invalid cursor',
- GraphqlQueryRunnerExceptionCode.INVALID_CURSOR,
- { userFriendlyMessage: STANDARD_ERROR_MESSAGE },
- );
- }
-
- // Merge all orderBy entries for the same composite field key so that
- // separate { fullName: { firstName } } and { fullName: { lastName } } entries
- // are treated as a single composite orderBy
- const mergedValue = matchingOrderBys.reduce(
- (acc, orderByEntry) => ({
- ...acc,
- ...(orderByEntry[key as string] as Record<string, OrderByDirection>),
- }),
- {} as Record<string, OrderByDirection>,
- );
-
- const mergedOrderBy = { [key as string]: mergedValue };
-
- if (!isOrderByForCompositeField(mergedOrderBy, key)) {
- throw new GraphqlQueryRunnerException(
- 'Expected composite field order by',
- GraphqlQueryRunnerExceptionCode.INVALID_CURSOR,
- { userFriendlyMessage: STANDARD_ERROR_MESSAGE },
- );
- }
-
- return mergedOrderBy;
-};
-
-export const countRelationFieldsInOrderBy = (
- orderBy: ObjectRecordOrderBy,
- flatFieldMetadataMaps: FlatEntityMaps<FlatFieldMetadata>,
- fieldIdByName: Record<string, string>,
-): number => {
- return orderBy.filter((orderByItem) => {
- const fieldName = Object.keys(orderByItem)[0];
- const fieldMetadataId = fieldIdByName[fieldName];
- const fieldMetadata = findFlatEntityByIdInFlatEntityMaps({
- flatEntityId: fieldMetadataId,
- flatEntityMaps: flatFieldMetadataMaps,
- });
-
- return fieldMetadata?.type === FieldMetadataType.RELATION;
- }).length;
-};
-
-export const hasRelationFieldInOrderBy = (
- orderBy: ObjectRecordOrderBy,
- flatFieldMetadataMaps: FlatEntityMaps<FlatFieldMetadata>,
- fieldIdByName: Record<string, string>,
-): boolean => {
- return (
- countRelationFieldsInOrderBy(
- orderBy,
- flatFieldMetadataMaps,
- fieldIdByName,
- ) > 0
- );
-};
diff --git a/packages/twenty-server/src/engine/metadata-modules/flat-field-metadata/utils/build-field-maps-from-flat-object-metadata.util.ts b/packages/twenty-server/src/engine/metadata-modules/flat-field-metadata/utils/build-field-maps-from-flat-object-metadata.util.ts
index b4ddc1c32ef..15af21c3695 100644
--- a/packages/twenty-server/src/engine/metadata-modules/flat-field-metadata/utils/build-field-maps-from-flat-object-metadata.util.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/flat-field-metadata/utils/build-field-maps-from-flat-object-metadata.util.ts
@@ -12,10 +12,26 @@ export type FieldMapsForObject = {
fieldIdByJoinColumnName: Record<string, string>;
};
+// Flat metadata snapshots are immutable and cached per workspace metadata
+// version, so the maps derived from a given (fieldMaps, objectMetadata) pair can
+// be memoized by identity: several helpers rebuild them per request otherwise
+// (order parsing, cursor encoding per record, cursor conditions per key).
+const fieldMapsCache = new WeakMap<
+ FlatEntityMaps<FlatFieldMetadata>,
+ WeakMap<FlatObjectMetadata, FieldMapsForObject>
+>();
+
export const buildFieldMapsFromFlatObjectMetadata = (
flatFieldMetadataMaps: FlatEntityMaps<FlatFieldMetadata>,
flatObjectMetadata: FlatObjectMetadata,
): FieldMapsForObject => {
+ const cachedByObjectMetadata = fieldMapsCache.get(flatFieldMetadataMaps);
+ const cachedFieldMaps = cachedByObjectMetadata?.get(flatObjectMetadata);
+
+ if (cachedFieldMaps) {
+ return cachedFieldMaps;
+ }
+
const fieldIdByName: Record<string, string> = {};
const fieldIdByJoinColumnName: Record<string, string> = {};
@@ -40,8 +56,17 @@ export const buildFieldMapsFromFlatObjectMetadata = (
}
}
- return {
+ const fieldMaps = {
fieldIdByName,
fieldIdByJoinColumnName,
};
+
+ const cacheForFieldMaps =
+ cachedByObjectMetadata ??
+ new WeakMap<FlatObjectMetadata, FieldMapsForObject>();
+
+ cacheForFieldMaps.set(flatObjectMetadata, fieldMaps);
+ fieldMapsCache.set(flatFieldMetadataMaps, cacheForFieldMaps);
+
+ return fieldMaps;
};
diff --git a/packages/twenty-server/src/engine/twenty-orm/utils/__tests__/format-result.util.spec.ts b/packages/twenty-server/src/engine/twenty-orm/utils/__tests__/format-result.util.spec.ts
index a40eef18a18..24c83451927 100644
--- a/packages/twenty-server/src/engine/twenty-orm/utils/__tests__/format-result.util.spec.ts
+++ b/packages/twenty-server/src/engine/twenty-orm/utils/__tests__/format-result.util.spec.ts
@@ -125,11 +125,20 @@ describe('formatResult', () => {
expect(firstInvocationMetadataLookupCount).toBeGreaterThan(0);
expect(firstInvocationMetadataLookupCount).toBeLessThanOrEqual(4);
+ // Field maps derived from a metadata snapshot are memoized by object
+ // identity, so a second invocation only re-runs the lookups when it receives
+ // fresh snapshot objects
+ const rebuiltFlatFieldMetadataMaps = buildFlatEntityMaps([
+ companyNameFieldMetadata,
+ companyPeopleFieldMetadata,
+ personNameFieldMetadata,
+ ]);
+
formatResult(
records,
companyObjectMetadata,
flatObjectMetadataMaps,
- flatFieldMetadataMaps,
+ rebuiltFlatFieldMetadataMaps,
);
expect(
diff --git a/packages/twenty-server/test/integration/graphql/suites/cursor-pagination-order-by.integration-spec.ts b/packages/twenty-server/test/integration/graphql/suites/cursor-pagination-order-by.integration-spec.ts
new file mode 100644
index 00000000000..ff7d04fd818
--- /dev/null
+++ b/packages/twenty-server/test/integration/graphql/suites/cursor-pagination-order-by.integration-spec.ts
@@ -0,0 +1,522 @@
+import { randomUUID } from 'crypto';
+
+import { createManyOperationFactory } from 'test/integration/graphql/utils/create-many-operation-factory.util';
+import { findManyOperationFactory } from 'test/integration/graphql/utils/find-many-operation-factory.util';
+import { makeGraphqlAPIRequest } from 'test/integration/graphql/utils/make-graphql-api-request.util';
+import { deleteAllRecords } from 'test/integration/utils/delete-all-records';
+
+const PAGE_SIZE = 3;
+
+const DATED_CLOSE_DATES = [
+ '2026-01-01T00:00:00.000Z',
+ '2026-01-02T00:00:00.000Z',
+ '2026-01-03T00:00:00.000Z',
+ '2026-01-04T00:00:00.000Z',
+ '2026-01-05T00:00:00.000Z',
+ '2026-01-06T00:00:00.000Z',
+];
+const NULL_CLOSE_DATE_COUNT = 4;
+const TOTAL_COUNT = DATED_CLOSE_DATES.length + NULL_CLOSE_DATE_COUNT;
+
+const datedOpportunityIds = DATED_CLOSE_DATES.map(() => randomUUID());
+const nullCloseDateOpportunityIds = Array.from(
+ { length: NULL_CLOSE_DATE_COUNT },
+ () => randomUUID(),
+);
+
+type GraphqlResponse = {
+ body: {
+ errors?: { message: string }[];
+ // oxlint-disable-next-line typescript/no-explicit-any
+ data: Record<string, any>;
+ };
+};
+
+type RecordConnection = {
+ edges: { node: { id: string } }[];
+ pageInfo: {
+ hasNextPage: boolean;
+ hasPreviousPage: boolean;
+ startCursor: string;
+ endCursor: string;
+ };
+};
+
+type PaginateAllParams = {
+ orderBy: object;
+ objectMetadataSingularName?: string;
+ objectMetadataPluralName?: string;
+ filter?: object;
+ gqlFields?: string;
+ first?: number;
+};
+
+const paginateForward = async ({
+ orderBy,
+ objectMetadataSingularName = 'opportunity',
+ objectMetadataPluralName = 'opportunities',
+ filter,
+ gqlFields = 'id',
+ first = PAGE_SIZE,
+}: PaginateAllParams) => {
+ const ids: string[] = [];
+ let after: string | undefined = undefined;
+ let pages = 0;
+
+ // Cap the loop far above the expected page count so a paging bug cannot hang the suite
+ for (let iteration = 0; iteration < 20; iteration++) {
+ const response: GraphqlResponse = await makeGraphqlAPIRequest(
+ findManyOperationFactory({
+ objectMetadataSingularName,
+ objectMetadataPluralName,
+ gqlFields,
+ filter,
+ orderBy,
+ first,
+ after,
+ }),
+ ).expect(200);
+
+ expect(response.body.errors).toBeUndefined();
+
+ const connection: RecordConnection =
+ response.body.data[objectMetadataPluralName];
+
+ ids.push(...connection.edges.map((edge) => edge.node.id));
+ pages++;
+
+ if (!connection.pageInfo.hasNextPage) {
+ break;
+ }
+
+ after = connection.pageInfo.endCursor;
+ }
+
+ return { ids, pages };
+};
+
+const paginateBackwardFrom = async ({
+ orderBy,
+ startingBefore,
+ gqlFields = 'id',
+}: PaginateAllParams & { startingBefore: string }) => {
+ const ids: string[] = [];
+ let before: string | undefined = startingBefore;
+
+ for (let iteration = 0; iteration < 20; iteration++) {
+ const response: GraphqlResponse = await makeGraphqlAPIRequest(
+ findManyOperationFactory({
+ objectMetadataSingularName: 'opportunity',
+ objectMetadataPluralName: 'opportunities',
+ gqlFields,
+ orderBy,
+ last: PAGE_SIZE,
+ before,
+ }),
+ ).expect(200);
+
+ expect(response.body.errors).toBeUndefined();
+
+ const connection: RecordConnection = response.body.data.opportunities;
+
+ ids.unshift(...connection.edges.map((edge) => edge.node.id));
+
+ if (!connection.pageInfo.hasPreviousPage) {
+ break;
+ }
+
+ before = connection.pageInfo.startCursor;
+ }
+
+ return { ids };
+};
+
+describe('Cursor pagination exhaustiveness with orderBy (issue #24333)', () => {
+ beforeAll(async () => {
+ await deleteAllRecords('opportunity');
+
+ await makeGraphqlAPIRequest(
+ createManyOperationFactory({
+ objectMetadataSingularName: 'opportunity',
+ objectMetadataPluralName: 'opportunities',
+ gqlFields: 'id',
+ data: [
+ ...DATED_CLOSE_DATES.map((closeDate, index) => ({
+ id: datedOpportunityIds[index],
+ name: `Dated opportunity ${index + 1}`,
+ closeDate,
+ })),
+ ...nullCloseDateOpportunityIds.map((id, index) => ({
+ id,
+ name: `Undated opportunity ${index + 1}`,
+ })),
+ ],
+ }),
+ ).expect(200);
+ });
+
+ it('should return every record when paginating ordered by id (baseline)', async () => {
+ const { ids } = await paginateForward({
+ orderBy: { id: 'AscNullsLast' },
+ });
+
+ expect(new Set(ids).size).toBe(TOTAL_COUNT);
+ });
+
+ it('should return every record when the orderBy field is not in the selection set', async () => {
+ const { ids, pages } = await paginateForward({
+ orderBy: { closeDate: 'AscNullsFirst' },
+ gqlFields: 'id',
+ });
+
+ expect(ids).toHaveLength(TOTAL_COUNT);
+ expect(new Set(ids).size).toBe(TOTAL_COUNT);
+ expect(pages).toBe(Math.ceil(TOTAL_COUNT / PAGE_SIZE));
+ });
+
+ it.each(['AscNullsLast', 'DescNullsLast'])(
+ 'should paginate across the trailing NULL block with %s',
+ async (direction) => {
+ const { ids } = await paginateForward({
+ orderBy: { closeDate: direction },
+ });
+
+ expect(ids).toHaveLength(TOTAL_COUNT);
+ expect(new Set(ids).size).toBe(TOTAL_COUNT);
+
+ // The NULL block sorts last: its records must all be there, at the end
+ expect(new Set(ids.slice(DATED_CLOSE_DATES.length))).toEqual(
+ new Set(nullCloseDateOpportunityIds),
+ );
+ },
+ );
+
+ it.each(['AscNullsFirst', 'DescNullsFirst'])(
+ 'should paginate across the leading NULL block with %s',
+ async (direction) => {
+ const { ids } = await paginateForward({
+ orderBy: { closeDate: direction },
+ });
+
+ expect(ids).toHaveLength(TOTAL_COUNT);
+ expect(new Set(ids).size).toBe(TOTAL_COUNT);
+
+ expect(new Set(ids.slice(0, NULL_CLOSE_DATE_COUNT))).toEqual(
+ new Set(nullCloseDateOpportunityIds),
+ );
+ },
+ );
+
+ it('should keep the requested global order across pages', async () => {
+ const { ids } = await paginateForward({
+ orderBy: { closeDate: 'AscNullsLast' },
+ });
+
+ expect(ids.slice(0, DATED_CLOSE_DATES.length)).toEqual(datedOpportunityIds);
+ });
+
+ it('should walk backward across the NULL boundary with before cursors', async () => {
+ // Reach the last page forward, then walk back from its end cursor: the
+ // backward scan re-crosses the null/non-null boundary in reverse
+ const forwardResponse = await makeGraphqlAPIRequest(
+ findManyOperationFactory({
+ objectMetadataSingularName: 'opportunity',
+ objectMetadataPluralName: 'opportunities',
+ gqlFields: 'id',
+ orderBy: { closeDate: 'AscNullsLast' },
+ first: TOTAL_COUNT,
+ }),
+ ).expect(200);
+
+ const forwardConnection = forwardResponse.body.data.opportunities;
+ const forwardIds = forwardConnection.edges.map(
+ (edge: { node: { id: string } }) => edge.node.id,
+ );
+
+ expect(forwardIds).toHaveLength(TOTAL_COUNT);
+
+ const { ids } = await paginateBackwardFrom({
+ orderBy: { closeDate: 'AscNullsLast' },
+ startingBefore: forwardConnection.pageInfo.endCursor,
+ });
+
+ // Everything before the last record, in the same order as the forward scan
+ expect(ids).toEqual(forwardIds.slice(0, -1));
+ });
+
+ it('should reject a cursor that does not carry the orderBy field value', async () => {
+ const staleCursor = Buffer.from(
+ JSON.stringify({ id: datedOpportunityIds[0] }),
+ ).toString('base64');
+
+ const response: GraphqlResponse = await makeGraphqlAPIRequest(
+ findManyOperationFactory({
+ objectMetadataSingularName: 'opportunity',
+ objectMetadataPluralName: 'opportunities',
+ gqlFields: 'id',
+ orderBy: { closeDate: 'AscNullsLast' },
+ first: PAGE_SIZE,
+ after: staleCursor,
+ }),
+ ).expect(200);
+
+ expect(response.body.errors).toBeDefined();
+ expect(response.body.errors?.[0].message).toContain(
+ 'Cursor is missing the value for orderBy field "closeDate"',
+ );
+ });
+
+ it('should paginate exhaustively when a filter is combined with the cursor', async () => {
+ const { ids } = await paginateForward({
+ filter: { closeDate: { gte: DATED_CLOSE_DATES[2] } },
+ orderBy: { closeDate: 'AscNullsLast' },
+ first: 2,
+ });
+
+ expect(ids).toEqual(datedOpportunityIds.slice(2));
+ });
+
+ // Canonical lowercase UUID strings sort the same way in JS and in Postgres,
+ // so the expected order can be computed with a plain string sort
+ it('should honor an explicit descending id ordering across pages', async () => {
+ const { ids } = await paginateForward({
+ orderBy: { id: 'DescNullsLast' },
+ });
+
+ expect(ids).toEqual(
+ [...datedOpportunityIds, ...nullCloseDateOpportunityIds].sort().reverse(),
+ );
+ });
+
+ it('should tie-break with an explicit descending id inside the NULL block', async () => {
+ const { ids } = await paginateForward({
+ orderBy: [{ closeDate: 'AscNullsLast' }, { id: 'DescNullsLast' }],
+ });
+
+ expect(ids).toEqual([
+ ...datedOpportunityIds,
+ ...[...nullCloseDateOpportunityIds].sort().reverse(),
+ ]);
+ });
+
+ it('should keep the first direction when the same field is ordered twice', async () => {
+ const { ids } = await paginateForward({
+ orderBy: [{ closeDate: 'AscNullsLast' }, { closeDate: 'DescNullsFirst' }],
+ });
+
+ expect(ids.slice(0, DATED_CLOSE_DATES.length)).toEqual(datedOpportunityIds);
+ expect(new Set(ids.slice(DATED_CLOSE_DATES.length))).toEqual(
+ new Set(nullCloseDateOpportunityIds),
+ );
+ });
+});
+
+describe('Cursor pagination with composite orderBy not in the selection set', () => {
+ const personIds = Array.from({ length: 5 }, () => randomUUID());
+ const firstNames = ['Alice', 'Bob', 'Charlie', 'Diana', 'Eve'];
+
+ beforeAll(async () => {
+ await deleteAllRecords('person');
+
+ await makeGraphqlAPIRequest(
+ createManyOperationFactory({
+ objectMetadataSingularName: 'person',
+ objectMetadataPluralName: 'people',
+ gqlFields: 'id',
+ data: personIds.map((id, index) => ({
+ id,
+ name: {
+ firstName: firstNames[index],
+ lastName: 'Test',
+ },
+ })),
+ }),
+ ).expect(200);
+ });
+
+ it('should return every record when only id is selected', async () => {
+ const { ids } = await paginateForward({
+ objectMetadataSingularName: 'person',
+ objectMetadataPluralName: 'people',
+ orderBy: { name: { firstName: 'AscNullsLast' } },
+ first: 2,
+ });
+
+ // Global order must hold across pages: Alice..Eve
+ expect(ids).toEqual(personIds);
+ });
+});
+
+describe('Cursor pagination ordered by a nullable foreign key', () => {
+ const companyIds = [randomUUID(), randomUUID()];
+ const withCompanyOpportunityIds = [randomUUID(), randomUUID(), randomUUID()];
+ const withoutCompanyOpportunityIds = [
+ randomUUID(),
+ randomUUID(),
+ randomUUID(),
+ ];
+ const fkTotalCount =
+ withCompanyOpportunityIds.length + withoutCompanyOpportunityIds.length;
+
+ beforeAll(async () => {
+ await deleteAllRecords('opportunity');
+ await deleteAllRecords('company');
+
+ await makeGraphqlAPIRequest(
+ createManyOperationFactory({
+ objectMetadataSingularName: 'company',
+ objectMetadataPluralName: 'companies',
+ gqlFields: 'id',
+ data: companyIds.map((id, index) => ({
+ id,
+ name: `Cursor FK company ${index + 1}`,
+ })),
+ }),
+ ).expect(200);
+
+ await makeGraphqlAPIRequest(
+ createManyOperationFactory({
+ objectMetadataSingularName: 'opportunity',
+ objectMetadataPluralName: 'opportunities',
+ gqlFields: 'id',
+ data: [
+ ...withCompanyOpportunityIds.map((id, index) => ({
+ id,
+ name: `FK opportunity ${index + 1}`,
+ companyId: companyIds[index % companyIds.length],
+ })),
+ ...withoutCompanyOpportunityIds.map((id, index) => ({
+ id,
+ name: `FK-less opportunity ${index + 1}`,
+ })),
+ ],
+ }),
+ ).expect(200);
+ });
+
+ it('should return every record when ordering by the foreign key column', async () => {
+ const { ids } = await paginateForward({
+ orderBy: { companyId: 'AscNullsLast' },
+ first: 2,
+ });
+
+ expect(ids).toHaveLength(fkTotalCount);
+ expect(new Set(ids).size).toBe(fkTotalCount);
+ expect(new Set(ids.slice(withCompanyOpportunityIds.length))).toEqual(
+ new Set(withoutCompanyOpportunityIds),
+ );
+ });
+});
+
+describe('Cursor pagination ordered by a nullable composite sub-field', () => {
+ const withAmountOpportunityIds = [
+ randomUUID(),
+ randomUUID(),
+ randomUUID(),
+ randomUUID(),
+ ];
+ const withoutAmountOpportunityIds = [
+ randomUUID(),
+ randomUUID(),
+ randomUUID(),
+ ];
+ const amountTotalCount =
+ withAmountOpportunityIds.length + withoutAmountOpportunityIds.length;
+
+ beforeAll(async () => {
+ await deleteAllRecords('opportunity');
+
+ await makeGraphqlAPIRequest(
+ createManyOperationFactory({
+ objectMetadataSingularName: 'opportunity',
+ objectMetadataPluralName: 'opportunities',
+ gqlFields: 'id',
+ data: [
+ ...withAmountOpportunityIds.map((id, index) => ({
+ id,
+ name: `Amount opportunity ${index + 1}`,
+ amount: {
+ amountMicros: (index + 1) * 1_000_000,
+ currencyCode: 'USD',
+ },
+ })),
+ ...withoutAmountOpportunityIds.map((id, index) => ({
+ id,
+ name: `Amount-less opportunity ${index + 1}`,
+ })),
+ ],
+ }),
+ ).expect(200);
+ });
+
+ it('should paginate across the NULL block of a currency sub-field', async () => {
+ const { ids } = await paginateForward({
+ orderBy: { amount: { amountMicros: 'AscNullsLast' } },
+ first: 2,
+ });
+
+ expect(ids).toHaveLength(amountTotalCount);
+ expect(new Set(ids).size).toBe(amountTotalCount);
+ // Non-null amounts keep their micros order across pages
+ expect(ids.slice(0, withAmountOpportunityIds.length)).toEqual(
+ withAmountOpportunityIds,
+ );
+ expect(new Set(ids.slice(withAmountOpportunityIds.length))).toEqual(
+ new Set(withoutAmountOpportunityIds),
+ );
+ });
+});
+
+describe('Cursor pagination with duplicate sort values', () => {
+ const duplicatedCloseDates = [
+ '2026-02-01T00:00:00.000Z',
+ '2026-02-01T00:00:00.000Z',
+ '2026-02-02T00:00:00.000Z',
+ '2026-02-02T00:00:00.000Z',
+ '2026-02-03T00:00:00.000Z',
+ '2026-02-03T00:00:00.000Z',
+ ];
+ const duplicateDatedOpportunityIds = duplicatedCloseDates.map(() =>
+ randomUUID(),
+ );
+ const duplicateNullOpportunityIds = [randomUUID(), randomUUID()];
+ const duplicatesTotalCount =
+ duplicateDatedOpportunityIds.length + duplicateNullOpportunityIds.length;
+
+ beforeAll(async () => {
+ await deleteAllRecords('opportunity');
+
+ await makeGraphqlAPIRequest(
+ createManyOperationFactory({
+ objectMetadataSingularName: 'opportunity',
+ objectMetadataPluralName: 'opportunities',
+ gqlFields: 'id',
+ data: [
+ ...duplicatedCloseDates.map((closeDate, index) => ({
+ id: duplicateDatedOpportunityIds[index],
+ name: `Duplicate dated opportunity ${index + 1}`,
+ closeDate,
+ })),
+ ...duplicateNullOpportunityIds.map((id, index) => ({
+ id,
+ name: `Duplicate undated opportunity ${index + 1}`,
+ })),
+ ],
+ }),
+ ).expect(200);
+ });
+
+ it('should neither skip nor repeat records when the sort value has duplicates', async () => {
+ // Page size 2 lands page boundaries inside the duplicate groups
+ const { ids } = await paginateForward({
+ orderBy: { closeDate: 'AscNullsLast' },
+ first: 2,
+ });
+
+ expect(ids).toHaveLength(duplicatesTotalCount);
+ expect(new Set(ids).size).toBe(duplicatesTotalCount);
+ expect(new Set(ids.slice(duplicatedCloseDates.length))).toEqual(
+ new Set(duplicateNullOpportunityIds),
+ );
+ });
+});
diff --git a/packages/twenty-server/test/integration/rest/suites/rest-api-core-find-many.integration-spec.ts b/packages/twenty-server/test/integration/rest/suites/rest-api-core-find-many.integration-spec.ts
index 4f1a37aad70..5da4fe716c7 100644
--- a/packages/twenty-server/test/integration/rest/suites/rest-api-core-find-many.integration-spec.ts
+++ b/packages/twenty-server/test/integration/rest/suites/rest-api-core-find-many.integration-spec.ts
@@ -376,4 +376,67 @@ describe('Core REST API Find Many endpoint', () => {
path: '/people?depth=2',
}).expect(400);
});
+
+ describe('cursor pagination ordered by a nullable field', () => {
+ const datedOpportunityCloseDates = [
+ '2026-03-01T00:00:00.000Z',
+ '2026-03-02T00:00:00.000Z',
+ '2026-03-03T00:00:00.000Z',
+ ];
+ const opportunityCount = datedOpportunityCloseDates.length + 2;
+
+ beforeAll(async () => {
+ await deleteAllRecords('opportunity');
+
+ for (const [index, closeDate] of datedOpportunityCloseDates.entries()) {
+ await makeRestAPIRequest({
+ method: 'post',
+ path: '/opportunities',
+ body: { name: `REST dated opportunity ${index + 1}`, closeDate },
+ });
+ }
+
+ for (const index of [1, 2]) {
+ await makeRestAPIRequest({
+ method: 'post',
+ path: '/opportunities',
+ body: { name: `REST undated opportunity ${index}` },
+ });
+ }
+ });
+
+ afterAll(async () => {
+ await deleteAllRecords('opportunity');
+ });
+
+ it('should return every record when paginating with starting_after', async () => {
+ const ids: string[] = [];
+ let startingAfter: string | undefined = undefined;
+
+ for (let iteration = 0; iteration < 10; iteration++) {
+ const path: string =
+ '/opportunities?order_by=closeDate[AscNullsLast]&limit=2' +
+ (startingAfter ? `&starting_after=${startingAfter}` : '');
+ const response = await makeRestAPIRequest({
+ method: 'get',
+ path,
+ }).expect(200);
+
+ ids.push(
+ ...response.body.data.opportunities.map(
+ (opportunity: { id: string }) => opportunity.id,
+ ),
+ );
+
+ if (!response.body.pageInfo.hasNextPage) {
+ break;
+ }
+
+ startingAfter = response.body.pageInfo.endCursor;
+ }
+
+ expect(ids).toHaveLength(opportunityCount);
+ expect(new Set(ids).size).toBe(opportunityCount);
+ });
+ });
});