@distrohelena/canton-typescript-sdk 0.1.28 → 0.1.30

package/dist/daml-interface/emission/template-binding-emitter.js

@@ -3,6 +3,7 @@ import { GeneratedChoiceBinding } from "../emission-model/generated-choice-bindi
 import { GeneratedTemplateBinding, GeneratedTemplateBindingField, } from "../emission-model/generated-template-binding.js";
 import { GeneratedTemplateBindingFile } from "../emission-model/generated-template-binding-file.js";
 import { TypeScriptNameResolver } from "./type-script-name-resolver.js";
+import { RelativeModuleSpecifier } from "./relative-module-specifier.js";
 /** Emits typed contract and exercise-event bindings for analyzed DAML templates. */
 export class TemplateBindingEmitter {
     nameResolver;
@@ -15,12 +16,12 @@ export class TemplateBindingEmitter {
         this.nameResolver.prepareTemplatesOrThrow(templates);
     }
     /** Emits a generated TypeScript file for one analyzed DAML template. */
-    emitTemplateFile(template, namedTypeFiles = []) {
-        const namedReferences = this.resolveNamedReferences(template, namedTypeFiles);
+    emitTemplateFile(template, namedTypeFiles = [], moduleImportStyle) {
+        const namedReferences = this.resolveNamedReferences(template, namedTypeFiles, moduleImportStyle);
         const binding = this.createBinding(template, namedReferences);
         return new GeneratedTemplateBindingFile({
             path: binding.path,
-            contents: this.emitContents(binding, namedReferences),
+            contents: this.emitContents(binding, namedReferences, moduleImportStyle),
             binding,
         });
     }
@@ -35,10 +36,16 @@ export class TemplateBindingEmitter {
         });
     }
     createBinding(template, namedReferences) {
+        const className = this.nameResolver.getTemplateClassName(template);
+        const choices = template.choices.map((choice) => ({
+            choice,
+            exercisedEventTypeName: this.nameResolver.getExercisedEventTypeName(template, choice),
+        }));
+        const runtimeWrapperTypeNames = this.resolveRuntimeWrapperTypeNames(className, choices.map((entry) => entry.exercisedEventTypeName));
         return new GeneratedTemplateBinding({
             templateIdentityKey: this.nameResolver.getTemplateIdentityKey(template),
             namespaceAlias: this.nameResolver.getNamespaceAlias(template),
-            className: this.nameResolver.getTemplateClassName(template),
+            className,
             templateIdLiteral: this.nameResolver.getTemplateIdLiteral(template),
             path: this.nameResolver.getTemplateFilePath(template),
             createFieldsTypeName: this.nameResolver.getCreateFieldsTypeName(template),
@@ -48,24 +55,25 @@ export class TemplateBindingEmitter {
                 propertyName: this.nameResolver.getFieldPropertyName(template, field),
                 constructorParameterName: this.nameResolver.getFieldConstructorParameterName(template, field),
                 type: this.normalizeType(field.type),
-                typeName: this.getTypeName(this.normalizeType(field.type), namedReferences),
+                typeName: this.getTypeName(this.normalizeType(field.type), namedReferences, runtimeWrapperTypeNames),
             })),
-            choices: template.choices.map((choice) => new GeneratedChoiceBinding({
+            choices: choices.map(({ choice, exercisedEventTypeName }) => new GeneratedChoiceBinding({
                 choiceIdentityKey: this.nameResolver.getChoiceIdentityKey(template, choice),
                 name: choice.name,
                 methodName: this.nameResolver.getChoiceMethodName(template, choice),
                 choiceTypeName: this.nameResolver.getChoiceTypeName(template, choice),
-                exercisedEventTypeName: this.nameResolver.getExercisedEventTypeName(template, choice),
+                exercisedEventTypeName,
                 parameterName: this.nameResolver.getChoiceParameterName(template, choice),
                 parameterType: this.normalizeType(choice.parameterType),
-                parameterTypeName: this.getTypeName(this.normalizeType(choice.parameterType), namedReferences),
+                parameterTypeName: this.getTypeName(this.normalizeType(choice.parameterType), namedReferences, runtimeWrapperTypeNames),
                 returnType: this.normalizeType(choice.returnType),
-                returnTypeName: this.getTypeName(this.normalizeType(choice.returnType), namedReferences),
+                returnTypeName: this.getTypeName(this.normalizeType(choice.returnType), namedReferences, runtimeWrapperTypeNames),
             })),
         });
     }
-    emitContents(binding, namedReferences) {
-        const imports = this.emitImports(binding, namedReferences);
+    emitContents(binding, namedReferences, moduleImportStyle) {
+        const runtimeWrapperTypeNames = this.resolveRuntimeWrapperTypeNames(binding.className, binding.choices.map((choice) => choice.exercisedEventTypeName));
+        const imports = this.emitImports(binding, namedReferences, runtimeWrapperTypeNames, moduleImportStyle);
         const fields = binding.createFields.map((field) => `    readonly ${field.propertyName}: ${field.typeName};`);
         const constructorParameters = binding.createFields.map((field) => `${field.constructorParameterName}: ${field.typeName}`);
         const constructorAssignments = binding.createFields.map((field) => `        this.${field.propertyName} = ${field.constructorParameterName};`);
@@ -80,14 +88,14 @@ export class TemplateBindingEmitter {
             ...fields,
             "}",
             "",
-            this.emitTemplateClass(binding, constructorParameters, constructorAssignments, orderedArguments, exercisedReturnType),
+            this.emitTemplateClass(binding, constructorParameters, constructorAssignments, orderedArguments, exercisedReturnType, runtimeWrapperTypeNames),
             ...(binding.choices.length === 0 ? [] : ["", ...binding.choices.flatMap((choice) => [
-                    this.emitChoiceEventClass(binding, choice),
+                    this.emitChoiceEventClass(binding, choice, runtimeWrapperTypeNames),
                     "",
                 ])]),
         ].join("\n");
     }
-    emitImports(binding, namedReferences) {
+    emitImports(binding, namedReferences, runtimeWrapperTypeNames, moduleImportStyle) {
         const namedImports = new Map();
         for (const reference of namedReferences.values()) {
             const imported = namedImports.get(reference.path) ?? new Map();
@@ -95,17 +103,34 @@ export class TemplateBindingEmitter {
             namedImports.set(reference.path, imported);
         }
         return [
-            'import { DamlMaterializationError, DamlTemplate, decodeDamlValue, materializeDamlValue, normalizeDamlCreatedEventSource, normalizeDamlExercisedEventSource } from "@distrohelena/canton-typescript-sdk/daml-interface";',
-            'import type { DamlCreatedEventSource, DamlDate, DamlExercisedEventMetadata, DamlExercisedEventSource, DamlNormalizedExercisedEvent, DamlNumeric, DamlParty, DamlTimestamp, DamlTypeDescriptor, DamlUnit } from "@distrohelena/canton-typescript-sdk/daml-interface";',
-            `import { generatedDamlTypeDescriptorRegistry } from ${JSON.stringify(this.relativeFilePath(binding.path, "generated/support/descriptors.ts"))};`,
-            ...[...namedImports.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([path, imported]) => `import type { ${[...imported.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([name, alias]) => `${name} as ${alias}`).join(", ")} } from ${JSON.stringify(path)};`),
+            `import { ${[
+                "DamlEventSourceNormalizer",
+                "DamlMaterializationError",
+                "DamlTemplate",
+                "DamlValueConverter",
+                "DamlValueMaterializer",
+            ].map((name) => this.emitImportedName(name, runtimeWrapperTypeNames)).join(", ")} } from "@distrohelena/canton-typescript-sdk/daml-interface";`,
+            `import type { ${[
+                "DamlCreatedEventSource",
+                "DamlDate",
+                "DamlExercisedEventMetadata",
+                "DamlExercisedEventSource",
+                "DamlNormalizedExercisedEvent",
+                "DamlNumeric",
+                "DamlParty",
+                "DamlTimestamp",
+                "DamlTypeDescriptor",
+                "DamlUnit",
+            ].map((name) => this.emitImportedName(name, runtimeWrapperTypeNames)).join(", ")} } from "@distrohelena/canton-typescript-sdk/daml-interface";`,
+            `import { GeneratedDamlTypeDescriptorRegistry } from ${JSON.stringify(this.relativeFilePath(binding.path, "generated/support/descriptors.ts", moduleImportStyle))};`,
+            ...[...namedImports.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([path, imported]) => `import type { ${[...imported.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([name, alias]) => name === alias ? name : `${name} as ${alias}`).join(", ")} } from ${JSON.stringify(path)};`),
         ];
     }
-    emitTemplateClass(binding, constructorParameters, constructorAssignments, orderedArguments, exercisedReturnType) {
+    emitTemplateClass(binding, constructorParameters, constructorAssignments, orderedArguments, exercisedReturnType, runtimeWrapperTypeNames) {
         return [
-            `export class ${binding.className} extends DamlTemplate implements ${binding.createFieldsTypeName} {`,
+            `export class ${binding.className} extends ${this.getSdkName("DamlTemplate", runtimeWrapperTypeNames)} implements ${binding.createFieldsTypeName} {`,
             `    public static readonly templateId = ${JSON.stringify(binding.templateIdLiteral)};`,
-            `    private static readonly descriptor: DamlTypeDescriptor = ${this.emitTemplateDescriptor(binding)};`,
+            `    private static readonly descriptor: ${this.getSdkName("DamlTypeDescriptor", runtimeWrapperTypeNames)} = ${this.emitTemplateDescriptor(binding)};`,
             "",
             ...binding.createFields.map((field) => `    public readonly ${field.propertyName}: ${field.typeName};`),
             ...(binding.createFields.length === 0 ? [] : [""]),
@@ -114,48 +139,48 @@ export class TemplateBindingEmitter {
             ...constructorAssignments,
             "    }",
             "",
-            `    public static fromCreatedEvent(event: DamlCreatedEventSource): ${binding.className} {`,
-            "        const normalized = normalizeDamlCreatedEventSource(event);",
+            `    public static fromCreatedEvent(event: ${this.getSdkName("DamlCreatedEventSource", runtimeWrapperTypeNames)}): ${binding.className} {`,
+            `        const normalized = ${this.getSdkName("DamlEventSourceNormalizer", runtimeWrapperTypeNames)}.normalizeCreated(event);`,
             `        ${binding.className}.assertTemplateIdentity(normalized.metadata.templateId);`,
-            `        const fields = materializeDamlValue<${binding.createFieldsTypeName}>(decodeDamlValue(normalized.payload, ${binding.className}.descriptor, generatedDamlTypeDescriptorRegistry, "create arguments"));`,
+            `        const fields = ${this.getSdkName("DamlValueMaterializer", runtimeWrapperTypeNames)}.materialize<${binding.createFieldsTypeName}>(${this.getSdkName("DamlValueConverter", runtimeWrapperTypeNames)}.decode(normalized.payload, ${binding.className}.descriptor, GeneratedDamlTypeDescriptorRegistry, "create arguments"));`,
             `        return new ${binding.className}(`,
             "            normalized.contractId,",
             ...orderedArguments,
             "        );",
             "    }",
             "",
-            `    public static fromExercisedEvent(event: DamlExercisedEventSource): ${exercisedReturnType} {`,
-            "        const normalized = normalizeDamlExercisedEventSource(event);",
+            `    public static fromExercisedEvent(event: ${this.getSdkName("DamlExercisedEventSource", runtimeWrapperTypeNames)}): ${exercisedReturnType} {`,
+            `        const normalized = ${this.getSdkName("DamlEventSourceNormalizer", runtimeWrapperTypeNames)}.normalizeExercised(event);`,
             `        ${binding.className}.assertTemplateIdentity(normalized.metadata.templateId);`,
             "        switch (normalized.choice) {",
             ...binding.choices.map((choice) => `            case ${JSON.stringify(choice.name)}:\n                return ${choice.exercisedEventTypeName}.fromNormalizedEvent(normalized);`),
             "            default:",
-            `                throw new DamlMaterializationError("choice", \`Unexpected choice '\${normalized.choice}' for template '${binding.templateIdLiteral}'\`);`,
+            `                throw new ${this.getSdkName("DamlMaterializationError", runtimeWrapperTypeNames)}("choice", \`Unexpected choice '\${normalized.choice}' for template '${binding.templateIdLiteral}'\`);`,
             "        }",
             "    }",
             "",
             "    private static assertTemplateIdentity(identity: { readonly packageId: string; readonly moduleName: string; readonly entityName: string }): void {",
             `        if (identity.packageId !== ${JSON.stringify(this.packageId(binding))} || identity.moduleName !== ${JSON.stringify(this.moduleName(binding))} || identity.entityName !== ${JSON.stringify(this.entityName(binding))}) {`,
-            `            throw new DamlMaterializationError("template ID", \`Expected template '${binding.templateIdLiteral}' but received '\${identity.packageId}:\${identity.moduleName}:\${identity.entityName}'\`);`,
+            `            throw new ${this.getSdkName("DamlMaterializationError", runtimeWrapperTypeNames)}("template ID", \`Expected template '${binding.templateIdLiteral}' but received '\${identity.packageId}:\${identity.moduleName}:\${identity.entityName}'\`);`,
             "        }",
             "    }",
             "}",
         ].join("\n");
     }
-    emitChoiceEventClass(binding, choice) {
+    emitChoiceEventClass(binding, choice, runtimeWrapperTypeNames) {
         return [
             `export class ${choice.exercisedEventTypeName} {`,
-            `    private static readonly argumentDescriptor: DamlTypeDescriptor = ${this.emitDescriptor(choice.parameterType)};`,
-            `    private static readonly resultDescriptor: DamlTypeDescriptor = ${this.emitDescriptor(choice.returnType)};`,
+            `    private static readonly argumentDescriptor: ${this.getSdkName("DamlTypeDescriptor", runtimeWrapperTypeNames)} = ${this.emitDescriptor(choice.parameterType)};`,
+            `    private static readonly resultDescriptor: ${this.getSdkName("DamlTypeDescriptor", runtimeWrapperTypeNames)} = ${this.emitDescriptor(choice.returnType)};`,
             "",
             `    public readonly choiceName = ${JSON.stringify(choice.name)} as const;`,
             "    public readonly contractId: string;",
             `    public readonly argument: ${choice.parameterTypeName};`,
             `    public readonly result: ${choice.returnTypeName};`,
             "    public readonly consuming: boolean;",
-            "    public readonly metadata: DamlExercisedEventMetadata;",
+            `    public readonly metadata: ${this.getSdkName("DamlExercisedEventMetadata", runtimeWrapperTypeNames)};`,
             "",
-            "    public constructor(contractId: string, argument: " + choice.parameterTypeName + ", result: " + choice.returnTypeName + ", consuming: boolean, metadata: DamlExercisedEventMetadata) {",
+            "    public constructor(contractId: string, argument: " + choice.parameterTypeName + ", result: " + choice.returnTypeName + ", consuming: boolean, metadata: " + this.getSdkName("DamlExercisedEventMetadata", runtimeWrapperTypeNames) + ") {",
             "        this.contractId = contractId;",
             "        this.argument = argument;",
             "        this.result = result;",
@@ -163,25 +188,25 @@ export class TemplateBindingEmitter {
             "        this.metadata = metadata;",
             "    }",
             "",
-            `    public static fromExercisedEvent(event: DamlExercisedEventSource): ${choice.exercisedEventTypeName} {`,
-            "        const normalized = normalizeDamlExercisedEventSource(event);",
+            `    public static fromExercisedEvent(event: ${this.getSdkName("DamlExercisedEventSource", runtimeWrapperTypeNames)}): ${choice.exercisedEventTypeName} {`,
+            `        const normalized = ${this.getSdkName("DamlEventSourceNormalizer", runtimeWrapperTypeNames)}.normalizeExercised(event);`,
             `        ${choice.exercisedEventTypeName}.assertTemplateIdentity(normalized.metadata.templateId);`,
             `        return ${choice.exercisedEventTypeName}.fromNormalizedEvent(normalized);`,
             "    }",
             "",
-            `    public static fromNormalizedEvent(event: DamlNormalizedExercisedEvent): ${choice.exercisedEventTypeName} {`,
+            `    public static fromNormalizedEvent(event: ${this.getSdkName("DamlNormalizedExercisedEvent", runtimeWrapperTypeNames)}): ${choice.exercisedEventTypeName} {`,
             `        ${choice.exercisedEventTypeName}.assertTemplateIdentity(event.metadata.templateId);`,
             `        if (event.choice !== ${JSON.stringify(choice.name)}) {`,
-            `            throw new DamlMaterializationError("choice", \`Expected choice '${choice.name}' but received '\${event.choice}'\`);`,
+            `            throw new ${this.getSdkName("DamlMaterializationError", runtimeWrapperTypeNames)}("choice", \`Expected choice '${choice.name}' but received '\${event.choice}'\`);`,
             "        }",
-            `        const argument = materializeDamlValue<${choice.parameterTypeName}>(decodeDamlValue(event.argument, ${choice.exercisedEventTypeName}.argumentDescriptor, generatedDamlTypeDescriptorRegistry, "choice argument"));`,
-            `        const result = materializeDamlValue<${choice.returnTypeName}>(decodeDamlValue(event.result, ${choice.exercisedEventTypeName}.resultDescriptor, generatedDamlTypeDescriptorRegistry, "exercise result"));`,
+            `        const argument = ${this.getSdkName("DamlValueMaterializer", runtimeWrapperTypeNames)}.materialize<${choice.parameterTypeName}>(${this.getSdkName("DamlValueConverter", runtimeWrapperTypeNames)}.decode(event.argument, ${choice.exercisedEventTypeName}.argumentDescriptor, GeneratedDamlTypeDescriptorRegistry, "choice argument"));`,
+            `        const result = ${this.getSdkName("DamlValueMaterializer", runtimeWrapperTypeNames)}.materialize<${choice.returnTypeName}>(${this.getSdkName("DamlValueConverter", runtimeWrapperTypeNames)}.decode(event.result, ${choice.exercisedEventTypeName}.resultDescriptor, GeneratedDamlTypeDescriptorRegistry, "exercise result"));`,
             `        return new ${choice.exercisedEventTypeName}(event.contractId, argument, result, event.consuming, event.metadata);`,
             "    }",
             "",
             "    private static assertTemplateIdentity(identity: { readonly packageId: string; readonly moduleName: string; readonly entityName: string }): void {",
             `        if (identity.packageId !== ${JSON.stringify(this.packageId(binding))} || identity.moduleName !== ${JSON.stringify(this.moduleName(binding))} || identity.entityName !== ${JSON.stringify(this.entityName(binding))}) {`,
-            `            throw new DamlMaterializationError("template ID", \`Expected template '${binding.templateIdLiteral}' but received '\${identity.packageId}:\${identity.moduleName}:\${identity.entityName}'\`);`,
+            `            throw new ${this.getSdkName("DamlMaterializationError", runtimeWrapperTypeNames)}("template ID", \`Expected template '${binding.templateIdLiteral}' but received '\${identity.packageId}:\${identity.moduleName}:\${identity.entityName}'\`);`,
             "        }",
             "    }",
             "}",
@@ -210,47 +235,102 @@ export class TemplateBindingEmitter {
                 return `{ kind: "variant", constructors: [${type.constructors.map((constructor) => `{ constructor: ${JSON.stringify(constructor.constructor)}, payload: ${this.emitDescriptor(constructor.payload)} }`).join(", ")}] }`;
             case "enum":
                 return `{ kind: "enum", constructors: [${type.constructors.map((constructor) => JSON.stringify(constructor)).join(", ")}] }`;
+            case "typeVariable":
+                throw new Error("Cannot emit generic DAML type variables");
             case "namedReference":
-                return `{ kind: "namedReference", identity: { packageId: ${JSON.stringify(type.identity.packageId)}, moduleName: ${JSON.stringify(type.identity.moduleName)}, entityName: ${JSON.stringify(type.identity.name)} } }`;
+                return `{ kind: "namedReference", identity: { packageId: ${JSON.stringify(type.identity.packageId)}, moduleName: ${JSON.stringify(type.identity.moduleName)}, entityName: ${JSON.stringify(type.identity.name)} }, typeArguments: [${(type.typeArguments ?? []).map((argument) => this.emitDescriptor(argument)).join(", ")}] }`;
         }
     }
-    getTypeName(type, namedReferences) {
+    getTypeName(type, namedReferences, runtimeWrapperTypeNames = new Map()) {
         switch (type.kind) {
             case "primitive":
-                return this.getPrimitiveTypeName(type.builtinType);
+                return this.getPrimitiveTypeName(type.builtinType, runtimeWrapperTypeNames);
             case "contractId":
                 return "string";
             case "optional":
-                return `${this.getTypeName(type.element, namedReferences)} | undefined`;
+                return `${this.getTypeName(type.element, namedReferences, runtimeWrapperTypeNames)} | undefined`;
             case "list":
-                return `readonly ${this.getTypeName(type.element, namedReferences)}[]`;
+                return `readonly ${this.getArrayElementTypeName(type.element, namedReferences, runtimeWrapperTypeNames)}[]`;
             case "textMap":
-                return `ReadonlyMap<string, ${this.getTypeName(type.value, namedReferences)}>`;
+                return `ReadonlyMap<string, ${this.getTypeName(type.value, namedReferences, runtimeWrapperTypeNames)}>`;
             case "genMap":
-                return `ReadonlyMap<${this.getTypeName(type.key, namedReferences)}, ${this.getTypeName(type.value, namedReferences)}>`;
+                return `ReadonlyMap<${this.getTypeName(type.key, namedReferences, runtimeWrapperTypeNames)}, ${this.getTypeName(type.value, namedReferences, runtimeWrapperTypeNames)}>`;
             case "record":
-                return `{ ${type.fields.map((field) => `readonly ${field.propertyName}: ${this.getTypeName(field.type, namedReferences)};`).join(" ")} }`;
+                return `{ ${type.fields.map((field) => `readonly ${field.propertyName}: ${this.getTypeName(field.type, namedReferences, runtimeWrapperTypeNames)};`).join(" ")} }`;
             case "variant":
-                return type.constructors.map((constructor) => `{ readonly tag: ${JSON.stringify(constructor.constructor)}; readonly value: ${this.getTypeName(constructor.payload, namedReferences)}; }`).join(" | ");
+                return type.constructors.map((constructor) => `{ readonly tag: ${JSON.stringify(constructor.constructor)}; readonly value: ${this.getTypeName(constructor.payload, namedReferences, runtimeWrapperTypeNames)}; }`).join(" | ");
             case "enum":
                 return type.constructors.map((constructor) => JSON.stringify(constructor)).join(" | ");
-            case "namedReference":
-                return this.getNamedReference(type.identity, namedReferences).alias;
+            case "typeVariable":
+                throw new Error("Cannot emit generic DAML type variables");
+            case "namedReference": {
+                const name = this.getNamedReference(type.identity, namedReferences).alias;
+                return (type.typeArguments?.length ?? 0) === 0
+                    ? name
+                    : `${name}<${(type.typeArguments ?? []).map((argument) => this.getTypeName(argument, namedReferences, runtimeWrapperTypeNames)).join(", ")}>`;
+            }
         }
     }
-    getPrimitiveTypeName(type) {
+    getArrayElementTypeName(type, namedReferences, runtimeWrapperTypeNames) {
+        const name = this.getTypeName(type, namedReferences, runtimeWrapperTypeNames);
+        return type.kind === "optional" || type.kind === "variant" || type.kind === "enum"
+            ? `(${name})`
+            : name;
+    }
+    getPrimitiveTypeName(type, runtimeWrapperTypeNames) {
         switch (type) {
-            case DamlLfBuiltinType.unit: return "DamlUnit";
+            case DamlLfBuiltinType.unit: return runtimeWrapperTypeNames.get("DamlUnit") ?? "DamlUnit";
             case DamlLfBuiltinType.bool: return "boolean";
             case DamlLfBuiltinType.int64: return "bigint";
-            case DamlLfBuiltinType.date: return "DamlDate";
-            case DamlLfBuiltinType.timestamp: return "DamlTimestamp";
-            case DamlLfBuiltinType.numeric: return "DamlNumeric";
-            case DamlLfBuiltinType.party: return "DamlParty";
+            case DamlLfBuiltinType.date: return runtimeWrapperTypeNames.get("DamlDate") ?? "DamlDate";
+            case DamlLfBuiltinType.timestamp: return runtimeWrapperTypeNames.get("DamlTimestamp") ?? "DamlTimestamp";
+            case DamlLfBuiltinType.numeric: return runtimeWrapperTypeNames.get("DamlNumeric") ?? "DamlNumeric";
+            case DamlLfBuiltinType.party: return runtimeWrapperTypeNames.get("DamlParty") ?? "DamlParty";
             case DamlLfBuiltinType.text: return "string";
             default: throw new Error(`Cannot emit unsupported primitive DAML type '${type}'`);
         }
     }
+    resolveRuntimeWrapperTypeNames(className, exercisedEventTypeNames) {
+        const usedNames = new Set([className, ...exercisedEventTypeNames]);
+        const names = new Map();
+        for (const name of [
+            "DamlCreatedEventSource",
+            "DamlDate",
+            "DamlEventSourceNormalizer",
+            "DamlExercisedEventMetadata",
+            "DamlExercisedEventSource",
+            "DamlMaterializationError",
+            "DamlNormalizedExercisedEvent",
+            "DamlNumeric",
+            "DamlParty",
+            "DamlTemplate",
+            "DamlTimestamp",
+            "DamlTypeDescriptor",
+            "DamlUnit",
+            "DamlValueConverter",
+            "DamlValueMaterializer",
+        ]) {
+            let localName = name;
+            let suffix = 2;
+            if (usedNames.has(localName)) {
+                localName = `GeneratedRuntime${name}`;
+            }
+            while (usedNames.has(localName)) {
+                localName = `GeneratedRuntime${name}_${suffix}`;
+                suffix += 1;
+            }
+            usedNames.add(localName);
+            names.set(name, localName);
+        }
+        return names;
+    }
+    getSdkName(name, runtimeWrapperTypeNames) {
+        return runtimeWrapperTypeNames.get(name) ?? name;
+    }
+    emitImportedName(name, runtimeWrapperTypeNames) {
+        const localName = this.getSdkName(name, runtimeWrapperTypeNames);
+        return localName === name ? name : `${name} as ${localName}`;
+    }
     normalizeType(type) {
         if ("kind" in type) {
             return type;
@@ -262,7 +342,14 @@ export class TemplateBindingEmitter {
             return { kind: "contractId" };
         }
         else if (type.typeConReference !== undefined) {
-            return { kind: "namedReference", identity: type.typeConReference };
+            if (type.typeArguments.length !== 0) {
+                throw new Error("Cannot emit generic DAML named type applications");
+            }
+            return {
+                kind: "namedReference",
+                identity: type.typeConReference,
+                typeArguments: [],
+            };
         }
         const arguments_ = type.typeArguments.map((argument) => this.normalizeType(argument));
         switch (type.builtinType) {
@@ -289,7 +376,7 @@ export class TemplateBindingEmitter {
                 throw new Error("Cannot emit unsupported DAML type");
         }
     }
-    resolveNamedReferences(template, namedTypeFiles) {
+    resolveNamedReferences(template, namedTypeFiles, moduleImportStyle) {
         const identities = new Map();
         for (const type of [
             ...template.createFields.map((field) => this.normalizeType(field.type)),
@@ -304,7 +391,26 @@ export class TemplateBindingEmitter {
         }
         const aliases = new Map();
         const usedAliases = new Set();
-        for (const [key, reference] of [...identities.entries()].sort(([left], [right]) => left.localeCompare(right))) {
+        const exportedNameCounts = new Map();
+        for (const [key, reference] of identities) {
+            const file = namedTypeFiles.find((candidate) => candidate.packageId === reference.identity.packageId
+                && candidate.moduleName === reference.identity.moduleName);
+            const exportedName = file?.exportedTypeNamesByIdentity.get(key);
+            if (exportedName !== undefined) {
+                exportedNameCounts.set(exportedName, (exportedNameCounts.get(exportedName) ?? 0) + 1);
+            }
+        }
+        for (const [key, reference] of [...identities.entries()].sort(([, left], [, right]) => {
+            const leftIsLocal = left.identity.packageId === template.templateId.packageId
+                && left.identity.moduleName === template.templateId.moduleName;
+            const rightIsLocal = right.identity.packageId === template.templateId.packageId
+                && right.identity.moduleName === template.templateId.moduleName;
+            if (leftIsLocal !== rightIsLocal) {
+                return leftIsLocal ? -1 : 1;
+            }
+            return this.getNamedReferenceKey(left.identity)
+                .localeCompare(this.getNamedReferenceKey(right.identity));
+        })) {
             const file = namedTypeFiles.find((candidate) => candidate.packageId === reference.identity.packageId
                 && candidate.moduleName === reference.identity.moduleName);
             const exportedName = file?.exportedTypeNamesByIdentity.get(key);
@@ -315,7 +421,11 @@ export class TemplateBindingEmitter {
                 aliases.set(key, reference.identity.name);
                 continue;
             }
-            const baseAlias = this.toTypeName(`${reference.identity.packageId} ${reference.identity.moduleName} ${exportedName}`);
+            const isLocal = reference.identity.packageId === template.templateId.packageId
+                && reference.identity.moduleName === template.templateId.moduleName;
+            const baseAlias = exportedNameCounts.get(exportedName) === 1 || isLocal
+                ? exportedName
+                : this.toTypeName(`${file.namespaceAlias} ${exportedName}`);
             let alias = baseAlias;
             let escalation = 2;
             while (usedAliases.has(alias)) {
@@ -338,7 +448,7 @@ export class TemplateBindingEmitter {
                     }];
             }
             return [key, {
-                    path: this.relativeFilePath(this.nameResolver.getTemplateFilePath(template), file.path),
+                    path: this.relativeFilePath(this.nameResolver.getTemplateFilePath(template), file.path, moduleImportStyle),
                     exportedName,
                     alias: alias,
                 }];
@@ -348,6 +458,9 @@ export class TemplateBindingEmitter {
         switch (type.kind) {
             case "namedReference":
                 yield type;
+                for (const typeArgument of type.typeArguments ?? []) {
+                    yield* this.walkNamedReferences(typeArgument);
+                }
                 return;
             case "contractId": return;
             case "optional":
@@ -372,7 +485,8 @@ export class TemplateBindingEmitter {
                 }
                 return;
             case "primitive":
-            case "enum": return;
+            case "enum":
+            case "typeVariable": return;
         }
     }
     getNamedReference(identity, namedReferences) {
@@ -407,14 +521,7 @@ export class TemplateBindingEmitter {
     entityName(binding) {
         return binding.templateIdLiteral.split(":")[2];
     }
-    relativeFilePath(fromPath, toPath) {
-        const from = fromPath.split("/").slice(0, -1);
-        const to = toPath.split("/");
-        while (from[0] === to[0] && from.length > 0) {
-            from.shift();
-            to.shift();
-        }
-        const relative = from.map(() => "..").concat(to).join("/") || ".";
-        return `${relative.startsWith(".") ? relative : `./${relative}`}`.replace(/\.ts$/, ".js");
+    relativeFilePath(fromPath, toPath, moduleImportStyle) {
+        return RelativeModuleSpecifier.fromPaths(fromPath, toPath, moduleImportStyle);
     }
 }

package/dist/daml-interface/emission/type-script-name-resolver.d.ts

@@ -2,15 +2,17 @@ import { AnalyzedChoice } from "../analysis/analyzed-choice.js";
 import { AnalyzedDamlType } from "../analysis/analyzed-daml-type.js";
 import { AnalyzedDamlTypeDefinition } from "../analysis/analyzed-daml-type-definition.js";
 import { AnalyzedTemplate, AnalyzedTemplateField } from "../analysis/analyzed-template.js";
+import { DamlInterfacePackageMetadata } from "../analysis/daml-interface-analyzer.js";
 export declare class TypeScriptNameResolver {
     private readonly templatesByIdentity;
     private resolvedTemplates;
     private resolvedModules;
-    constructor(templates?: readonly AnalyzedTemplate[]);
+    private packageMetadata;
+    constructor(templates?: readonly AnalyzedTemplate[], packageMetadata?: ReadonlyMap<string, DamlInterfacePackageMetadata>);
     /** Prepares a project-wide name table and rejects irreconcilable output collisions. */
     prepareTemplatesOrThrow(templates: readonly AnalyzedTemplate[]): void;
     /** Prepares shared package/module paths for template and named DAML type output. */
-    prepareProjectOrThrow(templates: readonly AnalyzedTemplate[], typeDefinitions: readonly AnalyzedDamlTypeDefinition[]): void;
+    prepareProjectOrThrow(templates: readonly AnalyzedTemplate[], typeDefinitions: readonly AnalyzedDamlTypeDefinition[], packageMetadata?: ReadonlyMap<string, DamlInterfacePackageMetadata>): void;
     /** Resolves the full package/module/entity identity key for a template. */
     getTemplateIdentityKey(template: AnalyzedTemplate): string;
     /** Resolves the generated namespace alias for a template package/module. */
@@ -55,6 +57,10 @@ export declare class TypeScriptNameResolver {
     private assertDistinctTemplateOutput;
     private assertDistinctNamespaceAliases;
     private getModuleDirectory;
+    private getPackageDirectoryBaseName;
+    private getPackageNamespaceLabel;
+    private toPackageNameSegment;
+    private toPackageVersionSegment;
     private getTemplateFileBaseName;
     private getPackageModuleIdentityKey;
     private getPackageModuleIdentityKeyFromParts;

package/dist/daml-interface/emission/type-script-name-resolver.js

@@ -17,18 +17,20 @@ export class TypeScriptNameResolver {
     templatesByIdentity = new Map();
     resolvedTemplates = new Map();
     resolvedModules = new Map();
-    constructor(templates = []) {
-        this.prepareTemplatesOrThrow(templates);
+    packageMetadata = new Map();
+    constructor(templates = [], packageMetadata = new Map()) {
+        this.prepareProjectOrThrow(templates, [], packageMetadata);
     }
     /** Prepares a project-wide name table and rejects irreconcilable output collisions. */
     prepareTemplatesOrThrow(templates) {
-        this.prepareProjectOrThrow(templates, []);
+        this.prepareProjectOrThrow(templates, [], this.packageMetadata);
     }
     /** Prepares shared package/module paths for template and named DAML type output. */
-    prepareProjectOrThrow(templates, typeDefinitions) {
+    prepareProjectOrThrow(templates, typeDefinitions, packageMetadata = new Map()) {
         this.templatesByIdentity.clear();
         this.resolvedTemplates.clear();
         this.resolvedModules.clear();
+        this.packageMetadata = new Map(packageMetadata);
         for (const template of templates) {
             const identityKey = this.getTemplateIdentityKey(template);
             const existing = this.templatesByIdentity.get(identityKey);
@@ -56,7 +58,7 @@ export class TypeScriptNameResolver {
         const packageDirectories = this.resolveNames(packageIds.map((packageId) => ({
             value: packageId,
             key: `package\u0000${packageId}`,
-            baseName: this.toKebabCase(packageId),
+            baseName: this.getPackageDirectoryBaseName(packageId),
             scope: "packages",
         })));
         const moduleDirectories = this.resolveNames([...modulesByIdentity.entries()].map(([identityKey, module]) => ({
@@ -74,7 +76,7 @@ export class TypeScriptNameResolver {
         const namespaceAliases = this.resolveNames([...modulesByIdentity.entries()].map(([identityKey, module]) => ({
             value: identityKey,
             key: `namespace\u0000${identityKey}`,
-            baseName: this.safeNamespaceAlias(`${module.packageId} ${module.moduleName}`),
+            baseName: this.safeNamespaceAlias(`${this.getPackageNamespaceLabel(module.packageId)} ${module.moduleName}`),
             collisionSeparator: "_",
         })));
         const classNames = this.resolveNames(allTemplates.map((template) => ({
@@ -336,6 +338,39 @@ export class TypeScriptNameResolver {
             .map((segment) => this.toKebabCase(segment))
             .join("/");
     }
+    getPackageDirectoryBaseName(packageId) {
+        const metadata = this.packageMetadata.get(packageId);
+        if (metadata === undefined
+            || metadata.packageName.trim().length === 0
+            || metadata.packageVersion.trim().length === 0) {
+            return this.toKebabCase(packageId);
+        }
+        return `${this.toPackageNameSegment(metadata.packageName)}_${this.toPackageVersionSegment(metadata.packageVersion)}`;
+    }
+    getPackageNamespaceLabel(packageId) {
+        const packageName = this.packageMetadata.get(packageId)?.packageName.trim();
+        return packageName === undefined || packageName.length === 0
+            ? packageId
+            : packageName;
+    }
+    toPackageNameSegment(value) {
+        const segment = value
+            .trim()
+            .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+            .replace(/[^A-Za-z0-9]+/g, "-")
+            .replace(/-+/g, "-")
+            .replace(/^-|-$/g, "")
+            .toLowerCase();
+        return segment.length === 0 ? "package" : segment;
+    }
+    toPackageVersionSegment(value) {
+        const segment = value
+            .trim()
+            .replace(/[^A-Za-z0-9._-]+/g, "-")
+            .replace(/-+/g, "-")
+            .replace(/^-|-$/g, "");
+        return segment.length === 0 ? "unknown" : segment;
+    }
     getTemplateFileBaseName(template) {
         const fileName = this.toKebabCase(template.templateId.templateName);
         return fileName === "index" || fileName === "types"

package/dist/daml-interface/emission-model/generated-daml-interface-project.d.ts

@@ -1,18 +1,27 @@
 import { GeneratedNamedTypeFile } from "./generated-named-type-file.js";
 import { GeneratedRegistryFile } from "./generated-registry-file.js";
+import { GeneratedSpecFile } from "./generated-spec-file.js";
 import { GeneratedSupportFile } from "./generated-support-file.js";
 import { GeneratedTemplateBindingFile } from "./generated-template-binding-file.js";
+type GeneratedProductionFile = GeneratedTemplateBindingFile | GeneratedNamedTypeFile | GeneratedRegistryFile | GeneratedSupportFile;
 export declare class GeneratedDamlInterfaceProject {
     readonly templateFiles: readonly GeneratedTemplateBindingFile[];
     readonly namedTypeFiles: readonly GeneratedNamedTypeFile[];
     readonly supportFiles: readonly GeneratedSupportFile[];
     readonly registryFile?: GeneratedRegistryFile;
     readonly indexFile?: GeneratedSupportFile;
+    /** Every non-spec module emitted by this project. */
+    readonly productionFiles: readonly GeneratedProductionFile[];
+    /** Runnable specs, each colocated with exactly one production module. */
+    readonly specFiles: readonly GeneratedSpecFile[];
     constructor(init: {
         templateFiles: readonly GeneratedTemplateBindingFile[];
         namedTypeFiles?: readonly GeneratedNamedTypeFile[];
         supportFiles?: readonly GeneratedSupportFile[];
         registryFile?: GeneratedRegistryFile;
         indexFile?: GeneratedSupportFile;
+        specFiles?: readonly GeneratedSpecFile[];
     });
+    private validateFilesOrThrow;
 }
+export {};