Is there a term that's kind of the opposite of 'deprecated' - that's 'in future major versions this thing will be required'

Question

In terms of deprecation strategies, we can mark a value as deprecated and this can imply that 'this thing exists now and should work, but in future major releases this thing may disappear and will break your code'.

eg:

type MyClient =  {
/** 
  @deprecated - prefer using `bar` instead 
*/
foo: () =&gt; string; 
bar: () =&gt; Promise&lt;string&gt;; 

}

At the same time, in terms of an extensible/non-breaking strategy - we can always allow additional optional inputs to add extra functionality without breaking existing code:


type MyClient =  {
/** 
  @deprecated - prefer using `bar` instead 
*/
foo: () =&gt; string; 


bar: () => Promise<string>;


bar: (options?: {x: boolean}) => Promise<string>;

}

In this scenario, I want to indicate that that options object will be mandatory in future major releases - is there a term for this kind of annotation?

Flater · Answer 1 · 2024-08-07T06:58:20.697

That's still a deprecation. You will be deprecating the optional nature of the parameter, which will be a breaking change.

For the purpose of your consumer being alerted to the deprecation, it's irrelevant whether you're going to be removing bar entirely or changing bar in a way that old usages will break.

It's a deprecation, and it should be treated as a deprecation, because that's what it is: a currently valid way of working today will break in a future version.

It is of course relevant to also document what the new way of working is/will be; but whether that's a totally different way of working or a similarly named method with a slightly different signature is an irrelevant distinction. We don't spend time quantifying the degree to which it is a breaking change. Either it's a breaking change or it's not. "A bit of a breaking change" is not a thing.

score 2 · Accepted Answer · answered Aug 07 '24 at 23:59

As @jonrsharpe points out in the comments, this is simply overloading a function and deprecating one of the overloads.

In TypeScript you would do it this way:


async function bar(options: {x : boolean}) : Promise<string>; 
/**
 * @deprecated - options object will be mandatory
 */
async function bar() : Promise<string>; 
async function bar(options?: {x: boolean}) : Promise<string> {
    return ""; 
}
type MyClient = {
    bar: typeof bar, 
}
async function main(client: MyClient) {
const result1 : string = await client.bar(); 
const result2 : string = await client.bar({x: true}); 

}

(Straight declaration of a union of function signatures doesn't play nicely in TypeScript - see: https://stackoverflow.com/questions/43662729/union-type-of-two-functions-in-typescript)

Note the IDE deprecation strikethrough hint:

Is there a term that's kind of the opposite of 'deprecated' - that's 'in future major versions this thing will be required'

2 Answers2