The fact that it is using spread syntax is irrelevant. You document what the function does not necessarily how. So, it takes some object and (potentially) enriches it with more properties keeping the id in place.
/**
* @typedef Thingamajig
* @type {object}
* @property {number} foo - some number here
* @property {string} bar - a string used for something
*/
/**
* Transforms things.
* @param {string} key - what to transform
* @return {Promise<Thingamajig>} - transforms into this
*/
function thingDoer(key) { /* .... */ }
/**
* it does the things
* @param {Object} input - object containing id and key
* @param {string} input.id - unique id to associate with return value
* @param {string} input.key - unique key used to get things
* @returns {Promise<Thingamajig & {id:string}>} the returned things and id.
*/
const doTheThings = ({id, key}) =>
thingDoer(key).then(things => {
...things,
id
})
See on the TypeScript Playground - the file type has been set to JavaScript (found under TS Options), so this is purely a way to demonstrate how the JSDoc will be interpreted. Hover over functions and parameters to see what their types are.
The key thing here is using @typedef to declare the same object structure that thingDoer returns and doTheThings also uses. That way if it changes, you only change one place.
The doTheThings function then returns Thingamajig & {id:string} which is a Thingamajig with an added id property which is a string. An alternative is to create another typedef like ThingamajigWithId and document the property there. Depends on which tool consumes the JSDoc.
/**
* @typedef ThingamajigWithId
* @type {object}
* @property {number} foo - some number here
* @property {string} bar - a string used for something
* @property {string} id - unique identifier.
*/
One interesting thing you can do with an intersection (the &) is to declare the type with an ID separately, then intersect the two. This way you can document it:
/**
* @typedef Thingamajig
* @type {object}
* @property {number} foo - some number here
* @property {string} bar - a string used for something
*/
/**
* @typedef WithId
* @type {object}
* @property {string} id - unique identifier
*/
/** ...
* @returns {Promise<Thingamajig & WithId>} the returned things and id.
*/
See on the TypeScript Playground
Note that type intersections are not part of JSDoc itself. They are a TypeScript feature. Depending on which tool consumes the JSDoc it might or might not work. For example, Visual Studio Code likely will not complain, however, if you have a tool that constructs documentation from the annotations, it might not recognise the & as valid.
Also note that there is a long-standing feature to add this type of extension of objects in JSDoc itself:
Issue on GitHub from April 2016
Question on Stack Overflow that spawned it: How to extend a typedef parameter in JSDOC?
Right now there does not seem to be a way to extend a typedef that satisfies all consumers of JSDoc. The only thing that seems to be guaranteed to work is to manually create a typedef which manually repeats all properties (which I showed above):
/**
* @typedef ThingamajigWithId
* @type {object}
* @property {number} foo - some number here
* @property {string} bar - a string used for something
* @property {string} id - unique identifier.
*/
However, it does not change with the base typedef for Thingamajig, which makes it annoying to maintain. Here is a brief rundown of different things that might be supported
- Using an intersection works for anything that bases interpretation on TypeScript.
- There is also a plugin to extend JSDoc to recognise
&.
- Some tools seem to support using
| instead and would show A | B as having both properties from A and B, even though it should be an alternation.
- Some tools recognise
/**
* @typedef {A, B} Combined
*/
- Some tools recognise
/**
* @typedef Combined
* @type {A, B}
*/
I could not find a technique that seems to work consistently everywhere.
