[New] add types

index.d.ts

@@ -0,0 +1,16 @@
+declare namespace isWellKnownSymbol {
+    type WellKnownSymbolName = Exclude<
+        keyof SymbolConstructor,
+        | 'constructor'
+        | 'for'
+        | 'from'
+        | 'keyFor'
+        | 'prototype'
+    >;
+
+    type WellKnownSymbol = SymbolConstructor[WellKnownSymbolName];
+}
+
+declare function isWellKnownSymbol(sym: unknown): sym is isWellKnownSymbol.WellKnownSymbol;
+
+export = isWellKnownSymbol;

index.js

@@ -8,33 +8,37 @@ var callBound = require('call-bound');
 
 var symbolValueOf = callBound('Symbol.prototype.valueOf', true);
 
+/** @type {import('.') | undefined} */
 var result;
 
 if (hasSymbols) {
 	var wellKnownSymbols = hasSymbols && flatMap(
 		ownKeys(Symbol),
 		function (k) {
 			var v = Symbol[k];
-			return typeof v === 'symbol' ? v : [];
+			// eslint-disable-next-line no-extra-parens
+			return typeof v === 'symbol' ? /** @type {[import('.').WellKnownSymbol]} */ (/** @type {unknown} */ (v)) : [];
 		}
 	);
 
+	/** @type {{ __proto__: null } & { [k in import('.').WellKnownSymbol]?: true }} */
 	var map = { __proto__: null };
 	for (var i = 0; i < wellKnownSymbols.length; i += 1) {
 		map[wellKnownSymbols[i]] = true;
 	}
 
-	result = function isWellKnownSymbol(sym) {
+	result = /** @type {import('.')} */ function isWellKnownSymbol(sym) {
 		if (!isSymbol(sym)) {
 			return false;
 		}
 		return (typeof sym === 'symbol' ? sym : symbolValueOf(sym)) in map;
 	};
 } else {
 	// eslint-disable-next-line no-unused-vars
-	result = function isWellKnownSymbol(sym) {
+	result = /** @type {import('.')} */ function isWellKnownSymbol(_sym) {
 		return false;
 	};
 }
 
+/** @type {import('.')} */
 module.exports = result;

package.json

@@ -17,6 +17,7 @@
 		"posttest": "npx npm@'>= 10.2' audit --production",
 		"prelint": "evalmd README.md",
 		"lint": "eslint --ext=js,mjs .",
+		"postlint": "tsc && attw -P",
 		"version": "auto-changelog && git add CHANGELOG.md",
 		"postversion": "auto-changelog && git add CHANGELOG.md && git commit --no-edit --amend && git tag -f \"v$(node -e \"console.log(require('./package.json').version)\")\""
 	},
@@ -47,7 +48,14 @@
 		"reflect.ownkeys": "^1.1.4"
 	},
 	"devDependencies": {
+		"@arethetypeswrong/cli": "^0.17.1",
 		"@ljharb/eslint-config": "^21.1.1",
+		"@ljharb/tsconfig": "^0.2.2",
+		"@types/array.prototype.flatmap": "^1.2.6",
+		"@types/for-each": "^0.3.3",
+		"@types/object-inspect": "^1.13.0",
+		"@types/reflect.ownkeys": "^1.1.0",
+		"@types/tape": "^5.6.5",
 		"auto-changelog": "^2.5.0",
 		"encoding": "^0.1.13",
 		"es-value-fixtures": "^1.5.0",
@@ -60,7 +68,8 @@
 		"nyc": "^10.3.2",
 		"object-inspect": "^1.13.3",
 		"safe-publish-latest": "^2.0.0",
-		"tape": "^5.9.0"
+		"tape": "^5.9.0",
+		"typescript": "^5.8.0-dev.20241211"
 	},
 	"testling": {
 		"files": "test/index.js"

test/index.js

@@ -13,7 +13,11 @@ test('isWellKnownSymbol', function (t) {
 	t.equal(typeof isWellKnownSymbol, 'function', 'is a function');
 
 	t.test('non-symbols', function (st) {
-		forEach(v.nonSymbolPrimitives.concat(v.objects), function (nonSymbol) {
+		forEach([].concat(
+			// @ts-expect-error TS sucks with concat
+			v.nonSymbolPrimitives,
+			v.objects
+		), function (nonSymbol) {
 			st.equal(isWellKnownSymbol(nonSymbol), false, inspect(nonSymbol) + ' is not a Symbol');
 		});
 

tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@ljharb/tsconfig",
+  "exclude": [
+    "coverage"
+  ]
+}