Public vals often use resources which have some usage limits ("quota"). Publishing such vals carries the risk that these quotas may be exceeded. For this reason, it makes sense to keep track of resource consumption and trigger a relevant response when a preset limit is reached (for example, one could provide the user with a meaningful error message). The "resettableQuotaTracker" is designed to help monitor resources that are replenished at a specific time (e.g., at a certain time each day or at the beginning of a month). Simply add an invocation of the "resettableQuotaTracker" into your val just before the tracked resource is going to be used and, from then on, that resource will be tracked and protected against excessive consumption. ## Usage Example ## Using a `resettableQuotaTracker` (within the val that requires the resource) is quite simple: ```javascript import { resettableQuotaTracker } from 'https://esm.town/v/rozek/resettableQuotaTracker' const ResourceTable = 'xxx' // enter name of sqlite table that can be used const ResourceLimit = 10 // max. number of allowed requests before reset ;(async () => { const Tracker = await resettableQuotaTracker.new(ResourceTable,ResourceLimit) let exceeded = await Tracker.LimitExceeded() // true if quota exceeded // can be used to chech the current status await Tracker.incrementIfAllowed() // increments resource usage if allowed // or throws a "LimitExceeded" exception otherwise ... now use your resource as usual })() ``` Simply enter the name of an sqlite table in `ResourceTable` where the resource consumption should be logged, and specify in `ResourceLimit` how many calls are allowed before the resource needs to be replenished. **The "resettableQuotaTracker" is designed to be accessed simultaneously from multiple vals without interfering with each other.** Resetting the consumption must be handled, for example, by a separate CRON job. ```javascript import { resettableQuotaTracker } from 'https://esm.town/v/rozek/resettableQuotaTracker' const ResourceTable = '' // enter name of sqlite table that can be used ;(async () => { const Tracker = await resettableQuotaTracker.new(ResourceTable) await Tracker.reset() })() ``` ## API Reference ## * `static async new (TableName:string, Limit:number=10):resettableQuotaTracker`
creates a new `resettableQuotaTracker` instance for the table `TableName` (which must match the RegEx pattern `/^[a-z_][0-9a-z_]+$/i`). If this table does not exist yet, it will be created automatically, with `Limit` set as the quota (`Limit` is optional and is only needed when the table is created). * `async isReady ():Promise`
returns a Promise that resolves to `true` as soon as the `resettableQuotaTracker` is available (this is unfortunately necessary because the constructor contains asynchronous code). * `async reset ():Promise`
can be used to reset the resource consumption back to 0. * `async Usage ():Promise`
returns the number of counted calls so far. * `async Limit ():Promise`
returns the currently configured limit. * `async setLimit (newLimit:number):Promise`
can be used to configure a new limit. * `async LimitExceeded ():Promise`
returns `true` if the configured limit has been reached or exceeded, or `false` if further calls are still allowed. * `async increment ():Promise`
increases the consumption counter by 1 (even if the configured limit has already been reached). * `async incrementIfAllowed ():Promise`
increases the consumption counter by 1 only if the configured limit has not yet been reached. **Important: the check and the incrementing of the counter occur in the same transaction**, allowing multiple `resettableQuotaTracker` instances to access the same table simultaneously. ## Tests ## Some tests can be found in val [resettableQuotaTracker_Test](https://www.val.town/v/rozek/resettableQuotaTracker_Test)