A small in-memory TTL cache for MoonBit

ttl

cache

time-to-live

in-memory

moon add justjavac/ttl@0.1.2

Download zip

Author

justjavac

Version

0.1.2

License

MIT

Repository

github.com/justjavac/ttl

Last updated

24 days ago

Downloads

README

#justjavac/ttl

A small runtime-neutral TTL cache for MoonBit.

///|
test {
  let ttl : @ttl.TTL[String] = @ttl.TTL::new(default_ttl_ms=10_000L)

  assert_true(ttl.set("foo", "bar", now_ms=0L))

  guard ttl.get("foo", now_ms=1L) is Some("bar") else {
    fail("expected foo hit")
  }
  guard ttl.get("foo", now_ms=10_000L) is None else {
    fail("expected foo to expire")
  }
}

#
CacheEntry

source

pub(all) struct CacheEntry[T] {
  key : String
  val : T
  expire_ms : Int64
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

Item returned by TTL::entries.

#
EventKind

source

pub(all) enum EventKind {
  Hit
  Miss
  Expired
  Drop
  Set
  Del
} derive(Eq, Hash, @moonbitlang/core/debug.Debug
Debug)

Event kind emitted by a TTL cache.

impl Show for EventKind

#
Item

source

type Item[T]

#
Listener

source

type Listener[T]

#
SetEntry

source

pub(all) struct SetEntry[T] {
  key : String
  val : T
  ttl_ms : Int64?
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

Item accepted by TTL::mset.

#
SetEntry::new

source

fn[T] SetEntry::new(key : String, val : T, ttl_ms? : Int64) -> SetEntry[T]

Creates an entry for TTL::mset.

#
TTL

source

pub struct TTL[T] {
  store : Map[String, Item[T]]
  listeners : Map[EventKind, Array[Listener[T]]]
  default_ttl_ms : Int64
  capacity : Int
  next_listener_id : Int
}

A generic in-memory time-to-live cache.

The cache is runtime-neutral: callers pass now_ms to methods that need a clock. Expired values are removed lazily on reads or explicit cleanup.

#
TTL::add_listener

source

fn[T] TTL::add_listener(self : TTL[T], kind : EventKind, callback : (TTLEvent[T]) -> Unit) -> Int

Registers an event listener and returns its listener id.

#
TTL::capacity

source

fn[T] TTL::capacity(self : TTL[T]) -> Int

Returns the maximum number of keys accepted by the cache.

#
TTL::clear

source

fn[T] TTL::clear(self : TTL[T]) -> Unit

Removes all keys, emitting Del for each removed item.

#
TTL::default_ttl_ms

source

fn[T] TTL::default_ttl_ms(self : TTL[T]) -> Int64

Returns the configured default TTL in milliseconds.

#
TTL::del

source

fn[T] TTL::del(self : TTL[T], key : String) -> T?

Deletes a key and returns its value when present.

#
TTL::entries

source

fn[T] TTL::entries(self : TTL[T], now_ms~ : Int64) -> Array[CacheEntry[T]]

Returns unexpired cache entries. Expired keys are purged before the snapshot is produced.

#
TTL::get

source

fn[T] TTL::get(self : TTL[T], key : String, now_ms~ : Int64) -> T?

Gets a value by key and removes it first if it has expired.

#
TTL::has

source

fn[T] TTL::has(self : TTL[T], key : String, now_ms~ : Int64) -> Bool

Returns whether a key exists and has not expired.

#
TTL::mset

source

fn[T] TTL::mset(self : TTL[T], entries : ArrayView[SetEntry[T]], now_ms~ : Int64) -> Int

Sets multiple keys and returns the number accepted by the cache.

#
TTL::new

source

fn[T] TTL::new(default_ttl_ms? : Int64, capacity? : Int) -> TTL[T]

Creates an empty TTL cache.

#
TTL::purge_expired

source

fn[T] TTL::purge_expired(self : TTL[T], now_ms~ : Int64) -> Int

Removes all expired keys and returns the number removed.

#
TTL::remove_listener

source

fn[T] TTL::remove_listener(self : TTL[T], kind : EventKind, listener_id : Int) -> Bool

Removes a previously registered listener.

#
TTL::set

source

fn[T] TTL::set(self : TTL[T], key : String, val : T, now_ms~ : Int64, ttl_ms? : Int64) -> Bool

Sets a key-value pair. Returns false when a new key is dropped because the cache is at capacity.

#
TTL::set_capacity

source

fn[T] TTL::set_capacity(self : TTL[T], capacity : Int) -> Bool

Updates cache capacity. Negative values are rejected.

#
TTL::set_default_ttl_ms

source

fn[T] TTL::set_default_ttl_ms(self : TTL[T], ttl_ms : Int64) -> Unit

Updates the default TTL in milliseconds.

#
TTL::size

source

fn[T] TTL::size(self : TTL[T], now_ms? : Int64) -> Int

Returns the number of stored keys. When now_ms is supplied, expired keys are purged before counting.

#
TTLEvent

source

pub(all) struct TTLEvent[T] {
  kind : EventKind
  key : String
  val : T?
  expire_ms : Int64?
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

Event payload passed to cache listeners.

Source Files

Site source Report issue Packages Build queue Skills Statistics

ttl

#justjavac/ttl

#CacheEntry

#EventKind

#Item

#Listener

#SetEntry

#SetEntry::new

#TTL

#TTL::add_listener

#TTL::capacity

#TTL::clear

#TTL::default_ttl_ms

#TTL::del

#TTL::entries

#TTL::get

#TTL::has

#TTL::mset

#TTL::new

#TTL::purge_expired

#TTL::remove_listener

#TTL::set

#TTL::set_capacity

#TTL::set_default_ttl_ms

#TTL::size

#TTLEvent

Source Files

#
CacheEntry

#
EventKind

#
Item

#
Listener

#
SetEntry

#
SetEntry::new

#
TTL

#
TTL::add_listener

#
TTL::capacity

#
TTL::clear

#
TTL::default_ttl_ms

#
TTL::del

#
TTL::entries

#
TTL::get

#
TTL::has

#
TTL::mset

#
TTL::new

#
TTL::purge_expired

#
TTL::remove_listener

#
TTL::set

#
TTL::set_capacity

#
TTL::set_default_ttl_ms

#
TTL::size

#
TTLEvent