esm.dev 1.5.0

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "esm.dev",
+  "version": "1.5.0",
+  "description": "TypeScript library template",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/cli.ts"
+  },
+  "bin": {
+    "esm.dev": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "esm.dev": "bun ./src/cli.ts",
+    "prepare": "husky",
+    "start": "docker compose up --detach --remove-orphans",
+    "stop": "docker compose down"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/johngeorgewright/esm.dev.git"
+  },
+  "keywords": [],
+  "author": "John Wright <johngeorge.wright@gmail.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/johngeorgewright/esm.dev/issues"
+  },
+  "homepage": "https://github.com/johngeorgewright/esm.dev#readme",
+  "devDependencies": {
+    "@commitlint/cli": "19.8.1",
+    "@commitlint/config-conventional": "19.8.1",
+    "@commitlint/types": "19.8.1",
+    "@types/bun": "latest",
+    "@types/http-proxy": "^1.17.16",
+    "@types/lodash.debounce": "^4.0.9",
+    "@types/mustache": "^4.2.6",
+    "@types/ramda": "^0.30.2",
+    "husky": "9.1.7",
+    "lint-staged": "16.0.0",
+    "prettier": "3.5.3",
+    "rimraf": "6.0.1",
+    "semantic-release": "^24.2.3",
+    "typescript": "5.8.3"
+  },
+  "lint-staged": {
+    "*.{md,json,js,jsx,ts,tsx,yml,yaml}": [
+      "bunx prettier --ignore-path .gitignore --write"
+    ]
+  },
+  "dependencies": {
+    "clipanion": "^4.0.0-rc.4",
+    "clipanion-generator-command": "^1.2.0",
+    "escape-string-regexp": "^5.0.0",
+    "glob": "^11.0.2",
+    "http-proxy": "^1.18.1",
+    "lodash.debounce": "^4.0.8",
+    "mustache": "^4.2.0",
+    "npm": "^11.3.0",
+    "ramda": "^0.30.1",
+    "throat": "^6.0.2",
+    "tslib": "^2.8.1",
+    "zod": "^3.24.4"
+  }
+}

package/release.config.cjs

@@ -0,0 +1,20 @@
+// @ts-check
+
+/**
+ * @type {import('semantic-release').Options}
+ */
+module.exports = {
+  branches: ['master'],
+  plugins: [
+    '@semantic-release/commit-analyzer',
+    '@semantic-release/release-notes-generator',
+    '@semantic-release/npm',
+    [
+      '@semantic-release/git',
+      {
+        message: 'chore(release): ${nextRelease.version} [skip ci]',
+      },
+    ],
+    '@semantic-release/github',
+  ],
+}

package/src/cli.ts

@@ -0,0 +1,18 @@
+import { runExit } from 'clipanion'
+import { WatchCommand } from './commands/WatchCommand.js'
+import { RepublishCommand } from './commands/RepublishCommand.js'
+import { LoginCommand } from './commands/LoginCommand.js'
+import { TokenCommand } from './commands/TokenCommand.js'
+import { WaitForRegistryCommand } from './commands/WaitForRegistryCommand.js'
+import { StartCommand } from './commands/StartCommand.js'
+import { InitCommand } from './commands/InitCommand.js'
+
+runExit([
+  InitCommand,
+  LoginCommand,
+  TokenCommand,
+  RepublishCommand,
+  StartCommand,
+  WaitForRegistryCommand,
+  WatchCommand,
+])

package/src/commands/ESMDevCommand.ts

@@ -0,0 +1,8 @@
+import { Command } from 'clipanion'
+import { RegistrySpecific } from './mixins/RegistrySpecific.js'
+import { ESMStorageSpecific } from './mixins/ESMStorageSpecific.js'
+import { PackagePathSpecific } from './mixins/PackagePathSpecific.js'
+
+export abstract class ESMDevCommand extends ESMStorageSpecific(
+  RegistrySpecific(PackagePathSpecific(Command)),
+) {}

package/src/commands/InitCommand.ts

