typespec-typescript-emitter 1.2.0 → 2.0.1

package/src/resolve/Resolvable.ts

@@ -0,0 +1,267 @@
+import { Model, Type } from "@typespec/compiler";
+import { AppendableString } from "../helpers/appendableString.js";
+import { compareArrays } from "../helpers/arrays.js";
+import { TTypeMap } from "../helpers/buildTypeMap.js";
+import { reportDiagnostic } from "../helpers/diagnostics.js";
+import { namespaceListFromNamespace } from "../helpers/namespaces.js";
+import {
+  Resolver,
+  ResolverOptions,
+  ResolverResult,
+} from "./Resolvable_helpers.js";
+
+export abstract class Resolvable<T extends Type> {
+  /** Recursively resolves a type. */
+  static async resolve<R extends Resolver>(
+    r: R,
+    t: Type,
+    opts: ResolverOptions<R>,
+  ): Promise<ResolverResult<R>> {
+    const ret: ResolverResult<R> = {
+      resolved: new AppendableString(),
+      visibilityMap: "",
+      hasVisibility: false,
+      imports: [],
+    };
+    await (await Resolvable.for(r, t)).resolve(opts, ret);
+    return ret;
+  }
+
+  /**
+   * To be called from within the resolution logic of a type:
+   * Resolves another type for the current type, handling required changes to the resolution options.
+   * The passed `out` object is not signifiantly changed, only the `hasVisibility` flag is managed.
+   */
+  protected async resolveNested<R extends typeof this._r>(
+    t: Type,
+    opts: ResolverOptions<R>,
+    out: ResolverResult<R>,
+    nest: boolean = true,
+  ): Promise<ResolverResult<R>> {
+    // prepare nested resolution
+    if (nest) opts.nestlevel++;
+    if (!opts.parents) opts.parents = [];
+    opts.parents.push(this._t);
+
+    const ret = await Resolvable.resolve(this._r, t, opts);
+
+    // revert to current level
+    if (nest) opts.nestlevel--;
+    opts.parents.pop();
+
+    return ret;
+  }
+
+  /** Creates the appropriate Resolvable instance for a given type. */
+  static async for<T extends Type>(r: Resolver, t: T): Promise<Resolvable<T>> {
+    // use lazy imports to break circular dependencies
+    const { ResolvableSimple } = await import("./types/Simple.js");
+    if (ResolvableSimple.AllowedTypeKinds.includes(t.kind as any)) {
+      return new ResolvableSimple(t, r) as any;
+    }
+    switch (t.kind) {
+      case "Enum": {
+        const { ResolvableEnum } = await import("./types/Enum.js");
+        return new ResolvableEnum(t, r) as any;
+      }
+      case "EnumMember": {
+        const { ResolvableEnumMember } = await import("./types/Enum.js");
+        return new ResolvableEnumMember(t, r) as any;
+      }
+      case "Model": {
+        const { IndexedModel } = await import("./types/Model.Indexed.js");
+        const { ShapedModel } = await import("./types/Model.Shaped.js");
+        switch ((t as Model).name) {
+          case "Array":
+          case "Record":
+            return new IndexedModel(t, r) as any;
+
+          default:
+            return new ShapedModel(t, r) as any;
+        }
+      }
+      case "Scalar": {
+        const { ResolvableScalar } = await import("./types/Scalar.js");
+        return new ResolvableScalar(t, r) as any;
+      }
+      case "Tuple": {
+        const { ResolvableTuple } = await import("./types/Tuple.js");
+        return new ResolvableTuple(t, r) as any;
+      }
+      case "Union": {
+        const { ResolvableUnion } = await import("./types/Union.js");
+        return new ResolvableUnion(t, r) as any;
+      }
+
+      default:
+        reportDiagnostic({
+          code: "resolve-unresolved",
+          message: `Could not resolve type ${t.kind}`,
+          severity: "error",
+        });
+        throw new TypeError(`Could not resolve type ${t.kind}`);
+    }
+  }
+
+  constructor(t: T, r: Resolver) {
+    this._t = t;
+    this._r = r;
+  }
+
+  protected abstract expectedTypeKind: string;
+
+  protected _t: T;
+  protected _r: Resolver;
+
+  /** Modifies passed output object in-place. */
+  protected abstract type(
+    opts: ResolverOptions<Resolver.Type>,
+    out: ResolverResult<Resolver.Type>,
+  ): Promise<void>;
+  /** Modifies passed output object in-place. */
+  protected abstract typeguard(
+    opts: ResolverOptions<Resolver.Typeguard>,
+    out: ResolverResult<Resolver.Typeguard>,
+  ): Promise<void>;
+
+  /** Resolves the type, modifying an output object in place. */
+  public async resolve(
+    opts: ResolverOptions<Resolver>,
+    out: ResolverResult<Resolver>,
+  ): Promise<void> {
+    this.validate();
+
+    const ownVisibility = await this.hasVisibility(opts, out);
+    if (ownVisibility) out.hasVisibility = true;
+
+    // check for known resolved type
+    if (opts.rootTypeReady && (this._t as any).name) {
+      // type without name can't be resolved
+      const currentNamespaces = namespaceListFromNamespace(
+        (this._t as any).namespace,
+      );
+      // find known resolved type
+      const foundKnownResolved = ((): TTypeMap[number] | null => {
+        const currentNamespaces = namespaceListFromNamespace(
+          (this._t as any).namespace,
+        );
+        if (currentNamespaces && currentNamespaces.length > 0) {
+          const found = opts.typemap.find(
+            (mt) =>
+              mt.type.kind === this._t.kind &&
+              mt.type.name === (this._t as any).name &&
+              compareArrays(mt.namespaces, currentNamespaces),
+          );
+          return found ?? null;
+        }
+        return null;
+      })();
+
+      // if found, return name instead of full resolution
+      if (foundKnownResolved) {
+        if (
+          opts.rootType &&
+          compareArrays(currentNamespaces!, opts.rootType.namespaces)
+        ) {
+          // if namespace of found is same as current (= same file), just return name
+          out.resolved.append(
+            this._r === Resolver.Type
+              ? foundKnownResolved.type.name
+              : this._t.kind === "Enum"
+                ? "true" // enums don't have typeguards
+                : `is${foundKnownResolved.type.name}(${(opts as ResolverOptions<Resolver.Typeguard>).accessor}${ownVisibility ? ", vis" : ""})`,
+          );
+        } else {
+          // found is in different file than current, prepare importing
+          out.resolved.append(
+            `${foundKnownResolved.namespaces.join("_")}.${
+              this._r === Resolver.Type
+                ? foundKnownResolved.type.name
+                : this._t.kind === "Enum"
+                  ? "true" // enums don't have typeguards
+                  : `is${foundKnownResolved.type.name}(${(opts as ResolverOptions<Resolver.Typeguard>).accessor}${ownVisibility ? ", vis" : ""})`
+            }`,
+          );
+          out.imports.push(foundKnownResolved.namespaces);
+        }
+
+        // optionally allow found type to modify output
+        if (this.transformKnownType !== undefined)
+          this.transformKnownType(opts, out);
+        return;
+      }
+    }
+
+    // this prevents the root type from triggering known resolution
+    opts.rootTypeReady = true;
+
+    switch (this._r) {
+      case Resolver.Type:
+        return await this.type(
+          opts as ResolverOptions<Resolver.Type>,
+          out as ResolverResult<Resolver.Type>,
+        );
+      case Resolver.Typeguard:
+        return await this.typeguard(
+          opts as ResolverOptions<Resolver.Typeguard>,
+          out as ResolverResult<Resolver.Typeguard>,
+        );
+    }
+  }
+
+  protected transformKnownType(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    opts: ResolverOptions<Resolver>,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    out: ResolverResult<Resolver>,
+  ): void {}
+
+  /** Returns true if this type or anything it contains or references has visibility modifiers. */
+  public async hasVisibility(
+    opts: ResolverOptions<Resolver>,
+    out: ResolverResult<Resolver>,
+  ): Promise<boolean> {
+    return out.hasVisibility;
+  }
+  /** Returns true if this type or anything it contains or references has visibility modifiers. */
+  protected static async hasVisibility(
+    t: Type,
+    opts: ResolverOptions<Resolver>,
+    out: ResolverResult<Resolver>,
+    current: Type,
+  ): Promise<boolean> {
+    if (!opts.parents) opts.parents = [];
+    opts.parents.push(current);
+    const ret = await (
+      await Resolvable.for(Resolver.Type /** doesn't matter */, t)
+    ).hasVisibility(opts, out);
+    opts.parents.pop();
+    return ret;
+  }
+
+  /** Checks its stored type to ensure the instance was created on a suitable type. */
+  protected validate(): void {
+    if (this._t.kind !== this.expectedTypeKind) {
+      this.diagnostic(
+        "typeclass-mismatch",
+        `Tried creating resolver for ${this.expectedTypeKind} on type ${this._t.kind}`,
+        "error",
+      );
+      throw new TypeError(
+        `Type-kind/class mismatch: instanced ${this.expectedTypeKind} on type ${this._t.kind}`,
+      );
+    }
+  }
+
+  protected diagnostic(
+    code: string,
+    msg: string,
+    level: "error" | "warning",
+  ): void {
+    reportDiagnostic({
+      code: `resolve-${this._r}-${code}`,
+      message: msg,
+      severity: level,
+    });
+  }
+}

