5etools Utils

https://github.com/zjhsteven/5etools-utils
Admin
5etools Utils provides command-line utilities for testing and validating JSON breweries and...
Tokens:6,911
Snippets:52
Trust Score:5.6
Update:10 months ago
Show doc for...
Tokens:
Raw
### Validate File Names - CLI

Source: https://context7.com/zjhsteven/5etools-utils/llms.txt

Command-line tool to validate file naming conventions across the project using npx.

```bash
# Run file name tests
npx test-file-names
```

--------------------------------

### Logging and Utilities with Um (UtilMisc)

Source: https://context7.com/zjhsteven/5etools-utils/llms.txt

Um (UtilMisc) offers convenient logging utilities with customizable tags for different message types (info, warn, error). It also includes utility functions for comparing sets for equality and performing fast deep copies of objects, ensuring original objects remain unchanged.

```javascript
import Um from "5etools-utils";

// Info logging
Um.info("VALIDATOR", "Starting validation process...");
// Output: [VALIDATOR] Starting validation process...

// Warning logging
Um.warn("CLEANER", "File missing timestamp, adding default");
// Output: [CLEANER] File missing timestamp, adding default

// Error logging
Um.error("SCHEMA", "Validation failed for creature.json");
// Output: [SCHEMA] Validation failed for creature.json

// Set equality check
const set1 = new Set([1, 2, 3]);
const set2 = new Set([3, 2, 1]);
console.log(Um.setEq(set1, set2)); // true

// Deep copy objects
const original = { name: "Test", nested: { value: 42 } };
const copy = Um.copyFast(original);
copy.nested.value = 100;
console.log(original.nested.value); // 42 (unchanged)
```

--------------------------------

### Validate File Locations - CLI

Source: https://context7.com/zjhsteven/5etools-utils/llms.txt

Command-line tool to verify that files are located in their expected directory paths using npx.

```bash
# Run file location tests
npx test-file-locations
```

--------------------------------

### BrewIndexGenerator Class API

Source: https://context7.com/zjhsteven/5etools-utils/llms.txt

Generates various index files for homebrew content, facilitating quick lookups by timestamps, properties, sources, and metadata.

```APIDOC
## BrewIndexGenerator Class

### Description
Generates index files for quick lookup of homebrew content.

### Usage
```javascript
import { BrewIndexGenerator } from "5etools-utils";

// Generate all indexes
BrewIndexGenerator.run();

// Creates the following indexes in _generated/:
// - index-timestamps.json (dateAdded, dateLastModified, datePublished)
// - index-props.json (properties mapped to files)
// - index-sources.json (source abbreviations to files)
// - index-meta.json (metadata like names, status, edition)
// - index-adventure-book-ids.json (adventure/book ID mappings)

// Example index-sources.json structure:
// {
//   "MySource": "collection/My Homebrew.json"
// }

// Example index-timestamps.json structure:
// {
//   "collection/My Homebrew.json": {
//     "a": 1639392000,  // dateAdded
//     "m": 1640601600,  // dateLastModified
//     "p": 1640601600   // datePublished
//   }
// }
```
```

--------------------------------

### JSON Schema Validation - test-json-brew

Source: https://context7.com/zjhsteven/5etools-utils/llms.txt

Command-line tool for validating homebrew JSON files against predefined schemas. It can test single files or all JSON files within a directory.

```APIDOC
## JSON Schema Validation - test-json-brew

### Description
Command-line tool for validating homebrew JSON files against predefined schemas.

### Usage
```bash
# Test a single file
npx test-json-brew creature.json

# Test all JSON files in a directory
npx test-json-brew --dir ./homebrew

# Test with environment variables for verbose output
VET_TEST_JSON_RESULTS_UNSORTED=1 VET_TEST_JSON_QUIET=0 npx test-json-brew myfile.json
```
```

--------------------------------

### UtilFs: File System Operations

Source: https://context7.com/zjhsteven/5etools-utils/llms.txt

