@ibm/ibmi-mcp-server 0.1.0

package/dist/utils/scheduling/scheduler.js

@@ -0,0 +1,155 @@
+/**
+ * @fileoverview Provides a singleton service for scheduling and managing cron jobs.
+ * This service wraps the 'node-cron' library to offer a unified interface for
+ * defining, starting, stopping, and listing recurring tasks within the application.
+ * @module src/utils/scheduling/scheduler
+ */
+import cron, { createTask } from "node-cron";
+import { logger } from "../internal/index.js";
+import { requestContextService } from "../internal/requestContext.js";
+/**
+ * A singleton service for scheduling and managing cron jobs.
+ */
+export class SchedulerService {
+    static instance;
+    jobs = new Map();
+    /** @private */
+    constructor() {
+        logger.info({
+            requestId: "scheduler-init",
+            timestamp: new Date().toISOString(),
+        }, "SchedulerService initialized.");
+    }
+    /**
+     * Gets the singleton instance of the SchedulerService.
+     * @returns The singleton SchedulerService instance.
+     */
+    static getInstance() {
+        if (!SchedulerService.instance) {
+            SchedulerService.instance = new SchedulerService();
+        }
+        return SchedulerService.instance;
+    }
+    /**
+     * Schedules a new job.
+     *
+     * @param id - A unique identifier for the job.
+     * @param schedule - The cron pattern for the schedule (e.g., '* * * * *').
+     * @param taskFunction - The function to execute on schedule. It receives a RequestContext.
+     * @param description - A description of the job.
+     * @returns The newly created Job object.
+     */
+    schedule(id, schedule, taskFunction, description) {
+        if (this.jobs.has(id)) {
+            throw new Error(`Job with ID '${id}' already exists.`);
+        }
+        if (!cron.validate(schedule)) {
+            throw new Error(`Invalid cron schedule: ${schedule}`);
+        }
+        const task = createTask(schedule, async () => {
+            const job = this.jobs.get(id);
+            if (job && job.isRunning) {
+                logger.warning({
+                    requestId: `job-skip-${id}`,
+                    timestamp: new Date().toISOString(),
+                }, `Job '${id}' is already running. Skipping this execution.`);
+                return;
+            }
+            if (job) {
+                job.isRunning = true;
+            }
+            const context = requestContextService.createRequestContext({
+                jobId: id,
+                schedule,
+            });
+            logger.info(context, `Starting job '${id}'...`);
+            try {
+                await Promise.resolve(taskFunction(context));
+                logger.info(context, `Job '${id}' completed successfully.`);
+            }
+            catch (error) {
+                logger.error({
+                    error: error,
+                    ...context,
+                }, `Job '${id}' failed.`);
+            }
+            finally {
+                if (job) {
+                    job.isRunning = false;
+                }
+            }
+        });
+        const newJob = {
+            id,
+            schedule,
+            description,
+            task,
+            isRunning: false,
+        };
+        this.jobs.set(id, newJob);
+        logger.info({
+            requestId: `job-schedule-${id}`,
+            timestamp: new Date().toISOString(),
+        }, `Job '${id}' scheduled: ${description}`);
+        return newJob;
+    }
+    /**
+     * Starts a scheduled job.
+     * @param id - The ID of the job to start.
+     */
+    start(id) {
+        const job = this.jobs.get(id);
+        if (!job) {
+            throw new Error(`Job with ID '${id}' not found.`);
+        }
+        job.task.start();
+        logger.info({
+            requestId: `job-start-${id}`,
+            timestamp: new Date().toISOString(),
+        }, `Job '${id}' started.`);
+    }
+    /**
+     * Stops a scheduled job.
+     * @param id - The ID of the job to stop.
+     */
+    stop(id) {
+        const job = this.jobs.get(id);
+        if (!job) {
+            throw new Error(`Job with ID '${id}' not found.`);
+        }
+        job.task.stop();
+        logger.info({
+            requestId: `job-stop-${id}`,
+            timestamp: new Date().toISOString(),
+        }, `Job '${id}' stopped.`);
+    }
+    /**
+     * Removes a job from the scheduler. The job is stopped before being removed.
+     * @param id - The ID of the job to remove.
+     */
+    remove(id) {
+        const job = this.jobs.get(id);
+        if (!job) {
+            throw new Error(`Job with ID '${id}' not found.`);
+        }
+        job.task.stop();
+        this.jobs.delete(id);
+        logger.info({
+            requestId: `job-remove-${id}`,
+            timestamp: new Date().toISOString(),
+        }, `Job '${id}' removed.`);
+    }
+    /**
+     * Gets a list of all scheduled jobs.
+     * @returns An array of all Job objects.
+     */
+    listJobs() {
+        return Array.from(this.jobs.values());
+    }
+}
+/**
+ * The singleton instance of the SchedulerService.
+ * Use this instance for all job scheduling operations.
+ */
+export const schedulerService = SchedulerService.getInstance();
+//# sourceMappingURL=scheduler.js.map

