@azure-tools/typespec-ts 0.54.0 → 0.54.2

package/src/rlc-common/helpers/type-util.ts

@@ -0,0 +1,166 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { Schema } from "../interfaces.js";
+
+export function isRecord(type: string) {
+  return /^Record<([a-zA-Z]+),(\s*)(?<type>.+)>$/.test(type);
+}
+
+export function getRecordType(type: string) {
+  return /^Record<([a-zA-Z]+),(\s*)(?<type>.+)>$/.exec(type)?.groups?.["type"];
+}
+
+export function isArray(type: string) {
+  return isArrayObject(type) || isNativeArray(type);
+}
+
+export function isArrayObject(type: string) {
+  return /(^Array<(.+)>$)/g.test(type);
+}
+
+export function getArrayObjectType(type: string) {
+  return /^Array<(?<type>.+)>$/g.exec(type)?.groups?.["type"];
+}
+
+export function isNativeArray(type: string) {
+  return /(^.+)\[\]$/g.test(type);
+}
+
+export function getNativeArrayType(type: string) {
+  return /(?<type>.+)\[\]/g.exec(type)?.groups?.["type"];
+}
+
+export function isUnion(type: string) {
+  const members = type.split("|").map((m) => m.trim());
+  return members.length > 1 && !isStringLiteral(type) && !isRecord(type);
+}
+
+export function getUnionType(type: string) {
+  const firstMember = type.split("|").map((m) => m.trim())[0];
+  if (firstMember === undefined) {
+    return type;
+  }
+  return leaveBracket(firstMember);
+}
+
+export function leaveBracket(type: string) {
+  if (!type || type.length < 2) {
+    return type;
+  } else if (type.startsWith("(") && type.endsWith(")")) {
+    return type.slice(1, type.length - 1);
+  }
+  return type;
+}
+
+export function leaveStringQuotes(str: string) {
+  if (isStringLiteral(str)) {
+    return str.slice(1, str.length - 1);
+  }
+  return str;
+}
+
+export enum TypeScriptType {
+  string,
+  date,
+  number,
+  boolean,
+  constant,
+  record,
+  array,
+  object,
+  union,
+  unknown,
+  enum,
+}
+
+export function toTypeScriptTypeFromSchema(schema: Schema): TypeScriptType | undefined {
+  schema.type = schema.type.trim();
+  if (
+    schema.type === "string" &&
+    schema.typeName === "Date | string" &&
+    schema.outputTypeName === "string"
+  ) {
+    return TypeScriptType.date;
+  } else if (schema.enum && schema.enum.length > 0) {
+    if (schema.type === "union" || schema.type === "object") {
+      // Include both union and named union
+      return TypeScriptType.union;
+    } else {
+      // Include both extensible and fixed enum
+      return TypeScriptType.enum;
+    }
+  } else if (schema.isConstant === true || isConstant(schema.typeName ?? schema.type)) {
+    return TypeScriptType.constant;
+  } else if (schema.type === "number") {
+    return TypeScriptType.number;
+  } else if (schema.type === "boolean") {
+    return TypeScriptType.boolean;
+  } else if (schema.type === "string") {
+    return TypeScriptType.string;
+  } else if (schema.type === "unknown") {
+    return TypeScriptType.unknown;
+  } else if (schema.type === "dictionary") {
+    return TypeScriptType.record;
+  } else if (schema.type === "array") {
+    return TypeScriptType.array;
+  } else if (schema.type === "object") {
+    return TypeScriptType.object;
+  }
+  return undefined;
+}
+
+export function toTypeScriptTypeFromName(typeName: string): TypeScriptType | undefined {
+  typeName = typeName.trim();
+  if (typeName === "Date") {
+    return TypeScriptType.date;
+  } else if (typeName === "string") {
+    return TypeScriptType.string;
+  } else if (typeName === "number") {
+    return TypeScriptType.number;
+  } else if (typeName === "boolean") {
+    return TypeScriptType.boolean;
+  } else if (typeName === "unknown") {
+    return TypeScriptType.unknown;
+  } else if (isConstant(typeName)) {
+    return TypeScriptType.constant;
+  } else if (isRecord(typeName)) {
+    return TypeScriptType.record;
+  } else if (isArray(typeName)) {
+    return TypeScriptType.array;
+  } else if (isUnion(typeName)) {
+    return TypeScriptType.union;
+  }
+  return undefined;
+}
+
+export function isConstant(typeName: string) {
+  return (
+    ["never", "null"].includes(typeName) ||
+    isBoolLiteral(typeName) ||
+    isNumericLiteral(typeName) ||
+    isStringLiteral(typeName)
+  );
+}
+
+export function isNumericLiteral(str: string) {
+  if (typeof str !== "string") return false;
+  return !isNaN(Number(str)) && !isNaN(parseFloat(str));
+}
+
+export function isBoolLiteral(str: string) {
+  return str === "true" || str === "false";
+}
+
+export function isStringLiteral(type: string) {
+  if (type.length < 2) {
+    return false;
+  }
+  const first = type[0];
+  const lastPos = type.length - 1;
+  return (
+    first === type[lastPos] &&
+    (first === '"' || first === "'") &&
+    type.indexOf(first, 1) === lastPos
+  );
+}

