Flashback Stack

A micro-sized, zero-dependency undo/redo timeline for any serializable JavaScript/TypeScript state. Use it for time-travel debugging, state management, document editors, games, and more.

Table of Contents

1. Installation
2. Quick Start
3. Features
4. API Reference
5. Examples
6. Code of Conduct
7. License

Installation

npm install flashback-stack
# Requires Node ≥ 20, ESM-only

Quick Start

import flashback from 'flashback-stack'

async function demo() {
    // 1. Create a timeline with a 50-entry cap:
    const tl = flashback({ count: 0 }, undefined, { maxHistory: 50 })

    // 2. Make a change (async):
    await tl.change(draft => {
        draft.count += 2
    })
    console.log(tl.state) // { count: 2 }

    // 3. Save an explicit state:
    await tl.save({ count: 42 })

    // 4. Undo / redo:
    tl.undo() // returns true
    console.log(tl.state) // { count: 2 }
    tl.redo()
    console.log(tl.state) // { count: 42 }
}

demo()

Features

• 🚀 Tiny & Fast: ~200 LOC, zero dependencies, O(1) undo/redo operations
• 🔒 Type Safe: Full TypeScript definitions
• 🧠 Immutable: Internally deep-frozen state with fresh clones on access
• 🔄 Async & Chainable: save()/change() return Promise<this> for await or chaining
• 🧩 Flexible: Sync/async compression hooks, plus maxHistory option

API Reference

See API.md for full details.

Examples

Keyboard Shortcuts

window.addEventListener('keydown', e => {
    if (e.ctrlKey && e.key === 'z') tl.undo()
    if (e.ctrlKey && e.key === 'y') tl.redo()
})

Code of Conduct

Please read our Code of Conduct to keep this community welcoming and inclusive.

License

Distributed under the MIT License. See LICENSE for details.