cddl 0.12.0 → 0.12.1

package/build/parser.d.ts

@@ -6,6 +6,7 @@ export default class Parser {
     l: Lexer;
     curToken: Token;
     peekToken: Token;
+    peekBelowToken: Token;
     constructor(filePath: string);
     private nextToken;
     private parseAssignments;

package/build/parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../src/parser.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,MAAM,YAAY,CAAA;AAE9B,OAAO,EAAE,KAAK,EAAU,MAAM,aAAa,CAAC;AAG5C,OAAO,EAE2C,UAAU,EAE3D,MAAM,UAAU,CAAA;AAoBjB,MAAM,CAAC,OAAO,OAAO,MAAM;;IAEvB,CAAC,EAAE,KAAK,CAAC;IAET,QAAQ,EAAE,KAAK,CAAa;IAC5B,SAAS,EAAE,KAAK,CAAa;gBAEhB,QAAQ,EAAE,MAAM;IAQ7B,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,gBAAgB;IA2CxB,OAAO,CAAC,oBAAoB;IA0b5B,OAAO,CAAC,wBAAwB;IAahC;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAoBnB,OAAO,CAAC,iBAAiB;IAazB,OAAO,CAAC,iBAAiB;IAqJzB,OAAO,CAAC,aAAa;IAgBrB,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,kBAAkB;IAuD1B,OAAO,CAAC,gBAAgB;IA4DxB;;OAEG;IACH,OAAO,CAAC,YAAY;IAcpB,KAAK;IAaL,OAAO,CAAC,WAAW;CAKtB"}
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../src/parser.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,MAAM,YAAY,CAAA;AAE9B,OAAO,EAAE,KAAK,EAAU,MAAM,aAAa,CAAC;AAG5C,OAAO,EAE2C,UAAU,EAE3D,MAAM,UAAU,CAAA;AAoBjB,MAAM,CAAC,OAAO,OAAO,MAAM;;IAEvB,CAAC,EAAE,KAAK,CAAC;IAET,QAAQ,EAAE,KAAK,CAAa;IAC5B,SAAS,EAAE,KAAK,CAAa;IAC7B,cAAc,EAAE,KAAK,CAAa;gBAErB,QAAQ,EAAE,MAAM;IAS7B,OAAO,CAAC,SAAS;IAOjB,OAAO,CAAC,gBAAgB;IA2CxB,OAAO,CAAC,oBAAoB;IA8d5B,OAAO,CAAC,wBAAwB;IAahC;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAenB,OAAO,CAAC,iBAAiB;IAazB,OAAO,CAAC,iBAAiB;IAqKzB,OAAO,CAAC,aAAa;IAgBrB,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,kBAAkB;IAuD1B,OAAO,CAAC,gBAAgB;IA4DxB;;OAEG;IACH,OAAO,CAAC,YAAY;IAcpB,KAAK;IAaL,OAAO,CAAC,WAAW;CAKtB"}

package/build/parser.js

@@ -26,15 +26,18 @@ export default class Parser {
     l;
     curToken = NIL_TOKEN;
     peekToken = NIL_TOKEN;
+    peekBelowToken = NIL_TOKEN;
     constructor(filePath) {
         this.#filePath = filePath;
         this.l = new Lexer(fs.readFileSync(filePath, 'utf-8'));
         this.nextToken();
         this.nextToken();
+        this.nextToken();
     }
     nextToken() {
         this.curToken = this.peekToken;
-        this.peekToken = this.l.nextToken();
+        this.peekToken = this.peekBelowToken;
+        this.peekBelowToken = this.l.nextToken();
         return true;
     }
     parseAssignments() {
@@ -110,7 +113,10 @@ export default class Parser {
          *       attireBlock
          *   )
          */
-        if (closingTokens.length && this.peekToken.Type === Tokens.SLASH) {
+        if (closingTokens.includes(Tokens.RPAREN) &&
+            this.peekToken.Type === Tokens.SLASH &&
+            this.peekBelowToken.Type !== Tokens.SLASH &&
+            !(this.curToken.Type === Tokens.SLASH && this.peekToken.Type === Tokens.SLASH)) {
             const propertyType = [];
             while (!closingTokens.includes(this.curToken.Type)) {
                 propertyType.push(...this.parsePropertyTypes());
@@ -123,6 +129,9 @@ export default class Parser {
                     this.nextToken();
                 }
             }
+            if (this.curToken.Type === Tokens.RPAREN) {
+                this.nextToken();
+            }
             if (groupName) {
                 const variable = {
                     Type: 'variable',
@@ -163,6 +172,22 @@ export default class Parser {
             return [prop];
         }
         while (!closingTokens.includes(this.curToken.Type)) {
+            /**
+             * check if we have a group choice instead of an assignment
+             */
+            if (this.curToken.Type === Tokens.SLASH && this.peekToken.Type === Tokens.SLASH) {
+                if (valuesOrProperties.length === 0) {
+                    throw this.parserError('Unexpected group choice operator "//" at start of group');
+                }
+                if (!isChoice) {
+                    const last = valuesOrProperties.pop();
+                    valuesOrProperties.push([last]);
+                    isChoice = true;
+                }
+                this.nextToken();
+                this.nextToken();
+                continue;
+            }
             const propertyType = [];
             const comments = [];
             let isUnwrapped = false;
@@ -197,13 +222,23 @@ export default class Parser {
                 this.curToken.Literal === Tokens.LBRACK ||
                 this.curToken.Literal === Tokens.LPAREN) {
                 const innerGroup = this.parseAssignmentValue();
-                valuesOrProperties.push({
+                const prop = {
                     HasCut: false,
                     Occurrence: occurrence,
                     Name: '',
                     Type: innerGroup,
                     Comments: []
-                });
+                };
+                if (isChoice) {
+                    valuesOrProperties[valuesOrProperties.length - 1].push(prop);
+                }
+                else {
+                    valuesOrProperties.push(prop);
+                }
+                if (this.curToken.Type === Tokens.COMMA) {
+                    this.nextToken();
+                    isChoice = false;
+                }
                 continue;
             }
             /**
@@ -317,7 +352,7 @@ export default class Parser {
              */
             const props = this.parseAssignmentValue();
             let operator = this.isOperator() ? this.parseOperator() : undefined;
-            if (!isChoice && this.curToken.Type === Tokens.SLASH) {
+            if (!isChoice && this.curToken.Type === Tokens.SLASH && this.peekToken.Type !== Tokens.SLASH) {
                 this.nextToken();
                 const nextType = this.parsePropertyType();
                 if (Array.isArray(props)) {
@@ -485,10 +520,6 @@ export default class Parser {
     openSegment() {
         if (this.curToken.Type === Tokens.LBRACE) {
             this.nextToken();
-            if (this.peekToken.Type === Tokens.LPAREN) {
-                this.nextToken();
-                return [Tokens.RPAREN, Tokens.RBRACE];
-            }
             return [Tokens.RBRACE];
         }
         else if (this.curToken.Type === Tokens.LPAREN) {
@@ -549,6 +580,13 @@ export default class Parser {
                         Unwrapped: isUnwrapped
                     };
                 }
+                else if (this.curToken.Literal === Tokens.LBRACE) {
+                    const val = this.parseAssignmentValue();
+                    if (Array.isArray(val)) {
+                        throw new Error('Unexpected array in property type parsing');
+                    }
+                    type = val;
+                }
                 else if (this.curToken.Type === Tokens.IDENT) {
                     type = {
                         Type: 'group',
@@ -616,6 +654,9 @@ export default class Parser {
                 this.nextToken();
             }
             this.nextToken();
+            if (!type || (typeof type === 'object' && !('Value' in type))) {
+                throw new Error('Invalid type for range definition');
+            }
             const Min = typeof type === 'string' || typeof type.Value === 'number'
                 ? type
                 : type.Value;
@@ -654,6 +695,10 @@ export default class Parser {
                 this.nextToken(); // eat ")"
             }
         }
+        if (!type) {
+            const { line, position: column } = this.l.getLocation();
+            throw new Error(`Unexpected type: ${this.curToken.Type} at line ${line} column ${column}`);
+        }
         return type;
     }
     parseOperator() {

package/docs/cddl-cheatsheet.md

@@ -0,0 +1,196 @@
+# CDDL Core Concepts: Choices and Maps
+
+This guide explains three fundamental concepts in CDDL that are often confused: **Type Choices**, **Group Choices**, and **Maps**.
+
+## 1. Type Choice (`/`)
+
+A **Type Choice** allows a value to be one of several distinct types. It is represented by the single forward slash `/`.
+
+Think of it as an "OR" operator for *values*.
+
+### Syntax
+```cddl
+type1 / type2 / type3
+```
+
+### Examples
+
+**Simple Value Choice:**
+```cddl
+; MyValue can be an integer OR a text string
+MyValue = int / tstr
+```
+
+**Inside an Array:**
+```cddl
+; An array where the first element is either an int OR a float
+MyArray = [ int / float, tstr ]
+```
+
+**Inside a Map Property:**
+```cddl
+; The "score" property can be an integer OR null
+MyMap = {
+    "score" => int / null
+}
+```
+
+---
+
+## 2. Group Choice (`//`)
+
+A **Group Choice** allows a structure (like a map or array) to match one of several *groups* of properties. It is represented by the double forward slash `//`.
+
+Think of it as an "OR" operator for *sets of fields/entries*.
+
+### Syntax
+```cddl
+(group1) // (group2) // (group3)
+```
+
+### Examples
+
+**Choice between sets of fields:**
+```cddl
+; A defined group that is either a "street address" OR a "po box"
+Address = (
+    street: tstr,
+    city: tstr
+) // (
+    po-box: int,
+    city: tstr
+)
+```
+
+**Usage in Maps:**
+When used inside a map, it means the map must contain *either* the keys from the first group *OR* the keys from the second group.
+
+```cddl
+; A user profile must have either a "username" OR an "email" (but not necessarily both, depending on other rules)
+UserProfile = {
+    id: int,
+    (
+        username: tstr
+    ) // (
+        email: tstr
+    )
+}
+```
+
+**Key Difference from Type Choice:**
+- `key: int / tstr` -> The key exists, and its value is either int or string.
+- `(key1: int) // (key2: int)` -> Either the key `key1` exists OR the key `key2` exists.
+
+---
+
+## 3. Maps
+
+In CDDL, a **Map** is defined using curly braces `{}`. It corresponds to a JSON Object or a dictionary/hash map.
+
+Inside a Map, you define **Groups** of properties/pairs using `key => value` or `key: value` syntax.
+
+### Syntax
+```cddl
+MyMap = {
+    key1 => value1,
+    key2: value2,
+    optional-key3?: value3
+}
+```
+
+### Deep Dive: Maps vs. Groups
+
+- A **Group** is just a sequence of fields (key-value pairs) inside a structure.
+- A **Map** `{ ... }` acts as a container for a Group.
+
+**Defining a reusable Group:**
+```cddl
+; "PersonFields" is just a list of fields, NOT a map yet.
+PersonFields = (
+    name: tstr,
+    age: int
+)
+```
+
+**Using the Group in a Map:**
+```cddl
+; "Student" is a Map that contains the PersonFields
+Student = {
+    PersonFields,
+    school: tstr
+}
+
+; "Teacher" is also a Map that contains the PersonFields
+Teacher = {
+    PersonFields,
+    subject: tstr
+}
+```
+
+### Mixing Choices in Maps
+
+You can combine Maps and Choices to create complex validation logic:
+
+```cddl
+Response = {
+    "status" => "ok",
+    "data" => tstr
+} / {
+    "status" => "error",
+    "code" => int,
+    "message" => tstr
+}
+```
+*This definition means a Response object must look like EITHER the first block (status="ok", data=...) OR the second block (status="error", code=...).*
+
+---
+
+## 4. Arrays
+
+Arrays in CDDL are defined using square brackets `[]`. They correspond to JSON Arrays.
+
+### Syntax
+```cddl
+MyArray = [ type1, type2, ... ]
+```
+
+### Examples
+
+**Simple Array:**
+```cddl
+; An array of an integer, a string, and a float
+Point3D = [ x: float, y: float, z: float ]
+```
+
+**Array with Group Choice:**
+You can use group choices inside arrays to allow different structures.
+
+```cddl
+; An item is either an integer OR a string
+Item = [ (int // tstr) ]
+```
+
+---
+
+## 5. Literals
+
+CDDL supports various literal values which are useful for exact matching.
+
+### Examples
+
+```cddl
+LiteralTest = {
+  ; Exact string match
+  type: "widget",
+
+  ; Exact integer match
+  version: 1,
+
+  ; Big Integers
+  big_id: 9007199254740995,
+
+  ; Null and Booleans
+  is_active: true,
+  deleted_at: null
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cddl",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "description": "Concise data definition language (RFC 8610) implementation and JSON validator in Node.js",
   "author": "Christian Bromann <mail@bromann.dev>",
   "license": "MIT",
@@ -30,7 +30,8 @@
     "release:patch": "npm run release -- patch",
     "release:minor": "npm run release -- minor",
     "release:major": "npm run release -- major",
-    "test": "vitest",
+    "test": "vitest run",
+    "checks:all": "npm run compile && npm run test",
     "watch": "tsc --watch"
   },
   "devDependencies": {
@@ -38,7 +39,7 @@
     "@types/node": "^22.15.3",
     "@vitest/coverage-v8": "^3.1.2",
     "npm-run-all": "^4.1.5",
-    "release-it": "^19.0.1",
+    "release-it": "^19.2.4",
     "typescript": "^5.8.3",
     "vitest": "^3.1.2"
   },