@strapi/typescript-utils 4.2.0-beta.4 → 4.3.0

package/lib/generators/schemas/attributes.js

@@ -0,0 +1,281 @@
+'use strict';
+
+const ts = require('typescript');
+const { factory } = require('typescript');
+const _ = require('lodash/fp');
+
+const { addImport } = require('./imports');
+const { getTypeNode, toTypeLiteral } = require('./utils');
+
+/**
+ * Generate a property signature node for a given attribute
+ *
+ * @param {object} schema
+ * @param {string} attributeName
+ * @param {object} attribute
+ * @returns {object}
+ */
+const attributeToPropertySignature = (schema, attributeName, attribute) => {
+  const baseType = getAttributeType(attributeName, attribute, schema.uid);
+
+  if (baseType === null) {
+    return null;
+  }
+
+  const modifiers = getAttributeModifiers(attribute);
+
+  const nodes = [baseType, ...modifiers];
+
+  return factory.createPropertySignature(
+    undefined,
+    factory.createIdentifier(attributeName),
+    undefined,
+    factory.createIntersectionTypeNode(nodes)
+  );
+};
+
+/**
+ * Create the base type node for a given attribute
+ *
+ * @param {string} attributeName
+ * @param {object} attribute
+ * @param {string} uid
+ * @returns {object}
+ */
+const getAttributeType = (attributeName, attribute, uid) => {
+  if (!Object.keys(mappers).includes(attribute.type)) {
+    console.warn(
+      `"${attributeName}" attribute from "${uid}" has an invalid type: "${attribute.type}"`
+    );
+
+    return null;
+  }
+
+  const [attributeType, typeParams] = mappers[attribute.type]({ uid, attribute, attributeName });
+
+  addImport(attributeType);
+
+  return getTypeNode(attributeType, typeParams);
+};
+
+/**
+ * Collect every modifier node from an attribute
+ *
+ * @param {object} attribute
+ * @returns {object[]}
+ */
+const getAttributeModifiers = attribute => {
+  const modifiers = [];
+
+  // Required
+  if (attribute.required) {
+    addImport('RequiredAttribute');
+
+    modifiers.push(factory.createTypeReferenceNode(factory.createIdentifier('RequiredAttribute')));
+  }
+
+  // Private
+  if (attribute.private) {
+    addImport('PrivateAttribute');
+
+    modifiers.push(factory.createTypeReferenceNode(factory.createIdentifier('PrivateAttribute')));
+  }
+
+  // Unique
+  if (attribute.unique) {
+    addImport('UniqueAttribute');
+
+    modifiers.push(factory.createTypeReferenceNode(factory.createIdentifier('UniqueAttribute')));
+  }
+
+  // Configurable
+  if (attribute.configurable) {
+    addImport('ConfigurableAttribute');
+
+    modifiers.push(
+      factory.createTypeReferenceNode(factory.createIdentifier('ConfigurableAttribute'))
+    );
+  }
+
+  // Plugin Options
+  if (!_.isEmpty(attribute.pluginOptions)) {
+    addImport('SetPluginOptions');
+
+    modifiers.push(
+      factory.createTypeReferenceNode(
+        factory.createIdentifier('SetPluginOptions'),
+        // Transform the pluginOptions object into an object literal expression
+        [toTypeLiteral(attribute.pluginOptions)]
+      )
+    );
+  }
+
+  // Min / Max
+  // TODO: Always provide a second type argument for min/max (ie: resolve the attribute scalar type with a `GetAttributeType<${mappers[attribute][0]}>` (useful for biginter (string values)))
+  if (!_.isNil(attribute.min) || !_.isNil(attribute.max)) {
+    addImport('SetMinMax');
+
+    const minMaxProperties = _.pick(['min', 'max'], attribute);
+
+    modifiers.push(
+      factory.createTypeReferenceNode(factory.createIdentifier('SetMinMax'), [
+        toTypeLiteral(minMaxProperties),
+      ])
+    );
+  }
+
+  // Min length / Max length
+  if (!_.isNil(attribute.minLength) || !_.isNil(attribute.maxLength)) {
+    addImport('SetMinMaxLength');
+
+    const minMaxProperties = _.pick(['minLength', 'maxLength'], attribute);
+
+    modifiers.push(
+      factory.createTypeReferenceNode(factory.createIdentifier('SetMinMaxLength'), [
+        toTypeLiteral(minMaxProperties),
+      ])
+    );
+  }
+
+  // Default
+  if (!_.isNil(attribute.default)) {
+    addImport('DefaultTo');
+
+    const defaultLiteral = toTypeLiteral(attribute.default);
+
+    modifiers.push(
+      factory.createTypeReferenceNode(factory.createIdentifier('DefaultTo'), [defaultLiteral])
+    );
+  }
+
+  return modifiers;
+};
+
+const mappers = {
+  string() {
+    return ['StringAttribute'];
+  },
+  text() {
+    return ['TextAttribute'];
+  },
+  richtext() {
+    return ['RichTextAttribute'];
+  },
+  password() {
+    return ['PasswordAttribute'];
+  },
+  email() {
+    return ['EmailAttribute'];
+  },
+  date() {
+    return ['DateAttribute'];
+  },
+  time() {
+    return ['TimeAttribute'];
+  },
+  datetime() {
+    return ['DateTimeAttribute'];
+  },
+  timestamp() {
+    return ['TimestampAttribute'];
+  },
+  integer() {
+    return ['IntegerAttribute'];
+  },
+  biginteger() {
+    return ['BigIntegerAttribute'];
+  },
+  float() {
+    return ['FloatAttribute'];
+  },
+  decimal() {
+    return ['DecimalAttribute'];
+  },
+  uid({ attribute, uid }) {
+    const { targetField, options } = attribute;
+
+    // If there are no params to compute, then return the attribute type alone
+    if (targetField === undefined && options === undefined) {
+      return ['UIDAttribute'];
+    }
+
+    const params = [];
+
+    // If the targetField property is defined, then reference it,
+    // otherwise, put `undefined` keyword type nodes as placeholders
+    const targetFieldParams = _.isUndefined(targetField)
+      ? [
+          factory.createKeywordTypeNode(ts.SyntaxKind.UndefinedKeyword),
+          factory.createKeywordTypeNode(ts.SyntaxKind.UndefinedKeyword),
+        ]
+      : [factory.createStringLiteral(uid), factory.createStringLiteral(targetField)];
+
+    params.push(...targetFieldParams);
+
+    // If the options property is defined, transform it to
+    // a type literral node and add it to the params list
+    if (_.isObject(options)) {
+      params.push(toTypeLiteral(options));
+    }
+
+    return ['UIDAttribute', params];
+  },
+  enumeration({ attribute }) {
+    const { enum: enumValues } = attribute;
+
+    return ['EnumerationAttribute', [toTypeLiteral(enumValues)]];
+  },
+  boolean() {
+    return ['BooleanAttribute'];
+  },
+  json() {
+    return ['JSONAttribute'];
+  },
+  media() {
+    return ['MediaAttribute'];
+  },
+  relation({ uid, attribute }) {
+    const { relation, target } = attribute;
+
+    const isMorphRelation = relation.toLowerCase().includes('morph');
+
+    if (isMorphRelation) {
+      return [
+        'RelationAttribute',
+        [factory.createStringLiteral(uid, true), factory.createStringLiteral(relation, true)],
+      ];
+    }
+
+    return [
+      'RelationAttribute',
+      [
+        factory.createStringLiteral(uid, true),
+        factory.createStringLiteral(relation, true),
+        factory.createStringLiteral(target, true),
+      ],
+    ];
+  },
+  component({ attribute }) {
+    const target = attribute.component;
+    const params = [factory.createStringLiteral(target, true)];
+
+    if (attribute.repeatable) {
+      params.push(factory.createTrue());
+    }
+
+    return ['ComponentAttribute', params];
+  },
+  dynamiczone({ attribute }) {
+    const componentsParam = factory.createTupleTypeNode(
+      attribute.components.map(component => factory.createStringLiteral(component))
+    );
+
+    return ['DynamicZoneAttribute', [componentsParam]];
+  },
+};
+
+module.exports = attributeToPropertySignature;
+
+module.exports.mappers = mappers;
+module.exports.getAttributeType = getAttributeType;
+module.exports.getAttributeModifiers = getAttributeModifiers;

