# ion-js

> A JavaScript implementation of the Ion data interchange format

Latest version **5.2.1** (published 2024-04-30) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install ion-js
pnpm add ion-js
yarn add ion-js
bun add ion-js
```

## Health

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

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

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 5.2.1 |
| Published | 2024-04-30 |
| First published | 2017-05-09 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 1.4 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | The Ion Team |
| Maintainers | ion-team |
| Keywords | ion, JSON, data format |

## Links

- npm: https://www.npmjs.com/package/ion-js
- Repository: https://github.com/amazon-ion/ion-js
- Homepage: https://github.com/amazon-ion/ion-js#readme
- Issues: https://github.com/amazon-ion/ion-js/issues
- npm.io page: https://npm.io/package/ion-js

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 5.2.1 (latest) — 2024-04-30
- 3.0.0-beta.3 (beta) — 2019-02-18
- 5.2.0 — 2023-09-07
- 5.1.0 — 2023-07-24
- 5.0.0 — 2023-04-25
- 4.3.0 — 2022-05-10
- 4.2.3 — 2022-05-05
- 4.2.2 — 2022-03-17
- 4.2.1 — 2021-05-07
- 4.2.0 — 2021-05-05
- 4.1.0 — 2020-12-02
- 4.0.1 — 2020-05-27
- 4.0.0 — 2020-03-30
- 3.1.2 — 2019-10-29
- 3.1.1 — 2019-10-29
- … 13 more at https://npm.io/package/ion-js/versions

## README

# Amazon Ion JavaScript
An implementation of [Amazon Ion](https://amazon-ion.github.io/ion-docs/) for JavaScript written in TypeScript.

[![NPM Version](https://img.shields.io/npm/v/ion-js.svg)](https://www.npmjs.com/package/ion-js)
[![License](https://img.shields.io/hexpm/l/plug.svg)](https://github.com/amazon-ion/ion-js/blob/master/LICENSE)
[![Documentation](https://img.shields.io/badge/docs-api-green.svg)](https://amazon-ion.github.io/ion-js/api/index.html)

This package is tested with Node JS major versions **14**, **16**, and **18**.  While this library
should be usable within browsers that support **ES5+**, please note that it is not currently being tested
in any browser environments.

## Getting Started

You can use this library either as a Node.js module or inside an HTML page.

### NPM

1. Add `ion-js` to your dependencies using `npm`
    ```
    npm install --save ion-js
    ```
1. Use the library to read/write Ion data. Here is an example that reads Ion data from a JavaScript string:
    ```javascript
    let ion = require("ion-js");
    
    // Reading
    let ionData = '{ greeting: "Hello", name: "Ion" }';
    let value = ion.load(ionData);
    console.log(value.greeting + ", " + value.name + "!");
   
    // Writing
    let ionText = ion.dumpText(value);
    console.log("Serialized Ion: " + ionText);
    ```
   
   For more examples, see the [Ion DOM `README`](/src/dom/README.md).

[Try it yourself](https://npm.runkit.com/ion-js).

**Note:** if your package's public interface exposes part of this library, this library should be specified
as a peer dependency in your package's package.json file.  Otherwise, packages that depend on your package
*and* this library may experience unexpected behavior, as two installations of this library (even if the same
version) are not designed or tested to behave correctly.

### Web Browser

You can include the Ion-js bundle (ES5 compatible) using the URLs

* [ion-bundle.min.js](https://amazon-ion.github.io/ion-js/browser/scripts/ion-bundle.min.js)
* [ion-bundle.js](https://amazon-ion.github.io/ion-js/browser/scripts/ion-bundle.js)

These will create and initialize `window.ion` which has the same exact API as our `npm` package. Here is an example

```html
<html>
<head>
  <meta charset="UTF-8"/>
  <script src="scripts/ion-bundle.min.js"></script>

  <!-- more HTML/JS code that can now use `window.ion` to create/write Ion -->
