Package Exports

@openai-hce/decode

Readme

@openai-hce/decode# @hce/decode

HCE (Hierarchical Columnar Encoding) decoder for converting HCE format back to JSON. Works seamlessly with @openai-hce/encode.HCE (Hierarchical Columnar Encoding) decoder for converting HCE back to JSON.

Installation## Installation

bashbash

npm install @openai-hce/decodenpm install @hce/decode

or# or

pnpm add @openai-hce/decodepnpm add @hce/decode

or```

yarn add @openai-hce/decode




## Quick Start```typescript

import { HCEDecoder } from '@hce/decode';

```typescript

import { HCEDecoder } from '@openai-hce/decode';const hceContent = `users(user)[2]:

  user(id,name,role)[2]:

const hceContent = `users(user)[2]:    1,Alice,admin|2,Bob,user`;

  user(id,name,role)[2]:

    1,Alice,admin|2,Bob,user`;const decoder = new HCEDecoder({

  fieldDelimiter: ',',

const decoder = new HCEDecoder();  recordDelimiter: '|',

const data = decoder.decode(hceContent);  typeField: 'type'

console.log(JSON.stringify(data, null, 2));});

const data = decoder.decode(hceContent);

**Output:**console.log(JSON.stringify(data, null, 2));

json

{

"users": [## Options

{ "type": "user", "id": 1, "name": "Alice", "role": "admin" },

{ "type": "user", "id": 2, "name": "Bob", "role": "user" }- `fieldDelimiter` - Delimiter between fields (default: ',')

]- recordDelimiter - Delimiter between records (default: '|')

}- nestedDelimiter - Delimiter for nested arrays (default: ';')

```- missingValue - Placeholder for missing/null values (default: ' ')

typeField - Name of the type field (default: 'type')

Examples- `indent` - Expected indentation size in spaces (default: 2)

Example 1: Simple Type Grouping## Features

HCE Input:- Fast and accurate HCE to JSON conversion


data(user,org)[3]:- Handles missing/null values

  user(id,name,email)[2]:- Type-safe TypeScript implementation

    1,Alice,alice@example.com|2,Bob,bob@example.com- Automatic type detection

  org(id,name,industry)[1]:

    100,'Acme Corp',Tech## License

MIT

JSON Output:

{
  "data": [
    { "type": "user", "id": 1, "name": "Alice", "email": "alice@example.com" },
    { "type": "user", "id": 2, "name": "Bob", "email": "bob@example.com" },
    { "type": "org", "id": 100, "name": "Acme Corp", "industry": "Tech" }
  ]
}

Example 2: Secondary Grouping

HCE Input:

users(user by role)[4]:
  admin(id,name,active)[2]:
    1,Alice,true|2,Bob,true
  guest(id,name,active)[2]:
    3,Carol,false|4,Dave,true

JSON Output:

{
  "users": [
    { "type": "user", "id": 1, "name": "Alice", "role": "admin", "active": true },
    { "type": "user", "id": 2, "name": "Bob", "role": "admin", "active": true },
    { "type": "user", "id": 3, "name": "Carol", "role": "guest", "active": false },
    { "type": "user", "id": 4, "name": "Dave", "role": "guest", "active": true }
  ]
}

Note: The "by role" notation indicates secondary grouping, and the decoder automatically reconstructs the role field.

Example 3: Nested Objects

HCE Input:

data(user)[2]:
  user(id,name,.profile)[2]:
    1,Alice|2,Bob
    .profile(bio,location,avatar)[2]:
      'Software engineer',SF,avatar1.jpg|'Product manager',NY,avatar2.jpg

JSON Output:

{
  "data": [
    {
      "type": "user",
      "id": 1,
      "name": "Alice",
      "profile": {
        "bio": "Software engineer",
        "location": "SF",
        "avatar": "avatar1.jpg"
      }
    },
    {
      "type": "user",
      "id": 2,
      "name": "Bob",
      "profile": {
        "bio": "Product manager",
        "location": "NY",
        "avatar": "avatar2.jpg"
      }
    }
  ]
}

Example 4: Arrays of Objects

HCE Input:

posts(post)[2]:
  post(id,title,.tags)[2]:
    1,'Hello World'|2,'HCE Guide'
    .tags(name,color)[4]:
      javascript,yellow;tutorial,blue|hce,green;encoding,purple

JSON Output:

{
  "posts": [
    {
      "type": "post",
      "id": 1,
      "title": "Hello World",
      "tags": [
        { "name": "javascript", "color": "yellow" },
        { "name": "tutorial", "color": "blue" }
      ]
    },
    {
      "type": "post",
      "id": 2,
      "title": "HCE Guide",
      "tags": [
        { "name": "hce", "color": "green" },
        { "name": "encoding", "color": "purple" }
      ]
    }
  ]
}

