feat: add ordering of threads/messages/attachments

docs/docs/reference/enum-types.mdx

@@ -6,6 +6,16 @@ sidebar_position: 32
 
 These are the supported enum types and the possible values that can be used in the configuration.
 
+## AttachmentOrderField
+
+Represents an attachment field to be ordered by for processing.
+
+| Value | Description |
+|-------|-------------|
+| `contentType` | Order by the content type of the attachment. |
+| `hash` | Order by the hash of the attachment. |
+| `name` | Order by the name of the attachment. |
+
 ## ConflictStrategy
 
 Strategy that defines how to deal in case of conflicts with already existing files at the desired location in Google Drive.
@@ -85,6 +95,17 @@ A flag to match messages with certain properties.
 | `unread` | Matches unread messages. |
 | `unstarred` | Matches un-starred messages. |
 
+## MessageOrderField
+
+Represents a message field to be ordered by for processing.
+
+| Value | Description |
+|-------|-------------|
+| `date` | Order by the date of the message. |
+| `from` | Order by the sender of the message. |
+| `id` | Order by the ID of the message. |
+| `subject` | Order by the subject of the message. |
+
 ## MetaInfoType
 
 The type of meta information used for context substitution placeholders.
@@ -97,6 +118,15 @@ The type of meta information used for context substitution placeholders.
 | `string` | A string data type. |
 | `variable` | A custom configuration variable. |
 
+## OrderDirection
+
+Represents the direction a list should be ordered.
+
+| Value | Description |
+|-------|-------------|
+| `asc` | Order ascending. |
+| `desc` | Order descending. |
+
 ## PlaceholderModifierType
 
 The modifiers for placeholder expressions.
@@ -148,3 +178,13 @@ The runtime mode in which processing takes place.
 | `dangerous` | This run-mode will execute all configured actions including possibly destructive actions like overwriting files or removing threads or messages.<br />ATTENTION: Use this only if you know exactly what you're doing and won't complain if something goes wrong! |
 | `dry-run` | This run-mode skips execution of writing actions. Use this for testing config changes or library upgrades. |
 | `safe-mode` | This run-mode can be used for normal operation but will skip possibly destructive actions like overwriting files or removing threads or messages. |
+
+## ThreadOrderField
+
+Represents a thread field to be ordered by for processing.
+
+| Value | Description |
+|-------|-------------|
+| `lastMessageDate` | Order by the date of the last message in the thread. |
+| `id` | Order by the ID of the thread. |
+| `firstMessageSubject` | Order by the subject of the first message in the thread. |

src/lib/config/AttachmentConfig.ts

@@ -12,6 +12,25 @@ import {
   essentialAttachmentMatchConfig,
   newAttachmentMatchConfig,
 } from "./AttachmentMatchConfig"
+import { OrderDirection } from "./CommonConfig"
+
+/**
+ * Represents an attachment field to be ordered by for processing.
+ */
+export enum AttachmentOrderField {
+  /**
+   * Order by the content type of the attachment.
+   */
+  CONTENT_TYPE = "contentType",
+  /**
+   * Order by the hash of the attachment.
+   */
+  HASH = "hash",
+  /**
+   * Order by the name of the attachment.
+   */
+  NAME = "name",
+}
 
 /**
  * Represents a config to handle a certain GMail attachment
@@ -39,6 +58,16 @@ export class AttachmentConfig {
    */
   @Expose()
   name? = ""
+  /**
+   * The field to order attachments by for processing.
+   */
+  @Expose()
+  orderBy?: AttachmentOrderField = undefined
+  /**
+   * The direction to order attachments for processing.
+   */
+  @Expose()
+  orderDirection?: OrderDirection = undefined
 }
 
 export type RequiredAttachmentConfig = RequiredDeep<AttachmentConfig>

src/lib/config/CommonConfig.ts

@@ -0,0 +1,18 @@
+/**
+ * Represents the direction a list should be ordered.
+ */
+export enum OrderDirection {
+  /**
+   * Order ascending.
+   */
+  ASC = "asc",
+  /**
+   * Order descending.
+   */
+  DESC = "desc",
+}
+
+export type OrderableEntityConfig<T extends string> = {
+  orderBy: T
+  orderDirection: OrderDirection
+}

src/lib/config/MessageConfig.ts

@@ -12,12 +12,35 @@ import {
   essentialAttachmentConfig,
   normalizeAttachmentConfigs,
 } from "./AttachmentConfig"
+import { OrderDirection } from "./CommonConfig"
 import {
   MessageMatchConfig,
   essentialMessageMatchConfig,
   newMessageMatchConfig,
 } from "./MessageMatchConfig"
 
+/**
+ * Represents a message field to be ordered by for processing.
+ */
+export enum MessageOrderField {
+  /**
+   * Order by the date of the message.
+   */
+  DATE = "date",
+  /**
+   * Order by the sender of the message.
+   */
+  FROM = "from",
+  /**
+   * Order by the ID of the message.
+   */
+  ID = "id",
+  /**
+   * Order by the subject of the message.
+   */
+  SUBJECT = "subject",
+}
+
 /**
  * Represents a config to handle a certain GMail message
  */
@@ -50,6 +73,16 @@ export class MessageConfig {
    */
   @Expose()
   name? = ""
+  /**
+   * The field to order messages by for processing.
+   */
+  @Expose()
+  orderBy?: MessageOrderField = undefined
+  /**
+   * The direction to order messages for processing.
+   */
+  @Expose()
+  orderDirection?: OrderDirection = undefined
 }
 
 export type RequiredMessageConfig = RequiredDeep<MessageConfig>

src/lib/config/ThreadConfig.ts

