npm - @megabudino/stack-utils - Versions diffs - 1.5.0 → 2.0.0 - Mend

@megabudino/stack-utils 1.5.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (22) hide show

package/README.md +16 -3
package/dist/proxy/client.d.ts +33 -0
package/dist/proxy/client.js +101 -0
package/dist/proxy/define-islands.d.ts +16 -0
package/dist/proxy/define-islands.js +21 -0
package/dist/proxy/handle.js +32 -5
package/dist/proxy/index.d.ts +2 -1
package/dist/proxy/index.js +1 -0
package/dist/proxy/islands.d.ts +51 -0
package/dist/proxy/islands.js +105 -0
package/dist/proxy/transform-html.d.ts +20 -0
package/dist/proxy/transform-html.js +80 -0
package/dist/proxy/types.d.ts +120 -32
package/dist/proxy/vite-plugin-core.d.ts +57 -0
package/dist/proxy/vite-plugin-core.js +288 -0
package/dist/proxy/vite-plugin.d.ts +2 -0
package/dist/proxy/vite-plugin.js +292 -0
package/dist/proxy/vite.d.ts +1 -0
package/dist/proxy/vite.js +1 -0
package/package.json +9 -1
package/dist/proxy/dom-actions.d.ts +0 -9
package/dist/proxy/dom-actions.js +0 -54

package/dist/proxy/types.d.ts CHANGED Viewed

@@ -1,39 +1,110 @@
-/** 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;
-    /**
-     * Insert HTML inside every matched element before its existing children.
-     *
-     * When combined with `setText` or `setHtml`, the content replacement runs
-     * first and `prependHtml` is inserted into the resulting element contents.
+import type { RequestEvent } from '@sveltejs/kit';
+import type { Cheerio, CheerioAPI } from 'cheerio';
+/**
+ * Activation mode for a Svelte island.
+ *
+ * - `serverOnly`: render the component server-side and freeze it as HTML.
+ *   No client runtime is involved; props can be anything.
+ * - `mount`: render server-side for first paint, then mount the component on
+ *   the client by replacing the SSR markup. Props must be JSON-serializable.
+ * - `hydrate`: render server-side and hydrate the existing markup in place
+ *   on the client. Requires that the server output and client component are
+ *   the exact same compiled Svelte 5 component and that props match.
+ */
+export type IslandMode = 'serverOnly' | 'mount' | 'hydrate';
+/**
+ * A registered Svelte component. Typed permissively so consumers can pass
+ * either a Svelte 5 function component or a legacy class component without
+ * coupling proxy types to Svelte type internals.
+ *
+ * Use `import Foo from './Foo.svelte'` and pass `Foo` directly.
+ */
+export type IslandComponent = any;
+/** Reference to a registered island for a `DomAction`. */
+export interface IslandSpec {
+    /** Registry key. Must exist in `ProxyConfig.islands.components`. */
+    name: string;
+    /**
+     * Props passed to the component. For `mount` and `hydrate` modes the props
+     * are JSON-serialized into the page so the client can rehydrate with the
+     * same input, so they must be JSON-safe.
+     */
+    props?: Record<string, unknown>;
+    /** Activation mode. Defaults to `'serverOnly'`. */
+    mode?: IslandMode;
+}
+/** Island registry and client bootstrap configuration. */
+export interface ProxyIslandsConfig {
+    /**
+     * Registry of components keyed by name. Names referenced by `DomAction.island`
+     * must exist in this registry or `createProxyHandle` throws.
+     */
+    components: Record<string, IslandComponent>;
+    /**
+     * URL of a client bootstrap script. When set, the proxy injects
+     * `<script type="module" src="${clientEntry}"></script>` at the end of the
+     * `<body>` whenever at least one `mount` or `hydrate` island is rendered on
+     * the page. Leave undefined to wire the script tag manually with
+     * `domActions.appendHtml`.
      */
-    prependHtml?: string;
+    clientEntry?: string;
     /**
-     * Insert HTML inside every matched element after its existing children.
+     * Optional stylesheet URLs that should be injected into the document head
+     * whenever at least one client island (`mount` or `hydrate`) is rendered.
      *
-     * When combined with `setText` or `setHtml`, the content replacement runs
-     * first and `appendHtml` is inserted into the resulting element contents.
+     * This is mainly useful for advanced/manual setups. When using the
+     * `proxyIslands()` Vite plugin, these URLs are auto-generated from the
+     * emitted client chunk CSS and should not need to be set by hand.
      */
-    appendHtml?: string;
+    clientStylesheets?: string[];
+}
+/**
+ * Cheerio wrapper around the elements passed to `TransformDomContext.renderIsland`.
+ *
+ * Loosely typed (`Cheerio<any>`) so consumers can pass whatever shape `$(selector)`
+ * returns without coupling to cheerio's element internals. Cheerio infers a
+ * narrower element type at the call site for any usage outside of this helper.
+ */
+export type TransformDomTarget = Cheerio<any>;
+/**
+ * Context object passed to a `transformDom` hook.
+ *
+ * Carries the SvelteKit request currently being proxied so the hook can make
+ * per-request decisions (e.g., based on URL, route id, cookies) and exposes a
+ * `renderIsland` helper that mirrors `domActions[i].island`: it renders a
+ * registered Svelte component into the matched elements, tags them so the
+ * client runtime can pick them up, and registers head fragments and the
+ * client bootstrap exactly once for the document.
+ */
+export interface TransformDomContext {
+    /** The SvelteKit request event for the proxied request. */
+    event: RequestEvent;
+    /** Shortcut for `event.url`. */
+    url: URL;
     /**
-     * Remove every matched element.
-     * When true, removal takes precedence over all other fields in the same action.
+     * Render a registered Svelte island into every element in `target`.
+     *
+     * Throws when `islands.components` is not configured on `ProxyConfig`,
+     * when the island name is unknown, or when props cannot be serialized for
+     * `mount` / `hydrate` modes. Server-rendered head fragments are deduped by
+     * exact string match and the client bootstrap is injected at most once per
+     * document.
      */
-    remove?: boolean;
+    renderIsland(target: TransformDomTarget, spec: IslandSpec): Promise<void>;
 }
