@loopback/cli 4.0.0-alpha.8 → 4.1.0

package/generators/import-lb3-models/index.js

@@ -0,0 +1,197 @@
+// Copyright IBM Corp. and LoopBack contributors 2019,2020. All Rights Reserved.
+// Node module: @loopback/cli
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+'use strict';
+
+const chalk = require('chalk');
+const path = require('path');
+const BaseGenerator = require('../../lib/base-generator');
+const modelUtils = require('../../lib/model-discoverer');
+const debug = require('../../lib/debug')('import-lb3-models');
+const utils = require('../../lib/utils');
+const {loadLb3App} = require('./lb3app-loader');
+const {importLb3ModelDefinition} = require('./migrate-model');
+const {canImportModelName} = require('./model-names');
+const g = require('../../lib/globalize');
+
+module.exports = class Lb3ModelImporter extends BaseGenerator {
+  constructor(args, opts) {
+    super(args, opts);
+
+    this.argument('lb3app', {
+      type: String,
+      required: true,
+      description: g.f(
+        'Path to your LoopBack 3.x application. ' +
+          'This can be a project directory (e.g. "my-lb3-app") or ' +
+          'the server file (e.g. "my-lb3-app/server/server.js").',
+      ),
+      // description:
+      //   'Path to your LoopBack 3.x application. ' +
+      //   'This can be a project directory (e.g. "my-lb3-app") or ' +
+      //   'the server file (e.g. "my-lb3-app/server/server.js").',
+    });
+
+    this.option('outDir', {
+      type: String,
+      description: g.f('Directory where to write the generated source file'),
+      default: 'src/models',
+    });
+  }
+
+  async processOptions() {
+    this.sourceAppDir = this.args[0];
+    this.artifactInfo.outDir = this.options.outDir;
+    this.artifactInfo.relPath = path.relative(
+      this.destinationPath(),
+      this.artifactInfo.outDir,
+    );
+    this.artifactInfo.modelDir = path.resolve(
+      this.artifactInfo.rootDir,
+      utils.modelsDir,
+    );
+    return super.setOptions();
+  }
+
+  async logExperimentalStatus() {
+    this.log(
+      chalk.red(`
+WARNING: This command is experimental and not feature-complete yet.
+Learn more at https://loopback.io/doc/en/lb4/Importing-LB3-models.html
+`),
+    );
+  }
+
+  /**
+   * Ensure CLI is being run in a LoopBack 4 project.
+   */
+  checkLoopBackProject() {
+    if (this.shouldExit()) return;
+    return super.checkLoopBackProject();
+  }
+
+  async loadTheApp() {
+    this.lb3app = await loadLb3App(this.sourceAppDir);
+    this.modelRegistry = this.lb3app.registry.modelBuilder.models;
+  }
+
+  async promptModels() {
+    const modelNames = Object.keys(this.modelRegistry).filter(
+      canImportModelName,
+    );
+
+    debug('Available LB3 models', modelNames);
+
+    const prompts = [
+      {
+        name: 'modelNames',
+        message: g.f('Select models to import:'),
+        type: 'checkbox',
+        choices: modelNames,
+        // Require at least one model to be selected
+        // This prevents users from accidentally pressing ENTER instead of SPACE
+        // to select a model from the list
+        validate: result => !!result.length,
+        // TODO: add a CLI flag to supply these names programmatically
+      },
+    ];
+
+    const answers = await this.prompt(prompts);
+    debug('Models chosen:', answers.modelNames);
+    this.modelNames = answers.modelNames;
+  }
+
+  async loadExistingLb4Models() {
+    debug(`model list dir ${this.artifactInfo.modelDir}`);
+    this.existingLb4ModelNames = await utils.getArtifactList(
+      this.artifactInfo.modelDir,
+      'model',
+    );
+  }
+
+  async migrateSelectedModels() {
+    if (this.shouldExit()) return;
+    this.modelFiles = [];
+
+    try {
+      for (const name of this.modelNames) {
+        await this._migrateSingleModel(name);
+      }
+    } catch (err) {
+      if (err.exit) {
+        this.exit(err.message);
+      } else {
+        throw err;
+      }
+    }
+  }
+
+  async _migrateSingleModel(name) {
+    utils.logClassCreation('model', 'models', name, this.log.bind(this));
+    const modelCtor = this.modelRegistry[name];
+    if (typeof modelCtor !== 'function') {
+      const availableModels = Object.keys(this.modelRegistry)
+        .filter(canImportModelName)
+        .join(', ');
+
+      this.exit(
+        `Unknown model name ${name}. Available models: ${availableModels}.`,
+      );
+      return;
+    }
+
+    const templateData = importLb3ModelDefinition(
+      modelCtor,
+      this.log.bind(this),
+    );
+    debug('LB4 model data', templateData);
+
+    if (!templateData.isModelBaseBuiltin) {
+      const baseName = templateData.modelBaseClass;
+      if (
+        !this.existingLb4ModelNames.includes(baseName) &&
+        !this.modelNames.includes(baseName)
+      ) {
+        this.log(
+          'Adding %s (base of %s) to the list of imported models.',
+          chalk.yellow(baseName),
+          chalk.yellow(name),
+        );
+        this.modelNames.push(baseName);
+      }
+    }
+    const fileName = utils.getModelFileName(name);
+    const fullTargetPath = path.resolve(this.artifactInfo.relPath, fileName);
+    debug('Model %s output file', name, fullTargetPath);
+
+    this.copyTemplatedFiles(
+      modelUtils.MODEL_TEMPLATE_PATH,
+      fullTargetPath,
+      templateData,
+    );
+
+    this.modelFiles.push(fileName);
+  }
+
+  /**
+   * Iterate through all the models we have discovered and scaffold
+   */
+  async scaffold() {
+    if (this.shouldExit()) return;
+  }
+
+  async end() {
+    if (this.shouldExit() || !this._isGenerationSuccessful()) {
+      await super.end();
+      return;
+    }
+
+    for (const f of this.modelFiles) {
+      await this._updateIndexFile(this.artifactInfo.outDir, f);
+    }
+
+    await super.end();
+  }
+};

