@megabudino/stack-utils 1.3.0 → 1.4.1

package/README.md

@@ -99,18 +99,24 @@ What it does:
 - reads source images from `static/images`
 - writes responsive variants to `static/_image-variants`
 - writes its generated manifest to `.stack-utils/image-variants.generated.json`
+- writes cache metadata to `.stack-utils/image-variants.cache.json`
 - rewrites compatible `<img src="/images/...">` tags to an internal `StaticImage` component
 - keeps `StaticImage` internal to the package so the public API stays small
 
-### Consumer gitignore
+### Reusing built images
 
-In the consuming app, ignore the generated pipeline output:
+If you want to build the image variants once and reuse them across machines or CI runs, commit:
 
-```gitignore
-static/_image-variants
-.stack-utils
+```text
+static/_image-variants/
+.stack-utils/image-variants.generated.json
+.stack-utils/image-variants.cache.json
 ```
 
+The pipeline will hash the current source images, verify the referenced generated files still exist, and skip regeneration when everything matches.
+
+If you prefer generated artifacts to stay local, you can still ignore those paths in the consuming app.
+
 ## Publishing Notes
 
 The package is intended to be consumed via subpath imports:

package/dist/images/config.d.ts

@@ -4,6 +4,7 @@ export declare const staticImagePipelineConfig: {
     readonly publicSourcePrefix: "/images";
     readonly publicOutputPrefix: "/_image-variants";
     readonly manifestPath: ".stack-utils/image-variants.generated.json";
+    readonly cachePath: ".stack-utils/image-variants.cache.json";
     readonly supportedExtensions: readonly [".jpg", ".jpeg", ".png", ".webp"];
     readonly widths: readonly [320, 480, 640, 768, 960, 1280, 1536, 1920];
     readonly quality: {

package/dist/images/config.js

@@ -4,6 +4,7 @@ export const staticImagePipelineConfig = {
     publicSourcePrefix: '/images',
     publicOutputPrefix: '/_image-variants',
     manifestPath: '.stack-utils/image-variants.generated.json',
+    cachePath: '.stack-utils/image-variants.cache.json',
     supportedExtensions: ['.jpg', '.jpeg', '.png', '.webp'],
     widths: [320, 480, 640, 768, 960, 1280, 1536, 1920],
     quality: {

package/dist/images/generator.js

@@ -1,20 +1,37 @@
-import { promises as fs } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { createReadStream, promises as fs } from 'node:fs';
 import path from 'node:path';
 import sharp from 'sharp';
 import { staticImagePipelineConfig } from './config.js';
 const SUPPORTED_EXTENSIONS = new Set(staticImagePipelineConfig.supportedExtensions);
+const IMAGE_VARIANT_CACHE_VERSION = 1;
 export async function generateStaticImageVariants({ root, log = () => undefined }) {
     const sourceDirectory = path.join(root, staticImagePipelineConfig.sourceDirectory);
     const outputDirectory = path.join(root, staticImagePipelineConfig.outputDirectory);
     const manifestPath = path.join(root, staticImagePipelineConfig.manifestPath);
+    const cachePath = path.join(root, staticImagePipelineConfig.cachePath);
     await fs.mkdir(path.dirname(manifestPath), { recursive: true });
+    await fs.mkdir(path.dirname(cachePath), { recursive: true });
     const sourceFiles = await collectSourceImages(sourceDirectory);
+    const cacheMetadata = await buildCacheMetadata(sourceFiles);
     if (sourceFiles.length === 0) {
         await fs.mkdir(outputDirectory, { recursive: true });
         await fs.writeFile(manifestPath, '{}\n');
+        await fs.writeFile(cachePath, `${JSON.stringify(cacheMetadata, null, 2)}\n`);
         return {};
     }
     await fs.mkdir(outputDirectory, { recursive: true });
+    const reusableManifest = await readReusableManifest({
+        root,
+        sourceFiles,
+        manifestPath,
+        cachePath,
+        cacheMetadata
+    });
+    if (reusableManifest) {
+        log(`[static-image-pipeline] reused ${Object.keys(reusableManifest).length} manifest entries`);
+        return reusableManifest;
+    }
     const manifest = {};
     for (const file of sourceFiles) {
         const entry = await generateManifestEntry({ file, outputDirectory });
@@ -23,9 +40,34 @@ export async function generateStaticImageVariants({ root, log = () => undefined
         }
     }
     await fs.writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+    await fs.writeFile(cachePath, `${JSON.stringify(cacheMetadata, null, 2)}\n`);
     log(`[static-image-pipeline] generated ${Object.keys(manifest).length} manifest entries`);
     return manifest;
 }
+async function readReusableManifest({ root, sourceFiles, manifestPath, cachePath, cacheMetadata }) {
+    const [manifest, persistedCache] = await Promise.all([
+        readJsonFile(manifestPath),
+        readJsonFile(cachePath)
+    ]);
+    if (!manifest || !persistedCache) {
+        return null;
+    }
+    if (persistedCache.version !== IMAGE_VARIANT_CACHE_VERSION) {
+        return null;
+    }
+    if (persistedCache.configHash !== cacheMetadata.configHash) {
+        return null;
+    }
+    if (!areStringRecordsEqual(persistedCache.sources, cacheMetadata.sources)) {
+        return null;
+    }
+    if (!manifestMatchesSources(manifest, sourceFiles)) {
+        return null;
+    }
+    const outputFiles = getOutputFilesFromManifest(root, manifest);
+    const outputFilesExist = await allFilesExist(outputFiles);
+    return outputFilesExist ? manifest : null;
+}
 async function generateManifestEntry({ file, outputDirectory }) {
     const image = sharp(file.absolutePath, { failOn: 'none' });
     const metadata = await image.metadata();
@@ -146,6 +188,22 @@ async function collectSourceImages(directory) {
     files.sort((left, right) => left.relativePath.localeCompare(right.relativePath));
     return files;
 }
+async function buildCacheMetadata(sourceFiles) {
+    const sources = Object.fromEntries(await Promise.all(sourceFiles.map(async (file) => [toSourcePath(file.relativePath), await hashFile(file.absolutePath)])));
+    return {
+        version: IMAGE_VARIANT_CACHE_VERSION,
+        configHash: createHash('sha1')
+            .update(JSON.stringify({
+            outputDirectory: staticImagePipelineConfig.outputDirectory,
+            publicOutputPrefix: staticImagePipelineConfig.publicOutputPrefix,
+            widths: staticImagePipelineConfig.widths,
+            quality: staticImagePipelineConfig.quality,
+            supportedExtensions: staticImagePipelineConfig.supportedExtensions
+        }))
+            .digest('hex'),
+        sources
+    };
+}
 async function walkDirectory(directory, onFile, baseDirectory = directory) {
     let entries;
     try {
@@ -179,10 +237,71 @@ async function needsWrite(outputPath, sourceMtimeMs) {
         throw error;
     }
 }
+async function hashFile(filePath) {
+    return new Promise((resolve, reject) => {
+        const hash = createHash('sha1');
+        const stream = createReadStream(filePath);
+        stream.on('data', (chunk) => hash.update(chunk));
+        stream.on('end', () => resolve(hash.digest('hex')));
+        stream.on('error', reject);
+    });
+}
+async function readJsonFile(filePath) {
+    try {
+        const fileContents = await fs.readFile(filePath, 'utf8');
+        return JSON.parse(fileContents);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    }
+}
+function areStringRecordsEqual(left, right) {
+    const leftEntries = Object.entries(left).sort(([leftKey], [rightKey]) => leftKey.localeCompare(rightKey));
+    const rightEntries = Object.entries(right).sort(([leftKey], [rightKey]) => leftKey.localeCompare(rightKey));
+    if (leftEntries.length !== rightEntries.length) {
+        return false;
+    }
+    return leftEntries.every(([leftKey, leftValue], index) => leftKey === rightEntries[index]?.[0] && leftValue === rightEntries[index]?.[1]);
+}
+function manifestMatchesSources(manifest, sourceFiles) {
+    const manifestSources = Object.keys(manifest).sort((left, right) => left.localeCompare(right));
+    const expectedSources = sourceFiles
+        .map((file) => toSourcePath(file.relativePath))
+        .sort((left, right) => left.localeCompare(right));
+    if (manifestSources.length !== expectedSources.length) {
+        return false;
+    }
+    return manifestSources.every((sourcePath, index) => sourcePath === expectedSources[index]);
+}
+async function allFilesExist(filePaths) {
+    for (const filePath of filePaths) {
+        try {
+            await fs.stat(filePath);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return false;
+            }
+            throw error;
+        }
+    }
+    return true;
+}
 function getTargetWidths(originalWidth) {
     const widths = staticImagePipelineConfig.widths.filter((width) => width < originalWidth).map(Number);
     return Array.from(new Set([...widths, originalWidth])).sort((left, right) => left - right);
 }
+function getOutputFilesFromManifest(root, manifest) {
+    return Object.values(manifest).flatMap((entry) => Object.values(entry.formats).flatMap((variants) => variants.map((variant) => {
+        const outputRelativePath = variant.url
+            .replace(`${staticImagePipelineConfig.publicOutputPrefix}/`, '')
+            .replace(`${staticImagePipelineConfig.publicOutputPrefix}`, '');
+        return path.join(root, staticImagePipelineConfig.outputDirectory, outputRelativePath);
+    })));
+}
 function getFallbackExtension(extension) {
     if (extension === '.png') {
         return 'png';
@@ -201,3 +320,6 @@ function getGeneratedExtension(format, fallbackExtension) {
 function toPosixPath(filePath) {
     return filePath.split(path.sep).join('/');
 }
+function toSourcePath(relativePath) {
+    return `${staticImagePipelineConfig.publicSourcePrefix}/${toPosixPath(relativePath)}`;
+}

package/dist/proxy/dom-actions.js

@@ -42,6 +42,13 @@ export function applyDomActions(html, actions) {
         if (action.setHtml !== undefined) {
             elements.html(action.setHtml);
         }
+        // Insertions compose with content replacement in the same action.
+        if (action.prependHtml !== undefined) {
+            elements.prepend(action.prependHtml);
+        }
+        if (action.appendHtml !== undefined) {
+            elements.append(action.appendHtml);
+        }
     }
     return $.html();
 }

package/dist/proxy/types.d.ts

@@ -14,6 +14,20 @@ export interface DomAction {
     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.
+     */
+    prependHtml?: string;
+    /**
+     * Insert HTML inside every matched element after its existing children.
+     *
+     * When combined with `setText` or `setHtml`, the content replacement runs
+     * first and `appendHtml` is inserted into the resulting element contents.
+     */
+    appendHtml?: string;
     /**
      * Remove every matched element.
      * When true, removal takes precedence over all other fields in the same action.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@megabudino/stack-utils",
-	"version": "1.3.0",
+	"version": "1.4.1",
 	"description": "Reusable utilities for a SvelteKit stack, including a reverse proxy and static image pipeline",
 	"type": "module",
 	"exports": {
@@ -28,7 +28,7 @@
 	],
 	"scripts": {
 		"build": "node ./scripts/build.mjs",
-		"test": "node --test proxy.test.mjs",
+		"test": "node --test *.test.mjs",
 		"typecheck": "tsc --noEmit"
 	},
 	"dependencies": {