Getting Started

Quick Start

Encode your first data structure with AXON in minutes

What You'll Learn

  • Basic encode/decode workflow with round-trip fidelity
  • Adding schema validation to catch errors early
  • Using AXON in a real LLM API call to save tokens
  • Converting XML data and using the CLI tool

Basic Encoding

The simplest way to use AXON is with the encode() and decode() functions:

import { encode, decode } from '@axon-format/core';

// Your data
const data = {
  users: [
    { id: 1, name: "Alice", active: true },
    { id: 2, name: "Bob", active: true },
    { id: 3, name: "Charlie", active: false }
  ]
};

// Encode to AXON
const axonString = encode(data);
console.log(axonString);
// Output: users::[3] active:bool|id:u8|name:str
//         true|1|Alice
//         true|2|Bob
//         false|3|Charlie

// Decode back to original
const decoded = decode(axonString);
// Perfect round-trip!

With Schema Validation

Add type validation to catch errors before sending data to expensive LLM APIs:

import { encode, decode, registerSchema, type Schema } from '@axon-format/core';

// Define schema as a plain object
const userSchema: Schema = {
  name: 'User',
  fields: [
    { name: 'id', type: 'u8' },
    { name: 'name', type: 'str' },
    { name: 'email', type: 'str' },
    { name: 'verified', type: 'bool' }
  ]
};

// Register the schema globally (optional)
registerSchema(userSchema);

const userData = {
  id: 1,
  name: "Alice",
  email: "alice@example.com",
  verified: true
};

// Encode with validation
const encoded = encode(userData, { schemas: [userSchema] });

// Type-safe decode
const decoded = decode(encoded, { schemas: [userSchema] });

Real-World Example: LLM API Call

Here's how to use AXON in a real LLM API call to save tokens:

import { encode } from '@axon-format/core';

// Your database query results
const results = {
  products: [
    { id: 1, name: "Widget", price: 19.99, stock: 50 },
    { id: 2, name: "Gadget", price: 29.99, stock: 30 },
    // ... more products
  ]
};

// Encode before sending to LLM
const axonData = encode(results);

// Send to your LLM (60-95% smaller!)
const response = await fetch('https://api.openai.com/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' + apiKey
  },
  body: JSON.stringify({
    model: 'gpt-4o',
    messages: [
      {
        role: 'user',
        content: "Here's the product data in AXON format: " + axonData
      }
    ]
  })
});

Pro Tip: AXON automatically selects the best encoding mode and compression algorithms. You don't need to configure anything for basic usage!

Converting from XML

AXON can also convert XML data, eliminating verbose tags while preserving structure:

import { encodeXml } from '@axon-format/core';

const xmlData = `
<employees>
  <employee id="E001" department="Engineering">
    <name>Alice Chen</name>
    <salary currency="USD">125000</salary>
    <active>true</active>
  </employee>
  <employee id="E002" department="Engineering">
    <name>Bob Smith</name>
    <salary currency="USD">120000</salary>
    <active>true</active>
  </employee>
</employees>
`;

const axonString = encodeXml(xmlData);
// Removes repetitive tags, applies columnar format
// Typically 50-70% smaller than original XML!

XML Compression: XML's verbose structure (opening/closing tags, attributes) makes it especially well-suited for AXON compression. Repeated element names become schema definitions, and uniform child elements are converted to columnar format.

CLI Usage

You can also use AXON from the command line:

# Convert JSON to AXON
axon encode data.json -o data.axon

# Convert XML to AXON
axon encode invoice.xml -o invoice.axon

# See token savings
axon stats data.json data.axon

# Convert back to JSON
axon decode data.axon -o output.json

Next Steps