@gerync/utils 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 @gerync
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,385 @@
+# @gerync/utils
+
+A collection of utilities for any type of project, providing logging, error handling, configuration management, and object manipulation helpers.
+
+## Installation
+
+```bash
+npm install @gerync/utils
+```
+
+## Features
+
+- **Colored Logging**: Console logging with hex, RGB, and named color support
+- **Error Handler Middleware**: Express-compatible error handler with multi-language support
+- **Configuration Manager**: Dynamic setup for preferences and localized response messages
+- **Object Utilities**: Helper functions for object key validation and inspection
+
+---
+
+## API Reference
+
+### 1. coloredlog
+
+Log messages to the console with color support. Accepts hex, RGB, or CSS named colors.
+
+**Import:**
+```typescript
+import utils from '@gerync/utils';
+utils.coloredlog(message, color);
+```
+
+**Usage:**
+```typescript
+// Named colors
+utils.coloredlog('This is an error', 'red');
+utils.coloredlog('This is a warning', 'orange');
+utils.coloredlog('Success!', 'green');
+
+// Hex colors
+utils.coloredlog('Custom color', '#FF5733');
+utils.coloredlog('Another shade', '#FF5733CC'); // with alpha
+
+// RGB colors
+utils.coloredlog('RGB color', 'rgb(255, 87, 51)');
+utils.coloredlog('RGBA with alpha', 'rgba(255, 87, 51, 0.8)');
+
+// If color is invalid, logs without styling
+utils.coloredlog('No styling', 'invalid-color');
+```
+
+**Parameters:**
+- `message` (string): The text to log
+- `color` (string): A valid hex (`#XXX`, `#XXXX`, `#XXXXXX`, `#XXXXXXXX`), RGB (`rgb(r, g, b)`), RGBA (`rgba(r, g, b, a)`), or CSS named color
+
+---
+
+### 2. config
+
+Manage application preferences and localized response messages.
+
+**Import:**
+```typescript
+import utils from '@gerync/utils';
+utils.configure({ ... });
+```
+
+**Usage:**
+
+#### Initial Setup
+
+```typescript
+import utils from '@gerync/utils';
+
+utils.configure({
+    prefs: {
+        acceptedLanguages: ['en', 'fr', 'de'],
+        noDupesAllowedof: ['email', 'username', 'phone']
+    },
+    responses: {
+        en: {
+            dupes: {
+                email: 'Email already exists.',
+                username: 'Username is taken.',
+                phone: 'Phone number is already in use.'
+            },
+            general: {
+                error: 'An error occurred. Please try again later.'
+            }
+        },
+        fr: {
+            dupes: {
+                email: 'Cet email existe déjà.',
+                username: 'Ce nom d\'utilisateur est pris.',
+                phone: 'Ce numéro est déjà utilisé.'
+            },
+            general: {
+                error: 'Une erreur est survenue. Veuillez réessayer.'
+            }
+        }
+    }
+});
+```
+
+#### Retrieve Configuration
+
+```typescript
+const responses = utils.config.getResponses();
+const prefs = utils.config.getPrefs();
+
+console.log(responses['en'].dupes.email); // "Email already exists."
+console.log(prefs.acceptedLanguages);     // ['en', 'fr', 'de']
+```
+
+**Methods:**
+- `configure(options)`: Set preferences and responses at runtime
+- `getResponses()`: Return the current response messages object
+- `getPrefs()`: Return the current preferences object
+
+---
+
+### 3. errorHandler
+
+Express middleware for centralized error handling with multi-language support, smart logging, and user-friendly messages.
+
+**Import:**
+```typescript
+import utils from '@gerync/utils';
+app.use(utils.errorHandler);
+```
+
+**Setup:**
+
+```typescript
+import express from 'express';
+import utils from '@gerync/utils';
+
+const app = express();
+
+// Configure responses and preferences BEFORE using the middleware
+utils.configure({
+    prefs: {
+        acceptedLanguages: ['en', 'hu', 'es'],
+        noDupesAllowedof: ['email', 'username', 'phone']
+    },
+    responses: {
+        en: {
+            dupes: {
+                email: 'Email address already exists.',
+                username: 'Username is already taken.',
+                phone: 'Phone number is already in use.'
+            },
+            general: {
+                error: 'An internal server error occurred.'
+            }
+        }
+    }
+});
+
+// Use the middleware at the end
+app.use(utils.errorHandler);
+```
+
+**Features:**
+
+- **Language Detection**: Detects language from `req.lang`, `req.language`, or `Accept-Language` header
+- **User-Friendly Responses**: Returns localized messages to clients based on their language
+- **Smart Logging**: Only logs detailed error reports for server-side issues (5xx), not user errors (4xx)
+- **Multi-Colored Console Output**: Color-coded error reports for easy debugging
+- **Automatic Error Classification**: Recognizes user-caused errors (validation, duplicates, etc.)
+
+**Error Response Format:**
+
+```json
+{
+    "status": "error",
+    "code": "ER_DUP_ENTRY",
+    "message": "Email address already exists."
+}
+```
+
+**Console Output (Server Errors Only):**
+
+```
+===================== ERROR REPORT =====================
+Time: 2025-12-29 19:52:09
+Route: POST /api/users
+RequestId: abc123def456
+Status: 500
+Code: DATABASE_ERROR
+UserMessage: An internal server error occurred.
+RawMessage: Connection timeout
+Stack: Error: Connection timeout
+    at Database.query (...)
+    at ...
+========================================================
+```
+
+**Supported Error Codes:**
+
+User-caused (4xx):
+- `BAD_REQUEST`: Malformed request
+- `UNAUTHORIZED`: Auth required
+- `FORBIDDEN`: Permission denied
+- `NOT_FOUND`: Resource not found
+- `CONFLICT`: Resource conflict
+- `METHOD_NOT_ALLOWED`
+- `NOT_ACCEPTABLE`
+- `UNSUPPORTED_MEDIA_TYPE`
+- `PAYLOAD_TOO_LARGE`
+- `UNPROCESSABLE_ENTITY`
+- `TOO_MANY_REQUESTS`
+- `VALIDATION_ERROR`: User input validation failure
+- `ER_DUP_ENTRY`: Duplicate database entry
+
+Server-side (5xx):
+- `INTERNAL_SERVER_ERROR`: Unhandled error
+- `DATABASE_ERROR`: Database operation failed
+- `SERVICE_UNAVAILABLE`: Temporary service outage
+- `BAD_GATEWAY`
+- `GATEWAY_TIMEOUT`
+- `NOT_IMPLEMENTED`
+- `NETWORK_ERROR`
+- `TIMEOUT`
+
+---
+
+### 4. object utilities
+
+Helper functions for validating and inspecting object keys.
+
+**Import:**
+```typescript
+import utils from '@gerync/utils';
+const { Keysamount, KeysInRange, KeysInRangeDetailed, AllowedKeys } = utils.object;
+```
+
+#### Keysamount
+Get the number of keys in an object.
+
+```typescript
+const user = { name: 'John', email: 'john@example.com', age: 30 };
+const count = utils.object.Keysamount(user); // 3
+```
+
+#### KeysInRange
+Check if an object has a key count within a specified range.
+
+```typescript
+const user = { name: 'John', email: 'john@example.com', age: 30 };
+
+// Exact count
+utils.object.KeysInRange(user, 3); // true
+utils.object.KeysInRange(user, 2); // false
+
+// Range check
+utils.object.KeysInRange(user, 2, 5); // true (3 is between 2 and 5)
+utils.object.KeysInRange(user, 4, 10); // false (3 is not between 4 and 10)
+```
+
+#### KeysInRangeDetailed
+Check key count within range and return detailed status.
+
+```typescript
+const user = { name: 'John', email: 'john@example.com' };
+
+utils.object.KeysInRangeDetailed(user, 1, 5);   // 0 (within range)
+utils.object.KeysInRangeDetailed(user, 5, 10);  // -1 (below minimum)
+utils.object.KeysInRangeDetailed(user, 1, 1);   // 1 (above maximum)
+```
+
+Returns:
+- `0`: Key count is within range
+- `-1`: Key count is below minimum
+- `1`: Key count is above maximum
+
+#### AllowedKeys
+Validate that an object contains only allowed keys, with required and optional key support.
+
+```typescript
+const createUserPayload = { name: 'John', email: 'john@example.com' };
+const updateUserPayload = { name: 'Jane' };
+
+// Required keys: name, email
+// Optional keys: phone, bio
+const requiredKeys = ['name', 'email'];
+const optionalKeys = ['phone', 'bio'];
+
+utils.object.AllowedKeys(createUserPayload, requiredKeys, optionalKeys);  // true
+utils.object.AllowedKeys(updateUserPayload, requiredKeys, optionalKeys);  // false (missing email)
+
+// All keys in object must be allowed
+const invalidPayload = { name: 'John', email: 'john@example.com', admin: true };
+utils.object.AllowedKeys(invalidPayload, requiredKeys, optionalKeys);     // false (admin not allowed)
+```
+
+**Parameters:**
+- `obj` (Record<string, any>): Object to validate
+- `keys` (string[]): Required keys that must be present
+- `optionalKeys` (string[], default `[]`): Optional keys that may be present
+
+**Returns:** `true` if validation passes, `false` otherwise
+
+---
+
+## Complete Example
+
+```typescript
+import express from 'express';
+import utils from '@gerync/utils';
+
+const app = express();
+
+// Setup Config
+utils.configure({
+    prefs: {
+        acceptedLanguages: ['en', 'es'],
+        noDupesAllowedof: ['email', 'username']
+    },
+    responses: {
+        en: {
+            dupes: {
+                email: 'Email already exists.',
+                username: 'Username is taken.'
+            },
+            general: {
+                error: 'An error occurred.'
+            }
+        },
+        es: {
+            dupes: {
+                email: 'El email ya existe.',
+                username: 'El nombre de usuario ya está en uso.'
+            },
+            general: {
+                error: 'Ocurrió un error.'
+            }
+        }
+    }
+});
+
+app.use(express.json());
+
+// Routes
+app.post('/users', (req, res, next) => {
+    try {
+        // Validate request payload
+        const requiredKeys = ['name', 'email'];
+        const optionalKeys = ['phone'];
+
+        if (!utils.object.AllowedKeys(req.body, requiredKeys, optionalKeys)) {
+            return res.status(400).json({
+                status: 'error',
+                message: 'Invalid request payload'
+            });
+        }
+
+        utils.coloredlog(`User creation requested: ${req.body.email}`, 'cyan');
+
+        // Simulate user creation
+        const user = { id: 1, ...req.body };
+        res.json(user);
+    } catch (error) {
+        next(error);
+    }
+});
+
+// Error handler middleware (must be last)
+app.use(utils.errorHandler);
+
+app.listen(3000, () => {
+    utils.coloredlog('Server running on port 3000', 'green');
+});
+```
+
+---
+
+## License
+
+This project is licensed under the MIT License.
+
+- Permissions: Commercial use, modification, distribution, private use
+- Conditions: Include copyright and license notices
+- Limitations: No warranty; authors are not liable for damages
+
+See the full license text in [LICENSE](LICENSE).

