jam 0.6.1 → 0.7.1

package/README.md

@@ -1,276 +1,60 @@
-[![Build Status](https://travis-ci.org/chakrit/jam.png?branch=master)](https://travis-ci.org/chakrit/jam)
+# jam
 
-# JAM JAM JAM
+Jam is an application server for isolated JavaScript. It runs JavaScript (and TypeScript) per request with isolated execution contexts, inspired by the PHP-FPM model.
 
-```sh
-$ npm install jam --save
-```
-
-JAM is another kind of async framework that tries to have as minimum boilerplate code as
-possible with sensible defaults. (Or as sensible as I can make it; PR and ideas welcome.)
-
-JAM wants you to get right in to building your `async` chain as soon as possible.
-
-JAM also aims to bundle with itself some "combinators" (or just "helpers") which helps you
-manipulate arguments and functions that are being passed around in the chain with ease.
-There is only a handful of them right now, but I will add more whenever I see a good use
-for one.
-
-# HOW TO
-
-JAM functions must accept a `next` argument first thing which you should call as soon as
-your asynchronous processing is done:
-
-Let's start with the simplest possible invocation of jam:
-
-```js
-var chain = jam( function(next) { next(); } );
-```
-
-**JAM will starts executing your chain as soon as `nextTick`.** So, in the event loop time
-you have been allocated, you can add as many methods as you like and the chain will start
-executing as soon your loop finishes. No more steps necessary!
-
-You may think that this poses a problem but I find that most (if not all) of the cases
-where you want to do multiple asynchronous calls, you will build all your calls in a
-single run loop. So this is a non-issue.
-
-To add a method to the chain, simply invoke the result from the last JAM invocation as a
-function like this:
-
-```js
-chain = chain( function secondStep(next) { next(); } );
-```
-
-JAM expects most asynchronous method calls to be executed serially so that is what the
-chain does by default when you start adding methods to the chain.
-
-Since JAM return values are just functions, you don't even need to hold it in a variable
-if you like extra brevity of code:
-
-```js
-jam( function firstStep(next)  { next(); } )
-  (  function secondStep(next) { next(); } )
-  (  function lastStep()       { } );
-```
-
-JAM also handles `Error`s for you. Note:
-
-* The convention here is that the last function in the chain is often the one that will
-  handle all errors in the chain.
-* The last function does not need any more `next()` since it's the last one.
-
-JAM convention utilizes the two facts above to pass any `Error` that happens in the chain
-to the last function as first argument.
-
-So if you need error handling, write the last function as a standard node.js callback:
-
-```js
-jam(function erroneous(next) {
-    next(new Error('naw!');
-  })
-  (function handler(err) {
-    if (err) { console.log(err.stack); }
-  });
-```
-
-Additionally, JAM also passes anything else given to the `next()` function to the next one
-as arguments as well so you can do this:
-
-```js
-jam(function(next) { fs.readFile('filename.txt', next); })
-  (function(next, data) {
-    console.log("FILE DATA:\r\n" + data);
-  });
-```
-
-This is much better than if JAM put `next()` as the last argument since some functions
-calls your `callback` with more arguments than you need (or aware of) thus making your
-code dependent on the number of arguments given.
-
-Passing `next` as first argument eliminates the dependency since you can bind as many
-arguments as you want and the `next()` is still passed as first argument always.
-
-Since this pattern allows you to pass functions verbatim, JAM also helps you binds the
-funciton context as well if you supply the context object as the second argument:
-
-```js
-var myObj =
-  { text: 'HELLO'
-  , echo: function() { console.log(this.text); }
-  };
-
-jam(myObj.echo, myObj); // executes myObj.echo with this === myObj
-```
-
-Additionally, there are helpers available that lets you build JAM chains more easily.
-
-# HELPERS
+## Install
 
-This is just a quick list to give you some ideas. More documentation on helpers are
-available with with the [annotated source of jam.js](http://gh.chakrit.net/jam/).
-
-Or feel free to ping me [@chakrit](http://twitter.com/chakrit) on Twitter or open a GH
-issue for questions.
-
-#### identity( )
-
-```js
-jam(function first(next) { next('one'); })
-  (jam.identity)
-  (function second(err, arg) {
-    assert(arg === 'one'); // passese
-  });
-```
-
-Passes arguments it receives to the next function in the chain without any modification.
-Also useful as a starting point when building a complex jam chain (i.e. in a for loops
-that re-uses the jam return values.)
-
-See `nextTick()` below.
-
-#### nextTick( )
-
-```js
-jam( function firstStep(next) { next(); } )
-  ( jam.nextTick )
-  ( function badSecondStep(next) { next(); } );
+```sh
+npm install -g jam
+jam --help
 ```
 
-Except for the first invocation, JAM chains are executed synchronously one after another
-as soon as you call `next()`. This may pose a problem for some code that does not expect
-asynchronous functions to execute immeditaely.
+## Usage
 
-This function fixes this case by inserting a nextTick() in-between the call chain to make
-sure it executes on `process.nextTick`.
+Create a `scripts/app.ts` file:
 
-This function is actually just an alias for `.identity`
-
-#### return( [args...] )
-
-```js
-function handleFileContent(e, file) {
+```ts
+export default {
+  fetch(request: Request): Response {
+    return new Response("Hello from Jam");
+  }
 };
-
-// parallel handleFileContent jam
-['file1.txt', 'file2.txt', 'file3.txt'].forEach(function(file) {
-  jam(jam.return(file))
-    (jam.call(fs.readFile)) // no function() needed!
-    (handleFileContent);
-});
 ```
 
-This allows you to provide arguments to the next function in the chain (or for starting
-it) without modifying or wrapping code for the rest of the chains.
-
-#### call( func, [args...] )
-
-```js
-jam(jam.call(findTheRightFile))
-  (jam.call(fs.readFile))
-  (function(e, fileContent) {
-    // fileContent is the content of the right file
-  });
-```
-
-This helper lets you call standard node.js functions that expect callbacks at the end.
-Additionally, any arguments that would normally be given to the chain function would be
-used to call the function instead (`next()` is then added at the end of the arguments
-list).
-
-#### each and map( array, iterator( next, element, index ) )
-
-```js
-var FILES = 'file1.txt,file2.txt,file3.txt'.split(',');
+Start Jam, pointing it at the scripts folder:
 
-jam(jam.map(FILES, function(next, filename) {
-  fs.readFile(filename, next);
-
-})(function(e, result) {
-  var cat = result.join('');
-  console.log(cat);
-
-});
+```sh
+jam ./scripts
 ```
 
-Runs the `iterator` for each element in the array. The `iterator` is given its own version
-of `next()` and the element to process. If no array is given, the method assumes that the
-previous step in the chain produce something that looks like an array.
-
-Internally a new JAM chain is built and a chain step is added for each element.
-
-The next step in the JAM chain will receive the original array verbatim, or the
-transformed result in case of `map`.
+Now make a request. Jam maps `/app` to `app.ts`.
 
-See the `example/map.js` file for more information.
-
-### promise( chain )
-
-```js
-var chain = jam(jam.identity); // or any existing chain
-fs.readFile('file1.txt', chain.promise()); // adds a step to "wait" for fs.readFile result
-
-chain(function(e, content) {
-  console.log("Content of file1 is:");
-  console.log(content);
-});
+```sh
+curl http://localhost:3000/app
 ```
 
-Creates and return a special promise-style callback function that is internally bound to
-the JAM chain. This callback accepts the standard node.js callback signature of
-`function(e, args)` and upon calling, will pass any given arguments properly into the
-`next` function in the JAM chain.
-
-This function is useful when you have already started a JAM chain and want to include an
-asynchronous function into the chain but do not want to wrap the initial call into the
-chain as well (so you can create a `.promise()` callback from the chain and pass that
-instead effectively making the chain wait for the callback.)
-
-This function works regardless of wether the callback or the JAM chain is called first and
-will pass arguments and handle errors properly in both cases.
-
-See the `example/promise.js` file for more information.
-
-# LICENSE
-
-MIT (see LICENSE file for the full text.)
-
-# SUPPORT / CONTRIBUTE
-
-Pull requests and/or ideas welcome.
-
-Please open a [new GitHub Issue](https://github.com/chakrit/jam/issues/new) for any bugs
-you find or if you just had a question.
+Edit the file and make the same request again. The next request runs the updated script immediately, with no rebuilds or restarts.
 
-#### TODOs
+## Documentation
 
-* Binded calls. Something like `jam.method(object, 'func')` that works like `jam.call`.
-* Nullify calls, in case you don't want any arguments passed.
-* Parellel map() ?
+To learn more, see [the documentation](https://github.com/mjackson/jam/tree/main/docs).
 
-# WHY ?
+## How platform binaries are downloaded
 
-Short answer: Because the existing ones are so cumbersome to use that I just had enough
-with it.
+The `jam` package uses platform-specific optional dependencies. During install, npm picks the matching package for your OS/CPU target:
 
-Yeah, I know there're tons of other continuation helpers out there already but there
-really isn't one where you could quickly just type-in the list of stuff to do and be done
-with it without worrying about forgetting to close the list with that final parenthesis or
-forgetting to add a comma. And yeah, IMO it is wayyy easier to just add a
-`(function() { })` block at the end because that's what you're usually doing all the time
-anyway taking care of all those JS variable scopes. Plus it is easier to
-copy/paste/reorder the steps as well.
+- [`jam-darwin-arm64`](https://www.npmjs.com/package/jam-darwin-arm64)
+- [`jam-darwin-x64`](https://www.npmjs.com/package/jam-darwin-x64)
+- [`jam-linux-x64`](https://www.npmjs.com/package/jam-linux-x64)
+- [`jam-linux-arm64`](https://www.npmjs.com/package/jam-linux-arm64)
 
-Another thing is that most of the libraries try to provide you with a lot of powerful way
-to run asynchronous functions where most of the time you just want to reduce the amount of
-nesting in your code.
+Current support is macOS (`darwin`) and Linux glibc builds. Linux musl and Windows targets are not published yet.
 
-So my idea is that the interface should be really minimal using the most common case with
-sane defaults and then provide helpers for bringing edge cases into this minimal interface
-neatly so you can just get your stuff done without worrying about wether you are using the
-right async call or if you have the right number of arguments.
+## Environment overrides
 
-So I decided, WTH, I had enough and I could just write one.
+- `JAM_LIBC=glibc|musl`: override Linux libc detection.
+- `JAM_BINARY_PATH=<path>`: run a specific local binary instead of the optional dependency binary.
 
-And you gotta admit, writing all these stuff is just god damned *fun*! XD
+## Local development
 
+Install dependencies with optional dependencies enabled so the matching platform package is available.

package/bin/jam.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+"use strict";
+
+let { spawnSync } = require("node:child_process");
+
+let { resolveBinaryPath } = require("../lib/resolve-binary");
+
+function main() {
+  try {
+    let binaryPath = resolveBinaryPath();
+    let result = spawnSync(binaryPath, process.argv.slice(2), {
+      stdio: "inherit",
+    });
+
+    if (result.error) throw result.error;
+
+    if (typeof result.status === "number") {
+      process.exit(result.status);
+    }
+
+    if (result.signal) {
+      process.kill(process.pid, result.signal);
+      return;
+    }
+  } catch (error) {
+    console.error(`[jam] ${error.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/lib/platform.js

@@ -0,0 +1,72 @@
+"use strict";
+
+function parseNodeLibcFromReport(report) {
+  if (!report || !report.header) return null;
+  if (report.header.glibcVersionRuntime) return "glibc";
+
+  let reportText = JSON.stringify(report).toLowerCase();
+  if (reportText.includes("musl")) return "musl";
+  return null;
+}
+
+function detectLibc(runtime) {
+  if (runtime.platform !== "linux") return null;
+
+  let forced = runtime.env.JAM_LIBC;
+  if (forced === "glibc" || forced === "musl") return forced;
+
+  let fromReport = parseNodeLibcFromReport(runtime.report);
+  if (fromReport) return fromReport;
+
+  return "glibc";
+}
+
+function resolveTarget(platform, arch, libc) {
+  if (platform === "darwin" && arch === "arm64") return "darwin-arm64";
+  if (platform === "darwin" && arch === "x64") return "darwin-x64";
+
+  if (platform === "linux" && arch === "x64" && libc === "glibc") return "linux-x64";
+  if (platform === "linux" && arch === "arm64" && libc === "glibc") return "linux-arm64";
+  if (platform === "linux" && libc === "musl") {
+    throw new Error(
+      `Linux musl is not supported yet: platform=${platform} arch=${arch} libc=${libc}`
+    );
+  }
+
+  throw new Error(
+    `Unsupported platform for Jam npm package: platform=${platform} arch=${arch} libc=${libc || "n/a"}`
+  );
+}
+
+function binaryFileName(platform) {
+  return platform === "win32" ? "jam.exe" : "jam";
+}
+
+function getRuntimeDescriptor(overrides) {
+  let platform = overrides?.platform ?? process.platform;
+  let arch = overrides?.arch ?? process.arch;
+  let report =
+    overrides?.report ??
+    (process.report && typeof process.report.getReport === "function"
+      ? process.report.getReport()
+      : null);
+  let env = overrides?.env ?? process.env;
+
+  let libc = detectLibc({ platform, env, report });
+  let target = resolveTarget(platform, arch, libc);
+
+  return {
+    arch,
+    libc,
+    platform,
+    target,
+    binaryName: binaryFileName(platform),
+  };
+}
+
+module.exports = {
+  binaryFileName,
+  detectLibc,
+  getRuntimeDescriptor,
+  resolveTarget,
+};

package/lib/resolve-binary.js

@@ -0,0 +1,30 @@
+"use strict";
+
+let {
+  packageNameForTarget,
+  resolveOptionalPackageBinaryPath,
+} = require("./resolve-optional-package");
+let { getRuntimeDescriptor } = require("./platform");
+
+function resolveBinaryPath() {
+  let fromEnv = process.env.JAM_BINARY_PATH;
+  if (fromEnv) return fromEnv;
+
+  let descriptor = getRuntimeDescriptor();
+  let optionalPath = resolveOptionalPackageBinaryPath(descriptor);
+  if (optionalPath) return optionalPath;
+
+  let packageName = packageNameForTarget(descriptor.target);
+
+  if (!packageName) {
+    throw new Error(`No optional dependency package is configured for ${descriptor.target}.`);
+  }
+
+  throw new Error(
+    `Jam optional dependency package not installed for ${descriptor.target}: ${packageName}. Try reinstalling with optional dependencies enabled.`
+  );
+}
+
+module.exports = {
+  resolveBinaryPath,
+};

package/lib/resolve-optional-package.js

@@ -0,0 +1,43 @@
+"use strict";
+
+let fs = require("node:fs");
+let path = require("node:path");
+
+let TARGET_TO_PACKAGE = {
+  "darwin-arm64": "jam-darwin-arm64",
+  "darwin-x64": "jam-darwin-x64",
+  "linux-x64": "jam-linux-x64",
+  "linux-arm64": "jam-linux-arm64",
+};
+
+function packageNameForTarget(target) {
+  return TARGET_TO_PACKAGE[target] || null;
+}
+
+function packageRootFromName(packageName) {
+  try {
+    let packageJsonPath = require.resolve(`${packageName}/package.json`, {
+      paths: [path.join(__dirname, "..")],
+    });
+    return path.dirname(packageJsonPath);
+  } catch {
+    return null;
+  }
+}
+
+function resolveOptionalPackageBinaryPath(runtimeDescriptor) {
+  let packageName = packageNameForTarget(runtimeDescriptor.target);
+  if (!packageName) return null;
+
+  let packageRoot = packageRootFromName(packageName);
+  if (!packageRoot) return null;
+
+  let binaryPath = path.join(packageRoot, "bin", runtimeDescriptor.binaryName);
+  if (!fs.existsSync(binaryPath)) return null;
+  return binaryPath;
+}
+
+module.exports = {
+  packageNameForTarget,
+  resolveOptionalPackageBinaryPath,
+};

package/package.json

@@ -1,36 +1,36 @@
 {
   "name": "jam",
-  "version": "0.6.1",
-  "description": "JAM your async calls together *faster*",
-  "main": "index.js",
-  "scripts": {
-    "test": "make test"
-  },
+  "version": "0.7.1",
+  "description": "An application server for isolated JavaScript",
+  "license": "MIT",
+  "type": "commonjs",
   "repository": {
     "type": "git",
-    "url": "git://github.com/chakrit/jam.git"
+    "url": "git+https://github.com/mjackson/jam.git",
+    "directory": "packages/jam"
+  },
+  "homepage": "https://github.com/mjackson/jam",
+  "bugs": {
+    "url": "https://github.com/mjackson/jam/issues"
   },
-  "keywords": [
-    "jam",
-    "async",
-    "monad",
-    "concurrent",
-    "parallel"
+  "bin": {
+    "jam": "bin/jam.js"
+  },
+  "optionalDependencies": {
+    "jam-darwin-arm64": "0.7.1",
+    "jam-darwin-x64": "0.7.1",
+    "jam-linux-x64": "0.7.1",
+    "jam-linux-arm64": "0.7.1"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
   ],
-  "author": "Chakrit Wichian <service@chakrit.net> (http://chakrit.net)",
-  "license": "BSD",
-  "readmeFilename": "README.md",
-  "directories": {
-    "test": "test",
-    "lib": "lib"
+  "engines": {
+    "node": ">=18"
   },
-  "devDependencies": {
-    "istanbul": "~0.1.43",
-    "mocha-istanbul": "~0.2.0",
-    "mocha": "~1.12.0",
-    "plato": "~0.6.1",
-    "chai": "~1.7.2",
-    "sinon": "~1.7.3",
-    "groc": "~0.4.0"
+  "scripts": {
+    "test": "node test/platform.test.js && node test/resolve-optional-package.test.js"
   }
-}
+}

package/.npmignore

@@ -1,6 +0,0 @@
-
-node_modules
-html-report
-lib-cov
-doc
-

package/.travis.yml

@@ -1,3 +0,0 @@
-language: node_js
-node_js:
-- 0.8

package/LICENSE

@@ -1,21 +0,0 @@
-The MIT License (MIT)
-Copyright (c) 2013 Chakrit Wichian <service@chakrit.net> (http://chakrit.net)
-
-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/Makefile

@@ -1,67 +0,0 @@
-
-BIN := $(shell pwd)/node_modules/.bin
-
-GLOBALS := __coverage__,buffertools,SlowBuffer,events,util,task
-TEST_ENV := test
-
-# Project files definition
-TEST_FILES := $(wildcard test/**/*.js) $(wildcard test/*.js)
-LIB_FILES := $(wildcard lib/**/*.js) $(wildcard lib/*.js)
-COV_FILES := $(LIB_FILES:lib/%.js=lib-cov/%.js)
-
-INDEX_FILE = index.js
-MAIN_FILE = lib/jam.js
-
-# Test parameters so we can configure these via make
-TEST_TIMEOUT = 100
-TEST_REPORTER = list
-TDD_REPORTER = min
-COVER_REPORTER = mocha-istanbul
-
-# Command-line tools options
-MOCHA_OPTS = --bail --timeout $(TEST_TIMEOUT) --reporter $(TEST_REPORTER) --globals $(GLOBALS)
-MOCHA_TDD_OPTS = $(MOCHA_OPTS) --watch --reporter $(TDD_REPORTER)
-MOCHA_COVER_OPTS = $(MOCHA_OPTS) --reporter $(COVER_REPORTER)
-ISTANBUL_OPTS = instrument --variable global.__coverage__ --no-compact
-PLATO_OPTS = -d html-report/
-GROC_OPTS = -t lib/ -o doc/ --no-whitespace-after-token false --index $(MAIN_FILE)
-
-
-default: node_modules
-
-node_modules:
-	npm install
-
-# File transformations
-lib-cov/%.js: lib/%.js
-	@mkdir -p $(@D)
-	$(BIN)/istanbul $(ISTANBUL_OPTS) --output $@ $<
-
-
-# Testing
-test: node_modules
-	NODE_ENV=$(TEST_ENV) $(BIN)/mocha $(MOCHA_OPTS) $(TEST_FILES)
-tdd: node_modules
-	NODE_ENV=$(TEST_ENV) $(BIN)/mocha $(MOCHA_TDD_OPTS) $(TEST_FILES)
-
-
-# Code instrumentation
-instrument: node_modules $(COV_FILES)
-cover: instrument
-	NODE_ENV=$(TEST_ENV) JAM_COVER=1 $(BIN)/mocha $(MOCHA_COVER_OPTS) $(TEST_FILES)
-complex:
-	$(BIN)/plato $(PLATO_OPTS) $(LIB_FILES)
-
-doc:
-	$(BIN)/groc $(GROC_OPTS) $(LIB_FILES)
-
-
-# Cleans
-clean:
-	-rm -Rf lib-cov/
-	-rm -Rf html-report/
-	-rm -Rf doc/
-
-
-.PHONY: debug default test tdd clean doc doc-gh instrument cover complex
-

package/example/file1.txt

@@ -1 +0,0 @@
-a - First! I am the very very first file.

package/example/file2.txt

@@ -1 +0,0 @@
-b - I am the second file, residing in B. 2nd's not a bad place, ain't it?

package/example/file3.txt

@@ -1 +0,0 @@
-c - I'm the last one. I get to write the ending!