@mrxsys/mrx-core 2.6.0 → 2.8.0

package/dist/modules/elysia/{ratelimit/ratelimit.d.ts → rateLimit/rateLimit.d.ts}

@@ -16,30 +16,47 @@ import type { RateLimitOptions } from './types/rateLimitOptions';
  * @returns An {@link Elysia} plugin that adds rate limiting functionality
  *
  * @example
+ * Basic usage with default in-memory store
  * ```ts
- * // Create Redis instance
- * const redis = new Redis({
+ * import { rateLimit } from '@nowarajs/elysia-ratelimit';
+ * import { Elysia } from 'elysia';
+ *
+ * const app = new Elysia()
+ *   .use(rateLimit({
+ *     store: ':memory:',    // Use in-memory store
+ *     limit: 100,           // 100 requests
+ *     window: 60,           // per minute
+ *   }))
+ *   .get('/api/endpoint', () => ({ message: 'Hello World' }));
+ *
+ * app.listen(3000);
+ * ```
+ *
+ * @example
+ * Using Redis store for distributed rate limiting
+ * ```ts
+ * import { IoRedisStore } from '@nowarajs/kv-store';
+ * import { rateLimit } from '@nowarajs/elysia-ratelimit';
+ * import { Elysia } from 'elysia';
+ *
+ * const redisStore = new IoRedisStore({
  *   host: 'localhost',
  *   port: 6379
  * });
- * await redis.connect();
+ * await redisStore.connect();
  *
- * // Create and configure the application with rate limiting
  * const app = new Elysia()
  *   .use(rateLimit({
- *     redis,
- *     limit: 100,           // 100 requests
- *     window: 60,           // per minute
+ *     store: redisStore,
+ *     limit: 1000,          // 1000 requests
+ *     window: 3600,         // per hour
  *   }))
- *   .get('/public-api', () => {
- *     return { success: true, message: 'This endpoint is rate limited' };
- *   });
+ *   .get('/api/endpoint', () => ({ message: 'Hello World' }));
  *
- * // Start the server
  * app.listen(3000);
  * ```
  */
