@cyberismo/data-handler 0.0.2

package/dist/utils/csv.d.ts

@@ -0,0 +1,18 @@
+/**
+    Cyberismo
+    Copyright © Cyberismo Ltd and contributors 2024
+
+    This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License version 3 as published by the Free Software Foundation.
+
+    This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public
+    License along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+import type { CSVRowRaw } from '../interfaces/project-interfaces.js';
+/**
+ * Reads a CSV file and returns its content as an array of objects.
+ * @param file Path to the CSV file.
+ * @returns Array of objects. Each object represents a row in the CSV file.
+ */
+export declare function readCsvFile(file: string): Promise<CSVRowRaw[]>;

package/dist/utils/csv.js

@@ -0,0 +1,45 @@
+/**
+    Cyberismo
+    Copyright © Cyberismo Ltd and contributors 2024
+
+    This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License version 3 as published by the Free Software Foundation.
+
+    This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public
+    License along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+import { readFile } from 'fs/promises';
+import { parse } from 'csv-parse/sync';
+/**
+ * Reads a CSV file and returns its content as an array of objects.
+ * @param file Path to the CSV file.
+ * @returns Array of objects. Each object represents a row in the CSV file.
+ */
+export async function readCsvFile(file) {
+    const content = await readFile(file, {
+        encoding: 'utf-8',
+    });
+    const records = parse(content, {
+        bom: true,
+    });
+    if (!Array.isArray(records) || records.length < 2) {
+        throw new Error('CSV file must have headers');
+    }
+    const [headers, ...data] = records;
+    if (!Array.isArray(headers) ||
+        new Set(headers).size !== headers.length ||
+        headers.length === 0) {
+        throw new Error('Error parsing header');
+    }
+    return data.map((row) => {
+        if (!Array.isArray(row)) {
+            throw new Error('Row is not an array');
+        }
+        return headers.reduce((acc, header, index) => {
+            acc[header] = row[index];
+            return acc;
+        }, {});
+    });
+}
+//# sourceMappingURL=csv.js.map