package/src/rlc-common/helpers/value-generation-util.ts

@@ -0,0 +1,234 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { getImmediateParentsNames } from "../build-object-types.js";
+import {
+  ArraySchema,
+  DictionarySchema,
+  ObjectSchema,
+  Schema,
+  SchemaContext,
+} from "../interfaces.js";
+import {
+  TypeScriptType,
+  getArrayObjectType,
+  getNativeArrayType,
+  getRecordType,
+  getUnionType,
+  isArrayObject,
+  isNativeArray,
+  leaveBracket,
+  leaveStringQuotes,
+  toTypeScriptTypeFromName,
+  toTypeScriptTypeFromSchema,
+} from "./type-util.js";
+
+/**
+ * Generate parameter type value for the given type and parameter name
+ * @param type the typescript type
+ * @param parameterName the parameter name
+ * @param schemaMap the schema info to help generate the value
+ * @param path optional path to help detect self reference
+ * @param _allowMockValue the flag to indicate whether to allow mock value, currently we always generate mock value
+ * @returns
+ */
+export function generateParameterTypeValue(
+  type: string,
+  parameterName: string,
+  schemaMap: Map<string, Schema>,
+  path: Set<string> = new Set(),
+  _allowMockValue = true,
+): string | undefined {
+  type = leaveBracket(type?.trim());
+  let tsType: TypeScriptType | undefined;
+  // Give priority to suggest the ts-type from schema
+  if (schemaMap.has(type)) {
+    tsType = toTypeScriptTypeFromSchema(schemaMap.get(type)!);
+  }
+  // Fallback to suggest ts-type from the type iteself
+  if (!tsType) {
+    tsType = toTypeScriptTypeFromName(type);
+  }
+  switch (tsType) {
+    case TypeScriptType.string:
+      return `"{Your ${leaveStringQuotes(parameterName)}}"`;
+    case TypeScriptType.number:
+      return "123";
+    case TypeScriptType.boolean:
+      return "true";
+    case TypeScriptType.date:
+      return "new Date()";
+    case TypeScriptType.unknown:
+      return `"Unknown Type"`;
+    case TypeScriptType.object: {
+      return generateObjectValues(type, parameterName, schemaMap, path);
+    }
+    case TypeScriptType.array: {
+      return generateArrayValues(type, parameterName, schemaMap, path);
+    }
+    case TypeScriptType.record: {
+      return generateRecordValues(type, parameterName, schemaMap, path);
+    }
+    case TypeScriptType.enum: {
+      return mockEnumValues(type, parameterName, schemaMap, path);
+    }
+    case TypeScriptType.union: {
+      return mockUnionValues(type, parameterName, schemaMap, path);
+    }
+    case TypeScriptType.constant:
+      return type;
+  }
+  return `undefined /**FIXME */`;
+}
+
+function mockEnumValues(
+  type: string,
+  parameterName: string,
+  schemaMap: Map<string, Schema>,
+  path: Set<string> = new Set(),
+) {
+  const schema = schemaMap.get(type);
+  if (schema && schema.enum && schema.enum.length > 0) {
+    return schema.enum[0].type;
+  }
+  return generateParameterTypeValue(getUnionType(type), parameterName, schemaMap, path);
+}
+
+function mockUnionValues(
+  type: string,
+  parameterName: string,
+  schemaMap: Map<string, Schema>,
+  path: Set<string> = new Set(),
+) {
+  const schema = schemaMap.get(type);
+  if (schema && schema.enum && schema.enum.length > 0) {
+    addToSchemaMap(schemaMap, schema.enum[0]);
+    return generateParameterTypeValue(
+      getAccurateTypeName(schema.enum[0]) ?? schema.enum[0],
+      parameterName,
+      schemaMap,
+      path,
+    );
+  }
+  return generateParameterTypeValue(getUnionType(type), parameterName, schemaMap, path);
+}
+
+function generateRecordValues(
+  type: string,
+  parameterName: string,
+  schemaMap: Map<string, Schema>,
+  path: Set<string> = new Set(),
+) {
+  let recordType = getRecordType(type);
+  const schema = schemaMap.get(type) as DictionarySchema;
+  if (schema && schema.additionalProperties) {
+    recordType = getAccurateTypeName(schema.additionalProperties);
+    addToSchemaMap(schemaMap, schema.additionalProperties);
+  }
+
+  return recordType
+    ? `{"key": ${generateParameterTypeValue(recordType, parameterName, schemaMap, path)}}`
+    : `{}`;
+}
+
+function generateArrayValues(
+  type: string,
+  parameterName: string,
+  schemaMap: Map<string, Schema>,
+  path: Set<string> = new Set(),
+) {
+  let arrayType;
+  const schema = schemaMap.get(type) as ArraySchema;
+  if (schema && schema.items) {
+    arrayType = getAccurateTypeName(schema.items);
+    addToSchemaMap(schemaMap, schema.items);
+  } else if (isArrayObject(type)) {
+    arrayType = getArrayObjectType(type);
+  } else if (isNativeArray(type)) {
+    arrayType = getNativeArrayType(type);
+  }
+  const itemValue = arrayType
+    ? generateParameterTypeValue(arrayType, parameterName, schemaMap, path)
+    : undefined;
+  return itemValue ? `[${itemValue}]` : `[]`;
+}
+
+function generateObjectValues(
+  type: string,
+  _parameterName: string,
+  schemaMap: Map<string, Schema>,
+  path: Set<string> = new Set(),
+) {
+  if (path.has(type)) {
+    // skip generating if self referenced
+    return `{} as any /**FIXME */`;
+  }
+  path.add(type);
+  // Extract all properties from the schema
+  const allProperties = getAllProperties(schemaMap.get(type), schemaMap);
+  const values = extractObjectProperties(allProperties, schemaMap, path);
+
+  path.delete(type);
+  return `{${values.join(", ")}}`;
+}
+
+function getAllProperties(
+  schema?: ObjectSchema,
+  schemaMap: Map<string, Schema> = new Map(),
+): Map<string, Schema> {
+  const propertiesMap: Map<string, Schema> = new Map();
+  if (!schema) {
+    return new Map();
+  }
+  getImmediateParentsNames(schema, [SchemaContext.Input])?.forEach((p) => {
+    const parentProperties = getAllProperties(schemaMap.get(p), schemaMap);
+    for (const prop of parentProperties.keys()) {
+      propertiesMap.set(prop, parentProperties.get(prop)!);
+    }
+  });
+  for (const prop in schema.properties) {
+    const propValue = schema.properties[prop];
+    if (propValue) {
+      propertiesMap.set(prop, propValue);
+    }
+  }
+  return propertiesMap;
+}
+
+function extractObjectProperties(
+  properties: Map<string, Schema>,
+  schemaMap: Map<string, Schema> = new Map(),
+  path: Set<string> = new Set(),
+) {
+  const values: string[] = [];
+  for (const name of properties.keys()) {
+    const property = properties.get(name);
+    if (!property || property.readOnly || property.type === "never") {
+      continue;
+    }
+    addToSchemaMap(schemaMap, property);
+    values.push(
+      `${name}: ` +
+        generateParameterTypeValue(getAccurateTypeName(property), name, schemaMap, path),
+    );
+  }
+  return values;
+}
+
+function getAccurateTypeName(schema: Schema) {
+  // For extensible enum, fallback to use the type
+  if (schema.typeName === "string" && schema.enum && schema.enum.length > 0) {
+    return schema.type;
+  }
+  return schema.typeName ?? schema.type;
+}
+
+function addToSchemaMap(schemaMap: Map<string, Schema>, schema: Schema) {
+  const type = getAccurateTypeName(schema);
+  if (!type) {
+    return;
+  }
+  if (!schemaMap.has(type) && !["string", "number", "boolean"].includes(schema.type)) {
+    schemaMap.set(type, schema);
+  }
+}

