[New] add types

Author: ljharb

.attw.json

@@ -0,0 +1,6 @@
+{
+	"pack": true,
+	"ignoreRules": [
+		"named-exports"
+	]
+}

.eslintrc

@@ -6,6 +6,7 @@
 	"rules": {
 		"eqeqeq": [2, "allow-null"],
 		"id-length": 0,
+		"no-extra-parens": "off",
 		"no-invalid-this": "off",
 	},
 

auto.d.ts

@@ -0,0 +1,6 @@
+interface RegExp {
+	readonly flags: typeof RegExp.prototype.flags;
+}
+
+declare const x: never;
+export = x;

implementation.d.ts

@@ -0,0 +1,28 @@
+type D = 'd' | '';
+type G = 'g' | '';
+type I = 'i' | '';
+type M = 'm' | '';
+type S = 's' | '';
+type U = 'u' | '';
+type V = 'v' | '';
+type Y = 'y' | '';
+
+declare namespace flags {
+	type Flags = '' | `${D}${G}${I}${M}${S}${U}${V}${Y}`;
+}
+
+declare function flags(
+	this: RegExp | {
+		__proto__?: unknown;
+		hasIndices?: boolean;
+		global?: boolean;
+		ignoreCase?: boolean;
+		multiline?: boolean;
+		dotAll?: boolean;
+		unicode?: boolean;
+		unicodeSets?: boolean;
+		sticky?: boolean;
+	},
+): flags.Flags;
+
+export = flags;

implementation.js

@@ -5,10 +5,11 @@ var $TypeError = require('es-errors/type');
 
 var $Object = Object;
 
