@savannstm/marshal

TypeScript implementation of Ruby Marshal, that can be used both in browser and in Node.js. This project is a fork of @hyrious/marshal, rewritten according to ES6 standards and adding some additional features.

Installation

npm i @savannstm/marshal

Usage

import { dump, load } from "@savannstm/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());

Overview

This library has two main functions: load() and dump(). load() takes a Uint8Array, ArrayBuffer or string, consisting of Marshal data bytes as its only argument, and outputs JSON object. dump() takes a JavaScript object, and outputs respective Marshal Uint8Array of bytes.

Note

This library does NOT write object links in dump(). Because of it, it may produce larger files than initial. Otherwise, it shouldn't affect output files in any other way. It you want to help with solving this problem, consider submitting a pull request.

load() serializes Ruby data to JSON using the table:

| Ruby object | Serialized to JSON | | ---------------------------------------------- | ------------------------------------------------------------------------------ | | nil | null | | 1337 (Integer) | 1337 | | 36893488147419103232 (Big Integer) | { __type: "bigint", value: "36893488147419103232" } (Plain object) | | 13.37 (Float) | 13.37 | | "ligma" (String) | "ligma" | | :ligma (Symbol) | "__symbol__ligma" | | /ligma/xim (Regex) | { "__type": "regexp", "expression": "ligma", "flags": "xim" } (Plain object) | | [] (Array) | [] | | {} (Hash) | {} (Plain object) | | Object.new (Including structs, modules etc.) | { "__class": "__symbol__Object", "__type": "object" } (Plain object) |

String

By default, Ruby strings that include encoding instnace variable are serialized to JSON strings, and those which don't, serialized to { __type: "bytes", data: [...] } objects.

This behavior can be controlled with the stringMode option of load() function.

stringMode: "utf8" tries to convert arrays without instance variable to string, and produces string if array is valid UTF8, and object otherwise.

stringMode: "binary" converts all strings to objects.

Symbols

Symbols are always decoded in UTF-8 even if they may have other encodings.

Instance Variables

Instance variables always decoded as strings with __symbol__ prefix. You can manage the prefix of instance variables using instance_var_prefix argument in load() and dump(). Passed string replaces "@" instance variables' prefixes.

Stringifying load()ed JSON objects

Implementation of this library allows you to stringify load()ed JSON objects out of the box.

API Reference

FAQ

Changelog

Development

• Run npm test to run tests.

Reference

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

License

MIT @ hyrious