Skip to content

docs: add @since tags to exports#1089

Open
alexvyber wants to merge 1 commit intothefrontside:v4from
alexvyber:since-tag-every-api-method
Open

docs: add @since tags to exports#1089
alexvyber wants to merge 1 commit intothefrontside:v4from
alexvyber:since-tag-every-api-method

Conversation

@alexvyber
Copy link
Collaborator

@alexvyber alexvyber commented Jan 27, 2026

Closes #1039
Adds @since tags to exports

@pkg-pr-new
Copy link

pkg-pr-new bot commented Jan 27, 2026

Open in StackBlitz

npm i https://pkg.pr.new/thefrontside/effection@1089

commit: ed7c284

Copy link
Member

@cowboyd cowboyd left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here are a couple of tweaks:

  1. Let's only use the major minor version since those are the only meaningful semver points that can introduce or change an api. I.e. instead of since @effection-v3.0.1, just @since 3.1
  2. I've noted it in a couple of places, but it looks as though the version is not correct. In fact, it appears that all of the versions are either 3.0 or 4.0 which means we're losing something somewhere. For example, the scoped API was introduced in v3.2.0
  3. For interface that have methods like Scope, we need to include their methods. For example Scope.run() was introduced in 3.0, but Scope.spawn() not until 3.5

* @param operation - the operation to be encapsulated
*
* @returns the scoped operation
* @since effection-v3.0.0
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was released with version 3.2.0 so I think that the algorithm might be not quite right.

*
* @param effect - the effect to perform
* @returns an operation that performs `effect`
* @since effection-v4.0.0
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do() is not part of the public api and should not be reachable via lib/mod.ts.

* @see {@link run}
* @see {@link spawn}
* @see {@link Scope.run}
* @since effection-v3.0.0
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the Task interface was actually introduce in 2.0

Comment on lines 363 to 380
@@ -366,6 +375,7 @@ export interface Coroutine<T = unknown> {

/**
* @ignore
* @since effection-v3.0.0
*/
export interface Resolve<T> {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't need since tags for ignored APIs since they are not part of the public api and should not be relied upon.

* @template {T}
* @param promise
* @returns {Operation<T>} that succeeds or fails depending on the outcome of `promise`
* @since effection-v3.0.0
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe this was introduced in v3.4.0, so again, we may need to revisit the logic.

@taras
Copy link
Member

taras commented Feb 13, 2026

@alexvyber you've done all of the heavy lifting here. I don't want to rush you, but I do want to extend an hand in case you need help driving this over the finish line. Please let me know if there is anything I can do to help.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Mark every API method, in both v3 and v4 as having "since" tag

3 participants