package/SECURITY.md

@@ -0,0 +1,45 @@
+# Security Policy
+
+## Overview
+
+@gerync/utils is a lightweight utility library with no sensitive data handling, no network calls, and no authentication mechanisms. It primarily provides:
+- Console logging utilities
+- Error handling and configuration
+- Object validation helpers
+
+As such, security risks are minimal. However, we appreciate responsible disclosure.
+
+## Reporting Security Issues
+
+If you discover a security concern:
+
+1. **Please do not open a public issue** on GitHub
+2. Email: contact@gerync.com with details
+3. Include a description of the issue and steps to reproduce (if applicable)
+
+We'll acknowledge receipt and respond as time permits.
+
+## Known Limitations
+
+- This is a hobby/utility project with no guaranteed maintenance SLA
+- Security updates may take time or may not happen immediately
+- Users are responsible for validating their own use cases
+
+## Best Practices for Users
+
+- **Sanitize user input** before passing to object validation functions
+- **Avoid logging sensitive data** (credentials, tokens, PII) through coloredlog
+- **Configure error responses** carefully to avoid exposing internal details to clients
+- **Keep dependencies updated** in your own projects
+
+## Third-Party Dependencies
+
+- **express**: Security maintained by the Express community
+- **typescript**: Security maintained by the TypeScript team
+
+We don't actively monitor these, but we recommend keeping them updated in your own projects.
+
+## No Warranty
+
+This library is provided "as-is" without warranty. See [LICENSE](LICENSE) for full details.
+

