{"id":13727225,"url":"https://github.com/amazon-ion/ion-js","last_synced_at":"2025-04-11T23:17:10.269Z","repository":{"id":20707872,"uuid":"72466336","full_name":"amazon-ion/ion-js","owner":"amazon-ion","description":"A JavaScript implementation of Amazon Ion.","archived":false,"fork":false,"pushed_at":"2024-09-03T23:18:15.000Z","size":4052,"stargazers_count":358,"open_issues_count":92,"forks_count":49,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-04-03T05:11:14.495Z","etag":null,"topics":["ion","javascript"],"latest_commit_sha":null,"homepage":"http://amzn.github.io/ion-docs/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amazon-ion.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-10-31T18:31:32.000Z","updated_at":"2025-04-02T20:15:53.000Z","dependencies_parsed_at":"2024-04-30T17:38:22.861Z","dependency_job_id":"295b673a-12ab-43c7-bae9-a5dea546a1cf","html_url":"https://github.com/amazon-ion/ion-js","commit_stats":null,"previous_names":["amzn/ion-js"],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amazon-ion%2Fion-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amazon-ion%2Fion-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amazon-ion%2Fion-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amazon-ion%2Fion-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amazon-ion","download_url":"https://codeload.github.com/amazon-ion/ion-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248103864,"owners_count":21048245,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ion","javascript"],"created_at":"2024-08-03T01:03:44.962Z","updated_at":"2025-04-11T23:17:10.250Z","avatar_url":"https://github.com/amazon-ion.png","language":"TypeScript","readme":"# Amazon Ion JavaScript\nAn implementation of [Amazon Ion](https://amazon-ion.github.io/ion-docs/) for JavaScript written in TypeScript.\n\n[![NPM Version](https://img.shields.io/npm/v/ion-js.svg)](https://www.npmjs.com/package/ion-js)\n[![License](https://img.shields.io/hexpm/l/plug.svg)](https://github.com/amazon-ion/ion-js/blob/master/LICENSE)\n[![Documentation](https://img.shields.io/badge/docs-api-green.svg)](https://amazon-ion.github.io/ion-js/api/index.html)\n\nThis package is tested with Node JS major versions **14**, **16**, and **18**.  While this library\nshould be usable within browsers that support **ES5+**, please note that it is not currently being tested\nin any browser environments.\n\n## Getting Started\n\nYou can use this library either as a Node.js module or inside an HTML page.\n\n### NPM\n\n1. Add `ion-js` to your dependencies using `npm`\n    ```\n    npm install --save ion-js\n    ```\n1. Use the library to read/write Ion data. Here is an example that reads Ion data from a JavaScript string:\n    ```javascript\n    let ion = require(\"ion-js\");\n    \n    // Reading\n    let ionData = '{ greeting: \"Hello\", name: \"Ion\" }';\n    let value = ion.load(ionData);\n    console.log(value.greeting + \", \" + value.name + \"!\");\n   \n    // Writing\n    let ionText = ion.dumpText(value);\n    console.log(\"Serialized Ion: \" + ionText);\n    ```\n   \n   For more examples, see the [Ion DOM `README`](/src/dom/README.md).\n\n[Try it yourself](https://npm.runkit.com/ion-js).\n\n**Note:** if your package's public interface exposes part of this library, this library should be specified\nas a peer dependency in your package's package.json file.  Otherwise, packages that depend on your package\n*and* this library may experience unexpected behavior, as two installations of this library (even if the same\nversion) are not designed or tested to behave correctly.\n\n### Web Browser\n\nYou can include the Ion-js bundle (ES5 compatible) using the URLs\n\n* [ion-bundle.min.js](https://amazon-ion.github.io/ion-js/browser/scripts/ion-bundle.min.js)\n* [ion-bundle.js](https://amazon-ion.github.io/ion-js/browser/scripts/ion-bundle.js)\n\nThese will create and initialize `window.ion` which has the same exact API as our `npm` package. Here is an example\n\n```html\n\u003chtml\u003e\n\u003chead\u003e\n  \u003cmeta charset=\"UTF-8\"/\u003e\n  \u003cscript src=\"scripts/ion-bundle.min.js\"\u003e\u003c/script\u003e\n\n  \u003c!-- more HTML/JS code that can now use `window.ion` to create/write Ion --\u003e\n\u003c/head\u003e\n\u003c/html\u003e\n```\n\n### API\n\n[TypeDoc](https://typedoc.org/) generated documentation can be found at [here](https://amazon-ion.github.io/ion-js/api/).\nPlease note that anything not documented in the the API documentation is not supported for public use and is\nsubject to change in any version.\n\n## Git Setup\n\nThis repository contains a [git submodule](https://git-scm.com/docs/git-submodule)\ncalled `ion-tests`, which holds test data used by `ion-js`'s unit tests.\n\nThe easiest way to clone the `ion-js` repository and initialize its `ion-tests`\nsubmodule is to run the following command.\n\n```\n$ git clone --recursive https://github.com/amazon-ion/ion-js.git ion-js\n```\n\nAlternatively, the submodule may be initialized independently from the clone\nby running the following commands.\n\n```\n$ git submodule init\n$ git submodule update\n```\n\n## Development\n\nUse `npm` to setup the dependencies.  In the project directory you can run the following:\n\n```\n$ npm install\n```\n\nBuilding the package can be done with the release script (which runs the tests).\n\n```\n$ npm run release\n```\n\nTests can be run using npm as well\n\n```\n$ npm test\n```\n\nThis package uses [Grunt](https://gruntjs.com/) for its build tasks.  For convenience, you may want to install\nthis globally:\n\n```\n$ npm -g install grunt-cli\n$ grunt release\n```\n\nOr you could use the locally installed Grunt:\n\n```\n$ ./node_modules/.bin/grunt release\n```\n\n### Build Output\n\nThe build above will compile the library into the `dist` directory.  This directory has subdirectories of\nthe form `\u003cmodule type\u003e/\u003ctarget ES version\u003e`.  In general, we target ES6 and rely on polyfills to support earlier\nversions.\n\n* `dist/es6/es6` - Targets the ES6 module system and ES6\n* `dist/commonjs/es6` - Targets the CommonJS module system and ES6 \n* `dist/amd/es6` - Targets the AMD module system and ES6\n\nA distribution using `browserify` and `babelify` creates a browser friendly polyfilled distribution targeting ES5:\nat `dist/browser/js/ion-bundle.js`.\n\n## Ion Specification Support\n\n| Types                     | IonText       | IonBinary     | Limitations                                   |\n|:-------------------------:|:-------------:|:-------------:|:---------------------------------------------:|\n| `null`                    | yes           | yes           | none                                          |\n| `bool`                    | yes           | yes           | none                                          |\n| `int`                     | yes           | yes           | underscores, binary digits                    |\n| `float`                   | yes           | yes           | underscores                                   |\n| `decimal`                 | yes           | yes           | none                                          |\n| `timestamp`               | yes           | yes           | none                                          |\n| `string`                  | yes           | yes           | none                                          |\n| `symbol`                  | yes           | yes           | `$0`, symbol tokens                           |\n| `blob`                    | yes           | yes           | none                                          |\n| `clob`                    | yes           | yes           | none                                          |\n| `struct`                  | yes           | yes           | none                                          |\n| `list`                    | yes           | yes           | none                                          |\n| `sexp`                    | yes           | yes           | none                                          |\n| annotations               | yes           | yes           | none                                          |\n| local symbol tables       | yes           | yes           | none                                          |\n| shared symbol tables      | no            | yes           | none                                          |\n\nNotes:\n* [test/iontests.ts](https://github.com/amazon-ion/ion-js/blob/master/test/iontests.ts) defines multiple skipList variables\n  referencing test vectors that are not expected to work at this time.\n\n* ion-js supports shared symbol table for Ion Binary. Below is an example of how shared symbol table can be used here: \n```javascript\n// Create a SharedSymbolTable with the desired strings\nlet sharedSymbolTable = new SharedSymbolTable('foo', 1, ['id', 'name']);\n// Define an import chain\n// The system symbol table does not import any other tables (`null` below)\nlet systemSymbolTableImport = new Import(null, getSystemSymbolTable());\n// The shared symbol table imports the system symbol table\nlet sharedSymbolTableImport = new Import(systemSymbolTableImport, sharedSymbolTable);\n// Create a local symbol table that imports the shared symbol table\nlet localSymbolTable = new LocalSymbolTable(sharedSymbolTableImport);\n// Create a writer that uses our new local symbol table\nlet writer = new BinaryWriter(localSymbolTable, new Writeable());\n\n// Write id and name fields in a struct\nwriter.stepIn(IonTypes.STRUCT);\nwriter.writeFieldName(\"id\");\nwriter.writeInt(5);\nwriter.writeFieldName(\"name\");\nwriter.writeString(\"Max\");\nwriter.stepOut();\nwriter.close();\n\n// Create a catalog with shared symbol table\nlet catalog = new Catalog();\ncatalog.add(sharedSymbolTable);\n\n// Create a reader with catalog\nlet bytes = writer.getBytes();\nlet reader = makeReader(bytes, catalog);\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md)\n\n## License\n\nThis library is licensed under [Apache License version 2.0](LICENSE)\n\n## Links\nFor more information about Ion or its other implementation, please see:\n\n* [Ion](https://amazon-ion.github.io/ion-docs/)\n* [Ion Specification](https://amazon-ion.github.io/ion-docs/spec.html)\n* [Ion Cookbook](https://amazon-ion.github.io/ion-docs/cookbook.html) uses the Java library for its examples.\n* [Ion C](https://github.com/amazon-ion/ion-c)\n* [Ion Java](https://github.com/amazon-ion/ion-java)\n* [Ion Python](https://github.com/amazon-ion/ion-python)\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famazon-ion%2Fion-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famazon-ion%2Fion-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famazon-ion%2Fion-js/lists"}