Provide easier access to object in JavaScript JSDoc

[ExE-Boss]

Search Terms

• JSDoc object
• Allow primitive types in JSDoc to start wtih uppercase letters #14284

Suggestion

There should be a compiler option like strictJSDocTypes or something to disable the object to any conversion present in TypeScript’s JSDoc parser.

Use Cases

I’m currently forced to use:

/** @typedef {NonNullable<Parameters<typeof Object.create>[0]>} obj */

to get a reference to TypeScript’s object type.

Examples

Any code where I use the above.

---

The following code creates an object with writable, configurable and non‑enumerable properties:

var ES = require("es-abstract");
var define = require("define-properties");
var $ObjectCreate = GetIntrinsic("%Object.create%", true);

/**
 * @template {object} M
 * @param {object | null} proto
 * @param {M & ThisType<any>} [props]
 * @return {object}
 */
function createObj(proto, props) {
	var result = ES.ObjectCreate(proto);
	if (arguments.length > 1) {
		define(result, props);
	}
	return result;
}

All instances of object in the above code currently have to be replaced with the obj type alias.

Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

[andrewbranch]

@sandersn my understanding from microsoft/TypeScript-New-Handbook#36 was that object was no longer rewritten to any as of 3.7, but it doesn’t seem like that’s the case?

Neither object nor Object have defined properties or string index
signatures, which means that they give too many errors to be useful in
Javascript. Until Typescript 3.7, both were rewritten to any, but we
found that few people used object in JSDoc, and that more and more
JSDoc authors wanted to use object with its Typescript meaning. The
rewrite Object -> any is disabled when "noImplicitAny": true,
which the compiler takes as a signal that the code is being written
with Typescript in mind.

[sandersn]

derp! yes, I misread the code when writing that new text. getIntendedTypeFromJSDocTypeReference doesn't handle object, so I assumed that a discussion I had earlier about turning off object -> any had resulted in the change. But actually it only operates on type references, not keywords. object is a keyword, so it's handled in getTypeFromTypeNode.

I need to track down that discussion, because I think it had some analysis of actual usage.

[sandersn]

But in summary:

1. We want to do this.
2. I thought we already did this.
3. We should make sure that lots of JS code isn't currently using object to mean any the way we've observed Object being used.