@kumix/utils 0.1.0

package/dist/logger-BOB35dQN.js

@@ -0,0 +1,231 @@
+import { createConsola } from "consola";
+//#region src/env.ts
+/**
+* Reads an environment variable in a runtime-agnostic way.
+* Tries `process.env` first (Node/Bun), then falls back to `Deno.env`,
+* and finally to the provided fallback value. Failures are swallowed so
+* the function is safe to call in any JavaScript runtime, including
+* Workers where neither global is available.
+*
+* @param key - The name of the environment variable to read
+* @param fallback - Optional value to return when the variable is unset or empty
+* @returns The environment value, or `fallback` if unavailable
+*
+* @example
+* ```ts
+* import { getEnv } from '@kumix/utils';
+*
+* // Read with a fallback
+* const port = getEnv('PORT', '3000');
+* // Example output: '3000' if PORT is unset
+*
+* // Read optional config
+* const databaseUrl = getEnv('DATABASE_URL');
+* // Example output: 'postgres://...' or undefined
+*
+* // Use across runtimes (Node, Bun, Deno, Workers)
+* const apiKey = getEnv('API_KEY');
+* if (!apiKey) throw new Error('API_KEY is required');
+* ```
+*/
+function getEnv(key, fallback) {
+	try {
+		if (typeof process !== "undefined" && process.env) return process.env[key] || fallback;
+	} catch {}
+	try {
+		if (typeof Deno !== "undefined") {
+			const env = Deno.env;
+			if (env && typeof env.get === "function") return env.get(key) || fallback;
+		}
+	} catch {}
+	return fallback;
+}
+//#endregion
+//#region src/constants/development.ts
+/**
+* Development and environment constants
+* Provides environment detection and development-specific configuration values
+*/
+/**
+* Node environment variable
+* Indicates the current environment in which the application is running (e.g., 'development', 'production', 'staging').
+*
+* @example
+* ```ts
+* import { NODE_ENV } from '@/utils/constants';
+*
+* if (NODE_ENV === 'development') {
+*   // Enable dev-only features
+*   console.log('Development mode enabled');
+* }
+*
+* // Environment-specific configuration
+* const apiUrl = NODE_ENV === 'production'
+*   ? 'https://api.kumix.com'
+*   : 'http://localhost:3001';
+* ```
+*/
+const NODE_ENV = getEnv("NODE_ENV");
+/**
+* Checks if the application is running in development mode
+* Useful for enabling development-specific features and debugging.
+*
+* @returns True if NODE_ENV is 'development', false otherwise
+*
+* @example
+* ```ts
+* import { isDevelopment } from '@/utils/constants';
+*
+* if (isDevelopment) {
+*   // Enable hot reloading and dev tools
+*   console.log('Development mode enabled');
+*   enableDevTools();
+* }
+*
+* // Conditional imports
+* if (isDevelopment) {
+*   import('./dev-utils').then(devUtils => {
+*     devUtils.setupDevEnvironment();
+*   });
+* }
+* ```
+*/
+const isDevelopment = NODE_ENV === "development";
+/**
+* Checks if the application is running in staging mode
+* Used for testing production-like environments before deployment.
+*
+* @returns True if NODE_ENV is 'test', false otherwise
+*
+* @example
+* ```ts
+* import { isStaging } from '@/utils/constants';
+*
+* if (isStaging) {
+*   // Use staging API endpoints
+*   apiUrl = 'https://staging-api.kumix.com';
+* }
+*
+* // Staging-specific analytics
+* const analyticsConfig = {
+*   enabled: isStaging || isProduction,
+*   debug: isStaging
+* };
+* ```
+*/
+const isStaging = NODE_ENV === "test";
+/**
+* Checks if the application is running in production mode
+* Used for enabling production optimizations and features.
+*
+* @returns True if NODE_ENV is 'production', false otherwise
+*
+* @example
+* ```ts
+* import { isProduction } from '@/utils/constants';
+*
+* if (isProduction) {
+*   // Enable analytics and error tracking
+*   enableAnalytics();
+*   enableErrorTracking();
+* }
+*
+* // Performance optimizations
+* const shouldMinify = isProduction;
+* const shouldCompress = isProduction;
+* ```
+*/
+const isProduction = NODE_ENV === "production";
+/**
+* The port number on which the application server runs.
+* Defaults to '3000' if the PORT environment variable is not set.
+*
+* @example
+* app.listen(PORT, () => {
+*   console.log(`Server running on port ${PORT}`);
+* });
+*/
+const PORT = getEnv("PORT") || "3000";
+/**
+* The port number on which the api application server runs.
+* Defaults to '3001' if the API_PORT environment variable is not set.
+*
+* @example
+* app.listen(API_PORT, () => {
+*   console.log(`Server running on port ${API_PORT}`);
+* });
+*/
+const API_PORT = getEnv("API_PORT") || "3001";
+/**
+* Indicates whether debug mode is enabled (true in development mode).
+*
+* @example
+* if (DEBUG) {
+*   console.log('Debugging enabled');
+* }
+*/
+const DEBUG = !!isDevelopment;
+/**
+* Log level for Consola or other logging libraries.
+* Controls the verbosity of logs output to the console.
+*
+* @example
+* if (LOG_LEVEL === 'debug') {
+*   consola.debug('Debugging enabled');
+* }
+*/
+const LOG_LEVEL = getEnv("LOG_LEVEL");
+//#endregion
+//#region src/functions/logging/logger.ts
+/**
+* Centralized logging utility for the application
+* Provides consistent logging interface using Consola with custom formatting
+* Used throughout the application to replace console.log statements
+*/
+/**
+* Application logger instance with consistent formatting
+*
+* Provides structured logging with different levels (info, warn, error, debug)
+* and consistent formatting across the application. Replaces direct console usage.
+*
+* @example
+* ```typescript
+* import { logger } from '@kumix/utils';
+*
+* // Basic logging
+* logger.info('User logged in successfully');
+* logger.warn('API rate limit approaching');
+* logger.error('Database connection failed');
+* logger.debug('Processing user data', { userId: 123 });
+*
+* // With context data
+* logger.info('User action completed', {
+*   userId: user.id,
+*   action: 'profile_update',
+*   timestamp: new Date().toISOString()
+* });
+*
+* // Error logging with stack trace
+* try {
+*   await riskyOperation();
+* } catch (error) {
+*   logger.error('Operation failed', { error, context: 'user-service' });
+* }
+*
+* // Performance logging
+* const startTime = Date.now();
+* await someOperation();
+* logger.debug('Operation completed', {
+*   duration: Date.now() - startTime,
+*   operation: 'data-processing'
+* });
+* ```
+*/
+const logger = createConsola({
+	level: isDevelopment ? 5 : LOG_LEVEL ? Number(LOG_LEVEL) : 3,
+	formatOptions: { date: false }
+});
+//#endregion
+export { NODE_ENV as a, isProduction as c, LOG_LEVEL as i, isStaging as l, API_PORT as n, PORT as o, DEBUG as r, isDevelopment as s, logger as t, getEnv as u };
+
+//# sourceMappingURL=logger-BOB35dQN.js.map

