bidi-js: Unicode Bidirectional Algorithm

Common errors

• TypeError: bidi-js is not a function

  cause Attempting to use the default import `bidiFactory` directly as an object or calling a method on it without first invoking it as a function.
  fix Ensure you call the factory function to get the bidi object: `const bidiFactory = require('bidi-js'); const bidi = bidiFactory();` or `import bidiFactory from 'bidi-js'; const bidi = bidiFactory();`

• TypeError: bidi.getEmbeddingLevels is not a function

  cause This error occurs when `bidi` is not the object returned by the factory function, meaning `bidiFactory()` was likely not called, or `bidi` was incorrectly assigned.
  fix Verify that `bidiFactory()` has been correctly invoked and its return value assigned to the `bidi` variable: `const bidi = bidiFactory()`.

Warnings

• gotcha The `bidi-js` package's only export is a factory function that *must* be invoked to obtain the bidi processing object. Forgetting to call `bidiFactory()` will lead to errors when attempting to access methods.
  Fix: Always initialize the library by calling the default imported function: `const bidi = bidiFactory()`.
• gotcha When applying character reorderings from `getReorderSegments`, the returned array of `flips` contains ranges that *must* be applied sequentially in the order they are provided to ensure correct visual representation.
  Fix: Iterate through the `flips` array using `forEach` and apply the reversal for each range from `start` to `end` inclusive, in the given order.
• gotcha For line-wrapped text, `getReorderSegments` should be called for each individual line by providing the `start` and `end` parameters corresponding to that line. This handles special cases for trailing whitespace within line segments.
  Fix: When processing multi-line or segmented text, call `bidi.getReorderSegments(text, embeddingLevels, lineStart, lineEnd)` for each segment.
• gotcha While the library ensures conformance to Unicode Bidirectional Algorithm version 13.0.0, future Unicode standard updates (new versions of UAX #9) may introduce changes. The library's current implementation adheres strictly to the specified version.
  Fix: Periodically check the `bidi-js` repository for updates that might align with newer Unicode Bidi Algorithm versions if strict adherence to the latest spec is critical for your application.

Install

• npm install bidi-js npm
• yarn add bidi-js yarn
• pnpm add bidi-js pnpm

Imports

• bidiFactory
  wrong:

  import { bidiFactory } from 'bidi-js'

  correct:

  import bidiFactory from 'bidi-js'

  'bidi-js' exclusively exports a single default factory function; there are no named exports.
• bidi object
  wrong:

  const bidi = bidiFactory

  correct:

  const bidi = bidiFactory()

  The default export is a factory function that *must* be invoked to return the actual bidi processing object. Assigning the factory directly will result in method invocation errors.
• getEmbeddingLevels
  wrong:

  getEmbeddingLevels(text, explicitDirection)

  correct:

  bidi.getEmbeddingLevels(text, explicitDirection)

  Methods like `getEmbeddingLevels`, `getReorderSegments`, and `getMirroredCharactersMap` are properties of the `bidi` object returned by the factory function, not global or named exports.

Quickstart

Demonstrates installation, factory initialization, and usage of core methods like `getEmbeddingLevels`, `getReorderSegments`, and `getMirroredCharactersMap` with a mixed-direction string to illustrate the Unicode Bidirectional Algorithm.

import bidiFactory from 'bidi-js';

// In a Node.js environment or a browser with ESM support
async function runBidiExample() {
  // 1. Initialize the bidi object by invoking the factory function
  const bidi = bidiFactory();

  // Example text with mixed directions (English and Hebrew)
  const text = "Hello אֲנִי World, this is a test."; // Hebrew for "I"
  const explicitDirection = "ltr"; // Optional, if you want to force base direction

  console.log("Original Text:", text);

  // 2. Calculate bidi embedding levels for each character
  const embeddingLevels = bidi.getEmbeddingLevels(text, explicitDirection);
  const { levels, paragraphs } = embeddingLevels;
  console.log("Embedding Levels (Uint8Array):");
  console.log(levels.join(', '));
  console.log("Paragraphs:", paragraphs);

  // 3. Calculate character reorderings (segments to reverse)
  const flips = bidi.getReorderSegments(text, embeddingLevels);
  console.log("Reorder Flips (ranges [start, end] to reverse):", flips);

  // 4. Apply reordering to get the visual order of characters
  let reorderedTextArray = Array.from(text);
  flips.forEach(range => {
    const [start, end] = range;
    // Reverse the segment in place
    let segment = reorderedTextArray.slice(start, end + 1);
    segment.reverse();
    reorderedTextArray.splice(start, segment.length, ...segment);
  });
  console.log("Reordered Text (visual order):
", reorderedTextArray.join(''));

  // 5. Identify characters that need to be mirrored (e.g., parentheses)
  const mirroredCharactersMap = bidi.getMirroredCharactersMap(text, embeddingLevels);
  console.log("Mirrored Characters Map (index -> replacement):", Array.from(mirroredCharactersMap.entries()));
}

runBidiExample();