xcdn 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gioele Stefano Luca Fierro
+
+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,139 @@
+# > xCDN_ (JavaScript)
+
+A complete JavaScript library to parse, serialize and deserialize **> xCDN_ — eXtensible Cognitive Data Notation**.
+
+> **What is > xCDN_?**
+> xCDN_ is a human-first, machine-optimized data notation with native types, tags and annotations.
+> It supports comments, trailing commas, unquoted keys and multi-line strings.
+> You can read more about this notation in the [> xCDN_ repository](https://github.com/gslf/xCDN).
+
+## Features
+
+- Full streaming document model (one or more top-level values)
+- Optional **prolog** (`$schema: "..."`, ...)
+- Objects, arrays and scalars
+- Native types: `Decimal` (`d"..."`), `UUID` (`u"..."`), `DateTime` (`t"..."` RFC3339),
+  `Duration` (`r"..."` ISO8601), `Bytes` (`b"..."` Base64)
+- `#tags` and `@annotations(args?)` that decorate any value
+- Comments: `//` and `/* ... */`
+- Trailing commas and unquoted keys
+- Pretty or compact serialization
+- Zero dependencies
+
+## Example
+
+```xcdn
+$schema: "https://gslf.github.io/xCDN/schemas/v1/meta.xcdn",
+
+server_config: {
+  host: "localhost",
+  // Unquoted keys & trailing commas? Yes.
+  ports: [8080, 9090,],
+
+  // Native Decimals & ISO8601 Duration
+  timeout: r"PT30S",
+  max_cost: d"19.99",
+
+  // Semantic Tagging
+  admin: #user {
+    id: u"550e8400-e29b-41d4-a716-446655440000",
+    role: "superuser"
+  },
+
+  // Binary data handling
+  icon: @mime("image/png") b"iVBORw0KGgoAAAANSUhEUgAAAAUA...",
+}
+```
+
+## Installation
+
+```bash
+npm install xcdn
+```
+
+## Usage
+
+```javascript
+import xcdn from 'xcdn';
+
+// Parse an xCDN string
+const doc = xcdn.parse(`
+  name: "Alice",
+  age: 30,
+  active: true,
+`);
+
+// Pretty-print
+console.log(xcdn.stringify(doc));
+
+// Compact output
+console.log(xcdn.stringifyCompact(doc));
+```
+
+### Named imports
+
+```javascript
+import { parseStr, toStringPretty, toStringCompact } from 'xcdn';
+
+const doc = parseStr(source);
+const pretty = toStringPretty(doc);
+const compact = toStringCompact(doc);
+```
+
+### Accessing fields
+
+```javascript
+import { parseStr } from 'xcdn';
+
+const doc = parseStr(`
+  user: {
+    name: "Mario Rossi",
+    age: 30,
+    roles: [#admin "administrator", #user "standard"],
+  },
+  session_id: u"550e8400-e29b-41d4-a716-446655440000",
+  balance: d"1234.56",
+  created_at: t"2025-01-15T10:30:00Z",
+`);
+
+const root = doc.values[0].value;
+
+// Access nested values
+root.get('user').value.get('name').value.value; // "Mario Rossi"
+
+// Check keys
+root.has('user');   // true
+root.keys();        // ["user", "session_id", "balance", "created_at"]
+
+// Iterate decorated items
+const roles = root.get('user').value.get('roles').value;
+for (const role of roles) {
+  console.log(role.tags[0].name, role.value.value);
+  // "admin" "administrator"
+  // "user"  "standard"
+}
+```
+
+### Sub-module imports
+
+```javascript
+import { Parser } from 'xcdn/parser';
+import { Serializer, Format } from 'xcdn/serializer';
+import { XObject, XArray, Node, XString } from 'xcdn/ast';
+import { XCDNError } from 'xcdn/error';
+import { Lexer } from 'xcdn/lexer';
+```
+
+## Testing
+
+```bash
+npm test
+```
+
+## License
+
+MIT, see [LICENSE](LICENSE).
+
+---
+
+#### This is a :/# GSLF project.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "xcdn",
+  "version": "1.0.0",
+  "description": "xCDN parser and serializer for JavaScript",
+  "main": "src/index.js",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js",
+    "./ast": "./src/ast.js",
+    "./error": "./src/error.js",
+    "./lexer": "./src/lexer.js",
+    "./parser": "./src/parser.js",
+    "./serializer": "./src/serializer.js"
+  },
+  "scripts": {
+    "test": "node --test tests/"
+  },
+  "keywords": [
+    "xcdn",
+    "parser",
+    "serializer",
+    "data-format"
+  ],
+  "author": "GioeleSLFierro",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gslf/xCDN-JavaScript.git"
+  },
+  "files": [
+    "src/",
+    "LICENSE",
+    "README.md"
+  ],
+  "license": "MIT"
+}

