ts

TypeScript Coding Rules for LLML Project

Overall Philosophy

The TypeScript implementation is a minimalist, functional, and robust library with zero production dependencies besides dedent. It prioritizes predictable output and developer experience through a simple API and strict typing, while gracefully handling varied and unpredictable input data.

Project Structure & Conventions

Tooling

• Runtime and Package Management: Use bun for all operations (installing dependencies, running scripts, building). The project is configured with bun.lockb.
• Testing: vitest is the testing framework. Use bun test to run the test suite.
• Type Checking: typescript is used for static analysis. Run bun run tsc --noEmit to check for type errors without generating JavaScript files.

Module System

• The project uses ES Modules (ESM) exclusively, as defined by "type": "module" in package.json.
• Use import/export syntax. Do not use require/module.exports.

File Organization

• Source Code: All core logic resides in the src/ directory. The main entry point is src/index.ts.
• Utilities: Pure, reusable helper functions (like kebabCase) should be placed in src/utils.ts.
• Tests: All test files are located in the tests/ directory. Maintain the one-to-one mapping of feature-to-test-file (e.g., nested.ts logic is tested in tests/nested.test.ts).

Coding Style & Patterns

• Functional Approach: The core logic is implemented as a set of pure functions. The main llml function is recursive and delegates formatting tasks to helpers. Avoid classes and stateful logic.
• Immutability: Do not mutate input data. Functions should return new, transformed values.
• Dependencies: Maintain the zero-dependency principle for production code. The only exception is dedent, which is used for cleaning up multiline strings. Do not add new production dependencies without strong justification.
• Readability: Use const by default and let only when a variable must be reassigned. Code is formatted with a 2-space indent.
• Comments: Add JSDoc-style comments to exported functions and complex utility functions to explain their purpose, parameters, and return values, as seen in src/utils.ts.