package/dist/utils/scheduling/scheduler.js.map

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

package/dist/utils/security/idGenerator.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Defines the structure for configuring entity prefixes.
+ * Keys are entity type names (e.g., "project", "task"), and values are their corresponding ID prefixes (e.g., "PROJ", "TASK").
+ */
+export interface EntityPrefixConfig {
+    [key: string]: string;
+}
+/**
+ * Defines options for customizing ID generation.
+ */
+export interface IdGenerationOptions {
+    length?: number;
+    separator?: string;
+    charset?: string;
+}
+/**
+ * A generic ID Generator class for creating and managing unique, prefixed identifiers.
+ * Allows defining custom prefixes, generating random strings, and validating/normalizing IDs.
+ */
+export declare class IdGenerator {
+    /**
+     * Default character set for the random part of the ID.
+     * @private
+     */
+    private static DEFAULT_CHARSET;
+    /**
+     * Default separator character between prefix and random part.
+     * @private
+     */
+    private static DEFAULT_SEPARATOR;
+    /**
+     * Default length for the random part of the ID.
+     * @private
+     */
+    private static DEFAULT_LENGTH;
+    /**
+     * Stores the mapping of entity types to their prefixes.
+     * @private
+     */
+    private entityPrefixes;
+    /**
+     * Stores a reverse mapping from prefixes (case-insensitive) to entity types.
+     * @private
+     */
+    private prefixToEntityType;
+    /**
+     * Constructs an `IdGenerator` instance.
+     * @param entityPrefixes - An initial map of entity types to their prefixes.
+     */
+    constructor(entityPrefixes?: EntityPrefixConfig);
+    /**
+     * Sets or updates the entity prefix configuration and rebuilds the internal reverse lookup map.
+     * @param entityPrefixes - A map where keys are entity type names and values are their desired ID prefixes.
+     */
+    setEntityPrefixes(entityPrefixes: EntityPrefixConfig): void;
+    /**
+     * Retrieves a copy of the current entity prefix configuration.
+     * @returns The current entity prefix configuration.
+     */
+    getEntityPrefixes(): EntityPrefixConfig;
+    /**
+     * Generates a cryptographically secure random string.
+     * @param length - The desired length of the random string. Defaults to `IdGenerator.DEFAULT_LENGTH`.
+     * @param charset - The character set to use. Defaults to `IdGenerator.DEFAULT_CHARSET`.
+     * @returns The generated random string.
+     */
+    generateRandomString(length?: number, charset?: string): string;
+    /**
+     * Generates a unique ID, optionally prepended with a prefix.
+     * @param prefix - An optional prefix for the ID.
+     * @param options - Optional parameters for ID generation (length, separator, charset).
+     * @returns A unique identifier string.
+     */
+    generate(prefix?: string, options?: IdGenerationOptions): string;
+    /**
+     * Generates a unique ID for a specified entity type, using its configured prefix.
+     * @param entityType - The type of entity (must be registered).
+     * @param options - Optional parameters for ID generation.
+     * @returns A unique identifier string for the entity (e.g., "PROJ_A6B3J0").
+     * @throws {McpError} If the `entityType` is not registered.
+     */
+    generateForEntity(entityType: string, options?: IdGenerationOptions): string;
+    /**
+     * Validates if an ID conforms to the expected format for a specific entity type.
+     * @param id - The ID string to validate.
+     * @param entityType - The expected entity type of the ID.
+     * @param options - Optional parameters used during generation for validation consistency.
+     *                  The `charset` from these options will be used for validation.
+     * @returns `true` if the ID is valid, `false` otherwise.
+     */
+    isValid(id: string, entityType: string, options?: IdGenerationOptions): boolean;
+    /**
+     * Escapes special characters in a string for use in a regular expression.
+     * @param str - The string to escape.
+     * @returns The escaped string.
+     * @private
+     */
+    private escapeRegex;
+    /**
+     * Strips the prefix and separator from an ID string.
+     * @param id - The ID string (e.g., "PROJ_A6B3J0").
+     * @param separator - The separator used in the ID. Defaults to `IdGenerator.DEFAULT_SEPARATOR`.
+     * @returns The ID part without the prefix, or the original ID if separator not found.
+     */
+    stripPrefix(id: string, separator?: string): string;
+    /**
+     * Determines the entity type from an ID string by its prefix (case-insensitive).
+     * @param id - The ID string (e.g., "PROJ_A6B3J0").
+     * @param separator - The separator used in the ID. Defaults to `IdGenerator.DEFAULT_SEPARATOR`.
+     * @returns The determined entity type.
+     * @throws {McpError} If ID format is invalid or prefix is unknown.
+     */
+    getEntityType(id: string, separator?: string): string;
+    /**
+     * Normalizes an entity ID to ensure the prefix matches the registered case
+     * and the random part is uppercase. Note: This assumes the charset characters
+     * have a meaningful uppercase version if case-insensitivity is desired for the random part.
+     * For default charset (A-Z0-9), this is fine. For custom charsets, behavior might vary.
+     * @param id - The ID to normalize (e.g., "proj_a6b3j0").
+     * @param separator - The separator used in the ID. Defaults to `IdGenerator.DEFAULT_SEPARATOR`.
+     * @returns The normalized ID (e.g., "PROJ_A6B3J0").
+     * @throws {McpError} If the entity type cannot be determined from the ID.
+     */
+    normalize(id: string, separator?: string): string;
+}
+/**
+ * Default singleton instance of the `IdGenerator`.
+ * Initialize with `idGenerator.setEntityPrefixes({})` to configure.
+ */
+export declare const idGenerator: IdGenerator;
+/**
+ * Generates a standard Version 4 UUID (Universally Unique Identifier).
+ * Uses the Node.js `crypto` module. This function is independent of the IdGenerator instance
+ * to prevent circular dependencies when used by other utilities like requestContextService.
+ * @returns A new UUID string.
+ */
+export declare const generateUUID: () => string;
+/**
+ * Generates a short, 8-character alphanumeric identifier using the default IdGenerator instance.
+ * This is suitable for non-colliding IDs within a reasonable scope, like request IDs.
+ * @returns A new 8-character alphanumeric ID string.
+ */
+export declare const generateShortAlphanumericId: () => string;
+//# sourceMappingURL=idGenerator.d.ts.map