package/lib/generators/schemas/global.js

@@ -0,0 +1,68 @@
+'use strict';
+
+const ts = require('typescript');
+const { factory } = require('typescript');
+
+const { getSchemaInterfaceName } = require('./utils');
+
+/**
+ * Generate the global module augmentation block
+ *
+ * @param {Array<{ schema: object; definition: ts.TypeNode }>} schemasDefinitions
+ * @returns {ts.ModuleDeclaration}
+ */
+const generateGlobalDefinition = (schemasDefinitions = []) => {
+  const properties = schemasDefinitions.map(schemaDefinitionToPropertySignature);
+
+  return factory.createModuleDeclaration(
+    undefined,
+    [factory.createModifier(ts.SyntaxKind.DeclareKeyword)],
+    factory.createIdentifier('global'),
+    factory.createModuleBlock([
+      factory.createModuleDeclaration(
+        undefined,
+        undefined,
+        factory.createIdentifier('Strapi'),
+        factory.createModuleBlock([
+          factory.createInterfaceDeclaration(
+            undefined,
+            undefined,
+            factory.createIdentifier('Schemas'),
+            undefined,
+            undefined,
+            properties
+          ),
+        ]),
+        ts.NodeFlags.Namespace |
+          ts.NodeFlags.ExportContext |
+          ts.NodeFlags.Ambient |
+          ts.NodeFlags.ContextFlags
+      ),
+    ]),
+    ts.NodeFlags.ExportContext |
+      ts.NodeFlags.GlobalAugmentation |
+      ts.NodeFlags.Ambient |
+      ts.NodeFlags.ContextFlags
+  );
+};
+
+/**
+ *
+ * @param {object} schemaDefinition
+ * @param {ts.InterfaceDeclaration} schemaDefinition.definition
+ * @param {object} schemaDefinition.schema
+ */
+const schemaDefinitionToPropertySignature = ({ schema }) => {
+  const { uid } = schema;
+
+  const interfaceTypeName = getSchemaInterfaceName(uid);
+
+  return factory.createPropertySignature(
+    undefined,
+    factory.createStringLiteral(uid, true),
+    undefined,
+    factory.createTypeReferenceNode(factory.createIdentifier(interfaceTypeName))
+  );
+};
+
+module.exports = { generateGlobalDefinition };

