prool 0.0.0 → 0.0.1

package/instance.test.ts

@@ -0,0 +1,311 @@
+import { expect, test } from 'vitest'
+import { defineInstance } from './instance.js'
+
+test('default', async () => {
+  let started = false
+  const foo = defineInstance(() => {
+    return {
+      name: 'foo',
+      host: 'localhost',
+      port: 3000,
+      async start() {
+        started = true
+      },
+      async stop() {
+        started = false
+      },
+    }
+  })
+
+  const instance = foo()
+
+  expect(started).toEqual(false)
+  await instance.start()
+  expect(started).toEqual(true)
+  await instance.stop()
+  expect(started).toEqual(false)
+})
+
+test('behavior: parameters', async () => {
+  let started = [false, {}]
+  const foo = defineInstance((parameters: { bar: string }) => {
+    return {
+      name: 'foo',
+      host: 'localhost',
+      port: 3000,
+      async start() {
+        started = [true, parameters]
+      },
+      async stop() {
+        started = [false, {}]
+      },
+    }
+  })
+
+  const instance = foo({ bar: 'baz' })
+
+  expect(started).toEqual([false, {}])
+  await instance.start()
+  expect(started).toEqual([true, { bar: 'baz' }])
+  await instance.stop()
+  expect(started).toEqual([false, {}])
+})
+
+test('behavior: start', async () => {
+  let count = 0
+  const foo = defineInstance(() => {
+    return {
+      name: 'foo',
+      host: 'localhost',
+      port: 3000,
+      async start() {
+        count++
+      },
+      async stop() {},
+    }
+  })
+
+  const instance = foo()
+
+  expect(instance.status).toEqual('idle')
+
+  const promise_1 = instance.start()
+  expect(instance.status).toEqual('starting')
+
+  const promise_2 = instance.start()
+  expect(instance.status).toEqual('starting')
+
+  expect(promise_1).toStrictEqual(promise_2)
+  expect(count).toEqual(1)
+
+  await promise_1
+
+  expect(instance.status).toEqual('started')
+
+  instance.stop()
+  expect(instance.status).toEqual('stopping')
+
+  expect(() => instance.start()).rejects.toThrowErrorMatchingInlineSnapshot(
+    `[Error: Instance "foo" is not in an idle or stopped state. Status: stopping]`,
+  )
+})
+
+test('behavior: start (error)', async () => {
+  const foo = defineInstance(() => {
+    return {
+      name: 'foo',
+      host: 'localhost',
+      port: 3000,
+      async start() {
+        throw new Error('oh no')
+      },
+      async stop() {},
+    }
+  })
+
+  const instance = foo()
+
+  expect(instance.status).toEqual('idle')
+  await expect(instance.start()).rejects.toThrowErrorMatchingInlineSnapshot(
+    '[Error: oh no]',
+  )
+  expect(instance.status).toEqual('idle')
+})
+
+test('behavior: stop', async () => {
+  let count = 0
+  const foo = defineInstance(() => {
+    return {
+      name: 'foo',
+      host: 'localhost',
+      port: 3000,
+      async start() {},
+      async stop() {
+        count++
+      },
+    }
+  })
+
+  const instance = foo()
+  await instance.start()
+
+  const promise_1 = instance.stop()
+  expect(instance.status).toEqual('stopping')
+  const promise_2 = instance.stop()
+  expect(instance.status).toEqual('stopping')
+
+  expect(promise_1).toStrictEqual(promise_2)
+  expect(count).toEqual(1)
+
+  await promise_1
+
+  expect(instance.status).toEqual('stopped')
+
+  instance.start()
+  expect(instance.status).toEqual('starting')
+
+  expect(() => instance.stop()).rejects.toThrowErrorMatchingInlineSnapshot(
+    `[Error: Instance "foo" is starting.]`,
+  )
+})
+
+test('behavior: stop (error)', async () => {
+  const foo = defineInstance(() => {
+    return {
+      name: 'foo',
+      host: 'localhost',
+      port: 3000,
+      async start() {},
+      async stop() {
+        throw new Error('oh no')
+      },
+    }
+  })
+
+  const instance = foo()
+
+  await instance.start()
+  expect(instance.status).toEqual('started')
+
+  await expect(instance.stop()).rejects.toThrowErrorMatchingInlineSnapshot(
+    '[Error: oh no]',
+  )
+  expect(instance.status).toEqual('started')
+})
+
+test('behavior: events', async () => {
+  const foo = defineInstance(() => {
+    let count = 0
+    return {
+      name: 'foo',
+      host: 'localhost',
+      port: 3000,
+      async start({ emitter }) {
+        emitter.emit('message', count.toString())
+        emitter.emit('listening')
+        if (count > 0) emitter.emit('stderr', 'stderr')
+        else emitter.emit('stdout', 'stdout')
+        count++
+      },
+      async stop({ emitter }) {
+        emitter.emit('exit', 0, 'SIGTERM')
+        emitter.emit('message', 'goodbye')
+      },
+    }
+  })
+
+  const listening = Promise.withResolvers<void>()
+  const message_1 = Promise.withResolvers<string>()
+  const stdout = Promise.withResolvers<string>()
+  const stderr = Promise.withResolvers<string>()
+  const exit = Promise.withResolvers<unknown>()
+
+  const instance = foo()
+  instance.once('listening', listening.resolve)
+  instance.once('message', message_1.resolve)
+  instance.once('stdout', stdout.resolve)
+  instance.once('stderr', stderr.resolve)
+  instance.once('exit', exit.resolve)
+
+  await instance.start()
+
+  await listening.promise
+  expect(await message_1.promise).toEqual('0')
+  expect(await stdout.promise).toEqual('stdout')
+
+  const message_2 = Promise.withResolvers()
+  instance.once('message', message_2.resolve)
+
+  await instance.stop()
+
+  expect(await message_2.promise).toEqual('goodbye')
+  await exit.promise
+
+  const message_3 = Promise.withResolvers()
+  instance.once('message', message_3.resolve)
+
+  await instance.start()
+
+  expect(await message_3.promise).toEqual('1')
+  expect(await stderr.promise).toEqual('stderr')
+})
+
+test('behavior: messages', async () => {
+  const foo = defineInstance(() => {
+    return {
+      name: 'foo',
+      host: 'localhost',
+      port: 3000,
+      async start({ emitter }) {
+        for (let i = 0; i < 50; i++) emitter.emit('message', i.toString())
+      },
+      async stop() {},
+    }
+  })
+
+  const instance = foo()
+  expect(instance.messages.get()).toEqual([])
+
+  await instance.start()
+  expect(instance.messages.get()).toMatchInlineSnapshot(`
+    [
+      "30",
+      "31",
+      "32",
+      "33",
+      "34",
+      "35",
+      "36",
+      "37",
+      "38",
+      "39",
+      "40",
+      "41",
+      "42",
+      "43",
+      "44",
+      "45",
+      "46",
+      "47",
+      "48",
+      "49",
+    ]
+  `)
+})
+
+test('options: timeout', async () => {
+  const foo = defineInstance(() => {
+    return {
+      name: 'foo',
+      host: 'localhost',
+      port: 3000,
+      async start() {
+        await new Promise((resolve) => setTimeout(resolve, 200))
+      },
+      async stop() {},
+    }
+  })
+
+  const instance_1 = foo({ timeout: 100 })
+  await expect(() => instance_1.start()).rejects.toThrow(
+    'Instance "foo" failed to start in time',
+  )
+
+  const bar = defineInstance(() => {
+    return {
+      name: 'bar',
+      host: 'localhost',
+      port: 3000,
+      async start() {},
+      async stop() {
+        await new Promise((resolve) => setTimeout(resolve, 200))
+      },
+    }
+  })
+
+  const instance_2 = bar({ timeout: 100 })
+  await instance_2.start()
+  await expect(() => instance_2.stop()).rejects.toThrow(
+    'Instance "bar" failed to stop in time',
+  )
+})

