node-chromium-pickle-js

chromium-pickle-js ports Chromium’s C++ Pickle class to Node.js, giving JavaScript code the same low-level binary value packing and unpacking facilities Chromium uses internally. It lets callers append primitive values (booleans, ints, 32/64-bit unsigned integers, floats, doubles, and length-prefixed strings) onto a growing in-memory buffer, then read them back in the same order with a companion PickleIterator.

The library is deliberately tiny and dependency-free, mirroring the original Pickle header-plus-payload layout byte for byte so that data produced by Chromium’s native Pickle and by this JS port stay binary-compatible. It has shipped for years as an internal utility inside Electron’s tooling, most notably asar, where it’s used to encode the archive header before Chromium reads it.

What You Get

• A Pickle class with createEmpty() and createFromBuffer() factories for building or parsing a binary pickle
• Typed write methods (writeBool, writeInt, writeUInt32, writeInt64, writeUInt64, writeFloat, writeDouble, writeString) that append values to a self-resizing buffer
• A PickleIterator returned by createIterator() with matching typed read methods that walk the buffer in write order
• Byte-for-byte compatibility with Chromium’s native C++ Pickle format, including its 4-byte alignment and header-size handling
• Zero runtime dependencies — the entire implementation is two small files with no external packages required at install time

Common Use Cases

• Encoding Electron asar archive headers in a format Chromium’s native code can read directly
• Passing structured binary data between a Node.js process and Chromium/native code that expects Pickle-formatted buffers
• Building or parsing any custom binary protocol that needs simple, ordered primitive packing without a full serialization framework
• Interoperating with other Electron tooling that already depends on the Pickle wire format

Under The Hood

Architecture The entire module is two files: lib/pickle.js, which defines both the Pickle class and a nested PickleIterator class as IIFE-wrapped constructors, and lib/exports.js, a thin factory layer exposing only createEmpty() and createFromBuffer(). There’s no separation between serialization logic and public API beyond that thin wrapper — Pickle holds its own header buffer, write offset, and capacity as instance state and mutates them directly in methods like writeBytes, resize, and setPayloadSize, while PickleIterator walks the same underlying buffer sequentially with no independent copy. Data flows one way: values are appended with 4-byte alignment padding via alignInt, and the iterator reads them back in identical order, so the format is a direct, low-level mirror of Chromium’s native Pickle header-plus-payload layout rather than a general abstraction.

Tech Stack The implementation is plain ES5-style JavaScript using var and IIFE module patterns, with zero runtime dependencies declared in package.json — only mocha and standard are listed, and both are devDependencies for testing and linting. All binary I/O goes through Node’s built-in Buffer methods (readInt32LE, writeUInt32LE, readDoubleLE, and so on) with no bundler, transpiler, or TypeScript involved; the package ships its lib/*.js files directly as its main entry with no build step, and a .travis.yml config runs the test suite on push.

Code Quality The test suite consists of a single Mocha test (test/pickle-test.js) that round-trips a multi-byte string through writeString/readString, using Node’s built-in assert module — there’s no coverage of the numeric read/write paths, buffer resizing, or the error path when reading past the end of the buffer. Error handling is inconsistent: getReadPayloadOffsetAndAdvance explicitly throws on an out-of-range read, but the write methods return booleans rather than throwing on failure. There are no type annotations or JSDoc, though naming is terse and consistent (paired write/read methods per type), and standard (StandardJS) lint rules are enforced as part of npm test.

API Design The public surface — createEmpty/createFromBuffer plus mirrored write*/read* methods — requires almost no boilerplate to use and directly follows the naming of Chromium’s original C++ Pickle class, which helps anyone already familiar with Chromium internals but departs from typical Node.js idioms (returning false on write failure rather than throwing). Documentation is limited to the README’s method reference with no worked examples beyond install instructions, reflecting its role as a narrow, single-purpose internal utility for Electron tooling rather than a general-audience library.