feat: deprecate toRGB (for set()) and fromRGB (for fromValues)

Closes #21
pex-gl · Feb 5, 2024 · 06cc1e2 · 06cc1e2
1 parent b71c0b4
commit 06cc1e2
Show file tree

Hide file tree

Showing 7 changed files with 113 additions and 100 deletions.
diff --git a/README.md b/README.md
@@ -91,6 +91,9 @@ API naming follows the following rules:
 <dt><a href="#set">set(color, color2)</a> ⇒ <code><a href="#color">color</a></code></dt>
 <dd><p>Sets a color to another color.</p>
 </dd>
+<dt><a href="#fromValues">fromValues(color, r, g, b, [a])</a> ⇒ <code><a href="#color">color</a></code></dt>
+<dd><p>Updates a color based on r, g, b, [a] values.</p>
+</dd>
 <dt><a href="#toCSSRGB">toCSSRGB(color, [precision])</a> ⇒ <code><a href="#css">css</a></code></dt>
 <dd><p>Returns a rgb CSS string representation of a given color.</p>
 </dd>
@@ -178,12 +181,6 @@ API naming follows the following rules:
 <dt><a href="#toOklab">toOklab(color, out)</a> ⇒ <code><a href="#oklab">oklab</a></code></dt>
 <dd><p>Returns an Oklab representation of a given color.</p>
 </dd>
-<dt><a href="#fromRGB">fromRGB(color, r, g, b, [a])</a> ⇒ <code><a href="#color">color</a></code></dt>
-<dd><p>Updates a color based on r, g, b, a values.</p>
-</dd>
-<dt><a href="#toRGB">toRGB(color, out)</a> ⇒ <code><a href="#color">color</a></code></dt>
-<dd><p>Returns a copy of a RGB color.</p>
-</dd>
 <dt><a href="#fromXYZ">fromXYZ(color, x, y, z, a)</a> ⇒ <code><a href="#color">color</a></code></dt>
 <dd><p>Updates a color based on XYZ values and alpha.</p>
 </dd>
