serialize-function 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Evan Kaufman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# serialize-function
+
+![ci status](https://github.com/EvanK/npm-serialize-function/actions/workflows/ci.yaml/badge.svg)
+![node.js supported as of v20](https://img.shields.io/badge/Node.js-v20-green)
+![ECMAScript standard supported as of ES2023](https://img.shields.io/badge/ES-2023-yellow)
+
+## Quickstart
+
+Supports both CommonJS and ES Modules:
+
+```js
+const { serialize, deserialize } = require('serialize-function');
+// or
+import { serialize, deserialize } from 'serialize-function';
+```
+
+Serializes javascript functions to a JSON-encodable object suitable for storage to file or transfer over the wire:
+
+```js
+function doTheThing(a,b,c,d,e) { return a + b * c / d % e; }
+
+const obj = serialize(doTheThing);
+console.log(obj);
+// {
+//   params: [ 'a', 'b', 'c', 'd', 'e' ],
+//   body: 'return a + b * c / d % e;',
+//   type: 'Function'
+// }
+```
+
+Deserializes back into an invokable function:
+
+```js
+const func = deserialize(obj);
+console.log( func(1, 2, 3, 4, 5) );
+// 2.5
+```
+
+## Hashing
+
+Optionally supports SHA256 checksum hashing to prevent MITM tampering:
+
+```js
+// note: use of hashing returns a promise
+const hashedObj = await serialize(doTheThing, { hash: true });
+console.log(hashedObj);
+// {
+//   params: [ 'a', 'b', 'c', 'd', 'e' ],
+//   body: 'return a + b * c / d % e;',
+//   type: 'Function',
+//   hash: '814fab043d5bcee7a589b1d73a9fb42a2d716c3f615056c41a062478e7844827'
+// }
+
+hashedObj.body = 'return doSomethingMalicious(...arguments);';
+const tamperedFunc = await deserialize(hashedObj, { hash: true });
+// ChecksumError: Checksum failed
+```
+
+> Under the hood, the browser-based implementation uses the [SubtleCrypto](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto) API, while the node implementation uses the built-in [crypto module](https://nodejs.org/docs/latest-v20.x/api/crypto.html).
+
+## Whitespace and comments
+
+Line breaks within the function body are preserved and normalized, but all other padding whitespace is removed from the function by default, along with any comments.
+
+You can optionally preserve either or both, with the corresponding options:
+
+```js
+function thingNumberTwo(
+  /* marco */
+  a,   b,	c,
+  d,e/* polo */
+) {
+  // add some things
+  const sum = a + b;
+
+  /* multiply by another thing */
+  const product = sum * c;
+
+  // divide by _another_
+  // different thing
+  const quotient = product / d;
+  /*
+    and modulus THAT thing
+  */
+  const remainder = quotient % e;
+  return remainder;
+}
+
+const commentedObj = serialize(thingNumberTwo, { whitespace: true, comments: true });
+console.log(commentedObj);
+// {
+//   params: [ '\n  /* marco */\n  a', '   b', '\tc', '\n  d', 'e/* polo */\n' ],
+//   body: '\n' +
+//     '  // add some things\n' +
+//     '  const sum = a + b;\n' +
+//     '\n' +
+//     '  /* multiply by another thing */\n' +
+//     '  const product = sum * c;\n' +
+//     '\n' +
+//     '  // divide by _another_\n' +
+//     '  // different thing\n' +
+//     '  const quotient = product / d;\n' +
+//     '  /*\n' +
+//     '    and modulus THAT thing\n' +
+//     '  */\n' +
+//     '  const remainder = quotient % e;\n' +
+//     '  return remainder;\n',
+//   type: 'Function'
+// }
+```
+
+## Function type support
+
+Arrow functions, generators, and all async variants are supported (contingent on _browser support_ where relevant):
+
+```js
+serialize(
+  (i,j,k) => ({ i, j, k })
+);
+// {
+//   params: [ 'i', 'j', 'k' ],
+//   body: 'return (({ i, j, k }));',
+//   type: 'ArrowFunction'
+// }
+
+serialize(
+  function* (x,y,z) {
+    yield x;
+    yield y;
+    yield z;
+  }
+);
+// {
+//   params: [ 'x', 'y', 'z' ],
+//   body: 'yield x;\nyield y;\nyield z;',
+//   type: 'Generator'
+// }
+
+serialize(
+  async (ms) => new Promise( 
+    resolve => setTimeout(resolve, ms)
+  )
+);
+// {
+//   params: [ 'ms' ],
+//   body: 'return (new Promise(\nresolve => setTimeout(resolve, ms)\n));',
+//   type: 'AsyncArrowFunction'
+// }
+```

package/dist/import.mjs

@@ -0,0 +1,5 @@
+// ESM support
+import { serialize, deserialize } from './main.js';
+
+export { serialize, deserialize }
+export default { serialize, deserialize }

package/dist/main.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:true});exports.deserialize=deserialize;exports.serialize=serialize;function _interopRequireWildcard(e,t){if("function"==typeof WeakMap)var r=new WeakMap,n=new WeakMap;return(_interopRequireWildcard=function(e,t){if(!t&&e&&e.__esModule)return e;var o,i,f={__proto__:null,default:e};if(null===e||"object"!=typeof e&&"function"!=typeof e)return f;if(o=t?n:r){if(o.has(e))return o.get(e);o.set(e,f)}for(const t in e)"default"!==t&&{}.hasOwnProperty.call(e,t)&&((i=(o=Object.defineProperty)&&Object.getOwnPropertyDescriptor(e,t))&&(i.get||i.set)?o(f,t,i):f[t]=e[t]);return f})(e,t)}async function digest(input){const{createHash}=await Promise.resolve().then(()=>_interopRequireWildcard(require("node:crypto")));return createHash("sha256").update(input).digest("hex")}class JsonError extends Error{};class CryptoError extends Error{};async function hasher(obj){let json,hashed;try{json=JSON.stringify(obj)}catch(cause){throw new JsonError("Failed to stringify serialized function structure",{cause})}try{hashed=await digest(json)}catch(cause){throw new CryptoError("Failed to generate hash digest",{cause})}return hashed}const AsyncFunction=async function(){}.constructor;const Generator=function*(){}.constructor;const AsyncGenerator=async function*(){}.constructor;const formatPatterns={"Generator":/^(async\s+)?function\*\s*[^()]*\(([^)]*)\)\s*{([\s\S]*)}$/,"Function":/^(async\s+)?function\s*[^()]*\(([^)]*)\)\s*{([\s\S]*)}$/,"ArrowFunction":/^(async\s+)?(?:\(([^)]*)\)|([^=\s(]+))\s*=>\s*(?:{([\s\S]*)}|([\s\S]+))$/};class SerializeError extends Error{}class DeserializeError extends Error{}class ChecksumError extends Error{}class ConstructError extends Error{}function getConstructor(type){switch(type){case"Function":case"ArrowFunction":return Function;case"AsyncFunction":case"AsyncArrowFunction":return AsyncFunction;case"Generator":return Generator;case"AsyncGenerator":return AsyncGenerator;default:throw new ConstructError(`Unexpected type ${type}`)}}function serialize(func,opts){const def={hash:false,comments:false,whitespace:false};opts=typeof opts==="object"&&null!==opts?Object.assign({},def,opts):Object.assign({},def);const typed=typeof func;if(typed!=="function"){throw new SerializeError("Invalid argument type, must be a function",{cause:{"typeof":typed}})}let stringified=func.toString();if(!opts.comments){stringified=stringified.replace(/\/\*[\s\S]*?\*\//g,"").replace(/\/\/.*$/gm,"")}if(!opts.whitespace){stringified=stringified.split(/[\r\n]+/).map(line=>line.trim()).filter(line=>line!=="").join("\n")}let match,serialized;for(const[type,pattern]of Object.entries(formatPatterns)){try{match=stringified.match(pattern);if(match){let async=match[1]?"Async":"";let params=type==="ArrowFunction"?match[2]??match[3]:match[2];params=params.split(",").map(p=>opts.whitespace?p:p.trim()).filter(Boolean);let body=type==="ArrowFunction"?match[4]??`return (${match[5]});`:match[3];if(!opts.whitespace)body=body.trim();serialized={params,body,type:`${async}${type}`};break}}catch(cause){throw new SerializeError(`Unexpected error serializing ${type}`,{cause})}}if(!serialized){throw new SerializeError("Unsupported function format",{cause:stringified})}if(opts.hash){return hasher(serialized).then(hashed=>{serialized.hash=hashed;return serialized}).catch(cause=>{throw new SerializeError("Failure hashing serialized function",{cause})})}return serialized}function deserialize(struct,opts={hash:false}){if(opts?.hash){if(struct?.hash===undefined){throw new DeserializeError("Deserialized function missing hash")}const test=Object.assign({},struct);delete test.hash;return hasher(test).then(checksum=>{if(checksum!==struct.hash){throw new ChecksumError("Checksum failed",{cause:{a:checksum,b:struct.hash}})}return deserialize(struct,{hash:false})}).catch(cause=>{if(cause instanceof ChecksumError||cause instanceof DeserializeError||cause instanceof ConstructError){throw cause}throw new DeserializeError("Failure generating checksum",{cause})})}try{const constructor=getConstructor(struct.type);return new constructor(...struct.params,struct.body)}catch(cause){if(cause instanceof ConstructError)throw cause;throw new DeserializeError("Failure deserializing",{cause})}}

package/lib/main.js

@@ -0,0 +1 @@
+async function digest(input){const hashBuffer=await window.crypto.subtle.digest("SHA-256",new TextEncoder().encode(input));return Array.from(new Uint8Array(hashBuffer)).map(item=>item.toString(16).padStart(2,"0")).join("")}class JsonError extends Error{};class CryptoError extends Error{};async function hasher(obj){let json,hashed;try{json=JSON.stringify(obj)}catch(cause){throw new JsonError("Failed to stringify serialized function structure",{cause})}try{hashed=await digest(json)}catch(cause){throw new CryptoError("Failed to generate hash digest",{cause})}return hashed}const AsyncFunction=async function(){}.constructor;const Generator=function*(){}.constructor;const AsyncGenerator=async function*(){}.constructor;const formatPatterns={"Generator":/^(async\s+)?function\*\s*[^()]*\(([^)]*)\)\s*{([\s\S]*)}$/,"Function":/^(async\s+)?function\s*[^()]*\(([^)]*)\)\s*{([\s\S]*)}$/,"ArrowFunction":/^(async\s+)?(?:\(([^)]*)\)|([^=\s(]+))\s*=>\s*(?:{([\s\S]*)}|([\s\S]+))$/};class SerializeError extends Error{}class DeserializeError extends Error{}class ChecksumError extends Error{}class ConstructError extends Error{}function getConstructor(type){switch(type){case"Function":case"ArrowFunction":return Function;case"AsyncFunction":case"AsyncArrowFunction":return AsyncFunction;case"Generator":return Generator;case"AsyncGenerator":return AsyncGenerator;default:throw new ConstructError(`Unexpected type ${type}`)}}function serialize(func,opts){const def={hash:false,comments:false,whitespace:false};opts=typeof opts==="object"&&null!==opts?Object.assign({},def,opts):Object.assign({},def);const typed=typeof func;if(typed!=="function"){throw new SerializeError("Invalid argument type, must be a function",{cause:{"typeof":typed}})}let stringified=func.toString();if(!opts.comments){stringified=stringified.replace(/\/\*[\s\S]*?\*\//g,"").replace(/\/\/.*$/gm,"")}if(!opts.whitespace){stringified=stringified.split(/[\r\n]+/).map(line=>line.trim()).filter(line=>line!=="").join("\n")}let match,serialized;for(const[type,pattern]of Object.entries(formatPatterns)){try{match=stringified.match(pattern);if(match){var _match$,_match$2;let async=match[1]?"Async":"";let params=type==="ArrowFunction"?(_match$=match[2])!==null&&_match$!==void 0?_match$:match[3]:match[2];params=params.split(",").map(p=>opts.whitespace?p:p.trim()).filter(Boolean);let body=type==="ArrowFunction"?(_match$2=match[4])!==null&&_match$2!==void 0?_match$2:`return (${match[5]});`:match[3];if(!opts.whitespace)body=body.trim();serialized={params,body,type:`${async}${type}`};break}}catch(cause){throw new SerializeError(`Unexpected error serializing ${type}`,{cause})}}if(!serialized){throw new SerializeError("Unsupported function format",{cause:stringified})}if(opts.hash){return hasher(serialized).then(hashed=>{serialized.hash=hashed;return serialized}).catch(cause=>{throw new SerializeError("Failure hashing serialized function",{cause})})}return serialized}function deserialize(struct){let opts=arguments.length>1&&arguments[1]!==undefined?arguments[1]:{hash:false};if(opts?.hash){if(struct?.hash===undefined){throw new DeserializeError("Deserialized function missing hash")}const test=Object.assign({},struct);delete test.hash;return hasher(test).then(checksum=>{if(checksum!==struct.hash){throw new ChecksumError("Checksum failed",{cause:{a:checksum,b:struct.hash}})}return deserialize(struct,{hash:false})}).catch(cause=>{if(cause instanceof ChecksumError||cause instanceof DeserializeError||cause instanceof ConstructError){throw cause}throw new DeserializeError("Failure generating checksum",{cause})})}try{const constructor=getConstructor(struct.type);return new constructor(...struct.params,struct.body)}catch(cause){if(cause instanceof ConstructError)throw cause;throw new DeserializeError("Failure deserializing",{cause})}}export{serialize,deserialize};

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "serialize-function",
+  "version": "1.0.0",
+  "description": "Serializes javascript functions to a JSON-friendly format",
+  "author": "Evan Kaufman <evan@evanskaufman.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EvanK/npm-serialize-function.git"
+  },
+  "bugs": {
+    "url": "https://github.com/EvanK/npm-serialize-function/issues"
+  },
+  "homepage": "https://github.com/EvanK/npm-serialize-function",
+  "keywords": [
+    "function",
+    "serialize",
+    "json"
+  ],
+  "files": [
+    "dist/*",
+    "lib/*"
+  ],
+  "exports": {
+    "import": "./dist/import.mjs",
+    "require": "./dist/main.js"
+  },
+  "browser": "./lib/main.js",
+  "scripts": {
+    "concat-browser": "cat src/001-digest-browser.mjs src/002-hasher.mjs src/003-main.mjs > build-main-browser.mjs",
+    "concat-node": "cat src/001-digest-node.mjs src/002-hasher.mjs src/003-main.mjs > build-main-node.mjs",
+    "transpile-browser": "babel build-main-browser.mjs --no-babelrc --out-file lib/main.js --config-file ./.babelrc.esm.json",
+    "transpile-node": "babel build-main-node.mjs --no-babelrc --out-file dist/main.js --config-file ./.babelrc.cjs.json",
+    "build-browser-dev": "npm run concat-browser && npm run transpile-browser",
+    "build-node-dev": "npm run concat-node && npm run transpile-node && cp src/import.mjs dist/",
+    "build-browser": "npm run concat-browser && npm run transpile-browser -- --minified --no-comments",
+    "build-node": "npm run concat-node && npm run transpile-node -- --minified --no-comments && cp src/import.mjs dist/",
+    "dist-dev": "npm run build-browser-dev && npm run build-node-dev",
+    "dist": "npm run build-browser && npm run build-node",
+    "lint": "eslint .",
+    "prepare-test-browser": "sed '/TEST_SPEC_END/e cat tests/general.spec.js' tests/003-browser.test.html > ./003-browser.test.html",
+    "test-browser": "node ./tests/003-puppeteer.script.mjs",
+    "prepare-test-node": "cat tests/001-general.test.template.cjs tests/general.spec.js > tests/001-general.ignore.test.cjs",
+    "test-node": "mocha ./tests/**.test.*js",
+    "test": "npm run prepare-test-browser && npm run test-browser && npm run prepare-test-node && npm run test-node"
+  },
+  "devDependencies": {
+    "@babel/cli": "^7.28.0",
+    "@babel/core": "^7.28.0",
+    "@babel/plugin-transform-nullish-coalescing-operator": "^7.27.1",
+    "@babel/preset-env": "^7.28.0",
+    "@eslint/js": "^9.30.1",
+    "@fastify/static": "^8.2.0",
+    "@stylistic/eslint-plugin": "^5.1.0",
+    "chai": "^5.2.0",
+    "eslint": "^9.30.1",
+    "eslint-plugin-mocha": "^11.1.0",
+    "fastify": "^5.4.0",
+    "globals": "^16.3.0",
+    "mocha": "^11.7.1",
+    "proxyquire": "^2.1.3",
+    "puppeteer": "^24.14.0",
+    "sinon": "^21.0.0"
+  }
+}