usfm3 0.1.0 → 0.1.4

package/README.md

@@ -0,0 +1,81 @@
+# usfm3
+
+An error-tolerant [USFM 3.x](https://docs.usfm.bible/usfm/3.1.1/index.html) parser for JavaScript and TypeScript. Outputs [USJ](https://docs.usfm.bible/usfm/3.1.1/usj/index.html) (JSON), [USX](https://docs.usfm.bible/usfm/3.1.1/usx/index.html) (XML), and normalized USFM.
+
+Built in Rust and compiled to WebAssembly. Works in browsers, Node.js, Deno, and Bun.
+
+Also available as a [Rust crate](https://crates.io/crates/usfm3) and [Python package](https://pypi.org/project/usfm3/).
+
+## Installation
+
+```sh
+npm install usfm3
+```
+
+## Usage
+
+```typescript
+import init, { parse } from "usfm3";
+
+await init(); // load WASM (browser only — not needed in Node.js)
+
+const result = parse(usfmText);
+
+if (result.hasErrors()) {
+    console.error("Document has errors");
+}
+
+// Output formats (lazy — only serialized when called)
+const usj = result.toUsj();    // plain JS object
+const usx = result.toUsx();    // XML string
+const usfm = result.toUsfm();  // USFM string
+
+// Diagnostics
+for (const d of result.diagnostics) {
+    console.log(`[${d.severity}] ${d.message} (${d.start}..${d.end})`);
+    // d.code is a machine-readable string like "UnknownMarker", "ImplicitClose", etc.
+}
+
+// Skip semantic validation
+const result2 = parse(usfmText, { validate: false });
+
+// Free WASM memory when done
+result.free();
+```
+
+## API
+
+### `parse(usfm: string, options?: ParseOptions): ParseResult`
+
+Parse a USFM string. Returns a `ParseResult` with lazy output methods and diagnostics.
+
+**ParseOptions:**
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `validate` | `boolean` | `true` | Run semantic validation after parsing |
+
+### `ParseResult`
+
+| Method / Property | Returns | Description |
+|---|---|---|
+| `toUsj()` | `object` | USJ (Unified Scripture JSON) |
+| `toUsx()` | `string` | USX (Unified Scripture XML) |
+| `toUsfm()` | `string` | Normalized USFM |
+| `hasErrors()` | `boolean` | True if any error-severity diagnostics |
+| `diagnostics` | `Diagnostic[]` | Parser and validation diagnostics |
+| `free()` | `void` | Free WASM memory |
+
+### `Diagnostic`
+
+| Property | Type | Description |
+|---|---|---|
+| `severity` | `string` | `"error"`, `"warning"`, or `"info"` |
+| `code` | `string` | Machine-readable code (e.g. `"UnknownMarker"`) |
+| `message` | `string` | Human-readable message |
+| `start` | `number` | Start byte offset in source |
+| `end` | `number` | End byte offset in source |
+
+## License
+
+MIT

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "usfm3",
   "type": "module",
-  "version": "0.1.0",
+  "version": "0.1.4",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jcuenod/usfm3"
+  },
   "files": [
     "usfm3_wasm_bg.wasm",
     "usfm3_wasm.js",
@@ -12,4 +16,4 @@
   "sideEffects": [
     "./snippets/*"
   ]
-}
+}