@hyrious/marshal

Ruby marshal for the browser and Node.js.

Install

npm add @hyrious/marshal

Usage

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

[^1]: Symbols are always decoded in UTF-8 even if they may have other encodings. [^2]: Instance variables are stored directly as props, i.e. obj[Symbol(@a)] = 1. [^3]: String/symbol/number keys are always decoded as JS object props.

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.

load('\x04\b"\0'); //=> Uint8Array []
load('\x04\bI"\0\x06:\x06ET'); //=> ""

The special instance variables are:

So for strict compatibility, you should check if a string is Uint8Array before using it:

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.

Symbols

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.

Hash

This library decodes Hash as plain object by default, which means unusual keys like an object is ignored. However, it is still possible to keep these keys using Map or wrapper classes, see options.hash.

Instance Variables

This library decodes instance variables (often @a = 1) as object props. It is guaranteed that you can retrieve these properties using Object.getOwnPropertySymbols(). It is possible to convert these symbols to strings, see options.ivarToString.

API Reference

FAQ

ChangeLog

Develop

• Run npm t to run tests.
• Run npm t clone to only run clone.ts.

Reference

• marshal.c
• Marshal Format (official doc)
• node marshal
• @qnighy/marshal
• A little/another/final dip into Ruby's Marshal format

License

MIT @ hyrious

Changelog

0.3.3

• Add regexp: wrap to wrap ruby regexp in RubyRegexp.

0.3.2

• Add string: utf8 | binary in load() to force decode or not decode strings.

0.3.1

• Fix load(string) should decode string in each code manually.

0.3.0

• :warning: BREAKING. Read the API Reference to learn the new API.

0.2.5

• hashToJS now also accepts number (Integer, Float) keys.

0.2.4

• Fix mutating default options.

0.2.3

• Add clone(x, opt) as a shortcut to load(dump(x), opt).

0.2.2

• Fix hashToJS, hashToMap with nested hashes.

0.2.1

• Fix dump Bignum logic.
• Fix dump Hash with default value.
• Fix instance variables logic.
• Add RubyRange, RubyTime helper classes.

0.2.0

• Refactored a lot to make this package smaller.
• Fix T_EXTENDED parse and dump behavior.
• Support dump circular objects.

0.1.6

• esbuild has inline enum, this package can be smaller and run quicker.

0.1.5

• Changed exports field in package.json so that it always use ESM when bundling to browser.

0.1.4

• Fixed parsing circular objects.

0.1.3

• Added load option decodeString: false and wrapString: true

0.1.2

• Fixed dump(new RubyObject()) generates wrong marshal data

0.1.0

• Added load(arrayBuffer) to parse marshal data
• Added dump(value) to dump marshal data (not strictly equal to the ruby ones)