@@ -0,0 +1,57 @@
+import * as path from 'node:path'
+import { ESMDevCommand } from './ESMDevCommand'
+import { PackagePathSpecific } from './mixins/PackagePathSpecific'
+import { MustacheGeneratorCommand } from './MustacheGeneratorCommand'
+import { Option } from 'clipanion'
+
+export class InitCommand extends PackagePathSpecific(MustacheGeneratorCommand) {
+  static override paths = [['init']]
+
+  static override usage = ESMDevCommand.Usage({
+    description: 'Initialises your repo ready to work with ESM.sh locally',
+  })
+
+  readonly esmOrigin = Option.String(
+    '-e,--esm-origin',
+    'http://localhost:8080',
+    {
+      description: 'The base URL of the ESM Server',
+    },
+  )
+
+  readonly esmStoragePath = Option.String(
+    '-s,--esm-storage-path',
+    './docker-storage/esm/esmd',
+    {
+      description: "Path to ESM.sh's storage",
+    },
+  )
+
+  readonly port = Option.String('-p,--port', '3000', {
+    description: "The server's port",
+  })
+
+  readonly outputDirectory = Option.String('-o,--output-dir', '.', {
+    description: 'The output directory',
+  })
+
+  readonly registry = Option.String('-r,--registry', 'http://localhost:4873', {
+    description: 'The URL of your local registry',
+  })
+
+  esmURL!: URL
+  npmRegistryURL!: URL
+  packages!: { path: string; basename: string }[]
+
+  override async execute() {
+    this.templateDir = path.join(import.meta.dirname, 'templates', 'init')
+    this.destinationDir = this.outputDirectory
+    this.esmURL = new URL(this.esmOrigin)
+    this.npmRegistryURL = new URL(this.registry)
+    this.packages = this.packagePaths.map((packagePath) => ({
+      path: packagePath,
+      basename: path.basename(packagePath),
+    }))
+    await super.execute()
+  }
+}

package/src/commands/LoginCommand.ts

@@ -0,0 +1,15 @@
+import { Command } from 'clipanion'
+import { RegistrySpecific } from './mixins/RegistrySpecific.js'
+
+export class LoginCommand extends RegistrySpecific(Command) {
+  static override paths = [['login']]
+
+  static override usage = Command.Usage({
+    description: 'Login in to the NPM registry',
+  })
+
+  override async execute() {
+    const { login } = await import('../lib/login.js')
+    return login(this.registry)
+  }
+}

package/src/commands/MustacheGeneratorCommand.ts

@@ -0,0 +1,10 @@
+import { GeneratorCommand } from 'clipanion-generator-command'
+import { MustacheGenerator } from '../lib/MustacheGenerator'
+
+export abstract class MustacheGeneratorCommand extends GeneratorCommand {
+  override get generator() {
+    return new MustacheGenerator(this.templateDir, this.destinationDir, [
+      '.mustache',
+    ])
+  }
+}

package/src/commands/RepublishCommand.ts

@@ -0,0 +1,15 @@
+import { ESMDevCommand } from './ESMDevCommand.js'
+
+export class RepublishCommand extends ESMDevCommand {
+  static override paths = [['republish']]
+
+  static override usage = ESMDevCommand.Usage({
+    description:
+      'Removes the references, of given packages, from the ESM server and registry and republishes.',
+  })
+
+  override async execute() {
+    const { republish } = await import('../lib/republish.js')
+    await this.eachPackagePath((packagePath) => republish(packagePath, this))
+  }
+}

package/src/commands/StartCommand.ts

@@ -0,0 +1,21 @@
+import { ESMDevCommand } from './ESMDevCommand.js'
+import { Servable } from './mixins/Servable.js'
+import { Watchable } from './mixins/Watchable.js'
+import { ESMServed } from './mixins/ESMServed.js'
+
+export class StartCommand extends Servable(
+  Watchable(ESMServed(ESMDevCommand)),
+) {
+  static override paths = [['start']]
+
+  static override usage = ESMDevCommand.Usage({
+    description: 'Runs a server and concurrently watches a file system',
+  })
+
+  override async execute() {
+    const { watch } = await import('../lib/watch.js')
+    const { serve } = await import('../lib/server.js')
+    serve(this.port, this.esmOrigin)
+    await this.eachPackagePath((packagePath) => watch(packagePath, this))
+  }
+}

package/src/commands/TokenCommand.ts

