ts-server-lib 0.0.48

package/db/TSRedisTB.d.ts

@@ -0,0 +1,80 @@
+/**
+ * TSRedisTB — a cross-process token-bucket rate budget shared by every process/replica that draws from the SAME Redis,
+ * so a per-credential / per-operator cap is honoured fleet-wide instead of statically divided (N replicas each
+ * believing they own the whole allowance). A topology-aware primitive built on {@link TSRedis} — like {@link TSRQW},
+ * it does not care whether the fleet is cluster workers, `docker scale N`, or k8s pods: they all draw from one bucket,
+ * so the sum of grants across ANY number of processes can never exceed the cap. No process needs to know the live
+ * replica count.
+ *
+ * `take(want)` is ONE atomic Lua round trip: refill by elapsed time, grant `min(floor(tokens), want)`, persist the
+ * remainder. Atomicity is the whole guarantee — two processes asking for the last token at the same instant cannot
+ * both be granted it. The key is hash-tagged (`{ratelimit:<scope>}`) so the script stays single-slot on a cluster.
+ *
+ * Optional / fail-open by design: pass `null` as the client (or `perSecond <= 0`) and every `take` grants in full —
+ * an unwired or absent shared cap must never block the caller. That makes it safe to reach for in a host that may or
+ * may not have Redis: single-process / no-Redis deployments simply pace themselves elsewhere.
+ */
+import { type TSRedisClient } from './TSRedis';
+export interface TokenGrant {
+    /** Tokens actually handed out, 0..want. */
+    granted: number;
+    /** When another token is expected, in ms (0 when some were granted). */
+    retryAfterMs: number;
+}
+export interface TSRedisTBOptions {
+    /** Budget identity — the shared cap (e.g. the operator id). Every process using the same `scope` draws one budget. */
+    scope: string;
+    /** Sustained refill rate (the operator cap). */
+    perSecond: number;
+    /** Bucket depth (max burst). Default: `perSecond`. */
+    burst?: number;
+    /** Time source — injectable for determinism; defaults to the system clock. */
+    now?: () => number;
+}
+export declare class TSRedisTB {
+    #private;
+    constructor(client: TSRedisClient | null, opts: TSRedisTBOptions);
+    /** The configured sustained rate (the shared cap), for reporting. */
+    get perSecond(): number;
+    /** The configured bucket depth (max burst). */
+    get burst(): number;
+    /** Atomically claim up to `want` tokens from the shared budget. Fail-open (grant all) when unwired (no Redis) or
+     *  unlimited (`perSecond <= 0`) — an absent shared cap must never block the caller. */
+    take(want: number): Promise<TokenGrant>;
+}
+/** Default tokens to claim per shared-bucket round trip: ~100ms of tokens, capped by burst, floored at 1. */
+export declare function reservationBatch(perSecond: number, burst: number): number;
+/** Result of {@link TSRedisTBReservation.acquire}. `retryAfterMs` is a wait hint when not admitted. */
+export interface Admission {
+    admitted: boolean;
+    retryAfterMs: number;
+}
+/**
+ * A LOCAL token reservation over a shared {@link TSRedisTB} — the reusable "amortise the round trip" layer both the
+ * durable queue ({@link TSRQW}'s rate limit) and per-driver consumers build on, so the batching + coalescing logic
+ * lives in ONE place.
+ *
+ * `acquire()` spends a locally-reserved token with NO round trip; when empty it claims `batch` tokens from the
+ * shared bucket in ONE atomic round trip and serves them locally. Concurrent acquirers COALESCE onto the same
+ * in-flight claim (a burst of N costs one round trip, not N). The shared bucket is still the ceiling — a batch is
+ * claimed atomically, so N processes never exceed the cap; unspent reserved tokens on a crash are simply lost
+ * (safe under-admission). Fail-open is inherited from the bucket (`perSecond <= 0` / no Redis ⇒ every claim grants,
+ * so a reservation is never a blocker when the cap is unset). Construct ONE per consumer (per driver / per queue).
+ */
+export declare class TSRedisTBReservation {
+    #private;
+    constructor(bucket: TSRedisTB, batch?: number);
+    /** Admit one unit against the shared cap, amortising the round trip across the batch. */
+    acquire(): Promise<Admission>;
+}
+export interface TokenBucketCheck {
+    name: string;
+    ok: boolean;
+    detail?: string;
+}
+/**
+ * Conformance suite for any `TSRedisTB`-shaped budget (the counterpart of `checkJournalContract`). `make` returns a
+ * bucket for a FRESH, unique scope on each call so the checks do not collide — back it with a live Redis. Proves the
+ * properties that make the budget a real shared cap: burst grant, drain, refill, partial, and fail-open.
+ */
+export declare function checkTokenBucketContract(make: (opts: TSRedisTBOptions) => TSRedisTB, scopePrefix?: string): Promise<TokenBucketCheck[]>;

