wardens 0.1.0 → 0.4.0

package/CHANGELOG.md

@@ -6,7 +6,47 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
-## [0.1.0]
+## [0.4.0] - 2022-06-19
+
+### Added
+
+- Support for provisioning resources through async functions instead of `Resource` subclasses. This offers better type safety around null conditions.
+- A new `Resource` utility type is exported. The new functional API expects you to return this interface.
+
+### Removed
+
+- The `Resource` abstract class was removed. Use async functions instead.
+- The `Controls<...>` utility type was removed. Import the type you need from the module instead.
+
+## [0.3.0] - 2022-06-04
+
+### Changed
+
+- Prevent use of `allocate(...)`/`deallocate(...)` outside a resource subclass.
+- Renamed `enter()` and `leave()` to `create()` and `destroy()`.
+- Renamed `mount()` and `unmount()` to `create()` and `destroy()`.
+
+### Removed
+
+- Second type parameter to `Resource` is gone. Arguments to `enter(...)` are now inferred.
+- No more default implementations for `enter(...)`/`leave(...)` on resources.
+
+## [0.2.0] - 2022-05-24
+
+### Fixed
+
+- `mount(...)` and `allocate(...)` no longer require a config argument if the resource doesn't explicitly define one.
+
+### Added
+
+- `enter(...)` now supports variable arguments.
+
+### Changed
+
+- The second generic parameter of `Resource` was a config parameter, but now it's an argument tuple.
+- The `ExternalControls` utility type was renamed to `Controls`.
+
+## [0.1.0] - 2022-05-22
 
 ### Added
 
@@ -14,5 +54,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 - `mount`/`unmount` hooks to provision resources
 - `allocate`/`deallocate` for creating hierarchies of resources
 
-[Unreleased]: https://github.com/PsychoLlama/wardens/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/PsychoLlama/wardens/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/PsychoLlama/wardens/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/PsychoLlama/wardens/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/PsychoLlama/wardens/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/PsychoLlama/wardens/releases/tag/v0.1.0

package/README.md

@@ -1,6 +1,10 @@
-# Wardens
-
-A tiny framework for managing resources.
+<div align="center">
+  <h1>Wardens</h1>
+  <p>A tiny framework for managing resources.</p>
+  <img alt="Build status" src="https://img.shields.io/github/workflow/status/PsychoLlama/wardens/Test/main" />
+  <img alt="TypeScript" src="https://img.shields.io/npm/types/wardens" />
+  <img alt="npm version" src="https://img.shields.io/npm/v/wardens" />
+</div>
 
 ## Overview
 
@@ -9,50 +13,40 @@ This library is designed for applications that dynamically provision and dealloc
 Here's an example: let's say you've got a thread pool, one per CPU. Each thread gets a `Resource`, a small wrapper that hooks into setup and teardown controls.
 
 ```typescript
-class Worker extends Resource<Thread> {
-  thread!: Thread;
+async function Worker() {
+  const thread = await spawn()
 
-  // Called when the resource is created
-  async enter() {
-    this.thread = await spawn()
-  }
+  return {
+    // The value returned after initialization completes
+    value: thread,
 
-  // Called when the resource is destroyed
-  async leave() {
-    this.thread.close()
+    // Called when the resource is destroyed
+    destroy: () => thread.close(),
   }
-
-  // The value returned after initialization completes
-  exports = () => this.thread
 }
 ```
 
 Now define a pool that creates and manages workers:
 
 ```typescript
-class WorkerPool extends Resource<Controls, Config> {
-  threads!: Array<Thread> = [];
-
-  async enter({ poolSize }: Config) {
-    const promises = Array(poolSize).fill().map(() => {
-      return this.allocate(Worker)
-    })
-
-    this.threads = await Promise.all(promises)
+async function WorkerPool({ create }: ResourceContext, config: { poolSize: number }) {
+  const promises = Array(config.poolSize).fill(Worker).map(create)
+  const threads = await Promise.all(promises)
+
+  return {
+    // ... External API goes here ...
+    value: {
+      doSomeWork() {},
+      doSomethingElse() {},
+    }
   }
-
-  // ... External API goes here ...
-  exports = (): Controls => ({
-    doSomeWork() {},
-    doSomethingElse() {},
-  })
 }
 ```
 
