@openzim/libzim 2.4.4 → 3.1.0

package/src/index.d.ts

@@ -0,0 +1,254 @@
+export class IntegrityCheck {
+  static CHECKSUM: symbol;
+  static DIRENT_PTRS: symbol;
+  static DIRENT_ORDER: symbol;
+  static TITLE_INDEX: symbol;
+  static CLUSTER_PTRS: symbol;
+  static DIRENT_MIMETYPES: symbol;
+  static COUNT: symbol; // DO NOT USE THIS. See libzim docs.
+}
+
+export class Compression {
+  static None: symbol;
+  static Zstd: symbol;
+}
+
+export class Blob {
+  constructor(buf?: ArrayBuffer | Buffer | string);
+  get data(): Buffer;
+  get size(): number | bigint;
+  toString(): string;
+}
+
+export type ContentProvider = {
+  size: number | bigint;
+  feed(): Blob;
+};
+
+export class StringProvider {
+  constructor(content: string);
+  get size(): number;
+  feed(): Blob;
+}
+
+export class FileProvider {
+  constructor(filepath: string);
+  get size(): number | bigint;
+  feed(): Blob;
+}
+
+export type Hint = {
+  COMPRESS?: number;
+  FRONT_ARTICLE?: number;
+};
+
+export interface IndexData {
+  hasIndexData?: boolean;
+  title?: string;
+  content?: string;
+  keywords?: string;
+  wordcount?: number;
+  position?: [boolean, number, number];
+}
+
+export interface WriterItem {
+  path: string;
+  title: string;
+  mimeType: string;
+  getContentProvider(): ContentProvider;
+  hints: Hint;
+  getIndexData?: () => IndexData;
+}
+
+export class StringItem {
+  constructor(
+    path: string,
+    mimeType: string,
+    title: string,
+    hint: Hint,
+    content: ArrayBuffer | Buffer | string
+  );
+  readonly path: string;
+  readonly title: string;
+  readonly mimeType: string;
+  getContentProvider(): StringProvider;
+  readonly hints: Hint;
+}
+
+export class FileItem {
+  constructor(
+    path: string,
+    mimeType: string,
+    title: string,
+    hints: Hint,
+    filePath: string
+  );
+  readonly path: string;
+  readonly title: string;
+  readonly mimeType: string;
+  getContentProvider(): StringProvider;
+  readonly hints: Hint;
+}
+
+export class Creator {
+  constructor();
+  configVerbose(verbose: boolean): this;
+  configCompression(value: Compression): this;
+  configClusterSize(size: number): this;
+  configIndexing(indexing: boolean, language: string): this;
+  configNbWorkers(num: number): this;
+  startZimCreation(filepath: string): this;
+  addItem(item: WriterItem): Promise<void>;
+  addMetadata(
+    name: string,
+    content: string | ContentProvider,
+    mimetype?: string
+  ): void;
+  addIllustration(size: number, content: string | ContentProvider): void;
+  addRedirection(
+    path: string,
+    title: string,
+    targetPath: string,
+    hints?: Hint
+  ): void;
+  setMainPath(mainPath: string): void;
+  setUuid(uuid: string): void;
+  finishZimCreation(): Promise<void>;
+}
+
+export class Item {
+  get title(): string;
+  get path(): string;
+  get mimetype(): string;
+  get data(): Blob;
+  getData(offset?: number | bigint, limit?: number | bigint): Blob;
+  get size(): number | bigint;
+  get directAccessInformation(): {
+    filename: string;
+    offset: number;
+  };
+  get index(): number | bigint;
+}
+
+export class Entry {
+  get isRedirect(): boolean;
+  get title(): string;
+  get path(): string;
+  get item(): Item;
+  getItem(followRedirect?: boolean): Item;
+  get redirect(): Item;
+  get redirectEntry(): Entry;
+  get index(): number;
+}
+
+export interface EntryRange extends Iterable<Entry> {
+  size: number;
+  offset(start: number, maxResults: number): EntryRange;
+}
+
+export class Archive {
+  constructor(filepath: string);
+  get filename(): string;
+  get filesize(): number | bigint;
+  get allEntryCount(): number;
+  get entryCount(): number;
+  get articleCount(): number;
+  get uuid(): string;
+  getMetadata(name: string): string;
+  getMetadataItem(name: string): Item;
+  get metadataKeys(): string[];
+  getIllustrationItem(size: number): Item;
+  get illustrationSizes(): Set<number>;
+  getEntryByPath(path_or_idx: string | number): Entry;
+  getEntryByTitle(title_or_idx: string | number): Entry;
+  getEntryByClusterOrder(idx: number): Entry;
+  get mainEntry(): Entry;
+  get randomEntry(): Entry;
+  hasEntryByPath(path: string): boolean;
+  hasEntryByTitle(title: string): boolean;
+  hasMainEntry(): boolean;
+  hasIllustration(size: number): boolean;
+  hasFulltextIndex(): boolean;
+  hasTitleIndex(): boolean;
+  iterByPath(): EntryRange;
+  iterByTitle(): EntryRange;
+  iterEfficient(): EntryRange;
+  findByPath(path: string): EntryRange;
+  findByTitle(title: string): EntryRange;
+  get hasChecksum(): boolean;
+  get checksum(): string;
+  check(): boolean;
+  checkIntegrity(checkType: symbol): boolean; // one of IntegrityCheck
+  get isMultiPart(): boolean;
+  get hasNewNamespaceScheme(): boolean;
+
+  static validate(zimPath: string, checksToRun: symbol[]): boolean; // list of IntegrityCheck
+}
+
+interface Georange {
+  latitude: number;
+  longitude: number;
+  distance: number;
+}
+
+export class Query {
+  constructor(query: string);
+  setQuery(query: string): this;
+  setGeorange(latitude: number, longitude: number, distance: number): this;
+  get query(): string;
+  set query(query: string);
+  toString(): string;
+  get georange(): Georange;
+  set georange(range: Georange);
+}
+
+export class SearchIterator {
+  get path(): string;
+  get title(): string;
+  get score(): number;
+  get snippet(): string;
+  get wordCount(): number;
+  get size(): number;
+  get fileIndex(): number;
+  get zimId(): string;
+  get entry(): Entry;
+}
+
+export interface SearchResultSet extends Iterable<SearchIterator> {
+  readonly size: number;
+}
+
+export class Search {
+  getResults(start: number, maxResults: number): SearchResultSet;
+  get estimatedMatches(): number;
+}
+
+export class Searcher {
+  constructor(archives: Archive | Archive[]);
+  addArchive(archive: Archive): this;
+  search(query: string | Query): Search;
+  setVerbose(verbose: boolean): this;
+}
+
+export class SuggestionIterator {
+  get entry(): Entry;
+  get title(): string;
+  get path(): string;
+  get snippet(): string;
+  get hasSnippet(): boolean;
+}
+
+export interface SuggestionResultSet extends Iterable<SuggestionIterator> {
+  readonly size: number;
+}
+
+export class SuggestionSearch {
+  getResults(start: number, maxResults: number): SuggestionResultSet;
+  get estimatedMatches(): number;
+}
+
+export class SuggestionSearcher {
+  constructor(archives: Archive);
+  suggest(query: string): SuggestionSearch;
+  setVerbose(verbose: boolean): this;
+}

