typescript-ds-lib 0.4.5 → 0.4.7

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Artiom Baloian
+Copyright (c) 2026 Artiom Baloian
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,8 +1,9 @@
-# TypeScript Data Structure Library
+# TypeScript Data Structure & Algorithm Library
 [![NPM](https://img.shields.io/npm/v/typescript-ds-lib?label=npm%20package&color=limegreen)](https://www.npmjs.com/package/typescript-ds-lib)
 
-TypeScript data structure implementations without external dependencies. Why to use this library?  
+TypeScript data structure and algorithm implementations with no external dependencies.
 
+**Why to use this library?**  
 - Fully Tested
 - Fast
 - 0 Dependencies
@@ -36,7 +37,7 @@ console.log(stack.size());  // 2
 
 
 ## Documentation and Examples
-See the [documentation](https://github.com/baloian/typescript-ds-lib/blob/master/doc/DOCUMENTATION.md) for more details and examples.
+See the [documentation](https://github.com/baloian/typescript-ds-lib/blob/master/doc/README.md) for more details and examples.
 
 
 ## Data Structures
@@ -54,6 +55,10 @@ See the [documentation](https://github.com/baloian/typescript-ds-lib/blob/master
 - Set
 - Stack
 
+## Algorithms
+- Binary Search (with custom comparator)
+- Levenshtein Distance (calculates the edit distance between two strings)
+- Shuffle (shuffles the array in-place)
 
 ## `Map-Set` vs Native JavaScript `Map-Set`
 The library's `Map` and `Set` data structures are implemented as Red-Black Tree and Binary Search Tree respectively.

package/dist/algorithms/binary-search.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Performs a binary search on a sorted array to locate a target element.
+ *
+ * This function assumes that the input array is sorted in ascending order with respect to the comparison logic.
+ * It accepts an optional comparison function for custom sorting logic; if not provided,
+ * native < and > operators are used.
+ *
+ * @param arr - A sorted array of elements of type T.
+ * @param target - The element to search for within the array.
+ * @param compare - (Optional) A comparison function that returns a negative value if the first argument is less
+ *                  than the second, a positive value if the first is greater, and zero if they are considered equal.
+ * @returns The index of the target element if it is found in the array; otherwise, returns -1.
+ */
+export declare function binarySearch<T>(arr: T[], target: T, compare?: (a: T, b: T) => number): number;

package/dist/algorithms/binary-search.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.binarySearch = binarySearch;
+/**
+ * Performs a binary search on a sorted array to locate a target element.
+ *
+ * This function assumes that the input array is sorted in ascending order with respect to the comparison logic.
+ * It accepts an optional comparison function for custom sorting logic; if not provided,
+ * native < and > operators are used.
+ *
+ * @param arr - A sorted array of elements of type T.
+ * @param target - The element to search for within the array.
+ * @param compare - (Optional) A comparison function that returns a negative value if the first argument is less
+ *                  than the second, a positive value if the first is greater, and zero if they are considered equal.
+ * @returns The index of the target element if it is found in the array; otherwise, returns -1.
+ */
+function binarySearch(arr, target, compare) {
+    let left = 0;
+    let right = arr.length - 1;
+    const cmp = compare ? compare : (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+    while (left <= right) {
+        const mid = left + Math.floor((right - left) / 2);
+        const comparison = cmp(arr[mid], target);
+        if (comparison === 0) {
+            return mid;
+        }
+        if (comparison < 0) {
+            left = mid + 1;
+        }
+        else {
+            right = mid - 1;
+        }
+    }
+    return -1;
+}
+//# sourceMappingURL=binary-search.js.map

package/dist/algorithms/binary-search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binary-search.js","sourceRoot":"","sources":["../../algorithms/binary-search.ts"],"names":[],"mappings":";;AAaA,oCAiBC;AA9BD;;;;;;;;;;;;GAYG;AACH,SAAgB,YAAY,CAAI,GAAQ,EAAE,MAAS,EAAE,OAAgC;IACnF,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,KAAK,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;IAC3B,MAAM,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAI,EAAE,CAAI,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7E,OAAO,IAAI,IAAI,KAAK,EAAE,CAAC;QACrB,MAAM,GAAG,GAAG,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAClD,MAAM,UAAU,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;QACzC,IAAI,UAAU,KAAK,CAAC,EAAE,CAAC;YACrB,OAAO,GAAG,CAAC;QACb,CAAC;QACD,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;YACnB,IAAI,GAAG,GAAG,GAAG,CAAC,CAAC;QACjB,CAAC;aAAM,CAAC;YACN,KAAK,GAAG,GAAG,GAAG,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IACD,OAAO,CAAC,CAAC,CAAC;AACZ,CAAC"}

package/dist/algorithms/levenshtein-distance.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Calculates the Levenshtein distance (edit distance) between two strings.
+ *
+ * The Levenshtein distance is the minimum number of single-character edits
+ * (insertions, deletions, or substitutions) required to transform one string into another.
+ *
+ * This implementation uses space-optimized dynamic programming with O(min(m, n)) space complexity
+ * instead of the naive O(m * n) approach, where m and n are the lengths of the input strings.
+ *
+ * Time complexity: O(m * n)
+ * Space complexity: O(min(m, n))
+ *
+ * @param str1 - The first string to compare.
+ * @param str2 - The second string to compare.
+ * @returns The Levenshtein distance between the two strings (a non-negative integer).
+ *
+ * @example
+ * ```typescript
+ * levenshteinDistance('kitten', 'sitting'); // Returns 3
+ * levenshteinDistance('hello', 'hello'); // Returns 0
+ * levenshteinDistance('', 'abc'); // Returns 3
+ * levenshteinDistance('abc', ''); // Returns 3
+ * ```
+ */
+export declare function levenshteinDistance(str1: string, str2: string): number;

package/dist/algorithms/levenshtein-distance.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.levenshteinDistance = levenshteinDistance;
+/**
+ * Calculates the Levenshtein distance (edit distance) between two strings.
+ *
+ * The Levenshtein distance is the minimum number of single-character edits
+ * (insertions, deletions, or substitutions) required to transform one string into another.
+ *
+ * This implementation uses space-optimized dynamic programming with O(min(m, n)) space complexity
+ * instead of the naive O(m * n) approach, where m and n are the lengths of the input strings.
+ *
+ * Time complexity: O(m * n)
+ * Space complexity: O(min(m, n))
+ *
+ * @param str1 - The first string to compare.
+ * @param str2 - The second string to compare.
+ * @returns The Levenshtein distance between the two strings (a non-negative integer).
+ *
+ * @example
+ * ```typescript
+ * levenshteinDistance('kitten', 'sitting'); // Returns 3
+ * levenshteinDistance('hello', 'hello'); // Returns 0
+ * levenshteinDistance('', 'abc'); // Returns 3
+ * levenshteinDistance('abc', ''); // Returns 3
+ * ```
+ */
+function levenshteinDistance(str1, str2) {
+    // Early termination: if strings are identical, distance is 0
+    if (str1 === str2) {
+        return 0;
+    }
+    // Early termination: if one string is empty, distance is the length of the other
+    if (str1.length === 0) {
+        return str2.length;
+    }
+    if (str2.length === 0) {
+        return str1.length;
+    }
+    // Use the shorter string for the inner dimension to minimize space
+    const [longer, shorter] = str1.length >= str2.length ? [str1, str2] : [str2, str1];
+    const m = longer.length;
+    const n = shorter.length;
+    // Initialize two rows: previous and current
+    // prevRow represents the distances for the previous character of the longer string
+    let prevRow = Array.from({ length: n + 1 }, (_, i) => i);
+    let currRow = new Array(n + 1);
+    // Fill the DP table row by row
+    for (let i = 1; i <= m; i++) {
+        currRow[0] = i; // Cost of deleting all characters up to i in longer string
+        for (let j = 1; j <= n; j++) {
+            // If characters match, no operation needed (take diagonal value)
+            if (longer[i - 1] === shorter[j - 1]) {
+                currRow[j] = prevRow[j - 1];
+            }
+            else {
+                // Take minimum of three operations:
+                // 1. Deletion: prevRow[j] + 1
+                // 2. Insertion: currRow[j - 1] + 1
+                // 3. Substitution: prevRow[j - 1] + 1
+                currRow[j] = Math.min(prevRow[j] + 1, // deletion
+                currRow[j - 1] + 1, // insertion
+                prevRow[j - 1] + 1 // substitution
+                );
+            }
+        }
+        // Swap rows for next iteration
+        [prevRow, currRow] = [currRow, prevRow];
+    }
+    // The result is in prevRow[n] (since we swapped at the end)
+    return prevRow[n];
+}
+//# sourceMappingURL=levenshtein-distance.js.map

package/dist/algorithms/levenshtein-distance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"levenshtein-distance.js","sourceRoot":"","sources":["../../algorithms/levenshtein-distance.ts"],"names":[],"mappings":";;AAwBA,kDA4CC;AApED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,SAAgB,mBAAmB,CAAC,IAAY,EAAE,IAAY;IAC5D,6DAA6D;IAC7D,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,OAAO,CAAC,CAAC;IACX,CAAC;IACD,iFAAiF;IACjF,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IACD,mEAAmE;IACnE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACnF,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC;IACxB,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IACzB,4CAA4C;IAC5C,mFAAmF;IACnF,IAAI,OAAO,GAAa,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IACnE,IAAI,OAAO,GAAa,IAAI,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACzC,+BAA+B;IAC/B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5B,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,2DAA2D;QAC3E,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC5B,iEAAiE;YACjE,IAAI,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;gBACrC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAC9B,CAAC;iBAAM,CAAC;gBACN,oCAAoC;gBACpC,8BAA8B;gBAC9B,mCAAmC;gBACnC,sCAAsC;gBACtC,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CACnB,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EAAO,WAAW;gBAChC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,EAAG,YAAY;gBACjC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAG,eAAe;iBACrC,CAAC;YACJ,CAAC;QACH,CAAC;QACD,+BAA+B;QAC/B,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC1C,CAAC;IACD,4DAA4D;IAC5D,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC"}

package/dist/algorithms/shuffle.d.ts

@@ -0,0 +1 @@
+export declare function shuffle<T>(array: T[]): void;

package/dist/algorithms/shuffle.js

@@ -0,0 +1,20 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shuffle = shuffle;
+const crypto_1 = __importDefault(require("crypto"));
+/*
+* Fisher-Yates shuffle algorithm, Durstenfeld's variant as described in
+* https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle
+*
+* This function shuffles the given array in-place.
+*/
+function shuffle(array) {
+    for (let i = array.length - 1; i > 0; i--) {
+        const j = crypto_1.default.randomInt(0, i + 1);
+        [array[i], array[j]] = [array[j], array[i]];
+    }
+}
+//# sourceMappingURL=shuffle.js.map

package/dist/algorithms/shuffle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shuffle.js","sourceRoot":"","sources":["../../algorithms/shuffle.ts"],"names":[],"mappings":";;;;;AAQA,0BAKC;AAbD,oDAAgC;AAEhC;;;;;EAKE;AACF,SAAgB,OAAO,CAAI,KAAU;IACnC,KAAK,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC1C,MAAM,CAAC,GAAG,gBAAU,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACzC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9C,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -13,3 +13,6 @@ export { Queue } from './lib/queue';
 export { RedBlackTree } from './lib/red-black-tree';
 export { Set } from './lib/set';
 export { Stack } from './lib/stack';
+export { binarySearch } from './algorithms/binary-search';
+export { levenshteinDistance } from './algorithms/levenshtein-distance';
+export { shuffle } from './algorithms/shuffle';

package/dist/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Stack = exports.Set = exports.RedBlackTree = exports.Queue = exports.PriorityQueue = exports.Matrix = exports.Map = exports.LinkedList = exports.Heap = exports.HashTable = exports.LinkedListGraph = exports.MatrixGraph = exports.Deque = exports.BinarySearchTree = void 0;
+exports.shuffle = exports.levenshteinDistance = exports.binarySearch = exports.Stack = exports.Set = exports.RedBlackTree = exports.Queue = exports.PriorityQueue = exports.Matrix = exports.Map = exports.LinkedList = exports.Heap = exports.HashTable = exports.LinkedListGraph = exports.MatrixGraph = exports.Deque = exports.BinarySearchTree = void 0;
 __exportStar(require("./types"), exports);
 var binary_search_tree_1 = require("./lib/binary-search-tree");
 Object.defineProperty(exports, "BinarySearchTree", { enumerable: true, get: function () { return binary_search_tree_1.BinarySearchTree; } });
@@ -44,4 +44,10 @@ var set_1 = require("./lib/set");
 Object.defineProperty(exports, "Set", { enumerable: true, get: function () { return set_1.Set; } });
 var stack_1 = require("./lib/stack");
 Object.defineProperty(exports, "Stack", { enumerable: true, get: function () { return stack_1.Stack; } });
+var binary_search_1 = require("./algorithms/binary-search");
+Object.defineProperty(exports, "binarySearch", { enumerable: true, get: function () { return binary_search_1.binarySearch; } });
+var levenshtein_distance_1 = require("./algorithms/levenshtein-distance");
+Object.defineProperty(exports, "levenshteinDistance", { enumerable: true, get: function () { return levenshtein_distance_1.levenshteinDistance; } });
+var shuffle_1 = require("./algorithms/shuffle");
+Object.defineProperty(exports, "shuffle", { enumerable: true, get: function () { return shuffle_1.shuffle; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,+DAA4D;AAAnD,sHAAA,gBAAgB,OAAA;AACzB,qCAAoC;AAA3B,8FAAA,KAAK,OAAA;AACd,yDAAuD;AAA9C,2GAAA,WAAW,OAAA;AACpB,mEAAgE;AAAvD,oHAAA,eAAe,OAAA;AACxB,+CAA6C;AAApC,uGAAA,SAAS,OAAA;AAClB,mCAAkC;AAAzB,4FAAA,IAAI,OAAA;AACb,iDAA+C;AAAtC,yGAAA,UAAU,OAAA;AACnB,iCAAgC;AAAvB,0FAAA,GAAG,OAAA;AACZ,uCAAsC;AAA7B,gGAAA,MAAM,OAAA;AACf,uDAAqD;AAA5C,+GAAA,aAAa,OAAA;AACtB,qCAAoC;AAA3B,8FAAA,KAAK,OAAA;AACd,uDAAoD;AAA3C,8GAAA,YAAY,OAAA;AACrB,iCAAgC;AAAvB,0FAAA,GAAG,OAAA;AACZ,qCAAoC;AAA3B,8FAAA,KAAK,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,+DAA4D;AAAnD,sHAAA,gBAAgB,OAAA;AACzB,qCAAoC;AAA3B,8FAAA,KAAK,OAAA;AACd,yDAAuD;AAA9C,2GAAA,WAAW,OAAA;AACpB,mEAAgE;AAAvD,oHAAA,eAAe,OAAA;AACxB,+CAA6C;AAApC,uGAAA,SAAS,OAAA;AAClB,mCAAkC;AAAzB,4FAAA,IAAI,OAAA;AACb,iDAA+C;AAAtC,yGAAA,UAAU,OAAA;AACnB,iCAAgC;AAAvB,0FAAA,GAAG,OAAA;AACZ,uCAAsC;AAA7B,gGAAA,MAAM,OAAA;AACf,uDAAqD;AAA5C,+GAAA,aAAa,OAAA;AACtB,qCAAoC;AAA3B,8FAAA,KAAK,OAAA;AACd,uDAAoD;AAA3C,8GAAA,YAAY,OAAA;AACrB,iCAAgC;AAAvB,0FAAA,GAAG,OAAA;AACZ,qCAAoC;AAA3B,8FAAA,KAAK,OAAA;AACd,4DAA0D;AAAjD,6GAAA,YAAY,OAAA;AACrB,0EAAwE;AAA/D,2HAAA,mBAAmB,OAAA;AAC5B,gDAA+C;AAAtC,kGAAA,OAAO,OAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typescript-ds-lib",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "description": "A collection of TypeScript data structure implementations",
   "author": "Artiom Baloian <artiom.baloian@gmail.com>",
   "license": "MIT",
@@ -24,10 +24,10 @@
   },
   "devDependencies": {
     "@types/jest": "^29.5.14",
-    "@types/node": "^22.15.21",
-    "ts-jest": "^29.2.5",
+    "@types/node": "^25.0.3",
+    "ts-jest": "^29.4.1",
     "ts-node": "^10.9.2",
-    "typescript": "^5.8.3"
+    "typescript": "^5.9.3"
   },
   "keywords": [
     "typescript",