package/dist/functions/Colorlog.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Log a message to console with color support.
+ * Accepts hex, RGB, RGBA, and CSS named colors.
+ * Falls back to unstyled console.log if color is invalid.
+ *
+ * @param message - Text to log
+ * @param color - Valid hex (#XXX, #XXXX, #XXXXXX, #XXXXXXXX),
+ *                RGB (rgb(r, g, b)), RGBA (rgba(r, g, b, a)),
+ *                or CSS named color
+ *
+ * @example
+ * coloredlog('Error!', 'red');
+ * coloredlog('Success', '#00FF00');
+ * coloredlog('Info', 'rgb(0, 0, 255)');
+ */
+export default function Coloredlog(message: string, color: string): void;
+//# sourceMappingURL=Colorlog.d.ts.map

package/dist/functions/Colorlog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Colorlog.d.ts","sourceRoot":"","sources":["../../functions/Colorlog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,OAAO,UAAU,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CA8BvE"}

package/dist/functions/Colorlog.js

@@ -0,0 +1,44 @@
+/**
+ * Log a message to console with color support.
+ * Accepts hex, RGB, RGBA, and CSS named colors.
+ * Falls back to unstyled console.log if color is invalid.
+ *
+ * @param message - Text to log
+ * @param color - Valid hex (#XXX, #XXXX, #XXXXXX, #XXXXXXXX),
+ *                RGB (rgb(r, g, b)), RGBA (rgba(r, g, b, a)),
+ *                or CSS named color
+ *
+ * @example
+ * coloredlog('Error!', 'red');
+ * coloredlog('Success', '#00FF00');
+ * coloredlog('Info', 'rgb(0, 0, 255)');
+ */
+export default function Coloredlog(message, color) {
+    // #region Color Validation Regexes
+    /** Regex patterns to validate different color formats */
+    const ColorRegex = {
+        /** Hex colors: #RGB, #RGBA, #RRGGBB, #RRGGBBAA */
+        hex: /^#([A-Fa-f0-9]{3}|[A-Fa-f0-9]{4}|[A-Fa-f0-9]{6}|[A-Fa-f0-9]{8})$/,
+        /** RGB/RGBA colors: rgb(r, g, b) or rgba(r, g, b, a) */
+        rgb: /^rgba?\(\s*(\d{1,3}%?)\s*[\s,]\s*(\d{1,3}%?)\s*[\s,]\s*(\d{1,3}%?)(?:\s*[\s,/]\s*((?:0|1|0?\.\d+)(?:%?)))?\s*\)$/,
+        /** CSS named colors (e.g., 'red', 'blue', 'aliceblue') */
+        named: /^(?:aliceblue|antiquewhite|aqua|aquamarine|azure|beige|bisque|black|blanchedalmond|blue|blueviolet|brown|burlywood|cadetblue|chartreuse|chocolate|coral|cornflowerblue|cornsilk|crimson|cyan|darkblue|darkcyan|darkgoldenrod|darkgray|darkgreen|darkgrey|darkkhaki|darkmagenta|darkolivegreen|darkorange|darkorchid|darkred|darksalmon|darkseagreen|darkslateblue|darkslategray|darkslategrey|darkturquoise|darkviolet|deeppink|deepskyblue|dimgray|dimgrey|dodgerblue|firebrick|floralwhite|forestgreen|fuchsia|gainsboro|ghostwhite|gold|goldenrod|gray|green|greenyellow|grey|honeydew|hotpink|indianred|indigo|ivory|khaki|lavender|lavenderblush|lawngreen|lemonchiffon|lightblue|lightcoral|lightcyan|lightgoldenrodyellow|lightgray|lightgreen|lightgrey|lightpink|lightsalmon|lightseagreen|lightskyblue|mineskyblue|lightslategray|lightslategrey|lightsteelblue|lightyellow|limegreen|linen|magenta|mediumaquamarine|mediumblue|mediumorchid|mediumpurple|mediumseagreen|mediumslateblue|mediumspringgreen|mediumturquoise|mediumvioletred|midnightblue|mintcream|mistyrose|moccasin|navajowhite|oldlace|olivedrab|orangered|palegoldenrod|palegreen|palevioletred)$/i,
+    };
+    // #endregion
+    // #region Validate Color Format
+    /** Test if color matches any valid format */
+    const isValid = ColorRegex.hex.test(color) ||
+        ColorRegex.rgb.test(color) ||
+        ColorRegex.named.test(color);
+    // #endregion
+    // #region Output
+    if (isValid) {
+        /** Use CSS styling for valid colors */
+        console.log(`%c${message}`, `color: ${color}; font-weight: bold;`);
+    }
+    else {
+        /** Fallback: plain console.log if color is invalid */
+        console.log(message);
+    }
+    // #endregion
+}

package/dist/functions/Config.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Runtime configuration manager for preferences and localized response messages.
+ * Stores global state for error messages, language preferences, and custom messages.
+ */
+declare const Configs: {
+    /**
+     * Initialize configuration with custom responses and preferences.
+     * Merges or replaces the runtime state.
+     * @param options.responses - Localized message objects by language
+     * @param options.prefs - Preferences including acceptedLanguages and noDupesAllowedof
+     */
+    configure(options: {
+        responses: any;
+        prefs: any;
+    }): void;
+    /**
+     * Retrieve all configured localized response messages.
+     * @returns The current responses object (by language and code)
+     */
+    getResponses(): any;
+    /**
+     * Retrieve current preferences.
+     * @returns The current preferences object
+     */
+    getPrefs(): any;
+    /**
+     * Set or update a single message for a language and error code.
+     * Useful for dynamically adding custom messages at runtime.
+     * @param lang - Language code (e.g., 'en', 'es', 'fr')
+     * @param code - Error or message code (e.g., 'CUSTOM_ERROR', 'ObjectTooLong')
+     * @param message - The message text
+     */
+    setMessage(lang: string, code: string, message: string): void;
+    /**
+     * Retrieve a message by language and code with graceful fallbacks.
+     * Fallback chain: requested language → English → provided fallback → undefined
+     * @param lang - Language code to look up
+     * @param code - Message code to retrieve
+     * @param fallback - Optional fallback message if not found
+     * @returns The message, fallback, or undefined
+     */
+    getMessage(lang: string, code: string, fallback?: string): string | undefined;
+};
+export default Configs;
+//# sourceMappingURL=Config.d.ts.map

package/dist/functions/Config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Config.d.ts","sourceRoot":"","sources":["../../functions/Config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAaH,QAAA,MAAM,OAAO;IAET;;;;;OAKG;uBACgB;QAAE,SAAS,EAAE,GAAG,CAAC;QAAC,KAAK,EAAE,GAAG,CAAA;KAAE;IAOjD;;;OAGG;;IAOH;;;OAGG;;IAOH;;;;;;OAMG;qBACc,MAAM,QAAQ,MAAM,WAAW,MAAM;IAetD;;;;;;;OAOG;qBACc,MAAM,QAAQ,MAAM,aAAa,MAAM,GAAG,MAAM,GAAG,SAAS;CAehF,CAAC;AAEF,eAAe,OAAO,CAAC"}

package/dist/functions/Config.js

@@ -0,0 +1,91 @@
+/**
+ * Runtime configuration manager for preferences and localized response messages.
+ * Stores global state for error messages, language preferences, and custom messages.
+ */
+// #region Runtime State
+/** Cached localized response messages for all languages */
+let runtimeResponses = {};
+/** Cached preferences (languages, duplicate field names, etc.) */
+let runtimePrefs = {
+    noDupesAllowedof: [],
+    acceptedLanguages: ['en']
+};
+// #endregion
+const Configs = {
+    // #region Configure
+    /**
+     * Initialize configuration with custom responses and preferences.
+     * Merges or replaces the runtime state.
+     * @param options.responses - Localized message objects by language
+     * @param options.prefs - Preferences including acceptedLanguages and noDupesAllowedof
+     */
+    configure(options) {
+        runtimeResponses = options.responses;
+        runtimePrefs = options.prefs;
+    },
+    // #endregion
+    // #region Get Responses
+    /**
+     * Retrieve all configured localized response messages.
+     * @returns The current responses object (by language and code)
+     */
+    getResponses() {
+        return runtimeResponses;
+    },
+    // #endregion
+    // #region Get Preferences
+    /**
+     * Retrieve current preferences.
+     * @returns The current preferences object
+     */
+    getPrefs() {
+        return runtimePrefs;
+    },
+    // #endregion
+    // #region Set Message
+    /**
+     * Set or update a single message for a language and error code.
+     * Useful for dynamically adding custom messages at runtime.
+     * @param lang - Language code (e.g., 'en', 'es', 'fr')
+     * @param code - Error or message code (e.g., 'CUSTOM_ERROR', 'ObjectTooLong')
+     * @param message - The message text
+     */
+    setMessage(lang, code, message) {
+        // Initialize responses if not yet configured
+        if (!runtimeResponses || typeof runtimeResponses !== 'object') {
+            runtimeResponses = {};
+        }
+        // Initialize language pack if not exists
+        if (!runtimeResponses[lang] || typeof runtimeResponses[lang] !== 'object') {
+            runtimeResponses[lang] = {};
+        }
+        // Set the message
+        runtimeResponses[lang][code] = message;
+    },
+    // #endregion
+    // #region Get Message
+    /**
+     * Retrieve a message by language and code with graceful fallbacks.
+     * Fallback chain: requested language → English → provided fallback → undefined
+     * @param lang - Language code to look up
+     * @param code - Message code to retrieve
+     * @param fallback - Optional fallback message if not found
+     * @returns The message, fallback, or undefined
+     */
+    getMessage(lang, code, fallback) {
+        // Try requested language first
+        const langPack = runtimeResponses?.[lang];
+        if (langPack && typeof langPack[code] === 'string') {
+            return langPack[code];
+        }
+        // Fall back to English
+        const englishPack = runtimeResponses?.['en'];
+        if (englishPack && typeof englishPack[code] === 'string') {
+            return englishPack[code];
+        }
+        // Return provided fallback or undefined
+        return fallback;
+    }
+    // #endregion
+};
+export default Configs;

package/dist/functions/ObjectKeys.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Object utilities for key validation and inspection.
+ * Provides functions to count, range-check, and validate object keys.
+ */
+/**
+ * Count the number of keys in an object.
+ * @param obj - The object to inspect
+ * @returns The number of keys (properties) in the object
+ */
+export declare function Keysamount(obj: Record<string, any>): number;
+/**
+ * Check if an object's key count is within a specified range.
+ * If only min is provided, checks for exact match.
+ * @param obj - The object to inspect
+ * @param min - Minimum key count (or exact count if max is undefined)
+ * @param max - Maximum key count (optional)
+ * @returns true if key count is within range, false otherwise
+ */
+export declare function KeysInRange(obj: Record<string, any>, min: number, max: number): boolean;
+/**
+ * Check if an object's key count is within range and return detailed status.
+ * @param obj - The object to inspect
+ * @param min - Minimum key count
+ * @param max - Maximum key count
+ * @returns -1 if below minimum, 1 if above maximum, 0 if within range
+ */
+export declare function KeysInRangeDetailed(obj: Record<string, any>, min: number, max: number): number;
+/**
+ * Validate that an object contains only allowed keys.
+ * All required keys must be present; object can only contain required + optional keys.
+ * @param obj - The object to validate
+ * @param keys - Required keys that must be present
+ * @param optionalKeys - Optional keys that may be present (default: [])
+ * @returns true if validation passes, false if any rule violated
+ */
+export declare function AllowedKeys(obj: Record<string, any>, keys: string[], optionalKeys?: string[]): boolean;
+declare const _default: {
+    Keysamount: typeof Keysamount;
+    KeysInRange: typeof KeysInRange;
+    KeysInRangeDetailed: typeof KeysInRangeDetailed;
+    AllowedKeys: typeof AllowedKeys;
+};
+export default _default;
+//# sourceMappingURL=ObjectKeys.d.ts.map

package/dist/functions/ObjectKeys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ObjectKeys.d.ts","sourceRoot":"","sources":["../../functions/ObjectKeys.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAE3D;AAID;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAOvF;AAID;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAa9F;AAID;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,YAAY,GAAE,MAAM,EAAO,GAAG,OAAO,CAwB1G;;;;;;;AAID,wBAKE"}

package/dist/functions/ObjectKeys.js

@@ -0,0 +1,96 @@
+/**
+ * Object utilities for key validation and inspection.
+ * Provides functions to count, range-check, and validate object keys.
+ */
+// #region Keysamount
+/**
+ * Count the number of keys in an object.
+ * @param obj - The object to inspect
+ * @returns The number of keys (properties) in the object
+ */
+export function Keysamount(obj) {
+    return Object.keys(obj).length;
+}
+// #endregion
+// #region KeysInRange
+/**
+ * Check if an object's key count is within a specified range.
+ * If only min is provided, checks for exact match.
+ * @param obj - The object to inspect
+ * @param min - Minimum key count (or exact count if max is undefined)
+ * @param max - Maximum key count (optional)
+ * @returns true if key count is within range, false otherwise
+ */
+export function KeysInRange(obj, min, max) {
+    const keyCount = Keysamount(obj);
+    // If max not provided, treat min as exact count
+    if (max === undefined) {
+        max = min;
+    }
+    return keyCount >= min && keyCount <= max;
+}
+// #endregion
+// #region KeysInRangeDetailed
+/**
+ * Check if an object's key count is within range and return detailed status.
+ * @param obj - The object to inspect
+ * @param min - Minimum key count
+ * @param max - Maximum key count
+ * @returns -1 if below minimum, 1 if above maximum, 0 if within range
+ */
+export function KeysInRangeDetailed(obj, min, max) {
+    const keyCount = Keysamount(obj);
+    // If max not provided, treat min as exact count
+    if (max === undefined) {
+        max = min;
+    }
+    if (keyCount < min) {
+        return -1;
+    }
+    else if (keyCount > max) {
+        return 1;
+    }
+    else {
+        return 0;
+    }
+}
+// #endregion
+// #region AllowedKeys
+/**
+ * Validate that an object contains only allowed keys.
+ * All required keys must be present; object can only contain required + optional keys.
+ * @param obj - The object to validate
+ * @param keys - Required keys that must be present
+ * @param optionalKeys - Optional keys that may be present (default: [])
+ * @returns true if validation passes, false if any rule violated
+ */
+export function AllowedKeys(obj, keys, optionalKeys = []) {
+    const objKeys = Object.keys(obj);
+    const allowedSet = new Set([...keys, ...optionalKeys]);
+    // Check: object doesn't have extra keys
+    if (objKeys.length > allowedSet.size) {
+        return false;
+    }
+    // Check: all required keys are present
+    for (const key of keys) {
+        if (!(key in obj)) {
+            return false;
+        }
+    }
+    // Check: all keys in object are allowed
+    for (const key of objKeys) {
+        if (!allowedSet.has(key)) {
+            return false;
+        }
+    }
+    return true;
+}
+// #endregion
+// #region Exports
+export default {
+    Keysamount,
+    KeysInRange,
+    KeysInRangeDetailed,
+    AllowedKeys
+};
+// #endregion

package/dist/functions/handleError.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Express error handler middleware for centralized error handling
+ * with multi-language support, smart logging, and user-friendly messages.
+ *
+ * Usage: app.use(errorHandler) at the end of middleware chain
+ */
+export default function errorHandler(err: any, req: any, res: any, next: any): void;
+//# sourceMappingURL=handleError.d.ts.map

package/dist/functions/handleError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handleError.d.ts","sourceRoot":"","sources":["../../functions/handleError.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,MAAM,CAAC,OAAO,UAAU,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,GAAG,IAAI,CA+IlF"}

package/dist/functions/handleError.js

@@ -0,0 +1,137 @@
+import Configs from './Config';
+import Coloredlog from './Colorlog';
+/**
+ * Express error handler middleware for centralized error handling
+ * with multi-language support, smart logging, and user-friendly messages.
+ *
+ * Usage: app.use(errorHandler) at the end of middleware chain
+ */
+export default function errorHandler(err, req, res, next) {
+    // #region Initialize Configuration
+    const responses = Configs.getResponses();
+    const prefs = Configs.getPrefs();
+    // #endregion
+    // #region Extract Request Context
+    /** Detect user language from request or Accept-Language header */
+    const lang = (req.lang || req.language || (req.headers['accept-language'] ? req.headers['accept-language'].split(',')[0] : 'en'));
+    /** Extract error details from error object */
+    const statusCode = err.status || 500;
+    const code = err.code || 'INTERNAL_SERVER_ERROR';
+    const rawErrorMessage = err.message || '';
+    // #endregion
+    // #region Server Default Messages
+    /** Fallback messages for server-side (5xx) errors when localized responses unavailable */
+    const serverDefaultMessages = {
+        INTERNAL_SERVER_ERROR: 'An internal server error occurred.',
+        DATABASE_ERROR: 'A database error occurred.',
+        SERVICE_UNAVAILABLE: 'Service is temporarily unavailable.',
+        BAD_GATEWAY: 'Bad gateway.',
+        GATEWAY_TIMEOUT: 'Gateway timed out.',
+        NOT_IMPLEMENTED: 'This feature is not implemented.',
+        NETWORK_ERROR: 'A network error occurred.',
+        TIMEOUT: 'The operation timed out.'
+    };
+    // #endregion
+    // #region Build User-Facing Response Message
+    /** Get localized responses for detected language, fallback to English */
+    const possibleResponses = responses[lang] || responses['en'] || {};
+    let responseMessage = '';
+    /** Handle duplicate entry errors (e.g., unique constraint violations) */
+    if (code === 'ER_DUP_ENTRY' || rawErrorMessage.includes('ER_DUP_ENTRY')) {
+        const noDupesof = prefs.noDupesAllowedof || [];
+        for (const field of noDupesof) {
+            if (rawErrorMessage.includes(field)) {
+                responseMessage = possibleResponses.dupes?.[field];
+                break;
+            }
+        }
+    }
+    /** Handle validation errors with per-field messages */
+    else if (code === 'VALIDATION_ERROR' && err.errors) {
+        for (const fieldError of err.errors) {
+            const fieldName = fieldError.param || fieldError.path;
+            if (possibleResponses.validation?.[fieldName]) {
+                responseMessage = possibleResponses.validation[fieldName];
+                break;
+            }
+        }
+    }
+    /** Fallback: use raw error message if no specific handler matched */
+    else {
+        responseMessage = rawErrorMessage;
+    }
+    /** Apply fallback logic for message resolution */
+    if (!responseMessage) {
+        // Try localized message by error code
+        if (possibleResponses[code]) {
+            responseMessage = possibleResponses[code];
+        }
+        // Try server default for 5xx errors
+        else if (statusCode >= 500 && serverDefaultMessages[code]) {
+            responseMessage = serverDefaultMessages[code];
+        }
+        // Final fallback: generic error message
+        else {
+            responseMessage = possibleResponses.general?.error || serverDefaultMessages['INTERNAL_SERVER_ERROR'];
+        }
+    }
+    // #endregion
+    // #region Error Classification (User vs Server)
+    /**
+     * Classify errors to determine whether to log details for maintainers.
+     * User-caused errors (4xx) are silenced; server errors (5xx) are logged.
+     */
+    const userCausedCodes = new Set([
+        'VALIDATION_ERROR',
+        'ER_DUP_ENTRY',
+        'BAD_REQUEST',
+        'UNAUTHORIZED',
+        'FORBIDDEN',
+        'NOT_FOUND',
+        'CONFLICT',
+        'METHOD_NOT_ALLOWED',
+        'NOT_ACCEPTABLE',
+        'UNSUPPORTED_MEDIA_TYPE',
+        'PAYLOAD_TOO_LARGE',
+        'UNPROCESSABLE_ENTITY',
+        'TOO_MANY_REQUESTS'
+    ]);
+    const isUserError = (statusCode >= 400 && statusCode < 500) || userCausedCodes.has(code);
+    // #endregion
+    // #region Maintainer Logging (Server Errors Only)
+    /** Extract route information for logging */
+    const routeInfo = `${req.method || ''} ${req.originalUrl || req.url || ''}`.trim();
+    const requestId = (req.id || req.requestId || '');
+    /** Log detailed, color-coded error report for maintainers (skip for user-caused errors) */
+    if (!isUserError) {
+        Coloredlog('===================== ERROR REPORT =====================', 'red');
+        // Timestamp
+        let exactTime = new Date().toISOString();
+        exactTime = exactTime.replace('T', ' ').replace('Z', '');
+        Coloredlog(`Time: ${exactTime}`, 'yellow');
+        // Request context
+        if (routeInfo)
+            Coloredlog(`Route: ${routeInfo}`, 'yellow');
+        if (requestId)
+            Coloredlog(`RequestId: ${requestId}`, 'yellow');
+        // Error details
+        Coloredlog(`Status: ${statusCode}`, 'magenta');
+        Coloredlog(`Code: ${code}`, 'magenta');
+        // Messages for comparison
+        Coloredlog(`UserMessage: ${responseMessage}`, 'cyan');
+        Coloredlog(`RawMessage: ${rawErrorMessage}`, 'white');
+        // Stack trace for debugging
+        Coloredlog('Stack:', 'gray');
+        Coloredlog(err && err.stack ? String(err.stack) : 'N/A', 'gray');
+        Coloredlog('========================================================', 'red');
+    }
+    // #endregion
+    // #region Send Response to Client
+    /** Return JSON response with error details (safe for client) */
+    res.status(statusCode).json({
+        status: 'error',
+        code: code,
+        message: responseMessage
+    });
+    // #endregion
+}

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+import coloredlog from "./functions/Colorlog";
+import errorHandler from "./functions/handleError";
+declare const _default: {
+    coloredlog: typeof coloredlog;
+    errorHandler: typeof errorHandler;
+    config: {
+        configure(options: {
+            responses: any;
+            prefs: any;
+        }): void;
+        getResponses(): any;
+        getPrefs(): any;
+        setMessage(lang: string, code: string, message: string): void;
+        getMessage(lang: string, code: string, fallback?: string): string | undefined;
+    };
+    configure: (options: {
+        responses: any;
+        prefs: any;
+    }) => void;
+    object: {
+        Keysamount: typeof import("./functions/ObjectKeys").Keysamount;
+        KeysInRange: typeof import("./functions/ObjectKeys").KeysInRange;
+        KeysInRangeDetailed: typeof import("./functions/ObjectKeys").KeysInRangeDetailed;
+        AllowedKeys: typeof import("./functions/ObjectKeys").AllowedKeys;
+    };
+};
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,UAAU,MAAM,sBAAsB,CAAC;AAC9C,OAAO,YAAY,MAAM,yBAAyB,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;AAKnD,wBAME"}

package/dist/index.js

@@ -0,0 +1,11 @@
+import coloredlog from "./functions/Colorlog";
+import errorHandler from "./functions/handleError";
+import config from "./functions/Config";
+import object from "./functions/ObjectKeys";
+export default {
+    coloredlog,
+    errorHandler,
+    config,
+    configure: config.configure,
+    object
+};

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@gerync/utils",
+  "version": "1.0.0",
+  "description": "A collection of utilities for any type of project, providing logging, error handling, configuration management, and object manipulation helpers.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "utilities",
+    "error-handling",
+    "logging",
+    "express",
+    "middleware",
+    "validation",
+    "configuration",
+    "i18n",
+    "object-manipulation",
+    "typescript",
+    "multi-language",
+    "utils",
+    "multilingual"
+  ],
+  "author": "gerync",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gerync/utils.git"
+  },
+  "bugs": {
+    "url": "https://github.com/gerync/utils/issues"
+  },
+  "homepage": "https://github.com/gerync/utils#readme",
+  "peerDependencies": {
+    "express": "^5.0.0"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^20.11.30",
+    "@types/express": "^4.17.21",
+    "express": "^5.2.1",
+    "typescript": "^5.6.3",
+    "vitest": "^1.6.0"
+  }
+}