Zakary Timson ztimson

Ontario, Canada
https://zakscode.com
Joined on 2023-07-26

@ztimson/zim-utils (0.1.1)

Published 2026-08-20 11:40:57 -04:00 by ztimson in ztimson/zim-utils

Set up this registry in your project .npmrc file:

@ztimson:registry=

To install the package using npm, run the following command:

npm install @ztimson/zim-utils@0.1.1

or add it to the package.json file:

"@ztimson/zim-utils": "0.1.1"

For more information on the npm registry, see the documentation.

Zim Utils

Native, dependency-light ZIM archive reader/searcher and Kiwix catalog downloader for Node.js

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

Zim Utils
- About
  - Built With
- Setup
  - Production
- Usage
- License

About

@ztimson/zim-utils is a native, dependency-light toolkit for working with ZIM archives and the Kiwix 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

Setup

Production

Prerequisites

Node.js

Instructions

Install the dependencies: npm install
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.

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:

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:

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

Dependencies

ID	Version
@ztimson/utils	^0.30.7
lzma1	^0.3.0
zstd-codec	^0.1.5

Details

npm

ztimson/zim-utils

2026-08-20 11:40:57 -04:00

Zak Timson

MIT

latest

11 KiB

Assets (1)

zim-utils-0.1.1.tgz 11 KiB

Versions (1) View all

0.1.1

2026-08-20

Issues