generated from ztimson/template
New Zim utilties
This commit is contained in:
187
README.md
187
README.md
@@ -1,96 +1,59 @@
|
||||
<!-- Header -->
|
||||
<div id="top" align="center">
|
||||
<br />
|
||||
|
||||
|
||||
<!-- Logo -->
|
||||
<img src="https://git.zakscode.com/repo-avatars/2b4ee6ba1f2e2618bf7694e4a52fb56d1d0ea6abafa2dcbe496ab786b86d5a76" alt="Logo" width="200" height="200">
|
||||
|
||||
<!-- Title -->
|
||||
### Template
|
||||
|
||||
### Zim Utils
|
||||
|
||||
<!-- Description -->
|
||||
Simple repository template
|
||||
Native, dependency-light ZIM archive reader/searcher and Kiwix catalog downloader for Node.js
|
||||
|
||||
<!-- Repo badges -->
|
||||
[](https://git.zakscode.com/ztimson/template/tags)
|
||||
[](https://git.zakscode.com/ztimson/template/pulls)
|
||||
[](https://git.zakscode.com/ztimson/template/issues)
|
||||
[](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/template/wiki" target="_blank">Documentation</a>
|
||||
• <a href="https://git.zakscode.com/ztimson/template/releases" target="_blank">Release Notes</a>
|
||||
• <a href="https://git.zakscode.com/ztimson/template/issues/new?template=.github%2fissue_template%2fbug.md" target="_blank">Report a Bug</a>
|
||||
• <a href="https://git.zakscode.com/ztimson/template/issues/new?template=.github%2fissue_template%2fenhancement.md" target="_blank">Request a Feature</a>
|
||||
<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
|
||||
- [Template](#top)
|
||||
- [About](#about)
|
||||
- [Demo](#demo)
|
||||
- [Built With](#built-with)
|
||||
- [Setup](#setup)
|
||||
- [Production](#production)
|
||||
- [Development](#development)
|
||||
- [License](#license)
|
||||
- [Zim Utils](#top)
|
||||
- [About](#about)
|
||||
- [Built With](#built-with)
|
||||
- [Setup](#setup)
|
||||
- [Production](#production)
|
||||
- [Usage](#usage)
|
||||
- [ZimManager](#zimmanager)
|
||||
- [ZimReader](#zimreader)
|
||||
- [Catalog](#catalog)
|
||||
- [License](#license)
|
||||
|
||||
## About
|
||||
|
||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
|
||||
`@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
|
||||
|
||||
### Demo
|
||||
It comes with the following helpers:
|
||||
|
||||
Website: https://git.zakscode.com
|
||||
- **`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://angular.io/)
|
||||
[](https://www.android.com/)
|
||||
[](https://www.arduino.cc/)
|
||||
[](https://getbootstrap.com)
|
||||
[](https://en.cppreference.com/w/c/language)
|
||||
[](https://cplusplus.com/)
|
||||
[](https://dotnet.microsoft.com/)
|
||||
[](https://www.w3.org/Style/CSS/Overview.en.html)
|
||||
[](https://www.djangoproject.com/)
|
||||
[](https://docker.com/)
|
||||
[](https://www.electronjs.org/)
|
||||
[](https://firebase.google.com/)
|
||||
[](https://go.dev/)
|
||||
[](https://graphql.org/)
|
||||
[](https://developer.mozilla.org/en-US/docs/Glossary/HTML)
|
||||
[](https://java.com/)
|
||||
[](https://javascript.com/)
|
||||
[](https://jquery.com )
|
||||
[](https://laravel.com)
|
||||
[](https://www.linux.org/)
|
||||
[](https://git.zakscode.com/ztimson/momentum)
|
||||
[](https://www.mongodb.com/)
|
||||
[](https://www.mysql.com/)
|
||||
[](https://nestjs.com/)
|
||||
[](https://dotnet.microsoft.com/)
|
||||
[](https://nextjs.org/)
|
||||
[](https://www.nginx.com/)
|
||||
[](https://nodejs.org/)
|
||||
[](https://p5js.org/)
|
||||
[](https://www.php.net/)
|
||||
[](https://www.postgresql.org/)
|
||||
[](https://www.python.org/)
|
||||
[](https://reactjs.org/)
|
||||
[](https://redis.com/)
|
||||
[](https://sass-lang.com/)
|
||||
[](https://en.wikipedia.org/wiki/Shell_script)
|
||||
[](https://www.microsoft.com/en-ca/sql-server)
|
||||
[](https://www.sqlite.org/index.html)
|
||||
[](https://svelte.dev/)
|
||||
[](https://typescriptlang.org/)
|
||||
[](https://microsoft.com/windows)
|
||||
[](https://vitejs.dev/)
|
||||
[](https://vuejs.org/)
|
||||
[](https://javascript.com/)
|
||||
|
||||
## Setup
|
||||
|
||||
@@ -101,32 +64,88 @@ Website: https://git.zakscode.com
|
||||
</h3>
|
||||
</summary>
|
||||
|
||||
#### Prerequisites
|
||||
- [Docker](https://docs.docker.com/install/)
|
||||
|
||||
#### Instructions
|
||||
1. Run the docker image: `docker run -p 80:80 git.zakscode.com/ztimson/template:latest`
|
||||
2. Open [http://localhost](http://localhost)
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>
|
||||
<h3 id="development" style="display: inline">
|
||||
Development
|
||||
</h3>
|
||||
</summary>
|
||||
|
||||
#### Prerequisites
|
||||
- [Node.js](https://nodejs.org/en/download)
|
||||
|
||||
#### Instructions
|
||||
1. Install the dependencies: `npm install`
|
||||
2. Start the Angular server: `npm run start`
|
||||
3. Open [http://localhost:4200](http://localhost:4200)
|
||||
2. Install the package: `npm install @ztimson/zim-utils`
|
||||
|
||||
</details>
|
||||
|
||||
## License
|
||||
Copyright © 2023 Zakary Timson | All Rights Reserved | Available under MIT Licensing
|
||||
## 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
|
||||
|
||||
See the [license](./LICENSE) for more information.
|
||||
|
||||
Reference in New Issue
Block a user