hslid 0.1.0

package/README.md

@@ -0,0 +1,65 @@
+# hsl-id
+
+A collision-resistant ID generator that creates readable, color-based identifiers that convert to valid CSS `hsl()` / `hsla()` values.
+
+* URL-safe
+* Collisions are unlikely
+* Relatively performant
+* Converts to CSS
+* Configurable
+
+## Usage
+
+Normal: 
+```ts
+import hslid from "hsl-id";
+
+const id = hslid();
+
+console.log(id);
+// h18342.s04821.l06342.a00912.A9F
+```
+
+Custom:
+```ts
+import hslid from "hsl-id";
+
+const id = hslid({ //A vivid color example
+    separator: "-",
+    precision: 5,
+    salt: false,
+    clamp: {
+        h: { min: 0, max: 36000 },
+        s: { min: 6000, max: 10000 },
+        l: { min: 4500, max: 6500 },
+        a: { min: 10000, max: 10000 },
+    }
+});
+
+console.log(id);
+// h27442-s06468-l06167-a10000
+```
+
+## API
+```ts
+// defaults (all optional)
+hslid({
+    separator: '.', // String
+    precision: 5, // Number (Minimum: 3, pads each value of hsla to this length with leading zeroes.)
+    salt: true, // Boolean (Appends a random 3 character hexadecimal string to the end of the id.)
+    clamp: { // Object (Minimum and maximum values of range for each value of hsla.)
+        h: { min: 0, max: 36000 },
+        s: { min: 0, max: 10000 },
+        l: { min: 0, max: 10000 },
+        a: { min: 0, max: 10000 },
+    }
+})
+```
+
+## Why
+
+Mostly as a toy but should work for low-stakes applications or applications where security is not a priority, even though the collision probability is very low and generation is secure.
+
+## License
+
+MIT

package/dist/css/index.d.ts

@@ -0,0 +1,16 @@
+/**
+* Converts an hslid string to a CSS hsl/hsla string.
+*
+* @param {string} hslid - The hslid string to convert.
+* @param {boolean} [alpha=true] - Whether to include alpha in the output. (hsl vs hsla)
+* @returns {string|null} - The converted CSS string or null if the input is invalid.
+*
+* @example
+* hslToCSS("h01234.s01234.l01234.a01234.ABC");
+* // "hsla(12.34, 12.34%, 12.34%, 12.34%)"
+* @example
+* hslToCSS("h01234.s01234.l01234", false);
+* // "hsl(12.34, 12.34%, 12.34%)"
+* */
+declare const hslToCSS: (hslid: string, alpha?: boolean) => string | null;
+export { hslToCSS };

package/dist/css/index.js

@@ -0,0 +1,16 @@
+// src/css/index.ts
+var hslToCSS = (hslid, alpha = true) => {
+  const match = hslid.match(/^h(?<h>\d+).*?s(?<s>\d+).*?l(?<l>\d+).*?a(?<a>\d+)(?:.*?(?<salt>\w{3}))?$/);
+  if (!match?.groups)
+    return null;
+  const h = Number(match.groups.h) / 100;
+  const s = Number(match.groups.s) / 100;
+  const l = Number(match.groups.l) / 100;
+  const a = Number(match.groups.a) / 100;
+  if (!alpha)
+    return `hsl(${h}, ${s}%, ${l}%)`;
+  return `hsla(${h}, ${s}%, ${l}%, ${a})`;
+};
+export {
+  hslToCSS
+};

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+type ClampRange = {
+	min: number;
+	max: number;
+};
+type PartialClamp = {
+	h?: Partial<ClampRange>;
+	s?: Partial<ClampRange>;
+	l?: Partial<ClampRange>;
+	a?: Partial<ClampRange>;
+};
+type HslInputOptions = Partial<Omit<HslOptions, "clamp"> & {
+	clamp?: PartialClamp;
+}>;
+interface HslOptions {
+	separator: string;
+	salt: boolean;
+	precision: number;
+	clamp: {
+		h: ClampRange;
+		s: ClampRange;
+		l: ClampRange;
+		a: ClampRange;
+	};
+}
+declare const DEFAULT_OPTIONS: HslOptions;
+/**
+* Generates a random hsl id.
+*
+* @param {HslInputOptions} [options] - Options to generate the id.
+* @param {string} [options.separator="."] - The separator to use between the hsla values.
+* @param {boolean} [options.salt=true] - Whether to append a random salt to the end of the id.
+* @param {number} [options.precision=5] - The padded length of the generated id.
+* @param {PartialClamp} [options.clamp] - Custom clamp ranges (min/max) for each hsla value.
+*/
+declare const hslid: (options?: HslInputOptions) => string;
+export { hslid as default, PartialClamp, HslOptions, HslInputOptions, DEFAULT_OPTIONS, ClampRange };

