lunibee 0.3.1 → 0.3.2

package/dist/collection/index.d.ts

@@ -223,3 +223,4 @@ export declare class Collection<K, V> extends Map<K, V> {
 }
 export { Cache } from "./cache.js";
 export type { CacheOptions } from "./cache.js";
+export { RedisCollection, type RedisCollectionOptions, type RedisCommandClient, type RedisSerializer, } from "./redis.js";

package/dist/collection/index.js

@@ -56,6 +56,260 @@ class Cache {
     return [...this.#entries.entries()];
   }
 }
+// packages/collection/src/redis.ts
+var PRELUDE = `
+local exp, lru, clock, ep = KEYS[1], KEYS[2], KEYS[3], ARGV[1]
+local t = redis.call('TIME')
+local now = tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)
+local out = {}
+local function drop(m, reason)
+  local v = redis.call('GET', ep .. m)
+  redis.call('DEL', ep .. m)
+  redis.call('ZREM', exp, m)
+  redis.call('ZREM', lru, m)
+  if reason then
+    table.insert(out, m)
+    table.insert(out, v or false)
+    table.insert(out, reason)
+  end
+end
+local gone = redis.call('ZRANGEBYSCORE', exp, '-inf', now, 'LIMIT', 0, 1000)
+for _, m in ipairs(gone) do drop(m, 'expired') end
+local function touch(m) redis.call('ZADD', lru, redis.call('INCR', clock), m) end
+`;
+var SET_SCRIPT = `${PRELUDE}
+local m, payload, ttl, max, mode = ARGV[2], ARGV[3], tonumber(ARGV[4]), tonumber(ARGV[5]), ARGV[6]
+if mode == 'nx' then
+  local cur = redis.call('GET', ep .. m)
+  if cur then
+    touch(m)
+    table.insert(out, 1, cur)
+    return out
+  end
+end
+local env = ttl .. ':' .. payload
+if ttl > 0 then
+  -- The key outlives its logical expiry by a grace second, so the prune
+  -- that reports the expiry can still hand the value to onEvict.
+  redis.call('SET', ep .. m, env, 'PX', ttl + 1000)
+  redis.call('ZADD', exp, now + ttl, m)
+else
+  redis.call('SET', ep .. m, env)
+  redis.call('ZREM', exp, m)
+end
+touch(m)
+if max > 0 then
+  local n = redis.call('ZCARD', lru)
+  while n > max do
+    local popped = redis.call('ZPOPMIN', lru)
+    local victim = popped[1]
+    if victim == nil then break end
+    if victim ~= m then drop(victim, 'evicted') end
+    n = n - 1
+  end
+end
+table.insert(out, 1, false)
+return out
+`;
+var GET_SCRIPT = `${PRELUDE}
+local m, slide, mark = ARGV[2], ARGV[3], ARGV[4]
+local env = redis.call('GET', ep .. m)
+if not env then
+  redis.call('ZREM', exp, m)
+  redis.call('ZREM', lru, m)
+  table.insert(out, 1, false)
+  return out
+end
+if mark == '1' then touch(m) end
+if slide == '1' then
+  local ttl = tonumber(string.match(env, '^(%d+):'))
+  if ttl and ttl > 0 then
+    redis.call('PEXPIRE', ep .. m, ttl + 1000)
+    redis.call('ZADD', exp, now + ttl, m)
+  end
+end
+table.insert(out, 1, env)
+return out
+`;
+var DELETE_SCRIPT = `${PRELUDE}
+local m = ARGV[2]
+local existed = redis.call('EXISTS', ep .. m)
+drop(m, nil)
+table.insert(out, 1, existed)
+return out
+`;
+var LIST_SCRIPT = `${PRELUDE}
+local what = ARGV[2]
+if what == 'clear' then
+  local n = 0
+  repeat
+    local batch = redis.call('ZRANGE', lru, 0, 999)
+    for _, m in ipairs(batch) do drop(m, nil) end
+    n = n + #batch
+  until #batch == 0
+  redis.call('DEL', exp, lru, clock)
+  return {n}
+end
+local result = what == 'size' and redis.call('ZCARD', lru) or redis.call('ZRANGE', lru, 0, -1)
+return {result, unpack(out)}
+`;
+var EXPIRY_GRACE_MS = 1000;
+var JSON_SERIALIZER = {
+  serialize: (value) => JSON.stringify(value),
+  deserialize: (raw) => JSON.parse(raw)
+};
+
+class RedisCollection {
+  #redis;
+  #keys;
+  #ep;
+  #ttl;
+  #slide;
+  #maxSize;
+  #serializer;
+  #onEvict;
+  #stats = {
+    hits: 0,
+    misses: 0,
+    expired: 0,
+    evicted: 0
+  };
+  name;
+  constructor(options) {
+    if (typeof options.name !== "string" || !/^[\w.:-]{1,100}$/.test(options.name))
+      throw new TypeError("name must be 1-100 letters, digits, '_', '.', ':' or '-'.");
+    checkTTL(options.ttl);
+    if (options.maxSize !== undefined && !(Number.isInteger(options.maxSize) && options.maxSize > 0))
+      throw new RangeError("maxSize must be a positive integer.");
+    this.#redis = options.client;
+    this.name = options.name;
+    const base = `${options.prefix ?? "lunibee:collection:"}v1:{${options.name}}:`;
+    this.#keys = [`${base}exp`, `${base}lru`, `${base}clock`];
+    this.#ep = `${base}e:`;
+    this.#ttl = options.ttl ?? 0;
+    this.#slide = options.slide ?? true;
+    this.#maxSize = options.maxSize ?? 0;
+    this.#serializer = options.serializer ?? JSON_SERIALIZER;
+    this.#onEvict = options.onEvict;
+  }
+  get stats() {
+    return { ...this.#stats };
+  }
+  async#run(script, ...argv) {
+    const reply = await this.#redis.send("EVAL", [
+      script,
+      "3",
+      ...this.#keys,
+      this.#ep,
+      ...argv
+    ]);
+    if (!Array.isArray(reply))
+      throw new Error("Unexpected reply from a RedisCollection script.");
+    return reply;
+  }
+  #settle(reply, skip) {
+    for (let i = skip;i + 2 < reply.length + 0; i += 3) {
+      const key = String(reply[i]);
+      const raw = reply[i + 1];
+      const reason = reply[i + 2];
+      if (reason === "expired")
+        this.#stats.expired++;
+      else
+        this.#stats.evicted++;
+      if (!this.#onEvict)
+        continue;
+      let value;
+      try {
+        value = typeof raw === "string" ? this.#decode(raw) : undefined;
+      } catch {
+        value = undefined;
+      }
+      try {
+        this.#onEvict(key, value, reason);
+      } catch {}
+    }
+    return reply[0];
+  }
+  #decode(envelope) {
+    const colon = envelope.indexOf(":");
+    return this.#serializer.deserialize(envelope.slice(colon + 1));
+  }
+  async get(key) {
+    const raw = this.#settle(await this.#run(GET_SCRIPT, String(key), this.#slide ? "1" : "0", "1"), 1);
+    if (typeof raw !== "string") {
+      this.#stats.misses++;
+      return;
+    }
+    this.#stats.hits++;
+    return this.#decode(raw);
+  }
+  async peek(key) {
+    const raw = this.#settle(await this.#run(GET_SCRIPT, String(key), "0", "0"), 1);
+    return typeof raw === "string" ? this.#decode(raw) : undefined;
+  }
+  async has(key) {
+    return await this.peek(key) !== undefined;
+  }
+  async set(key, value, ttl) {
+    checkTTL(ttl, true);
+    this.#settle(await this.#run(SET_SCRIPT, String(key), this.#serializer.serialize(value), String(Math.ceil(ttl ?? this.#ttl)), String(this.#maxSize), "set"), 1);
+    return this;
+  }
+  setWithoutTTL(key, value) {
+    return this.set(key, value, 0);
+  }
+  async ensure(key, factory, ttl) {
+    const existing = await this.get(key);
+    if (existing !== undefined)
+      return existing;
+    checkTTL(ttl, true);
+    const value = await factory(String(key));
+    const raw = this.#settle(await this.#run(SET_SCRIPT, String(key), this.#serializer.serialize(value), String(Math.ceil(ttl ?? this.#ttl)), String(this.#maxSize), "nx"), 1);
+    return typeof raw === "string" ? this.#decode(raw) : value;
+  }
+  async delete(key) {
+    const reply = await this.#run(DELETE_SCRIPT, String(key));
+    return Number(this.#settle(reply, 1)) === 1;
+  }
+  async clear() {
+    const reply = await this.#run(LIST_SCRIPT, "clear");
+    return Number(reply[0]);
+  }
+  async size() {
+    return Number(this.#settle(await this.#run(LIST_SCRIPT, "size"), 1));
+  }
+  async keys() {
+    return this.#settle(await this.#run(LIST_SCRIPT, "keys"), 1).map(String);
+  }
+  async entries() {
+    const keys = await this.keys();
+    if (keys.length === 0)
+      return [];
+    const out = [];
+    for (let i = 0;i < keys.length; i += 1000) {
+      const batch = keys.slice(i, i + 1000);
+      const raws = await this.#redis.send("MGET", batch.map((k) => this.#ep + k));
+      raws.forEach((raw, j) => {
+        if (typeof raw === "string")
+          out.push([batch[j], this.#decode(raw)]);
+      });
+    }
+    return out;
+  }
+  async values() {
+    return (await this.entries()).map(([, value]) => value);
+  }
+  async ttlRemaining(key) {
+    const ms = Number(await this.#redis.send("PTTL", [this.#ep + String(key)]));
+    return ms >= 0 ? Math.max(0, ms - EXPIRY_GRACE_MS) : undefined;
+  }
+}
+function checkTTL(ttl, allowZero = false) {
+  if (ttl === undefined)
+    return;
+  if (!Number.isFinite(ttl) || ttl < 0 || !allowZero && ttl === 0)
+    throw new RangeError(allowZero ? "ttl must be 0 or a positive number." : "ttl must be a positive number.");
+}
 
 // packages/collection/src/index.ts
 function newPolicy(options = {}) {
@@ -114,21 +368,35 @@ class Collection extends Map {
         this.set(key, value);
   }
   set(key, value, ttl) {
-    if (ttl === undefined && this.#policy === undefined)
-      return super.set(key, value);
-    assertTTL(ttl);
-    let window = ttl ?? this.#policy?.ttl;
-    const jitter = this.#policy?.jitter ?? 0;
-    if (window !== undefined && jitter > 0)
-      window = Math.max(1, window * (1 - jitter * Math.random()));
-    if (window !== undefined)
-      this.#policy ??= newPolicy();
-    if (!this.#policy)
+    let policy = this.#policy;
+    if (ttl === undefined && policy === undefined)
       return super.set(key, value);
-    const before = super.size;
+    if (ttl !== undefined)
+      assertTTL(ttl);
+    let window = ttl ?? policy?.ttl;
+    if (window !== undefined && policy !== undefined && policy.jitter > 0)
+      window = Math.max(1, window * (1 - policy.jitter * Math.random()));
+    if (policy === undefined) {
+      if (window === undefined)
+        return super.set(key, value);
+      policy = this.#policy = newPolicy();
+    }
+    const entry = policy.entries.get(key);
     super.set(key, value);
-    this.#track(key, value, window, super.size !== before);
-    this.#enforceCap();
+    if (entry !== undefined && window !== undefined && entry.window !== 0) {
+      const deadline = Date.now() + window;
+      if (deadline >= entry.filed) {
+        entry.value = value;
+        entry.deadline = deadline;
+        entry.window = window;
+        if (entry.inLru)
+          this.#promote(policy, entry);
+        return this;
+      }
+    }
+    this.#track(key, value, window, entry);
+    if (policy.maxSize !== undefined && policy.lruSize > policy.maxSize)
+      this.#enforceCap();
     return this;
   }
   setWithoutTTL(key, value) {
@@ -284,10 +552,10 @@ class Collection extends Map {
       this.#unlink(policy, entry);
     policy.entries.delete(key);
   }
-  #track(key, value, window, isNew) {
+  #track(key, value, window, existing) {
     const policy = this.#policy;
     const lru = policy.maxSize !== undefined;
-    let entry = isNew ? undefined : policy.entries.get(key);
+    let entry = existing;
     if (entry)
       entry.value = value;
     if (window === undefined) {
@@ -419,11 +687,20 @@ class Collection extends Map {
     while (policy.lruSize > max) {
       const oldest = policy.oldest;
       const value = policy.onEvict ? super.get(oldest.key) : undefined;
-      this.#unlink(policy, oldest);
+      const next = oldest.newer;
+      policy.oldest = next;
+      if (next)
+        next.older = undefined;
+      else
+        policy.newest = undefined;
+      oldest.newer = undefined;
+      oldest.inLru = false;
+      policy.lruSize--;
       policy.entries.delete(oldest.key);
       super.delete(oldest.key);
       policy.evicted++;
-      this.#notify(oldest.key, value, "evicted");
+      if (policy.onEvict)
+        this.#notify(oldest.key, value, "evicted");
     }
   }
   #nextDeadline() {
@@ -838,7 +1115,8 @@ class Collection extends Map {
 }
 export {
   Cache,
-  Collection
+  Collection,
+  RedisCollection
 };
 
-//# debugId=44902D8F098C340964756E2164756E21
+//# debugId=8859F4CE73F8594764756E2164756E21