feat: add order query parameter

lib/types/query/order.ts

@@ -0,0 +1,68 @@
+import { FieldsType } from './util'
+import { EntryFields, EntrySys } from '../entry'
+import { AssetSys } from '../asset'
+import { ConditionalPick } from 'type-fest'
+import { TagSys } from '../tag'
+
+type SupportedTypes =
+  | EntryFields.Symbol
+  | EntryFields.Integer
+  | EntryFields.Number
+  | EntryFields.Date
+  | EntryFields.Boolean
+  | undefined
+
+type SupportedLinkTypes = EntryFields.AssetLink | EntryFields.EntryLink<any> | undefined
+
+export type OrderFilterPaths<Fields extends FieldsType, Prefix extends string> =
+  | `${Prefix}.${keyof ConditionalPick<Fields, SupportedTypes> & string}`
+  | `-${Prefix}.${keyof ConditionalPick<Fields, SupportedTypes> & string}`
+
+/**
+ * @desc order for entries
+ * @see [documentation]{@link https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/search-parameters/order}
+ */
+export type EntryOrderFilterWithFields<Fields extends FieldsType> = {
+  order?: (
+    | OrderFilterPaths<Fields, 'fields'>
+    | `fields.${keyof ConditionalPick<Fields, SupportedLinkTypes> & string}.sys.id`
+    | `-fields.${keyof ConditionalPick<Fields, SupportedLinkTypes> & string}.sys.id`
+    | OrderFilterPaths<EntrySys, 'sys'>
+    | 'sys.contentType.sys.id'
+    | '-sys.contentType.sys.id'
+  )[]
+}
+
+/**
+ * @desc order for entries
+ * @see [documentation]{@link https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/search-parameters/order}
+ */
+export type EntryOrderFilter = {
+  order?: (
+    | OrderFilterPaths<EntrySys, 'sys'>
+    | 'sys.contentType.sys.id'
+    | '-sys.contentType.sys.id'
+  )[]
+}
+
+/**
+ * @desc order for assets
+ * @see [documentation]{@link https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/search-parameters/order}
+ */
+export type AssetOrderFilter = {
+  order?: (
+    | OrderFilterPaths<AssetSys, 'sys'>
+    | 'fields.file.contentType'
+    | '-fields.file.contentType'
+    | 'fields.file.fileName'
+    | '-fields.file.fileName'
+  )[]
+}
+
+/**
+ * @desc order for tags
+ * @see [documentation]{@link https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/search-parameters/order}
+ */
+export type TagOrderFilter = {
+  order?: (OrderFilterPaths<TagSys, 'sys'> | 'name' | '-name')[]
+}

lib/types/query/query.ts

@@ -12,6 +12,12 @@ import { ReferenceSearchFilters } from './reference'
 import { TagSys } from '../sys'
 import { Metadata } from '../metadata'
 import { TagLink } from '../link'
+import {
+  AssetOrderFilter,
+  EntryOrderFilter,
+  EntryOrderFilterWithFields,
+  TagOrderFilter,
+} from './order'
 
 type FixedPagedOptions = {
   skip?: number
@@ -45,6 +51,7 @@ export type MetadataTagsQueries =
 
 export type EntryFieldsQueries<Fields extends FieldsType> =
   | EntrySelectFilterWithFields<Fields>
+  | EntryOrderFilterWithFields<Fields>
   | ExistenceFilter<Fields, 'fields'>
   | EqualityFilter<Fields, 'fields'>
   | InequalityFilter<Fields, 'fields'>
@@ -59,9 +66,10 @@ export type EntriesQueries<Fields extends FieldsType> =
   | (SysQueries<Pick<EntrySys, 'createdAt' | 'updatedAt' | 'revision' | 'id' | 'type'>> &
       MetadataTagsQueries &
       EntrySelectFilter &
+      EntryOrderFilter &
       FixedQueryOptions &
       FixedPagedOptions &
-      FixedLinkOptions & { order?: string })
+      FixedLinkOptions)
 
 export type EntryQueries = Omit<FixedQueryOptions, 'query'>
 
@@ -70,14 +78,15 @@ export type AssetFieldsQueries<Fields extends FieldsType> = ExistenceFilter<Fiel
   InequalityFilter<Fields, 'fields'> &
   FullTextSearchFilters<Fields, 'fields'> &
   AssetSelectFilter<Fields> &
+  AssetOrderFilter &
   RangeFilters<Fields, 'fields'> &
   SubsetFilters<Fields, 'fields'>
 
 export type AssetQueries<Fields extends FieldsType> = AssetFieldsQueries<Fields> &
   SysQueries<Pick<AssetSys, 'createdAt' | 'updatedAt' | 'revision' | 'id' | 'type'>> &
   MetadataTagsQueries &
   FixedQueryOptions &
-  FixedPagedOptions & { mimetype_group?: AssetMimeType } & { order?: string }
+  FixedPagedOptions & { mimetype_group?: AssetMimeType }
 
 export type TagNameFilters = {
   'name[exists]'?: boolean
@@ -90,4 +99,5 @@ export type TagNameFilters = {
 
 export type TagQueries = TagNameFilters &
   SysQueries<Pick<TagSys, 'createdAt' | 'updatedAt' | 'visibility' | 'id' | 'type'>> &
-  FixedPagedOptions & { order?: string }
+  TagOrderFilter &
+  FixedPagedOptions

test/integration/getEntries.test.ts

@@ -241,7 +241,7 @@ describe('getEntries via chained clients', () => {
 
     test('Gets entries by creation order', async () => {
       const response = await client.getEntries({
-        order: 'sys.createdAt',
+        order: ['sys.createdAt'],
       })
 
       expect(new Date(response.items[0].sys.createdAt).getTime()).toBeLessThan(
@@ -251,7 +251,7 @@ describe('getEntries via chained clients', () => {
 
     test('Gets entries by inverse creation order', async () => {
       const response = await client.getEntries({
-        order: '-sys.createdAt',
+        order: ['-sys.createdAt'],
       })
 
       expect(new Date(response.items[0].sys.createdAt).getTime()).toBeGreaterThan(
@@ -270,7 +270,7 @@ describe('getEntries via chained clients', () => {
      */
     test('Gets entries by creation order and id order', async () => {
       const response = await client.getEntries({
-        order: 'sys.contentType.sys.id,sys.id',
+        order: ['sys.contentType.sys.id', 'sys.id'],
       })
 
       const contentTypeOrder = response.items

test/types/queries/asset-queries.test-d.ts

@@ -123,6 +123,21 @@ expectNotAssignable<DefaultAssetQueries>({
   'sys.unknownProp[nin]': mocks.anyValue,
 })
 
+// order operator
+
+expectAssignable<DefaultAssetQueries>({ order: ['sys.createdAt'] })
+expectNotAssignable<DefaultAssetQueries>({ order: ['sys.unknownProperty'] })
+
+expectAssignable<DefaultAssetQueries>({
+  order: [
+    'fields.file.contentType',
+    '-fields.file.contentType',
+    'fields.file.fileName',
+    '-fields.file.fileName',
+  ],
+})
+expectNotAssignable<DefaultAssetQueries>({ order: ['fields.unknownField'] })
+
 // select operator
 
 expectAssignable<DefaultAssetQueries>({ select: ['sys'] })

test/types/queries/entry-queries.test-d.ts

@@ -232,6 +232,34 @@ expectNotAssignable<EntriesQueries<{ numberField: number; stringArrayField: stri
   'fields.unknownField[nin]': mocks.anyValue,
 })
 
+// order operator
+
+expectAssignable<EntriesQueries<{ someField: string }>>({
+  order: ['sys.createdAt', '-sys.createdAt'],
+})
+expectNotAssignable<EntriesQueries<{ someField: string }>>({ order: ['sys.unknownProperty'] })
+
+expectNotAssignable<EntriesQueries<{ someField: string }>>({ order: ['fields.someField'] })
+expectAssignable<EntriesQueries<{ someField: string }>>({
+  content_type: 'id',
+  order: ['fields.someField', '-fields.someField'],
+})
+expectAssignable<
+  EntriesQueries<{ mediaField: EntryFields.AssetLink; referenceField: EntryFields.EntryLink<any> }>
+>({
+  content_type: 'id',
+  order: [
+    'fields.mediaField.sys.id',
+    '-fields.mediaField.sys.id',
+    'fields.referenceField.sys.id',
+    '-fields.referenceField.sys.id',
+  ],
+})
+expectNotAssignable<EntriesQueries<{ someField: string }>>({
+  content_type: 'id',
+  order: ['fields.unknownField'],
+})
+
 // select operator
 
 expectAssignable<EntriesQueries<{ someField: string }>>({ select: ['sys'] })

test/types/queries/tag-queries.test-d.ts

@@ -115,7 +115,16 @@ expectNotAssignable<TagQueries>({ 'sys.updatedBy[nin]': mocks.anyValue })
 expectNotAssignable<TagQueries>({ 'sys.version[nin]': mocks.anyValue })
 expectNotAssignable<TagQueries>({ 'sys.revision[nin]': mocks.anyValue })
 
+// order operator
+
+expectAssignable<TagQueries>({
+  order: ['sys.id', 'sys.createdAt', 'sys.updatedAt', 'sys.visibility', 'sys.type'],
+})
+expectAssignable<TagQueries>({
+  order: ['-sys.id', '-sys.createdAt', '-sys.updatedAt', '-sys.visibility', '-sys.type'],
+})
+
 // Fixed query filters
 
-expectAssignable<TagQueries>({ skip: 1, limit: 1, order: 'sys.updatedAt' })
+expectAssignable<TagQueries>({ skip: 1, limit: 1 })
 expectNotAssignable<TagQueries>({ locale: 'en' })

test/types/query-types/boolean.test-d.ts

@@ -9,6 +9,7 @@ import { EntrySelectFilterWithFields } from '../../../lib/types/query/select'
 import { SubsetFilters } from '../../../lib/types/query/subset'
 // @ts-ignore
 import * as mocks from '../mocks'
+import { EntryOrderFilterWithFields } from '../../../lib/types/query/order'
 
 expectAssignable<EqualityFilter<{ testField: EntryFields.Boolean }, 'fields'>>({})
 expectType<Required<EqualityFilter<{ testField: EntryFields.Boolean }, 'fields'>>>({
@@ -31,6 +32,11 @@ expectAssignable<Required<RangeFilters<{ testField: EntryFields.Boolean }, 'fiel
 
 expectAssignable<Required<FullTextSearchFilters<{ testField: EntryFields.Boolean }, 'fields'>>>({})
 
+expectAssignable<EntryOrderFilterWithFields<{ testField: EntryFields.Boolean }>>({})
+expectAssignable<Required<EntryOrderFilterWithFields<{ testField: EntryFields.Boolean }>>>({
+  order: ['fields.testField', '-fields.testField'],
+})
+
 expectAssignable<EntrySelectFilterWithFields<{ testField: EntryFields.Boolean }>>({})
 expectAssignable<Required<EntrySelectFilterWithFields<{ testField: EntryFields.Boolean }>>>({
   select: ['fields.testField'],

test/types/query-types/date.test-d.ts

@@ -9,6 +9,7 @@ import { EntrySelectFilterWithFields } from '../../../lib/types/query/select'
 import { SubsetFilters } from '../../../lib/types/query/subset'
 // @ts-ignore
 import * as mocks from '../mocks'
+import { EntryOrderFilterWithFields } from '../../../lib/types/query/order'
 
 expectAssignable<EqualityFilter<{ testField: EntryFields.Date }, 'fields'>>({})
 expectType<Required<EqualityFilter<{ testField: EntryFields.Date }, 'fields'>>>({
@@ -40,6 +41,11 @@ expectType<Required<FullTextSearchFilters<{ testField: EntryFields.Date }, 'fiel
   'fields.testField[match]': mocks.stringValue,
 })
 
+expectAssignable<EntryOrderFilterWithFields<{ testField: EntryFields.Date }>>({})
+expectAssignable<Required<EntryOrderFilterWithFields<{ testField: EntryFields.Date }>>>({
+  order: ['fields.testField', '-fields.testField'],
+})
+
 expectAssignable<EntrySelectFilterWithFields<{ testField: EntryFields.Date }>>({})
 expectAssignable<Required<EntrySelectFilterWithFields<{ testField: EntryFields.Date }>>>({
   select: ['fields.testField'],

test/types/query-types/integer.test-d.ts

@@ -9,6 +9,7 @@ import { EntrySelectFilterWithFields } from '../../../lib/types/query/select'
 import { SubsetFilters } from '../../../lib/types/query/subset'
 // @ts-ignore
 import * as mocks from '../mocks'
+import { EntryOrderFilterWithFields } from '../../../lib/types/query/order'
 
 expectAssignable<EqualityFilter<{ testField: EntryFields.Integer }, 'fields'>>({})
 expectType<Required<EqualityFilter<{ testField: EntryFields.Integer }, 'fields'>>>({
@@ -37,7 +38,13 @@ expectType<Required<RangeFilters<{ testField: EntryFields.Integer }, 'fields'>>>
 
 expectAssignable<Required<FullTextSearchFilters<{ testField: EntryFields.Integer }, 'fields'>>>({})
 
-expectAssignable<EntrySelectFilterWithFields<{ testField: EntryFields.Integer }>>({
+expectAssignable<EntryOrderFilterWithFields<{ testField: EntryFields.Integer }>>({})
+expectAssignable<Required<EntryOrderFilterWithFields<{ testField: EntryFields.Integer }>>>({
+  order: ['fields.testField', '-fields.testField'],
+})
+
+expectAssignable<EntrySelectFilterWithFields<{ testField: EntryFields.Integer }>>({})
+expectAssignable<Required<EntrySelectFilterWithFields<{ testField: EntryFields.Integer }>>>({
   select: ['fields.testField'],
 })
 

test/types/query-types/location.test-d.ts

@@ -9,6 +9,7 @@ import { EntrySelectFilterWithFields } from '../../../lib/types/query/select'
 import { SubsetFilters } from '../../../lib/types/query/subset'
 // @ts-ignore
 import * as mocks from '../mocks'
+import { EntryOrderFilterWithFields } from '../../../lib/types/query/order'
 
 expectAssignable<Required<EqualityFilter<{ testField: EntryFields.Location }, 'fields'>>>({})
 
@@ -42,7 +43,12 @@ expectAssignable<Required<RangeFilters<{ testField: EntryFields.Location }, 'fie
 
 expectAssignable<Required<FullTextSearchFilters<{ testField: EntryFields.Location }, 'fields'>>>({})
 
-expectAssignable<EntrySelectFilterWithFields<{ testField: EntryFields.Location }>>({
+expectNotAssignable<Required<EntryOrderFilterWithFields<{ testField: EntryFields.Location }>>>({
+  order: ['fields.testField'],
+})
+
+expectAssignable<EntrySelectFilterWithFields<{ testField: EntryFields.Location }>>({})
+expectAssignable<Required<EntrySelectFilterWithFields<{ testField: EntryFields.Location }>>>({
   select: ['fields.testField'],
 })
 

test/types/query-types/number.test-d.ts

@@ -9,6 +9,7 @@ import { EntrySelectFilterWithFields } from '../../../lib/types/query/select'
 import { SubsetFilters } from '../../../lib/types/query/subset'
 // @ts-ignore
 import * as mocks from '../mocks'
+import { EntryOrderFilterWithFields } from '../../../lib/types/query/order'
 
 expectAssignable<EqualityFilter<{ testField: EntryFields.Number }, 'fields'>>({})
 expectType<Required<EqualityFilter<{ testField: EntryFields.Number }, 'fields'>>>({
@@ -37,6 +38,11 @@ expectType<Required<RangeFilters<{ testField: EntryFields.Number }, 'fields'>>>(
 
 expectAssignable<Required<FullTextSearchFilters<{ testField: EntryFields.Number }, 'fields'>>>({})
 
+expectAssignable<EntryOrderFilterWithFields<{ testField: EntryFields.Number }>>({})
+expectAssignable<Required<EntryOrderFilterWithFields<{ testField: EntryFields.Number }>>>({
+  order: ['fields.testField', '-fields.testField'],
+})
+
 expectAssignable<EntrySelectFilterWithFields<{ testField: EntryFields.Number }>>({})
 expectAssignable<Required<EntrySelectFilterWithFields<{ testField: EntryFields.Number }>>>({
   select: ['fields.testField'],

test/types/query-types/object.test-d.ts

@@ -1,4 +1,4 @@
-import { expectAssignable, expectType } from 'tsd'
+import { expectAssignable, expectNotAssignable, expectType } from 'tsd'
 import { EntryFields } from '../../../lib'
 import { EqualityFilter, InequalityFilter } from '../../../lib/types/query/equality'
 import { ExistenceFilter } from '../../../lib/types/query/existence'
@@ -7,6 +7,7 @@ import { RangeFilters } from '../../../lib/types/query/range'
 import { FullTextSearchFilters } from '../../../lib/types/query/search'
 import { EntrySelectFilterWithFields } from '../../../lib/types/query/select'
 import { SubsetFilters } from '../../../lib/types/query/subset'
+import { EntryOrderFilterWithFields } from '../../../lib/types/query/order'
 // @ts-ignore
 import * as mocks from '../mocks'
 
@@ -25,6 +26,10 @@ expectAssignable<Required<RangeFilters<{ testField: EntryFields.Object }, 'field
 
 expectAssignable<Required<FullTextSearchFilters<{ testField: EntryFields.Object }, 'fields'>>>({})
 
+expectNotAssignable<EntryOrderFilterWithFields<{ testField: EntryFields.Object }>>({
+  order: ['fields.testField'],
+})
+
 expectAssignable<EntrySelectFilterWithFields<{ testField: EntryFields.Object }>>({})
 expectAssignable<Required<EntrySelectFilterWithFields<{ testField: EntryFields.Object }>>>({
   select: ['fields.testField'],

test/types/query-types/richtext.test-d.ts

@@ -1,4 +1,4 @@
-import { expectAssignable, expectType } from 'tsd'
+import { expectAssignable, expectNotAssignable, expectType } from 'tsd'
 import { EntryFields } from '../../../lib'
 import { EqualityFilter, InequalityFilter } from '../../../lib/types/query/equality'
 import { ExistenceFilter } from '../../../lib/types/query/existence'
@@ -9,6 +9,7 @@ import { EntrySelectFilterWithFields } from '../../../lib/types/query/select'
 import { SubsetFilters } from '../../../lib/types/query/subset'
 // @ts-ignore
 import * as mocks from '../mocks'
+import { EntryOrderFilterWithFields } from '../../../lib/types/query/order'
 
 expectAssignable<Required<EqualityFilter<{ testField: EntryFields.RichText }, 'fields'>>>({})
 
@@ -28,6 +29,10 @@ expectType<Required<FullTextSearchFilters<{ testField: EntryFields.RichText }, '
   'fields.testField[match]': mocks.stringValue,
 })
 
+expectNotAssignable<EntryOrderFilterWithFields<{ testField: EntryFields.Object }>>({
+  order: ['fields.testField'],
+})
+
 expectAssignable<EntrySelectFilterWithFields<{ testField: EntryFields.RichText }>>({})
 expectAssignable<Required<EntrySelectFilterWithFields<{ testField: EntryFields.RichText }>>>({
   select: ['fields.testField'],