@arkadia/ai-data-format 1.0.0

package/src/models/Meta.ts

@@ -0,0 +1,135 @@
+
+export interface MetaProps {
+    comments?: string[];
+    attr?: Record<string, any>;
+    tags?: string[];
+}
+
+/**
+ * Mixin/Base class that adds metadata storage capabilities to Node and Schema.
+ */
+export class Meta {
+    comments: string[];
+    attr: Record<string, any>;
+    tags: string[];
+
+    constructor({ comments, attr, tags }: MetaProps = {}) {
+        this.comments = comments ? [...comments] : [];
+        this.attr = attr ? { ...attr } : {};
+        this.tags = tags ? [...tags] : [];
+    }
+
+    /**
+     * Clears ALL metadata (comments, attributes, tags).
+     */
+    clearCommonMeta(): void {
+        this.comments = [];
+        this.attr = {};
+        this.tags = [];
+    }
+
+    /**
+     * Merges only the common fields (attributes, comments, tags)
+     * from a MetaInfo object. Safe for both Node and Schema.
+     */
+    applyCommonMeta(info: Meta): void {
+        // Append comments
+        if (info.comments.length > 0) {
+            this.comments.push(...info.comments);
+        }
+
+        // Merge attributes ($key=value)
+        if (Object.keys(info.attr).length > 0) {
+            Object.assign(this.attr, info.attr);
+        }
+
+        // Append tags
+        if (info.tags.length > 0) {
+            this.tags.push(...info.tags);
+        }
+    }
+}
+
+/**
+ * A temporary container (DTO) holding parsed metadata from a / ... / block.
+ * It contains BOTH Schema constraints (!required) and Node attributes ($key=val).
+ */
+export class MetaInfo extends Meta {
+    required: boolean;
+
+    constructor(props: MetaProps & { required?: boolean } = {}) {
+        super(props);
+        this.required = props.required || false;
+    }
+
+    /**
+     * Merges everything from another MetaInfo object, including 'required' flag.
+     */
+    applyMeta(info: MetaInfo): void {
+        // Apply common fields (comments, attr, tags)
+        this.applyCommonMeta(info);
+
+        // Override required meta (Schema Only)
+        if (info.required) {
+            this.required = true;
+        }
+    }
+
+    /**
+     * Allows usage checks like 'if meta.isEmpty()' to see if any metadata was collected.
+     * Equivalent to Python's __bool__.
+     */
+    isEmpty(): boolean {
+        return (
+            this.comments.length === 0 &&
+            Object.keys(this.attr).length === 0 &&
+            this.tags.length === 0 &&
+            !this.required
+        );
+    }
+
+    /**
+     * Debug representation mimicking the actual ADF format style.
+     * Example: <MetaInfo !required #tag $key=val >
+     */
+    toString(): string {
+        const parts: string[] = [];
+
+        // 1. Flags
+        if (this.required) {
+            parts.push("!required");
+        }
+
+        // 2. Tags
+        for (const t of this.tags) {
+            parts.push(`#${t}`);
+        }
+
+        // 3. Attributes
+        for (const [k, v] of Object.entries(this.attr)) {
+            // Simplistic value repr for debug
+            let valStr: string;
+            if (typeof v === 'string') {
+                valStr = `"${v}"`;
+            } else {
+                valStr = String(v);
+            }
+            parts.push(`$${k}=${valStr}`);
+        }
+
+        // 4. Comments (Summary)
+        if (this.comments.length > 0) {
+            if (this.comments.length === 1) {
+                const c = this.comments[0];
+                const preview = c.length > 15 ? c.substring(0, 15) + '..' : c;
+                parts.push(`/* ${preview} */`);
+            } else {
+                parts.push(`/* ${this.comments.length} comments */`);
+            }
+        }
+
+        const content = parts.join(" ");
+        return content ? `<MetaInfo ${content}>` : "<MetaInfo (empty)>";
+    }
+
+}

package/src/models/Node.ts

