cddl2ts 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Christian Bromann<mail@bromann.dev>
+
+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,62 @@
+CDDL to TypeScript ![Test](https://github.com/christian-bromann/cddl/workflows/Test/badge.svg?branch=master)
+==================
+
+> A Node.js package that can generate a TypeScript definition based on a CDDL file
+
+CDDL expresses Concise Binary Object Representation (CBOR) data structures ([RFC 7049](https://tools.ietf.org/html/rfc7049)). Its main goal is to provide an easy and unambiguous way to express structures for protocol messages and data formats that use CBOR or JSON. This package allows you to transform a CDDL file into a TypeScript interface that you can use for other TypeScript project.
+
+Related projects:
+- [christian-bromann/cddl](https://github.com/christian-bromann/cddl): parses CDDL into an AST
+
+## Install
+
+To install this package run:
+
+```sh
+$ npm install cddl2ts
+```
+
+## Using this package
+
+This package exposes a CLI as well as a programmatic interface for transforming CDDL into TypeScript.
+
+### CLI
+
+```sh
+npx cddl2ts ./path/to/interface.cddl &> ./path/to/interface.ts
+```
+
+### Programmatic Interface
+
+The module exports a `transform` method that takes an CDDL AST object and returns a TypeScript definition as `string`, e.g.:
+
+```js
+import { transform } from 'cddl2ts'
+
+/**
+ * spec.cddl:
+ *
+ * session.CapabilityRequest = {
+ *   ?acceptInsecureCerts: bool,
+ *   ?browserName: text,
+ *   ?browserVersion: text,
+ *   ?platformName: text,
+ * };
+ */
+const ts = transform('./spec.cddl')
+console.log(ts)
+/**
+ * outputs:
+ *
+ * interface SessionCapabilityRequest {
+ *   acceptInsecureCerts?: boolean,
+ *   browserName?: string,
+ *   browserVersion?: string,
+ *   platformName?: string,
+ * }
+ */
+```
+
+---
+
+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/cddl2ts/blob/master/CONTRIBUTING.md) to get started.

package/bin/cddl2ts.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import parse from '../build/cli.js'
+
+if (process.env.NODE_ENV == null) {
+    process.env.NODE_ENV = 'test'
+}
+
+parse()

package/build/cli.d.ts

@@ -0,0 +1,2 @@
+export default function cli(args?: string[]): Promise<undefined>;
+//# sourceMappingURL=cli.d.ts.map

package/build/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAmBA,wBAA8B,GAAG,CAAE,IAAI,WAAwB,sBAmB9D"}

package/build/cli.js

@@ -0,0 +1,33 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { parse } from 'cddl';
+import { transform } from './index.js';
+import { pkg } from './constants.js';
+const HELP = `
+${pkg.name}
+${pkg.description}
+
+Usage:
+runme2ts ./path/to/spec.cddl &> ./path/to/interface.ts
+
+v${pkg.version}
+Copyright ${(new Date()).getFullYear()} ${pkg.author}
+`;
+export default async function cli(args = process.argv.slice(2)) {
+    if (args.includes('--help') || args.length === 0) {
+        console.log(HELP);
+        return process.exit(0);
+    }
+    if (args.includes('--version') || args.includes('-v')) {
+        console.log(pkg.version);
+        return process.exit(0);
+    }
+    const absoluteFilePath = path.resolve(process.cwd(), args[0]);
+    const hasAccess = await fs.access(absoluteFilePath).then(() => true, () => false);
+    if (!hasAccess) {
+        console.error(`Couldn't find or access source CDDL file at "${absoluteFilePath}"`);
+        return process.exit(1);
+    }
+    const ast = parse(absoluteFilePath);
+    console.log(transform(ast));
+}

package/build/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const pkg: any;
+//# sourceMappingURL=constants.d.ts.map

package/build/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,GAAG,KAAqF,CAAA"}

package/build/constants.js

@@ -0,0 +1,5 @@
+import fs from 'node:fs/promises';
+import url from 'node:url';
+import path from 'node:path';
+const __dirname = url.fileURLToPath(new URL('.', import.meta.url));
+export const pkg = JSON.parse(await fs.readFile(path.join(__dirname, '..', 'package.json'), 'utf-8'));

package/build/index.d.ts

@@ -0,0 +1,3 @@
+import type { Assignment } from 'cddl';
+export declare function transform(assignments: Assignment[]): string;
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAmG,MAAM,MAAM,CAAA;AAqBvI,wBAAgB,SAAS,CAAE,WAAW,EAAE,UAAU,EAAE,UAkBnD"}

package/build/index.js

@@ -0,0 +1,200 @@
+import camelcase from 'camelcase';
+import { parse, print, types } from 'recast';
+import typescriptParser from 'recast/parsers/typescript.js';
+import { pkg } from './constants.js';
+const b = types.builders;
+const NATIVE_TYPES = {
+    number: b.tsNumberKeyword(),
+    float: b.tsNumberKeyword(),
+    uint: b.tsNumberKeyword(),
+    bool: b.tsBooleanKeyword(),
+    str: b.tsStringKeyword(),
+    text: b.tsStringKeyword(),
+    tstr: b.tsStringKeyword(),
+    range: b.tsNumberKeyword(),
+    nil: b.tsNullKeyword(),
+    null: b.tsNullKeyword()
+};
+export function transform(assignments) {
+    let ast = parse(`// compiled with https://www.npmjs.com/package/cddl2ts v${pkg.version}`, {
+        parser: typescriptParser,
+        sourceFileName: 'cddl2Ts.ts',
+        sourceRoot: process.cwd()
+    });
+    for (const assignment of assignments) {
+        const statement = parseAssignment(ast, assignment);
+        if (!statement) {
+            continue;
+        }
+        ast.program.body.push(statement);
+    }
+    return print(ast).code;
+}
+function parseAssignment(ast, assignment) {
+    if (assignment.Type === 'variable') {
+        const propType = Array.isArray(assignment.PropertyType)
+            ? assignment.PropertyType
+            : [assignment.PropertyType];
+        const id = b.identifier(camelcase(assignment.Name, { pascalCase: true }));
+        let typeParameters;
+        // @ts-expect-error e.g. "js-int = -9007199254740991..9007199254740991"
+        if (propType.length === 1 && propType[0].Type === 'range') {
+            typeParameters = b.tsNumberKeyword();
+        }
+        else {
+            typeParameters = b.tsUnionType(propType.map(parsePropertyType));
+        }
+        const expr = b.tsTypeAliasDeclaration(id, typeParameters);
+        expr.comments = assignment.Comments.map((c) => b.commentLine(` ${c.Content}`, true));
+        return expr;
+    }
+    if (assignment.Type === 'group') {
+        const id = b.identifier(camelcase(assignment.Name, { pascalCase: true }));
+        const objectType = parseObjectType(assignment.Properties);
+        const extendInterfaces = assignment.Properties
+            .filter((prop) => prop.Name === '')
+            .map((prop) => b.tsExpressionWithTypeArguments(b.identifier(camelcase(prop.Type[0].Value, { pascalCase: true }))));
+        const expr = b.tsInterfaceDeclaration(id, b.tsInterfaceBody(objectType));
+        expr.extends = extendInterfaces;
+        expr.comments = assignment.Comments.map((c) => b.commentLine(` ${c.Content}`, true));
+        return expr;
+    }
+    if (assignment.Type === 'array') {
+        const id = b.identifier(camelcase(assignment.Name, { pascalCase: true }));
+        const firstType = assignment.Values[0].Type;
+        const obj = Array.isArray(firstType)
+            ? firstType.map(parseUnionType)
+            : firstType.Values
+                ? firstType.Values.map((val) => parseUnionType(val.Type[0]))
+                // ToDo(Christian): transpile this case correctly
+                : [];
+        const value = b.tsArrayType(b.tsParenthesizedType(b.tsUnionType(obj)));
+        const expr = b.tsTypeAliasDeclaration(id, value);
+        expr.comments = assignment.Comments.map((c) => b.commentLine(` ${c.Content}`, true));
+        return expr;
+    }
+    throw new Error(`Unknown assignment type "${assignment.Type}"`);
+}
+function parsePropertyType(propType) {
+    if (typeof propType === 'string') {
+        return b.tsStringKeyword();
+    }
+    if (propType.Type === 'group') {
+        return b.tsTypeReference(b.identifier(camelcase(propType.Value.toString(), { pascalCase: true })));
+    }
+    if (propType.Type === 'literal') {
+        return b.tsLiteralType(b.stringLiteral(propType.Value.toString()));
+    }
+    throw new Error(`Couldn't parse property type ${JSON.stringify(propType, null, 4)}`);
+}
+function parseObjectType(props) {
+    const propItems = [];
+    for (const prop of props) {
+        /**
+         * Empty groups like
+         * {
+         *   HasCut: false,
+         *   Occurrence: { n: 1, m: 1 },
+         *   Name: '',
+         *   Type: [ { Type: 'group', Value: 'Extensible', Unwrapped: false } ],
+         *   Comment: ''
+         * }
+         * are ignored and later added as interface extensions
+         */
+        if (prop.Name === '') {
+            continue;
+        }
+        const id = b.identifier(camelcase(prop.Name));
+        const cddlType = Array.isArray(prop.Type) ? prop.Type : [prop.Type];
+        const comments = prop.Comments.map((c) => ` ${c.Content}`);
+        if (prop.Operator && prop.Operator.Type === 'default') {
+            const defaultValue = parseDefaultValue(prop.Operator);
+            defaultValue && comments.length && comments.push(''); // add empty line if we have previous comments
+            defaultValue && comments.push(` @default ${defaultValue}`);
+        }
+        const type = cddlType.map((t) => {
+            const unionType = parseUnionType(t);
+            if (unionType) {
+                const defaultValue = parseDefaultValue(t.Operator);
+                defaultValue && comments.length && comments.push(''); // add empty line if we have previous comments
+                defaultValue && comments.push(` @default ${defaultValue}`);
+                return unionType;
+            }
+            throw new Error(`Couldn't parse property ${JSON.stringify(t)}`);
+        });
+        const typeAnnotation = b.tsTypeAnnotation(b.tsUnionType(type));
+        const isOptional = prop.Occurrence.n === 0;
+        const propSignature = b.tsPropertySignature(id, typeAnnotation, isOptional);
+        propSignature.comments = comments.length ? [b.commentBlock(`*\n *${comments.join('\n *')}\n `)] : [];
+        propItems.push(propSignature);
+    }
+    return propItems;
+}
+function parseUnionType(t) {
+    if (typeof t === 'string') {
+        if (!NATIVE_TYPES[t]) {
+            throw new Error(`Unknown native type: "${t}`);
+        }
+        return NATIVE_TYPES[t];
+    }
+    else if (NATIVE_TYPES[t.Type]) {
+        return NATIVE_TYPES[t.Type];
+    }
+    else if (t.Value === 'null') {
+        return b.tsNullKeyword();
+    }
+    else if (t.Type === 'group') {
+        const value = t.Value;
+        /**
+         * check if we have
+         * ?attributes: {*text => text},
+         */
+        if (!value && t.Properties) {
+            return b.tsTypeLiteral(parseObjectType(t.Properties));
+        }
+        return b.tsTypeReference(b.identifier(camelcase(value.toString(), { pascalCase: true })));
+    }
+    else if (t.Type === 'literal' && typeof t.Value === 'string') {
+        return b.tsLiteralType(b.stringLiteral(t.Value));
+    }
+    else if (t.Type === 'literal' && typeof t.Value === 'number') {
+        return b.tsLiteralType(b.numericLiteral(t.Value));
+    }
+    else if (t.Type === 'array') {
+        const types = t.Values[0].Type;
+        const typedTypes = (Array.isArray(types) ? types : [types]).map((val) => {
+            return typeof val === 'string' && NATIVE_TYPES[val]
+                ? NATIVE_TYPES[val]
+                : b.tsTypeReference(b.identifier(camelcase(val.Value, { pascalCase: true })));
+        });
+        return b.tsArrayType(typedTypes.length > 1
+            ? b.tsParenthesizedType(b.tsUnionType(typedTypes))
+            : b.tsUnionType(typedTypes));
+    }
+    else if (typeof t.Type === 'object' && t.Type.Type === 'range') {
+        return b.tsNumberKeyword();
+    }
+    else if (typeof t.Type === 'object' && t.Type.Type === 'group') {
+        /**
+         * e.g. ?pointerType: input.PointerType .default "mouse"
+         */
+        const referenceValue = camelcase(t.Type.Value, { pascalCase: true });
+        return b.tsTypeReference(b.identifier(referenceValue));
+    }
+    throw new Error(`Unknown union type: ${JSON.stringify(t)}`);
+}
+function parseDefaultValue(operator) {
+    if (!operator || operator.Type !== 'default') {
+        return;
+    }
+    const operatorValue = operator.Value;
+    if (operator.Value === 'null') {
+        return operator.Value;
+    }
+    if (operatorValue.Type !== 'literal') {
+        throw new Error(`Can't parse operator default value of ${JSON.stringify(operator)}`);
+    }
+    return typeof operatorValue.Value === 'string'
+        ? `'${operatorValue.Value}'`
+        : operatorValue.Value;
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "cddl2ts",
+  "version": "0.1.0",
+  "description": "A Node.js package that can generate a TypeScript definition based on a CDDL file",
+  "author": "Christian Bromann <mail@bromann.dev>",
+  "license": "MIT",
+  "homepage": "https://github.com/christian-bromann/cddl2ts#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/christian-bromann/cddl2ts.git"
+  },
+  "keywords": [
+    "cddl"
+  ],
+  "bugs": {
+    "url": "https://github.com/christian-bromann/cddl2ts/issues"
+  },
+  "type": "module",
+  "exports": "./build/index.js",
+  "bin": {
+    "cddl2ts": "./bin/cddl2ts.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",
+    "watch": "tsc --watch"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.1",
+    "@types/node": "^20.2.3",
+    "@vitest/coverage-c8": "^0.31.1",
+    "npm-run-all": "^4.1.5",
+    "release-it": "^15.10.3",
+    "typescript": "^5.0.4",
+    "vitest": "^0.31.1"
+  },
+  "dependencies": {
+    "@babel/parser": "^7.21.9",
+    "camelcase": "^7.0.1",
+    "cddl": "^0.8.3",
+    "recast": "^0.23.2",
+    "yargs": "^17.7.2"
+  }
+}