A collection of utility functions for common file system operations. This includes reading and writing JSON files (with BOM handling and formatting), listing JSON files recursively, executing functions on directories (serially or in parallel), copying files/directories, and recursively listing all files. It supports synchronous and asynchronous operations.

```javascript
import * as Uf from "5etools-utils";

// Read JSON file (handles BOM, case-insensitive paths)
const data = Uf.readJsonSync("./homebrew/creature.json");
console.log(data);

// Write JSON with automatic formatting
Uf.writeJsonSync("./output.json", { name: "Test" }, { isClean: true });

// List all JSON files recursively
const jsonFiles = Uf.listJsonFiles("./homebrew", {
  dirBlocklist: ["node_modules", ".git"]
});
console.log(`Found ${jsonFiles.length} JSON files`);

// Run function on each top-level directory
Uf.runOnDirs((dir) => {
  console.log(`Processing directory: ${dir}`);
  // Your logic here
});

// Async version with parallel execution
await Uf.pRunOnDirs(async (dir) => {
  console.log(`Processing ${dir}...`);
  await someAsyncOperation(dir);
}, {
  root: ".",
  isSerial: false // Set true to run sequentially
});

// Copy files/directories
Uf.copySync("./source", "./destination", {
  isForce: true,
  isDryRun: false
});

// List all files recursively
const allFiles = Uf.lsRecursiveSync("./homebrew");
```

--------------------------------

### Validate File Properties - CLI

Source: https://context7.com/zjhsteven/5etools-utils/llms.txt

Command-line tool to validate the properties within JSON files using npx.

```bash
# Run file property tests
npx test-file-props
```

--------------------------------

### Conditional Merging with $$ifBrew/$$ifSite/$$ifUa

Source: https://github.com/zjhsteven/5etools-utils/blob/master/schema-template/README.md

Demonstrates how preprocessor properties like `$$ifBrew`, `$$ifSite`, and `$$ifUa` conditionally merge object values into their parent based on the current compilation mode. This allows for mode-specific schema configurations.

```json
{
	"$$ifBrew": {
		"b": 1
	}
}
```

```json
{
	"$$ifSite": {
		"a": 1
	},
	"$$ifBrew": {
		"a": 2
	}
}
```

--------------------------------

### Validate Homebrew JSON - CLI

Source: https://context7.com/zjhsteven/5etools-utils/llms.txt

Command-line interface for validating homebrew JSON files against predefined schemas using npx. Supports single file or directory validation, with options for verbose output via environment variables.

```bash
# Test a single file
npx test-json-brew creature.json

# Test all JSON files in a directory
npx test-json-brew --dir ./homebrew

# Test with environment variables for verbose output
VET_TEST_JSON_RESULTS_UNSORTED=1 VET_TEST_JSON_QUIET=0 npx test-json-brew myfile.json
```

--------------------------------

### Schema Validation with UtilAjv

Source: https://context7.com/zjhsteven/5etools-utils/llms.txt

UtilAjv simplifies JSON schema validation by providing a preconfigured AJV instance that includes necessary formats. You can add custom schemas and then validate data objects against them, with errors reported if validation fails.

```javascript
import { UtilAjv } from "5etools-utils";

// Get preconfigured AJV instance with formats
const ajv = UtilAjv.getValidator();

// Add schema
ajv.addSchema({
  type: "object",
  properties: {
    name: { type: "string" },
    level: { type: "number", minimum: 1, maximum: 20 }
  },
  required: ["name", "level"]
}, "character.json");

// Validate data
const valid = ajv.validate("character.json", {
  name: "Elara",
  level: 5
});

if (!valid) {
  console.error("Validation errors:", ajv.errors);
} else {
  console.log("Data is valid!");
}
```

--------------------------------

### File Name Validation

Source: https://context7.com/zjhsteven/5etools-utils/llms.txt

Validates file naming conventions across the project using a command-line interface.