package/src/resolve/Resolvable_helpers.ts

@@ -0,0 +1,65 @@
+import { Program, Type } from "@typespec/compiler";
+import { AppendableString } from "../helpers/appendableString.js";
+import { compareArrays } from "../helpers/arrays.js";
+import { TTypeMap } from "../helpers/buildTypeMap.js";
+import { namespaceListFromNamespace } from "../helpers/namespaces.js";
+import { EmitterOptions } from "../lib.js";
+
+export enum Resolver {
+  Type,
+  Typeguard,
+}
+
+export type ResolverOptions<R extends Resolver> = {
+  program: Program;
+  options: EmitterOptions;
+  typemap: TTypeMap;
+  nestlevel: number;
+  /** The type the entire resolution chain started with. */
+  rootType: TTypeMap[number] | null;
+  /**
+   * This tracks whether or not resolving *to* the type currently being investigated
+   * is valid. This allows for recursive types.
+   */
+  rootTypeReady?: boolean;
+  /** The types "up the chain" - "parent" types on nested resolution. */
+  parents?: Type[];
+} & (R extends Resolver.Type
+  ? {
+      emitDocs: boolean;
+    }
+  : {
+      /**
+       * This string describes how a function (part) of a typeguard can
+       * access the value currently being tested by it.
+       * Example: typeguard(t: any) on `n` for {n: string} -> this = "t"
+       */
+      accessor: string;
+    });
+
+/** Tries to find type in known types map */
+export const getKnownResolvedType = (
+  typemap: TTypeMap,
+  t: any,
+): TTypeMap[number] | null => {
+  const currentNamespaces = namespaceListFromNamespace((t as any).namespace);
+  if (currentNamespaces && currentNamespaces.length > 0) {
+    const found = typemap.find(
+      (mt) =>
+        mt.type.kind === t.kind &&
+        mt.type.name === (t as any).name &&
+        compareArrays(mt.namespaces, currentNamespaces),
+    );
+    return found ?? null;
+  }
+  return null;
+};
+
+export type ResolverResult<R extends Resolver> = {
+  readonly resolved: AppendableString;
+  visibilityMap: string;
+  imports: TTypeMap[number]["namespaces"][];
+  /** Whether any resolved part (nested types and base types included) have @visibility modifiers */
+  hasVisibility: boolean;
+  doc?: R extends Resolver.Type ? string : never;
+};

