bare-stow 0.1.1 → 0.1.3

package/README.md

@@ -118,7 +118,7 @@ await ipc.ready
 
 Bundle the module graph rooted at `entry` for a `target` runtime and write the resulting artifacts to disk at and alongside `out`. Returns an async generator that yields `{ url }` objects as each artifact is written, allowing callers to observe progress.
 
-`entry` is a `URL` (or `URL`-coercible string) pointing at the entry module. `target` selects the target runtime, given either as the built-in name `'bare-sidecar'` or as a [target provider](#targets-and-rpc-providers) object. Other targets ship as their own packages; require one and pass it as the provider. The target determines the harness format, bundle extension, host triples, and whether assets and addons are linked into the bundle or offloaded as sibling files. `out` is the output `URL` of the harness; the bundle is written next to it with the target's extension.
+`entry` is a `URL` (or `URL`-coercible string) pointing at the entry module. `target` selects the target runtime, given either as a built-in name (`'bare-sidecar'` or `'bare-worker'`) or as a [target provider](#targets-and-rpc-providers) object. Other targets ship as their own packages; require one and pass it as the provider. The target determines the harness format, bundle extension, host triples, and whether assets and addons are linked into the bundle or offloaded as sibling files. `out` is the output `URL` of the harness; the bundle is written next to it with the target's extension.
 
 The harness artifacts are yielded first: The harness itself at `out`, followed by a TypeScript declaration (`.d.ts`) alongside it so hosts importing the harness are typed. The bundle is yielded next, then any offloaded assets and native addons when the target supports offloading.
 
@@ -139,7 +139,7 @@ opts = {
 - `server`: The RPC library to wire into the bundle entry shim as a server, given either as a built-in name (`'bare-rpc'`) or as an [RPC provider](#targets-and-rpc-providers) object.
 - `base`: The base `URL` of the module graph. Defaults to the directory containing `entry`.
 - `hosts`: An array of host triples to build for. Must be a subset of the host triples supported by the target; passing a host the target does not support throws. Defaults to all host triples supported by the target.
-- `resolveTarget`: A function mapping a target name to a [target provider](#targets-and-rpc-providers) object, called when `target` is a name not in the built-in registry (which only knows `'bare-sidecar'`).
+- `resolveTarget`: A function mapping a target name to a [target provider](#targets-and-rpc-providers) object, called when `target` is a name not in the built-in registry (which knows `'bare-sidecar'` and `'bare-worker'`).
 - `resolveRPC`: A function mapping an RPC library name to an [RPC provider](#targets-and-rpc-providers) object, called when `client` or `server` is a name not in the built-in registry (which only knows `'bare-rpc'`).
 
 Any additional options are forwarded to `bare-pack`. See <https://github.com/holepunchto/bare-pack> for the full set, including `builtins`, `imports`, `defer`, and `resolve`.
@@ -171,9 +171,9 @@ target = {
   format, // The bundle encoding: 'bundle', 'bundle.cjs', 'bundle.mjs', or 'bundle.json'.
   encoding, // The string encoding for encoded formats, or null for raw bytes.
   extension, // The bundle file extension, e.g. '.bundle'.
-  module, // The harness module system: 'esm' or 'cjs'.
+  module, // Optional. Pins the harness module system to 'esm' or 'cjs'.
   hosts, // The host triples the target supports.
-  generate({ bundleSpecifier, ipc, rpc, client }) {
+  generate({ bundleSpecifier, ipc, rpc, module, client }) {
     // Return an array of harness artifacts.
   }
 }
@@ -181,7 +181,9 @@ target = {
 
 For a target, each artifact is a file. The first has no `extension` and is written to `out`; each remaining artifact is written next to `out` with its own `extension` substituted for the harness extension (e.g. `{ extension: '.d.ts' }` becomes `index.d.ts`). The built-in targets emit two artifacts: The harness and its TypeScript declaration.
 
-`generate()` receives `bundleSpecifier`, the relative specifier from the harness to the bundle artifact; `ipc`, the identifier the harness should bind the IPC stream to; `rpc`, the identifier the RPC client setup binds its instance to; and `client`, the resolved RPC client (or `null` when no client is requested). When present, `client` is `{ source, type }`: `source` is the runtime setup to splice into the harness (referencing `ipc` and binding `rpc`), and `type` is the TypeScript type of the bound instance to splice into the declaration. The target owns `linked`, `offload`, `format`, `encoding`, and `extension`; they are not overridable through `opts`.
+`generate()` receives `bundleSpecifier`, the relative specifier from the harness to the bundle artifact; `ipc`, the identifier the harness should bind the IPC stream to; `rpc`, the identifier the RPC client setup binds its instance to; `module`, the harness module system (`'esm'` or `'cjs'`) so the harness can emit the matching module and import forms; and `client`, the resolved RPC client (or `null` when no client is requested). When present, `client` is `{ source, type }`: `source` is the runtime setup to splice into the harness (referencing `ipc` and binding `rpc`), and `type` is the TypeScript type of the bound instance to splice into the declaration. The target owns `linked`, `offload`, `format`, `encoding`, and `extension`; they are not overridable through `opts`.
+
+The harness `module` system is derived from the output path: `out` ending in `.mjs` is ESM and `.cjs` is CommonJS, while an ambiguous `.js` (or other) extension follows the `type` of the closest enclosing `package.json` (`"module"` is ESM, otherwise CommonJS). A target may set its own `module` to pin the harness to one system regardless of the output path.
 
 An RPC provider generates the wiring that binds an RPC instance to the IPC stream, used on both the client (harness) and server (shim) side:
 
@@ -194,7 +196,7 @@ rpc = {
 }
 ```
 
-For an RPC provider, each artifact is a fragment contributed to the harness file with the matching extension. The artifact with no `extension` is the runtime setup (reading `ipc`, binding `rpc`); the `{ extension: '.d.ts' }` artifact is the TypeScript type of the bound instance. `generate()` receives `ipc`, the identifier of the IPC stream in scope; `rpc`, the identifier to bind the RPC instance to; `module`, the surrounding module system (`'esm'` or `'cjs'`) so the runtime fragment can emit the matching import form; and `role`, either `'client'` or `'server'`. The bundler owns the `ipc` and `rpc` binding names and threads them to both the target and the RPC provider so neither has to assume them. It renders the client in the target's `module` and the server as `'esm'` (the shim is always an ES module), splicing the runtime fragment and, for the client, the type fragment into the target's artifacts. The shim is not a typed, host-facing module, so the server's type fragment is unused.
+For an RPC provider, each artifact is a fragment contributed to the harness file with the matching extension. The artifact with no `extension` is the runtime setup (reading `ipc`, binding `rpc`); the `{ extension: '.d.ts' }` artifact is the TypeScript type of the bound instance. `generate()` receives `ipc`, the identifier of the IPC stream in scope; `rpc`, the identifier to bind the RPC instance to; `module`, the surrounding module system (`'esm'` or `'cjs'`) so the runtime fragment can emit the matching import form; and `role`, either `'client'` or `'server'`. The bundler owns the `ipc` and `rpc` binding names and threads them to both the target and the RPC provider so neither has to assume them. It renders the client in the harness `module` and the server as `'esm'` (the shim is always an ES module), splicing the runtime fragment and, for the client, the type fragment into the target's artifacts. The shim is not a typed, host-facing module, so the server's type fragment is unused.
 
 ## CLI
 
@@ -218,7 +220,7 @@ Stow the module graph rooted at `<entry>`, writing the harness and bundle to the
 
 ##### `--target <name>`
 
-The target runtime. Required. The built-in `bare-sidecar` is resolved directly; any other `<name>` is loaded from its `bare-stow-target-<name>` package, or from `<name>` itself as a full module specifier, resolved from the working directory.
+The target runtime. Required. The built-in `bare-sidecar` and `bare-worker` are resolved directly; any other `<name>` is loaded from its `bare-stow-target-<name>` package, or from `<name>` itself as a full module specifier, resolved from the working directory.
 
 ##### `--client <name>` and `--server <name>`
 

package/index.d.ts

@@ -5,12 +5,13 @@ interface Artifact {
   source: string
 }
 
-type TargetName = 'bare-sidecar'
+type TargetName = 'bare-sidecar' | 'bare-worker'
 
 interface TargetContext {
   bundleSpecifier: string
   ipc: string
   rpc: string
+  module: 'esm' | 'cjs'
   client: RPCClient | null
 }
 
@@ -21,7 +22,7 @@ interface Target {
   format: 'bundle' | 'bundle.cjs' | 'bundle.mjs' | 'bundle.json'
   encoding: string | null
   extension: string
-  module: 'esm' | 'cjs'
+  module?: 'esm' | 'cjs'
   hosts: string[]
   generate(context: TargetContext): Artifact[]
 }

package/index.js

@@ -23,6 +23,9 @@ module.exports = async function* stow(entry, target, out, opts = {}) {
   out = new URL(out)
   base = base ? new URL(base) : new URL('./', entry)
 
+  // The target may pin a module system; otherwise it follows the output path.
+  const module = t.module || (await resolveModule(out))
+
   if (hosts) {
     for (const host of hosts) {
       if (!t.hosts.includes(host)) {
@@ -93,8 +96,8 @@ module.exports = async function* stow(entry, target, out, opts = {}) {
     const artifacts = rpc(client, resolveRPC).generate({
       ipc: 'ipc',
       rpc: 'rpc',
-      module: t.module,
-      role: 'client'
+      role: 'client',
+      module
     })
 
     clientSetup = {
@@ -107,6 +110,7 @@ module.exports = async function* stow(entry, target, out, opts = {}) {
     bundleSpecifier,
     ipc: 'ipc',
     rpc: 'rpc',
+    module,
     client: clientSetup
   })
 
@@ -171,6 +175,39 @@ function collectOffloaded(base, out, sink) {
   }
 }
 
+async function resolveModule(out) {
+  switch (path.extname(out.pathname)) {
+    case '.mjs':
+      return 'esm'
+    case '.cjs':
+      return 'cjs'
+  }
+
+  // For an ambiguous extension (e.g. '.js') the module system follows the
+  // `type` of the closest enclosing `package.json`, defaulting to CommonJS.
+  return (await packageType(new URL('./', out))) === 'module' ? 'esm' : 'cjs'
+}
+
+async function packageType(dir) {
+  while (true) {
+    let source = null
+
+    try {
+      source = await fs.readFile(new URL('package.json', dir))
+    } catch {
+      // No `package.json` in this directory; keep searching upwards.
+    }
+
+    if (source !== null) return JSON.parse(source).type ?? null
+
+    const parent = new URL('../', dir)
+
+    if (parent.pathname === dir.pathname) return null
+
+    dir = parent
+  }
+}
+
 function siblingURL(out, extension) {
   const dir = new URL('./', out)
   const base = path.basename(out.pathname, path.extname(out.pathname))

package/lib/target/bare-sidecar.js

@@ -4,7 +4,6 @@ exports.offload = true
 exports.format = 'bundle'
 exports.encoding = null
 exports.extension = '.bundle'
-exports.module = 'cjs'
 exports.hosts = [
   'darwin-arm64',
   'darwin-x64',
@@ -15,7 +14,9 @@ exports.hosts = [
 ]
 
 exports.generate = function generate(opts) {
-  const { bundleSpecifier, ipc, rpc, client = null } = opts
+  const { bundleSpecifier, ipc, rpc, module = 'cjs', client = null } = opts
+
+  const esm = module === 'esm'
 
   const returned = client ? `{ ${ipc}, ${rpc} }` : `{ ${ipc} }`
 
@@ -23,9 +24,25 @@ exports.generate = function generate(opts) {
     ? `{ ${ipc}: import('bare-stow/host').IPC; ${rpc}: ${client.type} }`
     : `{ ${ipc}: import('bare-stow/host').IPC }`
 
-  return [
-    {
-      source: `\
+  const source = esm
+    ? `\
+import Sidecar from 'bare-sidecar'
+import stow from 'bare-stow/host'
+import { fileURLToPath } from 'url'
+
+const bundle = fileURLToPath(new URL(${JSON.stringify(bundleSpecifier)}, import.meta.url))
+
+export async function start(opts = {}) {
+  const sidecar = new Sidecar(bundle, opts)
+
+  const ${ipc} = stow.wrap(sidecar)
+${client ? '\n' + indent(client.source, 2) : ''}
+  await ${ipc}.ready
+
+  return ${returned}
+}
+`
+    : `\
 const path = require('path')
 const Sidecar = require('bare-sidecar')
 const stow = require('bare-stow/host')
@@ -44,7 +61,9 @@ ${client ? '\n' + indent(client.source, 4) : ''}
   }
 }
 `
-    },
+
+  return [
+    { source },
     {
       extension: '.d.ts',
       source: `\

package/lib/target/bare-worker.js

@@ -0,0 +1,82 @@
+exports.name = 'bare-worker'
+exports.linked = false
+exports.offload = true
+exports.format = 'bundle'
+exports.encoding = null
+exports.extension = '.bundle'
+exports.hosts = [
+  'darwin-arm64',
+  'darwin-x64',
+  'linux-arm64',
+  'linux-x64',
+  'win32-arm64',
+  'win32-x64'
+]
+
+exports.generate = function generate(opts) {
+  const { bundleSpecifier, ipc, rpc, module = 'cjs', client = null } = opts
+
+  const esm = module === 'esm'
+
+  const returned = client ? `{ ${ipc}, ${rpc} }` : `{ ${ipc} }`
+
+  const handle = client
+    ? `{ ${ipc}: import('bare-stow/host').IPC; ${rpc}: ${client.type} }`
+    : `{ ${ipc}: import('bare-stow/host').IPC }`
+
+  const source = esm
+    ? `\
+import Worker from 'bare-worker'
+import stow from 'bare-stow/host'
+import { fileURLToPath } from 'bare-url'
+
+const bundle = fileURLToPath(new URL(${JSON.stringify(bundleSpecifier)}, import.meta.url))
+
+export async function start(opts = {}) {
+  const worker = new Worker(bundle, opts)
+
+  const ${ipc} = stow.wrap(worker.IPC)
+${client ? '\n' + indent(client.source, 2) : ''}
+  await ${ipc}.ready
+
+  return ${returned}
+}
+`
+    : `\
+const path = require('bare-path')
+const Worker = require('bare-worker')
+const stow = require('bare-stow/host')
+
+const bundle = path.join(__dirname, ${JSON.stringify(bundleSpecifier)})
+
+module.exports = {
+  async start(opts = {}) {
+    const worker = new Worker(bundle, opts)
+
+    const ${ipc} = stow.wrap(worker.IPC)
+${client ? '\n' + indent(client.source, 4) : ''}
+    await ${ipc}.ready
+
+    return ${returned}
+  }
+}
+`
+
+  return [
+    { source },
+    {
+      extension: '.d.ts',
+      source: `\
+export function start(opts?: import('bare-worker').WorkerOptions): Promise<${handle}>
+`
+    }
+  ]
+}
+
+function indent(source, spaces) {
+  const pad = ' '.repeat(spaces)
+  return source
+    .split('\n')
+    .map((line) => (line.length === 0 ? line : pad + line))
+    .join('\n')
+}

package/lib/target.js

@@ -1,5 +1,6 @@
 const registry = {
-  'bare-sidecar': () => require('./target/bare-sidecar')
+  'bare-sidecar': () => require('./target/bare-sidecar'),
+  'bare-worker': () => require('./target/bare-worker')
 }
 
 module.exports = function target(name, resolve) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-stow",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Module bundling and harness generation for Bare",
   "exports": {
     "./package": "./package.json",
@@ -40,6 +40,10 @@
     "bin.js",
     "lib"
   ],
+  "workspaces": [
+    "test/fixtures/*",
+    "test/fixtures/*/*"
+  ],
   "scripts": {
     "format": "prettier --write . && lunte --fix",
     "lint": "prettier --check . && lunte",
@@ -72,6 +76,7 @@
   "devDependencies": {
     "bare-rpc": "^1.3.2",
     "bare-sidecar": "^0.5.0",
+    "bare-worker": "^4.3.0",
     "brittle": "^4.0.2",
     "lunte": "^1.7.0",
     "prettier": "^3.3.3",