### Zim Utils Native, dependency-light ZIM archive reader/searcher and Kiwix catalog downloader for Node.js [![Version](https://img.shields.io/badge/dynamic/json.svg?label=Version&style=for-the-badge&url=https://git.zakscode.com/api/v1/repos/ztimson/zim-utils/tags&query=$[0].name)](https://git.zakscode.com/ztimson/zim-utils/tags) [![Pull Requests](https://img.shields.io/badge/dynamic/json.svg?label=Pull%20Requests&style=for-the-badge&url=https://git.zakscode.com/api/v1/repos/ztimson/zim-utils&query=open_pr_counter)](https://git.zakscode.com/ztimson/zim-utils/pulls) [![Issues](https://img.shields.io/badge/dynamic/json.svg?label=Issues&style=for-the-badge&url=https://git.zakscode.com/api/v1/repos/ztimson/zim-utils&query=open_issues_count)](https://git.zakscode.com/ztimson/zim-utils/issues) ---

Documentation • Release Notes • Report a Bug • Request a Feature

---

## Table of Contents - [Zim Utils](#top) - [About](#about) - [Built With](#built-with) - [Setup](#setup) - [Production](#production) - [Usage](#usage) - [ZimManager](#zimmanager) - [ZimReader](#zimreader) - [Catalog](#catalog) - [License](#license) ## About `@ztimson/zim-utils` is a native, dependency-light toolkit for working with [ZIM](https://wiki.openzim.org/wiki/ZIM_file_format) archives and the [Kiwix](https://kiwix.org/) catalog in Node.js It comes with the following helpers: - **`ZimManager`** — Local library manager: listing, updating/downloading, and running searches accross the entire library - **`ZimReader`** — A `.zim` file reader for reading pages, metadata and running searches - **Catalog** (`zimCatalog`/`zimCatalogInfo`) — Helper functions to search the Kiwix OPDS catalog ### Built With [![Node](https://img.shields.io/badge/Node.js-000000?style=for-the-badge&logo=nodedotjs)](https://nodejs.org/) [![JavaScript](https://img.shields.io/badge/JavaScript-000000?style=for-the-badge&logo=javascript)](https://javascript.com/) ## Setup

Production

#### Prerequisites - [Node.js](https://nodejs.org/en/download) #### Instructions 1. Install the dependencies: `npm install` 2. Install the package: `npm install @ztimson/zim-utils`

## Usage ### ZimManager `ZimManager` owns a directory of `.zim` files and handles everything from downloading to cross-archive search. ```js import {ZimManager} from '@ztimson/zim-utils'; const manager = new ZimManager('./zims'); // optional 2nd arg: custom catalog URL // Search the Kiwix catalog & download the top hit const [entry] = await manager.catalog('wikipedia,medicine'); await manager.download(entry.href); // List local archives with their parsed metadata const local = await manager.list(); // [{file: './zims/wikipedia_en_medicine.zim', meta: {name, date, title}}, ...] // Check a single file for updates without downloading const status = await manager.isOutdated(local[0].file); // Update every local ZIM that has a newer catalog version await manager.updateAll({force: false}); // Fuzzy-search titles across ALL local archives at once const hits = await manager.search('diabetes treatment', {limit: 10}); // Open a reader by file path OR by catalog name const reader = await manager.open('wikipedia_en_medicine'); const page = await reader.readPage('A/Diabetes'); await reader.close(); ``` ### ZimReader Everything `ZimManager` does to a single archive is just a thin wrapper around `ZimReader`. Use it directly when you don't need a whole managed library: ```js import {ZimReader} from '@ztimson/zim-utils'; const reader = await new ZimReader('./zims/wikipedia_en_medicine.zim').open(); // Metadata (what manager.#readMeta / isOutdated rely on) const name = await reader.metadata('Name'); const date = await reader.metadata('Date'); const title = await reader.metadata('Title'); // Landing page const home = await reader.mainPage(); // Direct page lookup by URL const page = await reader.readPage('A/Diabetes'); console.log(page.mimetype, page.data.toString('utf8')); // Fuzzy title search within just this archive (what manager.search fans out over) const results = await reader.search('diabetes,insulin', {limit: 20, htmlOnly: true}); await reader.close(); ``` ### Catalog `ZimManager.catalog()` and its update checks are backed directly by these two functions: ```js import {zimCatalog, zimCatalogInfo, CATALOG_URL} from '@ztimson/zim-utils'; // Ranked search across the Kiwix catalog (comma-separated terms, like ZimReader.search) const results = await zimCatalog('history,rome', {lang: 'eng', count: 20, url: CATALOG_URL}); // Exact lookup by catalog `name`, used to check if a local copy is outdated const entry = await zimCatalogInfo('wikipedia_en_medicine'); ``` ## License Copyright © 2026 Zakary Timson | Available under MIT Licensing