@auto_js/napi 0.0.1

package/CMakeLists.txt

@@ -0,0 +1,55 @@
+find_package_from_npm(@auto_js/js)
+find_package_from_npm(@auto_js/napi_exports)
+
+add_library(napi_js OBJECT)
+target_compile_features(napi_js PUBLIC cxx_std_23)
+target_include_directories(napi_js INTERFACE include)
+target_link_libraries(napi_js PRIVATE auto_js nodejs utility_js)
+
+target_sources(napi_js
+	PRIVATE
+		api/uv_scheduler.cc
+		support/environment.cc
+		support/initialize.cc
+		value/array.cc
+		value/dictionary.cc
+		value/object.cc
+		value/primitive.cc
+	PUBLIC FILE_SET CXX_MODULES FILES
+		_module.cc
+		api/api.cc
+		api/callback_info.cc
+		api/finalizer.cc
+		api/handle_scope.cc
+		api/invoke.cc
+		api/uv_handle.cc
+		api/uv_scheduler.h.cc
+		handle/bound_value.cc
+		handle/reference.cc
+		handle/remote.cc
+		handle/types.cc
+		handle/value.cc
+		support/callback_storage.cc
+		support/callback.cc
+		support/class_template_storage.cc
+		support/container.cc
+		support/environment_fwd.cc
+		support/environment.h.cc
+		support/error_scope.cc
+		support/initialize.h.cc
+		support/promise.cc
+		support/string_table.cc
+		support/utility.cc
+		transfer/accept.cc
+		transfer/visit.cc
+		value/array.h.cc
+		value/class.cc
+		value/class.h.cc
+		value/dictionary.h.cc
+		value/external.cc
+		value/function.cc
+		value/function.h.cc
+		value/object.h.cc
+		value/primitive.h.cc
+		value/value.cc
+)

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2017 Marcel Laverdet
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,255 @@
+[![npm version](https://badgen.now.sh/npm/v/@auto_js/napi)](https://www.npmjs.com/package/@auto_js/napi)
+[![isc license](https://badgen.now.sh/npm/license/@auto_js/napi)](https://github.com/laverdet/isolated-vm/blob/experimental/LICENSE)
+[![npm downloads](https://badgen.now.sh/npm/dm/@auto_js/napi)](https://www.npmjs.com/package/@auto_js/napi)
+
+`@auto_js` -- Automatic C++ bindings for JavaScript
+===================================================
+
+<img align="right" width="33%" height="33%" src="upload/macro.jpg">
+
+I made this C++ template thing that converts JavaScript functions and values automatically.
+
+```c++
+auto log(std::string message) -> void {
+	std::print("{}", message);
+}
+
+js::napi::napi_js_module module_namespace{
+	std::type_identity<environment>{},
+	[](environment& env) -> auto {
+		return std::tuple{
+			std::in_place,
+			std::pair{util::cw<"log">, js::free_function{log}},
+		};
+	}
+};
+```
+
+## It's better than what you're writing by hand
+
+```c++
+struct point {
+		int x;
+		int y;
+
+		constexpr static auto struct_template = js::struct_template{
+			js::struct_member{util::cw<"x">, &point::x},
+			js::struct_member{util::cw<"y">, &point::y},
+		};
+};
+
+auto take_points(std::vector<point> points) -> void {
+	for (const auto& [ x, y ] : points) {
+		std::print("({}, {})\n", x, y);
+	}
+}
+
+constexpr auto string_literals = std::tuple{
+	"x"sv,
+	"y"sv,
+};
+
+class environment
+		: public napi::environment,
+			public napi::string_table<string_literals> {
+	public:
+		using napi::environment::environment;
+};
+
+js::napi::napi_js_module module_namespace{
+	std::type_identity<environment>{},
+	[](environment& env) -> auto {
+		return std::tuple{
+			std::in_place,
+			std::pair{util::cw<"take_points">, js::free_function{take_points}},
+		};
+	}
+};
+```
+
+`@auto_js/napi` compiles this in a way such that the "x" and "y" strings each get their own
+`v8::Persistent<v8::String>` handles. Furthermore, for each invocation to the translation layer
+those strings only need to dereference the persistent handle once, then they're cached in
+`v8::Local<v8::String>` handles. The upshot is that your code is not hammering the v8 runtime with
+unneeded work.
+
+
+Runtimes
+========
+
+The core `@auto_js/js` module is runtime-agnostic. It describes *JavaScript* values in an abstract
+way. A bunch of generic support code then provides the translation. The same support code which
+translates an array of JavaScript arguments to C++ can be used to implement the structured clone
+algorithm with a one-liner.
+
+Modules `@auto_js/napi` and `@auto_js/v8` are provided which implement runtime support. The Napi
+implementation is more complete than v8.
+
+
+Transferable Types
+==================
+
+## Integrals
+
+`bool` and `double` transfer exactly how you would expect.
+
+`int32_t` and `uint32_t` will be coerced from the internal JavaScript `double` type. If the user
+passes a value that is out of range an error will be thrown.
+
+
+## Strings
+
+Strings are interesting. Internally, JavaScript specifies that strings are UTF-16. Runtimes
+typically also provide an optimized "one byte" representation for ASCII strings. On the C++ side you
+probably want UTF-8. So that's at least three types of strings you'll want to know how to handle.
+
+You can accept `std::u16string` which will always work. You can also accept `std::u8string` which
+will automatically interpolate the string from UTF-16 to UTF-8. Another option is `std::string`
+which would be an optimized "one byte" ASCII string. This string type will throw if a string
+contains non-ASCII data.
+
+
+## Bigints
+
+You can accept `int64_t` or `uint64_t` for bigint types. These will throw if the bigint cannot be
+coerced to the given C++ type. A utility class `js::bigint` is provided which can losslessly
+represent any JavaScript bigint. Mathematical operations are not provided.
+
+
+## Dates
+
+A `std::chrono`-compatible `js::js_clock` is provided. This losslessly represents a JavaScript date
+using the same `double` value that the runtime uses. It provides `std::chrono::clock_cast` for
+casting to other C++ clock ranges.
+
+
+## Optionals
+
+`std::optional<T>` can be used on top of any other type to accept values of `undefined`.
+
+
+## Enumerations
+
+Enumerated values can be represented as strings in JavaScript by declaring those strings statically in C++.
+
+```c++
+enum class enum_test : std::int8_t {
+	first,
+	second,
+	third,
+};
+
+namespace js {
+template <>
+struct enum_values<enum_test> {
+		constexpr static auto values = std::array{
+			std::pair{"first", enum_test::first},
+			std::pair{"second", enum_test::second},
+			std::pair{"third", enum_test::third}
+		};
+};
+}
+```
+
+
+## Variants
+
+`std::variant<std::u16string, double>` could be used to accept *either* a string or a number value.
+You can mix and match types as needed.
+
+
+## Covariants
+
+`std::variant<double, int32_t>` can be used to accept *either* a floating point or a signed integer.
+Note that this uses runtime function calls to resolve the covariance. In v8 it will invoke
+`value->IsInt32()` to discover what to return. Napi does not support this, so a `double` will always
+be returned.
+
+`std::variant<std::string, std::u16string>` can be used in a similar way to accept either a UTF-16
+string or the optimized ASCII string. This uses `value->IsOneByte()` to resolve the covariance.
+Again, in napi a UTF-16 string will always be returned.
+
+
+## Structures
+
+`struct` & `class` types can be defined with either direct member access, or accessor functions.
+Structures defined in this way are completely transferred to/from JavaScript. This isn't the "object
+wrap" thing where a C++ value lives in JavaScript.
+
+Direct member access:
+```c++
+struct point {
+		int x;
+		int y;
+
+		constexpr static auto struct_template = js::struct_template{
+			js::struct_member{util::cw<"x">, &point::x},
+			js::struct_member{util::cw<"y">, &point::y},
+		};
+};
+```
+
+Getter & setter:
+```c++
+struct point {
+		auto get_x() const -> int;
+		auto set_x(int x) const -> void;
+
+		constexpr static auto struct_template = js::struct_template{
+			// Getter and setter are both optional. Pass `nullptr` to define a type without a
+			// getter/setter. If an accessor is missing the type would only be transferable
+			// one way, for example a type missing a setter could only be `return`ed and not
+			// accepted as a function parameter.
+			js::struct_accessor{util::cw<"x">, util::fn<&point::get_x>, util::fn<&point::set_x>},
+			js::struct_member{util::cw<"y">, &point::y},
+		};
+};
+```
+
+## Discriminated Unions
+
+TypeScript-style [discriminated
+unions](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#union-types) can be
+defined as a `std::variant` with a discriminant.
+
+The following would accept either something like `{ type: "bear", honey: 1 }` or
+`{ type: "horse", hay: 1 }`
+
+```c++
+struct bear; // imagine it defines: honey
+struct horse; // imagine it defines: hay
+
+namespace js {
+template <>
+struct union_of<std::variant<bear, horse>> {
+		constexpr static auto& discriminant = util::cw<"type">;
+		constexpr static auto alternatives = std::tuple{
+			alternative<bear>{"bear"},
+			alternative<horse>{"horse"},
+		};
+};
+}
+```
+
+
+## Arrays
+
+`std::vector<T>` will accept a JavaScript array of the given type.
+
+
+## Classes
+
+"Object wrap" Napi functions are supported.
+
+```c++
+export class database {
+	public:
+		using transfer_type = js::tagged_external<database>;
+
+		auto query(environment& env, std::string query) -> std::string;
+		static auto connect(environment& env, std::string uri) -> js::forward<js::napi::value<>>;
+		static auto class_template(environment& env) -> js::napi::value<class_tag_of<database>> {
+			// incomplete
+		}
+};
+```

package/_module.cc

@@ -0,0 +1,19 @@
+export module napi_js;
+// nb: These must come first, for some reason
+import :accept;
+import :visit;
+// Before these:
+export import :api; // should be removed
+export import :class_template_storage;
+export import :environment;
+export import :external;
+export import :function;
+export import :initialize;
+export import :object;
+export import :promise;
+export import :reference;
+export import :remote;
+export import :string_table;
+export import :value;
+import :class_definitions;
+import :function_definitions;

package/api/api.cc

@@ -0,0 +1,10 @@
+export module napi_js:api;
+// Internal nodejs API utilities which have no dependencies on anything else in `napi_js`
+export import :api.callback_info;
+export import :api.finalizer;
+export import :api.handle_scope;
+export import :api.invoke;
+export import :api.uv_handle;
+export import :api.uv_scheduler;
+export import auto_js;
+export import nodejs;

package/api/callback_info.cc

@@ -0,0 +1,41 @@
+module;
+#include <array>
+#include <span>
+#if _LIBCPP_VERSION
+// clang 22.1.0: Without this I get a big horrible ICE in this file
+#include <new>
+#endif
+export module napi_js:api.callback_info;
+import :api.invoke;
+import auto_js;
+import util;
+
+namespace js::napi {
+
+// Helper which reads arguments from napi invocation
+export struct callback_info : util::non_copyable {
+	public:
+		// NOLINTNEXTLINE(cppcoreguidelines-pro-type-member-init)
+		callback_info(napi_env env, napi_callback_info info) {
+			napi::invoke0(napi_get_cb_info, env, info, &count_, storage_.data(), &this_, &data_);
+			if (count_ > storage_.size()) {
+				throw js::range_error{u"Too many arguments provided for a function call"};
+			}
+		}
+
+		[[nodiscard]] auto arguments() const -> std::span<const napi_value> { return std::span{storage_}.first(count_); }
+		[[nodiscard]] auto data() const -> void* { return data_; }
+		[[nodiscard]] auto this_arg() const -> napi_value { return this_; }
+
+	private:
+		napi_value this_;
+		std::array<napi_value, 8> storage_;
+		std::size_t count_{storage_.size()};
+		void* data_;
+};
+
+// Common declaration for `napi_type_tag` by type
+export template <class Type>
+constexpr auto type_tag_for = napi_type_tag{.lower = util::type_hash<Type>, .upper = 0};
+
+} // namespace js::napi

package/api/finalizer.cc

@@ -0,0 +1,44 @@
+module;
+#include <concepts>
+#include <memory>
+#include <type_traits>
+export module napi_js:api.finalizer;
+import nodejs;
+import util;
+
+namespace js::napi {
+
+// Finalizer for basic unique_ptr
+export template <class Type, class Deleter>
+auto apply_finalizer(std::unique_ptr<Type, Deleter> unique, std::invocable<Type*, napi_finalize, void*> auto accept) -> decltype(auto)
+	requires std::is_empty_v<Deleter> {
+	// Finalizer uses a default-constructed deleter
+	const napi_finalize finalize = [](napi_env /*env*/, void* data, void* /*hint*/) -> void {
+		Deleter deleter{};
+		deleter(static_cast<Type*>(data));
+	};
+	auto result = util::regular_return{[ & ]() -> decltype(auto) {
+		return accept(unique.get(), finalize, nullptr);
+	}}();
+	unique.release();
+	return *std::move(result);
+}
+
+// Finalizer for shared_ptr
+export template <class Type>
+auto apply_finalizer(std::shared_ptr<Type> shared, std::invocable<Type*, napi_finalize, void*> auto accept) -> decltype(auto) {
+	// `shared_ptr<T>*` is passed as the finalizer hint
+	using shared_ptr_type = std::shared_ptr<Type>;
+	auto* ptr = shared.get();
+	auto ptr_ptr = std::make_unique<shared_ptr_type>(std::move(shared));
+	const napi_finalize finalize = [](napi_env /*env*/, void* /*data*/, void* hint) -> void {
+		delete static_cast<shared_ptr_type*>(hint);
+	};
+	auto result = util::regular_return{[ & ]() -> decltype(auto) {
+		return accept(ptr, finalize, ptr_ptr.get());
+	}}();
+	ptr_ptr.release();
+	return *std::move(result);
+}
+
+} // namespace js::napi

package/api/handle_scope.cc

@@ -0,0 +1,23 @@
+export module napi_js:api.handle_scope;
+import :api.invoke;
+import util;
+
+namespace js::napi {
+
+// RAII napi handle scope
+export class handle_scope : util::non_moveable {
+	public:
+		explicit handle_scope(napi_env env) :
+				env_{env},
+				handle_scope_{napi::invoke(napi_open_handle_scope, env)} {}
+
+		~handle_scope() {
+			napi::invoke0_noexcept(napi_close_handle_scope, env_, handle_scope_);
+		}
+
+	private:
+		napi_env env_;
+		napi_handle_scope handle_scope_;
+};
+
+} // namespace js::napi

package/api/invoke.cc

@@ -0,0 +1,99 @@
+module;
+#include <concepts>
+#include <exception>
+#include <optional>
+#include <stdexcept>
+#include <type_traits>
+export module napi_js:api.invoke;
+export import nodejs;
+import util;
+
+namespace js::napi {
+
+// Thrown from `invoke` to indicate that a napi operation failed and there is an exception waiting
+// on the JS stack.
+export class pending_error : public std::exception {
+	public:
+		[[nodiscard]] auto what() const noexcept -> const char* final { return "[pending napi error]"; }
+};
+
+// Invoke the given napi function, returning void, or throw if it fails
+export template <class... Params>
+auto invoke0(auto(function)(Params...)->napi_status, auto&&... args) -> void
+	requires std::invocable<decltype(function), decltype(args)...> {
+	// nb: Don't lint on something like:
+	// `napi::invoke0(napi_throw_type_error, napi_env{env}, nullptr, "Illegal constructor");`
+	// NOLINTNEXTLINE(cppcoreguidelines-pro-bounds-array-to-pointer-decay)
+	switch (function(std::forward<decltype(args)>(args)...)) {
+		case napi_ok: return;
+		case napi_pending_exception: throw napi::pending_error{};
+		default: throw std::runtime_error{"napi dispatch error"};
+	}
+}
+
+// Invoke the given napi function, returning a bool indicating success
+export template <class... Params>
+auto invoke0_maybe(auto(function)(Params...)->napi_status, auto&&... args) -> bool
+	requires std::invocable<decltype(function), decltype(args)...> {
+	switch (function(std::forward<decltype(args)>(args)...)) {
+		case napi_ok: return true;
+		case napi_pending_exception: return false;
+		default: throw std::runtime_error{"napi dispatch error"};
+	}
+}
+
+// Invoke the given napi function, returning void, or terminate if it fails.
+export template <class... Params>
+auto invoke0_noexcept(auto(function)(Params...)->napi_status, auto&&... args) noexcept -> void
+	requires std::invocable<decltype(function), decltype(args)...> {
+	if (function(std::forward<decltype(args)>(args)...) != napi_ok) {
+		std::terminate();
+	}
+}
+
+// Extract the `out` parameter type from a napi function signature
+constexpr auto napi_invoke_out = [](auto... types) {
+	constexpr auto take = util::overloaded{
+		[]<class Param>(std::type_identity<Param> /*type*/) -> void {
+			static_assert(false, "Last parameter is not a pointer");
+		},
+		[]<class Param>(std::type_identity<Param*> /*type*/) -> auto {
+			return type<Param>;
+		},
+	};
+	return take(types...[ sizeof...(types) - 1 ]);
+};
+
+template <class... Params>
+using napi_invoke_out_t = type_t<napi_invoke_out(type<Params>...)>;
+
+// Invoke the given napi function and throw if it fails.
+export template <class... Params>
+auto invoke(auto(function)(Params...)->napi_status, auto&&... args)
+	requires std::invocable<decltype(function), decltype(args)..., napi_invoke_out_t<Params...>*> {
+	napi_invoke_out_t<Params...> out_arg;
+	napi::invoke0(function, std::forward<decltype(args)>(args)..., &out_arg);
+	return std::move(out_arg);
+}
+
+// Invoke the given napi function and return `optional<T>` indicating failure.
+export template <class... Params>
+auto invoke_maybe(auto(function)(Params...)->napi_status, auto&&... args)
+	requires std::invocable<decltype(function), decltype(args)..., napi_invoke_out_t<Params...>*> {
+	using out_type = napi_invoke_out_t<Params...>;
+	out_type out_arg;
+	return napi::invoke0_maybe(function, std::forward<decltype(args)>(args)..., &out_arg)
+		? std::optional<out_type>{std::move(out_arg)}
+		: std::nullopt;
+}
+
+// Invoke the given napi function and terminate if it fails.
+export template <class... Params>
+auto invoke_noexcept(auto(function)(Params...)->napi_status, auto&&... args) noexcept
+	requires std::invocable<decltype(function), decltype(args)..., napi_invoke_out_t<Params...>*> {
+	napi_invoke_out_t<Params...> out_arg;
+	napi::invoke0_noexcept(function, std::forward<decltype(args)>(args)..., &out_arg);
+	return std::move(out_arg);
+}
+
+} // namespace js::napi

package/api/uv_handle.cc

@@ -0,0 +1,113 @@
+module;
+#include <memory>
+#include <stdexcept>
+#include <type_traits>
+#include <utility>
+export module napi_js:api.uv_handle;
+import nodejs;
+import util;
+
+namespace js::napi {
+
+// Simple `uv_handle` wrapper which isolates all the pointer casting that needs to be done w/ the C
+// API.
+template <class Handle, class Type>
+	requires std::is_trivial_v<Type> && (sizeof(Type) == sizeof(Handle::data))
+class uv_typed_handle {
+	public:
+		// NOLINTNEXTLINE(google-explicit-constructor)
+		operator Handle*() { return static_cast<Handle*>(&handle_); }
+		// NOLINTNEXTLINE(google-explicit-constructor)
+		operator uv_handle_t*() { return reinterpret_cast<uv_handle_t*>(&handle_); }
+		// (non-const) returns data lvalue
+		auto data() -> Type& {
+			void* ptr = static_cast<void*>(&handle_.data);
+			return *static_cast<Type*>(ptr);
+		}
+		// (const) returns data rvalue
+		[[nodiscard]] auto data() const -> Type { return static_cast<Type>(handle_.data); }
+		[[nodiscard]] auto loop() const -> uv_loop_t* { return handle_.loop; }
+		[[nodiscard]] auto type() const -> uv_handle_type { return handle_.type; }
+
+	private:
+		Handle handle_;
+};
+
+// `uv_handle_t` subtype wrapper with uv-owned shared memory. An open handle must be closed before
+// the handle is destroyed or it is UB.
+export template <class Handle, class Type>
+class uv_handle_of : public util::pointer_facade {
+	private:
+		struct private_constructor {
+				explicit private_constructor() = default;
+		};
+		using shared_ptr_type = std::shared_ptr<uv_handle_of>;
+		using weak_ptr_type = std::weak_ptr<uv_handle_of>;
+		// An open handle's `data` pointer refers to a `shared_ptr` of itself. A closed handle refers to
+		// a `weak_ptr`, which will be deleted in the destructor.
+		union shared_or_weak_ptr {
+				shared_ptr_type* shared;
+				weak_ptr_type* weak;
+		};
+
+	public:
+		explicit uv_handle_of(const private_constructor& /*private*/, auto&&... args) :
+				value_{std::forward<decltype(args)>(args)...} {}
+		~uv_handle_of();
+		uv_handle_of() = delete;
+		uv_handle_of(const uv_handle_of&) = delete;
+		auto operator=(const uv_handle_of&) -> uv_handle_of& = delete;
+
+		auto operator*() -> auto& { return value_; }
+		auto close() -> void;
+		auto handle() -> auto& { return handle_; }
+		auto open(const auto& init, uv_loop_t* loop, auto&&... args) -> void;
+
+		static auto make(auto&&... args) -> shared_ptr_type;
+		static auto unwrap(const Handle* handle) -> const shared_ptr_type&;
+
+	private:
+		uv_typed_handle<Handle, shared_or_weak_ptr> handle_;
+		Type value_;
+};
+
+// ---
+
+template <class Handle, class Type>
+uv_handle_of<Handle, Type>::~uv_handle_of() {
+	delete handle_.data().weak;
+}
+
+template <class Handle, class Type>
+auto uv_handle_of<Handle, Type>::close() -> void {
+	uv_close(handle(), [](uv_handle_t* handle) -> void {
+		delete static_cast<shared_ptr_type*>(std::exchange(handle->data, nullptr));
+	});
+}
+
+template <class Handle, class Type>
+auto uv_handle_of<Handle, Type>::open(const auto& init, uv_loop_t* loop, auto&&... args) -> void {
+	auto weak_ptr_ptr = std::unique_ptr<weak_ptr_type>{std::exchange(handle_.data().weak, nullptr)};
+	auto shared_ptr_ptr = std::make_unique<shared_ptr_type>(*weak_ptr_ptr);
+	if (init(loop, handle(), std::forward<decltype(args)>(args)...) == 0) {
+		handle_.data().shared = shared_ptr_ptr.release();
+	} else {
+		handle_.data().weak = weak_ptr_ptr.release();
+		throw std::runtime_error{"Failed to open async handle"};
+	}
+}
+
+template <class Handle, class Type>
+auto uv_handle_of<Handle, Type>::make(auto&&... args) -> shared_ptr_type {
+	auto shared_with_block = std::make_shared<uv_handle_of>(private_constructor{}, std::forward<decltype(args)>(args)...);
+	auto weak_ptr_ptr = std::make_unique<weak_ptr_type>(shared_with_block);
+	shared_with_block->handle_.data().weak = weak_ptr_ptr.release();
+	return shared_with_block;
+}
+
+template <class Handle, class Type>
+auto uv_handle_of<Handle, Type>::unwrap(const Handle* handle) -> const shared_ptr_type& {
+	return *static_cast<shared_ptr_type*>(handle->data);
+}
+
+} // namespace js::napi