@@ -8,6 +8,7 @@ import {
   essentialThreadActionConfig,
 } from "./ActionConfig"
 import { AttachmentConfig, essentialAttachmentConfig } from "./AttachmentConfig"
+import { OrderDirection } from "./CommonConfig"
 import {
   MessageConfig,
   essentialMessageConfig,
@@ -19,6 +20,24 @@ import {
   newThreadMatchConfig,
 } from "./ThreadMatchConfig"
 
+/**
+ * Represents a thread field to be ordered by for processing.
+ */
+export enum ThreadOrderField {
+  /**
+   * Order by the date of the last message in the thread.
+   */
+  DATE = "lastMessageDate",
+  /**
+   * Order by the ID of the thread.
+   */
+  ID = "id",
+  /**
+   * Order by the subject of the first message in the thread.
+   */
+  SUBJECT = "firstMessageSubject",
+}
+
 /**
  * Represents a config handle a certain GMail thread
  */
@@ -57,6 +76,16 @@ export class ThreadConfig {
    */
   @Expose()
   name? = ""
+  /**
+   * The field to order threads by for processing.
+   */
+  @Expose()
+  orderBy?: ThreadOrderField = undefined
+  /**
+   * The direction to order threads for processing.
+   */
+  @Expose()
+  orderDirection?: OrderDirection = undefined
 }
 
 export type RequiredThreadConfig = RequiredDeep<ThreadConfig>

src/lib/config/config-schema-v2.json

@@ -31,6 +31,25 @@
                     "description": "The unique name of the attachment config (will be generated if not set)",
                     "title": "name",
                     "type": "string"
+                },
+                "orderBy": {
+                    "description": "The field to order attachments by for processing.",
+                    "enum": [
+                        "contentType",
+                        "hash",
+                        "name"
+                    ],
+                    "title": "orderBy",
+                    "type": "string"
+                },
+                "orderDirection": {
+                    "description": "The direction to order attachments for processing.",
+                    "enum": [
+                        "asc",
+                        "desc"
+                    ],
+                    "title": "orderDirection",
+                    "type": "string"
                 }
             },
             "title": "AttachmentConfig",
@@ -1548,6 +1567,26 @@
                     "description": "The unique name of the message config (will be generated if not set)",
                     "title": "name",
                     "type": "string"
+                },
+                "orderBy": {
+                    "description": "The field to order messages by for processing.",
+                    "enum": [
+                        "date",
+                        "from",
+                        "id",
+                        "subject"
+                    ],
+                    "title": "orderBy",
+                    "type": "string"
+                },
+                "orderDirection": {
+                    "description": "The direction to order messages for processing.",
+                    "enum": [
+                        "asc",
+                        "desc"
+                    ],
+                    "title": "orderDirection",
+                    "type": "string"
                 }
             },
             "title": "MessageConfig",
@@ -3046,6 +3085,25 @@
                     "description": "The unique name of the thread config (will be generated if not set)",
                     "title": "name",
                     "type": "string"
+                },
+                "orderBy": {
+                    "description": "The field to order threads by for processing.",
+                    "enum": [
+                        "firstMessageSubject",
+                        "id",
+                        "lastMessageDate"
+                    ],
+                    "title": "orderBy",
+                    "type": "string"
+                },
+                "orderDirection": {
+                    "description": "The direction to order threads for processing.",
+                    "enum": [
+                        "asc",
+                        "desc"
+                    ],
+                    "title": "orderDirection",
+                    "type": "string"
                 }
             },
             "title": "ThreadConfig",

src/lib/processors/AttachmentProcessor.spec.ts

@@ -1,12 +1,16 @@
 import { GMailMocks } from "../../test/mocks/GMailMocks"
 import { MockFactory, Mocks } from "../../test/mocks/MockFactory"
 import { ProcessingStatus } from "../Context"
-import { newAttachmentConfig } from "../config/AttachmentConfig"
+import {
+  AttachmentOrderField,
+  newAttachmentConfig,
+} from "../config/AttachmentConfig"
 import {
   AttachmentMatchConfig,
   RequiredAttachmentMatchConfig,
   newAttachmentMatchConfig,
 } from "../config/AttachmentMatchConfig"
+import { OrderDirection } from "../config/CommonConfig"
 import { AttachmentProcessor } from "./AttachmentProcessor"
 
 let mocks: Mocks
@@ -187,3 +191,42 @@ it("should process an attachment entity", () => {
     status: ProcessingStatus.OK,
   })
 })
+
+describe("order attachments", () => {
+  let attachments = [
+    GMailMocks.newAttachmentMock({
+      hash: "a1",
+      name: "2",
+    }),
+    GMailMocks.newAttachmentMock({
+      hash: "a2",
+      name: "1",
+    }),
+    GMailMocks.newAttachmentMock({
+      hash: "a3",
+      name: "3",
+    }),
+  ]
+  it("should order threads ascending", () => {
+    attachments = AttachmentProcessor.ordered(
+      attachments,
+      {
+        orderBy: AttachmentOrderField.NAME,
+        orderDirection: OrderDirection.ASC,
+      },
+      AttachmentProcessor.orderRules,
+    )
+    expect(attachments.map((t) => t.getHash())).toEqual(["a2", "a1", "a3"])
+  })
+  it("should order threads ascending", () => {
+    attachments = AttachmentProcessor.ordered(
+      attachments,
+      {
+        orderBy: AttachmentOrderField.NAME,
+        orderDirection: OrderDirection.DESC,
+      },
+      AttachmentProcessor.orderRules,
+    )
+    expect(attachments.map((t) => t.getHash())).toEqual(["a3", "a1", "a2"])
+  })
+})