json-rule-engine-csv

Compile business-managed CSV rules once, then reuse an immutable schema for fast JSON validation, repair, skeleton generation, and missing-field detection.

Install

npm install json-rule-engine-csv

Node.js 18.18 or newer is required.

Quick start

import { createEngine } from "json-rule-engine-csv";

const csvContent = `Key,Type,Required,Regex,ConditionExpression,AllowedValues,DefaultValue,MinItems
userId,number,true
email,email,true,,!userId
status,string,true,,,"ACTIVE,INACTIVE",ACTIVE
addresses[],array,true,,,,,1
addresses[].city,string,true`;

const engine = createEngine({ csvContent });
const result = engine.isValid({
  userId: 42,
  status: "ACTIVE",
  addresses: [{ city: "Pune" }],
});

For files:

import { createEngineFromFile } from "json-rule-engine-csv";

const engine = await createEngineFromFile({ csvFile: "./schema.csv" });

Compiler-first design

SchemaCompiler validates every schema concern at startup and emits frozen, execution-ready rules. Invalid paths, defaults, regexes, references, cycles, and array hierarchies fail before requests are accepted.

import { SchemaCompiler, Engine } from "json-rule-engine-csv";

const schema = new SchemaCompiler().compileCsv(csvContent);
const engine = new Engine(schema);

Repair

const { nextValidJson, logs } = engine.nextValidJson(input);

Repair deep-clones input, applies defaults, creates missing parents, and uses null for required values without defaults. It never deletes fields or overwrites existing non-null values. Arrays receive generated items only when MinItems explicitly requires them.

Conditions

Supported operators are !, ==, !=, >, <, >=, <=, &&, ||, and IN. Expressions are tokenized and parsed into an AST; JavaScript evaluation functions are never used.

contact.email,email,true,,!userId
state,string,true,,"country == ""IN"""
status,string,true,,"status IN [""ACTIVE"",""PENDING""]"

Custom validators and types

const engine = createEngine({
  csvContent,
  customTypeValidators: {
    money: (value) => Number.isFinite(value) && value >= 0,
  },
});

engine.registerValidator("panValidator", (value, context) => {
  return /^[A-Z]{5}[0-9]{4}[A-Z]$/.test(value) || "Invalid PAN";
});

Custom validator names are declared in the CSV Validator column.

Configuration

createEngine({
  csvContent,
  allowUnknownFields: true,
  warnUnknownFields: true,
  treatEmptyStringAsMissing: true,
  nullMode: "strict", // strict | allow | default
  coercion: "strict", // strict | permissive
});

See API.md and ARCHITECTURE.md.