package/instance.ts

@@ -0,0 +1,277 @@
+import { EventEmitter } from 'eventemitter3'
+
+type EventTypes = {
+  exit: [code: number | null, signal: NodeJS.Signals | null]
+  listening: []
+  message: [message: string]
+  stderr: [message: string]
+  stdout: [message: string]
+}
+
+type InstanceStartOptions_internal = {
+  emitter: EventEmitter<EventTypes>
+  status: Instance['status']
+}
+type InstanceStopOptions_internal = {
+  emitter: EventEmitter<EventTypes>
+  status: Instance['status']
+}
+
+export type InstanceStartOptions = {
+  /**
+   * Port to start the instance on.
+   */
+  port?: number | undefined
+}
+
+export type DefineInstanceFn<
+  parameters,
+  _internal extends object | undefined = object | undefined,
+> = (parameters: parameters) => Pick<Instance, 'host' | 'name' | 'port'> & {
+  _internal?: _internal | undefined
+  start(
+    options: InstanceStartOptions & InstanceStartOptions_internal,
+  ): Promise<void>
+  stop(options: InstanceStopOptions_internal): Promise<void>
+}
+
+export type Instance<
+  _internal extends object | undefined = object | undefined,
+> = Pick<
+  EventEmitter<EventTypes>,
+  | 'addListener'
+  | 'off'
+  | 'on'
+  | 'once'
+  | 'removeAllListeners'
+  | 'removeListener'
+> & {
+  _internal: _internal
+  /**
+   * Creates an instance.
+   */
+  create(
+    parameters?: { port?: number | undefined } | undefined,
+  ): Omit<Instance<_internal>, 'create'>
+  /**
+   * Host the instance is running on.
+   */
+  host: string
+  /**
+   * Name of the instance.
+   *
+   * @example "anvil"
+   */
+  name: string
+  /**
+   * Port the instance is running on.
+   */
+  port: number
+  /**
+   * Set of messages emitted from the `"message"` event stored in-memory,
+   * with length {@link InstanceOptions`messageBuffer`}.
+   * Useful for debugging.
+   *
+   * @example ["Listening on http://127.0.0.1", "Started successfully."]
+   */
+  messages: { clear(): void; get(): string[] }
+  /**
+   * Status of the instance.
+   *
+   * @default "idle"
+   */
+  status: 'idle' | 'stopped' | 'starting' | 'started' | 'stopping'
+  /**
+   * Starts the instance.
+   *
+   * @param options - Options for starting the instance.
+   * @returns A function to stop the instance.
+   */
+  start(): Promise<() => void>
+  /**
+   * Stops the instance.
+   */
+  stop(): Promise<void>
+}
+
+export type InstanceOptions = {
+  /** Number of messages to store in-memory. @default 20 */
+  messageBuffer?: number
+  /** Timeout (in milliseconds) for starting and stopping the instance. @default 10_000 */
+  timeout?: number
+}
+
+export type DefineInstanceReturnType<
+  _internal extends object | undefined = object | undefined,
+  parameters = undefined,
+> = (
+  ...parameters: parameters extends undefined
+    ? [options?: InstanceOptions]
+    : [parameters: parameters, options?: InstanceOptions]
+) => Instance<_internal>
+
+/**
+ * Creates an instance definition.
+ *
+ * @param fn - Function to define the instance.
+ *
+ * @example
+ * ```ts
+ * const foo = defineInstance((parameters: FooParameters) => {
+ *  return {
+ *    name: 'foo',
+ *    host: 'localhost',
+ *    port: 3000,
+ *    async start() {
+ *      // ...
+ *    },
+ *    async stop() {
+ *      // ...
+ *    },
+ *  }
+ * })
+ * ```
+ */
+export function defineInstance<
+  _internal extends object | undefined,
+  parameters = undefined,
+>(
+  fn: DefineInstanceFn<parameters, _internal>,
+): DefineInstanceReturnType<_internal, parameters> {
+  return (...[parametersOrOptions, options_]) => {
+    function create(createParameters: Parameters<Instance['create']>[0] = {}) {
+      const parameters = parametersOrOptions as parameters
+      const options = options_ || parametersOrOptions || {}
+
+      const { _internal, host, name, port, start, stop } = {
+        ...fn(parameters),
+        ...createParameters,
+      }
+      const { messageBuffer = 20, timeout = 10_000 } = options
+
+      let startResolver = Promise.withResolvers<() => void>()
+      let stopResolver = Promise.withResolvers<void>()
+
+      const emitter = new EventEmitter<EventTypes>()
+
+      let messages: string[] = []
+      let status: Instance['status'] = 'idle'
+
+      function onExit() {
+        status = 'stopped'
+      }
+      function onListening() {
+        status = 'started'
+      }
+      function onMessage(message: string) {
+        messages.push(message)
+        if (messages.length > messageBuffer) messages.shift()
+      }
+
+      return {
+        _internal: _internal as _internal,
+        messages: {
+          clear() {
+            messages = []
+          },
+          get() {
+            return messages
+          },
+        },
+        host,
+        name,
+        port,
+        get status() {
+          return status
+        },
+        async start() {
+          if (status === 'starting') return startResolver.promise
+          if (status !== 'idle' && status !== 'stopped')
+            throw new Error(
+              `Instance "${name}" is not in an idle or stopped state. Status: ${status}`,
+            )
+
+          if (typeof timeout === 'number') {
+            const timer = setTimeout(() => {
+              clearTimeout(timer)
+              startResolver.reject(
+                new Error(`Instance "${name}" failed to start in time.`),
+              )
+            }, timeout)
+          }
+
+          emitter.on('message', onMessage)
+          emitter.on('listening', onListening)
+          emitter.on('exit', onExit)
+
+          status = 'starting'
+          start({
+            emitter,
+            port,
+            status: this.status,
+          })
+            .then(() => {
+              status = 'started'
+
+              stopResolver = Promise.withResolvers<void>()
+              startResolver.resolve(this.stop)
+            })
+            .catch((error) => {
+              status = 'idle'
+              this.messages.clear()
+              emitter.off('message', onMessage)
+              startResolver.reject(error)
+            })
+
+          return startResolver.promise
+        },
+        async stop() {
+          if (status === 'stopping') return stopResolver.promise
+          if (status === 'starting')
+            throw new Error(`Instance "${name}" is starting.`)
+
+          if (typeof timeout === 'number') {
+            const timer = setTimeout(() => {
+              clearTimeout(timer)
+              stopResolver.reject(
+                new Error(`Instance "${name}" failed to stop in time.`),
+              )
+            }, timeout)
+          }
+
+          status = 'stopping'
+          stop({
+            emitter,
+            status: this.status,
+          })
+            .then((...args) => {
+              status = 'stopped'
+              this.messages.clear()
+
+              emitter.off('message', onMessage)
+              emitter.off('listening', onListening)
+              emitter.off('exit', onExit)
+
+              startResolver = Promise.withResolvers<() => void>()
+              stopResolver.resolve(...args)
+            })
+            .catch((error) => {
+              status = 'started'
+              stopResolver.reject(error)
+            })
+
+          return stopResolver.promise
+        },
+
+        addListener: emitter.addListener.bind(emitter),
+        off: emitter.off.bind(emitter),
+        on: emitter.on.bind(emitter),
+        once: emitter.once.bind(emitter),
+        removeListener: emitter.removeListener.bind(emitter),
+        removeAllListeners: emitter.removeAllListeners.bind(emitter),
+      }
+    }
+
+    return Object.assign(create(), { create })
+  }
+}