package/generators/import-lb3-models/lb3app-loader.js

@@ -0,0 +1,31 @@
+// Copyright IBM Corp. and LoopBack contributors 2019,2020. All Rights Reserved.
+// Node module: @loopback/cli
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+'use strict';
+
+const debug = require('../../lib/debug')('import-lb3-models');
+const path = require('path');
+const {once} = require('events');
+
+module.exports = {
+  loadLb3App,
+};
+
+// TODO: do we want to share this code with `Lb3AppBooter.loadAndBootTheApp`?
+async function loadLb3App(dir) {
+  debug('Loading LB3 app from', dir);
+  const lb3App = require(path.resolve(dir));
+
+  debug(
+    'If your LB3 app does not boot correctly then make sure it is using loopback-boot version 3.2.1 or higher.',
+  );
+
+  if (lb3App.booting) {
+    debug('  waiting for boot process to finish');
+    // Wait until the legacy LB3 app boots
+    await once(lb3App, 'booted');
+  }
+  return lb3App;
+}

package/generators/import-lb3-models/migrate-model.js

@@ -0,0 +1,249 @@
+// Copyright IBM Corp. and LoopBack contributors 2019,2020. All Rights Reserved.
+// Node module: @loopback/cli
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+'use strict';
+
+const {
+  validateClassName,
+  logNamingIssues,
+  pascalCase,
+  stringifyModelSettings,
+} = require('../../lib/utils');
+const {sanitizeProperty} = require('../../lib/model-discoverer');
+const {
+  createPropertyTemplateData,
+  findBuiltinType,
+} = require('../model/property-definition');
+const chalk = require('chalk');
+const {isDeepStrictEqual} = require('util');
+
+module.exports = {
+  importLb3ModelDefinition,
+};
+
+/**
+ * Convert definition of a LB3 model into template data used by
+ * LB4 model generator.
+ *
+ * @param {Function} modelCtor LB3 model class
+ * @param {(msg: string, ...args: any) => void} log Logging function
+ * @returns {object} Template data for model source file template
+ */
+function importLb3ModelDefinition(modelCtor, log) {
+  const modelName = modelCtor.modelName;
+  const result = validateClassName(modelName);
+  if (!result) {
+    const err = new Error(
+      `Cannot import model: the name ${modelName} is not valid. ${result}`,
+    );
+    err.exit = true;
+    throw err;
+  }
+
+  logNamingIssues(modelName, log);
+
+  const baseDefinition = modelCtor.base.definition;
+  const baseProps = {...baseDefinition.properties};
+
+  // Core LB3 models like PersistedModel come with an id property that's
+  // injected by juggler. We don't want to inherit that property, because
+  // in LB4, we want models to define the id property explicitly.
+  if (isCoreModel(modelCtor.base)) {
+    delete baseProps.id;
+  }
+
+  const templateData = {
+    name: modelName,
+    className: pascalCase(modelName),
+    ...migrateBaseClass(modelCtor.settings.base),
+    properties: migrateModelProperties(
+      modelCtor.definition.properties,
+      baseProps,
+    ),
+    settings: migrateModelSettings(
+      modelCtor.definition.settings,
+      baseDefinition.settings,
+      log,
+    ),
+  };
+
+  const settings = templateData.settings;
+  delete settings.base; // already handled by migrateBaseClass
+  templateData.allowAdditionalProperties = !settings.strict;
+  templateData.modelSettings = stringifyModelSettings(settings);
+
+  return templateData;
+}
+
+function migrateModelProperties(properties = {}, inherited = {}) {
+  const templateData = {};
+
+  // In LB 3.x, primary keys are typically contributed by connectors later in
+  // the startup process, therefore they end up at the end of the property list.
+  // Here we create placeholder entries for PKs to get them generated first.
+  Object.keys(properties)
+    .filter(p => !!properties[p].id)
+    .forEach(pk => {
+      templateData[pk] = null;
+    });
+
+  for (const prop in properties) {
+    const propDef = properties[prop];
+
+    // Skip the property if it was inherited from the base model (the parent)
+    const baseProp = inherited[prop];
+    if (baseProp && isDeepStrictEqual(propDef, baseProp)) {
+      delete templateData[prop];
+      continue;
+    }
+
+    const def = migratePropertyDefinition(propDef);
+    templateData[prop] = createPropertyTemplateData(def);
+  }
+
+  return templateData;
+}
+
+function migratePropertyDefinition(lb3PropDef) {
+  const def = {...lb3PropDef};
+
+  if (!Array.isArray(def.type)) {
+    // scalar type
+    def.type = migratePropertyType(def.type);
+  } else {
+    // array type - conversion is slightly more complex
+    def.itemType = migratePropertyType(def.type[0]);
+    def.type = 'array';
+
+    // workaround for a weird behavior of LB3
+    if (0 in def && def[0] === def.itemType) {
+      delete def[0];
+    }
+  }
+
+  if (def.updateOnly === false) {
+    // updateOnly is disabled by default, no need to specify "false" value
+    delete def.updateOnly;
+  }
+  sanitizeProperty(def);
+  return def;
+}
+
+function migratePropertyType(typeDef) {
+  if (typeof typeDef === 'function') {
+    typeDef = typeDef.name.toString();
+  }
+
+  const builtin = findBuiltinType(typeDef);
+  if (builtin) typeDef = builtin;
+
+  // TODO: handle anonymous object types (nested properties)
+
+  return typeDef;
+}
+
+const BUILTIN_BASE_MODELS = {
+  Model: 'Model',
+  PersistedModel: 'Entity',
+  KeyValueModel: 'KeyValueModel',
+};
+
+function migrateBaseClass(base) {
+  const baseModelName = base.modelName || base.name || base;
+  if (baseModelName in BUILTIN_BASE_MODELS) {
+    return {
+      modelBaseClass: BUILTIN_BASE_MODELS[baseModelName],
+      isModelBaseBuiltin: true,
+    };
+  }
+
+  return {
+    modelBaseClass: baseModelName,
+    isModelBaseBuiltin: false,
+  };
+}
+
+function migrateModelSettings(settings = {}, inherited = {}, log) {
+  // Shallow-clone the object to prevent modification of external data
+  settings = {...settings};
+
+  // "strict" mode is enabled only when explicitly requested
+  // LB3 models allow additional properties by default
+  settings.strict = settings.strict === true;
+
+  // Remove settings inherited from the base model
+  for (const key in inherited) {
+    // Always emit the value of 'strict' setting, make it explicit
+    if (key === 'strict') continue;
+
+    if (isDeepStrictEqual(settings[key], inherited[key])) {
+      delete settings[key];
+    }
+  }
+
+  if (settings.forceId === 'auto') {
+    // The value 'auto' is used when a parent model wants to let the child
+    // model make the decision automatically, depending on whether the child
+    // model has a database-generated PK.
+    // See https://github.com/loopbackio/loopback-datasource-juggler/blob/15251880a1d07ccc2ca6d2dccdd065d00a7375eb/lib/model-builder.js#L347-L355
+    //
+    // Let's delete the flag from the generated model settings and
+    // leave it up to the runtime to decide.
+    delete settings.forceId;
+  }
+
+  // Notable settings that are not supported yet:
+  //   relations, acls, methods, mixins, validations
+
+  const relationNames = Object.keys(settings.relations || {});
+  if (relationNames.length) {
+    log(
+      chalk.yellow(
+        'Import of model relations is not supported yet. ' +
+          'Skipping the following relations: ' +
+          relationNames.join(', '),
+      ),
+    );
+  }
+  delete settings.relations;
+
+  const unsupportedSettings = [];
+  if ((settings.acls || []).length) {
+    unsupportedSettings.push('acls');
+  }
+  delete settings.acls;
+
+  for (const k of ['methods', 'mixins', 'validations']) {
+    if (k in settings && Object.keys(settings[k]).length) {
+      unsupportedSettings.push(k);
+    }
+    delete settings[k];
+  }
+
+  if (unsupportedSettings.length) {
+    log(
+      chalk.yellow(
+        'Ignoring the following unsupported settings: ' +
+          unsupportedSettings.join(', '),
+      ),
+    );
+  }
+
+  if (
+    typeof settings.hiddenProperties === 'object' &&
+    Object.keys(settings.hiddenProperties).length === 0
+  ) {
+    delete settings.hiddenProperties;
+  }
+
+  return settings;
+}
+
+function isCoreModel(modelCtor) {
+  const name = modelCtor.modelName;
+  return (
+    name === 'Model' || name === 'PersistedModel' || name === 'KeyValueModel'
+  );
+}