package/dist/index.js

@@ -0,0 +1,73 @@
+// src/index.ts
+var SALT_DICT = "0123456789ABCDEF";
+var SALT_LOOKUP = new Array(16).fill("").map((_, i) => SALT_DICT[i]);
+var BUFFER_SIZE = 2048;
+var BUFFER = new Uint32Array(BUFFER_SIZE);
+var BUFFER_INDEX = BUFFER_SIZE;
+var MAX_RANGE = Math.pow(2, 32);
+var DEFAULT_CLAMP = {
+  h: { min: 0, max: 36000 },
+  s: { min: 0, max: 1e4 },
+  l: { min: 0, max: 1e4 },
+  a: { min: 0, max: 1e4 }
+};
+var DEFAULT_OPTIONS = {
+  clamp: structuredClone(DEFAULT_CLAMP),
+  precision: 5,
+  salt: true,
+  separator: "."
+};
+var mergeClamp = (clamp) => {
+  return {
+    h: { ...DEFAULT_CLAMP.h, ...clamp?.h },
+    s: { ...DEFAULT_CLAMP.s, ...clamp?.s },
+    l: { ...DEFAULT_CLAMP.l, ...clamp?.l },
+    a: { ...DEFAULT_CLAMP.a, ...clamp?.a }
+  };
+};
+var randomInt = (min, max) => {
+  const range = max - min + 1;
+  const limit = MAX_RANGE - MAX_RANGE % range;
+  while (true) {
+    if (BUFFER_INDEX >= BUFFER_SIZE) {
+      crypto.getRandomValues(BUFFER);
+      BUFFER_INDEX = 0;
+    }
+    const value = BUFFER[BUFFER_INDEX++];
+    if (value < limit) {
+      return min + value % range;
+    }
+  }
+};
+var generateSalt = () => {
+  if (BUFFER_INDEX >= 2048) {
+    crypto.getRandomValues(BUFFER);
+    BUFFER_INDEX = 0;
+  }
+  const val = BUFFER[BUFFER_INDEX++];
+  return SALT_LOOKUP[val & 15] + SALT_LOOKUP[val >> 4 & 15] + SALT_LOOKUP[val >> 8 & 15];
+};
+var hslid = (options) => {
+  const mergedOptions = {
+    ...DEFAULT_OPTIONS,
+    ...options,
+    clamp: mergeClamp(options?.clamp)
+  };
+  let h = randomInt(mergedOptions.clamp.h.min, mergedOptions.clamp.h.max).toString();
+  let s = randomInt(mergedOptions.clamp.s.min, mergedOptions.clamp.s.max).toString();
+  let l = randomInt(mergedOptions.clamp.l.min, mergedOptions.clamp.l.max).toString();
+  let a = randomInt(mergedOptions.clamp.a.min, mergedOptions.clamp.a.max).toString();
+  const width = mergedOptions.precision <= 3 ? 3 : mergedOptions.precision;
+  h = h.padStart(width, "0");
+  s = s.padStart(width, "0");
+  l = l.padStart(width, "0");
+  a = a.padStart(width, "0");
+  const salt = mergedOptions.salt ? `.${generateSalt()}` : "";
+  let sep = mergedOptions.separator;
+  return `h${h}${sep}s${s}${sep}l${l}${sep}a${a}${salt}`;
+};
+var src_default = hslid;
+export {
+  src_default as default,
+  DEFAULT_OPTIONS
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "hslid",
+  "description": "Securely generate a random id that converts to an hsla css color.",
+  "version": "0.1.0",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./css": {
+      "import": {
+        "types": "./dist/css/index.d.ts",
+        "default": "./dist/css/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "author": "JosephY (https://github.com/exoup)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/exoup/hsl-id.git"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "bunup": "^0.16.17"
+  },
+  "homepage": "https://github.com/exoup/hsl-id#readme",
+  "keywords": [
+    "random",
+    "id",
+    "number",
+    "generator",
+    "hsl",
+    "hsla"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "test": "bun test",
+    "build": "bunup"
+  }
+}