DMN FEEL Parser and Interpreter

Common errors

• TypeError: require is not a function

  cause Attempting to import `feelin` using CommonJS `require()` syntax in an ES module context or without proper CommonJS fallback/transpilation.
  fix Use ES module import syntax: `import { evaluate } from 'feelin';` in your JavaScript/TypeScript files. Ensure your project is configured for ES modules (e.g., `"type": "module"` in `package.json`).

• Variable 'x' not found

  cause An expression references a variable (e.g., 'x') that is not present in the provided context object.
  fix Ensure all variables referenced within your FEEL expression are provided as properties of the context object passed to `evaluate` or `unaryTest`. For example, `evaluate('x', { x: 10 })`.

Warnings

• breaking Starting with v6.0.0, the package explicitly reports `null` conversion errors in the `warnings` array. Previously, such errors might have been silently handled or returned `null` without explicit warning details. Developers should now inspect the `warnings` property of the result object to understand why a `null` value was produced.
  Fix: Always check the `warnings` array in the returned object for detailed error information, especially when `value` is `null`. Adapt any logic that relied on implicit `null` handling to explicitly process these warnings.
• gotcha Feelin requires Node.js version 20.12.0 or higher. Using it with older Node.js versions may lead to compatibility issues, particularly with ESM imports or underlying dependencies.
  Fix: Ensure your Node.js environment meets the minimum requirement of 20.12.0. Update Node.js if necessary.
• gotcha The package is primarily designed as an ES module (ESM). Attempting to use `require()` for imports in a CommonJS environment without proper transpilation or configuration will result in an error.
  Fix: For Node.js environments, use `import { evaluate } from 'feelin';` in ES module contexts. If you must use CommonJS, consider dynamic `import()` or ensuring your build setup transpiles ESM to CJS.
• gotcha While `feelin` recognizes the full FEEL grammar and includes many built-in functions, it is not yet fully compliant with the DMN TCK (Decision Model and Notation Test Compatibility Kit). This means certain complex or edge-case FEEL expressions might behave differently compared to a fully TCK-compliant engine.
  Fix: Consult the project's DMN TCK coverage documentation (e.g., `./docs/DMN_TCK.md` in the repository) to understand current limitations and ensure critical DMN expressions function as expected in your specific use case. File issues for observed discrepancies.

Install

• npm install feelin npm
• yarn add feelin yarn
• pnpm add feelin pnpm

Imports

• evaluate
  wrong:

  const { evaluate } = require('feelin');

  correct:

  import { evaluate } from 'feelin';

  Feelin is an ESM-first package, requiring Node.js >= 20.12.0 for direct usage. Use named imports.
• unaryTest
  wrong:

  import unaryTest from 'feelin';

  correct:

  import { unaryTest } from 'feelin';

  Both `unaryTest` and `evaluate` are named exports, not default. Ensure correct destructuring.
• *

  import * as feelin from 'feelin';

  This pattern imports all named exports into a namespace object, useful for accessing multiple utilities without individual destructuring.

Quickstart

Demonstrates basic usage of `evaluate` and `unaryTest` functions, including context passing, list iteration, and inspecting `warnings` for execution issues like undefined variables.

import { evaluate, unaryTest } from 'feelin';

// Evaluate a simple expression with a context
const result1 = evaluate("Mike's daughter.name", {
  'Mike\'s daughter.name': 'Lisa'
});
console.log('Expression evaluation:', result1.value); // Lisa

// Perform a unary test
const result2 = unaryTest('1', { '?': 1 });
console.log('Unary test 1:', result2.value); // true

const result3 = unaryTest('[1..end]', { '?': 1, end: 10 });
console.log('Unary test 2:', result3.value); // true

// Iterate and transform a list
const result4 = evaluate('for a in [1, 2, 3] return a * 2');
console.log('Loop evaluation:', result4.value); // [2, 4, 6]

// Check warnings for undefined variables or null conversions
const { value, warnings } = evaluate('x');
console.log('Undefined variable result:', value); // null
console.log('Warnings for undefined variable:', warnings);
/*
Output: [
  {
    message: "Variable 'x' not found",
    type: 'NO_VARIABLE_FOUND',
    position: { from: 0, to: 1 }
  }
]
*/