@@ -0,0 +1,212 @@
+import { Meta, MetaInfo, MetaProps } from './Meta';
+import { Schema } from './Schema';
+
+export interface NodeProps extends MetaProps {
+    name?: string;
+    value?: any;
+    fields?: Record<string, Node>;
+    elements?: Node[];
+}
+
+/**
+ * Canonical runtime data object for AI.DATA.
+ * A Node always refers to a Schema which defines how data should be interpreted.
+ */
+export class Node extends Meta {
+    schema: Schema;
+    name: string;
+    value: any;
+    fields: Record<string, Node>;
+    elements: Node[];
+
+    constructor(schema: Schema, props: NodeProps = {}) {
+        super(props);
+        this.schema = schema;
+        this.name = props.name || "";
+        this.value = props.value ?? null;
+        this.fields = props.fields || {};
+        this.elements = props.elements ? [...props.elements] : [];
+    }
+
+    // -----------------------------------------------------------
+    // Introspection helpers
+    // -----------------------------------------------------------
+
+    get isPrimitive(): boolean { return this.schema && this.schema.isPrimitive; }
+    get isRecord(): boolean { return this.schema && this.schema.isRecord; }
+    get isList(): boolean { return this.schema && this.schema.isList; }
+
+    // -----------------------------------------------------------
+    // Meta
+    // -----------------------------------------------------------
+
+    clearMeta(): void {
+        this.clearCommonMeta();
+    }
+
+    applyMeta(info: MetaInfo): void {
+        // Applies ALL metadata (common stuff: meta dict, comments)
+        this.applyCommonMeta(info);
+    }
+
+
+
+    // -----------------------------------------------------------
+    // Conversion Methods (dict / json)
+    // -----------------------------------------------------------
+
+    /**
+     * Recursively converts the Node into a standard JavaScript object/array/primitive.
+     * Equivalent to Python's .dict() method.
+     */
+    dict(): any {
+        if (this.isPrimitive) {
+            return this.value;
+        }
+
+        if (this.isList) {
+            return this.elements.map(element => element.dict());
+        }
+
+        if (this.isRecord) {
+            const result: Record<string, any> = {};
+            for (const [key, fieldNode] of Object.entries(this.fields)) {
+                result[key] = fieldNode.dict();
+            }
+            return result;
+        }
+
+        return this.value;
+    }
+
+    /**
+     * Converts the Node to a JSON string.
+     * * @param indent Number of spaces for indentation.
+     * @param colorize If true, applies ANSI colors to keys, strings, numbers, etc.
+     */
+    JSON(indent: number = 2, colorize: boolean = false): string {
+        // 1. Convert to standard JS object
+        const data = this.dict();
+
+        // 2. Dump to string
+        const jsonStr = JSON.stringify(data, null, indent);
+
+        if (!colorize) {
+            return jsonStr;
+        }
+
+        // 3. Apply Colors (Regex Tokenizer)
+        // ANSI codes matching the Encoder class
+        const C = {
+            RESET: "\x1b[0m",
+            STRING: "\x1b[92m", // Green
+            NUMBER: "\x1b[94m", // Blue
+            BOOL: "\x1b[95m",   // Magenta
+            NULL: "\x1b[90m",   // Gray
+            KEY: "\x1b[93m"     // Yellow
+        };
+
+        // Regex to capture JSON tokens:
+        // Group 1: Keys ("key": )
+        // Group 2: String values ("value")
+        // Group 3: Booleans/Null
+        // Group 4: Numbers
+        const tokenPattern = /(".*?"\s*:)|(".*?")|\b(true|false|null)\b|(-?\d+(?:\.\d*)?(?:[eE][+\-]?\d+)?)/g;
+
+        return jsonStr.replace(tokenPattern, (match) => {
+            // Check based on content patterns
+            
+            // Key: Ends with ':' (ignoring whitespace) and starts with '"'
+            if (/^".*":\s*$/.test(match)) {
+                return `${C.KEY}${match}${C.RESET}`;
+            }
+
+            // String value: Starts with '"'
+            if (match.startsWith('"')) {
+                return `${C.STRING}${match}${C.RESET}`;
+            }
+
+            // Boolean
+            if (match === "true" || match === "false") {
+                return `${C.BOOL}${match}${C.RESET}`;
+            }
+
+            // Null
+            if (match === "null") {
+                return `${C.NULL}${match}${C.RESET}`;
+            }
+
+            // Number (Fallthrough)
+            return `${C.NUMBER}${match}${C.RESET}`;
+        });
+    }
+    
+    // -----------------------------------------------------------
+    // Debug / Representation
+    // -----------------------------------------------------------
+
+    /**
+     * Technical debug representation.
+     * Format: <Node(KIND:type) value/len=... details...>
+     */
+    toString(): string {
+        // 1. Type Info
+        let typeLabel = "UNKNOWN";
+        if (this.schema) {
+            const kind = this.schema.kind;
+            const typeName = this.schema.typeName;
+
+            if (this.isList) {
+                const elType = this.schema.element ? (this.schema.element.typeName || "any") : "any";
+                typeLabel = `LIST[${elType}]`;
+            } else if (this.isRecord && typeName !== "record" && typeName !== "any") {
+                typeLabel = `RECORD:${typeName}`;
+            } else {
+                typeLabel = `${kind}:${typeName}`;
+            }
+        }
+
+        const header = `<Node(${typeLabel})`;
+        const content: string[] = [];
+
+        // 2. Content Info
+        if (this.isPrimitive) {
+            let v = String(this.value);
+            if (typeof this.value === 'string') v = `"${v}"`;
+            if (v.length > 50) v = v.substring(0, 47) + "...";
+            content.push(`val=${v}`);
+        } else if (this.isList) {
+            content.push(`len=${this.elements.length}`);
+        } else if (this.isRecord) {
+            const keys = Object.keys(this.fields);
+            let keysStr = "";
+            if (keys.length > 3) {
+                keysStr = keys.slice(0, 3).join(", ") + ", ...";
+            } else {
+                keysStr = keys.join(", ");
+            }
+            content.push(`fields=[${keysStr}]`);
+        } else {
+            // Fallback
+            let v = String(this.value);
+            if (v.length > 50) v = v.substring(0, 47) + "...";
+            content.push(`val=${v}`);
+        }
+
+        // 3. Meta Indicators
+        if (this.comments.length > 0) {
+            content.push(`comments=${this.comments.length}`);
+        }
+        if (Object.keys(this.attr).length > 0) {
+            content.push(`attr=[${Object.keys(this.attr).join(', ')}]`);
+        }
+        if (this.tags.length > 0) {
+            content.push(`tags=[${this.tags.join(', ')}]`);
+        }
+
+        const detailsStr = content.length > 0 ? " " + content.join(" ") : "";
+        return `${header}${detailsStr}>`;
+    }
+
+
+}

