@openzim/libzim

node-libzim

This is the Node.js binding to the libzim. Read and write ZIM files easily in Javascript.

Dependencies

This package relies on node-addon-api / n-api.

On GNU/Linux & macOS, the package will download a libzim binary. On other OSes you will need to install libzim separately (see here).

Usage

npm i @openzim/libzim

Writing a ZIM file

// write.js
import { Creator, StringItem } from "@openzim/libzim";

(async () => {
    console.info('Starting');
    const outFile = "./test.zim";
    const creator = new Creator()
        .configNbWorkers(1)
        .configIndexing(true, "en")
        .configClusterSize(2048)
        .startZimCreation(outFile);

    for (let i = 0; i < 100; i++) {
        const item = new StringItem(
            `file${i}`,                       // path url
            "text/plain",                     // content-type
            `Title ${i}`,                     // title
            {FRONT_ARTICLE: 1, COMPRESS: 1},  // hint option flags
            `<h1>Content / Data ${i}</h1>`    // content
        );
        await creator.addItem(item);
    }

    creator.setMainPath("file0");
    await creator.finishZimCreation();

    console.log('Done Writing');
})();

Reading a ZIM file

// read.js
import { Archive, Query, SuggestionSearcher, Searcher } from "@openzim/libzim";

(async () => {
    const outFile = "./test.zim";
    const archive = new Archive(outFile);
    console.log(`Archive opened: main entry path - ${archive.mainEntry.path}`);

    for (const entry of archive.iterByPath()) {
        console.log(`entry: ${entry.path} - ${entry.title}`);
    }

    const suggestionSearcher = new SuggestionSearcher(archive);
    const suggestion = suggestionSearcher.suggest('laborum');
    let results = suggestion.getResults(0, 10);
    console.log("Suggestion results:");
    for(const entry of results) {
        console.log(`\t- ${entry.path} - ${entry.title}`);
    }

    const searcher = new Searcher(archive);
    const search = searcher.search(new Query('rem'));
    results = search.getResults(0, 10);
    console.log("Search results:");
    for(const entry of results) {
        console.log(`\t- ${entry.path} - ${entry.title}`);
    }


    const entry = archive.getEntryByPath("A/laborum");
    const item = entry.item;
    const blob = item.data;
    console.info(`Entry by url (laborum):`, blob.data);
})();

Local Development

Important Files

.env - Set environment variables for local development. Only LIBZIM_VERSION for now bindings.gyp - Node-gyp build configuration file src/ - Source code for the Node.js bindings test/ - Test cases

Setup

git clone [e-mail]:openzim/node-libzim.git
cd node-libzim

# Will install dependencies, download libzim binary and build the bindings
npm run install

# Required in order for local binding and tests to work.
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$PWD/download/lib/x86_64-linux-gnu

Iterating during development

Make your changes in src/ and then run:

node-gyp rebuild --debug -v && npx jest ./test/zim.test.ts

Updating libzim version

To update the libzim version used, change the LIBZIM_VERSION variable in .env file to the desired version and run:

npm run install

If you are upgrading libzim from a major version you will need to edit the bundle-libzim.js file and change the libzim.so* file names to match the new version.

License

GPLv3 or later, see LICENSE for more details.