@kastov/uuid-color 0.0.2 → 0.1.0

package/lib/index.d.ts

@@ -42,7 +42,7 @@ export interface Options {
      * 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}.
+     * Does not affect the return value of the color generation functions.
      *
      * @see {@link Receivers | the Receivers type}
      */
@@ -61,4 +61,28 @@ export interface Options {
  * @public
  */
 export declare function colorFromUuid(uuid: string, options?: Options): string;
+/**
+ * Returns the generated color associated with the given numeric id.
+ *
+ * @remarks
+ * Unlike {@link colorFromUuid | colorFromUuid}, whose input bits are already uniformly
+ * distributed, numeric ids are typically sequential. The id is therefore run through a
+ * SplitMix64 bit-mixer so that consecutive ids (e.g. `1`, `2`, `3`) map to well-separated,
+ * visually distinct colors instead of near-identical ones. The mapping is deterministic:
+ * the same id always yields the same color.
+ *
+ * The id must be a non-negative integer. `number` inputs are subject to the usual
+ * `Number.MAX_SAFE_INTEGER` limit; pass a `bigint` for larger ids.
+ *
+ * @param id - The numeric id (a `number` or `bigint`) 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 id is not a non-negative integer.
+ *
+ * @public
+ */
+export declare function colorFromId(id: number | bigint, options?: Options): string;
 export {};
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,KAAK,uBAAuB,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;AAErD,KAAK,SAAS,GAAG;IACb,GAAG,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACzE,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CACtF,CAAC;AAEF,MAAM,WAAW,OAAO;IACpB;;;;;;;OAOG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;IAEd;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,uBAAuB,CAAC;IAEjC;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;CACzB;AA4FD;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,OAAY,GAAG,MAAM,CAEzE;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,GAAE,OAAY,GAAG,MAAM,CAe9E"}

package/lib/index.js

@@ -1,57 +1,43 @@
-"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;
+import convert from 'color-convert';
+const DEFAULT_COLOR_FORMAT = 'hex';
+const DEFAULT_IS_RAW = false;
+const U64_MASK = 0xffffffffffffffffn;
+const MIX_C1 = 0xbf58476d1ce4e5b9n;
+const MIX_C2 = 0x94d049bb133111ebn;
 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
+ * Mixes a non-negative integer into a well-distributed 64-bit value using the
+ * SplitMix64 finalizer, so that sequential ids (1, 2, 3, …) map to colors that
+ * are far apart rather than nearly identical.
  */
-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) {
+function mixId(id) {
+    let z = id & U64_MASK;
+    z = ((z ^ (z >> 30n)) * MIX_C1) & U64_MASK;
+    z = ((z ^ (z >> 27n)) * MIX_C2) & U64_MASK;
+    z = z ^ (z >> 31n);
+    return z & U64_MASK;
+}
+/** Converts a clamped alpha value in [0; 1] to its hexadecimal channel representation. */
+function alphaToHex(alpha) {
+    return Math.floor(alpha * 255).toString(16);
+}
+/**
+ * Returns the generated color associated with the given encoded value by taking
+ * its lowest 24 bits as the RGB channels and formatting them per {@link Options}.
+ */
+function colorFromBigInt(encoded, options) {
+    const colorCode = Number(encoded % 0x1000000n);
+    const red = colorCode >> 16;
+    const green = (colorCode >> 8) & 0xff;
+    const blue = colorCode & 0xff;
+    const isRaw = options.raw ?? DEFAULT_IS_RAW;
+    // clamp to [0; 1]
+    const alpha = options.alpha === undefined ? undefined : Math.min(Math.max(options.alpha, 0), 1);
+    const toHsl = () => isRaw ? convert.rgb.hsl.raw(red, green, blue) : convert.rgb.hsl(red, green, blue);
+    const receivers = options.receivers;
+    if (receivers?.rgb) {
         if (alpha === undefined) {
             receivers.rgb(red, green, blue);
         }
@@ -59,47 +45,89 @@ function colorFromUuid(uuid, options) {
             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 (receivers?.hsl) {
+        const [hue, saturation, lightness] = toHsl();
         if (alpha === undefined) {
-            receivers.hex(hexColorCode);
+            receivers.hsl(hue, saturation, lightness);
         }
         else {
-            var hexAlphaCode = Math.floor(alpha * 255).toString(16);
-            receivers.hex(hexColorCode + hexAlphaCode);
+            receivers.hsl(hue, saturation, lightness, alpha);
         }
     }
-    var format = DEFAULT_COLOR_FORMAT;
-    if (options.hasOwnProperty('format')) {
-        format = options.format;
+    if (receivers?.hex) {
+        const hexColorCode = convert.rgb.hex(red, green, blue).toLowerCase();
+        receivers.hex(alpha === undefined ? hexColorCode : hexColorCode + alphaToHex(alpha));
     }
+    const format = options.format ?? DEFAULT_COLOR_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);
+                ? `rgb(${red}, ${green}, ${blue})`
+                : `rgb(${red}, ${green}, ${blue}, ${alpha})`;
+        case 'hsl': {
+            const [hue, saturation, lightness] = toHsl();
             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
+                ? `hsl(${hue}, ${saturation}%, ${lightness}%)`
+                : `hsl(${hue}, ${saturation}%, ${lightness}%, ${alpha})`;
+        }
         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);
+        default: {
+            const hexColorCode = convert.rgb.hex(red, green, blue).toLowerCase();
+            return alpha === undefined ? `#${hexColorCode}` : `#${hexColorCode}${alphaToHex(alpha)}`;
+        }
+    }
+}
+/**
+ * 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 function colorFromUuid(uuid, options = {}) {
+    return colorFromBigInt(uuidToBigInt(uuid), options);
+}
+/**
+ * Returns the generated color associated with the given numeric id.
+ *
+ * @remarks
+ * Unlike {@link colorFromUuid | colorFromUuid}, whose input bits are already uniformly
+ * distributed, numeric ids are typically sequential. The id is therefore run through a
+ * SplitMix64 bit-mixer so that consecutive ids (e.g. `1`, `2`, `3`) map to well-separated,
+ * visually distinct colors instead of near-identical ones. The mapping is deterministic:
+ * the same id always yields the same color.
+ *
+ * The id must be a non-negative integer. `number` inputs are subject to the usual
+ * `Number.MAX_SAFE_INTEGER` limit; pass a `bigint` for larger ids.
+ *
+ * @param id - The numeric id (a `number` or `bigint`) 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 id is not a non-negative integer.
+ *
+ * @public
+ */
+export function colorFromId(id, options = {}) {
+    let encoded;
+    if (typeof id === 'bigint') {
+        encoded = id;
+    }
+    else {
+        if (!Number.isInteger(id)) {
+            throw new Error(`Invalid id: expected an integer, received ${id}`);
+        }
+        encoded = BigInt(id);
+    }
+    if (encoded < 0n) {
+        throw new Error(`Invalid id: expected a non-negative integer, received ${id}`);
     }
+    return colorFromBigInt(mixId(encoded), options);
 }
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

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

package/package.json

@@ -1,24 +1,32 @@
 {
   "name": "@kastov/uuid-color",
-  "version": "0.0.2",
-  "description": "A lightweight package to generate unique and uniformly sampled colors from UUIDs.",
-  "main": "lib/index.js",
+  "version": "0.1.0",
+  "description": "A lightweight package to generate unique and uniformly sampled colors from UUIDs and numeric ids.",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
   "scripts": {
     "build": "tsc",
-    "prepare": "rm -rf lib && NODE_ENV=production tsc"
+    "clean": "rm -rf lib",
+    "prepare": "npm run clean && 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": {
@@ -32,4 +40,4 @@
     "color-convert": "^3.1.3"
   },
   "sideEffects": false
-}
+}

package/src/index.ts

@@ -0,0 +1,202 @@
+import convert from 'color-convert';
+
+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 the color generation functions.
+     *
+     * @see {@link Receivers | the Receivers type}
+     */
+    receivers?: Receivers;
+}
+
+const DEFAULT_COLOR_FORMAT: SupportedColorNotations = 'hex';
+const DEFAULT_IS_RAW = false;
+
+const U64_MASK = 0xffffffffffffffffn;
+const MIX_C1 = 0xbf58476d1ce4e5b9n;
+const MIX_C2 = 0x94d049bb133111ebn;
+
+function uuidToBigInt(uuid: string): bigint {
+    return BigInt('0x' + uuid.replace(/-/g, ''));
+}
+
+/**
+ * Mixes a non-negative integer into a well-distributed 64-bit value using the
+ * SplitMix64 finalizer, so that sequential ids (1, 2, 3, …) map to colors that
+ * are far apart rather than nearly identical.
+ */
+function mixId(id: bigint): bigint {
+    let z = id & U64_MASK;
+    z = ((z ^ (z >> 30n)) * MIX_C1) & U64_MASK;
+    z = ((z ^ (z >> 27n)) * MIX_C2) & U64_MASK;
+    z = z ^ (z >> 31n);
+    return z & U64_MASK;
+}
+
+/** Converts a clamped alpha value in [0; 1] to its hexadecimal channel representation. */
+function alphaToHex(alpha: number): string {
+    return Math.floor(alpha * 255).toString(16);
+}
+
+/**
+ * Returns the generated color associated with the given encoded value by taking
+ * its lowest 24 bits as the RGB channels and formatting them per {@link Options}.
+ */
+function colorFromBigInt(encoded: bigint, options: Options): string {
+    const colorCode = Number(encoded % 0x1000000n);
+    const red = colorCode >> 16;
+    const green = (colorCode >> 8) & 0xff;
+    const blue = colorCode & 0xff;
+
+    const isRaw = options.raw ?? DEFAULT_IS_RAW;
+
+    // clamp to [0; 1]
+    const alpha =
+        options.alpha === undefined ? undefined : Math.min(Math.max(options.alpha, 0), 1);
+
+    const toHsl = () =>
+        isRaw ? convert.rgb.hsl.raw(red, green, blue) : convert.rgb.hsl(red, green, blue);
+
+    const receivers = options.receivers;
+    if (receivers?.rgb) {
+        if (alpha === undefined) {
+            receivers.rgb(red, green, blue);
+        } else {
+            receivers.rgb(red, green, blue, alpha);
+        }
+    }
+    if (receivers?.hsl) {
+        const [hue, saturation, lightness] = toHsl();
+        if (alpha === undefined) {
+            receivers.hsl(hue, saturation, lightness);
+        } else {
+            receivers.hsl(hue, saturation, lightness, alpha);
+        }
+    }
+    if (receivers?.hex) {
+        const hexColorCode = convert.rgb.hex(red, green, blue).toLowerCase();
+        receivers.hex(alpha === undefined ? hexColorCode : hexColorCode + alphaToHex(alpha));
+    }
+
+    const format = options.format ?? DEFAULT_COLOR_FORMAT;
+
+    switch (format) {
+        case 'rgb':
+            return alpha === undefined
+                ? `rgb(${red}, ${green}, ${blue})`
+                : `rgb(${red}, ${green}, ${blue}, ${alpha})`;
+        case 'hsl': {
+            const [hue, saturation, lightness] = toHsl();
+            return alpha === undefined
+                ? `hsl(${hue}, ${saturation}%, ${lightness}%)`
+                : `hsl(${hue}, ${saturation}%, ${lightness}%, ${alpha})`;
+        }
+        case 'hex':
+        default: {
+            const hexColorCode = convert.rgb.hex(red, green, blue).toLowerCase();
+            return alpha === undefined ? `#${hexColorCode}` : `#${hexColorCode}${alphaToHex(alpha)}`;
+        }
+    }
+}
+
+/**
+ * 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 function colorFromUuid(uuid: string, options: Options = {}): string {
+    return colorFromBigInt(uuidToBigInt(uuid), options);
+}
+
+/**
+ * Returns the generated color associated with the given numeric id.
+ *
+ * @remarks
+ * Unlike {@link colorFromUuid | colorFromUuid}, whose input bits are already uniformly
+ * distributed, numeric ids are typically sequential. The id is therefore run through a
+ * SplitMix64 bit-mixer so that consecutive ids (e.g. `1`, `2`, `3`) map to well-separated,
+ * visually distinct colors instead of near-identical ones. The mapping is deterministic:
+ * the same id always yields the same color.
+ *
+ * The id must be a non-negative integer. `number` inputs are subject to the usual
+ * `Number.MAX_SAFE_INTEGER` limit; pass a `bigint` for larger ids.
+ *
+ * @param id - The numeric id (a `number` or `bigint`) 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 id is not a non-negative integer.
+ *
+ * @public
+ */
+export function colorFromId(id: number | bigint, options: Options = {}): string {
+    let encoded: bigint;
+    if (typeof id === 'bigint') {
+        encoded = id;
+    } else {
+        if (!Number.isInteger(id)) {
+            throw new Error(`Invalid id: expected an integer, received ${id}`);
+        }
+        encoded = BigInt(id);
+    }
+    if (encoded < 0n) {
+        throw new Error(`Invalid id: expected a non-negative integer, received ${id}`);
+    }
+
+    return colorFromBigInt(mixId(encoded), options);
+}

package/.prettierrc

@@ -1,21 +0,0 @@
-{
-  "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
-      }
-    }
-  ]
-}