msgpack-lite

Common errors

• TypeError: msgpack.encode is not a function

  cause This typically occurs when trying to destructure the `msgpack` object incorrectly or when using `import { encode } from 'msgpack-lite';` in an unsupported environment.
  fix Ensure you are using `const msgpack = require('msgpack-lite');` and then calling `msgpack.encode()` or `msgpack.decode()`. The module does not provide named exports for ES Modules.

• TypeError: data must be a Buffer or an Array or a Uint8Array

  cause The `decode` function received an argument that is not a valid binary type (Node.js Buffer, standard JavaScript Array of numbers, or Uint8Array).
  fix Ensure the input to `msgpack.decode()` is a `Buffer` (in Node.js), a `Uint8Array`, or a simple `Array` containing byte values (e.g., `[0x81, 0xA3, ...]`). Do not pass raw strings or other object types.

• Error: read after end

  cause This error can occur when trying to read from a stream that has already ended or when stream piping/handling is incorrectly set up, leading to attempts to process data from a closed stream.
  fix Verify that your stream pipeline is correctly configured. Ensure `encodeStream.end()` is called only once all data is written and that subsequent operations respect the stream's state. For reading, ensure `pipe()` is set up before data is expected, and handle `end` events to signal completion.

Warnings

• breaking The `msgpack-lite` package is no longer actively maintained, with its last publish occurring over 8 years ago. This means there will be no updates for new features, bug fixes, or critical security vulnerabilities. Users should consider migrating to actively maintained MessagePack libraries like `@msgpack/msgpack` or `msgpackr` for modern applications.
  Fix: Migrate to an actively maintained MessagePack library (e.g., `npm install @msgpack/msgpack` or `npm install msgpackr`). Be aware that API changes will require code refactoring.
• gotcha This library is designed for CommonJS (`require`) environments and does not natively support ES Modules (`import`). Using `import` syntax directly in a Node.js ESM context or without proper bundler configuration for browsers will result in module resolution errors.
  Fix: Always use `const msgpack = require('msgpack-lite');` for Node.js. For browser environments, use the provided `msgpack.min.js` directly via a `<script>` tag or configure a bundler (like Browserify, as suggested in the old README) to handle CommonJS modules.
• gotcha The library primarily deals with Node.js `Buffer` objects for binary data. While it accepts `Uint8Array` for decoding, its core operations in Node.js often produce and expect `Buffer` instances. In modern Node.js, `new Buffer()` is deprecated in favor of `Buffer.from()`, `Buffer.alloc()`, or `Buffer.allocUnsafe()`. Older code examples or existing data might use `new Buffer()`, which could lead to runtime warnings or security issues if not updated.
  Fix: When creating `Buffer` instances from raw data, use `Buffer.from(array)` or `Buffer.from(string, encoding)` instead of `new Buffer()`. When allocating new, uninitialized buffers, use `Buffer.alloc()` or `Buffer.allocUnsafe()`.
• gotcha Due to its age and lack of maintenance, `msgpack-lite`'s performance claims (being faster than C++ based `msgpack` on Node.js v4) are likely outdated. Modern MessagePack implementations and V8 engine optimizations have significantly advanced.
  Fix: For high-performance or modern Node.js/browser applications, benchmark `msgpack-lite` against current alternatives like `@msgpack/msgpack` or `msgpackr` within your specific use case to determine actual performance characteristics.

Install

• npm install msgpack-lite npm
• yarn add msgpack-lite yarn
• pnpm add msgpack-lite pnpm

Imports

• msgpack
  wrong:

  import msgpack from 'msgpack-lite';

  correct:

  const msgpack = require('msgpack-lite');

  This library is CommonJS-only and does not provide native ES Module exports. Attempting to use `import` syntax will fail in Node.js environments unless transpiled or configured with a bundler for browser usage.
• encode, decode
  wrong:

  import { encode, decode } from 'msgpack-lite';

  correct:

  const { encode, decode } = require('msgpack-lite'); // Not recommended for direct destructuring
  // Or, preferably:
  const msgpack = require('msgpack-lite');
  const encoded = msgpack.encode(data);

  While CommonJS allows destructuring `require` results, the primary export is the `msgpack` object, and accessing `encode` and `decode` as properties (`msgpack.encode`, `msgpack.decode`) is the intended and most robust pattern. Direct destructuring can sometimes lead to context issues or subtle bugs depending on the module loader.
• createEncodeStream, createDecodeStream
  wrong:

  import { createEncodeStream } from 'msgpack-lite';

  correct:

  const msgpack = require('msgpack-lite');
  const encodeStream = msgpack.createEncodeStream();

  These streaming utilities are methods on the main `msgpack` export and are accessed after requiring the entire module. They are specifically for Node.js stream environments.

Quickstart

This quickstart demonstrates both synchronous MessagePack encoding/decoding and the use of streaming APIs to write and read multiple MessagePack objects to/from a file, including proper error handling and cleanup for the file system operations.

const fs = require('fs');
const msgpack = require('msgpack-lite');

// Example 1: Basic synchronous encoding and decoding
const dataToSend = { id: 1, message: 'Hello, MessagePack!', timestamp: Date.now() };
const buffer = msgpack.encode(dataToSend);
console.log('Encoded buffer:', buffer.toString('hex'));
const decodedData = msgpack.decode(buffer);
console.log('Decoded data:', decodedData);

// Example 2: Streaming encoding and decoding
// Prepare a dummy file path for demonstration
const filePath = 'temp_data.msp';

const writeStream = fs.createWriteStream(filePath);
const encodeStream = msgpack.createEncodeStream();

encodeStream.pipe(writeStream);

encodeStream.write({ event: 'start', time: Date.now() });
encodeStream.write({ user: 'Alice', action: 'login' });
encodeStream.write({ user: 'Bob', action: 'logout' });

// Ensure stream closes after all data is written
encodeStream.end(() => {
  console.log(`
Successfully wrote MessagePack data to ${filePath}`);

  // Now read from the stream
  const readStream = fs.createReadStream(filePath);
  const decodeStream = msgpack.createDecodeStream();

  console.log('Decoding stream data:');
  readStream.pipe(decodeStream).on('data', (obj) => {
    console.log('Stream decoded object:', obj);
  });

  decodeStream.on('end', () => {
    console.log('Finished decoding stream.');
    fs.unlinkSync(filePath); // Clean up the dummy file
  });

  decodeStream.on('error', (err) => {
    console.error('Error decoding stream:', err);
    fs.unlinkSync(filePath); // Clean up on error
  });
});

writeStream.on('error', (err) => {
  console.error('Error writing to stream:', err);
  fs.unlinkSync(filePath); // Clean up on error
});