docs: add @since tags to exports

lib/abort-signal.ts

@@ -27,6 +27,7 @@ import { resource } from "./resource.ts";
  *   return yield* fetch('/some/url', { signal });
  * }
  * ```
+ * @since 3.0
  */
 export function useAbortSignal(): Operation<AbortSignal> {
   return resource(function* (provide) {

lib/action.ts

@@ -43,6 +43,7 @@ interface Executor<T> {
  *
  * @param executor - a function called every time that an action is evaluated
  * @return an operation that will run according to `executor` every time it is evaluated
+ * @since 3.0
  */
 export function action<T>(executor: Executor<T>, desc?: string): Operation<T> {
   return {

lib/all.ts

@@ -26,6 +26,7 @@ import { trap } from "./task.ts";
  *
  * @param ops a list of operations to wait for
  * @returns the list of values that the operations evaluate to, in the order they were given
+ * @since 3.0
  */
 export function* all<T extends readonly Operation<unknown>[] | []>(
   ops: T,

lib/async.ts

@@ -9,6 +9,7 @@ import { call } from "./call.ts";
  *
  * @param iter - the iterator to convert
  * @returns a subscription that will produce each item of `iter`
+ * @since 3.0
  */
 export function subscribe<T, R>(iter: AsyncIterator<T, R>): Subscription<T, R> {
   return {
@@ -23,6 +24,7 @@ export function subscribe<T, R>(iter: AsyncIterator<T, R>): Subscription<T, R> {
  *
  * @param iterable - the async iterable to convert
  * @returns a stream that will produce each item of `iterable`
+ * @since 3.0
  */
 export function stream<T, R>(iterable: AsyncIterable<T, R>): Stream<T, R> {
   return {

lib/call.ts

@@ -23,6 +23,7 @@ import type { Operation } from "./types.ts";
  * await run(() => hello(async () => "world!")); // => "hello world!"
  * await run(() => hello(function*() { return "world!" })); "hello world!";
  * ```
+ * @since 3.0
  */
 export interface Callable<
   T extends Operation<unknown> | Promise<unknown> | unknown,
@@ -64,6 +65,7 @@ export interface Callable<
  * or plain function to call as part of this operation
  *
  * @returns an {@link Operation} that evaluates to the result of executing the function to completion