package/src/ast.js

@@ -0,0 +1,409 @@
+/**
+ * xCDN AST Module
+ * Data structures for the xCDN format
+ */
+
+/**
+ * Main xCDN document
+ */
+export class Document {
+  /**
+   * @param {Directive[]} prolog - Initial directives ($schema, etc.)
+   * @param {Node[]} values - Top-level values
+   */
+  constructor(prolog = [], values = []) {
+    this.prolog = prolog;
+    this.values = values;
+  }
+
+  /**
+   * Dict-like access
+   * @param {number|string} key
+   */
+  get(key) {
+    if (typeof key === 'number') {
+      return this.values[key];
+    }
+    // Access the first object
+    if (this.values.length > 0 && this.values[0].value instanceof XObject) {
+      return this.values[0].value.get(key);
+    }
+    return undefined;
+  }
+
+  /**
+   * Set dict-like
+   * @param {string} key
+   * @param {*} value
+   */
+  set(key, value) {
+    if (this.values.length > 0 && this.values[0].value instanceof XObject) {
+      this.values[0].value.set(key, value);
+    }
+  }
+
+  /**
+   * Check if key exists
+   * @param {string} key
+   */
+  has(key) {
+    if (this.values.length > 0 && this.values[0].value instanceof XObject) {
+      return this.values[0].value.has(key);
+    }
+    return false;
+  }
+}
+
+/**
+ * Directive ($name: value)
+ */
+export class Directive {
+  /**
+   * @param {string} name - Directive name (without $)
+   * @param {*} value - Directive value
+   */
+  constructor(name, value) {
+    this.name = name;
+    this.value = value;
+  }
+}
+
+/**
+ * Node decorated with tags and annotations
+ */
+export class Node {
+  /**
+   * @param {Tag[]} tags - List of tags (#tag)
+   * @param {Annotation[]} annotations - List of annotations (@anno)
+   * @param {*} value - Actual value
+   */
+  constructor(tags = [], annotations = [], value = null) {
+    this.tags = tags;
+    this.annotations = annotations;
+    this.value = value;
+  }
+
+  // Dict-like methods delegated to the value
+  get(key, defaultValue = undefined) {
+    if (this.value && typeof this.value.get === 'function') {
+      return this.value.get(key, defaultValue);
+    }
+    return defaultValue;
+  }
+
+  set(key, value) {
+    if (this.value && typeof this.value.set === 'function') {
+      this.value.set(key, value);
+    }
+  }
+
+  has(key) {
+    if (this.value && typeof this.value.has === 'function') {
+      return this.value.has(key);
+    }
+    return false;
+  }
+
+  keys() {
+    if (this.value instanceof XObject) {
+      return this.value.keys();
+    }
+    return [];
+  }
+
+  valuesIter() {
+    if (this.value instanceof XObject) {
+      return this.value.valuesIter();
+    }
+    return [];
+  }
+
+  items() {
+    if (this.value instanceof XObject) {
+      return this.value.items();
+    }
+    return [];
+  }
+
+  append(value) {
+    if (this.value instanceof XArray) {
+      this.value.append(value);
+    }
+  }
+
+  get length() {
+    if (this.value && typeof this.value.length !== 'undefined') {
+      return this.value.length;
+    }
+    return 0;
+  }
+
+  [Symbol.iterator]() {
+    if (this.value && typeof this.value[Symbol.iterator] === 'function') {
+      return this.value[Symbol.iterator]();
+    }
+    return [][Symbol.iterator]();
+  }
+}
+
+/**
+ * Tag (#tag)
+ */
+export class Tag {
+  /**
+   * @param {string} name - Tag name
+   */
+  constructor(name) {
+    this.name = name;
+  }
+}
+
+/**
+ * Annotation (@name(args...))
+ */
+export class Annotation {
+  /**
+   * @param {string} name - Annotation name
+   * @param {*[]} args - Optional arguments
+   */
+  constructor(name, args = []) {
+    this.name = name;
+    this.args = args;
+  }
+}
+
+// ============== VALUE TYPES ==============
+
+/**
+ * Base class for value types
+ */
+export class ValueType {
+  constructor() {
+    if (new.target === ValueType) {
+      throw new Error('ValueType is abstract');
+    }
+  }
+}
+
+/**
+ * Null value
+ */
+export class Null extends ValueType {
+  constructor() {
+    super();
+  }
+}
+
+/**
+ * Boolean value
+ */
+export class Bool extends ValueType {
+  /**
+   * @param {boolean} value
+   */
+  constructor(value) {
+    super();
+    this.value = value;
+  }
+}
+
+/**
+ * Integer value
+ */
+export class Int extends ValueType {
+  /**
+   * @param {number|bigint} value
+   */
+  constructor(value) {
+    super();
+    this.value = typeof value === 'bigint' ? value : BigInt(Math.trunc(value));
+  }
+}
+
+/**
+ * Float value
+ */
+export class Float extends ValueType {
+  /**
+   * @param {number} value
+   */
+  constructor(value) {
+    super();
+    this.value = value;
+  }
+}
+
+/**
+ * Decimal value (d"...")
+ */
+export class DecimalValue extends ValueType {
+  /**
+   * @param {string} value - String representation of the decimal
+   */
+  constructor(value) {
+    super();
+    this.value = value; // Keep as string for precision
+  }
+}
+
+/**
+ * String value
+ */
+export class XString extends ValueType {
+  /**
+   * @param {string} value
+   */
+  constructor(value) {
+    super();
+    this.value = value;
+  }
+}
+
+/**
+ * Bytes value (b"..." base64)
+ */
+export class Bytes extends ValueType {
+  /**
+   * @param {Uint8Array} value - Decoded bytes
+   */
+  constructor(value) {
+    super();
+    this.value = value;
+  }
+}
+
+/**
+ * Datetime value (t"...")
+ */
+export class DateTime extends ValueType {
+  /**
+   * @param {Date} value
+   */
+  constructor(value) {
+    super();
+    this.value = value;
+  }
+}
+
+/**
+ * Duration value (r"...")
+ */
+export class Duration extends ValueType {
+  /**
+   * @param {string} value - ISO8601 duration as string
+   */
+  constructor(value) {
+    super();
+    this.value = value;
+  }
+}
+
+/**
+ * UUID value (u"...")
+ */
+export class Uuid extends ValueType {
+  /**
+   * @param {string} value - UUID as string
+   */
+  constructor(value) {
+    super();
+    this.value = value;
+  }
+}
+
+/**
+ * xCDN Array
+ */
+export class XArray extends ValueType {
+  /**
+   * @param {Node[]} value - List of nodes
+   */
+  constructor(value = []) {
+    super();
+    this.value = value;
+  }
+
+  get(index) {
+    return this.value[index];
+  }
+
+  set(index, val) {
+    this.value[index] = val;
+  }
+
+  get length() {
+    return this.value.length;
+  }
+
+  append(val) {
+    // Wrap in Node if not already
+    if (val instanceof Node) {
+      this.value.push(val);
+    } else {
+      this.value.push(new Node([], [], val));
+    }
+  }
+
+  [Symbol.iterator]() {
+    return this.value[Symbol.iterator]();
+  }
+}
+
+/**
+ * xCDN Object
+ */
+export class XObject extends ValueType {
+  /**
+   * @param {Map<string, Node>|Object} value - Key-value map
+   */
+  constructor(value = new Map()) {
+    super();
+    if (value instanceof Map) {
+      this.value = value;
+    } else {
+      this.value = new Map(Object.entries(value));
+    }
+  }
+
+  get(key, defaultValue = undefined) {
+    return this.value.has(key) ? this.value.get(key) : defaultValue;
+  }
+
+  set(key, val) {
+    // Wrap in Node if not already
+    if (val instanceof Node) {
+      this.value.set(key, val);
+    } else {
+      this.value.set(key, new Node([], [], val));
+    }
+  }
+
+  has(key) {
+    return this.value.has(key);
+  }
+
+  get length() {
+    return this.value.size;
+  }
+
+  keys() {
+    return Array.from(this.value.keys());
+  }
+
+  valuesIter() {
+    return Array.from(this.value.values());
+  }
+
+  items() {
+    return Array.from(this.value.entries());
+  }
+
+  [Symbol.iterator]() {
+    return this.value.keys()[Symbol.iterator]();
+  }
+}
+
+// Export aliases for compatibility
+export { XString as String };
+export { XArray as Array };
+export { XObject as Object };