package/dist/utils/csv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"csv.js","sourceRoot":"","sources":["../../src/utils/csv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;EAUE;AAEF,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAGvC;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAY;IAC5C,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE;QACnC,QAAQ,EAAE,OAAO;KAClB,CAAC,CAAC;IACH,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,EAAE;QAC7B,GAAG,EAAE,IAAI;KACV,CAAC,CAAC;IAEH,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;IAChD,CAAC;IAED,MAAM,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,OAAO,CAAC;IAEnC,IACE,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QACvB,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,MAAM;QACxC,OAAO,CAAC,MAAM,KAAK,CAAC,EACpB,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;IAC1C,CAAC;IAED,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QACtB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;QACzC,CAAC;QACD,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE;YAC3C,GAAG,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC;YACzB,OAAO,GAAG,CAAC;QACb,CAAC,EAAE,EAAE,CAAC,CAAC;IACT,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/utils/file-utils.d.ts

@@ -0,0 +1,69 @@
+/**
+  Cyberismo
+  Copyright © Cyberismo Ltd and contributors 2024
+
+  This program is free software: you can redistribute it and/or modify it under
+  the terms of the GNU Affero General Public License version 3 as published by
+  the Free Software Foundation. This program is distributed in the hope that it
+  will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+  See the GNU Affero General Public License for more details.
+  You should have received a copy of the GNU Affero General Public
+  License along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
+import { writeFile } from 'node:fs/promises';
+/**
+ * Works like the writeFile method, but ensures that the directory exists
+ * There is only one difference: This method only supports a string as the filePath
+ */
+export declare function writeFileSafe(filePath: string, data: Parameters<typeof writeFile>[1], options?: Parameters<typeof writeFile>[2]): Promise<void>;
+/**
+ * Copies directory content (subdirectories and files) to destination.
+ * Note that it won't create 'source', but copies all that is inside of 'source'.
+ * @param source path to start from
+ * @param destination path where to copy to
+ */
+export declare function copyDir(source: string, destination: string): Promise<void>;
+/**
+ * Delete directory.
+ * @param path path to be deleted
+ */
+export declare function deleteDir(path: string): Promise<void>;
+/**
+ * Delete file.
+ * @param path path to file to be deleted
+ * @returns true, if file was deleted; false otherwise.
+ */
+export declare function deleteFile(path: string): Promise<boolean>;
+/**
+ * Removes extension from filename.
+ * @param filename Filename
+ * @returns filename without extension. If there was no extension, returns the original filename.
+ */
+export declare function stripExtension(filename: string): string;
+/**
+ * Lists all files from a folder.
+ * @param path path to folder
+ * @param pathPrefix relative adjustment to 'path', if any; optional; by default empty.
+ * @param files currently collected files; optional; by default empty.
+ * @returns array of filenames that are in the folder or in one of its subfolders.
+ * @note that 'pathPrefix' and 'files' are generally only used in internal recursion.
+ *       When calling this from code, do not pass the parameters.
+ */
+export declare function getFilesSync(path: string, pathPrefix?: string, files?: string[]): string[];
+/**
+ * Checks if file or folder exists.
+ * @param path file or folder path
+ * @returns true if file exists, otherwise false
+ */
+export declare function pathExists(path: string): boolean;
+/**
+ * Handles tilde from a path (ie. appends user home to its place).
+ * @param filePath Path to handle tilde from.
+ * @returns Path with tilde resolved.
+ */
+export declare function resolveTilde(filePath: string): string;
+/**
+ * Path separator RE.
+ */
+export declare const sepRegex: RegExp;

package/dist/utils/file-utils.js

@@ -0,0 +1,158 @@
+/**
+  Cyberismo
+  Copyright © Cyberismo Ltd and contributors 2024
+
+  This program is free software: you can redistribute it and/or modify it under
+  the terms of the GNU Affero General Public License version 3 as published by
+  the Free Software Foundation. This program is distributed in the hope that it
+  will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+  See the GNU Affero General Public License for more details.
+  You should have received a copy of the GNU Affero General Public
+  License along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
+import { copyFile, mkdir, readdir, rm, unlink, writeFile, } from 'node:fs/promises';
+import { existsSync, readdirSync } from 'node:fs';
+import { dirname, join, sep } from 'node:path';
+import { homedir } from 'node:os';
+/**
+ * Works like the writeFile method, but ensures that the directory exists
+ * There is only one difference: This method only supports a string as the filePath
+ */
+export async function writeFileSafe(filePath, data, options) {
+    const dir = dirname(filePath);
+    await mkdir(dir, {
+        recursive: true,
+    });
+    return writeFile(filePath, data, options);
+}
+/**
+ * Copies directory content (subdirectories and files) to destination.
+ * Note that it won't create 'source', but copies all that is inside of 'source'.
+ * @param source path to start from
+ * @param destination path where to copy to
+ */
+export async function copyDir(source, destination) {
+    const entries = await readdir(source, { withFileTypes: true });
+    for (const entry of entries) {
+        const sourcePath = join(source, entry.name);
+        const destinationPath = join(destination, entry.name);
+        if (entry.isDirectory()) {
+            await mkdir(destinationPath, { recursive: true });
+            await copyDir(sourcePath, destinationPath);
+        }
+        else {
+            await mkdir(destination, { recursive: true });
+            await copyFile(sourcePath, destinationPath);
+        }
+    }
+}
+/**
+ * Delete directory.
+ * @param path path to be deleted
+ */
+export async function deleteDir(path) {
+    await rm(resolveTilde(path), { recursive: true, force: true });
+}
+/**
+ * Delete file.
+ * @param path path to file to be deleted
+ * @returns true, if file was deleted; false otherwise.
+ */
+export async function deleteFile(path) {
+    if (!path) {
+        return false;
+    }
+    try {
+        await unlink(path);
+    }
+    catch {
+        console.error(`Cannot delete file '${path}'`);
+        return false;
+    }
+    return true;
+}
+/**
+ * Removes extension from filename.
+ * @param filename Filename
+ * @returns filename without extension. If there was no extension, returns the original filename.
+ */
+export function stripExtension(filename) {
+    // First handle special cases. Just return the filename in all of these cases.
+    // 1) If the filename ends to "."" or ".." (e.g. ".cards/local/..")
+    const parts = filename.split(sep);
+    if (parts.at(parts.length - 1) === '..' ||
+        parts.at(parts.length - 1) === '.') {
+        return filename;
+    }
+    const dotLocation = filename.lastIndexOf('.');
+    const sepLocation = filename.lastIndexOf(sep);
+    // 2) If there is a dot in the filename before sep (e.g. ".cards/local")
+    if (dotLocation < sepLocation) {
+        return filename;
+    }
+    // 3) If there is a dot in filename but it is not an actual extension (e.g. "test/.filename", or ".filename")
+    if (dotLocation === 0 || filename.at(dotLocation - 1) === sep) {
+        return filename;
+    }
+    const noExtension = filename.split('.').slice(0, -1).join('.');
+    // if there was no extension at all, return the original file name.
+    return noExtension ? noExtension : filename;
+}
+/**
+ * Lists all files from a folder.
+ * @param path path to folder
+ * @param pathPrefix relative adjustment to 'path', if any; optional; by default empty.
+ * @param files currently collected files; optional; by default empty.
+ * @returns array of filenames that are in the folder or in one of its subfolders.
+ * @note that 'pathPrefix' and 'files' are generally only used in internal recursion.
+ *       When calling this from code, do not pass the parameters.
+ */
+export function getFilesSync(path, pathPrefix = '', files = []) {
+    try {
+        for (const entry of readdirSync(path, { withFileTypes: true })) {
+            const relativePath = pathPrefix
+                ? join(pathPrefix, entry.name)
+                : entry.name;
+            if (entry.isFile()) {
+                files.push(relativePath);
+            }
+            else if (entry.isDirectory()) {
+                getFilesSync(join(path, entry.name), relativePath, files);
+            }
+        }
+    }
+    catch {
+        // do nothing, wrong path, or no permissions to read the files
+    }
+    return files;
+}
+/**
+ * Checks if file or folder exists.
+ * @param path file or folder path
+ * @returns true if file exists, otherwise false
+ */
+export function pathExists(path) {
+    path = resolveTilde(path);
+    return existsSync(path);
+}
+/**
+ * Handles tilde from a path (ie. appends user home to its place).
+ * @param filePath Path to handle tilde from.
+ * @returns Path with tilde resolved.
+ */
+export function resolveTilde(filePath) {
+    if (!filePath || typeof filePath !== 'string') {
+        return '';
+    }
+    // '~/folder/path' or '~' not '~alias/folder/path'
+    if (filePath.startsWith('~/') || filePath === '~') {
+        return filePath.replace('~', homedir());
+    }
+    return filePath;
+}
+/**
+ * Path separator RE.
+ */
+export const sepRegex = /[/\\]/;
+//# sourceMappingURL=file-utils.js.map

package/dist/utils/file-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-utils.js","sourceRoot":"","sources":["../../src/utils/file-utils.ts"],"names":[],"mappings":"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"}

package/dist/utils/json.d.ts

@@ -0,0 +1,61 @@
+/**
+  Cyberismo
+  Copyright © Cyberismo Ltd and contributors 2024
+
+  This program is free software: you can redistribute it and/or modify it under
+  the terms of the GNU Affero General Public License version 3 as published by
+  the Free Software Foundation. This program is distributed in the hope that it
+  will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+  See the GNU Affero General Public License for more details.
+  You should have received a copy of the GNU Affero General Public
+  License along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
+import { type FileHandle } from 'node:fs/promises';
+/**
+ * Handles reading of a JSON file.
+ * @param file file name (and path) to read.
+ * @returns Parsed JSON content.
+ * @throws if file is not found, or file is not a JSON file.
+ */
+export declare function readJsonFileSync(file: string): any;
+/**
+ * Handles reading of a JSON file.
+ * @param file file name (and path) to read.
+ * @returns Parsed JSON content.
+ * @throws if file is not found, or file is not a JSON file.
+ */
+export declare function readJsonFile(file: string): Promise<any>;
+/**
+ * Reads ADOC file.
+ * @param file file name (and path) to read.
+ * @returns ADOC file content.
+ * @throws if file is not found.
+ */
+export declare function readADocFileSync(file: string): string;
+/**
+ * Removes leading or trailing whitespace
+ * Can be passed to JSON.stringify method
+ * @param _ First parameter is key of object, but it is not used
+ * @param value Value of the json object
+ * @returns JSON object with values trimmed for leading or trailing white space.
+ */
+export declare function trimReplacer(_: string, value: unknown): unknown;
+/**
+ * Format an object with JSON.stringify
+ *
+ * The purpose of this function is to format the JSON output in a centralised function
+ * so that the format can be controlled in a single location.
+ *
+ * @param json JSON object to format.
+ * @returns Formatted JSON string
+ */
+export declare function formatJson(json: object): string;
+/**
+ * Writes and formats a JSON file.
+ * @param filename file name (and path) to write.
+ * @param json JSON object to format.
+ * @param options Optional, write options
+ * @return true if write succeeded, false otherwise.
+ */
+export declare function writeJsonFile(filename: string | FileHandle, json: object, options?: object): Promise<boolean>;

package/dist/utils/json.js

@@ -0,0 +1,108 @@
+/**
+  Cyberismo
+  Copyright © Cyberismo Ltd and contributors 2024
+
+  This program is free software: you can redistribute it and/or modify it under
+  the terms of the GNU Affero General Public License version 3 as published by
+  the Free Software Foundation. This program is distributed in the hope that it
+  will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+  See the GNU Affero General Public License for more details.
+  You should have received a copy of the GNU Affero General Public
+  License along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
+import { readFileSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+/**
+ * Handles reading of a JSON file.
+ * @param file file name (and path) to read.
+ * @returns Parsed JSON content.
+ * @throws if file is not found, or file is not a JSON file.
+ */
+export function readJsonFileSync(file) {
+    try {
+        const raw = readFileSync(file, { flag: 'rs', encoding: 'utf-8' });
+        const returnValue = JSON.parse(raw);
+        return returnValue;
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            throw new Error(`Error while handling JSON file '${file}' : ${error.message}`);
+        }
+    }
+}
+/**
+ * Handles reading of a JSON file.
+ * @param file file name (and path) to read.
+ * @returns Parsed JSON content.
+ * @throws if file is not found, or file is not a JSON file.
+ */
+export async function readJsonFile(file) {
+    try {
+        const raw = await readFile(file, { encoding: 'utf-8' });
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            throw new Error(`Error while handling JSON file '${file}' : ${error.message}`);
+        }
+    }
+}
+/**
+ * Reads ADOC file.
+ * @param file file name (and path) to read.
+ * @returns ADOC file content.
+ * @throws if file is not found.
+ */
+export function readADocFileSync(file) {
+    try {
+        const raw = readFileSync(file, { encoding: 'utf-8' });
+        return raw;
+    }
+    catch {
+        throw new Error(`Adoc file '${file}' not found`);
+    }
+}
+/**
+ * Removes leading or trailing whitespace
+ * Can be passed to JSON.stringify method
+ * @param _ First parameter is key of object, but it is not used
+ * @param value Value of the json object
+ * @returns JSON object with values trimmed for leading or trailing white space.
+ */
+export function trimReplacer(_, value) {
+    if (typeof value === 'string') {
+        return value.trim();
+    }
+    return value;
+}
+/**
+ * Format an object with JSON.stringify
+ *
+ * The purpose of this function is to format the JSON output in a centralised function
+ * so that the format can be controlled in a single location.
+ *
+ * @param json JSON object to format.
+ * @returns Formatted JSON string
+ */
+export function formatJson(json) {
+    return JSON.stringify(json, trimReplacer, 4);
+}
+/**
+ * Writes and formats a JSON file.
+ * @param filename file name (and path) to write.
+ * @param json JSON object to format.
+ * @param options Optional, write options
+ * @return true if write succeeded, false otherwise.
+ */
+export async function writeJsonFile(filename, json, options) {
+    try {
+        await writeFile(filename, formatJson(json), options);
+        return true;
+    }
+    catch {
+        // do nothing, file didn't exist, or no permissions to write
+    }
+    return false;
+}
+//# sourceMappingURL=json.js.map

