@azure-tools/typespec-ts 0.29.0-alpha.20240626.1 → 0.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure-tools/typespec-ts",
-  "version": "0.29.0-alpha.20240626.1",
+  "version": "0.30.0",
   "description": "An experimental TypeSpec emitter for TypeScript RLC",
   "main": "dist/src/index.js",
   "type": "module",
@@ -17,7 +17,7 @@
   "author": "Jose Heredia <joheredi@microsoft.com>",
   "license": "MIT",
   "devDependencies": {
-    "@azure-rest/core-client": "^2.0.0",
+    "@azure-rest/core-client": "^2.1.0",
     "@azure-tools/cadl-ranch-expect": "^0.13.4",
     "@azure-tools/cadl-ranch-specs": "^0.33.4",
     "@azure-tools/cadl-ranch": "^0.12.8",
@@ -27,7 +27,7 @@
     "@azure-tools/typespec-client-generator-core": ">=0.43.0 <1.0.0",
     "@azure/abort-controller": "^2.1.2",
     "@azure/core-auth": "^1.6.0",
-    "@azure/core-lro": "3.0.0-beta.2",
+    "@azure/core-lro": "3.0.0",
     "@azure/core-paging": "^1.5.0",
     "@azure/core-rest-pipeline": "^1.14.0",
     "@azure/core-util": "^1.4.0",
@@ -70,7 +70,7 @@
     "@typespec/versioning": ">=0.57.0 <1.0.0"
   },
   "dependencies": {
-    "@azure-tools/rlc-common": "^0.29.0",
+    "@azure-tools/rlc-common": "^0.30.0",
     "fs-extra": "^11.1.0",
     "lodash": "^4.17.21",
     "prettier": "^3.1.0",

package/src/contextManager.ts

@@ -0,0 +1,99 @@
+import { Project, SourceFile } from "ts-morph";
+import { ModularMetaTree, RlcMetaTree } from "./metaTree.js";
+import { EmitContext } from "@typespec/compiler";
+import { SdkContext } from "@azure-tools/typespec-client-generator-core";
+
+/**
+ * Contexts Object Guidelines
+ * --------------------------
+ * The `Contexts` object contains various application-wide data that needs to be accessible across different parts of the program without the need to pass down props deeply.
+ *
+ * When to add a new context:
+ * - **Cross-Cutting Concerns**: Add a new context when the data or functionality is a cross-cutting concern used by multiple unrelated components or modules.
+ * - **Global State**: If the state needs to be globally accessible and mutable by different parts of the application, and does not belong to a specific component or module.
+ * - **Performance Optimization**: To avoid unnecessary compute or prop drilling that may lead to performance bottlenecks, especially when passing down props through many levels.
+ * - **Shared Resources**: For resources that are shared across various parts of the application, such as settings, configurations, or metadata.
+ *
+ * Remember, adding too many contexts can lead to complex dependencies and harder-to-maintain code. Always evaluate if the context is truly necessary or if there are better alternatives such as localized state management or passing props for simpler scenarios.
+ */
+type Contexts = {
+  rlcMetaTree: RlcMetaTree; // Context for RLC types metadata.
+  modularMetaTree: ModularMetaTree; // Context for modular types metadata.
+  outputProject: Project; // The TS-Morph root project context for code generation.
+  symbolMap: Map<string, SourceFile>; // Mapping of symbols to their corresponding source files.
+  emitContext: {
+    compilerContext: EmitContext;
+    tcgcContext: SdkContext;
+  };
+};
+
+type ContextKey = keyof Contexts;
+
+/**
+ * Manages shared contexts across the application to minimize prop drilling and enhance modularity.
+ * Implements the Singleton pattern to ensure there is a single instance of ContextManager.
+ */
+class ContextManager {
+  private static instance: ContextManager;
+  private contexts: Map<ContextKey, any> = new Map();
+
+  private constructor() {}
+
+  /**
+   * Retrieves the singleton instance of the ContextManager.
+   * @returns {ContextManager} The singleton instance.
+   */
+  public static getInstance(): ContextManager {
+    if (!ContextManager.instance) {
+      ContextManager.instance = new ContextManager();
+    }
+    return ContextManager.instance;
+  }
+
+  /**
+   * Sets a value for a specific context key.
+   * @param {ContextKey} key - The key of the context to set.
+   * @param {Contexts[K]} value - The value to set for the specified context.
+   */
+  public setContext<K extends ContextKey>(key: K, value: Contexts[K]): void {
+    this.contexts.set(key, value);
+  }
+
+  /**
+   * Retrieves the context value for a specific key.
+   * @param {ContextKey} key - The key of the context to retrieve.
+   * @returns {Contexts[K] | undefined} The value of the context if found, otherwise undefined.
+   */
+  public getContext<K extends ContextKey>(key: K): Contexts[K] | undefined {
+    return this.contexts.get(key) as Contexts[K] | undefined;
+  }
+}
+
+// Expose the singleton instance of the context manager.
+export const contextManager = ContextManager.getInstance();
+
+/**
+ * A utility function to use a context by key.
+ * @param {ContextKey} key - The key of the context to retrieve.
+ * @throws Will throw an error if the context is not found.
+ * @returns {Contexts[K]} The context value.
+ */
+export function useContext<K extends ContextKey>(key: K): Contexts[K] {
+  const context = contextManager.getContext(key);
+  if (!context) {
+    throw new Error(`Context ${key} not found`);
+  }
+  return context;
+}
+
+/**
+ * Provides a context with a value to be accessible across the program.
+ * @param {ContextKey} key - The key of the context to provide.
+ * @param {Contexts[K]} value - The value to set for the specified context.
+ */
+export function provideContext<K extends ContextKey>(
+  key: K,
+  value: Contexts[K]
+): void {
+  contextManager.setContext(key, value);
+}

package/src/index.ts

@@ -66,6 +66,8 @@ import { transformRLCOptions } from "./transform/transfromRLCOptions.js";
 import { getRLCClients } from "./utils/clientUtils.js";
 import { emitContentByBuilder, emitModels } from "./utils/emitUtil.js";
 import { GenerationDirDetail, SdkContext } from "./utils/interfaces.js";
+import { provideContext, useContext } from "./contextManager.js";
+import { emitSerializerHelpersFile } from "./modular/buildHelperSerializers.js";
 
 export * from "./lib.js";
 
@@ -79,6 +81,15 @@ export async function $onEmit(context: EmitContext) {
     string,
     RLCModel
   >();
+  provideContext("rlcMetaTree", new Map());
+  provideContext("symbolMap", new Map());
+  provideContext("modularMetaTree", new Map());
+  provideContext("outputProject", new Project());
+  provideContext("emitContext", {
+    compilerContext: context,
+    tcgcContext: dpgContext
+  });
+
   const rlcCodeModels: RLCModel[] = [];
   let modularCodeModel: ModularCodeModel;
   // 1. Enrich the dpg context with path detail and common options
@@ -173,7 +184,8 @@ export async function $onEmit(context: EmitContext) {
       // TODO: Emit modular parts of the library
       const modularSourcesRoot =
         dpgContext.generationPathDetail?.modularSourcesDir ?? "src";
-      const project = new Project();
+      const project = useContext("outputProject");
+      emitSerializerHelpersFile(project, modularSourcesRoot);
       modularCodeModel = emitCodeModel(
         dpgContext,
         serviceNameToRlcModelsMap,
@@ -302,7 +314,7 @@ export async function $onEmit(context: EmitContext) {
       );
 
       if (option.isModularLibrary) {
-        const project = new Project();
+        const project = useContext("outputProject");
         for (const file of project.getSourceFiles()) {
           await emitContentByBuilder(
             program,

package/src/metaTree.ts

@@ -0,0 +1,14 @@
+import { Schema as RlcType } from "@azure-tools/rlc-common";
+import { Type as ModularType } from "./modular/modularCodeModel.js";
+import { Type } from "@typespec/compiler";
+
+export interface RlcTypeMetadata {
+  rlcType: RlcType;
+}
+
+export interface ModularTypeMetadata {
+  modularType: ModularType;
+}
+
+export type RlcMetaTree = Map<Type, RlcTypeMetadata>;
+export type ModularMetaTree = Map<Type, ModularTypeMetadata>;

package/src/modular/buildClassicalClient.ts

@@ -142,7 +142,11 @@ function importAllModels(
     return;
   }
 
-  const exported = [...apiModels.getExportedDeclarations().keys()];
+  const exported = [...apiModels.getExportedDeclarations().keys()].filter(
+    (e) => {
+      return !e.startsWith("_");
+    }
+  );
 
   if (exported.length > 0) {
     clientFile.addImportDeclaration({

package/src/modular/buildCodeModel.ts

@@ -92,6 +92,7 @@ import {
 } from "../utils/modelUtils.js";
 import { getModelNamespaceName } from "../utils/namespaceUtils.js";
 import {
+  extractPagedMetadataNested,
   getOperationGroupName,
   getOperationName,
   isBinaryPayload,
@@ -113,6 +114,7 @@ import {
   Response,
   Type as HrlcType
 } from "./modularCodeModel.js";
+import { useContext } from "../contextManager.js";
 
 interface HttpServerParameter {
   type: "endpointPath";
@@ -308,6 +310,8 @@ function getType(
   type: EmitterType,
   options: { disableEffectiveModel?: boolean; usage?: UsageFlags } = {}
 ): any {
+  const modularMetatree = useContext("modularMetaTree");
+
   // don't cache simple type(string, int, etc) since decorators may change the result
   const enableCache = !isSimpleType(context.program, type);
   const effectiveModel =
@@ -322,6 +326,7 @@ function getType(
     }
   }
   let newValue: any;
+
   if (isEmptyAnonymousModel(type)) {
     // do not generate model for empty model, treat it as any
     newValue = { type: "any" };
@@ -332,6 +337,12 @@ function getType(
     newValue = applyEncoding(context.program, type, newValue);
   }
 
+  if (isTypespecType(type)) {
+    newValue.tcgcType = getClientType(context, type);
+    newValue.__raw = type;
+    modularMetatree.set(type, newValue);
+  }
+
   if (enableCache) {
     if (!options.disableEffectiveModel) {
       typesMap.set(effectiveModel, newValue);
@@ -352,7 +363,8 @@ function getType(
       }
     }
   } else {
-    const key = JSON.stringify(newValue);
+    const { __raw, tcgcType, ...keyableValue } = newValue;
+    const key = JSON.stringify(keyableValue);
     const value = simpleTypesMap.get(key);
     if (value) {
       newValue = value;
@@ -373,12 +385,14 @@ function getType(
       target: type
     });
   }
-  if (!["Credential", "CredentialTypeUnion"].includes(type.kind)) {
-    newValue.tcgcType = getClientType(context, type as Type);
-  }
+
   return newValue;
 }
 
+function isTypespecType(type: EmitterType): type is Type {
+  return type.kind !== "Credential" && type.kind !== "CredentialTypeUnion";
+}
+
 // To pass the yaml dump
 function getAddedOnVersion(p: Program, t: Type): string | undefined {
   return getAddedOnVersions(p, t)?.[0]?.value;
@@ -1022,9 +1036,11 @@ function emitModel(
         .join("") + "List";
   }
 
+  const page = extractPagedMetadataNested(context.program, type);
+  const isPaging = page && page.itemsSegments && page.itemsSegments.length > 0;
   return {
     type: "model",
-    name: modelName,
+    name: `${isPaging ? "_" : ""}${modelName}`,
     description: getDocStr(context.program, type),
     parents: baseModel ? [baseModel] : [],
     discriminatedSubtypes: [],
@@ -1342,7 +1358,7 @@ function emitUnion(
   usage: UsageFlags
 ): Record<string, any> {
   let sdkType = getSdkUnion(context, type);
-  const isNull = sdkType.kind === "nullable";
+  const isNull = false;
   if (sdkType.kind === "nullable") {
     sdkType = sdkType.type;
   }

package/src/modular/buildHelperSerializers.ts

@@ -0,0 +1,71 @@
+import { Project } from "ts-morph";
+import { useContext } from "../contextManager.js";
+const serializeRecordFunction = {
+  symbol: "serializeRecord",
+  content: `
+export function serializeRecord<
+  T extends string | number | boolean | Date | null,
+  R
+>(item: Record<string, T>): Record<string, R>;
+export function serializeRecord<T, R>(
+  item: Record<string, T>,
+  serializer: (item: T) => R
+): Record<string, R>;
+export function serializeRecord<T, R>(
+  item: Record<string, T>,
+  serializer?: (item: T) => R
+): Record<string, R> {
+  return Object.keys(item).reduce(
+    (acc, key) => {
+      if (isSupportedRecordType(item[key])) {
+        acc[key] = item[key] as any;
+      } else if (serializer) {
+        const value = item[key];
+        if (value !== undefined) {
+          acc[key] = serializer(value);
+        }
+      } else {
+        console.warn(\`Don't know how to serialize \${item[key]}\`);
+        acc[key] = item[key] as any;
+      }
+      return acc;
+    },
+    {} as Record<string, R>
+  );
+}`
+};
+const isRecordElementSupportedFunction = {
+  symbol: "isSupportedRecordType",
+  content: `
+function isSupportedRecordType(t: any) {
+  return ["number", "string", "boolean", "null"].includes(typeof t) || t instanceof Date;
+}
+`
+};
+
+export function emitSerializerHelpersFile(
+  project: Project,
+  srcPath: string = "src"
+) {
+  const symbolMap = useContext("symbolMap");
+  const sourceFile = project.createSourceFile(
+    `${srcPath}/helpers/serializerHelpers.ts`,
+    "",
+    {
+      overwrite: true
+    }
+  );
+
+  if (!symbolMap.has(serializeRecordFunction.symbol)) {
+    symbolMap.set(serializeRecordFunction.symbol, sourceFile);
+  }
+
+  if (!symbolMap.has(isRecordElementSupportedFunction.symbol)) {
+    symbolMap.set(isRecordElementSupportedFunction.symbol, sourceFile);
+  }
+
+  sourceFile.addStatements([
+    serializeRecordFunction.content,
+    isRecordElementSupportedFunction.content
+  ]);
+}

package/src/modular/buildOperations.ts

@@ -27,7 +27,7 @@ import {
   getSendPrivateFunction as experimentalGetSendPrivateFunction
 } from "./serialization/operationHelpers.js";
 import { SerializerMap } from "./serialization/util.js";
-
+import { addImportBySymbol } from "../utils/importHelper.js";
 /**
  * This function creates a file under /api for each operation group.
  * If there is no operation group in the TypeSpec program, we create a single
@@ -195,7 +195,10 @@ export function buildOperationFiles(
         ]
       }
     ]);
+
     addImportsToFiles(codeModel.runtimeImports, operationGroupFile);
+    addImportBySymbol("serializeRecord", operationGroupFile);
+
     operationGroupFile.fixMissingImports();
     // have to fixUnusedIdentifiers after everything get generated.
     operationGroupFile.fixUnusedIdentifiers();
@@ -222,6 +225,9 @@ export function importModels(
   const models: string[] = [];
 
   for (const [name] of modelsFile?.getExportedDeclarations().entries() ?? []) {
+    if (name.startsWith("_")) {
+      continue;
+    }
     models.push(name);
   }
 

package/src/modular/buildSerializeUtils.ts

@@ -25,7 +25,7 @@ import { ModularCodeModel, Type } from "./modularCodeModel.js";
  */
 export function buildSerializeUtils(model: ModularCodeModel) {
   const serializeUtilFiles = [];
-  for (const serializeType of ["serialize", "deserialize"]) {
+  for (const serializeType of ["deserialize"]) {
     const usageCondition =
       serializeType === "serialize" ? UsageFlags.Input : UsageFlags.Output;
     const specialUnions = model.types.filter(
@@ -107,7 +107,8 @@ export function buildSerializeUtils(model: ModularCodeModel) {
     });
     addImportsToFiles(model.runtimeImports, utilsFile, {
       rlcIndex: "../rest/index.js",
-      modularModel: "../models/models.js"
+      modularModel: "../models/models.js",
+      coreUtil: "@azure/core-util"
     });
     serializeUtilFiles.push(utilsFile);
   }
@@ -517,11 +518,14 @@ function getTypeSerializeFunction(
       returnType: typeName
     };
     if (type.properties) {
-      statements.push(
-        `return {${getRequestModelMapping(type, "obj", runtimeImports).join(
-          ", "
-        )}};`
+      const { propertiesStr } = getRequestModelMapping(
+        type,
+        "obj",
+        runtimeImports
       );
+      statements.push(`return {
+        ${propertiesStr.join(", ")}
+        };`);
     } else {
       statements.push(`return {};`);
     }
@@ -556,12 +560,16 @@ function getTypeSerializeFunction(
       parameters: [{ name: "obj", type: type.elementType.name + "[]" }],
       returnType: `${typeName}[]`
     };
+    const { propertiesStr } = getRequestModelMapping(
+      type.elementType,
+      "item",
+      runtimeImports
+    );
+
     statements.push(
-      `return (obj || []).map(item => { return {${getRequestModelMapping(
-        type.elementType,
-        "item",
-        runtimeImports
-      ).join(", ")}}})`
+      `return (obj || []).map(item => { 
+          return { ${propertiesStr.join(", ")} }
+        })`
     );
     functionStatement.statements = statements.join("\n");
     if (!hasDuplicateFunction(sourceFile, functionStatement)) {

package/src/modular/buildSubpathIndex.ts

@@ -53,6 +53,16 @@ export function buildSubpathIndexFile(
           ) {
             return false;
           }
+
+          // skip exporting serializers for models
+          if (
+            subpath === "models" &&
+            ex.getKindName() === "FunctionDeclaration" &&
+            exDeclaration[0].endsWith("Serializer")
+          ) {
+            return false;
+          }
+
           return true;
         });
       })

package/src/modular/emitModels.ts

@@ -1,4 +1,4 @@
-import { getImportSpecifier } from "@azure-tools/rlc-common";
+import { addImportsToFiles, getImportSpecifier } from "@azure-tools/rlc-common";
 import * as path from "path";
 import {
   InterfaceDeclarationStructure,
@@ -10,11 +10,18 @@ import { buildOperationOptions } from "./buildOperations.js";
 import { getDocsFromDescription } from "./helpers/docsHelpers.js";
 import { getModularModelFilePath } from "./helpers/namingHelpers.js";
 import { getType } from "./helpers/typeHelpers.js";
-import { Client, ModularCodeModel, Type } from "./modularCodeModel.js";
+import {
+  Client,
+  ModularCodeModel,
+  Type as ModularType
+} from "./modularCodeModel.js";
+import { buildModelSerializer } from "./serialization/buildSerializerFunction.js";
+import { toCamelCase } from "../utils/casingUtils.js";
+import { addImportBySymbol } from "../utils/importHelper.js";
 
 // ====== UTILITIES ======
 
-function isAzureCoreErrorSdkType(t: Type) {
+function isAzureCoreErrorSdkType(t: ModularType) {
   return (
     t.name &&
     ["error", "errormodel", "innererror", "errorresponse"].includes(
@@ -24,7 +31,7 @@ function isAzureCoreErrorSdkType(t: Type) {
   );
 }
 
-function isAzureCoreLroSdkType(t: Type) {
+function isAzureCoreLroSdkType(t: ModularType) {
   return (
     t.name &&
     ["operationstate"].includes(t.name.toLowerCase()) &&
@@ -32,11 +39,11 @@ function isAzureCoreLroSdkType(t: Type) {
   );
 }
 
-function isAnonymousModel(t: Type) {
+function isAnonymousModel(t: ModularType) {
   return t.type === "model" && t.name === "";
 }
 
-export function isModelWithAdditionalProperties(t: Type) {
+export function isModelWithAdditionalProperties(t: ModularType) {
   return t.type === "dict" && t.name !== "Record";
 }
 
@@ -54,7 +61,7 @@ function getCoreLroType(name: string, coreLroTypes: Set<string>) {
 
 // ====== TYPE EXTRACTION ======
 
-function extractModels(codeModel: ModularCodeModel): Type[] {
+function extractModels(codeModel: ModularCodeModel): ModularType[] {
   const models = codeModel.types.filter(
     (t) =>
       ((t.type === "model" || t.type === "enum") &&
@@ -65,7 +72,7 @@ function extractModels(codeModel: ModularCodeModel): Type[] {
   );
 
   for (const model of codeModel.types) {
-    if (model.type === "combined" && model.nullable) {
+    if (model.type === "combined") {
       for (const unionModel of model.types ?? []) {
         if (unionModel.type === "model") {
           models.push(unionModel);
@@ -81,7 +88,7 @@ function extractModels(codeModel: ModularCodeModel): Type[] {
  * 1. alias from polymorphic base model, where we need to use typescript union to combine all the sub models
  * 2. alias from unions, where we also need to use typescript union to combine all the union variants
  */
-export function extractAliases(codeModel: ModularCodeModel): Type[] {
+export function extractAliases(codeModel: ModularCodeModel): ModularType[] {
   const models = codeModel.types.filter(
     (t) =>
       ((t.type === "model" || t.type === "combined") &&
@@ -93,7 +100,7 @@ export function extractAliases(codeModel: ModularCodeModel): Type[] {
 }
 // ====== TYPE BUILDERS ======
 function buildEnumModel(
-  model: Type
+  model: ModularType
 ): OptionalKind<TypeAliasDeclarationStructure> {
   const valueType = model.valueType?.type === "string" ? "string" : "number";
   return {
@@ -122,7 +129,7 @@ type InterfaceStructure = OptionalKind<InterfaceDeclarationStructure> & {
 };
 
 export function buildModelInterface(
-  model: Type,
+  model: ModularType,
   cache: { coreClientTypes: Set<string>; coreLroTypes: Set<string> }
 ): InterfaceStructure {
   const modelProperties = model.properties ?? [];
@@ -178,7 +185,6 @@ export function buildModels(
   const modelsFile = codeModel.project.createSourceFile(
     getModularModelFilePath(codeModel, subClient)
   );
-
   for (const model of models) {
     if (model.type === "enum") {
       if (modelsFile.getTypeAlias(model.name!)) {
@@ -214,10 +220,38 @@ export function buildModels(
           codeModel.modularOptions.compatibilityMode
         );
       }
-      modelsFile.addInterface(modelInterface);
+
+      if (!modelsFile.getInterface(modelInterface.name)) {
+        modelsFile.addInterface(modelInterface);
+      }
+
+      // Generate a serializer function next to each model
+      const serializerFunction = buildModelSerializer(
+        model,
+        codeModel.runtimeImports
+      );
+
+      if (
+        serializerFunction &&
+        !modelsFile.getFunction(toCamelCase(modelInterface.name + "Serializer"))
+      ) {
+        modelsFile.addStatements(serializerFunction);
+      }
+      addImportBySymbol("serializeRecord", modelsFile);
+      modelsFile.fixUnusedIdentifiers();
     }
   }
 
+  const projectRootFromModels = codeModel.clients.length > 1 ? "../.." : "../";
+  addImportsToFiles(codeModel.runtimeImports, modelsFile, {
+    rlcIndex: path.posix.join(projectRootFromModels, "rest", "index.js"),
+    serializerHelpers: path.posix.join(
+      projectRootFromModels,
+      "helpers",
+      "serializerHelpers.js"
+    )
+  });
+
   if (coreClientTypes.size > 0) {
     modelsFile.addImportDeclarations([
       {
@@ -248,12 +282,22 @@ export function buildModels(
 
   aliases.forEach((alias) => {
     modelsFile.addTypeAlias(buildModelTypeAlias(alias));
+    if (!models.includes(alias)) {
+      // Generate a serializer function next to each model
+      const serializerFunction = buildModelSerializer(
+        alias,
+        codeModel.runtimeImports
+      );
+      if (serializerFunction) {
+        modelsFile.addStatements(serializerFunction);
+      }
+    }
   });
   return modelsFile;
 }
 
 function addExtendedDictInfo(
-  model: Type,
+  model: ModularType,
   modelInterface: InterfaceStructure,
   compatibilityMode: boolean = false
 ) {
@@ -282,7 +326,7 @@ function addExtendedDictInfo(
   }
 }
 
-export function buildModelTypeAlias(model: Type) {
+export function buildModelTypeAlias(model: ModularType) {
   return {
     name: model.name!,
     isExported: true,
@@ -321,7 +365,13 @@ export function buildModelsOptions(
     }
   ]);
 
-  modelOptionsFile.fixMissingImports();
+  modelOptionsFile.fixMissingImports(
+    {},
+    {
+      importModuleSpecifierPreference: "shortest",
+      importModuleSpecifierEnding: "js"
+    }
+  );
   modelOptionsFile
     .getImportDeclarations()
     .filter((id) => {