jam 0.9.2 → 0.10.0

package/README.md

@@ -1,62 +1,28 @@
 # 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.
+`jam` is the canonical Jam install package.
 
 ## Usage
 
-```bash
+```sh
 jam [flags] [scripts-dir]
 ```
 
-Run `jam --help` for all options:
-
-```text
-Options:
-  --port <port>                            TCP port to listen on.
-  --host <host>                            Host or IP address to bind the TCP server to.
-  --unix <path>                            Unix socket path to listen on instead of TCP.
-  --php                                    Enable PHP-style globals such as $_GET, $_POST, and $_SERVER.
-  --public <dir>                           Directory for static files (checked before script routes).
-  --access-log                             Enable per-request access log output.
-  --config <path>                          Path to jamconfig.json (default: ./jamconfig.json).
-  --env <KEY=VALUE>                        Set an env var for scripts; include multiple times.
-  --log <path|->                           Log destination ('-' for stdout, otherwise a file path).
-  --log-level <error|warning|info|debug>   Minimum log level to emit (default: info).
-  --tls-cert <path>                        Path to TLS certificate PEM file.
-  --tls-key <path>                         Path to TLS private key PEM file.
-  --timeout-ms <ms>                        Maximum script execution time in milliseconds.
-  --request-max-body-bytes <bytes>         Maximum allowed request body size in bytes.
-  --request-max-header-bytes <bytes>       Maximum allowed request header size in bytes.
-  --workers <count>                        Worker pool size (0 uses automatic sizing).
-  --worker-memory-mb <mb>                  Per-worker memory limit in MB.
-  --worker-max-requests <count>            Recycle a worker after this many requests.
-  --mode <value>                           Runtime mode string (commonly production or development).
-  --error-page-404 <path>                  Path to a custom 404 error page.
-  --error-page-500 <path>                  Path to a custom 500 error page.
-  --help                                   Print this help message and exit.
-  --version                                Print version and exit.
-
-Examples:
-  jam
-  jam --port 3000
-  jam ./app
-  jam --php --public ./public ./app
-```
-
-Warning and error messages are written to stderr, while info/debug messages are written to stdout when logging to stdout.
-When stderr is an interactive terminal, warning output is yellow and error output is red.
-Set `NO_COLOR` in the environment to force no colors.
+## Notes
 
-## Development
+- `jam` installs the matching `jam-<os>-<arch>` platform package through npm `optionalDependencies`.
+- The platform package provides the Node SEA executable that actually runs the server.
+- This package publishes the ambient `jam` TypeScript types.
 
-`jam` has two entry points with different roles:
+## Ambient Types
 
-- `bin/jam.js`: Node-facing dispatch shim for the npm package.
-  - This is what `npx jam` and `npm/yarn/pnpm` bin resolution executes.
-  - It picks the correct platform package (`jam-darwin-arm64`, `jam-darwin-x64`, `jam-linux-arm64`, `jam-linux-x64`), installs it if needed, and forwards execution to its binary.
-- `src/entry.ts`: Bun runtime CLI entrypoint.
-  - This is what gets compiled into each platform binary.
-  - It should remain minimal and primarily call into `main` from `src/main.ts`.
-  - CI and release scripts build it for each target.
+Ambient `jam` types are generated from `packages/jam-node/types/` when this package is built.
+Fixtures/apps consume the published types with:
 
-The fallback path used in `bin/jam.js` (`../src/entry.ts`) is for local development when running from a checked out repo and the platform package binary is unavailable.
+```json
+{
+  "compilerOptions": {
+    "types": ["jam"]
+  }
+}
+```

package/bin/jam.js

@@ -1,22 +1,5 @@
 #!/usr/bin/env node
 
-// This is the user-facing Node entrypoint for the npm `jam` package.
-// `npx jam` and the package binary in `package.json` resolve here first.
-//
-// It exists because the published `jam` package is a tiny bootstrap layer:
-// it detects the host platform, resolves the corresponding platform package
-// (`jam-darwin-arm64`, `jam-darwin-x64`, `jam-linux-arm64`, `jam-linux-x64`),
-// and executes the native Jam binary shipped by that package.
-//
-// If the platform package is not installed yet, this shim tries to install it
-// on demand via `npm install <platform-package>@<version> --no-save`.
-// If Bun is available in a local repo checkout and no platform package is
-// present, it falls back to running `src/main.ts` directly for development.
-//
-// `src/entry.ts` is the Bun source entrypoint used by platform package builds;
-// this file (`jam.js`) is the runtime dispatcher that selects and runs them.
-
-import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { createRequire } from "node:module";
@@ -25,8 +8,6 @@ import { fileURLToPath } from "node:url";
 let require = createRequire(import.meta.url);
 let THIS_FILE = fileURLToPath(import.meta.url);
 let THIS_DIR = path.dirname(THIS_FILE);
-let PACKAGE_DIR = path.resolve(THIS_DIR, "..");
-let PACKAGE_JSON = path.join(PACKAGE_DIR, "package.json");
 
 function resolvePlatformPackageName() {
   let key = `${process.platform}-${process.arch}`;
@@ -72,61 +53,11 @@ function resolvePlatformBinary(packageName) {
   return path.join(path.dirname(packageJsonPath), "bin", "jam");
 }
 
-function getMainPackageVersion() {
-  let packageJson = JSON.parse(fs.readFileSync(PACKAGE_JSON, "utf8"));
-  return packageJson.version;
-}
-
-function installPlatformPackage(packageName) {
-  let version = getMainPackageVersion();
-  let packageSpec = `${packageName}@${version}`;
-
-  let npmHasInstall = false;
-  let npmVersionResult = spawnSync("npm", ["--version"], {
-    stdio: "ignore"
-  });
-
-  if (
-    typeof npmVersionResult.status === "number" &&
-    npmVersionResult.status === 0
-  ) {
-    npmHasInstall = true;
-  }
-
-  if (!npmHasInstall) {
-    throw new Error(
-      "npm is required to install the platform package automatically."
-    );
-  }
-
-  let result = runProcess(
-    "npm",
-    ["install", packageSpec, "--no-save", "--no-audit", "--no-fund"],
-    {
-      cwd: PACKAGE_DIR
-    }
-  );
-
-  if (result !== 0) {
-    throw new Error(`npm install failed for ${packageSpec} (status: ${result}).`);
-  }
-}
-
 function runPlatformBinary(packageName, args) {
   let binaryPath = resolvePlatformBinary(packageName);
   return runProcess(binaryPath, args);
 }
 
-function maybeRunDevFallback(args) {
-  let sourceEntrypoint = path.resolve(THIS_DIR, "../src/entry.ts");
-  if (!fs.existsSync(sourceEntrypoint)) {
-    return false;
-  }
-
-  runProcess("bun", [sourceEntrypoint, ...args]);
-  return true;
-}
-
 function main() {
   let packageName = resolvePlatformPackageName();
 
@@ -144,36 +75,12 @@ function main() {
     let exitCode = runPlatformBinary(packageName, args);
     process.exit(exitCode);
   } catch (error) {
-    let installError = null;
-    if (
-      error instanceof Error &&
-      error.message.includes("Could not resolve") &&
-      error.message.includes(`${packageName}/package.json`)
-    ) {
-      try {
-        process.stderr.write(
-          `[jam] Installing platform package ${packageName}...\n`
-        );
-        installPlatformPackage(packageName);
-        let exitCode = runPlatformBinary(packageName, args);
-        process.exit(exitCode);
-      } catch (secondError) {
-        installError = secondError;
-      }
-    }
-
-    if (installError === null && maybeRunDevFallback(args)) {
-      return;
-    }
-
-    let message = installError instanceof Error
-      ? installError.message
-      : error instanceof Error
-        ? error.message
-        : String(error);
+    let message = error instanceof Error
+      ? error.message
+      : String(error);
     process.stderr.write(
-      `[jam] Could not find platform binary package ${packageName}. ` +
-      `Try reinstalling dependencies. (${message})\n`
+      `[jam] Could not find the installed platform binary ${packageName}. ` +
+      `Reinstall the \`jam\` package so npm can restore the matching optional dependency. (${message})\n`
     );
     process.exit(1);
   }

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "jam",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "description": "An application server for isolated JavaScript",
   "license": "MIT",
