lingotweaker-wasm 0.0.1 → 0.2.0

package/README.md

@@ -1,5 +1,82 @@
-# lingotweaker-wasm
+# LingoTweaker (WebAssembly)
 
-Placeholder release. The real package ships the WebAssembly bindings of the
-LingoTweaker proofreading engine for browsers and Node.js. See
-https://github.com/fiduswriter/LingoTweaker
+WebAssembly bindings for the LingoTweaker proofreading engine (wasm-bindgen),
+for browsers and Node.js. The engine runs entirely from an in-memory data pack,
+so no file system or native addon is required.
+
+```sh
+npm install lingotweaker-wasm@next
+```
+
+## Browser
+
+```js
+import init, { LtEngine } from "lingotweaker-wasm";
+import { fetchPack } from "lingotweaker-wasm/pack";
+
+await init();
+
+const pack = await fetchPack("en"); // release asset for this package version
+const engine = new LtEngine(
+  "en-US",
+  pack,
+  JSON.stringify({ today: new Date().toISOString() }),
+);
+const result = JSON.parse(engine.check_json("I can heard you."));
+for (const match of result.matches) {
+  console.log(match.rule_id, match.suggestions);
+}
+```
+
+## Node.js
+
+The Node build is CommonJS (`lingotweaker-wasm/node`); the data helper is ESM,
+so import it dynamically from CJS:
+
+```js
+const { LtEngine } = require("lingotweaker-wasm/node");
+
+(async () => {
+  const { fetchPack } = await import("lingotweaker-wasm/pack");
+  const pack = await fetchPack("en");
+  const engine = new LtEngine(
+    "en-US",
+    pack,
+    JSON.stringify({ today: new Date().toISOString() }),
+  );
+  console.log(engine.check_json("I can heard you."));
+})();
+```
+
+Or, from an ES module: `import { LtEngine } from "lingotweaker-wasm/node"`.
+
+`today` is required in practice: WebAssembly has no clock, so the date is
+passed in and pinned for the engine's date filters.
+
+## Data
+
+The package ships **code only** and depends on the code-only
+`lingotweaker-data` loader; the packs ship in one small package per language
+(`lingotweaker-data-<lang>`). In Node.js the data helper resolves installed
+`lingotweaker-data-<lang>` packages locally; in the browser (or without them)
+it falls back to the per-release GitHub Release assets:
+
+```js
+import { fetchPack, packUrl, manifestUrl } from "lingotweaker-wasm/pack";
+
+await fetchPack("en");                  // installed lingotweaker-data-en in Node, else release assets
+await fetchPack("gn", { baseUrl: "https://fiduswriter.github.io/LingoTweaker" });
+packUrl("de");                           // build a URL yourself
+```
+
+`baseUrl` points at a directory that contains `packs/<lang>.pack.gz` and
+`manifest.json`. All languages are attached to every release; `manifest.json`
+lists file sizes and sha256 hashes. Each pack is also served from any npm CDN
+(`https://cdn.jsdelivr.net/npm/lingotweaker-data-<lang>/packs/<lang>.pack.gz`),
+and you can host the packs yourself.
+
+LingoTweaker is an independent project and includes a port of the legacy
+LanguageTool proofreading engine and its rule data. Upstream references and
+licenses are kept; see `THIRD_PARTY_NOTICES.md` in the repository.
+
+License: LGPL-2.1-or-later.

package/pack.js

