# node-native2ascii

> Node.js implementation of Java's Native-to-ASCII Converter

Latest version **0.3.0** (published 2025-08-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install node-native2ascii
pnpm add node-native2ascii
yarn add node-native2ascii
bun add node-native2ascii
```

Provides the command `native2ascii`.

## Health

**Score 40/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.3.0 |
| Published | 2025-08-04 |
| First published | 2017-12-08 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 4 |
| Unpacked size | 91 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 4 |
| Author | neocotic |
| Maintainers | neocotic |
| Keywords | native, ascii, converter, unicode, escape, unescape |

## Links

- npm: https://www.npmjs.com/package/node-native2ascii
- Repository: https://github.com/neocotic/node-native2ascii
- Issues: https://github.com/neocotic/node-native2ascii/issues
- Funding: https://github.com/sponsors/neocotic
- npm.io page: https://npm.io/package/node-native2ascii

## Dependencies (4)

- [commander](https://npm.io/package/commander.md) ^14.0.0
- [escape-unicode](https://npm.io/package/escape-unicode.md) ^0.3.0
- [unescape-unicode](https://npm.io/package/unescape-unicode.md) ^0.3.0
- [package-json-from-dist](https://npm.io/package/package-json-from-dist.md) ^1.0.1

## Recent versions

- 0.3.0 (latest) — 2025-08-04
- 0.2.0 — 2018-12-04
- 0.1.2 — 2018-01-25
- 0.1.1 — 2017-12-09
- 0.1.0 — 2017-12-08

## README

_   _           ___                _ _ 
                | | (_)         |__ \              (_|_)
     _ __   __ _| |_ ___   _____   ) |__ _ ___  ___ _ _
    | '_ \ / _` | __| \ \ / / _ \ / // _` / __|/ __| | |
    | | | | (_| | |_| |\ V /  __// /| (_| \__ \ (__| | |
    |_| |_|\__,_|\__|_| \_/ \___|____\__,_|___/\___|_|_|

[![Build Status](https://img.shields.io/github/actions/workflow/status/neocotic/node-native2ascii/ci.yml?event=push&style=for-the-badge)](https://github.com/neocotic/node-native2ascii/actions/workflows/ci.yml)
[![Downloads](https://img.shields.io/npm/dw/node-native2ascii?style=for-the-badge)](https://github.com/neocotic/node-native2ascii)
[![Release](https://img.shields.io/npm/v/node-native2ascii?style=for-the-badge)](https://github.com/neocotic/node-native2ascii)
[![License](https://img.shields.io/github/license/neocotic/node-native2ascii?style=for-the-badge)](https://github.com/neocotic/node-native2ascii/blob/main/LICENSE.md)

[node-native2ascii](https://github.com/neocotic/node-native2ascii) is a [Node.js](https://nodejs.org) implementation of
Java's Native-to-ASCII Converter.

## Install

Install using [npm](https://npmjs.com):

``` sh
npm install --save node-native2ascii
```

Or, to be able to access the `native2ascii` command from anywhere:

``` sh
npm install --global node-native2ascii
```

## Usage

### API

#### `native2ascii(input[, options])`

Converts characters within `input` so that it can be encoded in ASCII by using Unicode escapes ("\uxxxx" notation) for
all characters that are not part of the ASCII character set.

This can be useful when dealing with `.properties` files and characters that are not in the ISO-8859-1 character set.

The `reverse` option can be specified to reverse the conversion and instead convert Unicode escapes to their
corresponding Unicode characters.

Characters within the Basic Multilingual Plane (BMP) as well as surrogate pairs for characters outside BMP are
supported.

##### Options

| Option    | Type      | Default | Description                         |
|-----------|-----------|---------|-------------------------------------|
| `reverse` | `boolean` | `false` | Whether the reverse the conversion. |

##### Examples

``` javascript
import { native2ascii } from "node-native2ascii";

native2ascii("I ♥ Unicode!");
//=> "I \\u2665 Unicode!"
native2ascii("𠮷𠮾");
//=> "\\ud842\\udfb7\\ud842\\udfbe"

native2ascii("I \\u2665 Unicode!", { reverse: true });
//=> "I ♥ Unicode!"
native2ascii("\\ud842\\udfb7\\ud842\\udfbe", { reverse: true });
//=> "𠮷𠮾"
```

### CLI

    Usage: native2ascii [options] [input-file] [output-file]

    Options:
      -e, --encoding <encoding>  specify encoding to use (default: "utf8")
      -r, --reverse              perform reverse conversion (default: false)
      -V, --version              output the version number
      -h, --help                 display help for command

Converts a file that is encoded to any character encoding that is
[supported by Node.js](https://nodejs.org/api/buffer.html#buffers-and-character-encodings) (which can be controlled via
the `encoding` command line option) to a file encoded in ASCII, using Unicode escapes ("\uxxxx" notation) for all
characters that are not part of the ASCII character set.

This can be useful when dealing with `.properties` files and characters that are not in the ISO-8859-1 character set.

The `reverse` command line option can be specified to reverse the conversion and instead convert Unicode escapes to
their corresponding Unicode characters.

If the `output-file` command line argument is not specified, standard output is used for output. Additionally, if the
`input-file` command line argument is not specified, standard input is used for input.

#### Examples

Convert a file encoded using UTF-8 into a file encoded using ASCII, Unicode escaping characters not in the ASCII
character set:

``` sh
# Using file command line arguments:
native2ascii utf8.properties ascii.properties
# Using STDIN and STDOUT:
cat utf8.properties | native2ascii > ascii.properties
```

Convert a file encoded using ASCII into a file encoded using UTF-8, unescaping any Unicode escapes:

``` sh
# Using file command line arguments:
native2ascii --reverse ascii.properties utf8.properties
# Using STDIN and STDOUT:
cat ascii.properties | native2ascii --reverse > utf8.properties
```

## Related

* [escape-unicode](https://github.com/neocotic/escape-unicode)
* [properties-store](https://github.com/neocotic/properties-store)
* [unescape-unicode](https://github.com/neocotic/unescape-unicode)

## Bugs

If you have any problems with this package or would like to see changes currently in development, you can do so
[here](https://github.com/neocotic/node-native2ascii/issues).

## Contributors

If you want to contribute, you're a legend! Information on how you can do so can be found in
[CONTRIBUTING.md](https://github.com/neocotic/node-native2ascii/blob/main/CONTRIBUTING.md). We want your suggestions and
pull requests!

A list of all contributors can be found in
[AUTHORS.md](https://github.com/neocotic/node-native2ascii/blob/main/AUTHORS.md).

## License

Copyright © 2025 neocotic

See [LICENSE.md](https://github.com/neocotic/node-native2ascii/raw/main/LICENSE.md) for more information on our MIT
license.

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