sort-array-criteria v1.0.1

sort array criteria

This library allows you to semi-automatically sort documents based on specified configuration parameters, with zero dependency with TypeScript support.

Node >=12

You can watch a preview of how the library works in this demo version

Installation

To use Sort Array Criteria in your project, run:

npm install sort-array-criteria
or
yarn add sort-array-criteria

Usage

import { sortingArray } from "sort-array-criteria"; //ESM
//or
const { sortingArray } = require("sort-array-criteria"); //CJS

//example
const documents = [
  {
    newspaperType: "Newspaper",
    authorName: "John Smith",
    articleTitle: "Breaking News",
  },
  {
    newspaperType: "Magazine",
    authorName: "Emily Johnson",
    articleTitle: "Fashion Trends",
  },
  {
    newspaperType: "Newspaper",
    authorName: "John Smith",
    articleTitle: "Sports Section",
  },
  {
    newspaperType: "Magazine",
    authorName: "Sarah Thompson",
    articleTitle: "Healthy Living",
  },
  {
    newspaperType: "Newspaper",
    authorName: "Daniel Wilson",
    articleTitle: "Local Events",
  },
  {
    newspaperType: "Magazine",
    authorName: "Jennifer Adams",
    articleTitle: "Travel Guide",
  },
  {
    newspaperType: "Newspaper",
    authorName: "Matthew Turner",
    articleTitle: "Business News",
  },
  {
    newspaperType: "Magazine",
    authorName: "Olivia Roberts",
    articleTitle: "Art and Culture",
  },
  {
    newspaperType: "Newspaper",
    authorName: "William Thompson",
    articleTitle: "Opinion Piece",
  },
  {
    newspaperType: "Magazine",
    authorName: "Sophia Clark",
    articleTitle: "Entertainment Buzz",
  },
];

const criteria = [
  {
    field: "newspaperType",
    priorities: ["Newspaper", "Magazine"],
  },
  {
    field: "authorName",
    basedOn: { field: "newspaperType", value: "Newspaper" },
    priorities: ["John Smith", "Daniel Wilson", "William Thompson"],
  },
  {
    field: "authorName",
    basedOn: { field: "newspaperType", value: "Magazine" },
    priorities: [
      "Emily Johnson",
      "Sarah Thompson",
      "Jennifer Adams",
      "Olivia Roberts",
      "Sophia Clark",
    ],
  },
  {
    field: "articleTitle",
    basedOn: { field: "newspaperType", value: "Newspaper" },
    priorities: ["Sports Section", "Breaking News"],
  },
];

const sortedDocuments = sortingArray(documents, criteria);

Response

//Example response

[
  {
    newspaperType: "Newspaper",
    authorName: "John Smith",
    articleTitle: "Sports Section",
  },
  {
    newspaperType: "Newspaper",
    authorName: "John Smith",
    articleTitle: "Breaking News",
  },
  {
    newspaperType: "Newspaper",
    authorName: "Daniel Wilson",
    articleTitle: "Local Events",
  },
  {
    newspaperType: "Newspaper",
    authorName: "William Thompson",
    articleTitle: "Opinion Piece",
  },
  {
    newspaperType: "Newspaper",
    authorName: "Matthew Turner",
    articleTitle: "Business News",
  },
  {
    newspaperType: "Magazine",
    authorName: "Emily Johnson",
    articleTitle: "Fashion Trends",
  },
  {
    newspaperType: "Magazine",
    authorName: "Sarah Thompson",
    articleTitle: "Healthy Living",
  },
  {
    newspaperType: "Magazine",
    authorName: "Jennifer Adams",
    articleTitle: "Travel Guide",
  },
  {
    newspaperType: "Magazine",
    authorName: "Olivia Roberts",
    articleTitle: "Art and Culture",
  },
  {
    newspaperType: "Magazine",
    authorName: "Sophia Clark",
    articleTitle: "Entertainment Buzz",
  },
];

Step by step explanation

1. The array 'criteria' specifies the priority rules for reordering the elements in the array 'documents'. Specifically, the criteria are based on three fields: *'newspaperType'*, *'authorName'*, and *'articleTitle'*. These criteria specify the order of priority based on the type of newspaper, the author, and the article title.
2. The function begins by sorting the documents based on the priority of the *'newspaperType'* field, as specified in the rules in 'criteria'. Since *'Newspaper'* has priority over *'Magazine'*, the documents with *'newspaperType'* equal to *'Newspaper'* are sorted first.
3. Subsequently, the function considers the *'authorName'* field based on the specific rule for the type of newspaper. For example, *'John Smith'*, *'Daniel Wilson'*, and *'William Thompson'* are the prioritized authors for the *'Newspaper'* type, while for the *'Magazine'* type, *'Emily Johnson'*, *'Sarah Thompson'*, *'Jennifer Adams'*, *'Olivia Roberts'*, and *'Sophia Clark'* are prioritized.
4. Finally, the function considers the *'articleTitle'* field for the *'Newspaper'* type. The prioritized titles are *"Sports Section"* and *"Breaking News"*.
5. By combining all these rules, the function rearranges the objects in the *'documents'* array according to these specific priorities, producing the sorted array as the result.

Array Sorting Specification Parameters (criteria)

Note: It's not necessary to specify an array of priorities, although it would make little sense not to do so as it would function just like a regular sort. However, you can still pass a parameter of null or an empty array to achieve correct results.

const array = [
  "Sarah Thompson",
  "William Thompson",
  "Emily Johnson",
  "Alan Smith",
];

const sortedDocuments = sortingArray(array, null, { order: "asc" });
// Sorts the array like a regular sort if nothing is specified

["Alan Smith", "Emily Johnson", "Sarah Thompson", "William Thompson"];

Sorting Options (options)

caseInsensitive

const sortedDocuments = semiAutomaticSorting(documents, criteria, {
  caseInsensitive: true,
});

order

const sortedDocuments = semiAutomaticSorting(documents, criteria, {
  order: "asc",
});

customGetValue

Suppose we have a case where the documents contain a complex object for the "name" and for "documents" field, and we want to sort the documents based on the authors' names. We can define a customGetValue function to specifically extract the authors' names from the documents:

const availableFields = [
  { value: "name", type: "author" },
  { value: "documents", type: "publications" },
  // ... other fields available ...
];

const customGetValue = (obj, field) => {
  /*
     Example obj
      obj = {
          name: {firstname: 'Mario', surname: 'Rossi'},
          documents: [{title: 'fsrtDoc', year: 2010}, {title: 'secDoc', year: 2020}],
          // ... other data ...
      };

      Example field
      field = name | documents
  */

  const fieldValue = availableFields.find((f) => f.value === field);

  const { type } = fieldValue || {};

  const value = obj[field];

  if (type === "author") {
    // I just want the name as the calculation value
    return value.firstname;
  } else if (type === "publications") {
    // Please consider only the titles of documents published
    // by the author for a correct calculation
    return value.map((d) => d.title);
  }

  return value;
};

// Example of using the sort function with customGetValue
const sortedDocuments = sortingSemiAutomaticCollectionByConfig(
  documents,
  criteria,
  { customGetValue }
);

The logic defined in "customGetValue" can manipulate the complex object and extract the desired values for sorting. This allows for more precise control over the value extraction logic during the sorting process.

❤️ Support

If you make any profit from this or you just want to encourage me, you can offer me a coffee and I'll try to accommodate you.