package/src/error.js

@@ -0,0 +1,106 @@
+/**
+ * xCDN Error Module
+ * Error handling for the xCDN parser
+ */
+
+/**
+ * Represents a position in the source code
+ */
+export class Span {
+  /**
+   * @param {number} offset - Absolute byte offset
+   * @param {number} line - Line number (1-indexed)
+   * @param {number} column - Column number (1-indexed)
+   */
+  constructor(offset, line, column) {
+    this.offset = offset;
+    this.line = line;
+    this.column = column;
+  }
+
+  toString() {
+    return `${this.line}:${this.column}`;
+  }
+
+  clone() {
+    return new Span(this.offset, this.line, this.column);
+  }
+}
+
+/**
+ * Possible error types
+ */
+export const ErrorKind = {
+  Eof: 'Eof',
+  InvalidToken: 'InvalidToken',
+  Expected: 'Expected',
+  InvalidEscape: 'InvalidEscape',
+  InvalidNumber: 'InvalidNumber',
+  InvalidDecimal: 'InvalidDecimal',
+  InvalidDateTime: 'InvalidDateTime',
+  InvalidDuration: 'InvalidDuration',
+  InvalidUuid: 'InvalidUuid',
+  InvalidBase64: 'InvalidBase64',
+  Message: 'Message',
+};
+
+/**
+ * xCDN error with position information
+ */
+export class XCDNError extends Error {
+  /**
+   * @param {string} kind - Error type (from ErrorKind)
+   * @param {Span} span - Error position
+   * @param {string} [context] - Additional context
+   */
+  constructor(kind, span, context = null) {
+    const message = XCDNError.formatMessage(kind, context, span);
+    super(message);
+    this.name = 'XCDNError';
+    this.kind = kind;
+    this.span = span;
+    this.context = context;
+  }
+
+  static formatMessage(kind, context, span) {
+    let msg;
+    switch (kind) {
+      case ErrorKind.Eof:
+        msg = 'Unexpected end of input';
+        break;
+      case ErrorKind.InvalidToken:
+        msg = `Invalid token: ${context}`;
+        break;
+      case ErrorKind.Expected:
+        msg = context; // "Expected X, found Y"
+        break;
+      case ErrorKind.InvalidEscape:
+        msg = 'Invalid escape sequence';
+        break;
+      case ErrorKind.InvalidNumber:
+        msg = 'Invalid number format';
+        break;
+      case ErrorKind.InvalidDecimal:
+        msg = `Invalid decimal value: ${context}`;
+        break;
+      case ErrorKind.InvalidDateTime:
+        msg = `Invalid datetime value: ${context}`;
+        break;
+      case ErrorKind.InvalidDuration:
+        msg = `Invalid duration value: ${context}`;
+        break;
+      case ErrorKind.InvalidUuid:
+        msg = `Invalid UUID value: ${context}`;
+        break;
+      case ErrorKind.InvalidBase64:
+        msg = `Invalid base64 value: ${context}`;
+        break;
+      case ErrorKind.Message:
+        msg = context;
+        break;
+      default:
+        msg = context || 'Unknown error';
+    }
+    return `${msg} at ${span.toString()}`;
+  }
+}