@@ -0,0 +1,26 @@
+import { Command } from 'clipanion'
+import { RegistrySpecific } from './mixins/RegistrySpecific.js'
+
+export class TokenCommand extends RegistrySpecific(Command) {
+  static override paths = [['token']]
+
+  static override usage = Command.Usage({
+    description: 'Get the NPM token',
+  })
+
+  override async execute() {
+    const { default: escapeStringRegexp } = await import('escape-string-regexp')
+    const npmrc = await Bun.file(`~/.npmrc`).text()
+    const url = new URL(this.registry)
+    const regex = new RegExp(
+      `^//${escapeStringRegexp(url.hostname)}/:_authToken=(.*)$`,
+      'm',
+    )
+    const match = regex.exec(npmrc)
+    if (!match) {
+      this.context.stderr.write(`Token has not been created yet\n`)
+      return 1
+    }
+    this.context.stdout.write(match[1] + '\n')
+  }
+}

package/src/commands/WaitForRegistryCommand.ts

@@ -0,0 +1,17 @@
+import { Command } from 'clipanion'
+import { RegistrySpecific } from './mixins/RegistrySpecific.js'
+import { Retryable } from './mixins/Retryable.js'
+
+export class WaitForRegistryCommand extends Retryable(
+  RegistrySpecific(Command),
+) {
+  static override paths = [['wait-for-registry'], ['wfr']]
+
+  static override usage = Command.Usage({
+    description: 'wait for the registry to be online',
+  })
+
+  override async execute() {
+    return this.retry(this.registry)
+  }
+}

package/src/commands/WatchCommand.ts

@@ -0,0 +1,15 @@
+import { ESMDevCommand } from './ESMDevCommand.js'
+import { Watchable } from './mixins/Watchable.js'
+
+export class WatchCommand extends Watchable(ESMDevCommand) {
+  static override paths = [['watch']]
+
+  static override usage = ESMDevCommand.Usage({
+    description: 'Watches directories and republishes on changes',
+  })
+
+  override async execute() {
+    const { watch } = await import('../lib/watch.js')
+    await this.eachPackagePath((packagePath) => watch(packagePath, this))
+  }
+}

package/src/commands/mixins/CommandClass.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'clipanion'
+
+export type CommandClass = abstract new (...args: any[]) => Command

package/src/commands/mixins/ESMServed.ts

@@ -0,0 +1,12 @@
+import { EnvOption } from '../../options/EnvOption'
+import type { CommandClass } from './CommandClass'
+
+export function ESMServed<T extends CommandClass>(Base: T) {
+  abstract class ESMServed extends Base {
+    readonly esmOrigin = EnvOption('ESM_ORIGIN', '-e,--esm-origin', {
+      description: 'The base URL of the ESM Server',
+    })
+  }
+
+  return ESMServed
+}

package/src/commands/mixins/ESMStorageSpecific.ts

@@ -0,0 +1,16 @@
+import type { CommandClass } from './CommandClass'
+import { EnvOption } from '../../options/EnvOption.js'
+
+export function ESMStorageSpecific<T extends CommandClass>(Base: T) {
+  abstract class ESMStorageSpecific extends Base {
+    readonly esmStoragePath = EnvOption(
+      'ESM_STORAGE_PATH',
+      '-s,--esm-storage-path',
+      {
+        description: "Path to ESM.sh's storage",
+      },
+    )
+  }
+
+  return ESMStorageSpecific
+}

package/src/commands/mixins/PackagePathSpecific.ts

@@ -0,0 +1,22 @@
+import { Option } from 'clipanion'
+import type { CommandClass } from './CommandClass.js'
+
+export function PackagePathSpecific<T extends CommandClass>(Base: T) {
+  abstract class PackagePathSpecific extends Base {
+    readonly packagePaths = Option.Rest({
+      name: 'packages',
+    })
+
+    protected async eachPackagePath(cb: (packagePath: string) => Promise<any>) {
+      const { glob } = await import('glob')
+      const packagePaths = (
+        await Promise.all(
+          this.packagePaths.map((packagePath) => glob(packagePath)),
+        )
+      ).flat()
+      await Promise.all(packagePaths.map(cb))
+    }
+  }
+
+  return PackagePathSpecific
+}

package/src/commands/mixins/RegistrySpecific.ts

@@ -0,0 +1,12 @@
+import type { CommandClass } from './CommandClass.js'
+import { EnvOption } from '../../options/EnvOption.js'
+
+export function RegistrySpecific<TBase extends CommandClass>(Base: TBase) {
+  abstract class RegistrySpecific extends Base {
+    readonly registry = EnvOption('NPM_REGISTRY', '-r,--registry', {
+      description: 'The URL of your local registry',
+    })
+  }
+
+  return RegistrySpecific
+}

