jsdoc support

Author: stepankuzmin

bin/pbf

@@ -4,13 +4,14 @@ import resolve from 'resolve-protobuf-schema';
 import {compileRaw} from '../compile.js';
 
 if (process.argv.length < 3) {
-    console.error('Usage: pbf [file.proto] [--no-read] [--no-write] [--legacy]');
+    console.error('Usage: pbf [file.proto] [--no-read] [--no-write] [--jsdoc] [--legacy]');
     process.exit(0);
 }
 
 const code = compileRaw(resolve.sync(process.argv[2]), {
     noRead: process.argv.indexOf('--no-read') >= 0,
     noWrite: process.argv.indexOf('--no-write') >= 0,
+    jsDoc: process.argv.indexOf('--jsdoc') >= 0,
     legacy: process.argv.indexOf('--legacy') >= 0
 });
 

compile.js

@@ -9,7 +9,13 @@ export function compile(proto) {
 
 export function compileRaw(proto, options = {}) {
     const context = buildDefaults(buildContext(proto, null), proto.syntax);
-    return `${options.dev ? '' : `// code generated by pbf v${version}\n`}${writeContext(context, options)}`;
+
+    let output = options.dev ? '' : `// code generated by pbf v${version}\n`;
+    if (options.jsDoc) {
+        output += typeDef(`import("${options.dev ? '../../index.js' : 'pbf'}").default`, 'Pbf');
+    }
+    output += writeContext(context, options);
+    return output;
 }
 
 function writeContext(ctx, options) {
@@ -24,17 +30,35 @@ function writeContext(ctx, options) {
 }
 
 function writeMessage(ctx, options) {
+    const name = ctx._name;
     const fields = ctx._proto.fields;
 
     let code = '\n';
 
+    if (options.jsDoc) {
+        code += compileType(ctx, name, fields);
+    }
+
     if (!options.noRead) {
-        const readName = `read${ctx._name}`;
+        const readName = `read${name}`;
+        if (options.jsDoc) {
+            code += ['\n/**', ' * @param {Pbf} pbf', ' * @param {number} [end]', ` * @returns {${name}}`, ' */'].join('\n').concat('\n');
+        }
         code +=
 `${writeFunctionExport(options, readName)}function ${readName}(pbf, end) {
     return pbf.readFields(${readName}Field, ${compileDest(ctx)}, end);
-}
-function ${readName}Field(tag, obj, pbf) {
+}\n`;
+
+        if (options.jsDoc) {
+            let param = name;
+            if (ctx._proto.map) {
+                const {key, value} = getMapTsType(fields);
+                param = `{key: ${key}; value: ${value}}`;
+            }
+            code += ['\n/**', ' * @param {number} tag', ` * @param {${param}} obj`, ' * @param {Pbf} pbf', ' */'].join('\n').concat('\n');
+        }
+        code +=
+`function ${readName}Field(tag, obj, pbf) {
 `;
         for (let i = 0; i < fields.length; i++) {
             const field = fields[i];
@@ -60,7 +84,18 @@ function ${readName}Field(tag, obj, pbf) {
     }
 
     if (!options.noWrite) {
-        const writeName = `write${ctx._name}`;
+        const writeName = `write${name}`;
+
+        if (options.jsDoc) {
+            let param = name;
+            if (ctx._proto.map) {
+                const {key, value} = getMapTsType(fields);
+                param = `{key: ${key}; value: ${value}}`;
+            }
+
+            code += ['\n/**', ` * @param {${param}} obj`, ' * @param {Pbf} pbf', ' */'].join('\n').concat('\n');
+        }
+
         code += `${writeFunctionExport(options, writeName)}function ${writeName}(obj, pbf) {\n`;
         for (const field of fields) {
             const writeCode =
@@ -87,10 +122,17 @@ function getEnumValues(ctx) {
     return enums;
 }
 
-function writeEnum(ctx, {legacy}) {
+function writeEnum(ctx, options) {
     const enums = JSON.stringify(getEnumValues(ctx), null, 4);
     const name = ctx._name;
-    return `\n${legacy ? `const ${name} = exports.${name}` : `export const ${name}`} = ${enums};\n`;
+
+    let code = '\n';
+    if (options.jsDoc) {
+        code = '\n/** @enum {number} */\n';
+    }
+
+    code += `${options.legacy ? `const ${name} = exports.${name}` : `export const ${name}`} = ${enums};\n`;
+    return code;
 }
 
 function compileDest(ctx) {
@@ -114,23 +156,27 @@ function getType(ctx, field) {
     return path.reduce((ctx, name) => ctx && ctx[name], ctx);
 }
 
+function fieldTypeIsNumber(field) {
+    switch (field.type) {
+    case 'float':
+    case 'double':
+    case 'uint32':
+    case 'uint64':
+    case 'int32':
+    case 'int64':
+    case 'sint32':
+    case 'sint64':
+    case 'fixed32':
+    case 'fixed64':
+    case 'sfixed32':
+    case 'sfixed64': return true;
+    default: return false;
+    }
+}
+
 function fieldShouldUseStringAsNumber(field) {
     if (field.options.jstype === 'JS_STRING') {
-        switch (field.type) {
-        case 'float':
-        case 'double':
-        case 'uint32':
-        case 'uint64':
-        case 'int32':
-        case 'int64':
-        case 'sint32':
-        case 'sint64':
-        case 'fixed32':
-        case 'fixed64':
-        case 'sfixed32':
-        case 'sfixed64': return true;
-        default:         return false;
-        }
+        return fieldTypeIsNumber(field);
     }
     return false;
 }
@@ -256,6 +302,7 @@ function getMapMessage(field) {
     return {
         name: getMapMessageName(field.tag),
         enums: [],
+        map: true,
         messages: [],
         extensions: null,
         fields: [
@@ -415,3 +462,72 @@ function getDefaultWriteTest(ctx, field) {
 function isPacked(field) {
     return field.options.packed === 'true';
 }
+
+function getTsType(field) {
+    let type = field.type;
+
+    if (fieldShouldUseStringAsNumber(field)) type = 'string';
+    else if (fieldTypeIsNumber(field)) type = 'number';
+    else if (field.type === 'bytes') type = 'Uint8Array';
+    else if (field.type === 'bool') type = 'boolean';
+
+    return field.repeated ? `Array<${type}>` : type;
+}
+
+function getMapTsType(fields) {
+    const key = getTsType(fields[0]);
+    const value = getTsType(fields[1]);
+    return {key, value};
+}
+
+/**
+ * @param {string} type
+ * @param {string} name
+ * @param {{name: string; type: string; required: boolean}} [fields]
+ * @returns {string}
+ */
+function typeDef(type, name, fields = []) {
+    const unionProperties = {};
+    const properties = fields.map((field) => {
+        if (field.oneof) {
+            unionProperties[field.oneof] = unionProperties[field.oneof] || [];
+            unionProperties[field.oneof].push(field.name);
+        }
+
+        const type = getTsType(field);
+        const isRequired = field.required || field.repeated || field.map;
+
+        const name = isRequired ? field.name : `[${field.name}]`;
+
+        return ` * @property {${type}} ${name}`;
+    });
+
+    for (const prop in unionProperties) {
+        const union = unionProperties[prop].map(s => `"${s}"`).join(' | ');
+        properties.push(` * @property {${union}} [${prop}]`);
+    }
+
+    return ['/**', ` * @typedef {${type}} ${name}`, ...properties, ' */']
+        .join('\n')
+        .concat('\n');
+}
+
+/**
+ * @param {object} ctx
+ * @param {string} name
+ * @param {{name: string; type: string; required: boolean}} [fields]
+ * @returns {string}
+ */
+function compileType(ctx, name, fields = []) {
+    if (ctx._proto.map) {
+        const {key, value} = getMapTsType(fields);
+        return typeDef(`Object<${key}, ${value}>`, name, []);
+    }
+
+    const typedFields = fields.map((field) => {
+        const type = getType(ctx, field);
+        return {...field, type: type ? type._name : field.type};
+    });
+
+    return typeDef('object', name, typedFields);
+}

package.json

@@ -11,7 +11,7 @@
   "scripts": {
     "bench": "node bench/bench.js",
     "pretest": "eslint *.js compile.js test/*.js test/fixtures/*.js bin/pbf",
-    "test": "tsc && node --test",
+    "test": "tsc && node --test && tsc --project tsconfig.test.json",
     "cov": "node --test --experimental-test-covetage",
     "build": "rollup -c",
     "prepublishOnly": "npm run test && npm run build"

test/compile.test.js

@@ -12,7 +12,7 @@ test('compiles all proto files to proper js', () => {
     for (const path of files) {
         if (!path.endsWith('.proto')) continue;
         const proto = resolve(new URL(`fixtures/${path}`, import.meta.url));
-        const js = compileRaw(proto, {dev: true});
+        const js = compileRaw(proto, {dev: true, jsDoc: true});
 
         // uncomment to update the fixtures
         // fs.writeFileSync(new URL(`fixtures/${path}`.replace('.proto', '.js'), import.meta.url), js);

test/fixtures/defaults.js

@@ -1,19 +1,48 @@
+/**
+ * @typedef {import("../../index.js").default} Pbf
+ */
 
+/** @enum {number} */
 export const MessageType = {
     "UNKNOWN": 0,
     "GREETING": 1
 };
 
+/**
+ * @typedef {object} Envelope
+ * @property {MessageType} [type]
+ * @property {string} [name]
+ * @property {boolean} [flag]
+ * @property {number} [weight]
+ * @property {number} [id]
+ */
+
+/**
+ * @param {Pbf} pbf
+ * @param {number} [end]
+ * @returns {Envelope}
+ */
 export function readEnvelope(pbf, end) {
     return pbf.readFields(readEnvelopeField, {type: 1, name: "test", flag: true, weight: 1.5, id: 1}, end);
 }
+
+/**
+ * @param {number} tag
+ * @param {Envelope} obj
+ * @param {Pbf} pbf
+ */
 function readEnvelopeField(tag, obj, pbf) {
     if (tag === 1) obj.type = pbf.readVarint();
     else if (tag === 2) obj.name = pbf.readString();
     else if (tag === 3) obj.flag = pbf.readBoolean();
     else if (tag === 4) obj.weight = pbf.readFloat();
     else if (tag === 5) obj.id = pbf.readVarint(true);
 }
+
+/**
+ * @param {Envelope} obj
+ * @param {Pbf} pbf
+ */
 export function writeEnvelope(obj, pbf) {
     if (obj.type != null && obj.type !== 1) pbf.writeVarintField(1, obj.type);
     if (obj.name != null && obj.name !== "test") pbf.writeStringField(2, obj.name);

test/fixtures/defaults_implicit.js

@@ -1,20 +1,69 @@
+/**
+ * @typedef {import("../../index.js").default} Pbf
+ */
 
+/** @enum {number} */
 export const MessageType = {
     "UNKNOWN": 0,
     "GREETING": 1
 };
 
+/**
+ * @typedef {object} CustomType
+ */
+
+/**
+ * @param {Pbf} pbf
+ * @param {number} [end]
+ * @returns {CustomType}
+ */
 export function readCustomType(pbf, end) {
     return pbf.readFields(readCustomTypeField, {}, end);
 }
+
+/**
+ * @param {number} tag
+ * @param {CustomType} obj
+ * @param {Pbf} pbf
+ */
 function readCustomTypeField(tag, obj, pbf) {
 }
+
+/**
+ * @param {CustomType} obj
+ * @param {Pbf} pbf
+ */
 export function writeCustomType(obj, pbf) {
 }
 
+/**
+ * @typedef {object} Envelope
+ * @property {MessageType} [type]
+ * @property {string} [name]
+ * @property {boolean} [flag]
+ * @property {number} [weight]
+ * @property {number} [id]
+ * @property {Array<string>} tags
+ * @property {Array<number>} numbers
+ * @property {Uint8Array} [bytes]
+ * @property {CustomType} [custom]
+ * @property {Array<MessageType>} types
+ */
+
+/**
+ * @param {Pbf} pbf
+ * @param {number} [end]
+ * @returns {Envelope}
+ */
 export function readEnvelope(pbf, end) {
     return pbf.readFields(readEnvelopeField, {type: 0, name: "", flag: false, weight: 0, id: 0, tags: [], numbers: [], bytes: undefined, custom: undefined, types: []}, end);
 }
+
+/**
+ * @param {number} tag
+ * @param {Envelope} obj
+ * @param {Pbf} pbf
+ */
 function readEnvelopeField(tag, obj, pbf) {
     if (tag === 1) obj.type = pbf.readVarint();
     else if (tag === 2) obj.name = pbf.readString();
@@ -27,6 +76,11 @@ function readEnvelopeField(tag, obj, pbf) {
     else if (tag === 9) obj.custom = readCustomType(pbf, pbf.readVarint() + pbf.pos);
     else if (tag === 10) pbf.readPackedVarint(obj.types);
 }
+
+/**
+ * @param {Envelope} obj
+ * @param {Pbf} pbf
+ */
 export function writeEnvelope(obj, pbf) {
     if (obj.type) pbf.writeVarintField(1, obj.type);
     if (obj.name) pbf.writeStringField(2, obj.name);