json_to_prolog 0.3.1

# json_to_prolog

`json_to_prolog` converts structured JSON descriptions of facts, queries, and rules into Prolog source code. It is published as both a Rust crate (for native use) and a Wasm package (for npm), so you can validate domain data on the server or in the browser with the same logic.

> [!WARNING]
> The schema is still evolving. Expect breaking changes before `1.0.0`.

## Features

- JSON Schema validation for each claim type (facts, rules, queries) before conversion.
- Deterministic Prolog output (fields sorted alphabetically, consistent quoting, and wildcard handling).
- Support for logical combinators (`and`, `or`, `not`) when defining rule bodies.
- Wasm bindings generated with `wasm-bindgen`, making the same API available on npm.

## Installation

### Rust (crates.io)

```toml
[dependencies]
json_to_prolog = "0.3.0"
```

### JavaScript/TypeScript (npm)

```bash
npm install json_to_prolog
# or
yarn add json_to_prolog
```

The npm package ships pre-built Wasm bindings in `pkg/`. You can import the helper functions from `json_to_prolog` or use the generated JS glue directly.

## Quick Start

### Converting a fact (Rust)

```rust
use json_to_prolog::convert_fact_to_prolog;
use serde_json::json;

let fact = json!({
 "claimType": "fact",
 "predicate": "person",
 "updateView": "assert",
 "name": "Alice",
 "age": 30,
 "active": true,
 "nickname": null // converted to wildcard `_`
});

let prolog = convert_fact_to_prolog(&fact)?;
assert_eq!(prolog, "assert(person(true, 30, 'Alice', _)).");
```

### JavaScript + SWI-Prolog (Node)

```ts
import init, {
  convert_fact_to_prolog_wasm,
  convert_query_to_prolog_wasm,
} from "json_to_prolog";
import SWIPL from "swipl-wasm";

const main = async () => {
  await init();
  const swipl = await SWIPL({ arguments: ["-q"] });

  const fact = {
    claimType: "fact",
    predicate: "person",
    name: "Alice",
    age: 20,
    updateView: "assert",
  };

  const query = {
    claimType: "query",
    predicate: "person",
    name: "Alice",
    age: { var: "Age" },
  };

  const factClause = convert_fact_to_prolog_wasm(fact);
  const queryClause = convert_query_to_prolog_wasm(query);

  await swipl.prolog.call(factClause); // assert fact once
  const results = await swipl.prolog.query(queryClause);
  console.log(results.once()); // -> { Age: "20" }
};

main();
```

### Converting a rule

```rust
use json_to_prolog::convert_rule_to_prolog;
use serde_json::json;

let rule = json!({
 "claimType": "rule",
 "name": "grandparent",
 "headVariables": [{ "var": "X" }, { "var": "Z" }],
 "returns": "boolean",
 "evaluate": {
  "and": [
   { "predicate": "parent", "args": [{ "var": "X" }, { "var": "Y" }] },
   { "predicate": "parent", "args": [{ "var": "Y" }, { "var": "Z" }] }
  ]
 }
});

let prolog = convert_rule_to_prolog(&rule)?;
assert_eq!(prolog, "assert(grandparent(X, Z) :- (parent(X, Y), parent(Y, Z))).");
```

### Converting a query

```rust
use json_to_prolog::convert_query_to_prolog;
use serde_json::json;

let query = json!({
 "claimType": "query",
 "predicate": "person",
 "name": { "var": "Name" },
 "age": { "var": "Age" }
});

let prolog = convert_query_to_prolog(&query)?;
assert_eq!(prolog, "person(Age, Name)");
```

## JSON Schema Overview

Each converter validates its input using [jsonschema](https://docs.rs/jsonschema) before emitting Prolog:

- **Facts** – must provide `claimType: "fact"` and `predicate`. The optional `updateView` field can be one of: `"assert"`, `"retract"`, `"assertz"`, `"asserta"` (defaults to `"assert"` if omitted). Additional keys become arguments and are sorted alphabetically for deterministic output.
- **Rules** – require `claimType: "rule"`, a head name, `headVariables`, and an `evaluate` tree composed of logic nodes (`predicate`, `and`, `or`, `not`). Only `boolean` rules are currently supported. The optional `updateView` defaults to `"assert"`.
- **Queries** – must include `claimType: "query"` and a `predicate`; any other properties become arguments. Objects of the form `{ "var": "VarName" }` produce bare Prolog variables.

Null JSON values translate to the wildcard `_`. Arrays become Prolog lists, and strings are single-quoted to match atom syntax. Objects shaped like `{ "var": "Token" }` insert the token verbatim (useful for variables or pre-declared atoms). The `claimType` field is filtered out during conversion and does not appear in the generated Prolog code.

## API Surface

Rust functions:

- `convert_json_to_prolog(value: &Value) -> Result<String, String>` – **Unified converter** that dispatches to the appropriate converter based on `claimType`
- `convert_fact_to_prolog(value: &Value) -> Result<String, String>`
- `convert_rule_to_prolog(value: &Value) -> Result<String, String>`
- `convert_query_to_prolog(value: &Value) -> Result<String, String>`

Wasm bindings expose the same conversions but accept/return `JsValue`:

- `convert_json_to_prolog_wasm(value: &JsValue) -> Result<JsValue, JsValue>` – **Unified converter**
- `convert_fact_to_prolog_wasm(value: &JsValue) -> Result<JsValue, JsValue>`
- `convert_rule_to_prolog_wasm(value: &JsValue) -> Result<JsValue, JsValue>`
- `convert_query_to_prolog_wasm(value: &JsValue) -> Result<JsValue, JsValue>`

All functions return descriptive error messages when validation fails. The unified `convert_json_to_prolog` function is recommended when you have mixed claim types or want automatic dispatch based on the `claimType` field.

## Development

Prerequisites:

- Rust toolchain (stable)
- `wasm-pack` (for rebuilding the npm package)

Helpful commands:

```bash
cargo test           # Run the unit test suite
wasm-pack build --target bundler  # Rebuild Wasm bindings
```

Before publishing to crates.io or npm, ensure tests pass and review the schema contracts. Because the project is still experimental, contributions that extend validation or add new claim types are welcome—open an issue or PR describing your idea.

## License

MIT. See `Cargo.toml` for the authoritative declaration.