@ya-accelerators/web-backend-framework 0.0.52 → 0.0.54

package/dist/index.d.ts

@@ -1,7 +1,10 @@
 export * from './app/index.ts';
 export * from './env.ts';
+export * from './lock/index.ts';
 export * from './logger/index.ts';
 export * from './prisma/index.ts';
+export * from './rate-limit/index.ts';
 export * from './redis/index.ts';
 export * from './s3/index.ts';
+export * from './throttle/index.ts';
 export * from './util/index.ts';

package/dist/index.js

@@ -1,8 +1,11 @@
 export * from "./app/index.js";
 export * from "./env.js";
+export * from "./lock/index.js";
 export * from "./logger/index.js";
 export * from "./prisma/index.js";
+export * from "./rate-limit/index.js";
 export * from "./redis/index.js";
 export * from "./s3/index.js";
+export * from "./throttle/index.js";
 export * from "./util/index.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAA;AAC9B,cAAc,UAAU,CAAA;AACxB,cAAc,mBAAmB,CAAA;AACjC,cAAc,mBAAmB,CAAA;AACjC,cAAc,kBAAkB,CAAA;AAChC,cAAc,eAAe,CAAA;AAC7B,cAAc,iBAAiB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAA;AAC9B,cAAc,UAAU,CAAA;AACxB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,mBAAmB,CAAA;AACjC,cAAc,mBAAmB,CAAA;AACjC,cAAc,uBAAuB,CAAA;AACrC,cAAc,kBAAkB,CAAA;AAChC,cAAc,eAAe,CAAA;AAC7B,cAAc,qBAAqB,CAAA;AACnC,cAAc,iBAAiB,CAAA"}

package/dist/lock/index.d.ts

@@ -0,0 +1,27 @@
+export declare const lock: {
+    acquire: ({ key, ttlSec }: {
+        key: string;
+        ttlSec: number;
+    }) => Promise<string | null>;
+    release: ({ key, token }: {
+        key: string;
+        token: string;
+    }) => Promise<void>;
+    /**
+     * Run `fn` while holding the lock. Returns `{ acquired: false }` without
+     * invoking `fn` if the lock could not be acquired. Always releases the lock,
+     * even when `fn` throws.
+     *
+     * The discriminated return lets callers tell "lock not acquired" from "fn
+     * ran and returned undefined" — a plain `T | undefined` would collide.
+     */
+    withLock: <T>({ key, ttlSec }: {
+        key: string;
+        ttlSec: number;
+    }, fn: () => Promise<T>) => Promise<{
+        acquired: true;
+        value: T;
+    } | {
+        acquired: false;
+    }>;
+};

package/dist/lock/index.js

