@cubingcenter/scrambler 0.6.3 → 0.8.0

package/dist-cjs/puzzles/cube4/scramble-cache.js

@@ -0,0 +1,156 @@
+"use strict";
+/**
+ * Background prefetch buffer for 4x4 scrambles — the Node-side analogue of
+ * TNoodle's `ScrambleCacher`.
+ *
+ * The cache keeps up to `size` scrambles generating AHEAD of consumption:
+ *  - `take()` shifts the OLDEST slot; if it is already settled it resolves
+ *    immediately (no waiting for later slots), otherwise it awaits only
+ *    that slot. Order is FIFO of START (not of completion), so a seeded
+ *    stream hands out `seed:0`, `seed:1`, … in order even when the
+ *    underlying generator finishes out of order (parallel pool).
+ *  - every shift triggers a refill, so the buffer repopulates in the
+ *    background — wire `generate: (o) => pool.generate(o)` and the refill
+ *    itself runs across worker threads (see the pool integration test).
+ *  - failures are FIRST-CLASS slots: a slot that rejects is delivered as a
+ *    rejection to the next `take()` (consumed exactly once) and the cache
+ *    keeps going with the following slots. Every slot promise is wrapped
+ *    at creation so a background failure can NEVER surface as an
+ *    unhandledRejection, and `take()` never hangs: slots always settle
+ *    (the generator contract is "settles eventually").
+ *  - `dispose()` stops refilling and drops buffered slots. In-flight
+ *    generations are left to settle silently (results discarded). There
+ *    are NO timers anywhere, so a disposed (or even forgotten) cache never
+ *    keeps a process alive.
+ *
+ * Seeding: when `options.seed` is defined, slot n is generated with
+ * `${seed}:${n}` — byte-identical to core `generateScrambles("444", …)`
+ * for any count > 1 (slot 0 ↔ item 0 of a batch). Without a seed every
+ * slot uses the base options unchanged (fresh randomness).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Cube4ScrambleCache = void 0;
+exports.deriveCube4StreamOptions = deriveCube4StreamOptions;
+exports.createCube4ScrambleCache = createCube4ScrambleCache;
+const scrambler_js_1 = require("./scrambler.js");
+/**
+ * Stream slot derivation (cache analogue of core's batch derivation).
+ * Exported for tests and for hosts that precompute the same sequence.
+ */
+function deriveCube4StreamOptions(options, index) {
+    if (options.seed === undefined)
+        return options;
+    return { ...options, seed: `${options.seed}:${index}` };
+}
+class Cube4ScrambleCache {
+    capacity;
+    baseOptions;
+    generator;
+    /** FIFO of slots (start order); settled or still pending. */
+    slots = [];
+    nextIndex = 0;
+    disposed = false;
+    constructor(options = {}) {
+        const size = options.size ?? 4;
+        if (!Number.isInteger(size) || size < 1) {
+            throw new RangeError(`[cube4] cache size must be an integer >= 1 (got ${size}).`);
+        }
+        this.capacity = size;
+        this.baseOptions = options.options ?? {};
+        this.generator = options.generate ?? scrambler_js_1.generateCube4Scramble;
+        // Prefetch starts immediately: that is the point of constructing a cache.
+        this.pump();
+    }
+    /** Configured buffer capacity. */
+    get size() {
+        return this.capacity;
+    }
+    /** Slots currently buffered (settled + still generating). */
+    get buffered() {
+        return this.slots.length;
+    }
+    /** Buffered slots that have already settled (ready for an instant take()). */
+    get ready() {
+        let count = 0;
+        for (const carrier of this.slots)
+            if (carrier.slot !== undefined)
+                count++;
+        return count;
+    }
+    /** Slots currently generating in the background. */
+    get inFlight() {
+        let count = 0;
+        for (const carrier of this.slots)
+            if (carrier.slot === undefined)
+                count++;
+        return count;
+    }
+    get isDisposed() {
+        return this.disposed;
+    }
+    /**
+     * Resolves once the buffer holds `size` settled results (i.e. a
+     * subsequent `take()` is served instantly). Safe to call at any time;
+     * rejects only if called after `dispose()`.
+     */
+    warmup() {
+        if (this.disposed) {
+            return Promise.reject(new Error("[cube4] scramble cache is disposed (warmup)."));
+        }
+        this.pump();
+        return Promise.all(this.slots.map((carrier) => carrier.promise)).then(() => undefined);
+    }
+    /**
+     * Next scramble in FIFO order. Instant when the front slot is settled;
+     * otherwise waits only for the front slot (never for later ones).
+     * A failed background generation surfaces here as a rejection — exactly
+     * once — and the cache continues with subsequent slots.
+     */
+    take() {
+        if (this.disposed) {
+            return Promise.reject(new Error("[cube4] scramble cache is disposed (take)."));
+        }
+        const carrier = this.slots.shift();
+        this.pump(); // refill BEFORE awaiting, so generation overlaps consumption
+        if (carrier === undefined) {
+            // Only reachable when capacity was somehow drained concurrently;
+            // generate one on the spot rather than hang.
+            return this.generateNow();
+        }
+        return carrier.promise.then((slot) => {
+            if (slot.ok)
+                return slot.result;
+            throw slot.error;
+        });
+    }
+    /**
+     * Stops prefetching, drops buffered slots and ignores in-flight
+     * completions. No timers are involved, so nothing can keep a process
+     * alive afterwards. Idempotent.
+     */
+    dispose() {
+        this.disposed = true;
+        this.slots.length = 0;
+    }
+    // ── internals ────────────────────────────────────────────────────────
+    pump() {
+        while (!this.disposed && this.slots.length < this.capacity) {
+            const index = this.nextIndex++;
+            const promise = this.generator(deriveCube4StreamOptions(this.baseOptions, index)).then((result) => ({ ok: true, result }), (error) => ({ ok: false, error }));
+            const carrier = { promise, slot: undefined };
+            void promise.then((slot) => {
+                carrier.slot = slot;
+            });
+            this.slots.push(carrier);
+        }
+    }
+    generateNow() {
+        const index = this.nextIndex++;
+        return this.generator(deriveCube4StreamOptions(this.baseOptions, index));
+    }
+}
+exports.Cube4ScrambleCache = Cube4ScrambleCache;
+/** Convenience factory mirroring the other cube4 constructors. */
+function createCube4ScrambleCache(options = {}) {
+    return new Cube4ScrambleCache(options);
+}