-Finally, mount it:
+Finally, create the pool:
 
 ```typescript
-const pool = await mount(WorkerPool, {
+const pool = await create(WorkerPool, {
   poolSize: cpus().length,
 })
 
@@ -64,7 +58,7 @@ pool.doSomethingElse()
 The magic of this framework is that resources never outlive their owners. If you tear down the pool, it will deallocate everything beneath it first:
 
 ```typescript
-await unmount(pool)
+await destroy(pool)
 
 // [info] closing worker
 // [info] closing worker

package/dist/wardens.es.js

@@ -1,3 +1,9 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => {
+  __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
 var __accessCheck = (obj, member, msg) => {
   if (!member.has(obj))
     throw TypeError("Cannot " + msg);
@@ -11,67 +17,12 @@ var __privateAdd = (obj, member, value) => {
     throw TypeError("Cannot add the same private member more than once");
   member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
 };
-var _resources, _children;
-const resources = /* @__PURE__ */ new WeakMap();
-const ownership = /* @__PURE__ */ new WeakMap();
-function wrapWithProxy(value) {
-  return Proxy.revocable(value, {});
-}
-async function mount(Subtype, params) {
-  const resource = new Subtype();
-  await resource.enter(params);
-  const api = resource.exports();
-  const { proxy, revoke } = wrapWithProxy(api);
-  resources.set(proxy, {
-    resource,
-    revoke
-  });
-  return proxy;
-}
-async function unmount(api) {
-  const entry = resources.get(api);
-  if (entry) {
-    resources.delete(api);
-    entry.revoke();
-    const children = ownership.get(entry.resource);
-    ownership.delete(entry.resource);
-    const recursiveUnmounts = children.map((api2) => unmount(api2));
-    const results = await Promise.allSettled(recursiveUnmounts);
-    await entry.resource.leave();
-    results.forEach((result) => {
-      if (result.status === "rejected") {
-        throw result.reason;
-      }
-    });
-  }
-}
-class Resource {
-  constructor() {
-    __privateAdd(this, _resources, /* @__PURE__ */ new WeakSet());
-    __privateAdd(this, _children, []);
-    ownership.set(this, __privateGet(this, _children));
-  }
-  async enter(_params) {
-    return;
-  }
-  async leave() {
-    return;
-  }
-  async allocate(Child, params) {
-    const api = await mount(Child, params);
-    __privateGet(this, _resources).add(api);
-    __privateGet(this, _children).push(api);
-    return api;
-  }
-  async deallocate(api) {
-    if (!__privateGet(this, _resources).has(api)) {
-      throw new Error("You do not own this resource.");
-    }
-    return unmount(api);
-  }
-}
-_resources = new WeakMap();
-_children = new WeakMap();
+var __privateSet = (obj, member, value, setter) => {
+  __accessCheck(obj, member, "write to private field");
+  setter ? setter.call(obj, value) : member.set(obj, value);
+  return value;
+};
+var _resources;
 function bindContext(value) {
   const methodBindings = /* @__PURE__ */ new WeakMap();
   return new Proxy(value, {
@@ -92,4 +43,60 @@ function bindContext(value) {
     }
   });
 }
-export { Resource, bindContext, mount, unmount };
+const resources = /* @__PURE__ */ new WeakMap();
+function wrapWithProxy(value) {
+  return Proxy.revocable(value, {});
+}
+class ResourceContext {
+  constructor(ownedResources) {
+    __privateAdd(this, _resources, void 0);
+    __publicField(this, "create", async (factory, ...args) => {
+      const controls = await create(factory, ...args);
+      __privateGet(this, _resources).add(controls);
+      return controls;
+    });
+    __publicField(this, "destroy", async (resource) => {
+      if (!__privateGet(this, _resources).has(resource)) {
+        throw new Error("You do not own this resource.");
+      }
+      try {
+        await destroy(resource);
+      } finally {
+        __privateGet(this, _resources).delete(resource);
+      }
+    });
+    __privateSet(this, _resources, ownedResources);
+  }
+}
+_resources = new WeakMap();
+async function create(provision, ...args) {
+  const children = /* @__PURE__ */ new Set();
+  const context = new ResourceContext(children);
+  const resource = await provision(context, ...args);
+  const controls = resource.value;
+  const { proxy, revoke } = wrapWithProxy(controls);
+  resources.set(proxy, {
+    resource,
+    children,
+    revoke
+  });
+  return proxy;
+}
+async function destroy(controls) {
+  const entry = resources.get(controls);
+  if (entry) {
+    resources.delete(controls);
+    entry.revoke();
+    const recursiveUnmounts = Array.from(entry.children).map(destroy);
+    const results = await Promise.allSettled(recursiveUnmounts);
+    if (entry.resource.destroy) {
+      await entry.resource.destroy();
+    }
+    results.forEach((result) => {
+      if (result.status === "rejected") {
+        throw result.reason;
+      }
+    });
+  }
+}
+export { bindContext, create, destroy };

package/dist/wardens.umd.js

@@ -1 +1 @@
-var b=(e,t,c)=>{if(!t.has(e))throw TypeError("Cannot "+c)};var f=(e,t,c)=>(b(e,t,"read from private field"),c?c.call(e):t.get(e)),h=(e,t,c)=>{if(t.has(e))throw TypeError("Cannot add the same private member more than once");t instanceof WeakSet?t.add(e):t.set(e,c)};(function(e,t){typeof exports=="object"&&typeof module!="undefined"?t(exports):typeof define=="function"&&define.amd?define(["exports"],t):(e=typeof globalThis!="undefined"?globalThis:e||self,t(e.wardens={}))})(this,function(e){var a,d;"use strict";const t=new WeakMap,c=new WeakMap;function w(i){return Proxy.revocable(i,{})}async function p(i,n){const o=new i;await o.enter(n);const s=o.exports(),{proxy:r,revoke:u}=w(s);return t.set(r,{resource:o,revoke:u}),r}async function l(i){const n=t.get(i);if(n){t.delete(i),n.revoke();const o=c.get(n.resource);c.delete(n.resource);const s=o.map(u=>l(u)),r=await Promise.allSettled(s);await n.resource.leave(),r.forEach(u=>{if(u.status==="rejected")throw u.reason})}}class y{constructor(){h(this,a,new WeakSet);h(this,d,[]);c.set(this,f(this,d))}async enter(n){}async leave(){}async allocate(n,o){const s=await p(n,o);return f(this,a).add(s),f(this,d).push(s),s}async deallocate(n){if(!f(this,a).has(n))throw new Error("You do not own this resource.");return l(n)}}a=new WeakMap,d=new WeakMap;function m(i){const n=new WeakMap;return new Proxy(i,{get(o,s){const r=Reflect.get(o,s,o);if(typeof r=="function"){if(n.has(r)===!1){const u=r.bind(o);Object.defineProperties(u,Object.getOwnPropertyDescriptors(r)),n.set(r,u)}return n.get(r)}return r},set(o,s,r){return Reflect.set(o,s,r,o)}})}e.Resource=y,e.bindContext=m,e.mount=p,e.unmount=l,Object.defineProperties(e,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}})});
+var P=Object.defineProperty;var g=(e,t,n)=>t in e?P(e,t,{enumerable:!0,configurable:!0,writable:!0,value:n}):e[t]=n;var y=(e,t,n)=>(g(e,typeof t!="symbol"?t+"":t,n),n),p=(e,t,n)=>{if(!t.has(e))throw TypeError("Cannot "+n)};var f=(e,t,n)=>(p(e,t,"read from private field"),n?n.call(e):t.get(e)),b=(e,t,n)=>{if(t.has(e))throw TypeError("Cannot add the same private member more than once");t instanceof WeakSet?t.add(e):t.set(e,n)},m=(e,t,n,u)=>(p(e,t,"write to private field"),u?u.call(e,n):t.set(e,n),n);(function(e,t){typeof exports=="object"&&typeof module!="undefined"?t(exports):typeof define=="function"&&define.amd?define(["exports"],t):(e=typeof globalThis!="undefined"?globalThis:e||self,t(e.wardens={}))})(this,function(e){var a;"use strict";function t(c){const o=new WeakMap;return new Proxy(c,{get(s,i){const r=Reflect.get(s,i,s);if(typeof r=="function"){if(o.has(r)===!1){const d=r.bind(s);Object.defineProperties(d,Object.getOwnPropertyDescriptors(r)),o.set(r,d)}return o.get(r)}return r},set(s,i,r){return Reflect.set(s,i,r,s)}})}const n=new WeakMap;function u(c){return Proxy.revocable(c,{})}class v{constructor(o){b(this,a,void 0);y(this,"create",async(o,...s)=>{const i=await h(o,...s);return f(this,a).add(i),i});y(this,"destroy",async o=>{if(!f(this,a).has(o))throw new Error("You do not own this resource.");try{await l(o)}finally{f(this,a).delete(o)}});m(this,a,o)}}a=new WeakMap;async function h(c,...o){const s=new Set,i=new v(s),r=await c(i,...o),d=r.value,{proxy:w,revoke:x}=u(d);return n.set(w,{resource:r,children:s,revoke:x}),w}async function l(c){const o=n.get(c);if(o){n.delete(c),o.revoke();const s=Array.from(o.children).map(l),i=await Promise.allSettled(s);o.resource.destroy&&await o.resource.destroy(),i.forEach(r=>{if(r.status==="rejected")throw r.reason})}}e.bindContext=t,e.create=h,e.destroy=l,Object.defineProperties(e,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}})});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wardens",
-  "version": "0.1.0",
+  "version": "0.4.0",
   "description": "A framework for resource management",
   "main": "./dist/wardens.umd.js",
   "module": "./dist/wardens.es.js",
