@far-world-labs/verblets 0.2.0 → 0.4.0

package/src/lib/retry/index.spec.js

@@ -1,86 +0,0 @@
-import { describe, expect, it } from 'vitest';
-
-import retry from './index.js';
-
-const retryDelayGlobal = 10;
-
-const mockFn = () => {
-  return 'Success';
-};
-
-describe('Retry', () => {
-  it('Succeeds on first attempt', async () => {
-    const result = await retry(mockFn, { retryDelay: retryDelayGlobal });
-    expect(result).toStrictEqual('Success');
-  });
-
-  it('Succeeds after retrying', async () => {
-    let callCount = 0;
-    const fn = async () => {
-      callCount += 1;
-      if (callCount === 1) {
-        const error = new Error('Error 429');
-        error.response = { status: 429 };
-        throw error;
-      }
-      return 'Success';
-    };
-
-    const result = await retry(fn, { retryDelay: retryDelayGlobal });
-    expect(result).toStrictEqual('Success');
-    expect(callCount).toStrictEqual(2);
-  });
-
-  it('Fails after maxRetries', async () => {
-    const maxRetries = 2;
-    let callCount = 0;
-
-    const fn = async () => {
-      callCount += 1;
-      const error = new Error('Error 429');
-      error.response = { status: 429 };
-      throw error;
-    };
-
-    try {
-      await retry(fn, { maxRetries, retryDelay: retryDelayGlobal });
-    } catch (error) {
-      expect(error.message).toStrictEqual('Error 429');
-      expect(callCount).toStrictEqual(maxRetries + 1);
-    }
-  });
-
-  it('Throws non-retryable error', async () => {
-    const mockFnWithOtherError = () => {
-      throw new Error('Error 500');
-    };
-
-    try {
-      await retry(mockFnWithOtherError, { retryDelay: retryDelayGlobal });
-    } catch (error) {
-      expect(error.message).toStrictEqual('Error 500');
-    }
-  });
-
-  it('Retries on all errors when retryOnAll is true', async () => {
-    let callCount = 0;
-    const maxRetries = 2;
-    const fn = async () => {
-      callCount += 1;
-      const error = new Error('Error 500');
-      error.response = { status: 500 };
-      throw error;
-    };
-
-    try {
-      await retry(fn, {
-        maxRetries,
-        retryDelay: retryDelayGlobal,
-        retryOnAll: true,
-      });
-    } catch (error) {
-      expect(error.message).toStrictEqual('Error 500');
-      expect(callCount).toStrictEqual(maxRetries + 1);
-    }
-  });
-});

package/src/lib/ring-buffer/README.md

@@ -1,82 +0,0 @@
-# High-Performance Ring Buffer
-
-A high-performance ring buffer for single writer, multiple async readers with blocking semantics and offset tracking for coordination.
-
-## Key Features
-
-- **Double Buffering**: Eliminates wraparound logic for efficient batch reads
-- **Blocking Reads**: Readers block until data is available
-- **Multiple Independent Readers**: Each reader maintains its own position
-- **Offset Tracking**: Returns offset information for external coordination
-- **Zero-Copy Slicing**: Efficient batch operations using array slicing
-
-## Example Usage
-
-```javascript
-import RingBuffer from './index.js';
-
-const buffer = new RingBuffer(100);
-
-// Register readers
-const reader1 = buffer.registerReader();
-const reader2 = buffer.registerReader();
-
-// Write data
-buffer.write('message1');
-buffer.write('message2');
-buffer.write('message3');
-
-// Read single items with offset tracking
-const result1 = await buffer.read(reader1);
-// { data: 'message1', offset: 0 }
-
-// Read batches with offset tracking
-const batch = await buffer.readBatch(reader2, 2);
-// { data: ['message1', 'message2'], startOffset: 0, lastOffset: 1 }
-
-// Coordinate multiple readers using offsets
-const processedOffsets = new Map();
-processedOffsets.set(reader1, result1.offset);
-processedOffsets.set(reader2, batch.lastOffset);
-
-const minOffset = Math.min(...processedOffsets.values());
-console.log(`Safe to cleanup data up to offset ${minOffset}`);
-```
-
-## API
-
-### Constructor
-```javascript
-const buffer = new RingBuffer(maxSize);
-```
-
-### Reader Management
-```javascript
-const readerId = buffer.registerReader();
-buffer.unregisterReader(readerId);
-```
-
-### Writing
-```javascript
-const sequence = buffer.write(data);
-```
-
-### Reading
-```javascript
-// Single item - blocks until available
-const result = await buffer.read(readerId);
-// Returns: { data: any, offset: number }
-
-// Batch - blocks until full batch available
-const batch = await buffer.readBatch(readerId, batchSize);
-// Returns: { data: any[], startOffset: number, lastOffset: number }
-```
-
-### Utilities
-```javascript
-const stats = buffer.getStats();
-console.log(`Buffer usage: ${stats.sequence} items written`);
-console.log(`Active readers: ${stats.registeredReaders}`);
-console.log(`Waiting readers: ${stats.waitingReaders}`);
-```
-

