prool 0.0.3 → 0.0.5

package/pool.test.ts

@@ -1,9 +1,15 @@
 import getPort from 'get-port'
-import { afterEach, describe, expect, test } from 'vitest'
+import { afterEach, beforeAll, describe, expect, test } from 'vitest'
+
+import { stackupOptions } from '../test/utils.js'
 import { anvil } from './instances/anvil.js'
+import { stackup } from './instances/stackup.js'
 import { definePool } from './pool.js'
 
 let pool: ReturnType<typeof definePool>
+const port = await getPort()
+
+beforeAll(() => anvil({ port }).start())
 
 afterEach(async () => {
   try {
@@ -13,197 +19,256 @@ afterEach(async () => {
   }
 })
 
-describe.each([{ instance: anvil() }])(
-  'instance: $instance.name',
-  ({ instance }) => {
-    test('default', async () => {
-      pool = definePool({
-        instance,
-      })
+describe.each([
+  { instance: anvil() },
+  {
+    instance: stackup(stackupOptions({ port })),
+  },
+])('instance: $instance.name', ({ instance }) => {
+  test('default', async () => {
+    pool = definePool({
+      instance,
+    })
+
+    expect(pool).toBeDefined()
+  })
 
-      expect(pool).toBeDefined()
+  test('start', async () => {
+    pool = definePool({
+      instance,
     })
 
-    test('start', async () => {
-      pool = definePool({
-        instance,
-      })
+    expect(pool.size).toEqual(0)
 
-      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_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_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)
+  })
 
-      const instance_3 = await pool.start(1337)
-      expect(instance_3.status).toBe('started')
-      expect(pool.size).toEqual(3)
+  test('callback instance', async () => {
+    const keys: (number | string)[] = []
+    pool = definePool({
+      instance(key) {
+        keys.push(key)
+        return instance
+      },
     })
 
-    test('stop / destroy', async () => {
-      pool = definePool({
-        instance,
-      })
+    await pool.start(1)
+    await pool.start(2)
+    await pool.start(1337)
 
-      const instance_1 = await pool.start(1)
-      const instance_2 = await pool.start(2)
-      const instance_3 = await pool.start(3)
+    expect(keys).toStrictEqual([1, 2, 1337])
+  })
 
-      expect(instance_1.status).toBe('started')
-      expect(instance_2.status).toBe('started')
-      expect(instance_3.status).toBe('started')
-      expect(pool.size).toEqual(3)
+  test('stop / destroy', async () => {
+    pool = definePool({
+      instance,
+    })
 
-      await pool.stop(1)
-      expect(instance_1.status).toBe('stopped')
+    const instance_1 = await pool.start(1)
+    const instance_2 = await pool.start(2)
+    const instance_3 = await pool.start(3)
 
-      await pool.stop(2)
-      expect(instance_2.status).toBe('stopped')
+    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(3)
-      expect(instance_3.status).toBe('stopped')
+    await pool.stop(1)
+    expect(instance_1.status).toBe('stopped')
 
-      await pool.stop(1)
-      await pool.stop(2)
-      await pool.stop(3)
-      await pool.stop(4)
+    await pool.stop(2)
+    expect(instance_2.status).toBe('stopped')
 
-      expect(pool.size).toEqual(3)
+    await pool.stop(3)
+    expect(instance_3.status).toBe('stopped')
 
-      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)
+    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('restart', async () => {
+    pool = definePool({
+      instance,
     })
 
-    test('start > stop > start', 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)
 
-      const instance_1 = await pool.start(1)
-      expect(instance_1.status).toBe('started')
+    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')
+    const promise_1 = pool.restart(1)
+    expect(instance_1.status).toBe('restarting')
+    await promise_1
+    expect(instance_1.status).toBe('started')
+  })
 
-      await pool.start(1)
-      expect(instance_1.status).toBe('started')
+  test('start > stop > start', async () => {
+    pool = definePool({
+      instance,
     })
 
-    test('stopAll / destroyAll', async () => {
-      pool = definePool({
-        instance,
-      })
+    const instance_1 = await pool.start(1)
+    expect(instance_1.status).toBe('started')
 
-      await pool.start(1)
-      await pool.start(2)
-      await pool.start(3)
+    await pool.stop(1)
+    expect(instance_1.status).toBe('stopped')
 
-      expect(pool.size).toEqual(3)
+    await pool.start(1)
+    expect(instance_1.status).toBe('started')
+  })
+
+  test('stopAll / destroyAll', async () => {
+    pool = definePool({
+      instance,
+    })
 
-      await pool.stopAll()
-      expect(pool.size).toEqual(3)
+    await pool.start(1)
+    await pool.start(2)
+    await pool.start(3)
 
-      await pool.destroyAll()
-      expect(pool.size).toEqual(0)
+    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,
     })
 
-    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)
 
-      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)
+  })
 
-      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,
     })
 
-    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 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)
+  })
 
-      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,
     })
 
-    test('behavior: clear more than once', async () => {
-      pool = definePool({
-        instance,
-      })
+    await pool.start(1)
+    await pool.start(2)
+    await pool.start(3)
 
-      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)
 
-      const promise_1 = pool.stopAll()
-      const promise_2 = pool.stopAll()
-      expect(promise_1).toStrictEqual(promise_2)
+    await promise_1
+    await promise_2
+  })
 
-      await promise_1
-      await promise_2
+  test('behavior: restart more than once', async () => {
+    pool = definePool({
+      instance,
     })
 
-    test('behavior: stop more than once', async () => {
-      pool = definePool({
-        instance,
-      })
+    const instance_1 = await pool.start(1)
+    expect(instance_1.status).toBe('started')
+
+    const promise_1 = pool.restart(1)
+    expect(instance_1.status).toBe('restarting')
+    const promise_2 = pool.restart(1)
+    expect(instance_1.status).toBe('restarting')
 
-      await pool.start(1)
+    expect(promise_1).toStrictEqual(promise_2)
 
-      const promise_1 = pool.stop(1)
-      const promise_2 = pool.stop(1)
-      expect(promise_1).toStrictEqual(promise_2)
+    await promise_1
+    expect(instance_1.status).toBe('started')
+    await promise_2
+    expect(instance_1.status).toBe('started')
+  })
 
-      await promise_1
-      await promise_2
+  test('behavior: stop more than once', async () => {
+    pool = definePool({
+      instance,
     })
 
-    test('error: start more than once on same port', async () => {
-      const port = await getPort()
+    await pool.start(1)
 
-      pool = definePool({
-        instance,
-      })
+    const promise_1 = pool.stop(1)
+    const promise_2 = pool.stop(1)
+    expect(promise_1).toStrictEqual(promise_2)
 
-      await pool.start(1, { port })
+    await promise_1
+    await promise_2
+  })
 
-      const promise_1 = pool.start(2, { port })
-      const promise_2 = pool.start(2, { port })
-      expect(promise_1).toStrictEqual(promise_2)
+  test('error: start more than once on same port', async () => {
+    const port = await getPort()
 
-      await expect(() => promise_1).rejects.toThrowError()
-      await expect(() => promise_2).rejects.toThrowError()
+    pool = definePool({
+      instance,
     })
 
-    test('error: instance limit reached', async () => {
-      pool = definePool({
-        instance,
-        limit: 2,
-      })
+    await pool.start(1, { port })
 
-      await pool.start(1)
-      await pool.start(2)
+    const promise_1 = pool.start(2, { port })
+    const promise_2 = pool.start(2, { port })
+    expect(promise_1).toStrictEqual(promise_2)
 
-      await expect(() => pool.start(3)).rejects.toThrowError(
-        'Instance limit of 2 reached.',
-      )
+    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.',
+    )
+  })
+})

package/pool.ts

@@ -4,28 +4,33 @@ import type { Instance } from './instance.js'
 
 type Instance_ = Omit<Instance, 'create'>
 
-export type Pool<key = number> = Pick<
+export type Pool<key extends number | string = number | string> = Pick<
   Map<key, Instance_>,
   'entries' | 'keys' | 'forEach' | 'get' | 'has' | 'size' | 'values'
 > & {
   _internal: {
-    instance: Instance_
+    instance: Instance_ | ((key: key) => Instance_)
   }
   destroy(key: key): Promise<void>
   destroyAll(): Promise<void>
+  restart(key: key): Promise<void>
   start(key: key, options?: { port?: number }): Promise<Instance_>
   stop(key: key): Promise<void>
   stopAll(): Promise<void>
 }
 
-export type DefinePoolParameters = {
+export type DefinePoolParameters<
+  key extends number | string = number | string,
+> = {
   /** Instance for the pool. */
-  instance: Instance
+  instance: Instance | ((key: key) => Instance)
   /** The maximum number of instances that can be started. */
   limit?: number | number
 }
 
-export type DefinePoolReturnType<key = number> = Pool<key>
+export type DefinePoolReturnType<
+  key extends number | string = number | string,
+> = Pool<key>
 
 /**
  * Defines an instance pool. Instances can be started, cached, and stopped against an identifier.
@@ -41,10 +46,10 @@ export type DefinePoolReturnType<key = number> = Pool<key>
  * const instance_3 = await pool.start(3)
  * ```
  */
-export function definePool<key = number>(
-  parameters: DefinePoolParameters,
+export function definePool<key extends number | string = number>(
+  parameters: DefinePoolParameters<key>,
 ): DefinePoolReturnType<key> {
-  const { instance, limit } = parameters
+  const { limit } = parameters
 
   type Instance_ = Omit<Instance, 'create'>
   const instances = new Map<key, Instance_>()
@@ -56,6 +61,7 @@ export function definePool<key = number>(
   const promises = {
     destroy: new Map<key, Promise<void>>(),
     destroyAll: undefined as Promise<void> | undefined,
+    restart: new Map<key, Promise<void>>(),
     start: new Map<key, Promise<Instance_>>(),
     stop: new Map<key, Promise<void>>(),
     stopAll: undefined as Promise<void> | undefined,
@@ -63,7 +69,7 @@ export function definePool<key = number>(
 
   return {
     _internal: {
-      instance,
+      instance: parameters.instance,
     },
     async destroy(key) {
       const destroyPromise = promises.destroy.get(key)
@@ -71,16 +77,14 @@ export function definePool<key = number>(
 
       const resolver = Promise.withResolvers<void>()
 
-      try {
-        promises.destroy.set(key, resolver.promise)
+      promises.destroy.set(key, resolver.promise)
 
-        await this.stop(key)
-        instances.delete(key)
-
-        resolver.resolve()
-      } catch (error) {
-        resolver.reject(error)
-      }
+      this.stop(key)
+        .then(() => {
+          instances.delete(key)
+          resolver.resolve()
+        })
+        .catch(resolver.reject)
 
       return resolver.promise
     },
@@ -89,17 +93,35 @@ export function definePool<key = number>(
 
       const resolver = Promise.withResolvers<void>()
 
-      try {
-        promises.destroyAll = resolver.promise
+      promises.destroyAll = resolver.promise
+
+      Promise.all([...instances.keys()].map((key) => this.destroy(key)))
+        .then(() => {
+          promises.destroyAll = undefined
+          resolver.resolve()
+        })
+        .catch(resolver.reject)
+
+      return resolver.promise
+    },
+    async restart(key) {
+      const restartPromise = promises.restart.get(key)
+      if (restartPromise) return restartPromise
+
+      const resolver = Promise.withResolvers<void>()
+
+      const instance_ = instances.get(key)
+      if (!instance_) return
 
-        await Promise.all([...instances.keys()].map((key) => this.destroy(key)))
+      promises.restart.set(key, resolver.promise)
 
-        promises.destroyAll = undefined
+      instance_
+        .restart()
+        .then(resolver.resolve)
+        .catch(resolver.reject)
+        .finally(() => promises.restart.delete(key))
 
-        resolver.resolve()
-      } catch (error) {
-        resolver.reject(error)
-      }
+      return resolver.promise
     },
     async start(key, options = {}) {
       const startPromise = promises.start.get(key)
@@ -107,24 +129,26 @@ export function definePool<key = number>(
 
       const resolver = Promise.withResolvers<Instance_>()
 
-      try {
-        promises.start.set(key, resolver.promise)
-
-        if (limit && instances.size >= limit)
-          throw new Error(`Instance limit of ${limit} reached.`)
+      if (limit && instances.size >= limit)
+        throw new Error(`Instance limit of ${limit} reached.`)
 
-        const { port = await getPort() } = options
+      promises.start.set(key, resolver.promise)
 
-        const instance_ = instances.get(key) || instance.create({ port })
-        await instance_.start()
+      const instance =
+        typeof parameters.instance === 'function'
+          ? parameters.instance(key)
+          : parameters.instance
+      const { port = await getPort() } = options
 
-        instances.set(key, instance_)
-        resolver.resolve(instance_)
-      } catch (error) {
-        resolver.reject(error)
-      } finally {
-        promises.start.delete(key)
-      }
+      const instance_ = instances.get(key) || instance.create({ port })
+      instance_
+        .start()
+        .then(() => {
+          instances.set(key, instance_)
+          resolver.resolve(instance_)
+        })
+        .catch(resolver.reject)
+        .finally(() => promises.start.delete(key))
 
       return resolver.promise
     },
@@ -132,42 +156,35 @@ export function definePool<key = number>(
       const stopPromise = promises.stop.get(key)
       if (stopPromise) return stopPromise
 
-      const resolver = Promise.withResolvers<void>()
+      const instance_ = instances.get(key)
+      if (!instance_) return
 
-      try {
-        promises.stop.set(key, resolver.promise)
-
-        const instance_ = instances.get(key)
-        if (!instance_) {
-          resolver.resolve()
-          return
-        }
+      const resolver = Promise.withResolvers<void>()
 
-        await instance_.stop()
+      promises.stop.set(key, resolver.promise)
+      instance_
+        .stop()
+        .then(resolver.resolve)
+        .catch(resolver.reject)
+        .finally(() => promises.stop.delete(key))
 
-        resolver.resolve()
-      } catch (error) {
-        resolver.reject(error)
-      } finally {
-        promises.stop.delete(key)
-      }
+      return resolver.promise
     },
     async stopAll() {
       if (promises.stopAll) return promises.stopAll
 
       const resolver = Promise.withResolvers<void>()
 
-      try {
-        promises.stopAll = resolver.promise
-
-        await Promise.all([...instances.keys()].map((key) => this.stop(key)))
+      promises.stopAll = resolver.promise
 
-        promises.stopAll = undefined
+      Promise.all([...instances.keys()].map((key) => this.stop(key)))
+        .then(() => {
+          promises.stopAll = undefined
+          resolver.resolve()
+        })
+        .catch(resolver.reject)
 
-        resolver.resolve()
-      } catch (error) {
-        resolver.reject(error)
-      }
+      return resolver.promise
     },
 
     get size() {