package/instances/anvil.test.ts

@@ -0,0 +1,130 @@
+import { afterEach, expect, test } from 'vitest'
+import type { Instance } from '../instance.js'
+import { type AnvilParameters, anvil } from './anvil.js'
+
+const instances: Instance[] = []
+const timestamp = 1717114065
+
+const defineInstance = (parameters: AnvilParameters = {}) => {
+  const instance = anvil(parameters)
+  instances.push(instance)
+  return instance
+}
+
+afterEach(async () => {
+  for (const instance of instances) await instance.stop().catch(() => {})
+})
+
+test('default', async () => {
+  const messages: string[] = []
+  const stdouts: string[] = []
+
+  const instance = defineInstance({ timestamp })
+
+  instance.on('message', (m) => messages.push(m))
+  instance.on('stdout', (m) => stdouts.push(m))
+
+  expect(instance.messages.get()).toMatchInlineSnapshot('[]')
+
+  await instance.start()
+  expect(instance.status).toEqual('started')
+
+  expect(messages.join('')).toBeDefined()
+  expect(stdouts.join('')).toBeDefined()
+  expect(instance.messages.get().join('')).toBeDefined()
+
+  await instance.stop()
+  expect(instance.status).toEqual('stopped')
+
+  expect(messages.join('')).toBeDefined()
+  expect(stdouts.join('')).toBeDefined()
+  expect(instance.messages.get()).toMatchInlineSnapshot('[]')
+})
+
+test('behavior: instance errored (duplicate ports)', async () => {
+  const instance_1 = defineInstance({ timestamp, port: 8545 })
+  const instance_2 = defineInstance({ timestamp, port: 8545 })
+
+  await instance_1.start()
+  await expect(() => instance_2.start()).rejects.toThrowError(
+    'Failed to start anvil',
+  )
+})
+
+test('behavior: start and stop multiple times', async () => {
+  const instance = defineInstance()
+
+  await instance.start()
+  await instance.stop()
+  await instance.start()
+  await instance.stop()
+  await instance.start()
+  await instance.stop()
+  await instance.start()
+  await instance.stop()
+})
+
+test('behavior: can subscribe to stdout', async () => {
+  const messages: string[] = []
+  const instance = defineInstance({ timestamp })
+  instance.on('stdout', (message) => messages.push(message))
+
+  await instance.start()
+  expect(messages.length).toBeGreaterThanOrEqual(1)
+})
+
+test('behavior: can subscribe to stderr', async () => {
+  const messages: string[] = []
+
+  const instance_1 = defineInstance({ timestamp, port: 8545 })
+  const instance_2 = defineInstance({ timestamp, port: 8545 })
+
+  await instance_1.start()
+  instance_2.on('stderr', (message) => messages.push(message))
+  await expect(instance_2.start()).rejects.toThrow('Failed to start anvil')
+
+  expect(messages.length).toBeGreaterThanOrEqual(1)
+  expect(messages.join('')).toContain('Address already in use')
+})
+
+test('behavior: starts anvil with custom options', async () => {
+  const instance = defineInstance({
+    timestamp,
+    chainId: 123,
+    forkBlockNumber: 69420,
+    forkUrl: 'https://cloudflare-eth.com',
+  })
+
+  await instance.start()
+})
+
+test('behavior: exit', async () => {
+  const instance = defineInstance({ timestamp })
+
+  let exitCode: number | null | undefined = undefined
+  instance.on('exit', (code) => {
+    exitCode = code
+  })
+
+  await instance.start()
+  expect(instance.status).toEqual('started')
+
+  instance._internal.process.kill()
+
+  await new Promise<void>((res) => setTimeout(res, 100))
+  expect(instance.status).toEqual('stopped')
+  expect(typeof exitCode !== 'undefined').toBeTruthy()
+})
+
+test('behavior: exit when status is starting', async () => {
+  const instance = defineInstance({ timestamp })
+
+  const promise = instance.start()
+  expect(instance.status).toEqual('starting')
+
+  instance._internal.process.kill()
+
+  await expect(promise).rejects.toThrowErrorMatchingInlineSnapshot(
+    '[Error: Failed to start anvil: exited.]',
+  )
+})