soroban-events 0.1.0 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "soroban-events",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "Resilient, windowed event streamer and XDR decoder for Soroban RPC",
   "type": "module",
   "main": "./src/index.js",

package/src/decoder.js

@@ -2,6 +2,13 @@ import { scValToNative } from '@stellar/stellar-sdk';
 
 const DEFAULT_MAX_DEPTH = 50;
 
+class ScValDepthError extends Error {
+  constructor(maxDepth) {
+    super(`ScVal nesting exceeds maximum depth of ${maxDepth}`);
+    this.name = "ScValDepthError";
+  }
+}
+
 export function unwrapScVal(scVal, options = {}) {
   if (scVal == null) return null;
 
@@ -9,14 +16,15 @@ export function unwrapScVal(scVal, options = {}) {
 
   try {
     return normalizeNative(scValToNative(scVal), 0, maxDepth);
-  } catch {
+  } catch (error) {
+    if (error instanceof ScValDepthError) throw error;
     return parseScValDirect(scVal);
   }
 }
 
 function normalizeNative(value, depth, maxDepth) {
   if (depth > maxDepth) {
-    throw new Error(`ScVal nesting exceeds maximum depth of ${maxDepth}`);
+    throw new ScValDepthError(maxDepth);
   }
 
   if (value === null || value === undefined) return null;

package/src/streamer.js

@@ -45,15 +45,20 @@ export class SorobanEventStreamer {
     );
 
     this.pollInterval = options.pollInterval ?? 3000;
-    this.windowSize = Math.min(
-      options.windowSize ?? MAX_SAFE_LEDGER_SPAN,
-      MAX_SAFE_LEDGER_SPAN
-    );
 
-    this.pageSize = Math.min(
-      options.pageSize ?? DEFAULT_PAGE_SIZE,
-      10000
-    );
+    const windowSize = options.windowSize ?? MAX_SAFE_LEDGER_SPAN;
+    if (!Number.isInteger(windowSize) || windowSize < 1) {
+      throw new TypeError("windowSize must be a positive integer");
+    }
+
+    this.windowSize = Math.min(windowSize, MAX_SAFE_LEDGER_SPAN);
+
+    const pageSize = options.pageSize ?? DEFAULT_PAGE_SIZE;
+    if (!Number.isInteger(pageSize) || pageSize < 1 || pageSize > 10000) {
+      throw new TypeError("pageSize must be an integer between 1 and 10000");
+    }
+
+    this.pageSize = pageSize;
 
     this.maxRetries = options.maxRetries ?? 3;
     this.retryBaseMs = options.retryBaseMs ?? 500;
@@ -75,6 +80,10 @@ export class SorobanEventStreamer {
       throw new TypeError('startLedger must be a positive integer');
     }
 
+    if (!Number.isInteger(limit) || limit < 1) {
+      throw new TypeError('limit must be a positive integer');
+    }
+
     if (endLedger != null && (!Number.isInteger(endLedger) || endLedger < startLedger)) {
       throw new TypeError('endLedger must be >= startLedger');
     }
@@ -182,6 +191,70 @@ export class SorobanEventStreamer {
     return rawEvents.slice(0, limit);
   }
 
+  async fetchWindowNewest(
+    startLedger,
+    endLedgerExclusive,
+    filters,
+    limit,
+    signal
+  ) {
+    const newest = [];
+    let cursor;
+
+    while (true) {
+      if (signal?.aborted) {
+        throw new DOMException("Operation aborted", "AbortError");
+      }
+
+      const pagination = {
+        limit: this.pageSize
+      };
+
+      if (cursor) {
+        pagination.cursor = cursor;
+      }
+
+      const params = {
+        filters,
+        pagination
+      };
+
+      if (!cursor) {
+        params.startLedger = startLedger;
+        params.endLedger = endLedgerExclusive;
+      }
+
+      const response = await this.requestWithRetry(params, signal);
+      const events = response?.events ?? [];
+
+      for (const event of events) {
+        if (!event?.id) continue;
+
+        newest.push(event);
+
+        if (newest.length > limit) {
+          newest.shift();
+        }
+      }
+
+      const nextCursor = response?.cursor;
+
+      if (!nextCursor || events.length === 0) {
+        break;
+      }
+
+      if (nextCursor === cursor) {
+        throw new Error(
+          `RPC pagination cursor did not advance for ledger range ${startLedger}-${endLedgerExclusive}`
+        );
+      }
+
+      cursor = nextCursor;
+    }
+
+    return newest;
+  }
+
   async requestWithRetry(params, signal) {
     let attempt = 0;
 
@@ -217,7 +290,8 @@ export class SorobanEventStreamer {
     contractId,
     limit = 10,
     maxLookbackLedgers = 50000,
-    filters
+    filters,
+    signal
   } = {}) {
     if (limit <= 0) return [];
 
@@ -247,11 +321,12 @@ export class SorobanEventStreamer {
         endExclusive - this.windowSize
       );
 
-      const events = await this.fetchWindow(
+      const events = await this.fetchWindowNewest(
         start,
         endExclusive,
         effectiveFilters,
-        this.pageSize
+        limit,
+        signal
       );
 
       for (let i = events.length - 1; i >= 0; i--) {