ts-server-lib 0.0.48

package/LICENSE

@@ -0,0 +1 @@
+This is not free

package/README.md

@@ -0,0 +1,8 @@
+# ts-server-lib
+Server-side collection 
+
+
+## Clean solutions
+```bash
+rm -rf {db,ussd,ussd/providers,utils,ws}/*.{d.ts,js}
+```

package/db/TSJournal.d.ts

@@ -0,0 +1,108 @@
+export interface JournalEntryBase {
+    key: string;
+    operation: string;
+    /** When the key was first claimed. Expiry is measured from this; it never moves (settle preserves it). */
+    at: number;
+}
+/** Sent, outcome unknown. Carries the request verbatim — the only thing that can be replayed. */
+export interface InDoubtEntry<T = unknown> extends JournalEntryBase {
+    settled: false;
+    request: T;
+}
+/** Decided — and deliberately WITHOUT the request (retaining it makes memory a function of throughput). */
+export interface SettledEntry extends JournalEntryBase {
+    settled: true;
+    reply: unknown;
+}
+export type JournalEntry<T = unknown> = InDoubtEntry<T> | SettledEntry;
+/**
+ * What `claim` needs. `settled` is the journal's to assign; `at` too for a fresh claim — but a DURABLE adapter
+ * restoring state on restart may pass the ORIGINAL `at` so expiry keeps measuring from the first claim (not from
+ * the replay). Omit it in normal use.
+ */
+export type JournalClaim<T = unknown> = Pick<InDoubtEntry<T>, 'key' | 'operation' | 'request'> & {
+    at?: number;
+};
+/**
+ * Every method is async so a network-backed store fits without changing a caller. Three writing methods, not four:
+ * `claim` maps onto a single conditional write; `settle` records the outcome and drops the request; `discard`
+ * forgets a record for a request proven never to have taken effect. `lookup` reads; `inDoubt` lists the unsettled.
+ */
+export interface Journal<T = unknown> {
+    /** Record intent + report the prior record if the key was already claimed (settled -> do not act again). */
+    claim(entry: JournalClaim<T>): Promise<JournalEntry<T> | null>;
+    /** Read a record without creating one. */
+    lookup(key: string): Promise<JournalEntry<T> | null>;
+    /** Record the outcome once known (drops the retained request). */
+    settle(key: string, reply: unknown): Promise<void>;
+    /** Forget a record for a request that never reached the downstream (never-sent). */
+    discard(key: string): Promise<void>;
+    /** Requests begun but never settled — the ones whose fate is unknown. */
+    inDoubt(): Promise<InDoubtEntry<T>[]>;
+}
+/**
+ * Bounding shared by map-backed journals: entries held in insertion order, `at` never moving after claim, so age
+ * rises along that order and both helpers can stop at the first entry that must stay.
+ */
+export declare function dropExpired<T>(entries: Map<string, JournalEntry<T>>, unsettled: Set<string>, cutoff: number): number;
+/** Hold the entry ceiling, oldest first. Returns how many it had to remove. */
+export declare function holdCeiling<T>(entries: Map<string, JournalEntry<T>>, unsettled: Set<string>, maxEntries: number): number;
+export interface TSJournalOptions {
+    /** How long a decision stays replayable. */
+    ttlMs?: number;
+    /** Memory this journal may occupy — the real ceiling; entry count is derived from it. */
+    maxBytes?: number;
+    /** Entry ceiling, if you would rather set it directly than via `maxBytes`. */
+    maxEntries?: number;
+    /** Expected requests/second — avoids reserving a window larger than traffic can fill. */
+    ratePerSecond?: number;
+    /** Time source — injectable for determinism; defaults to the system clock. */
+    now?: () => number;
+}
+/**
+ * Single-process journal: survives retries within a process, not a restart. All operations are O(1) except
+ * `inDoubt` (O(number still open) via the `#unsettled` index — never a full scan) and `#prune` (amortised, stops at
+ * the first live entry). Swap in a durable adapter when losing in-doubt records on restart matters.
+ */
+export declare class TSJournal<T = unknown> implements Journal<T> {
+    #private;
+    constructor(options?: TSJournalOptions | number, legacyMaxEntries?: number);
+    /** What the journal is holding; `windowCappedByMemory` warns when the ceiling shortens the retention window. */
+    stats(): {
+        entries: number;
+        inDoubt: number;
+        maxEntries: number;
+        evicted: number;
+        windowMs: number;
+        windowCappedByMemory: boolean;
+    };
+    get size(): {
+        entries: number;
+        inDoubt: number;
+    };
+    /**
+     * Read-only snapshot of every held entry, in insertion (claim-time) order — for a DURABLE adapter that composes
+     * this index and needs to persist/compact it (write the live set to disk/a table). Yields the entries by
+     * reference: serialize them, do not mutate them.
+     */
+    entries(): IterableIterator<JournalEntry<T>>;
+    claim(entry: JournalClaim<T>): Promise<JournalEntry<T> | null>;
+    lookup(key: string): Promise<JournalEntry<T> | null>;
+    discard(key: string): Promise<void>;
+    settle(key: string, reply: unknown): Promise<void>;
+    inDoubt(): Promise<InDoubtEntry<T>[]>;
+}
+/** One conformance check result. */
+export interface JournalContractCheck {
+    name: string;
+    ok: boolean;
+    detail: string;
+}
+type JournalFactory<T> = () => Promise<Journal<T>> | Journal<T>;
+/**
+ * The contract every `Journal` must satisfy, as runnable checks — ships with the port so an adapter author (Redis, a
+ * table, a TSRQW stream) proves conformance without reading the prose. Zero dependencies. Pass a factory that makes a
+ * fresh journal and a sample request value.
+ */
+export declare function checkJournalContract<T>(create: JournalFactory<T>, sampleRequest: T): Promise<JournalContractCheck[]>;
+export {};