package/dist/utils/security/idGenerator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idGenerator.d.ts","sourceRoot":"","sources":["../../../src/utils/security/idGenerator.ts"],"names":[],"mappings":"AAeA;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,qBAAa,WAAW;IACtB;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe,CAA0C;IACxE;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAO;IACvC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc,CAAK;IAElC;;;OAGG;IACH,OAAO,CAAC,cAAc,CAA0B;IAChD;;;OAGG;IACH,OAAO,CAAC,kBAAkB,CAA8B;IAExD;;;OAGG;gBACS,cAAc,GAAE,kBAAuB;IAKnD;;;OAGG;IACI,iBAAiB,CAAC,cAAc,EAAE,kBAAkB,GAAG,IAAI;IAalE;;;OAGG;IACI,iBAAiB,IAAI,kBAAkB;IAI9C;;;;;OAKG;IACI,oBAAoB,CACzB,MAAM,GAAE,MAAmC,EAC3C,OAAO,GAAE,MAAoC,GAC5C,MAAM;IAuBT;;;;;OAKG;IACI,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,MAAM;IAe3E;;;;;;OAMG;IACI,iBAAiB,CACtB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,mBAAwB,GAChC,MAAM;IAWT;;;;;;;OAOG;IACI,OAAO,CACZ,EAAE,EAAE,MAAM,EACV,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,mBAAwB,GAChC,OAAO;IAuBV;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IAInB;;;;;OAKG;IACI,WAAW,CAChB,EAAE,EAAE,MAAM,EACV,SAAS,GAAE,MAAsC,GAChD,MAAM;IAKT;;;;;;OAMG;IACI,aAAa,CAClB,EAAE,EAAE,MAAM,EACV,SAAS,GAAE,MAAsC,GAChD,MAAM;IAqBT;;;;;;;;;OASG;IACI,SAAS,CACd,EAAE,EAAE,MAAM,EACV,SAAS,GAAE,MAAsC,GAChD,MAAM;CAUV;AAED;;;GAGG;AACH,eAAO,MAAM,WAAW,aAAoB,CAAC;AAE7C;;;;;GAKG;AACH,eAAO,MAAM,YAAY,QAAO,MAE/B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,QAAO,MAM9C,CAAC"}

