wardens 0.6.0-rc.0 → 0.6.0-rc.2

package/CHANGELOG.md

@@ -12,7 +12,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ### Changed
 
-- Renamed public type `ResourceContext` to `ResourceControls`.
+- Renamed public type `ResourceContext` to `ResourceScope`.
+- `destroy(...)` is no longer allowed to destroy child resources, only roots.
 
 ## [0.5.1] - 2023-08-12
 

package/README.md

@@ -30,7 +30,7 @@ Now define a pool that creates and manages workers:
 
 ```typescript
 async function WorkerPool(
-  { create }: ResourceControls,
+  { create }: ResourceScope,
   config: { poolSize: number },
 ) {
   const promises = Array(config.poolSize).fill(Worker).map(create);

package/dist/wardens.cjs

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

package/dist/wardens.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wardens",
-  "version": "0.6.0-rc.0",
+  "version": "0.6.0-rc.2",
   "description": "A framework for resource management",
   "type": "module",
   "main": "./dist/wardens.cjs",
@@ -79,13 +79,13 @@
     }
   },
   "devDependencies": {
-    "@typescript-eslint/eslint-plugin": "6.4.0",
-    "@typescript-eslint/parser": "6.4.0",
-    "eslint": "8.47.0",
+    "@typescript-eslint/eslint-plugin": "6.4.1",
+    "@typescript-eslint/parser": "6.4.1",
+    "eslint": "8.48.0",
     "husky": "8.0.3",
-    "lint-staged": "14.0.0",
+    "lint-staged": "14.0.1",
     "prettier": "2.8.8",
-    "typescript": "5.1.6",
+    "typescript": "5.2.2",
     "vite": "4.4.9",
     "vitest": "^0.34.0"
   }

package/src/__tests__/{resource-api.test.ts → resource-scope.test.ts}

@@ -1,8 +1,8 @@
-import ResourceControls from '../resource-controls';
+import ResourceScope from '../resource-scope';
 import { create } from '../';
 import { createContext } from '../inherited-context';
 
-describe('ResourceControls', () => {
+describe('ResourceScope', () => {
   async function Test() {
     return { value: {} };
   }
@@ -12,7 +12,7 @@ describe('ResourceControls', () => {
       value: { child: true },
     });
 
-    const Parent = async (resource: ResourceControls) => {
+    const Parent = async (resource: ResourceScope) => {
       return { value: await resource.create(Child) };
     };
 
@@ -27,7 +27,7 @@ describe('ResourceControls', () => {
       destroy: spy,
     });
 
-    const Parent = async (resource: ResourceControls) => {
+    const Parent = async (resource: ResourceScope) => {
       const child = await resource.create(Child);
       await resource.destroy(child);
 
@@ -43,7 +43,7 @@ describe('ResourceControls', () => {
   it('fails to destroy resources owned by someone else', async () => {
     const test = await create(Test);
 
-    const Sneaky = async (resource: ResourceControls) => {
+    const Sneaky = async (resource: ResourceScope) => {
       await resource.destroy(test);
       return { value: {} };
     };
@@ -52,7 +52,7 @@ describe('ResourceControls', () => {
   });
 
   it('binds create/destroy handlers to the class instance', async () => {
-    async function Allocator({ create, destroy }: ResourceControls) {
+    async function Allocator({ create, destroy }: ResourceScope) {
       const test = await create(Test);
       await destroy(test);
 
@@ -63,7 +63,7 @@ describe('ResourceControls', () => {
   });
 
   it('indicates if a resource was already destroyed', async () => {
-    async function Allocator(resource: ResourceControls) {
+    async function Allocator(resource: ResourceScope) {
       const test = await resource.create(Test);
       await resource.destroy(test);
       await resource.destroy(test);
@@ -77,7 +77,7 @@ describe('ResourceControls', () => {
   it('can set and retrieve context', async () => {
     const SharedValue = createContext(() => 'none');
 
-    const Test = async (resource: ResourceControls) => {
+    const Test = async (resource: ResourceScope) => {
       expect(resource.getContext(SharedValue)).toBe('none');
 
       resource.setContext(SharedValue, 'saved');
@@ -92,14 +92,26 @@ describe('ResourceControls', () => {
     await expect(create(Test)).resolves.toEqual([]);
   });
 
+  it('returns the new context value', async () => {
+    const SharedValue = createContext(() => 'none');
+
+    const Test = async (resource: ResourceScope) => {
+      return {
+        value: { value: resource.setContext(SharedValue, 'returned') },
+      };
+    };
+
+    await expect(create(Test)).resolves.toEqual({ value: 'returned' });
+  });
+
   it('passes context to child resources', async () => {
     const SharedValue = createContext<null | string>(() => null);
 
-    const Child = async (ctx: ResourceControls) => ({
+    const Child = async (ctx: ResourceScope) => ({
       value: { content: ctx.getContext(SharedValue) },
     });
 
-    const Parent = async (resource: ResourceControls) => {
+    const Parent = async (resource: ResourceScope) => {
       resource.setContext(SharedValue, 'inherited');
       return { value: await resource.create(Child) };
     };
@@ -109,7 +121,7 @@ describe('ResourceControls', () => {
 
   it('can override context without affecting the parent', async () => {
     const Message = createContext<null | string>(() => null);
-    const Child = async (resource: ResourceControls) => {
+    const Child = async (resource: ResourceScope) => {
       // This should *NOT* affect the parent context.
       resource.setContext(Message, 'child context');
 
@@ -118,7 +130,7 @@ describe('ResourceControls', () => {
       };
     };
 
-    const Parent = async (resource: ResourceControls) => {
+    const Parent = async (resource: ResourceScope) => {
       resource.setContext(Message, 'parent context');
       const child = await resource.create(Child);
 
@@ -140,7 +152,7 @@ describe('ResourceControls', () => {
 
   it('allows two siblings to have different context values', async () => {
     const Message = createContext<null | string>(() => null);
-    const Child = async (resource: ResourceControls, msg: string) => {
+    const Child = async (resource: ResourceScope, msg: string) => {
       resource.setContext(Message, msg);
 
       return {
@@ -148,7 +160,7 @@ describe('ResourceControls', () => {
       };
     };
 
-    const Parent = async (resource: ResourceControls) => {
+    const Parent = async (resource: ResourceScope) => {
       resource.setContext(Message, 'parent context');
 
       return {
@@ -166,11 +178,11 @@ describe('ResourceControls', () => {
 
   it('provides a live view of the current value, not just a snapshot', async () => {
     const Message = createContext(() => 'default');
-    const Child = async (resource: ResourceControls) => ({
+    const Child = async (resource: ResourceScope) => ({
       value: { getMessage: () => resource.getContext(Message) },
     });
 
-    const Parent = async (resource: ResourceControls) => ({
+    const Parent = async (resource: ResourceScope) => ({
       value: {
         setMessage: (msg: string) => resource.setContext(Message, msg),
         child: await resource.create(Child),

package/src/__tests__/root-lifecycle.test.ts

@@ -1,5 +1,5 @@
-import type ResourceControls from '../resource-controls';
-import { create, destroy } from '../root-lifecycle';
+import type ResourceScope from '../resource-scope';
+import { create, destroy } from '../';
 import bindContext from '../bind-context';
 
 describe('roots', () => {
@@ -7,7 +7,7 @@ describe('roots', () => {
     it('allocates the resource', async () => {
       const config = { test: 'init-args' };
       const Test = vi.fn(
-        async (_resource: ResourceControls, config: { test: string }) => ({
+        async (_resource: ResourceScope, config: { test: string }) => ({
           value: config,
         }),
       );
@@ -22,7 +22,7 @@ describe('roots', () => {
         const First = async () => ({ value: [], destroy: () => spy('1st') });
         const Second = async () => ({ value: [], destroy: () => spy('2nd') });
 
-        const Parent = async (resource: ResourceControls) => {
+        const Parent = async (resource: ResourceScope) => {
           await resource.create(First);
           await resource.create(Second);
           throw new Error('Testing resource initialization errors');
@@ -42,7 +42,7 @@ describe('roots', () => {
           },
         });
 
-        const Parent = async (resource: ResourceControls) => {
+        const Parent = async (resource: ResourceScope) => {
           await resource.create(Child);
           await resource.create(Child);
           throw parentError;
@@ -89,7 +89,7 @@ describe('roots', () => {
     it('automatically unmounts all children', async () => {
       const spy = vi.fn();
       const Child = async () => ({ value: [], destroy: spy });
-      async function Parent(resource: ResourceControls) {
+      async function Parent(resource: ResourceScope) {
         await resource.create(Child);
         return { value: [] };
       }
@@ -109,7 +109,7 @@ describe('roots', () => {
         },
       });
 
-      const Parent = async (resource: ResourceControls) => {
+      const Parent = async (resource: ResourceScope) => {
         await resource.create(Child);
         return { value: [] };
       };
@@ -123,7 +123,7 @@ describe('roots', () => {
       const First = async () => ({ value: [], destroy: () => spy('1st') });
       const Second = async () => ({ value: [], destroy: () => spy('2nd') });
 
-      const Parent = async (resource: ResourceControls) => {
+      const Parent = async (resource: ResourceScope) => {
         await resource.create(First);
         await resource.create(Second);
         return { value: [] };
@@ -144,7 +144,7 @@ describe('roots', () => {
         },
       });
 
-      const Parent = async (resource: ResourceControls) => {
+      const Parent = async (resource: ResourceScope) => {
         await resource.create(Child);
         await resource.create(Child);
         return { value: [] };
@@ -158,7 +158,7 @@ describe('roots', () => {
 
     it('ensures child resources outlive their consumers', async () => {
       const Child = async () => ({ value: [1] });
-      const Parent = async (resource: ResourceControls) => {
+      const Parent = async (resource: ResourceScope) => {
         const child = await resource.create(Child);
         return {
           value: [],
@@ -176,7 +176,7 @@ describe('roots', () => {
     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: ResourceControls) => {
+      const Parent = async (resource: ResourceScope) => {
         await resource.create(Child);
         return {
           value: [],
@@ -202,7 +202,7 @@ describe('roots', () => {
         },
       });
 
-      const Parent = async (resource: ResourceControls) => {
+      const Parent = async (resource: ResourceScope) => {
         await resource.create(Child);
         return {
           value: [],
@@ -220,7 +220,7 @@ describe('roots', () => {
 
     it('guards against creating new resources after teardown', async () => {
       const Child = async () => ({ value: [] });
-      const Parent = async (resource: ResourceControls) => ({
+      const Parent = async (resource: ResourceScope) => ({
         value: bindContext(resource),
       });
 
@@ -232,5 +232,18 @@ describe('roots', () => {
         /cannot create.*after teardown/i,
       );
     });
+
+    it('refuses to destroy non-root resources', async () => {
+      const Child = async () => ({ value: [] });
+      const Parent = async ({ create }: ResourceScope) => ({
+        value: { child: await create(Child) },
+      });
+
+      const { child } = await create(Parent);
+
+      await expect(destroy(child)).rejects.toThrow(
+        /cannot destroy child resource/i,
+      );
+    });
   });
 });

package/src/__tests__/roots.test.ts

@@ -1,5 +1,5 @@
-import type ResourceControls from '../resource-controls';
-import { create, destroy } from '../root-lifecycle';
+import type ResourceScope from '../resource-scope';
+import { create, destroy } from '../';
 import bindContext from '../bind-context';
 
 describe('roots', () => {
@@ -7,7 +7,7 @@ describe('roots', () => {
     it('allocates the resource', async () => {
       const config = { test: 'init-args' };
       const Test = vi.fn(
-        async (_resource: ResourceControls, config: { test: string }) => ({
+        async (_resource: ResourceScope, config: { test: string }) => ({
           value: config,
         }),
       );
@@ -22,7 +22,7 @@ describe('roots', () => {
         const First = async () => ({ value: [], destroy: () => spy('1st') });
         const Second = async () => ({ value: [], destroy: () => spy('2nd') });
 
-        const Parent = async (resource: ResourceControls) => {
+        const Parent = async (resource: ResourceScope) => {
           await resource.create(First);
           await resource.create(Second);
           throw new Error('Testing resource initialization errors');
@@ -42,7 +42,7 @@ describe('roots', () => {
           },
         });
 
-        const Parent = async (resource: ResourceControls) => {
+        const Parent = async (resource: ResourceScope) => {
           await resource.create(Child);
           await resource.create(Child);
           throw parentError;
@@ -89,7 +89,7 @@ describe('roots', () => {
     it('automatically unmounts all children', async () => {
       const spy = vi.fn();
       const Child = async () => ({ value: [], destroy: spy });
-      async function Parent(resource: ResourceControls) {
+      async function Parent(resource: ResourceScope) {
         await resource.create(Child);
         return { value: [] };
       }
@@ -109,7 +109,7 @@ describe('roots', () => {
         },
       });
 
-      const Parent = async (resource: ResourceControls) => {
+      const Parent = async (resource: ResourceScope) => {
         await resource.create(Child);
         return { value: [] };
       };
@@ -123,7 +123,7 @@ describe('roots', () => {
       const First = async () => ({ value: [], destroy: () => spy('1st') });
       const Second = async () => ({ value: [], destroy: () => spy('2nd') });
 
-      const Parent = async (resource: ResourceControls) => {
+      const Parent = async (resource: ResourceScope) => {
         await resource.create(First);
         await resource.create(Second);
         return { value: [] };
@@ -144,7 +144,7 @@ describe('roots', () => {
         },
       });
 
-      const Parent = async (resource: ResourceControls) => {
+      const Parent = async (resource: ResourceScope) => {
         await resource.create(Child);
         await resource.create(Child);
         return { value: [] };
@@ -158,7 +158,7 @@ describe('roots', () => {
 
     it('ensures child resources outlive their consumers', async () => {
       const Child = async () => ({ value: [1] });
-      const Parent = async (resource: ResourceControls) => {
+      const Parent = async (resource: ResourceScope) => {
         const child = await resource.create(Child);
         return {
           value: [],
@@ -176,7 +176,7 @@ describe('roots', () => {
     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: ResourceControls) => {
+      const Parent = async (resource: ResourceScope) => {
         await resource.create(Child);
         return {
           value: [],
@@ -202,7 +202,7 @@ describe('roots', () => {
         },
       });
 
-      const Parent = async (resource: ResourceControls) => {
+      const Parent = async (resource: ResourceScope) => {
         await resource.create(Child);
         return {
           value: [],
@@ -220,7 +220,7 @@ describe('roots', () => {
 
     it('guards against creating new resources after teardown', async () => {
       const Child = async () => ({ value: [] });
-      const Parent = async (resource: ResourceControls) => ({
+      const Parent = async (resource: ResourceScope) => ({
         value: bindContext(resource),
       });
 

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

@@ -1,4 +1,4 @@
-import { create, ResourceControls, ResourceHandle } from '../';
+import { create, ResourceScope, ResourceHandle } from '../';
 
 describe('Utility types', () => {
   describe('ResourceHandle', () => {
@@ -17,7 +17,7 @@ describe('Utility types', () => {
     });
 
     it('infers the type when the value comes from a parameter', async () => {
-      async function Test(_ctx: ResourceControls, value: { count: number }) {
+      async function Test(_ctx: ResourceScope, value: { count: number }) {
         return {
           value,
         };

package/src/global-weakrefs.ts

@@ -10,6 +10,12 @@ export const resources = new WeakMap<object, RevokableResource>();
  */
 export const constructed = new WeakSet<object>();
 
+/**
+ * Indicates if an object is a root resource. This is used to prevent
+ * child resources from being destroyed by the root `destroy(...)` function.
+ */
+export const roots = new WeakSet<object>();
+
 export interface RevokableResource {
   resource: Resource<object>;
 

package/src/index.ts

@@ -1,5 +1,5 @@
 export { default as bindContext } from './bind-context';
-export { create, destroy } from './root-lifecycle';
+export { createRoot as create, destroyRoot as destroy } from './root-lifecycle';
 export { createContext } from './inherited-context';
 export type { Resource, ResourceHandle } from './utility-types';
-export type { default as ResourceControls } from './resource-controls';
+export type { default as ResourceScope } from './resource-scope';

package/src/resource-lifecycle.ts

@@ -1,6 +1,6 @@
 import { resources, constructed } from './global-weakrefs';
 import wrap from './wrap-with-proxy';
-import ResourceControls from './resource-controls';
+import ResourceScope from './resource-scope';
 import type { InheritedContext } from './inherited-context';
 import { ResourceFactory, ParametrizedResourceFactory } from './utility-types';
 
@@ -17,7 +17,7 @@ export const createWithContext = async <
 ): Promise<Controls> => {
   const curfew = { enforced: false };
   const children: Set<object> = new Set();
-  const context = new ResourceControls(state, children, curfew);
+  const context = new ResourceScope(state, children, curfew);
   let resource: Awaited<ReturnType<typeof factory>>;
 
   try {
@@ -60,7 +60,7 @@ export const createWithContext = async <
 
 /**
  * Tear down the resource and all its children, permanently destroying the
- * reference.
+ * reference. This works on both root resources and child resources.
  */
 export const destroy = async (handle: object) => {
   if (!constructed.has(handle)) {

package/src/{resource-controls.ts → resource-scope.ts}

@@ -8,7 +8,7 @@ import { ResourceFactory, ParametrizedResourceFactory } from './utility-types';
  * provisioned. It allows them to provision other resources while keeping
  * track of ownership and lifetimes.
  */
-export default class ResourceControls {
+export default class ResourceScope {
   #destroyed = new WeakSet<object>();
   #resources: Set<object>;
   #curfew: RevokableResource['curfew'];
@@ -64,8 +64,9 @@ export default class ResourceControls {
   public setContext = <Value>(
     context: ContextHandle<Value>,
     value: Value,
-  ): void => {
+  ): Value => {
     this.#state[ContextHandle.getId(context)] = value;
+    return value;
   };
 
   /** Retrieve a value from context, or a default if it is unset. */

package/src/root-lifecycle.ts

@@ -1,9 +1,10 @@
-import { createWithContext } from './resource-lifecycle';
+import { createWithContext, destroy } from './resource-lifecycle';
 import { ParametrizedResourceFactory } from './utility-types';
 import { ResourceFactory } from './utility-types';
+import { resources, roots } from './global-weakrefs';
 
 /** Provision a resource and return its external API. */
-export const create = async <
+export const createRoot = async <
   Controls extends object,
   Args extends Array<unknown>,
 >(
@@ -14,9 +15,22 @@ export const create = async <
   ...args: Args
 ): Promise<Controls> => {
   const rootContext = Object.create(null);
-  return createWithContext(rootContext, factory, ...args);
+  const root = await createWithContext(rootContext, factory, ...args);
+  roots.add(root);
+
+  return root;
 };
 
-// Destroying a root resource is the same process as destroying a child
-// resource. No need to change the implementation.
-export { destroy } from './resource-lifecycle';
+/**
+ * Tear down the resource and all its children, permanently destroying the
+ * reference. This cannot be used to destroy child resources, only roots.
+ */
+export const destroyRoot = async (resource: object): Promise<void> => {
+  if (resources.has(resource) && !roots.has(resource)) {
+    throw new Error(
+      'Cannot destroy child resource. It is owned by another scope.',
+    );
+  }
+
+  return destroy(resource);
+};

package/src/utility-types.ts

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import type ResourceControls from './resource-controls';
+import type ResourceScope from './resource-scope';
 
 /**
  * Represents an arbitrary stateful resource that is asynchronously provisioned
@@ -7,14 +7,14 @@ import type ResourceControls from './resource-controls';
  * first tears down the children.
  */
 export interface ResourceFactory<Value extends object> {
-  (resource: ResourceControls): Promise<Resource<Value>>;
+  (resource: ResourceScope): Promise<Resource<Value>>;
 }
 
 export interface ParametrizedResourceFactory<
   Value extends object,
   Args extends Array<unknown>,
 > {
-  (resource: ResourceControls, ...args: Args): Promise<Resource<Value>>;
+  (resource: ResourceScope, ...args: Args): Promise<Resource<Value>>;
 }
 
 export interface Resource<Value extends object> {

package/src/__tests__/root-lifecycles.test.ts

@@ -1,236 +0,0 @@
-import type ResourceControls from '../resource-controls';
-import { create, destroy } from '../root-lifecycle';
-import bindContext from '../bind-context';
-
-describe('roots', () => {
-  describe('create', () => {
-    it('allocates the resource', async () => {
-      const config = { test: 'init-args' };
-      const Test = vi.fn(
-        async (_resource: ResourceControls, config: { test: string }) => ({
-          value: config,
-        }),
-      );
-
-      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: ResourceControls) => {
-          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: ResourceControls) => {
-          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 = vi.fn<[], void>();
-      const Test = async () => ({
-        value: {},
-        destroy: spy,
-      });
-
-      const test = await create(Test);
-
-      expect(spy).not.toHaveBeenCalled();
-      await expect(destroy(test)).resolves.not.toThrow();
-      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: [] });
-
-      const test = await create(Test);
-      await destroy(test);
-
-      await expect(destroy(test)).resolves.not.toThrow();
-    });
-
-    it('automatically unmounts all children', async () => {
-      const spy = vi.fn();
-      const Child = async () => ({ value: [], destroy: spy });
-      async function Parent(resource: ResourceControls) {
-        await resource.create(Child);
-        return { value: [] };
-      }
-
-      const parent = await create(Parent);
-      await destroy(parent);
-
-      expect(spy).toHaveBeenCalled();
-    });
-
-    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;
-        },
-      });
-
-      const Parent = async (resource: ResourceControls) => {
-        await resource.create(Child);
-        return { value: [] };
-      };
-
-      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: ResourceControls) => {
-        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: ResourceControls) => {
-        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: ResourceControls) => {
-        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: ResourceControls) => {
-        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: ResourceControls) => {
-        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: ResourceControls) => ({
-        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,
-      );
-    });
-  });
-});