coon-format

COON JavaScript/TypeScript SDK

Token-efficient code compression for Dart/Flutter, optimized for LLM contexts.

Table of Contents

• Installation
• Quick Start
• Advanced Usage
• Compression Strategies
• API Reference
• Architecture
• Testing
• License

Installation

# npm
npm install @coon-format

# pnpm
pnpm add @coon-format

# yarn
yarn add @coon-format

Quick Start

import { compressDart, decompressCoon } from '@coon-format';

// Compress Dart code
const dartCode = `
class MyWidget extends StatelessWidget {
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: Text("Hello World"),
      ),
    );
  }
}
`;

const compressed = compressDart(dartCode);
console.log(compressed);
// Output: c:MyWidget<StatelessWidget>;m:b S{b:N{c:T"Hello World"}}

// Decompress back to Dart
const original = decompressCoon(compressed);

Advanced Usage

Using the Compressor Class

import { Compressor, CompressionStrategyType } from '@coon-format';

const compressor = new Compressor({
    strategy: CompressionStrategyType.AUTO,
    enableMetrics: true,
    validate: true
});

const result = compressor.compress(dartCode);

console.log(`Original tokens: ${result.originalTokens}`);
console.log(`Compressed tokens: ${result.compressedTokens}`);
console.log(`Savings: ${result.percentageSaved.toFixed(1)}%`);
console.log(`Strategy used: ${result.strategyUsed}`);

Using Specific Strategies

import { Compressor, CompressionStrategyType } from '@coon-format';

const compressor = new Compressor();

// Use aggressive strategy for maximum compression
const result = compressor.compress(dartCode, CompressionStrategyType.AGGRESSIVE);

// Use basic strategy for safer compression
const safeResult = compressor.compress(dartCode, CompressionStrategyType.BASIC);

Decompression with Formatting

import { Decompressor } from '@coon-format';

const decompressor = new Decompressor({
    formatOutput: true,
    indentSize: 2
});

const result = decompressor.decompress(compressed);
console.log(result.code);

Compression Strategies

Strategy	Compression	Speed	Description
AUTO	50-70%	Fast	Automatic optimal selection
BASIC	30-40%	Fastest	Simple abbreviations
AGGRESSIVE	60-70%	Fast	Maximum compression
AST_BASED	50-65%	Moderate	Syntax tree analysis
COMPONENT_REF	70-80%	Moderate	Pattern-based references

Strategy Selection

import { CompressionStrategyType } from '@coon-format';

// Available strategies
CompressionStrategyType.AUTO          // Default - automatic selection
CompressionStrategyType.BASIC         // Conservative compression
CompressionStrategyType.AGGRESSIVE    // Maximum compression
CompressionStrategyType.AST_BASED     // Syntax-aware compression
CompressionStrategyType.COMPONENT_REF // Pattern reference compression

API Reference

Core Functions

compressDart(code: string, strategy?: CompressionStrategyType): string

Compress Dart code to COON format.

const compressed = compressDart(dartCode);
const compressed = compressDart(dartCode, CompressionStrategyType.AGGRESSIVE);

decompressCoon(compressed: string): string

Decompress COON format back to Dart code.

const original = decompressCoon(compressed);

Classes

Compressor

Main compression class with configuration options.

interface CompressorConfig {
    strategy?: CompressionStrategyType;
    enableMetrics?: boolean;
    validate?: boolean;
}

const compressor = new Compressor(config);
const result = compressor.compress(code, strategy?);

Decompressor

Decompression class with formatting options.

interface DecompressorConfig {
    formatOutput?: boolean;
    indentSize?: number;
}

const decompressor = new Decompressor(config);
const result = decompressor.decompress(compressed);

CompressionResult

Result object containing compression output and metrics.

interface CompressionResult {
    compressed: string;       // Compressed code string
    originalTokens: number;   // Original token count
    compressedTokens: number; // Compressed token count
    percentageSaved: number;  // Compression percentage
    strategyUsed: string;     // Strategy that was used
}

Types

import {
    Compressor,
    Decompressor,
    CompressionResult,
    CompressionStrategyType,
    CompressorConfig,
    DecompressorConfig
} from '@coon-format';

Architecture

src/
├── core/           # Compressor, Decompressor, Config, Result
│   ├── compressor.ts
│   ├── decompressor.ts
│   ├── config.ts
│   └── result.ts
├── strategies/     # Compression strategy implementations
│   ├── base.ts
│   ├── basic.ts
│   ├── aggressive.ts
│   ├── ast_based.ts
│   └── component_ref.ts
├── data/           # Data loader for abbreviations
├── languages/      # Language-specific handlers
│   └── dart/
├── parser/         # Lexer, Parser, AST
└── utils/          # Validator, Formatter, Registry

Data Files

The SDK loads abbreviation data from the shared spec/data/ directory:

File	Description
widgets.json	Widget abbreviations (Scaffold → S, Column → C)
properties.json	Property abbreviations (appBar: → a:, body: → b:)
keywords.json	Keyword abbreviations (class → c:, extends → <)

Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run conformance tests
npm run test:conformance

# Watch mode for development
npm run test:watch

Building

# Build the package
npm run build

# Type checking
npm run typecheck

# Linting
npm run lint

License

MIT - See LICENSE for details.