+  "author": "Michael Jackson <mjijackson@gmail.com>",
   "type": "module",
   "types": "types/index.d.ts",
   "repository": {
@@ -28,28 +29,22 @@
     ]
   },
   "optionalDependencies": {
-    "jam-darwin-arm64": "0.9.2",
-    "jam-darwin-x64": "0.9.2",
-    "jam-linux-arm64": "0.9.2",
-    "jam-linux-x64": "0.9.2"
-  },
-  "dependencies": {
-    "@jridgewell/trace-mapping": "^0.3.31",
-    "typescript": "^5.6.3"
+    "jam-darwin-arm64": "0.10.0",
+    "jam-darwin-x64": "0.10.0",
+    "jam-linux-arm64": "0.10.0",
+    "jam-linux-x64": "0.10.0"
   },
   "devDependencies": {
-    "@types/node": "^22.15.31",
-    "bun-types": "^1.2.8"
+    "@types/node": "^24.0.0",
+    "typescript": "^5.6.3"
   },
   "engines": {
-    "bun": ">=1.2"
+    "node": ">=24.14.0"
   },
   "scripts": {
+    "build": "node ./scripts/build-types.js",
     "lint": "eslint .",
-    "typecheck": "tsc -p tsconfig.json",
-    "test": "bun run test:unit && bun run test:integration",
-    "test:unit": "bun test ./src/**/*.test.ts",
-    "test:integration": "bun test ./test/*.test.ts",
-    "build:bin": "bun build ./src/entry.ts --compile --outfile ./dist/jam && bun build ./src/worker-thread.ts --target=bun --outfile ./dist/worker-thread.js"
+    "typecheck": "pnpm run build && tsc -p tsconfig.json",
+    "test": "node --eval \"\""
   }
 }

