# native-huron

> Utility classes for writing native addons for node.js.

Latest version **0.1.7** (published 2020-05-11) · MIT license · 0 weekly downloads

## Install

```sh
npm install native-huron
pnpm add native-huron
yarn add native-huron
bun add native-huron
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.7 |
| Published | 2020-05-11 |
| First published | 2015-11-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 52.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 3 |
| Author | @thekaliprince |
| Maintainers | brenca, gerhardberger |
| Keywords | native, huron, addon, dictionary |

## Links

- npm: https://www.npmjs.com/package/native-huron
- Repository: https://github.com/gerhardberger/native-huron
- Homepage: https://github.com/gerhardberger/native-huron#readme
- Issues: https://github.com/gerhardberger/native-huron/issues
- npm.io page: https://npm.io/package/native-huron

## Dependencies (1)

- [nan](https://npm.io/package/nan.md) ^2.14.1

## Recent versions

- 0.1.7 (latest) — 2020-05-11
- 0.1.6 — 2020-05-10
- 0.1.5 — 2018-01-22
- 0.1.4 — 2017-11-09
- 0.1.3 — 2017-08-15
- 0.1.2 — 2016-10-25
- 0.1.1 — 2016-07-27
- 0.1.0 — 2016-06-11
- 0.0.7 — 2016-03-03
- 0.0.6 — 2016-02-09
- 0.0.5 — 2016-02-08
- 0.0.4 — 2015-11-26
- 0.0.3 — 2015-11-18
- 0.0.2 — 2015-11-17
- 0.0.1 — 2015-11-15

## README

# native-huron

A set of utility classes to make writing native addons easier. The majority of the code is from [zcbenz's](https://github.com/zcbenz) [native-mate](https://github.com/zcbenz/native-mate) library. See `tests` folder for example. Current list of classes:
- **Converter:** Converting from primitive and basic C++ variables to V8 variables and from V8 variables to C++ variables.
- **Dictionary:** Handle dictionaries that represents a Javascript Object.
- **PersistentDictionary:** Same as Dictionaries but stored on the heap.
- **ScopedPersistent:** Store V8 objects on the heap.
- **Emitter:** Event emitter class.

## Install
```
$ npm i native-huron
```

## Usage
In your `binding.gyp`:
``` gyp
{
  'includes': [ 'path/to/native-huron/module/native_huron_files.gypi' ],
  'targets': [ {
    'target_name': 'test'
    , 'sources': [ '<@(native_huron_files)' ]
    , 'include_dirs': [ "<!(node -e \"require('native-huron')\")" ]
  } ]
}
```

In your C++ files:
``` c++
#include <native_huron/converter.h>
#include <native_huron/dictionary.h>

// Use utility classes...
```

## API

### Converter

##### ConvertToV8(isolate, value)
Converts the value, a primitive or simple C++ variable (e.g. `double` or `std::string`) to a V8 variable. **Returns** the converted V8 variable.

##### TryConvertToV8(isolate, value, result)
Tries to convert the value, a primitive or simple C++ variable (e.g. `double` or `std::string`) to a V8 variable. **Returns** a `boolean` wether the conversion was successful, if it was, the result is written to the `result` address.

##### ConvertFromV8(isolate, value, result)
Tries to convert the value, a V8 variable, primitive or simple C++ variable (e.g. `double` or `std::string`). **Returns** a `boolean` wether the conversion was successful, if it was, the result is written to the `result` address.

##### StringToV8(isolate, input)
Convenience function to convert a `std::string` to a `v8::String`. **Returns** the converted string.

##### V8ToString(isolate, input)
Convenience function to convert a `v8::String` to a `std::string`. **Returns** the converted string.

### Dictionary
This class can also be used with Converter's `ConvertTo/FromV8` functions.

##### Dictionary::Dictionary(isolate, object)
Creates a `Dictionary` object from the `object` parameter, which is a `v8::Local<v8::Object>`.

##### Dictionary::CreateEmpty(isolate)
Creates an empty `Dictionary` object. **Returns** the created dictionary.

##### dict.Get(key, out)
**Returns** `true`, if the `key` (`std::string`) exists in the dictionary and writes it to the `out` address.

##### dict.GetHidden(key, out)
**Returns** `true`, if the `key` (`std::string`) exists as a hidden value in the dictionary and writes it to the `out` address.

##### dict.Set(key, value)
**Returns** `true`, if the `key` (`std::string`) is successfully set in the dictionary with the given `value`.

##### dict.SetHidden(key, value)
**Returns** `true`, if the `key` (`std::string`) is successfully set as hidden value in the dictionary with the given `value`.

##### dict.SetMethod(key, callback)
**Returns** `true`, if the `key` (`std::string`) method is successfully set in the dictionary with the given `callback`, which is a C++ method with V8 `FunctionCallback` signature (standard V8 addon method signature).

##### dict.Delete(key)
**Returns** `true`, if the `key` (`std::string`) is successfully deleted from the dictionary.

##### dict.IsEmpty()
**Returns** if the dictionary is empty.

### PersistentDictionary
Same functionality as `Dictionary`, but it is stored on the heap. *Use only if really neccessary.*

### Emitter
Classes derived from this class can use the `Emit` method to fire listeners added in Javascript. In your class you have to add `Emitter`'s `On` method to use it (see test folder).

##### Emit(V8String eventName, V8Types args...)
Emits the `eventName` event handlers with the specified `args`. **All parameters' type should be V8 types!**

##### Emit(std::string eventName, V8Types args...)
Alias for the above method.

##### Emit(const char* eventName, V8Types args...)
Alias for the above method.

##### Emit(std::string eventName, lambda(Dictionary &dict))
Emits the `eventName` event handlers with the `dict` object as a parameter. So you have to add the desired parameters in your `lambda` function your dictionary. **This is needed to emit events from different threads as V8's thread.**

##### Emit(const char* eventName, lambda(Dictionary &dict))
Alias for the above method.

##### On(std::string eventName, Local<Function> callback)
This *member method* lets you set listeners from c++ code.

##### Off(std::string eventName, Local<Function> callback)
This *member method* lets you remove listeners from c++ code.

##### Once(std::string eventName, Local<Function> callback)
This *member method* lets you set listeners from c++ code that fire only once.

---
_Source: https://npm.io/package/native-huron · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._