lib0 Isomorphic Utility Functions

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported. Instead change the require of ... to a dynamic import() or an ESM import statement.

  cause Attempting to use `require()` to import a `lib0` subpath module in an environment or bundler setup that expects ESM, or when `lib0` itself resolves to its ESM entrypoint for that subpath.
  fix Change your import statement from `const { someFunc } = require('lib0/module');` to `import { someFunc } from 'lib0/module';`. Ensure your project's `tsconfig.json` (if using TypeScript) and bundler are configured for ESM output where appropriate.

• TypeError: (0 , _lib0_error.assert) is not a function

  cause This error often occurs due to issues with how bundlers or transpilers handle named exports from subpath imports, sometimes related to tree-shaking configurations or incorrect module interop settings.
  fix Verify your bundler (e.g., Webpack, Rollup, esbuild) configuration has `esModuleInterop: true` in TypeScript, and that tree-shaking rules are not overly aggressive or misconfigured for `lib0`'s subpath exports. Ensure direct named imports (`import { assert } from 'lib0/error'`) are used rather than default imports or namespace imports if only specific functions are needed.

Warnings

• breaking The upcoming `v1.0.0` major version introduces significant breaking changes, particularly within the `delta` and `schema` modules. Users relying on these specific functionalities in `0.x` versions will need to adapt their code when upgrading to `1.0.0` or later release candidates.
  Fix: Consult the `v1.0.0` changelog and specific module documentation for migration guides. Extensive refactoring may be required for `delta` and `schema` module consumers.
• breaking lib0 requires Node.js version `16` or higher. Projects running on older Node.js runtimes will encounter compatibility issues, including syntax errors or missing global APIs.
  Fix: Upgrade your Node.js environment to version 16 or newer to ensure compatibility. This is an explicit engine requirement in the package metadata.
• gotcha While lib0 ships with both CommonJS and ESM module formats, misconfigured bundlers or incorrect `package.json` configurations in consumer projects can lead to module resolution errors (e.g., `ERR_REQUIRE_ESM`) when attempting to `require()` an ESM-only entrypoint or vice-versa.
  Fix: Ensure your project's `package.json` `type` field and bundler configuration (e.g., Webpack, Rollup) are correctly set up for dual CJS/ESM compatibility, especially when consuming subpath imports. Prefer `import` statements over `require` in modern TypeScript/ESM projects.

Install

• npm install lib0 npm
• yarn add lib0 yarn
• pnpm add lib0 pnpm

Imports

• assert
  wrong:

  import * as error from 'lib0/error'; error.assert(...)

  correct:

  import { assert } from 'lib0/error'

  For specific utilities like `assert`, directly import the named export. Importing the entire namespace for simple functions can be less optimized if your bundler doesn't fully support dead code elimination.
• createEncoder, writeVarUint
  wrong:

  const { createEncoder } = require('lib0/encoding')

  correct:

  import { createEncoder, writeVarUint } from 'lib0/encoding'

  lib0 provides both ESM and CommonJS exports. For modern Node.js (`>=16`) and browser environments, ESM imports are preferred. The `createEncoder` and `writeVarUint` functions are part of lib0's efficient binary encoding capabilities.
• from
  wrong:

  import { from as arrayFrom } from 'lib0/array'

  correct:

  import { from } from 'lib0/array'

  While aliasing `from` to `arrayFrom` can prevent name collisions, it's generally unnecessary for subpath imports in lib0 unless you have other `from` functions in the same scope. This utility converts array-like objects to true arrays.

Quickstart

Demonstrates basic usage of `lib0/error` for assertions, `lib0/encoding` and `lib0/decoding` for binary data manipulation, and `lib0/array` for common array utilities.

import { assert } from 'lib0/error';
import { createEncoder, writeVarUint, writeString } from 'lib0/encoding';
import { createDecoder, readVarUint, readString } from 'lib0/decoding';

// Basic assertion
assert(1 + 1 === 2, 'Arithmetic should work!');
console.log('Assertion passed: 1 + 1 === 2');

// Encoding and decoding a simple value
const encoder = createEncoder();
writeVarUint(encoder, 12345);
writeString(encoder, 'Hello, lib0!');
const encodedData = encoder.buf;

console.log(`Encoded data (Uint8Array): ${encodedData}`);

const decoder = createDecoder(encodedData);
const decodedNumber = readVarUint(decoder);
const decodedString = readString(decoder);

console.log(`Decoded number: ${decodedNumber}`);
console.log(`Decoded string: ${decodedString}`);

assert(decodedNumber === 12345, 'Decoded number mismatch');
assert(decodedString === 'Hello, lib0!', 'Decoded string mismatch');
console.log('Encoding and decoding successful!');

// Using an array utility
import { from } from 'lib0/array';
const iterable = new Set([1, 2, 3]);
const arr = from(iterable);
assert(arr.length === 3 && arr[0] === 1, 'Array conversion failed');
console.log(`Converted iterable to array: ${arr}`);