-module.exports = setFunctionName(function flags() {
+module.exports = setFunctionName(/** @type {import('./implementation')} */ function flags() {
 	if (this == null || this !== $Object(this)) {
 		throw new $TypeError('RegExp.prototype.flags getter called on non-object');
 	}
+
 	var result = '';
 	if (this.hasIndices) {
 		result += 'd';
@@ -34,6 +35,7 @@ module.exports = setFunctionName(function flags() {
 	if (this.sticky) {
 		result += 'y';
 	}
-	return result;
+	// eslint-disable-next-line no-extra-parens
+	return /** @type {ReturnType<flags>} */ (result);
 }, 'get flags', true);
 

index.d.ts

@@ -0,0 +1,19 @@
+import implementation = require('./implementation');
+import polyfill = require('./polyfill');
+import shim = require('./shim');
+
+type Implementation = typeof implementation;
+type Polyfill = typeof polyfill;
+type Shim = typeof shim;
+
+declare namespace index {
+	type Flags = implementation.Flags;
+
+	const implementation: Implementation;
+	const polyfill: Polyfill;
+	const shim: Shim;
+}
+
+declare function index(re: ThisParameterType<Implementation>): implementation.Flags;
+
+export = index;

package.json

@@ -18,7 +18,7 @@
 		"tests-only": "nyc tape 'test/**/*.js'",
 		"prelint": "eclint check $(git ls-files | xargs find 2> /dev/null | grep -vE 'node_modules|\\.git')",
 		"lint": "eslint --ext=js,mjs .",
-		"postlint": "evalmd README.md && es-shim-api --bound",
+		"postlint": "evalmd README.md && es-shim-api --bound && 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)\")\""
 	},
@@ -48,8 +48,14 @@
 		"set-function-name": "^2.0.2"
 	},
 	"devDependencies": {
+		"@arethetypeswrong/cli": "^0.17.4",
 		"@es-shims/api": "^2.5.1",
 		"@ljharb/eslint-config": "^21.1.1",
+		"@types/call-bind": "^1.0.5",
+		"@types/define-properties": "^1.1.5",
+		"@types/functions-have-names": "^1.2.2",
+		"@types/object-inspect": "^1.13.0",
+		"@types/tape": "^5.8.1",
 		"auto-changelog": "^2.5.0",
 		"available-regexp-flags": "^1.0.4",
 		"eclint": "^2.8.1",
@@ -66,7 +72,8 @@
 		"nyc": "^10.3.2",
 		"object-inspect": "^1.13.4",
 		"safe-publish-latest": "^2.0.0",
-		"tape": "^5.9.0"
+		"tape": "^5.9.0",
+		"typescript": "next"
 	},
 	"testling": {
 		"files": "test/index.js",
@@ -99,7 +106,8 @@
 	},
 	"publishConfig": {
 		"ignore": [
-			".github/workflows"
+			".github/workflows",
+			".attw.json"
 		]
 	}
 }

polyfill.d.ts

@@ -0,0 +1,5 @@
+import implementation from "./implementation";
+
+declare function polyfill(): typeof implementation;
+
+export = polyfill;

polyfill.js

@@ -5,6 +5,7 @@ var implementation = require('./implementation');
 var supportsDescriptors = require('define-properties').supportsDescriptors;
 var $gOPD = Object.getOwnPropertyDescriptor;
 
+/** @type {import('./polyfill.d.ts')} */
 module.exports = function getPolyfill() {
 	if (supportsDescriptors && (/a/mig).flags === 'gim') {
 		var descriptor = $gOPD(RegExp.prototype, 'flags');

shim.d.ts

@@ -0,0 +1,6 @@
+import implementation from "./implementation";
+
+declare function shim(): typeof implementation;
+
+export = shim;
+

shim.js

@@ -8,12 +8,13 @@ var $TypeError = require('es-errors');
 var getProto = require('get-proto');
 var regex = /a/;
 
+/** @type {import('./shim.d.ts')} */
 module.exports = function shimFlags() {
-	if (!supportsDescriptors || !getProto) {
+	if (!supportsDescriptors || !getProto || !gOPD) {
 		throw new $TypeError('RegExp.prototype.flags requires a true ES5 environment that supports property descriptors');
 	}
 	var polyfill = getPolyfill();
-	var proto = getProto(regex);
+	var proto = /** @type {typeof RegExp.prototype} */ (getProto(regex));
 	var descriptor = gOPD(proto, 'flags');
 	if (!descriptor || descriptor.get !== polyfill) {
 		defineProperty(proto, 'flags', {

test/implementation.js

@@ -9,7 +9,9 @@ var runTests = require('./tests');
 test('as a function', function (t) {
 	t.test('bad array/this value', { skip: !hasStrictMode }, function (st) {
 		/* eslint no-useless-call: 0 */
+		// @ts-expect-error
 		st['throws'](function () { flags.call(undefined); }, TypeError, 'undefined is not an object');
+		// @ts-expect-error
 		st['throws'](function () { flags.call(null); }, TypeError, 'null is not an object');
 		st.end();
 	});

test/index.js

@@ -6,7 +6,9 @@ var runTests = require('./tests');
 
 test('as a function', function (t) {
 	t.test('bad array/this value', function (st) {
+		// @ts-expect-error
 		st['throws'](function () { flags(undefined); }, TypeError, 'undefined is not an object');
+		// @ts-expect-error
 		st['throws'](function () { flags(null); }, TypeError, 'null is not an object');
 		st.end();
 	});

test/shimmed.js

@@ -16,9 +16,11 @@ var runTests = require('./tests');
 test('shimmed', function (t) {
 	var descriptor = Object.getOwnPropertyDescriptor(RegExp.prototype, 'flags');
 
+	// @ts-expect-error
 	t.equal(descriptor.get.length, 0, 'RegExp#flags getter has a length of 0');
 
 	t.test('Function name', { skip: !functionsHaveNames }, function (st) {
+		// @ts-expect-error
 		st.equal(descriptor.get.name, functionsHaveConfigurableNames ? 'get flags' : 'flags', 'RegExp#flags getter has name "get flags" (or "flags" if function names are not configurable)');
 		st.end();
 	});
@@ -29,19 +31,26 @@ test('shimmed', function (t) {
 	});
 
 	t.test('bad array/this value', { skip: !hasStrictMode }, function (st) {
+		// @ts-expect-error
 		st['throws'](function () { return descriptor.get.call(undefined); }, TypeError, 'undefined is not an object');
+		// @ts-expect-error
 		st['throws'](function () { return descriptor.get.call(null); }, TypeError, 'null is not an object');
 		st.end();
 	});
 
 	t.test('has the correct descriptor', function (st) {
+		// @ts-expect-error
 		st.equal(descriptor.configurable, true);
+		// @ts-expect-error
 		st.equal(descriptor.enumerable, false);
+		// @ts-expect-error
 		st.equal(typeof descriptor.get, 'function');
+		// @ts-expect-error
 		st.equal(descriptor.set, undefined);
 		st.end();
 	});
 
+	// @ts-expect-error
 	runTests(callBind(descriptor.get), t);
 
 	t.end();

test/tests.js

@@ -11,17 +11,17 @@ var regexProperties = require('available-regexp-flags/properties');
 
 var sortedFlags = availableFlags.slice().sort(function (a, b) { return a.localeCompare(b); }).join('');
 
+/** @type {(stringRegex: string) => RegExp} */
 var getRegexLiteral = function (stringRegex) {
-	try {
-		// eslint-disable-next-line no-new-func
-		return Function('return ' + stringRegex + ';')();
-	} catch (e) { /**/ }
-	return null;
+	// eslint-disable-next-line no-new-func
+	return Function('return ' + stringRegex + ';')();
 };
 
+/** @type {(flags: (re: ThisParameterType<typeof import('../implementation')>) => ReturnType<import('../implementation')>, t: import('tape').Test) => void} */
 module.exports = function runTests(flags, t) {
 	forEach(v.primitives, function (nonObject) {
 		t['throws'](
+			// @ts-expect-error
 			function () { flags(nonObject); },
 			TypeError,
 			'throws when called with a non-object receiver: ' + inspect(nonObject)
@@ -80,9 +80,11 @@ module.exports = function runTests(flags, t) {
 	t.test('generic flags', function (st) {
 		st.equal(flags({}), '');
 		st.equal(flags({ ignoreCase: true }), 'i');
+		// @ts-expect-error truthy values work, but the type says "boolean"
 		st.equal(flags({ dotAll: 1, global: 0, sticky: 1, unicode: 1 }), 'suy');
 		st.equal(flags({ __proto__: { multiline: true } }), 'm');
 
+		/** @type {Extract<Parameters<flags>[0], { __proto__?: unknown }>} */
 		var obj = {};
 		forEach(availableFlags, function (flag) {
 			if (flag !== 'v') {
@@ -134,6 +136,7 @@ module.exports = function runTests(flags, t) {
 			}
 		});
 
+		// @ts-expect-error
 		flags(re);
 
 		st.equal(calls, 'dgimsuy', 'getters are called in expected order');

tsconfig.json

@@ -0,0 +1,49 @@
+{
+	"compilerOptions": {
+		/* Visit https://aka.ms/tsconfig.json to read more about this file */
+
+		/* Projects */
+
+		/* Language and Environment */
+		"target": "ESNext",																	/* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
+		// "lib": [],																				/* Specify a set of bundled library declaration files that describe the target runtime environment. */
+		// "noLib": true,																		/* Disable including any library files, including the default lib.d.ts. */
+		"useDefineForClassFields": true,										 /* Emit ECMAScript-standard-compliant class fields. */
+		// "moduleDetection": "auto",												/* Control what method is used to detect module-format JS files. */
+
+		/* Modules */
+		"module": "commonjs",																/* Specify what module code is generated. */
+		// "rootDir": "./",																	/* Specify the root folder within your source files. */
+		// "moduleResolution": "node",											 /* Specify how TypeScript looks up a file from a given module specifier. */
+		// "baseUrl": "./",																	/* Specify the base directory to resolve non-relative module names. */
+		// "paths": {},																			/* Specify a set of entries that re-map imports to additional lookup locations. */
+		// "rootDirs": [],																	 /* Allow multiple folders to be treated as one when resolving modules. */
+		// "typeRoots": ["types"],													 /* Specify multiple folders that act like `./node_modules/@types`. */
+		"resolveJsonModule": true,													 /* Enable importing .json files. */
+		// "allowArbitraryExtensions": true,								 /* Enable importing files with any extension, provided a declaration file is present. */
+
+		/* JavaScript Support */
+		"allowJs": true,																		 /* Allow JavaScript files to be a part of your program. Use the `checkJS` option to get errors from these files. */
+		"checkJs": true,																		 /* Enable error reporting in type-checked JavaScript files. */
+		"maxNodeModuleJsDepth": 1,													 /* Specify the maximum folder depth used for checking JavaScript files from `node_modules`. Only applicable with `allowJs`. */
+
+		/* Emit */
+		"declaration": true,																 /* Generate .d.ts files from TypeScript and JavaScript files in your project. */
+		"declarationMap": true,															/* Create sourcemaps for d.ts files. */
+		"noEmit": true,																			/* Disable emitting files from a compilation. */
+
+		/* Interop Constraints */
+		"allowSyntheticDefaultImports": true,								/* Allow `import x from y` when a module doesn't have a default export. */
+		"esModuleInterop": true,														 /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables `allowSyntheticDefaultImports` for type compatibility. */
+		"forceConsistentCasingInFileNames": true,						/* Ensure that casing is correct in imports. */
+
+		/* Type Checking */
+		"strict": true,																			/* Enable all strict type-checking options. */
+
+		/* Completeness */
+		// "skipLibCheck": true															/* Skip type checking all .d.ts files. */
+	},
+	"exclude": [
+		"coverage",
+	],
+}