@kastov/uuid-color 0.0.1

package/.prettierrc

@@ -0,0 +1,21 @@
+{
+  "bracketSpacing": true,
+  "tabWidth": 4,
+  "printWidth": 100,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "overrides": [
+    {
+      "files": ["*.js", "*.jsx", "*.ts", "*.tsx"],
+      "options": {
+        "parser": "typescript"
+      }
+    },
+    {
+      "files": ["*.md", "*.json", "*.yaml", "*.yml"],
+      "options": {
+        "tabWidth": 2
+      }
+    }
+  ]
+}

package/README.md

@@ -0,0 +1,71 @@
+**uuid-color package on npm: https://www.npmjs.com/package/uuid-color**
+
+A lightweight package to deterministically generate unique and uniformly sampled colors from UUIDs.
+
+### How it works
+
+The RGB color space is represented by hexadecimal numbers in the 0x000000 to 0xffffff range. We use a simple modulo hash function (`% (0xffffff + 0x000001)` i.e. `% 0x100000`) to produce numbers in that range from the decimal representation of the UUID (a base 10 39-digit integer). We then extract the red, green, and blue components from the resulting hash (which represents a specific color in hexadecimal notation) using bit masks.
+
+### Limitations
+
+Since the color space is only 256^3 whereas the UUID space is much larger ([approximtely 5.3 x 10^36 possible UUIDs](https://www.uuidtools.com/what-is-uuid#overview)), it is impossible to create a complete bijection between the spaces, and so collisions in the generated color space can occur. This package does however guarantee that the color space is maximally utilized, assuming a uniform distribution of the input UUIDs within the UUID space.
+
+# Installation:
+
+```sh
+npm i uuid-color
+```
+
+# Usage
+
+```js
+import { v4 as uuidv4 } from "uuid";
+import { colorFromUuid } from "uuid-color";
+
+const myUuid = uuidv4();
+
+// returns a hex color code as a string "#rrggbb"
+const hexColor = colorFromUuid(myUuid);
+```
+
+[Live demo](https://codesandbox.io/s/uuid-color-usage-o0e4o)
+
+# Reference - v0.1.0
+
+## Table of contents
+
+### Interfaces
+
+- [Options](docs/dist/interfaces/Options.md)
+
+### Functions
+
+- [colorFromUuid](docs/dist/README.md#colorfromuuid)
+
+## Functions
+
+### colorFromUuid
+
+▸ **colorFromUuid**(`uuid`, `options?`): `string`
+
+Returns the generated color associated with the given uuid.
+
+**`throws`** [Error](https://developer.mozilla.org/en-US/docs/web/javascript/reference/global_objects/error)
+This exception is thrown if the input uuid string is not a valid UUID.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `uuid` | `string` | The uuid for which to generate a color |
+| `options` | [`Options`](docs/dist/interfaces/Options.md) | An optional object to configure the color generation, and attach callbacks that directly receive the generated color code or components in various formats |
+
+#### Returns
+
+`string`
+
+The generated color as a CSS `<color>` notation string
+
+#### Defined in
+
+[index.ts:81](https://github.com/loucadufault/uuid-color/blob/1d2a5c0/src/index.ts#L81)

package/lib/index.d.ts

@@ -0,0 +1,64 @@
+type SupportedColorNotations = 'hex' | 'rgb' | 'hsl';
+type Receivers = {
+    hex?: (hexString: string) => void;
+    rgb?: (red: number, green: number, blue: number, alpha?: number) => void;
+    hsl?: (hue: number, saturation: number, lightness: number, alpha?: number) => void;
+};
+export interface Options {
+    /**
+     * Determines whether to skip rounding the generated color components.
+     *
+     * @remarks
+     * Only applies when the specified format is `"hsl"`, as this is the only output format that involves a lossy conversion (from RGB model components).
+     *
+     * @defaultValue `false`
+     */
+    raw?: boolean;
+    /**
+     * Determines the alpha of the generated color as a number between 0 and 1. Passed through to the final generated color without any involvement in the generation process.
+     *
+     * @remarks
+     * Specifying any value (even if it is equal to or greater than 1) will cause the function to return the generated color as a notation string including the alpha component (see the alpha variants in {@link Options.format | Options.format}), and cause the alpha to be included in the parameter(s) of the call to the supplied {@link Receivers} value(s).
+     * Values are not validated, but are clamped to between 0 and 1.
+     *
+     * @defaultValue `1`
+     */
+    alpha?: number;
+    /**
+     * Determines the output format of the generated color.
+     *
+     * hex: #rrggbb[aa]
+     * rgb: rgb[a](R, G, B[, A])
+     * hsl: hsl[a](H, S, L[, A])
+     * @see { @link https://developer.mozilla.org/en-US/docs/Web/CSS/color_value | \<color\> }
+     *
+     * @remarks
+     * Colors are returned as strings in the CSS <color> data type hexadecimal or comma-separated functional notation corresponding to the specified format.
+     *
+     * @defaultValue `"hex"`
+     */
+    format?: SupportedColorNotations;
+    /**
+     * Attach callbacks to {@link SupportedColorNotations | supported color notations} as keys that will be called with the corresponding generated color components or code. Eliminates the need to parse the returned string if further manipulation is desired.
+     *
+     * @remarks
+     * Does not affect the return value of {@link colorFromUuid | the `colorFromUuid` function}.
+     *
+     * @see {@link Receivers | the Receivers type}
+     */
+    receivers?: Receivers;
+}
+/**
+ * Returns the generated color associated with the given uuid.
+ *
+ * @param uuid - The uuid for which to generate a color
+ * @param options - An optional object to configure the color generation, and attach callbacks that directly receive the generated color code or components in various formats
+ * @returns The generated color as a CSS `<color>` notation string
+ *
+ * @throws {@link https://developer.mozilla.org/en-US/docs/web/javascript/reference/global_objects/error | Error}
+ * This exception is thrown if the input uuid string is not a valid UUID.
+ *
+ * @public
+ */
+export declare function colorFromUuid(uuid: string, options?: Options): string;
+export {};

package/lib/index.js

@@ -0,0 +1,105 @@
+"use strict";
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.colorFromUuid = colorFromUuid;
+var convert = require("color-convert");
+var DEFAULT_COLOR_FORMAT = 'hex';
+var DEFAULT_IS_RAW = false;
+function uuidToBigInt(uuid) {
+    return BigInt('0x' + uuid.replace(/-/g, ''));
+}
+/**
+ * Returns the generated color associated with the given uuid.
+ *
+ * @param uuid - The uuid for which to generate a color
+ * @param options - An optional object to configure the color generation, and attach callbacks that directly receive the generated color code or components in various formats
+ * @returns The generated color as a CSS `<color>` notation string
+ *
+ * @throws {@link https://developer.mozilla.org/en-US/docs/web/javascript/reference/global_objects/error | Error}
+ * This exception is thrown if the input uuid string is not a valid UUID.
+ *
+ * @public
+ */
+function colorFromUuid(uuid, options) {
+    if (options === void 0) { options = {}; }
+    var encodedUuid = uuidToBigInt(uuid);
+    var colorCode = Number(encodedUuid % BigInt(0x1000000));
+    var red = colorCode >> 16;
+    var green = (colorCode >> 8) & 0xff;
+    var blue = colorCode & 0xff;
+    var receivers = {};
+    if (options.hasOwnProperty('receivers')) {
+        ['rgb', 'hsl', 'hex'].forEach(function (format) {
+            if (options.receivers.hasOwnProperty(format)) {
+                receivers[format] = options.receivers[format]; // link to callbacks
+            }
+        });
+    }
+    var isRaw = DEFAULT_IS_RAW;
+    if (options.hasOwnProperty('raw')) {
+        isRaw = options.raw;
+    }
+    var alpha;
+    if (options.hasOwnProperty('alpha')) {
+        alpha = Math.min(Math.max(options.alpha, 0), 1); // clamp to [0; 1]
+    }
+    if ('rgb' in receivers) {
+        if (alpha === undefined) {
+            receivers.rgb(red, green, blue);
+        }
+        else {
+            receivers.rgb(red, green, blue, alpha);
+        }
+    }
+    if ('hsl' in receivers) {
+        var hsl = isRaw
+            ? convert.default.rgb.hsl.raw(red, green, blue)
+            : convert.default.rgb.hsl(red, green, blue);
+        if (alpha === undefined) {
+            receivers.hsl.apply(receivers, hsl);
+        }
+        else {
+            receivers.hsl.apply(receivers, __spreadArray(__spreadArray([], hsl, true), [alpha], false));
+        }
+    }
+    if ('hex' in receivers) {
+        var hexColorCode = convert.default.rgb.hex(red, green, blue).toLowerCase();
+        if (alpha === undefined) {
+            receivers.hex(hexColorCode);
+        }
+        else {
+            var hexAlphaCode = Math.floor(alpha * 255).toString(16);
+            receivers.hex(hexColorCode + hexAlphaCode);
+        }
+    }
+    var format = DEFAULT_COLOR_FORMAT;
+    if (options.hasOwnProperty('format')) {
+        format = options.format;
+    }
+    switch (format) {
+        case 'rgb':
+            return alpha === undefined
+                ? "rgb(".concat(red, ", ").concat(green, ", ").concat(blue, ")")
+                : "rgb(".concat(red, ", ").concat(green, ", ").concat(blue, ", ").concat(alpha, ")");
+        case 'hsl':
+            var hsl = isRaw
+                ? convert.default.rgb.hsl.raw(red, green, blue)
+                : convert.default.rgb.hsl(red, green, blue);
+            return alpha === undefined
+                ? "hsl(".concat(hsl[0], ", ").concat(hsl[1], "%, ").concat(hsl[2], "%)")
+                : "hsl(".concat(hsl[0], ", ").concat(hsl[1], "%, ").concat(hsl[2], "%, ").concat(alpha, ")");
+        default: // don't error
+        case 'hex':
+            var hexColorCode = convert.default.rgb.hex(red, green, blue).toLowerCase();
+            var hexAlphaCode = Math.floor(alpha * 255).toString(16);
+            return alpha === undefined ? "#".concat(hexColorCode) : "#".concat(hexColorCode).concat(hexAlphaCode);
+    }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@kastov/uuid-color",
+  "version": "0.0.1",
+  "description": "A lightweight package to generate unique and uniformly sampled colors from UUIDs.",
+  "main": "lib/index.js",
+  "scripts": {
+    "build": "tsc",
+    "prepare": "rm -rf lib && NODE_ENV=production tsc"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kastov/uuid-color.git"
+  },
+  "keywords": [
+    "uuid",
+    "color",
+    "colour",
+    "unique",
+    "hash",
+    "uuid-v4"
+  ],
+  "author": "Louca Dufault",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/kastov/uuid-color/issues"
+  },
+  "homepage": "https://github.com/kastov/uuid-color#readme",
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "color-convert": "^3.1.3"
+  },
+  "sideEffects": false
+}