package/dist/logger-BOB35dQN.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger-BOB35dQN.js","names":[],"sources":["../src/env.ts","../src/constants/development.ts","../src/functions/logging/logger.ts"],"sourcesContent":["/**\n * Runtime-agnostic environment variable reader\n * Provides safe environment variable access across Bun, Node, Deno, and Workers\n * without throwing when the host runtime does not expose `process` or `Deno`.\n */\n\n/** Minimal Deno global shape we rely on (full Deno namespace is not in std types). */\ndeclare const Deno: { env: { get(key: string): string | undefined } } | undefined;\n\n/**\n * Reads an environment variable in a runtime-agnostic way.\n * Tries `process.env` first (Node/Bun), then falls back to `Deno.env`,\n * and finally to the provided fallback value. Failures are swallowed so\n * the function is safe to call in any JavaScript runtime, including\n * Workers where neither global is available.\n *\n * @param key - The name of the environment variable to read\n * @param fallback - Optional value to return when the variable is unset or empty\n * @returns The environment value, or `fallback` if unavailable\n *\n * @example\n * ```ts\n * import { getEnv } from '@kumix/utils';\n *\n * // Read with a fallback\n * const port = getEnv('PORT', '3000');\n * // Example output: '3000' if PORT is unset\n *\n * // Read optional config\n * const databaseUrl = getEnv('DATABASE_URL');\n * // Example output: 'postgres://...' or undefined\n *\n * // Use across runtimes (Node, Bun, Deno, Workers)\n * const apiKey = getEnv('API_KEY');\n * if (!apiKey) throw new Error('API_KEY is required');\n * ```\n */\nexport function getEnv(key: string, fallback?: string): string | undefined {\n  try {\n    if (typeof process !== \"undefined\" && process.env) {\n      return process.env[key] || fallback;\n    }\n  } catch {\n    // process.env doesn't exist in Workers\n  }\n  try {\n    if (typeof Deno !== \"undefined\") {\n      const env = Deno.env;\n      if (env && typeof env.get === \"function\") {\n        return env.get(key) || fallback;\n      }\n    }\n  } catch {\n    // Deno not available\n  }\n  return fallback;\n}\n","/**\n * Development and environment constants\n * Provides environment detection and development-specific configuration values\n */\n\nimport { getEnv } from \"../env\";\n\n/**\n * Node environment variable\n * Indicates the current environment in which the application is running (e.g., 'development', 'production', 'staging').\n *\n * @example\n * ```ts\n * import { NODE_ENV } from '@/utils/constants';\n *\n * if (NODE_ENV === 'development') {\n *   // Enable dev-only features\n *   console.log('Development mode enabled');\n * }\n *\n * // Environment-specific configuration\n * const apiUrl = NODE_ENV === 'production'\n *   ? 'https://api.kumix.com'\n *   : 'http://localhost:3001';\n * ```\n */\nexport const NODE_ENV = getEnv(\"NODE_ENV\");\n\n/**\n * Checks if the application is running in development mode\n * Useful for enabling development-specific features and debugging.\n *\n * @returns True if NODE_ENV is 'development', false otherwise\n *\n * @example\n * ```ts\n * import { isDevelopment } from '@/utils/constants';\n *\n * if (isDevelopment) {\n *   // Enable hot reloading and dev tools\n *   console.log('Development mode enabled');\n *   enableDevTools();\n * }\n *\n * // Conditional imports\n * if (isDevelopment) {\n *   import('./dev-utils').then(devUtils => {\n *     devUtils.setupDevEnvironment();\n *   });\n * }\n * ```\n */\nexport const isDevelopment = NODE_ENV === \"development\";\n\n/**\n * Checks if the application is running in staging mode\n * Used for testing production-like environments before deployment.\n *\n * @returns True if NODE_ENV is 'test', false otherwise\n *\n * @example\n * ```ts\n * import { isStaging } from '@/utils/constants';\n *\n * if (isStaging) {\n *   // Use staging API endpoints\n *   apiUrl = 'https://staging-api.kumix.com';\n * }\n *\n * // Staging-specific analytics\n * const analyticsConfig = {\n *   enabled: isStaging || isProduction,\n *   debug: isStaging\n * };\n * ```\n */\nexport const isStaging = NODE_ENV === \"test\";\n\n/**\n * Checks if the application is running in production mode\n * Used for enabling production optimizations and features.\n *\n * @returns True if NODE_ENV is 'production', false otherwise\n *\n * @example\n * ```ts\n * import { isProduction } from '@/utils/constants';\n *\n * if (isProduction) {\n *   // Enable analytics and error tracking\n *   enableAnalytics();\n *   enableErrorTracking();\n * }\n *\n * // Performance optimizations\n * const shouldMinify = isProduction;\n * const shouldCompress = isProduction;\n * ```\n */\nexport const isProduction = NODE_ENV === \"production\";\n\n/**\n * The port number on which the application server runs.\n * Defaults to '3000' if the PORT environment variable is not set.\n *\n * @example\n * app.listen(PORT, () => {\n *   console.log(`Server running on port ${PORT}`);\n * });\n */\nexport const PORT = getEnv(\"PORT\") || \"3000\";\n\n/**\n * The port number on which the api application server runs.\n * Defaults to '3001' if the API_PORT environment variable is not set.\n *\n * @example\n * app.listen(API_PORT, () => {\n *   console.log(`Server running on port ${API_PORT}`);\n * });\n */\nexport const API_PORT = getEnv(\"API_PORT\") || \"3001\";\n\n/**\n * Indicates whether debug mode is enabled (true in development mode).\n *\n * @example\n * if (DEBUG) {\n *   console.log('Debugging enabled');\n * }\n */\nexport const DEBUG = !!isDevelopment;\n\n/**\n * Log level for Consola or other logging libraries.\n * Controls the verbosity of logs output to the console.\n *\n * @example\n * if (LOG_LEVEL === 'debug') {\n *   consola.debug('Debugging enabled');\n * }\n */\nexport const LOG_LEVEL = getEnv(\"LOG_LEVEL\");\n","/**\n * Centralized logging utility for the application\n * Provides consistent logging interface using Consola with custom formatting\n * Used throughout the application to replace console.log statements\n */\n\nimport { createConsola } from \"consola\";\n\nimport { isDevelopment, LOG_LEVEL } from \"../../constants/development\";\n\n/**\n * Application logger instance with consistent formatting\n *\n * Provides structured logging with different levels (info, warn, error, debug)\n * and consistent formatting across the application. Replaces direct console usage.\n *\n * @example\n * ```typescript\n * import { logger } from '@kumix/utils';\n *\n * // Basic logging\n * logger.info('User logged in successfully');\n * logger.warn('API rate limit approaching');\n * logger.error('Database connection failed');\n * logger.debug('Processing user data', { userId: 123 });\n *\n * // With context data\n * logger.info('User action completed', {\n *   userId: user.id,\n *   action: 'profile_update',\n *   timestamp: new Date().toISOString()\n * });\n *\n * // Error logging with stack trace\n * try {\n *   await riskyOperation();\n * } catch (error) {\n *   logger.error('Operation failed', { error, context: 'user-service' });\n * }\n *\n * // Performance logging\n * const startTime = Date.now();\n * await someOperation();\n * logger.debug('Operation completed', {\n *   duration: Date.now() - startTime,\n *   operation: 'data-processing'\n * });\n * ```\n */\nexport const logger = createConsola({\n  level: isDevelopment ? 5 : LOG_LEVEL ? Number(LOG_LEVEL) : 3,\n  formatOptions: {\n    date: false,\n  },\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCA,SAAgB,OAAO,KAAa,UAAuC;CACzE,IAAI;EACF,IAAI,OAAO,YAAY,eAAe,QAAQ,KAC5C,OAAO,QAAQ,IAAI,QAAQ;CAE/B,QAAQ,CAER;CACA,IAAI;EACF,IAAI,OAAO,SAAS,aAAa;GAC/B,MAAM,MAAM,KAAK;GACjB,IAAI,OAAO,OAAO,IAAI,QAAQ,YAC5B,OAAO,IAAI,IAAI,GAAG,KAAK;EAE3B;CACF,QAAQ,CAER;CACA,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;;;;;;AC9BA,MAAa,WAAW,OAAO,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;AA0BzC,MAAa,gBAAgB,aAAa;;;;;;;;;;;;;;;;;;;;;;;AAwB1C,MAAa,YAAY,aAAa;;;;;;;;;;;;;;;;;;;;;;AAuBtC,MAAa,eAAe,aAAa;;;;;;;;;;AAWzC,MAAa,OAAO,OAAO,MAAM,KAAK;;;;;;;;;;AAWtC,MAAa,WAAW,OAAO,UAAU,KAAK;;;;;;;;;AAU9C,MAAa,QAAQ,CAAC,CAAC;;;;;;;;;;AAWvB,MAAa,YAAY,OAAO,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AC7F3C,MAAa,SAAS,cAAc;CAClC,OAAO,gBAAgB,IAAI,YAAY,OAAO,SAAS,IAAI;CAC3D,eAAe,EACb,MAAM,MACR;AACF,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,446 @@
+import jwt from "jsonwebtoken";
+
+//#region src/functions/crypto/generate-random-string.d.ts
+/**
+ * Utility function for generating cryptographically secure random strings
+ * Provides secure random string generation for tokens, IDs, and other security-sensitive uses
+ */
+/**
+ * Generates a cryptographically secure random string of specified length
+ * Uses Node.js crypto module for secure random number generation
+ *
+ * @param length - The length of the random string to generate
+ * @returns A random string consisting of uppercase letters and numbers
+ *
+ * @example
+ * ```ts
+ * import { generateRandomString } from '@/utils/functions';
+ *
+ * // Generate a 6-character random string
+ * const verificationCode = generateRandomString(6);
+ * // Example output: "A7B3C9"
+ *
+ * // Generate a longer random string for tokens
+ * const apiToken = generateRandomString(32);
+ * // Example output: "X7F9A2B5C8D1E4F7G0H3I6J9K2L5M8N1"
+ *
+ * // Use as unique identifiers
+ * const uniqueId = generateRandomString(12);
+ * // Example output: "B7C9D1E3F5G7"
+ * ```
+ */
+declare function generateRandomString(length: number): string;
+//#endregion
+//#region src/functions/crypto/jwt.d.ts
+/**
+ * Interface for JWT payload data
+ */
+interface JWTPayload {
+  /** User ID */
+  userId: string;
+  /** User email */
+  email: string;
+  /** User role */
+  role?: string;
+  /** Workspace ID */
+  workspaceId?: string;
+  /** Token expiration time (Unix timestamp) */
+  exp?: number;
+  /** Token issued at time (Unix timestamp) */
+  iat?: number;
+  /** Additional custom claims */
+  [key: string]: unknown;
+  /** For Supabase */
+  aud?: string;
+  sub?: string;
+}
+/**
+ * Interface for JWT options
+ */
+interface JWTOptions {
+  /** Token expiration time (default: '7d') */
+  expiresIn?: string;
+  /** Token issuer */
+  issuer?: string;
+  /** Token audience */
+  audience?: string;
+}
+/**
+ * Interface for JWT verification result
+ */
+interface JWTVerificationResult {
+  /** Whether the token is valid */
+  isValid: boolean;
+  /** Decoded payload if valid */
+  payload?: JWTPayload;
+  /** Error message if verification failed */
+  error?: string;
+}
+/**
+ * Generates a JWT token with the provided payload
+ *
+ * @param payload - The data to encode in the token
+ * @param secret - The secret key for signing the token
+ * @param options - Token generation options
+ * @returns The generated JWT token or null if failed
+ *
+ * @example
+ * ```typescript
+ * import { generateJWT } from '@kumix/utils';
+ *
+ * // Basic usage
+ * const token = generateJWT(
+ *   { userId: '123', email: 'user@example.com' },
+ *   process.env.JWT_SECRET
+ * );
+ *
+ * // With custom expiration
+ * const token = generateJWT(
+ *   { userId: '123', email: 'user@example.com', role: 'admin' },
+ *   process.env.JWT_SECRET,
+ *   { expiresIn: '1h' }
+ * );
+ *
+ * // For API authentication
+ * const authToken = generateJWT(
+ *   { userId: user.id, email: user.email, workspaceId: workspace.id },
+ *   process.env.JWT_SECRET,
+ *   { expiresIn: '24h', issuer: 'myapp.com' }
+ * );
+ * ```
+ */
+declare function generateJWT(payload: JWTPayload, secret: string, options?: JWTOptions): string | null;
+/**
+ * Verifies and decodes a JWT token
+ *
+ * @param token - The JWT token to verify
+ * @param secret - The secret key used to sign the token
+ * @param options - Verification options
+ * @returns Verification result with payload if valid
+ *
+ * @example
+ * ```typescript
+ * import { verifyJWT } from '@kumix/utils';
+ *
+ * // Basic usage
+ * const result = verifyJWT(token, process.env.JWT_SECRET);
+ * if (result.isValid && result.payload) {
+ *   const { userId, email } = result.payload;
+ *   // Proceed with authenticated user
+ * }
+ *
+ * // With issuer verification
+ * const result = verifyJWT(token, process.env.JWT_SECRET, {
+ *   issuer: 'myapp.com'
+ * });
+ *
+ * // In authentication middleware
+ * async function authenticateRequest(req, res, next) {
+ *   const token = req.headers.authorization?.replace('Bearer ', '');
+ *   const result = verifyJWT(token, process.env.JWT_SECRET);
+ *
+ *   if (!result.isValid) {
+ *     return res.status(401).json({ error: 'Invalid token' });
+ *   }
+ *
+ *   req.user = result.payload;
+ *   next();
+ * }
+ * ```
+ */
+declare function verifyJWT(token: string, secret: string, options?: {
+  issuer?: string;
+  audience?: string;
+}): JWTVerificationResult;
+/**
+ * Decodes a JWT token without verification (for debugging/inspection)
+ *
+ * @param token - The JWT token to decode
+ * @returns Decoded payload or null if failed
+ *
+ * @example
+ * ```typescript
+ * import { decodeJWT } from '@kumix/utils';
+ *
+ * // Inspect token contents without verification
+ * const payload = decodeJWT(token);
+ * if (payload) {
+ *   console.log('Token expires at:', new Date(payload.exp * 1000));
+ *   console.log('User ID:', payload.userId);
+ * }
+ *
+ * // For debugging purposes
+ * function debugToken(token: string) {
+ *   const payload = decodeJWT(token);
+ *   if (payload) {
+ *     console.log('Token payload:', payload);
+ *   } else {
+ *     console.log('Invalid token format');
+ *   }
+ * }
+ * ```
+ */
+declare function decodeJWT(token: string): JWTPayload | null;
+/**
+ * Checks if a JWT token is expired
+ *
+ * @param token - The JWT token to check
+ * @returns True if token is expired, false otherwise
+ *
+ * @example
+ * ```typescript
+ * import { isJWTExpired } from '@kumix/utils';
+ *
+ * // Check if token needs refresh
+ * if (isJWTExpired(userToken)) {
+ *   // Redirect to login or refresh token
+ *   await refreshUserToken();
+ * }
+ *
+ * // In token refresh logic
+ * function shouldRefreshToken(token: string): boolean {
+ *   return isJWTExpired(token);
+ * }
+ * ```
+ */
+declare function isJWTExpired(token: string): boolean;
+/**
+ * Gets the remaining time until token expiration
+ *
+ * @param token - The JWT token to check
+ * @returns Remaining time in seconds, or 0 if expired/invalid
+ *
+ * @example
+ * ```typescript
+ * import { getJWTTimeRemaining } from '@kumix/utils';
+ *
+ * // Check how much time is left
+ * const timeLeft = getJWTTimeRemaining(userToken);
+ * if (timeLeft < 300) { // Less than 5 minutes
+ *   // Show warning about token expiration
+ *   showTokenExpirationWarning();
+ * }
+ *
+ * // Format time remaining for display
+ * function formatTimeRemaining(token: string): string {
+ *   const seconds = getJWTTimeRemaining(token);
+ *   const minutes = Math.floor(seconds / 60);
+ *   const hours = Math.floor(minutes / 60);
+ *
+ *   if (hours > 0) return `${hours}h ${minutes % 60}m`;
+ *   if (minutes > 0) return `${minutes}m`;
+ *   return `${seconds}s`;
+ * }
+ * ```
+ */
+declare function getJWTTimeRemaining(token: string): number;
+//#endregion
+//#region src/functions/crypto/password.d.ts
+/**
+ * Password hashing and verification utilities for SaaS applications
+ * Provides secure password handling using bcrypt with proper salt rounds
+ * Includes validation and error handling for production use
+ */
+/**
+ * Interface for password hashing options
+ */
+interface HashPasswordOptions {
+  /** Number of salt rounds for bcrypt (default: 12) */
+  saltRounds?: number;
+}
+/**
+ * Interface for password verification result
+ */
+interface VerifyPasswordResult {
+  /** Whether the password is valid */
+  isValid: boolean;
+  /** Error message if verification failed */
+  error?: string;
+}
+/**
+ * Hashes a password using bcrypt with salt
+ *
+ * @param password - The plain text password to hash
+ * @param options - Hashing options
+ * @returns Promise that resolves to the hashed password or null if failed
+ *
+ * @example
+ * ```typescript
+ * import { hashPassword } from '@kumix/utils';
+ *
+ * // Basic usage
+ * const hashedPassword = await hashPassword('userPassword123');
+ * if (hashedPassword) {
+ *   // Store hashedPassword in database
+ *   await saveUser({ email, password: hashedPassword });
+ * }
+ *
+ * // With custom salt rounds
+ * const hashedPassword = await hashPassword('userPassword123', {
+ *   saltRounds: 14
+ * });
+ *
+ * // Error handling
+ * const hashedPassword = await hashPassword('userPassword123');
+ * if (!hashedPassword) {
+ *   throw new Error('Failed to hash password');
+ * }
+ * ```
+ */
+declare function hashPassword(password: string, options?: HashPasswordOptions): Promise<string | null>;
+/**
+ * Verifies a password against its hash
+ *
+ * @param password - The plain text password to verify
+ * @param hashedPassword - The hashed password to compare against
+ * @returns Promise that resolves to verification result
+ *
+ * @example
+ * ```typescript
+ * import { verifyPassword } from '@kumix/utils';
+ *
+ * // Basic usage
+ * const result = await verifyPassword('userPassword123', storedHashedPassword);
+ * if (result.isValid) {
+ *   // Password is correct, proceed with login
+ *   await loginUser(user);
+ * } else {
+ *   // Password is incorrect
+ *   throw new Error('Invalid credentials');
+ * }
+ *
+ * // With error handling
+ * const result = await verifyPassword('userPassword123', storedHashedPassword);
+ * if (result.error) {
+ *   logger.error('Password verification failed:', result.error);
+ *   throw new Error('Authentication error');
+ * }
+ *
+ * // In authentication middleware
+ * async function authenticateUser(email: string, password: string) {
+ *   const user = await getUserByEmail(email);
+ *   if (!user) {
+ *     return { success: false, error: 'User not found' };
+ *   }
+ *
+ *   const result = await verifyPassword(password, user.hashedPassword);
+ *   if (!result.isValid) {
+ *     return { success: false, error: 'Invalid password' };
+ *   }
+ *
+ *   return { success: true, user };
+ * }
+ * ```
+ */
+declare function verifyPassword(password: string, hashedPassword: string): Promise<VerifyPasswordResult>;
+/**
+ * Checks if a password needs to be rehashed (e.g., due to updated salt rounds)
+ *
+ * @param hashedPassword - The current hashed password
+ * @param targetSaltRounds - The target salt rounds (default: 12)
+ * @returns Whether the password needs to be rehashed
+ *
+ * @example
+ * ```typescript
+ * import { needsRehash, hashPassword } from '@kumix/utils';
+ *
+ * // Check if password needs rehashing during login
+ * async function loginUser(email: string, password: string) {
+ *   const user = await getUserByEmail(email);
+ *   const result = await verifyPassword(password, user.hashedPassword);
+ *
+ *   if (result.isValid) {
+ *     // Check if we need to rehash with updated salt rounds
+ *     if (needsRehash(user.hashedPassword, 14)) {
+ *       const newHash = await hashPassword(password, { saltRounds: 14 });
+ *       if (newHash) {
+ *         await updateUserPassword(user.id, newHash);
+ *       }
+ *     }
+ *
+ *     return { success: true, user };
+ *   }
+ *
+ *   return { success: false, error: 'Invalid credentials' };
+ * }
+ * ```
+ */
+declare function needsRehash(hashedPassword: string, targetSaltRounds?: number): boolean;
+/**
+ * Generates a secure random password
+ *
+ * @param length - Length of the password (default: 16, min: 8, max: 128)
+ * @param options - Password generation options
+ * @returns Generated password string
+ *
+ * @example
+ * ```typescript
+ * import { generateSecurePassword } from '@kumix/utils';
+ *
+ * // Generate default password (16 characters)
+ * const password = generateSecurePassword();
+ *
+ * // Generate longer password
+ * const longPassword = generateSecurePassword(24);
+ *
+ * // Generate password without symbols
+ * const simplePassword = generateSecurePassword(12, {
+ *   includeSymbols: false
+ * });
+ *
+ * // For temporary passwords
+ * const tempPassword = generateSecurePassword(12);
+ * await sendPasswordResetEmail(user.email, tempPassword);
+ * ```
+ */
+declare function generateSecurePassword(length?: number, options?: {
+  includeUppercase?: boolean;
+  includeLowercase?: boolean;
+  includeNumbers?: boolean;
+  includeSymbols?: boolean;
+}): string;
+//#endregion
+//#region src/functions/datetime/parse-datetime.d.ts
+/**
+ * Utility function for parsing date strings into Date objects
+ * Provides natural language date parsing capabilities
+ */
+/**
+ * Parses a date string into a Date object using natural language processing
+ * Passes through Date objects unchanged
+ *
+ * @param str - The date string to parse or a Date object to pass through
+ * @returns A Date object, or null if parsing fails
+ *
+ * @example
+ * ```ts
+ * // Parse natural language date strings
+ * parseDateTime('tomorrow at 3pm')
+ * // Returns a Date object for tomorrow at 3:00 PM
+ *
+ * // Parse formal date strings
+ * parseDateTime('2023-06-15')
+ * // Returns a Date object for June 15, 2023
+ *
+ * // Parse relative dates
+ * parseDateTime('next Friday')
+ * // Returns a Date object for next Friday
+ *
+ * // Pass through existing Date objects
+ * const date = new Date('2023-06-15')
+ * parseDateTime(date)
+ * // Returns the same Date object
+ *
+ * // Parse time strings
+ * parseDateTime('3:30pm')
+ * // Returns a Date object for today at 3:30 PM
+ *
+ * // Parse complex date expressions
+ * parseDateTime('3 days after next Monday')
+ * // Returns the appropriate Date object
+ * ```
+ */
+declare const parseDateTime: (str: Date | string) => Date | null;
+//#endregion
+export { decodeJWT, generateJWT, generateRandomString, generateSecurePassword, getJWTTimeRemaining, hashPassword, isJWTExpired, jwt, needsRehash, parseDateTime, verifyJWT, verifyPassword };
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","names":[],"sources":["../src/functions/crypto/generate-random-string.ts","../src/functions/crypto/jwt.ts","../src/functions/crypto/password.ts","../src/functions/datetime/parse-datetime.ts"],"mappings":";;;;;;AA+BA;;;;AAAmD;;;;ACrBpC;;;;;;;;;;;;;;AAsBV;AAAA;;iBDDW,oBAAA,CAAqB,MAAc;;;AAAA;;;AAAA,UChBzC,UAAA;EAAA;EAER,MAAA;;EAEA,KAAA;EAFA;EAIA,IAAA;EAAA;EAEA,WAAA;EAEA;EAAA,GAAA;EAIC;EAFD,GAAA;EAKA;EAAA,CAHC,GAAA;EAGE;EADH,GAAA;EACA,GAAA;AAAA;;;;UAMQ,UAAA;EAMA;EAJR,SAAA;EAUQ;EARR,MAAA;;EAEA,QAAA;AAAA;;;;UAMQ,qBAAA;EAMH;EAJL,OAAA;EAwCyB;EAtCzB,OAAA,GAAU,UAAU;EAyCI;EAvCxB,KAAA;AAAA;;;;;AAuCwB;AAiF1B;;;;;;;;;;;AAIwB;AAgFxB;;;;AAAoD;AAoCpD;;;;AAA0C;AAuC1C;;;;AAAiD;;iBAnPjC,WAAA,CACd,OAAA,EAAS,UAAA,EACT,MAAA,UACA,OAAA,GAAS,UAAe;;;;;;ACvEd;AAAA;;;;AAUL;AAiCP;;;;;;;;;AAGU;AA4EV;;;;;;;;;AAG+B;AAwE/B;;;;AAEgD;AAgDhD;;iBD/FgB,SAAA,CACd,KAAA,UACA,MAAA,UACA,OAAA;EAAW,MAAA;EAAiB,QAAA;AAAA,IAC3B,qBAAqB;;;;;;ACkGhB;;;;AC5OR;;;;;;;;AAAuD;;;;;;;;;;;iBF0NvC,SAAA,CAAU,KAAA,WAAgB,UAAU;;;;;;;;;;;;;;;;;;;;;;;iBAoCpC,YAAA,CAAa,KAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAuC1B,mBAAA,CAAoB,KAAa;;;;;;ADhTjD;;;;AAAmD;UETzC,mBAAA;;EAER,UAAU;AAAA;;;;UAMF,oBAAA;EDXR;ECaA,OAAA;EDTA;ECWA,KAAK;AAAA;;;;;ADFF;AAAA;;;;;;;;AAYK;AAAA;;;;;;;;;AAYH;AAoCP;;;;;;iBCzBsB,YAAA,CACpB,QAAA,UACA,OAAA,GAAS,mBAAA,GACR,OAAO;;;;ADyBgB;AAiF1B;;;;;;;;;;;AAIwB;AAgFxB;;;;AAAoD;AAoCpD;;;;AAA0C;AAuC1C;;;;AAAiD;;;;;;;;ACvTrC;AAAA;;;;AAUL;iBAgHe,cAAA,CACpB,QAAA,UACA,cAAA,WACC,OAAO,CAAC,oBAAA;;;;;;;;;AA/ED;AA4EV;;;;;;;;;AAG+B;AAwE/B;;;;AAEgD;AAgDhD;;;;;;;;iBAlDgB,WAAA,CACd,cAAA,UACA,gBAA8C;;;AAuDxC;;;;AC5OR;;;;;;;;AAAuD;;;;;;;;;;;;;iBDqOvC,sBAAA,CACd,MAAA,WACA,OAAA;EACE,gBAAA;EACA,gBAAA;EACA,cAAA;EACA,cAAA;AAAA;;;;;;AFtPJ;;;;AAAmD;;;;ACrBpC;;;;;;;;;;;;;;AAsBV;AAAA;;;;;;;;AAYK;AAAA;;;;cEFG,aAAA,GAAiB,GAAA,EAAK,IAAA,cAAgB,IAAI"}