@futdevpro/nts-dynamo 1.15.151 → 1.15.154

package/src/_modules/rate-limit/_enums/rate-limit-store-kind.type-enum.ts

@@ -1,5 +1,5 @@
-/** Persistence scope advertised by a rate-limit store implementation. */
-export enum DyNTS_RateLimitStoreKind_Type {
-  inMemory = 'in-memory',
-  shared = 'shared',
-}
+/** Persistence scope advertised by a rate-limit store implementation. */
+export enum DyNTS_RateLimitStoreKind_Type {
+  inMemory = 'in-memory',
+  shared = 'shared',
+}

package/src/_modules/rate-limit/_models/rate-limit-config.interface.ts

@@ -1,82 +1,82 @@
-import { Request } from 'express';
-
-import { DyNTS_RateLimit_Policy } from './rate-limit-policy.interface';
-import { DyNTS_RateLimit_Store_Interface } from './rate-limit-store.interface';
-
-/**
- * Config a `DyNTS_RateLimit_Middleware.configure(...)`-hoz.
- *
- * Minden mezo opcionalis — a default-ok megfelelnek a tipikus API
- * rate-limit-elvarasoknak (100 req/min, sliding window, IP-alapu kulcs,
- * path-alapu endpoint-csoportositas, X-RateLimit-* response header-ek).
- */
-export interface DyNTS_RateLimit_Config {
-  /**
-   * Default request-limit `windowMs` alatt, ha az adott kulcsra nincs
-   * `setPolicyForKey()`-szel beallitott egyedi policy. Default: `100`.
-   */
-  defaultLimit?: number;
-
-  /**
-   * Default sliding-window hossza milliszekundumban. Default: `60000` (1 perc).
-   */
-  defaultWindowMs?: number;
-
-  /**
-   * Rate-limit subject-extractor. Visszater a karakterlanccal, ami azonositja
-   * a rate-limit alanyat (pl. IP-cim, API-kulcs ID, account ID).
-   *
-   * Default: az Express altal mar megbizhatonak minositett `req.ip`, vagy ha
-   * hianyzik akkor `'unknown'`. A middleware szandekosan nem olvassa kozvetlenul
-   * az ugyfel altal hamisithato `x-forwarded-for` headert. Production uzemben a
-   * shared-store gate explicit, opaque extractort kovetel.
-   */
-  keyExtractor?: (req: Request) => string;
-
-  /**
-   * Endpoint-csoportosito. Visszater a karakterlanccal, ami azonositja az
-   * adott endpoint-csoportot. A storage-key egyertelmuen hossz-prefixelt
-   * subject + endpoint kompozicio lesz.
-   *
-   * Default: `req.path` — minden uri-path kulon vodorbe kerul. Csoportositas
-   * mas szempontok szerint (pl. "datasets" csoport = `/api/datasets/*`)
-   * a hostnal felulirhato.
-   */
-  endpointGrouper?: (req: Request) => string;
-
-  /** Optional permit cost per request. Default: one. */
-  costExtractor?: (req: Request) => number;
-
-  /** Atomic store. The default in-memory implementation is for tests and single-instance development only. */
-  store?: DyNTS_RateLimit_Store_Interface;
-
-  /** Fail configuration unless a shared store plus explicit opaque key/group extractors are supplied. */
-  requireSharedStore?: boolean;
-
-  /** Deterministic clock seam. Production callers normally omit it. */
-  clock?: () => number;
-
-  /**
-   * Beallitja-e a `X-RateLimit-Limit`, `X-RateLimit-Remaining`,
-   * `X-RateLimit-Reset` (es a 429-re `Retry-After`) response header-eket.
-   * Default: `true`.
-   *
-   * Test/dev kornyezetben opcionalisan kikapcsolhato.
-   */
-  responseHeaders?: boolean;
-
-  /**
-   * Per-policy override-ok az induloskor. A `setPolicyForKey()` runtime-ban is
-   * felulhatja ezeket.
-   */
-  initialKeyPolicies?: Record<string, DyNTS_RateLimit_Policy>;
-
-  /**
-   * Per-endpoint(-csoport) policy override-ok az induloskor. A `setPolicyForEndpoint()`
-   * runtime-ban is felulhatja ezeket. A kulcs annak felel meg, amit az `endpointGrouper`
-   * visszaad (default: `req.path`). Akkor hasznos, ha kulonbozo endpointoknak kulonbozo
-   * limit kell (pl. egy webhook nagy burst-toleranciat igenyel a legit forgalomhoz, mig
-   * egy admin-endpoint szuk limitet). Precedencia: per-kulcs policy > per-endpoint policy > default.
-   */
-  initialEndpointPolicies?: Record<string, DyNTS_RateLimit_Policy>;
-}
+import { Request } from 'express';
+
+import { DyNTS_RateLimit_Policy } from './rate-limit-policy.interface';
+import { DyNTS_RateLimit_Store_Interface } from './rate-limit-store.interface';
+
+/**
+ * Config a `DyNTS_RateLimit_Middleware.configure(...)`-hoz.
+ *
+ * Minden mezo opcionalis — a default-ok megfelelnek a tipikus API
+ * rate-limit-elvarasoknak (100 req/min, sliding window, IP-alapu kulcs,
+ * path-alapu endpoint-csoportositas, X-RateLimit-* response header-ek).
+ */
+export interface DyNTS_RateLimit_Config {
+  /**
+   * Default request-limit `windowMs` alatt, ha az adott kulcsra nincs
+   * `setPolicyForKey()`-szel beallitott egyedi policy. Default: `100`.
+   */
+  defaultLimit?: number;
+
+  /**
+   * Default sliding-window hossza milliszekundumban. Default: `60000` (1 perc).
+   */
+  defaultWindowMs?: number;
+
+  /**
+   * Rate-limit subject-extractor. Visszater a karakterlanccal, ami azonositja
+   * a rate-limit alanyat (pl. IP-cim, API-kulcs ID, account ID).
+   *
+   * Default: az Express altal mar megbizhatonak minositett `req.ip`, vagy ha
+   * hianyzik akkor `'unknown'`. A middleware szandekosan nem olvassa kozvetlenul
+   * az ugyfel altal hamisithato `x-forwarded-for` headert. Production uzemben a
+   * shared-store gate explicit, opaque extractort kovetel.
+   */
+  keyExtractor?: (req: Request) => string;
+
+  /**
+   * Endpoint-csoportosito. Visszater a karakterlanccal, ami azonositja az
+   * adott endpoint-csoportot. A storage-key egyertelmuen hossz-prefixelt
+   * subject + endpoint kompozicio lesz.
+   *
+   * Default: `req.path` — minden uri-path kulon vodorbe kerul. Csoportositas
+   * mas szempontok szerint (pl. "datasets" csoport = `/api/datasets/*`)
+   * a hostnal felulirhato.
+   */
+  endpointGrouper?: (req: Request) => string;
+
+  /** Optional permit cost per request. Default: one. */
+  costExtractor?: (req: Request) => number;
+
+  /** Atomic store. The default in-memory implementation is for tests and single-instance development only. */
+  store?: DyNTS_RateLimit_Store_Interface;
+
+  /** Fail configuration unless a shared store plus explicit opaque key/group extractors are supplied. */
+  requireSharedStore?: boolean;
+
+  /** Deterministic clock seam. Production callers normally omit it. */
+  clock?: () => number;
+
+  /**
+   * Beallitja-e a `X-RateLimit-Limit`, `X-RateLimit-Remaining`,
+   * `X-RateLimit-Reset` (es a 429-re `Retry-After`) response header-eket.
+   * Default: `true`.
+   *
+   * Test/dev kornyezetben opcionalisan kikapcsolhato.
+   */
+  responseHeaders?: boolean;
+
+  /**
+   * Per-policy override-ok az induloskor. A `setPolicyForKey()` runtime-ban is
+   * felulhatja ezeket.
+   */
+  initialKeyPolicies?: Record<string, DyNTS_RateLimit_Policy>;
+
+  /**
+   * Per-endpoint(-csoport) policy override-ok az induloskor. A `setPolicyForEndpoint()`
+   * runtime-ban is felulhatja ezeket. A kulcs annak felel meg, amit az `endpointGrouper`
+   * visszaad (default: `req.path`). Akkor hasznos, ha kulonbozo endpointoknak kulonbozo
+   * limit kell (pl. egy webhook nagy burst-toleranciat igenyel a legit forgalomhoz, mig
+   * egy admin-endpoint szuk limitet). Precedencia: per-kulcs policy > per-endpoint policy > default.
+   */
+  initialEndpointPolicies?: Record<string, DyNTS_RateLimit_Policy>;
+}

