Value tools | Gua Reference

Example: check the inventory contains the expected items

Compare a game’s JSON saying “key and map are held” with an expected set. parseValue takes the original JSON string and returns a validated value; valuesEqual returns whether the contents match. Invalid input raises ValueError.

Compare sets with a different item orderts

import { parseValue, valuesEqual } from "gua-value-tools";

const actual = parseValue('{"type":"set","elementType":"string","value":["key","map"]}');
const expected = parseValue('{"type":"set","elementType":"string","value":["map","key"]}');
console.log(valuesEqual(actual, expected)); // true

The game registers values outside the standard UI as Observe values: additional published observations. gua-value-tools handles received values; it does not register them or connect to the game. Register observations · Combine npm packages

Install the npm package

Install the packagepowershell

npm install gua-value-tools@latest

This is for a new setup. See npm packages for aligning an existing game and recording a lockfile.

gua-value-tools provides TypeScript types and validation, JSON parsing/serialization, enum catalogs, and semantic equality.

An enum is a value chosen from named alternatives. If a boss phase is First or Second, register those names in an EnumCatalog. Validation rejects unknown members or the wrong type.

Parse, validate, and compare an enumts

import { EnumCatalog, parseValue, serializeValue, valuesEqual } from "gua-value-tools";

const catalog = new EnumCatalog();
catalog.register("game.BossPhase", ["First", "Second"]);
const value = parseValue(
  '{"type":"enum","enumType":"game.BossPhase","value":"Second"}', catalog);
console.log(serializeValue(value, catalog));
console.log(valuesEqual(value, value, catalog));

Types and equality

Type	Contract
`bool`, `string`	Booleans and valid Unicode scalar strings; no case folding or Unicode normalization.
`integer`	Mathematical integers from −9007199254740991 to 9007199254740991, checked before binary64 rounding.
`number`	Finite binary64; distinct from integer even for the same numeric value.
`enum`	Explicit registered enum type and member name. Aliases with different names are different values.
`list`	Ordered homogeneous scalar elements; duplicates allowed.
`set`	Homogeneous scalar elements; order ignored for equality and duplicates rejected. Serialization preserves input order.

Empty collections retain elementType and any required enumType. Null, arbitrary objects, object references, nested collections, BigInt, NaN, and Infinity are forbidden. Different types are unequal; invalid values raise a validation error. Use valuesEqual rather than comparing serialized JSON bytes.

Enum catalog lifetime

Register a dotted explicit ID such as game.BossPhase and a nonempty set of unique member names. Re-registering the same ID with the same members succeeds regardless of member order; changing the member set is rejected. Use a new ID for a changed definition. Pass the corresponding catalog for enum validation, output, and equality, including empty enum collections. Catalogs are not global and do not infer IDs from language type names.

Native and .NET consumers

The same contract is available through gua/value.h, C++ gua::Value/gua::EnumCatalog, and Gua.Core.GuaValue/GuaEnumCatalog. C++ and .NET delegate to the native C ABI. The TypeScript package provides the same typed-value semantics.

Sources pinned to 1.1.0: package API, Value semantics and ABI, and schema.