https://github.com/hyrious/marshal
Ruby marshal for the browser and Node.js
https://github.com/hyrious/marshal
Last synced: 7 months ago
JSON representation
Ruby marshal for the browser and Node.js
- Host: GitHub
- URL: https://github.com/hyrious/marshal
- Owner: hyrious
- License: mit
- Created: 2021-05-28T10:20:18.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2025-01-10T06:44:27.000Z (over 1 year ago)
- Last Synced: 2025-10-24T04:27:45.512Z (7 months ago)
- Language: TypeScript
- Homepage:
- Size: 290 KB
- Stars: 16
- Watchers: 2
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# @hyrious/marshal
Ruby marshal for the browser and Node.js.
## Install
```
npm add @hyrious/marshal
```
## Usage
```ts
import { dump, load } from "@hyrious/marshal";
dump(null); // Uint8Array(3) [ 4, 8, 48 ]
load("\x04\b0"); // null
// in Node.js
load(fs.readFileSync("data"));
// in Browser
load(await file.arrayBuffer());
```
### Ruby ↔ JavaScript
| Ruby | JavaScript |
| ------------ | -------------------------------------- |
| `nil` | `null` |
| `"string"` | `"string"` |
| `:symbol` | `Symbol("symbol")` |
| `123456` | `123456` (number) |
| `123.456` | `123.456` (number) |
| `/cat/im` | `/cat/im` (RegExp) |
| `[]` | `[]` |
| `{}` | `{}` (plain object) |
| `Object.new` | `RubyObject { class: Symbol(object) }` |
#### String
Because users may store binary data that cannot be decoded as UTF-8 in Ruby,
strings are decoded into `Uint8Array` firstly, then converted to `string`
using `TextDecoder` if seeing an instance variable indicating the encoding.
```js
load('\x04\b"\0'); //=> Uint8Array []
load('\x04\bI"\0\x06:\x06ET'); //=> ""
```
The special instance variables are:
| name | value | encoding |
| ----------- | ------------ | ------------- |
| `:E` | true / false | UTF-8 / ASCII |
| `:encoding` | "enc" | enc |
So for strict compatibility, you should check if a string is Uint8Array before using it:
```js
var a = load(data);
if (a instanceof Uint8Array) a = decode(a); // if you know it must be a string
if (typeof a === "string") do_something(a);
```
Or you can use `options.string` to control the behavior, see [options.string](./docs/api.md#optionsstring-utf8--binary).
#### Symbols
Symbols are always decoded in UTF-8 even if they may have other encodings.
You can use `Symbol.keyFor(sym)` in JavaScript to get the symbol name in string.
#### RegExp
Only `i` (ignore case) and `m` (multi-line) flags are preserved.
However, it is still possible to read all flags by wrapper class, see [options.regexp](./docs/api.md#optionsregexp-wrap).
#### Hash
This library decodes Hash as plain object by default, string/symbol/number
keys are always decoded as JS object props, which means unusual keys like
an object are ignored. However, it is still possible to keep these keys
using `Map` or wrapper classes, see [options.hash](./docs/api.md#optionshash-map--wrap).
#### Instance Variables
This library decodes instance variables (often `@a = 1`) as object props, i.e. `obj[Symbol(@a)] = 1`.
It is guaranteed that you can retrieve these properties using `Object.getOwnPropertySymbols()`.
It is possible to convert these symbols to strings, see [options.ivarToString](./docs/api.md#optionsivartostring-true--string).
### [API Reference](./docs/api.md)
### [FAQ](./docs/faq.md)
### [ChangeLog](./CHANGELOG.md)
### Develop
- Run `npm t` to run tests.
- Run `npm t clone` to only run `clone.ts`.
### Reference
- [marshal.c](https://github.com/ruby/ruby/blob/master/marshal.c)
- [Marshal Format](https://github.com/ruby/ruby/blob/master/doc/marshal.rdoc) (official doc)
- [node marshal](https://github.com/clayzermk1/node-marshal)
- [@qnighy/marshal](https://github.com/qnighy/marshal-js)
- A [little](http://jakegoulding.com/blog/2013/01/15/a-little-dip-into-rubys-marshal-format)/[another](http://jakegoulding.com/blog/2013/01/16/another-dip-into-rubys-marshal-format)/[final](http://jakegoulding.com/blog/2013/01/20/a-final-dip-into-rubys-marshal-format) dip into Ruby's Marshal format
## License
MIT @ [hyrious](https://github.com/hyrious)