package/src/rlc-common/index.ts

@@ -1,43 +1,43 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
+export * from "./build-client-definitions.js";
+export * from "./build-client.js";
+export * from "./build-index-file.js";
+export * from "./build-is-unexpected-helper.js";
+export * from "./build-logger.js";
+export * from "./build-paginate-helper.js";
+export * from "./build-parameter-types.js";
+export * from "./build-polling-helper.js";
+export * from "./build-response-types.js";
+export * from "./build-samples.js";
+export * from "./build-schema-type.js";
+export * from "./build-serialize-helper.js";
+export * from "./build-top-level-index-file.js";
+export * from "./helpers/api-version-util.js";
+export * from "./helpers/imports-util.js";
+export * from "./helpers/name-constructors.js";
+export * from "./helpers/name-utils.js";
+export * from "./helpers/operation-helpers.js";
+export * from "./helpers/package-util.js";
+export * from "./helpers/schema-helpers.js";
+export * from "./helpers/shortcut-methods.js";
+export * from "./helpers/value-generation-util.js";
 export * from "./interfaces.js";
-export * from "./buildClientDefinitions.js";
-export * from "./buildSchemaType.js";
-export * from "./buildClient.js";
-export * from "./helpers/nameConstructors.js";
-export * from "./buildResponseTypes.js";
-export * from "./helpers/shortcutMethods.js";
-export * from "./helpers/nameUtils.js";
-export * from "./helpers/operationHelpers.js";
-export * from "./helpers/valueGenerationUtil.js";
-export * from "./helpers/schemaHelpers.js";
-export * from "./buildParameterTypes.js";
-export * from "./buildIsUnexpectedHelper.js";
-export * from "./buildTopLevelIndexFile.js";
-export * from "./buildIndexFile.js";
-export * from "./buildPaginateHelper.js";
-export * from "./buildPollingHelper.js";
-export * from "./test/buildKarmaConfig.js";
-export * from "./test/buildRecordedClient.js";
-export * from "./test/buildSampleTest.js";
-export * from "./test/buildSnippets.js";
-export * from "./metadata/buildReadmeFile.js";
-export * from "./metadata/buildApiExtractorConfig.js";
-export * from "./metadata/buildPackageFile.js";
-export * from "./metadata/buildRollupConfig.js";
-export * from "./metadata/buildTsConfig.js";
-export * from "./metadata/buildWarpConfig.js";
-export * from "./metadata/buildESLintConfig.js";
-export * from "./metadata/buildLicenseFile.js";
-export * from "./metadata/buildChangelogFile.js";
-export * from "./metadata/buildVitestConfig.js";
-export * from "./metadata/buildSampleEnvFile.js";
-export * from "./buildSerializeHelper.js";
-export * from "./helpers/apiVersionUtil.js";
-export * from "./buildLogger.js";
-export * from "./buildSamples.js";
-export * from "./transformSampleGroups.js";
-export * from "./helpers/importsUtil.js";
-export * from "./metadata/buildTestConfig.js";
-export * from "./helpers/packageUtil.js";
+export * from "./metadata/build-api-extractor-config.js";
+export * from "./metadata/build-changelog-file.js";
+export * from "./metadata/build-es-lint-config.js";
+export * from "./metadata/build-license-file.js";
+export * from "./metadata/build-package-file.js";
+export * from "./metadata/build-readme-file.js";
+export * from "./metadata/build-rollup-config.js";
+export * from "./metadata/build-sample-env-file.js";
+export * from "./metadata/build-test-config.js";
+export * from "./metadata/build-ts-config.js";
+export * from "./metadata/build-vitest-config.js";
+export * from "./metadata/build-warp-config.js";
+export * from "./test/build-karma-config.js";
+export * from "./test/build-recorded-client.js";
+export * from "./test/build-sample-test.js";
+export * from "./test/build-snippets.js";
+export * from "./transform-sample-groups.js";

