wardens 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -6,6 +6,23 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+## [0.5.0]
+
+### Changed
+
+- Wardens is now published with ESM (`type=module`). It should be backwards compatible.
+- Now `destroy(...)` throws if you pass an object that wasn't constructed with `create(...)`.
+
+### Fixed
+
+- If a resource fails while initializing, now all intermediate child resources are destroyed as well.
+- If a resource fails while being destroyed, now its child resources are destroyed as well.
+- Resources can no longer provision child resources after teardown. This closes a loophole where resources could escape destruction.
+
+### Added
+
+- New `ResourceHandle<T>` utility type represents the value returned when creating a resource.
+
 ## [0.4.1] - 2023-01-14
 
 ### Fixed
@@ -60,7 +77,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.4.1...HEAD
+[Unreleased]: https://github.com/PsychoLlama/wardens/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/PsychoLlama/wardens/compare/v0.4.1...v0.5.0
 [0.4.1]: https://github.com/PsychoLlama/wardens/compare/v0.4.0...v0.4.1
 [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

package/dist/wardens.cjs

@@ -0,0 +1 @@
+"use strict";var E=Object.defineProperty;var C=(t,e,r)=>e in t?E(t,e,{enumerable:!0,configurable:!0,writable:!0,value:r}):t[e]=r;var h=(t,e,r)=>(C(t,typeof e!="symbol"?e+"":e,r),r),g=(t,e,r)=>{if(!e.has(t))throw TypeError("Cannot "+r)};var a=(t,e,r)=>(g(t,e,"read from private field"),r?r.call(t):e.get(t)),f=(t,e,r)=>{if(e.has(t))throw TypeError("Cannot add the same private member more than once");e instanceof WeakSet?e.add(t):e.set(t,r)},y=(t,e,r,o)=>(g(t,e,"write to private field"),o?o.call(t,r):e.set(t,r),r);Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});function W(t){const e=new WeakMap;return new Proxy(t,{get(r,o){const s=Reflect.get(r,o,r);if(typeof s=="function"){if(e.has(s)===!1){const n=s.bind(r);Object.defineProperties(n,Object.getOwnPropertyDescriptors(s)),e.set(s,n)}return e.get(s)}return s},set(r,o,s){return Reflect.set(r,o,s,r)}})}const p=new WeakMap,S=new WeakSet;function O(t){return Proxy.revocable(t,{})}var l,i,u;class R{constructor(e,r){f(this,l,new WeakSet);f(this,i,void 0);f(this,u,void 0);h(this,"create",async(e,...r)=>{if(a(this,u).enforced)throw new Error("Cannot create new resources after teardown.");const o=await x(e,...r);return a(this,i).add(o),o});h(this,"destroy",async e=>{if(a(this,l).has(e))throw new Error("Resource already destroyed.");if(!a(this,i).has(e))throw new Error("You do not own this resource.");a(this,i).delete(e),a(this,l).add(e),await m(e)});y(this,i,e),y(this,u,r)}}l=new WeakMap,i=new WeakMap,u=new WeakMap;const x=async(t,...e)=>{const r={enforced:!1},o=new Set,s=new R(o,r);let n;try{n=await t(s,...e)}catch(v){const k=Array.from(o).reverse(),b=(await Promise.allSettled(k.map(d=>s.destroy(d)))).filter(d=>d.status==="rejected");throw b.length?P(b.map(d=>d.reason),{cause:v}):v}const c=n.value,{proxy:w,revoke:j}=O(c);return S.add(w),p.set(w,{curfew:r,resource:n,children:o,revoke:j}),w},m=async t=>{if(!S.has(t))throw new Error("Cannot destroy object. It is not a resource.");const e=p.get(t);if(e){p.delete(t),e.revoke();let r={status:"fulfilled",value:void 0};if(e.resource.destroy)try{await e.resource.destroy()}catch(c){r={status:"rejected",reason:c}}e.curfew.enforced=!0;const o=Array.from(e.children).reverse().map(m),s=await Promise.allSettled(o),n=[r].concat(s).filter(c=>c.status==="rejected");if(n.length)throw P(n.map(c=>c.reason))}},P=(t,e)=>t.length===1?t[0]:new B(t,e);class B extends Error{constructor(e,r){super("Some resources could not be destroyed. See the `failures` property for details.",r),this.failures=e}}exports.bindContext=W;exports.create=x;exports.destroy=m;