```APIDOC
## File Name Validation

### Description
Validates file naming conventions across the project.

### Usage
```bash
# Run file name tests
npx test-file-names
```
```

--------------------------------

### Validate Unearthed Arcana JSON - CLI

Source: https://context7.com/zjhsteven/5etools-utils/llms.txt

Command-line interface for validating Unearthed Arcana (UA) JSON files using npx. Allows testing single files, directories, and features a 'fail slow' mode to report all errors.

```bash
# Test a single UA file
npx test-json-ua ua-content.json

# Test all UA files in directory
npx test-json-ua --dir ./ua-content

# Fail slow mode - continue after errors to see all issues
FAIL_SLOW=1 npx test-json-ua --dir ./ua-content
```

--------------------------------

### BrewCleaner Class API

Source: https://context7.com/zjhsteven/5etools-utils/llms.txt

A class to clean and validate brew files, automatically handling timestamps, source definitions, filenames, and JSON formatting.

```APIDOC
## BrewCleaner Class

### Description
Cleans and validates brew files, ensuring proper formatting and metadata. Automatically handles timestamps, source definitions, filenames, and JSON formatting.

### Usage
```javascript
import { BrewCleaner } from "5etools-utils";

// Run cleaner on all directories
try {
  BrewCleaner.run();
  console.log("Cleaning complete!");
} catch (error) {
  console.error("Cleaning failed:", error.message);
}

// The cleaner automatically:
// - Adds missing dateAdded and dateLastModified timestamps
// - Converts millisecond timestamps to seconds
// - Validates source definitions
// - Checks for invalid filename characters
// - Ensures .json extension (case-sensitive)
// - Formats JSON with proper indentation
// - Validates sources are declared in _meta
```
```

--------------------------------

### Validate Content Sources with UtilSource

Source: https://context7.com/zjhsteven/5etools-utils/llms.txt

UtilSource provides functions to validate if a given source is an official 5etools source or a valid homebrew source format. It performs case-insensitive checks for official sources and adheres to a specific schema for homebrew source naming conventions, returning false for invalid characters.

```javascript
import { UtilSource } from "5etools-utils";

// Check if source is official 5etools source
const isOfficial = UtilSource.isSiteSource("PHB");
console.log(isOfficial); // true

const isOfficial2 = UtilSource.isSiteSource("MyHomebrew");
console.log(isOfficial2); // false

// Case-insensitive check
const isOfficial3 = UtilSource.isSiteSource("phb");
console.log(isOfficial3); // true

// Validate homebrew source format
const isValidHomebrew = UtilSource.isValidHomebrewSorce("MySource123");
console.log(isValidHomebrew); // true or false based on schema

// Invalid characters return false
const isValidHomebrew2 = UtilSource.isValidHomebrewSorce("My@Source#");
console.log(isValidHomebrew2); // false
```

--------------------------------

### Index Generation API - BrewIndexGenerator

Source: https://context7.com/zjhsteven/5etools-utils/llms.txt

JavaScript API for generating index files for homebrew content. The `BrewIndexGenerator` class creates various indexes in the `_generated/` directory for quick lookup of timestamps, properties, sources, metadata, and adventure IDs.

```javascript
import { BrewIndexGenerator } from "5etools-utils";

// Generate all indexes
BrewIndexGenerator.run();

// Creates the following indexes in _generated/:
// - index-timestamps.json (dateAdded, dateLastModified, datePublished)
// - index-props.json (properties mapped to files)
// - index-sources.json (source abbreviations to files)
// - index-meta.json (metadata like names, status, edition)
// - index-adventure-book-ids.json (adventure/book ID mappings)

// Example index-sources.json structure:
// {
//   "MySource": "collection/My Homebrew.json"
// }

// Example index-timestamps.json structure:
// {
//   "collection/My Homebrew.json": {
//     "a": 1639392000,  // dateAdded
//     "m": 1640601600,  // dateLastModified
//     "p": 1640601600   // datePublished
//   }
// }
```