package/src/models/Schema.ts

@@ -0,0 +1,222 @@
+import { Meta, MetaInfo, MetaProps } from './Meta';
+
+export enum SchemaKind {
+    PRIMITIVE = "PRIMITIVE", // int, string, bool, null
+    RECORD = "RECORD",       // User, Point, or anonymous <...>
+    LIST = "LIST",           // Array/Sequence
+    DICT = "DICT",           // Future-proofing: Key-Value pairs
+    ANY = "ANY"              // Fallback
+}
+
+export interface SchemaProps extends MetaProps {
+    typeName?: string;
+    name?: string;
+    fields?: Schema[];
+    element?: Schema;
+    key?: Schema;
+    value?: Schema;
+    required?: boolean;
+}
+
+export class Schema extends Meta {
+    kind: SchemaKind;
+    typeName: string;
+    name: string;
+    
+    // Structure references
+    element: Schema | null;
+    key: Schema | null;
+    value: Schema | null;
+    
+    // Flags
+    required: boolean;
+
+    // Internal fields storage
+    private _fieldsList: Schema[] = [];
+    private _fieldsMap: Map<string, Schema> = new Map();
+
+    constructor(kind: SchemaKind, props: SchemaProps = {}) {
+        super(props);
+        
+        this.kind = kind;
+        this.typeName = props.typeName || "any";
+        this.name = props.name || "";
+
+        this.element = props.element || null;
+        this.key = props.key || null;
+        this.value = props.value || null;
+        this.required = props.required || false;
+
+        if (props.fields) {
+            props.fields.forEach(f => this.addField(f));
+        }
+    }
+
+    // -----------------------------------------------------------
+    // Properties (Is...)
+    // -----------------------------------------------------------
+
+    get isPrimitive(): boolean { return this.kind === SchemaKind.PRIMITIVE; }
+    get isRecord(): boolean { return this.kind === SchemaKind.RECORD; }
+    get isList(): boolean { return this.kind === SchemaKind.LIST; }
+    
+    get isAny(): boolean {
+        return (
+            this.kind === SchemaKind.ANY ||
+            (this.typeName === "any" && this.kind === SchemaKind.PRIMITIVE) ||
+            (this.typeName === "any" && this.kind === SchemaKind.RECORD)
+        );
+    }
+
+    get fields(): Schema[] {
+        return this._fieldsList;
+    }
+
+    // -----------------------------------------------------------
+    // Field Management
+    // -----------------------------------------------------------
+
+    clearFields(): void {
+        this._fieldsList = [];
+        this._fieldsMap.clear();
+    }
+
+    addField(field: Schema): void {
+        // Python logic: Auto-switch to RECORD if adding fields
+        if (this.kind !== SchemaKind.RECORD) {
+            this.kind = SchemaKind.RECORD;
+        }
+
+        // Auto-naming if missing
+        const fName = field.name || String(this._fieldsList.length);
+        field.name = fName;
+
+        this._fieldsList.push(field);
+        this._fieldsMap.set(fName, field);
+    }
+
+    /**
+     * Equivalent to Python's __getitem__.
+     * Allows access by numeric index or field name string.
+     */
+    getField(key: number | string): Schema | undefined {
+        if (!this.isRecord) {
+            throw new Error(`Schema kind ${this.kind} is not subscriptable (not a RECORD).`);
+        }
+        if (typeof key === 'number') {
+            return this._fieldsList[key];
+        }
+        return this._fieldsMap.get(key);
+    }
+
+    /**
+     * Replaces an existing field with a new definition based on field.name.
+     * Preserves the original order in the fields list.
+     * If the field does not exist, it appends it (like addField).
+     */
+    replaceField(field: Schema): void {
+        const fName = field.name;
+        if (!fName) {
+            throw new Error("Cannot replace a field without a name.");
+        }
+
+        if (this._fieldsMap.has(fName)) {
+            // 1. Retrieve the old object to find its index
+            const oldField = this._fieldsMap.get(fName)!;
+            const idx = this._fieldsList.indexOf(oldField);
+
+            if (idx !== -1) {
+                // 2. Replace in list (preserve order)
+                this._fieldsList[idx] = field;
+            } else {
+                // Fallback safety (should not happen if map/list synced)
+                this._fieldsList.push(field);
+            }
+
+            // 3. Update map
+            this._fieldsMap.set(fName, field);
+        } else {
+            // Field doesn't exist, treat as add
+            this.addField(field);
+        }
+    }
+
+    // -----------------------------------------------------------
+    // Meta Management
+    // -----------------------------------------------------------
+
+    clearMeta(): void {
+        this.clearCommonMeta();
+        this.required = false;
+    }
+
+    applyMeta(info: MetaInfo | Schema | undefined): void {
+        if(!info) return;
+        // 1. Apply common stuff (meta dict, comments, tags)
+        this.applyCommonMeta(info);
+
+        // 2. Apply Schema-specific constraints
+        if (info.required) {
+            this.required = true;
+        }
+    }
+
+    // -----------------------------------------------------------
+    // Debug / Representation
+    // -----------------------------------------------------------
+
+    /**
+     * Technical debug representation.
+     * Format: <Schema(KIND:type_name) name='...' details...>
+     */
+    toString(): string {
+        // 1. Basic Info: Kind and TypeName
+        const kindStr = this.kind;
+        
+        let typeLabel = "";
+        if (this.typeName && this.typeName !== "any" && this.typeName !== this.kind) {
+            typeLabel = `:${this.typeName}`;
+        }
+
+        const header = `<Schema(${kindStr}${typeLabel})`;
+
+        // 2. Field Name
+        const nameStr = this.name ? ` name="${this.name}"` : "";
+
+        // 3. Details
+        const details: string[] = [];
+
+        if (this.required) details.push("!required");
+        
+        const attrKeys = Object.keys(this.attr);
+        if (attrKeys.length > 0) details.push(`attr=[${attrKeys.map(a => '"' + a + '"').join(', ')}]`);
+        
+        if (this.tags.length > 0) details.push(`tags=[${this.tags.join(', ')}]`);
+        if (this.comments.length > 0) details.push(`comments=${this.comments.length}`);
+
+        // Structure: Record
+        if (this.isRecord) {
+            const count = this._fieldsList.length;
+            if (count > 0) {
+                const limit = 3;
+                const fieldNames = this._fieldsList.slice(0, limit).map(f => f.name);
+                if (count > limit) fieldNames.push("...");
+                details.push(`fields(${count})=[${fieldNames.join(', ')}]`);
+            } else {
+                details.push("fields=[]");
+            }
+        }
+        // Structure: List
+        else if (this.isList) {
+            const elType = this.element ? (this.element.typeName || "None") : "None";
+            const elKind = this.element ? this.element.kind : "ANY";
+            details.push(`element=${elKind}:${elType}`);
+        }
+
+        const detailsStr = details.length > 0 ? " " + details.join(" ") : "";
+
+        return `${header}${nameStr}${detailsStr}>`;
+    }
+
+  
+}