</head>
</html>
```

### API

[TypeDoc](https://typedoc.org/) generated documentation can be found at [here](https://amazon-ion.github.io/ion-js/api/).
Please note that anything not documented in the the API documentation is not supported for public use and is
subject to change in any version.

## Git Setup

This repository contains a [git submodule](https://git-scm.com/docs/git-submodule)
called `ion-tests`, which holds test data used by `ion-js`'s unit tests.

The easiest way to clone the `ion-js` repository and initialize its `ion-tests`
submodule is to run the following command.

```
$ git clone --recursive https://github.com/amazon-ion/ion-js.git ion-js
```

Alternatively, the submodule may be initialized independently from the clone
by running the following commands.

```
$ git submodule init
$ git submodule update
```

## Development

Use `npm` to setup the dependencies.  In the project directory you can run the following:

```
$ npm install
```

Building the package can be done with the release script (which runs the tests).

```
$ npm run release
```

Tests can be run using npm as well

```
$ npm test
```

This package uses [Grunt](https://gruntjs.com/) for its build tasks.  For convenience, you may want to install
this globally:

```
$ npm -g install grunt-cli
$ grunt release
```

Or you could use the locally installed Grunt:

```
$ ./node_modules/.bin/grunt release
```

### Build Output

The build above will compile the library into the `dist` directory.  This directory has subdirectories of
the form `<module type>/<target ES version>`.  In general, we target ES6 and rely on polyfills to support earlier
versions.

* `dist/es6/es6` - Targets the ES6 module system and ES6
* `dist/commonjs/es6` - Targets the CommonJS module system and ES6 
* `dist/amd/es6` - Targets the AMD module system and ES6

A distribution using `browserify` and `babelify` creates a browser friendly polyfilled distribution targeting ES5:
at `dist/browser/js/ion-bundle.js`.

## Ion Specification Support

| Types                     | IonText       | IonBinary     | Limitations                                   |
|:-------------------------:|:-------------:|:-------------:|:---------------------------------------------:|
| `null`                    | yes           | yes           | none                                          |
| `bool`                    | yes           | yes           | none                                          |
| `int`                     | yes           | yes           | underscores, binary digits                    |
| `float`                   | yes           | yes           | underscores                                   |
| `decimal`                 | yes           | yes           | none                                          |
| `timestamp`               | yes           | yes           | none                                          |
| `string`                  | yes           | yes           | none                                          |
| `symbol`                  | yes           | yes           | `$0`, symbol tokens                           |
| `blob`                    | yes           | yes           | none                                          |
| `clob`                    | yes           | yes           | none                                          |
| `struct`                  | yes           | yes           | none                                          |
| `list`                    | yes           | yes           | none                                          |
| `sexp`                    | yes           | yes           | none                                          |
| annotations               | yes           | yes           | none                                          |
| local symbol tables       | yes           | yes           | none                                          |
| shared symbol tables      | no            | yes           | none                                          |

Notes:
* [test/iontests.ts](https://github.com/amazon-ion/ion-js/blob/master/test/iontests.ts) defines multiple skipList variables
  referencing test vectors that are not expected to work at this time.

* ion-js supports shared symbol table for Ion Binary. Below is an example of how shared symbol table can be used here: 
```javascript
// Create a SharedSymbolTable with the desired strings
let sharedSymbolTable = new SharedSymbolTable('foo', 1, ['id', 'name']);
// Define an import chain
// The system symbol table does not import any other tables (`null` below)
let systemSymbolTableImport = new Import(null, getSystemSymbolTable());
// The shared symbol table imports the system symbol table
let sharedSymbolTableImport = new Import(systemSymbolTableImport, sharedSymbolTable);
// Create a local symbol table that imports the shared symbol table
let localSymbolTable = new LocalSymbolTable(sharedSymbolTableImport);
// Create a writer that uses our new local symbol table
let writer = new BinaryWriter(localSymbolTable, new Writeable());

// Write id and name fields in a struct
writer.stepIn(IonTypes.STRUCT);
writer.writeFieldName("id");
writer.writeInt(5);
writer.writeFieldName("name");
writer.writeString("Max");
writer.stepOut();
writer.close();

// Create a catalog with shared symbol table
let catalog = new Catalog();
catalog.add(sharedSymbolTable);

// Create a reader with catalog
let bytes = writer.getBytes();
let reader = makeReader(bytes, catalog);
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md)

## License

This library is licensed under [Apache License version 2.0](LICENSE)

## Links
For more information about Ion or its other implementation, please see:

* [Ion](https://amazon-ion.github.io/ion-docs/)
* [Ion Specification](https://amazon-ion.github.io/ion-docs/spec.html)
* [Ion Cookbook](https://amazon-ion.github.io/ion-docs/cookbook.html) uses the Java library for its examples.
* [Ion C](https://github.com/amazon-ion/ion-c)
* [Ion Java](https://github.com/amazon-ion/ion-java)
* [Ion Python](https://github.com/amazon-ion/ion-python)

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