[types] Generate declarations from JS (#564)

* feat: Generate declarations from JSDoc

* feat: Add back `package.json` types mentions

* fix: Add missing `copy-declarations.js` script

* fix: Ordering in `build:ts` script

Co-authored-by: Lloyd Kupchanko <lloyd@lloydk.ca>

* fix: Create declarations directory if nonexistant

Co-authored-by: Lloyd Kupchanko <lloyd@lloydk.ca>

* fix: Add missing import

Co-authored-by: Lloyd Kupchanko <lloyd@lloydk.ca>

* fix: Remove non-existent file from `TO_COPY`

* build: Add `watch:ts` script

---------

Co-authored-by: Lloyd Kupchanko <lloyd@lloydk.ca>

.eslintignore

@@ -3,4 +3,5 @@ assets/js/prism.js
 api/
 /dist/
 docs/
+types/src/
 node_modules/

.gitignore

@@ -8,4 +8,7 @@ node_modules/
 !test/*.html
 !benchmarks/*.html
 
-api/
+# Ignore generated TypeScript files
+types/src/
+
+api/

package.json

@@ -4,27 +4,40 @@
 	"description": "Let’s get serious about color",
 	"files": [
 		"dist/",
-		"src/"
+		"src/",
+		"types/src/",
+		"types/index.d.ts"
 	],
 	"exports": {
 		".": {
 			"import": {
+				"types": "./types/index.d.ts",
 				"default": "./dist/color.js"
 			},
 			"require": {
+				"types": "./types/index.d.ts",
 				"default": "./dist/color.cjs"
 			}
 		},
 		"./fn": {
 			"import": {
+				"types": "./types/src/index-fn.d.ts",
 				"default": "./src/index-fn.js"
 			},
 			"require": {
+				"types": "./types/src/index-fn.d.ts",
 				"default": "./dist/color-fn.cjs"
 			}
 		},
 		"./dist/*": "./dist/*"
 	},
+	"typesVersions": {
+		"*": {
+			"fn": [
+				"./types/src/index-fn.d.ts"
+			]
+		}
+	},
 	"type": "module",
 	"main": "./dist/color.cjs",
 	"module": "./dist/color.js",
@@ -41,11 +54,13 @@
 		"watch:html": "npx @11ty/eleventy --config=_build/eleventy.js --serve",
 		"build:js": "rollup -c _build/rollup.config.js",
 		"watch:js": "rollup -c _build/rollup.config.js --watch",
+		"build:ts": "node ./scripts/copy-declarations.js && tsc",
+		"watch:ts": "tsc --watch",
 		"build:apidocs": "npx typedoc",
 		"watch:apidocs": "npx typedoc --watch",
 		"build:js:legacy": "rollup -c _build/rollup.legacy.config.js",
 		"build:space-accessors": "node ./scripts/generate-space-accessor-types.js",
-		"build": "run-s build:apidocs build:html build:js build:js:legacy build:space-accessors",
+		"build": "run-s build:apidocs build:html build:js build:ts build:js:legacy build:space-accessors",
 		"watch": "run-p watch:*",
 		"prepack": "npm run build",
 		"release": "release-it"

scripts/copy-declarations.js

@@ -0,0 +1,30 @@
+// Copy manually-written `.d.ts` files from `src/` to `types/src/`
+import { copyFileSync, mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SOURCE = "../src/";
+const DEST = "../types/src/";
+
+/**
+ * `.d.ts` files to copy.
+ * Paths written relative to the `src/` directory
+ */
+const TO_COPY = [
+	"color.d.ts",
+	"ColorSpace.d.ts",
+	"hooks.d.ts",
+	"index.d.ts",
+	"space-coord-accessors.d.ts",
+	"types.d.ts",
+];
+
+/** Script file directory */
+const __dirname = dirname(fileURLToPath(import.meta.url));
+mkdirSync(resolve(__dirname, DEST), { recursive: true });
+for (const file of TO_COPY) {
+	copyFileSync(
+		resolve(__dirname, SOURCE, file),
+		resolve(__dirname, DEST, file),
+	);
+}

tsconfig.json

@@ -3,7 +3,10 @@
 		"checkJs": true,
 		"lib": ["DOM", "ESNext"],
 		"skipLibCheck": true,
-		"noEmit": true
+		"declaration": true,
+		"emitDeclarationOnly": true,
+		"declarationMap": true,
+		"outDir": "types/src"
 	},
 	"include": ["src/**/*.js", "src/**/*.d.ts"],
 	"exclude": ["node_modules/**"]

types/index.d.ts

@@ -1 +1,3 @@
 // Minimum TypeScript Version: 5.0
+export { default } from "./src/index.js";
+export * from "./src/index.js";

types/tsconfig.json

@@ -10,11 +10,10 @@
 		"noEmit": true,
 		"forceConsistentCasingInFileNames": true,
 		"baseUrl": ".",
-		"allowJs": true,
 		"paths": {
-			"colorjs.io": ["../src"],
-			"colorjs.io/fn": ["../src/index-fn.js"],
-			"colorjs.io/*": ["../*"]
+			"colorjs.io": ["."],
+			"colorjs.io/fn": ["./src/index-fn.js"],
+			"colorjs.io/*": ["./*"]
 		}
 	}
 }