package/src/_modules/rate-limit/_models/rate-limit-consume-request.interface.ts

@@ -1,9 +1,9 @@
-import { DyNTS_RateLimit_Policy } from './rate-limit-policy.interface';
-
-/** Atomic permit request passed to a rate-limit store. */
-export interface DyNTS_RateLimit_ConsumeRequest_Interface {
-  bucketKey: string;
-  policy: DyNTS_RateLimit_Policy;
-  cost: number;
-  now: number;
-}
+import { DyNTS_RateLimit_Policy } from './rate-limit-policy.interface';
+
+/** Atomic permit request passed to a rate-limit store. */
+export interface DyNTS_RateLimit_ConsumeRequest_Interface {
+  bucketKey: string;
+  policy: DyNTS_RateLimit_Policy;
+  cost: number;
+  now: number;
+}

package/src/_modules/rate-limit/_models/rate-limit-consume-result.interface.ts

@@ -1,6 +1,6 @@
-/** Content-free result of one atomically committed permit request. */
-export interface DyNTS_RateLimit_ConsumeResult_Interface {
-  allowed: boolean;
-  remaining: number;
-  resetAt: number;
-}
+/** Content-free result of one atomically committed permit request. */
+export interface DyNTS_RateLimit_ConsumeResult_Interface {
+  allowed: boolean;
+  remaining: number;
+  resetAt: number;
+}