--------------------------------

### Dynamic Key Selection with $$switch_key

Source: https://github.com/zjhsteven/5etools-utils/blob/master/schema-template/README.md

Explains the `$$switch_key` preprocessor directive, which merges a key-value pair into the parent object. The key used for merging is determined by the compilation mode, allowing for dynamic schema key names.

```json
{
	"$$switch_key": {
		"key_site": "enum",
		"key_ua": "enum",
		"key_brew": "examples",
		"value": [1]
	}
}
```

--------------------------------

### Brew File Cleaning API - BrewCleaner

Source: https://context7.com/zjhsteven/5etools-utils/llms.txt

JavaScript API for cleaning and validating brew files. The `BrewCleaner` class automatically adds timestamps, converts date formats, validates sources, checks filenames, ensures correct extensions, formats JSON, and validates sources against the _meta file.

```javascript
import { BrewCleaner } from "5etools-utils";

// Run cleaner on all directories
try {
  BrewCleaner.run();
  console.log("Cleaning complete!");
} catch (error) {
  console.error("Cleaning failed:", error.message);
}

// The cleaner automatically:
// - Adds missing dateAdded and dateLastModified timestamps
// - Converts millisecond timestamps to seconds
// - Validates source definitions
// - Checks for invalid filename characters
// - Ensures .json extension (case-sensitive)
// - Formats JSON with proper indentation
// - Validates sources are declared in _meta
```

--------------------------------

### JSON Schema Validation - test-json-ua

Source: https://context7.com/zjhsteven/5etools-utils/llms.txt

Command-line tool for validating Unearthed Arcana (UA) JSON files. Supports testing single files, directories, and a 'fail slow' mode.

```APIDOC
## JSON Schema Validation - test-json-ua

### Description
Command-line tool for validating Unearthed Arcana JSON files. It can test single files, all files in a directory, and has a 'fail slow' option.

### Usage
```bash
# Test a single UA file
npx test-json-ua ua-content.json

# Test all UA files in directory
npx test-json-ua --dir ./ua-content

# Fail slow mode - continue after errors to see all issues
FAIL_SLOW=1 npx test-json-ua --dir ./ua-content
```
```

--------------------------------

### Conditional Array Items with $$ifBrew_item/$$ifSite_item/$$ifUa_item

Source: https://github.com/zjhsteven/5etools-utils/blob/master/schema-template/README.md

Illustrates the usage of `$$ifBrew_item`, `$$ifSite_item`, and `$$ifUa_item` for conditionally including values within arrays based on the compilation mode. These are specifically designed for array contexts.

```json
{
	"myArray": [
		{"$$ifBrew_item": 1},
		2,
		3
	]
}
```

--------------------------------

### File Properties Validation

Source: https://context7.com/zjhsteven/5etools-utils/llms.txt

Validates the properties present within JSON files to ensure data consistency.

```APIDOC
## File Properties Validation

### Description
Validates properties within JSON files.

### Usage
```bash
# Run file property tests
npx test-file-props
```
```

--------------------------------

### File Location Validation

Source: https://context7.com/zjhsteven/5etools-utils/llms.txt

Tests that files are located in their expected directory paths within the project structure.

```APIDOC
## File Location Validation

### Description
Tests that files are in their expected directory locations.

### Usage
```bash
# Run file location tests
npx test-file-locations
```
```

--------------------------------

### JsonTester Class API

Source: https://context7.com/zjhsteven/5etools-utils/llms.txt

Provides a JavaScript API for schema validation with support for parallel processing, ideal for large datasets.

```APIDOC
## JsonTester Class

### Description
JavaScript API for schema validation with parallel processing support.

### Usage
```javascript
import { JsonTester } from "5etools-utils";

// Create a tester for homebrew content
const tester = new JsonTester({
  mode: "brew", // or "ua" for Unearthed Arcana, "site" for official content
  fnGetSchemaId: (filePath) => "homebrew.json"
});

