xword-core

Core types, parser, validator, and checker for crossword puzzles.

Install

npm install xword-core

Usage

import { parsePuzzle, serializePuzzle, checkPuzzle, formatPuzzle } from "xword-core";

// Parse and validate a puzzle from JSON
const puzzle = parsePuzzle(JSON.parse(fs.readFileSync("puzzle.json", "utf8")));

// Check a player's solution
const result = checkPuzzle(puzzle, {
  version: "1.0",
  grid: {
    width: puzzle.grid.width,
    height: puzzle.grid.height,
    cells: [["C", "L", "U", "E", "S"], /* ... */],
  },
});
// result.grid.cells[y][x] → "correct" | "incorrect" | "empty" | null

// Pretty-print to the terminal
formatPuzzle(puzzle); // returns a string
printPuzzle(puzzle);  // console.log shorthand

// Serialize back to JSON
const json = serializePuzzle(puzzle);

API

Parsing & serialization

• parsePuzzle(input: unknown): Puzzle — validates structure and semantics, throws ParseError on failure
• serializePuzzle(puzzle: Puzzle): string — formats to JSON
• ParseError — thrown by parsePuzzle; instanceof-checkable

Checking

• checkPuzzle(puzzle, solution): CheckResult — compares a Solution against the puzzle answer key

Validation

• validatePuzzle(puzzle: Puzzle): boolean — useful when building puzzles programmatically

Display

• formatPuzzle(puzzle: Puzzle): string — ANSI-formatted grid and clues for terminal output
• printPuzzle(puzzle: Puzzle): void — console.log shorthand

Types

Puzzle, PuzzleMeta, Grid, Cell, BlockCell, LetterCell, Clue, Clues, Difficulty, Letter, CellDecoration, Solution, SolutionCell, CheckResult, CheckResultCell

Puzzle format

Puzzles are stored as JSON. The canonical schema is the Puzzle TypeScript type. See src/fixtures/ for examples.