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.

Using a resettableQuotaTracker (within the val that requires the resource) is quite simple:

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.

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()
})()

• 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<boolean>
  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<void>
  can be used to reset the resource consumption back to 0.
• async Usage ():Promise<number>
  returns the number of counted calls so far.
• async Limit ():Promise<number>
  returns the currently configured limit.
• async setLimit (newLimit:number):Promise<void>
  can be used to configure a new limit.
• async LimitExceeded ():Promise<boolean>
  returns true if the configured limit has been reached or exceeded, or false if further calls are still allowed.
• async increment ():Promise<void>
  increases the consumption counter by 1 (even if the configured limit has already been reached).
• async incrementIfAllowed ():Promise<void>
  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.

Some tests can be found in val resettableQuotaTracker_Test