package/src/index.js

@@ -0,0 +1,33 @@
+import bindings from "bindings";
+
+const {
+  Archive,
+  Entry,
+  IntegrityCheck,
+  Compression,
+  Blob,
+  Searcher,
+  Query,
+  SuggestionSearcher,
+  Creator,
+  StringProvider,
+  FileProvider,
+  StringItem,
+  FileItem,
+} = bindings("zim_binding");
+
+module.exports = {
+  Archive,
+  Entry,
+  IntegrityCheck,
+  Compression,
+  Blob,
+  Searcher,
+  Query,
+  SuggestionSearcher,
+  Creator,
+  StringProvider,
+  FileProvider,
+  StringItem,
+  FileItem,
+};

package/src/item.h

@@ -0,0 +1,152 @@
+#pragma once
+
+#include <napi.h>
+#include <zim/item.h>
+#include <exception>
+#include <memory>
+
+#include "blob.h"
+
+class Item : public Napi::ObjectWrap<Item> {
+ public:
+  explicit Item(const Napi::CallbackInfo &info)
+      : Napi::ObjectWrap<Item>(info), item_{nullptr} {
+    Napi::Env env = info.Env();
+    Napi::HandleScope scope(env);
+
+    if (!info[0].IsExternal()) {
+      throw Napi::Error::New(
+          env, "Item must be constructed internally by another class.");
+    }
+
+    item_ = std::make_shared<zim::Item>(
+        *info[0].As<Napi::External<zim::Item>>().Data());
+  }
+
+  static Napi::Object New(Napi::Env env, zim::Item &&item) {
+    auto external = Napi::External<zim::Item>::New(env, &item);
+    auto &constructor = env.GetInstanceData<ModuleConstructors>()->item;
+    return constructor.New({external});
+  }
+
+  Napi::Value getTitle(const Napi::CallbackInfo &info) {
+    try {
+      return Napi::Value::From(info.Env(), item_->getTitle());
+    } catch (const std::exception &err) {
+      throw Napi::Error::New(info.Env(), err.what());
+    }
+  }
+
+  Napi::Value getPath(const Napi::CallbackInfo &info) {
+    try {
+      return Napi::Value::From(info.Env(), item_->getPath());
+    } catch (const std::exception &err) {
+      throw Napi::Error::New(info.Env(), err.what());
+    }
+  }
+
+  Napi::Value getMimetype(const Napi::CallbackInfo &info) {
+    try {
+      return Napi::Value::From(info.Env(), item_->getMimetype());
+    } catch (const std::exception &err) {
+      throw Napi::Error::New(info.Env(), err.what());
+    }
+  }
+
+  Napi::Value getData(const Napi::CallbackInfo &info) {
+    try {
+      auto env = info.Env();
+      size_t offset = 0;
+
+      // load offset if defined and is Number or BigInt
+      if (info[0].IsBigInt()) {
+        offset = info[0].As<Napi::BigInt>().Uint64Value(nullptr);
+      } else if (info[0].IsNumber()) {
+        int64_t val = info[0].ToNumber().Int64Value();
+        if (val < 0) {
+          throw Napi::Error::New(env,
+                                 "Offset must be greater than or equal to 0");
+        }
+        offset = static_cast<size_t>(val);
+      }
+
+      // load size if defined and is Number or BigInt
+      if (info.Length() > 1) {
+        size_t size;
+        if (info[1].IsBigInt()) {
+          size = info[1].As<Napi::BigInt>().Uint64Value(nullptr);
+        } else if (info[1].IsNumber()) {
+          int64_t val = info[1].ToNumber().Int64Value();
+          if (val < 0) {
+            throw Napi::Error::New(env,
+                                   "Size must be greater than or equal to 0");
+          }
+          size = static_cast<size_t>(val);
+        } else {  // fail here because the wrong type defaults to 0
+          throw Napi::Error::New(env, "Size must be an Number or BigInt");
+        }
+
+        auto blob = item_->getData(offset, size);
+        return Blob::New(env, blob);
+      }
+
+      auto blob = item_->getData(offset);
+      return Blob::New(env, blob);
+    } catch (const std::exception &err) {
+      throw Napi::Error::New(info.Env(), err.what());
+    }
+  }
+
+  Napi::Value getSize(const Napi::CallbackInfo &info) {
+    try {
+      return Napi::Value::From(info.Env(), item_->getSize());
+    } catch (const std::exception &err) {
+      throw Napi::Error::New(info.Env(), err.what());
+    }
+  }
+
+  Napi::Value getDirectAccessInformation(const Napi::CallbackInfo &info) {
+    try {
+      auto env = info.Env();
+      const auto valPair = item_->getDirectAccessInformation();
+      auto res = Napi::Object::New(env);
+      res["filename"] = Napi::Value::From(env, valPair.first);
+      res["offset"] = Napi::Value::From(env, valPair.second);
+      return res;
+    } catch (const std::exception &err) {
+      throw Napi::Error::New(info.Env(), err.what());
+    }
+  }
+
+  Napi::Value getIndex(const Napi::CallbackInfo &info) {
+    try {
+      return Napi::Value::From(info.Env(), item_->getIndex());
+    } catch (const std::exception &err) {
+      throw Napi::Error::New(info.Env(), err.what());
+    }
+  }
+
+  static void Init(Napi::Env env, Napi::Object exports,
+                   ModuleConstructors &constructors) {
+    Napi::HandleScope scope(env);
+    Napi::Function func =
+        DefineClass(env, "Item",
+                    {
+                        InstanceAccessor<&Item::getTitle>("title"),
+                        InstanceAccessor<&Item::getPath>("path"),
+                        InstanceAccessor<&Item::getMimetype>("mimetype"),
+                        InstanceAccessor<&Item::getData>("data"),
+                        InstanceMethod<&Item::getData>("getData"),
+                        InstanceAccessor<&Item::getSize>("size"),
+                        InstanceAccessor<&Item::getDirectAccessInformation>(
+                            "directAccessInformation"),
+                        InstanceAccessor<&Item::getIndex>("index"),
+                    });
+
+    exports.Set("Item", func);
+    constructors.item = Napi::Persistent(func);
+  }
+
+ private:
+  std::shared_ptr<zim::Item> item_;
+};

