prool 0.0.0 → 0.0.2

package/instances/anvil.ts

@@ -0,0 +1,322 @@
+import { type ResultPromise, execa } from 'execa'
+import { defineInstance } from '../instance.js'
+import { stripColors } from '../utils.js'
+import { toArgs } from '../utils.js'
+
+export type AnvilParameters = {
+  /**
+   * Number of dev accounts to generate and configure.
+   *
+   * @defaultValue 10
+   */
+  accounts?: number | undefined
+  /**
+   * Set the Access-Control-Allow-Origin response header (CORS).
+   *
+   * @defaultValue *
+   */
+  allowOrigin?: string | undefined
+  /**
+   * Enable autoImpersonate on startup
+   */
+  autoImpersonate?: boolean | undefined
+  /**
+   * The balance of every dev account in Ether.
+   *
+   * @defaultValue 10000
+   */
+  balance?: number | bigint | undefined
+  /**
+   * The base fee in a block.
+   */
+  blockBaseFeePerGas?: number | bigint | undefined
+  /**
+   * Block time in seconds for interval mining.
+   */
+  blockTime?: number | undefined
+  /**
+   * Path or alias to the Anvil binary.
+   */
+  binary?: string | undefined
+  /**
+   * The chain id.
+   */
+  chainId?: number | undefined
+  /**
+   * EIP-170: Contract code size limit in bytes. Useful to increase this because of tests.
+   *
+   * @defaultValue 0x6000 (~25kb)
+   */
+  codeSizeLimit?: number | undefined
+  /**
+   * Sets the number of assumed available compute units per second for this fork provider.
+   *
+   * @defaultValue 350
+   * @see https://github.com/alchemyplatform/alchemy-docs/blob/master/documentation/compute-units.md#rate-limits-cups
+   */
+  computeUnitsPerSecond?: number | undefined
+  /**
+   * Writes output of `anvil` as json to user-specified file.
+   */
+  configOut?: string | undefined
+  /**
+   * Sets the derivation path of the child key to be derived.
+   *
+   * @defaultValue m/44'/60'/0'/0/
+   */
+  derivationPath?: string | undefined
+  /**
+   * Disable the `call.gas_limit <= block.gas_limit` constraint.
+   */
+  disableBlockGasLimit?: boolean | undefined
+  /**
+   * Dump the state of chain on exit to the given file. If the value is a directory, the state will be
+   * written to `<VALUE>/state.json`.
+   */
+  dumpState?: string | undefined
+  /**
+   * Fetch state over a remote endpoint instead of starting from an empty state.
+   *
+   * If you want to fetch state from a specific block number, add a block number like `http://localhost:8545@1400000`
+   * or use the `forkBlockNumber` option.
+   */
+  forkUrl?: string | undefined
+  /**
+   * Fetch state from a specific block number over a remote endpoint.
+   *
+   * Requires `forkUrl` to be set.
+   */
+  forkBlockNumber?: number | bigint | undefined
+  /**
+   * Specify chain id to skip fetching it from remote endpoint. This enables offline-start mode.
+   *
+   * You still must pass both `forkUrl` and `forkBlockNumber`, and already have your required state cached
+   * on disk, anything missing locally would be fetched from the remote.
+   */
+  forkChainId?: number | undefined
+  /**
+   * Specify headers to send along with any request to the remote JSON-RPC server in forking mode.
+   *
+   * e.g. "User-Agent: test-agent"
+   *
+   * Requires `forkUrl` to be set.
+   */
+  forkHeader?: Record<string, string> | undefined
+  /**
+   * Initial retry backoff on encountering errors.
+   */
+  forkRetryBackoff?: number | undefined
+  /**
+   * The block gas limit.
+   */
+  gasLimit?: number | bigint | undefined
+  /**
+   * The gas price.
+   */
+  gasPrice?: number | bigint | undefined
+  /**
+   * The EVM hardfork to use.
+   */
+  hardfork?:
+    | 'Frontier'
+    | 'Homestead'
+    | 'Dao'
+    | 'Tangerine'
+    | 'SpuriousDragon'
+    | 'Byzantium'
+    | 'Constantinople'
+    | 'Petersburg'
+    | 'Istanbul'
+    | 'Muirglacier'
+    | 'Berlin'
+    | 'London'
+    | 'ArrowGlacier'
+    | 'GrayGlacier'
+    | 'Paris'
+    | 'Shanghai'
+    | 'Cancun'
+    | 'Latest'
+    | undefined
+  /**
+   * The host the server will listen on.
+   */
+  host?: string | undefined
+  /**
+   * Initialize the genesis block with the given `genesis.json` file.
+   */
+  init?: string | undefined
+  /**
+   * Launch an ipc server at the given path or default path = `/tmp/anvil.ipc`.
+   */
+  ipc?: string | undefined
+  /**
+   * Initialize the chain from a previously saved state snapshot.
+   */
+  loadState?: string | undefined
+  /**
+   * BIP39 mnemonic phrase used for generating accounts.
+   */
+  mnemonic?: string | undefined
+  /**
+   * Automatically generates a BIP39 mnemonic phrase, and derives accounts from it.
+   */
+  mnemonicRandom?: boolean | undefined
+  /**
+   * Disable CORS.
+   */
+  noCors?: boolean | undefined
+  /**
+   * Disable auto and interval mining, and mine on demand instead.
+   */
+  noMining?: boolean | undefined
+  /**
+   * Disables rate limiting for this node's provider.
+   *
+   * @defaultValue false
+   * @see https://github.com/alchemyplatform/alchemy-docs/blob/master/documentation/compute-units.md#rate-limits-cups
+   */
+  noRateLimit?: boolean | undefined
+  /**
+   * Explicitly disables the use of RPC caching.
+   *
+   * All storage slots are read entirely from the endpoint.
+   */
+  noStorageCaching?: boolean | undefined
+  /**
+   * How transactions are sorted in the mempool.
+   *
+   * @defaultValue fees
+   */
+  order?: string | undefined
+  /**
+   * Run an Optimism chain.
+   */
+  optimism?: boolean | undefined
+  /**
+   * Port number to listen on.
+   *
+   * @defaultValue 8545
+   */
+  port?: number | undefined
+  /**
+   * Don't keep full chain history. If a number argument is specified, at most this number of states is kept in memory.
+   */
+  pruneHistory?: number | undefined | boolean
+  /**
+   * Number of retry requests for spurious networks (timed out requests).
+   *
+   * @defaultValue 5
+   */
+  retries?: number | undefined
+  /**
+   * Don't print anything on startup and don't print logs.
+   */
+  silent?: boolean | undefined
+  /**
+   * Slots in an epoch.
+   */
+  slotsInAnEpoch?: number | undefined
+  /**
+   * Enable steps tracing used for debug calls returning geth-style traces.
+   */
+  stepsTracing?: boolean | undefined
+  /**
+   * Interval in seconds at which the status is to be dumped to disk.
+   */
+  stateInterval?: number | undefined
+  /**
+   * This is an alias for both `loadState` and `dumpState`. It initializes the chain with the state stored at the
+   * file, if it exists, and dumps the chain's state on exit
+   */
+  state?: string | undefined
+  /**
+   * Timeout in ms for requests sent to remote JSON-RPC server in forking mode.
+   *
+   * @defaultValue 45000
+   */
+  timeout?: number | undefined
+  /**
+   * The timestamp of the genesis block.
+   */
+  timestamp?: number | bigint | undefined
+  /**
+   * Number of blocks with transactions to keep in memory.
+   */
+  transactionBlockKeeper?: number | undefined
+}
+
+/**
+ * Defines an Anvil instance.
+ *
+ * @example
+ * ```ts
+ * const instance = anvil({ forkRpcUrl: 'https://cloudflare-eth.com', port: 8546 })
+ * await instance.start()
+ * // ...
+ * await instance.stop()
+ * ```
+ */
+export const anvil = defineInstance((parameters?: AnvilParameters) => {
+  const { binary = 'anvil', ...args } = parameters || {}
+
+  let process: ResultPromise<{ cleanup: true; reject: false }>
+
+  async function stop() {
+    const killed = process.kill()
+    if (!killed) throw new Error('Failed to stop anvil')
+    return new Promise((resolve) => process.on('close', resolve))
+  }
+
+  return {
+    _internal: {
+      args,
+      get process() {
+        return process
+      },
+    },
+    host: args.host ?? 'localhost',
+    name: 'anvil',
+    port: args.port ?? 8545,
+    async start({ emitter, port = args.port, status }) {
+      const { promise, resolve, reject } = Promise.withResolvers<void>()
+
+      process = execa(binary, toArgs({ ...args, port }), {
+        cleanup: true,
+        reject: false,
+      })
+
+      process.stdout.on('data', (data) => {
+        const message = stripColors(data.toString())
+        emitter.emit('message', message)
+        emitter.emit('stdout', message)
+        if (message.includes('Listening on')) {
+          emitter.emit('listening')
+          resolve()
+        }
+      })
+      process.stderr.on('data', async (data) => {
+        const message = stripColors(data.toString())
+        emitter.emit('message', message)
+        emitter.emit('stderr', message)
+        await stop()
+        reject(new Error(`Failed to start anvil: ${data.toString()}`))
+      })
+      process.on('close', () => process.removeAllListeners())
+      process.on('exit', (code, signal) => {
+        emitter.emit('exit', code, signal)
+
+        if (!code) {
+          process.removeAllListeners()
+          if (status === 'starting')
+            reject(new Error('Failed to start anvil: exited.'))
+        }
+      })
+
+      return promise
+    },
+    async stop() {
+      process.removeAllListeners()
+      await stop()
+    },
+  }
+})

