{"id":46833987,"url":"https://github.com/aminekun90/advanced-color-utils","last_synced_at":"2026-03-10T11:04:37.574Z","repository":{"id":250064413,"uuid":"833368311","full_name":"aminekun90/advanced-color-utils","owner":"aminekun90","description":"Unleash the full potential of color manipulation with the ColorUtils library! Designed for developers who need precise control over color processing 💄 ","archived":false,"fork":false,"pushed_at":"2025-12-10T23:04:04.000Z","size":192,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-11T11:14:45.533Z","etag":null,"topics":["chroma","color","color-diff","color-utils","library","manipulation"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aminekun90.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"Contributing.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["aminekun90"],"custom":"https://www.paypal.com/paypalme/aminebouzahar"}},"created_at":"2024-07-24T22:55:14.000Z","updated_at":"2025-12-10T23:01:38.000Z","dependencies_parsed_at":"2025-09-11T13:14:35.304Z","dependency_job_id":"35f5d67e-78ed-4d8a-9852-703f2cb4ca3f","html_url":"https://github.com/aminekun90/advanced-color-utils","commit_stats":null,"previous_names":["aminekun90/color-utils","aminekun90/advanced-color-utils"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/aminekun90/advanced-color-utils","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aminekun90%2Fadvanced-color-utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aminekun90%2Fadvanced-color-utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aminekun90%2Fadvanced-color-utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aminekun90%2Fadvanced-color-utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aminekun90","download_url":"https://codeload.github.com/aminekun90/advanced-color-utils/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aminekun90%2Fadvanced-color-utils/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30331646,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T05:25:20.737Z","status":"ssl_error","status_checked_at":"2026-03-10T05:25:17.430Z","response_time":106,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chroma","color","color-diff","color-utils","library","manipulation"],"created_at":"2026-03-10T11:04:37.037Z","updated_at":"2026-03-10T11:04:37.560Z","avatar_url":"https://github.com/aminekun90.png","language":"TypeScript","funding_links":["https://github.com/sponsors/aminekun90","https://www.paypal.com/paypalme/aminebouzahar"],"categories":[],"sub_categories":[],"readme":"# Advanced ColorUtils Library\n\n[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/aminekun90/advanced-color-utils/graphs/commit-activity) [![version number](https://img.shields.io/npm/v/advanced-color-utils?color=green\u0026label=version)](https://github.com/aminekun90/advanced-color-utils/releases) [![Actions Status](https://github.com/aminekun90/advanced-color-utils/workflows/Test/badge.svg)](https://github.com/aminekun90/advanced-color-utils/actions) [![License](https://img.shields.io/github/license/aminekun90/color-utils)](https://github.com/aminekun90/advanced-color-utils/blob/master/LICENSE)\n![node-current](https://img.shields.io/node/v/advanced-color-utils)\n[![Socket Badge](https://socket.dev/api/badge/npm/package/advanced-color-utils)](https://socket.dev/npm/package/advanced-color-utils)\n\nA TypeScript library for working with colors, providing functionality to find distinct colors from a list based on a similarity threshold.\n\n## Description\n\nUnleash the full potential of color manipulation with the ColorUtils library! Designed for developers who need precise control over color processing, this TypeScript library provides powerful tools to efficiently find and manipulate distinct colors from any color palette. Whether you're working on data visualization, graphic design, or user interface development, ColorUtils ensures your colors are perfectly balanced and aesthetically pleasing.\n\n## Key Features\n\n- Precision Color Conversion: Seamlessly convert between HEX and LAB color spaces to ensure accurate color representation and manipulation.\n- Distinct Color Extraction: Effortlessly extract a specified number of distinct colors from any list, using customizable similarity thresholds to ensure the perfect balance.\n- Performance Optimization: Optimized for both memory and time efficiency, making it suitable for handling large datasets with millions of colors.\n- TypeScript Support: Fully typed for enhanced developer experience and robust error checking.\n\n## Why Choose ColorUtils?\n\n- High Efficiency: Designed to handle massive color datasets with ease, providing rapid results even with millions of colors.\n- Customizability: Fine-tune color similarity thresholds to match your specific needs and achieve the perfect color harmony.\n- Reliability: Built with rigorous testing and performance benchmarks to ensure consistent and reliable results.\n- Ease of Use: Intuitive API design, comprehensive documentation, and seamless integration into any TypeScript project.\n- Elevate your projects with the precision and performance of the ColorUtils library, your ultimate tool for advanced color processing and manipulation.\n-\n\n## Requirements\n\n- Node.js 22+\n- OS (Windows, Linux, macOS)\n- Not tested on Docker containers but should work fine (no network usage).\n\n## Installation\n\nInstall the library using npm:\n\n```sh\nnpm install advanced-color-utils\n# or prefered way\nyarn add advanced-color-utils\n```\n\n## Usage\n\n### Importing the Library\n\nYou can import the ColorUtils class from the library as follows:\n\n ```typescript\nimport ColorUtils from \"advanced-color-utils\";\n ```\n\n### Methods\n\n`getDistinctColors`\n\nFinds a specified number of distinct colors from a list based on a similarity threshold.\n\n**- Parameters:**\n\n`hexColors` (string[]): The list of hex color strings (e.g., `['#ff0000', '#00ff00']`).\n\n`numColors` (number): The number of distinct colors to retrieve.\n\n`threshold` (number): The threshold for color similarity (lower values mean more similar).\n\n**- Returns:**\n\n(string[]): The list of distinct hex color strings.\n\n**- Example:**\n\n```typescript\nconst colors = ['#ff0000', '#00ff00', '#0000ff', '#ff00ff'];\nconst numColorsToRetrieve = 2;\nconst threshold = 20;\n\nconst distinctColors = ColorUtils.getDistinctColors(colors, numColorsToRetrieve, threshold);\nconsole.log(distinctColors); // Output: ['#ff0000', '#00ff00']\n```\n\n`labToHex`\n\nConverts a LAB color to a hex color string.\n\n**- Parameters:**\n\n`lab` (LabColor): The LAB color object.\n\n**- Returns:**\n\n(string): The hex color string.\n\n**- Example:**\n\n```typescript\nconst lab = { L: 53.23288, a: 80.10933, b: 67.22006 };\nconst hex = ColorUtils.labToHex(lab);\nconsole.log(hex); // Output: '#ff0000'\n```\n\n`hexToLab`\n\nConverts a hex color to a LAB color object.\n\n**- Parameters:**\n\n`hex` (string): The hex color string (e.g., '#ff0000').\n\n**- Returns:**\n\n(LabColor): The LAB color object.\n\n**- Example:**\n\n```typescript\nconst hex = '#ff0000';\nconst lab = ColorUtils.hexToLab(hex);\nconsole.log(lab); // Output: { L: 53.23288, a: 80.10933, b: 67.22006 }\n```\n\n`rgbToHex`\n\nConverts an RGB color to a hex color string.\n\n**- Parameters:**\n\n`rgb` (RGBColor): The RGB color object.\n\n**- Returns:**\n\n(string): The hex color string.\n\n**- Example:**\n\n```typescript\nconst rgb = { R: 255, G: 0, B: 0 };\nconst hex = ColorUtils.rgbToHex(rgb);\nconsole.log(hex); // Output: '#ff0000'\n```\n\n`hexToRgb`\n\nConverts a hex color to an RGB color object.\n\n**- Parameters:**\n\n`hex` (string): The hex color string (e.g., '#ff0000').\n\n**- Returns:**\n\n(RGBColor): The RGB color object.\n**- Example:**\n\n```typescript\nconst hex = '#ff0000';\nconst rgb = ColorUtils.hexToRgb(hex);\nconsole.log(rgb); // Output: { R: 255, G: 0, B: 0 }\n```\n\n`generateColorPalette`\n\nGenerates a color palette based on a given hex color and the desired number of colors.\n\n**- Parameters:**\n\n`hex` (string): The hex color string (e.g., '#ff0000').\nnumColors (number): The number of colors in the palette.\n\n**- Returns:**\n\n(string[]): The array of hex color strings in the palette.\n\n**- Example:**\n\n```typescript\nconst palette = ColorUtils.generateComplementaryPalette('#ff0000', 5);\nconsole.log(palette); // Output: ['#ff0000', '#ff3333', '#ff6666', '#ff9999', '#ffcccc']\n```\n\n`getComplementaryColor`\n\nGenerates a complementary color for a given hex color.\n\n**- Parameters:**\n\n`hex` (string): The hex color string (e.g., '#ff0000').\n\n**- Returns:**\n\n(string): The complementary hex color string.\n\n**- Example:**\n\n```typescript\nconst complementaryColor = ColorUtils.getComplementaryColor('#ff0000');\nconsole.log(complementaryColor); // Output: '#00ffff'\n```\n\n`generateShades`\n\nGenerates a list of shades from a base color.\n\n**- Parameters:**\n\n`hex` (string): The base hex color string (e.g., '#ff0000').\n\n`numShades` (number): The number of shades to generate.\n\n**- Returns:**\n\n(string[]) An array of hex color strings representing the shades.\n\n**- Example:**\n\n```typescript\nconst shades = ColorUtils.generateShades('#ff0000', 5);\nconsole.log(shades); // Output: ['#ff0000', '#bb1909', '#7a1b0c', '#3f1508', '#000000']\n```\n\n`generateTints`\n\nGenerates a list of tints from a base color.\n\n**- Parameters:**\n\n`hex` (string): The base hex color string (e.g., '#ff0000').\n\n`numTints` (number): The number of tints to generate.\n\n**- Returns:**\n\n(string[]) An array of hex color strings representing the tints.\n\n**- Example:**\n\n```typescript\nconst tints = ColorUtils.generateTints('#ff0000', 5);\nconsole.log(tints); // Output: ['#ff0000', '#ff4040', '#ff8080', '#ffbfbf', '#ffffff']\n```\n\n`blendColors`\n\nBlends two hex colors together.\n\n**- Parameters:**\n\n`color1` (string): The first hex color string.\n\n`color2` (string): The second hex color string.\n\n`ratio` (number): The ratio of blending (0 to 1). 0 means full color1, 1 means full color2.\n\n`colorSpace` (InterpolationMode): The color space to use for blending (default is 'lab').\n\nPossible values for `colorSpace` are `\"rgb\" | \"hsl\" | \"hsv\" | \"hsi\" | \"lab\" | \"oklab\" | \"lch\" | \"oklch\" | \"hcl\" | \"lrgb\"`\n\n**- Returns:**\n\n(string) The blended hex color string.\n\nExample:\n\n```typescript\nconst blendedColor = ColorUtils.blendColors('#ff0000', '#0000ff', 0.5, 'lab');\nconsole.log(blendedColor); // Output: '#b400b4'\n```\n\n`hexToHsl`\n\nConverts a hex color string to an HSL object.\n\n**- Parameters:**\n\n`hex` (string): The hex color string (e.g., '#ff0000').\n\n**- Returns:**\n\n(HSLColor) The HSL color object.\n\n**- Example:**\n\n```typescript\nconst hsl = ColorUtils.hexToHsl('#ff0000');\nconsole.log(hsl); // Output: { h: 0, s: 100, l: 50 }\n\n```\n\n`getContrastRatio`\n\nCalculates the contrast ratio between two hex colors.\n\n**- Parameters:**\n\n`color1` (string): The first hex color string.\n\n`color2` (string): The second hex color string.\n\n**- Returns:**\n\n (number) The contrast ratio.\n\n**- Example:**\n\n```typescript\nconst ratio = ColorUtils.getContrastRatio('#ff0000', '#0000ff');\nconsole.log(ratio); // Output: 4.5\n\n```\n\n`generateRandomColor`\n\nGenerates a random hex color.\n\n**- Returns:**\n(string) The random hex color string.\n\n**- Example:**\n\n```typescript\nconst randomColor = ColorUtils.generateRandomColor();\nconsole.log(randomColor); // Output: e.g., '#a1b2c3'\n```\n\n`generateAnalogousColors`\n\nGenerates a list of analogous colors based on a base color.\n\nParameters:\n\n`hex` (string): The base hex color string (e.g., '#ff0000').\n\n`numColors` (number): The number of analogous colors to generate.\n\n**- Returns:**\n\n(string[]) An array of hex color strings representing the analogous colors.\n\n**- Example:**\n\n```typescript\nconst analogousColors = ColorUtils.generateAnalogousColors('#ff0000', 5);\nconsole.log(analogousColors); // Output: ['#ff0000', '#ff3333', '#ff6666', '#ff9999', '#ffcccc']\n```\n\n## License\n\nThis library is licensed under the [MIT License](https://github.com/aminekun90/advanced-color-utils?tab=MIT-1-ov-file#readme).\n\nFeel free to contribute or report issues via the [GitHub repository](https://github.com/aminekun90/advanced-color-utils).\n\n## Support me :coffee:\n\n[![PayPal](https://img.shields.io/badge/PayPal-00457C?style=for-the-badge\u0026logo=paypal\u0026logoColor=white)](https://www.paypal.com/paypalme/aminebouzahar)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faminekun90%2Fadvanced-color-utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faminekun90%2Fadvanced-color-utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faminekun90%2Fadvanced-color-utils/lists"}