package/dist/utils/security/idGenerator.js

@@ -0,0 +1,232 @@
+/**
+ * @fileoverview Provides a utility class `IdGenerator` for creating customizable, prefixed unique identifiers,
+ * and a standalone `generateUUID` function for generating standard UUIDs.
+ * The `IdGenerator` supports entity-specific prefixes, custom character sets, and lengths.
+ *
+ * Note: Logging has been removed from this module to prevent circular dependencies
+ * with the `requestContextService`, which itself uses `generateUUID` from this module.
+ * This was causing `ReferenceError: Cannot access 'generateUUID' before initialization`
+ * during application startup.
+ * @module src/utils/security/idGenerator
+ */
+import { randomUUID as cryptoRandomUUID, randomBytes } from "crypto";
+import { JsonRpcErrorCode, McpError } from "../../types-global/errors.js";
+/**
+ * A generic ID Generator class for creating and managing unique, prefixed identifiers.
+ * Allows defining custom prefixes, generating random strings, and validating/normalizing IDs.
+ */
+export class IdGenerator {
+    /**
+     * Default character set for the random part of the ID.
+     * @private
+     */
+    static DEFAULT_CHARSET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+    /**
+     * Default separator character between prefix and random part.
+     * @private
+     */
+    static DEFAULT_SEPARATOR = "_";
+    /**
+     * Default length for the random part of the ID.
+     * @private
+     */
+    static DEFAULT_LENGTH = 6;
+    /**
+     * Stores the mapping of entity types to their prefixes.
+     * @private
+     */
+    entityPrefixes = {};
+    /**
+     * Stores a reverse mapping from prefixes (case-insensitive) to entity types.
+     * @private
+     */
+    prefixToEntityType = {};
+    /**
+     * Constructs an `IdGenerator` instance.
+     * @param entityPrefixes - An initial map of entity types to their prefixes.
+     */
+    constructor(entityPrefixes = {}) {
+        // Logging removed to prevent circular dependency with requestContextService.
+        this.setEntityPrefixes(entityPrefixes);
+    }
+    /**
+     * Sets or updates the entity prefix configuration and rebuilds the internal reverse lookup map.
+     * @param entityPrefixes - A map where keys are entity type names and values are their desired ID prefixes.
+     */
+    setEntityPrefixes(entityPrefixes) {
+        // Logging removed.
+        this.entityPrefixes = { ...entityPrefixes };
+        this.prefixToEntityType = Object.entries(this.entityPrefixes).reduce((acc, [type, prefix]) => {
+            acc[prefix.toLowerCase()] = type; // Store lowercase for case-insensitive lookup
+            return acc;
+        }, {});
+    }
+    /**
+     * Retrieves a copy of the current entity prefix configuration.
+     * @returns The current entity prefix configuration.
+     */
+    getEntityPrefixes() {
+        return { ...this.entityPrefixes };
+    }
+    /**
+     * Generates a cryptographically secure random string.
+     * @param length - The desired length of the random string. Defaults to `IdGenerator.DEFAULT_LENGTH`.
+     * @param charset - The character set to use. Defaults to `IdGenerator.DEFAULT_CHARSET`.
+     * @returns The generated random string.
+     */
+    generateRandomString(length = IdGenerator.DEFAULT_LENGTH, charset = IdGenerator.DEFAULT_CHARSET) {
+        let result = "";
+        // Determine the largest multiple of charset.length that is less than or equal to 256
+        // This is the threshold for rejection sampling to avoid bias.
+        const maxValidByteValue = Math.floor(256 / charset.length) * charset.length;
+        while (result.length < length) {
+            const byteBuffer = randomBytes(1); // Get one random byte
+            const byte = byteBuffer[0];
+            // If the byte is within the valid range (i.e., it won't introduce bias),
+            // use it to select a character from the charset. Otherwise, discard and try again.
+            if (byte !== undefined && byte < maxValidByteValue) {
+                const charIndex = byte % charset.length;
+                const char = charset[charIndex];
+                if (char) {
+                    result += char;
+                }
+            }
+        }
+        return result;
+    }
+    /**
+     * Generates a unique ID, optionally prepended with a prefix.
+     * @param prefix - An optional prefix for the ID.
+     * @param options - Optional parameters for ID generation (length, separator, charset).
+     * @returns A unique identifier string.
+     */
+    generate(prefix, options = {}) {
+        // Logging removed.
+        const { length = IdGenerator.DEFAULT_LENGTH, separator = IdGenerator.DEFAULT_SEPARATOR, charset = IdGenerator.DEFAULT_CHARSET, } = options;
+        const randomPart = this.generateRandomString(length, charset);
+        const generatedId = prefix
+            ? `${prefix}${separator}${randomPart}`
+            : randomPart;
+        return generatedId;
+    }
+    /**
+     * Generates a unique ID for a specified entity type, using its configured prefix.
+     * @param entityType - The type of entity (must be registered).
+     * @param options - Optional parameters for ID generation.
+     * @returns A unique identifier string for the entity (e.g., "PROJ_A6B3J0").
+     * @throws {McpError} If the `entityType` is not registered.
+     */
+    generateForEntity(entityType, options = {}) {
+        const prefix = this.entityPrefixes[entityType];
+        if (!prefix) {
+            throw new McpError(JsonRpcErrorCode.ValidationError, `Unknown entity type: ${entityType}. No prefix registered.`);
+        }
+        return this.generate(prefix, options);
+    }
+    /**
+     * Validates if an ID conforms to the expected format for a specific entity type.
+     * @param id - The ID string to validate.
+     * @param entityType - The expected entity type of the ID.
+     * @param options - Optional parameters used during generation for validation consistency.
+     *                  The `charset` from these options will be used for validation.
+     * @returns `true` if the ID is valid, `false` otherwise.
+     */
+    isValid(id, entityType, options = {}) {
+        const prefix = this.entityPrefixes[entityType];
+        const { length = IdGenerator.DEFAULT_LENGTH, separator = IdGenerator.DEFAULT_SEPARATOR, charset = IdGenerator.DEFAULT_CHARSET, // Use charset from options or default
+         } = options;
+        if (!prefix) {
+            return false;
+        }
+        // Build regex character class from the charset
+        // Escape characters that have special meaning inside a regex character class `[]`
+        const escapedCharsetForClass = charset.replace(/[[\]\\^-]/g, "\\$&");
+        const charsetRegexPart = `[${escapedCharsetForClass}]`;
+        const pattern = new RegExp(`^${this.escapeRegex(prefix)}${this.escapeRegex(separator)}${charsetRegexPart}{${length}}$`);
+        return pattern.test(id);
+    }
+    /**
+     * Escapes special characters in a string for use in a regular expression.
+     * @param str - The string to escape.
+     * @returns The escaped string.
+     * @private
+     */
+    escapeRegex(str) {
+        return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    }
+    /**
+     * Strips the prefix and separator from an ID string.
+     * @param id - The ID string (e.g., "PROJ_A6B3J0").
+     * @param separator - The separator used in the ID. Defaults to `IdGenerator.DEFAULT_SEPARATOR`.
+     * @returns The ID part without the prefix, or the original ID if separator not found.
+     */
+    stripPrefix(id, separator = IdGenerator.DEFAULT_SEPARATOR) {
+        const parts = id.split(separator);
+        return parts.length > 1 ? parts.slice(1).join(separator) : id; // Handle separators in random part
+    }
+    /**
+     * Determines the entity type from an ID string by its prefix (case-insensitive).
+     * @param id - The ID string (e.g., "PROJ_A6B3J0").
+     * @param separator - The separator used in the ID. Defaults to `IdGenerator.DEFAULT_SEPARATOR`.
+     * @returns The determined entity type.
+     * @throws {McpError} If ID format is invalid or prefix is unknown.
+     */
+    getEntityType(id, separator = IdGenerator.DEFAULT_SEPARATOR) {
+        const parts = id.split(separator);
+        if (parts.length < 2 || !parts[0]) {
+            throw new McpError(JsonRpcErrorCode.ValidationError, `Invalid ID format: ${id}. Expected format like: PREFIX${separator}RANDOMLPART`);
+        }
+        const prefix = parts[0];
+        const entityType = this.prefixToEntityType[prefix.toLowerCase()];
+        if (!entityType) {
+            throw new McpError(JsonRpcErrorCode.ValidationError, `Unknown entity type for prefix: ${prefix}`);
+        }
+        return entityType;
+    }
+    /**
+     * Normalizes an entity ID to ensure the prefix matches the registered case
+     * and the random part is uppercase. Note: This assumes the charset characters
+     * have a meaningful uppercase version if case-insensitivity is desired for the random part.
+     * For default charset (A-Z0-9), this is fine. For custom charsets, behavior might vary.
+     * @param id - The ID to normalize (e.g., "proj_a6b3j0").
+     * @param separator - The separator used in the ID. Defaults to `IdGenerator.DEFAULT_SEPARATOR`.
+     * @returns The normalized ID (e.g., "PROJ_A6B3J0").
+     * @throws {McpError} If the entity type cannot be determined from the ID.
+     */
+    normalize(id, separator = IdGenerator.DEFAULT_SEPARATOR) {
+        const entityType = this.getEntityType(id, separator);
+        const registeredPrefix = this.entityPrefixes[entityType];
+        const idParts = id.split(separator);
+        const randomPart = idParts.slice(1).join(separator);
+        // Consider if randomPart.toUpperCase() is always correct for custom charsets.
+        // For now, maintaining existing behavior.
+        return `${registeredPrefix}${separator}${randomPart.toUpperCase()}`;
+    }
+}
+/**
+ * Default singleton instance of the `IdGenerator`.
+ * Initialize with `idGenerator.setEntityPrefixes({})` to configure.
+ */
+export const idGenerator = new IdGenerator();
+/**
+ * Generates a standard Version 4 UUID (Universally Unique Identifier).
+ * Uses the Node.js `crypto` module. This function is independent of the IdGenerator instance
+ * to prevent circular dependencies when used by other utilities like requestContextService.
+ * @returns A new UUID string.
+ */
+export const generateUUID = () => {
+    return cryptoRandomUUID();
+};
+/**
+ * Generates a short, 8-character alphanumeric identifier using the default IdGenerator instance.
+ * This is suitable for non-colliding IDs within a reasonable scope, like request IDs.
+ * @returns A new 8-character alphanumeric ID string.
+ */
+export const generateShortAlphanumericId = () => {
+    // Use the default instance and its generate method without a prefix.
+    return idGenerator.generate(undefined, {
+        length: 8,
+        separator: "", // No separator needed for a simple random string
+    });
+};
+//# sourceMappingURL=idGenerator.js.map

package/dist/utils/security/idGenerator.js.map

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

package/dist/utils/security/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @fileoverview Barrel file for security-related utility modules.
+ * This file re-exports utilities for input sanitization, rate limiting,
+ * and ID generation.
+ * @module src/utils/security
+ */
+export * from "./idGenerator.js";
+export * from "./rateLimiter.js";
+export * from "./sanitization.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/security/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/security/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC"}

package/dist/utils/security/index.js

@@ -0,0 +1,10 @@
+/**
+ * @fileoverview Barrel file for security-related utility modules.
+ * This file re-exports utilities for input sanitization, rate limiting,
+ * and ID generation.
+ * @module src/utils/security
+ */
+export * from "./idGenerator.js";
+export * from "./rateLimiter.js";
+export * from "./sanitization.js";
+//# sourceMappingURL=index.js.map

package/dist/utils/security/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utils/security/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC"}