generated from ztimson/template
152 lines
5.5 KiB
Markdown
152 lines
5.5 KiB
Markdown
<!-- Header -->
|
|
<div id="top" align="center">
|
|
<br />
|
|
|
|
<!-- Logo -->
|
|
<img src="https://git.zakscode.com/repo-avatars/c44395fb50d10629bb79ae9294b43884679720fb589b69ea5fc854d790a6d8ec" alt="Logo" width="175" height="200">
|
|
|
|
<!-- Title -->
|
|
### Zim Utils
|
|
|
|
<!-- Description -->
|
|
Native, dependency-light ZIM archive reader/searcher and Kiwix catalog downloader for Node.js
|
|
|
|
<!-- Repo badges -->
|
|
[](https://git.zakscode.com/ztimson/zim-utils/tags)
|
|
[](https://git.zakscode.com/ztimson/zim-utils/pulls)
|
|
[](https://git.zakscode.com/ztimson/zim-utils/issues)
|
|
|
|
<!-- Links -->
|
|
|
|
---
|
|
<div>
|
|
<a href="https://git.zakscode.com/ztimson/zim-utils/wiki" target="_blank">Documentation</a>
|
|
• <a href="https://git.zakscode.com/ztimson/zim-utils/releases" target="_blank">Release Notes</a>
|
|
• <a href="https://git.zakscode.com/ztimson/zim-utils/issues/new?template=.github%2fissue_template%2fbug.md" target="_blank">Report a Bug</a>
|
|
• <a href="https://git.zakscode.com/ztimson/zim-utils/issues/new?template=.github%2fissue_template%2fenhancement.md" target="_blank">Request a Feature</a>
|
|
</div>
|
|
|
|
---
|
|
</div>
|
|
|
|
## 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
|
|
[](https://nodejs.org/)
|
|
[](https://javascript.com/)
|
|
|
|
## Setup
|
|
|
|
<details>
|
|
<summary>
|
|
<h3 id="production" style="display: inline">
|
|
Production
|
|
</h3>
|
|
</summary>
|
|
|
|
#### Prerequisites
|
|
- [Node.js](https://nodejs.org/en/download)
|
|
|
|
#### Instructions
|
|
1. Install the dependencies: `npm install`
|
|
2. Install the package: `npm install @ztimson/zim-utils`
|
|
|
|
</details>
|
|
|
|
## 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
|
|
|