package/dist/wardens.js

@@ -0,0 +1,125 @@
+var P = Object.defineProperty;
+var j = (t, e, r) => e in t ? P(t, e, { enumerable: !0, configurable: !0, writable: !0, value: r }) : t[e] = r;
+var h = (t, e, r) => (j(t, typeof e != "symbol" ? e + "" : e, r), r), x = (t, e, r) => {
+  if (!e.has(t))
+    throw TypeError("Cannot " + r);
+};
+var a = (t, e, r) => (x(t, e, "read from private field"), r ? r.call(t) : e.get(t)), f = (t, e, r) => {
+  if (e.has(t))
+    throw TypeError("Cannot add the same private member more than once");
+  e instanceof WeakSet ? e.add(t) : e.set(t, r);
+}, y = (t, e, r, o) => (x(t, e, "write to private field"), o ? o.call(t, r) : e.set(t, r), r);
+function A(t) {
+  const e = /* @__PURE__ */ new WeakMap();
+  return new Proxy(t, {
+    get(r, o) {
+      const s = Reflect.get(r, o, r);
+      if (typeof s == "function") {
+        if (e.has(s) === !1) {
+          const n = s.bind(r);
+          Object.defineProperties(
+            n,
+            Object.getOwnPropertyDescriptors(s)
+          ), e.set(s, n);
+        }
+        return e.get(s);
+      }
+      return s;
+    },
+    set(r, o, s) {
+      return Reflect.set(r, o, s, r);
+    }
+  });
+}
+const p = /* @__PURE__ */ new WeakMap(), g = /* @__PURE__ */ new WeakSet();
+function W(t) {
+  return Proxy.revocable(t, {});
+}
+var l, i, u;
+class C {
+  constructor(e, r) {
+    f(this, l, /* @__PURE__ */ new WeakSet());
+    f(this, i, void 0);
+    f(this, u, void 0);
+    /** Provision an owned resource and make sure it doesn't outlive us. */
+    h(this, "create", async (e, ...r) => {
+      if (a(this, u).enforced)
+        throw new Error("Cannot create new resources after teardown.");
+      const o = await R(e, ...r);
+      return a(this, i).add(o), o;
+    });
+    /**
+     * Tear down a resource. Happens automatically when resource owners are
+     * deallocated.
+     */
+    h(this, "destroy", async (e) => {
+      if (a(this, l).has(e))
+        throw new Error("Resource already destroyed.");
+      if (!a(this, i).has(e))
+        throw new Error("You do not own this resource.");
+      a(this, i).delete(e), a(this, l).add(e), await S(e);
+    });
+    y(this, i, e), y(this, u, r);
+  }
+}
+l = new WeakMap(), i = new WeakMap(), u = new WeakMap();
+const R = async (t, ...e) => {
+  const r = { enforced: !1 }, o = /* @__PURE__ */ new Set(), s = new C(o, r);
+  let n;
+  try {
+    n = await t(s, ...e);
+  } catch (m) {
+    const E = Array.from(o).reverse(), v = (await Promise.allSettled(
+      E.map((d) => s.destroy(d))
+    )).filter(
+      (d) => d.status === "rejected"
+    );
+    throw v.length ? b(
+      v.map((d) => d.reason),
+      { cause: m }
+    ) : m;
+  }
+  const c = n.value, { proxy: w, revoke: k } = W(c);
+  return g.add(w), p.set(w, {
+    curfew: r,
+    resource: n,
+    children: o,
+    revoke: k
+  }), w;
+}, S = async (t) => {
+  if (!g.has(t))
+    throw new Error("Cannot destroy object. It is not a resource.");
+  const e = p.get(t);
+  if (e) {
+    p.delete(t), e.revoke();
+    let r = {
+      status: "fulfilled",
+      value: void 0
+    };
+    if (e.resource.destroy)
+      try {
+        await e.resource.destroy();
+      } catch (c) {
+        r = { status: "rejected", reason: c };
+      }
+    e.curfew.enforced = !0;
+    const o = Array.from(e.children).reverse().map(S), s = await Promise.allSettled(o), n = [r].concat(s).filter(
+      (c) => c.status === "rejected"
+    );
+    if (n.length)
+      throw b(n.map((c) => c.reason));
+  }
+}, b = (t, e) => t.length === 1 ? t[0] : new B(t, e);
+class B extends Error {
+  constructor(e, r) {
+    super(
+      "Some resources could not be destroyed. See the `failures` property for details.",
+      r
+    ), this.failures = e;
+  }
+}
+export {
+  A as bindContext,
+  R as create,
+  S as destroy
+};

