@localnerve/csp-hashes 7.0.3 → 7.1.0

package/index.js

@@ -1,10 +1,11 @@
 /**
  * CSP Hashes.
  * 
- * Return a Vinyl transform object stream to process html files for
- * generating the required CSP hashes for inline and attribute scripts, styles.
+ * Return a Transform object stream to process Vinyl or plain file-like
+ * objects for generating the required CSP hashes for inline and attribute
+ * scripts, styles.
  * 
  * Copyright (c) 2022-2025 Alex Grant (@localnerve), LocalNerve LLC
  * Licensed under the MIT license.
  */
-export { hashstream as default, hashstream, removeCspMeta, createCspHash } from './lib/index.js';
+export { hashstream as default, hashstream, removeCspMeta, createCspHash, cspHashes } from './lib/index.js';

package/lib/index.js

@@ -1,8 +1,9 @@
 /**
  * CSP Hashes.
  * 
- * Return a Vinyl transform object stream to process html files for
- * generating the required CSP hashes for inline and attribute scripts, styles.
+ * Return a Transform object stream to process Vinyl or plain file-like
+ * objects for generating the required CSP hashes for inline and attribute
+ * scripts, styles.
  * 
  * Copyright (c) 2022-2025 Alex Grant (@localnerve), LocalNerve LLC
  * Licensed under the MIT license.
@@ -74,15 +75,53 @@ export function createCspHash(input, algo = 'sha256') {
   return makeCspHash(algo, input);
 }
 
+/**
+ * cspHashes
+ * Accepts an algorithm and content buffer/string and returns a hashes object
+ * containing all CSP hashes for inline scripts and styles. This is useful for
+ * users who just have a few files to process and will handle I/O themselves,
+ * without needing a stream.
+ *
+ * @param {String} [algo] - hash algorithm, default sha256. Can be sha384, sha512.
+ * @param {Buffer|String} content - The HTML content to extract hashes from.
+ * @returns {Object} The hashes object with script and style elements and attributes.
+ */
+export function cspHashes (algo = 'sha256', content) {
+  if (!/^sha(256|384|512)$/.test(algo)) {
+    throw new Error('algo option must be one of "sha256", "sha384", or "sha512" only.');
+  }
+
+  const hashes = {
+    script: {
+      elements: [],
+      attributes: [],
+      get all () {
+        return this.elements.concat(this.attributes);
+      }
+    },
+    style: {
+      elements: [],
+      attributes: [],
+      get all () {
+        return this.elements.concat(this.attributes);
+      }
+    }
+  };
+
+  collectHashes(makeCspHash.bind(null, algo), content, hashes);
+
+  return hashes;
+}
+
 /**
  * hashstream
- * Accepts the processing options and returns the Vinyl transform object stream.
+ * Accepts the processing options and returns a Transform object stream.
  *
  * @param {Object} options
  * @param {Function} options.callback - Function to call to process the csp hashes.
  * @param {String} [options.algo] - hash algorithm, default sha256. Can be sha384, sha512.
  * @param {Boolean} [options.replace] - True if callback is used for meta html replacements, defaults to false.
- * @returns Transform object stream to process Vinyl objects.
+ * @returns Transform object stream that accepts Vinyl or plain file-like objects with `path` and `contents`.
  */
 export function hashstream ({
   algo = 'sha256',
@@ -100,37 +139,20 @@ export function hashstream ({
 
   const transformObjectStream = new Transform({
     objectMode: true,
-    transform: (vinyl, enc, done) => {
-      const path = vinyl.path;
-      const content = vinyl.contents;
-  
-      const hashes = {
-        script: {
-          elements: [],
-          attributes: [],
-          get all () {
-            return this.elements.concat(this.attributes);
-          }
-        },
-        style: {
-          elements: [],
-          attributes: [],
-          get all () {
-            return this.elements.concat(this.attributes);
-          }
-        }
-      };
-  
-      collectHashes(makeCspHash.bind(null, algo), content, hashes);
+    transform: (file, enc, done) => {
+      const path = file.path;
+      const content = file.contents;
+
+      const hashes = cspHashes(algo, content);
   
       if (replace) {
         const s = callback(path, hashes, content.toString());
-        vinyl.contents = Buffer.from(s, enc);
+        file.contents = Buffer.from(s, enc);
       } else {
         callback(path, hashes);
       }
-  
-      done(null, vinyl);
+
+      done(null, file);
     }
   });
 

package/lib/removeCspMeta.js

@@ -12,19 +12,19 @@ import { Transform } from 'node:stream';
 export function removeCspMeta () {
   return new Transform({
     objectMode: true,
-    transform: (vinyl, enc, done) => {
+    transform: (file, enc, done) => {
       let e = null;
-      const input = vinyl?.contents?.toString();
+      const input = file?.contents?.toString();
       if (input) {
         const output = input.replace(
           /("?Content-Security-Policy"?)(\s+)(content=")([^"]+)"/i, '$1$2$3$2"'
         );
-        vinyl.contents = Buffer.from(output, enc);
+        file.contents = Buffer.from(output, enc);
       } else {
-        e = new Error('removeCspMeta could not get Vinyl object file contents');
+        e = new Error('removeCspMeta could not get file object contents');
         e.errorCode = 'EBADINPUT';
       }
-      done(e, vinyl);
+      done(e, file);
     }
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@localnerve/csp-hashes",
-  "version": "7.0.3",
+  "version": "7.1.0",
   "description": "Flexible library to generate CSP hashes",
   "main": "index.js",
   "type": "module",
@@ -15,9 +15,9 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "eslint": "^10.5.0",
-    "eslint-plugin-n": "^18.1.0",
-    "globals": "^17.6.0",
+    "eslint": "^10.8.0",
+    "eslint-plugin-n": "^18.2.2",
+    "globals": "^17.8.0",
     "vinyl": "^3.0.1"
   },
   "dependencies": {

package/readme.md

@@ -13,6 +13,7 @@
   - [Breaking Changes](#breaking-changes)
   - [API](#api)
     - [hashstream (also the default export)](#hashstream-also-the-default-export)
+    - [cspHashes](#csphashes)
     - [createCspHash](#createcsphash)
     - [removeCspMeta](#removecspmeta)
     - [Hashstream Options](#hashstream-options)
@@ -22,11 +23,12 @@
     - [Build Step to Maintain CSP Headers](#build-step-to-maintain-csp-headers)
     - [Build Step to Maintain CSP Meta Tags](#build-step-to-maintain-csp-meta-tags)
     - [Build Step to Remove CSP Meta Tag Content](#build-step-to-remove-csp-meta-tag-content)
+    - [Native Node.js Streams (No Gulp/Vinyl Required)](#native-nodejs-streams-no-gulpvinyl-required)
     - [Non-ESM usage](#non-esm-usage)
   - [LICENSE](#license)
 
 ## Overview
-This Nodejs library generates script and style inline element and attribute hashes. It is for use in the generation of HTTP content security policy (CSP) headers or to replace/update Meta tags as a website build step. Ready for use with [Gulp](https://github.com/gulpjs/gulp).
+This Node.js library generates script and style inline element and attribute hashes. It is for use in the generation of HTTP content security policy (CSP) headers or to replace/update Meta tags as a website build step. Works with [Gulp](https://github.com/gulpjs/gulp) via Vinyl objects, or directly with native Node.js streams using plain file-like objects.
 
 ## Breaking Changes
 + As of Version 2+, this is an ES Module. See [Non-Esm Usage](#non-esm-usage) for how to use outside of ESM.
@@ -48,6 +50,33 @@ Stream hashstream ({
 
 See [`hashstream options`](#hashstream-options) for a detailed explanation of the input options.
 
+### cspHashes
+This library exports a convenience function that takes an algorithm and HTML content, and returns a hashes object containing all CSP hashes for inline scripts and styles. This is useful for users who just have a few files to process and will handle I/O themselves, without needing a stream.
+
+```
+Object cspHashes(algo = 'sha256', content)
+```
+
++ {String} **\[algo\]** - Optional - Defaults to `'sha256'`, can be one of 'sha256', 'sha384' or 'sha512'.
++ {Buffer|String} **content** - Required - The HTML content to extract hashes from.
+
+Returns a [`hashes` object](#callback-hashes-object) with the same structure as the `hashstream` callback receives:
+
+```javascript
+{
+  script: {
+    elements: [],
+    attributes: [],
+    get all () { return this.elements.concat(this.attributes); }
+  },
+  style: {
+    elements: [],
+    attributes: [],
+    get all () { return this.elements.concat(this.attributes); }
+  }
+}
+```
+
 ### createCspHash
 This library exports the helper method it uses to make CSP formatted hashes. This is useful if you have a picece of code you need to hash and place into your hash list outside the scope of the page as rendered.
 
@@ -61,7 +90,7 @@ String createCSPHash(inputString, algo = 'sha256')
 Returns a ready to use csp hash string (with quotes) in the form of `'sha256-d3ii1Pel57UO62xosCMNgTaZJhJa87Gd/X6e7UdlEU8='`.
 
 ### removeCspMeta
-This library also exports a convenience helper method, `removeCspMeta` that is useful for some types of development builds. This method takes no options and returns a stream that operates on [Vinyl](https://github.com/gulpjs/vinyl) objects and removes any `Content-Security-Policy` content found in the files.
+This library also exports a convenience helper method, `removeCspMeta` that is useful for some types of development builds. This method takes no options and returns a stream that operates on [Vinyl](https://github.com/gulpjs/vinyl) objects or plain file-like objects with `path` and `contents` properties, removing any `Content-Security-Policy` content found in the files.
 
 ```
 Stream removeCspMeta ()
@@ -178,6 +207,84 @@ export function stripCspMetaContents (settings) {
 }
 ```
 
+### Simple File Processing (No Stream Required)
+If you just have a few files to process and want to handle I/O yourself, use `cspHashes` instead of `hashstream`:
+
+```javascript
+import fs from 'node:fs';
+import { cspHashes } from '@localnerve/csp-hashes';
+
+const html = fs.readFileSync('./dist/index.html', { encoding: 'utf8' });
+const hashes = cspHashes('sha256', html);
+
+console.log('Script element hashes:', hashes.script.elements.join(' '));
+console.log('Style attribute hashes:', hashes.style.attributes.join(' '));
+```
+
+### Native Node.js Streams (No Gulp/Vinyl Required)
+You can use `hashstream` directly with native Node.js streams by wrapping raw file buffers into plain file-like objects. This example reads HTML files from a source directory, processes them through `hashstream`, and writes the output to a destination:
+
+```javascript
+import fs from 'node:fs';
+import path from 'node:path';
+import { pipeline, Transform } from 'node:stream';
+import hashstream from '@localnerve/csp-hashes';
+
+const srcDir = './src/html';
+const destDir = './dist/html';
+
+// Wrap raw buffer chunks into plain file-like objects for the transform stream.
+function wrapFileObject (filePath) {
+  return new Transform({
+    readableObjectMode: true,
+    construct (callback) { callback(); },
+    transform (chunk, enc, done) {
+      this.push({ path: filePath, contents: chunk });
+      done();
+    }
+  });
+}
+
+// Unwrap file-like objects back to raw buffers for writing.
+function unwrapFileObject () {
+  return new Transform({
+    writableObjectMode: true,
+    construct (callback) { callback(); },
+    transform (fileObj, enc, done) {
+      this.push(fileObj.contents);
+      done();
+    }
+  });
+}
+
+async function processFile (filePath) {
+  const destPath = path.join(destDir, path.relative(srcDir, filePath));
+  fs.mkdirSync(path.dirname(destPath), { recursive: true });
+
+  await new Promise((resolve, reject) => {
+    pipeline(
+      fs.createReadStream(filePath),
+      wrapFileObject(filePath),
+      hashstream({
+        algo: 'sha256',
+        callback: (filePath, hashes) => {
+          console.log(`Processed ${path.basename(filePath)}:`);
+          console.log(`  Script hashes: ${hashes.script.all.length}`);
+          console.log(`  Style hashes:  ${hashes.style.all.length}`);
+        }
+      }),
+      unwrapFileObject(),
+      fs.createWriteStream(destPath),
+      (err) => err ? reject(err) : resolve()
+    );
+  });
+}
+
+// Process all .html files in the source directory
+const htmlFiles = fs.readdirSync(srcDir).filter(f => f.endsWith('.html')).map(f => path.join(srcDir, f));
+await Promise.all(htmlFiles.map(processFile));
+```
+
 ### Non-ESM usage
 As of Version 2, this package is an ES Module, making it incompatible with `require`. To use outside of ESM, you can use this with a dynamic import as in the following example:
 
@@ -194,3 +301,7 @@ import('@localnerve/csp-hashes').then(({ hashstream }) => {
 ## LICENSE
 
 * [MIT, Alex Grant, LocalNerve, LLC](license.md)
+
+## Author
+
+* Alex Grant, alex@localnerve.com, https://localnerve.com