pankosmia-lib 0.0.3 → 0.0.5

package/README.md

@@ -0,0 +1,35 @@
+# pankosmia-lib
+
+A utility library for the Pankosmia ecosystem.
+
+## Modules
+
+The library is divided into multiple modules:
+
+- **`http`** — Functions for communicating with a Pankosmia server through HTTP requests (GET/POST).
+- **`i18n`** — Internationalization utilities, mainly the `do18n` function.
+- **`usfm`** — Utility functions for working with USFM.
+
+Each module can be imported independently:
+
+```ts
+import { ... } from "pankosmia-lib/http"
+import { ... } from "pankosmia-lib/i18n"
+import { ... } from "pankosmia-lib/usfm"
+```
+
+## Installation
+
+```bash
+pnpm add pankosmia-lib
+```
+
+## Testing
+
+Tests require a running Pankosmia server.
+
+Once the server is running, execute:
+
+```bash
+pnpm run test
+```

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "pankosmia-lib",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "type": "module",
   "main": "./index.js",
+  "packageManager": "pnpm@11.20.0",
+  "engines": {
+    "node": ">=24",
+    "pnpm": "11.20.0"
+  },
   "files": [
     "src",
     "index.js",

package/src/http/getLib.js

@@ -1,88 +1,323 @@
-async function getJson(url, debug=false) {
-    try {
-        const response = await fetch(url);
-        if (!response.ok) {
-            const result = {
-                url,
-                ok: false,
-                status: response.status,
-                error: await response.text()
-            };
-            if (debug) {
-                console.log("getJson", result);
-            }
-            return result;
-        }
-        const result = {
-            url,
-            ok: true,
-            status: response.status,
-            json: await response.json()
-        };
-        if (debug) {
-            console.log("getJson", result);
-        }
-        return result;
-    } catch (err) {
-        const result = {
-            url,
-            ok: false,
-            status: 0,
-            error: err.message
-        };
-        if (debug) {
-            console.log("getJson", result);
-        }
-        return result;
+/**
+ * @typedef {Object} GetSuccess
+ * @property {string} url - The requested URL.
+ * @property {true} ok - Indicates that the request succeeded.
+ * @property {number} status - The HTTP response status code.
+ */
+
+/**
+ * @typedef {GetSuccess & {
+ *   json: any
+ * }} GetJsonResult
+ *
+ * @typedef {GetSuccess & {
+ *   text: string
+ * }} GetTextResult
+ *
+ * @typedef {GetSuccess & {
+ *   bytes: ArrayBuffer
+ * }} GetBytesResult
+ *
+ * @typedef {Object} GetError
+ * @property {string} url - The requested URL.
+ * @property {false} ok - Indicates that the request failed.
+ * @property {number} status - The HTTP status code, or 0 when the request
+ *   failed before receiving an HTTP response.
+ * @property {any|string} error - The server error or JavaScript error message.
+ */
+
+/**
+ * Performs an HTTP GET request and parses the response as JSON.
+ *
+ * Use this function when the API endpoint returns a JSON response.
+ *
+ * @param {string} url - The URL to request.
+ * @param {boolean} [debug=false] - If true, logs the result to the console.
+ *
+ * @returns {Promise<GetJsonResult|GetError>} The HTTP response result.
+ *
+ * @example
+ * const result = await getJson(
+ *   "http://127.0.0.1:19119/api/settings/languages/en"
+ * );
+ *
+ * if (result.ok) {
+ *   console.log(result.status);
+ *   console.log(result.json);
+ * } else {
+ *   console.error(result.error);
+ * }
+ *
+ * @example
+ * // Enable debug logging.
+ * const result = await getJson(
+ *   "https://example.com/api/settings",
+ *   true
+ * );
+ */
+async function getJson(url, debug = false) {
+  try {
+    const response = await fetch(url);
+
+    if (!response.ok) {
+      const result = {
+        url,
+        ok: false,
+        status: response.status,
+        error: JSON.parse(await response.text()),
+      };
+
+      if (debug) {
+        console.log("getJson", result);
+      }
+
+      return result;
+    }
+
+    const result = {
+      url,
+      ok: true,
+      status: response.status,
+      json: await response.json(),
+    };
+
+    if (debug) {
+      console.log("getJson", result);
+    }
+
+    return result;
+  } catch (err) {
+    const result = {
+      url,
+      ok: false,
+      status: 0,
+      error: err.message,
+    };
+
+    if (debug) {
+      console.log("getJson", result);
     }
+
+    return result;
+  }
 }
-async function getText(url, debug=false) {
-    try {
-        const response = await fetch(url);
-        if (!response.ok) {
-            const result = {
-                url,
-                ok: false,
-                status: response.status,
-                error: await response.text()
-            };
-            if (debug) {
-                console.log("getText", result);
-            }
-            return result;
-        }
-        const result = {
-            url,
-            ok: true,
-            status: response.status,
-            text: await response.text()
-        };
-        if (debug) {
-            console.log("getText", result);
-        }
-        return result;
-    } catch (err) {
-        const result = {
-            url,
-            ok: false,
-            status: 0,
-            error: err.message
-        };
-        if (debug) {
-            console.log("getText", result);
-        }
-        return result;
+
+/**
+ * Performs an HTTP GET request and returns the response body as text.
+ *
+ * Use this function when the API endpoint returns plain text, source text,
+ * configuration text, USFM, XML, HTML, or another text-based response.
+ *
+ * @param {string} url - The URL to request.
+ * @param {boolean} [debug=false] - If true, logs the result to the console.
+ *
+ * @returns {Promise<GetTextResult|GetError>} The HTTP response result.
+ *
+ * @example
+ * const result = await getText(
+ *   "http://127.0.0.1:19119/api/burrito/ingredient/raw/_local_/_local_/plt?ipath=test.usfm"
+ * );
+ *
+ * if (result.ok) {
+ *   console.log(result.text);
+ * } else {
+ *   console.error(result.error);
+ * }
+ *
+ * @example
+ * // Enable debug logging.
+ * const result = await getText(
+ *   "https://example.com/api/content",
+ *   true
+ * );
+ */
+async function getText(url, debug = false) {
+  try {
+    const response = await fetch(url);
+
+    if (!response.ok) {
+      const result = {
+        url,
+        ok: false,
+        status: response.status,
+        error: JSON.parse(await response.text()),
+      };
+
+      if (debug) {
+        console.log("getText", result);
+      }
+
+      return result;
     }
+
+    const result = {
+      url,
+      ok: true,
+      status: response.status,
+      text: await response.text(),
+    };
+
+    if (debug) {
+      console.log("getText", result);
+    }
+
+    return result;
+  } catch (err) {
+    const result = {
+      url,
+      ok: false,
+      status: 0,
+      error: err.message,
+    };
+
+    if (debug) {
+      console.log("getText", result);
+    }
+
+    return result;
+  }
 }
 
-const getAndSetJson = async ({url, setter, debug=false}) => {
-    const response = await getJson(url, debug);
-    if (response.ok
-    ) {
-        setter(response.json);
-    } else {
-        return response;
+/**
+ * Performs an HTTP GET request and returns the response body as binary data.
+ *
+ * The response is returned as an ArrayBuffer, which can be converted to
+ * a Uint8Array when byte-level access is required.
+ *
+ * @param {string} url - The URL to request.
+ * @param {boolean} [debug=false] - If true, logs the result to the console.
+ *
+ * @returns {Promise<GetBytesResult|GetError>} The HTTP response result.
+ *
+ * @example
+ * const result = await getBytes(
+ *   "http://127.0.0.1:19119/api/burrito/ingredient/bytes/_local_/_local_/plt?ipath=test.usfm"
+ * );
+ *
+ * if (result.ok) {
+ *   const bytes = new Uint8Array(result.bytes);
+ *
+ *   console.log(bytes);
+ * } else {
+ *   console.error(result.error);
+ * }
+ *
+ * @example
+ * // Enable debug logging.
+ * const result = await getBytes(
+ *   "https://example.com/api/file",
+ *   true
+ * );
+ */
+async function getBytes(url, debug = false) {
+  try {
+    const response = await fetch(url);
+
+    if (!response.ok) {
+      const result = {
+        url,
+        ok: false,
+        status: response.status,
+        error: JSON.parse(await response.text()),
+      };
+
+      if (debug) {
+        console.log("getBytes", result);
+      }
+
+      return result;
     }
+
+    const result = {
+      url,
+      ok: true,
+      status: response.status,
+      bytes: await response.arrayBuffer(),
+    };
+
+    if (debug) {
+      console.log("getBytes", result);
+    }
+
+    return result;
+  } catch (err) {
+    const result = {
+      url,
+      ok: false,
+      status: 0,
+      error: err.message,
+    };
+
+    if (debug) {
+      console.log("getBytes", result);
+    }
+
+    return result;
+  }
 }
 
-export {getJson, getAndSetJson, getText};
+/**
+ * Performs a GET request for JSON and passes the resulting JSON value
+ * to a setter function when the request succeeds.
+ *
+ * This is a convenience wrapper around {@link getJson}.
+ *
+ * If the request fails, the error response is returned instead of calling
+ * the setter.
+ *
+ * @param {Object} options - Function options.
+ * @param {string} options.url - The URL to request.
+ * @param {(json: any) => void} options.setter - Function that receives
+ *   the parsed JSON response.
+ * @param {boolean} [options.debug=false] - If true, logs the request result.
+ *
+ * @returns {Promise<GetError|undefined>} The error response when the request
+ *   fails, otherwise undefined.
+ *
+ * @example
+ * let languages;
+ *
+ * const result = await getAndSetJson({
+ *   url: "http://127.0.0.1:19119/api/settings/languages/en",
+ *   setter: (json) => {
+ *     languages = json;
+ *   },
+ * });
+ *
+ * if (result) {
+ *   console.error(result.error);
+ * }
+ *
+ * @example
+ * // Using a framework state setter.
+ * await getAndSetJson({
+ *   url: "https://example.com/api/settings",
+ *   setter: setSettings,
+ * });
+ *
+ * @example
+ * // Enable debug logging.
+ * await getAndSetJson({
+ *   url: "https://example.com/api/settings",
+ *   setter: (json) => {
+ *     console.log("Received:", json);
+ *   },
+ *   debug: true,
+ * });
+ */
+const getAndSetJson = async ({ url, setter, debug = false }) => {
+  const response = await getJson(url, debug);
+
+  if (response.ok) {
+    setter(response.json);
+  } else {
+    return response;
+  }
+};
+
+export {
+  getJson,
+  getAndSetJson,
+  getText,
+  getBytes,
+};

package/src/http/index.js

@@ -1,12 +1,14 @@
 
-import {getJson, getAndSetJson, getText} from "./getLib.js";
-import {postEmptyJson, postJson, postText} from "./postLib.js";
+import {getJson, getAndSetJson, getText,getBytes} from "./getLib.js";
+import {postEmpty, postJson, postText,postBytes} from "./postLib.js";
 
 export {
     getJson,
     getText,
     getAndSetJson,
-    postEmptyJson,
+    postEmpty,
     postJson,
-    postText
+    postText,
+    postBytes,
+    getBytes
 };

package/src/http/postLib.js

@@ -1,128 +1,383 @@
-async function postEmptyJson(url, debug=false) {
-    try {
-        const response = await fetch(url, {method: "POST"});
-        if (!response.ok) {
-            const result = {
-                url,
-                ok: false,
-                status: response.status,
-                error: await response.text()
-            };
-            if (debug) {
-                console.log("postEmptyJson", result);
-            }
-            return result;
-        }
-        const result = {
-            url,
-            ok: true,
-            status: response.status,
-            json: await response.json()
-        };
-        if (debug) {
-            console.log("postEmptyJson", result);
-        }
-        return result;
-    } catch (err) {
-        const result = {
-            url,
-            ok: false,
-            status: 0,
-            error: err.message
-        };
-        if (debug) {
-            console.log("postEmptyJson", result);
-        }
-        return result;
+/**
+ * Sends an HTTP POST request without a request body.
+ *
+ * The server response is expected to contain JSON.
+ *
+ * @param {string} url - The URL to send the POST request to.
+ * @param {boolean} [debug=false] - If true, logs the request result to the console.
+ *
+ * @returns {Promise<PostEmptyResult>} The HTTP response result.
+ *
+ * @example
+ * // POST /api/settings/languages/en
+ * const result = await postEmpty(
+ *   "http://127.0.0.1:19119/api/settings/languages/en"
+ * );
+ *
+ * if (result.ok) {
+ *   console.log(result.status);
+ *   console.log(result.json);
+ * } else {
+ *   console.error(result.error);
+ * }
+ */
+async function postEmpty(url, debug = false) {
+  try {
+    const response = await fetch(url, { method: "POST" });
+
+    if (!response.ok) {
+      const result = {
+        url,
+        ok: false,
+        status: response.status,
+        error: JSON.parse(await response.text()),
+      };
+
+      if (debug) {
+        console.log("postEmpty", result);
+      }
+
+      return result;
+    }
+
+    const result = {
+      url,
+      ok: true,
+      status: response.status,
+      json: await response.json(),
+    };
+
+    if (debug) {
+      console.log("postEmpty", result);
     }
+
+    return result;
+  } catch (err) {
+    const result = {
+      url,
+      ok: false,
+      status: 0,
+      error: err.message,
+    };
+
+    if (debug) {
+      console.log("postEmpty", result);
+    }
+
+    return result;
+  }
 }
 
-async function postJson(url, body, debug=false, contentType = "application/json") {
-    try {
-        const response = await fetch(
-            url,
-            {
-                method: "POST",
-                headers: {"Content-Type": contentType},
-                body});
-        if (!response.ok) {
-            const result = {
-                url,
-                ok: false,
-                status: response.status,
-                error: await response.text()
-            };
-            if (debug) {
-                console.log("postJson", result);
-            }
-            return result;
-        }
-        const result = {
-            url,
-            ok: true,
-            status: response.status,
-            json: await response.json()
-        };
-        if (debug) {
-            console.log("postJson", result);
-        }
-        return result;
-    } catch (err) {
-        const result = {
-            url,
-            ok: false,
-            status: 0,
-            error: err.message
-        };
-        if (debug) {
-            console.log("postJson", result);
-        }
-        return result;
+/**
+ * Sends an HTTP POST request with a JSON request body.
+ *
+ * The request body is sent using the specified Content-Type.
+ * By default, the Content-Type is `application/json`.
+ *
+ * The server response is expected to contain JSON.
+ *
+ * @param {string} url - The URL to send the POST request to.
+ * @param {string|object} body - The request body. When using an object,
+ *   convert it to JSON with JSON.stringify() before passing it.
+ * @param {boolean} [debug=false] - If true, logs the request result to the console.
+ * @param {string} [contentType="application/json"] - The Content-Type
+ *   header sent with the request.
+ *
+ * @returns {Promise<PostJsonResult>} The HTTP response result.
+ *
+ * @example
+ * const body = JSON.stringify({
+ *   payload: JSON.stringify({
+ *     language: "en",
+ *   }),
+ * });
+ *
+ * const result = await postJson(
+ *   "http://127.0.0.1:19119/api/burrito/ingredient/raw/_local_/_local_/plt?ipath=test.json",
+ *   body
+ * );
+ *
+ * if (result.ok) {
+ *   console.log(result.json);
+ * } else {
+ *   console.error(result.error);
+ * }
+ *
+ * @example
+ * // Custom Content-Type
+ * const result = await postJson(
+ *   "https://example.com/api/data",
+ *   JSON.stringify({ hello: "world" }),
+ *   false,
+ *   "application/custom+json"
+ * );
+ */
+async function postJson(
+  url,
+  body,
+  debug = false,
+  contentType = "application/json",
+) {
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": contentType },
+      body,
+    });
+
+    if (!response.ok) {
+      const result = {
+        url,
+        ok: false,
+        status: response.status,
+        error: JSON.parse(await response.text()),
+      };
+
+      if (debug) {
+        console.log("postJson", result);
+      }
+
+      return result;
+    }
+
+    const result = {
+      url,
+      ok: true,
+      status: response.status,
+      json: await response.json(),
+    };
+
+    if (debug) {
+      console.log("postJson", result);
+    }
+
+    return result;
+  } catch (err) {
+    const result = {
+      url,
+      ok: false,
+      status: 0,
+      error: err.message,
+    };
+
+    if (debug) {
+      console.log("postJson", result);
     }
+
+    return result;
+  }
 }
 
-async function postText(url, body, debug=false, contentType = "text/plain") {
-    try {
-        const response = await fetch(
-            url,
-            {
-                method: "POST",
-                headers: {"Content-Type": contentType},
-                body});
-        if (!response.ok) {
-            const result = {
-                url,
-                ok: false,
-                status: response.status,
-                error: await response.text()
-            };
-            if (debug) {
-                console.log("postText", result);
-            }
-            return result;
-        }
-        const result = {
-            url,
-            ok: true,
-            status: response.status,
-            text: await response.text()
-        };
-        if (debug) {
-            console.log("postText", result);
-        }
-        return result;
-    } catch (err) {
-        const result = {
-            url,
-            ok: false,
-            status: 0,
-            error: err.message
-        };
-        if (debug) {
-            console.log("postText", result);
-        }
-        return result;
+/**
+ * Sends an HTTP POST request with a text request body.
+ *
+ * The request body is sent using the specified Content-Type.
+ * By default, the Content-Type is `application/json`.
+ *
+ * Unlike {@link postJson}, the response body is returned as text.
+ *
+ * @param {string} url - The URL to send the POST request to.
+ * @param {string} body - The text request body.
+ * @param {boolean} [debug=false] - If true, logs the request result to the console.
+ * @param {string} [contentType="application/json"] - The Content-Type
+ *   header sent with the request.
+ *
+ * @returns {Promise<PostTextResult>} The HTTP response result.
+ *
+ * @example
+ * const body = JSON.stringify({
+ *   payload: "this is a test",
+ * });
+ *
+ * const result = await postText(
+ *   "http://127.0.0.1:19119/api/burrito/ingredient/raw/_local_/_local_/plt?ipath=textTest.usfm",
+ *   body
+ * );
+ *
+ * if (result.ok) {
+ *   console.log(result.text);
+ * } else {
+ *   console.error(result.error);
+ * }
+ *
+ * @example
+ * // Sending plain text instead of JSON
+ * const result = await postText(
+ *   "https://example.com/api/text",
+ *   "this is a test",
+ *   false,
+ *   "text/plain"
+ * );
+ */
+async function postText(
+  url,
+  body,
+  debug = false,
+  contentType = "application/json",
+) {
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": contentType },
+      body,
+    });
+
+    if (!response.ok) {
+      const result = {
+        url,
+        ok: false,
+        status: response.status,
+        error: JSON.parse(await response.text()),
+      };
+
+      if (debug) {
+        console.log("postText", result);
+      }
+
+      return result;
     }
+
+    const result = {
+      url,
+      ok: true,
+      status: response.status,
+      text: await response.text(),
+    };
+
+    if (debug) {
+      console.log("postText", result);
+    }
+
+    return result;
+  } catch (err) {
+    const result = {
+      url,
+      ok: false,
+      status: 0,
+      error: err.message,
+    };
+
+    if (debug) {
+      console.log("postText", result);
+    }
+
+    return result;
+  }
 }
 
-export {postEmptyJson, postJson, postText};
+/**
+ * Sends an HTTP POST request containing binary data or multipart FormData.
+ *
+ * When using FormData, the Content-Type header is intentionally not set
+ * manually. The browser/runtime automatically creates the required
+ * multipart boundary.
+ *
+ * This is useful for uploading files or binary content to an API.
+ *
+ * @param {string} url - The URL to send the POST request to.
+ * @param {BodyInit} body - The request body. This can be FormData,
+ *   Uint8Array, ArrayBuffer, Blob, or another valid fetch BodyInit.
+ * @param {boolean} [debug=false] - If true, logs the request result to the console.
+ * @param {string|null} [contentType=null] - Optional Content-Type.
+ *   This is ignored when `body` is a FormData instance.
+ *
+ * @returns {Promise<PostBytesResult>} The HTTP response result.
+ *
+ * @example
+ * // Upload a file using multipart/form-data.
+ * const form = new FormData();
+ *
+ * form.append(
+ *   "file",
+ *   new Blob(["this is a test"], {
+ *     type: "application/octet-stream",
+ *   }),
+ *   "bytesTest.usfm"
+ * );
+ *
+ * const result = await postBytes(
+ *   "http://127.0.0.1:19119/api/burrito/ingredient/bytes/_local_/_local_/plt?ipath=bytesTest.usfm",
+ *   form
+ * );
+ *
+ * if (result.ok) {
+ *   console.log(result.text);
+ * } else {
+ *   console.error(result.error);
+ * }
+ *
+ * @example
+ * // Send raw binary data.
+ * const body = new TextEncoder().encode("this is a test");
+ *
+ * const result = await postBytes(
+ *   "https://example.com/api/upload",
+ *   body,
+ *   true,
+ *   "application/octet-stream"
+ * );
+ */
+async function postBytes(url, body, debug = false, contentType = null) {
+  try {
+    const headers = {};
+
+    if (!(body instanceof FormData) && contentType) {
+      headers["Content-Type"] = contentType;
+    }
+
+    const response = await fetch(url, {
+      method: "POST",
+      headers,
+      body,
+    });
+
+    if (!response.ok) {
+      const result = {
+        url,
+        ok: false,
+        status: response.status,
+        error: JSON.parse(await response.text()),
+      };
+
+      if (debug) {
+        console.log("postBytes", result);
+      }
+
+      return result;
+    }
+
+    const result = {
+      url,
+      ok: true,
+      status: response.status,
+      text: await response.text(),
+    };
+
+    if (debug) {
+      console.log("postBytes", result);
+    }
+
+    return result;
+  } catch (err) {
+    const result = {
+      url,
+      ok: false,
+      status: 0,
+      error: err.message,
+    };
+
+    if (debug) {
+      console.log("postBytes", result);
+    }
+
+    return result;
+  }
+}
+
+export {
+  postEmpty,
+  postJson,
+  postText,
+  postBytes,
+};
+

package/src/i18n/i18nLib.js

@@ -1,3 +1,44 @@
 const doI18n = (key, source) => source[key] || key;
 
-export {doI18n};
+const doInterpolatedI18n = (key, values, source = {}) => {
+    if (!Array.isArray(values)) {
+        throw new TypeError("Interpolation values must be an array of strings");
+    }
+    for (const value of values) {
+        if (typeof value !== "string") {
+            throw new TypeError("Interpolation values must be strings");
+        }
+    }
+
+    const template = source && source[key];
+    if (!template) {
+        throw new Error(`No localized string found for key: ${key}`);
+    }
+
+    if (typeof template !== "string") {
+        throw new TypeError("The localized string template must be a string");
+    }
+
+    const invalidPlaceholder = template.match(/%([^%]*)%/g)?.find((placeholder) => {
+        const position = placeholder.slice(1, -1);
+        return position === "" || (/\S/.test(position) && !/^\d+$/.test(position));
+    });
+    if (invalidPlaceholder) {
+        throw new SyntaxError(`Invalid interpolation placeholder: ${invalidPlaceholder}`);
+    }
+
+    const placeholders = template.match(/%\d+%/g) || [];
+    if (placeholders.length !== values.length) {
+        throw new RangeError("The number of interpolation values must match the placeholders");
+    }
+
+    return template.replace(/%(\d+)%/g, (placeholder, position) => {
+        const index = Number(position) - 1;
+        if (index < 0 || index >= values.length) {
+            throw new RangeError(`Placeholder ${placeholder} has no matching interpolation value`);
+        }
+        return values[index];
+    });
+};
+
+export {doI18n, doInterpolatedI18n};

package/src/i18n/index.js

@@ -1,3 +1,3 @@
-import { doI18n } from "./i18nLib.js";
+import { doI18n, doInterpolatedI18n } from "./i18nLib.js";
 
-export { doI18n };
+export { doI18n, doInterpolatedI18n };