@@ -356,6 +353,22 @@ Sets a color to another color.
 | color  | [<code>color</code>](#color) |
 | color2 | [<code>color</code>](#color) |
 
+<a name="fromValues"></a>
+
+## fromValues(color, r, g, b, [a]) ⇒ [<code>color</code>](#color)
+
+Updates a color based on r, g, b, [a] values.
+
+**Kind**: global function
+
+| Param | Type                         |
+| ----- | ---------------------------- |
+| color | [<code>color</code>](#color) |
+| r     | <code>number</code>          |
+| g     | <code>number</code>          |
+| b     | <code>number</code>          |
+| [a]   | <code>number</code>          |
+
 <a name="toCSSRGB"></a>
 
 ## toCSSRGB(color, [precision]) ⇒ [<code>css</code>](#css)
@@ -768,35 +781,6 @@ Returns an Oklab representation of a given color.
 | color | [<code>color</code>](#color) |
 | out   | <code>Array</code>           |
 
-<a name="fromRGB"></a>
-
-## fromRGB(color, r, g, b, [a]) ⇒ [<code>color</code>](#color)
-
-Updates a color based on r, g, b, a values.
-
-**Kind**: global function
-
-| Param | Type                         |
-| ----- | ---------------------------- |
-| color | [<code>color</code>](#color) |
-| r     | <code>number</code>          |
-| g     | <code>number</code>          |
-| b     | <code>number</code>          |
-| [a]   | <code>number</code>          |
-
-<a name="toRGB"></a>
-
-## toRGB(color, out) ⇒ [<code>color</code>](#color)
-
-Returns a copy of a RGB color.
-
-**Kind**: global function
-
-| Param | Type                         |
-| ----- | ---------------------------- |
-| color | [<code>color</code>](#color) |
-| out   | <code>Array</code>           |
-
 <a name="fromXYZ"></a>
 
 ## fromXYZ(color, x, y, z, a) ⇒ [<code>color</code>](#color)

diff --git a/color.js b/color.js
@@ -1,3 +1,4 @@
+import { setAlpha } from "./utils.js";
 /**
  * @typedef {number[]} color An array of 3 (RGB) or 4 (A) values.
  *
@@ -35,6 +36,39 @@ export function set(color, color2) {
   color[0] = color2[0];
   color[1] = color2[1];
   color[2] = color2[2];
-  if (color2[3] !== undefined) color[3] = color2[3];
-  return color;
+  return setAlpha(color, color2[3]);
+}
+
+/**
+ * Updates a color based on r, g, b, [a] values.
+ * @param {import("./color.js").color} color
+ * @param {number} r
+ * @param {number} g
+ * @param {number} b
+ * @param {number} [a]
+ * @returns {import("./color.js").color}
+ */
+export function fromValues(color, r, g, b, a) {
+  color[0] = r;
+  color[1] = g;
+  color[2] = b;
+  return setAlpha(color, a);
+}
+
+/**
+ * @deprecated Use "fromValues()".
+ * @ignore
+ */
+export function fromRGB(color, r, g, b, a) {
+  console.error(`"fromRGB()" deprecated. Use "fromValues()".`);
+  return fromValues(color, r, g, b, a);
+}
+
+/**
+ * @deprecated Use "set()".
+ * @ignore
+ */
+export function toRGB(color, out = []) {
+  console.error(`"toRGB()" deprecated. Use "set()".`);
+  return set(out, color);
 }
diff --git a/index.js b/index.js
@@ -1,6 +1,5 @@
 export * from "./color.js";
 
-export * from "./rgb.js";
 export * from "./bytes.js";
 export * from "./linear.js";
 

diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -46,7 +46,7 @@
     "test:watch": "node --test --watch test"
   },
   "engines": {
-    "node": ">=18.0.0",
-    "npm": ">=8.6.0"
+    "node": ">=20.0.0",
+    "npm": ">=9.6.4"
   }
 }
diff --git a/rgb.js b/rgb.js
diff --git a/test/index.js b/test/index.js
@@ -40,12 +40,14 @@ describe("copy()", () => {
 describe("set()", () => {
   it("should set a color", () => {
     deepEqual(color.set(TEMP_VEC3, [0.1, 0.2, 0.3]), [0.1, 0.2, 0.3]);
+    deepEqual(color.toRGB([0.1, 0.2, 0.3]), [0.1, 0.2, 0.3]);
   });
   it("should set a color with supplied alpha", () => {
     deepEqual(
       color.set(color.create(), [0.1, 0.2, 0.3, 0.4]),
       [0.1, 0.2, 0.3, 0.4],
     );
+    deepEqual(color.toRGB([0.1, 0.2, 0.3, 0.4]), [0.1, 0.2, 0.3, 0.4]);
   });
   it("should set a color and keep the color alpha", () => {
     deepEqual(color.set(color.create(), [0.1, 0.2, 0.3]), [
@@ -57,34 +59,34 @@ describe("set()", () => {
   });
 });
 
-describe("RGB", () => {
-  describe("from", () => {
-    it("should set a color", () => {
-      deepEqual(color.fromRGB(TEMP_VEC3, 0.1, 0.2, 0.3), [0.1, 0.2, 0.3]);
-    });
-    it("should set a color with supplied alpha", () => {
-      deepEqual(
-        color.fromRGB(color.create(), 0.1, 0.2, 0.3, 0.4),
-        [0.1, 0.2, 0.3, 0.4],
-      );
-    });
-    it("should set a color and keep the color alpha", () => {
-      deepEqual(color.fromRGB(color.create(), 0.1, 0.2, 0.3), [
-        0.1,
-        0.2,
-        0.3,
-        DEFAULT_ALPHA,
-      ]);
-    });
+describe("fromValues", () => {
+  it("should set a color", () => {
+    deepEqual(color.fromValues(TEMP_VEC3, 0.1, 0.2, 0.3), [0.1, 0.2, 0.3]);
+    deepEqual(color.fromRGB(TEMP_VEC3, 0.1, 0.2, 0.3), [0.1, 0.2, 0.3]);
   });
-
-  describe("to", () => {
-    it("should return a color copy with alpha from a color with supplied alpha", () => {
-      deepEqual(color.toRGB([0.1, 0.2, 0.3, 0.4]), [0.1, 0.2, 0.3, 0.4]);
-    });
-    it("should return a color copy from a color", () => {
-      deepEqual(color.toRGB([0.1, 0.2, 0.3]), [0.1, 0.2, 0.3]);
-    });
+  it("should set a color with supplied alpha", () => {
+    deepEqual(
+      color.fromValues(color.create(), 0.1, 0.2, 0.3, 0.4),
+      [0.1, 0.2, 0.3, 0.4],
+    );
+    deepEqual(
+      color.fromRGB(color.create(), 0.1, 0.2, 0.3, 0.4),
+      [0.1, 0.2, 0.3, 0.4],
+    );
+  });
+  it("should set a color and keep the color alpha", () => {
+    deepEqual(color.fromValues(color.create(), 0.1, 0.2, 0.3), [
+      0.1,
+      0.2,
+      0.3,
+      DEFAULT_ALPHA,
+    ]);
+    deepEqual(color.fromRGB(color.create(), 0.1, 0.2, 0.3), [
+      0.1,
+      0.2,
+      0.3,
+      DEFAULT_ALPHA,
+    ]);
   });
 });
 
@@ -96,6 +98,11 @@ describe("Bytes", () => {
         100 / 255,
         125 / 255,
       ]);
+      deepEqual(color.fromRGBBytes(TEMP_VEC3, [222, 100, 125]), [
+        222 / 255,
+        100 / 255,
+        125 / 255,
+      ]);
     });
     it("should set a color from a Bytes array with supplied alpha", () => {
       deepEqual(color.fromBytes(color.create(), [222, 100, 125, 23]), [
@@ -104,6 +111,12 @@ describe("Bytes", () => {
         125 / 255,
         23 / 255,
       ]);
+      deepEqual(color.fromRGBBytes(color.create(), [222, 100, 125, 23]), [
+        222 / 255,
+        100 / 255,
+        125 / 255,
+        23 / 255,
+      ]);
     });
     it("should set a color from a Bytes array and keep the color alpha", () => {
       deepEqual(color.fromBytes(color.create(), [222, 100, 125]), [
@@ -112,6 +125,12 @@ describe("Bytes", () => {
         125 / 255,
         DEFAULT_ALPHA,
       ]);
+      deepEqual(color.fromRGBBytes(color.create(), [222, 100, 125]), [
+        222 / 255,
+        100 / 255,
+        125 / 255,
+        DEFAULT_ALPHA,
+      ]);
     });
   });
 
@@ -121,12 +140,20 @@ describe("Bytes", () => {
         color.toBytes([222 / 255, 100 / 255, 125 / 255, 23 / 255]),
         [222, 100, 125, 23],
       );
+      deepEqual(
+        color.toRGBBytes([222 / 255, 100 / 255, 125 / 255, 23 / 255]),
+        [222, 100, 125, 23],
+      );
     });
     it("should return a RGB Bytes array from a color", () => {
       deepEqual(
         color.toBytes([222 / 255, 100 / 255, 125 / 255]),
         [222, 100, 125],
       );
+      deepEqual(
+        color.toRGBBytes([222 / 255, 100 / 255, 125 / 255]),
+        [222, 100, 125],
+      );
     });
   });
 });