From 017b56e3e1aab4546678a79848fe72b1ac6b2cf1 Mon Sep 17 00:00:00 2001 From: DmitryAstafyev Date: Tue, 21 Nov 2023 21:48:26 +0100 Subject: [PATCH 1/4] Update README (add ref to tslink) --- README.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/README.md b/README.md index 1ed7c2a4..2c33b559 100644 --- a/README.md +++ b/README.md @@ -386,6 +386,58 @@ $ npx electron-build-env nj-cli build --release otherwise you will get dreaded `A dynamic link library (DLL) initialization routine failed` when importing the rust module in electron +## Preparing npm packages + +Node module generated with `node-bindgen` can be used directly in any node JS project, just copied `index.node` into it. But in case of direct access to a module IDE will not highlight available functions, classes etc. Usually, this is not comfortable and makes the risks of potential bugs higher as soon as the public API of the node module is changed. + +To create a full-fledged npm package with TypeScript types definitions and all necessary JavaScript wrappers can be used a crate `tslink`. + +`tslink` crate generates files `*.d.ts`, `*.js` and `package.json` with a description of the npm module. Such package could be integrated into an end-project with minimal effort. + +In addition, because `tslink` generates TypeScript types definitions, any changes on the native node module (`index.node`) will be highlighted by `TypeScript` compiler and it makes the risk of bugs (related to changed API or public data types) much lower. + +For example, + +```ignore +#[macro_use] extern crate tslink; +use tslink::tslink; +use node_bindgen::derive::node_bindgen; + +struct MyScruct {} + +#[tslink(class)] +#[node_bindgen] +impl MyScruct { + #[tslink(constructor)] + #[node_bindgen(constructor)] + pub fn new() -> Self { + Self {} + } + + #[tslink(snake_case_naming)] + #[node_bindgen] + fn inc_my_number(&self, a: i32) -> i32 { + a + 1 + } +} +``` + +Pay your attention, call of `#[tslink]` should be always above of call `#[node_bindgen]`. + +Also, please **note**, `node-bindgen` by default applies snake case naming to methods. You should use `#[tslink(snake_case_naming)]` to consider this moment (see more on [crate page](https://docs.rs/tslink/0.1.0/tslink)). + +`tslink` requires a configuration file in the root of your project (`tslink.toml`). Configuration file should include a valid path to the native node module. By default `node-bindgen` creates `index.node` in `./dist` folder of your `root`. + +File: `./tslink.toml` (in a `root` of project): + +```ignore +node = "./dist/index.node" +``` + +Full example of usage `tslink` and `node-bindgen` is [here](https://github.com/DmitryAstafyev/tslink/tree/master/examples/node_bindgen). + +See more API documentation on a `tslink` [crate page](https://docs.rs/tslink/0.1.0/tslink). + ## Contributing If you'd like to contribute to the project, please read our [Contributing guide](CONTRIBUTING.md). From 06f63f144adf72cb9b95041c016d15a1ae532648 Mon Sep 17 00:00:00 2001 From: DmitryAstafyev Date: Wed, 22 Nov 2023 08:45:18 +0100 Subject: [PATCH 2/4] Extend example of tslink usage --- README.md | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 2c33b559..59f9914b 100644 --- a/README.md +++ b/README.md @@ -403,25 +403,36 @@ For example, use tslink::tslink; use node_bindgen::derive::node_bindgen; -struct MyScruct {} +struct MyScruct { + inc: i32, +} #[tslink(class)] #[node_bindgen] impl MyScruct { #[tslink(constructor)] #[node_bindgen(constructor)] - pub fn new() -> Self { - Self {} + pub fn new(inc: i32) -> Self { + Self { inc } } #[tslink(snake_case_naming)] #[node_bindgen] fn inc_my_number(&self, a: i32) -> i32 { - a + 1 + a + self.inc } } ``` +Would be represented (`*.d.ts`) as + +```ignore +export declare class MyStruct { + constructor(inc: number); + incMyNumber(a: number): number; +} +``` + Pay your attention, call of `#[tslink]` should be always above of call `#[node_bindgen]`. Also, please **note**, `node-bindgen` by default applies snake case naming to methods. You should use `#[tslink(snake_case_naming)]` to consider this moment (see more on [crate page](https://docs.rs/tslink/0.1.0/tslink)). From 72772525920a5cfce91dbaac5314dda8deb84dc1 Mon Sep 17 00:00:00 2001 From: DmitryAstafyev Date: Wed, 22 Nov 2023 08:59:53 +0100 Subject: [PATCH 3/4] Add responsibility note --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 59f9914b..7e9f8ec4 100644 --- a/README.md +++ b/README.md @@ -449,6 +449,8 @@ Full example of usage `tslink` and `node-bindgen` is [here](https://github.com/D See more API documentation on a `tslink` [crate page](https://docs.rs/tslink/0.1.0/tslink). +**Note**. The node-bindgen's developers are not responsible for the correctness of the work tslink crate. All possible issues and feature requests related to tslink should be addressed to tslink's developers. + ## Contributing If you'd like to contribute to the project, please read our [Contributing guide](CONTRIBUTING.md). From 87e5a4750c166d3400f39788b5a4a1928825531b Mon Sep 17 00:00:00 2001 From: DmitryAstafyev Date: Wed, 22 Nov 2023 18:20:10 +0100 Subject: [PATCH 4/4] Add link to crates.io --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7e9f8ec4..e0623c39 100644 --- a/README.md +++ b/README.md @@ -390,7 +390,7 @@ otherwise you will get dreaded `A dynamic link library (DLL) initialization rou Node module generated with `node-bindgen` can be used directly in any node JS project, just copied `index.node` into it. But in case of direct access to a module IDE will not highlight available functions, classes etc. Usually, this is not comfortable and makes the risks of potential bugs higher as soon as the public API of the node module is changed. -To create a full-fledged npm package with TypeScript types definitions and all necessary JavaScript wrappers can be used a crate `tslink`. +To create a full-fledged npm package with TypeScript types definitions and all necessary JavaScript wrappers can be used a crate [tslink](https://crates.io/crates/tslink). `tslink` crate generates files `*.d.ts`, `*.js` and `package.json` with a description of the npm module. Such package could be integrated into an end-project with minimal effort.