@operato/utils 2.0.0-alpha.0 → 2.0.0-alpha.28

package/src/timecapsule/snapshot-taker.ts

@@ -1,10 +1,11 @@
-/*
- * Copyright © HatioLab Inc. All rights reserved.
- */
-
 import { TimeCapsule } from './timecapsule'
 import debounce from 'lodash-es/debounce'
 
+/**
+ * A function that takes a SnapshotTaker as an argument and initiates snapshot creation
+ * using a debouncer to delay the process.
+ * @param {SnapshotTaker} taker - The SnapshotTaker instance to trigger snapshots for.
+ */
 var debouncer = debounce(
   taker => {
     if (!taker.brake) {
@@ -15,15 +16,28 @@ var debouncer = debounce(
   { leading: true, trailing: false }
 )
 
+/**
+ * Function to trigger snapshot creation for a SnapshotTaker instance.
+ * Checks if the taker is in a brake state or not dirty before triggering the snapshot.
+ * @param {SnapshotTaker} taker - The SnapshotTaker instance to create a snapshot for.
+ */
 function take_snapshot(taker: SnapshotTaker) {
   if (taker.brake || !taker.dirty) return
   debouncer(taker)
 }
 
+/**
+ * Type definition for holding state information.
+ * @typedef {Object} StateHolder
+ * @property {*} state - The state to be held.
+ */
 export type StateHolder = {
   state: any
 }
 
+/**
+ * Class responsible for taking and managing snapshots of state.
+ */
 export class SnapshotTaker {
   private _brake: boolean = false
 
@@ -32,23 +46,38 @@ export class SnapshotTaker {
   state_holder?: StateHolder
   timecapsule?: TimeCapsule
 
+  /**
+   * Creates an instance of SnapshotTaker.
+   * @param {*} state_holder - The object that holds the state to be snapshot.
+   * @param {TimeCapsule} timecapsule - The TimeCapsule instance associated with this SnapshotTaker.
+   */
   constructor(state_holder: any, timecapsule: TimeCapsule) {
     this.state_holder = state_holder
     this.timecapsule = timecapsule
     this.timecapsule.snapshot_taker = this
   }
 
+  /**
+   * Disposes of the SnapshotTaker and clears associated references.
+   */
   dispose() {
     delete this.state_holder
     delete this.timecapsule
   }
 
+  /**
+   * Marks the SnapshotTaker as dirty and initiates snapshot creation.
+   */
   touch() {
     this.dirty = true
     take_snapshot(this)
   }
 
   /* 모든 조건에 관계없이 현재 상태를 snapshot으로 취한다. */
+  /**
+   * Takes a snapshot of the current state.
+   * @param {boolean} [force=false] - If true, the snapshot is taken even if not dirty.
+   */
   take(force: boolean = false) {
     if (this.dirty || force) {
       this.timecapsule?.snapshot(this.state_holder?.state)
@@ -56,11 +85,19 @@ export class SnapshotTaker {
     }
   }
 
+  /**
+   * Gets the brake state of the SnapshotTaker.
+   * @returns {boolean} - true if the brake is active, false otherwise.
+   */
   get brake() {
     return this._brake
   }
 
   /* 마우스를 드래깅하는 동안, 보통 brake 를 ON 시킨다. */
+  /**
+   * Sets the brake state of the SnapshotTaker and initiates snapshot creation.
+   * @param {boolean} brake - The new brake state.
+   */
   set brake(brake) {
     this._brake = !!brake
     take_snapshot(this)

package/src/timecapsule/timecapsule.ts

@@ -1,11 +1,10 @@
-/*
- * Copyright © HatioLab Inc. All rights reserved.
- */
-
 import { debug, error, warn } from '../logger'
 
 import { SnapshotTaker } from './snapshot-taker'
 
+/**
+ * A utility class for managing and navigating through a history of snapshots.
+ */
 export class TimeCapsule {
   private q: Array<any> = []
   private maxsize = 10
@@ -13,6 +12,11 @@ export class TimeCapsule {
 
   private _snapshot_taker: SnapshotTaker | null = null
 
+  /**
+   * Creates an instance of TimeCapsule.
+   * @param {number} maxsize - The maximum number of snapshots to store.
+   * @param {any} [start_state] - The initial state to be stored as the first snapshot (optional).
+   */
   constructor(maxsize: number, start_state?: any) {
     maxsize = Number(maxsize)
 
@@ -28,10 +32,17 @@ export class TimeCapsule {
     }
   }
 
+  /**
+   * Disposes of the TimeCapsule and clears all stored snapshots.
+   */
   dispose() {
     this.reset()
   }
 
+  /**
+   * Captures a snapshot of the current state and stores it.
+   * @param {any} state - The state to be captured as a snapshot.
+   */
   snapshot(state: any) {
     this.q.splice(this.pos + 1, this.q.length - (this.pos + 1), state)
 
@@ -42,6 +53,10 @@ export class TimeCapsule {
     this.pos = this.q.length - 1
   }
 
+  /**
+   * Moves forward to the next snapshot in the history.
+   * @returns {any} The next state snapshot if available, or logs a warning if not.
+   */
   forward() {
     if (this.snapshot_taker) this.snapshot_taker.take()
 
@@ -51,6 +66,10 @@ export class TimeCapsule {
     warn('Not forwardable.')
   }
 
+  /**
+   * Moves backward to the previous snapshot in the history.
+   * @returns {any} The previous state snapshot if available, or logs a warning if not.
+   */
   backward() {
     if (this.snapshot_taker) this.snapshot_taker.take()
 
@@ -60,32 +79,59 @@ export class TimeCapsule {
     warn('Not backwardable.')
   }
 
+  /**
+   * Gets the current state snapshot.
+   * @returns {any} The current state snapshot if available, or logs a warning if not.
+   */
   get current() {
     if (this.pos !== -1) return this.q[this.pos]
 
     warn('Non state has been recorded.')
   }
 
+  /**
+   * Gets the number of snapshots stored in the TimeCapsule.
+   * @returns {number} The count of stored snapshots.
+   */
   get length() {
     return this.q.length
   }
 
+  /**
+   * Checks if there is a snapshot available to move forward.
+   * @returns {boolean} True if moving forward is possible, otherwise false.
+   */
   get forwardable() {
     return this.pos < this.q.length - 1
   }
 
+  /**
+   * Checks if there is a snapshot available to move backward.
+   * @returns {boolean} True if moving backward is possible, otherwise false.
+   */
   get backwardable() {
     return this.pos > 0
   }
 
+  /**
+   * Gets the SnapshotTaker associated with this TimeCapsule.
+   * @returns {SnapshotTaker | null} The associated SnapshotTaker, or null if not set.
+   */
   get snapshot_taker(): SnapshotTaker | null {
     return this._snapshot_taker
   }
 
+  /**
+   * Sets the SnapshotTaker for this TimeCapsule.
+   * @param {SnapshotTaker | null} snapshot_taker - The SnapshotTaker instance to associate with this TimeCapsule.
+   */
   set snapshot_taker(snapshot_taker: SnapshotTaker | null) {
     this._snapshot_taker = snapshot_taker
   }
 
+  /**
+   * Resets the TimeCapsule, clearing all stored snapshots and resetting the position.
+   */
   reset() {
     this.q = []
     this.pos = -1