cddl 0.13.1 → 0.14.0

package/.release-it.json

@@ -0,0 +1,12 @@
+{
+  "plugins": {
+    "release-it-pnpm": {}
+  },
+  "git": {
+    "requireCleanWorkingDir": false,
+    "addUntrackedFiles": true,
+    "tagName": "cddl-v${version}",
+    "commitMessage": "chore(cddl): release v${version}",
+    "changelog": "git log --pretty=format:\"* %s (%h)\" ${latestTag ? latestTag + '..HEAD' : ''} -- . ../../tsconfig.json"
+  }
+}

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 Christian Bromann
+Copyright (c) 2026 Christian Bromann
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,4 +1,4 @@
-CDDL [![Test](https://github.com/christian-bromann/cddl/actions/workflows/test.yml/badge.svg)](https://github.com/christian-bromann/cddl/actions/workflows/test.yml)
+CDDL
 ====
 
 > Concise data definition language ([RFC 8610](https://tools.ietf.org/html/rfc8610)) implementation and JSON validator in Node.js.
@@ -10,7 +10,7 @@ There are also CDDL parsers for other languages:
 
 The package is currently mostly used to help generate typed interfaces for the WebDriver Bidi specification in the following projects:
 - [WebdriverIO](https://webdriver.io) - via the [`cddl2ts`](https://www.npmjs.com/package/cddl2ts) package and [this script](https://github.com/webdriverio/webdriverio/blob/a2ae35332f9b3fc9490136df1ac3d2e14c1e35b6/scripts/bidi/index.ts)
-- [Selenium](https://selenium.dev) - via the [`cddl2java`](https://github.com/christian-bromann/cddl2java) package
+- [Selenium](https://selenium.dev) - via the [`cddl2java`](https://github.com/webdriverio/cddl2java) package
 
 __Note:__ this is __work in progress__, feel free to have a look at the code or contribute but don't use this for anything yet!
 
@@ -66,8 +66,8 @@ console.log(ast)
  */
 ```
 
-Read the full documentation on this AST in the [`/docs`](/docs/README.md) directory.
+Read the full documentation on this AST in the [`docs`](./docs/README.md) directory.
 
 ---
 
-If you are interested in this project, please feel free to contribute ideas or code patches. Have a look at our [contributing guidelines](https://github.com/christian-bromann/cddl/blob/master/CONTRIBUTING.md) to get started.
+If you are interested in this project, please feel free to contribute ideas or code patches. Have a look at our [contributing guidelines](https://github.com/webdriverio/cddl/blob/master/CONTRIBUTING.md) to get started.

package/package.json

@@ -1,23 +1,19 @@
 {
   "name": "cddl",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "description": "Concise data definition language (RFC 8610) implementation and JSON validator in Node.js",
   "author": "Christian Bromann <mail@bromann.dev>",
   "license": "MIT",
-  "homepage": "https://github.com/christian-bromann/cddl#readme",
+  "homepage": "https://github.com/webdriverio/cddl#readme",
   "repository": {
     "type": "git",
-    "url": "git+ssh://git@github.com/christian-bromann/cddl.git"
+    "url": "git+ssh://git@github.com/webdriverio/cddl.git"
   },
   "keywords": [
     "cddl"
   ],
-  "engines": {
-    "node": ">=20.0.0",
-    "npm": ">=9.0.0"
-  },
   "bugs": {
-    "url": "https://github.com/christian-bromann/cddl/issues"
+    "url": "https://github.com/webdriverio/cddl/issues"
   },
   "type": "module",
   "exports": "./build/index.js",
@@ -25,29 +21,19 @@
   "bin": {
     "cddl": "./bin/cddl.js"
   },
-  "scripts": {
-    "build": "run-s clean compile",
-    "clean": "rm -rf ./build ./coverage",
-    "compile": "tsc -p ./tsconfig.json",
-    "release": "release-it --github.release",
-    "release:ci": "npm run release -- --ci --npm.skipChecks --no-git.requireCleanWorkingDir",
-    "release:patch": "npm run release -- patch",
-    "release:minor": "npm run release -- minor",
-    "release:major": "npm run release -- major",
-    "test": "vitest run",
-    "checks:all": "npm run compile && npm run test",
-    "watch": "tsc --watch"
-  },
   "devDependencies": {
-    "@types/node": "^24.12.0",
+    "@types/node": "^25.5.0",
     "@types/yargs": "^17.0.35",
     "@vitest/coverage-v8": "^4.1.0",
-    "npm-run-all": "^4.1.5",
-    "release-it": "^19.2.4",
-    "typescript": "^5.9.3",
+    "npm-run-all2": "^8.0.4",
+    "typescript": "^6.0.2",
     "vitest": "^4.1.0"
   },
   "dependencies": {
     "yargs": "^18.0.0"
+  },
+  "scripts": {
+    "release": "release-it --github.release",
+    "release:ci": "pnpm release --ci --npm.skipChecks"
   }
-}
+}

package/src/ast.ts

@@ -0,0 +1,180 @@
+/**
+ * a group definition
+ * ```
+ * person = {
+ *     age: int,
+ *     name: tstr,
+ *     employer: tstr,
+ * }
+ * ```
+ */
+export type Group = {
+    Type: 'group'
+    Name: string
+    IsChoiceAddition: boolean
+    Properties: (Property|Property[])[]
+    Comments: Comment[]
+}
+
+/**
+ * an array definition
+ * ```
+ * Geography = [
+ *     city: tstr
+ * ]
+ * ```
+ */
+export type Array = {
+    Type: 'array'
+    Name: string
+    Values: (Property|Property[])[]
+    Comments: Comment[]
+}
+
+/**
+ * a tag definition
+ * ```
+ * #6.32(tstr)
+ * ```
+ */
+export type Tag = {
+    NumericPart: number
+    TypePart: string
+}
+
+/**
+ * a variable assignment
+ * ```
+ * device-address = byte
+ * ```
+ */
+export type Variable = {
+    Type: 'variable'
+    Name: string
+    IsChoiceAddition: boolean
+    PropertyType: PropertyType | PropertyType[]
+    Operator?: Operator
+    Comments: Comment[]
+}
+
+/**
+ * a comment statement
+ * ```
+ * ; This is a comment
+ * ```
+ */
+export type Comment = {
+    Type: 'comment'
+    Content: string
+    Leading: boolean
+}
+
+export type Occurrence = {
+    n: number
+    m: number
+}
+
+export type Property = {
+    HasCut: boolean
+    Occurrence: Occurrence
+    Name: PropertyName
+    Type: PropertyType | PropertyType[]
+    Comments: Comment[]
+    Operator?: Operator
+}
+
+export enum Type {
+    /**
+     * any types
+     */
+    ANY = 'any',
+
+    /**
+     * boolean types
+     */
+    // Boolean value (major type 7, additional information 20 or 21).
+    BOOL = 'bool',
+
+    /**
+     * numeric types
+     */
+    // An unsigned integer or a negative integer.
+    INT = 'int',
+    // An unsigned integer (major type 0).
+    UINT = 'uint',
+    // A negative integer (major type 1).
+    NINT = 'nint',
+    // One of float16, float32, or float64.
+    FLOAT = 'float',
+    // A number representable as an IEEE 754 half-precision float
+    FLOAT16 = 'float16',
+    // A number representable as an IEEE 754 single-precision
+    FLOAT32 = 'float32',
+    // A number representable as an IEEE 754 double-precision
+    FLOAT64 = 'float64',
+
+    /**
+     * string types
+     */
+    // A byte string (major type 2).
+    BSTR = 'bstr',
+    // A byte string (major type 2).
+    BYTES = 'bytes',
+    // Text string (major type 3)
+    TSTR = 'tstr',
+    // Text string (major type 3)
+    TEXT = 'text',
+
+    /**
+     * null types
+     */
+    NIL = 'nil',
+    NULL = 'null'
+}
+
+/**
+ * can be a number, e.g. "foo = 0..10"
+ * ```
+ * {
+ *   Type: "int",
+ *   Value: 6
+ * }
+ * ```
+ * or a literal, e.g. "foo = 0..max-byte"
+ * ```
+ * {
+ *   Type: "literal",
+ *   Value: "max-byte"
+ * }
+ * ```
+ */
+export type RangePropertyReference = number | string
+
+export type Range = {
+    Min: RangePropertyReference
+    Max: RangePropertyReference
+    Inclusive: boolean
+}
+
+export type OperatorType = 'default' | 'size' | 'regexp' | 'bits' | 'and' | 'within' | 'eq' | 'ne' | 'lt' | 'le' | 'gt' | 'ge'
+export interface Operator {
+    Type: OperatorType
+    Value: PropertyType
+}
+
+export type PropertyReferenceType = 'literal' | 'group' | 'group_array' | 'array' | 'range' | 'tag'
+export type PropertyReference = {
+    Type: PropertyReferenceType
+    Value: string | number | boolean | Group | Array | Range | Tag
+    Unwrapped: boolean
+    Operator?: Operator
+}
+
+export interface NativeTypeWithOperator {
+    Type: Type | PropertyReference
+    Operator?: Operator
+}
+
+export type Assignment = Group | Array | Variable
+export type PropertyType = Assignment | Array | PropertyReference | string | NativeTypeWithOperator
+export type PropertyName = string

package/src/cli/commands/repl.ts

@@ -0,0 +1,33 @@
+import repl from 'node:repl'
+import type { Argv } from 'yargs'
+
+import { CLI_EPILOGUE } from '../constants.js'
+import Lexer from '../../lexer.js'
+import { Tokens } from '../../tokens.js'
+
+export const command = 'repl'
+export const desc = 'Run CDDL repl'
+export const builder = (yargs: Argv<{}>) => {
+    return yargs
+        .epilogue(CLI_EPILOGUE)
+        .help()
+}
+
+export const handler = () => {
+    repl.start({
+        prompt: '> ',
+        eval: evaluate
+    })
+}
+
+export function evaluate (evalCmd: string, _: any, _file: string, callback: (err: Error | null, result: any) => void) {
+    if (!evalCmd) {
+        return callback(new Error('No input'), null)
+    }
+
+    const l = new Lexer(evalCmd)
+    for (let tok = l.nextToken(); tok.Type !== Tokens.EOF; tok = l.nextToken()) {
+        console.log(tok)
+    }
+    return callback(null, null)
+}

package/src/cli/commands/validate.ts

@@ -0,0 +1,44 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import type { Argv, ArgumentsCamelCase } from 'yargs'
+
+import { CLI_EPILOGUE } from '../constants.js'
+import { parse } from '../../index.js'
+
+interface ValidateArguments {
+    filePath: string
+}
+
+export const command = 'validate <filePath>'
+export const desc = 'Validate a *.cddl file'
+export const builder = (yargs: Argv<{}>) => {
+    return yargs
+        .epilogue(CLI_EPILOGUE)
+        .help()
+}
+
+export const handler = (argv: ArgumentsCamelCase<ValidateArguments>) => {
+    const filePath = argv.filePath.startsWith('/')
+        ? argv.filePath
+        : path.resolve(process.cwd(), argv.filePath)
+
+    if (!fs.existsSync(filePath)) {
+        console.error(`Couldn't find CDDL file at ${filePath}`)
+        return process.exit(1)
+    }
+
+    try {
+        parse(filePath)
+
+
+        /**
+         * ToDo check for
+         *  - missing group declarations
+         */
+
+        console.log('✅ Valid CDDL file!')
+    } catch (err: unknown) {
+        console.error(`⚠️  Invalid CDDL file (${filePath})\n\n${(err as Error).stack}`)
+        process.exit(1)
+    }
+}

package/src/cli/constants.ts

@@ -0,0 +1 @@
+export const CLI_EPILOGUE = `Copyright 2023 - Christian Bromann`

package/src/cli/index.ts

@@ -0,0 +1,18 @@
+import yargs from 'yargs/yargs'
+import { hideBin } from 'yargs/helpers'
+
+import * as replCommand from './commands/repl.js'
+import * as validateCommand from './commands/validate.js'
+import { CLI_EPILOGUE } from './constants.js'
+
+export default async function () {
+    const argv = yargs(hideBin(process.argv))
+        .command(replCommand)
+        .command(validateCommand as any)
+        .example('$0 repl', 'Start CDDL repl')
+        .epilogue(CLI_EPILOGUE)
+        .demandCommand()
+        .help()
+
+    return argv.argv
+}

package/src/constants.ts

@@ -0,0 +1,16 @@
+export const WHITESPACE_CHARACTERS = [' ', '\t', '\n', '\r']
+export const BOOLEAN_LITERALS = ['true', 'false']
+
+/**
+ * as defined in Appendix D
+ * https://tools.ietf.org/html/draft-ietf-cbor-cddl-08#appendix-D
+ */
+export const PREDEFINED_IDENTIFIER = [
+    'any', 'uint', 'nint', 'int', 'bstr', 'bytes', 'tstr', 'text',
+    'tdate', 'time', 'number', 'biguint', 'bignint', 'bigint',
+    'integer', 'unsigned', 'decfrac', 'bigfloat', 'eb64url',
+    'eb64legacy', 'eb16', 'encoded-cbor', 'uri', 'b64url',
+    'b64legacy', 'regexp', 'mime-message', 'cbor-any', 'float16',
+    'float32', 'float64', 'float16-32', 'float32-64', 'float',
+    'false', 'true', 'bool', 'nil', 'null', 'undefined'
+]

package/src/index.ts

@@ -0,0 +1,11 @@
+import Lexer from './lexer.js'
+import Parser from './parser.js'
+
+export function parse (filePath: string) {
+    const parser = new Parser(filePath)
+    return parser.parse()
+}
+
+export default { parse }
+export { Lexer, Parser }
+export * from './ast.js'

package/src/lexer.ts

@@ -0,0 +1,238 @@
+import { Token, Tokens } from './tokens.js';
+import { isLetter, isAlphabeticCharacter, isDigit, hasSpecialNumberCharacter } from './utils.js'
+import { WHITESPACE_CHARACTERS } from './constants.js';
+
+export default class Lexer {
+    input: string
+    position: number = 0
+    readPosition: number = 0
+    ch: number = 0
+
+    constructor (source: string) {
+        this.input = source
+
+        this.readChar()
+    }
+
+    private readChar (): void {
+        if (this.readPosition >= this.input.length) {
+            this.ch = 0
+        } else {
+            this.ch = this.input[this.readPosition].charCodeAt(0)
+        }
+        this.position = this.readPosition
+        this.readPosition++
+    }
+
+    getLocation () {
+        const position = this.position - 2
+        const sourceLines = this.input.split('\n')
+        const sourceLineLength = sourceLines.map((l) => l.length)
+        let i = 0
+
+        for (const [line, lineLength] of Object.entries(sourceLineLength)) {
+            i += lineLength + 1
+            if (i > position) {
+                const lineBegin = i - lineLength
+                return {
+                    line: parseInt(line, 10),
+                    position: position - lineBegin + 1
+                }
+            }
+        }
+
+        return { line: 0, position: 0 }
+    }
+
+    getLine (lineNumber: number) {
+        return this.input.split('\n')[lineNumber]
+    }
+
+    getLocationInfo () {
+        const loc = this.getLocation()
+        const line = loc ? this.getLine(loc.line) : ''
+        let locationInfo = line + '\n'
+        locationInfo += ' '.repeat(loc?.position || 0) + '^\n'
+        locationInfo += ' '.repeat(loc?.position || 0) + '|\n'
+        return locationInfo
+    }
+
+    nextToken (): Token {
+        let token: Token
+        this.skipWhitespace()
+
+        const Literal = String.fromCharCode(this.ch)
+        switch (this.ch) {
+            case '='.charCodeAt(0):
+                token = { Type: Tokens.ASSIGN, Literal }
+                break
+            case '('.charCodeAt(0):
+                token = { Type: Tokens.LPAREN, Literal }
+                break
+            case ')'.charCodeAt(0):
+                token = { Type: Tokens.RPAREN, Literal }
+                break
+            case '{'.charCodeAt(0):
+                token = { Type: Tokens.LBRACE, Literal }
+                break
+            case '}'.charCodeAt(0):
+                token = { Type: Tokens.RBRACE, Literal }
+                break
+            case '['.charCodeAt(0):
+                token = { Type: Tokens.LBRACK, Literal }
+                break
+            case ']'.charCodeAt(0):
+                token = { Type: Tokens.RBRACK, Literal }
+                break
+            case '<'.charCodeAt(0):
+                token = { Type: Tokens.LT, Literal }
+                break
+            case '>'.charCodeAt(0):
+                token = { Type: Tokens.GT, Literal }
+                break
+            case '+'.charCodeAt(0):
+                token = { Type: Tokens.PLUS, Literal }
+                break
+            case ','.charCodeAt(0):
+                token = { Type: Tokens.COMMA, Literal }
+                break
+            case '.'.charCodeAt(0):
+                token = { Type: Tokens.DOT, Literal }
+                break
+            case ':'.charCodeAt(0):
+                token = { Type: Tokens.COLON, Literal }
+                break
+            case '?'.charCodeAt(0):
+                token = { Type: Tokens.QUEST, Literal }
+                break
+            case '/'.charCodeAt(0):
+                token = { Type: Tokens.SLASH, Literal }
+                break
+            case '*'.charCodeAt(0):
+                token = { Type: Tokens.ASTERISK, Literal }
+                break
+            case '^'.charCodeAt(0):
+                token = { Type: Tokens.CARET, Literal }
+                break
+            case '#'.charCodeAt(0):
+                token = { Type: Tokens.HASH, Literal }
+                break
+            case '~'.charCodeAt(0):
+                token = { Type: Tokens.TILDE, Literal }
+                break
+            case '"'.charCodeAt(0):
+                token = { Type: Tokens.STRING, Literal: this.readString() }
+                break
+            case ';'.charCodeAt(0):
+                token = { Type: Tokens.COMMENT, Literal: this.readComment() }
+                break
+            case 0:
+                token = { Type: Tokens.EOF, Literal: '' }
+                break
+            default: {
+                if (isAlphabeticCharacter(Literal)) {
+                    return { Type: Tokens.IDENT, Literal: this.readIdentifier() }
+                } else if (
+                    // positive number
+                    isDigit(Literal) ||
+                    // negative number
+                    (this.ch === Tokens.MINUS.charCodeAt(0) && isDigit(this.input[this.readPosition]))
+                ) {
+                    const numberOrFloat = this.readNumberOrFloat()
+                    return {
+                        Type: numberOrFloat.includes(Tokens.DOT) ? Tokens.FLOAT : Tokens.NUMBER,
+                        Literal: numberOrFloat
+                    }
+                }
+                token = { Type: Tokens.ILLEGAL, Literal: '' }
+            }
+        }
+
+        this.readChar()
+        return token
+    }
+
+    private readIdentifier (): string {
+        const position = this.position
+
+        /**
+         * an identifier can contain
+         * see https://tools.ietf.org/html/draft-ietf-cbor-cddl-08#section-3.1
+         */
+        while (
+            // a letter (a-z, A-Z)
+            isLetter(String.fromCharCode(this.ch)) ||
+            // a digit (0-9)
+            isDigit(String.fromCharCode(this.ch)) ||
+            // and special characters (-, _, @, ., $)
+            [
+                Tokens.MINUS.charCodeAt(0),
+                Tokens.UNDERSCORE.charCodeAt(0),
+                Tokens.ATSIGN.charCodeAt(0),
+                Tokens.DOT.charCodeAt(0),
+                Tokens.DOLLAR.charCodeAt(0)
+            ].includes(this.ch)
+        ) {
+            this.readChar()
+        }
+
+        return this.input.slice(position, this.position)
+    }
+
+    private readComment (): string {
+        const position = this.position
+
+        while (this.ch && String.fromCharCode(this.ch) !== '\n') {
+            this.readChar()
+        }
+
+        return this.input.slice(position, this.position).trim()
+    }
+
+    private readString (): string {
+        const position = this.position
+
+        this.readChar() // eat "
+        while (this.ch && String.fromCharCode(this.ch) !== Tokens.QUOT) {
+            this.readChar() // eat any character until "
+        }
+
+        return this.input.slice(position + 1, this.position).trim()
+    }
+
+    private readNumberOrFloat (): string {
+        const position = this.position
+        let foundSpecialCharacter = false
+
+        /**
+         * a number of float can contain
+         */
+        while (
+            // a number
+            isDigit(String.fromCharCode(this.ch)) ||
+            // a special character, e.g. ".", "x" and "b"
+            hasSpecialNumberCharacter(this.ch)
+        ) {
+            /**
+             * ensure we respect ranges, e.g. 0..10
+             * so break after the second dot and adjust read position
+             */
+            if (hasSpecialNumberCharacter(this.ch) && foundSpecialCharacter) {
+                this.position--
+                this.readPosition--
+                break
+            }
+
+            foundSpecialCharacter = hasSpecialNumberCharacter(this.ch)
+            this.readChar() // eat any character until a non digit or a 2nd dot
+        }
+
+        return this.input.slice(position, this.position).trim()
+    }
+
+    private skipWhitespace () {
+        while (WHITESPACE_CHARACTERS.includes(String.fromCharCode(this.ch))) {
+            this.readChar()
+        }
+    }
+}