package/src/rlc-common/interfaces.ts

@@ -115,12 +115,7 @@ export interface ApiVersionInfo {
   required?: boolean;
 }
 
-export type ApiVersionPosition =
-  | "path"
-  | "query"
-  | "baseurl"
-  | "duplicate"
-  | "none";
+export type ApiVersionPosition = "path" | "query" | "baseurl" | "duplicate" | "none";
 export interface HelperFunctionDetails {
   hasPaging?: boolean;
   hasLongRunning?: boolean;
@@ -306,7 +301,7 @@ export enum SchemaContext {
   /** Schema is used as an output from an operation. */
   Output = "output",
   /** Schema is used as an exception from an operation. */
-  Exception = "exception"
+  Exception = "exception",
 }
 
 export interface Schema {
@@ -429,10 +424,7 @@ export type ContentBuilder = {
 
 export type SampleParameterPosition = "client" | "path" | "method";
 
-export type SampleParameters = Record<
-  SampleParameterPosition,
-  SampleParameter[]
->;
+export type SampleParameters = Record<SampleParameterPosition, SampleParameter[]>;
 
 export interface SampleParameter {
   name: string;

package/src/rlc-common/metadata/build-api-extractor-config.ts

@@ -0,0 +1,64 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { Project } from "ts-morph";
+import { RLCModel } from "../interfaces.js";
+
+export function buildApiExtractorConfig(model: RLCModel) {
+  const { packageDetails, isModularLibrary, generateTest, azureSdkForJs } = model.options || {};
+  const project = new Project();
+
+  let mainEntryPointFilePath = "dist/esm/index.d.ts";
+
+  if (model.options?.moduleKind === "cjs") {
+    mainEntryPointFilePath = `./types${generateTest || isModularLibrary ? "/src" : ""}/index.d.ts`;
+  }
+
+  const config = azureSdkForJs
+    ? {
+        extends: "../../../api-extractor-base.json",
+      }
+    : {
+        $schema:
+          "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+        mainEntryPointFilePath,
+        docModel: {
+          enabled: true,
+        },
+        apiReport: {
+          enabled: true,
+          reportFolder: "./review",
+        },
+        dtsRollup: {
+          enabled: true,
+          untrimmedFilePath: "",
+          publicTrimmedFilePath: `dist/${
+            packageDetails?.nameWithoutScope ?? packageDetails?.name
+          }.d.ts`,
+        },
+        messages: {
+          tsdocMessageReporting: {
+            default: {
+              logLevel: "none",
+            },
+          },
+          extractorMessageReporting: {
+            "ae-missing-release-tag": {
+              logLevel: "none",
+            },
+            "ae-unresolved-link": {
+              logLevel: "none",
+            },
+          },
+        },
+      };
+
+  const filePath = "api-extractor.json";
+  const configFile = project.createSourceFile(filePath, JSON.stringify(config), {
+    overwrite: true,
+  });
+  return {
+    path: filePath,
+    content: configFile.getFullText(),
+  };
+}

package/src/rlc-common/metadata/build-changelog-file.ts

@@ -0,0 +1,29 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { RLCModel } from "../interfaces.js";
+
+function getPackageVersion(model: RLCModel): string {
+  return model.options?.packageDetails?.version ?? "1.0.0-beta.1";
+}
+
+export function buildChangelogFile(model: RLCModel) {
+  const version = getPackageVersion(model);
+  const content = `# Release History
+
+## ${version} (Unreleased)
+
+### Features Added
+
+### Breaking Changes
+
+### Bugs Fixed
+
+### Other Changes
+`;
+
+  return {
+    path: "CHANGELOG.md",
+    content,
+  };
+}

package/src/rlc-common/metadata/build-es-lint-config.ts

@@ -0,0 +1,84 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { Project } from "ts-morph";
+import { RLCModel } from "../interfaces.js";
+
+const eslintConfig = `import azsdkEslint from "@azure/eslint-plugin-azure-sdk";
+
+export default azsdkEslint.config([
+  {
+    rules: {
+      "@azure/azure-sdk/ts-modules-only-named": "warn",
+      "@azure/azure-sdk/ts-package-json-types": "warn",
+      "@azure/azure-sdk/ts-package-json-engine-is-present": "warn",
+      "tsdoc/syntax": "warn"
+    }
+  }
+]);
+`;
+
+const esLintConfigEsm = `import azsdkEslint from "@azure/eslint-plugin-azure-sdk";
+
+export default azsdkEslint.config([
+  {
+    rules: {
+      "@azure/azure-sdk/ts-modules-only-named": "warn",
+      "@azure/azure-sdk/ts-package-json-types": "warn",
+      "@azure/azure-sdk/ts-package-json-engine-is-present": "warn",
+      "@azure/azure-sdk/ts-package-json-files-required": "off",
+      "@azure/azure-sdk/ts-package-json-main-is-cjs": "off",
+      "tsdoc/syntax": "warn"
+    }
+  }
+]);
+`;
+
+const esLintConfigEsmAzureSdk = `import azsdkEslint from "@azure/eslint-plugin-azure-sdk";
+
+export default [
+  ...azsdkEslint.config([
+    {
+      rules: {
+        "@azure/azure-sdk/ts-modules-only-named": "warn",
+        "@azure/azure-sdk/ts-package-json-types": "warn",
+        "@azure/azure-sdk/ts-package-json-engine-is-present": "warn",
+        "@azure/azure-sdk/ts-package-json-files-required": "off",
+        "@azure/azure-sdk/ts-package-json-main-is-cjs": "off",
+        "tsdoc/syntax": "warn"
+      }
+    },
+  ]),
+  {
+    files: ["src/**/*.ts", "src/**/*.mts", "test/**/*.ts"],
+    languageOptions: {
+      parserOptions: {
+        projectService: false,
+        project: "./config/tsconfig.lint.json",
+      },
+    },
+  },
+];
+`;
+
+export function buildEsLintConfig(model: RLCModel) {
+  if (model.options?.flavor !== "azure") {
+    return;
+  }
+  const project = new Project();
+  const filePath = "eslint.config.mjs";
+
+  let template: string;
+  if (model.options?.moduleKind === "esm") {
+    template = model.options?.azureSdkForJs ? esLintConfigEsmAzureSdk : esLintConfigEsm;
+  } else {
+    template = eslintConfig;
+  }
+  const configFile = project.createSourceFile("eslint.config.mjs", template, {
+    overwrite: true,
+  });
+  return {
+    path: filePath,
+    content: configFile.getFullText(),
+  };
+}