Data Encoding/Decoding for Database Records

1.0.1 verified Thu Apr 23 auth: no javascript abandoned

This package offers low-level utilities for deterministically encoding and decoding JavaScript records into binary formats suitable for database storage, particularly within contexts like B-trees or LevelDB-style key-value stores. It provides an `Encoder` class that accepts a schema-like definition of fields, allowing developers to precisely control the binary representation of structured data. This deterministic encoding is crucial for correct sorting and indexing in ordered data structures. The library is currently at version 1.0.1 and has not received updates in approximately ten years, indicating it is no longer actively maintained. Its core functionality revolves around efficient, type-aware binary serialization and deserialization of objects to and from Node.js `Buffer` instances, a key differentiator for performance-critical database operations over more generic serialization methods like JSON. The `Encoder` also exposes a `compare` method for comparing encoded binary records directly.

Common errors

error ReferenceError: require is not defined ↓

cause Attempting to `require('encode')` in a JavaScript module configured as ES Module (e.g., `type: "module"` in package.json or using `.mjs` extension).

fix

Change the module to CommonJS (.js without type: "module") or use a dynamic import('encode') call within an async function in your ESM code. Example: const { Encoder } = await import('encode');

error TypeError: Encoder is not a constructor ↓

cause Incorrectly importing the `Encoder` in a CommonJS module, such as attempting `const { Encoder } = require('encode');` when the module exports directly, or using an ESM `import` in a CJS file that hasn't been transpiled.

fix

The package exports the Encoder class as the module's default export. Use const Encoder = require('encode'); for CommonJS environments.

Warnings

breaking The package is CommonJS only. Attempting to use `import` syntax (ESM) directly will result in a runtime error like 'require is not defined' in an ESM module context. There are no official ESM builds or compatibility layers provided. ↓

fix Use `const Encoder = require('encode');` in CommonJS modules. For ESM projects, consider dynamic import (`import('encode').then(mod => const Encoder = mod)`) or transpilation if full ESM integration is required.

gotcha This package has not been updated in approximately 10 years and is considered abandoned. While it may still function for its intended purpose, there will be no future updates, bug fixes, or security patches. Compatibility with newer Node.js versions or JavaScript features is not guaranteed. ↓

fix Evaluate carefully before adopting for new projects. For existing projects, consider migrating to actively maintained alternatives if long-term support or modern features are critical.

gotcha The library does not ship with TypeScript type definitions. Developers using TypeScript will need to create their own declaration files (`.d.ts`) or use a generic `declare module 'encode';` to avoid type errors. ↓

fix Create a `declare module 'encode';` file (e.g., `types/encode.d.ts`) or provide more specific typings for the `Encoder` class and its methods manually if type safety is required.

gotcha The encoding is strictly based on the defined schema. Incorrect or mismatched data types in the input object compared to the schema, or attempting to decode a `Buffer` not created by the same schema, will lead to unexpected values, errors, or data corruption. ↓

fix Ensure that the input data strictly conforms to the `Encoder`'s schema during encoding, and that the same schema (or a compatible one) is used for decoding. Validate input data before encoding.

Install

npm install encode

yarn add encode

pnpm add encode

Imports

Encoder
wrong
```
import { Encoder } from 'encode'
```
correct
```
const Encoder = require('encode')
```
This package is CommonJS only; direct ESM `import` statements will fail. Use dynamic import for ESM compatibility or stick to `require()` in CJS environments.
encodeInstance.encode
```
const encoded = encoder.encode(record)
```
The `encode` method serializes a JavaScript object into a Node.js `Buffer` based on the defined schema.
encodeInstance.decode
```
const decoded = encoder.decode(buffer)
```
The `decode` method deserializes a Node.js `Buffer` back into a JavaScript object according to the `Encoder`'s schema.

Quickstart

Demonstrates defining an `Encoder` schema, encoding a JavaScript object into a binary `Buffer`, decoding it back, and using the built-in comparator.

const Encoder = require('encode');
const { v4: uuidv4 } = require('uuid'); // Peer dependency for UUID type

// Define a schema for a user record
const userSchema = [
  { name: 'id', type: 'uuid' },
  { name: 'age', type: 'uint32' },
  { name: 'name', type: 'string' },
  { name: 'isActive', type: 'uint8', map: { true: 1, false: 0 } } // Map boolean to uint8
];

const userEncoder = new Encoder(userSchema);

// Example record to encode
const userId = uuidv4();
const userRecord = {
  id: userId,
  age: 30,
  name: 'Alice Smith',
  isActive: true
};

console.log('Original record:', userRecord);

// Encode the record
const encodedBuffer = userEncoder.encode(userRecord);
console.log('Encoded buffer (hex):', encodedBuffer.toString('hex'));

// Decode the buffer back to a record
const decodedRecord = userEncoder.decode(encodedBuffer);
console.log('Decoded record:', decodedRecord);

// Demonstrate the comparator for two records
const userRecord2 = {
  id: uuidv4(),
  age: 25,
  name: 'Bob Johnson',
  isActive: false
};
const encodedBuffer2 = userEncoder.encode(userRecord2);

// The comparator helps sort records based on the defined schema
// (Note: The comparison logic is field-by-field based on schema definition order)
const comparisonResult = userEncoder.compare(encodedBuffer, encodedBuffer2);
console.log(`Comparison (user1 vs user2): ${comparisonResult}`);

// Ensure decoded values match original (mapping back 'isActive' from 0/1 to boolean)
const originalIsActive = userRecord.isActive;
const decodedIsActive = decodedRecord.isActive === 1;
console.log(`isActive matches: ${originalIsActive === decodedIsActive}`);