package/src/commands/mixins/Retryable.ts

@@ -0,0 +1,35 @@
+import { Option } from 'clipanion'
+import { isNumber } from 'typanion'
+import type { CommandClass } from './CommandClass.js'
+
+export function Retryable<T extends CommandClass>(Base: T) {
+  abstract class Retryable extends Base {
+    readonly timeout = Option.String('-t,--timeout', '10000', {
+      description: 'The amount of total ms to keep trying for',
+      validator: isNumber(),
+    })
+
+    readonly interval = Option.String('-i,--interval', '300', {
+      description: 'The amount of ms inbetween each attempt',
+      validator: isNumber(),
+    })
+
+    protected async retry(endpoint: string) {
+      const { until } = await import('../../lib/until.js')
+      if (
+        !(await until({
+          ...this,
+          try: async (signal) => {
+            const response = await fetch(endpoint, { signal })
+            return response.ok
+          },
+        }))
+      ) {
+        this.context.stderr.write(`${endpoint} is not available\n`)
+        return 1
+      }
+    }
+  }
+
+  return Retryable
+}

package/src/commands/mixins/Servable.ts

@@ -0,0 +1,14 @@
+import { isNumber } from 'typanion'
+import { EnvOption } from '../../options/EnvOption.js'
+import type { CommandClass } from './CommandClass.js'
+
+export function Servable<T extends CommandClass>(Base: T) {
+  abstract class Servable extends Base {
+    readonly port = EnvOption('PORT', '-p,--port', {
+      description: 'The port to run the server on',
+      validator: isNumber(),
+    })
+  }
+
+  return Servable
+}

package/src/commands/mixins/Watchable.ts

@@ -0,0 +1,13 @@
+import { Option } from 'clipanion'
+import type { CommandClass } from './CommandClass'
+
+export function Watchable<T extends CommandClass>(Base: T) {
+  abstract class Watchable extends Base {
+    readonly legacyMethod = Option.Boolean('-l,--legacy-method', false, {
+      description:
+        'Use a less performant, legacy, watch method. Sometimes needed in docker or vagrant environments.',
+    })
+  }
+
+  return Watchable
+}

package/src/commands/templates/init/docker-compose.yml.mustache