package/src/module.cc

@@ -1,14 +1,50 @@
 
 #include <napi.h>
 
-#include "article.h"
-#include "reader.h"
-#include "writer.h"
+#include "archive.h"
+#include "blob.h"
+#include "common.h"
+#include "contentProvider.h"
+#include "creator.h"
+#include "entry.h"
+#include "item.h"
+#include "search.h"
+#include "suggestion.h"
+#include "writerItem.h"
 
 Napi::Object InitAll(Napi::Env env, Napi::Object exports) {
-  Article::Init(env, exports);
-  ZimCreatorWrapper::Init(env, exports);
-  ZimReaderWrapper::Init(env, exports);
+  // used for storing constructor function references for this instance of the
+  // module. This allows the re-use of the module in workers and threads via
+  // multiple instances of this module.
+  auto constructors = new ModuleConstructors{};
+  env.SetInstanceData(constructors);
+
+  IntegrityCheck::Init(env, exports, *constructors);
+  Compression::Init(env, exports, *constructors);
+
+  Blob::Init(env, exports, *constructors);
+  Item::Init(env, exports, *constructors);
+  Entry::Init(env, exports, *constructors);
+  Archive::Init(env, exports, *constructors);
+
+  Searcher::Init(env, exports, *constructors);
+  Query::Init(env, exports, *constructors);
+  Search::Init(env, exports, *constructors);
+  SearchResultSet::Init(env, exports, *constructors);
+  SearchIterator::Init(env, exports, *constructors);
+
+  SuggestionSearcher::Init(env, exports, *constructors);
+  SuggestionSearch::Init(env, exports, *constructors);
+  SuggestionResultSet::Init(env, exports, *constructors);
+  SuggestionIterator::Init(env, exports, *constructors);
+
+  StringProvider::Init(env, exports, *constructors);
+  FileProvider::Init(env, exports, *constructors);
+  Creator::Init(env, exports, *constructors);
+
+  StringItem::Init(env, exports, *constructors);
+  FileItem::Init(env, exports, *constructors);
+
   return exports;
 }