function asyncRateLimit<TFn>(fn, initialOptions): (...args) => Promise<undefined | ReturnType<TFn>>

function asyncRateLimit<TFn>(fn, initialOptions): (...args) => Promise<undefined | ReturnType<TFn>>

Definiert in: async-rate-limiter.ts:539

Erstellt eine asynchrone ratenbegrenzte Funktion, die die bereitgestellte Funktion bis zu einer maximalen Anzahl von Malen innerhalb eines Zeitfensters ausführt.

Im Gegensatz zum nicht-asynchronen Ratenbegrenzer unterstützt diese asynchrone Version die Rückgabe von Werten aus der ratenbegrenzten Funktion, was sie ideal für API-Aufrufe und andere asynchrone Operationen macht, bei denen Sie das Ergebnis des maybeExecute-Aufrufs anstelle der Festlegung des Ergebnisses in einer Zustandsvariable innerhalb der ratenbegrenzten Funktion wünschen.

Der Ratenbegrenzer unterstützt zwei Arten von Fenstern

• 'fixed': Ein striktes Fenster, das nach Ablauf des Zeitfensters zurückgesetzt wird. Alle Ausführungen innerhalb des Fensters zählen für das Limit, und das Fenster wird nach Ablauf der Periode vollständig zurückgesetzt.
• 'sliding': Ein rollierendes Fenster, das Ausführungen ermöglicht, sobald ältere abgelaufen sind. Dies sorgt für eine konsistentere Ausführungsrate im Laufe der Zeit.

Beachten Sie, dass Ratenbegrenzung eine einfachere Form der Ausführungskontrolle im Vergleich zu Throttling oder Debouncing ist

• Ein Ratenbegrenzer lässt alle Ausführungen zu, bis das Limit erreicht ist, und blockiert dann alle nachfolgenden Aufrufe, bis das Fenster zurückgesetzt wird
• Ein Throttle-Mechanismus sorgt für eine gleichmäßige Verteilung zwischen den Ausführungen, was für eine konsistente Leistung besser sein kann
• Ein Debouncer fasst mehrere Aufrufe zu einem zusammen, was besser für die Verarbeitung von Ereignisstößen ist

Zustandsverwaltung

• Verwendet TanStack Store für reaktives Zustandsmanagement
• Verwenden Sie initialState, um Anfangswerte für den Zustand bei der Erstellung des Ratenbegrenzers bereitzustellen
• initialState kann ein partielles Zustandsobjekt sein
• Verwenden Sie den Callback onSuccess, um auf die erfolgreiche Ausführung der Funktion zu reagieren und benutzerdefinierte Logik zu implementieren
• Verwenden Sie den Callback onError, um auf Fehler bei der Ausführung der Funktion zu reagieren und benutzerdefiniertes Fehlerhandling zu implementieren
• Verwenden Sie den Callback onSettled, um auf den Abschluss der Ausführung der Funktion (Erfolg oder Fehler) zu reagieren und benutzerdefinierte Logik zu implementieren
• Verwenden Sie den Callback onReject, um auf zurückgewiesene Ausführungen zu reagieren, wenn das Ratenlimit überschritten wird
• Der Zustand umfasst Ausführungszeiten, Erfolgs-/Fehlerzähler und den aktuellen Ausführungsstatus
• Der Zustand kann über die store.state-Eigenschaft der zugrunde liegenden AsyncRateLimiter-Instanz abgerufen werden
• Bei Verwendung von Framework-Adaptern (React/Solid) wird der Zustand aus der `state`-Eigenschaft des Hooks abgerufen

Erwägen Sie die Verwendung von throttle() oder debounce(), wenn Sie eine intelligentere Ausführungskontrolle benötigen. Verwenden Sie Ratenbegrenzung, wenn Sie speziell eine harte Grenze für die Anzahl der Ausführungen innerhalb eines Zeitraums durchsetzen müssen.

Fehlerbehandlung

