circular-history 1.0.0

package/.husky/pre-commit

@@ -0,0 +1 @@
+pnpm prettier

package/.husky/pre-push

@@ -0,0 +1 @@
+pnpm prettier

package/.nvmrc

@@ -0,0 +1 @@
+v22.20.0

package/.prettierignore

@@ -0,0 +1,3 @@
+node_modules
+pnpm-lock.yaml
+dist

package/.prettierrc.json

@@ -0,0 +1,7 @@
+{
+  "semi": true,
+  "trailingComma": "all",
+  "singleQuote": false,
+  "tabWidth": 2,
+  "printWidth": 100
+}

package/LICENCE

@@ -0,0 +1,20 @@
+MIT Licence
+
+Copyright (c) Ihor ZAVIRIUKHA <ihor.zaviriukha@protonmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy 
+of this software and associated documentation files (the "Software"), to deal 
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+# Circular History
+
+Data structure that holds a fixed amount of items of a specific data type. It's designed more for managing history, such as undo-redo functionality, therefore it allows you to overwrite the items after moving backward in order to discard the "redo" history.
+
+## Usage
+
+### 1. Create an instance of `CircularHistory` with a specified capacity and data type.
+
+```javascript
+var history = new CircularHistory(5, "string");
+```
+
+### 2. Commit new items to the history.
+
+```javascript
+history.commit("First");
+history.commit("Second");
+```
+
+Keep in mind that after moving backward, committing a new item will overwrite the items ahead of the current index.
+It was designed this way to facilitate undo-redo functionality by discarding the "redo" history when a new action is taken.
+
+When the capacity is reached, the oldest items will be overwritten in a circular manner.
+
+### 3. Get the current item.
+
+```javascript
+var currentItem = history.current();
+```
+
+Returns either the current item or `CircularHistory.FLAGS.empty` if current index is `-1` which means there are no committed items yet or you went backwards beyond the first committed item (basically an empty state).
+
+### 4. Move backward and forward in the history.
+
+```javascript
+history.moveBackward();
+history.moveForward();
+```
+
+Moving backward and forward will adjust the current index accordingly and allow you to navigate within specific range which is determined by the number of committed items before navigation. If the number of committed items exceeds the capacity, the range will be limited to the capacity.
+
+### 5. Clear the history.
+
+```javascript
+history.clear();
+```
+
+### 6. Get the history array.
+
+```javascript
+var historyArray = history.dump();
+```
+
+This will return an array of all committed items in the history. If capacity has not been reached, the array will contain items with `undefined` values for uncommitted slots.
+
+If you want to get only the committed items, you can pass `true` as an argument.
+
+```javascript
+var committedItems = history.dump(true);
+```
+
+### 7. Get the current index.
+
+```javascript
+var currentIndex = history.getCurrentIndex();
+```
+
+### 8. Determine if start/end has been reached
+
+```javascript
+var isAtStart = history.isStartReached();
+var isAtEnd = history.isEndReached();
+```
+
+## Running tests
+
+1. `pnpm install`
+
+2. `pnpm test`
+
+## Usage example
+
+Imagine that you have a drawing application. You have a layer where you can draw
+shapes and you can create a snapshot of the layer's state to keep track of changes.
+
+```javascript
+var history = new CircularHistory(50, "string");
+
+function commitHistorySnapshot() {
+  const snapshot = drawLayer.toJSON();
+  if (!snapshot) return;
+  history.commit(snapshot);
+}
+
+function restoreHistorySnapshot(snapshot) {
+  if (!snapshot) return;
+
+  if (snapshot === CircularHistory.FLAGS.empty) {
+    drawLayer.clear();
+    drawLayer.redraw();
+    return;
+  }
+
+  drawLayer.unmount();
+
+  const restoredLayer = new Layer(snapshot);
+  drawLayer = restoredLayer;
+
+  restoredLayer.redraw();
+}
+
+function undo() {
+  history.moveBackward();
+  restoreHistorySnapshot(history.current());
+}
+
+function redo() {
+  history.moveForward();
+  restoreHistorySnapshot(history.current());
+}
+```

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "circular-history",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "description": "Data structure with a fixed number of items of a specific type. Supports adding elements, moving backward and forward with wrapping. Suitable for undo/redo implementations such as history management.",
+  "scripts": {
+    "test": "vitest .",
+    "prettier": "prettier --check .",
+    "prettier:fix": "prettier --write .",
+    "build": "esbuild src/circular-history.js --bundle --packages=external --format=esm --minify --keep-names --outfile=./dist/index.js",
+    "prepare": "husky",
+    "prepare-release": "pnpm build && node ./scripts/prepare-release.js"
+  },
+  "devDependencies": {
+    "esbuild": "^0.27.2",
+    "husky": "^9.1.7",
+    "prettier": "^3.8.0",
+    "vite": "npm:rolldown-vite@7.2.5",
+    "vitest": "^4.0.17"
+  },
+  "pnpm": {
+    "overrides": {
+      "vite": "npm:rolldown-vite@7.2.5"
+    }
+  }
+}

