typespec-typescript-emitter 1.2.0 → 2.0.1

package/src/emitter.ts

@@ -1,114 +1,26 @@
-import {
-  EmitContext,
-  emitFile,
-  navigateProgram,
-  resolvePath,
-} from "@typespec/compiler";
-import { emitRoutedTypemap } from "./emit_mapped_types.js";
+import { EmitContext } from "@typespec/compiler";
+import { emitRoutedTypemap } from "./emit_routedTypemap.js";
 import { emitRoutes } from "./emit_routes.js";
-import emitTypes from "./emit_types.js";
-import autogenerateWarning from "./helper_autogenerateWarning.js";
+import { emitTypes } from "./emit_types.js";
+import { buildTypeMap } from "./helpers/buildTypeMap.js";
+import { setContext } from "./helpers/diagnostics.js";
+import { emitVisibilityHelperFile } from "./helpers/visibilityHelperFile.js";
 import { EmitterOptions } from "./lib.js";
+import { parseOptions } from "./parseOptions.js";
 
-// helper to add lines to string with indentation
-declare global {
-  interface String {
-    addLine(str: string, tabs?: number, continued?: boolean): string;
-  }
-}
-String.prototype.addLine = function (
-  this: string,
-  str: string,
-  tabs?: number,
-  continued?: boolean,
-): string {
-  return `${this}${"  ".repeat(tabs ?? 0)}${str}${continued ? "" : "\n"}`;
-};
-
-export async function $onEmit(context: EmitContext) {
-  if (!context.program.compilerOptions.noEmit) {
-    const options: EmitterOptions = {
-      "root-namespace": context.options["root-namespace"],
-      "out-dir": context.options["out-dir"] ?? context.emitterOutputDir,
-      "enable-types": context.options["enable-types"] ?? true,
-      "enable-typeguards":
-        (context.options["enable-types"] ?? true) &&
-        (context.options["enable-typeguards"] ?? false),
-      "enable-routes": context.options["enable-routes"] ?? false,
-      "enable-routed-typemap":
-        context.options["enable-routed-typemap"] ?? false,
-      "string-nominal-enums":
-        (context.options["enable-routed-typemap"] ?? false) &&
-        (context.options["string-nominal-enums"] ?? false),
-      "serializable-date-types":
-        context.options["serializable-date-types"] ?? false,
-    };
-
-    console.log(`Writing routes to ${options["out-dir"]}`);
-
-    let targetNamespaceFound = false;
-    let routesObject = "";
-    let routedTypemap = "";
-    let typeFiles: ReturnType<typeof emitTypes> = {
-      files: {},
-      typeguardedNames: [],
-    };
-    navigateProgram(context.program, {
-      namespace(n) {
-        if (
-          !targetNamespaceFound &&
-          n.name === context.options["root-namespace"]
-        ) {
-          targetNamespaceFound = true;
-          if (options["enable-types"] || options["enable-typeguards"])
-            typeFiles = emitTypes(context, n, options);
-          if (options["enable-routes"]) {
-            routesObject = emitRoutes(context, n);
-          }
-          if (options["enable-routed-typemap"]) {
-            routedTypemap = emitRoutedTypemap(context, n);
-          }
-        }
-      },
-    });
-
-    if (!targetNamespaceFound)
-      throw new Error("Targeted root namespace not found.");
+export async function $onEmit(context: EmitContext<EmitterOptions>) {
+  if (context.program.compilerOptions.noEmit) return;
+  setContext(context);
+  parseOptions(context);
 
-    // routes object
-    if (options["enable-routes"]) {
-      if (!routesObject) throw new Error("Routes object empty.");
-      await emitFile(context.program, {
-        path: resolvePath(
-          options["out-dir"],
-          `routes_${options["root-namespace"]}.ts`,
-        ),
-        content: `/* eslint-disable */\n\n${autogenerateWarning}${routesObject}`,
-      });
-    }
+  const typeMap = buildTypeMap(context.program, context.options);
 
-    // routed typemap
-    if (options["enable-routed-typemap"]) {
-      if (!routedTypemap) throw new Error("Routed typemap empty.");
-      await emitFile(context.program, {
-        path: resolvePath(
-          options["out-dir"],
-          `routedTypemap_${options["root-namespace"]}.ts`,
-        ),
-        content: `/* eslint-disable */\n\n${autogenerateWarning}${routedTypemap}`,
-      });
-    }
+  if (context.options["enable-types"])
+    await emitTypes(context.program, context.options, typeMap);
+  if (context.options["enable-routed-typemap"])
+    await emitRoutedTypemap(context.program, context.options, typeMap);
+  if (context.options["enable-routes"])
+    await emitRoutes(context.program, context.options);
 
-    // type files
-    if (options["enable-types"] || options["enable-typeguards"]) {
-      const typeFileArr = Object.entries(typeFiles.files);
-      for (let i = 0; i < typeFileArr.length; i++) {
-        if (typeFileArr[i][1])
-          await emitFile(context.program, {
-            path: resolvePath(options["out-dir"], `${typeFileArr[i][0]}.ts`),
-            content: `/* eslint-disable */\n\n${autogenerateWarning}${typeFileArr[i][1]}`,
-          });
-      }
-    }
-  }
+  await emitVisibilityHelperFile(context.program, context.options);
 }

package/src/helpers/appendableString.ts

@@ -0,0 +1,52 @@
+/**
+ * This class provides a string type which can only be appended to but not overwritten.
+ */
+export class AppendableString {
+  constructor(init?: string) {
+    this._content = init ?? "";
+  }
+
+  private _content: string;
+
+  get value(): string {
+    return this._content;
+  }
+  append(s?: string | AppendableString) {
+    this._content += s ?? "";
+  }
+
+  /** Changes in place, returning the new value */
+  addLine(
+    str: string | AppendableString,
+    tabs?: number,
+    continued: "continued" | "line-end" = "line-end",
+  ): this {
+    this._content += `${"  ".repeat(tabs ?? 0)}${str}${continued === "continued" ? "" : "\n"}`;
+    return this;
+  }
+
+  [Symbol.toPrimitive](hint: string) {
+    switch (hint) {
+      case "default":
+      case "string":
+        return this.value;
+
+      case "boolean":
+        return !!this.value;
+
+      default:
+        throw new TypeError(`Appendable string cannot be coerced to ${hint}`);
+    }
+  }
+
+  /** Removes the last x characters */
+  dropLast(n: number = 1): this {
+    this._content = this._content.substring(0, this._content.length - n);
+    return this;
+  }
+
+  clear(): this {
+    this._content = "";
+    return this;
+  }
+}

package/src/helpers/arrays.ts

@@ -0,0 +1,21 @@
+export const compareArrays = (a: any[], b: any[]): boolean => {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+};
+
+/** Unique-ifies a 2D array of strings (imported namespaces list). */
+export const unique2D = (rows: string[][]): string[][] => {
+  const seen = new Set<string>();
+  const out: string[][] = [];
+  for (const r of rows) {
+    const key = r.join("\u0000"); // safe separator
+    if (!seen.has(key)) {
+      seen.add(key);
+      out.push(r);
+    }
+  }
+  return out;
+};

package/src/{helper_autogenerateWarning.ts → helpers/autogenerateWarning.ts}

@@ -6,7 +6,6 @@ const autogenerateWarning = `
  * Instead, change the underlying spec.
  */
 
-
 `;
 
 export default autogenerateWarning;

package/src/helpers/buildTypeMap.ts

@@ -0,0 +1,72 @@
+import {
+  Enum,
+  Model,
+  Namespace,
+  navigateProgram,
+  navigateTypesInNamespace,
+  Program,
+  Scalar,
+  Union,
+} from "@typespec/compiler";
+import { EmitterOptions } from "../lib.js";
+
+export type TTypeMap = {
+  type: Enum | Model | Scalar | Union;
+  namespaces: string[];
+  hasVisibility: boolean | undefined;
+}[];
+
+/**
+ * Traverses all namespaces in the program and produces
+ * a map of all types-to-be-emitted and their namespace hierarchy.
+ */
+export const buildTypeMap = (
+  program: Program,
+  options: EmitterOptions,
+): TTypeMap => {
+  // save original targeted namespaces array because it's mutated here
+  const targetedNamespaces = structuredClone(options["root-namespaces"]);
+  const map: TTypeMap = [];
+
+  const pushType = (t: TTypeMap[number]["type"], hierarchy: string[]): void => {
+    if (!t.name) return;
+    map.push({
+      type: t,
+      namespaces: hierarchy,
+      hasVisibility: undefined,
+    });
+  };
+
+  const traverseNamespace = (n: Namespace, hierarchy: string[]) => {
+    navigateTypesInNamespace(
+      n,
+      {
+        enum: (t) => pushType(t, [...hierarchy, n.name]),
+        scalar: (t) => pushType(t, [...hierarchy, n.name]),
+        model: (t) => pushType(t, [...hierarchy, n.name]),
+        union: (t) => pushType(t, [...hierarchy, n.name]),
+      },
+      {
+        skipSubNamespaces: true,
+      },
+    );
+    n.namespaces.forEach((ns) => traverseNamespace(ns, [...hierarchy, n.name]));
+  };
+
+  navigateProgram(program, {
+    namespace(n) {
+      const nsIndex = options["root-namespaces"].findIndex(
+        (ns) => n.name === ns,
+      );
+      if (nsIndex === -1) return;
+      // for some reason, navigateProgram visits each namespace multiple times; this prevents that
+      delete options["root-namespaces"][nsIndex];
+
+      traverseNamespace(n, []);
+    },
+  });
+
+  // restore un-mutated version
+  options["root-namespaces"] = targetedNamespaces;
+  return map;
+};

package/src/helpers/diagnostics.ts

@@ -0,0 +1,19 @@
+import { Diagnostic, EmitContext, NoTarget } from "@typespec/compiler";
+import { EmitterOptions } from "../lib.js";
+
+let context: EmitContext<EmitterOptions> | null = null;
+
+export const setContext = (c: EmitContext<EmitterOptions>): void => {
+  context = c;
+};
+
+export const reportDiagnostic = (
+  diagnostic: Pick<Diagnostic, "code" | "message" | "severity">,
+): void => {
+  if (!context) throw new Error("Couldn't report diagnostic: context not set");
+  context.program.reportDiagnostic({
+    ...diagnostic,
+    code: `typespec-emitter-${diagnostic.code}`,
+    target: NoTarget,
+  });
+};

package/src/helpers/getImports.ts

@@ -0,0 +1,9 @@
+import { TTypeMap } from "./buildTypeMap.js";
+import { filenameFromNamespaces } from "./namespaces.js";
+
+export const getImports = (
+  imports: TTypeMap[number]["namespaces"][],
+): string[] =>
+  imports.map(
+    (i) => `import * as ${i.join("_")} from './${filenameFromNamespaces(i)}';`,
+  );

package/src/helpers/namespaces.ts

@@ -0,0 +1,18 @@
+import { Namespace } from "@typespec/compiler";
+
+/** Traverses *up* a namespace, generating a hierarchy array from itself and its parents. */
+export const namespaceListFromNamespace = (
+  n: Namespace | undefined,
+): string[] | null => {
+  if (!n) return null;
+  const ret: string[] = [];
+  let cur: Namespace | undefined = n;
+  while (cur && cur.name) {
+    ret.unshift(cur.name);
+    cur = cur.namespace;
+  }
+  return ret;
+};
+
+export const filenameFromNamespaces = (ns: string[]): string =>
+  `${ns.join(".")}.ts`;

package/src/helpers/visibilityHelperFile.ts

@@ -0,0 +1,63 @@
+import { emitFile, Program, resolvePath } from "@typespec/compiler";
+import { EmitterOptions } from "../lib.js";
+
+const visibilityHelperFile = `
+/* eslint-disable */
+
+/*
+  This file is auto-generated by typespec-typescript-emitter and
+  contains helpers for accessing lifecycle-visibility-modified
+  variants of the emitted types.
+*/
+
+export enum Lifecycle {
+  Read, Create, Update, Delete, Query,
+  None, All
+}
+
+export type VisibilityMap<T> = {
+  [K in keyof T]?: {
+    vis?: readonly Lifecycle[]
+    nested?: VisibilityMap<T[K]>
+  }
+}
+
+export type FilterLifecycle<
+  T,
+  M extends VisibilityMap<T>,
+  Current extends Lifecycle
+> = {
+  [K in keyof T as (
+    Current extends Lifecycle.All
+      ? K
+      : Current extends Lifecycle.None
+        ? never
+        : K extends keyof M
+          ? M[K] extends { vis?: readonly (infer L)[]; }
+            ? (undefined extends M[K]['vis']
+              ? K
+              : (Current extends L ? K : never)
+            )
+            : K
+          : K
+  )]: K extends keyof M
+    ? M[K] extends {nested?: infer N}
+      ? N extends VisibilityMap<T[K]>
+        ? FilterLifecycle<T[K], N, Current>
+        : T[K]
+      : T[K]
+    : T[K]
+}
+`;
+
+export const visibilityHelperFileName = "lifecycleVisibility.ts";
+
+export const emitVisibilityHelperFile = async (
+  program: Program,
+  options: EmitterOptions,
+): Promise<void> => {
+  await emitFile(program, {
+    path: resolvePath(options["out-dir"], visibilityHelperFileName),
+    content: visibilityHelperFile,
+  });
+};

package/src/lib.ts

@@ -1,7 +1,11 @@
-import { createTypeSpecLibrary, JSONSchemaType } from "@typespec/compiler";
+import {
+  createTypeSpecLibrary,
+  EmitContext,
+  JSONSchemaType,
+} from "@typespec/compiler";
 
 export interface EmitterOptions {
-  "root-namespace": string;
+  "root-namespaces": string[];
   "out-dir": string;
   "enable-types": boolean;
   "enable-typeguards": boolean;
@@ -15,7 +19,7 @@ const EmitterOptionsSchema: JSONSchemaType<EmitterOptions> = {
   type: "object",
   additionalProperties: false,
   properties: {
-    "root-namespace": { type: "string" },
+    "root-namespaces": { type: "array", items: { type: "string" } },
     "out-dir": { type: "string", format: "absolute-path" },
     "enable-types": { type: "boolean" },
     "enable-typeguards": { type: "boolean" },
@@ -24,9 +28,26 @@ const EmitterOptionsSchema: JSONSchemaType<EmitterOptions> = {
     "string-nominal-enums": { type: "boolean" },
     "serializable-date-types": { type: "boolean" },
   },
-  required: ["root-namespace"],
+  required: ["root-namespaces"],
 };
 
+/** Maps option to its default value and options that must be set to `true` for this one to work */
+export const optionDependencies = (
+  context: EmitContext,
+): {
+  [K in keyof EmitterOptions]: [EmitterOptions[K], (keyof EmitterOptions)[]];
+} => ({
+  ["root-namespaces"]: [[], []],
+  ["out-dir"]: [context.emitterOutputDir, []],
+  ["enable-types"]: [false, []],
+  ["enable-routes"]: [false, []],
+  ["string-nominal-enums"]: [false, []],
+  ["serializable-date-types"]: [false, []],
+
+  ["enable-typeguards"]: [false, ["enable-types"]],
+  ["enable-routed-typemap"]: [false, ["enable-types"]],
+});
+
 export const $lib = createTypeSpecLibrary({
   name: "typespec-typescript-emitter",
   diagnostics: {},

package/src/parseOptions.ts

@@ -0,0 +1,26 @@
+import { EmitContext } from "@typespec/compiler";
+import { reportDiagnostic } from "./helpers/diagnostics.js";
+import { EmitterOptions, optionDependencies } from "./lib.js";
+
+/**
+ * Parses config-file options including inter-option dependencies, setting defaults,
+ * emitting warnings/errors as required,
+ * replacing options in context with parsed versions.
+ */
+export const parseOptions = (context: EmitContext<EmitterOptions>): void => {
+  Object.entries(optionDependencies).forEach(([k, val]) => {
+    const key: keyof EmitterOptions = k as any;
+    const [def, deps]: [unknown, (keyof EmitterOptions)[]] = val;
+    if (deps.length === 0) {
+      (context.options[key] as unknown) = context.options[key] ?? def;
+    } else {
+      if (context.options[key] && !deps.every((d) => context.options[d])) {
+        reportDiagnostic({
+          code: `opts-dependency-${key}`,
+          severity: "error",
+          message: `Option ${key} requires ${deps.join(", ")}`,
+        });
+      }
+    }
+  });
+};