feat: adding defineConfig and reroute function exports (#66)

* feat: adding defineConfig and reroute function exports

* chore: add changset

* chore: update README.md

* chore: update readme

Author: heyMP

.changeset/lovely-rats-glow.md

@@ -0,0 +1,27 @@
+---
+"@heymp/scratchpad": minor
+---
+
+Add config and playwright rerouting helpers
+
+Export `defineConfig`, `rerouteUrl`, `rerouteDocument`.
+
+Example:
+
+```ts
+import * as Scratchpad from '@heymp/scratchpad';
+
+export default Scratchpad.defineConfig({
+  devtools: true,
+  url: 'https://www.redhat.com/en',
+  playwright: async (args) => {
+    const { page } = args;
+    await Scratchpad.rerouteDocument(page, './pages');
+    await Scratchpad.rerouteUrl(page, {
+      type: 'path',
+      target: '**/rh-cta/rh-cta.js',
+      source: './rh-cta.js'
+    })
+  }
+});
+```

.gitignore

@@ -1,5 +1,7 @@
-node_modules
+# Dependencies
+node_modules/
 
-src/**.js
-src/**.d.ts
-src/**.d.ts.map
+# Compiled JavaScript and TypeScript definition files from the src directory
+src/**/*.js
+src/**/*.d.ts
+src/**/*.d.ts.map

README.md

@@ -11,6 +11,8 @@ https://github.com/heyMP/scratchpad/assets/3428964/2a58d587-510d-418f-bd8a-99958
 npx @heymp/scratchpad@next run ./my-test-file.js
 ```
 
+Note: This is still in development. Use the `next` tag until 1.0 release is ready.
+
 ## Commands
 
 ```bash
@@ -47,15 +49,116 @@ This allows you to interact with the Playwright API to perform actions like bloc
 network requests or navigating to different urls.
 
 ```js
-export default /** @type {import('@heymp/scratchpad/src/config').Config} */ ({
+export default ({
+  devtools: true,
+  url: 'https://google.com',
+  headless: true,
+});
+```
+
+#### Define Config
+
+While you can create a `scratchpad.config.js` file above without installing this package,
+it's recommended to install `@heymp/scratchpad` and use the `defineConfig` helper to access
+the correct types.
+
+**Usage:**
+
+`scratchpad.config.js`
+```ts
+import { defineConfig } from '@heymp/scratchpad';
+
+export default defineConfig({
   devtools: true,
+  url: 'https://google.com',
+  headless: true,
+});
+```
+
+#### Reroute Documents
+
+The `rerouteDocument` function allows you to replace the HTML content of any webpage with a local HTML file from your system. This is incredibly useful for testing changes or developing components in the context of a live site without deploying your code.
+
+When used, `rerouteDocument` also watches your local HTML file for changes. If you save an update to the file, the Playwright page will automatically reload to reflect your latest edits, providing a fast feedback loop.
+
+**How it works:**
+
+* It intercepts requests made by the Playwright `page` that are for HTML documents.
+* It maps the URL's path to a local file structure. For instance, if you are on `http://example.com/user/profile` and you've set your local directory to `'./my-pages'`, the function will look for `'./my-pages/user/profile/index.html'`.
+
+**Usage:**
+
+You would typically use this function within the `playwright` async method in your `scratchpad.config.js`:
+
+`scratchpad.config.js`
+```javascript
+import { defineConfig, rerouteDocument } from '@heymp/scratchpad';
+
+export default defineConfig({
+  url: 'https://example.com', // The initial URL you are working with
   playwright: async (args) => {
-    const { context, page } = args;
-    // block esmodule shims
-    await context.route(/es-module-shims\.js/, async route => {
-      await route.abort();
+    const { page } = args;
+
+    // Tell Scratchpad to serve local HTML files from the './pages' directory
+    // whenever a document is requested.
+    await rerouteDocument(page, './pages');
+
+    // Now, if you navigate to https://example.com/some/path,
+    // Scratchpad will try to serve './pages/some/path/index.html'.
+    // If that file doesn't exist, it will load the original page from the web.
+  }
+});
+```
+
+#### Reroute URLs
+
+The `rerouteUrl` function gives you the power to intercept network requests for specific assets (like JavaScript files, CSS, images, or API calls) and redirect them. You can reroute a `target` URL to either another live `source` URL or to a `source` local file from your system. This is incredibly useful for testing local versions of assets against a live site, mocking API responses, or redirecting to different service endpoints without deploying code.
+
+If you save an update to this file, the Playwright page will automatically reload to show your latest edits, creating a very fast development feedback loop.
+
+**How it works:**
+
+* It uses Playwright's `page.route()` to intercept network requests that match the `target` URL or pattern you specify.
+* If you set `type: 'url'`, it fetches the content from your specified `source` URL instead of the original `target`.
+* If you set `type: 'path'`, it serves the content from your local `source` file. It also starts watching this file, and if any changes are detected, it reloads the page.
+
+**Usage:**
+
+You typically use `rerouteUrl` within the `playwright` async method in your configuration file (e.g., `scratchpad.config.js`):
+
+`scratchpad.config.js`
+```javascript
+import * as Scratchpad from '@heymp/scratchpad';
+
+export default Scratchpad.defineConfig({
+  url: 'https://www.your-website.com',
+  playwright: async (args) => {
+    const { page } = args;
+
+    // Example 1: Reroute a specific JavaScript file to a local version
+    await Scratchpad.rerouteUrl(page, {
+      type: 'path',
+      target: '**/scripts/main-app.js', // Intercept requests for this JS file
+      source: './local-dev/main-app.js'  // Serve your local version instead
+    });
+
+    // Example 2: Reroute an API call to a different endpoint
+    await Scratchpad.rerouteUrl(page, {
+      type: 'url',
+      target: 'https://api.production.com/data', // Original API endpoint
+      source: 'https://api.staging.com/data'     // Reroute to staging API
+    });
+
+    // Example 3: Reroute an API call to a local mock JSON file
+    await Scratchpad.rerouteUrl(page, {
+      type: 'path',
+      target: 'https://api.production.com/user/settings',
+      source: './mocks/user-settings.json' // Serve local mock data
     });
-    await page.goto('https://ux.redhat.com');
+
+    // Now, when the page requests '**/scripts/main-app.js',
+    // your local './local-dev/main-app.js' will be served and auto-reloaded on change.
+    // Requests to 'https://api.production.com/data' will go to the staging API.
   }
 });
 ```
@@ -106,14 +209,15 @@ log(undefined);
 You can provide your own custom exposed functions using the `scratchpad.config.js` file.
 
 ```.js
+import * as Scratchpad from '@heymp/scratchpad';
 import { join } from 'node:path'
 import fs from 'node:fs/promises';
 
 function loadFile(path) {
   return fs.readFile(join(process.cwd(), path), 'utf8');
 }
 
-export default /** @type {import('@heymp/scratchpad/src/config').Config} */ ({
+export default defineConfig({
   playwright: async (args) => {
     const { context, page } = args;
     await context.exposeFunction('loadFile', loadFile)
@@ -149,14 +253,13 @@ yourself.
 }
 ```
 
-An alternatice to the `tsconfig.json` file is to use the following triple-slash comment
+An alternative to the `tsconfig.json` file is to use the following triple-slash comment
 in your `.ts` files:
 
 ```ts
 /// <reference path="./node_modules/@heymp/scratchpad/types.d.ts" />
 ```
 
-
 ## Development
 
 ```bash

package.json

@@ -2,11 +2,18 @@
   "name": "@heymp/scratchpad",
   "description": "Run TS/JS snippets in a locally",
   "version": "1.0.0-next.13",
-  "main": "bin/cli.js",
+  "main": "src/lib/index.js",
+  "module": "src/lib/index.js",
   "type": "module",
   "bin": {
     "scratchpad": "bin/cli.js"
   },
+  "exports": {
+    ".": {
+      "types": "./src/lib/index.d.ts.js",
+      "default": "./src/lib/index.js"
+    }
+  },
   "files": [
     "bin/cli.js",
     "src/**",

src/lib/index.ts

@@ -0,0 +1,151 @@
+import { readFile } from 'node:fs/promises';
+import fs from 'node:fs';
+import { join } from 'node:path';
+import type { Page } from 'playwright';
+import type { RerouteUrlParams } from './types.js';
+import { Config } from '../config.js';
+import type { PathLike } from 'node:fs';
+
+/**
+ * Defines the configuration for the application.
+ * This function simply returns the configuration object passed to it,
+ * often used for type-checking and providing a clear entry point for configuration.
+ * @param {Config} config - The configuration object.
+ * @returns {Config} The configuration object.
+ */
+export function defineConfig(config: Config) {
+  return config;
+}
+
+/**
+ * Reroutes document requests to local files within a specified directory.
+ * It intercepts 'document' type requests and attempts to serve a corresponding
+ * 'index.html' file from the local file system. It also watches the local file
+ * for changes and reloads the page if a change is detected.
+ * @async
+ * @param {Page} context - The Playwright Page object to apply the rerouting to.
+ * @param {string} dir - The root directory where the local page files (e.g., 'about/index.html') are stored.
+ * @returns {Promise<void>} A promise that resolves when the routing has been set up.
+ */
+export async function rerouteDocument(context: Page, dir: string) {
+  // reload the page if the document has been changed
+  const watchCallback = () => {
+    context.reload();
+  }
+
+  await context.route('**', async route => {
+    const resourceType = route.request().resourceType();
+    if (resourceType !== 'document') {
+      await route.fallback();
+      return;
+    }
+    const pageName = new URL(route.request().url())
+      .pathname
+      .replace(/^\//, '');
+    const pagePath = join(dir, `${pageName}/index.html`);
+
+    // watch file for changes
+    watchFile(pagePath, watchCallback);
+
+    const dashboardHtml = await readFile(join(process.cwd(), pagePath), 'utf8')
+      .catch(() => null);
+
+    if (dashboardHtml) {
+      const response = await route.fetch();
+      await route.fulfill({
+        response,
+        body: dashboardHtml
+      });
+      console.log(`\x1b[33m 🚸 Page override:\x1b[0m ${pagePath}`);
+    } else {
+      await route.fallback();
+    }
+  });
+}
+
+/**
+ * Reroutes network requests for a given Playwright Page context.
+ * It can reroute a target URL to another URL or to a local file path.
+ * If rerouting to a local file path, it watches the file for changes and
+ * reloads the page if the file is modified.
+ * @async
+ * @param {Page} context - The Playwright Page object to apply the rerouting to.
+ * @param {RerouteUrlParams} options - An object containing the rerouting parameters.
+ * @param {('url' | 'path')} options.type - The type of rerouting: 'url' to reroute to another URL,
+ * 'path' to reroute to a local file.
+ * @param {string | RegExp} options.target - The URL or pattern to intercept and reroute.
+ * @param {string} options.source - The source URL or local file path to reroute to.
+ * @returns {Promise<void>} A promise that resolves when the routing has been set up.
+ */
+export async function rerouteUrl(context: Page, options: RerouteUrlParams) {
+  const { type, target, source } = options;
+  // reload the page if the document has been changed
+  const watchCallback = () => {
+    context.reload();
+  }
+
+  if (type === 'url') {
+    await context.route(target, async route => {
+      const response = await route.fetch({
+        url: source,
+      });
+      await route.fulfill({ response })
+      console.log(`\x1b[33m 🚸 Reroute url:\x1b[0m ${target} → ${source}`);
+    });
+    return;
+  }
+  if (type === 'path') {
+    const path = join(process.cwd(), source);
+
+    // watch the file for changes
+    watchFile(path, watchCallback);
+
+    await context.route(target, async route => {
+      const file = await readFile(path, 'utf8')
+        .catch(() => null);
+      if (!file) {
+        console.warn(`\x1b[33m ⚠️ Could not read file for reroute:\x1b[0m ${path}`);
+        await route.abort(); // Abort the request if the file is not found
+        return;
+      }
+
+      const response = await route.fetch(); // Fetch original to get headers, status etc. if needed
+      await route.fulfill({
+        body: file,
+        response // Pass the original response to inherit headers, status (unless overridden)
+      });
+      console.log(`\x1b[33m 🚸 Reroute url:\x1b[0m ${target} → ${source}`);
+    });
+  }
+}
+
+/**
+ * Watches a file for changes and executes a callback function when the file is modified.
+ * It ensures that a file is not watched multiple times by attempting to unwatch it first.
+ * Handles cases where the file might not exist.
+ * @async
+ * @param {PathLike} path - The path to the file to watch.
+ * @param {() => void} callback - The function to call when the file changes.
+ * @returns {Promise<void>} A promise that resolves when the file watching is set up or if an error occurs during setup.
+ * It does not wait for file changes themselves.
+ */
+async function watchFile(path: PathLike, callback: () => void): Promise<void> {
+  try {
+    // Check if file exists first
+    if (!fs.existsSync(path)) {
+      return;
+    }
+
+    // Try to unwatch, but don't throw if it fails
+    try {
+      fs.unwatchFile(path, callback);
+    } catch (e) {
+      // Ignore unwatch errors, e.g., if the file was not previously watched with the same callback
+    }
+
+    // Set up new watch
+    fs.watchFile(path, { interval: 100 }, callback);
+  } catch (e: unknown) {
+    console.error(`watchFile: Failed to watch file ${path.toString()}:`, e);
+  }
+}