package/lib/generators/schemas/imports.js

@@ -0,0 +1,33 @@
+'use strict';
+
+const { factory } = require('typescript');
+
+const imports = [];
+
+module.exports = {
+  getImports() {
+    return imports;
+  },
+
+  addImport(type) {
+    const hasType = imports.includes(type);
+
+    if (!hasType) {
+      imports.push(type);
+    }
+  },
+
+  generateImportDefinition() {
+    const formattedImports = imports.map(key =>
+      factory.createImportSpecifier(false, undefined, factory.createIdentifier(key))
+    );
+
+    return factory.createImportDeclaration(
+      undefined,
+      undefined,
+      factory.createImportClause(false, undefined, factory.createNamedImports(formattedImports)),
+      factory.createStringLiteral('@strapi/strapi'),
+      undefined
+    );
+  },
+};

package/lib/generators/schemas/index.js

@@ -0,0 +1,185 @@
+'use strict';
+
+const path = require('path');
+
+const ts = require('typescript');
+const { factory } = require('typescript');
+
+const fp = require('lodash/fp');
+const fse = require('fs-extra');
+const prettier = require('prettier');
+const chalk = require('chalk');
+const CLITable = require('cli-table3');
+
+const { generateImportDefinition } = require('./imports');
+const { generateSchemaDefinition } = require('./schema');
+const { generateGlobalDefinition } = require('./global');
+const {
+  getAllStrapiSchemas,
+  getSchemaInterfaceName,
+  getSchemaModelType,
+  getDefinitionAttributesCount,
+} = require('./utils');
+
+const DEFAULT_OUT_FILENAME = 'schemas.d.ts';
+
+/**
+ * Generate type definitions for Strapi schemas
+ *
+ * @param {object} options
+ * @param {Strapi} options.strapi
+ * @param {{ distDir: string; appDir: string; }} options.dirs
+ * @param {string} [options.outDir]
+ * @param {string} [options.file]
+ * @param {boolean} [options.verbose]
+ */
+const generateSchemasDefinitions = async (options = {}) => {
+  const {
+    strapi,
+    outDir = process.cwd(),
+    file = DEFAULT_OUT_FILENAME,
+    verbose = false,
+    silent = false,
+  } = options;
+
+  const schemas = getAllStrapiSchemas(strapi);
+
+  const schemasDefinitions = Object.values(schemas).map(schema => ({
+    schema,
+    definition: generateSchemaDefinition(schema),
+  }));
+
+  const formattedSchemasDefinitions = schemasDefinitions.reduce((acc, def) => {
+    acc.push(
+      // Definition
+      def.definition,
+
+      // Add a newline between each interface declaration
+      factory.createIdentifier('\n')
+    );
+
+    return acc;
+  }, []);
+
+  const allDefinitions = [
+    // Imports
+    generateImportDefinition(),
+
+    // Add a newline after the import statement
+    factory.createIdentifier('\n'),
+
+    // Schemas
+    ...formattedSchemasDefinitions,
+
+    // Global
+    generateGlobalDefinition(schemasDefinitions),
+  ];
+
+  const output = emitDefinitions(allDefinitions);
+  const formattedOutput = await format(output);
+
+  const definitionFilepath = await saveDefinitionToFileSystem(outDir, file, formattedOutput);
+
+  logDebugInformation(schemasDefinitions, { filepath: definitionFilepath, verbose, silent });
+};
+
+const emitDefinitions = definitions => {
+  const nodeArray = factory.createNodeArray(definitions);
+
+  const sourceFile = ts.createSourceFile(
+    'placeholder.ts',
+    '',
+    ts.ScriptTarget.ESNext,
+    true,
+    ts.ScriptKind.TS
+  );
+
+  const printer = ts.createPrinter({ newLine: true, omitTrailingSemicolon: true });
+
+  return printer.printList(ts.ListFormat.MultiLine, nodeArray, sourceFile);
+};
+
+const saveDefinitionToFileSystem = async (dir, file, content) => {
+  const filepath = path.join(dir, file);
+
+  await fse.writeFile(filepath, content);
+
+  return filepath;
+};
+
+/**
+ * Format the given definitions.
+ * Uses the existing config if one is defined in the project.
+ *
+ * @param {string} content
+ * @returns {Promise<string>}
+ */
+const format = async content => {
+  const configFile = await prettier.resolveConfigFile();
+  const config = configFile
+    ? await prettier.resolveConfig(configFile)
+    : // Default config
+      {
+        singleQuote: true,
+        useTabs: false,
+        tabWidth: 2,
+      };
+
+  Object.assign(config, { parser: 'typescript' });
+
+  return prettier.format(content, config);
+};
+
+const logDebugInformation = (definitions, options = {}) => {
+  const { filepath, verbose, silent } = options;
+
+  if (verbose) {
+    const table = new CLITable({
+      head: [
+        chalk.bold(chalk.green('Model Type')),
+        chalk.bold(chalk.blue('UID')),
+        chalk.bold(chalk.blue('Type')),
+        chalk.bold(chalk.gray('Attributes Count')),
+      ],
+      colAligns: ['center', 'left', 'left', 'center'],
+    });
+
+    const sortedDefinitions = definitions.map(def => ({
+      ...def,
+      attributesCount: getDefinitionAttributesCount(def.definition),
+    }));
+
+    for (const { schema, attributesCount } of sortedDefinitions) {
+      const modelType = fp.upperFirst(getSchemaModelType(schema));
+      const interfaceType = getSchemaInterfaceName(schema.uid);
+
+      table.push([
+        chalk.greenBright(modelType),
+        chalk.blue(schema.uid),
+        chalk.blue(interfaceType),
+        chalk.grey(fp.isNil(attributesCount) ? 'N/A' : attributesCount),
+      ]);
+    }
+
+    // Table
+    console.log(table.toString());
+  }
+
+  if (!silent) {
+    // Metrics
+    console.log(
+      chalk.greenBright(
+        `Generated ${definitions.length} type definition for your Strapi application's schemas.`
+      )
+    );
+
+    // Filepath
+    const relativePath = path.relative(process.cwd(), filepath);
+
+    console.log(
+      chalk.grey(`The definitions file has been generated here: ${chalk.bold(relativePath)}`)
+    );
+  }
+};
+
+module.exports = generateSchemasDefinitions;