package/src/_modules/rate-limit/_models/rate-limit-policy.interface.ts

@@ -1,16 +1,16 @@
-/**
- * Per-kulcs rate-limit policy.
- *
- * A `DyNTS_RateLimit_Middleware.setPolicyForKey(key, policy)` allitja be,
- * vagy a `DyNTS_RateLimit_Config.initialKeyPolicies` map-en at.
- *
- * Tipikus use-case: subscription-tier-up — egy belepett user API-kulcsa
- * magasabb `limit`-et kap, mint a default (anonim/IP-alapu) limit.
- */
-export interface DyNTS_RateLimit_Policy {
-  /** Hany request engedelyezett a `windowMs` alatt. */
-  limit: number;
-
-  /** A sliding-window hossza milliszekundumban. */
-  windowMs: number;
-}
+/**
+ * Per-kulcs rate-limit policy.
+ *
+ * A `DyNTS_RateLimit_Middleware.setPolicyForKey(key, policy)` allitja be,
+ * vagy a `DyNTS_RateLimit_Config.initialKeyPolicies` map-en at.
+ *
+ * Tipikus use-case: subscription-tier-up — egy belepett user API-kulcsa
+ * magasabb `limit`-et kap, mint a default (anonim/IP-alapu) limit.
+ */
+export interface DyNTS_RateLimit_Policy {
+  /** Hany request engedelyezett a `windowMs` alatt. */
+  limit: number;
+
+  /** A sliding-window hossza milliszekundumban. */
+  windowMs: number;
+}

package/src/_modules/rate-limit/_models/rate-limit-store.interface.ts

@@ -1,9 +1,9 @@
-import { DyNTS_RateLimitStoreKind_Type } from '../_enums/rate-limit-store-kind.type-enum';
-import { DyNTS_RateLimit_ConsumeRequest_Interface } from './rate-limit-consume-request.interface';
-import { DyNTS_RateLimit_ConsumeResult_Interface } from './rate-limit-consume-result.interface';
-
-/** Atomic persistence seam. Production hosts can require `shared` scope at configuration time. */
-export interface DyNTS_RateLimit_Store_Interface {
-  readonly storeKind: DyNTS_RateLimitStoreKind_Type;
-  consume(request: DyNTS_RateLimit_ConsumeRequest_Interface): Promise<DyNTS_RateLimit_ConsumeResult_Interface>;
-}
+import { DyNTS_RateLimitStoreKind_Type } from '../_enums/rate-limit-store-kind.type-enum';
+import { DyNTS_RateLimit_ConsumeRequest_Interface } from './rate-limit-consume-request.interface';
+import { DyNTS_RateLimit_ConsumeResult_Interface } from './rate-limit-consume-result.interface';
+
+/** Atomic persistence seam. Production hosts can require `shared` scope at configuration time. */
+export interface DyNTS_RateLimit_Store_Interface {
+  readonly storeKind: DyNTS_RateLimitStoreKind_Type;
+  consume(request: DyNTS_RateLimit_ConsumeRequest_Interface): Promise<DyNTS_RateLimit_ConsumeResult_Interface>;
+}

package/src/_modules/rate-limit/index.ts

