arrganizer v0.0.2

Arrganizer Documentation

The Arrganizer class is a utility for organizing, transforming, and formatting data sets. It provides various methods to group, filter, modify, and format data, as well as to manage the history of operations performed on the data. Documentation page is here.

Installation

To install the Arrganizer class, run the following command:

npm i arrganizer

This command installs the Arrganizer package, which includes the Arrganizer class and its dependencies. You can then import and use the class in your TypeScript or JavaScript project as shown in the examples below.

To use the Arrganizer, you need to import it into your TypeScript or JavaScript file.

import { Arrganizer } from 'arrganizer';

Ensure that all dependencies like formatters and utility functions ( formatNumbers , getTimeRange, etc.) are properly implemented and imported in the project.

Constructor

new Arrganizer(data: Data, options?: ArrganizerOptions)

Parameters:

• data : An array of data rows (each row is an object with key-value pairs).

• options : Optional configuration object (ArrganizerOptions), which may include:

• headerDictionary : An optional dictionary for translating header keys. Object, where the key is the original key and the value is the translated text.

  • [key]: string : A key of the original data
  • translated text : The text that replaces the key of the data.

• historySize : The maximum size of the history stack (default: 10).

• cellFormats : An optional mapping of keys to cell formatters. Object that describes which columns should be formatted. Object, where the key is the original key and the value is the formatter name or a custom formatter function.

  • [key]: string : A key of the original data
  • formatter name | custom formatter function : The name of the built-in formatter or a custom formatter function.

• locale : Locale used for formatting (default: "en").

During the documentation used data

[
  {
    "id": 1,
    "name": "John Doe",
    "age": 25,
    "salary": 1000,
    "job": "Developer",
    "dateOfBirth": "1999-04-15"
  },
  {
    "id": 2,
    "name": "Jane Smith",
    "age": 25,
    "salary": 1200,
    "job": "Designer",
    "dateOfBirth": "1999-08-22"
  },
  {
    "id": 3,
    "name": "Emily Johnson",
    "age": 22,
    "salary": 1100,
    "job": "Project Manager",
    "dateOfBirth": "2002-01-10"
  },
  {
    "id": 4,
    "name": "Michael Brown",
    "age": 22,
    "salary": 1500,
    "job": "Engineer",
    "dateOfBirth": "2002-11-05"
  },
  {
    "id": 5,
    "name": "Chris Lee",
    "age": 28,
    "salary": 1300,
    "job": "Data Analyst",
    "dateOfBirth": "1996-03-18"
  },
  {
    "id": 6,
    "name": "Sarah Wilson",
    "age": 32,
    "salary": 1400,
    "job": "Marketing Specialist",
    "dateOfBirth": "1992-07-30"
  },
  {
    "id": 7,
    "name": "David Taylor",
    "age": 29,
    "salary": 1150,
    "job": "Sales Representative",
    "dateOfBirth": "1995-12-11"
  },
  {
    "id": 8,
    "name": "Jessica Clark",
    "age": 26,
    "salary": 1250,
    "job": "Content Writer",
    "dateOfBirth": "1998-09-25"
  },
  {
    "id": 9,
    "name": "Daniel Harris",
    "age": 31,
    "salary": 1350,
    "job": "Consultant",
    "dateOfBirth": "1993-06-07"
  },
  {
    "id": 10,
    "name": "Laura Martinez",
    "age": 27,
    "salary": 1050,
    "job": "Administrative Assistant",
    "dateOfBirth": "1997-02-20"
  }
]

Example #1:

Creating a new Arrganizer class:

const arrganizer = new Arrganizer(data);
const original = arrganizer.getTables();
console.log(original);

Results:

root

Example #2:

const headerDictionary = {
  "dateOfBirth": "Date of Birth",
  "age": "Age",
  "salary": "Salary",
  "job": "Job Title",
  "name": "Worker",
};

const cellFormats = {
  "salary": "usd",
  "name": (name: string) => {
    const [first, last] = name.split(" ");
    return last.toUpperCase() + ", " + first;
  },
};

