@arkadia/data 0.1.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arkadia Solutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,191 @@
+# @arkadia/data
+
+```
+                                   ; i  :J                                      
+                               U, .j..fraaM.  nl                                
+                            b h.obWMkkWWMMWMCdkvz,k                             
+                         ! .mQWM:o hiMoMW v.uaXMdohbi                           
+                        hI,MMmaIao.Wo .IMkoh FCMwqoXa                           
+                      ,.c.aWdM. d,aToW  .    Mb!. MopfQ.L                       
+                       jhj.xoM :k    aCu F: w MpmqMvMMI,I                       
+                      bzMhz:W    .Mw . o lYh ai M iMa pM.j                      
+                     hzqWWM;    M;o.WMWWMkMX f.a aa bModpo.                     
+                     ;tMbbv   xp oJMMWWWWMMMM iv  dLMXakM:T                     
+                       mdh        MMWWWWWWWbQLCzurjktvMor                       
+                      ,QFw ;M,b .MWWWWWWWMWMWd  xz   M,kd X                     
+                      qjMIo IMTW.WWWWWMWWWM.o.I   rpULaMdi.                     
+                       .mMM  uoWWWMWWWWWWp qM,,M l M;mMbrI                      
+                        f nm  MMW MWWjMuMj  I  o   LbMac                        
+                              WWdMWWWW Mv a.b..aauMhMwQf                        
+                              MoWWW,WWtjonJMWtoMdoaoMI                          
+                              MMMM Mi    xd:Mm tMwo Cr,                         
+                             xMMc .otqokWMMMao:oio.                             
+                             MW    .   C..MkTIo                                 
+                            WW                                                  
+                           QWM                                                  
+                           WW                                                   
+                          uMW                                                   
+                          WW                                                    
+                          MW
+```
+
+
+[![npm version](https://img.shields.io/npm/v/@arkadia/data.svg)](https://www.npmjs.com/package/@arkadia/data)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Official Parser and Stringifier for the Arkadia Data Format (AKD).**
+
+AKD is a schema-first, high-density data protocol designed specifically for **LLM context optimization**. It significantly reduces token usage compared to JSON by eliminating redundant syntax characters and enforcing strict typing via schemas.
+
+## ✨ Features
+
+- **Token Efficient:** Reduces context window usage by 15-30% compared to standard JSON.
+- **Type Safe:** Enforces types (int, float, bool, string) explicitly in the schema.
+- **Dual Mode:** Supports both **Named Records** (Map-like) and **Positional Records** (Tuple-like).
+- **Zero-Dependency:** Lightweight and fast, built for high-performance pipelines.
+
+## 📦 Installation
+
+```bash
+npm install @arkadia/data
+
+```
+
+## 🚀 Usage
+
+### Importing
+
+```typescript
+import { encode, decode } from '@arkadia/data';
+
+```
+
+### Encoding (JavaScript Object → AKD String)
+
+Converts standard JavaScript objects into the token-optimized AKD string format.
+
+```typescript
+const data = {
+  id: 1,
+  name: "Alice",
+  active: true
+};
+
+// Compact encoding (default)
+const akdString = encode(data);
+
+console.log(akdString);
+// Output: <id:number,name:string,active:bool>(1,"Alice",true)
+
+```
+
+### Decoding (AKD String → AST / Value)
+
+Parses an AKD string back into a usable node structure.
+
+```typescript
+const input = '<score:number>(98.5)';
+
+const result = decode(input);
+
+if (result.errors.length === 0) {
+  console.log(result.node.value); 
+  // Output: 98.5
+  
+  console.log(result.node.isRecord); 
+  // Output: true
+} else {
+  console.error("Parsing errors:", result.errors);
+}
+
+```
+
+## 📖 Syntax Guide
+
+The AKD format uses a distinct syntax to separate schema definition from data values.
+
+### Primitives
+
+Primitive values are explicitly typed using angle brackets `<type>`.
+
+| Type | Input Example | Encoded Output |
+| --- | --- | --- |
+| Integer | `123` | `<number>123` |
+| Float | `12.34` | `<number>12.34` |
+| String | `"hello"` | `<string>"hello"` |
+| Boolean | `true` | `<bool>true` |
+| Null | `null` | `<null>null` |
+
+### Named Records
+
+Similar to JSON objects, but the keys are lifted into a schema definition.
+
+**Input:**
+
+```json
+{ "id": 1, "name": "Test" }
+
+```
+
+**Encoded (AKD):**
+
+```text
+<id:number,name:string>(1,"Test")
+
+```
+
+### Positional Records (Tuples)
+
+Data without keys, where position determines meaning.
+
+**Input:**
+
+```javascript
+// (10, "Alice") - conceptually
+
+```
+
+**Encoded (AKD):**
+
+```text
+<_0:number,_1:string>(10,"Alice")
+
+```
+
+## 🛠️ API Reference
+
+### `encode(input: any, options?: EncodeOptions): string`
+
+Serializes a JavaScript value into an AKD string.
+
+* `input`: The data to encode.
+* `options`:
+* `compact`: (boolean) Remove whitespace. Default: `true`.
+* `colorize`: (boolean) Add ANSI colors for terminal output. Default: `false`.
+
+
+
+### `decode(text: string, options?: DecodeOptions): ParseResult`
+
+Parses an AKD string.
+
+* `text`: The AKD string to parse.
+* `options`:
+* `debug`: (boolean) Enable detailed logging.
+
+
+* **Returns** `ParseResult`:
+* `node`: The parsed AST node containing value and metadata.
+* `errors`: Array of parsing errors, if any.
+
+
+
+## 📄 License
+
+This project is licensed under the [MIT License].
+
+---
+
+<div align="center">
+<sub>Built by <strong>Arkadia AI</strong>. Engineering the kernel of distributed intelligence.</sub>
+</div>

package/dist/config.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Configuration options for the AK Data Format Encoder.
+ */
+export interface EncoderConfig {
+    /**
+     * Embed schema directly inside sample data (useful for LLM prompting).
+     * Example: [ (name: string /name of user/, age: int) ]
+     * Default: false
+     */
+    promptOutput: boolean;
+    /**
+     * Number of spaces used for indentation.
+     * Default: 2
+     */
+    indent: number;
+    /**
+     * Initial indentation offset (level).
+     * Default: 0
+     */
+    startIndent: number;
+    /**
+     * Enable compact formatting. Removes unnecessary spaces and newlines.
+     * Default: false
+     */
+    compact: boolean;
+    /**
+     * Escape newline characters in strings as literal \n and \r.
+     * Default: false
+     */
+    escapeNewLines: boolean;
+    /**
+     * purely removes new lines from strings.
+     * Default: false
+     */
+    removeNewLines: boolean;
+    /**
+     * Enable ANSI colorized output for terminal debugging.
+     * Default: false
+     */
+    colorize: boolean;
+    /**
+     * Include comments in the output ).
+     * Default: true
+     */
+    includeComments: boolean;
+    /**
+     * Include array size information (e.g. [ $size=5 : ... ]).
+     * Default: false
+     */
+    includeArraySize: boolean;
+    /**
+     * Include the schema definition header (e.g. <name: string>).
+     * Default: true
+     */
+    includeSchema: boolean;
+    /**
+     * Include metadata attributes and tags ($attr=1 #tag).
+     * Default: true
+     */
+    includeMeta: boolean;
+    /**
+     * Include type signature after field names (e.g. name: string vs name).
+     * Default: true
+     */
+    includeType: boolean;
+}
+/**
+ * Default configuration values.
+ */
+export declare const DEFAULT_CONFIG: EncoderConfig;
+/**
+ * Helper to merge partial user config with defaults.
+ */
+export declare function resolveConfig(config?: Partial<EncoderConfig>): EncoderConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,aAAa;IAC1B;;;;OAIG;IACH,YAAY,EAAE,OAAO,CAAC;IAEtB;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,cAAc,EAAE,OAAO,CAAC;IAExB;;;OAGG;IACH,cAAc,EAAE,OAAO,CAAC;IAExB;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;IAElB;;;OAGG;IACH,eAAe,EAAE,OAAO,CAAC;IAEzB;;;OAGG;IACH,gBAAgB,EAAE,OAAO,CAAC;IAE1B;;;OAGG;IACH,aAAa,EAAE,OAAO,CAAC;IAEvB;;;OAGG;IACH,WAAW,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,WAAW,EAAE,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,aAa5B,CAAC;AAEF;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,aAAa,CAE5E"}

package/dist/config.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CONFIG = void 0;
+exports.resolveConfig = resolveConfig;
+/**
+ * Default configuration values.
+ */
+exports.DEFAULT_CONFIG = {
+    indent: 2,
+    startIndent: 0,
+    compact: false,
+    escapeNewLines: false,
+    removeNewLines: false,
+    colorize: false,
+    includeComments: true,
+    includeArraySize: false,
+    includeSchema: true,
+    includeMeta: true,
+    includeType: true,
+    promptOutput: false,
+};
+/**
+ * Helper to merge partial user config with defaults.
+ */
+function resolveConfig(config) {
+    return { ...exports.DEFAULT_CONFIG, ...config };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":";;;AAmGA,sCAEC;AAvBD;;GAEG;AACU,QAAA,cAAc,GAAkB;IACzC,MAAM,EAAE,CAAC;IACT,WAAW,EAAE,CAAC;IACd,OAAO,EAAE,KAAK;IACd,cAAc,EAAE,KAAK;IACrB,cAAc,EAAE,KAAK;IACrB,QAAQ,EAAE,KAAK;IACf,eAAe,EAAE,IAAI;IACrB,gBAAgB,EAAE,KAAK;IACvB,aAAa,EAAE,IAAI;IACnB,WAAW,EAAE,IAAI;IACjB,WAAW,EAAE,IAAI;IACjB,YAAY,EAAE,KAAK;CACtB,CAAC;AAEF;;GAEG;AACH,SAAgB,aAAa,CAAC,MAA+B;IACzD,OAAO,EAAE,GAAG,sBAAc,EAAE,GAAG,MAAM,EAAE,CAAC;AAC5C,CAAC"}

package/dist/core/Decoder.d.ts

@@ -0,0 +1,86 @@
+import { Node } from '../models/Node';
+import { Schema } from '../models/Schema';
+export declare class DecodeError {
+    message: string;
+    position: number;
+    context: string;
+    schema: Schema | null;
+    node: Node | null;
+    constructor(message: string, position: number, schema?: Schema | null, node?: Node | null);
+    toString(): string;
+}
+export declare class DecodeWarning {
+    message: string;
+    position: number;
+    schema: Schema | null;
+    node: Node | null;
+    constructor(message: string, position: number, schema?: Schema | null, node?: Node | null);
+    toString(): string;
+}
+export interface DecodeResult {
+    node: Node;
+    schema: Schema | null;
+    errors: DecodeError[];
+    warnings: DecodeWarning[];
+}
+export declare class Decoder {
+    private static PRIMITIVES;
+    private static PRIMITIVES_MAPPING;
+    private static MAX_ERRORS;
+    private text;
+    private debug;
+    private i;
+    private line;
+    private col;
+    private pendingMeta;
+    private nodeStack;
+    private schemaStack;
+    private errors;
+    private warnings;
+    private namedSchemas;
+    constructor(text: string, schema?: string, removeAnsiColors?: boolean, debug?: boolean);
+    decode(): DecodeResult;
+    private parseSchemaAtRef;
+    private parseSchemaBody;
+    private parseSchemaBodyContent;
+    private parseSchemaType;
+    private parseNode;
+    private parseNodeWithSchemaRef;
+    private parseNodeWithInlineSchema;
+    private parseList;
+    private parsePositionalRecord;
+    private parseNamedRecord;
+    private parseMeta;
+    private parseCommentBlock;
+    private parseModifierInline;
+    private parseMetaBlock;
+    private parseMetaAttribute;
+    private parseMetaTag;
+    private parseMetaFlag;
+    private parseIdent;
+    private parseString;
+    private parseNumber;
+    private parseRawString;
+    private parsePrimitiveValue;
+    private readQuotedString;
+    private readNumber;
+    private get currentSchema();
+    private createSchema;
+    private pushSchema;
+    private popSchema;
+    private get currentNode();
+    private pushNode;
+    private popNode;
+    private createNode;
+    private applyMeta;
+    private advance;
+    private skipWhitespace;
+    private eof;
+    private peek;
+    private peekNext;
+    private expect;
+    private addError;
+    private addWarning;
+    private _dbg;
+}
+//# sourceMappingURL=Decoder.d.ts.map

package/dist/core/Decoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Decoder.d.ts","sourceRoot":"","sources":["../../src/core/Decoder.ts"],"names":[],"mappings":"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"}