+/**
+ * Arbitrary asynchronous transformation applied to proxied HTML documents.
+ *
+ * Runs after the standard proxy URL rewrites and after the legacy `domActions`
+ * pass (so it sees the same DOM the actions produced), and before
+ * `textReplacements` (which remain the last low-level override).
+ *
+ * The hook mutates the document via the cheerio root `$`. Returning a value is
+ * not supported — mutate `$` in place. The same `$` instance is used by
+ * `domActions` and the island bootstrap finalization, so all changes compose
+ * into a single rendered document.
+ */
+export type TransformDomHook = ($: CheerioAPI, ctx: TransformDomContext) => void | Promise<void>;
 type DeprecatedProxyOption<Message extends string> = {
     readonly __deprecatedProxyOption: Message;
 };
@@ -96,9 +167,26 @@ export interface ProxyConfig {
      */
     textReplacements?: Record<string, string>;
     /**
-     * Declarative DOM transformations applied to HTML responses after the
-     * standard proxy rewrites and before `textReplacements`.
+     * @deprecated Removed in v2. Express every DOM mutation directly inside
+     * `transformDom`, which receives the cheerio root and `ctx.renderIsland`.
+     * Passing this field is rejected at startup by `createProxyHandle`.
+     */
+    domActions?: DeprecatedProxyOption<'`domActions` was removed in v2. Express mutations with `transformDom` (cheerio root) and call `ctx.renderIsland(...)` for islands.'>;
+    /**
+     * Arbitrary asynchronous transformation applied to HTML responses.
+     *
+     * Receives the cheerio root `$` for the proxied document plus a context
+     * with the request `event`, the `url`, and a `renderIsland` helper that
+     * wires registered Svelte components and the client bootstrap.
+     *
+     * Runs after the standard URL rewrites and before `textReplacements`.
+     * Non-HTML responses are not affected.
+     */
+    transformDom?: TransformDomHook;
+    /**
+     * Svelte component registry and client bootstrap configuration for the
+     * islands feature. Required when `transformDom` calls `ctx.renderIsland(...)`.
      */
-    domActions?: DomAction[];
+    islands?: ProxyIslandsConfig;
 }
 export {};