const arrganizer2 = new Arrganizer(data, {
  headerDictionary, cellFormats})
const translated = arrganizer2.getTables();
console.log(translated);

Results:

root

Methods

getTables(showSummary?: Partial<Record<keyof Summary, boolean): TableData[]

Returns the current data sets as tables, optionally including summary data.

Parameters:

• showSummary: Record<"total" | "min" | "max" | "average" | "length", boolean> : An optional object specifying which summary metrics to display.

  • total : Adds the calculated total to every column, where is is possible.
  • min : Adds the calculated minimum value to every column, where is is possible.
  • max : Adds the calculated maximum value to every column, where is is possible.
  • average : Adds the calculated average value to every column, where is is possible.
  • length : Adds the number of elements to every column.

Returns:

• TableData[] : An array of table data objects.

Example:

  const arrganizer = new Arrganizer(data);
  const tableWithSummary = arrganizer.getTables({
    showSummary: {
      totalRows: true,
      totalAmount: true,
    }
  })
  console.log(tableWithSummary);

Results:

root

getHistory(): DataSet[][]

Returns the history of operations performed on the data.

Returns:

• DataSet[][] : An array of history records.

Example:

const arrganizer = new Arrganizer(data);
arrganizer.sortByKey("age", "asc");
const history = arrganizer.getHistory();
console.log(history);

Results:

[
  [
    {
      "groupName": "root->sortedByKey_age",
      "keys": [
        "id",
        "name",
        "age",
        "salary",
        "job",
        "dateOfBirth"
      ],
      "header": [
        "id",
        "name",
        "age",
        "salary",
        "job",
        "dateOfBirth"
      ],
      "data": [
        {
          "id": 3,
          "name": "Emily Johnson",
          "age": 22,
          "salary": 1100,
          "job": "Project Manager",
          "dateOfBirth": "2002-01-10"
        },
        {
          "id": 4,
          "name": "Michael Brown",
          "age": 22,
          "salary": 1500,
          "job": "Engineer",
          "dateOfBirth": "2002-11-05"
        },
        {
          "id": 1,
          "name": "John Doe",
          "age": 25,
          "salary": 1000,
          "job": "Developer",
          "dateOfBirth": "1999-04-15"
        },
        {
          "id": 2,
          "name": "Jane Smith",
          "age": 25,
          "salary": 1200,
          "job": "Designer",
          "dateOfBirth": "1999-08-22"
        },
        {
          "id": 8,
          "name": "Jessica Clark",
          "age": 26,
          "salary": 1250,
          "job": "Content Writer",
          "dateOfBirth": "1998-09-25"
        },
        {
          "id": 10,
          "name": "Laura Martinez",
          "age": 27,
          "salary": 1050,
          "job": "Administrative Assistant",
          "dateOfBirth": "1997-02-20"
        },
        {
          "id": 5,
          "name": "Chris Lee",
          "age": 28,
          "salary": 1300,
          "job": "Data Analyst",
          "dateOfBirth": "1996-03-18"
        },
        {
          "id": 7,
          "name": "David Taylor",
          "age": 29,
          "salary": 1150,
          "job": "Sales Representative",
          "dateOfBirth": "1995-12-11"
        },
        {
          "id": 9,
          "name": "Daniel Harris",
          "age": 31,
          "salary": 1350,
          "job": "Consultant",
          "dateOfBirth": "1993-06-07"
        },
        {
          "id": 6,
          "name": "Sarah Wilson",
          "age": 32,
          "salary": 1400,
          "job": "Marketing Specialist",
          "dateOfBirth": "1992-07-30"
        }
      ],
      "summary": {
        "total": {
          "id": 55,
          "name": "-",
          "age": 267,
          "salary": 12300,
          "job": "-",
          "dateOfBirth": "-"
        },
        "min": {
          "id": 1,
          "name": "-",
          "age": 22,
          "salary": 1000,
          "job": "-",
          "dateOfBirth": "-"
        },
        "max": {
          "id": 10,
          "name": "-",
          "age": 32,
          "salary": 1500,
          "job": "-",
          "dateOfBirth": "-"
        },
        "average": {
          "id": 5.5,
          "name": "-",
          "age": 26.7,
          "salary": 1230,
          "job": "-",
          "dateOfBirth": "-"
        },
        "length": 10
      }
    }
  ],
  [
    {
      "groupName": "root",
      "keys": [
        "id",
        "name",
        "age",
        "salary",
        "job",
        "dateOfBirth"
      ],
      "header": [
        "id",
        "name",
        "age",
        "salary",
        "job",
        "dateOfBirth"
      ],
      "data": [
        {
          "id": 1,
          "name": "John Doe",
          "age": 25,
          "salary": 1000,
          "job": "Developer",
          "dateOfBirth": "1999-04-15"
        },
        {
          "id": 2,
          "name": "Jane Smith",
          "age": 25,
          "salary": 1200,
          "job": "Designer",
          "dateOfBirth": "1999-08-22"
        },
        {
          "id": 3,
          "name": "Emily Johnson",
          "age": 22,
          "salary": 1100,
          "job": "Project Manager",
          "dateOfBirth": "2002-01-10"
        },
        {
          "id": 4,
          "name": "Michael Brown",
          "age": 22,
          "salary": 1500,
          "job": "Engineer",
          "dateOfBirth": "2002-11-05"
        },
        {
          "id": 5,
          "name": "Chris Lee",
          "age": 28,
          "salary": 1300,
          "job": "Data Analyst",
          "dateOfBirth": "1996-03-18"
        },
        {
          "id": 6,
          "name": "Sarah Wilson",
          "age": 32,
          "salary": 1400,
          "job": "Marketing Specialist",
          "dateOfBirth": "1992-07-30"
        },
        {
          "id": 7,
          "name": "David Taylor",
          "age": 29,
          "salary": 1150,
          "job": "Sales Representative",
          "dateOfBirth": "1995-12-11"
        },
        {
          "id": 8,
          "name": "Jessica Clark",
          "age": 26,
          "salary": 1250,
          "job": "Content Writer",
          "dateOfBirth": "1998-09-25"
        },
        {
          "id": 9,
          "name": "Daniel Harris",
          "age": 31,
          "salary": 1350,
          "job": "Consultant",
          "dateOfBirth": "1993-06-07"
        },
        {
          "id": 10,
          "name": "Laura Martinez",
          "age": 27,
          "salary": 1050,
          "job": "Administrative Assistant",
          "dateOfBirth": "1997-02-20"
        }
      ],
      "summary": {
        "total": {
          "id": 55,
          "name": "-",
          "age": 267,
          "salary": 12300,
          "job": "-",
          "dateOfBirth": "-"
        },
        "min": {
          "id": 1,
          "name": "-",
          "age": 22,
          "salary": 1000,
          "job": "-",
          "dateOfBirth": "-"
        },
        "max": {
          "id": 10,
          "name": "-",
          "age": 32,
          "salary": 1500,
          "job": "-",
          "dateOfBirth": "-"
        },
        "average": {
          "id": 5.5,
          "name": "-",
          "age": 26.7,
          "salary": 1230,
          "job": "-",
          "dateOfBirth": "-"
        },
        "length": 10
      }
    }
  ]
]

getData(): Data

Returns the current data set.

Returns:

• DataSet : The current data set.

Example:

const organizer = new Arrganizer(data);
const dataSet = organizer.getData();
console.log(dataSet);

Results:

[
  {
    "groupName": "root",
    "keys": [
      "id",
      "name",
      "age",
      "salary",
      "job",
      "dateOfBirth"
    ],
    "header": [
      "id",
      "name",
      "age",
      "salary",
      "job",
      "dateOfBirth"
    ],
    "data": [
      {
        "id": 1,
        "name": "John Doe",
        "age": 25,
        "salary": 1000,
        "job": "Developer",
        "dateOfBirth": "1999-04-15"
      },
      {
        "id": 2,
        "name": "Jane Smith",
        "age": 25,
        "salary": 1200,
        "job": "Designer",
        "dateOfBirth": "1999-08-22"
      },
      {
        "id": 3,
        "name": "Emily Johnson",
        "age": 22,
        "salary": 1100,
        "job": "Project Manager",
        "dateOfBirth": "2002-01-10"
      },
      {
        "id": 4,
        "name": "Michael Brown",
        "age": 22,
        "salary": 1500,
        "job": "Engineer",
        "dateOfBirth": "2002-11-05"
      },
      {
        "id": 5,
        "name": "Chris Lee",
        "age": 28,
        "salary": 1300,
        "job": "Data Analyst",
        "dateOfBirth": "1996-03-18"
      },
      {
        "id": 6,
        "name": "Sarah Wilson",
        "age": 32,
        "salary": 1400,
        "job": "Marketing Specialist",
        "dateOfBirth": "1992-07-30"
      },
      {
        "id": 7,
        "name": "David Taylor",
        "age": 29,
        "salary": 1150,
        "job": "Sales Representative",
        "dateOfBirth": "1995-12-11"
      },
      {
        "id": 8,
        "name": "Jessica Clark",
        "age": 26,
        "salary": 1250,
        "job": "Content Writer",
        "dateOfBirth": "1998-09-25"
      },
      {
        "id": 9,
        "name": "Daniel Harris",
        "age": 31,
        "salary": 1350,
        "job": "Consultant",
        "dateOfBirth": "1993-06-07"
      },
      {
        "id": 10,
        "name": "Laura Martinez",
        "age": 27,
        "salary": 1050,
        "job": "Administrative Assistant",
        "dateOfBirth": "1997-02-20"
      }
    ],
    "summary": {
      "total": {
        "id": 55,
        "name": "-",
        "age": 267,
        "salary": 12300,
        "job": "-",
        "dateOfBirth": "-"
      },
      "min": {
        "id": 1,
        "name": "-",
        "age": 22,
        "salary": 1000,
        "job": "-",
        "dateOfBirth": "-"
      },
      "max": {
        "id": 10,
        "name": "-",
        "age": 32,
        "salary": 1500,
        "job": "-",
        "dateOfBirth": "-"
      },
      "average": {
        "id": 5.5,
        "name": "-",
        "age": 26.7,
        "salary": 1230,
        "job": "-",
        "dateOfBirth": "-"
      },
      "length": 10
    }
  }
]

getOriginalData(): Data

The original data set.

Returns:

• DataSet : The current data set.

Example:

const arrganizer = new Arrganizer(data);
const original = arrganizer.getOriginalData();
console.log(original);

Results:

[
  {
    "id": 1,
    "name": "John Doe",
    "age": 25,
    "salary": 1000,
    "job": "Developer",
    "dateOfBirth": "1999-04-15"
  },
  {
    "id": 2,
    "name": "Jane Smith",
    "age": 25,
    "salary": 1200,
    "job": "Designer",
    "dateOfBirth": "1999-08-22"
  },
  {
    "id": 3,
    "name": "Emily Johnson",
    "age": 22,
    "salary": 1100,
    "job": "Project Manager",
    "dateOfBirth": "2002-01-10"
  },
  {
    "id": 4,
    "name": "Michael Brown",
    "age": 22,
    "salary": 1500,
    "job": "Engineer",
    "dateOfBirth": "2002-11-05"
  },
  {
    "id": 5,
    "name": "Chris Lee",
    "age": 28,
    "salary": 1300,
    "job": "Data Analyst",
    "dateOfBirth": "1996-03-18"
  },
  {
    "id": 6,
    "name": "Sarah Wilson",
    "age": 32,
    "salary": 1400,
    "job": "Marketing Specialist",
    "dateOfBirth": "1992-07-30"
  },
  {
    "id": 7,
    "name": "David Taylor",
    "age": 29,
    "salary": 1150,
    "job": "Sales Representative",
    "dateOfBirth": "1995-12-11"
  },
  {
    "id": 8,
    "name": "Jessica Clark",
    "age": 26,
    "salary": 1250,
    "job": "Content Writer",
    "dateOfBirth": "1998-09-25"
  },
  {
    "id": 9,
    "name": "Daniel Harris",
    "age": 31,
    "salary": 1350,
    "job": "Consultant",
    "dateOfBirth": "1993-06-07"
  },
  {
    "id": 10,
    "name": "Laura Martinez",
    "age": 27,
    "salary": 1050,
    "job": "Administrative Assistant",
    "dateOfBirth": "1997-02-20"
  }
]