@@ -0,0 +1,38 @@
+services:
+  esm.dev:
+    image: ghcr.io/johngeorgewright/esm.dev:latest
+    depends_on:
+      - esm
+      - npm
+    environment:
+      - NPM_REGISTRY=http://npm:{{npmRegistryURL.port}}
+      - ESM_ORIGIN=http://esm:{{esmURL.port}}
+      - ESM_STORAGE_PATH=/esmd
+      - PORT={{port}}
+    command:
+      - start
+      - /watch/*
+    ports:
+      - '{{port}}:{{port}}'
+    volumes:
+      - {{esmStoragePath}}:/esmd
+      # The following are paths to all the packages you wish to auto publish
+      {{#packages}}
+      - {{path}}:/watch/{{basename}}:ro
+      {{/packages}}
+
+  esm:
+    image: ghcr.io/esm-dev/esm:latest
+    environment:
+      - NPM_REGISTRY=http://npm:{{npmRegistryURL.port}}
+      - NPM_TOKEN=fake
+      - LOG_LEVEL=debug
+    ports:
+      - '{{esmURL.port}}:8080'
+    volumes:
+      - {{esmStoragePath}}:/esmd
+
+  npm:
+    image: verdaccio/verdaccio:latest
+    ports:
+      - '{{npmRegistryURL.port}}:4873'

package/src/lib/MustacheGenerator.ts

@@ -0,0 +1,10 @@
+import Mustache from 'mustache'
+import { Generator } from 'clipanion-generator-command/Generator'
+
+export class MustacheGenerator extends Generator {
+  override renderTemplate(templateContext: any, template: string) {
+    return Mustache.render(template, templateContext, undefined, {
+      escape: (x) => x,
+    })
+  }
+}

package/src/lib/getPackageMeta.ts

@@ -0,0 +1,15 @@
+import { readFile, stat as getStat } from 'node:fs/promises'
+import * as path from 'node:path'
+
+export async function getPackageMeta(
+  packagePath: string,
+): Promise<{ name: string; packageRoot: string; private?: boolean }> {
+  const stat = await getStat(packagePath)
+  const packageRoot = stat.isDirectory()
+    ? packagePath
+    : path.dirname(packagePath)
+  const pckg = JSON.parse(
+    await readFile(path.join(packageRoot, 'package.json'), 'utf-8'),
+  )
+  return { name: pckg.name, packageRoot, private: pckg.private }
+}

package/src/lib/login.ts

@@ -0,0 +1,35 @@
+import { spawn } from 'node:child_process'
+
+export function login(registry: string) {
+  return new Promise<number>((resolve) => {
+    const child = spawn('bunx', [
+      'npm',
+      'login',
+      '--registry',
+      registry,
+      '--quiet',
+    ])
+
+    child.stderr.on('data', (d) => console.error(d.toString()))
+
+    child.stdout.on('data', (d) => {
+      const data = d.toString()
+      switch (true) {
+        case /username/i.test(data):
+          child.stdin.write('esm.dev\n')
+          break
+        case /password/i.test(data):
+          child.stdin.write('esm.dev\n')
+          break
+        case /email/i.test(data):
+          child.stdin.write('esm.dev@esm.dev.com')
+          break
+        case /logged in as/i.test(data):
+          child.stdin.end()
+          break
+      }
+    })
+
+    child.on('exit', resolve)
+  })
+}

package/src/lib/publish.ts

@@ -0,0 +1,14 @@
+import { $ } from 'bun'
+import * as path from 'node:path'
+
+export async function publish({
+  packageRoot,
+  registry,
+}: {
+  packageRoot: string
+  registry: string
+}) {
+  await $`bunx npm publish --registry ${registry}`.cwd(
+    path.resolve(packageRoot),
+  )
+}

package/src/lib/queue.ts

@@ -0,0 +1,39 @@
+import debounce from 'lodash.debounce'
+import throat from 'throat'
+
+export const queue = throat(1)
+
+/**
+ * Just like debounce, but the first call will add a promise to the queue
+ * and that promise won't resolve until the debounced function is finally called.
+ */
+export function queuedDebounce<Args extends unknown[], R>(
+  fn: (...args: Args) => R,
+  delay: number,
+): (...args: Args) => Promise<R> {
+  let promiseWithResolvers: PromiseWithResolvers<R> | undefined
+
+  const debounced = debounce(async (...args: Args) => {
+    try {
+      const result = await fn(...args)
+      promiseWithResolvers?.resolve(result)
+    } catch (error: any) {
+      promiseWithResolvers?.reject(error)
+    } finally {
+      promiseWithResolvers = undefined
+    }
+  }, delay)
+
+  return (...args: Args) => {
+    start()
+    debounced(...args)
+    return promiseWithResolvers!.promise
+  }
+
+  function start() {
+    if (!promiseWithResolvers) {
+      promiseWithResolvers = Promise.withResolvers<R>()
+      queue(async () => promiseWithResolvers?.promise)
+    }
+  }
+}

package/src/lib/republish.ts

@@ -0,0 +1,16 @@
+import { getPackageMeta } from './getPackageMeta.js'
+import { publish } from './publish.js'
+import { unpublish } from './unpublish.js'
+
+export async function republish(
+  packagePath: string,
+  opts: {
+    registry: string
+    esmStoragePath: string
+  },
+) {
+  console.info(`Republishing ${packagePath}`)
+  const { name, packageRoot } = await getPackageMeta(packagePath)
+  await unpublish({ ...opts, name })
+  await publish({ ...opts, packageRoot })
+}

package/src/lib/server.ts

@@ -0,0 +1,29 @@
+import { queue } from './queue.js'
+import { createServer } from 'node:http'
+import httpProxy from 'http-proxy'
+
+export function serve(port: number, esmOrigin: string) {
+  const proxy = httpProxy.createProxyServer()
+
+  const server = createServer((req, res) => {
+    queue(
+      () =>
+        new Promise<void>((resolve, reject) => {
+          console.info('Proxying', req.url)
+          res.on('error', reject)
+          res.on('close', resolve)
+          res.on('finish', resolve)
+          proxy.web(req, res, { target: esmOrigin })
+        }),
+    ).catch((error) => {
+      res.statusCode = 500
+      res.setHeader('Content-Type', 'application/json; charset=utf-8')
+      res.write(JSON.stringify(error))
+      res.end()
+    })
+  }).listen(port, () => {
+    console.info('ESM proxy server listining on', server.address())
+  })
+
+  return server
+}