@@ -1,8 +1,8 @@
-export { DyNTS_RateLimit_Middleware } from './rate-limit.middleware';
-export { DyNTS_RateLimit_InMemoryStore } from './rate-limit-in-memory.store';
-export { DyNTS_RateLimit_Config } from './_models/rate-limit-config.interface';
-export { DyNTS_RateLimit_ConsumeRequest_Interface } from './_models/rate-limit-consume-request.interface';
-export { DyNTS_RateLimit_ConsumeResult_Interface } from './_models/rate-limit-consume-result.interface';
-export { DyNTS_RateLimit_Policy } from './_models/rate-limit-policy.interface';
-export { DyNTS_RateLimit_Store_Interface } from './_models/rate-limit-store.interface';
-export { DyNTS_RateLimitStoreKind_Type } from './_enums/rate-limit-store-kind.type-enum';
+export { DyNTS_RateLimit_Middleware } from './rate-limit.middleware';
+export { DyNTS_RateLimit_InMemoryStore } from './rate-limit-in-memory.store';
+export { DyNTS_RateLimit_Config } from './_models/rate-limit-config.interface';
+export { DyNTS_RateLimit_ConsumeRequest_Interface } from './_models/rate-limit-consume-request.interface';
+export { DyNTS_RateLimit_ConsumeResult_Interface } from './_models/rate-limit-consume-result.interface';
+export { DyNTS_RateLimit_Policy } from './_models/rate-limit-policy.interface';
+export { DyNTS_RateLimit_Store_Interface } from './_models/rate-limit-store.interface';
+export { DyNTS_RateLimitStoreKind_Type } from './_enums/rate-limit-store-kind.type-enum';

package/src/_modules/rate-limit/rate-limit-in-memory.store.ts