package/db/TSJournal.js

@@ -0,0 +1,229 @@
+"use strict";
+// Canonical idempotency + in-doubt Journal — the domain-neutral generalisation of the pattern proven in the MTS
+// driver. One record of every effect-causing request, read two ways:
+//
+//   * already settled  -> return the recorded decision, never act again
+//   * still in flight  -> "in doubt", replay/verify it to find out
+//
+// Replay is safe only when the downstream deduplicates on the request's own id (MTS does on `ticketId`, a payment
+// provider on `orderId`, ...). This module is a PORT with a built-in in-memory implementation and ZERO runtime
+// imports, so nothing here ties the library to a filesystem, a database, or a queue. `TSJournal` covers a
+// single process; anything durable — Redis, a table, a TSRQW stream (see lookupById/claimById) — is an adapter the
+// application injects. `checkJournalContract` lets an adapter author prove conformance without re-reading the prose.
+//
+// `claim` folds "have we seen this?" and "record intent" into ONE conditional write (Redis `SET NX`, a unique-key
+// insert, a conditional put) so it is atomic across processes sharing a store — a read-then-write would race.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TSJournal = void 0;
+exports.dropExpired = dropExpired;
+exports.holdCeiling = holdCeiling;
+exports.checkJournalContract = checkJournalContract;
+/**
+ * Bounding shared by map-backed journals: entries held in insertion order, `at` never moving after claim, so age
+ * rises along that order and both helpers can stop at the first entry that must stay.
+ */
+function dropExpired(entries, unsettled, cutoff) {
+    let dropped = 0;
+    for (const [key, entry] of entries) {
+        if (entry.at >= cutoff)
+            return dropped;
+        entries.delete(key);
+        unsettled.delete(key);
+        dropped++;
+    }
+    return dropped;
+}
+/** Hold the entry ceiling, oldest first. Returns how many it had to remove. */
+function holdCeiling(entries, unsettled, maxEntries) {
+    let evicted = 0;
+    while (entries.size > maxEntries) {
+        const oldest = entries.keys().next();
+        if (oldest.done === true)
+            break;
+        entries.delete(oldest.value);
+        unsettled.delete(oldest.value);
+        evicted++;
+    }
+    return evicted;
+}
+/** Bytes assumed per entry when sizing the memory budget (measured ~256B with typical keys). */
+const ESTIMATED_BYTES_PER_ENTRY = 256;
+/**
+ * Single-process journal: survives retries within a process, not a restart. All operations are O(1) except
+ * `inDoubt` (O(number still open) via the `#unsettled` index — never a full scan) and `#prune` (amortised, stops at
+ * the first live entry). Swap in a durable adapter when losing in-doubt records on restart matters.
+ */
+class TSJournal {
+    #entries = new Map();
+    #unsettled = new Set();
+    #ttlMs;
+    #maxEntries;
+    #evicted = 0;
+    #now;
+    constructor(options = {}, legacyMaxEntries) {
+        const opts = typeof options === 'number'
+            ? { ttlMs: options, ...(legacyMaxEntries !== undefined ? { maxEntries: legacyMaxEntries } : {}) }
+            : options;
+        this.#ttlMs = opts.ttlMs ?? 6 * 60 * 60_000;
+        this.#now = opts.now ?? (() => Date.now());
+        const byBudget = Math.floor((opts.maxBytes ?? 64 * 1024 * 1024) / ESTIMATED_BYTES_PER_ENTRY);
+        const byTraffic = opts.ratePerSecond !== undefined && opts.ratePerSecond > 0
+            ? Math.ceil(opts.ratePerSecond * (this.#ttlMs / 1000))
+            : Number.POSITIVE_INFINITY;
+        this.#maxEntries = Math.max(1, Math.min(opts.maxEntries ?? Number.POSITIVE_INFINITY, byBudget, byTraffic));
+    }
+    /** What the journal is holding; `windowCappedByMemory` warns when the ceiling shortens the retention window. */
+    stats() {
+        const oldest = this.#entries.values().next();
+        const windowMs = oldest.done === true ? 0 : this.#now() - oldest.value.at;
+        return {
+            entries: this.#entries.size,
+            inDoubt: this.#unsettled.size,
+            maxEntries: this.#maxEntries,
+            evicted: this.#evicted,
+            windowMs,
+            windowCappedByMemory: this.#entries.size >= this.#maxEntries
+        };
+    }
+    get size() {
+        return { entries: this.#entries.size, inDoubt: this.#unsettled.size };
+    }
+    /**
+     * Read-only snapshot of every held entry, in insertion (claim-time) order — for a DURABLE adapter that composes
+     * this index and needs to persist/compact it (write the live set to disk/a table). Yields the entries by
+     * reference: serialize them, do not mutate them.
+     */
+    entries() {
+        return this.#entries.values();
+    }
+    async claim(entry) {
+        this.#prune();
+        const previous = this.#entries.get(entry.key);
+        if (previous !== undefined)
+            return previous;
+        // `request` kept by reference (do not mutate a request after claiming it); dropped at `settle`. `at` defaults to
+        // now, but a durable adapter may restore the original claim time on replay.
+        this.#entries.set(entry.key, { key: entry.key, operation: entry.operation, request: entry.request, settled: false, at: entry.at ?? this.#now() });
+        this.#unsettled.add(entry.key);
+        this.#enforceCeiling();
+        return null;
+    }
+    async lookup(key) {
+        return this.#entries.get(key) ?? null;
+    }
+    async discard(key) {
+        this.#entries.delete(key);
+        this.#unsettled.delete(key);
+    }
+    async settle(key, reply) {
+        const entry = this.#entries.get(key);
+        if (entry === undefined)
+            return;
+        // Rebuilt field-by-field so `request` is dropped; `at` carried over (expiry measures from first claim).
+        this.#entries.set(key, { key: entry.key, operation: entry.operation, at: entry.at, settled: true, reply });
+        this.#unsettled.delete(key);
+    }
+    async inDoubt() {
+        const open = [];
+        for (const key of this.#unsettled) {
+            const entry = this.#entries.get(key);
+            if (entry?.settled === false)
+                open.push(entry);
+        }
+        return open;
+    }
+    #prune() {
+        dropExpired(this.#entries, this.#unsettled, this.#now() - this.#ttlMs);
+    }
+    #enforceCeiling() {
+        this.#evicted += holdCeiling(this.#entries, this.#unsettled, this.#maxEntries);
+    }
+}
+exports.TSJournal = TSJournal;
+/** claim: first wins (null), a repeat returns the prior unsettled entry, and settle does not move the claim time. */
+async function checkClaimLifecycle(create, entry, rec) {
+    const j = await create();
+    const first = await j.claim(entry);
+    rec('first claim returns null', first === null, `got ${JSON.stringify(first)}`);
+    const second = await j.claim(entry);
+    rec('second claim returns the prior entry', second?.key === entry.key, `got ${JSON.stringify(second?.key)}`);
+    rec('prior entry is unsettled', second?.settled === false, `settled=${String(second?.settled)}`);
+    // Age must not move when an entry settles: expiry measures from the first claim, and pruning relies on age rising
+    // in insertion order — an adapter that refreshes `at` on settle would extend retention silently.
+    const claimedAt = second?.at;
+    await j.settle(entry.key, { code: 0 });
+    const afterSettle = await j.claim(entry);
+    rec('settle preserves the original claim time', afterSettle?.at === claimedAt, `claimed ${String(claimedAt)}, after ${String(afterSettle?.at)}`);
+}
+/** lookup: a read never writes, finds a claimed key, and reflects unsettled → settled. */
+async function checkLookup(create, entry, rec) {
+    const j = await create();
+    const missing = await j.lookup('op:never');
+    rec('lookup of an unknown key returns null', missing === null, `got ${JSON.stringify(missing)}`);
+    const openAfterLookup = await j.inDoubt();
+    rec('lookup creates nothing', openAfterLookup.every((e) => e.key !== 'op:never'), `${openAfterLookup.length} in doubt after a lookup`);
+    await j.claim(entry);
+    const found = await j.lookup(entry.key);
+    rec('lookup finds a claimed key', found?.key === entry.key, `got ${JSON.stringify(found?.key)}`);
+    rec('lookup reports it unsettled', found?.settled === false, `settled=${String(found?.settled)}`);
+    await j.settle(entry.key, { code: 0 });
+    const decided = await j.lookup(entry.key);
+    rec('lookup reports it settled', decided?.settled === true, `settled=${String(decided?.settled)}`);
+}
+/** discard: a never-sent request leaves nothing to recover and is re-claimable. */
+async function checkDiscard(create, entry, rec) {
+    const j = await create();
+    await j.claim(entry);
+    await j.discard(entry.key);
+    const gone = await j.lookup(entry.key);
+    rec('discard removes the record', gone === null, `got ${JSON.stringify(gone?.key)}`);
+    const open = await j.inDoubt();
+    rec('a discarded key is not in doubt', open.every((e) => e.key !== entry.key), `${open.length} in doubt`);
+    const reclaimed = await j.claim(entry);
+    rec('a discarded key can be claimed again', reclaimed === null, `got ${JSON.stringify(reclaimed)}`);
+}
+/** settled entry: reports settled, carries the reply, and drops the request payload. */
+async function checkSettledEntry(create, entry, rec) {
+    const j = await create();
+    await j.claim(entry);
+    await j.settle(entry.key, { code: 0 });
+    const seen = await j.claim(entry);
+    rec('claim after settle reports settled', seen?.settled === true, `settled=${String(seen?.settled)}`);
+    const decided = seen?.settled === true ? seen : undefined;
+    rec('settled entry carries the reply', decided?.reply?.code === 0, `reply=${JSON.stringify(decided?.reply)}`);
+    rec('settled entry does not retain the request', decided !== undefined && !('request' in decided), `keys=${decided === undefined ? 'none' : Object.keys(decided).join(',')}`);
+}
+/** inDoubt: an unsettled claim is in doubt; settling removes it. */
+async function checkInDoubt(create, entry, rec) {
+    const j = await create();
+    await j.claim(entry);
+    const before = await j.inDoubt();
+    rec('unsettled appears in inDoubt', before.some((e) => e.key === entry.key), `${before.length} in doubt`);
+    await j.settle(entry.key, { code: 0 });
+    const after = await j.inDoubt();
+    rec('settled leaves inDoubt', !after.some((e) => e.key === entry.key), `${after.length} in doubt`);
+}
+/** The property that makes `claim` safe to share between processes: even when several race, exactly one wins. */
+async function checkConcurrency(create, entry, rec) {
+    const j = await create();
+    const claims = await Promise.all(Array.from({ length: 8 }, () => j.claim(entry)));
+    const winners = claims.filter((c) => c === null).length;
+    rec('concurrent claims elect one winner', winners === 1, `${winners} of 8 saw null`);
+}
+/**
+ * The contract every `Journal` must satisfy, as runnable checks — ships with the port so an adapter author (Redis, a
+ * table, a TSRQW stream) proves conformance without reading the prose. Zero dependencies. Pass a factory that makes a
+ * fresh journal and a sample request value.
+ */
+async function checkJournalContract(create, sampleRequest) {
+    const results = [];
+    const rec = (name, ok, detail = '') => { results.push({ name, ok, detail }); };
+    const entry = { key: 'op:1', operation: 'test-op', request: sampleRequest };
+    await checkClaimLifecycle(create, entry, rec);
+    await checkLookup(create, entry, rec);
+    await checkDiscard(create, entry, rec);
+    await checkSettledEntry(create, entry, rec);
+    await checkInDoubt(create, entry, rec);
+    await checkConcurrency(create, entry, rec);
+    return results;
+}

package/db/TSMongo.d.ts

@@ -0,0 +1,103 @@
+/**
+ * TSMongo – MongoDB connection (pooling, health, index registration).
+ * Static API like TSRedis. Use TSMongo.connect(), TSMongo.getDatabase(), etc.
+ */
+import { MongoClient, Db } from 'mongodb';
+export { MongoClient, Db, ObjectId, ReadPreference, type Collection, type Filter, type Document, type FindOptions, type ClientSession, type TransactionOptions, type CommandStartedEvent, type CommandSucceededEvent, type CommandFailedEvent, type ReadPreferenceLike, type UpdateFilter, type Sort, type IndexDescription } from 'mongodb';
+export type MongoEventLevel = 'error' | 'warn' | 'info';
+/**
+ * Structured event emitted by TSMongo for significant pool lifecycle moments.
+ *
+ * Wire a handler once at service startup via `TSMongo.setEventHandler()` to route
+ * these events into your structured logger with correlation context.
+ *
+ * When no handler is registered, events fall back to `console.error` / `console.warn`
+ * using the `TSMongo:ERROR` / `TSMongo:WARN` prefix convention.
+ */
+export interface MongoEvent {
+    level: MongoEventLevel;
+    /** Low-cardinality dot-namespaced event identifier. */
+    event: string;
+    message: string;
+    timestamp: string;
+    data: Record<string, unknown>;
+}
+export type MongoEventHandler = (event: MongoEvent) => void;
+/**
+ * Register a structured event handler for TSMongo lifecycle events.
+ *
+ * Call once at service startup before `TSMongo.connect()`. Pass `null` to
+ * remove a previously registered handler and revert to console fallback.
+ *
+ * @example
+ * TSMongo.setEventHandler((evt) => {
+ *   logger[evt.level]('TSMongo event', { operation: 'core.database', event: evt.event, ...evt.data });
+ * });
+ */
+declare function setEventHandlerImpl(handler: MongoEventHandler | null): void;
+export interface ConnectionPoolStats {
+    totalConnections: number;
+    checkedOut: number;
+    availableConnections: number;
+    waitQueueSize: number;
+    maxPoolSize: number;
+    minPoolSize: number;
+    totalCheckouts: number;
+    totalCheckins: number;
+    connectionCreated: number;
+    connectionClosed: number;
+    waitQueueTimeouts: number;
+    lastWaitQueueTimeout: Date | null;
+}
+export interface MongoConfig {
+    uri: string;
+    dbName?: string;
+    maxPoolSize?: number;
+    minPoolSize?: number;
+    maxIdleTimeMS?: number;
+    waitQueueTimeoutMS?: number;
+    maxWaitingRequests?: number;
+    connectTimeoutMS?: number;
+    socketTimeoutMS?: number;
+    serverSelectionTimeoutMS?: number;
+    readPreference?: 'primary' | 'primaryPreferred' | 'secondary' | 'secondaryPreferred' | 'nearest';
+    writeConcern?: 'majority' | number;
+    retryWrites?: boolean;
+    retryReads?: boolean;
+    compressors?: ('snappy' | 'zlib' | 'zstd')[];
+    monitorCommands?: boolean;
+}
+export declare const DEFAULT_MONGO_CONFIG: Omit<Required<MongoConfig>, 'uri' | 'dbName' | 'compressors' | 'monitorCommands'>;
+declare function registerIndexesImpl(collection: string, indexes: Array<{
+    key: Record<string, 1 | -1>;
+    unique?: boolean;
+}>): void;
+export declare class TSMongo {
+    static connect: typeof connectImpl;
+    static getDatabase: typeof getDatabaseImpl;
+    static getClient: typeof getClientImpl;
+    static close: typeof closeImpl;
+    static checkHealth: typeof checkHealthImpl;
+    static registerIndexes: typeof registerIndexesImpl;
+    static getConnectionPoolStats: typeof getConnectionPoolStatsImpl;
+    static getPoolHealthStatus: typeof getPoolHealthStatusImpl;
+    static getDatabaseStats: typeof getDatabaseStatsImpl;
+    static setEventHandler: typeof setEventHandlerImpl;
+}
+declare function connectImpl(uri: string, config?: Partial<MongoConfig>): Promise<Db>;
+declare function getDatabaseImpl(): Db;
+declare function getClientImpl(): MongoClient;
+declare function closeImpl(): Promise<void>;
+declare function getConnectionPoolStatsImpl(): ConnectionPoolStats;
+declare function getPoolHealthStatusImpl(): {
+    status: 'healthy' | 'warning' | 'critical';
+    utilizationPercent: number;
+    message: string;
+};
+declare function checkHealthImpl(): Promise<{
+    healthy: boolean;
+    latencyMs: number;
+    connections: number;
+    checkedOut: number;
+}>;
+declare function getDatabaseStatsImpl(): Promise<Record<string, unknown>>;