@@ -0,0 +1,62 @@
+import { Script } from '@valkey/valkey-glide';
+import { redis } from "../redis/index.js";
+import { Util } from "../util/index.js";
+/**
+ * Distributed mutex built on Redis SET NX + check-and-delete.
+ *
+ * Use to serialize work that must not run concurrently across processes —
+ * payout execution, batch jobs, anything where two concurrent runs would
+ * double-spend or corrupt state.
+ *
+ * `acquire` returns a unique token on success (null when the lock is held).
+ * `release` only deletes the key when the stored token still matches, so a
+ * TTL-expired-then-reacquired lock is never deleted by the original holder.
+ *
+ * Redis errors propagate as throws — callers decide whether to fail-closed
+ * via `.catch(() => null)` (acquire) or surface the failure.
+ *
+ * Note: even with the token check, a critical section that overruns `ttlSec`
+ * no longer holds the lock; another worker can enter while `fn` is still
+ * running. Pick `ttlSec` larger than the worst-case body duration.
+ */
+const RELEASE_SCRIPT = new Script(`
+if redis.call("GET", KEYS[1]) == ARGV[1] then
+  return redis.call("DEL", KEYS[1])
+else
+  return 0
+end
+`);
+export const lock = {
+    acquire: async ({ key, ttlSec }) => {
+        const token = Util.createULID();
+        const ok = await redis.setNx(key, token, ttlSec);
+        return ok != null ? token : null;
+    },
+    release: async ({ key, token }) => {
+        await redis.invokeScript(RELEASE_SCRIPT, { keys: [key], args: [token] });
+    },
+    /**
+     * Run `fn` while holding the lock. Returns `{ acquired: false }` without
+     * invoking `fn` if the lock could not be acquired. Always releases the lock,
+     * even when `fn` throws.
+     *
+     * The discriminated return lets callers tell "lock not acquired" from "fn
+     * ran and returned undefined" — a plain `T | undefined` would collide.
+     */
+    withLock: async ({ key, ttlSec }, fn) => {
+        const token = await lock.acquire({ key, ttlSec });
+        if (token === null) {
+            return { acquired: false };
+        }
+        try {
+            return { acquired: true, value: await fn() };
+        }
+        finally {
+            // Swallow release failures so a Redis blip in cleanup doesn't mask
+            // `fn`'s original exception. The framework-level redis.invokeScript
+            // already logs the failure, and the lock TTL guarantees recovery.
+            await lock.release({ key, token }).catch(() => undefined);
+        }
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/lock/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/lock/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAA;AAE7C,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AACzC,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAEvC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,cAAc,GAAG,IAAI,MAAM,CAAC;;;;;;CAMjC,CAAC,CAAA;AAEF,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB,OAAO,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,MAAM,EAAmC,EAA0B,EAAE;QAC1F,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,EAAE,CAAA;QAC/B,MAAM,EAAE,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,CAAC,CAAA;QAChD,OAAO,EAAE,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAA;IAClC,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,KAAK,EAAkC,EAAiB,EAAE;QAC/E,MAAM,KAAK,CAAC,YAAY,CAAC,cAAc,EAAE,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;IAC1E,CAAC;IACD;;;;;;;OAOG;IACH,QAAQ,EAAE,KAAK,EACb,EAAE,GAAG,EAAE,MAAM,EAAmC,EAChD,EAAoB,EACyC,EAAE;QAC/D,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAA;QACjD,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACnB,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAA;QAC5B,CAAC;QACD,IAAI,CAAC;YACH,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAA;QAC9C,CAAC;gBAAS,CAAC;YACT,mEAAmE;YACnE,oEAAoE;YACpE,kEAAkE;YAClE,MAAM,IAAI,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;QAC3D,CAAC;IACH,CAAC;CACF,CAAA"}

package/dist/rate-limit/index.d.ts

@@ -0,0 +1,16 @@
+export declare const rateLimit: {
+    /**
+     * Increment the counter for `key` and decide whether the current attempt is
+     * allowed. Returns the post-increment count and how many attempts remain in
+     * the current window.
+     */
+    attempt: ({ key, max, windowSec, }: {
+        key: string;
+        max: number;
+        windowSec: number;
+    }) => Promise<{
+        allowed: boolean;
+        count: number;
+        remaining: number;
+    }>;
+};

package/dist/rate-limit/index.js

@@ -0,0 +1,38 @@
+import { Script } from '@valkey/valkey-glide';
+import { redis } from "../redis/index.js";
+/**
+ * Fixed-window rate limiter built on a single atomic Lua script
+ * (INCR + EXPIRE on the first hit of a window).
+ *
+ * Use to cap the number of attempts against a key inside a rolling window —
+ * unauthenticated endpoints (password reset, signup, OTP request, etc.) that
+ * would otherwise be abusable by brute-force or spam.
+ *
+ * The INCR and EXPIRE run inside a Lua script, so the key is guaranteed to
+ * have a TTL whenever its value > 0 — an interrupt between the two ops is
+ * impossible.
+ *
+ * Redis errors propagate as throws — callers decide whether to fail-closed
+ * via `.catch(...)` or surface the failure.
+ */
+const ATTEMPT_SCRIPT = new Script(`
+local n = redis.call("INCR", KEYS[1])
+if n == 1 then redis.call("EXPIRE", KEYS[1], ARGV[1]) end
+return n
+`);
+export const rateLimit = {
+    /**
+     * Increment the counter for `key` and decide whether the current attempt is
+     * allowed. Returns the post-increment count and how many attempts remain in
+     * the current window.
+     */
+    attempt: async ({ key, max, windowSec, }) => {
+        const count = Number(await redis.invokeScript(ATTEMPT_SCRIPT, { keys: [key], args: [String(windowSec)] }));
+        return {
+            allowed: count <= max,
+            count,
+            remaining: Math.max(0, max - count),
+        };
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/rate-limit/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/rate-limit/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAA;AAE7C,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAEzC;;;;;;;;;;;;;;GAcG;AACH,MAAM,cAAc,GAAG,IAAI,MAAM,CAAC;;;;CAIjC,CAAC,CAAA;AAEF,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB;;;;OAIG;IACH,OAAO,EAAE,KAAK,EAAE,EACd,GAAG,EACH,GAAG,EACH,SAAS,GAKV,EAAmE,EAAE;QACpE,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,KAAK,CAAC,YAAY,CAAC,cAAc,EAAE,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;QAC1G,OAAO;YACL,OAAO,EAAE,KAAK,IAAI,GAAG;YACrB,KAAK;YACL,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,GAAG,KAAK,CAAC;SACpC,CAAA;IACH,CAAC;CACF,CAAA"}

package/dist/redis/index.d.ts

@@ -1,3 +1,4 @@
+import { type Script } from '@valkey/valkey-glide';
 export declare const redis: {
     health: () => Promise<"NG" | "OK">;
     set: (key: string, value: string, expirationSeconds?: number) => Promise<void>;
@@ -5,5 +6,10 @@ export declare const redis: {
     get: (key: string) => Promise<string | undefined>;
     remove: (key: string) => Promise<void>;
     incr: (key: string) => Promise<number>;
+    expire: (key: string, expirationSeconds: number) => Promise<boolean>;
     decr: (key: string) => Promise<number>;
+    invokeScript: (script: Script, opts: {
+        keys: string[];
+        args: string[];
+    }) => Promise<import("@valkey/valkey-glide").GlideReturnType>;
 };

package/dist/redis/index.js

@@ -84,6 +84,16 @@ export const redis = {
             throw e;
         }
     },
+    expire: async (key, expirationSeconds) => {
+        try {
+            const client = await getClient();
+            return await client.expire(key, expirationSeconds);
+        }
+        catch (e) {
+            logger.error('cache', { op: 'expire', key, error: e });
+            throw e;
+        }
+    },
     decr: async (key) => {
         try {
             const client = await getClient();
@@ -94,5 +104,15 @@ export const redis = {
             throw e;
         }
     },
+    invokeScript: async (script, opts) => {
+        try {
+            const client = await getClient();
+            return await client.invokeScript(script, opts);
+        }
+        catch (e) {
+            logger.error('cache', { op: 'invokeScript', key: opts.keys[0], error: e });
+            throw e;
+        }
+    },
 };
 //# sourceMappingURL=index.js.map

package/dist/redis/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/redis/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/redis/index.ts"],"names":[],"mappings":"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"}

package/dist/throttle/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * At-most-once-per-window throttle built on Redis SET NX.
+ *
+ * Use when an action should run at most once per `windowSec` — sanctions
+ * evaluation that should not re-fire on every call-log ingest, single-use
+ * token claims that must succeed exactly once across concurrent attempts.
+ *
+ * Unlike `lock`, there is no explicit release: the slot opens again only
+ * when the TTL expires.
+ *
+ * Redis errors propagate as throws — callers decide whether to fail-closed
+ * via `.catch(() => false)` or surface the failure.
+ */
+export declare const throttle: {
+    tryAcquire: ({ key, windowSec }: {
+        key: string;
+        windowSec: number;
+    }) => Promise<boolean>;
+};

package/dist/throttle/index.js

@@ -0,0 +1,21 @@
+import { redis } from "../redis/index.js";
+/**
+ * At-most-once-per-window throttle built on Redis SET NX.
+ *
+ * Use when an action should run at most once per `windowSec` — sanctions
+ * evaluation that should not re-fire on every call-log ingest, single-use
+ * token claims that must succeed exactly once across concurrent attempts.
+ *
+ * Unlike `lock`, there is no explicit release: the slot opens again only
+ * when the TTL expires.
+ *
+ * Redis errors propagate as throws — callers decide whether to fail-closed
+ * via `.catch(() => false)` or surface the failure.
+ */
+export const throttle = {
+    tryAcquire: async ({ key, windowSec }) => {
+        const ok = await redis.setNx(key, '1', windowSec);
+        return ok != null;
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/throttle/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/throttle/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAEzC;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,UAAU,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,SAAS,EAAsC,EAAoB,EAAE;QAC7F,MAAM,EAAE,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,SAAS,CAAC,CAAA;QACjD,OAAO,EAAE,IAAI,IAAI,CAAA;IACnB,CAAC;CACF,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ya-accelerators/web-backend-framework",
-  "version": "0.0.52",
+  "version": "0.0.54",
   "type": "module",
   "description": "",
   "author": "YA Technologies OÜ",