+ * @since 3.0
  */
 export function call<T, TArgs extends unknown[] = []>(
   fn: (...args: TArgs) => Promise<T>,

lib/channel.ts

@@ -7,6 +7,7 @@ import { lift } from "./lift.ts";
  * via the same {@link Stream}, and messages sent to the channel are
  * received by all consumers. The channel is not buffered, so if there
  * are no consumers, the message is dropped.
+ * @since 3.0
  */
 export interface Channel<T, TClose> extends Stream<T, TClose> {
   /**
@@ -51,6 +52,7 @@ export interface Channel<T, TClose> extends Stream<T, TClose> {
  *   console.log(yield* subscription2.next()); //=> { done: false, value: 'world' }
  * });
  * ```
+ * @since 3.0
  */
 export function createChannel<T, TClose = void>(): Channel<T, TClose> {
   let signal = createSignal<T, TClose>();

lib/context.ts

@@ -7,6 +7,7 @@ import { Do } from "./do.ts";
  *
  * @param name - the unique name to give this context.
  * @returns the new context
+ * @since 3.0
  */
 export function createContext<T>(name: string, defaultValue?: T): Context<T> {
   let context: Context<T> = {

lib/each.ts

@@ -27,6 +27,7 @@ import { withResolvers } from "./with-resolvers.ts";
  * @typeParam T - the type of each value in the stream.
  * @param stream - the stream to iterate
  * @returns an operation to iterate `stream`
+ * @since 3.0
  */
 export function each<T>(stream: Stream<T, unknown>): Operation<Iterable<T>> {
   return {

lib/ensure.ts

@@ -40,6 +40,7 @@ import { resource } from "./resource.ts";
  * asynchronous cleanup. Otherwise, you can return `void`
  *
  * @param fn - a function which returns an {@link Operation} or void
+ * @since 3.0
  */
 export function ensure(fn: () => Operation<unknown> | void): Operation<void> {
   return resource(function* (provide) {

lib/events.ts

@@ -26,6 +26,7 @@ export type EventList<T> = T extends {
  * @param target - the event target to be watched
  * @param name - the name of the event to watch. E.g. "click"
  * @returns an Operation that yields the next emitted event
+ * @since 3.0
  */
 export function once<
   T extends EventTarget,
@@ -50,6 +51,7 @@ export function once<
  * @param target - the event target whose events will be streamed
  * @param name - the name of the event to stream. E.g. "click"
  * @returns a stream that will see one item for each event
+ * @since 3.0
  */
 export function on<
   T extends EventTarget,

lib/interval.ts

@@ -15,6 +15,7 @@ import type { Stream } from "./types.ts";
  * }
  * ```
  * @param milliseconds - how long to delay between each item in the stream
+ * @since 3.6
  */
 export function interval(milliseconds: number): Stream<void, never> {
   return resource(function* (provide) {

lib/lift.ts

@@ -17,6 +17,7 @@ import type { Operation } from "./types.ts";
  * @typeParam TArgs - the type of the arguments to `fn`
  * @typeParam TReturn - return type of `fn`
  * @returns a function returning an operation that invokes `fn` when evaluated
+ * @since 3.0
  */
 export function lift<TArgs extends unknown[], TReturn>(
   fn: (...args: TArgs) => TReturn,

lib/main.ts

@@ -17,6 +17,7 @@ import { call } from "./call.ts";
  * @param status - the exit code to use for the process exit
  * @param message - message to print to the console before exiting.
  * @param returns an operation that exits the program
+ * @since 3.0
  */
 export function* exit(status: number, message?: string): Operation<void> {
   let escape = yield* ExitContext.expect();
@@ -56,6 +57,7 @@ export function* exit(status: number, message?: string): Operation<void> {
  *
  * @param body - an operation to run as the body of the program
  * @returns a promise that resolves right after the program exits
+ * @since 3.0
  */
 
 export async function main(

lib/queue.ts

@@ -9,6 +9,7 @@ import { action } from "./action.ts";
  *
  * @typeParam T the type of the items in the queue
  * @typeParam TClose the type of the value that the queue is closed with
+ * @since 3.0
  */
 export interface Queue<T, TClose> extends Subscription<T, TClose> {
   /**
@@ -50,6 +51,7 @@ export interface Queue<T, TClose> extends Subscription<T, TClose> {
  *
  * @typeParam T the type of the items in the queue
  * @typeParam TClose the type of the value that the queue is closed with
+ * @since 3.0
  */
 export function createQueue<T, TClose>(): Queue<T, TClose> {
   type Item = IteratorResult<T, TClose>;

lib/race.ts

@@ -26,6 +26,7 @@ import { Err, Ok, type Result } from "./result.ts";
  *
  * @param operations a list of operations to race against each other
  * @returns the value of the fastest operation
+ * @since 3.0
  */
 
 export function* race<T extends Operation<unknown>>(

lib/resource.ts

@@ -42,6 +42,7 @@ import { Priority } from "./contexts.ts";
  *
  * @param operation the operation defining the lifecycle of the resource
  * @returns an operation yielding the resource
+ * @since 3.0
  */
 export function resource<T>(
   op: (provide: Provide<T>) => Operation<void>,
@@ -77,6 +78,9 @@ export function resource<T>(
   };
 }
 
+/**
+ * @since 3.0
+ */
 export interface Provide<T> {
   /**
    * Provide `value` to the calling operation as a resource.

lib/run.ts

@@ -27,6 +27,7 @@ import { global } from "./scope.ts";
  *
  * @param operation the operation to run
  * @returns a task representing the running operation.
+ * @since 3.0
  */
 export function run<T>(operation: () => Operation<T>): Task<T> {
   return global.run(operation);

lib/scope.ts

@@ -4,6 +4,7 @@ import { createScopeInternal } from "./scope-internal.ts";
 
 /**
  * The root of all Effection Scopes.
+ * @since 4.0
  */
 export const global = createScopeInternal()[0] as Scope;
 
@@ -38,6 +39,7 @@ export const global = createScopeInternal()[0] as Scope;
  * @param parent scope. If no parent is specified it will derive directly from {@link global}
  * @returns a tuple containing the freshly created scope, along with a function to
  *          destroy it.
+ * @since 3.0
  */
 export function createScope(
   parent: Scope = global,
@@ -50,6 +52,7 @@ export function createScope(
  * Get the scope of the currently running {@link Operation}.
  *
  * @returns an operation yielding the current scope
+ * @since 3.0
  */
 export function* useScope(): Operation<Scope> {
   return (yield {

lib/scoped.ts

@@ -24,6 +24,7 @@ import { createScopeInternal } from "./scope-internal.ts";
  * @param operation - the operation to be encapsulated
  *
  * @returns the scoped operation
+ * @since 3.2
  */
 export function scoped<T>(operation: () => Operation<T>): Operation<T> {
   return {

lib/signal.ts

@@ -34,6 +34,7 @@ import type { Context } from "./types.ts";
  *
  * @typeParam T - type of each event sent by this signal
  * @typeParam TClose - type of the final event sent by this signal
+ * @since 3.0
  */
 export interface Signal<T, TClose> extends Stream<T, TClose> {
   /**
@@ -113,6 +114,7 @@ export const SignalQueueFactory: Context<typeof createQueue> = createContext(
  * Do not use a signal to send messages from within an operation as it could
  * result in out-of-scope code being executed. In those cases, you should use a
  * {@link Channel}.
+ * @since 3.0
  */
 export function createSignal<T, TClose = never>(): Signal<T, TClose> {
   let subscribers = new Set<Queue<T, TClose>>();

lib/sleep.ts

@@ -15,6 +15,7 @@ import { action } from "./action.ts";
  * ```
  *
  * @param duration - the number of milliseconds to sleep
+ * @since 3.0
  */
 export function sleep(duration: number): Operation<void> {
   return action((resolve) => {

lib/spawn.ts

@@ -27,6 +27,7 @@ import type { Operation, Task } from "./types.ts";
  * @param operation - the operation to run as a child of the current task
  * @typeParam T the type that the spawned task evaluates to
  * @returns a {@link Task} representing a handle to the running operation
+ * @since 3.0
  */
 export function spawn<T>(op: () => Operation<T>): Operation<Task<T>> {
   return {

lib/suspend.ts

@@ -23,6 +23,7 @@ import type { Operation } from "./types.ts";
  * ```
  *
  * @returns an operation that suspends the current operation
+ * @since 3.0
  */
 export function suspend(): Operation<void> {
   return action(() => () => {}, "suspend");

lib/types.ts

@@ -37,7 +37,7 @@ import type { Result } from "./result.ts";
  * ```
  *
  * See [Operations guide](https://frontside.com/effection/docs/operations) for more information.
- *
+ * @since 3.0
  */
 export interface Operation<T> {
   [Symbol.iterator](): Iterator<Effect<unknown>, T, unknown>;
@@ -51,6 +51,7 @@ export interface Operation<T> {
  * can also be evaluated directly within another operation, so among other
  * things, if the operation resolves synchronously, it will continue within the
  * same tick of the run loop.
+ * @since 3.0
  */
 export interface Future<T> extends Operation<T>, Promise<T> {}
 
@@ -131,6 +132,7 @@ export interface Future<T> extends Operation<T>, Promise<T> {}
  * @see {@link run}
  * @see {@link spawn}
  * @see {@link Scope.run}
+ * @since 3.0
  */
 export interface Task<T> extends Future<T> {
   /**
@@ -155,6 +157,7 @@ export interface Task<T> extends Future<T> {
  * {@link Stream}.
  *
  * @see https://effection.deno.dev/docs/collections#subscription
+ * @since 3.0
  */
 export interface Subscription<T, TDone> {
   next(): Operation<IteratorResult<T, TDone>>;
@@ -167,6 +170,7 @@ export interface Subscription<T, TDone> {
  * contain the recipe for how to create a {@link Subscription}
  *
  * @see https://frontside.com/effection/docs/collections#stream
+ * @since 3.0
  */
 export type Stream<T, TReturn> = Operation<Subscription<T, TReturn>>;
 
@@ -176,6 +180,7 @@ export type Stream<T, TReturn> = Operation<Subscription<T, TReturn>>;
  *
  * Unless a context value is defined for a particular scope, it will inherit
  * its value from its parent scope.
+ * @since 3.0
  */
 export interface Context<T> {
   /**
@@ -265,6 +270,7 @@ export interface Context<T> {
  *   yield* suspend();
  * });
  * ```
+ * @since 3.0
  */
 export interface Scope {
   /**
@@ -333,6 +339,7 @@ export interface Scope {
  * Unwrap the type of an `Operation`.
  * Analogous to the built in [`Awaited`](https://www.typescriptlang.org/docs/handbook/utility-types.html#awaitedtype) type.
  * `Yielded<Operation<T>> === T`
+ * @since 3.1
  */
 export type Yielded<T extends Operation<unknown>> = T extends
   Operation<infer TYield> ? TYield

lib/until.ts

@@ -11,6 +11,7 @@ import type { Operation } from "./types.ts";
  * @template {T}
  * @param promise
  * @returns {Operation<T>} that succeeds or fails depending on the outcome of `promise`
+ * @since 3.4
  */
 export function until<T>(promise: Promise<T>): Operation<T> {
   return action((resolve, reject) => {

lib/with-resolvers.ts

@@ -5,6 +5,7 @@ import type { Operation } from "./types.ts";
 /**
  * The return type of {@link withResolvers}. It contains an operation bundled with
  * synchronous functions that determine its outcome.
+ * @since 3.2
  */
 export interface WithResolvers<T> {
   /*
@@ -42,6 +43,7 @@ export interface WithResolvers<T> {
  * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/withResolvers}
  *
  * @returns an operation and its resolvers.
+ * @since 3.2
  */
 
 export function withResolvers<T>(description?: string): WithResolvers<T> {