diff --git a/docgen/generate-docs.js b/docgen/generate-docs.js index bc04538bfb..b7f7e33b51 100644 --- a/docgen/generate-docs.js +++ b/docgen/generate-docs.js @@ -25,10 +25,39 @@ const yaml = require('js-yaml'); const repoPath = path.resolve(`${__dirname}/..`); +// The following files do not belong in any namespace, for example: +// https://firebase.google.com/docs/reference/admin/node/TopicMessage +const noNamespace = [ + 'topicmessage.html', + 'tokenmessage.html', + 'conditionmessage.html' +]; + +// We determine if auto-type generation is turned on, and provide per-service +// paths to TypeDoc (as nested wildcard /lib/**/*.d.ts does not work). +// Note: The d.ts files need to be generated beforehand, using `npm run build` +// in order to refresh the typings. This is not needed normally because the +// src files would be inspected instead of lib. +const autoGeneratedTypingsEnabled = process.env.TYPE_GENERATION_MODE === 'auto'; +const generatedFiles = [ + `${repoPath}/lib/*.d.ts`, + `${repoPath}/lib/database/*.d.ts`, + `${repoPath}/lib/firestore/*.d.ts`, + `${repoPath}/lib/instance-id/*.d.ts`, + `${repoPath}/lib/messaging/*.d.ts`, + `${repoPath}/lib/project-management/*.d.ts`, + `${repoPath}/lib/remote-config/*.d.ts`, + `${repoPath}/lib/security-rules/*.d.ts`, +]; +let filenameIndex = {}; // global filenameIndex, used to remap files and links + +const defaultFiles = autoGeneratedTypingsEnabled ? + generatedFiles.join(' ') : `${repoPath}/src/*.d.ts`; + // Command-line options. const { source: sourceFile } = yargs .option('source', { - default: `${repoPath}/src/*.d.ts`, + default: defaultFiles, describe: 'Typescript source file(s)', type: 'string' }) @@ -40,16 +69,23 @@ const contentPath = path.resolve(`${__dirname}/content-sources/node`); const tempHomePath = path.resolve(`${contentPath}/HOME_TEMP.md`); const devsitePath = `/docs/reference/admin/node/`; +// Custom logic for 3rd party re-exported packages. const firestoreExcludes = ['v1', 'v1beta1', 'setLogFunction','DocumentData']; +const databaseExcludes = ['enableLogging', 'EventType']; + const firestoreHtmlPath = `${docPath}/admin.firestore.html`; -const firestoreHeader = ` +const databaseHtmlPath = `${docPath}/admin.database.html`; +const thirdPartyFooter = '\n \n\n'; + +function generateThirdPartyHeader(packageName) { + return ` Type aliases - Following types are defined in the @google-cloud/firestore package + Following types are defined in the ${packageName} package and re-exported from this namespace for convenience. `; -const firestoreFooter = '\n \n\n'; +} /** * Strips path prefix and returns only filename. @@ -60,6 +96,52 @@ function stripPath(path) { return parts[parts.length - 1]; } +/** + * Generates an index of filename to service name mappings used to infer + * the namespace of an exported type. This is determined based on the + * toc.yaml file. For example: + * { + * "androidconfig.html": "messaging", + * "androidfcmoptions.html": "messaging", + * ... + * "explicitparametervalue.html": "remote-config", + * ... + * } + * If the same typename is exported across two namespaces an error is logged, + * excluding RTDB/firestore query we simply provide links to external docs. + */ +function generateFilenameIndex() { + if (!autoGeneratedTypingsEnabled) { + return; + } + + const tocContents = fs.readFileSync(`${contentPath}/toc.yaml`, 'utf8'); + const { toc } = yaml.safeLoad(tocContents); + + toc.forEach(group => { + const section = group.section || []; + section.forEach(item => { + // Ex: /docs/reference/admin/node/admin.remoteConfig.RemoteConfig + // ^----------^ ^----------^ + // serviceName typeName + const filename = item.path.split('/').pop().split('.'); + + // For example, admin.admin does not have a serviceName + if (filename !== undefined && filename.length == 3) { + const serviceName = filename[1]; + const typeName = `${filename[2].toLowerCase()}.html`; + + // Both RTDB and Firestore export query, but we only export aliases + if (filenameIndex[typeName] !== undefined && typeName !== 'query.html') { + console.log(`ERROR ${typeName}:${serviceName} is defined in two namespaces!`); + } else { + filenameIndex[typeName] = serviceName; + } + } + }); + }); +} + /** * Runs Typedoc command. * @@ -67,6 +149,7 @@ function stripPath(path) { */ function runTypedoc() { const command = `${repoPath}/node_modules/.bin/typedoc ${sourceFile} \ + --excludePrivate \ --out ${docPath} \ --readme ${tempHomePath} \ --options ${__dirname}/typedoc.js \ @@ -98,10 +181,61 @@ function fixLinks(file) { .replace(/\.\.\//g, '') .replace(/(modules|interfaces|classes|enums)\//g, ''); let caseFixedLinks = flattenedLinks; + + // Fix filenames by leveraging the filenameIndex + // For example: (\r\n|\r|\n)(\s)*Implements<\/h3>(.|\r\n|\r|\n)*?<\/section>/g; + caseFixedLinks = caseFixedLinks.replace(implementsAnyRe, ''); + + // Replace Accessors with Properties + const accessorsMedium = /Accessors<\/h3>/g; + caseFixedLinks = caseFixedLinks.replace(accessorsMedium, 'Properties'); + + // Replace Accessors with Properties + const accessorsLarge = /Accessors<\/h2>/g; + caseFixedLinks = caseFixedLinks.replace(accessorsLarge, 'Properties'); + + // Replace FirebaseApp with _admin.app.App + const firebaseAppTagContents = />FirebaseApp<\//g; + caseFixedLinks = caseFixedLinks.replace(firebaseAppTagContents, '>_admin.app.App<\/'); + + // Remove the "GET" tag from Accessors + const accessorGet = /get<\/span>/g; + caseFixedLinks = caseFixedLinks.replace(accessorGet, ''); + } + for (const lower in lowerToUpperLookup) { const re = new RegExp(lower, 'g'); caseFixedLinks = caseFixedLinks.replace(re, lowerToUpperLookup[lower]); } + return fs.writeFile(file, caseFixedLinks); }); } @@ -119,11 +253,15 @@ function generateTempHomeMdFile(tocRaw, homeRaw) { const { toc } = yaml.safeLoad(tocRaw); let tocPageLines = [homeRaw, '# API Reference']; toc.forEach(group => { - tocPageLines.push(`\n## [${group.title}](${stripPath(group.path)})`); - const section = group.section || []; - section.forEach(item => { - tocPageLines.push(`- [${item.title}](${stripPath(item.path)}.html)`); - }); + tocPageLines.push(`\n## [${group.title}](${stripPath(group.path)}.html)`); + // We ignore the contents in toc.yaml for admin.database because we will + // simply redirect the user to the JS SDK RTDB documentation + if (autoGeneratedTypingsEnabled && group.title !== 'admin.database') { + const section = group.section || []; + section.forEach(item => { + tocPageLines.push(`- [${item.title}](${stripPath(item.path)}.html)`); + }); + } }); return fs.writeFile(tempHomePath, tocPageLines.join('\n')); } @@ -250,27 +388,45 @@ function fixAllLinks(htmlFiles) { } /** - * Updates the auto-generated Firestore API references page, by appending - * the specified HTML content block. + * Updates the auto-generated 3rd party module API references page, + * by appending the specified HTML content block. * - * @param {string} contentBlock The HTML content block to be added to the Firestore docs. + * @param {string} contentBlock The HTML content block to be added to the + * body of the docs. */ -function updateFirestoreHtml(contentBlock) { - const dom = new jsdom.JSDOM(fs.readFileSync(firestoreHtmlPath)); +function updateThirdPartyModuleBodyHtml(contentBlock, filePath) { + const dom = new jsdom.JSDOM(fs.readFileSync(filePath)); const contentNode = dom.window.document.body.querySelector('.col-12'); const newSection = new jsdom.JSDOM(contentBlock); contentNode.appendChild(newSection.window.document.body.firstChild); - fs.writeFileSync(firestoreHtmlPath, dom.window.document.documentElement.outerHTML); + fs.writeFileSync(filePath, dom.window.document.documentElement.outerHTML); } /** - * Adds Firestore type aliases to the auto-generated API docs. These are the - * types that are imported from the @google-cloud/firestore package, and - * then re-exported from the admin.firestore namespace. Typedoc currently - * does not handle these correctly, so we need this solution instead. + * Removes all top-level content from the web-page, where top-level content + * is defined as the different sections such as "Index", "Variables", etc. + * + * @param {string} filePath The file to remove all top-level content from. */ -function addFirestoreTypeAliases() { +function removeAllNonTopLevelContent(filePath) { + const dom = new jsdom.JSDOM(fs.readFileSync(filePath)); + const contentNode = dom.window.document.body.querySelector('.col-12'); + + while (contentNode.children.length >= 2) { + contentNode.removeChild(contentNode.children[1]); + } + + fs.writeFileSync(filePath, dom.window.document.documentElement.outerHTML); +} + +/** + * Adds third-party type aliases to the auto-generated API docs. These are the + * types that are imported from another package, and then re-exported from the + * an admin.* namespace. TypeDoc currently does not handle these correctly, so + * we need this solution instead. + */ +function addThirdPartyTypeAliases(header, footer, filePath, moduleName, baseUrl, blacklist) { return new Promise((resolve, reject) => { const fileStream = fs.createReadStream(`${repoPath}/src/index.d.ts`); fileStream.on('error', (err) => { @@ -280,15 +436,15 @@ function addFirestoreTypeAliases() { input: fileStream, }); - let contentBlock = firestoreHeader; + let contentBlock = header; lineReader.on('line', (line) => { line = line.trim(); - if (line.startsWith('export import') && line.indexOf('_firestore.') >= 0) { + if (line.startsWith('export import') && line.indexOf(moduleName) >= 0) { const typeName = line.split(' ')[2]; - if (firestoreExcludes.indexOf(typeName) === -1) { + if (blacklist.indexOf(typeName) === -1) { contentBlock += ` - ${typeName} + ${typeName} `; } } @@ -296,8 +452,8 @@ function addFirestoreTypeAliases() { lineReader.on('close', () => { try { - contentBlock += firestoreFooter; - updateFirestoreHtml(contentBlock); + contentBlock += footer; + updateThirdPartyModuleBodyHtml(contentBlock, filePath); resolve(); } catch (err) { reject(err); @@ -306,6 +462,63 @@ function addFirestoreTypeAliases() { }); } +function addPageTitleNamespace() { + fs.readdirSync(docPath).forEach(file => { + const indexedFilename = file.toLowerCase().substr(file.lastIndexOf('.', file.lastIndexOf('.') - 1) + 1); + const namespace = filenameIndex[indexedFilename]; + + if (file.indexOf('.html') !== -1) { + const dom = new jsdom.JSDOM(fs.readFileSync(`${docPath}/${file}`)); + const contentNode = dom.window.document.body.querySelector('.tsd-breadcrumb'); + if (contentNode !== null && contentNode.children.length < 2) { + if (namespace !== undefined) { + const namespaceBreadcrumb = dom.window.document.createElement('div'); + namespaceBreadcrumb.style = 'display:inline'; + namespaceBreadcrumb.innerHTML = ` + ${namespace}. + `; + + contentNode.prepend(namespaceBreadcrumb); + } + const adminBreadcrumb = dom.window.document.createElement('div'); + adminBreadcrumb.style = 'display:inline'; + adminBreadcrumb.innerHTML = ` + admin. + `; + + contentNode.prepend(adminBreadcrumb); + } + + const variablesNode = dom.window.document.body.querySelector('.tsd-member-group'); + if (variablesNode !== null) { + if (variablesNode.children[0].nodeName === 'H2' && variablesNode.children[0].innerHTML === 'Variables') { + variablesNode.remove(); + } + } + fs.writeFileSync(`${docPath}/${file}`, dom.window.document.documentElement.outerHTML); + } + }); +} + +function renameUnmappedFiles() { + if (!autoGeneratedTypingsEnabled) { + return; + } + + fs.readdirSync(docPath).forEach(filename => { + if (filename !== 'interfaces' && !fs.lstatSync(`${docPath}/${filename}`).isDirectory() + && filename.indexOf('admin') === -1 + && !noNamespace.includes(filename)) { + const serviceName = filenameIndex[filename]; + if (serviceName === undefined) { + console.log(`ERROR Could not find a service for ${filename}`); + } else { + fs.renameSync(`${docPath}/${filename}`, `${docPath}/admin.${serviceName}.${filename}`); + } + } + }); +} + /** * Main document generation process. * @@ -343,12 +556,14 @@ Promise.all([ // it easier to manage the docs directory. .then(() => { return Promise.all([ - // moveFilesToRoot('classes'), + moveFilesToRoot('classes'), moveFilesToRoot('modules'), moveFilesToRoot('interfaces'), moveFilesToRoot('enums'), ]); }) + .then(() => generateFilenameIndex()) + .then(() => renameUnmappedFiles()) // Check for files listed in TOC that are missing and warn if so. // Not blocking. .then(checkForMissingFilesAndFixFilenameCase) @@ -365,7 +580,24 @@ Promise.all([ .then(fixAllLinks) // Add local variable include line to index.html (to access current SDK // version number). - .then(addFirestoreTypeAliases) + .then(() => addThirdPartyTypeAliases( + generateThirdPartyHeader('@google-cloud/firestore'), + thirdPartyFooter, + firestoreHtmlPath, + '_firestore.', + 'https://googleapis.dev/nodejs/firestore/latest/', + firestoreExcludes, + )) + .then(() => removeAllNonTopLevelContent(databaseHtmlPath)) + .then(() => addThirdPartyTypeAliases( + generateThirdPartyHeader('@firebase/database-types'), + thirdPartyFooter, + databaseHtmlPath, + '_database.', + 'https://firebase.google.com/docs/reference/js/firebase.database.', + databaseExcludes + )) + .then(addPageTitleNamespace) .then(() => { fs.readFile(`${docPath}/index.html`, 'utf8').then(data => { // String to include devsite local variables. diff --git a/package-lock.json b/package-lock.json index 74712bba20..290c16040c 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,6 +1,6 @@ { "name": "firebase-admin", - "version": "9.0.0", + "version": "9.1.1", "lockfileVersion": 1, "requires": true, "dependencies": { @@ -1150,6 +1150,11 @@ "integrity": "sha1-x57Zf380y48robyXkLzDZkdLS3k=", "dev": true }, + "at-least-node": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/at-least-node/-/at-least-node-1.0.0.tgz", + "integrity": "sha512-+q/t7Ekv1EDY2l6Gda6LLiX14rU9TV20Wa3ofeQmwPFZbOMo9DXrLbOjFaaclkXKWidIaopwAObQDqwWtGUjqg==" + }, "atob": { "version": "2.1.2", "resolved": "https://registry.npmjs.org/atob/-/atob-2.1.2.tgz", @@ -1185,20 +1190,10 @@ "now-and-later": "^2.0.0" } }, - "backbone": { - "version": "1.4.0", - "resolved": "https://registry.npmjs.org/backbone/-/backbone-1.4.0.tgz", - "integrity": "sha512-RLmDrRXkVdouTg38jcgHhyQ/2zjg7a8E6sz2zxfz21Hh17xDJYUHBZimVIt5fUyS8vbfpeSmTL3gUjTEvUV3qQ==", - "dev": true, - "requires": { - "underscore": ">=1.8.3" - } - }, "balanced-match": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.0.tgz", - "integrity": "sha1-ibTRmasr7kneFk6gK4nORi1xt2c=", - "dev": true + "integrity": "sha1-ibTRmasr7kneFk6gK4nORi1xt2c=" }, "base": { "version": "0.11.2", @@ -1323,7 +1318,6 @@ "version": "1.1.11", "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz", "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==", - "dev": true, "requires": { "balanced-match": "^1.0.0", "concat-map": "0.0.1" @@ -1758,8 +1752,7 @@ "concat-map": { "version": "0.0.1", "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz", - "integrity": "sha1-2Klr13/Wjfd5OnMDajug1UBdR3s=", - "dev": true + "integrity": "sha1-2Klr13/Wjfd5OnMDajug1UBdR3s=" }, "concat-stream": { "version": "2.0.0", @@ -3105,14 +3098,14 @@ } }, "fs-extra": { - "version": "8.1.0", - "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-8.1.0.tgz", - "integrity": "sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g==", - "dev": true, + "version": "9.0.1", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-9.0.1.tgz", + "integrity": "sha512-h2iAoN838FqAFJY2/qVpzFXy+EBxfVE220PalAqQLDVsFOHLJrZvut5puAbCdNv6WJk+B8ihI+k0c7JK5erwqQ==", "requires": { + "at-least-node": "^1.0.0", "graceful-fs": "^4.2.0", - "jsonfile": "^4.0.0", - "universalify": "^0.1.0" + "jsonfile": "^6.0.1", + "universalify": "^1.0.0" } }, "fs-minipass": { @@ -3149,8 +3142,7 @@ "fs.realpath": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz", - "integrity": "sha1-FQStJSMVjKpA20onh8sBQRmU6k8=", - "dev": true + "integrity": "sha1-FQStJSMVjKpA20onh8sBQRmU6k8=" }, "fsevents": { "version": "1.2.13", @@ -3265,7 +3257,6 @@ "version": "7.1.6", "resolved": "https://registry.npmjs.org/glob/-/glob-7.1.6.tgz", "integrity": "sha512-LwaxwyZ72Lk7vZINtNNrywX0ZuLyStrdDtabefZKAY5ZGJhVtgdznluResxNmPitE0SAO+O26sWTHeKSI2wMBA==", - "dev": true, "requires": { "fs.realpath": "^1.0.0", "inflight": "^1.0.4", @@ -3752,7 +3743,6 @@ "version": "4.7.6", "resolved": "https://registry.npmjs.org/handlebars/-/handlebars-4.7.6.tgz", "integrity": "sha512-1f2BACcBfiwAfStCKZNrUCgqNZkGsAT7UM3kkYtXuLo0KnaVfjKOyf7PRzB6++aK9STyT1Pd2ZCPe3EGOXleXA==", - "dev": true, "requires": { "minimist": "^1.2.5", "neo-async": "^2.6.0", @@ -3764,8 +3754,7 @@ "source-map": { "version": "0.6.1", "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.6.1.tgz", - "integrity": "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==", - "dev": true + "integrity": "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==" } } }, @@ -3907,10 +3896,9 @@ "dev": true }, "highlight.js": { - "version": "9.18.1", - "resolved": "https://registry.npmjs.org/highlight.js/-/highlight.js-9.18.1.tgz", - "integrity": "sha512-OrVKYz70LHsnCgmbXctv/bfuvntIKDz177h0Co37DQ5jamGZLVmoCVMtjMtNZY3X9DrCcKfklHPNeA0uPZhSJg==", - "dev": true + "version": "10.1.2", + "resolved": "https://registry.npmjs.org/highlight.js/-/highlight.js-10.1.2.tgz", + "integrity": "sha512-Q39v/Mn5mfBlMff9r+zzA+gWxRsCRKwEMvYTiisLr/XUiFI/4puWt0Ojdko3R3JCNWGdOWaA5g/Yxqa23kC5AA==" }, "homedir-polyfill": { "version": "1.0.3", @@ -4055,7 +4043,6 @@ "version": "1.0.6", "resolved": "https://registry.npmjs.org/inflight/-/inflight-1.0.6.tgz", "integrity": "sha1-Sb1jMdfQLQwJvJEKEHW6gWW1bfk=", - "dev": true, "requires": { "once": "^1.3.0", "wrappy": "1" @@ -4180,8 +4167,7 @@ "interpret": { "version": "1.4.0", "resolved": "https://registry.npmjs.org/interpret/-/interpret-1.4.0.tgz", - "integrity": "sha512-agE4QfB2Lkp9uICn7BAqoscw4SZP9kTE2hxiFI3jBPmXJfdqiahTbUuKGsMoN2GtqL9AxhYioAcVvgsb1HvRbA==", - "dev": true + "integrity": "sha512-agE4QfB2Lkp9uICn7BAqoscw4SZP9kTE2hxiFI3jBPmXJfdqiahTbUuKGsMoN2GtqL9AxhYioAcVvgsb1HvRbA==" }, "invert-kv": { "version": "1.0.0", @@ -4628,12 +4614,6 @@ "textextensions": "~1.0.0" } }, - "jquery": { - "version": "3.5.1", - "resolved": "https://registry.npmjs.org/jquery/-/jquery-3.5.1.tgz", - "integrity": "sha512-XwIBPqcMn57FxfT+Go5pzySnm4KWkT1Tv7gjrpT1srtf8Weynl6R273VJ5GjkRb51IzMp5nbaPjJXMWeju2MKg==", - "dev": true - }, "js-tokens": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz", @@ -4736,12 +4716,12 @@ "dev": true }, "jsonfile": { - "version": "4.0.0", - "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-4.0.0.tgz", - "integrity": "sha1-h3Gq4HmbZAdrdmQPygWPnBDjPss=", - "dev": true, + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.0.1.tgz", + "integrity": "sha512-jR2b5v7d2vIOust+w3wtFKZIfpC2pnRmFAhAC/BuweZFQR8qZzxH1OyrQ10HmdVYiXWkYUqPVsz91cG7EL2FBg==", "requires": { - "graceful-fs": "^4.1.6" + "graceful-fs": "^4.1.6", + "universalify": "^1.0.0" } }, "jsonwebtoken": { @@ -4935,8 +4915,7 @@ "lodash": { "version": "4.17.19", "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.19.tgz", - "integrity": "sha512-JNvd8XER9GQX0v2qJgsaN/mzFCNA5BRe/j8JN9d+tWyGLSodKQHKFicdwNYzWwI3wjRnaKPsGj1XkBjx/F96DQ==", - "dev": true + "integrity": "sha512-JNvd8XER9GQX0v2qJgsaN/mzFCNA5BRe/j8JN9d+tWyGLSodKQHKFicdwNYzWwI3wjRnaKPsGj1XkBjx/F96DQ==" }, "lodash._basecopy": { "version": "3.0.1", @@ -5136,10 +5115,9 @@ } }, "lunr": { - "version": "2.3.8", - "resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.8.tgz", - "integrity": "sha512-oxMeX/Y35PNFuZoHp+jUj5OSEmLCaIH4KTFJh7a93cHBoFmpw2IoPs22VIz7vyO2YUnx2Tn9dzIwO2P/4quIRg==", - "dev": true + "version": "2.3.9", + "resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.9.tgz", + "integrity": "sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==" }, "make-dir": { "version": "3.1.0", @@ -5181,10 +5159,9 @@ } }, "marked": { - "version": "0.8.2", - "resolved": "https://registry.npmjs.org/marked/-/marked-0.8.2.tgz", - "integrity": "sha512-EGwzEeCcLniFX51DhTpmTom+dSA/MG/OBUDjnWtHbEnjAH180VzUeAw+oE4+Zv+CoYBWyRlYOTR0N8SO9R1PVw==", - "dev": true + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/marked/-/marked-1.1.1.tgz", + "integrity": "sha512-mJzT8D2yPxoPh7h0UXkB+dBj4FykPJ2OIfxAWeIHrvoHDkFxukV/29QxoFQoPM6RLEwhIFdJpmKBlqVM3s2ZIw==" }, "matchdep": { "version": "2.0.0", @@ -5293,7 +5270,6 @@ "version": "3.0.4", "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.0.4.tgz", "integrity": "sha512-yJHVQEhyqPLUTgt9B83PXu6W3rx4MvvHvSUvToogpwoGDOUQ+yDrR0HRot+yOCdCO7u4hX3pWft6kWBBcqh0UA==", - "dev": true, "requires": { "brace-expansion": "^1.1.7" } @@ -5301,8 +5277,7 @@ "minimist": { "version": "1.2.5", "resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.5.tgz", - "integrity": "sha512-FM9nNUYrRBAELZQT3xeZQ7fmMOBg6nWNmJKTcgsJeaLstP/UODVpGsr5OhXhhXg6f+qtJ8uiZ+PUxkDWcgIXLw==", - "dev": true + "integrity": "sha512-FM9nNUYrRBAELZQT3xeZQ7fmMOBg6nWNmJKTcgsJeaLstP/UODVpGsr5OhXhhXg6f+qtJ8uiZ+PUxkDWcgIXLw==" }, "minipass": { "version": "2.9.0", @@ -5547,8 +5522,7 @@ "neo-async": { "version": "2.6.2", "resolved": "https://registry.npmjs.org/neo-async/-/neo-async-2.6.2.tgz", - "integrity": "sha512-Yd3UES5mWCSqR+qNT93S3UoYUkqAZ9lLg8a7g9rimsWmYGK8cVToA4/sF3RrshdyV3sAGMXVUmpMYOw+dLpOuw==", - "dev": true + "integrity": "sha512-Yd3UES5mWCSqR+qNT93S3UoYUkqAZ9lLg8a7g9rimsWmYGK8cVToA4/sF3RrshdyV3sAGMXVUmpMYOw+dLpOuw==" }, "nested-error-stacks": { "version": "2.1.0", @@ -6279,8 +6253,7 @@ "path-is-absolute": { "version": "1.0.1", "resolved": "http://registry.npmjs.org/path-is-absolute/-/path-is-absolute-1.0.1.tgz", - "integrity": "sha1-F0uSaHNVNP+8es5r9TpanhtcX18=", - "dev": true + "integrity": "sha1-F0uSaHNVNP+8es5r9TpanhtcX18=" }, "path-is-inside": { "version": "1.0.2", @@ -6297,8 +6270,7 @@ "path-parse": { "version": "1.0.6", "resolved": "https://registry.npmjs.org/path-parse/-/path-parse-1.0.6.tgz", - "integrity": "sha512-GSmOT2EbHrINBf9SR7CDELwlJ8AENk3Qn7OikK4nFYAu3Ote2+JYNVvkpAEQm3/TLNEJFD/xZJjzyxg3KBWOzw==", - "dev": true + "integrity": "sha512-GSmOT2EbHrINBf9SR7CDELwlJ8AENk3Qn7OikK4nFYAu3Ote2+JYNVvkpAEQm3/TLNEJFD/xZJjzyxg3KBWOzw==" }, "path-root": { "version": "0.1.1", @@ -6446,8 +6418,7 @@ "progress": { "version": "2.0.3", "resolved": "https://registry.npmjs.org/progress/-/progress-2.0.3.tgz", - "integrity": "sha512-7PiHtLll5LdnKIMw100I+8xJXR5gW2QwWYkT6iJva0bXitZKa/XMrSbdmg3r2Xnaidz9Qumd0VPaMrZlF9V9sA==", - "dev": true + "integrity": "sha512-7PiHtLll5LdnKIMw100I+8xJXR5gW2QwWYkT6iJva0bXitZKa/XMrSbdmg3r2Xnaidz9Qumd0VPaMrZlF9V9sA==" }, "promise-polyfill": { "version": "6.1.0", @@ -6629,7 +6600,6 @@ "version": "0.6.2", "resolved": "https://registry.npmjs.org/rechoir/-/rechoir-0.6.2.tgz", "integrity": "sha1-hSBLVNuoLVdC4oyWdW70OvUOM4Q=", - "dev": true, "requires": { "resolve": "^1.1.6" } @@ -6877,7 +6847,6 @@ "version": "1.17.0", "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.17.0.tgz", "integrity": "sha512-ic+7JYiV8Vi2yzQGFWOkiZD5Z9z7O2Zhm9XMaTxdJExKasieFCr+yXZ/WmXsckHiKl12ar0y6XiXDx3m4RHn1w==", - "dev": true, "requires": { "path-parse": "^1.0.6" } @@ -7076,7 +7045,6 @@ "version": "0.8.4", "resolved": "https://registry.npmjs.org/shelljs/-/shelljs-0.8.4.tgz", "integrity": "sha512-7gk3UZ9kOfPLIAbslLzyWeGiEqx9e3rxwZM0KE6EL8GlGwjym9Mrlx5/p33bWTu9YG6vcS4MBxYZDHYr5lr8BQ==", - "dev": true, "requires": { "glob": "^7.0.0", "interpret": "^1.0.0", @@ -8098,42 +8066,28 @@ } }, "typedoc": { - "version": "0.15.8", - "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.15.8.tgz", - "integrity": "sha512-a0zypcvfIFsS7Gqpf2MkC1+jNND3K1Om38pbDdy/gYWX01NuJZhC5+O0HkIp0oRIZOo7PWrA5+fC24zkANY28Q==", - "dev": true, + "version": "0.18.0", + "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.18.0.tgz", + "integrity": "sha512-UgDQwapCGQCCdYhEQzQ+kGutmcedklilgUGf62Vw6RdI29u6FcfAXFQfRTiJEbf16aK3YnkB20ctQK1JusCRbA==", "requires": { - "@types/minimatch": "3.0.3", - "fs-extra": "^8.1.0", - "handlebars": "^4.7.0", - "highlight.js": "^9.17.1", + "fs-extra": "^9.0.1", + "handlebars": "^4.7.6", + "highlight.js": "^10.0.0", "lodash": "^4.17.15", - "marked": "^0.8.0", + "lunr": "^2.3.8", + "marked": "^1.1.1", "minimatch": "^3.0.0", "progress": "^2.0.3", - "shelljs": "^0.8.3", - "typedoc-default-themes": "^0.6.3", - "typescript": "3.7.x" - }, - "dependencies": { - "typescript": { - "version": "3.7.5", - "resolved": "https://registry.npmjs.org/typescript/-/typescript-3.7.5.tgz", - "integrity": "sha512-/P5lkRXkWHNAbcJIiHPfRoKqyd7bsyCma1hZNUGfn20qm64T6ZBlrzprymeu918H+mB/0rIg2gGK/BXkhhYgBw==", - "dev": true - } + "shelljs": "^0.8.4", + "typedoc-default-themes": "^0.10.2" } }, "typedoc-default-themes": { - "version": "0.6.3", - "resolved": "https://registry.npmjs.org/typedoc-default-themes/-/typedoc-default-themes-0.6.3.tgz", - "integrity": "sha512-rouf0TcIA4M2nOQFfC7Zp4NEwoYiEX4vX/ZtudJWU9IHA29MPC+PPgSXYLPESkUo7FuB//GxigO3mk9Qe1xp3Q==", - "dev": true, + "version": "0.10.2", + "resolved": "https://registry.npmjs.org/typedoc-default-themes/-/typedoc-default-themes-0.10.2.tgz", + "integrity": "sha512-zo09yRj+xwLFE3hyhJeVHWRSPuKEIAsFK5r2u47KL/HBKqpwdUSanoaz5L34IKiSATFrjG5ywmIu98hPVMfxZg==", "requires": { - "backbone": "^1.4.0", - "jquery": "^3.4.1", - "lunr": "^2.3.8", - "underscore": "^1.9.1" + "lunr": "^2.3.8" } }, "typescript": { @@ -8143,10 +8097,9 @@ "dev": true }, "uglify-js": { - "version": "3.10.0", - "resolved": "https://registry.npmjs.org/uglify-js/-/uglify-js-3.10.0.tgz", - "integrity": "sha512-Esj5HG5WAyrLIdYU74Z3JdG2PxdIusvj6IWHMtlyESxc7kcDz7zYlYjpnSokn1UbpV0d/QX9fan7gkCNd/9BQA==", - "dev": true, + "version": "3.10.1", + "resolved": "https://registry.npmjs.org/uglify-js/-/uglify-js-3.10.1.tgz", + "integrity": "sha512-RjxApKkrPJB6kjJxQS3iZlf///REXWYxYJxO/MpmlQzVkDWVI3PSnCBWezMecmTU/TRkNxrl8bmsfFQCp+LO+Q==", "optional": true }, "unc-path-regex": { @@ -8155,12 +8108,6 @@ "integrity": "sha1-5z3T17DXxe2G+6xrCufYxqadUPo=", "dev": true }, - "underscore": { - "version": "1.10.2", - "resolved": "https://registry.npmjs.org/underscore/-/underscore-1.10.2.tgz", - "integrity": "sha512-N4P+Q/BuyuEKFJ43B9gYuOj4TQUHXX+j2FqguVOpjkssLUUrnJofCcBccJSCoeturDoZU6GorDTHSvUDlSQbTg==", - "dev": true - }, "undertaker": { "version": "1.2.1", "resolved": "https://registry.npmjs.org/undertaker/-/undertaker-1.2.1.tgz", @@ -8216,10 +8163,9 @@ } }, "universalify": { - "version": "0.1.2", - "resolved": "https://registry.npmjs.org/universalify/-/universalify-0.1.2.tgz", - "integrity": "sha512-rBJeI5CXAlmy1pV+617WB9J63U6XcazHHF2f2dbJix4XzpUF0RS3Zbj0FGIOCAva5P/d/GBOYaACQ1w+0azUkg==", - "dev": true + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/universalify/-/universalify-1.0.0.tgz", + "integrity": "sha512-rb6X1W158d7pRQBg5gkR8uPaSfiids68LTJQYOtEUhoJUWBdaQHsuT/EUduxXYxcrt4r5PJ4fuHW1MHT6p0qug==" }, "unset-value": { "version": "1.0.0", @@ -8534,8 +8480,7 @@ "wordwrap": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/wordwrap/-/wordwrap-1.0.0.tgz", - "integrity": "sha1-J1hIEIkUVqQXHI0CJkQa3pDLyus=", - "dev": true + "integrity": "sha1-J1hIEIkUVqQXHI0CJkQa3pDLyus=" }, "wrap-ansi": { "version": "2.1.0", diff --git a/package.json b/package.json index 061d5d0a1c..e35614f1da 100644 --- a/package.json +++ b/package.json @@ -59,7 +59,8 @@ "@types/node": "^10.10.0", "dicer": "^0.3.0", "jsonwebtoken": "^8.5.1", - "node-forge": "^0.9.1" + "node-forge": "^0.9.1", + "typedoc": "^0.18.0" }, "optionalDependencies": { "@google-cloud/firestore": "^4.0.0", @@ -112,7 +113,6 @@ "sinon": "^9.0.0", "sinon-chai": "^3.0.0", "ts-node": "^3.3.0", - "typedoc": "^0.15.0", "typescript": "^3.7.3", "yargs": "^13.2.2" } diff --git a/src/database/database-internal.ts b/src/database/database-internal.ts index fa955a9b7e..7efaa2ca7c 100644 --- a/src/database/database-internal.ts +++ b/src/database/database-internal.ts @@ -51,7 +51,6 @@ class DatabaseInternals implements FirebaseServiceInternalsInterface { } export class DatabaseService implements FirebaseServiceInterface { - public readonly INTERNAL: DatabaseInternals = new DatabaseInternals(); private readonly appInternal: FirebaseApp; diff --git a/src/instance-id/instance-id.ts b/src/instance-id/instance-id.ts index b17434e9a3..2f913fe4a9 100644 --- a/src/instance-id/instance-id.ts +++ b/src/instance-id/instance-id.ts @@ -51,6 +51,7 @@ class InstanceIdInternals implements FirebaseServiceInternalsInterface { * current app. */ export class InstanceId implements FirebaseServiceInterface { + /** @hidden */ public INTERNAL: InstanceIdInternals = new InstanceIdInternals(); private app_: FirebaseApp; @@ -59,6 +60,7 @@ export class InstanceId implements FirebaseServiceInterface { /** * @param {FirebaseApp} app The app for this InstanceId service. * @constructor + * @hidden */ constructor(app: FirebaseApp) { if (!validator.isNonNullObject(app) || !('options' in app)) { diff --git a/src/messaging/messaging.ts b/src/messaging/messaging.ts index eec16df661..7e15b55fb3 100644 --- a/src/messaging/messaging.ts +++ b/src/messaging/messaging.ts @@ -194,29 +194,27 @@ class MessagingInternals implements FirebaseServiceInternalsInterface { /** - * Messaging service bound to the provided app. + * Gets the {@link admin.messaging.Messaging `Messaging`} service for the + * current app. + * + * @example + * ```javascript + * var messaging = app.messaging(); + * // The above is shorthand for: + * // var messaging = admin.messaging(app); + * ``` + * + * @return The `Messaging` service for the current app. */ export class Messaging implements FirebaseServiceInterface { - + /** @hidden */ public INTERNAL: MessagingInternals = new MessagingInternals(); private urlPath: string; private readonly appInternal: FirebaseApp; private readonly messagingRequestHandler: FirebaseMessagingRequestHandler; - /** - * Gets the {@link admin.messaging.Messaging `Messaging`} service for the - * current app. - * - * @example - * ```javascript - * var messaging = app.messaging(); - * // The above is shorthand for: - * // var messaging = admin.messaging(app); - * ``` - * - * @return The `Messaging` service for the current app. - */ + /** @hidden */ constructor(app: FirebaseApp) { if (!validator.isNonNullObject(app) || !('options' in app)) { throw new FirebaseMessagingError( diff --git a/src/project-management/android-app.ts b/src/project-management/android-app.ts index 793d9137f3..ed01f29508 100644 --- a/src/project-management/android-app.ts +++ b/src/project-management/android-app.ts @@ -22,6 +22,7 @@ import { AndroidAppMetadata, AppPlatform } from './app-metadata'; export class AndroidApp { private readonly resourceName: string; + /** @hidden */ constructor( public readonly appId: string, private readonly requestHandler: ProjectManagementRequestHandler) { @@ -205,6 +206,7 @@ export class ShaCertificate { * ```javascript * var resourceName = shaCertificate.resourceName; * ``` + * @hidden */ constructor(public readonly shaHash: string, public readonly resourceName?: string) { if (/^[a-fA-F0-9]{40}$/.test(shaHash)) { diff --git a/src/project-management/index.ts b/src/project-management/index.ts index 7f9bb1a3c5..47e20d2509 100644 --- a/src/project-management/index.ts +++ b/src/project-management/index.ts @@ -42,7 +42,7 @@ export namespace admin.projectManagement { // See https://github.com/typescript-eslint/typescript-eslint/issues/363 export import AndroidAppMetadata = appMetadataApi.AndroidAppMetadata export import AppMetadata = appMetadataApi.AppMetadata - export import AppPlatform = appMetadataApi.AppPlatform + export import AppPlatform = appMetadataApi.AppPlatform; export import IosAppMetadata = appMetadataApi.IosAppMetadata // Allows for exposing classes as interfaces in typings diff --git a/src/project-management/ios-app.ts b/src/project-management/ios-app.ts index 0f5955c1a1..ccc32b6896 100644 --- a/src/project-management/ios-app.ts +++ b/src/project-management/ios-app.ts @@ -22,6 +22,7 @@ import { IosAppMetadata, AppPlatform } from './app-metadata'; export class IosApp { private readonly resourceName: string; + /** @hidden */ constructor( public readonly appId: string, private readonly requestHandler: ProjectManagementRequestHandler) { diff --git a/src/project-management/project-management.ts b/src/project-management/project-management.ts index daade63172..19ec606971 100644 --- a/src/project-management/project-management.ts +++ b/src/project-management/project-management.ts @@ -46,6 +46,7 @@ class ProjectManagementInternals implements FirebaseServiceInternalsInterface { * [`admin.projectManagement()`](admin.projectManagement#projectManagement). */ export class ProjectManagement implements FirebaseServiceInterface { + /** @hidden */ public readonly INTERNAL: ProjectManagementInternals = new ProjectManagementInternals(); private readonly requestHandler: ProjectManagementRequestHandler; @@ -54,6 +55,7 @@ export class ProjectManagement implements FirebaseServiceInterface { /** * @param {object} app The app for this ProjectManagement service. * @constructor + * @hidden */ constructor(readonly app: FirebaseApp) { if (!validator.isNonNullObject(app) || !('options' in app)) { diff --git a/src/remote-config/remote-config.ts b/src/remote-config/remote-config.ts index 4c67189a9f..1a50d66846 100644 --- a/src/remote-config/remote-config.ts +++ b/src/remote-config/remote-config.ts @@ -45,9 +45,13 @@ class RemoteConfigInternals implements FirebaseServiceInternalsInterface { } /** - * Remote Config service bound to the provided app. + * The Firebase `RemoteConfig` service interface. + * + * Do not call this constructor directly. Instead, use + * [`admin.remoteConfig()`](admin.remoteConfig#remoteConfig). */ export class RemoteConfig implements FirebaseServiceInterface { + /** @hidden */ public readonly INTERNAL: RemoteConfigInternals = new RemoteConfigInternals(); private readonly client: RemoteConfigApiClient; @@ -55,6 +59,7 @@ export class RemoteConfig implements FirebaseServiceInterface { /** * @param {FirebaseApp} app The app for this RemoteConfig service. * @constructor + * @hidden */ constructor(readonly app: FirebaseApp) { this.client = new RemoteConfigApiClient(app); diff --git a/src/security-rules/security-rules.ts b/src/security-rules/security-rules.ts index 89eda3825f..7b727e9ebb 100644 --- a/src/security-rules/security-rules.ts +++ b/src/security-rules/security-rules.ts @@ -97,6 +97,7 @@ export class Ruleset implements RulesetMetadata { public readonly createTime: string; public readonly source: RulesFile[]; + /** @hidden */ constructor(ruleset: RulesetResponse) { if (!validator.isNonNullObject(ruleset) || !validator.isNonEmptyString(ruleset.name) || @@ -124,6 +125,7 @@ export class SecurityRules implements FirebaseServiceInterface { private static readonly CLOUD_FIRESTORE = 'cloud.firestore'; private static readonly FIREBASE_STORAGE = 'firebase.storage'; + /** @hidden */ public readonly INTERNAL = new SecurityRulesInternals(); private readonly client: SecurityRulesApiClient; @@ -131,6 +133,7 @@ export class SecurityRules implements FirebaseServiceInterface { /** * @param {object} app The app for this SecurityRules service. * @constructor + * @hidden */ constructor(readonly app: FirebaseApp) { this.client = new SecurityRulesApiClient(app);
Following types are defined in the @google-cloud/firestore package +
@google-cloud/firestore
Following types are defined in the ${packageName} package and re-exported from this namespace for convenience.
${packageName}