Orgize

When working with the orgize WASM package, keep these two lifecycle rules in mind:

1. Initialization: You must call either init (asynchronous) or initSync (synchronous) to initialize the WebAssembly module before attempting to use the Org class.
2. Memory Cleanup: Because the core logic is written in Rust, memory is allocated outside of the standard JavaScript garbage collector. You must call org.free() on your Org instances to release this memory.

In Node.js, you must manually load the .wasm file bytes and initialize the module using initSync. This typically involves resolving the path to the orgize/wasm file within the package.

Important: You must call org.free() to release the memory allocated by the underlying Rust implementation.

import { Org, initSync } from "orgize";
import { readFile } from "node:fs/promises";
import { createRequire } from "node:module";

const require = createRequire(import.meta.url);

readFile(require.resolve("orgize/wasm")).then((bytes) => {
  initSync(bytes);

  const org = new Org("* Hello, /world/!");
  const html = org.html();
  console.log(html);
  org.free();
});

To benchmark the parsing performance, you must first download the sample Org files into the ./benches/ directory, then run the benchmark command:

curl -q https://orgmode.org/worg/doc.org --output ./benches/doc.org
curl -q https://orgmode.org/worg/org-faq.org --output ./benches/org-faq.org
curl -q https://orgmode.org/worg/org-hacks.org --output ./benches/org-hacks.org
curl -q https://orgmode.org/worg/org-release-notes.org --output ./benches/org-release-notes.org
curl -q https://orgmode.org/worg/org-syntax.org --output ./benches/org-syntax.org
curl -q https://raw.githubusercontent.com/bzg/org-mode/main/doc/org-manual.org --output ./benches/org-manual.org

cargo bench --bench parse

Fuzz testing is used to find edge cases and potential crashes. This requires cargo-fuzz and a nightly Rust toolchain:

cargo install cargo-fuzz
rustup default nightly
cargo fuzz run fuzz_target_1

To ensure code quality and compliance with project standards, run the following commands to check formatting, execute all tests, and run Clippy linting:

cargo fmt -- --check
cargo test --all-features
cargo clippy --allow-dirty --allow-staged

You can install the orgize package using standard package managers.

npm install orgize
yarn add orgize

The project uses cargo-insta for snapshot testing. To run tests and review changes to snapshots, follow these steps:

cargo install cargo-insta
cargo insta test --all-features
cargo insta review

To use orgize in a browser environment, you must first initialize the WebAssembly module using the init function. Once initialized, you can instantiate the Org class to parse Org syntax and generate HTML.

Important: You must call org.free() to release the memory allocated by the underlying Rust implementation to prevent memory leaks.

import init, { Org } from "orgize";

init().then(() => {
  const org = new Org("* Hello, /world/!");
  const html = org.html();
  console.log(html);
  org.free();
});

To visualize performance bottlenecks during parsing, use flamegraph. This generates a baseline.svg file which can be opened in any web browser:

cargo install flamegraph
cargo flamegraph --bench parse -o baseline.svg -- --bench
# then open baseline.svg with your browser

Orgize includes optional features that must be enabled in your Cargo.toml to use specific conversion capabilities:

• chrono: Enables converting Timestamp into chrono::NaiveDateTime.
• indexmap: Enables converting PropertyDrawer properties into IndexMap.

The use_sub_superscript field in ParseConfig determines how sub/superscripts are handled during parsing. This is equivalent to the org-use-sub-superscripts setting in Emacs Org-mode.

• UseSubSuperscript::Nil: Disables sub/superscript parsing.
• UseSubSuperscript::True: Enables parsing (standard behavior).
• UseSubSuperscript::Brace: Enables parsing, but requires braces to identify sub/superscripts.

// Example of requiring braces for sub/superscripts
let config = ParseConfig {
    use_sub_superscript: UseSubSuperscript::Brace,
    ..Default::default()
};