circular-history 1.0.1 → 1.0.2

package/dist/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/dist/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;
+}

package/dist/index.js

@@ -0,0 +1 @@
+var g=Object.defineProperty;var a=(e,t)=>g(e,"name",{value:t,configurable:!0});var y=["number","string","bigint","boolean","symbol","object"],p=0,f=-1,v={empty:Symbol("empty")},s=a(e=>y.includes(e),"isTypeAllowed"),c=a(e=>{var t=typeof e,n=t==="object"&&e!==null;return n||s(t)},"isValueTypeAllowed"),l=a((e,t)=>c(e)&&typeof e===t,"canCommit"),d=a(e=>e===void 0,"isItemEmpty"),u=a((e,t)=>e%t,"makeIndex"),r=new WeakMap;function i(e,t){if(typeof e!="number"||e<=0||!Number.isInteger(e))throw new Error(`Capacity must be a positive integer. Got "${e}".`);if(!s(t))throw new Error(`"${t}" is not allowed`);r.set(this,{navigationUpperBound:p,navigationIndex:p,pointer:f,capacity:e,dataType:t,buffer:new Array(e)})}a(i,"CircularHistory");i.prototype.commit=function(e){var t=r.get(this),n=t.dataType;if(!l(e,n))throw new Error(`Type of ${e} is invalid. Expected "${n}", got "${e===null?"null":typeof e}".`);var o=t.capacity;t.pointer===t.capacity-1?(t.navigationUpperBound=o-1,t.navigationIndex=o-1):t.navigationIndex=++t.navigationUpperBound,t.buffer[u(++t.pointer,o)]=e};i.prototype.current=function(){var e=r.get(this),t=e.buffer,n=e.pointer;if(n===f)return v.empty;var o=t[u(n,e.capacity)];return d(o)?v.empty:o};i.prototype.moveBackward=function(){var e=r.get(this);e.navigationIndex===p||e.pointer===f||(e.pointer--,e.navigationIndex--)};i.prototype.moveForward=function(){var e=r.get(this);e.navigationIndex!==e.navigationUpperBound&&(e.pointer++,e.navigationIndex++)};i.prototype.clear=function(){var e=r.get(this);e.navigationIndex=p,e.navigationUpperBound=p,e.pointer=f,e.buffer=new Array(e.capacity)};i.prototype.dump=function(e=!1){var t=r.get(this),n=[...t.buffer];return e?n.filter(o=>!d(o)):n};i.prototype.getCurrentIndex=function(){var e=r.get(this);return u(e.pointer,e.capacity)};i.prototype.isStartReached=function(){var e=r.get(this);return e.navigationIndex===p};i.prototype.isEndReached=function(){var e=r.get(this);return e.navigationIndex===e.navigationUpperBound};i.FLAGS=v;export{i as CircularHistory};

package/dist/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "circular-history",
+  "type": "module",
+  "version": "1.0.2",
+  "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.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zavvdev/circular-history"
+  },
+  "keywords": [
+    "javascript",
+    "data-structures",
+    "circular-buffer",
+    "circular-history",
+    "history-management"
+  ],
+  "author": "Ihor ZAVIRIUKHA <ihor.zaviriukha@protonmail.com>",
+  "license": "MIT"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "circular-history",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "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.",