• Wenn ein onError-Handler bereitgestellt wird, wird dieser mit dem Fehler und der Ratenbegrenzerinstanz aufgerufen
• Wenn throwOnError auf true gesetzt ist (Standardwert, wenn kein onError-Handler bereitgestellt wird), wird der Fehler ausgelöst.
• Wenn throwOnError auf false gesetzt ist (Standardwert, wenn ein onError-Handler bereitgestellt wird), wird der Fehler "verschluckt".
• Sowohl onError als auch throwOnError können zusammen verwendet werden – der Handler wird aufgerufen, bevor ein Fehler ausgelöst wird.
• Der Fehlerzustand kann mit der zugrunde liegenden AsyncRateLimiter-Instanz überprüft werden
• Ratenlimit-Zurückweisungen (wenn das Limit überschritten wird) werden getrennt von Ausführungsfehlern über den onReject-Handler behandelt

• TFn erbt von AnyAsyncFunction

TFn

AsyncRateLimiterOptions<TFn>

Funktion

Versucht, die ratenbegrenzte Funktion auszuführen, wenn sie innerhalb der konfigurierten Grenzen liegt. Die Ausführung wird zurückgewiesen, wenn die Anzahl der Aufrufe im aktuellen Fenster das Limit überschreitet.

Fehlerbehandlung

• Wenn die ratenbegrenzte Funktion einen Fehler auslöst und kein onError-Handler konfiguriert ist, wird der Fehler von dieser Methode ausgelöst.
• Wenn ein onError-Handler konfiguriert ist, werden Fehler abgefangen und an den Handler übergeben, und diese Methode gibt undefined zurück.
• Der Fehlerzustand kann mit getErrorCount() und getIsExecuting() überprüft werden.

...Parameters<TFn>

Promise<undefined | ReturnType<TFn>>

Ein Promise, das mit dem Rückgabewert der Funktion aufgelöst wird oder undefined, wenn ein Fehler aufgetreten und von onError behandelt wurde

Der Fehler aus der ratenbegrenzten Funktion, wenn kein onError-Handler konfiguriert ist

const rateLimiter = new AsyncRateLimiter(fn, { limit: 5, window: 1000 });

// First 5 calls will return a promise that resolves with the result
const result = await rateLimiter.maybeExecute('arg1', 'arg2');

// Additional calls within the window will return undefined
const result2 = await rateLimiter.maybeExecute('arg1', 'arg2'); // undefined

const rateLimiter = new AsyncRateLimiter(fn, { limit: 5, window: 1000 });

// First 5 calls will return a promise that resolves with the result
const result = await rateLimiter.maybeExecute('arg1', 'arg2');

// Additional calls within the window will return undefined
const result2 = await rateLimiter.maybeExecute('arg1', 'arg2'); // undefined

// Rate limit to 5 calls per minute with a sliding window
const rateLimited = asyncRateLimit(makeApiCall, {
  limit: 5,
  window: 60000,
  windowType: 'sliding',
  onError: (error) => {
    console.error('API call failed:', error);
  },
  onReject: (rateLimiter) => {
    console.log(`Rate limit exceeded. Try again in ${rateLimiter.getMsUntilNextWindow()}ms`);
  }
});

// First 5 calls will execute immediately
// Additional calls will be rejected until the minute window resets
// Returns the API response directly
const result = await rateLimited();

// For more even execution, consider using throttle instead:
const throttled = throttle(makeApiCall, { wait: 12000 }); // One call every 12 seconds

// Rate limit to 5 calls per minute with a sliding window
const rateLimited = asyncRateLimit(makeApiCall, {
  limit: 5,
  window: 60000,
  windowType: 'sliding',
  onError: (error) => {
    console.error('API call failed:', error);
  },
  onReject: (rateLimiter) => {
    console.log(`Rate limit exceeded. Try again in ${rateLimiter.getMsUntilNextWindow()}ms`);
  }
});

// First 5 calls will execute immediately
// Additional calls will be rejected until the minute window resets
// Returns the API response directly
const result = await rateLimited();

// For more even execution, consider using throttle instead:
const throttled = throttle(makeApiCall, { wait: 12000 }); // One call every 12 seconds