Add brandedAliases option for strongly branded aliases

README.md

@@ -31,6 +31,7 @@ Options:
   --help                   Show help                                                                                     [boolean]
   --packageVersion         The version of the generated package                                                           [string]
   --packageName            The name of the generated package                                                              [string]
+  --brandedAliases         Generates strongly branded types for compatible aliases.                     [boolean] [default: false]
   --flavorizedAliases      Generates flavoured types for compatible aliases.                            [boolean] [default: false]
   --nodeCompatibleModules  Generate node compatible javascript                                          [boolean] [default: false]
   --rawSource              Generate raw source without any package metadata                             [boolean] [default: false]
@@ -109,7 +110,61 @@ We also consider the command line interface and feature flags to be public API.
 
 - **Conjure alias**
 
-  TypeScript uses structural (duck-typing) so aliases are currently elided.
+  By default alias types are not generated and the underlying data type is use instead.
+  However typed Aliases can be generated with either branded or flavored nominal types, with a tradeoff between the two.
+
+  Branded aliases (via `--brandedAliases`) are stronger typed and require type assertions for more intentional usage, similar to the conjure-java generator.
+
+  ```typescript
+  // generated from conjure:
+  //    FooId:
+  //      alias: string
+  export type IFooId = string & {
+    __conjure_type: "FooId",
+    __conjure_package: "com.palantir.product",
+  };
+  // generated from conjure:
+  //    BarId:
+  //      alias: string
+  export type IBarId = string & {
+    __conjure_type: "BarId",
+    __conjure_package: "com.palantir.product",
+  };
+
+  let foo: IFooId;
+  foo = "foo"; // compile error
+  foo = "foo" as IFooId; // explicit type assertion ok
+
+  const bar: IBarId = value; // compile error, different alias types do not mix
+
+  const id: string = foo; // ok, can set string value from alias
+  const bar2: IBarId = id; // compile error, cannot set alias type from string without type assertion.
+  ```
+
+  Flavored types (via `--flavorizedAliases`) protect only between aliases but still allow implicit casting to & from the base type.
+
+  ```typescript
+  // generated from conjure:
+  //    FooId:
+  //      alias: string
+  export type IFooId = string & {
+    __conjure_type?: "FooId",
+    __conjure_package?: "com.palantir.product",
+  };
+  // generated from conjure:
+  //    BarId:
+  //      alias: string
+  export type IBarId = string & {
+    __conjure_type?: "BarId",
+    __conjure_package?: "com.palantir.product",
+  };
+
+  const foo: IFooId = "foo"; // ok to set from string
+  const bar: IBarId = foo; // compile error, different alias types do not mix
+
+  const id: string = foo; // ok, can set string value from alias
+  const bar2: IBarId = id; // ok, but no protection from string back to alias type this may mask an unintentional bug depending on usage.
+  ```
 
 ## Example Client interfaces
 

changelog/@unreleased/pr-225.v2.yml

@@ -0,0 +1,5 @@
+type: feature
+feature:
+  description: Add brandedAliases option for strongly branded aliases
+  links:
+  - https://github.com/palantir/conjure-typescript/pull/225

src/commands/generate/__tests__/generatorTest.ts

@@ -33,7 +33,7 @@ import { generate } from "../generator";
 import { typeNameToFilePath } from "../simpleAst";
 import { ITypeGenerationFlags } from "../typeGenerationFlags";
 import { isFlavorizable } from "../utils";
-import { DEFAULT_TYPE_GENERATION_FLAGS, FLAVORED_TYPE_GENERATION_FLAGS, READONLY_TYPE_GENERATION_FLAGS } from "./resources/constants";
+import { BRANDED_TYPE_GENERATION_FLAGS, DEFAULT_TYPE_GENERATION_FLAGS, FLAVORED_TYPE_GENERATION_FLAGS, READONLY_TYPE_GENERATION_FLAGS } from "./resources/constants";
 import { assertOutputAndExpectedAreEqual } from "./testTypesGeneratorTest";
 
 describe("generator", () => {
@@ -106,6 +106,7 @@ export { integrationSecond };
 
 const irDir = path.join(__dirname, "../../../../build/ir-test-cases");
 const testCaseDir = path.join(__dirname, "resources/test-cases");
+const brandedTestCaseDir = path.join(__dirname, "resources/branded-test-cases");
 const flavoredTestCaseDir = path.join(__dirname, "resources/flavored-test-cases");
 const readonlyTestCaseDir = path.join(__dirname, "resources/readonly-test-cases");
 
@@ -114,11 +115,17 @@ describe("definitionTests", () => {
         const definitionFilePath = path.join(irDir, fileName);
         const paths = fileName.substring(0, fileName.lastIndexOf("."));
         const actualTestCaseDir = path.join(testCaseDir, paths);
+        const actualBrandedTestCaseDir = path.join(brandedTestCaseDir, paths);
         const actualFlavoredTestCaseDir = path.join(flavoredTestCaseDir, paths);
         const actualReadonlyTestCaseDir = path.join(readonlyTestCaseDir, paths);
 
         it(`${fileName} produces equivalent TypeScript`, testGenerateAllFilesAreTheSame(definitionFilePath, paths, actualTestCaseDir, DEFAULT_TYPE_GENERATION_FLAGS));
 
+        // Not every test has a branded version
+        if (fs.existsSync(actualBrandedTestCaseDir)) {
+            it(`${fileName} produces equivalent branded TypeScript`, testGenerateAllFilesAreTheSame(definitionFilePath, paths, actualBrandedTestCaseDir, BRANDED_TYPE_GENERATION_FLAGS));
+        }
+
         // Not every test has a flavored version
         if (fs.existsSync(actualFlavoredTestCaseDir)) {
             it(`${fileName} produces equivalent flavored TypeScript`, testGenerateAllFilesAreTheSame(definitionFilePath, paths, actualFlavoredTestCaseDir, FLAVORED_TYPE_GENERATION_FLAGS));
@@ -152,7 +159,7 @@ function expectAllFilesAreTheSame(
 ) {
     for (const type of definition.types) {
         // We do not generate flavoured types for all aliases
-        if (type.type === "alias" && !isFlavorizable(type.alias.alias, typeGenerationFlags.flavorizedAliases)) {
+        if (type.type === "alias" && !isFlavorizable(type.alias.alias, typeGenerationFlags.aliases)) {
             continue;
         }
         const relativeFilePath = typeNameToFilePath(ITypeDefinition.visit(type, typeNameVisitor));