package/package.json

@@ -1,13 +1,20 @@
 {
   "name": "wardens",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "A framework for resource management",
-  "main": "./dist/wardens.umd.js",
-  "module": "./dist/wardens.es.js",
+  "type": "module",
+  "main": "./dist/wardens.cjs",
+  "module": "./dist/wardens.js",
   "types": "./src/index.ts",
   "repository": "git@github.com:PsychoLlama/wardens.git",
   "author": "Jesse Gibson <JesseTheGibson@gmail.com>",
   "license": "MIT",
+  "exports": {
+    ".": {
+      "require": "./dist/wardens.cjs",
+      "import": "./dist/wardens.js"
+    }
+  },
   "files": [
     "dist",
     "src"
@@ -22,19 +29,14 @@
     "framework"
   ],
   "scripts": {
-    "prepare": "tsc && vite build",
+    "prepack": "tsc && vite build",
     "test": "./bin/run-tests",
     "test:lint": "eslint src --color",
-    "test:unit": "jest --color",
+    "test:unit": "vitest --color",
+    "test:types": "vitest typecheck --color",
     "test:fmt": "prettier --check src --color",
     "dev": "vite build --watch"
   },
-  "exports": {
-    ".": {
-      "require": "./dist/wardens.umd.js",
-      "import": "./dist/wardens.mjs"
-    }
-  },
   "husky": {
     "hooks": {
       "pre-commit": "lint-staged"
@@ -60,9 +62,6 @@
         "files": [
           "./**/__tests__/*.ts{x,}"
         ],
-        "env": {
-          "jest": true
-        },
         "rules": {
           "@typescript-eslint/no-explicit-any": "off"
         }
@@ -79,20 +78,15 @@
       "no-prototype-builtins": "off"
     }
   },
-  "jest": {
-    "preset": "ts-jest"
-  },
   "devDependencies": {
-    "@types/jest": "29.2.5",
-    "@typescript-eslint/eslint-plugin": "5.48.1",
-    "@typescript-eslint/parser": "5.48.1",
-    "eslint": "8.31.0",
+    "@typescript-eslint/eslint-plugin": "6.3.0",
+    "@typescript-eslint/parser": "6.3.0",
+    "eslint": "8.47.0",
     "husky": "8.0.3",
-    "jest": "29.3.1",
-    "lint-staged": "13.1.0",
-    "prettier": "2.8.3",
-    "ts-jest": "29.0.5",
-    "typescript": "4.9.4",
-    "vite": "4.0.4"
+    "lint-staged": "13.2.3",
+    "prettier": "2.8.8",
+    "typescript": "5.1.6",
+    "vite": "4.4.9",
+    "vitest": "^0.34.0"
   }
 }

package/src/__tests__/allocation.test.ts

@@ -1,11 +1,12 @@
 import type ResourceContext from '../resource-context';
 import { create, destroy } from '../allocation';
