📝 Add Library Integration guide for Promise-based API pattern

Add documentation for using Effection inside a library while exposing
a traditional Promise-based API to clients. The pattern uses createScope(),
withResolvers(), resource(), and suspend() to bridge between Effection's
structured concurrency and async/await.

- Create docs/library-integration.mdx with full pattern and example
- Add to Advanced section in structure.json
- Add cross-reference from scope.mdx
- Add FAQ entry pointing to the guide

Author: Taras Mankovski

docs/faq.mdx

@@ -142,3 +142,12 @@ class Foo {
 const foo = new Foo();
 console.log(yield * foo.getData());
 ```
+
+## How do I use Effection inside a library while exposing a Promise-based API?
+
+Use `createScope()` to create an integration point, `withResolvers()` to
+synchronize initialization, and `scope.run()` to bridge between Effection
+operations and Promises.
+
+See the full [Library Integration](/docs/library-integration) guide for a
+complete example.

docs/library-integration.mdx

@@ -0,0 +1,237 @@
+You build a library with a Promise API. Your users call `await client.query()`
+and move on. Internally, though, you need stronger lifecycle guarantees than
+promises can give you. You need requests, sockets, subscriptions, and cleanup
+tied to one owner. You need work to stop when the library shuts down.
+
+This is where Effection fits behind a Promise API.
+
+The integration boundary is a scope. You create a scope once, initialize your
+stateful resource inside it, and keep that scope alive until shutdown. Then you
+expose plain methods that call `scope.run(() => operation)`. `scope.run()`
+returns a promise, so clients stay in normal `async/await`, while your internal
+work stays under structured concurrency.
+
+Startup is the place most libraries get this wrong. Initialization is async,
+method calls can arrive early, and now you have races between "pool is ready"
+and "query is called." `withResolvers()` gives you a single readiness operation
+that every public method can `yield*` before touching state.
+
+```typescript
+import {
+  createScope,
+  resource,
+  spawn,
+  sleep,
+  suspend,
+  until,
+  withResolvers,
+  type Operation,
+  type Task,
+} from "effection";
+
+interface QueryResult {
+  rows: unknown[];
+}
+
+interface Connection {
+  id: string;
+  execute(query: string): Operation<QueryResult>;
+}
+
+interface PoolState {
+  connections: Connection[];
+  available: Connection[];
+  acquire(): Operation<Connection>;
+  release(conn: Connection): void;
+}
+
+// stand-in for real IO
+function connectToDatabase(): Promise<{ close(): void }> {
+  return Promise.resolve({ close() {} });
+}
+
+// Connection with proper lifecycle via resource()
+function connection(id: string): Operation<Connection> {
+  return resource(function* (provide) {
+    const socket = yield* until(connectToDatabase());
+
+    const conn: Connection = {
+      id,
+      *execute(_query: string) {
+        return { rows: [] };
+      },
+    };
+
+    try {
+      yield* provide(conn);
+    } finally {
+      socket.close();
+    }
+  });
+}
+
+// Pool as a resource
+function connectionPool(maxConnections: number): Operation<PoolState> {
+  return resource(function* (provide) {
+    const connections: Connection[] = [];
+    const available: Connection[] = [];
+
+    for (let i = 0; i < maxConnections; i++) {
+      const conn = yield* connection(`conn-${i}`);
+      connections.push(conn);
+      available.push(conn);
+    }
+
+    const state: PoolState = {
+      connections,
+      available,
+      *acquire() {
+        while (available.length === 0) {
+          yield* sleep(50);
+        }
+        return available.pop()!;
+      },
+      release(conn) {
+        available.push(conn);
+      },
+    };
+
+    yield* provide(state);
+  });
+}
+
+// PUBLIC: Promise-based API
+export interface ConnectionPool extends AsyncDisposable {
+  query(sql: string): Promise<QueryResult>;
+  queryAll(queries: string[]): Promise<QueryResult[]>;
+  shutdown(): Promise<void>;
+}
+
+export function createPool(
+  options: { maxConnections: number },
+): ConnectionPool {
+  const [scope, destroy] = createScope();
+  const { operation: poolReady, resolve, reject } = withResolvers<PoolState>();
+
+  let closed = false;
+
+  scope.run(function* () {
+    try {
+      const pool = yield* connectionPool(options.maxConnections);
+      resolve(pool);
+      yield* suspend();
+    } catch (e) {
+      reject(e instanceof Error ? e : new Error(String(e)));
+    }
+  });
+
+  function* executeQuery(sql: string): Operation<QueryResult> {
+    if (closed) {
+      throw new Error("Pool is shut down");
+    }
+
+    const pool = yield* poolReady;
+    const conn = yield* pool.acquire();
+    try {
+      return yield* conn.execute(sql);
+    } finally {
+      pool.release(conn);
+    }
+  }
+
+  async function shutdown(): Promise<void> {
+    if (closed) return;
+    closed = true;
+    await destroy();
+  }
+
+  return {
+    query(sql: string): Promise<QueryResult> {
+      return scope.run(() => executeQuery(sql));
+    },
+
+    queryAll(queries: string[]): Promise<QueryResult[]> {
+      return scope.run(function* () {
+        const tasks: Task<QueryResult>[] = [];
+        for (const sql of queries) {
+          tasks.push(yield* spawn(() => executeQuery(sql)));
+        }
+
+        const results: QueryResult[] = [];
+        for (const task of tasks) {
+          results.push(yield* task);
+        }
+        return results;
+      });
+    },
+
+    shutdown,
+
+    [Symbol.asyncDispose](): Promise<void> {
+      return shutdown();
+    },
+  };
+}
+```
+
+Two lines here carry the weight.
+
+First, `spawn()` returns an operation, and `yield* spawn(...)` starts it.
+Operations are lazy, promises are eager.
+
+Second, `scope.run(() => executeQuery(sql))` keeps each query inside the same
+owning scope as the pool. Returning a promise to the caller does not let that
+work escape. If shutdown starts, in-flight work is halted with the rest of
+the scope.
+
+`resource()` and `suspend()` are what make this stable over time. `resource()`
+gives setup-before-use and cleanup in `finally`. `suspend()` keeps the scope
+resident so resources stay alive between calls. `destroy()` is teardown
+completion. Await it, or you can return from shutdown before `finally` blocks
+finish.
+
+You can expose explicit shutdown, or add async disposal so callers can use
+language-level cleanup.
+
+```typescript
+// Manual cleanup
+const pool = createPool({ maxConnections: 10 });
+const result = await pool.query("SELECT * FROM users");
+await pool.shutdown();
+
+// Automatic cleanup with await using
+await using autoPool = createPool({ maxConnections: 10 });
+const result2 = await autoPool.query("SELECT * FROM users");
+// cleanup runs automatically
+```
+
+## Gotchas
+
+**Guard against post-shutdown calls.** `scope.run()` can still be invoked after
+`destroy()` completes. Track a `closed` flag and reject new calls after
+shutdown, as shown in the example above.
+
+**Await destruction.** `destroy()` returns a future. If you don't await it,
+teardown may not complete before your process exits. Always `await shutdown()`
+or use `await using`.
+
+**In-flight work during shutdown.** When `destroy()` is called, any operations
+currently running via `scope.run()` are halted. Their `finally` blocks still
+execute, so cleanup happens, but the promises returned to callers will reject
+with a "halted" error.
+
+**Startup failures propagate.** If initialization throws, `reject()` is called
+once, and every caller waiting on `poolReady` receives the same error. This is
+deterministic and usually what you want.
+
+That is the whole pattern: one integration scope, one readiness gate, internal
+resources as operations, external methods as promises. Your users write `await`,
+you get structured shutdown.
+
+[createScope]: /api/v4/createScope
+[resource]: /api/v4/resource
+[withResolvers]: /api/v4/withResolvers
+[suspend]: /api/v4/suspend
+[until]: /api/v4/until
+[Scope]: /api/v4/Scope
+[spawn]: /api/v4/spawn

docs/scope.mdx

@@ -381,6 +381,9 @@ Whenever you use `createScope()` in this way, it is important that you
 `await` the destruction operation when the scope is no longer needed
 since it will not be destroyed implicitly.
 
+> 💡 For a complete example of using `createScope()` to build a library that
+> exposes a Promise-based API, see the [Library Integration](/docs/library-integration) guide.
+
 [spawn]: /api/v4/spawn
 [use-abort-signal]: /api/v4/useAbortSignal
 [scope]: /api/v4/Scope

docs/structure.json

@@ -20,6 +20,7 @@
   "Advanced": [
     ["faq.mdx", "FAQ"],
     ["scope.mdx", "Scope"],
-    ["processes.mdx", "Processes"]
+    ["processes.mdx", "Processes"],
+    ["library-integration.mdx", "Library Integration"]
   ]
 }