bare-stow 0.1.1 → 0.1.2

package/README.md

@@ -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
 

package/index.d.ts

@@ -11,6 +11,7 @@ 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-stow",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "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",