bare-stow 0.1.0 → 0.1.2

package/README.md

@@ -144,6 +144,10 @@ opts = {
 
 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`.
 
+#### TypeScript
+
+TypeScript modules are supported out of the box: `.ts`, `.mts`, and `.cts` sources are stripped of their type syntax with [`bare-type-stripper`](https://github.com/holepunchto/bare-type-stripper) as they are read, and their extensions are aliased to `.js`, `.mjs`, and `.cjs` respectively for module-type detection. The stripper only erases types, so the module system follows the aliased JavaScript extension. Because stripping is purely lexical, non-erasable constructs (`enum`, `namespace` with a body, parameter properties) throw, and JSX (`.tsx`) is not supported.
+
 ### Targets and RPC providers
 
 The harness and RPC code generators are decoupled from the bundler: `target`, `client`, and `server` each accept a provider object directly, so generators can live outside `bare-stow`. Passing a name instead resolves it through `resolveTarget` / `resolveRPC`, which default to the built-in registries.
@@ -167,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.
   }
 }
@@ -177,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:
 
@@ -190,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/bin.js

@@ -2,7 +2,6 @@
 const path = require('path')
 const { pathToFileURL } = require('url')
 const { command, flag, arg, summary } = require('paparam')
-const { resolve } = require('bare-module-traverse')
 const pkg = require('./package')
 const stow = require('.')
 
@@ -72,7 +71,6 @@ const cmd = command(
       hosts,
       resolveTarget,
       resolveRPC,
-      resolve: resolve.bare,
       builtins,
       imports,
       defer

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

@@ -1,12 +1,13 @@
 const path = require('path')
 const { fileURLToPath } = require('url')
 const pack = require('bare-pack')
-const { resolve } = require('bare-module-traverse')
 const id = require('bare-bundle-id')
+const strip = require('bare-type-stripper')
 const fs = require('./lib/fs')
 const shim = require('./lib/shim')
 const harness = require('./lib/target')
 const rpc = require('./lib/rpc')
+const resolve = require('./lib/resolve')
 
 module.exports = async function* stow(entry, target, out, opts = {}) {
   if (!target) throw new Error("'target' is required")
@@ -22,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)) {
@@ -64,12 +68,17 @@ module.exports = async function* stow(entry, target, out, opts = {}) {
   const bundle = await pack(
     shimURL,
     {
-      resolve: resolve.bare,
       ...packOpts,
+      resolve,
+      aliases: {
+        '.ts': '.js',
+        '.mts': '.mjs',
+        '.cts': '.cjs'
+      },
+      base,
       hosts,
       linked: t.linked,
-      offload: t.offload,
-      base: base
+      offload: t.offload
     },
     readModule,
     fs.listPrefix,
@@ -87,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 = {
@@ -101,6 +110,7 @@ module.exports = async function* stow(entry, target, out, opts = {}) {
     bundleSpecifier,
     ipc: 'ipc',
     rpc: 'rpc',
+    module,
     client: clientSetup
   })
 
@@ -130,10 +140,16 @@ function isOffloadEnabled(offload) {
 }
 
 function wrapReadModule(readModule, shimURL, shimSource) {
-  return function (url) {
+  return async function (url) {
     if (url.href === shimURL.href) return shimSource
 
-    return readModule(url)
+    const source = await readModule(url)
+
+    if (source === null) return null
+
+    if (/\.(c|m)?ts$/.test(url.pathname)) return strip(source)
+
+    return source
   }
 }
 
@@ -159,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/resolve.js

@@ -0,0 +1,40 @@
+const lex = require('bare-module-lexer')
+const { resolve } = require('bare-module-traverse')
+
+module.exports = function bare(entry, parentURL, opts = {}) {
+  const { linked = false, hosts } = opts
+
+  let extensions
+  let conditions = hosts.map((host) => ['bare', 'node', ...host.split('-')])
+
+  if (entry.type & lex.constants.ADDON) {
+    extensions = linked ? [] : ['.bare', '.node']
+    conditions = conditions.map((conditions) => ['addon', ...conditions])
+
+    return resolve.addon(entry.specifier || '.', parentURL, {
+      ...opts,
+      extensions,
+      conditions,
+      hosts,
+      linked
+    })
+  }
+
+  if (entry.type & lex.constants.ASSET) {
+    conditions = conditions.map((conditions) => ['asset', ...conditions])
+  } else {
+    extensions = ['.js', '.cjs', '.mjs', '.ts', '.cts', '.mts', '.json', '.bare', '.node']
+
+    if (entry.type & lex.constants.REQUIRE) {
+      conditions = conditions.map((conditions) => ['require', ...conditions])
+    } else if (entry.type & lex.constants.IMPORT) {
+      conditions = conditions.map((conditions) => ['import', ...conditions])
+    }
+  }
+
+  return resolve.module(entry.specifier, parentURL, {
+    ...opts,
+    extensions,
+    conditions
+  })
+}

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.0",
+  "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",
@@ -61,10 +65,12 @@
     "bare-bundle": "^1.8.3",
     "bare-bundle-id": "^1.0.0",
     "bare-fs": "^4.2.1",
+    "bare-module-lexer": "^1.5.2",
     "bare-module-traverse": "^2.1.1",
     "bare-pack": "^2.1.0",
     "bare-path": "^3.0.0",
     "bare-stream": "^2.13.1",
+    "bare-type-stripper": "^0.1.2",
     "paparam": "^1.5.0"
   },
   "devDependencies": {