@@ -11,6 +11,15 @@
     "dist",
     "src"
   ],
+  "keywords": [
+    "resource",
+    "management",
+    "manager",
+    "server",
+    "lifetimes",
+    "hierarchy",
+    "framework"
+  ],
   "scripts": {
     "prepare": "tsc && vite build",
     "test": "./bin/run-tests",
@@ -73,17 +82,17 @@
     "preset": "ts-jest"
   },
   "devDependencies": {
-    "@types/jest": "27.5.1",
-    "@typescript-eslint/eslint-plugin": "5.25.0",
-    "@typescript-eslint/parser": "5.25.0",
-    "eslint": "8.16.0",
+    "@types/jest": "28.1.2",
+    "@typescript-eslint/eslint-plugin": "5.28.0",
+    "@typescript-eslint/parser": "5.28.0",
+    "eslint": "8.18.0",
     "husky": "8.0.1",
-    "jest": "28.1.0",
-    "lint-staged": "12.4.1",
-    "prettier": "2.6.2",
-    "ts-jest": "28.0.2",
-    "typescript": "4.6.4",
-    "vite": "2.9.9",
+    "jest": "28.1.1",
+    "lint-staged": "13.0.2",
+    "prettier": "2.7.1",
+    "ts-jest": "28.0.5",
+    "typescript": "4.7.4",
+    "vite": "2.9.12",
     "vite-dts": "1.0.4"
   }
 }

