Funktion: useRateLimitedValue()

function useRateLimitedValue<TValue, TSelected>(
   value, 
   options, 
   selector?): [TValue, ReactRateLimiter<Dispatch<SetStateAction<TValue>>, TSelected>]

function useRateLimitedValue<TValue, TSelected>(
   value, 
   options, 
   selector?): [TValue, ReactRateLimiter<Dispatch<SetStateAction<TValue>>, TSelected>]

Definiert in: react-pacer/src/rate-limiter/useRateLimitedValue.ts:96

Ein High-Level React Hook, der eine ratenlimitierte Version eines Wertes erstellt, die sich höchstens eine bestimmte Anzahl von Malen innerhalb eines Zeitfensters aktualisiert. Dieser Hook verwendet intern Reacts useState zur Verwaltung des ratenlimitierten Zustands.

Ratenbegrenzung ist ein einfacher "Hartegrenze"-Ansatz – sie erlaubt alle Aktualisierungen, bis das Limit erreicht ist, und blockiert dann nachfolgende Aktualisierungen, bis das Fenster zurückgesetzt wird. Im Gegensatz zu Throttling oder Debouncing versucht sie nicht, Aktualisierungen zu verteilen oder intelligent zusammenzufassen. Dies kann zu Schüben schneller Aktualisierungen führen, gefolgt von Perioden ohne Aktualisierungen.

Der Ratenbegrenzer unterstützt zwei Arten von Fenstern

'fixed': Ein strenges Fenster, das nach der Fensterperiode zurückgesetzt wird. Alle Aktualisierungen innerhalb des Fensters zählen für das Limit, und das Fenster wird nach der Periode vollständig zurückgesetzt.
'sliding': Ein rollierendes Fenster, das Aktualisierungen zulässt, wenn alte ablaufen. Dies sorgt für eine konsistentere Rate von Aktualisierungen im Laufe der Zeit.

Für sanftere Aktualisierungsmuster sollten Sie in Betracht ziehen:

useThrottledValue: Wenn Sie konsistente Abstände zwischen Updates wünschen (z.B. UI-Änderungen)
useDebouncedValue: Wenn Sie schnelle Updates zu einem einzigen Update zusammenfassen möchten (z.B. Suchfeld)

Ratenbegrenzung sollte hauptsächlich verwendet werden, wenn Sie strenge Limits erzwingen müssen, wie z. B. API-Ratenlimits.

Der Hook gibt ein Tupel zurück, das enthält

Der ratenlimitierte Wert, der sich gemäß dem konfigurierten Ratenlimit aktualisiert
Die Ratenbegrenzer-Instanz mit Steuerungsmethoden

Für eine direktere Kontrolle über das Ratenbegrenzungsverhalten ohne React-Zustandsverwaltung sollten Sie stattdessen den einfacheren useRateLimiter Hook verwenden.

Zustandsverwaltung und Selektor

Der Hook verwendet TanStack Store zur reaktiven Zustandsverwaltung über die zugrunde liegende Ratenbegrenzer-Instanz. Der Parameter selector ermöglicht es Ihnen anzugeben, welche Zustandsänderungen des Ratenbegrenzers ein erneutes Rendern auslösen, wodurch die Leistung optimiert wird, indem unnötige Neu-Renderings bei irrelevanten Zustandsänderungen verhindert werden.

Standardmäßig erfolgen keine reaktiven Zustands-Subscriptions und Sie müssen das Zustands-Tracking durch Bereitstellen einer Selector-Funktion aktivieren. Dies verhindert unnötige Renderings und gibt Ihnen die volle Kontrolle darüber, wann Ihre Komponente aktualisiert wird. Nur wenn Sie einen Selector bereitstellen, wird die Komponente neu gerendert, wenn sich die ausgewählten Zustandswerte ändern.

Verfügbare ratenbegrenzte Zustandseigenschaften

executionCount: Anzahl der abgeschlossenen Funktionsaufrufe
executionTimes: Array von Zeitstempeln, wann Ausführungen für Ratenbegrenzungsberechnungen stattfanden
rejectionCount: Anzahl der Funktionsausführungen, die aufgrund von Ratenbegrenzung abgelehnt wurden

// Default behavior - no reactive state subscriptions
const [rateLimitedValue, rateLimiter] = useRateLimitedValue(rawValue, {
  limit: 5,
  window: 60000,
  windowType: 'sliding'
});

// Opt-in to re-render when execution count changes (optimized for tracking successful updates)
const [rateLimitedValue, rateLimiter] = useRateLimitedValue(
  rawValue,
  { limit: 5, window: 60000, windowType: 'sliding' },
  (state) => ({ executionCount: state.executionCount })
);

// Opt-in to re-render when rejection count changes (optimized for tracking rate limit violations)
const [rateLimitedValue, rateLimiter] = useRateLimitedValue(
  rawValue,
  { limit: 5, window: 60000, windowType: 'sliding' },
  (state) => ({ rejectionCount: state.rejectionCount })
);

// Opt-in to re-render when execution times change (optimized for window calculations)
const [rateLimitedValue, rateLimiter] = useRateLimitedValue(
  rawValue,
  { limit: 5, window: 60000, windowType: 'sliding' },
  (state) => ({ executionTimes: state.executionTimes })
);

// With rejection callback and fixed window
const [rateLimitedValue, rateLimiter] = useRateLimitedValue(rawValue, {
  limit: 3,
  window: 5000,
  windowType: 'fixed',
  onReject: (rateLimiter) => {
    console.log(`Update rejected. Try again in ${rateLimiter.getMsUntilNextWindow()}ms`);
  }
});

// Access the selected rate limiter state (will be empty object {} unless selector provided)
const { executionCount, rejectionCount } = rateLimiter.state;

// Default behavior - no reactive state subscriptions
const [rateLimitedValue, rateLimiter] = useRateLimitedValue(rawValue, {
  limit: 5,
  window: 60000,
  windowType: 'sliding'
});

// Opt-in to re-render when execution count changes (optimized for tracking successful updates)
const [rateLimitedValue, rateLimiter] = useRateLimitedValue(
  rawValue,
  { limit: 5, window: 60000, windowType: 'sliding' },
  (state) => ({ executionCount: state.executionCount })
);

// Opt-in to re-render when rejection count changes (optimized for tracking rate limit violations)
const [rateLimitedValue, rateLimiter] = useRateLimitedValue(
  rawValue,
  { limit: 5, window: 60000, windowType: 'sliding' },
  (state) => ({ rejectionCount: state.rejectionCount })
);

// Opt-in to re-render when execution times change (optimized for window calculations)
const [rateLimitedValue, rateLimiter] = useRateLimitedValue(
  rawValue,
  { limit: 5, window: 60000, windowType: 'sliding' },
  (state) => ({ executionTimes: state.executionTimes })
);

// With rejection callback and fixed window
const [rateLimitedValue, rateLimiter] = useRateLimitedValue(rawValue, {
  limit: 3,
  window: 5000,
  windowType: 'fixed',
  onReject: (rateLimiter) => {
    console.log(`Update rejected. Try again in ${rateLimiter.getMsUntilNextWindow()}ms`);
  }
});

// Access the selected rate limiter state (will be empty object {} unless selector provided)
const { executionCount, rejectionCount } = rateLimiter.state;

useRateLimitedValue

Funktion: useRateLimitedValue()

Zustandsverwaltung und Selektor

Typparameter

Parameter

value

optionen

selector?

Gibt zurück

Beispiel

Bytes abonnieren

Bytes abonnieren