typescript-ds-lib 0.4.5 → 0.4.6

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
 [![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 without 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,9 @@ See the [documentation](https://github.com/baloian/typescript-ds-lib/blob/master
 - Set
 - Stack
 
+## Algorithms
+- Binary Search (with custom comparator)
+- 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/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,5 @@ 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 { 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.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,8 @@ 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 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,gDAA+C;AAAtC,kGAAA,OAAO,OAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typescript-ds-lib",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "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",