effect-playwright 0.1.0 → 0.1.2

package/README.md

@@ -1,10 +1,15 @@
 # effect-playwright
 
+[![NPM Version](https://img.shields.io/npm/v/effect-playwright)](https://www.npmjs.com/package/effect-playwright)
 [![GitHub License](https://img.shields.io/github/license/Jobflow-io/effect-playwright)](https://github.com/Jobflow-io/effect-playwright/blob/main/LICENSE)
 [![Effect: yes](https://img.shields.io/badge/effect-yes-blue)](https://effect.website/)
+[![Documentation](https://img.shields.io/badge/view_documentation-purple)](https://jobflow-io.github.io/effect-playwright/modules/index.html)
 
 A Playwright wrapper for the Effect ecosystem. This library provides a set of services and layers to interact with Playwright in a type-safe way using Effect.
 
+> [!NOTE]
+> This library is currently focused on using Playwright for **automation** and **scraping**. It does not provide a wrapper for `@playwright/test` (the test runner).
+
 ## Installation
 
 ```bash
@@ -17,6 +22,8 @@ or
 npm install effect-playwright playwright-core
 ```
 
+You can also install `playwright` instead of `playwright-core` if you want the post-build auto install of the browsers.
+
 ## Quick Start
 
 ```ts
@@ -49,6 +56,36 @@ const program = Effect.gen(function* () {
 }).pipe(Effect.scoped);
 ```
 
+## Connecting via CDP
+
+You can connect to an existing browser instance using the Chrome DevTools Protocol (CDP).
+
+```ts
+const program = Effect.gen(function* () {
+  const playwright = yield* Playwright;
+
+  // Use connectCDPScoped to automatically close the CONNECTION when the scope ends
+  // Note: This does NOT close the browser process itself, only the CDP connection.
+  const browser = yield* playwright.connectCDPScoped("http://localhost:9222");
+
+  const page = yield* browser.newPage();
+  // ...
+}).pipe(Effect.scoped);
+```
+
+If you need to manage the connection lifecycle manually, use `connectCDP`:
+
+```ts
+const program = Effect.gen(function* () {
+  const playwright = yield* Playwright;
+  const browser = yield* playwright.connectCDP("http://localhost:9222");
+
+  // ... use browser ...
+
+  yield* browser.close;
+});
+```
+
 ## PlaywrightEnvironment (Experimental)
 
 The `PlaywrightEnvironment` simplifies setup by allowing you to configure the browser type and launch options once and reuse them across your application.
@@ -75,6 +112,55 @@ const program = Effect.gen(function* () {
 await Effect.runPromise(program.pipe(Effect.provide(liveLayer)));
 ```
 
+### `PlaywrightEnvironment.withBrowser`
+
+The `withBrowser` utility provides the `PlaywrightBrowser` service to your effect. It internally manages a `Scope`, which means the browser will be launched when the effect starts and closed automatically when the effect finishes (including on failure or interruption).
+
+```ts
+const program = Effect.gen(function* () {
+  const browser = yield* PlaywrightBrowser; // Now available in context
+  const page = yield* browser.newPage();
+
+  // ...
+  // Browser close is ensured
+}).pipe(PlaywrightEnvironment.withBrowser);
+```
+
+## Event Handling
+
+You can listen to Playwright events using the `eventStream` method. This returns an Effect `Stream` that emits events as they occur.
+
+> [!NOTE]
+> `eventStream` emits "Effectified" wrappers (e.g., `PlaywrightRequest`, `PlaywrightResponse`, `PlaywrightPage`) for most events. This allows you to continue using the Effect ecosystem seamlessly within your event handlers.
+
+The stream is automatically managed and will close when the underlying resource (like the Page or Browser) is closed.
+
+### Example: Monitoring Network Requests
+
+Since event streams run indefinitely until the resource closes, you often need to **fork** the resulting effect so it runs in the background without blocking your main program flow.
+
+```ts
+const program = Effect.gen(function* () {
+  const browser = yield* PlaywrightBrowser;
+  const page = yield* browser.newPage();
+
+  // Create a stream of request events
+  yield* page.eventStream("request").pipe(
+    Stream.runForEach((request) =>
+      Effect.gen(function* () {
+        const url = yield* request.url;
+        yield* Effect.log(`Request: ${url}`);
+      }),
+    ),
+
+    // Fork to run it in the background
+    Effect.fork,
+  );
+
+  yield* page.goto("https://example.com");
+}).pipe(PlaywrightEnvironment.withBrowser);
+```
+
 ## Accessing Native Playwright
 
 If you need to access functionality from the underlying Playwright objects that isn't directly exposed, you can use the `use` method available on most services/objects (browsers, pages, locators).

package/dist/experimental/index.d.mts

@@ -1,4 +1,4 @@
-import { d as PlaywrightError, o as PlaywrightBrowser } from "../index-aR0Fa_4Y.mjs";
+import { o as PlaywrightBrowser, x as PlaywrightError } from "../index-BTxElyN5.mjs";
 import { Context, Effect, Layer } from "effect";
 import { BrowserType, LaunchOptions } from "playwright-core";
 import { Scope as Scope$1 } from "effect/Scope";
@@ -13,9 +13,9 @@ declare const PlaywrightEnvironment_base: Context.TagClass<PlaywrightEnvironment
 /**
  * Most of the time you want to use the same kind of browser and configuration every time you use Playwright.
  * `PlaywrightEnvironment` is a service that allows you to configure how browsers are launched once. You can then
- * use {@link PlaywrightEnvironment.browser} to start browsers scoped to the current lifetime. They will be closed when the scope is closed.
+ * use `PlaywrightEnvironment.browser` to start browsers scoped to the current lifetime. They will be closed when the scope is closed.
  *
- * You can use {@link PlaywrightEnvironment.withBrowser} to provide the `PlaywrightBrowser` service to the wrapped effect. This
+ * You can use {@link withBrowser} to provide the `PlaywrightBrowser` service to the wrapped effect. This
  * also allows you to re-use the same browser as many times as you want.
  *
  * @since 0.1.0
@@ -35,10 +35,11 @@ declare class PlaywrightEnvironment extends PlaywrightEnvironment_base {}
  *
  * // use the layer
  * const program = Effect.gen(function* () {
- *   const browser = yield* PlaywrightEnvironment.browser;
+ *   const playwright = yield* PlaywrightEnvironment;
+ *   const browser = yield* playwright.browser;
  *   const page = yield* browser.newPage();
  *   yield* page.goto("https://example.com");
- * }).pipe(PlaywrightEnvironment.withBrowser, Effect.provide(playwrightEnv));
+ * }).pipe(Effect.scoped, Effect.provide(playwrightEnv));
  * ```
  *
  * @param browser - The Playwright BrowserType implementation (e.g. `chromium`, `firefox`, `webkit`).
@@ -59,15 +60,17 @@ declare const layer: (browser: BrowserType, launchOptions?: LaunchOptions) => La
  * import { PlaywrightEnvironment } from "effect-playwright/experimental";
  * import { chromium } from "playwright-core";
  *
- * const layer = PlaywrightEnvironment.layer(chromium);
+ * const env = PlaywrightEnvironment.layer(chromium);
+ *
  * const program = Effect.gen(function* () {
  *     const browser = yield* PlaywrightBrowser;
  *     const page = yield* browser.newPage();
  *     yield* page.goto("https://example.com");
- * }).pipe(PlaywrightEnvironment.withBrowser);
+ * }).pipe(PlaywrightEnvironment.withBrowser, Effect.provide(env));
  * ```
  *
  * @since 0.1.0
+ * @category util
  */
 declare const withBrowser: <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, PlaywrightError | E, PlaywrightEnvironment | Exclude<R, PlaywrightBrowser>>;
 //#endregion

package/dist/experimental/index.mjs

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "../chunk-BiucMVzj.mjs";
-import { n as PlaywrightBrowser, t as Playwright } from "../src-DveiwW4g.mjs";
+import { n as PlaywrightBrowser, t as Playwright } from "../src-D0uXY5ik.mjs";
 import { Context, Effect, Layer } from "effect";
 
 //#region src/experimental/environment.ts
@@ -11,9 +11,9 @@ var environment_exports = /* @__PURE__ */ __exportAll({
 /**
 * Most of the time you want to use the same kind of browser and configuration every time you use Playwright.
 * `PlaywrightEnvironment` is a service that allows you to configure how browsers are launched once. You can then
-* use {@link PlaywrightEnvironment.browser} to start browsers scoped to the current lifetime. They will be closed when the scope is closed.
+* use `PlaywrightEnvironment.browser` to start browsers scoped to the current lifetime. They will be closed when the scope is closed.
 *
-* You can use {@link PlaywrightEnvironment.withBrowser} to provide the `PlaywrightBrowser` service to the wrapped effect. This
+* You can use {@link withBrowser} to provide the `PlaywrightBrowser` service to the wrapped effect. This
 * also allows you to re-use the same browser as many times as you want.
 *
 * @since 0.1.0
@@ -33,10 +33,11 @@ var PlaywrightEnvironment = class extends Context.Tag("effect-playwright/experim
 *
 * // use the layer
 * const program = Effect.gen(function* () {
-*   const browser = yield* PlaywrightEnvironment.browser;
+*   const playwright = yield* PlaywrightEnvironment;
+*   const browser = yield* playwright.browser;
 *   const page = yield* browser.newPage();
 *   yield* page.goto("https://example.com");
-* }).pipe(PlaywrightEnvironment.withBrowser, Effect.provide(playwrightEnv));
+* }).pipe(Effect.scoped, Effect.provide(playwrightEnv));
 * ```
 *
 * @param browser - The Playwright BrowserType implementation (e.g. `chromium`, `firefox`, `webkit`).
@@ -61,15 +62,17 @@ const layer = (browser, launchOptions) => {
 * import { PlaywrightEnvironment } from "effect-playwright/experimental";
 * import { chromium } from "playwright-core";
 *
-* const layer = PlaywrightEnvironment.layer(chromium);
+* const env = PlaywrightEnvironment.layer(chromium);
+*
 * const program = Effect.gen(function* () {
 *     const browser = yield* PlaywrightBrowser;
 *     const page = yield* browser.newPage();
 *     yield* page.goto("https://example.com");
-* }).pipe(PlaywrightEnvironment.withBrowser);
+* }).pipe(PlaywrightEnvironment.withBrowser, Effect.provide(env));
 * ```
 *
 * @since 0.1.0
+* @category util
 */
 const withBrowser = Effect.provide(PlaywrightEnvironment.pipe(Effect.map((e) => e.browser), Effect.flatten, Layer.scoped(PlaywrightBrowser)));