@megabudino/stack-utils 1.2.1 → 1.3.0

package/README.md

@@ -53,13 +53,15 @@ Proxy config:
 | `sitemapCacheSeconds` | `number` | `3600` | Cache max-age for sitemap responses |
 | `proxyAssets` | `boolean` | `false` | Rewrite origin asset URLs to relative paths |
 | `additionalOrigins` | `string[]` | `[]` | Additional absolute origins to rewrite like `originUrl` |
+| `domActions` | `DomAction[]` | `[]` | Declarative DOM transformations for proxied HTML |
+| `textReplacements` | `Record<string, string>` | `{}` | Final string replacements applied after DOM actions |
 
 What it does:
 
 - lets SvelteKit routes resolve normally when a route exists
 - proxies unmatched requests to the configured origin
 - rewrites redirects back to the public domain
-- rewrites HTML and injects extra sitemap entries when configured
+- rewrites HTML, applies optional DOM actions, and injects extra sitemap entries when configured
 
 ### `images`
 

package/dist/proxy/dom-actions.d.ts

@@ -0,0 +1,9 @@
+import type { DomAction } from './types.js';
+/**
+ * Apply declarative DOM actions in array order.
+ *
+ * Actions run after the proxy's standard HTML rewrites so selectors see the
+ * final proxied markup shape, and before `textReplacements` so the legacy
+ * string-based pass remains the last low-level override.
+ */
+export declare function applyDomActions(html: string, actions: DomAction[]): string;

package/dist/proxy/dom-actions.js

@@ -0,0 +1,47 @@
+import { load } from 'cheerio';
+/**
+ * Apply declarative DOM actions in array order.
+ *
+ * Actions run after the proxy's standard HTML rewrites so selectors see the
+ * final proxied markup shape, and before `textReplacements` so the legacy
+ * string-based pass remains the last low-level override.
+ */
+export function applyDomActions(html, actions) {
+    if (actions.length === 0) {
+        return html;
+    }
+    const $ = load(html);
+    for (const action of actions) {
+        const elements = $(action.selector);
+        if (elements.length === 0) {
+            continue;
+        }
+        if (action.remove) {
+            elements.remove();
+            continue;
+        }
+        if (action.setAttributes) {
+            for (const [name, value] of Object.entries(action.setAttributes)) {
+                elements.attr(name, value);
+            }
+        }
+        if (action.removeAttributes) {
+            for (const name of action.removeAttributes) {
+                elements.removeAttr(name);
+            }
+        }
+        if (action.addClass && action.addClass.length > 0) {
+            elements.addClass(action.addClass.join(' '));
+        }
+        if (action.removeClass && action.removeClass.length > 0) {
+            elements.removeClass(action.removeClass.join(' '));
+        }
+        if (action.setText !== undefined) {
+            elements.text(action.setText);
+        }
+        if (action.setHtml !== undefined) {
+            elements.html(action.setHtml);
+        }
+    }
+    return $.html();
+}

package/dist/proxy/handle.js

@@ -1,3 +1,4 @@
+import { applyDomActions } from './dom-actions.js';
 import { injectIntoSitemapIndex, rewriteHtml } from './rewrite.js';
 /**
  * Create a SvelteKit `Handle` hook that reverse-proxies requests to an origin.
@@ -12,6 +13,7 @@ export function createProxyHandle(config) {
     const proxyAssets = config.proxyAssets ?? false;
     const additionalOrigins = config.additionalOrigins ?? [];
     const maxRedirects = config.maxInternalRedirects ?? 5;
+    const domActions = config.domActions ?? [];
     const textReplacements = config.textReplacements ?? {};
     const siteHost = new URL(siteUrl).hostname;
     const originHosts = new Set([
@@ -83,6 +85,7 @@ export function createProxyHandle(config) {
             if (contentType.includes('text/html')) {
                 const html = await upstreamResponse.text();
                 let result = rewriteHtml(html, originUrl, siteUrl, proxyAssets, additionalOrigins);
+                result = applyDomActions(result, domActions);
                 for (const [search, replace] of Object.entries(textReplacements)) {
                     result = result.replaceAll(search, replace);
                 }

package/dist/proxy/index.d.ts

@@ -1,2 +1,2 @@
 export { createProxyHandle } from './handle.js';
-export type { ProxyConfig } from './types.js';
+export type { DomAction, ProxyConfig } from './types.js';

package/dist/proxy/types.d.ts

@@ -1,3 +1,25 @@
+/** Declarative DOM transformations applied to proxied HTML documents. */
+export interface DomAction {
+    /** CSS selector used to match elements in the proxied HTML document. */
+    selector: string;
+    /** Set or replace attributes on every matched element. */
+    setAttributes?: Record<string, string>;
+    /** Remove attributes from every matched element. */
+    removeAttributes?: string[];
+    /** Add CSS classes to every matched element. */
+    addClass?: string[];
+    /** Remove CSS classes from every matched element. */
+    removeClass?: string[];
+    /** Replace the text content of every matched element. */
+    setText?: string;
+    /** Replace the inner HTML of every matched element. */
+    setHtml?: string;
+    /**
+     * Remove every matched element.
+     * When true, removal takes precedence over all other fields in the same action.
+     */
+    remove?: boolean;
+}
 /** Configuration for the reverse proxy. */
 export interface ProxyConfig {
     /** The origin URL (not publicly exposed). */
@@ -37,4 +59,9 @@ export interface ProxyConfig {
      * using `String.prototype.replaceAll`.
      */
     textReplacements?: Record<string, string>;
+    /**
+     * Declarative DOM transformations applied to HTML responses after the
+     * standard proxy rewrites and before `textReplacements`.
+     */
+    domActions?: DomAction[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@megabudino/stack-utils",
-	"version": "1.2.1",
+	"version": "1.3.0",
 	"description": "Reusable utilities for a SvelteKit stack, including a reverse proxy and static image pipeline",
 	"type": "module",
 	"exports": {
@@ -32,6 +32,7 @@
 		"typecheck": "tsc --noEmit"
 	},
 	"dependencies": {
+		"cheerio": "^1.2.0",
 		"sharp": "^0.34.5"
 	},
 	"peerDependencies": {