// Initialize and load schemas
await tester.pInit();

// Test a single file
const fileResults = tester.getFileErrors({
  filePath: "./homebrew/creature.json"
});

if (fileResults.errors.length) {
  console.error("Validation errors:", fileResults.errors);
} else {
  console.log("File is valid!");
}

// Test multiple files with parallel workers
const results = await tester.pGetErrorsOnDirsWorkers({
  isFailFast: false
});

console.log(`Found ${results.errors.length} errors`);
console.log(`Unknown errors: ${results.isUnknownError}`);
```

### Constructor Options
*   **mode** (string) - "brew", "ua", or "site".
*   **fnGetSchemaId** (function) - A function that takes a file path and returns the schema ID to use for validation.
```

--------------------------------

### UtilClean: JSON and String Formatting

Source: https://context7.com/zjhsteven/5etools-utils/llms.txt

Provides utility functions getCleanJson and getCleanString for cleaning and formatting JSON data and strings. It handles standardized character replacements, including unicode escapes for special characters and proper escaping of quotes within strings. This ensures consistent and safe JSON output.

```javascript
import { getCleanJson, getCleanString } from "5etools-utils";

// Clean an object (returns formatted JSON string)
const obj = {
  name: "Göblin",
  description: "An em—dash and smart quotes \"here\""
};

const cleanedJson = getCleanJson(obj);
console.log(cleanedJson);
// Output: properly formatted with unicode escapes
// "name": "Göblin"
// "description": "An em\u2014dash and smart quotes \"here\""

// Clean a string directly
const dirtyString = "Smart quotes: \"test\"";
const cleaned = getCleanString(dirtyString);
console.log(cleaned); // "Smart quotes: \"test\""
```

--------------------------------

### BrewTimestamper: Update Git-based Timestamps

Source: https://context7.com/zjhsteven/5etools-utils/llms.txt

The BrewTimestamper class automatically updates modification timestamps for files based on git history. It computes file content hashes, compares them to stored hashes, and updates 'dateLastModified' from git logs if content has changed. This process runs serially to prevent git conflicts. The timestamp update is reflected in a '_meta' object within JSON files.

```javascript
import { BrewTimestamper } from "5etools-utils";

// Update timestamps for all files
await BrewTimestamper.pRun();

// The timestamper:
// - Computes hash of file content (excluding timestamps)
// - Compares with stored _dateLastModifiedHash
// - Updates dateLastModified from git log if content changed
// - Stores new hash in _meta._dateLastModifiedHash
// - Runs serially to avoid git conflicts

// Example of timestamp update in JSON:
// {
//   "_meta": {
//     "dateAdded": 1639392000,
//     "dateLastModified": 1640601600,
//     "_dateLastModifiedHash": "a1b2c3d4e5"
//   }
// }
```

--------------------------------

### Schema Validation API - JsonTester

Source: https://context7.com/zjhsteven/5etools-utils/llms.txt

JavaScript API for performing schema validation, utilizing parallel processing for efficiency. The `JsonTester` class supports different content modes (brew, ua, site) and custom schema ID retrieval.

```javascript
import { JsonTester } from "5etools-utils";

// Create a tester for homebrew content
const tester = new JsonTester({
  mode: "brew", // or "ua" for Unearthed Arcana, "site" for official content
  fnGetSchemaId: (filePath) => "homebrew.json"
});

// Initialize and load schemas
await tester.pInit();

// Test a single file
const fileResults = tester.getFileErrors({
  filePath: "./homebrew/creature.json"
});

if (fileResults.errors.length) {
  console.error("Validation errors:", fileResults.errors);
} else {
  console.log("File is valid!");
}

// Test multiple files with parallel workers
const results = await tester.pGetErrorsOnDirsWorkers({
  isFailFast: false
});

console.log(`Found ${results.errors.length} errors`);
console.log(`Unknown errors: ${results.isUnknownError}`);
```

