fix: package.json docs

[reggi]

This is an attempt to reconcile and fully document package.json properties.

typescript type here: https://github.com/npm/types/blob/main/types/index.d.ts
json schema: https://github.com/SchemaStore/schemastore/blob/master/src/schemas/json/package.json

I personally had some confusion around maintainers.

Adds node specific fields like imports and type.

Also adds (deprecations) for bundledDependencies / maintainers and licences.

Related to @kenshanta's work on documenting type #7897

Moving forward i'd like to just callout the following:

1. Any property acknowledged by Node.js should point to the documentation.
2. We should not "copy and paste" or reinterpret the Node.js docs when a link is better.

[ljharb]

i think this is actually a typescript-deprecated field from TS < v3 or v2.

[reggi]

Yeah i didn't know about it until today.

From the ts docs:

Note that the "typings" field is synonymous with types, and could be used as well.

We do honor it.

If you can find deprecation docs I'm down to add (deprecation). I still think it should be documented.

[ljharb]

https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html implies it's just an alias, so maybe it's not actually deprecated.

[kenshanta]

@reggi why overwrite a pre-existing PR specifically created for the addition of the type attribute?
If you disagree with the changes in #7897 please feel free to add your comments and leave the rest for the reviewers to decide.
All the best

[reggi]

I'm realizing that past deprecated fields like preferGlobal were just removed. So the latest docs isn't a living list of all fields, which i'm not in favor of generally. I like to see deprecated fields the same way json schema, or @deprecated jsdoc typing would work.

[ljharb]

@reggi maybe a page that hides deprecated attributes by default, but they can be toggled visible? (and if someone arrives on a # link to one of them, it shows them as well)

that would reduce the risk that someone implements support for, or uses, one of the deprecated attributes without pretending they never existed.

[reggi]

I'm also realizing i'm lacking the terminology for the following:

• deprecated as in "never honored" (maintainers => contributors)
• deprecated as in "not honored" (ie licenses => license)
• deprecated as in "honored, not preferred" (bundledDependencies => bundleDependencies, typings => types)

[ljharb]

i'd say only the third one is "deprecated", the other two are removed, or legacy, or something.