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.