-export declare const rateLimit: ({ redis, limit, window }: RateLimitOptions) => Elysia<"", {
+export declare const rateLimit: ({ store, limit, window }: RateLimitOptions) => Elysia<"", {
     decorator: {};
     store: {};
     derive: {};
@@ -48,7 +65,7 @@ export declare const rateLimit: ({ redis, limit, window }: RateLimitOptions) =>
     typebox: {};
     error: {};
 }, {
-    schema: {};
+    schema: import("elysia").MergeSchema<import("elysia").MergeSchema<{}, {}, "">, {}, "">;
     standaloneSchema: {};
     macro: {};
     macroFn: {};
@@ -56,8 +73,8 @@ export declare const rateLimit: ({ redis, limit, window }: RateLimitOptions) =>
 }, {}, {
     derive: {};
     resolve: {};
-    schema: import("elysia").MergeSchema<{}, {}, "">;
-    standaloneSchema: import("elysia/types").PrettifySchema<{}>;
+    schema: {};
+    standaloneSchema: {};
 }, {
     derive: {};
     resolve: {};

package/dist/modules/elysia/{ratelimit → rateLimit}/types/rateLimitOptions.d.ts

@@ -1,22 +1,13 @@
-import type { Redis } from 'ioredis';
-/**
- * Options to configure the rate limit plugin.
- *
- * @example
- * ```ts
- * const options: RateLimitOptions = {
- *   redis: redisInstance, // Your Redis instance
- *   limit: 100,          // Allow 100 requests
- *   window: 60,          // Per 60 seconds
- *   message: 'You have exceeded the rate limit. Please try again later.'
- * };
- * ```
- */
+import type { KvStore } from '../../../../modules/kvStore/types/kvStore';
 export interface RateLimitOptions {
     /**
-     * Redis instance used for storing rate limit data.
+     * Storage backend for rate limit data.
+     *
+     * - If not specified, defaults to in-memory storage
+     * - Use ':memory:' to explicitly specify in-memory storage
+     * - Provide a KvStore instance for persistent distributed storage
      */
-    readonly redis: Redis;
+    readonly store?: ':memory:' | KvStore;
     /**
      * Maximum number of requests allowed in the time window.
      *

package/dist/modules/jwt/enums/index.d.ts

@@ -0,0 +1,2 @@
+export { JWT_ERROR_KEYS } from './jwtErrorKeys';
+export { PARSE_HUMAN_TIME_TO_SECONDS_ERROR_KEYS } from './parseHumanTimeToSecondsErrorKeys';

package/dist/modules/jwt/enums/index.js

@@ -0,0 +1,11 @@
+// @bun
+import {
+  JWT_ERROR_KEYS
+} from "../../../chunk-ncc0m208.js";
+import {
+  PARSE_HUMAN_TIME_TO_SECONDS_ERROR_KEYS
+} from "../../../chunk-sepwfqdh.js";
+export {
+  PARSE_HUMAN_TIME_TO_SECONDS_ERROR_KEYS,
+  JWT_ERROR_KEYS
+};

package/dist/modules/jwt/enums/jwtErrorKeys.d.ts

@@ -0,0 +1,5 @@
+export declare const JWT_ERROR_KEYS: {
+    readonly JWT_SIGN_ERROR: "jwt.error.sign_error";
+    readonly JWT_SECRET_NOT_FOUND: "jwt.error.secret_not_found";
+    readonly JWT_EXPIRATION_PASSED: "jwt.error.expiration_passed";
+};

package/dist/modules/jwt/enums/parseHumanTimeToSecondsErrorKeys.d.ts

@@ -0,0 +1,3 @@
+export declare const PARSE_HUMAN_TIME_TO_SECONDS_ERROR_KEYS: {
+    readonly INVALID_TIME_EXPRESSION: "parse_human_time_to_seconds.error.invalid_time_expression";
+};

package/dist/modules/jwt/index.d.ts

@@ -0,0 +1 @@
+export { signJWT, verifyJWT } from './jwt';

package/dist/modules/jwt/index.js

@@ -0,0 +1,58 @@
+// @bun
+import {
+  JWT_ERROR_KEYS
+} from "../../chunk-ncc0m208.js";
+import {
+  parseHumanTimeToSeconds
+} from "../../chunk-r1kcf1q6.js";
+import"../../chunk-sepwfqdh.js";
+import {
+  HttpError
+} from "../../chunk-683sda6e.js";
+import"../../chunk-9nw6qekv.js";
+import"../../chunk-vknq69e0.js";
+
+// source/modules/jwt/jwt.ts
+import {
+  SignJWT,
+  jwtVerify
+} from "jose";
+var signJWT = (secret, payload, expiration = Math.floor(Date.now() / 1000) + 60 * 15) => {
+  const exp = expiration instanceof Date ? Math.floor(expiration.getTime() / 1000) : typeof expiration === "number" ? expiration : parseHumanTimeToSeconds(expiration);
+  if (exp <= Math.floor(Date.now() / 1000))
+    throw new HttpError({
+      message: JWT_ERROR_KEYS.JWT_EXPIRATION_PASSED,
+      httpStatusCode: "BAD_REQUEST"
+    });
+  const finalPayload = {
+    iss: "Core-Issuer",
+    sub: "",
+    aud: ["Core-Audience"],
+    jti: Bun.randomUUIDv7(),
+    nbf: Math.floor(Date.now() / 1000),
+    iat: Math.floor(Date.now() / 1000),
+    exp,
+    ...payload
+  };
+  try {
+    const jwt = new SignJWT(finalPayload).setProtectedHeader({ alg: "HS256", typ: "JWT" }).setIssuer(finalPayload.iss).setSubject(finalPayload.sub).setAudience(finalPayload.aud).setJti(finalPayload.jti).setNotBefore(finalPayload.nbf).setIssuedAt(finalPayload.iat).setExpirationTime(expiration).sign(new TextEncoder().encode(secret));
+    return jwt;
+  } catch (error) {
+    throw new HttpError({
+      message: JWT_ERROR_KEYS.JWT_SIGN_ERROR,
+      httpStatusCode: "INTERNAL_SERVER_ERROR",
+      cause: error
+    });
+  }
+};
+var verifyJWT = async (token, secret) => {
+  try {
+    return await jwtVerify(token, new TextEncoder().encode(secret));
+  } catch {
+    return false;
+  }
+};
+export {
+  verifyJWT,
+  signJWT
+};

package/dist/modules/jwt/jwt.d.ts

@@ -0,0 +1,3 @@
+import { type JWTPayload, type JWTVerifyResult } from 'jose';
+export declare const signJWT: (secret: string, payload: JWTPayload, expiration?: number | string | Date) => Promise<string>;
+export declare const verifyJWT: (token: string, secret: string) => Promise<JWTVerifyResult | false>;

package/dist/modules/jwt/utils/index.d.ts

@@ -0,0 +1 @@
+export { parseHumanTimeToSeconds } from './parseHumanTimeToSeconds';

package/dist/modules/jwt/utils/index.js

@@ -0,0 +1,9 @@
+// @bun
+import {
+  parseHumanTimeToSeconds
+} from "../../../chunk-r1kcf1q6.js";
+import"../../../chunk-sepwfqdh.js";
+import"../../../chunk-vknq69e0.js";
+export {
+  parseHumanTimeToSeconds
+};

package/dist/modules/jwt/utils/parseHumanTimeToSeconds.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Converts a human-readable time expression to seconds
+ *
+ * @param timeExpression - A string representing a time period (e.g., "2 hours", "30 minutes ago", "+1 day")
+ *
+ * @throws ({@link BaseError}) - If the time expression is invalid or contains an unknown unit
+ *
+ * @returns The time period in seconds (negative for past times)
+*
+ * @example
+ * ```typescript
+ * parseHumanTimeToSeconds("2 hours")      // Returns 7200
+ * parseHumanTimeToSeconds("30 mins ago")  // Returns -1800
+ * parseHumanTimeToSeconds("+1 day")       // Returns 86400
+ * ```
+ */
+export declare const parseHumanTimeToSeconds: (timeExpression: string) => number;

package/dist/modules/kvStore/enums/index.d.ts

@@ -0,0 +1 @@
+export { KV_STORE_ERROR_KEYS } from './kvStoreErrorKeys';

package/dist/modules/kvStore/enums/index.js

@@ -0,0 +1,7 @@
+// @bun
+import {
+  KV_STORE_ERROR_KEYS
+} from "../../../chunk-z1skzn1j.js";
+export {
+  KV_STORE_ERROR_KEYS
+};

package/dist/modules/kvStore/enums/kvStoreErrorKeys.d.ts

@@ -0,0 +1,5 @@
+export declare const KV_STORE_ERROR_KEYS: {
+    readonly NOT_INTEGER: "kv-store.error.not_integer";
+    readonly CONNECTION_FAILED: "kv-store.error.connection_failed";
+    readonly CLOSING_CONNECTION_FAILED: "kv-store.error.closing_connection_failed";
+};

package/dist/modules/kvStore/ioredis/index.d.ts

@@ -0,0 +1 @@
+export { IoRedisStore } from './ioredisStore';

package/dist/modules/kvStore/ioredis/index.js

@@ -0,0 +1,102 @@
+// @bun
+import {
+  KV_STORE_ERROR_KEYS
+} from "../../../chunk-z1skzn1j.js";
+import {
+  BaseError
+} from "../../../chunk-vknq69e0.js";
+
+// source/modules/kvStore/ioredis/ioredisStore.ts
+import { Redis } from "ioredis";
+class IoRedisStore {
+  _client;
+  constructor(options) {
+    this._client = new Redis({
+      ...options,
+      lazyConnect: true
+    });
+  }
+  async connect() {
+    try {
+      await this._client.connect();
+    } catch (e) {
+      throw new BaseError({
+        message: KV_STORE_ERROR_KEYS.CONNECTION_FAILED,
+        cause: e
+      });
+    }
+  }
+  async close() {
+    try {
+      await this._client.quit();
+    } catch (e) {
+      throw new BaseError({
+        message: KV_STORE_ERROR_KEYS.CLOSING_CONNECTION_FAILED,
+        cause: e
+      });
+    }
+  }
+  async get(key) {
+    const value = await this._client.get(key);
+    if (value === null)
+      return null;
+    try {
+      return JSON.parse(value);
+    } catch {
+      return value;
+    }
+  }
+  async set(key, value, ttlSec) {
+    const serialized = typeof value === "string" ? value : JSON.stringify(value);
+    if (ttlSec)
+      await this._client.setex(key, ttlSec, serialized);
+    else
+      await this._client.set(key, serialized);
+  }
+  async increment(key, amount = 1) {
+    const current = await this._client.get(key);
+    if (current !== null) {
+      const parsed = Number(current);
+      if (Number.isNaN(parsed))
+        throw new BaseError({
+          message: KV_STORE_ERROR_KEYS.NOT_INTEGER
+        });
+    }
+    if (amount === 1)
+      return this._client.incr(key);
+    return this._client.incrby(key, amount);
+  }
+  async decrement(key, amount = 1) {
+    const current = await this._client.get(key);
+    if (current !== null) {
+      const parsed = Number(current);
+      if (Number.isNaN(parsed))
+        throw new BaseError({
+          message: KV_STORE_ERROR_KEYS.NOT_INTEGER
+        });
+    }
+    if (amount === 1)
+      return this._client.decr(key);
+    return this._client.decrby(key, amount);
+  }
+  async del(key) {
+    const result = await this._client.del(key);
+    return result === 1;
+  }
+  async expire(key, ttlSec) {
+    const result = await this._client.expire(key, ttlSec);
+    return result === 1;
+  }
+  ttl(key) {
+    return this._client.ttl(key);
+  }
+  async clean() {
+    const keys = await this._client.keys("*");
+    if (keys.length === 0)
+      return 0;
+    return this._client.del(...keys);
+  }
+}
+export {
+  IoRedisStore
+};

package/dist/modules/kvStore/ioredis/ioredisStore.d.ts

@@ -0,0 +1,107 @@
+import { type RedisOptions } from 'ioredis';
+import type { KvStore } from '../../../modules/kvStore/types/kvStore';
+/**
+ * Redis-based key-value store implementation using ioredis client.
+ *
+ * Provides a Redis-backed implementation of the KvStore interface with
+ * automatic JSON serialization/deserialization and proper error handling.
+ */
+export declare class IoRedisStore implements KvStore {
+    /**
+     * Redis client instance.
+     */
+    private readonly _client;
+    /**
+     * Creates an IoRedis store instance.
+     *
+     * @param options - Redis connection options
+     */
+    constructor(options: RedisOptions);
+    /**
+     * Establishes connection to Redis server.
+     *
+     * @throws ({@link BaseError}) - When connection fails
+     */
+    connect(): Promise<void>;
+    /**
+     * Closes the Redis connection gracefully.
+     *
+     * @throws ({@link BaseError}) - When closing connection fails
+     */
+    close(): Promise<void>;
+    /**
+     * Retrieves a value from Redis by key.
+     *
+     * @template T - The expected type of the stored value
+     *
+     * @param key - The key to retrieve
+     *
+     * @returns The value associated with the key, or null if not found or expired
+     */
+    get<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * Stores a value in Redis with optional TTL.
+     *
+     * @template T - The type of the value being stored
+     *
+     * @param key - The key to store the value under
+     * @param value - The value to store
+     * @param ttlSec - Time to live in seconds (optional)
+     */
+    set<T = unknown>(key: string, value: T, ttlSec?: number): Promise<void>;
+    /**
+     * Increments a numeric value stored at key by the specified amount.
+     * If the key does not exist, it is set to 0 before performing the operation.
+     *
+     * @param key - The key containing the numeric value
+     * @param amount - The amount to increment by (default: 1)
+     *
+     * @throws ({@link BaseError}) - When the value is not a valid integer
+     *
+     * @returns The value after incrementing
+     */
+    increment(key: string, amount?: number): Promise<number>;
+    /**
+     * Decrements a numeric value stored at key by the specified amount.
+     * If the key does not exist, it is set to 0 before performing the operation.
+     *
+     * @param key - The key containing the numeric value
+     * @param amount - The amount to decrement by (default: 1)
+     *
+     * @throws ({@link BaseError}) - When the value is not a valid integer
+     *
+     * @returns The value after decrementing
+     */
+    decrement(key: string, amount?: number): Promise<number>;
+    /**
+     * Deletes a key from Redis.
+     *
+     * @param key - The key to delete
+     *
+     * @returns True if the key was deleted, false if it did not exist
+     */
+    del(key: string): Promise<boolean>;
+    /**
+     * Sets an expiration time for a key.
+     *
+     * @param key - The key to set expiration for
+     * @param ttlSec - Time to live in seconds
+     *
+     * @returns True if the expiration was set, false if the key does not exist
+     */
+    expire(key: string, ttlSec: number): Promise<boolean>;
+    /**
+     * Gets the remaining time to live for a key.
+     *
+     * @param key - The key to check
+     *
+     * @returns Time to live in seconds, -1 if key has no expiration, -2 if key does not exist
+     */
+    ttl(key: string): Promise<number>;
+    /**
+     * Removes all keys from the Redis database.
+     *
+     * @returns The number of keys that were deleted
+     */
+    clean(): Promise<number>;
+}

package/dist/modules/kvStore/memory/index.d.ts

@@ -0,0 +1 @@
+export { MemoryStore } from './memoryStore';

package/dist/modules/kvStore/memory/index.js

@@ -0,0 +1,9 @@
+// @bun
+import {
+  MemoryStore
+} from "../../../chunk-7g8k2epn.js";
+import"../../../chunk-z1skzn1j.js";
+import"../../../chunk-vknq69e0.js";
+export {
+  MemoryStore
+};

package/dist/modules/kvStore/memory/memoryStore.d.ts

@@ -0,0 +1,119 @@
+import type { KvStore } from '../../../modules/kvStore/types/kvStore';
+/**
+ * In-memory key-value store implementation with automatic cleanup of expired entries.
+ *
+ * Provides a memory-based implementation of the KvStore interface with TTL support
+ * and automatic background cleanup of expired entries.
+ */
+export declare class MemoryStore implements KvStore {
+    /**
+     * In-memory key-value store.
+     */
+    private readonly _store;
+    /**
+     * Cleanup interval (5 minutes by default).
+     *
+     * @defaultValue 300000
+     */
+    private readonly _cleanupInterval;
+    /**
+     * Timer for cleanup operations.
+     */
+    private _cleanupTimer;
+    /**
+     * Creates instance and starts cleanup process.
+     *
+     * @param cleanupIntervalMs - Cleanup interval in milliseconds (default: 300000 ms / 5 minutes)
+     */
+    constructor(cleanupIntervalMs?: number);
+    /**
+     * Retrieves a value from the store by key.
+     * Automatically removes expired entries during retrieval.
+     *
+     * @template T - The expected type of the stored value
+     *
+     * @param key - The key to retrieve
+     *
+     * @returns The value associated with the key, or null if not found or expired
+     */
+    get<T = unknown>(key: string): T | null;
+    /**
+     * Stores a value in memory with optional TTL.
+     *
+     * @template T - The type of the value being stored
+     *
+     * @param key - The key to store the value under
+     * @param value - The value to store
+     * @param ttlSec - Time to live in seconds (optional)
+     */
+    set<T = unknown>(key: string, value: T, ttlSec?: number): void;
+    /**
+     * Increments a numeric value stored at key by the specified amount.
+     * If the key does not exist, it is set to 0 before performing the operation.
+     * Preserves existing TTL when incrementing.
+     *
+     * @param key - The key containing the numeric value
+     * @param amount - The amount to increment by (default: 1)
+     *
+     * @throws ({@link BaseError}) - When the value is not a valid integer
+     *
+     * @returns The value after incrementing
+     */
+    increment(key: string, amount?: number): number;
+    /**
+     * Decrements a numeric value stored at key by the specified amount.
+     * If the key does not exist, it is set to 0 before performing the operation.
+     * Preserves existing TTL when decrementing.
+     *
+     * @param key - The key containing the numeric value
+     * @param amount - The amount to decrement by (default: 1)
+     *
+     * @throws ({@link BaseError}) - When the value is not a valid integer
+     *
+     * @returns The value after decrementing
+     */
+    decrement(key: string, amount?: number): number;
+    /**
+     * Deletes a key from the store.
+     *
+     * @param key - The key to delete
+     *
+     * @returns True if the key was deleted, false if it did not exist
+     */
+    del(key: string): boolean;
+    /**
+     * Sets an expiration time for a key.
+     *
+     * @param key - The key to set expiration for
+     * @param ttlSec - Time to live in seconds
+     *
+     * @returns True if the expiration was set, false if the key does not exist
+     */
+    expire(key: string, ttlSec: number): boolean;
+    /**
+     * Gets the remaining time to live for a key.
+     *
+     * @param key - The key to check
+     *
+     * @returns Time to live in seconds, -1 if key has no expiration or does not exist
+     */
+    ttl(key: string): number;
+    /**
+     * Removes all keys from the store.
+     *
+     * @returns The number of keys that were deleted
+     */
+    clean(): number;
+    /**
+     * Starts the cleanup process for expired entries.
+     */
+    private _startCleanup;
+    /**
+     * Removes expired entries from the store.
+     */
+    private _removeExpiredEntries;
+    /**
+     * Stops the cleanup process and clears resources.
+     */
+    destroy(): void;
+}

package/dist/modules/kvStore/memory/types/memoryStoreEntry.d.ts

@@ -0,0 +1,11 @@
+export interface MemoryStoreEntry {
+    /**
+     * Current count value for the key.
+     */
+    readonly value: unknown;
+    /**
+     * Timestamp when this entry expires (in milliseconds).
+     * -1 means no expiration (like Redis behavior).
+     */
+    expiresAt: number;
+}

package/dist/modules/kvStore/types/index.d.ts

@@ -0,0 +1 @@
+export type { KvStore } from './kvStore';

package/dist/modules/kvStore/types/index.js

@@ -0,0 +1 @@
+// @bun