lingotweaker-wasm 0.2.2 → 0.2.4

package/README.md

@@ -10,13 +10,19 @@ npm install lingotweaker-wasm@next
 
 ## Browser
 
+The engine's language data packs must be served from your own server —
+browsers block cross-origin fetches, so the data helper has no built-in CDN
+default. Install the `lingotweaker-data-<lang>` npm packages for the languages
+you want, copy their `packs/` directory into your static assets, and pass its
+URL as `baseUrl`:
+
 ```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 pack = await fetchPack("en", { baseUrl: "/static/lingotweaker-packs" });
 const engine = new LtEngine(
   "en-US",
   pack,
@@ -56,24 +62,28 @@ 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` loader; the packs ship in one 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:
+`lingotweaker-data-<lang>` packages automatically. In the browser you serve
+the packs yourself (see above) and pass the directory URL as `baseUrl`:
 
 ```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
+await fetchPack("en"); // installed lingotweaker-data-en (Node.js)
+await fetchPack("gn", { baseUrl: "/static/lingotweaker-packs" }); // browser: your own server
+packUrl("de", "/static/lingotweaker-packs"); // 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.
+`baseUrl` points at a directory with the same layout as the
+`lingotweaker-data-<lang>` packages: a `packs/` subdirectory containing
+`<lang>.pack.gz` plus a `manifest.json` listing file sizes and sha256 hashes.
+Same-origin is the usual choice; any CORS-enabled static server works. Packs
+are downloaded individually per language, on demand.
+
+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.
 
 LingoTweaker is an independent project and includes a port of the legacy
 LanguageTool proofreading engine and its rule data. Upstream references and

package/pack.d.ts

@@ -1,13 +1,10 @@
 // Type definitions for the data-pack helpers in pack.js.
 
-/** Default base URL of the per-release GitHub Release data assets. */
-export const DEFAULT_DATA_BASE_URL: string
+/** The URL of the data manifest (`{ <lang>: { file, bytes, sha256 } }`) under `baseUrl`. */
+export function manifestUrl(baseUrl: string): string
 
-/** The URL of the release data manifest (`{ <lang>: { file, bytes, sha256 } }`). */
-export function manifestUrl(baseUrl?: string): string
-
-/** The URL of the gzipped pack for `lang`. */
-export function packUrl(lang: string, baseUrl?: string): string
+/** The URL of the gzipped pack for `lang` under `baseUrl`. */
+export function packUrl(lang: string, baseUrl: string): string
 
 /** Inflate a gzipped pack (browser `DecompressionStream`, else Node `zlib`). */
 export function decompressPack(
@@ -15,12 +12,14 @@ export function decompressPack(
 ): Promise<Uint8Array>
 
 /**
- * Fetch and inflate the pack for `lang` (`en`, `de`, `gn`, …).
+ * Load 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.
+ * Without `options.baseUrl` this resolves the pack from the locally
+ * installed `lingotweaker-data-<lang>` npm packages (Node.js only). In a
+ * browser you must pass `baseUrl` pointing at a directory you serve with the
+ * same layout as the `lingotweaker-data-<lang>` packages (a `packs/`
+ * subdirectory containing `<lang>.pack.gz`); same-origin is the usual choice,
+ * since browsers block cross-origin fetches.
  */
 export function fetchPack(
     lang: string,

package/pack.js

@@ -1,24 +1,26 @@
 // 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.
+// (`LtEngine(lang, pack, optionsJson)`); this module obtains those packs —
+// either from the locally installed `lingotweaker-data-<lang>` npm packages
+// (Node.js) or fetched from a `baseUrl` your server serves them from
+// (browsers). Packs are gzip-compressed and inflated after loading.
 //
 //   import { fetchPack } from "lingotweaker-wasm/pack";
-//   const pack = await fetchPack("en");
+//   const pack = await fetchPack("en", { baseUrl: "/static/lingotweaker-packs" });
 //   const engine = new LtEngine("en-US", pack, JSON.stringify({ today: new Date().toISOString() }));
+//
+// There is intentionally no built-in CDN default: pack files must be served
+// from the same origin as the page (or any CORS-enabled server you pass as
+// `baseUrl`), because browsers refuse cross-origin fetches otherwise.
 
-// 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.2";
-
-/** The URL of the release data manifest (`{ <lang>: { file, bytes, sha256 } }`). */
-export function manifestUrl(baseUrl = DEFAULT_DATA_BASE_URL) {
+/** The URL of the data manifest (`{ <lang>: { file, bytes, sha256 } }`) under `baseUrl`. */
+export function manifestUrl(baseUrl) {
   return `${baseUrl}/manifest.json`;
 }
 
-/** The URL of the gzipped pack for `lang`. */
-export function packUrl(lang, baseUrl = DEFAULT_DATA_BASE_URL) {
+/** The URL of the gzipped pack for `lang` under `baseUrl`. */
+export function packUrl(lang, baseUrl) {
   return `${baseUrl}/packs/${lang}.pack.gz`;
 }
 
@@ -34,21 +36,25 @@ export async function decompressPack(bytes) {
 }
 
 /**
- * Fetch and inflate the pack for `lang` (`en`, `de`, `gn`, …).
+ * Load 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.
+ * Without `options.baseUrl` this resolves the pack from the locally
+ * installed `lingotweaker-data-<lang>` npm packages (Node.js only). In a
+ * browser you must pass `baseUrl` pointing at a directory you serve with the
+ * same layout as the `lingotweaker-data-<lang>` packages (a `packs/`
+ * subdirectory containing `<lang>.pack.gz`); same-origin is the usual choice,
+ * since browsers block cross-origin fetches.
  */
 export async function fetchPack(lang, options = {}) {
-  const { fetch: fetchImpl = fetch } = options;
-  let { baseUrl } = options;
+  const { fetch: fetchImpl = fetch, baseUrl } = options;
   if (!baseUrl) {
     const local = await localPack(lang);
     if (local) return local;
-    baseUrl = DEFAULT_DATA_BASE_URL;
+    throw new Error(
+      `lingotweaker-wasm: no locally installed lingotweaker-data-${lang} package; ` +
+        `serve the packs/ directory of the lingotweaker-data-${lang} npm package from your ` +
+        `server and pass its URL as the fetchPack baseUrl option`
+    );
   }
   const url = packUrl(lang, baseUrl);
   const response = await fetchImpl(url);
@@ -75,4 +81,4 @@ export async function localPack(lang) {
   } catch {
     return null;
   }
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lingotweaker-wasm",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "LingoTweaker proofreading engine compiled to WebAssembly (browser and Node)",
   "license": "LGPL-2.1-or-later",
   "repository": {
@@ -22,7 +22,7 @@
   "module": "./web/lt_wasm.js",
   "types": "./web/lt_wasm.d.ts",
   "dependencies": {
-    "lingotweaker-data": "0.2.2"
+    "lingotweaker-data": "0.2.4"
   },
   "exports": {
     ".": {