package/dist/proxy/vite-plugin-core.d.ts ADDED Viewed

@@ -0,0 +1,57 @@
+export interface ProxyIslandComponentImport {
+    key: string;
+    localName: string;
+    source: string;
+    importKind: 'default' | 'named' | 'namespace';
+    importedName?: string;
+}
+export interface ProxyIslandsDeclaration {
+    variableName: string;
+    objectLiteralStart: number;
+    objectLiteralEnd: number;
+    hasClientEntry: boolean;
+    hasClientStylesheets: boolean;
+}
+export interface ExtractedProxyIslandsMetadata {
+    declarations: ProxyIslandsDeclaration[];
+    components: ProxyIslandComponentImport[];
+}
+export declare function needsAutoWiredAssets(metadata: ExtractedProxyIslandsMetadata): boolean;
+export declare function extractProxyIslandsMetadata(code: string, filePath: string): ExtractedProxyIslandsMetadata | null;
+export declare function buildProxyIslandsClientEntryModule(metadata: ExtractedProxyIslandsMetadata, hooksFilePath: string, generatedFilePath: string): string;
+export declare function injectAutoWiredIslandsConfig(code: string, metadata: ExtractedProxyIslandsMetadata, values: {
+    clientEntryExpression: string;
+    clientStylesheetsExpression: string;
+}): string;
+/**
+ * Build the public URL we inject into proxied HTML for a generated client
+ * bundle file or its associated CSS asset.
+ *
+ * The islands runtime sticks these URLs into the `<head>` (and end of `<body>`)
+ * of pages whose pathname has nothing to do with the bundle layout. Relative
+ * URLs like `./_app/...` only resolve correctly when the page itself sits at
+ * the site root, which makes the assets unreachable as soon as the proxy
+ * serves a nested URL. SvelteKit defaults `paths.relative` to true, so Vite's
+ * `base` resolves to `./` for the SvelteKit-rendered pages — fine for
+ * SvelteKit itself, useless for us. We therefore coerce to an absolute path
+ * starting with `/`, and only honour `base` when the consumer explicitly
+ * configured one (a base that starts with `/`).
+ */
+export declare function toPublicAssetUrl(fileName: string, base: string | undefined): string;
+/**
+ * In dev, `vite-plugin-svelte` serves a `<Component>.svelte?svelte&type=style&lang.css`
+ * module as a JS wrapper that imports `__vite__updateStyle` and calls it with
+ * the CSS literal:
+ *
+ *     const __vite__css = "<escaped css>"
+ *     __vite__updateStyle(__vite__id, __vite__css)
+ *
+ * To stop the islands runtime from triggering a flash, we need to ship a
+ * single real stylesheet up front (a `<link rel="stylesheet">` blocks render
+ * the way JS-injected `<style>` tags cannot). This pulls the raw CSS string
+ * out of that wrapper so the dev middleware can concatenate it across every
+ * island module.
+ */
+export declare function extractViteCssFromJs(jsCode: string): string;
+/** Match every module id we want to treat as a stylesheet for dev-time extraction. */
+export declare function isCssLikeModuleId(id: string | null | undefined): boolean;

package/dist/proxy/vite-plugin-core.js ADDED Viewed

