Introduce an interface IPackageJsonWithVersion to avoid constantly having to check for an undefined "version" in all the places where the version is guaranteed to exist

octogonz · octogonz · commit 053d31bb998c · 2019-03-17T13:20:37.000-07:00
diff --git a/apps/api-extractor/src/api/Extractor.ts b/apps/api-extractor/src/api/Extractor.ts
@@ -12,9 +12,9 @@ import {
   JsonSchema,
   Path,
   FileSystem,
-  IPackageJson,
   NewlineKind,
-  PackageJsonLookup
+  PackageJsonLookup,
+  IPackageJsonWithVersion
 } from '@microsoft/node-core-library';
 import {
   IExtractorConfig,
@@ -99,7 +99,7 @@ export class Extractor {
   /**
    * Returns the version number of the API Extractor NPM package.
    */
-  public static get version(): string | undefined {
+  public static get version(): string {
     return Extractor._getPackageJson().version;
   }
 
@@ -110,7 +110,7 @@ export class Extractor {
     return Extractor._getPackageJson().name;
   }
 
-  private static _getPackageJson(): IPackageJson {
+  private static _getPackageJson(): IPackageJsonWithVersion {
     return PackageJsonLookup.loadOwnPackageJson(__dirname);
   }
 
diff --git a/libraries/node-core-library/src/IPackageJson.ts b/libraries/node-core-library/src/IPackageJson.ts
@@ -148,3 +148,22 @@ export interface IPackageJson {
    */
   scripts?: IPackageJsonScriptTable;
 }
+
+/**
+ * Describes a `IPackageJson` object whose `version` field is guaranteed to be defined.
+ *
+ * @remarks
+ * The `IPackageJsonWithVersion` interface can be used with package.json files that were
+ * obtained from an NPM registry, or installed in the `node_modules` folder.
+ * According to the {@link https://docs.npmjs.com/files/package.json | NPM documentation},
+ * the `version` field will always be defined for published NPM packages.
+ *
+ * But this is not true in general.  For example, the
+ * {@link https://nodejs.org/dist/latest-v10.x/docs/api/modules.html#modules_folders_as_modules
+ * | NodeJS documentation} does not require the `version` field when using the `require()` API
+ * to import folders as modules.
+ */
+export interface IPackageJsonWithVersion extends IPackageJson {
+  /** {@inheritDoc IPackageJson.version} */
+  version: string;
+}
diff --git a/libraries/node-core-library/src/PackageJsonLookup.ts b/libraries/node-core-library/src/PackageJsonLookup.ts
@@ -5,7 +5,7 @@
 
 import * as path from 'path';
 import { JsonFile } from './JsonFile';
-import { IPackageJson } from './IPackageJson';
+import { IPackageJson, IPackageJsonWithVersion } from './IPackageJson';
 import { FileConstants } from './Constants';
 import { FileSystem } from './FileSystem';
 
@@ -66,7 +66,7 @@ export class PackageJsonLookup {
    * @returns This function always returns a valid `IPackageJson` object.  If any problems are encountered during
    * loading, an exception will be thrown instead.
    */
-  public static loadOwnPackageJson(dirnameOfCaller: string): IPackageJson {
+  public static loadOwnPackageJson(dirnameOfCaller: string): IPackageJsonWithVersion {
     const packageJson: IPackageJson | undefined = PackageJsonLookup._loadOwnPackageJsonLookup
       .tryLoadPackageJsonFor(dirnameOfCaller);
 
@@ -75,7 +75,14 @@ export class PackageJsonLookup {
         + `  The __dirname was: ${dirnameOfCaller}`);
     }
 
-    return packageJson;
+    if (packageJson.version !== undefined) {
+      return packageJson as IPackageJsonWithVersion;
+    }
+
+    const errorPath: string = PackageJsonLookup._loadOwnPackageJsonLookup.tryGetPackageJsonFilePathFor(dirnameOfCaller)
+      || 'package.json';
+    throw new Error(`PackageJsonLookup.loadOwnPackageJson() failed because the "version" field is missing in`
+      + ` ${errorPath}`);
   }
 
   constructor(parameters?: IPackageJsonLookupParameters) {
diff --git a/libraries/node-core-library/src/index.ts b/libraries/node-core-library/src/index.ts
@@ -20,6 +20,7 @@ export {
 } from './Executable';
 export {
   IPackageJson,
+  IPackageJsonWithVersion,
   IPackageJsonDependencyTable,
   IPackageJsonScriptTable,
   IPackageJsonTsdocConfiguration