package/src/resolve/operationTypemap.ts

@@ -0,0 +1,212 @@
+import { Operation, Program, Type } from "@typespec/compiler";
+import { getHttpOperation } from "@typespec/http";
+import { TTypeMap } from "../helpers/buildTypeMap.js";
+import { EmitterOptions } from "../lib.js";
+import { Resolvable } from "./Resolvable.js";
+import { Resolver } from "./Resolvable_helpers.js";
+
+/** Maps a route path to its typemap definition and required imports */
+export type TOperationTypemap = {
+  // "string" in these does not refer to the type "string"; it's the typescript code *as* string.
+  request: { content: string; hasVisibility: boolean };
+  response: {
+    content: Array<{
+      status: number | "unknown";
+      body: string;
+      hasVisibility: boolean;
+    }>;
+  };
+};
+
+export const resolveOperationTypemap = async (
+  program: Program,
+  options: EmitterOptions,
+  typemap: TTypeMap,
+  op: Operation,
+): Promise<{
+  types: TOperationTypemap;
+  imports: TTypeMap[number]["namespaces"][];
+}> => {
+  const httpOp = getHttpOperation(program, op)[0];
+  const ret: Awaited<ReturnType<typeof resolveOperationTypemap>> = {
+    types: {
+      request: { content: "null", hasVisibility: false },
+      response: { content: [] },
+    },
+    imports: [],
+  };
+
+  // request
+  if (httpOp.parameters.body) {
+    const resolved = await Resolvable.resolve(
+      Resolver.Type,
+      httpOp.parameters.body.type,
+      {
+        program,
+        options,
+        emitDocs: false,
+        nestlevel: 3,
+        rootType: null,
+        typemap,
+        rootTypeReady: true,
+      },
+    );
+    ret.imports.push(...resolved.imports);
+    ret.types.request.content = replaceLifecycle(
+      resolved.resolved.value,
+      httpOp.verb.toUpperCase(),
+      resolved.hasVisibility,
+    );
+    if (resolved.hasVisibility) ret.types.request.hasVisibility = true;
+  }
+
+  // response
+  if (op.returnType) {
+    const getReturnType = async (
+      t: Type,
+    ): Promise<{
+      content: {
+        status: number | "unknown";
+        body: string;
+        hasVisibility: boolean;
+      }[];
+    }> => {
+      const responseRet: TOperationTypemap["response"] = { content: [] };
+
+      switch (t.kind) {
+        case "Model": {
+          // If the return type is a model, it may either be a "blank" body or a fully
+          // qualified response with status and body.
+          const modelret: TOperationTypemap["response"]["content"][number] = {
+            status: 200,
+            body: "{}",
+            hasVisibility: false,
+          };
+
+          // check for fully qualified response or plain body
+          let wasFullyQualified = false;
+          for (const prop of t.properties) {
+            for (const decorator of prop[1].decorators) {
+              // find status code
+              if (
+                decorator.definition?.name === "@statusCode" &&
+                prop[1].type.kind === "Number"
+              )
+                modelret.status = prop[1].type.value;
+              // find body definiton
+              if (decorator.definition?.name === "@body") {
+                const resolved = await Resolvable.resolve(
+                  Resolver.Type,
+                  prop[1].type,
+                  {
+                    program,
+                    options,
+                    emitDocs: false,
+                    nestlevel: 3,
+                    rootType: null,
+                    typemap,
+                    rootTypeReady: true,
+                  },
+                );
+                if (resolved.hasVisibility) modelret.hasVisibility = true;
+                ret.imports.push(...resolved.imports);
+                modelret.body = replaceLifecycle(
+                  resolved.resolved.value,
+                  "RETURN",
+                  resolved.hasVisibility,
+                );
+                wasFullyQualified = true;
+              }
+            }
+          }
+
+          if (!wasFullyQualified) {
+            const resolved = await Resolvable.resolve(Resolver.Type, t, {
+              program,
+              options,
+              emitDocs: false,
+              nestlevel: 3,
+              rootType: null,
+              typemap,
+              rootTypeReady: true,
+            });
+            if (resolved.hasVisibility) modelret.hasVisibility = true;
+            ret.imports.push(...resolved.imports);
+            modelret.body = replaceLifecycle(
+              resolved.resolved.value,
+              "RETURN",
+              resolved.hasVisibility,
+            );
+          }
+
+          responseRet.content.push(modelret);
+
+          break;
+        }
+
+        case "Union": {
+          // if return type is a union, each variant may be fully qualified or body-only
+          for (const variant of t.variants) {
+            const resolved = await getReturnType(variant[1].type);
+            responseRet.content.push(...resolved.content);
+          }
+          break;
+        }
+
+        default: {
+          // return type does not have a qualified body; making one up and resolving that one
+          const resolved = await Resolvable.resolve(Resolver.Type, t, {
+            program,
+            options,
+            emitDocs: false,
+            nestlevel: 3,
+            rootType: null,
+            typemap,
+            rootTypeReady: true,
+          });
+          ret.imports.push(...resolved.imports);
+          responseRet.content.push({
+            status: 200,
+            body: replaceLifecycle(
+              resolved.resolved.value,
+              httpOp.verb.toUpperCase(),
+              resolved.hasVisibility,
+            ),
+            hasVisibility: resolved.hasVisibility,
+          });
+          break;
+        }
+      }
+
+      return responseRet;
+    };
+    ret.types.response = await getReturnType(op.returnType);
+  }
+
+  return ret;
+};
+
+/** Maps HTTP verbs to lifecycle states. See @typespec/compiler/.../visibility.tsp */
+const VerbToLifecycle = {
+  RETURN: ["Read"], // for all return types
+  POST: ["Create"],
+  PUT: ["Create", "Update"],
+  PATCH: ["Update"],
+  DELETE: ["Delete"],
+  GET: ["Query"], // *parameters* of request, return type is still RETURN
+  Head: ["Query"],
+};
+
+// lifecycle assignment helper
+const replaceLifecycle = (
+  resolved: string,
+  verb: string,
+  hasVisibility: boolean,
+): string => {
+  const opLifecycle = VerbToLifecycle[verb as keyof typeof VerbToLifecycle];
+  if (!hasVisibility) return resolved;
+  return resolved.replaceAll(
+    "V>",
+    `V extends Lifecycle.All ? (${opLifecycle.map((l) => `Lifecycle.${l}`).join(" | ")}) : V>`,
+  );
+};

