pixel-data-js 0.29.0 → 0.31.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pixel-data-js",
   "type": "module",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "packageManager": "pnpm@10.33.0",
   "description": "JS Pixel and ImageData operations",
   "author": {

package/src/Control/BatchedQueue.ts

@@ -0,0 +1,76 @@
+export type BatchedQueueFn = (fn: () => void) => void
+
+export type BatchedQueue = ReturnType<typeof makeBatchedQueue>
+
+/**
+ * Creates a high-performance, zero-allocation batching queue.
+ * This utility collects items marked as "dirty" and flushes them in a single batch.
+ * * **⚠️ CRITICAL: Synchronous Processing Required**
+ * Because the internal sets are reused, the `Set` passed to the `processor` is instantly
+ * cleared the moment the processor function returns. If you need to process the items
+ * asynchronously, you **must** manually clone the set inside your processor.
+ * @template T - The type of items being batched.
+ * @param processor - The callback executed when the batch flushes. Receives a `Set` of all batched items.
+ * @param queue - The scheduling function used to defer the flush. Defaults to `queueMicrotask`.
+ * @returns An object containing methods to mark items as dirty.
+ * @example
+ * * @example
+ * ```ts
+ * import { nextTick } from 'vue'
+ * let bq = makeBatchedQueue<string>(
+ *   (items) => drawSomething(items),
+ *   nextTick,
+ * )
+ * ```
+ */
+export function makeBatchedQueue<T>(
+  processor: (items: Set<T>) => void,
+  queue: BatchedQueueFn,
+) {
+  let activeSet = new Set<T>()
+  let processingSet = new Set<T>()
+  let scheduled = false
+
+  const flush = () => {
+    // swap sets
+    const current = activeSet
+    activeSet = processingSet
+    processingSet = current
+
+    scheduled = false
+
+    try {
+      processor(processingSet)
+    } finally {
+      processingSet.clear()
+    }
+  }
+
+  function markDirty(item: T) {
+    activeSet.add(item)
+
+    if (!scheduled) {
+      scheduled = true
+      queue(flush)
+    }
+  }
+
+  function markMultipleDirty(items: T[]) {
+    let len = items.length
+    if (len === 0) return
+
+    for (let i = 0; i < len; i++) {
+      activeSet.add(items[i])
+    }
+
+    if (!scheduled) {
+      scheduled = true
+      queue(flush)
+    }
+  }
+
+  return {
+    markDirty,
+    markMultipleDirty,
+  }
+}

package/src/Control/RenderQueue.ts

@@ -0,0 +1,49 @@
+/**
+ * Creates a debounced render queue using `requestAnimationFrame`.
+ * This utility ensures that a callback is executed exactly once right before
+ * the next visual frame, regardless of how many times the trigger is called
+ * synchronously. It safely prevents layout thrashing and redundant computations.
+ * @param cb - The function to execute on the next animation frame.
+ * @returns A trigger function that schedules the callback. It includes a `.cancel()` method to abort the pending frame.
+ * * @example
+ * ```ts
+ * let renderQueue = makeRenderQueue(() => {
+ * console.log('DOM updated!')
+ * })
+ * * // Calling this multiple times synchronously...
+ * renderQueue()
+ * renderQueue()
+ * renderQueue()
+ * * // ...will only result in one 'DOM updated!' log on the next frame.
+ * ```
+ * * @example
+ * ```ts
+ * // Canceling a scheduled render (e.g., when a component unmounts)
+ * let trigger = makeRenderQueue(updateLayout)
+ * trigger()
+ * trigger.cancel() // The callback will not execute
+ * ```
+ */
+export function makeRenderQueue(cb: () => void) {
+  let needsRender = false
+  let frameId = 0
+
+  const trigger = () => {
+    if (needsRender) return
+    needsRender = true
+
+    frameId = requestAnimationFrame(() => {
+      needsRender = false
+      cb()
+    })
+  }
+
+  trigger.cancel = () => {
+    if (needsRender) {
+      cancelAnimationFrame(frameId)
+      needsRender = false
+    }
+  }
+
+  return trigger
+}

package/src/History/HistoryAction.ts

@@ -14,9 +14,8 @@ export function makeHistoryAction(
   config: PixelEngineConfig,
   accumulator: PixelAccumulator,
   patch: PixelPatchTiles,
-  after?: () => void,
-  afterUndo?: () => void,
-  afterRedo?: () => void,
+  afterUndo?: (patch: PixelPatchTiles) => void,
+  afterRedo?: (patch: PixelPatchTiles) => void,
   applyPatchTilesFn = applyPatchTiles,
 ): HistoryAction {
 
@@ -26,13 +25,11 @@ export function makeHistoryAction(
   return {
     undo: () => {
       applyPatchTilesFn(target, patch.beforeTiles, tileSize)
-      afterUndo?.()
-      after?.()
+      afterUndo?.(patch)
     },
     redo: () => {
       applyPatchTilesFn(target, patch.afterTiles, tileSize)
-      afterRedo?.()
-      after?.()
+      afterRedo?.(patch)
     },
     dispose: () => accumulator.recyclePatch(patch),
   }

package/src/History/PixelWriter.ts

@@ -8,6 +8,7 @@ import { type HistoryActionFactory, makeHistoryAction } from './HistoryAction'
 import { HistoryManager } from './HistoryManager'
 import { PixelAccumulator } from './PixelAccumulator'
 import { PixelEngineConfig } from './PixelEngineConfig'
+import type { PixelPatchTiles } from './PixelPatchTiles'
 
 export interface PixelWriterOptions {
   maxHistorySteps?: number
@@ -72,15 +73,13 @@ export class PixelWriter<M> {
    *   throw immediately to prevent silent data loss from a nested extractPatch.
    *
    * @param transaction Callback to be executed inside the transaction.
-   * @param after    Called after both undo and redo — use for generic change notifications.
-   * @param afterUndo Called after undo only — use for dimension or state changes specific to undo.
+   * @param afterUndo Called after undo only.
    * @param afterRedo Called after redo only.
    */
   withHistory(
     transaction: (mutator: M) => void,
-    after?: () => void,
-    afterUndo?: () => void,
-    afterRedo?: () => void,
+    afterUndo?: (patch: PixelPatchTiles) => void,
+    afterRedo?: (patch: PixelPatchTiles) => void,
   ): void {
     if (this._inProgress) {
       throw new Error('withHistory is not re-entrant — commit or rollback the current operation first')
@@ -100,7 +99,7 @@ export class PixelWriter<M> {
     if (this.accumulator.beforeTiles.length === 0) return
 
     const patch = this.accumulator.extractPatch()
-    const action = this.historyActionFactory(this.config, this.accumulator, patch, after, afterUndo, afterRedo)
+    const action = this.historyActionFactory(this.config, this.accumulator, patch, afterUndo, afterRedo)
 
     this.historyManager.commit(action)
   }
@@ -110,7 +109,6 @@ export class PixelWriter<M> {
     newHeight: number,
     offsetX = 0,
     offsetY = 0,
-    after?: (target: ImageData) => void,
     afterUndo?: (target: ImageData) => void,
     afterRedo?: (target: ImageData) => void,
     resizeImageDataFn = resizeImageData,
@@ -134,12 +132,10 @@ export class PixelWriter<M> {
       undo: () => {
         setPixelData(target, beforeImageData)
         afterUndo?.(beforeImageData)
-        after?.(beforeImageData)
       },
       redo: () => {
         setPixelData(target, afterImageData)
         afterRedo?.(afterImageData)
-        after?.(afterImageData)
       },
     })
   }

package/src/index.ts

@@ -26,6 +26,9 @@ export * from './Clipboard/writeImgBlobToClipboard'
 
 export * from './color'
 
+export * from './Control/BatchedQueue'
+export * from './Control/RenderQueue'
+
 export * from './History/HistoryAction'
 export * from './History/HistoryManager'
 export * from './History/PixelAccumulator'