+import bindContext from '../bind-context';
 
 describe('allocation', () => {
   describe('create', () => {
     it('allocates the resource', async () => {
       const config = { test: 'init-args' };
-      const Test = jest.fn(
+      const Test = vi.fn(
         async (_resource: ResourceContext, config: { test: string }) => ({
           value: config,
         }),
@@ -14,11 +15,50 @@ describe('allocation', () => {
       await expect(create(Test, config)).resolves.toEqual(config);
       expect(Test).toHaveBeenCalledWith(expect.anything(), config);
     });
+
+    describe('after initialization failure', () => {
+      it('destroys child resources in reverse order', async () => {
+        const spy = vi.fn();
+        const First = async () => ({ value: [], destroy: () => spy('1st') });
+        const Second = async () => ({ value: [], destroy: () => spy('2nd') });
+
+        const Parent = async (resource: ResourceContext) => {
+          await resource.create(First);
+          await resource.create(Second);
+          throw new Error('Testing resource initialization errors');
+        };
+
+        await expect(create(Parent)).rejects.toThrow();
+        expect(spy.mock.calls).toEqual([['2nd'], ['1st']]);
+      });
+
+      it('continues even if the children cannot be destroyed', async () => {
+        const parentError = new Error('Testing parent resource aborts');
+        const childError = new Error('Testing child resource aborts');
+        const Child = async () => ({
+          value: [],
+          destroy() {
+            throw childError;
+          },
+        });
+
+        const Parent = async (resource: ResourceContext) => {
+          await resource.create(Child);
+          await resource.create(Child);
+          throw parentError;
+        };
+
+        await expect(create(Parent)).rejects.toMatchObject({
+          cause: parentError,
+          failures: [childError, childError],
+        });
+      });
+    });
   });
 
   describe('destroy', () => {
     it('deallocates the resource', async () => {
-      const spy = jest.fn<void, []>();
+      const spy = vi.fn<[], void>();
       const Test = async () => ({
         value: {},
         destroy: spy,
@@ -31,6 +71,12 @@ describe('allocation', () => {
       expect(spy).toHaveBeenCalled();
     });
 
+    it('throws an error if the object is not a resource', async () => {
+      await expect(destroy({})).rejects.toThrow(
+        'Cannot destroy object. It is not a resource.',
+      );
+    });
+
     it('survives if the resource is already deallocated', async () => {
       const Test = async () => ({ value: [] });
 
@@ -41,7 +87,7 @@ describe('allocation', () => {
     });
 
     it('automatically unmounts all children', async () => {
-      const spy = jest.fn();
+      const spy = vi.fn();
       const Child = async () => ({ value: [], destroy: spy });
       async function Parent(resource: ResourceContext) {
         await resource.create(Child);
@@ -71,5 +117,120 @@ describe('allocation', () => {
       const parent = await create(Parent);
       await expect(destroy(parent)).rejects.toThrow(error);
     });
+
+    it('destroys child resources in reverse order', async () => {
+      const spy = vi.fn();
+      const First = async () => ({ value: [], destroy: () => spy('1st') });
+      const Second = async () => ({ value: [], destroy: () => spy('2nd') });
+
+      const Parent = async (resource: ResourceContext) => {
+        await resource.create(First);
+        await resource.create(Second);
+        return { value: [] };
+      };
+
+      const parent = await create(Parent);
+      await destroy(parent);
+
+      expect(spy.mock.calls).toEqual([['2nd'], ['1st']]);
+    });
+
+    it('reports if multiple resources could not be destroyed', async () => {
+      const childError = new Error('Testing child resource aborts');
+      const Child = async () => ({
+        value: [],
+        destroy() {
+          throw childError;
+        },
+      });
+
+      const Parent = async (resource: ResourceContext) => {
+        await resource.create(Child);
+        await resource.create(Child);
+        return { value: [] };
+      };
+
+      const parent = await create(Parent);
+      await expect(destroy(parent)).rejects.toMatchObject({
+        failures: [childError, childError],
+      });
+    });
+
+    it('ensures child resources outlive their consumers', async () => {
+      const Child = async () => ({ value: [1] });
+      const Parent = async (resource: ResourceContext) => {
+        const child = await resource.create(Child);
+        return {
+          value: [],
+          destroy() {
+            // The `child` resource must still be usable here.
+            expect(child).toHaveLength(1);
+          },
+        };
+      };
+
+      const parent = await create(Parent);
+      await destroy(parent);
+    });
+
+    it('destroys child resources even if the parent fails to close', async () => {
+      const spy = vi.fn();
+      const Child = async () => ({ value: [], destroy: spy });
+      const Parent = async (resource: ResourceContext) => {
+        await resource.create(Child);
+        return {
+          value: [],
+          destroy() {
+            throw new Error('Testing parent teardown errors');
+          },
+        };
+      };
+
+      const parent = await create(Parent);
+      await expect(destroy(parent)).rejects.toThrow();
+      expect(spy).toHaveBeenCalled();
+    });
+
+    it('aggregates errors if the child resource fails to close', async () => {
+      const parentError = new Error('Testing parent resource aborts');
+      const childError = new Error('Testing child resource aborts');
+
+      const Child = async () => ({
+        value: [],
+        destroy() {
+          throw childError;
+        },
+      });
+
+      const Parent = async (resource: ResourceContext) => {
+        await resource.create(Child);
+        return {
+          value: [],
+          destroy() {
+            throw parentError;
+          },
+        };
+      };
+
+      const parent = await create(Parent);
+      await expect(destroy(parent)).rejects.toMatchObject({
+        failures: [parentError, childError],
+      });
+    });
+
+    it('guards against creating new resources after teardown', async () => {
+      const Child = async () => ({ value: [] });
+      const Parent = async (resource: ResourceContext) => ({
+        value: bindContext(resource),
+      });
+
+      const parent = await create(Parent);
+      const { create: resourceCreate } = parent;
+      await destroy(parent);
+
+      await expect(resourceCreate(Child)).rejects.toThrow(
+        /cannot create.*after teardown/i,
+      );
+    });
   });
 });

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

@@ -36,7 +36,7 @@ describe('Method rebinding', () => {
   });
 
   it('copies extended function properties', () => {
-    const proxy = bind({ mock: jest.fn() });
+    const proxy = bind({ mock: vi.fn() });
 
     // Mocks use state held on the function itself. This must be added to the
     // bound functions as well.

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

@@ -19,7 +19,7 @@ describe('ResourceContext', () => {
   });
 
   it('can deallocate child resources on demand', async () => {
-    const spy = jest.fn();
+    const spy = vi.fn();
 
     const Child = async () => ({
       value: { child: true },
@@ -60,4 +60,16 @@ describe('ResourceContext', () => {
 
     await expect(create(Allocator)).resolves.not.toThrow();
   });
+
+  it('indicates if a resource was already destroyed', async () => {
+    async function Allocator(resource: ResourceContext) {
+      const test = await resource.create(Test);
+      await resource.destroy(test);
+      await resource.destroy(test);
+
+      return { value: [] };
+    }
+
+    await expect(create(Allocator)).rejects.toThrow(/already destroyed/i);
+  });
 });

package/src/__tests__/types.test-d.ts

@@ -0,0 +1,19 @@
+import { create, ResourceHandle } from '../';
+
+describe('Utility types', () => {
+  describe('ResourceHandle', () => {
+    it('infers the correct type', async () => {
+      async function Test() {
+        return {
+          value: { hello: 'world' },
+        };
+      }
+
+      const test = await create(Test);
+
+      expectTypeOf(test).toEqualTypeOf<ResourceHandle<typeof Test>>({
+        hello: 'world',
+      });
+    });
+  });
+});

package/src/allocation.ts

@@ -1,10 +1,10 @@
-import { resources } from './state';
+import { resources, constructed } 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 create<
+export const create = async <
   Controls extends object,
   Args extends Array<unknown>,
 >(
@@ -12,53 +12,115 @@ export async function create<
     | ParametrizedResourceFactory<Controls, Args>
     | ResourceFactory<Controls>,
   ...args: Args
-): Promise<Controls> {
+): Promise<Controls> => {
+  const curfew = { enforced: false };
   const children: Set<object> = new Set();
-  const context = new ResourceContext(children);
-  const resource = await provision(context, ...args);
+  const context = new ResourceContext(children, curfew);
+  let resource: Awaited<ReturnType<typeof provision>>;
+
+  try {
+    resource = await provision(context, ...args);
+  } catch (error) {
+    // Resource could not be created. Clean up the intermediate resources.
+    const orphans = Array.from(children).reverse();
+    const deallocations = await Promise.allSettled(
+      orphans.map((orphan) => context.destroy(orphan)),
+    );
+
+    const failures = deallocations.filter(
+      (result): result is PromiseRejectedResult => result.status === 'rejected',
+    );
+
+    // The intermediate resources could not be destroyed.
+    if (failures.length) {
+      throw reduceToSingleError(
+        failures.map((failure) => failure.reason),
+        { cause: error },
+      );
+    }
+
+    throw error;
+  }
 
   const controls = resource.value;
   const { proxy, revoke } = wrap(controls);
 
+  constructed.add(proxy);
   resources.set(proxy, {
+    curfew,
     resource,
     children,
     revoke,
   });
 
   return proxy;
-}
+};
 
 /**
  * Tear down the resource and all its children, permanently destroying the
  * reference.
- *
- * @todo Add type marker to catch cases where the wrong object is unmounted.
  */
-export async function destroy(controls: object) {
-  const entry = resources.get(controls);
+export const destroy = async (handle: object) => {
+  if (!constructed.has(handle)) {
+    throw new Error('Cannot destroy object. It is not a resource.');
+  }
+
+  const entry = resources.get(handle);
 
   if (entry) {
     // Instantly delete to prevent race conditions.
-    resources.delete(controls);
+    resources.delete(handle);
 
     // Free all references.
     entry.revoke();
 
-    // Recursively close out the children first...
-    const recursiveUnmounts = Array.from(entry.children).map(destroy);
-    const results = await Promise.allSettled(recursiveUnmounts);
+    let parentDeallocation: PromiseSettledResult<void> = {
+      status: 'fulfilled',
+      value: undefined,
+    };
 
-    // Then close the parent.
+    // Try to close the parent resource...
     if (entry.resource.destroy) {
-      await entry.resource.destroy();
+      try {
+        await entry.resource.destroy();
+      } catch (error) {
+        parentDeallocation = { status: 'rejected', reason: error };
+      }
     }
 
+    // The resource is closed. Prevent new child resources before we start
+    // closing down the children.
+    entry.curfew.enforced = true;
+
+    // Recursively close out the children...
+    const recursiveUnmounts = Array.from(entry.children).reverse().map(destroy);
+    const deallocations = await Promise.allSettled(recursiveUnmounts);
+    const failures = [parentDeallocation]
+      .concat(deallocations)
+      .filter(
+        (result): result is PromiseRejectedResult =>
+          result.status === 'rejected',
+      );
+
     // Fail loudly if any of the children couldn't be deallocated.
-    results.forEach((result) => {
-      if (result.status === 'rejected') {
-        throw result.reason;
-      }
-    });
+    if (failures.length) {
+      throw reduceToSingleError(failures.map((failure) => failure.reason));
+    }
+  }
+};
+
+const reduceToSingleError = (errors: Array<Error>, options?: ErrorOptions) => {
+  return errors.length === 1
+    ? errors[0]
+    : new BulkDestroyError(errors, options);
+};
+
+/** Happens when 2 or more child resources cannot be destroyed. */
+class BulkDestroyError extends Error {
+  constructor(public failures: Array<unknown>, options?: ErrorOptions) {
+    super(
+      'Some resources could not be destroyed. See the `failures` property for details.',
+      options,
+    );
   }
 }

package/src/index.ts

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

package/src/resource-context.ts

@@ -1,4 +1,5 @@
 import { create, destroy } from './allocation';
+import { RevokableResource } from './state';
 import { ResourceFactory, ParametrizedResourceFactory } from './types';
 
 /**
@@ -7,10 +8,16 @@ import { ResourceFactory, ParametrizedResourceFactory } from './types';
  * track of ownership and lifetimes.
  */
 export default class ResourceContext {
+  #destroyed = new WeakSet<object>();
   #resources: Set<object>;
+  #freeze: RevokableResource['curfew'];
 
-  constructor(ownedResources: Set<object>) {
+  constructor(
+    ownedResources: Set<object>,
+    freeze: RevokableResource['curfew'],
+  ) {
     this.#resources = ownedResources;
+    this.#freeze = freeze;
   }
 
   /** Provision an owned resource and make sure it doesn't outlive us. */
@@ -20,6 +27,10 @@ export default class ResourceContext {
       | ResourceFactory<Controls>,
     ...args: Args
   ): Promise<Controls> => {
+    if (this.#freeze.enforced) {
+      throw new Error('Cannot create new resources after teardown.');
+    }
+
     const controls = await create(factory, ...args);
     this.#resources.add(controls);
 
@@ -31,14 +42,16 @@ export default class ResourceContext {
    * deallocated.
    */
   public destroy = async (resource: object) => {
+    if (this.#destroyed.has(resource)) {
+      throw new Error('Resource already destroyed.');
+    }
+
     if (!this.#resources.has(resource)) {
       throw new Error('You do not own this resource.');
     }
 
-    try {
-      await destroy(resource);
-    } finally {
-      this.#resources.delete(resource);
-    }
+    this.#resources.delete(resource);
+    this.#destroyed.add(resource);
+    await destroy(resource);
   };
 }

package/src/state.ts

@@ -1,6 +1,6 @@
 import type { Resource } from './types';
 
-interface RevokableResource {
+export interface RevokableResource {
   resource: Resource<object>;
 
   /** All the resources this resource personally allocated. */
@@ -11,7 +11,20 @@ interface RevokableResource {
    * collection.
    */
   revoke(): void;
+
+  /**
+   * A flag preventing the resource context from provisioning new child
+   * resources after the parent is destroyed.
+   */
+  curfew: { enforced: boolean };
 }
 
 /** Maps an external API back to the resource that created it. */
 export const resources = new WeakMap<object, RevokableResource>();
+
+/**
+ * Identifies if an object is a Wardens resource. Carries no metadata and
+ * objects are never deleted. This is separate from `resources` to avoid
+ * retaining associated objects in memory.
+ */
+export const constructed = new WeakSet<object>();

package/src/types.ts

@@ -1,4 +1,3 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
 import type ResourceContext from './resource-context';
 
 /**
@@ -6,15 +5,15 @@ import type ResourceContext from './resource-context';
  * 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 ResourceFactory<Value extends object> {
+  (resource: ResourceContext): Promise<Resource<Value>>;
 }
 
 export interface ParametrizedResourceFactory<
-  Controls extends object,
+  Value extends object,
   Args extends Array<unknown>,
 > {
-  (resource: ResourceContext, ...args: Args): Promise<Resource<Controls>>;
+  (resource: ResourceContext, ...args: Args): Promise<Resource<Value>>;
 }
 
 export interface Resource<Value extends object> {
@@ -24,3 +23,8 @@ export interface Resource<Value extends object> {
   /** A hook that gets called when the resource is destroyed. */
   destroy?(): Promise<unknown> | unknown;
 }
+
+/** The `value` type returned when creating a resource. */
+export type ResourceHandle<Factory extends ResourceFactory<object>> = Awaited<
+  ReturnType<Factory>
+>['value'];

package/dist/wardens.mjs

@@ -1,87 +0,0 @@
-var p = Object.defineProperty;
-var x = (n, e, t) => e in n ? p(n, e, { enumerable: !0, configurable: !0, writable: !0, value: t }) : n[e] = t;
-var a = (n, e, t) => (x(n, typeof e != "symbol" ? e + "" : e, t), t), f = (n, e, t) => {
-  if (!e.has(n))
-    throw TypeError("Cannot " + t);
-};
-var i = (n, e, t) => (f(n, e, "read from private field"), t ? t.call(n) : e.get(n)), y = (n, e, t) => {
-  if (e.has(n))
-    throw TypeError("Cannot add the same private member more than once");
-  e instanceof WeakSet ? e.add(n) : e.set(n, t);
-}, l = (n, e, t, o) => (f(n, e, "write to private field"), o ? o.call(n, t) : e.set(n, t), t);
-function g(n) {
-  const e = /* @__PURE__ */ new WeakMap();
-  return new Proxy(n, {
-    get(t, o) {
-      const r = Reflect.get(t, o, t);
-      if (typeof r == "function") {
-        if (e.has(r) === !1) {
-          const c = r.bind(t);
-          Object.defineProperties(
-            c,
-            Object.getOwnPropertyDescriptors(r)
-          ), e.set(r, c);
-        }
-        return e.get(r);
-      }
-      return r;
-    },
-    set(t, o, r) {
-      return Reflect.set(t, o, r, t);
-    }
-  });
-}
-const u = /* @__PURE__ */ new WeakMap();
-function m(n) {
-  return Proxy.revocable(n, {});
-}
-var s;
-class v {
-  constructor(e) {
-    y(this, s, void 0);
-    /** Provision an owned resource and make sure it doesn't outlive us. */
-    a(this, "create", async (e, ...t) => {
-      const o = await P(e, ...t);
-      return i(this, s).add(o), o;
-    });
-    /**
-     * Tear down a resource. Happens automatically when resource owners are
-     * deallocated.
-     */
-    a(this, "destroy", async (e) => {
-      if (!i(this, s).has(e))
-        throw new Error("You do not own this resource.");
-      try {
-        await w(e);
-      } finally {
-        i(this, s).delete(e);
-      }
-    });
-    l(this, s, e);
-  }
-}
-s = new WeakMap();
-async function P(n, ...e) {
-  const t = /* @__PURE__ */ new Set(), o = new v(t), r = await n(o, ...e), c = r.value, { proxy: d, revoke: h } = m(c);
-  return u.set(d, {
-    resource: r,
-    children: t,
-    revoke: h
-  }), d;
-}
-async function w(n) {
-  const e = u.get(n);
-  if (e) {
-    u.delete(n), e.revoke();
-    const t = Array.from(e.children).map(w), o = await Promise.allSettled(t);
-    e.resource.destroy && await e.resource.destroy(), o.forEach((r) => {
-      if (r.status === "rejected")
-        throw r.reason;
-    });
-  }
-}
-export {
-  g as bindContext,
-  P as create,
-  w as destroy
-};

package/dist/wardens.umd.js

@@ -1 +0,0 @@
-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 l=(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,d)=>(p(e,t,"write to private field"),d?d.call(e,n):t.set(e,n),n);(function(e,t){typeof exports=="object"&&typeof module<"u"?t(exports):typeof define=="function"&&define.amd?define(["exports"],t):(e=typeof globalThis<"u"?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 u=r.bind(s);Object.defineProperties(u,Object.getOwnPropertyDescriptors(r)),o.set(r,u)}return o.get(r)}return r},set(s,i,r){return Reflect.set(s,i,r,s)}})}const n=new WeakMap;function d(c){return Proxy.revocable(c,{})}class x{constructor(o){b(this,a,void 0);l(this,"create",async(o,...s)=>{const i=await h(o,...s);return f(this,a).add(i),i});l(this,"destroy",async o=>{if(!f(this,a).has(o))throw new Error("You do not own this resource.");try{await y(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 x(s),r=await c(i,...o),u=r.value,{proxy:w,revoke:v}=d(u);return n.set(w,{resource:r,children:s,revoke:v}),w}async function y(c){const o=n.get(c);if(o){n.delete(c),o.revoke();const s=Array.from(o.children).map(y),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=y,Object.defineProperty(e,Symbol.toStringTag,{value:"Module"})});