Light ECMAScript Value Notation (LEVN)

Common errors

• TypeError: require is not a function

  cause Attempting to use `require` in an ECMAScript Module (ESM) context without proper configuration.
  fix Ensure your project is configured for CommonJS, or use dynamic `import()` if absolutely necessary within an ESM file. `levn` is designed for CommonJS (`require`).

• Error: Cannot find module 'type-check'

  cause `type-check`, a core dependency, is missing from `node_modules`.
  fix Install the peer dependency: `npm install type-check`.

• SyntaxError: Unexpected token '...' (or similar parsing errors)

  cause Input string does not conform to Levn's syntax rules or the specified type, or contains unrecognized literals.
  fix Review the Levn format documentation and ensure the input string correctly matches the `type` string provided to the `parse` function. Pay attention to delimiters and value formats (e.g., dates with `#`, regex with `/`).

• TypeError: Cannot read properties of undefined (reading 'parse')

  cause The `levn` module was not successfully imported, or `require('levn')` returned `undefined` or an unexpected value.
  fix Verify that `levn` is installed (`npm list levn`) and that the `require` path is correct. Ensure no other module is inadvertently shadowing `levn`.

Warnings

• breaking Levn is an abandoned package. Its last major update was in 2013-2014, and the last npm publish was six years ago. It relies on very old Node.js versions (>=0.8.0). Use in modern environments without careful consideration and potential polyfills is not recommended and may lead to compatibility issues or security vulnerabilities through its dependencies.
  Fix: Consider modern alternatives like `yaml`, `toml`, or robust JSON parsers. If `levn` is critical, fork the project, update dependencies, and address any Node.js compatibility issues.
• gotcha Levn is a CommonJS-only module. Attempting to use `import` statements (ESM syntax) will result in runtime errors in Node.js environments unless transpiled or configured correctly with a CommonJS wrapper.
  Fix: Always use `require()` for importing `levn` and its functions: `const { parse } = require('levn');`.
• gotcha The library explicitly states it is slower and less efficient than JSON for transporting large amounts of data. Its purpose is for human-entered, concise data, not machine-to-machine communication.
  Fix: Do not use `levn` for performance-critical data serialization/deserialization involving large payloads. Stick to its intended use case for small, human-editable configuration or command-line inputs.
• gotcha Levn's parsing heavily relies on the `type-check` library for its type format and validation. Developers need to understand `type-check`'s syntax and capabilities to effectively use `levn` for complex data structures.
  Fix: Familiarize yourself with the `type-check` library's documentation, especially its type format, before attempting advanced parsing with `levn`.

Install

• npm install levn npm
• yarn add levn yarn
• pnpm add levn pnpm

Imports

• parse
  wrong:

  import { parse } from 'levn';

  correct:

  const { parse } = require('levn');

  Levn is a CommonJS module, primarily designed for Node.js environments with `require`. Direct ESM `import` is not supported.
• parsedTypeParse
  wrong:

  import parsedTypeParse from 'levn/parsedTypeParse';

  correct:

  const { parsedTypeParse } = require('levn');

  `parsedTypeParse` requires a pre-parsed type object, typically obtained from the `type-check` library. It's a named export from the main `levn` module.
• VERSION
  wrong:

  const VERSION = require('levn').VERSION;

  correct:

  const { VERSION } = require('levn');

  The `VERSION` string is a direct named export, not a property off the default export.

Quickstart

Demonstrates basic `parse` usage for various types (Number, String, Boolean, Array, Object) and the `parsedTypeParse` function with a pre-parsed type from `type-check`.

const { parse } = require('levn');
const { parseType } = require('type-check'); // Assuming 'type-check' is installed

// Basic type parsing
console.log('Number 2:', parse('Number', '2'));
console.log('String "levn":', parse('String', 'levn'));
console.log('Boolean true:', parse('Boolean', 'true'));

// Complex types and implicit delimiters
console.log('Array of Numbers:', parse('[Number]', '1,2,3'));
console.log('Object with properties:', parse('{a: String, b: Number}', 'a: str, b: 2'));

// Parsing with pre-parsed types (from type-check)
const parsedNumberArrayType = parseType('[Number]');
console.log('Parsed Type Array:', parse('parsedTypeParse', parsedNumberArrayType, '4,5,6'));