fill out JSDocs with examples (#1141)

jbolda · taras · web-flow · commit 826c8656b483 · 2026-05-13T20:47:13.000-05:00
* fill out JSDocs with examples

* api / middleware docs

* Apply suggestions from code review

Co-authored-by: Taras Mankovski &lt;tarasm@gmail.com&gt;

* Fix type annotation for DbMiddleware function

* adjust per comments on docs

* duplicate exports

* Update resource example to use ConxPool

* Replace send method with add in queue example

* preferred use of resource type

---------

Co-authored-by: Taras Mankovski &lt;tarasm@gmail.com&gt;
diff --git a/deno.json b/deno.json
@@ -1,6 +1,5 @@
 {
   "name": "@effection/effection",
-  "exports": "./mod.ts",
   "license": "ISC",
   "publish": { "include": ["lib", "mod.ts", "experimental.ts", "README.md"] },
   "lock": false,
diff --git a/lib/all.ts b/lib/all.ts
@@ -10,8 +10,7 @@ import { trap } from "./task.ts";
  *
  * If any of the operations become errored, then `all` will also become errored.
  *
- * ### Example
- *
+ * @example
  * ``` javascript
  * import { all, expect, main } from 'effection';
  *
diff --git a/lib/api.ts b/lib/api.ts
@@ -3,6 +3,33 @@ import type { Api, Context, Operation, Scope } from "./types.ts";
 import { createApiInternal } from "./api-internal.ts";
 import type { ScopeInternal } from "./scope-internal.ts";
 
+/**
+ * Create a new {@link Api}. This is the constructor behind
+ * middleware decoration used through core such as with {@link Scope#around}.
+ * One may implement an API around any operation or value and then decorate it per-scope.
+ *
+ * @example
+ * ```ts
+ * import { createApi, type Operation } from "effection/experimental";
+ *
+ * interface DatabaseApi {
+ *   query(sql: string): Operation<{ id: number; title: string }[]>;
+ * }
+ *
+ * // pass in the generic type or allow it to infer
+ * let Database = createApi<DatabaseApi>("database", {
+ *   *query(sql) {
+ *     console.log("running", sql);
+ *     return [];
+ *   },
+ * });
+ * ```
+ *
+ * @param name - the API identifier used in error and debug messages
+ * @param core - the core function/value implementations for this API
+ * @returns an {@link Api} that can be invoked and decorated per-scope
+ * @since 4.1
+ */
 export function createApi<A extends {}>(name: string, core: A): Api<A> {
   return createApiInternal(name, core);
 }
@@ -23,6 +50,30 @@ interface Apis {
   Main: Api<MainApi>;
 }
 
+/**
+ * Built-in internal APIs used by Effection's runtime and host integration.
+ * Advanced integrations can decorate these APIs in a scope.
+ *
+ * @example
+ * ```ts
+ * import { run, useScope } from "effection";
+ * import { api } from "effection/experimental";
+ *
+ * await run(function* () {
+ *   let scope = yield* useScope();
+ *
+ *   // Observe every scope creation in this scope subtree
+ *   scope.around(api.Scope, {
+ *     create(args, next) {
+ *       console.log("creating scope");
+ *       return next(...args);
+ *     },
+ *   });
+ * });
+ * ```
+ *
+ * @since 4.1
+ */
 export const api: Apis = {
   Scope: createApi<ScopeApi>("Scope", {
     create() {
diff --git a/lib/async.ts b/lib/async.ts
@@ -7,6 +7,22 @@ import { call } from "./call.ts";
  *
  * This allows you to consume any `AsyncIterator` as a {@link Subscription}.
  *
+ * @example
+ * ```ts
+ * import { subscribe } from "effection";
+ *
+ * let response = await fetch("https://example.com/data.bin");
+ * let iterator = response.body?.[Symbol.asyncIterator]();
+ *
+ * if (!iterator) throw new Error("response has no body");
+ *
+ * let subscription = subscribe(iterator);
+ * let first = yield* subscription.next();
+ * if (!first.done) {
+ *   console.log(first.value); // Uint8Array chunk
+ * }
+ * ```
+ *
  * @param iter - the iterator to convert
  * @returns a subscription that will produce each item of `iter`
  * @since 3.0
@@ -22,6 +38,19 @@ export function subscribe<T, R>(iter: AsyncIterator<T, R>): Subscription<T, R> {
  *
  * This allows you to consume any `AsyncIterable` as a {@link Stream}.
  *
+ * @example
+ * ```ts
+ * import { each, stream, until } from "effection";
+ *
+ * let response = yield* until(fetch("https://example.com/data.bin"));
+ * if (!response.body) throw new Error("response has no body");
+ *
+ * for (let chunk of yield* each(stream(response.body))) {
+ *   console.log(chunk.byteLength);
+ *   yield* each.next();
+ * }
+ * ```
+ *
  * @param iterable - the async iterable to convert
  * @returns a stream that will produce each item of `iterable`
  * @since 3.0
diff --git a/lib/call.ts b/lib/call.ts
@@ -12,6 +12,7 @@ import type { Operation } from "./types.ts";
  * APIs that accept `Callable` values allow end developers to pass simple
  * functions without necessarily needing to know anything about Operations.
  *
+ * @example
  * ```javascript
  * function hello(to: Callable<string>): Operation<string> {
  *   return function*() {
@@ -21,7 +22,7 @@ import type { Operation } from "./types.ts";
  *
  * await run(() => hello(() => "world!")); // => "hello world!"
  * await run(() => hello(async () => "world!")); // => "hello world!"
- * await run(() => hello(function*() { return "world!" })); "hello world!";
+ * await run(() => hello(function*() { return "world!" })); // => "hello world!"
  * ```
  * @since 3.0
  */
@@ -61,7 +62,7 @@ export interface Callable<
  *
  * The function will be invoked anew every time that the `call()` operation is evaluated.
  *
- * @param callable - the operation, promise, async function, generator funnction,
+ * @param callable - the operation, promise, async function, generator function,
  * 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
diff --git a/lib/channel.ts b/lib/channel.ts
@@ -7,6 +7,15 @@ 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.
+ *
+ * @example
+ * ```ts
+ * let channel = createChannel<string>();
+ * let subscription = yield* channel;
+ *
+ * yield* channel.send("hello");
+ * console.log(yield* subscription.next()); // { done: false, value: "hello" }
+ * ```
  * @since 3.0
  */
 export interface Channel<T, TClose> extends Stream<T, TClose> {
diff --git a/lib/context.ts b/lib/context.ts
@@ -5,6 +5,22 @@ import { Do } from "./do.ts";
 /**
  * Create a new {@link Context}
  *
+ * @example
+ * ```ts
+ * import { createContext, main } from "effection";
+ *
+ * const YourContext = createContext<string>("context-id");
+ *
+ * await main(function* () {
+ *   yield* YourContext.with("abc-123", function* () {
+ *     console.log(yield* YourContext.expect()); // "abc-123"
+ *   });
+ * });
+ * ```
+ *
+ * @example
+ * 
+ *
  * @param name - the unique name to give this context.
  * @returns the new context
  * @since 3.0
diff --git a/lib/each.ts b/lib/each.ts
@@ -10,6 +10,7 @@ import { withResolvers } from "./with-resolvers.ts";
  * Given any stream, you can access its values sequentially using the `each()`
  * operation just as you would use `for await of` loop with an async iterable:
  *
+ * @example
  * ```javascript
  * function* logvalues(stream) {
  *   for (let value of yield* each(stream)) {
@@ -18,6 +19,7 @@ import { withResolvers } from "./with-resolvers.ts";
  *   }
  * }
  * ```
+ *
  * You must always invoke `each.next` at the end of each iteration of the loop,
  * including if the interation ends with a `continue` statement.
  *
diff --git a/lib/events.ts b/lib/events.ts
@@ -23,6 +23,12 @@ export type EventList<T> = T extends {
  * Create an {@link Operation} that yields the next event to be emitted by an
  * [EventTarget](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget).
  *
+ * @example
+ * ```ts
+ * // wait for connection establishment before proceeding
+ * yield* once(socket, "open");
+ * ```
+ *
  * @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
@@ -48,6 +54,21 @@ export function once<
  * See the guide on [Streams and Subscriptions](https://frontside.com/effection/docs/collections)
  * for details on how to use streams.
  *
+ * @example
+ * ```ts
+ * import { each, on, once, spawn } from "effection";
+ *
+ * // handle socket errors in a concurrent child task
+ * yield* spawn(function* () {
+ *   throw yield* once(socket, "error");
+ * });
+ *
+ * for (let event of yield* each(on(socket, "message"))) {
+ *   console.log(event.data);
+ *   yield* each.next();
+ * }
+ * ```
+ *
  * @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
diff --git a/lib/interval.ts b/lib/interval.ts
@@ -5,6 +5,7 @@ import type { Stream } from "./types.ts";
 /**
  * Consume an interval as an infinite stream.
  *
+ * @example
  * ```ts
  * let startTime = Date.now();
  *
@@ -14,6 +15,7 @@ import type { Stream } from "./types.ts";
  *   yield* each.next();
  * }
  * ```
+ *
  * @param milliseconds - how long to delay between each item in the stream
  * @since 3.6
  */
diff --git a/lib/main.ts b/lib/main.ts
@@ -10,14 +10,15 @@ import { api } from "./api.ts";
  * Halt process execution immediately and initiate shutdown. If a message is
  * provided, it will be logged to the console after shutdown:
  *
+ * @example
  * ```js
  * if (invalidArgs()) {
  *   yield* exit(5, "invalid arguments")
  * }
  * ```
  * @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
+ * @returns an operation that exits the program
  * @since 3.0
  */
 export function* exit(status: number, message?: string): Operation<void> {
diff --git a/lib/queue.ts b/lib/queue.ts
@@ -7,6 +7,17 @@ import { action } from "./action.ts";
  * or a {@link Channel} as the mechanism, but `Queue` allows you to manage
  * a single subscription directly.
  *
+ * @example
+ * ```ts
+ * let queue = createQueue<number, void>();
+ * queue.add(1);
+ *
+ * let first = yield* queue.next();
+ * if (!first.done) {
+ *   console.log(first.value); // 1
+ * }
+ * ```
+ *
  * @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
@@ -37,9 +48,9 @@ export interface Queue<T, TClose> extends Subscription<T, TClose> {
  *
  * await main(function*() {
  *   let queue = createQueue<number>();
- *   queue.send(1);
- *   queue.send(2);
- *   queue.send(3);
+ *   queue.add(1);
+ *   queue.add(2);
+ *   queue.add(3);
  *
  *   let next = yield* queue.subscription.next();
  *   while (!next.done) {
diff --git a/lib/race.ts b/lib/race.ts
@@ -16,12 +16,21 @@ import { Err, Ok, type Result } from "./result.ts";
  * @example
  *
  * ```typescript
- * import { main, race, fetch } from 'effection';
+ * import { race, sleep } from "effection";
  *
- * await main(function*() {
- *  let fastest = yield* race([fetch('http://google.com'), fetch('http://bing.com')]);
- *  // ...
- * });
+ *   let fastest = yield* race([
+ *     call(function* () {
+ *       yield* sleep(100);
+ *       // this is halted as it loses the race
+ *       return "slow";
+ *     }),
+ *     call(function* () {
+ *       yield* sleep(10);
+ *       return "fast";
+ *     }),
+ *   ]);
+ *
+ *   console.log(fastest); // "fast"
  * ```
  *
  * @param operations a list of operations to race against each other
diff --git a/lib/resource.ts b/lib/resource.ts
@@ -79,12 +79,44 @@ export function resource<T>(
 }
 
 /**
+ * Provide `value` to the calling operation as a {@link resource}. You likely will not need
+ * to use this interface directly; instead, it is passed as an argument to `resource`.
+ * @returns an operation that suspends the resource operation until the caller is completed.
+ *
+ * @example
+ * ```ts
+ * type ConxPool = { ... } // example resource which manages a connection pool
+ *
+ * // preferred pattern in implementing a resource
+ * function useValue(): Operation<ConxPool> {
+ *   return resource(function* (provide) {
+ *     const pool: ConxPool = setupPool();
+ *     yield* provide(pool);
+ *   });
+ * }
+ * 
+ * // alternatively if you can't type the return value
+ * // then prefer typing the resource argument
+ * function useValue() {
+ *   return resource<ConxPool>(function* (provide) {
+ *     const pool: ConxPool = setupPool();
+ *     yield* provide(pool);
+ *   });
+ * }
+ * 
+ * // if neither pattern above is possible, then use `Provide<T>` directly
+ * function useValue() {
+ *   return resource(function* (provide: Provide<ConxPool>) {
+ *     const pool: ConxPool = setupPool();
+ *     yield* provide(pool);
+ *   });
+ * }
+ *
+ * console.log(yield* useValue()); // pool
+ * ```
+ *
  * @since 3.0
  */
 export interface Provide<T> {
-  /**
-   * Provide `value` to the calling operation as a resource.
-   * @returns an operation that suspends the resource operation until the caller is completed.
-   */
   (value: T): Operation<void>;
 }
diff --git a/lib/scope.ts b/lib/scope.ts
diff --git a/lib/types.ts b/lib/types.ts
diff --git a/lib/with-resolvers.ts b/lib/with-resolvers.ts

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,5 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@effection/effection",`
`3`		`- "exports": "./mod.ts",`
`4`	`3`	`"license": "ISC",`
`5`	`4`	`"publish": { "include": ["lib", "mod.ts", "experimental.ts", "README.md"] },`
`6`	`5`	`"lock": false,`
Original file line number	Diff line number	Diff line change
`@@ -10,8 +10,7 @@ import { trap } from "./task.ts";`
`10`	`10`	`*`
`11`	`11`	* If any of the operations become errored, then `all` will also become errored.
`12`	`12`	`*`
`13`		`- * ### Example`
`14`		`- *`
	`13`	`+ * @example`
`15`	`14`	* ``` javascript
`16`	`15`	`* import { all, expect, main } from 'effection';`
`17`	`16`	`*`
Original file line number	Diff line number	Diff line change
`@@ -12,6 +12,7 @@ import type { Operation } from "./types.ts";`
`12`	`12`	* APIs that accept `Callable` values allow end developers to pass simple
`13`	`13`	`* functions without necessarily needing to know anything about Operations.`
`14`	`14`	`*`
	`15`	`+ * @example`
`15`	`16`	* ```javascript
`16`	`17`	`* function hello(to: Callable<string>): Operation<string> {`
`17`	`18`	`* return function*() {`
`@@ -21,7 +22,7 @@ import type { Operation } from "./types.ts";`
`21`	`22`	`*`
`22`	`23`	`* await run(() => hello(() => "world!")); // => "hello world!"`
`23`	`24`	`* await run(() => hello(async () => "world!")); // => "hello world!"`
`24`		`- * await run(() => hello(function*() { return "world!" })); "hello world!";`
	`25`	`+ * await run(() => hello(function*() { return "world!" })); // => "hello world!"`
`25`	`26`	* ```
`26`	`27`	`* @since 3.0`
`27`	`28`	`*/`
`@@ -61,7 +62,7 @@ export interface Callable<`
`61`	`62`	`*`
`62`	`63`	* The function will be invoked anew every time that the `call()` operation is evaluated.
`63`	`64`	`*`
`64`		`- * @param callable - the operation, promise, async function, generator funnction,`
	`65`	`+ * @param callable - the operation, promise, async function, generator function,`
`65`	`66`	`* or plain function to call as part of this operation`
`66`	`67`	`*`
`67`	`68`	`* @returns an {@link Operation} that evaluates to the result of executing the function to completion`