package/dist/utils/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../../src/utils/json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;EAYE;AAEF,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAmB,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAExE;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;QAClE,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACpC,OAAO,WAAW,CAAC;IACrB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CACb,mCAAmC,IAAI,OAAO,KAAK,CAAC,OAAO,EAAE,CAC9D,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAY;IAC7C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;QACxD,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CACb,mCAAmC,IAAI,OAAO,KAAK,CAAC,OAAO,EAAE,CAC9D,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;QACtD,OAAO,GAAG,CAAC;IACb,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,cAAc,IAAI,aAAa,CAAC,CAAC;IACnD,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,CAAS,EAAE,KAAc;IACpD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC;IACtB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,QAA6B,EAC7B,IAAY,EACZ,OAAgB;IAEhB,IAAI,CAAC;QACH,MAAM,SAAS,CAAC,QAAQ,EAAE,UAAU,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;QACrD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,4DAA4D;IAC9D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/utils/lexorank.d.ts

@@ -0,0 +1,59 @@
+export declare const FIRST_RANK: string;
+export declare const LAST_RANK: string;
+export declare const EMPTY_RANK: string;
+type Rank = string;
+/**
+ * Convert a number to base 26
+ * @param num number to convert to base 26
+ * @returns the string representation of the number in base 26
+ */
+export declare function enbase(num: number): string;
+/**
+ * Convert a rank to a number
+ * @param str rank to convert to a number
+ * @returns the number representation of the rank
+ */
+export declare function debase(str: string): number;
+/**
+ * Returns the next available rank after the given rank
+ * @param rank rank to get the next rank after
+ * @returns the next available rank after the given rank
+ */
+export declare function getRankAfter(rank: Rank): Rank;
+/**
+ * Returns the previous available rank before the given rank
+ * if the rank is already the first rank, it throws an error
+ * @param rank rank to get the previous rank before
+ * @returns the previous available rank before the given rank
+ */
+export declare function getRankBefore(rank: Rank): Rank;
+/**
+ * Get the rank between two ranks
+ * Rank is a string that represents a number in base 26
+ * Rank must be a string of lowercase letters
+ * @param rank1 first rank
+ * @param rank2 second rank
+ * @returns the rank between the two ranks
+ */
+export declare function getRankBetween(rank1: string, rank2: string): string;
+/**
+ * Rebalance the ranks so that the distance between each rank is equal
+ * @param rankAmount number of ranks to rebalance
+ * @returns rebalanced ranks
+ */
+export declare function rebalanceRanks(rankAmount: number): string[];
+/**
+ * Sort items based on lexorank
+ * @param items items to sort
+ * @param rankGetter should return the lexorank of the item
+ * @returns sorted items
+ */
+export declare function sortItems<T>(items: T[], rankGetter: (item: T) => string): T[];
+/**
+ * default compare function
+ * @param a first string
+ * @param b second string
+ * @returns -1 if a < b, 0 if a === b, 1 if a > b
+ */
+export declare function compare(a: string, b: string): number;
+export {};