jam 0.6.0 → 0.7.0

package/README.md

@@ -1,249 +1,44 @@
-[![Build Status](https://travis-ci.org/chakrit/jam.png?branch=master)](https://travis-ci.org/chakrit/jam)
+# jam
 
-# JAM JAM JAM
+Install and run the Jam server binary from npm.
 
-```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.
+## Usage
 
-# HELPERS
-
-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(); } );
-```
-
-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.
-
-This function fixes this case by inserting a nextTick() in-between the call chain to make
-sure it executes on `process.nextTick`.
-
-This function is actually just an alias for `.identity`
-
-#### return( [args...] )
-
-```js
-function handleFileContent(e, file) {
-};
-
-// 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
-  });
+```sh
+npm install -g jam
+jam --help
 ```
 
-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(',');
+You can also use it without a global install:
 
-jam(jam.map(FILES, function(next, filename) {
-  fs.readFile(filename, next);
-
-})(function(e, result) {
-  var cat = result.join('');
-  console.log(cat);
-
-});
+```sh
+npx jam --help
 ```
 
-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`.
-
-See the `example/map.js` file for more information.
-
-# LICENSE
-
-BSD
-
-# 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.
-
-#### TODOs
+## How it works
 
-* 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() ?
+On install, this package detects your OS/CPU target and downloads the matching Jam binary from GitHub Releases.
 
-# WHY ?
+Expected release asset names:
 
-Short answer: Because the existing ones are so cumbersome to use that I just had enough
-with it.
+- `jam-darwin-arm64`
+- `jam-darwin-x64`
+- `jam-linux-x64`
+- `jam-linux-arm64`
 
-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.
+Current support is macOS (`darwin`) and Linux glibc builds. Linux musl and Windows targets are not published yet.
 
-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.
+The binary is stored inside this package at `downloaded/jam`, and the `jam` npm bin shim executes it.
 
-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_SKIP_DOWNLOAD=1`: skip binary download during install.
+- `JAM_FORCE_DOWNLOAD=1`: force download even in the Jam source checkout.
+- `JAM_BINARY_VERSION=<version>`: download a different Jam release version.
+- `JAM_BINARY_BASE_URL=<url>`: override the release URL prefix.
+- `JAM_LIBC=glibc|musl`: override Linux libc detection.
+- `JAM_BINARY_PATH=<path>`: run a specific local binary instead of the downloaded one.
 
-And you gotta admit, writing all these stuff is just god damned *fun*! XD
+## Local development
 
+When installing from the Jam source checkout (`packages/jam` workspace), postinstall download is skipped automatically. Set `JAM_FORCE_DOWNLOAD=1` to force a download during local testing.

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/install.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+"use strict";
+
+let fs = require("node:fs");
+let path = require("node:path");
+let { Readable } = require("node:stream");
+let { pipeline } = require("node:stream/promises");
+
+let { getRuntimeDescriptor } = require("./lib/platform");
+let { downloadedBinaryPath } = require("./lib/resolve-binary");
+
+let MAX_REDIRECTS = 5;
+let REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+
+function loadPackageVersion() {
+  let pkgPath = path.join(__dirname, "package.json");
+  let pkgJson = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+  return pkgJson.version;
+}
+
+function shouldSkipInstall(version) {
+  if (process.env.JAM_SKIP_DOWNLOAD === "1") return true;
+  if (isJamSourceCheckout() && process.env.JAM_FORCE_DOWNLOAD !== "1") return true;
+  return version.startsWith("0.0.0-");
+}
+
+function isJamSourceCheckout() {
+  let repoRoot = path.join(__dirname, "..", "..");
+  return (
+    fs.existsSync(path.join(repoRoot, "go.mod")) &&
+    fs.existsSync(path.join(repoRoot, "cmd", "jam", "main.go")) &&
+    fs.existsSync(path.join(repoRoot, "pnpm-workspace.yaml"))
+  );
+}
+
+function buildDownloadUrl(target, binaryName, version) {
+  let releaseVersion = process.env.JAM_BINARY_VERSION || version;
+  let explicitBaseUrl = process.env.JAM_BINARY_BASE_URL;
+  let baseUrl =
+    explicitBaseUrl ||
+    `https://github.com/mjackson/jam/releases/download/v${releaseVersion}`;
+  return `${baseUrl.replace(/\/+$/, "")}/jam-${target}${binaryName.endsWith(".exe") ? ".exe" : ""}`;
+}
+
+async function fetchToFile(url, filePath, redirects) {
+  if (redirects > MAX_REDIRECTS) {
+    throw new Error(`Too many redirects while downloading ${url}`);
+  }
+
+  let response = await fetch(url, {
+    headers: {
+      "user-agent": "jam-npm-installer",
+    },
+    redirect: "manual",
+  });
+
+  if (REDIRECT_STATUSES.has(response.status)) {
+    let location = response.headers.get("location");
+    if (!location) {
+      throw new Error(`Redirect missing location header: ${response.status} ${url}`);
+    }
+    let redirectUrl = new URL(location, url).toString();
+    await fetchToFile(redirectUrl, filePath, redirects + 1);
+    return;
+  }
+
+  if (response.status !== 200) {
+    throw new Error(`Download failed: ${response.status} ${url}`);
+  }
+
+  if (!response.body) {
+    throw new Error(`Download failed: empty response body for ${url}`);
+  }
+
+  let out = fs.createWriteStream(filePath, { mode: 0o755 });
+  await pipeline(Readable.fromWeb(response.body), out);
+}
+
+async function install() {
+  let version = loadPackageVersion();
+  if (shouldSkipInstall(version)) {
+    if (isJamSourceCheckout()) {
+      console.log("[jam] Skipping binary download in Jam source checkout.");
+      return;
+    }
+    console.log("[jam] Skipping binary download.");
+    return;
+  }
+
+  let descriptor = getRuntimeDescriptor();
+  let downloadUrl = buildDownloadUrl(descriptor.target, descriptor.binaryName, version);
+  let outputPath = downloadedBinaryPath(descriptor);
+
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  console.log(`[jam] Downloading ${descriptor.target} binary from ${downloadUrl}`);
+  await fetchToFile(downloadUrl, outputPath, 0);
+
+  if (descriptor.platform !== "win32") {
+    fs.chmodSync(outputPath, 0o755);
+  }
+
+  console.log(`[jam] Installed binary to ${outputPath}`);
+}
+
+install().catch((error) => {
+  console.error(`[jam] ${error.message}`);
+  process.exit(1);
+});

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,37 @@
+"use strict";
+
+let fs = require("node:fs");
+let path = require("node:path");
+
+let { getRuntimeDescriptor } = require("./platform");
+
+function packageRoot() {
+  return path.join(__dirname, "..");
+}
+
+function downloadedBinaryPath(runtimeDescriptor) {
+  let descriptor = runtimeDescriptor || getRuntimeDescriptor();
+  return path.join(packageRoot(), "downloaded", descriptor.binaryName);
+}
+
+function resolveBinaryPath() {
+  let fromEnv = process.env.JAM_BINARY_PATH;
+  if (fromEnv) return fromEnv;
+
+  let descriptor = getRuntimeDescriptor();
+  let targetPath = downloadedBinaryPath(descriptor);
+  if (fs.existsSync(targetPath)) return targetPath;
+
+  throw new Error(
+    [
+      `Jam binary not found for ${descriptor.target}.`,
+      `Expected: ${targetPath}`,
+      "Try reinstalling the package or run `npm rebuild jam`.",
+    ].join("\n")
+  );
+}
+
+module.exports = {
+  downloadedBinaryPath,
+  resolveBinaryPath,
+};

package/package.json

@@ -1,36 +1,33 @@
 {
   "name": "jam",
-  "version": "0.6.0",
-  "description": "JAM your async calls together *faster*",
-  "main": "index.js",
-  "scripts": {
-    "test": "make test"
-  },
+  "version": "0.7.0",
+  "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"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "install.js",
+    "README.md"
   ],
-  "author": "Chakrit Wichian <service@chakrit.net> (http://chakrit.net)",
-  "license": "BSD",
-  "readmeFilename": "README.md",
-  "directories": {
-    "test": "test",
-    "lib": "lib"
+  "scripts": {
+    "postinstall": "node install.js",
+    "test": "node test/platform.test.js",
+    "prepublishOnly": "node test/platform.test.js"
   },
-  "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"
+  "engines": {
+    "node": ">=18"
   }
 }

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/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!