Example 5: Optional Fields

HCE Input:

products(product)[3]:
  product(id,name,price,discount)[3]:
    1,Laptop,999,10|2,Mouse,25, |3,Keyboard,75,5

JSON Output:

{
  "products": [
    { "type": "product", "id": 1, "name": "Laptop", "price": 999, "discount": 10 },
    { "type": "product", "id": 2, "name": "Mouse", "price": 25 },
    { "type": "product", "id": 3, "name": "Keyboard", "price": 75, "discount": 5 }
  ]
}

Note: Missing values (represented by space in HCE) are omitted or set to undefined in JSON.

Example 6: Primitive Arrays

HCE Input:

students(student)[2]:
  student(id,name,.grades)[2]:
    1,Alice|2,Bob
    .grades: 85;90;88|92;87;95

JSON Output:

{
  "students": [
    { "type": "student", "id": 1, "name": "Alice", "grades": [85, 90, 88] },
    { "type": "student", "id": 2, "name": "Bob", "grades": [92, 87, 95] }
  ]
}

Example 7: Deep Nesting

HCE Input:

data(user)[1]:
  user(id,name,.settings)[1]:
    1,Alice
    .settings(theme,notifications,.preferences)[1]:
      dark,true
      .preferences(language,timezone)[1]:
        en-US,PST

JSON Output:

{
  "data": [
    {
      "type": "user",
      "id": 1,
      "name": "Alice",
      "settings": {
        "theme": "dark",
        "notifications": true,
        "preferences": {
          "language": "en-US",
          "timezone": "PST"
        }
      }
    }
  ]
}

API Reference

`new HCEDecoder(options?)`

Creates a new decoder instance.

Options:

interface HCEOptions {
  // Delimiters
  fieldDelimiter?: string;      // Default: ','
  recordDelimiter?: string;     // Default: '|'
  nestedDelimiter?: string;     // Default: ';'
  missingValue?: string;        // Default: ' '
  
  // Decoding options
  typeField?: string;           // Default: 'type'
  indent?: number;              // Default: 2
}

`decoder.decode(hceContent)`

Decodes HCE format to JSON.

Parameters:

hceContent: string - HCE formatted string

Returns: { [key: string]: any[] } - Object with root key and decoded array

Example:

const decoder = new HCEDecoder();
const result = decoder.decode(hceContent);

// Result structure:
// { "users": [...] }
// { "products": [...] }
// etc.

Advanced Usage

Custom Delimiters

If your HCE was encoded with custom delimiters, use the same options:

const decoder = new HCEDecoder({
  fieldDelimiter: '\t',
  recordDelimiter: '\n',
  nestedDelimiter: ','
});

Custom Type Field

const decoder = new HCEDecoder({
  typeField: 'kind' // Instead of default 'type'
});

Extract Just the Array

const result = decoder.decode(hceContent);
const array = Object.values(result)[0]; // Get just the array

Round-Trip Compatibility

The decoder is fully compatible with the encoder:

import { HCEEncoder } from '@openai-hce/encode';
import { HCEDecoder } from '@openai-hce/decode';

const original = [
  { type: 'user', id: 1, name: 'Alice' }
];

// Encode
const encoder = new HCEEncoder();
const hce = encoder.encode(original, 'users');

// Decode
const decoder = new HCEDecoder();
const decoded = decoder.decode(hce);

// decoded.users === original (deep equality)

Error Handling

The decoder throws descriptive errors for invalid HCE:

try {
  const result = decoder.decode(invalidHCE);
} catch (error) {
  console.error('Decoding failed:', error.message);
  // Examples:
  // - "Invalid HCE format: missing root header"
  // - "Invalid type group header at line 5"
  // - "Mismatched field count in row"
}

Type Inference

The decoder automatically infers types:

HCE Value	JSON Type
`123`	`number`
`45.67`	`number`
`true` / `false`	`boolean`
`null`	`null`
`'quoted text'`	`string`
`unquoted`	`string`
(space)	`undefined` (omitted)
`1;2;3`	`[1, 2, 3]` (array)

Performance

HCE Size	Decode Time	Output Size
10 KB	~3ms	22 KB JSON
100 KB	~25ms	220 KB JSON
1 MB	~200ms	2.2 MB JSON

System: MacBook Pro M1, Node.js v20

@openai-hce/encode - HCE encoder
@openai-hce/cli - Command-line tools

JSPM