package/scripts/prepare-release.js

@@ -0,0 +1,13 @@
+import fs from "fs";
+
+fs.copyFile("README.md", "./dist/README.md", (err) => {
+  if (err) throw err;
+  console.log("REAME.md was copied to dist folder");
+});
+
+fs.copyFile("./src/index.d.ts", "./dist/index.d.ts", (err) => {
+  if (err) throw err;
+  console.log("index.d.ts was copied to dist folder");
+  console.log("-----------------------------");
+  console.log("UPDATE THE VERSION IN package.json");
+});

package/src/circular-history.js

@@ -0,0 +1,185 @@
+/**
+ * #Config
+ */
+
+/**
+ * @description
+ * List of data types that are allowed to be stored in the items.
+ * All items should be of the same data type.
+ */
+var ALLOWED_DATA_TYPES = ["number", "string", "bigint", "boolean", "symbol", "object"];
+
+var NAVIGATION_LOWER_BOUND = 0;
+var EMPTY_POINTER = -1;
+
+/**
+ * @description
+ * List of values that can be returned by the CircularHistory methods
+ */
+var FLAGS = {
+  empty: Symbol("empty"),
+};
+
+/**
+ * #Utils
+ */
+
+var isTypeAllowed = (type) => ALLOWED_DATA_TYPES.includes(type);
+
+var isValueTypeAllowed = (value) => {
+  var valueType = typeof value;
+  var isObject = valueType === "object" && value !== null;
+  return isObject || isTypeAllowed(valueType);
+};
+
+var canCommit = (value, dataType) => isValueTypeAllowed(value) && typeof value === dataType;
+var isItemEmpty = (slot) => slot === undefined;
+var makeIndex = (pointer, capacity) => pointer % capacity;
+
+/**
+ * #State
+ *
+ * @description
+ * Using WeakMap to store private state in order to not expose private properties.
+ * This will ensure that the reference to the state will be dropped when instances
+ * are garbage collected.
+ */
+var STATE = new WeakMap();
+
+/**
+ * @description
+ *
+ * Circular History
+ *
+ * Data structure that holds a fixed amount of items of a specific data type.
+ * Supports committing new items, and moving backward and forward through the committed items.
+ * When the buffer is full the wrapping occurs and the oldest items are overwritten.
+ * After moving backward, new commits will overwrite the items ahead of the current pointer which
+ * makes this data structure suitable for undo-redo implementations like history management.
+ *
+ * @param {number} capacity - Maximum amount of items in the buffer
+ * @param {string} dataType - Data type of each slot
+ */
+function CircularHistory(capacity, dataType) {
+  if (typeof capacity !== "number" || capacity <= 0 || !Number.isInteger(capacity)) {
+    throw new Error(`Capacity must be a positive integer. Got "${capacity}".`);
+  }
+
+  if (!isTypeAllowed(dataType)) {
+    throw new Error(`"${dataType}" is not allowed`);
+  }
+
+  STATE.set(this, {
+    /**
+     * Represents range [0, navigationUpperBound] of how many items can be used
+     * for navigation.
+     */
+    navigationUpperBound: NAVIGATION_LOWER_BOUND,
+
+    /**
+     * Represents current index within the navigation range [0, navigationUpperBound].
+     */
+    navigationIndex: NAVIGATION_LOWER_BOUND,
+
+    /**
+     * Current pointer. It does not point to an index in the buffer directly.
+     * It is used to calculate the index in the buffer using modulo operation.
+     */
+    pointer: EMPTY_POINTER,
+
+    /**
+     * Total maximum amount of items.
+     */
+    capacity: capacity,
+
+    /**
+     * Data type of each slot.
+     */
+    dataType: dataType,
+
+    /**
+     * Array of items.
+     * Should always be pre-allocated with capacity.
+     */
+    buffer: new Array(capacity),
+  });
+}
+
+CircularHistory.prototype.commit = function (value) {
+  var self = STATE.get(this);
+  var dataType = self.dataType;
+
+  if (!canCommit(value, dataType)) {
+    throw new Error(
+      `Type of ${value} is invalid. Expected "${dataType}", got "${value === null ? "null" : typeof value}".`,
+    );
+  }
+
+  var capacity = self.capacity;
+
+  if (self.pointer === self.capacity - 1) {
+    self.navigationUpperBound = capacity - 1;
+    self.navigationIndex = capacity - 1;
+  } else {
+    self.navigationIndex = ++self.navigationUpperBound;
+  }
+  self.buffer[makeIndex(++self.pointer, capacity)] = value;
+};
+
+CircularHistory.prototype.current = function () {
+  var self = STATE.get(this);
+  var buffer = self.buffer;
+
+  var pointer = self.pointer;
+  if (pointer === EMPTY_POINTER) return FLAGS.empty;
+  var nextItem = buffer[makeIndex(pointer, self.capacity)];
+
+  return isItemEmpty(nextItem) ? FLAGS.empty : nextItem;
+};
+
+CircularHistory.prototype.moveBackward = function () {
+  var self = STATE.get(this);
+  if (self.navigationIndex === NAVIGATION_LOWER_BOUND || self.pointer === EMPTY_POINTER) return;
+  self.pointer--;
+  self.navigationIndex--;
+};
+
+CircularHistory.prototype.moveForward = function () {
+  var self = STATE.get(this);
+  if (self.navigationIndex === self.navigationUpperBound) return;
+  self.pointer++;
+  self.navigationIndex++;
+};
+
+CircularHistory.prototype.clear = function () {
+  var self = STATE.get(this);
+  self.navigationIndex = NAVIGATION_LOWER_BOUND;
+  self.navigationUpperBound = NAVIGATION_LOWER_BOUND;
+  self.pointer = EMPTY_POINTER;
+  self.buffer = new Array(self.capacity);
+};
+
+CircularHistory.prototype.dump = function (discardHoles = false) {
+  var self = STATE.get(this);
+  var result = [...self.buffer];
+  return discardHoles ? result.filter((slot) => !isItemEmpty(slot)) : result;
+};
+
+CircularHistory.prototype.getCurrentIndex = function () {
+  var self = STATE.get(this);
+  return makeIndex(self.pointer, self.capacity);
+};
+
+CircularHistory.prototype.isStartReached = function () {
+  var self = STATE.get(this);
+  return self.navigationIndex === NAVIGATION_LOWER_BOUND;
+};
+
+CircularHistory.prototype.isEndReached = function () {
+  var self = STATE.get(this);
+  return self.navigationIndex === self.navigationUpperBound;
+};
+
+CircularHistory.FLAGS = FLAGS;
+
+export { CircularHistory };