package/src/lib/ring-buffer/index.js

@@ -1,235 +0,0 @@
-/**
- * High-performance ring buffer with single writer, multiple async readers.
- * Uses double-buffer technique to eliminate wraparound logic.
- * Optimized for performance over safety - assumes buffer is sized appropriately.
- */
-export default class RingBuffer {
-  constructor(maxSize = 1000) {
-    this.maxSize = maxSize;
-    this.writeIndex = 0;
-    this.sequence = 0;
-    this.nextReaderId = 0;
-
-    // Double buffer: second half mirrors first half for wraparound-free reads
-    this.buffer = new Array(maxSize * 2);
-
-    // Reader tracking - Map for O(1) lookups
-    this.readers = new Map(); // readerId -> lastReadSequence
-
-    // Notification system for blocking reads
-    this.waitingReaders = new Set(); // Set of { resolve, readerId, batchSize? }
-  }
-
-  /**
-   * Register a new reader.
-   * @returns {string} Reader ID
-   */
-  registerReader() {
-    const readerId = `r${this.nextReaderId++}`;
-    this.readers.set(readerId, -1);
-    return readerId;
-  }
-
-  /**
-   * Unregister a reader.
-   * @param {string} readerId
-   */
-  unregisterReader(readerId) {
-    this.readers.delete(readerId);
-    // Remove any waiting operations for this reader
-    for (const waiter of this.waitingReaders) {
-      if (waiter.readerId === readerId) {
-        if (waiter.batchSize) {
-          waiter.resolve({ data: [], startOffset: 0, lastOffset: -1 });
-        } else {
-          waiter.resolve({ data: null, offset: -1 });
-        }
-        this.waitingReaders.delete(waiter);
-      }
-    }
-  }
-
-  /**
-   * Write data to buffer (single writer only).
-   * @param {any} data
-   * @returns {number} Sequence number
-   */
-  write(data) {
-    const seq = this.sequence++;
-    const idx = this.writeIndex;
-
-    // Write to both positions (main and mirror)
-    this.buffer[idx] = data;
-    this.buffer[idx + this.maxSize] = data;
-
-    this.writeIndex = (this.writeIndex + 1) % this.maxSize;
-
-    // Notify waiting readers
-    this._notifyWaiters(seq);
-
-    return seq;
-  }
-
-  /**
-   * Read latest data for a reader (blocks until available).
-   * @param {string} readerId
-   * @returns {Promise<{data: any, offset: number}>}
-   */
-  read(readerId) {
-    const lastSeq = this.readers.get(readerId);
-    if (lastSeq === undefined) {
-      throw new Error(`Reader ${readerId} not registered`);
-    }
-
-    // Check if new data is available
-    if (this.sequence > lastSeq + 1) {
-      const nextSeq = lastSeq + 1;
-      const data = this._getDataAtSequence(nextSeq);
-      this.readers.set(readerId, nextSeq);
-      return Promise.resolve({ data, offset: nextSeq });
-    }
-
-    // No data available, wait for it
-    return new Promise((resolve) => {
-      this.waitingReaders.add({ resolve, readerId });
-    });
-  }
-
-  /**
-   * Read batch of data (blocks until batch is full).
-   * @param {string} readerId
-   * @param {number} batchSize
-   * @returns {Promise<{data: any[], startOffset: number, lastOffset: number}>}
-   */
-  readBatch(readerId, batchSize) {
-    const lastSeq = this.readers.get(readerId);
-    if (lastSeq === undefined) {
-      throw new Error(`Reader ${readerId} not registered`);
-    }
-
-    const availableCount = this.sequence - (lastSeq + 1);
-
-    if (availableCount >= batchSize) {
-      // Batch is ready
-      const result = this._readBatchSync(readerId, batchSize);
-      return Promise.resolve(result);
-    }
-
-    // Wait for full batch
-    return new Promise((resolve) => {
-      this.waitingReaders.add({ resolve, readerId, batchSize });
-    });
-  }
-
-  /**
-   * Get data at specific sequence (uses double buffer for wraparound-free access).
-   * @private
-   */
-  _getDataAtSequence(seq) {
-    const bufferPos = seq % this.maxSize;
-    return this.buffer[bufferPos];
-  }
-
-  /**
-   * Read batch synchronously when data is available.
-   * @private
-   */
-  _readBatchSync(readerId, batchSize) {
-    const lastSeq = this.readers.get(readerId);
-    const startSeq = lastSeq + 1;
-    const startPos = startSeq % this.maxSize;
-
-    // Use double buffer to avoid wraparound logic
-    const batch = this.buffer.slice(startPos, startPos + batchSize);
-
-    this.readers.set(readerId, lastSeq + batchSize);
-    return { data: batch, startOffset: startSeq, lastOffset: lastSeq + batchSize };
-  }
-
-  /**
-   * Notify waiting readers when new data arrives.
-   * @private
-   */
-  _notifyWaiters(newSeq) {
-    const toRemove = [];
-
-    for (const waiter of this.waitingReaders) {
-      const { resolve, readerId, batchSize } = waiter;
-      const lastSeq = this.readers.get(readerId);
-
-      if (lastSeq === undefined) continue; // Reader was unregistered
-
-      if (batchSize) {
-        // Batch reader
-        const availableCount = newSeq - lastSeq;
-        if (availableCount >= batchSize) {
-          const result = this._readBatchSync(readerId, batchSize);
-          resolve(result);
-          toRemove.push(waiter);
-        }
-      } else {
-        // Single reader
-        if (newSeq > lastSeq) {
-          const nextSeq = lastSeq + 1;
-          const data = this._getDataAtSequence(nextSeq);
-          this.readers.set(readerId, nextSeq);
-          resolve({ data, offset: nextSeq });
-          toRemove.push(waiter);
-        }
-      }
-    }
-
-    // Remove resolved waiters
-    for (const waiter of toRemove) {
-      this.waitingReaders.delete(waiter);
-    }
-  }
-
-  /**
-   * Get available data count for a reader.
-   * @param {string} readerId
-   * @returns {number}
-   */
-  getAvailableCount(readerId) {
-    const lastSeq = this.readers.get(readerId);
-    return lastSeq === undefined ? 0 : Math.max(0, this.sequence - (lastSeq + 1));
-  }
-
-  /**
-   * Get buffer statistics.
-   * @returns {object}
-   */
-  getStats() {
-    return {
-      maxSize: this.maxSize,
-      writeIndex: this.writeIndex,
-      sequence: this.sequence,
-      registeredReaders: this.readers.size,
-      waitingReaders: this.waitingReaders.size,
-    };
-  }
-
-  /**
-   * Clear buffer and reset state.
-   */
-  clear() {
-    this.writeIndex = 0;
-    this.sequence = 0;
-    this.buffer.fill(undefined);
-
-    // Reset reader sequences
-    for (const readerId of this.readers.keys()) {
-      this.readers.set(readerId, -1);
-    }
-
-    // Resolve all waiting readers with empty results
-    for (const waiter of this.waitingReaders) {
-      if (waiter.batchSize) {
-        waiter.resolve({ data: [], startOffset: 0, lastOffset: -1 });
-      } else {
-        waiter.resolve({ data: null, offset: -1 });
-      }
-    }
-    this.waitingReaders.clear();
-  }
-}