package/src/__tests__/allocation.test.ts

@@ -1,87 +1,75 @@
-import Resource from '../resource';
-import { mount, unmount } from '../allocation';
+import type ResourceContext from '../resource-context';
+import { create, destroy } from '../allocation';
 
 describe('allocation', () => {
-  describe('mount', () => {
+  describe('create', () => {
     it('allocates the resource', async () => {
-      const params = { test: 'init-args' };
-      const enter = jest.fn();
-
-      class Test extends Resource<{ test: boolean }, { test: string }> {
-        exports = () => ({ test: true });
-        enter = enter;
-      }
-
-      await expect(mount(Test, params)).resolves.toEqual({ test: true });
-      expect(enter).toHaveBeenCalledWith(params);
+      const config = { test: 'init-args' };
+      const Test = jest.fn(
+        async (_resource: ResourceContext, config: { test: string }) => ({
+          value: config,
+        }),
+      );
+
+      await expect(create(Test, config)).resolves.toEqual(config);
+      expect(Test).toHaveBeenCalledWith(expect.anything(), config);
     });
   });
 
-  describe('unmount', () => {
+  describe('destroy', () => {
     it('deallocates the resource', async () => {
-      const leave = jest.fn();
-
-      class Test extends Resource<Array<string>> {
-        exports = () => [];
-        leave = leave;
-      }
+      const spy = jest.fn<void, []>();
+      const Test = async () => ({
+        value: {},
+        destroy: spy,
+      });
 
-      const api = await mount(Test, null);
+      const test = await create(Test);
 
-      expect(leave).not.toHaveBeenCalled();
-      await expect(unmount(api)).resolves.not.toThrow();
-      expect(leave).toHaveBeenCalled();
+      expect(spy).not.toHaveBeenCalled();
+      await expect(destroy(test)).resolves.not.toThrow();
+      expect(spy).toHaveBeenCalled();
     });
 
     it('survives if the resource is already deallocated', async () => {
-      class Test extends Resource<Array<number>> {
-        exports = () => [];
-      }
+      const Test = async () => ({ value: [] });
 
-      const api = await mount(Test, null);
-      await unmount(api);
+      const test = await create(Test);
+      await destroy(test);
 
-      await expect(unmount(api)).resolves.not.toThrow();
+      await expect(destroy(test)).resolves.not.toThrow();
     });
 
     it('automatically unmounts all children', async () => {
-      const leave = jest.fn();
-      class Child extends Resource<number[]> {
-        exports = () => [];
-        leave = leave;
-      }
-
-      class Parent extends Resource<string[]> {
-        exports = () => [];
-        async enter() {
-          await this.allocate(Child, null);
-        }
+      const spy = jest.fn();
+      const Child = async () => ({ value: [], destroy: spy });
+      async function Parent(resource: ResourceContext) {
+        await resource.create(Child);
+        return { value: [] };
       }
 
-      const parent = await mount(Parent, null);
-      await unmount(parent);
+      const parent = await create(Parent);
+      await destroy(parent);
 
-      expect(leave).toHaveBeenCalled();
+      expect(spy).toHaveBeenCalled();
     });
 
-    it('throws an error if any of the children fail to unmount', async () => {
-      const error = new Error('Testing unmount errors');
-      class Child extends Resource<number[]> {
-        exports = () => [];
-        async leave() {
+    it('throws an error if any of the children fail to close', async () => {
+      const error = new Error('Testing resource destruction errors');
+      const Child = async () => ({
+        value: [],
+        destroy() {
           throw error;
-        }
-      }
+        },
+      });
 
-      class Parent extends Resource<string[]> {
-        exports = () => [];
-        async enter() {
-          await this.allocate(Child, null);
-        }
-      }
+      const Parent = async (resource: ResourceContext) => {
+        await resource.create(Child);
+        return { value: [] };
+      };
 
-      const parent = await mount(Parent, null);
-      await expect(unmount(parent)).rejects.toThrow(error);
+      const parent = await create(Parent);
+      await expect(destroy(parent)).rejects.toThrow(error);
     });
   });
 });

package/src/__tests__/resource-context.test.ts

@@ -0,0 +1,63 @@
+import ResourceContext from '../resource-context';
+import { create } from '../allocation';
+
+describe('ResourceContext', () => {
+  async function Test() {
+    return { value: {} };
+  }
+
+  it('can spawn children of its own', async () => {
+    const Child = async () => ({
+      value: { child: true },
+    });
+
+    const Parent = async (resource: ResourceContext) => {
+      return { value: await resource.create(Child) };
+    };
+
+    await expect(create(Parent)).resolves.toEqual({ child: true });
+  });
+
+  it('can deallocate child resources on demand', async () => {
+    const spy = jest.fn();
+
+    const Child = async () => ({
+      value: { child: true },
+      destroy: spy,
+    });
+
+    const Parent = async (resource: ResourceContext) => {
+      const child = await resource.create(Child);
+      await resource.destroy(child);
+
+      return {
+        value: { parent: true },
+      };
+    };
+
+    await expect(create(Parent)).resolves.toEqual({ parent: true });
+    expect(spy).toHaveBeenCalled();
+  });
+
+  it('fails to destroy resources owned by someone else', async () => {
+    const test = await create(Test);
+
+    const Sneaky = async (resource: ResourceContext) => {
+      await resource.destroy(test);
+      return { value: {} };
+    };
+
+    await expect(create(Sneaky)).rejects.toThrow(/do not own/i);
+  });
+
+  it('binds create/destroy handlers to the class instance', async () => {
+    async function Allocator({ create, destroy }: ResourceContext) {
+      const test = await create(Test);
+      await destroy(test);
+
+      return { value: [] };
+    }
+
+    await expect(create(Allocator)).resolves.not.toThrow();
+  });
+});

package/src/allocation.ts

@@ -1,20 +1,28 @@
-import type Resource from './resource';
-import { resources, ownership } from './state';
+import { resources } from './state';
 import wrap from './proxy';
+import ResourceContext from './resource-context';
+import { ResourceFactory, ParametrizedResourceFactory } from './types';
 
 /** Provision a resource and return its external API. */
-export async function mount<Api extends object, InitArgs>(
-  Subtype: new () => Resource<Api, InitArgs>,
-  params: InitArgs,
-): Promise<Api> {
-  const resource = new Subtype();
-  await resource.enter(params);
+export async function create<
+  Controls extends object,
+  Args extends Array<unknown>,
+>(
+  provision:
+    | ParametrizedResourceFactory<Controls, Args>
+    | ResourceFactory<Controls>,
+  ...args: Args
+): Promise<Controls> {
+  const children: Set<object> = new Set();
+  const context = new ResourceContext(children);
+  const resource = await provision(context, ...args);
 
-  const api = resource.exports();
-  const { proxy, revoke } = wrap(api);
+  const controls = resource.value;
+  const { proxy, revoke } = wrap(controls);
 
   resources.set(proxy, {
     resource,
+    children,
     revoke,
   });
 
@@ -27,25 +35,24 @@ export async function mount<Api extends object, InitArgs>(
  *
  * @todo Add type marker to catch cases where the wrong object is unmounted.
  */
-export async function unmount(api: object) {
-  const entry = resources.get(api);
+export async function destroy(controls: object) {
+  const entry = resources.get(controls);
 
   if (entry) {
     // Instantly delete to prevent race conditions.
-    resources.delete(api);
+    resources.delete(controls);
 
     // Free all references.
     entry.revoke();
 
-    const children = ownership.get(entry.resource)!;
-    ownership.delete(entry.resource);
-
     // Recursively close out the children first...
-    const recursiveUnmounts = children.map((api) => unmount(api));
+    const recursiveUnmounts = Array.from(entry.children).map(destroy);
     const results = await Promise.allSettled(recursiveUnmounts);
 
     // Then close the parent.
-    await entry.resource.leave();
+    if (entry.resource.destroy) {
+      await entry.resource.destroy();
+    }
 
     // Fail loudly if any of the children couldn't be deallocated.
     results.forEach((result) => {

package/src/index.ts

@@ -1,3 +1,4 @@
-export { default as Resource, type ExternalControls } from './resource';
 export { default as bindContext } from './bind-context';
-export { mount, unmount } from './allocation';
+export { create, destroy } from './allocation';
+export type { Resource } from './types';
+export type { default as ResourceContext } from './resource-context';

package/src/resource-context.ts

@@ -0,0 +1,44 @@
+import { create, destroy } from './allocation';
+import { ResourceFactory, ParametrizedResourceFactory } from './types';
+
+/**
+ * An instance of this class is passed to resources as they're being
+ * provisioned. It allows them to provision other resources while keeping
+ * track of ownership and lifetimes.
+ */
+export default class ResourceContext {
+  #resources: Set<object>;
+
+  constructor(ownedResources: Set<object>) {
+    this.#resources = ownedResources;
+  }
+
+  /** Provision an owned resource and make sure it doesn't outlive us. */
+  public create = async <Controls extends object, Args extends Array<unknown>>(
+    factory:
+      | ParametrizedResourceFactory<Controls, Args>
+      | ResourceFactory<Controls>,
+    ...args: Args
+  ): Promise<Controls> => {
+    const controls = await create(factory, ...args);
+    this.#resources.add(controls);
+
+    return controls;
+  };
+
+  /**
+   * Tear down a resource. Happens automatically when resource owners are
+   * deallocated.
+   */
+  public destroy = async (resource: object) => {
+    if (!this.#resources.has(resource)) {
+      throw new Error('You do not own this resource.');
+    }
+
+    try {
+      await destroy(resource);
+    } finally {
+      this.#resources.delete(resource);
+    }
+  };
+}

package/src/state.ts

@@ -1,7 +1,10 @@
-import type Resource from './resource';
+import type { Resource } from './types';
 
 interface RevokableResource {
-  resource: Resource<object, unknown>;
+  resource: Resource<object>;
+
+  /** All the resources this resource personally allocated. */
+  children: Set<object>;
 
   /**
    * Destroys outer references to the API and frees the object for garbage
@@ -12,9 +15,3 @@ interface RevokableResource {
 
 /** Maps an external API back to the resource that created it. */
 export const resources = new WeakMap<object, RevokableResource>();
-
-/** Maps a resource to all the other resources it provisioned. */
-export const ownership = new WeakMap<
-  Resource<object, unknown>,
-  Array<object>
->();

package/src/types.ts

@@ -0,0 +1,26 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type ResourceContext from './resource-context';
+
+/**
+ * Represents an arbitrary stateful resource that is asynchronously provisioned
+ * and destroyed. Resources can own other resources, and destroying a parent
+ * first tears down the children.
+ */
+export interface ResourceFactory<Controls extends object> {
+  (resource: ResourceContext): Promise<Resource<Controls>>;
+}
+
+export interface ParametrizedResourceFactory<
+  Controls extends object,
+  Args extends Array<unknown>,
+> {
+  (resource: ResourceContext, ...args: Args): Promise<Resource<Controls>>;
+}
+
+export interface Resource<Value extends object> {
+  /** The resource value returned by `create(...)`. */
+  value: Value;
+
+  /** A hook that gets called when the resource is destroyed. */
+  destroy?(): Promise<unknown> | unknown;
+}

package/src/__tests__/resource.test.ts

@@ -1,67 +0,0 @@
-import Resource, { type ExternalControls } from '../resource';
-import { mount } from '../allocation';
-
-describe('Resource', () => {
-  class Test extends Resource<Record<string, never>> {
-    exports = () => ({});
-  }
-
-  it('implements default enter/leave methods', async () => {
-    const test = new Test();
-
-    await expect(test.enter()).resolves.not.toThrow();
-    await expect(test.leave()).resolves.not.toThrow();
-  });
-
-  it('can spawn children of its own', async () => {
-    class Child extends Resource<{ child: boolean }> {
-      exports = () => ({ child: true });
-    }
-
-    class Parent extends Resource<ExternalControls<Child>> {
-      exports = () => this.child;
-      child!: ExternalControls<Child>;
-
-      async enter() {
-        this.child = await this.allocate(Child, null);
-      }
-    }
-
-    await expect(mount(Parent, null)).resolves.toEqual({ child: true });
-  });
-
-  it('can deallocate child resources on demand', async () => {
-    const leave = jest.fn();
-
-    class Child extends Resource<{ child: boolean }> {
-      exports = () => ({ child: true });
-      leave = leave;
-    }
-
-    class Parent extends Resource<{ parent: boolean }> {
-      exports = () => ({ parent: true });
-      child!: ExternalControls<Child>;
-
-      async enter() {
-        const child = await this.allocate(Child, null);
-        await this.deallocate(child);
-      }
-    }
-
-    await expect(mount(Parent, null)).resolves.toEqual({ parent: true });
-    expect(leave).toHaveBeenCalled();
-  });
-
-  it('fails to destroy resources owned by someone else', async () => {
-    const test = await mount(Test, null);
-
-    class Sneaky extends Resource<string[]> {
-      exports = () => [];
-      async enter() {
-        await this.deallocate(test);
-      }
-    }
-
-    await expect(mount(Sneaky, null)).rejects.toThrow(/do not own/i);
-  });
-});

package/src/resource.ts

@@ -1,63 +0,0 @@
-import { mount, unmount } from './allocation';
-import { ownership } from './state';
-
-/**
- * Represents an arbitrary stateful resource that is asynchronously provisioned
- * and destroyed. Resources can own other resources, and destroying a parent
- * first tears down the children.
- */
-export default abstract class Resource<
-  ExternalApi extends object,
-  InitArgs = void,
-> {
-  #resources = new WeakSet<object>();
-  #children: Array<object> = [];
-
-  constructor() {
-    ownership.set(this, this.#children);
-  }
-
-  /** A hook that gets called when the resource is created. */
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  async enter(_params: InitArgs) {
-    return;
-  }
-
-  /** A hook that gets called when the resource is destroyed. */
-  async leave() {
-    return;
-  }
-
-  /** Provision an owned resource and make sure it doesn't outlive us. */
-  async allocate<Api extends object, Params>(
-    Child: new () => Resource<Api, Params>,
-    params: Params,
-  ): Promise<Api> {
-    const api = await mount(Child, params);
-    this.#resources.add(api);
-    this.#children.push(api);
-
-    return api;
-  }
-
-  /**
-   * Tear down a resource. Happens automatically when resource owners are
-   * deallocated.
-   */
-  async deallocate(api: object) {
-    if (!this.#resources.has(api)) {
-      throw new Error('You do not own this resource.');
-    }
-
-    return unmount(api);
-  }
-
-  /** Returns an external API to the parent resource. */
-  abstract exports(): ExternalApi;
-}
-
-/** The `exports` type for a resource. */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type ExternalControls<ArbitraryResource extends Resource<any, any>> =
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  ArbitraryResource extends Resource<infer Api, any> ? Api : never;