package/lib/generators/schemas/schema.js

@@ -0,0 +1,87 @@
+'use strict';
+
+const ts = require('typescript');
+const { factory } = require('typescript');
+const { isEmpty } = require('lodash/fp');
+
+const { getSchemaExtendsTypeName, getSchemaInterfaceName, toTypeLiteral } = require('./utils');
+const attributeToPropertySignature = require('./attributes');
+const { addImport } = require('./imports');
+
+/**
+ * Generate an interface declaration for a given schema
+ *
+ * @param {object} schema
+ * @returns {ts.InterfaceDeclaration}
+ */
+const generateSchemaDefinition = schema => {
+  const { uid } = schema;
+
+  // Resolve the different interface names needed to declare the schema's interface
+  const interfaceName = getSchemaInterfaceName(uid);
+  const parentType = getSchemaExtendsTypeName(schema);
+
+  // Make sure the extended interface are imported
+  addImport(parentType);
+
+  // Properties whose values can be mapped to a literal type expression
+  const literalPropertiesDefinitions = ['info', 'options', 'pluginOptions']
+    // Ignore non-existent or empty declarations
+    .filter(key => !isEmpty(schema[key]))
+    // Generate literal definition for each property
+    .map(generatePropertyLiteralDefinitionFactory(schema));
+
+  // Generate the `attributes` literal type definition
+  const attributesProp = generateAttributePropertySignature(schema);
+
+  // Merge every schema's definition in a single list
+  const schemaProperties = [...literalPropertiesDefinitions, attributesProp];
+
+  // Generate the schema's interface declaration
+  const schemaType = factory.createInterfaceDeclaration(
+    undefined,
+    [factory.createModifier(ts.SyntaxKind.ExportKeyword)],
+    factory.createIdentifier(interfaceName),
+    undefined,
+    [
+      factory.createHeritageClause(ts.SyntaxKind.ExtendsKeyword, [
+        factory.createIdentifier(parentType),
+      ]),
+    ],
+    schemaProperties
+  );
+
+  return schemaType;
+};
+
+/**
+ * Generate a property signature for the schema's `attributes` field
+ *
+ * @param {object} schema
+ * @returns {ts.PropertySignature}
+ */
+const generateAttributePropertySignature = schema => {
+  const { attributes } = schema;
+
+  const properties = Object.entries(attributes).map(([attributeName, attribute]) => {
+    return attributeToPropertySignature(schema, attributeName, attribute);
+  });
+
+  return factory.createPropertySignature(
+    undefined,
+    factory.createIdentifier('attributes'),
+    undefined,
+    factory.createTypeLiteralNode(properties)
+  );
+};
+
+const generatePropertyLiteralDefinitionFactory = schema => key => {
+  return factory.createPropertySignature(
+    undefined,
+    factory.createIdentifier(key),
+    undefined,
+    toTypeLiteral(schema[key])
+  );
+};
+
+module.exports = { generateSchemaDefinition };