@@ -1,91 +1,91 @@
-import { DyNTS_RateLimitStoreKind_Type } from './_enums/rate-limit-store-kind.type-enum';
-import { DyNTS_RateLimit_ConsumeRequest_Interface } from './_models/rate-limit-consume-request.interface';
-import { DyNTS_RateLimit_ConsumeResult_Interface } from './_models/rate-limit-consume-result.interface';
-import { DyNTS_RateLimit_Store_Interface } from './_models/rate-limit-store.interface';
-
-interface DyNTS_RateLimit_InMemoryRecord_Interface {
-  timestamps: number[];
-  windowMs: number;
-}
-
-/** Deterministic single-process store for tests and explicitly single-instance development. */
-export class DyNTS_RateLimit_InMemoryStore implements DyNTS_RateLimit_Store_Interface {
-  public readonly storeKind: DyNTS_RateLimitStoreKind_Type = DyNTS_RateLimitStoreKind_Type.inMemory;
-  private readonly records: Map<string, DyNTS_RateLimit_InMemoryRecord_Interface> = new Map();
-
-  /** Consumes permit units with exact sliding-window semantics and no background cleanup task. */
-  public async consume(
-    request: DyNTS_RateLimit_ConsumeRequest_Interface
-  ): Promise<DyNTS_RateLimit_ConsumeResult_Interface> {
-    this.assertRequest(request);
-
-    const windowStart: number = request.now - request.policy.windowMs;
-    const existing: DyNTS_RateLimit_InMemoryRecord_Interface | undefined = this.records.get(request.bucketKey);
-    const recent: number[] = (existing?.timestamps ?? []).filter(
-      (timestamp: number): boolean => timestamp > windowStart
-    );
-    const allowed: boolean = recent.length + request.cost <= request.policy.limit;
-
-    if (allowed) {
-      for (let index: number = 0; index < request.cost; index += 1) {
-        recent.push(request.now);
-      }
-    }
-
-    this.records.set(request.bucketKey, {
-      timestamps: recent,
-      windowMs: request.policy.windowMs,
-    });
-
-    return {
-      allowed: allowed,
-      remaining: Math.max(0, request.policy.limit - recent.length),
-      resetAt: (recent[0] ?? request.now) + request.policy.windowMs,
-    };
-  }
-
-  /** Opportunistically removes expired local records when explicitly invoked by the host. */
-  public cleanup(now: number): void {
-    for (const entry of this.records.entries()) {
-      const key: string = entry[0];
-      const record: DyNTS_RateLimit_InMemoryRecord_Interface = entry[1];
-      const recent: number[] = record.timestamps.filter(
-        (timestamp: number): boolean => timestamp > now - record.windowMs
-      );
-
-      if (!recent.length) {
-        this.records.delete(key);
-      } else {
-        this.records.set(key, { ...record, timestamps: recent });
-      }
-    }
-  }
-
-  /** Clears all local state for deterministic tests. */
-  public reset(): void {
-    this.records.clear();
-  }
-
-  /** Returns only the aggregate local bucket count for diagnostics. */
-  public getTrackedBucketCount(): number {
-    return this.records.size;
-  }
-
-  private assertRequest(request: DyNTS_RateLimit_ConsumeRequest_Interface): void {
-    const isValid: boolean = Boolean(request.bucketKey.trim())
-      && request.bucketKey.length <= 512
-      && Number.isSafeInteger(request.now)
-      && request.now >= 0
-      && Number.isSafeInteger(request.cost)
-      && request.cost > 0
-      && Number.isSafeInteger(request.policy.limit)
-      && request.policy.limit > 0
-      && Number.isSafeInteger(request.policy.windowMs)
-      && request.policy.windowMs > 0
-      && request.cost <= request.policy.limit;
-
-    if (!isValid) {
-      throw new Error('DYNTS_RATE_LIMIT_STORE_REQUEST_INVALID');
-    }
-  }
-}
+import { DyNTS_RateLimitStoreKind_Type } from './_enums/rate-limit-store-kind.type-enum';
+import { DyNTS_RateLimit_ConsumeRequest_Interface } from './_models/rate-limit-consume-request.interface';
+import { DyNTS_RateLimit_ConsumeResult_Interface } from './_models/rate-limit-consume-result.interface';
+import { DyNTS_RateLimit_Store_Interface } from './_models/rate-limit-store.interface';
+
+interface DyNTS_RateLimit_InMemoryRecord_Interface {
+  timestamps: number[];
+  windowMs: number;
+}
+
+/** Deterministic single-process store for tests and explicitly single-instance development. */
+export class DyNTS_RateLimit_InMemoryStore implements DyNTS_RateLimit_Store_Interface {
+  public readonly storeKind: DyNTS_RateLimitStoreKind_Type = DyNTS_RateLimitStoreKind_Type.inMemory;
+  private readonly records: Map<string, DyNTS_RateLimit_InMemoryRecord_Interface> = new Map();
+
+  /** Consumes permit units with exact sliding-window semantics and no background cleanup task. */
+  public async consume(
+    request: DyNTS_RateLimit_ConsumeRequest_Interface
+  ): Promise<DyNTS_RateLimit_ConsumeResult_Interface> {
+    this.assertRequest(request);
+
+    const windowStart: number = request.now - request.policy.windowMs;
+    const existing: DyNTS_RateLimit_InMemoryRecord_Interface | undefined = this.records.get(request.bucketKey);
+    const recent: number[] = (existing?.timestamps ?? []).filter(
+      (timestamp: number): boolean => timestamp > windowStart
+    );
+    const allowed: boolean = recent.length + request.cost <= request.policy.limit;
+
+    if (allowed) {
+      for (let index: number = 0; index < request.cost; index += 1) {
+        recent.push(request.now);
+      }
+    }
+
+    this.records.set(request.bucketKey, {
+      timestamps: recent,
+      windowMs: request.policy.windowMs,
+    });
+
+    return {
+      allowed: allowed,
+      remaining: Math.max(0, request.policy.limit - recent.length),
+      resetAt: (recent[0] ?? request.now) + request.policy.windowMs,
+    };
+  }
+
+  /** Opportunistically removes expired local records when explicitly invoked by the host. */
+  public cleanup(now: number): void {
+    for (const entry of this.records.entries()) {
+      const key: string = entry[0];
+      const record: DyNTS_RateLimit_InMemoryRecord_Interface = entry[1];
+      const recent: number[] = record.timestamps.filter(
+        (timestamp: number): boolean => timestamp > now - record.windowMs
+      );
+
+      if (!recent.length) {
+        this.records.delete(key);
+      } else {
+        this.records.set(key, { ...record, timestamps: recent });
+      }
+    }
+  }
+
+  /** Clears all local state for deterministic tests. */
+  public reset(): void {
+    this.records.clear();
+  }
+
+  /** Returns only the aggregate local bucket count for diagnostics. */
+  public getTrackedBucketCount(): number {
+    return this.records.size;
+  }
+
+  private assertRequest(request: DyNTS_RateLimit_ConsumeRequest_Interface): void {
+    const isValid: boolean = Boolean(request.bucketKey.trim())
+      && request.bucketKey.length <= 512
+      && Number.isSafeInteger(request.now)
+      && request.now >= 0
+      && Number.isSafeInteger(request.cost)
+      && request.cost > 0
+      && Number.isSafeInteger(request.policy.limit)
+      && request.policy.limit > 0
+      && Number.isSafeInteger(request.policy.windowMs)
+      && request.policy.windowMs > 0
+      && request.cost <= request.policy.limit;
+
+    if (!isValid) {
+      throw new Error('DYNTS_RATE_LIMIT_STORE_REQUEST_INVALID');
+    }
+  }
+}