initial jsdoc support

mapbox · Aug 12, 2024 · 29a022c · 29a022c
1 parent 5e17dd5
commit 29a022c
Show file tree

Hide file tree

Showing 20 changed files with 826 additions and 26 deletions.
diff --git a/bin/pbf b/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
 });
 

diff --git a/compile.js b/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,30 @@ function writeContext(ctx, options) {
 }
 
 function writeMessage(ctx, options) {
+    const name = ctx._name;
     const fields = ctx._proto.fields;
 
     let code = '\n';
 
+    if (options.jsDoc) {
+        code += compileObjectType(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) {
+            code += ['\n/**', ' * @param {number} tag', ` * @param {${name}} 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 +79,12 @@ function ${readName}Field(tag, obj, pbf) {
     }
 
     if (!options.noWrite) {
-        const writeName = `write${ctx._name}`;
+        const writeName = `write${name}`;
+
+        if (options.jsDoc) {
+            code += ['\n/**', ` * @param {${name}} obj`, ' * @param {Pbf} pbf', ' */'].join('\n').concat('\n');
+        }
+
         code += `${writeFunctionExport(options, writeName)}function ${writeName}(obj, pbf) {\n`;
         for (const field of fields) {
             const writeCode =
@@ -90,7 +114,10 @@ function getEnumValues(ctx) {
 function writeEnum(ctx, {legacy}) {
     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 output = '\n/** @enum {number} */';
+    output += `\n${legacy ? `const ${name} = exports.${name}` : `export const ${name}`} = ${enums};\n`;
+    return output;
 }
 
 function compileDest(ctx) {
@@ -114,23 +141,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;
 }
@@ -415,3 +446,63 @@ function getDefaultWriteTest(ctx, field) {
 function isPacked(field) {
     return field.options.packed === 'true';
 }
+
+/**
+ * @param {{type: string}} field
+ * @returns {string}
+ */
+function getTypeScriptType(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;
+}
+
+/**
+ * @param {string} type
+ * @param {string} name
+ * @param {{name: string; type: string; required: boolean}} [fields]
+ * @returns {string}
+ */
+function typeDef(type, name, fields = []) {
+    const oneofs = {};
+
+    const properties = fields.map((field) => {
+        if (field.oneof) {
+            oneofs[field.oneof] = oneofs[field.oneof] || [];
+            oneofs[field.oneof].push(field.name);
+        }
+
+        const type = getTypeScriptType(field);
+        const name = (field.required || field.repeated) ? field.name : `[${field.name}]`;
+        return ` * @property {${type}} ${name}`;
+    });
+
+    for (const oneof in oneofs) {
+        const subtypes = oneofs[oneof].map(s => `${name}["${s}"]`).join(' | ');
+        properties.push(` * @property {${subtypes}} ${oneof}`);
+    }
+
+    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 compileObjectType(ctx, name, fields = []) {
+    const typedFields = fields.map((field) => {
+        const type = getType(ctx, field);
+        return {...field, type: type ? type._name : field.type};
+    });
+
+    return typeDef('object', name, typedFields);
+}
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/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 --allowJs --checkJs --noEmit --isolatedModules test/fixtures/*.js",
     "cov": "node --test --experimental-test-covetage",
     "build": "rollup -c",
     "prepublishOnly": "npm run test && npm run build"
@@ -60,5 +60,8 @@
     "rollup": "^4.18.0",
     "tile-stats-runner": "^1.0.0",
     "typescript": "^5.5.3"
-  }
+  },
+  "workspaces": [
+    "test/typescript/"
+  ]
 }
diff --git a/test/compile.test.js b/test/compile.test.js
@@ -10,9 +10,9 @@ test('compiles all proto files to proper js', () => {
     const files = fs.readdirSync(new URL('fixtures', import.meta.url));
 
     for (const path of files) {
-        if (!path.endsWith('.proto')) continue;
+        if (!path.endsWith('oneof.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);

diff --git a/test/fixtures/defaults.js b/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);

diff --git a/test/fixtures/defaults_implicit.js b/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);