removeKey(key: keyof DataRow): this

Removes a specified key from the data.

Parameters:

• key : The key to remove.

Example:

const arrganizer = new Arrganizer(data);
arrganizer.removeKey("age");
const remove

Result:

root->removed_age

removeKeys(key: (keyof DataRow)[]): this

Removes a specified keys from the data.

Parameters:

• keys : The keys to remove.

Example:

const arrganizer = new Arrganizer(data);
arrganizer.removeKeys(["id", "age", "dateOfBirth"]);
const removedIdAgeDateOfBirth = arrganizer.getTables();
console.log(removedIdAgeDateOfBirth);

Results:

root->removed_id&age&dateOfBirth

groupByKey(key: keyof DataRow): this

Groups the data by a specified date key in specified time interval.

Parameters:

• timeRange : The interval to group by.

• YEAR : The data grouped yearly.

• MONTH : The data grouped monthly.
• DAY : The data grouped daily.
• HOUR : The data grouped hourly.
• MINUTE : The data grouped in minutes.

• SECOND : The data grouped in seconds.

• key : The key to group by.

Example:

const arrganizer = new Arrganizer(data);
arrganizer.groupByDate("YEAR", "dateOfBirth");
const groupedDateOfBirth = arrganizer.getTables();
console.log(groupedDateOfBirth);

Results:

root->groupedBy_1999

root->groupedBy_2002

root->groupedBy_1996

root->groupedBy_1992

root->groupedBy_1995

root->groupedBy_1998

root->groupedBy_1993

root->groupedBy_1997

groupByKey(key: keyof DataRow): this

Removes a specified key from the data.

Parameters:

• key : The key to group by.

Example:

const arrganizer = new Arrganizer(data);
arrganizer.groupByKey("age");
const groupedAge = arrganizer.getTables();
console.log(groupedAge);

Results:

root->groupedBy_age:25

root->groupedBy_age:22

root->groupedBy_age:28

root->groupedBy_age:32

root->groupedBy_age:29

root->groupedBy_age:26

root->groupedBy_age:31

root->groupedBy_age:27

groupByKeys``(key: (keyofData[0])[]): this

Removes a specified key from the data.

Parameters:

• keys : The keys to group by.

Example:

const arrganizer = new Arrganizer(data);
arrganizer.groupByKeys(["age", "job"]);
const groupedAgeJob = arrganizer.getTables();
console.log(groupedAgeJob);

Results:

root->groupedBy_age:25-job:Developer

root->groupedBy_age:25-job:Designer

root->groupedBy_age:22-job:Project Manager

root->groupedBy_age:22-job:Engineer

root->groupedBy_age:28-job:Data Analyst

root->groupedBy_age:32-job:Marketing Specialist

root->groupedBy_age:29-job:Sales Representative

root->groupedBy_age:26-job:Content Writer

root->groupedBy_age:31-job:Consultant

root->groupedBy_age:27-job:Administrative Assistant

filterByKey(key: keyof DataRow, values: DataRow[T][]): this

Filters the data by a specified key and value.

Parameters:

• key : The key to filter by.
• value : The value to filter for.

Example:

const arrganizer = new Arrganizer(data);
arrganizer.filterByKey("age", [25, 22]);
arrganizer.filterByKey("age", [25]);
const filteredAge = arrganizer.getTables();
console.log(filteredAge);

Results:

root->filtered_age:25&22

contains(key: keyofData[0], value: string | number): this

Filters the rows where the column values contains the given `value`.

Parameters:

• key : The key to check.
• value : The value to check for.

Example:

const arrganizer = new Arrganizer(data);
arrganizer.contains("er");
const contains_eer = arrganizer.getTables();
console.log(contains_eer);

Results:

root->contains_er

modifyValue(key: keyofDataRow, callback: (value: unknown) => unknown): this

Modifies the value for a specific key in the data.

Parameters:

• key : The key to modify.
• callback : The function that makes the modification on the value.

Example:

const arrganizer = new Arrganizer(data);
arrganizer.modifyValue("salary", (salary: number) => Math.ceil(salary * 1.1));
const raisedSalary = arrganizer.getTables();
console.log(raisedSalary);

Results:

root->modified_salary

sortByKey(key: keyof DataRow, direction: "asc" | "desc"): this

Sorts the data by a specified key.

Parameters:

• key : The key to sort by.
• ascending : Optional boolean to specify sorting order (default: "asc" for ascending).

Example:

const arrganizer = new Arrganizer(data);
arrganizer.sortByKey("age");
const sortedAge = arrganizer.getTables();
console.log(sortedAge);

Results:

root->sortedByKey_age

frequencyByKeysValue(keys: (keyof DataRow)[], frequencyKey: string = frequency, aggregateKeys: (keyof DataRow)[] = []): this

Calculates the frequency of each value for the specified keys, using the frequencyKey. Optionally, it can also aggregate additional values provided as an array in the aggregatesKey.

Parameters:

• keys : The keys they with same values counts as one.
• frequencyKey : The key name of the new column that contains the frequency.
• aggregateKeys : Another keys that will be aggregated.

Example:

const arrganizer = new Arrganizer(data);
arrganizer.frequencyByKeysValue(["age"]);
const calculatedAgeGroups = arrganizer.getTables();
console.log(calculatedAgeGroups);

Results:

root

reorderColumns(columnOrder: keyof DataRow, addMissing: boolean = true): this

Reorders the columns of the data rows according to the specified column order. If `addMissing` is true, missing columns will be added to the end of each row in their original order.

Parameters:

• columnOrder : The desired order of columns.
• addMissing : Whether to add missing columns at the end of each row (default is true).

Example #1:

const arrganizer2 = new Arrganizer(data);
arrganizer2.reorderColumns(["age", "id"]);
const reordered = arrganizer2.getTables();
console.log(reordered);

Results:

root->reordered_age-id

Example #2:

const arrganizer = new Arrganizer(data);
arrganizer.reorderColumns(["age", "id"], false);
const reorderedOnlyGiven = arrganizer.getTables();
console.log(reorderedOnlyGiven);

console.log(reorderedOnlyGiven);

root->reordered_age-id

reset(): void

Resets the data to its original state.

Example:

const arrganizer = new Arrganizer(data);
arrganizer.filterByKey("age", [25, 22]);
const tables = arrganizer.getTables();
console.log(tables);
arrganizer.reset();
const resetTables = arrganizer.getTables();
console.log(resetTables);

Results:

console.log(tables)

root->filtered_age:25&22

console.log(resetTables)

root

undo(): void

Undo steps back in the history to the previous state.

Example:

const arrganizer = new Arrganizer(data);
arrganizer.filterByKey("age", [25, 22]);
arrganizer.filterByKey("age", [25]);
const tables = arrganizer.getTables();
console.log(tables);
arrganizer.undo();
const undoTables = arrganizer.getTables();
console.log(undoTables);

Results:

console.log(tables)

root->filtered_age:25&22->filtered_age:25

console.log(undoTables)

root->filtered_age:25&22

undo(): void

Redo steps forward in the history to the next state (if there is a next).

Example:

const arrganizer = new Arrganizer(data);
arrganizer.filterByKey("age", [25, 22]);
arrganizer.filterByKey("age", [25]);
arrganizer.undo();
const undoTables = arrganizer.getTables();
arrganizer.redo();
console.log(undoTables);
const redoTables = arrganizer.getTables();
console.log(redoTables);

Results:

console.log(undoTables)

root->filtered_age:25&22

console.log(redoTables)

root->filtered_age:25&22->filtered_age:25