@@ -0,0 +1,288 @@
+import path from 'node:path';
+import * as ts from 'typescript';
+export function needsAutoWiredAssets(metadata) {
+    return metadata.declarations.some((declaration) => !declaration.hasClientEntry || !declaration.hasClientStylesheets);
+}
+export function extractProxyIslandsMetadata(code, filePath) {
+    const sourceFile = ts.createSourceFile(filePath, code, ts.ScriptTarget.Latest, true, getScriptKind(filePath));
+    const importsByLocalName = collectImports(sourceFile);
+    const declarations = [];
+    const components = new Map();
+    function visit(node) {
+        if (ts.isVariableDeclaration(node) &&
+            ts.isIdentifier(node.name) &&
+            node.initializer &&
+            ts.isCallExpression(node.initializer) &&
+            isDefineProxyIslandsCall(node.initializer)) {
+            const objectLiteral = node.initializer.arguments[0];
+            if (!objectLiteral || !ts.isObjectLiteralExpression(objectLiteral)) {
+                throw new Error('[stack-utils proxy] `defineProxyIslands(...)` must receive a direct object literal.');
+            }
+            const componentsProperty = findObjectProperty(objectLiteral, 'components');
+            if (!componentsProperty || !ts.isObjectLiteralExpression(componentsProperty.initializer)) {
+                throw new Error('[stack-utils proxy] `defineProxyIslands(...)` requires `components: { ... }` as a direct object literal.');
+            }
+            declarations.push({
+                variableName: node.name.text,
+                objectLiteralStart: objectLiteral.getStart(sourceFile),
+                objectLiteralEnd: objectLiteral.getEnd(),
+                hasClientEntry: Boolean(findObjectProperty(objectLiteral, 'clientEntry')),
+                hasClientStylesheets: Boolean(findObjectProperty(objectLiteral, 'clientStylesheets'))
+            });
+            for (const property of componentsProperty.initializer.properties) {
+                if (ts.isSpreadAssignment(property)) {
+                    throw new Error('[stack-utils proxy] `defineProxyIslands({ components })` does not support spread syntax. List components explicitly.');
+                }
+                if (ts.isShorthandPropertyAssignment(property)) {
+                    const localName = property.name.text;
+                    const binding = importsByLocalName.get(localName);
+                    if (!binding) {
+                        throw new Error(`[stack-utils proxy] component "${localName}" must be imported directly in hooks.server.ts to enable auto-wiring.`);
+                    }
+                    registerComponent(components, {
+                        key: localName,
+                        localName,
+                        ...binding
+                    });
+                    continue;
+                }
+                if (ts.isPropertyAssignment(property)) {
+                    const key = readPropertyName(property.name);
+                    if (!key) {
+                        throw new Error('[stack-utils proxy] component keys in `defineProxyIslands({ components })` must be plain identifiers or string literals.');
+                    }
+                    if (!ts.isIdentifier(property.initializer)) {
+                        throw new Error(`[stack-utils proxy] component "${key}" must point directly to an imported identifier.`);
+                    }
+                    const localName = property.initializer.text;
+                    const binding = importsByLocalName.get(localName);
+                    if (!binding) {
+                        throw new Error(`[stack-utils proxy] component "${key}" must reference an imported identifier to enable auto-wiring.`);
+                    }
+                    registerComponent(components, {
+                        key,
+                        localName,
+                        ...binding
+                    });
+                    continue;
+                }
+                throw new Error('[stack-utils proxy] unsupported `components` entry. Use `Foo` or `Alias: Foo`.');
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    if (declarations.length === 0) {
+        return null;
+    }
+    return {
+        declarations,
+        components: [...components.values()]
+    };
+}
+export function buildProxyIslandsClientEntryModule(metadata, hooksFilePath, generatedFilePath) {
+    const importLines = [
+        `import { mountIslands } from '@megabudino/stack-utils/proxy/client';`,
+        ...metadata.components.map((component) => buildImportLine(component, hooksFilePath, generatedFilePath))
+    ];
+    const componentEntries = metadata.components.map((component) => component.key === component.localName
+        ? component.localName
+        : `${formatObjectKey(component.key)}: ${component.localName}`);
+    return [
+        '// Generated by @megabudino/stack-utils/proxy/vite.',
+        '// Do not edit by hand.',
+        ...importLines,
+        '',
+        'mountIslands({',
+        '\tcomponents: {',
+        ...componentEntries.map((entry) => `\t\t${entry},`),
+        '\t}',
+        '});',
+        ''
+    ].join('\n');
+}
+export function injectAutoWiredIslandsConfig(code, metadata, values) {
+    let transformed = code;
+    for (const declaration of [...metadata.declarations].sort((left, right) => right.objectLiteralStart - left.objectLiteralStart)) {
+        const objectLiteralSource = transformed.slice(declaration.objectLiteralStart, declaration.objectLiteralEnd);
+        const nextLiteral = appendMissingObjectProperties(objectLiteralSource, [
+            ...(!declaration.hasClientEntry
+                ? [`clientEntry: ${values.clientEntryExpression}`]
+                : []),
+            ...(!declaration.hasClientStylesheets
+                ? [`clientStylesheets: ${values.clientStylesheetsExpression}`]
+                : [])
+        ]);
+        transformed =
+            transformed.slice(0, declaration.objectLiteralStart) +
+                nextLiteral +
+                transformed.slice(declaration.objectLiteralEnd);
+    }
+    return transformed;
+}
+function collectImports(sourceFile) {
+    const importsByLocalName = new Map();
+    for (const statement of sourceFile.statements) {
+        if (!ts.isImportDeclaration(statement) || !statement.importClause) {
+            continue;
+        }
+        const source = statement.moduleSpecifier;
+        if (!ts.isStringLiteral(source)) {
+            continue;
+        }
+        const sourceText = source.text;
+        const clause = statement.importClause;
+        if (clause.name) {
+            importsByLocalName.set(clause.name.text, {
+                source: sourceText,
+                importKind: 'default'
+            });
+        }
+        const bindings = clause.namedBindings;
+        if (!bindings) {
+            continue;
+        }
+        if (ts.isNamespaceImport(bindings)) {
+            importsByLocalName.set(bindings.name.text, {
+                source: sourceText,
+                importKind: 'namespace'
+            });
+            continue;
+        }
+        for (const element of bindings.elements) {
+            importsByLocalName.set(element.name.text, {
+                source: sourceText,
+                importKind: 'named',
+                importedName: element.propertyName?.text ?? element.name.text
+            });
+        }
+    }
+    return importsByLocalName;
+}
+function isDefineProxyIslandsCall(node) {
+    return ts.isIdentifier(node.expression) && node.expression.text === 'defineProxyIslands';
+}
+function findObjectProperty(objectLiteral, name) {
+    return objectLiteral.properties.find((property) => ts.isPropertyAssignment(property) && readPropertyName(property.name) === name);
+}
+function readPropertyName(name) {
+    if (ts.isIdentifier(name) || ts.isStringLiteral(name)) {
+        return name.text;
+    }
+    return null;
+}
+function registerComponent(components, component) {
+    const existing = components.get(component.key);
+    if (!existing) {
+        components.set(component.key, component);
+        return;
+    }
+    const sameBinding = existing.localName === component.localName &&
+        existing.source === component.source &&
+        existing.importKind === component.importKind &&
+        existing.importedName === component.importedName;
+    if (!sameBinding) {
+        throw new Error(`[stack-utils proxy] island registry key "${component.key}" is declared more than once with different imports.`);
+    }
+}
+function buildImportLine(component, hooksFilePath, generatedFilePath) {
+    const source = resolveComponentImportSource(component.source, hooksFilePath, generatedFilePath);
+    if (component.importKind === 'default') {
+        return `import ${component.localName} from ${JSON.stringify(source)};`;
+    }
+    if (component.importKind === 'namespace') {
+        return `import * as ${component.localName} from ${JSON.stringify(source)};`;
+    }
+    if (component.importedName && component.importedName !== component.localName) {
+        return `import { ${component.importedName} as ${component.localName} } from ${JSON.stringify(source)};`;
+    }
+    return `import { ${component.localName} } from ${JSON.stringify(source)};`;
+}
+function resolveComponentImportSource(source, hooksFilePath, generatedFilePath) {
+    if (!source.startsWith('.')) {
+        return source;
+    }
+    const resolvedSourcePath = path.resolve(path.dirname(hooksFilePath), source);
+    const relativeSourcePath = path.relative(path.dirname(generatedFilePath), resolvedSourcePath);
+    const normalized = relativeSourcePath.split(path.sep).join('/');
+    return normalized.startsWith('.') ? normalized : `./${normalized}`;
+}
+function appendMissingObjectProperties(objectLiteralSource, properties) {
+    if (properties.length === 0) {
+        return objectLiteralSource;
+    }
+    const inner = objectLiteralSource.slice(1, -1);
+    const trimmedInner = inner.trim();
+    if (trimmedInner.length === 0) {
+        return `{\n\t${properties.join(',\n\t')}\n}`;
+    }
+    const separator = /,\s*$/.test(inner) ? '' : ',';
+    return `{${inner}${separator}\n\t${properties.join(',\n\t')}\n}`;
+}
+function formatObjectKey(key) {
+    return /^[$A-Z_a-z][$\w]*$/.test(key) ? key : JSON.stringify(key);
+}
+function getScriptKind(filePath) {
+    if (filePath.endsWith('.js') || filePath.endsWith('.mjs')) {
+        return ts.ScriptKind.JS;
+    }
+    return ts.ScriptKind.TS;
+}
+/**
+ * Build the public URL we inject into proxied HTML for a generated client
+ * bundle file or its associated CSS asset.
+ *
+ * The islands runtime sticks these URLs into the `<head>` (and end of `<body>`)
+ * of pages whose pathname has nothing to do with the bundle layout. Relative
+ * URLs like `./_app/...` only resolve correctly when the page itself sits at
+ * the site root, which makes the assets unreachable as soon as the proxy
+ * serves a nested URL. SvelteKit defaults `paths.relative` to true, so Vite's
+ * `base` resolves to `./` for the SvelteKit-rendered pages — fine for
+ * SvelteKit itself, useless for us. We therefore coerce to an absolute path
+ * starting with `/`, and only honour `base` when the consumer explicitly
+ * configured one (a base that starts with `/`).
+ */
+export function toPublicAssetUrl(fileName, base) {
+    let prefix = '/';
+    if (base && base.startsWith('/')) {
+        prefix = base.endsWith('/') ? base : `${base}/`;
+    }
+    return `${prefix}${fileName}`.replace(/\/{2,}/g, '/');
+}
+/**
+ * In dev, `vite-plugin-svelte` serves a `<Component>.svelte?svelte&type=style&lang.css`
+ * module as a JS wrapper that imports `__vite__updateStyle` and calls it with
+ * the CSS literal:
+ *
+ *     const __vite__css = "<escaped css>"
+ *     __vite__updateStyle(__vite__id, __vite__css)
+ *
+ * To stop the islands runtime from triggering a flash, we need to ship a
+ * single real stylesheet up front (a `<link rel="stylesheet">` blocks render
+ * the way JS-injected `<style>` tags cannot). This pulls the raw CSS string
+ * out of that wrapper so the dev middleware can concatenate it across every
+ * island module.
+ */
+export function extractViteCssFromJs(jsCode) {
+    const match = jsCode.match(/const\s+__vite__css\s*=\s*("(?:\\.|[^"\\])*")/);
+    if (!match)
+        return '';
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-implied-eval, no-new-func
+        const value = new Function(`return ${match[1]};`)();
+        return typeof value === 'string' ? value : '';
+    }
+    catch {
+        return '';
+    }
+}
+/** Match every module id we want to treat as a stylesheet for dev-time extraction. */
+export function isCssLikeModuleId(id) {
+    if (!id)
+        return false;
+    if (id.includes('?svelte&type=style'))
+        return true;
+    if (/\.(css|scss|sass|less|styl|stylus|postcss|pcss)(\?|$)/i.test(id))
+        return true;
+    return false;
+}

package/dist/proxy/vite-plugin.d.ts ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ import type { Plugin } from 'vite';
2	+ export declare function proxyIslands(): Plugin;