--------------------------------

### DataTester: Custom Data Integrity Validation

Source: https://context7.com/zjhsteven/5etools-utils/llms.txt

The DataTester classes facilitate data integrity testing using custom validators. It includes pre-built checkers like BraceCheck and EscapeCharacterCheck, and allows for the creation of custom testers by extending DataTesterBase. Tests can be run on directories with options to ignore specific files or directories. A log report is generated to indicate validation failures.

```javascript
import {
  DataTester,
  DataTesterBase,
  BraceCheck,
  EscapeCharacterCheck
} from "5etools-utils";

// Create custom testers
const braceCheck = new BraceCheck();
const escapeCheck = new EscapeCharacterCheck();

const testers = [braceCheck, escapeCheck];

// Register testers
DataTester.register({ dataTesters: testers });

// Run tests on directory
await DataTester.pRun(
  "./homebrew",
  testers,
  {
    fnIsIgnoredFile: (path) => path.includes("test"),
    fnIsIgnoredDirectory: (path) => path.includes("node_modules")
  }
);

// Get results
const report = DataTester.getLogReport(testers);
if (report) {
  console.error("Data validation failed!");
  console.error(report);
  process.exit(1);
}

// Create custom tester
class CustomTester extends DataTesterBase {
  registerParsedPrimitiveHandlers(checker) {
    checker.addPrimitiveHandler("string", this._checkString.bind(this));
  }

  _checkString(str, { filePath }) {
    if (str.includes("TODO")) {
      this._addMessage(`Found TODO in ${filePath}: ${str}\n`);
    }
  }
}
```

--------------------------------

### ObjectWalker: Recursive JSON Object Traversal

Source: https://context7.com/zjhsteven/5etools-utils/llms.txt

The ObjectWalker class enables recursive traversal of JSON objects with customizable handlers for different data types (primitives, arrays, objects). It allows for modification of values during traversal and provides a mechanism to break out of the walking process early. This is useful for deep object manipulation and conditional processing.

```javascript
import { ObjectWalker, SymObjectWalkerBreak } from "5etools-utils";

// Walk an object and process strings
const result = ObjectWalker.walk({
  obj: { name: "Goblin", hp: 7, tags: ["humanoid", "goblinoid"] },
  filePath: "./creatures.json",
  primitiveHandlers: {
    string: (str, { filePath, lastKey }) => {
      console.log(`Found string: ${str} at key: ${lastKey}`);
      return str.toUpperCase(); // Modify if needed
    },
    number: (num) => {
      return num * 2; // Double all numbers
    },
    array: (arr) => {
      console.log(`Processing array with ${arr.length} items`);
      return arr;
    }
  },
  isModify: true // Set to true to modify the object
});

// Break out of walking early
ObjectWalker.walk({
  obj: data,
  primitiveHandlers: {
    string: (str) => {
      if (str.includes("SECRET")) {
        return SymObjectWalkerBreak; // Stop walking
      }
      return str;
    }
  }
});
```

--------------------------------

### Conditional Merging with $$if

Source: https://github.com/zjhsteven/5etools-utils/blob/master/schema-template/README.md

Details the `$$if` preprocessor directive, which conditionally merges a specified `value` into its parent object if the compilation mode is present in the `modes` array. This provides flexible conditional logic for schema properties.

```json
{
	"$$if": {
		"modes": ["site", "ua"],
		"value": {
			"a": 1
		}
	}
}
```

--------------------------------

### Conditional Array Items with $$if_item

Source: https://github.com/zjhsteven/5etools-utils/blob/master/schema-template/README.md

Describes the `$$if_item` preprocessor directive, designed for use within arrays. It conditionally includes its `value` in the array if the compilation mode matches any mode listed in the `modes` array.

```json
{
	"myArray": [
		{
			"$$if_item": {
				"modes": ["site", "ua"],
				"value": 1
			}
		},
		2,
		3
	]
}
```
Tokens:
Raw