utilities

Work in Progress

This module is under active development and has not been battle-tested in production. The API may change between releases.

@gwigz/slua-modules/utilities provides rate-limiting primitives built on SLua's LLTimers API. Each function accepts a callback and a duration in seconds, and returns a [wrapped, cancel] tuple.

import { debounce, throttle, cooldown } from "@gwigz/slua-modules/utilities"

const [save, cancelSave] = debounce((id: UUID) => {
  ll.Say(0, `saved ${id}`)
}, 2)

LLEvents.on("touch_start", (detected) => {
  save(detected[0].getKey())
})

Choosing the right utility

Utility	Leading	Trailing	Drops calls	Use when
`debounce`	No	Yes	No, defers	You want to wait until activity stops
`throttle`	Yes	Yes	No, defers trailing	You want at most one call per interval
`cooldown`	Yes	No	Yes	You want a simple gate that drops repeats

Cancel

All three return a cancel function as the second tuple value. Calling it clears any pending timer and resets internal state so the wrapped function can be reused immediately.

const [fn, cancel] = throttle(() => ll.Say(0, "hi"), 5)

// later, clean up:
cancel()

API

Prop

Type

Examples

debounce

Delay a save action until 2 seconds of silence after the last touch:

const [save, cancelSave] = debounce((id: UUID) => {
  ll.Say(0, `saved ${id}`)
}, 2)

LLEvents.on("touch_start", (detected) => {
  save(detected[0].getKey()) // resets the 2s timer each touch
})

throttle

Rate-limit chat output to at most once per second:

const [say, cancelSay] = throttle((msg: string) => {
  ll.Say(0, msg)
}, 1)

LLEvents.on("touch_start", () => {
  say("touched!") // first fires immediately, trailing fires after 1s
})

cooldown

Gate an activation action to once every 5 seconds, dropping any extra calls:

const [activate, cancelCooldown] = cooldown((id: UUID) => {
  ll.Say(0, `activated by ${id}`)
}, 5)

LLEvents.on("touch_start", (detected) => {
  activate(detected[0].getKey()) // fires once, then drops calls for 5s
})