package/package.json

@@ -1,12 +1,43 @@
 {
   "name": "prool",
-  "version": "0.0.0",
   "description": "",
-  "main": "index.js",
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  }
+  "version": "0.0.2",
+  "type": "module",
+  "module": "_lib/exports/index.mjs",
+  "types": "_lib/exports/index.d.ts",
+  "typings": "_lib/exports/index.d.ts",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./_lib/exports/index.d.ts",
+      "default": "./_lib/exports/index.js"
+    },
+    "./instances": {
+      "types": "./_lib/exports/instances.d.ts",
+      "default": "./_lib/exports/instances.js"
+    }
+  },
+  "dependencies": {
+    "eventemitter3": "^5.0.1",
+    "execa": "^9.1.0",
+    "get-port": "^7.1.0",
+    "http-proxy": "^1.18.1"
+  },
+  "license": "MIT",
+  "homepage": "https://wevm.dev",
+  "repository": "wevm/prool",
+  "authors": [
+    "awkweb",
+    "jxom"
+  ],
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/wevm"
+    }
+  ],
+  "keywords": []
 }

package/pool.test.ts

@@ -0,0 +1,209 @@
+import getPort from 'get-port'
+import { afterEach, describe, expect, test } from 'vitest'
+import { anvil } from './instances/anvil.js'
+import { definePool } from './pool.js'
+
+let pool: ReturnType<typeof definePool>
+
+afterEach(async () => {
+  try {
+    await pool.stopAll()
+  } catch (err) {
+    console.error(err)
+  }
+})
+
+describe.each([{ instance: anvil() }])(
+  'instance: $instance.name',
+  ({ instance }) => {
+    test('default', async () => {
+      pool = definePool({
+        instance,
+      })
+
+      expect(pool).toBeDefined()
+    })
+
+    test('start', async () => {
+      pool = definePool({
+        instance,
+      })
+
+      expect(pool.size).toEqual(0)
+
+      const instance_1 = await pool.start(1)
+      expect(instance_1.status).toBe('started')
+      expect(pool.size).toEqual(1)
+
+      const instance_2 = await pool.start(2)
+      expect(instance_2.status).toBe('started')
+      expect(pool.size).toEqual(2)
+
+      const instance_3 = await pool.start(1337)
+      expect(instance_3.status).toBe('started')
+      expect(pool.size).toEqual(3)
+    })
+
+    test('stop / destroy', async () => {
+      pool = definePool({
+        instance,
+      })
+
+      const instance_1 = await pool.start(1)
+      const instance_2 = await pool.start(2)
+      const instance_3 = await pool.start(3)
+
+      expect(instance_1.status).toBe('started')
+      expect(instance_2.status).toBe('started')
+      expect(instance_3.status).toBe('started')
+      expect(pool.size).toEqual(3)
+
+      await pool.stop(1)
+      expect(instance_1.status).toBe('stopped')
+
+      await pool.stop(2)
+      expect(instance_2.status).toBe('stopped')
+
+      await pool.stop(3)
+      expect(instance_3.status).toBe('stopped')
+
+      await pool.stop(1)
+      await pool.stop(2)
+      await pool.stop(3)
+      await pool.stop(4)
+
+      expect(pool.size).toEqual(3)
+
+      await pool.destroy(1)
+      expect(pool.size).toEqual(2)
+      await pool.destroy(2)
+      expect(pool.size).toEqual(1)
+      await pool.destroy(3)
+      expect(pool.size).toEqual(0)
+    })
+
+    test('start > stop > start', async () => {
+      pool = definePool({
+        instance,
+      })
+
+      const instance_1 = await pool.start(1)
+      expect(instance_1.status).toBe('started')
+
+      await pool.stop(1)
+      expect(instance_1.status).toBe('stopped')
+
+      await pool.start(1)
+      expect(instance_1.status).toBe('started')
+    })
+
+    test('stopAll / destroyAll', async () => {
+      pool = definePool({
+        instance,
+      })
+
+      await pool.start(1)
+      await pool.start(2)
+      await pool.start(3)
+
+      expect(pool.size).toEqual(3)
+
+      await pool.stopAll()
+      expect(pool.size).toEqual(3)
+
+      await pool.destroyAll()
+      expect(pool.size).toEqual(0)
+    })
+
+    test('get', async () => {
+      pool = definePool({
+        instance,
+      })
+
+      const instance_1 = await pool.start(1)
+      const instance_2 = await pool.start(2)
+      const instance_3 = await pool.start(3)
+
+      expect(pool.get(1)).toStrictEqual(instance_1)
+      expect(pool.get(2)).toStrictEqual(instance_2)
+      expect(pool.get(3)).toStrictEqual(instance_3)
+    })
+
+    test('behavior: start more than once', async () => {
+      pool = definePool({
+        instance,
+      })
+
+      const promise_1 = pool.start(1)
+      const promise_2 = pool.start(1)
+      expect(promise_1).toStrictEqual(promise_2)
+
+      const instance_1 = await promise_1
+      const instance_2 = await promise_2
+      expect(instance_1).toStrictEqual(instance_2)
+    })
+
+    test('behavior: clear more than once', async () => {
+      pool = definePool({
+        instance,
+      })
+
+      await pool.start(1)
+      await pool.start(2)
+      await pool.start(3)
+
+      const promise_1 = pool.stopAll()
+      const promise_2 = pool.stopAll()
+      expect(promise_1).toStrictEqual(promise_2)
+
+      await promise_1
+      await promise_2
+    })
+
+    test('behavior: stop more than once', async () => {
+      pool = definePool({
+        instance,
+      })
+
+      await pool.start(1)
+
+      const promise_1 = pool.stop(1)
+      const promise_2 = pool.stop(1)
+      expect(promise_1).toStrictEqual(promise_2)
+
+      await promise_1
+      await promise_2
+    })
+
+    test('error: start more than once on same port', async () => {
+      const port = await getPort()
+
+      pool = definePool({
+        instance,
+      })
+
+      await pool.start(1, { port })
+
+      const promise_1 = pool.start(2, { port })
+      const promise_2 = pool.start(2, { port })
+      expect(promise_1).toStrictEqual(promise_2)
+
+      await expect(() => promise_1).rejects.toThrowError()
+      await expect(() => promise_2).rejects.toThrowError()
+    })
+
+    test('error: instance limit reached', async () => {
+      pool = definePool({
+        instance,
+        limit: 2,
+      })
+
+      await pool.start(1)
+      await pool.start(2)
+
+      await expect(() => pool.start(3)).rejects.toThrowError(
+        'Instance limit of 2 reached.',
+      )
+    })
+  },
+)