package/src/resolve/types/Enum.ts

@@ -0,0 +1,92 @@
+import { Enum, EnumMember, getDoc } from "@typespec/compiler";
+import { compareArrays } from "../../helpers/arrays.js";
+import { namespaceListFromNamespace } from "../../helpers/namespaces.js";
+import { Resolvable } from "../Resolvable.js";
+import {
+  Resolver,
+  ResolverOptions,
+  ResolverResult,
+} from "../Resolvable_helpers.js";
+
+/**
+ * This resolves Enums completely, meaning it doesn't try to resolve
+ * members as EnumMember, because EnumMember resolution references the base Enum.
+ */
+export class ResolvableEnum extends Resolvable<Enum> {
+  protected expectedTypeKind = "Enum";
+
+  protected async type(
+    opts: ResolverOptions<Resolver.Type>,
+    out: ResolverResult<Resolver.Type>,
+  ): Promise<void> {
+    if (opts.emitDocs) {
+      out.doc = getDoc(opts.program, this._t);
+    }
+    out.resolved.append("{\n");
+    let i = 1;
+    this._t.members.forEach((member) => {
+      const val = resolveEnumMemberValue(member, opts);
+      out.resolved.addLine(
+        `${member.name.includes("-") ? `'${member.name}'` : member.name}${val}${i < this._t.members.size ? "," : ""}`,
+        opts.nestlevel + 1,
+      );
+      i++;
+    });
+    out.resolved.addLine("}", opts.nestlevel, "continued");
+  }
+
+  protected async typeguard(): Promise<void> {
+    // enums cannot have typeguards
+    return;
+  }
+}
+
+/**
+ * This cannot resolve members during Enum resolution, because this
+ * will try to reference the base Enum by name.
+ */
+export class ResolvableEnumMember extends Resolvable<EnumMember> {
+  protected expectedTypeKind = "EnumMember";
+
+  protected async type(
+    opts: ResolverOptions<Resolver.Type>,
+    out: ResolverResult<Resolver.Type>,
+  ): Promise<void> {
+    const foundParent = opts.typemap.find(
+      (mt) =>
+        mt.type.kind === "Enum" &&
+        mt.type.name === this._t.enum.name &&
+        compareArrays(
+          mt.namespaces,
+          namespaceListFromNamespace(this._t.enum.namespace) ?? [],
+        ),
+    );
+    if (foundParent) {
+      out.resolved.append(`${foundParent.type.name}.${this._t.name}`);
+      out.imports.push(foundParent.namespaces);
+    } else {
+      out.resolved.append(resolveEnumMemberValue(this._t, opts));
+    }
+  }
+
+  protected async typeguard(
+    opts: ResolverOptions<Resolver.Typeguard>,
+    out: ResolverResult<Resolver.Typeguard>,
+  ): Promise<void> {
+    out.resolved.append("true");
+  }
+}
+
+const resolveEnumMemberValue = (
+  member: EnumMember,
+  opts: ResolverOptions<any>,
+): string => {
+  return member.value === undefined
+    ? opts.options["string-nominal-enums"]
+      ? ` = '${member.name}'`
+      : ""
+    : " = " +
+        (typeof member.value === "string"
+          ? `'${member.value}'`
+          : member.value.toString());
+};