Improve promise documentation

Based on team discussion in #1658, we agreed that we should improve the documentation to help people avoid what might be a easy mistake to make.

It was noted that

node-addon-api/napi.h

Lines 1556 to 1578 in ff6a672

    
           class Promise : public Object { 
        
            public: 
        
             class Deferred { 
        
              public: 
        
               static Deferred New(napi_env env); 
        
               Deferred(napi_env env); 
        
               Napi::Promise Promise() const; 
        
               Napi::Env Env() const; 
        
               void Resolve(napi_value value) const; 
        
               void Reject(napi_value value) const; 
        
              private: 
        
               napi_env _env; 
        
               napi_deferred _deferred; 
        
               napi_value _promise; 
        
             }; 
        
             static void CheckCast(napi_env env, napi_value value); 
        
             Promise(napi_env env, napi_value value); 
        
           };

in the C API does not have catch or then methonds, however, it should be possible to add them to the C++ API to help make it easier to use them properly.

@vmoroz

@vmoroz also mentioned that it might be good to reference the JavaScript promise API and make the new documentation consistent where it makes sense. Maybe worth looking to see what other ones that are available in JavaScript might make sense to consider as well.

@legendecas mentioned should be cautious with some of the new wrappers that have been added more recently as they may not be available in older Node.js versions.

This issue is stale because it has been open many days with no activity. It will be closed soon unless the stale label is removed or a comment is made.

Discussion on the Node-API meeting today, #1668 should be sufficient to hint that the Promise Then/Catch methods return a new promise and an onRejection handler is available as a second parameter on the Then method, just like JS Promise APIs.

This can be closed as done now.

Navigation Menu

Repository navigation

Improve promise documentation #1666

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

	class Promise : public Object {
	public:
	class Deferred {
	public:
	static Deferred New(napi_env env);
	Deferred(napi_env env);

	Napi::Promise Promise() const;
	Napi::Env Env() const;

	void Resolve(napi_value value) const;
	void Reject(napi_value value) const;

	private:
	napi_env _env;
	napi_deferred _deferred;
	napi_value _promise;
	};

	static void CheckCast(napi_env env, napi_value value);

	Promise(napi_env env, napi_value value);
	};

Improve promise documentation #1666

Description

Activity

mhdawson commented on Jun 13, 2025

github-actions commented on Sep 12, 2025

legendecas commented on Sep 12, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions