History

@ailuracode/alpine-history

Headless undo/redo history controller for Alpine.js — transactions, persistence, and configurable limits.

CSS-framework agnostic — no markup, no styles. The controller tracks value snapshots and emits structured events; you wire your own UI.

Install

pnpm add @ailuracode/alpine-history @ailuracode/alpine-core alpinejs

Quick start

import Alpine from "alpinejs";
import history from "@ailuracode/alpine-history";

Alpine.plugin(history({ initialValue: 0 }));
Alpine.start();

<div>
  <output x-text="$store.history.value"></output>
  <button @click="$store.history.commit($store.history.value + 1)">+1</button>
  <button @click="$store.history.undo()" :disabled="!$store.history.canUndo">Undo</button>
  <button @click="$store.history.redo()" :disabled="!$store.history.canRedo">Redo</button>
</div>

Store API (`$store.history`)

Method / Property	Description
`commit(value, meta?)`	Record a new value in the undo stack
`undo()`	Pop the last entry and push it to redo; returns the restored value
`redo()`	Pop the last redo entry and push it to undo; returns the restored value
`canUndo`	`true` when the undo stack is non-empty
`canRedo`	`true` when the redo stack is non-empty
`clear()`	Empty both undo and redo stacks
`reset(value?, meta?)`	Clear stacks and commit a fresh initial value
`checkpoint(meta?)`	Snapshot the current value without changing it
`transaction(initialValue)`	Start a batch — returns a `TransactionHandle` with `.commit()` and `.rollback()`
`value`	Current value (may be `undefined` before first commit)
`undoStack`	Shallow copy of the undo entries
`redoStack`	Shallow copy of the redo entries
`transactionDepth`	`> 0` while a transaction is active
`destroy()`	Tear down the controller and release resources

Magic API (`$history`)

The callable magic $history is a shorthand for commit:

<button @click="$history($store.history.value + 1)">+1</button>

The magic also exposes read-only accessors: $history.current, $history.canUndo, $history.canRedo, and all store methods (undo, redo, clear, reset, checkpoint, transaction).

Plugin options

Option	Type	Default	Description
`initialValue`	`T`	`undefined`	Seed value — visible as `value` but not on the undo stack until the first commit
`limit`	`number`	`100`	Maximum entries in the undo stack
`maxSize`	`number`	`undefined`	Estimated byte budget; oldest entries are evicted first
`clone`	`(value: T) => T`	`structuredClone`	Deep-clone strategy for entries
`equality`	`(a: T, b: T) => boolean`	`Object.is`	Deduplication for consecutive identical commits
`debounceMs`	`number`	`undefined`	Debounce rapid commits
`nestedTransactionPolicy`	`"stack" \| "abort"`	`"stack"`	How to handle nested `.transaction()` calls
`persistence`	`PersistenceAdapter<T>`	`undefined`	Optional adapter for persisting undo history
`storeKey`	`string`	`"history"`	Alpine store key
`magicKey`	`string`	`"history"`	`$history` magic key

Transactions

Transactions batch multiple commits into a single undo entry:

const tx = $store.history.transaction(currentValue);
$store.history.commit(newValue1);
$store.history.commit(newValue2);
tx.commit(); // pushes a single undo entry

Calling tx.rollback() discards all intermediate commits and restores the snapshot taken when transaction() was called.

Avoiding name collisions

If your application already owns a $history store or magic — or another toolkit plugin registers on that name — rename the integration surface without touching the controller:

Alpine.plugin(
  historyPlugin({
    storeKey: "undoStack", // → $store.undoStack
    magicKey: "undo", // → $undo
  }),
);

The exposed constants DEFAULT_HISTORY_MAGIC_KEY and HISTORY_STORE_KEY keep the renames discoverable from TypeScript.

Persistence

Implement the PersistenceAdapter interface to persist undo history across reloads:

const localStorageAdapter = {
  load() {
    const raw = localStorage.getItem("my-history");
    return raw ? JSON.parse(raw) : [];
  },
  save(entries) {
    localStorage.setItem("my-history", JSON.stringify(entries));
  },
  clear() {
    localStorage.removeItem("my-history");
  },
};

Alpine.plugin(history({ persistence: localStorageAdapter }));

Controller API (no Alpine)

Use the controller directly for non-Alpine environments or testing:

import { HistoryController } from "@ailuracode/alpine-history";

const controller = new HistoryController({ initialValue: 0 });
controller.mount();

controller.commit(1);
controller.commit(2);
controller.undo(); // restores 1

controller.on("change", (detail) => {
  console.log(detail.value, detail.canUndo, detail.canRedo, detail.source);
});

Events

The change event fires on every mutation with a typed source:

`source`	Trigger
`"initialization"`	Controller mounted
`"commit"`	New value committed
`"undo"`	Undo navigation
`"redo"`	Redo navigation
`"clear"`	Stacks emptied
`"reset"`	Reset to fresh state
`"checkpoint"`	Snapshot recorded
`"transaction:start"`	Transaction opened
`"transaction:commit"`	Transaction committed
`"transaction:rollback"`	Transaction rolled back

License

MIT