package/tests/00.meta.test.ts

@@ -0,0 +1,31 @@
+import { describe, it, expect } from 'vitest';
+import { MetaInfo } from '../src/index';
+
+describe('AI Data Meta', () => {
+    it('should Meta be properly formatted', () => {
+        const meta = new MetaInfo({
+
+            comments: ["This is a comment"],
+            attr: { foo: "bar" },
+            tags: ["tag1", "tag2"],
+            required: true
+        });
+        const expected = '<MetaInfo !required #tag1 #tag2 $foo="bar" /* This is a comme.. */>';
+        // const expectedJSON
+        const expected_val = {
+            "comments": [
+                "This is a comment"
+            ],
+            "attr": {
+                "foo": "bar"
+            },
+            "tags": [
+                "tag1",
+                "tag2"
+            ],
+            "required": true
+        }
+        expect(meta).toMatchObject(expected_val);
+        expect(meta.toString()).toBe(expected);
+    });
+});

package/tests/00.node.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect } from 'vitest';
+import { Schema, SchemaKind, Node } from '../src/index';
+
+describe('AI Node test', () => {
+    it('should encode raw object', () => {
+        const schema = new Schema(
+            SchemaKind.DICT,
+            {
+                name: "TestSchema",
+                comments: ["This is a comment"],
+                attr: { foo: "bar" },
+                tags: ["tag1", "tag2"],
+                required: true
+
+            });
+        const node = new Node(schema, {
+            value: 3,
+        })
+
+        const expected = '<Node(DICT:any) val=3>';
+        const expected_val = {
+            "comments": [],
+            "attr": {},
+            "tags": [],
+            "schema": {
+                "comments": [
+                    "This is a comment"
+                ],
+                "attr": {
+                    "foo": "bar"
+                },
+                "tags": [
+                    "tag1",
+                    "tag2"
+                ],
+                "_fieldsList": [],
+                "_fieldsMap": {},
+                "kind": "DICT",
+                "typeName": "any",
+                "name": "TestSchema",
+                "element": null,
+                "key": null,
+                "value": null,
+                "required": true
+            },
+            "name": "",
+            "value": 3,
+            "fields": {},
+            "elements": []
+        }
+        expect(node).toMatchObject(expected_val);
+        expect(node.toString()).toBe(expected);
+    });
+});