@nolag/queue 0.1.3 → 1.1.0

package/dist/react-native.js

@@ -0,0 +1,1251 @@
+/**
+ * Tiny typed event emitter — framework-agnostic base for NoLag SDKs.
+ *
+ * EventMap is a record of event name → tuple of handler arguments.
+ */
+class EventEmitter {
+    constructor() {
+        this._handlers = new Map();
+    }
+    on(event, handler) {
+        if (!this._handlers.has(event)) {
+            this._handlers.set(event, new Set());
+        }
+        this._handlers.get(event).add(handler);
+        return this;
+    }
+    off(event, handler) {
+        if (handler) {
+            this._handlers.get(event)?.delete(handler);
+        }
+        else {
+            this._handlers.delete(event);
+        }
+        return this;
+    }
+    removeAllListeners() {
+        this._handlers.clear();
+        return this;
+    }
+    emit(event, ...args) {
+        const handlers = this._handlers.get(event);
+        if (!handlers)
+            return;
+        for (const handler of handlers) {
+            try {
+                handler(...args);
+            }
+            catch (e) {
+                console.error(`Error in ${String(event)} handler:`, e);
+            }
+        }
+    }
+    listenerCount(event) {
+        return this._handlers.get(event)?.size ?? 0;
+    }
+}
+
+/** Valid state transitions for job lifecycle */
+const VALID_TRANSITIONS = {
+    pending: ['claimed'],
+    claimed: ['active'],
+    active: ['completed', 'failed'],
+    failed: ['pending'], // retry path
+};
+/**
+ * In-memory job store with deduplication, filtering, and state-transition validation.
+ */
+class JobStore {
+    constructor(maxSize) {
+        this._jobs = new Map();
+        this._maxSize = maxSize;
+    }
+    /**
+     * Add a job to the store.
+     * Returns true if added, false if already present (dedup).
+     */
+    add(job) {
+        if (this._jobs.has(job.id))
+            return false;
+        // Evict oldest entry if at capacity
+        if (this._jobs.size >= this._maxSize) {
+            const firstKey = this._jobs.keys().next().value;
+            if (firstKey !== undefined) {
+                this._jobs.delete(firstKey);
+            }
+        }
+        this._jobs.set(job.id, job);
+        return true;
+    }
+    /**
+     * Get a job by ID.
+     */
+    get(id) {
+        return this._jobs.get(id);
+    }
+    /**
+     * Get all jobs, optionally filtered.
+     */
+    getAll(filter) {
+        const jobs = Array.from(this._jobs.values());
+        if (!filter)
+            return jobs;
+        return jobs.filter((job) => {
+            if (filter.status !== undefined && job.status !== filter.status)
+                return false;
+            if (filter.type !== undefined && job.type !== filter.type)
+                return false;
+            if (filter.priority !== undefined && job.priority !== filter.priority)
+                return false;
+            return true;
+        });
+    }
+    /**
+     * Transition a job to a new status with optional data update.
+     * Validates the state transition. Returns updated job or null if invalid.
+     */
+    updateStatus(id, status, data) {
+        const job = this._jobs.get(id);
+        if (!job)
+            return null;
+        const allowed = VALID_TRANSITIONS[job.status];
+        if (!allowed || !allowed.includes(status))
+            return null;
+        const now = Date.now();
+        const updated = {
+            ...job,
+            status,
+            updatedAt: now,
+            ...data,
+        };
+        if (status === 'completed' || status === 'failed') {
+            updated.completedAt = now;
+        }
+        this._jobs.set(id, updated);
+        return updated;
+    }
+    /**
+     * Update the progress percentage (0–100) for a job.
+     * Returns the updated job or null if not found.
+     */
+    updateProgress(id, progress) {
+        const job = this._jobs.get(id);
+        if (!job)
+            return null;
+        const clamped = Math.min(100, Math.max(0, progress));
+        const updated = { ...job, progress: clamped, updatedAt: Date.now() };
+        this._jobs.set(id, updated);
+        return updated;
+    }
+    /**
+     * Number of jobs currently in 'pending' status.
+     */
+    get pendingCount() {
+        let count = 0;
+        for (const job of this._jobs.values()) {
+            if (job.status === 'pending')
+                count++;
+        }
+        return count;
+    }
+    /**
+     * Number of jobs currently in 'active' status.
+     */
+    get activeCount() {
+        let count = 0;
+        for (const job of this._jobs.values()) {
+            if (job.status === 'active')
+                count++;
+        }
+        return count;
+    }
+    /**
+     * Check if a job with the given ID exists.
+     */
+    has(id) {
+        return this._jobs.has(id);
+    }
+    /**
+     * Total number of jobs in the store.
+     */
+    get size() {
+        return this._jobs.size;
+    }
+    /**
+     * Clear all jobs from the store.
+     */
+    clear() {
+        this._jobs.clear();
+    }
+}
+
+/**
+ * Tracks all known queue workers (local and remote).
+ */
+class WorkerManager {
+    constructor() {
+        this._workers = new Map();
+    }
+    /**
+     * Add or replace a worker entry.
+     */
+    addWorker(worker) {
+        this._workers.set(worker.workerId, worker);
+    }
+    /**
+     * Remove a worker by workerId.
+     * Returns the removed worker, or null if not found.
+     */
+    removeWorker(workerId) {
+        const worker = this._workers.get(workerId) ?? null;
+        this._workers.delete(workerId);
+        return worker;
+    }
+    /**
+     * Get a worker by workerId.
+     */
+    getWorker(workerId) {
+        return this._workers.get(workerId);
+    }
+    /**
+     * Get all tracked workers.
+     */
+    getAll() {
+        return Array.from(this._workers.values());
+    }
+    /**
+     * Increment the active job count for a worker.
+     * Returns the updated worker or null if not found.
+     */
+    incrementActiveJobs(workerId) {
+        const worker = this._workers.get(workerId);
+        if (!worker)
+            return null;
+        const updated = { ...worker, activeJobs: worker.activeJobs + 1 };
+        this._workers.set(workerId, updated);
+        return updated;
+    }
+    /**
+     * Decrement the active job count for a worker (floor 0).
+     * Returns the updated worker or null if not found.
+     */
+    decrementActiveJobs(workerId) {
+        const worker = this._workers.get(workerId);
+        if (!worker)
+            return null;
+        const updated = {
+            ...worker,
+            activeJobs: Math.max(0, worker.activeJobs - 1),
+        };
+        this._workers.set(workerId, updated);
+        return updated;
+    }
+    /**
+     * Check whether a worker can accept more work (activeJobs < concurrency).
+     */
+    canAcceptWork(workerId) {
+        const worker = this._workers.get(workerId);
+        if (!worker)
+            return false;
+        return worker.activeJobs < worker.concurrency;
+    }
+    /**
+     * Clear all tracked workers.
+     */
+    clear() {
+        this._workers.clear();
+    }
+}
+
+/**
+ * Maps actorTokenId ↔ QueueWorker, filtering self.
+ */
+class PresenceManager {
+    constructor(localActorId) {
+        this._workers = new Map();
+        this._actorToWorkerId = new Map();
+        this._localActorId = localActorId;
+    }
+    /**
+     * Add or update a worker from presence data.
+     * Returns the QueueWorker if it's a remote worker, null if it's self.
+     */
+    addFromPresence(actorTokenId, presence, joinedAt) {
+        const isLocal = actorTokenId === this._localActorId;
+        // Skip self
+        if (isLocal)
+            return null;
+        const existing = this._actorToWorkerId.get(actorTokenId);
+        const workerId = presence.workerId || existing || actorTokenId;
+        const worker = {
+            workerId,
+            actorTokenId,
+            role: presence.role,
+            activeJobs: presence.activeJobs ?? 0,
+            concurrency: presence.concurrency ?? 1,
+            metadata: presence.metadata,
+            joinedAt: joinedAt || Date.now(),
+            isLocal: false,
+        };
+        this._workers.set(workerId, worker);
+        this._actorToWorkerId.set(actorTokenId, workerId);
+        return worker;
+    }
+    /**
+     * Remove a worker by actorTokenId.
+     * Returns the removed worker, or null if not found / is self.
+     */
+    removeByActorId(actorTokenId) {
+        if (actorTokenId === this._localActorId)
+            return null;
+        const workerId = this._actorToWorkerId.get(actorTokenId);
+        if (!workerId)
+            return null;
+        const worker = this._workers.get(workerId) ?? null;
+        this._workers.delete(workerId);
+        this._actorToWorkerId.delete(actorTokenId);
+        return worker;
+    }
+    /**
+     * Get a worker by workerId.
+     */
+    getWorker(workerId) {
+        return this._workers.get(workerId);
+    }
+    /**
+     * Get a worker by actorTokenId.
+     */
+    getWorkerByActorId(actorTokenId) {
+        const workerId = this._actorToWorkerId.get(actorTokenId);
+        return workerId ? this._workers.get(workerId) : undefined;
+    }
+    /**
+     * Get all remote workers.
+     */
+    getAll() {
+        return Array.from(this._workers.values());
+    }
+    /**
+     * Get the workers Map (readonly view).
+     */
+    get workers() {
+        return this._workers;
+    }
+    /**
+     * Clear all tracked workers.
+     */
+    clear() {
+        this._workers.clear();
+        this._actorToWorkerId.clear();
+    }
+}
+
+function generateId() {
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+        return crypto.randomUUID();
+    }
+    return 'xxxx-xxxx-xxxx-xxxx'.replace(/x/g, () => Math.floor(Math.random() * 16).toString(16));
+}
+function createLogger(prefix, enabled) {
+    if (!enabled) {
+        return (..._args) => { };
+    }
+    return (...args) => {
+        console.log(`[${prefix}]`, ...args);
+    };
+}
+// ============ Wrapper registry ============
+// One wrapper instance per (client, appName): two wrappers sharing an app on
+// one connection would collide on topics, presence and the online lobby.
+// Warn (not throw): HMR and tests legitimately construct before disposing.
+const wrapperRegistry = new WeakMap();
+/** Register a wrapper against a client + appName; warns on collision. */
+function registerWrapper(client, appName, wrapperName) {
+    let apps = wrapperRegistry.get(client);
+    if (!apps) {
+        apps = new Map();
+        wrapperRegistry.set(client, apps);
+    }
+    const existing = apps.get(appName);
+    if (existing) {
+        console.warn(`[${wrapperName}] Another wrapper (${existing}) is already attached to this client for app "${appName}". ` +
+            `Use one wrapper per (client, app) — detach the other instance first.`);
+    }
+    apps.set(appName, wrapperName);
+}
+/** Release a wrapper's (client, appName) registration on detach. */
+function releaseWrapper(client, appName) {
+    wrapperRegistry.get(client)?.delete(appName);
+}
+
+/** Default app name for NoLag queue SDK */
+const DEFAULT_APP_NAME = 'queue';
+/** Default maximum number of jobs to cache in memory */
+const DEFAULT_MAX_JOB_CACHE = 1000;
+/** Default maximum number of attempts before a job is permanently failed */
+const DEFAULT_MAX_ATTEMPTS = 3;
+/** Topic name for job lifecycle messages within a queue room */
+const TOPIC_JOBS = 'jobs';
+/** Topic name for job progress updates within a queue room */
+const TOPIC_PROGRESS = '_progress';
+/** Lobby ID for global online presence */
+const LOBBY_ID = 'online';
+/** Delay before the post-setup lobby presence refetch (catches simultaneous joiners) */
+const LOBBY_REFRESH_DELAY_MS = 2000;
+
+/**
+ * QueueRoom — a single named queue with job lifecycle, progress tracking, and worker presence.
+ *
+ * Created via `NoLagQueue.joinQueue(name)`. Do not instantiate directly.
+ */
+class QueueRoom extends EventEmitter {
+    /** @internal */
+    constructor(name, roomContext, localWorkerId, options, log, isConnected) {
+        super();
+        // Stored topic handler refs — cleanup removes exactly these, never all
+        // handlers for a topic (the client may be shared with other consumers).
+        this._onJobsRef = null;
+        this._onProgressRef = null;
+        this.name = name;
+        this._roomContext = roomContext;
+        this._localWorkerId = localWorkerId;
+        this._options = options;
+        this._log = log;
+        this._isConnected = isConnected;
+        this._jobStore = new JobStore(options.maxJobCache);
+        this._workerManager = new WorkerManager();
+        this._presenceManager = new PresenceManager(''); // local actor set after connect
+    }
+    /** @internal Set the local actor ID once connected */
+    _setLocalActorId(actorId) {
+        this._presenceManager = new PresenceManager(actorId);
+    }
+    // ============ Producer Methods ============
+    /**
+     * Add a new job to the queue. Only producers should call this.
+     */
+    addJob(opts) {
+        const now = Date.now();
+        const job = {
+            id: generateId(),
+            type: opts.type,
+            payload: opts.payload,
+            priority: opts.priority ?? 'normal',
+            status: 'pending',
+            progress: 0,
+            attempts: 0,
+            maxAttempts: opts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS,
+            createdBy: this._localWorkerId,
+            createdAt: now,
+            updatedAt: now,
+            isReplay: false,
+        };
+        this._jobStore.add(job);
+        this._log('Job added:', job.id, job.type);
+        this._roomContext.emit(TOPIC_JOBS, { event: 'jobAdded', job }, { echo: true });
+        this.emit('jobAdded', job);
+        return job;
+    }
+    // ============ Worker Methods ============
+    /**
+     * Claim a pending job. Only workers should call this.
+     */
+    claimJob(jobId) {
+        const updated = this._jobStore.updateStatus(jobId, 'claimed', {
+            claimedBy: this._localWorkerId,
+        });
+        if (!updated)
+            return null;
+        this._log('Job claimed:', jobId, 'by', this._localWorkerId);
+        this._roomContext.emit(TOPIC_JOBS, { event: 'jobClaimed', job: updated }, { echo: true });
+        this.emit('jobClaimed', updated);
+        return updated;
+    }
+    /**
+     * Report progress on an active job (0–100).
+     */
+    reportProgress(jobId, progress) {
+        const job = this._jobStore.updateProgress(jobId, progress);
+        if (!job)
+            return;
+        const progressEvent = {
+            jobId,
+            progress: job.progress,
+            workerId: this._localWorkerId,
+            timestamp: Date.now(),
+        };
+        this._log('Job progress:', jobId, job.progress + '%');
+        this._roomContext.emit(TOPIC_PROGRESS, progressEvent, { echo: true });
+        this.emit('jobProgress', progressEvent);
+    }
+    /**
+     * Mark a claimed/active job as completed with an optional result.
+     */
+    completeJob(jobId, result) {
+        // Transition claimed → active → completed in one step for simplicity
+        let updated = this._jobStore.updateStatus(jobId, 'active');
+        if (!updated) {
+            // Already active — go straight to completed
+            updated = this._jobStore.get(jobId) ?? null;
+        }
+        if (!updated)
+            return null;
+        const completed = this._jobStore.updateStatus(jobId, 'completed', { result });
+        if (!completed)
+            return null;
+        this._log('Job completed:', jobId);
+        this._roomContext.emit(TOPIC_JOBS, { event: 'jobCompleted', job: completed }, { echo: true });
+        this.emit('jobCompleted', completed);
+        return completed;
+    }
+    /**
+     * Mark an active job as failed with an optional error message.
+     * Automatically retries if attempts < maxAttempts.
+     */
+    failJob(jobId, error) {
+        const job = this._jobStore.get(jobId);
+        if (!job)
+            return null;
+        // Move to active if still claimed
+        if (job.status === 'claimed') {
+            this._jobStore.updateStatus(jobId, 'active');
+        }
+        const nextAttempts = job.attempts + 1;
+        const failed = this._jobStore.updateStatus(jobId, 'failed', {
+            error,
+            attempts: nextAttempts,
+        });
+        if (!failed)
+            return null;
+        this._log('Job failed:', jobId, 'attempts:', nextAttempts, '/', failed.maxAttempts);
+        this._roomContext.emit(TOPIC_JOBS, { event: 'jobFailed', job: failed }, { echo: true });
+        this.emit('jobFailed', failed);
+        // Auto-retry if under maxAttempts
+        if (nextAttempts < failed.maxAttempts) {
+            const retried = this._jobStore.updateStatus(jobId, 'pending');
+            if (retried) {
+                this._log('Job retrying:', jobId, 'attempt', nextAttempts + 1);
+                this._roomContext.emit(TOPIC_JOBS, { event: 'jobRetrying', job: retried }, { echo: true });
+                this.emit('jobRetrying', retried);
+            }
+        }
+        return failed;
+    }
+    // ============ Monitor / Query Methods ============
+    /**
+     * Get a single job by ID.
+     */
+    getJob(id) {
+        return this._jobStore.get(id);
+    }
+    /**
+     * Get all jobs, optionally filtered.
+     */
+    getJobs(filter) {
+        return this._jobStore.getAll(filter);
+    }
+    /**
+     * Number of pending jobs.
+     */
+    get pendingCount() {
+        return this._jobStore.pendingCount;
+    }
+    /**
+     * Number of active jobs.
+     */
+    get activeCount() {
+        return this._jobStore.activeCount;
+    }
+    /**
+     * All workers currently in this queue room.
+     */
+    get workers() {
+        return this._presenceManager.workers;
+    }
+    /**
+     * Get all workers in this queue room.
+     */
+    getWorkers() {
+        return this._presenceManager.getAll();
+    }
+    // ============ Internal (called by NoLagQueue) ============
+    /** @internal Subscribe to jobs and progress topics, attach listeners */
+    _subscribe() {
+        this._log('Room subscribe:', this.name);
+        // Workers use load balancing so each job event is delivered to only ONE worker
+        // (round-robin across all workers in the same group). Producers and monitors
+        // receive all messages so they can track full queue state.
+        if (this._options.role === 'worker') {
+            const group = this._options.loadBalanceGroup ?? `queue-workers-${this.name}`;
+            this._log('Subscribing with load balance, group:', group);
+            this._roomContext.subscribe(TOPIC_JOBS, { loadBalance: true, loadBalanceGroup: group });
+        }
+        else {
+            this._roomContext.subscribe(TOPIC_JOBS);
+        }
+        this._roomContext.subscribe(TOPIC_PROGRESS);
+        // Listen for job lifecycle messages (refs stored for handler-specific removal)
+        this._onJobsRef = (data) => {
+            this._handleJobMessage(data);
+        };
+        this._roomContext.on(TOPIC_JOBS, this._onJobsRef);
+        this._onProgressRef = (data) => {
+            this._handleProgressMessage(data);
+        };
+        this._roomContext.on(TOPIC_PROGRESS, this._onProgressRef);
+    }
+    /** @internal Set presence and fetch room members */
+    _activate() {
+        this._log('Room activate:', this.name);
+        this._setPresence();
+        this._roomContext.fetchPresence().then((actors) => {
+            this._log('Room presence fetched:', this.name, actors.length, 'actors');
+            for (const actor of actors) {
+                if (actor.presence) {
+                    const worker = this._presenceManager.addFromPresence(actor.actorTokenId, actor.presence, actor.joinedAt);
+                    if (worker) {
+                        this._workerManager.addWorker(worker);
+                        this.emit('workerJoined', worker);
+                    }
+                }
+            }
+        }).catch((err) => {
+            this._log('Failed to fetch room presence:', err);
+        });
+    }
+    /** @internal Re-set presence after reconnect */
+    _updateLocalPresence() {
+        this._setPresence();
+    }
+    /** @internal Handle a presence:join event */
+    _handlePresenceJoin(actorTokenId, presenceData) {
+        const worker = this._presenceManager.addFromPresence(actorTokenId, presenceData);
+        if (worker) {
+            this._log('Worker joined queue:', this.name, worker.workerId);
+            this._workerManager.addWorker(worker);
+            this.emit('workerJoined', worker);
+        }
+    }
+    /** @internal Handle a presence:leave event */
+    _handlePresenceLeave(actorTokenId) {
+        const worker = this._presenceManager.removeByActorId(actorTokenId);
+        if (worker) {
+            this._log('Worker left queue:', this.name, worker.workerId);
+            this._workerManager.removeWorker(worker.workerId);
+            this.emit('workerLeft', worker);
+        }
+    }
+    /** @internal Handle a presence:update event */
+    _handlePresenceUpdate(actorTokenId, presenceData) {
+        const worker = this._presenceManager.addFromPresence(actorTokenId, presenceData);
+        if (worker) {
+            this._workerManager.addWorker(worker);
+        }
+    }
+    /** @internal Unsubscribe and clean up */
+    _cleanup() {
+        this._log('Room cleanup:', this.name);
+        // Server unsubscribes need a live socket; skip when disconnected
+        // (best-effort — the core would no-op with an error callback anyway).
+        if (this._isConnected()) {
+            this._roomContext.unsubscribe(TOPIC_JOBS);
+            this._roomContext.unsubscribe(TOPIC_PROGRESS);
+        }
+        // Handler-specific removal only: the client may be shared, and a bare
+        // off(topic) would strip other consumers' handlers too.
+        if (this._onJobsRef)
+            this._roomContext.off(TOPIC_JOBS, this._onJobsRef);
+        if (this._onProgressRef)
+            this._roomContext.off(TOPIC_PROGRESS, this._onProgressRef);
+        this._onJobsRef = null;
+        this._onProgressRef = null;
+        this._jobStore.clear();
+        this._workerManager.clear();
+        this._presenceManager.clear();
+        this.removeAllListeners();
+    }
+    // ============ Private ============
+    _handleJobMessage(data) {
+        const msg = data;
+        if (!msg?.event || !msg?.job)
+            return;
+        const { event, job } = msg;
+        this._log('Job message:', event, job.id);
+        switch (event) {
+            case 'jobAdded':
+                if (this._jobStore.add(job)) {
+                    this.emit('jobAdded', job);
+                }
+                break;
+            case 'jobClaimed': {
+                const existing = this._jobStore.get(job.id);
+                if (existing) {
+                    this._jobStore.updateStatus(job.id, 'claimed', { claimedBy: job.claimedBy });
+                    const updated = this._jobStore.get(job.id);
+                    this.emit('jobClaimed', updated);
+                }
+                break;
+            }
+            case 'jobCompleted': {
+                const existing = this._jobStore.get(job.id);
+                if (existing) {
+                    // Sync final state directly since remote already processed transitions
+                    const synced = { ...existing, ...job };
+                    this._jobStore.add(synced);
+                    this.emit('jobCompleted', synced);
+                }
+                break;
+            }
+            case 'jobFailed': {
+                const existing = this._jobStore.get(job.id);
+                if (existing) {
+                    const synced = { ...existing, ...job };
+                    this._jobStore.add(synced);
+                    this.emit('jobFailed', synced);
+                }
+                break;
+            }
+            case 'jobRetrying': {
+                const existing = this._jobStore.get(job.id);
+                if (existing) {
+                    const synced = { ...existing, ...job };
+                    this._jobStore.add(synced);
+                    this.emit('jobRetrying', synced);
+                }
+                break;
+            }
+        }
+    }
+    _handleProgressMessage(data) {
+        const progress = data;
+        if (!progress?.jobId)
+            return;
+        this._jobStore.updateProgress(progress.jobId, progress.progress);
+        this._log('Job progress update:', progress.jobId, progress.progress + '%');
+        this.emit('jobProgress', progress);
+    }
+    _setPresence() {
+        const presenceData = {
+            workerId: this._localWorkerId,
+            role: this._options.role,
+            activeJobs: 0,
+            concurrency: this._options.concurrency,
+            metadata: this._options.metadata,
+            // Scope tag: on a shared client, other apps' wrappers filter our
+            // presence out by this (and we filter theirs).
+            __scope: this._options.appName,
+        };
+        this._roomContext.setPresence(presenceData);
+    }
+}
+
+/**
+ * NoLagQueue — high-level real-time job queue SDK built on @nolag/js-sdk.
+ *
+ * Provides job lifecycle management, progress tracking, worker management,
+ * and global presence tracking — all framework-agnostic via events.
+ *
+ * The wrapper NEVER manages the connection. The app owns one core NoLag
+ * client (shared by any number of wrappers on distinct apps) and the
+ * wrapper attaches to it at construction and releases it via `detach()`.
+ *
+ * @example
+ * ```typescript
+ * import { NoLag } from '@nolag/js-sdk';
+ * import { NoLagQueue } from '@nolag/queue';
+ *
+ * const client = NoLag(async () => (await (await fetch('/api/nolag-token')).json()).token);
+ * const queue = new NoLagQueue({ client, role: 'worker', concurrency: 2 });
+ *
+ * queue.on('connected', () => console.log('Connected!'));
+ *
+ * await client.connect();   // the app owns the connection
+ * await queue.ready();      // wrapper setup done (identity, lobby, queues)
+ *
+ * const room = queue.joinQueue('image-processing');
+ * room.on('jobAdded', (job) => {
+ *   room.claimJob(job.id);
+ *   room.reportProgress(job.id, 50);
+ *   room.completeJob(job.id, { output: 'result' });
+ * });
+ *
+ * queue.detach();           // wrapper releases its handlers and topics
+ * client.disconnect();      // the app closes the socket
+ * ```
+ */
+class NoLagQueue extends EventEmitter {
+    constructor(options) {
+        super();
+        this._localWorker = null;
+        this._queues = new Map();
+        this._lobby = null;
+        this._onlineWorkers = new Map();
+        this._actorToWorkerId = new Map();
+        // Lifecycle: one setup run per connection epoch; detach is terminal.
+        this._epoch = 0;
+        this._detached = false;
+        this._isReady = false;
+        this._lobbyRefreshTimer = null;
+        // Stored client handler refs. INVARIANT: every client.on() below has a
+        // matching client.off() in detach() — never bare off(event), never inline
+        // closures on the client.
+        this._onConnectRef = () => this._onConnect();
+        this._onDisconnectRef = (reason) => {
+            this._log('Disconnected:', reason);
+            this.emit('disconnected', reason);
+        };
+        this._onReconnectRef = () => {
+            this._log('Reconnecting...');
+            this.emit('reconnecting');
+        };
+        this._onErrorRef = (error) => {
+            this._log('Error:', error);
+            this.emit('error', error);
+        };
+        this._onPresenceJoinRef = (data) => this._handleRoomPresenceJoin(data);
+        this._onPresenceLeaveRef = (data) => this._handleRoomPresenceLeave(data);
+        this._onPresenceUpdateRef = (data) => this._handleRoomPresenceUpdate(data);
+        this._onLobbyJoinRef = (data) => this._handleLobbyJoin(data);
+        this._onLobbyLeaveRef = (data) => this._handleLobbyLeave(data);
+        this._onLobbyUpdateRef = (data) => this._handleLobbyUpdate(data);
+        if (!options?.client) {
+            throw new TypeError('NoLagQueue requires an injected NoLag client: new NoLagQueue({ client, role, ... })');
+        }
+        this._client = options.client;
+        this._workerId = options.workerId ?? generateId();
+        this._options = {
+            workerId: this._workerId,
+            role: options.role ?? 'monitor',
+            concurrency: options.concurrency ?? 1,
+            metadata: options.metadata,
+            appName: options.appName ?? DEFAULT_APP_NAME,
+            maxJobCache: options.maxJobCache ?? DEFAULT_MAX_JOB_CACHE,
+            debug: options.debug ?? false,
+            queues: options.queues ?? [],
+            loadBalanceGroup: options.loadBalanceGroup,
+        };
+        this._log = createLogger('NoLagQueue', this._options.debug);
+        this._readyPromise = new Promise((resolve, reject) => {
+            this._readyResolve = resolve;
+            this._readyReject = reject;
+        });
+        // ready() rejection is only meaningful to callers that await it
+        this._readyPromise.catch(() => { });
+        registerWrapper(this._client, this._options.appName, 'NoLagQueue');
+        // Construction = attach: wire everything now, with stored refs.
+        this._client.on('connect', this._onConnectRef);
+        this._client.on('disconnect', this._onDisconnectRef);
+        this._client.on('reconnect', this._onReconnectRef);
+        this._client.on('error', this._onErrorRef);
+        this._client.on('presence:join', this._onPresenceJoinRef);
+        this._client.on('presence:leave', this._onPresenceLeaveRef);
+        this._client.on('presence:update', this._onPresenceUpdateRef);
+        this._client.on('lobbyPresence:join', this._onLobbyJoinRef);
+        this._client.on('lobbyPresence:leave', this._onLobbyLeaveRef);
+        this._client.on('lobbyPresence:update', this._onLobbyUpdateRef);
+        // Attach-to-connected: if the client is already authenticated, run setup.
+        // The microtask lets the caller wire wrapper event handlers synchronously
+        // first; a racing real 'connect' event wins via the epoch guard.
+        queueMicrotask(() => {
+            if (this._epoch === 0 && !this._detached && this._client.connected) {
+                this._onConnect();
+            }
+        });
+    }
+    // ============ Public Properties ============
+    /** Whether the underlying connection is established (connected ≠ ready) */
+    get connected() {
+        return !this._detached && this._client.connected;
+    }
+    /** The injected core client (owned by the app, not the wrapper) */
+    get client() {
+        return this._client;
+    }
+    /** The local worker's info (available after ready) */
+    get localWorker() {
+        return this._localWorker;
+    }
+    /** All currently joined queue rooms */
+    get queues() {
+        return this._queues;
+    }
+    // ============ Lifecycle ============
+    /**
+     * Resolves once the wrapper's first setup completed (identity, lobby and
+     * configured queues ready — equivalently, once 'connected' has fired).
+     * Rejects only if detach() is called before that. Client auth failures
+     * surface via the app's own `await client.connect()`, not here.
+     */
+    ready() {
+        return this._readyPromise;
+    }
+    /**
+     * Detach from the client: remove every handler this wrapper added,
+     * unsubscribe its topics and lobby (when connected), clear state.
+     * Terminal and idempotent; never touches the socket. To use the queue
+     * again, construct a new instance.
+     */
+    detach() {
+        if (this._detached)
+            return;
+        this._log('Detaching...');
+        this._detached = true;
+        this._epoch++; // aborts any in-flight setup at its next checkpoint
+        if (this._lobbyRefreshTimer) {
+            clearTimeout(this._lobbyRefreshTimer);
+            this._lobbyRefreshTimer = null;
+        }
+        // Remove all client handlers by stored ref
+        this._client.off('connect', this._onConnectRef);
+        this._client.off('disconnect', this._onDisconnectRef);
+        this._client.off('reconnect', this._onReconnectRef);
+        this._client.off('error', this._onErrorRef);
+        this._client.off('presence:join', this._onPresenceJoinRef);
+        this._client.off('presence:leave', this._onPresenceLeaveRef);
+        this._client.off('presence:update', this._onPresenceUpdateRef);
+        this._client.off('lobbyPresence:join', this._onLobbyJoinRef);
+        this._client.off('lobbyPresence:leave', this._onLobbyLeaveRef);
+        this._client.off('lobbyPresence:update', this._onLobbyUpdateRef);
+        // Queue rooms: handler-specific off + connected-gated server unsubscribe
+        for (const name of [...this._queues.keys()]) {
+            this._queues.get(name)._cleanup();
+            this._queues.delete(name);
+        }
+        // Lobby: server unsubscribe is best-effort and needs a live socket
+        if (this._lobby && this._client.connected) {
+            try {
+                this._lobby.unsubscribe();
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+        this._lobby = null;
+        this._onlineWorkers.clear();
+        this._actorToWorkerId.clear();
+        this._localWorker = null;
+        releaseWrapper(this._client, this._options.appName);
+        if (!this._isReady) {
+            this._readyReject(new Error('NoLagQueue detached before ready'));
+        }
+    }
+    // ============ Private: Epoch Setup ============
+    _onConnect() {
+        this._epoch++;
+        void this._runSetup(this._epoch);
+    }
+    /**
+     * One setup pass per connection epoch. Serves both initial setup (epoch 1)
+     * and reconnect restore (epoch > 1). Aborts silently whenever a newer
+     * epoch started or the wrapper detached — checked after every await.
+     */
+    async _runSetup(epoch) {
+        const stale = () => epoch !== this._epoch || this._detached;
+        this._log(this._isReady ? 'Restoring after reconnect...' : 'Setting up...');
+        // Identity (client.actorId is guaranteed post-auth)
+        if (!this._localWorker) {
+            this._localWorker = {
+                workerId: this._workerId,
+                actorTokenId: this._client.actorId,
+                role: this._options.role,
+                activeJobs: 0,
+                concurrency: this._options.concurrency,
+                metadata: this._options.metadata,
+                joinedAt: Date.now(),
+                isLocal: true,
+            };
+            this._log('Local worker:', this._localWorker.workerId, '→', this._localWorker.actorTokenId);
+        }
+        else {
+            this._localWorker.actorTokenId = this._client.actorId;
+        }
+        // Lobby: subscribe every epoch (idempotent server-side) and diff-hydrate
+        // from the returned snapshot — one path for setup and restore.
+        if (!this._lobby) {
+            this._lobby = this._client.setApp(this._options.appName).setLobby(LOBBY_ID);
+        }
+        try {
+            const state = await this._lobby.subscribe();
+            if (stale())
+                return;
+            this._diffHydrateOnlineWorkers(state);
+            this._log('Lobby subscribed, online workers:', this._onlineWorkers.size);
+        }
+        catch (err) {
+            if (stale())
+                return;
+            this._log('Lobby subscription failed:', err);
+        }
+        if (!this._isReady) {
+            // First successful setup: pre-subscribe configured queues.
+            for (const queueName of this._options.queues) {
+                this._subscribeQueue(queueName);
+            }
+        }
+        else {
+            // Server auto-restored topic subscriptions; only room-scoped presence
+            // needs re-applying (the core does not restore it).
+            for (const room of this._queues.values()) {
+                room._updateLocalPresence();
+            }
+        }
+        if (stale())
+            return;
+        // Ready keys on the first setup that COMPLETES, not on epoch 1: an
+        // epoch aborted by a racing reconnect must not strand ready().
+        if (!this._isReady) {
+            this._isReady = true;
+            this._readyResolve();
+            this.emit('connected');
+        }
+        else {
+            this.emit('reconnected');
+        }
+        // Deferred lobby refetch: catches workers who joined during the setup
+        // window (e.g. simultaneous multi-tab connects).
+        this._scheduleLobbyRefresh(epoch);
+    }
+    _scheduleLobbyRefresh(epoch) {
+        if (this._lobbyRefreshTimer)
+            clearTimeout(this._lobbyRefreshTimer);
+        this._lobbyRefreshTimer = setTimeout(() => {
+            this._lobbyRefreshTimer = null;
+            if (epoch !== this._epoch || this._detached || !this._client.connected || !this._lobby) {
+                return;
+            }
+            this._lobby
+                .fetchPresence()
+                .then((state) => {
+                if (epoch !== this._epoch || this._detached)
+                    return;
+                this._diffHydrateOnlineWorkers(state);
+            })
+                .catch(() => {
+                /* best-effort */
+            });
+        }, LOBBY_REFRESH_DELAY_MS);
+    }
+    // ============ Queue Management ============
+    /**
+     * Join a queue room. Creates, subscribes, and activates it.
+     * Returns an existing room if already joined.
+     */
+    joinQueue(name) {
+        this._assertUsable();
+        let room = this._queues.get(name);
+        if (!room) {
+            room = this._subscribeQueue(name);
+            room._activate();
+        }
+        return room;
+    }
+    /**
+     * Leave a queue room. Fully unsubscribes and removes it.
+     */
+    leaveQueue(name) {
+        const room = this._queues.get(name);
+        if (!room)
+            return;
+        this._log('Leaving queue:', name);
+        room._cleanup();
+        this._queues.delete(name);
+    }
+    /**
+     * Get all joined queue rooms.
+     */
+    getQueues() {
+        return Array.from(this._queues.values());
+    }
+    // ============ Global Presence ============
+    /**
+     * Get all workers currently online across all queue rooms.
+     */
+    getOnlineWorkers() {
+        return Array.from(this._onlineWorkers.values());
+    }
+    // ============ Private: Guards ============
+    _assertUsable() {
+        if (this._detached) {
+            throw new Error('NoLagQueue has been detached — construct a new instance');
+        }
+        if (!this._isReady || !this._localWorker) {
+            throw new Error('NoLagQueue not ready — await ready() or the "connected" event');
+        }
+    }
+    // ============ Private: Queue Setup ============
+    _subscribeQueue(name) {
+        this._log('Subscribing queue:', name);
+        const roomContext = this._client.setApp(this._options.appName).setRoom(name);
+        const room = new QueueRoom(name, roomContext, this._workerId, this._options, createLogger(`QueueRoom:${name}`, this._options.debug), () => this._client.connected);
+        room._setLocalActorId(this._localWorker.actorTokenId);
+        this._queues.set(name, room);
+        room._subscribe();
+        return room;
+    }
+    // ============ Private: Scope Filtering ============
+    /**
+     * On a shared client, presence events from other apps' wrappers arrive on
+     * the same connection-level events. Wrappers stamp their presence with a
+     * `__scope` (their appName); a mismatched tag means another app's data.
+     * Untagged presence is accepted (older peers in this same app).
+     */
+    _foreignScope(data) {
+        const scope = data?.__scope;
+        return typeof scope === 'string' && scope !== this._options.appName;
+    }
+    // ============ Private: Room Presence ============
+    _handleRoomPresenceJoin(data) {
+        if (data.actorTokenId === this._localWorker?.actorTokenId)
+            return;
+        const presenceData = data.presence;
+        if (!presenceData?.workerId || this._foreignScope(presenceData))
+            return;
+        const worker = this._presenceToWorker(data.actorTokenId, presenceData);
+        this._actorToWorkerId.set(data.actorTokenId, worker.workerId);
+        if (!this._onlineWorkers.has(worker.workerId)) {
+            this._onlineWorkers.set(worker.workerId, worker);
+            this.emit('workerOnline', worker);
+        }
+        // Route to all queue rooms
+        for (const room of this._queues.values()) {
+            room._handlePresenceJoin(data.actorTokenId, presenceData);
+        }
+    }
+    _handleRoomPresenceLeave(data) {
+        if (data.actorTokenId === this._localWorker?.actorTokenId)
+            return;
+        // Route to all queue rooms
+        for (const room of this._queues.values()) {
+            room._handlePresenceLeave(data.actorTokenId);
+        }
+    }
+    _handleRoomPresenceUpdate(data) {
+        if (data.actorTokenId === this._localWorker?.actorTokenId)
+            return;
+        const presenceData = data.presence;
+        if (!presenceData?.workerId || this._foreignScope(presenceData))
+            return;
+        if (this._onlineWorkers.has(presenceData.workerId)) {
+            const worker = this._presenceToWorker(data.actorTokenId, presenceData);
+            this._onlineWorkers.set(worker.workerId, worker);
+        }
+        // Route to all queue rooms
+        for (const room of this._queues.values()) {
+            room._handlePresenceUpdate(data.actorTokenId, presenceData);
+        }
+    }
+    // ============ Private: Lobby ============
+    _handleLobbyJoin(event) {
+        const { actorId, data } = event;
+        if (actorId === this._localWorker?.actorTokenId)
+            return;
+        const presenceData = data;
+        if (!presenceData?.workerId || this._foreignScope(presenceData))
+            return;
+        const worker = this._presenceToWorker(actorId, presenceData);
+        this._actorToWorkerId.set(actorId, worker.workerId);
+        if (!this._onlineWorkers.has(worker.workerId)) {
+            this._onlineWorkers.set(worker.workerId, worker);
+            this.emit('workerOnline', worker);
+        }
+    }
+    _handleLobbyLeave(event) {
+        const { actorId, data } = event;
+        if (actorId === this._localWorker?.actorTokenId)
+            return;
+        const presenceData = data;
+        if (this._foreignScope(presenceData))
+            return;
+        const workerId = presenceData?.workerId
+            || this._actorToWorkerId.get(actorId)
+            || this._findWorkerIdByActorId(actorId);
+        if (workerId) {
+            const worker = this._onlineWorkers.get(workerId);
+            if (worker) {
+                this._onlineWorkers.delete(workerId);
+                this._actorToWorkerId.delete(actorId);
+                this.emit('workerOffline', worker);
+            }
+        }
+    }
+    _handleLobbyUpdate(event) {
+        const { actorId, data } = event;
+        if (actorId === this._localWorker?.actorTokenId)
+            return;
+        const presenceData = data;
+        if (!presenceData?.workerId || this._foreignScope(presenceData))
+            return;
+        const worker = this._presenceToWorker(actorId, presenceData);
+        this._onlineWorkers.set(worker.workerId, worker);
+    }
+    /**
+     * Reconcile the online-worker map against a fresh lobby snapshot, emitting
+     * only the deltas (workerOffline for vanished, workerOnline for new). One
+     * path for initial hydration, reconnect restore, and the deferred refetch.
+     */
+    _diffHydrateOnlineWorkers(state) {
+        // Build the fresh worker set from the snapshot
+        const fresh = new Map();
+        const freshActors = new Map();
+        for (const roomId of Object.keys(state)) {
+            const roomPresence = state[roomId];
+            for (const actorId of Object.keys(roomPresence)) {
+                if (actorId === this._localWorker?.actorTokenId)
+                    continue;
+                const raw = roomPresence[actorId];
+                // Server returns full actor records with presence nested under .presence
+                const presenceData = (raw?.presence ?? raw);
+                if (presenceData?.workerId && !this._foreignScope(presenceData)) {
+                    if (!fresh.has(presenceData.workerId)) {
+                        fresh.set(presenceData.workerId, this._presenceToWorker(actorId, presenceData));
+                    }
+                    freshActors.set(actorId, presenceData.workerId);
+                }
+            }
+        }
+        // Vanished workers
+        for (const [workerId, worker] of [...this._onlineWorkers]) {
+            if (!fresh.has(workerId)) {
+                this._onlineWorkers.delete(workerId);
+                for (const [actorId, mappedWorkerId] of [...this._actorToWorkerId]) {
+                    if (mappedWorkerId === workerId)
+                        this._actorToWorkerId.delete(actorId);
+                }
+                this.emit('workerOffline', worker);
+            }
+        }
+        // New workers
+        for (const [workerId, worker] of fresh) {
+            if (!this._onlineWorkers.has(workerId)) {
+                this._onlineWorkers.set(workerId, worker);
+                this.emit('workerOnline', worker);
+            }
+        }
+        for (const [actorId, workerId] of freshActors) {
+            this._actorToWorkerId.set(actorId, workerId);
+        }
+    }
+    // ============ Private: Helpers ============
+    _presenceToWorker(actorTokenId, data) {
+        return {
+            workerId: data.workerId,
+            actorTokenId,
+            role: data.role,
+            activeJobs: data.activeJobs ?? 0,
+            concurrency: data.concurrency ?? 1,
+            metadata: data.metadata,
+            joinedAt: Date.now(),
+            isLocal: false,
+        };
+    }
+    _findWorkerIdByActorId(actorTokenId) {
+        for (const worker of this._onlineWorkers.values()) {
+            if (worker.actorTokenId === actorTokenId)
+                return worker.workerId;
+        }
+        return undefined;
+    }
+}
+
+export { EventEmitter, JobStore, NoLagQueue, PresenceManager, QueueRoom, WorkerManager };
+//# sourceMappingURL=react-native.js.map