LEAN Format

LEAN (Lightweight Efficient Adaptive Notation) is a minimal, human-readable data interchange format that combines the flexibility of JSON with the compactness of tabular data.

🌟 Why LEAN?

• Compact - Row syntax eliminates key repetition in lists
• Readable - Natural indentation and minimal syntax
• Flexible - Adapts between object and row representations
• Simple - Easy to write and parse

📦 Installation

npm install lean-format/core

🚀 Quick Start

Node.js

const { parse, format } = require('lean-format');

// Parse LEAN to JavaScript
const data = parse(`
users(id, name, age):
    - 1, Alice, 30
    - 2, Bob, 25
`);

console.log(data);
// {
//   users: [
//     { id: 1, name: 'Alice', age: 30 },
//     { id: 2, name: 'Bob', age: 25 }
//   ]
// }

// Format JavaScript as LEAN
const lean = format(data);
console.log(lean);

Browser (ES Module)

<script type="module">
import { parse, format } from 'https://unpkg.com/lean-format/dist/index.esm.js';

const data = parse('key: value');
console.log(data);
</script>

Browser (UMD)

<script src="https://unpkg.com/lean-format"></script>
<script>
  const { parse, format } = LEAN;
  const data = parse('key: value');
</script>

📖 API Reference

parse(input, options)

Parse LEAN format text into JavaScript object.

Parameters:

• input (string) - LEAN format text
• options (object) - Optional configuration
  • strict (boolean) - Enable strict mode (default: false)

Returns: Parsed JavaScript object

Example:

const data = parse(`
users(id, name):
    - 1, Alice
    - 2, Bob
`, { strict: true });

format(obj, options)

Convert JavaScript object to LEAN format.

Parameters:

• obj (object) - JavaScript object to serialize
• options (object) - Optional configuration
  • indent (string) - Indentation string (default: ' ')
  • useRowSyntax (boolean) - Enable row syntax (default: true)
  • rowThreshold (number) - Min items for row syntax (default: 3)

Returns: LEAN format string

Example:

const lean = format({ users: [...] }, {
  indent: '    ',
  useRowSyntax: true,
  rowThreshold: 5
});

validate(input, options)

Validate LEAN format text.

Parameters:

• input (string) - LEAN format text
• options (object) - Optional configuration
  • strict (boolean) - Enable strict mode

Returns: { valid: boolean, errors: Array }

Example:

const result = validate(leanText);
if (!result.valid) {
  result.errors.forEach(err => {
    console.error(`Line ${err.line}: ${err.message}`);
  });
}

🎯 LEAN Format Examples

Row Syntax (Compact Tables)

products(id, name, price, stock):
    - 1, "Wireless Mouse", 29.99, 45
    - 2, "Keyboard", 89.99, 23
    - 3, "USB Hub", 49.99, 67

Nested Objects

company:
    name: "Acme Corp"
    founded: 2020
    address:
        street: "123 Main St"
        city: Boston
        zip: 02101

Lists

tags:
    - technology
    - programming
    - data

users:
    - name: Alice
      age: 30
    - name: Bob
      age: 25

Mixed Structures

blog:
    title: "Tech Blog"
    tags:
        - tech
        - code
    posts(id, title, date):
        - 1, "First Post", "2025-01-15"
        - 2, "Second Post", "2025-02-01"
    config:
        theme: dark
        comments: true

🖥️ Command Line Interface

The package includes a CLI tool:

# Parse LEAN to JSON
lean parse data.lean

# Format JSON as LEAN
lean format data.json

# Convert between formats
lean convert input.lean output.json

# Validate LEAN syntax
lean validate data.lean --strict

# Watch and auto-convert
lean watch data.lean

# Create sample file
lean init mydata

Run lean help for full CLI documentation.

⚙️ TypeScript Support

import { parse, format, validate } from 'lean-format';

interface User {
  id: number;
  name: string;
  age: number;
}

const data = parse<{ users: User[] }>(`
users(id, name, age):
    - 1, Alice, 30
    - 2, Bob, 25
`);

🧪 Testing

npm test                # Run tests
npm run test:watch      # Watch mode
npm run test:coverage   # Coverage report

📊 Format Comparison

| Feature | JSON | YAML | CSV | LEAN | |---------|------|------|-----|------| | Human-readable | ⚠️ | ✅ | ⚠️ | ✅ | | Compact rows | ❌ | ❌ | ✅ | ✅ | | Nested objects | ✅ | ✅ | ❌ | ✅ | | No key repetition | ❌ | ❌ | ✅ | ✅ | | Comments | ❌ | ✅ | ❌ | ✅ |

🛠️ Advanced Usage

Custom Indentation

const lean = format(data, { indent: '\t' }); // Tabs
const lean = format(data, { indent: '    ' }); // 4 spaces

Disable Row Syntax

const lean = format(data, { useRowSyntax: false });

Strict Validation

const data = parse(input, { strict: true });
// Throws error on:
// - Extra row values
// - Duplicate keys
// - Mixed indentation

🔗 Ecosystem

• CLI Tool - Command-line converter (included)
• VS Code Extension - Syntax highlighting
• Online Playground - Interactive converter
• Python Parser - Coming soon
• Go Parser - Coming soon

📚 Resources

• Full Specification
• Online Playground
• VS Code Extension
• GitHub Repository

🤝 Contributing

Contributions welcome! Please see CONTRIBUTING.md

📄 License

MIT License - see LICENSE file

🙏 Acknowledgments

Inspired by JSON, YAML, CSV, and the need for a format that combines their best features.

Made with ❤️ by the LEAN Format Team