package/generators/import-lb3-models/model-names.js

@@ -0,0 +1,32 @@
+// Copyright IBM Corp. and LoopBack contributors 2019. All Rights Reserved.
+// Node module: @loopback/cli
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+'use strict';
+
+module.exports = {
+  canImportModelName,
+};
+
+// List of built-in LB models to exclude from the prompt
+const EXCLUDED_MODEL_NAMES = [
+  // base models
+  'Model',
+  'PersistedModel',
+  'KeyValueModel',
+  // change tracking & replication
+  'Change',
+  'Checkpoint',
+  // Email - a dummy model used to attach email-connector methods only
+  'Email',
+];
+
+function canImportModelName(name) {
+  if (EXCLUDED_MODEL_NAMES.includes(name)) return false;
+  // TODO: find out where are anonymous models coming from
+  // (perhaps from object types defined inside property definitions?)
+  // and add test cases to verify that we are handling those scenarios correctly
+  if (name.startsWith('AnonymousModel_')) return false;
+  return true;
+}

package/generators/interceptor/index.js

@@ -0,0 +1,178 @@
+// Copyright IBM Corp. and LoopBack contributors 2019,2020. All Rights Reserved.
+// Node module: @loopback/cli
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+// no translation: Interceptor
+'use strict';
+const ArtifactGenerator = require('../../lib/artifact-generator');
+const debug = require('../../lib/debug')('interceptor-generator');
+const inspect = require('util').inspect;
+const path = require('path');
+const utils = require('../../lib/utils');
+
+const SCRIPT_TEMPLATE = 'interceptor-template.ts.ejs';
+const g = require('../../lib/globalize');
+
+module.exports = class InterceptorGenerator extends ArtifactGenerator {
+  // Note: arguments and options should be defined in the constructor.
+  constructor(args, opts) {
+    super(args, opts);
+  }
+
+  _setupGenerator() {
+    this.option('global', {
+      description: g.f('Flag to indicate a global interceptor'),
+      required: false,
+      type: Boolean,
+    });
+
+    this.option('group', {
+      description: g.f('Group name for ordering the global interceptor'),
+      required: false,
+      type: String,
+    });
+
+    this.artifactInfo = {
+      type: 'interceptor',
+      rootDir: utils.sourceRootDir,
+    };
+
+    this.artifactInfo.outDir = path.resolve(
+      this.artifactInfo.rootDir,
+      utils.interceptorsDir,
+    );
+
+    this.artifactInfo.defaultTemplate = SCRIPT_TEMPLATE;
+
+    return super._setupGenerator();
+  }
+
+  setOptions() {
+    return super.setOptions();
+  }
+
+  checkLoopBackProject() {
+    if (this.shouldExit()) return;
+    return super.checkLoopBackProject();
+  }
+
+  /**
+   * Ask for Service Name
+   */
+  async promptArtifactName() {
+    debug('Prompting for interceptor name');
+    if (this.shouldExit()) return;
+
+    if (this.options.name) {
+      Object.assign(this.artifactInfo, {name: this.options.name});
+    }
+
+    const prompts = [
+      {
+        type: 'input',
+        name: 'name',
+        // capitalization
+        message: g.f('%s name:', utils.toClassName(this.artifactInfo.type)),
+        when: !this.artifactInfo.name,
+        validate: utils.validateClassName,
+      },
+    ];
+    return this.prompt(prompts).then(props => {
+      Object.assign(this.artifactInfo, props);
+      return props;
+    });
+  }
+
+  async promptGlobal() {
+    debug('Prompting for global interceptor flag');
+    if (this.shouldExit()) return;
+
+    if (this.options.global != null) {
+      Object.assign(this.artifactInfo, {isGlobal: !!this.options.global});
+      return;
+    }
+
+    // --group hints global
+    if (this.options.group != null) {
+      Object.assign(this.artifactInfo, {isGlobal: true});
+      return;
+    }
+
+    const prompts = [
+      {
+        type: 'confirm',
+        name: 'isGlobal',
+        message: g.f('Is it a global interceptor?'),
+        default: true,
+      },
+    ];
+    return this.prompt(prompts).then(props => {
+      Object.assign(this.artifactInfo, props);
+      return props;
+    });
+  }
+
+  async promptInterceptorGroup() {
+    if (!this.artifactInfo.isGlobal) return;
+    debug('Prompting for global interceptor group');
+    if (this.shouldExit()) return;
+
+    if (this.options.group) {
+      Object.assign(this.artifactInfo, {group: this.options.group});
+      return;
+    }
+
+    const note = g.f(
+      'Global interceptors are sorted by the order of an array of' +
+        ' group names bound to ContextBindings.GLOBAL_INTERCEPTOR_ORDERED_GROUPS.' +
+        ' See https://loopback.io/doc/en/lb4/Interceptors.html#order-of-invocation-for-interceptors.',
+    );
+
+    this.log();
+    this.log(note);
+    this.log();
+
+    const prompts = [
+      {
+        type: 'input',
+        name: 'group',
+        // capitalization
+        message: g.f("Group name for the global interceptor: ('')"),
+      },
+    ];
+    return this.prompt(prompts).then(props => {
+      Object.assign(this.artifactInfo, props);
+      return props;
+    });
+  }
+
+  scaffold() {
+    if (this.shouldExit()) return false;
+
+    // Setting up data for templates
+    this.artifactInfo.className =
+      utils.toClassName(this.artifactInfo.name) + 'Interceptor';
+    this.artifactInfo.fileName = utils.toFileName(this.artifactInfo.name);
+
+    Object.assign(this.artifactInfo, {
+      outFile: utils.getInterceptorFileName(this.artifactInfo.name),
+    });
+
+    const source = this.templatePath(this.artifactInfo.defaultTemplate);
+
+    const dest = this.destinationPath(
+      path.join(this.artifactInfo.outDir, this.artifactInfo.outFile),
+    );
+
+    debug(`artifactInfo: ${inspect(this.artifactInfo)}`);
+    debug(`Copying artifact to: ${dest}`);
+
+    this.copyTemplatedFiles(source, dest, this.artifactInfo);
+    return;
+  }
+
+  async end() {
+    await super.end();
+  }
+};