package/db/TSRedisTB.js

@@ -0,0 +1,178 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TSRedisTBReservation = exports.TSRedisTB = void 0;
+exports.reservationBatch = reservationBatch;
+exports.checkTokenBucketContract = checkTokenBucketContract;
+/**
+ * TSRedisTB — a cross-process token-bucket rate budget shared by every process/replica that draws from the SAME Redis,
+ * so a per-credential / per-operator cap is honoured fleet-wide instead of statically divided (N replicas each
+ * believing they own the whole allowance). A topology-aware primitive built on {@link TSRedis} — like {@link TSRQW},
+ * it does not care whether the fleet is cluster workers, `docker scale N`, or k8s pods: they all draw from one bucket,
+ * so the sum of grants across ANY number of processes can never exceed the cap. No process needs to know the live
+ * replica count.
+ *
+ * `take(want)` is ONE atomic Lua round trip: refill by elapsed time, grant `min(floor(tokens), want)`, persist the
+ * remainder. Atomicity is the whole guarantee — two processes asking for the last token at the same instant cannot
+ * both be granted it. The key is hash-tagged (`{ratelimit:<scope>}`) so the script stays single-slot on a cluster.
+ *
+ * Optional / fail-open by design: pass `null` as the client (or `perSecond <= 0`) and every `take` grants in full —
+ * an unwired or absent shared cap must never block the caller. That makes it safe to reach for in a host that may or
+ * may not have Redis: single-process / no-Redis deployments simply pace themselves elsewhere.
+ */
+const TSRedis_1 = require("./TSRedis");
+// Atomic take: refill from elapsed, grant min(floor(tokens), want), store the remainder + a 60s idle expiry.
+// Returns { granted, retryAfterMs }. Fractional tokens live in the hash (float string); the reply is integers.
+const TAKE_LUA = `
+local want = tonumber(ARGV[1])
+local perSecond = tonumber(ARGV[2])
+local burst = tonumber(ARGV[3])
+local now = tonumber(ARGV[4])
+local tokens = tonumber(redis.call('HGET', KEYS[1], 'tokens'))
+local at = tonumber(redis.call('HGET', KEYS[1], 'at'))
+if tokens == nil then tokens = burst; at = now end
+tokens = math.min(burst, tokens + (now - at) * perSecond / 1000)
+local granted = math.min(math.floor(tokens), want)
+tokens = tokens - granted
+redis.call('HSET', KEYS[1], 'tokens', tokens, 'at', now)
+redis.call('PEXPIRE', KEYS[1], 60000)
+local retry = 0
+if granted == 0 and perSecond > 0 then
+  retry = math.ceil((1 - tokens) / perSecond * 1000)
+  if retry < 1 then retry = 1 end
+end
+return { granted, retry }`;
+class TSRedisTB {
+    #client;
+    #key;
+    #perSecond;
+    #burst;
+    #now;
+    constructor(client, opts) {
+        this.#client = client;
+        this.#key = `{ratelimit:${opts.scope}}:tb`;
+        this.#perSecond = opts.perSecond;
+        this.#burst = Math.max(1, opts.burst ?? opts.perSecond);
+        this.#now = opts.now ?? (() => Date.now());
+    }
+    /** The configured sustained rate (the shared cap), for reporting. */
+    get perSecond() {
+        return this.#perSecond;
+    }
+    /** The configured bucket depth (max burst). */
+    get burst() {
+        return this.#burst;
+    }
+    /** Atomically claim up to `want` tokens from the shared budget. Fail-open (grant all) when unwired (no Redis) or
+     *  unlimited (`perSecond <= 0`) — an absent shared cap must never block the caller. */
+    async take(want) {
+        if (this.#client === null || this.#perSecond <= 0)
+            return { granted: want, retryAfterMs: 0 };
+        const res = (await (0, TSRedis_1.evalTaggedScript)(this.#client, {
+            keys: [this.#key],
+            argv: [String(want), String(this.#perSecond), String(this.#burst), String(this.#now())],
+            source: TAKE_LUA
+        }));
+        const granted = Number(res?.[0] ?? 0);
+        const retryAfterMs = Number(res?.[1] ?? 0);
+        return { granted, retryAfterMs };
+    }
+}
+exports.TSRedisTB = TSRedisTB;
+/** Default tokens to claim per shared-bucket round trip: ~100ms of tokens, capped by burst, floored at 1. */
+function reservationBatch(perSecond, burst) {
+    return Math.max(1, Math.min(burst, Math.ceil(Math.max(1, perSecond) / 10)));
+}
+/**
+ * A LOCAL token reservation over a shared {@link TSRedisTB} — the reusable "amortise the round trip" layer both the
+ * durable queue ({@link TSRQW}'s rate limit) and per-driver consumers build on, so the batching + coalescing logic
+ * lives in ONE place.
+ *
+ * `acquire()` spends a locally-reserved token with NO round trip; when empty it claims `batch` tokens from the
+ * shared bucket in ONE atomic round trip and serves them locally. Concurrent acquirers COALESCE onto the same
+ * in-flight claim (a burst of N costs one round trip, not N). The shared bucket is still the ceiling — a batch is
+ * claimed atomically, so N processes never exceed the cap; unspent reserved tokens on a crash are simply lost
+ * (safe under-admission). Fail-open is inherited from the bucket (`perSecond <= 0` / no Redis ⇒ every claim grants,
+ * so a reservation is never a blocker when the cap is unset). Construct ONE per consumer (per driver / per queue).
+ */
+class TSRedisTBReservation {
+    #bucket;
+    #batch;
+    #reserved = 0;
+    #refill = null;
+    #retryMs = 0;
+    constructor(bucket, batch) {
+        this.#bucket = bucket;
+        this.#batch = Math.max(1, batch ?? reservationBatch(bucket.perSecond, bucket.burst));
+    }
+    /** Admit one unit against the shared cap, amortising the round trip across the batch. */
+    async acquire() {
+        if (this.#reserved >= 1) {
+            this.#reserved -= 1;
+            return { admitted: true, retryAfterMs: 0 };
+        }
+        // Coalesce concurrent claims into ONE round trip: every acquirer awaits the SAME in-flight take.
+        this.#refill ??= this.#bucket.take(this.#batch).then((g) => { this.#reserved += g.granted; this.#retryMs = g.retryAfterMs; this.#refill = null; });
+        await this.#refill;
+        if (this.#reserved >= 1) {
+            this.#reserved -= 1;
+            return { admitted: true, retryAfterMs: 0 };
+        }
+        return { admitted: false, retryAfterMs: this.#retryMs };
+    }
+}
+exports.TSRedisTBReservation = TSRedisTBReservation;
+/**
+ * Conformance suite for any `TSRedisTB`-shaped budget (the counterpart of `checkJournalContract`). `make` returns a
+ * bucket for a FRESH, unique scope on each call so the checks do not collide — back it with a live Redis. Proves the
+ * properties that make the budget a real shared cap: burst grant, drain, refill, partial, and fail-open.
+ */
+async function checkTokenBucketContract(make, scopePrefix = 'contract') {
+    const checks = [];
+    const push = (name, ok, detail) => {
+        checks.push(detail === undefined ? { name, ok } : { name, ok, detail });
+    };
+    let seq = 0;
+    const freshScope = () => `${scopePrefix}:${seq++}`;
+    // A fixed clock so refill is deterministic — the bucket reads `now()` on every take.
+    let clock = 0;
+    const now = () => clock;
+    // 1. A fresh bucket grants up to `burst` immediately.
+    {
+        clock = 1_000_000;
+        const b = make({ scope: freshScope(), perSecond: 10, burst: 5, now });
+        const g = await b.take(5);
+        push('grants up to burst on a fresh bucket', g.granted === 5, `granted=${g.granted}`);
+    }
+    // 2. Draining past the burst grants nothing more within the same instant, and reports a positive retry.
+    {
+        clock = 2_000_000;
+        const b = make({ scope: freshScope(), perSecond: 10, burst: 5, now });
+        await b.take(5);
+        const g = await b.take(1);
+        push('never grants past the burst when drained', g.granted === 0, `granted=${g.granted}`);
+        push('reports a positive retryAfterMs when empty', g.retryAfterMs > 0, `retryAfterMs=${g.retryAfterMs}`);
+    }
+    // 3. Refills by elapsed time: after 1s at 10/s, ~10 tokens are available again (capped at burst).
+    {
+        clock = 3_000_000;
+        const b = make({ scope: freshScope(), perSecond: 10, burst: 20, now });
+        await b.take(20); // drain
+        clock += 1_000; // one second later
+        const g = await b.take(20);
+        push('refills by elapsed time', g.granted >= 9 && g.granted <= 11, `granted=${g.granted}`);
+    }
+    // 4. A partial grant hands out only what is available, not the full ask.
+    {
+        clock = 4_000_000;
+        const b = make({ scope: freshScope(), perSecond: 10, burst: 3, now });
+        const g = await b.take(10);
+        push('grants only what is available on a partial ask', g.granted === 3, `granted=${g.granted}`);
+    }
+    // 5. Fail-open when unlimited (perSecond <= 0): grants the full ask regardless of Redis.
+    {
+        const b = make({ scope: freshScope(), perSecond: 0, now });
+        const g = await b.take(1000);
+        push('fails open when unlimited (perSecond<=0)', g.granted === 1000, `granted=${g.granted}`);
+    }
+    return checks;
+}

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "ts-server-lib",
+  "version": "0.0.48",
+  "scripts": {
+    "prepublishOnly": "npm run build",
+    "postpublish": "npm run clean:artifacts",
+    "build": "tsc --declaration -p .",
+    "watch": "tsc -w --declaration -p .",
+    "clean:artifacts": "node -e \"const fs=require('fs'),path=require('path');const root=process.cwd();for(const rel of ['db','ussd','ussd/providers','utils','ws']){const dir=path.join(root,rel);let n;try{n=fs.readdirSync(dir)}catch{continue}for(const name of n){if(!name.endsWith('.d.ts')&&path.extname(name)!=='.js')continue;const fp=path.join(dir,name);try{if(fs.statSync(fp).isFile())fs.unlinkSync(fp)}catch{}}}\"",
+    "clean:deps": "node -e \"for(const p of ['coverage','node_modules','package-lock.json'])try{require('fs').rmSync(p,{recursive:true,force:true})}catch{}\"",
+    "clean": "npm run clean:artifacts && npm run clean:deps",
+    "lint": "oxlint --fix",
+    "test": "npm run build && vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/onalbi/ts-server-lib"
+  },
+  "author": {
+    "name": "Albion Liçi",
+    "email": "lici.albion@gmail.com"
+  },
+  "keywords": [
+    "typescript",
+    "server"
+  ],
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/onalbi/ts-server-lib/issues"
+  },
+  "files": [
+    "db/**/*.{js,d.ts}",
+    "utils/**/*.{js,d.ts}",
+    "ussd/**/*.{js,d.ts}",
+    "utils/mime.json"
+  ],
+  "dependencies": {
+    "cron": "^4.4.0",
+    "fast-xml-parser": "^5.8.0",
+    "i18n": "^0.15.3",
+    "mongodb": "^7.2.0",
+    "redis": "^6.0.0",
+    "ts-common-lib": "latest"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "vitest": {
+    "globals": true,
+    "environment": "node",
+    "include": [
+      "test/**/*.spec.ts"
+    ],
+    "exclude": [
+      "**/*.spec.js",
+      "**/node_modules/**"
+    ],
+    "resolve": {
+      "extensions": [
+        ".ts",
+        ".tsx",
+        ".mts",
+        ".cts",
+        ".js",
+        ".mjs",
+        ".jsx",
+        ".json"
+      ]
+    },
+    "coverage": {
+      "provider": "v8",
+      "include": [
+        "db/**/*.ts",
+        "ussd/**/*.ts",
+        "utils/**/*.ts"
+      ],
+      "reporter": [
+        "text",
+        "lcov"
+      ]
+    }
+  }
+}

package/ussd/TSUssdMenu.d.ts

@@ -0,0 +1,139 @@
+/**
+ *  USSD Menu with state
+ *
+ *  - General rules
+ *      - Routing
+ *          - ussd text in form 1*2*7
+ *          - * bring back to start menu
+ *
+ *  - Development Section
+ *      - To publish local ussd receiver to remote through ssh
+ *      # ssh -R 9093:localhost:9090 root@185.41.154.247 -N
+ *
+ */
+import { EventEmitter } from 'events';
+export declare class TSUssdState {
+    menu: TSUssdMenu;
+    name: string | null;
+    run: ((state: TSUssdState) => void) | null;
+    defaultNext: string | null;
+    val: string | null;
+    next: Record<string, unknown> | null;
+    constructor(menu: TSUssdMenu);
+}
+export declare class TSUssdMenu extends EventEmitter {
+    map: Record<string, unknown>;
+    static START_STATE: string;
+    static config: any;
+    session: any;
+    args: any;
+    states: any;
+    result: string;
+    onResult: any;
+    current: any;
+    val: string;
+    static forOwn(items: unknown[] | Record<string, unknown>, cb: (v: unknown, key?: number | string) => void): void;
+    static mapArgs(args?: Record<string, unknown>, map?: Record<string, unknown>): Record<string, unknown>;
+    static cleanRoute(route: string): string;
+    constructor(args: Record<string, unknown> | undefined, map: Record<string, unknown>);
+    /**
+     * A callback after result is set
+     */
+    callOnResult(): void;
+    /**
+     * This method send message to the client and take the session opened
+     *
+     * @param text string Message to sent
+     */
+    con(text: string): string;
+    /**
+     * This method send message to the client and close the session
+     *
+     * @param text string Message to sent
+     */
+    end(text: string): string;
+    /**
+    * This method format the message and if debug calcualte the length
+    *
+    * @param text string Message to sent
+    */
+    print(text: string): string;
+    testLinkRule(rule: string | RegExp | unknown, val: string): boolean;
+    /**
+     * Find state based on route — async/await, no external dependencies.
+     *
+     * next values may be: a string, a callback-based function (cb) => void,
+     * a function returning a string synchronously, or a function returning a Promise.
+     */
+    resolveRoute(route: string): Promise<TSUssdState | undefined>;
+    runState(state: TSUssdState): boolean | undefined;
+    go(stateName: string): void;
+    goStart(): void;
+    /**
+     * Configure custom session handler cross-compatible between callbacks and promises
+     *
+     * @example Memory configuration example with callback
+     *
+     * let sessions = {};
+     * let menu = new UssdMenu();
+     * menu.sessionConfig({
+     *   start: (sessionId, callback) {
+     *     // initialize current session if it doesn't exist this is called by menu.run()
+     *     if(!(sessionId in sessions)) sessions[sessionId] = {};
+     *     callback();
+     *   },
+     *   end: (sessionId, callback) {
+     *     // clear current session this is called by menu.end()
+     *     delete sessions[sessionId];
+     *     callback();
+     *   },
+     *   set: (sessionId, key, value, callback) {
+     *       // store key-value pair in current session
+     *       sessions[sessionId][key] = value;
+     *       callback();
+     *   },
+     *   get: (sessionId, key, callback) {
+     *       // retrieve value by key in current session
+     *       callback(null, sessions[sessionId][key]);
+     *   },
+     *   del: (sessionId, key, callback) {
+     *       delete sessions[sessionId][key];
+     *       callback();
+     *   }
+     * });
+     *
+     * @param {Object} c object with implementation for get, set, start and end methods
+     * @param {String} a attribute of args
+     */
+    sessionConfig(c: Record<string, (...args: unknown[]) => unknown>, a?: string): void;
+    /**
+     * Create a state on the ussd chain
+     *
+     * @param string name name of the state
+     * @param object options
+     * @param object options.next object mapping of route val to state names
+     * @param string options.defaultNext name of state to run when the given route from this state can't be resolved
+     * @param function options.run the method to run when this state is resolved
+     * @return TSUssdMenu the same instance of Ussd
+     */
+    state(name: string, options: {
+        next?: Record<string, unknown>;
+        defaultNext?: string;
+        run?: (state: TSUssdState) => void;
+    }): this;
+    /**
+     * Create the start state of the ussd chain
+     */
+    startState(options: {
+        next?: Record<string, unknown>;
+        defaultNext?: string;
+        run?: (state: TSUssdState) => void;
+    }): this;
+    /**
+     * Run the ussd menu
+     *
+     * @param function onResult a callback to handle on result
+     * @param TSUssdArgs options request args from the gateway api
+     */
+    run(onResult: (result: string) => void, map: Record<string, unknown>): void;
+}