package/types/jam/index.d.ts

@@ -46,10 +46,135 @@ declare module "jam:test" {
     operator: string;
   }
 
+  export type AssertPredicate =
+    | RegExp
+    | (new (...args: unknown[]) => object)
+    | ((thrown: unknown) => boolean)
+    | object
+    | Error;
+
   export namespace assert {
-    function ok(value: unknown, message?: string): asserts value;
-    function equal(actual: unknown, expected: unknown, message?: string): void;
-    function deepEqual(actual: unknown, expected: unknown, message?: string): void;
+    function ok(value: unknown, message?: string | Error): asserts value;
+    function equal(actual: unknown, expected: unknown, message?: string | Error): void;
+    function notEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+    function fail(message?: string | Error): never;
+    function fail(
+      actual: unknown,
+      expected: unknown,
+      message?: string | Error,
+      operator?: string,
+      stackStartFn?: Function
+    ): never;
+    function ifError(value: unknown): void;
+    function match(string: string, regexp: RegExp, message?: string | Error): void;
+    function doesNotMatch(string: string, regexp: RegExp, message?: string | Error): void;
+    function strictEqual<T>(actual: unknown, expected: T, message?: string | Error): asserts actual is T;
+    function notStrictEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+    function deepEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+    function deepStrictEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+    function notDeepEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+    function notDeepStrictEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+    function throws(
+      fn: () => unknown,
+      message?: string | Error
+    ): void;
+    function throws(
+      fn: () => unknown,
+      expected: AssertPredicate,
+      message?: string | Error
+    ): void;
+    function doesNotThrow(
+      fn: () => unknown,
+      message?: string | Error
+    ): void;
+    function doesNotThrow(
+      fn: () => unknown,
+      expected: AssertPredicate,
+      message?: string | Error
+    ): void;
+    function rejects(
+      promiseOrFn: Promise<unknown> | (() => Promise<unknown>),
+      message?: string | Error
+    ): Promise<void>;
+    function rejects(
+      promiseOrFn: Promise<unknown> | (() => Promise<unknown>),
+      expected: AssertPredicate,
+      message?: string | Error
+    ): Promise<void>;
+    function doesNotReject(
+      promiseOrFn: Promise<unknown> | (() => Promise<unknown>),
+      message?: string | Error
+    ): Promise<void>;
+    function doesNotReject(
+      promiseOrFn: Promise<unknown> | (() => Promise<unknown>),
+      expected: AssertPredicate,
+      message?: string | Error
+    ): Promise<void>;
+    function partialDeepStrictEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+  }
+
+  export function strict(value: unknown, message?: string | Error): asserts value;
+
+  export namespace strict {
+    export { AssertionError, strict };
+
+    function ok(value: unknown, message?: string | Error): asserts value;
+    function equal<T>(actual: unknown, expected: T, message?: string | Error): asserts actual is T;
+    function notEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+    function fail(message?: string | Error): never;
+    function fail(
+      actual: unknown,
+      expected: unknown,
+      message?: string | Error,
+      operator?: string,
+      stackStartFn?: Function
+    ): never;
+    function ifError(value: unknown): void;
+    function match(string: string, regexp: RegExp, message?: string | Error): void;
+    function doesNotMatch(string: string, regexp: RegExp, message?: string | Error): void;
+    function strictEqual<T>(actual: unknown, expected: T, message?: string | Error): asserts actual is T;
+    function notStrictEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+    function deepEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+    function deepStrictEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+    function notDeepEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+    function notDeepStrictEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+    function throws(
+      fn: () => unknown,
+      message?: string | Error
+    ): void;
+    function throws(
+      fn: () => unknown,
+      expected: AssertPredicate,
+      message?: string | Error
+    ): void;
+    function doesNotThrow(
+      fn: () => unknown,
+      message?: string | Error
+    ): void;
+    function doesNotThrow(
+      fn: () => unknown,
+      expected: AssertPredicate,
+      message?: string | Error
+    ): void;
+    function rejects(
+      promiseOrFn: Promise<unknown> | (() => Promise<unknown>),
+      message?: string | Error
+    ): Promise<void>;
+    function rejects(
+      promiseOrFn: Promise<unknown> | (() => Promise<unknown>),
+      expected: AssertPredicate,
+      message?: string | Error
+    ): Promise<void>;
+    function doesNotReject(
+      promiseOrFn: Promise<unknown> | (() => Promise<unknown>),
+      message?: string | Error
+    ): Promise<void>;
+    function doesNotReject(
+      promiseOrFn: Promise<unknown> | (() => Promise<unknown>),
+      expected: AssertPredicate,
+      message?: string | Error
+    ): Promise<void>;
+    function partialDeepStrictEqual(actual: unknown, expected: unknown, message?: string | Error): void;
   }
 
   export interface SpyCall {
@@ -73,6 +198,102 @@ declare module "jam:test" {
   export function restoreAll(): void;
 }
 
+declare module "jam:test/strict" {
+  export class AssertionError extends Error {
+    actual: unknown;
+    expected: unknown;
+    operator: string;
+  }
+
+  export type AssertPredicate = import("jam:test").AssertPredicate;
+
+  export function ok(value: unknown, message?: string | Error): asserts value;
+  export function equal<T>(actual: unknown, expected: T, message?: string | Error): asserts actual is T;
+  export function notEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+  export function fail(message?: string | Error): never;
+  export function fail(
+    actual: unknown,
+    expected: unknown,
+    message?: string | Error,
+    operator?: string,
+    stackStartFn?: Function
+  ): never;
+  export function ifError(value: unknown): void;
+  export function match(string: string, regexp: RegExp, message?: string | Error): void;
+  export function doesNotMatch(string: string, regexp: RegExp, message?: string | Error): void;
+  export function strictEqual<T>(actual: unknown, expected: T, message?: string | Error): asserts actual is T;
+  export function notStrictEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+  export function deepEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+  export function deepStrictEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+  export function notDeepEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+  export function notDeepStrictEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+  export function throws(
+    fn: () => unknown,
+    message?: string | Error
+  ): void;
+  export function throws(
+    fn: () => unknown,
+    expected: AssertPredicate,
+    message?: string | Error
+  ): void;
+  export function doesNotThrow(
+    fn: () => unknown,
+    message?: string | Error
+  ): void;
+  export function doesNotThrow(
+    fn: () => unknown,
+    expected: AssertPredicate,
+    message?: string | Error
+  ): void;
+  export function rejects(
+    promiseOrFn: Promise<unknown> | (() => Promise<unknown>),
+    message?: string | Error
+  ): Promise<void>;
+  export function rejects(
+    promiseOrFn: Promise<unknown> | (() => Promise<unknown>),
+    expected: AssertPredicate,
+    message?: string | Error
+  ): Promise<void>;
+  export function doesNotReject(
+    promiseOrFn: Promise<unknown> | (() => Promise<unknown>),
+    message?: string | Error
+  ): Promise<void>;
+  export function doesNotReject(
+    promiseOrFn: Promise<unknown> | (() => Promise<unknown>),
+    expected: AssertPredicate,
+    message?: string | Error
+  ): Promise<void>;
+  export function partialDeepStrictEqual(actual: unknown, expected: unknown, message?: string | Error): void;
+  export function strict(value: unknown, message?: string | Error): asserts value;
+
+  export namespace strict {
+    export {
+      AssertionError,
+      deepEqual,
+      deepStrictEqual,
+      doesNotMatch,
+      doesNotReject,
+      doesNotThrow,
+      equal,
+      fail,
+      ifError,
+      match,
+      notDeepEqual,
+      notDeepStrictEqual,
+      notEqual,
+      notStrictEqual,
+      ok,
+      partialDeepStrictEqual,
+      rejects,
+      strict,
+      strictEqual,
+      throws
+    };
+  }
+
+  export default strict;
+}
+
 declare type JamPhpFile = {
   name: string;
   type: string;