@@ -0,0 +1,78 @@
+// Data helpers for the `lingotweaker-wasm` package.
+//
+// The engine itself is loaded from an in-memory data pack
+// (`LtEngine(lang, pack, optionsJson)`); this module fetches those packs from
+// the per-release GitHub Release assets and inflates the gzip wrapper.
+//
+//   import { fetchPack } from "lingotweaker-wasm/pack";
+//   const pack = await fetchPack("en");
+//   const engine = new LtEngine("en-US", pack, JSON.stringify({ today: new Date().toISOString() }));
+
+// Updated by scripts/release/set-version.sh together with the package version.
+export const DEFAULT_DATA_BASE_URL =
+  "https://github.com/fiduswriter/LingoTweaker/releases/download/v0.2.0";
+
+/** The URL of the release data manifest (`{ <lang>: { file, bytes, sha256 } }`). */
+export function manifestUrl(baseUrl = DEFAULT_DATA_BASE_URL) {
+  return `${baseUrl}/manifest.json`;
+}
+
+/** The URL of the gzipped pack for `lang`. */
+export function packUrl(lang, baseUrl = DEFAULT_DATA_BASE_URL) {
+  return `${baseUrl}/packs/${lang}.pack.gz`;
+}
+
+/** Inflate a gzipped pack (browser `DecompressionStream`, else Node `zlib`). */
+export async function decompressPack(bytes) {
+  const u8 = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  if (typeof DecompressionStream === "function" && typeof Blob === "function") {
+    const stream = new Blob([u8]).stream().pipeThrough(new DecompressionStream("gzip"));
+    return new Uint8Array(await new Response(stream).arrayBuffer());
+  }
+  const { gunzipSync } = await import("node:zlib");
+  return new Uint8Array(gunzipSync(u8));
+}
+
+/**
+ * Fetch and inflate the pack for `lang` (`en`, `de`, `gn`, …).
+ *
+ * Node.js prefers the locally installed `lingotweaker-data-<lang>` data
+ * packages; browsers (and any environment without them) fall back to the
+ * release assets for this package version. Pass `baseUrl` to use different
+ * data — the Pages demo
+ * (`https://fiduswriter.github.io/LingoTweaker`) or a local directory.
+ */
+export async function fetchPack(lang, options = {}) {
+  const { fetch: fetchImpl = fetch } = options;
+  let { baseUrl } = options;
+  if (!baseUrl) {
+    const local = await localPack(lang);
+    if (local) return local;
+    baseUrl = DEFAULT_DATA_BASE_URL;
+  }
+  const url = packUrl(lang, baseUrl);
+  const response = await fetchImpl(url);
+  if (!response.ok) {
+    throw new Error(`cannot load ${url}: HTTP ${response.status}`);
+  }
+  return decompressPack(await response.arrayBuffer());
+}
+
+/**
+ * Read and inflate a pack from the locally installed data packages (the
+ * code-only `lingotweaker-data` loader resolving `lingotweaker-data-<lang>`).
+ * Returns `null` outside Node.js, or when the package/language is missing.
+ */
+export async function localPack(lang) {
+  if (typeof process === "undefined" || !process.versions?.node) return null;
+  try {
+    const { createRequire } = await import("node:module");
+    const require = createRequire(import.meta.url);
+    const data = require("lingotweaker-data");
+    const { readFile } = await import("node:fs/promises");
+    const bytes = await readFile(data.packPath(lang));
+    return decompressPack(bytes);
+  } catch {
+    return null;
+  }
+}

package/package.json

@@ -1,11 +1,57 @@
 {
   "name": "lingotweaker-wasm",
-  "version": "0.0.1",
-  "description": "LingoTweaker proofreading engine compiled to WebAssembly",
+  "version": "0.2.0",
+  "description": "LingoTweaker proofreading engine compiled to WebAssembly (browser and Node)",
   "license": "LGPL-2.1-or-later",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fiduswriter/LingoTweaker.git"
   },
-  "homepage": "https://fiduswriter.github.io/LingoTweaker/"
+  "homepage": "https://fiduswriter.github.io/LingoTweaker/",
+  "keywords": [
+    "proofreading",
+    "grammar",
+    "spellcheck",
+    "nlp",
+    "language",
+    "wasm",
+    "webassembly"
+  ],
+  "type": "module",
+  "main": "./node/lt_wasm.js",
+  "module": "./web/lt_wasm.js",
+  "types": "./web/lt_wasm.d.ts",
+  "dependencies": {
+    "lingotweaker-data": "0.2.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./web/lt_wasm.d.ts",
+      "browser": "./web/lt_wasm.js",
+      "import": "./web/lt_wasm.js",
+      "require": "./node/lt_wasm.js",
+      "default": "./web/lt_wasm.js"
+    },
+    "./web": {
+      "types": "./web/lt_wasm.d.ts",
+      "default": "./web/lt_wasm.js"
+    },
+    "./node": {
+      "types": "./node/lt_wasm.d.ts",
+      "default": "./node/lt_wasm.js"
+    },
+    "./pack": {
+      "default": "./pack.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "web",
+    "node",
+    "pack.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">= 18"
+  }
 }