package/src/circular-history.spec.js

@@ -0,0 +1,432 @@
+import { test, describe, expect } from "vitest";
+import { CircularHistory } from "./circular-history.js";
+
+describe("CircularHistory", () => {
+  test("should throw if capacity is not a positive integer", () => {
+    expect(() => new CircularHistory(0, "number")).toThrow();
+    expect(() => new CircularHistory(-5, "number")).toThrow();
+    expect(() => new CircularHistory(3.5, "number")).toThrow();
+    expect(() => new CircularHistory("10", "number")).toThrow();
+  });
+
+  test("should throw if data type is not allowed", () => {
+    expect(() => new CircularHistory(5, "invalidType")).toThrow();
+    expect(() => new CircularHistory(5, 123)).toThrow();
+    expect(() => new CircularHistory(5, null)).toThrow();
+  });
+
+  test("should successfully create a CircularHistory with valid parameters", () => {
+    var historyNumber = new CircularHistory(5, "number");
+    expect(historyNumber).toBeInstanceOf(CircularHistory);
+
+    var historyString = new CircularHistory(10, "string");
+    expect(historyString).toBeInstanceOf(CircularHistory);
+
+    var historyBigInt = new CircularHistory(3, "bigint");
+    expect(historyBigInt).toBeInstanceOf(CircularHistory);
+
+    var historyBoolean = new CircularHistory(7, "boolean");
+    expect(historyBoolean).toBeInstanceOf(CircularHistory);
+
+    var historySymbol = new CircularHistory(2, "symbol");
+    expect(historySymbol).toBeInstanceOf(CircularHistory);
+
+    var historyObject = new CircularHistory(4, "object");
+    expect(historyObject).toBeInstanceOf(CircularHistory);
+  });
+
+  test("should not commit invalid data types", () => {
+    var historyNumber = new CircularHistory(5, "number");
+    expect(() => historyNumber.commit("string")).toThrow();
+    expect(() => historyNumber.commit(true)).toThrow();
+    expect(() => historyNumber.commit({})).toThrow();
+    expect(() => historyNumber.commit([])).toThrow();
+    expect(() => historyNumber.commit(Symbol("sym"))).toThrow();
+    expect(() => historyNumber.commit(10n)).toThrow();
+
+    var historyString = new CircularHistory(5, "string");
+    expect(() => historyString.commit(100)).toThrow();
+    expect(() => historyString.commit(false)).toThrow();
+    expect(() => historyString.commit({})).toThrow();
+    expect(() => historyString.commit([])).toThrow();
+    expect(() => historyString.commit(Symbol("sym"))).toThrow();
+    expect(() => historyString.commit(10n)).toThrow();
+
+    var historyBigInt = new CircularHistory(5, "bigint");
+    expect(() => historyBigInt.commit(100)).toThrow();
+    expect(() => historyBigInt.commit("string")).toThrow();
+    expect(() => historyBigInt.commit(true)).toThrow();
+    expect(() => historyBigInt.commit({})).toThrow();
+    expect(() => historyBigInt.commit(Symbol("sym"))).toThrow();
+    expect(() => historyBigInt.commit(10.5)).toThrow();
+
+    var historyBoolean = new CircularHistory(5, "boolean");
+    expect(() => historyBoolean.commit(100)).toThrow();
+    expect(() => historyBoolean.commit("string")).toThrow();
+    expect(() => historyBoolean.commit({})).toThrow();
+    expect(() => historyBoolean.commit([])).toThrow();
+    expect(() => historyBoolean.commit(Symbol("sym"))).toThrow();
+    expect(() => historyBoolean.commit(10n)).toThrow();
+
+    var historySymbol = new CircularHistory(5, "symbol");
+    expect(() => historySymbol.commit(100)).toThrow();
+    expect(() => historySymbol.commit("string")).toThrow();
+    expect(() => historySymbol.commit(true)).toThrow();
+    expect(() => historySymbol.commit({})).toThrow();
+    expect(() => historySymbol.commit(10n)).toThrow();
+
+    var historyObject = new CircularHistory(5, "object");
+    expect(() => historyObject.commit(100)).toThrow();
+    expect(() => historyObject.commit("string")).toThrow();
+    expect(() => historyObject.commit(true)).toThrow();
+    expect(() => historyObject.commit(Symbol("sym"))).toThrow();
+    expect(() => historyObject.commit(10n)).toThrow();
+  });
+
+  test("should get an empty flag if history is empty", () => {
+    var history = new CircularHistory(5, "number");
+    expect(history.current()).toEqual(CircularHistory.FLAGS.empty);
+  });
+
+  test("should wrap around when capacity is exceeded", () => {
+    var history = new CircularHistory(3, "number");
+
+    history.commit(1);
+    history.commit(2);
+    history.commit(3);
+
+    expect(history.current()).toBe(3);
+    history.commit(4);
+
+    expect(history.current()).toBe(4);
+    expect(history.dump(true)).toEqual([4, 2, 3]);
+  });
+
+  test("should move backward and forward (no wrapping)", () => {
+    var history = new CircularHistory(3, "number");
+
+    history.commit(1);
+    history.commit(2);
+    history.commit(3);
+    expect(history.current()).toBe(3);
+
+    history.moveBackward();
+    expect(history.current()).toBe(2);
+
+    history.moveBackward();
+    expect(history.current()).toBe(1);
+
+    history.moveBackward();
+    expect(history.current()).toBe(CircularHistory.FLAGS.empty);
+
+    history.moveBackward();
+    expect(history.current()).toBe(CircularHistory.FLAGS.empty);
+    expect(history.getCurrentIndex()).toBe(-1);
+
+    history.moveForward();
+    expect(history.current()).toBe(1);
+
+    history.moveForward();
+    expect(history.current()).toBe(2);
+
+    history.moveForward();
+    expect(history.current()).toBe(3);
+
+    history.moveForward();
+    expect(history.current()).toBe(3);
+  });
+
+  test("should move backward and forward (with wrapping)", () => {
+    var history = new CircularHistory(3, "number");
+    history.commit(1);
+    history.commit(2);
+    history.commit(3);
+    expect(history.getCurrentIndex()).toBe(2);
+    history.commit(4);
+
+    expect(history.current()).toBe(4);
+    expect(history.getCurrentIndex()).toBe(0);
+
+    history.moveBackward();
+    expect(history.current()).toBe(3);
+
+    history.moveBackward();
+    expect(history.current()).toBe(2);
+
+    history.moveBackward();
+    expect(history.current()).toBe(2);
+
+    history.moveForward();
+    expect(history.current()).toBe(3);
+
+    history.moveForward();
+    expect(history.current()).toBe(4);
+
+    history.moveForward();
+    expect(history.current()).toBe(4);
+  });
+
+  test("should override items ahead after moving backward", () => {
+    var history = new CircularHistory(2, "number");
+
+    history.commit(1);
+    expect(history.current()).toBe(1);
+
+    history.commit(2);
+    expect(history.current()).toBe(2);
+
+    history.moveBackward();
+    expect(history.current()).toBe(1);
+
+    history.commit(3);
+    expect(history.current()).toBe(3);
+
+    history.moveBackward();
+    expect(history.current()).toBe(1);
+
+    history.moveForward();
+    expect(history.current()).toBe(3);
+
+    history.moveForward();
+    expect(history.current()).toBe(3);
+  });
+
+  test("should clear the history correctly", () => {
+    var history = new CircularHistory(3, "number");
+
+    history.commit(1);
+    history.commit(2);
+    history.commit(3);
+
+    expect(history.current()).toBe(3);
+
+    history.clear();
+    expect(history.current()).toEqual(CircularHistory.FLAGS.empty);
+    expect(history.getCurrentIndex()).toBe(-1);
+
+    history.commit(4);
+
+    expect(history.current()).toBe(4);
+    expect(history.getCurrentIndex()).toBe(0);
+  });
+
+  test("should return back the current history state with empty values", () => {
+    var history = new CircularHistory(3, "number");
+    history.commit(1);
+    history.commit(2);
+    expect(history.dump()).toEqual([1, 2, undefined]);
+  });
+
+  test("should return back the current history state without empty values", () => {
+    var history = new CircularHistory(3, "number");
+    history.commit(1);
+    history.commit(2);
+    expect(history.dump(true)).toEqual([1, 2]);
+  });
+
+  test("should return back the correct current pointer position", () => {
+    var history = new CircularHistory(3, "number");
+    expect(history.getCurrentIndex()).toBe(-1);
+
+    history.commit(1);
+    expect(history.getCurrentIndex()).toBe(0);
+
+    history.commit(2);
+    expect(history.getCurrentIndex()).toBe(1);
+
+    history.commit(3);
+    expect(history.getCurrentIndex()).toBe(2);
+
+    history.commit(4);
+    expect(history.getCurrentIndex()).toBe(0);
+
+    history.commit(5);
+    expect(history.getCurrentIndex()).toBe(1);
+
+    history.moveBackward();
+    expect(history.getCurrentIndex()).toBe(0);
+
+    history.moveBackward();
+    expect(history.getCurrentIndex()).toBe(2);
+
+    history.moveForward();
+    expect(history.getCurrentIndex()).toBe(0);
+
+    history.moveForward();
+    expect(history.getCurrentIndex()).toBe(1);
+
+    history.moveForward();
+    expect(history.getCurrentIndex()).toBe(1);
+
+    history.moveForward();
+    expect(history.getCurrentIndex()).toBe(1);
+  });
+
+  test("should correctly identify when start is reached", () => {
+    var history = new CircularHistory(3, "number");
+    expect(history.isStartReached()).toBe(true);
+
+    history.commit(1);
+    expect(history.isStartReached()).toBe(false);
+
+    history.commit(2);
+    expect(history.isStartReached()).toBe(false);
+
+    history.moveBackward();
+    expect(history.isStartReached()).toBe(false);
+
+    history.moveBackward();
+    expect(history.isStartReached()).toBe(true);
+
+    history.moveBackward();
+    expect(history.isStartReached()).toBe(true);
+  });
+
+  test("should correctly identify when end is reached", () => {
+    var history = new CircularHistory(3, "number");
+    expect(history.isEndReached()).toBe(true);
+
+    history.commit(1);
+    history.commit(2);
+    expect(history.current()).toBe(2);
+
+    history.moveForward();
+    expect(history.isEndReached()).toBe(true);
+
+    history.moveBackward();
+    expect(history.current()).toBe(1);
+    expect(history.isEndReached()).toBe(false);
+
+    history.moveBackward();
+    expect(history.current()).toBe(CircularHistory.FLAGS.empty);
+    expect(history.isEndReached()).toBe(false);
+
+    history.moveForward();
+    expect(history.current()).toBe(1);
+    expect(history.isEndReached()).toBe(false);
+
+    history.moveForward();
+    expect(history.current()).toBe(2);
+    expect(history.isEndReached()).toBe(true);
+
+    history.moveForward();
+    expect(history.current()).toBe(2);
+    expect(history.isEndReached()).toBe(true);
+  });
+
+  test("should return the last available item when capacity is not reached, the next item is empty and moving forward", () => {
+    var history = new CircularHistory(3, "number");
+
+    history.commit(1);
+    history.commit(2);
+    expect(history.current()).toBe(2);
+
+    history.moveForward();
+    expect(history.current()).toBe(2);
+
+    history.moveForward();
+    expect(history.current()).toBe(2);
+
+    history.moveBackward();
+    expect(history.current()).toBe(1);
+
+    history.moveBackward();
+    expect(history.current()).toBe(CircularHistory.FLAGS.empty);
+
+    history.moveBackward();
+    expect(history.current()).toBe(CircularHistory.FLAGS.empty);
+
+    history.moveForward();
+    expect(history.current()).toBe(1);
+
+    history.moveForward();
+    expect(history.current()).toBe(2);
+
+    history.moveForward();
+    expect(history.current()).toBe(2);
+  });
+
+  test("should behave correctly after multiple backward moves against empty history", () => {
+    var history = new CircularHistory(3, "number");
+
+    history.moveBackward();
+    history.moveBackward();
+    history.moveBackward();
+
+    history.commit(4);
+    expect(history.dump(true)).toEqual([4]);
+    expect(history.getCurrentIndex()).toBe(0);
+    expect(history.current()).toBe(4);
+  });
+
+  test("should behave correctly after multiple forward moves against empty history", () => {
+    var history = new CircularHistory(3, "number");
+
+    history.moveForward();
+    history.moveForward();
+    history.moveForward();
+
+    history.commit(3);
+    expect(history.dump(true)).toEqual([3]);
+    expect(history.getCurrentIndex()).toBe(0);
+
+    history.commit(5);
+    expect(history.dump(true)).toEqual([3, 5]);
+
+    history.moveForward();
+    history.moveForward();
+
+    expect(history.current()).toBe(5);
+  });
+
+  test("should not expose the next item after discarding previous after moving backwards", () => {
+    var history = new CircularHistory(10, "number");
+
+    history.commit(1);
+    history.commit(2);
+    history.commit(3);
+
+    history.moveBackward();
+    history.moveBackward();
+    expect(history.current()).toBe(1);
+
+    history.commit(4);
+    expect(history.dump(true)).toEqual([1, 4, 3]);
+
+    history.moveForward();
+    expect(history.getCurrentIndex()).toBe(1);
+    expect(history.isEndReached()).toBe(true);
+    expect(history.current()).toBe(4);
+
+    history.moveForward();
+    expect(history.current()).toBe(4);
+  });
+
+  test("should behave correctly after multiple moveBackward calls when some item was overriden", () => {
+    var history = new CircularHistory(3, "number");
+    history.commit(1);
+    history.commit(2);
+    history.commit(3);
+
+    history.moveBackward();
+    history.moveBackward();
+
+    history.commit(4);
+
+    history.moveBackward();
+    history.moveBackward();
+    history.moveBackward();
+    history.moveBackward();
+
+    expect(history.getCurrentIndex()).toBe(-1);
+
+    history.moveForward();
+    expect(history.current()).toBe(1);
+
+    history.moveForward();
+    expect(history.current()).toBe(4);
+
+    history.moveForward();
+    expect(history.current()).toBe(4);
+  });
+});

package/src/index.d.ts

@@ -0,0 +1,31 @@
+export declare const FLAGS: {
+  readonly empty: unique symbol;
+};
+
+export declare type CircularHistoryType = number | string | bigint | boolean | symbol | object;
+
+type DataType = "number" | "string" | "bigint" | "boolean" | "symbol" | "object";
+
+export declare class CircularHistory<T extends CircularHistoryType = CircularHistoryType> {
+  constructor(capacity: number, dataType: DataType);
+
+  commit(value: T): void;
+
+  current(): T | typeof FLAGS.empty;
+
+  moveBackward(): void;
+
+  moveForward(): void;
+
+  clear(): void;
+
+  dump(discardHoles?: boolean): T[];
+
+  getCurrentIndex(): number;
+
+  isStartReached(): boolean;
+
+  isEndReached(): boolean;
+
+  static readonly FLAGS: typeof FLAGS;
+}