@distrohelena/canton-typescript-sdk 0.1.28 → 0.1.30

package/dist/daml-interface/analysis/analyzed-daml-type-definition.d.ts

@@ -1,6 +1,11 @@
 import { AnalyzedDamlEnumType, AnalyzedDamlRecordType, AnalyzedDamlVariantType } from "./analyzed-daml-type.js";
+import { DamlLfTypeParameter } from "../../daml-lf/model/daml-lf-data-type.js";
 import { TypeConReference } from "../../daml-lf/model/type-con-reference.js";
 /** A reachable named DAML data type and its complete serializable shape. */
 export type AnalyzedDamlTypeDefinition = {
     readonly identity: TypeConReference;
-} & (AnalyzedDamlRecordType | AnalyzedDamlVariantType | AnalyzedDamlEnumType);
+} & ((AnalyzedDamlRecordType & {
+    readonly typeParameters: readonly DamlLfTypeParameter[];
+}) | (AnalyzedDamlVariantType & {
+    readonly typeParameters: readonly DamlLfTypeParameter[];
+}) | AnalyzedDamlEnumType);

package/dist/daml-interface/analysis/analyzed-daml-type.d.ts

@@ -46,9 +46,15 @@ export type AnalyzedDamlEnumType = {
     readonly kind: "enum";
     readonly constructors: readonly string[];
 };
+export type AnalyzedDamlTypeVariableType = {
+    readonly kind: "typeVariable";
+    readonly name?: string;
+    readonly internedStringIndex: number;
+};
 export type AnalyzedDamlNamedReferenceType = {
     readonly kind: "namedReference";
     readonly identity: TypeConReference;
+    readonly typeArguments: readonly AnalyzedDamlType[];
 };
 /** Closed, immutable description of a DAML value serializable by the generator. */
-export type AnalyzedDamlType = AnalyzedDamlPrimitiveType | AnalyzedDamlContractIdType | AnalyzedDamlOptionalType | AnalyzedDamlListType | AnalyzedDamlTextMapType | AnalyzedDamlGenMapType | AnalyzedDamlRecordType | AnalyzedDamlVariantType | AnalyzedDamlEnumType | AnalyzedDamlNamedReferenceType;
+export type AnalyzedDamlType = AnalyzedDamlPrimitiveType | AnalyzedDamlContractIdType | AnalyzedDamlOptionalType | AnalyzedDamlListType | AnalyzedDamlTextMapType | AnalyzedDamlGenMapType | AnalyzedDamlRecordType | AnalyzedDamlVariantType | AnalyzedDamlEnumType | AnalyzedDamlTypeVariableType | AnalyzedDamlNamedReferenceType;

package/dist/daml-interface/analysis/daml-interface-analyzer.d.ts

@@ -1,12 +1,18 @@
 import { DamlLfCompilation } from "../../daml-lf/daml-lf-compilation.js";
 import { AnalyzedDamlTypeDefinition } from "./analyzed-daml-type-definition.js";
 import { AnalyzedTemplate } from "./analyzed-template.js";
+export type DamlInterfacePackageMetadata = {
+    readonly packageName: string;
+    readonly packageVersion: string;
+};
 export declare class DamlInterfaceAnalysisResult {
     readonly templates: readonly AnalyzedTemplate[];
     readonly typeDefinitions: readonly AnalyzedDamlTypeDefinition[];
+    readonly packageMetadata: ReadonlyMap<string, DamlInterfacePackageMetadata>;
     constructor(init: {
         templates: readonly AnalyzedTemplate[];
         typeDefinitions: readonly AnalyzedDamlTypeDefinition[];
+        packageMetadata?: ReadonlyMap<string, DamlInterfacePackageMetadata>;
     });
 }
 export declare class DamlInterfaceAnalyzer {

package/dist/daml-interface/analysis/daml-interface-analyzer.js

@@ -6,9 +6,11 @@ import { AnalyzedTemplate, AnalyzedTemplateField } from "./analyzed-template.js"
 export class DamlInterfaceAnalysisResult {
     templates;
     typeDefinitions;
+    packageMetadata;
     constructor(init) {
         this.templates = Object.freeze([...init.templates]);
         this.typeDefinitions = Object.freeze([...init.typeDefinitions]);
+        this.packageMetadata = new Map(init.packageMetadata);
     }
 }
 export class DamlInterfaceAnalyzer {
@@ -22,6 +24,13 @@ export class DamlInterfaceAnalyzer {
         return new DamlInterfaceAnalysisResult({
             templates,
             typeDefinitions: typeBuilder.getTypeDefinitions(),
+            packageMetadata: new Map(compilation.getPackages().map((pkg) => [
+                pkg.packageId,
+                {
+                    packageName: pkg.packageName,
+                    packageVersion: pkg.packageVersion,
+                },
+            ])),
         });
     }
     analyzeTemplateOrThrow(template, typeBuilder) {
@@ -88,15 +97,32 @@ class AnalyzedDamlTypeBuilder {
         this.semanticModel = semanticModel;
         this.toCamelCase = toCamelCase;
     }
-    buildOrThrow(type, context) {
-        if (type.typeConReference !== undefined) {
-            if (type.builtinType !== DamlLfBuiltinType.unknown) {
-                throw this.unsupported(context, "a type constructor cannot also be a builtin type");
+    buildOrThrow(type, context, typeParameters = new Map()) {
+        if (type.diagnosticForall !== undefined) {
+            throw this.unsupported(context, "retained forall types are not supported");
+        }
+        else if (type.typeVariable !== undefined) {
+            if (type.typeVariable.name === undefined) {
+                throw this.unsupported(context, `type variable '${this.getTypeVariableName(type.typeVariable)}' requires a resolved name`);
             }
             else if (type.typeArguments.length !== 0) {
-                throw this.unsupported(context, "generic named type applications are not supported");
+                throw this.unsupported(context, "applied type variables are not supported");
+            }
+            const parameter = typeParameters.get(type.typeVariable.internedStringIndex);
+            if (parameter === undefined) {
+                throw this.unsupported(context, `unbound type variable '${this.getTypeVariableName(type.typeVariable)}'`);
+            }
+            return Object.freeze({
+                kind: "typeVariable",
+                ...(parameter.name === undefined ? {} : { name: parameter.name }),
+                internedStringIndex: parameter.internedStringIndex,
+            });
+        }
+        else if (type.typeConReference !== undefined) {
+            if (type.builtinType !== DamlLfBuiltinType.unknown) {
+                throw this.unsupported(context, "a type constructor cannot also be a builtin type");
             }
-            return this.buildNamedReferenceOrThrow(type.typeConReference, context);
+            return this.buildNamedReferenceOrThrow(type.typeConReference, type.typeArguments, context, typeParameters);
         }
         switch (type.builtinType) {
             case DamlLfBuiltinType.unit:
@@ -135,24 +161,24 @@ class AnalyzedDamlTypeBuilder {
             case DamlLfBuiltinType.optional:
                 return Object.freeze({
                     kind: "optional",
-                    element: this.buildUnaryArgumentOrThrow(type, context),
+                    element: this.buildUnaryArgumentOrThrow(type, context, typeParameters),
                 });
             case DamlLfBuiltinType.list:
                 return Object.freeze({
                     kind: "list",
-                    element: this.buildUnaryArgumentOrThrow(type, context),
+                    element: this.buildUnaryArgumentOrThrow(type, context, typeParameters),
                 });
             case DamlLfBuiltinType.textMap:
                 return Object.freeze({
                     kind: "textMap",
-                    value: this.buildUnaryArgumentOrThrow(type, context),
+                    value: this.buildUnaryArgumentOrThrow(type, context, typeParameters),
                 });
             case DamlLfBuiltinType.genMap:
                 this.assertArgumentCountOrThrow(type, 2, context);
                 return Object.freeze({
                     kind: "genMap",
-                    key: this.buildOrThrow(type.typeArguments[0], context),
-                    value: this.buildOrThrow(type.typeArguments[1], context),
+                    key: this.buildOrThrow(type.typeArguments[0], context, typeParameters),
+                    value: this.buildOrThrow(type.typeArguments[1], context, typeParameters),
                 });
             case DamlLfBuiltinType.unknown:
                 throw this.unsupported(context, "the type is not serializable");
@@ -167,49 +193,50 @@ class AnalyzedDamlTypeBuilder {
             return definition;
         }));
     }
-    buildUnaryArgumentOrThrow(type, context) {
+    buildUnaryArgumentOrThrow(type, context, typeParameters) {
         this.assertArgumentCountOrThrow(type, 1, context);
-        return this.buildOrThrow(type.typeArguments[0], context);
+        return this.buildOrThrow(type.typeArguments[0], context, typeParameters);
     }
-    buildNamedReferenceOrThrow(reference, context) {
+    buildNamedReferenceOrThrow(reference, typeArguments, context, typeParameters) {
         const key = this.getDefinitionKey(reference);
         const identity = this.getCanonicalIdentity(reference, key);
+        const dataType = this.getDataTypeOrThrow(reference, context);
+        this.assertSupportedDataTypeParametersOrThrow(dataType, context);
+        this.assertNamedArgumentCountOrThrow(typeArguments, dataType, context);
+        const analyzedTypeArguments = Object.freeze(typeArguments.map((argument) => this.buildOrThrow(argument, context, typeParameters)));
         if (!this.definitions.has(key)) {
             this.definitionKeys.push(key);
             this.definitions.set(key, undefined);
-            this.definitions.set(key, this.buildNamedDefinitionOrThrow(reference, identity, context));
+            this.definitions.set(key, this.buildNamedDefinitionOrThrow(reference, identity, dataType));
         }
         return Object.freeze({
             kind: "namedReference",
             identity,
+            typeArguments: analyzedTypeArguments,
         });
     }
-    buildNamedDefinitionOrThrow(reference, identity, context) {
-        let dataType;
-        try {
-            dataType = this.semanticModel.getDataTypeOrThrow(reference);
-        }
-        catch {
-            throw this.unsupported(context, `could not resolve named type '${reference.packageId}:${reference.moduleName}:${reference.name}'`);
-        }
+    buildNamedDefinitionOrThrow(reference, identity, dataType) {
+        const typeParameters = this.createTypeParameterScope(dataType.typeParameters);
         if (dataType.definition.kind === "record") {
             return Object.freeze({
                 identity,
+                typeParameters: Object.freeze([...dataType.typeParameters]),
                 kind: "record",
                 fields: Object.freeze(dataType.definition.fields.map((field) => Object.freeze({
                     damlLabel: field.name,
                     propertyName: this.toCamelCase(field.name),
-                    type: this.buildOrThrow(field.type, `field '${field.name}' of record '${reference.name}'`),
+                    type: this.buildOrThrow(field.type, `field '${field.name}' of record '${reference.name}'`, typeParameters),
                 }))),
             });
         }
         else if (dataType.definition.kind === "variant") {
             return Object.freeze({
                 identity,
+                typeParameters: Object.freeze([...dataType.typeParameters]),
                 kind: "variant",
                 constructors: Object.freeze(dataType.definition.constructors.map((constructor) => Object.freeze({
                     constructor: constructor.name,
-                    payload: this.buildOrThrow(constructor.type, `constructor '${constructor.name}' of variant '${reference.name}'`),
+                    payload: this.buildOrThrow(constructor.type, `constructor '${constructor.name}' of variant '${reference.name}'`, typeParameters),
                 }))),
             });
         }
@@ -224,6 +251,46 @@ class AnalyzedDamlTypeBuilder {
             throw this.unsupported(context, `builtin '${type.builtinType}' requires ${expectedCount} type argument${expectedCount === 1 ? "" : "s"}`);
         }
     }
+    getDataTypeOrThrow(reference, context) {
+        try {
+            return this.semanticModel.getDataTypeOrThrow(reference);
+        }
+        catch {
+            throw this.unsupported(context, `could not resolve named type '${reference.packageId}:${reference.moduleName}:${reference.name}'`);
+        }
+    }
+    assertSupportedDataTypeParametersOrThrow(dataType, context) {
+        if (dataType.definition.kind === "enum" &&
+            dataType.typeParameters.length !== 0) {
+            throw this.unsupported(context, "generic enums are not supported");
+        }
+        for (const parameter of dataType.typeParameters) {
+            if (parameter.name === undefined) {
+                throw this.unsupported(context, `type parameter '${this.getTypeParameterName(parameter)}' requires a resolved name`);
+            }
+            else if (parameter.kind.kind !== "star") {
+                throw this.unsupported(context, `type parameter '${this.getTypeParameterName(parameter)}' must have kind '*'`);
+            }
+        }
+    }
+    assertNamedArgumentCountOrThrow(typeArguments, dataType, context) {
+        const expectedCount = dataType.typeParameters.length;
+        if (typeArguments.length !== expectedCount) {
+            throw this.unsupported(context, `named type '${dataType.name}' requires ${expectedCount} type argument${expectedCount === 1 ? "" : "s"}`);
+        }
+    }
+    createTypeParameterScope(parameters) {
+        return new Map(parameters.map((parameter) => [
+            parameter.internedStringIndex,
+            parameter,
+        ]));
+    }
+    getTypeVariableName(typeVariable) {
+        return typeVariable.name ?? `#${typeVariable.internedStringIndex}`;
+    }
+    getTypeParameterName(parameter) {
+        return parameter.name ?? `#${parameter.internedStringIndex}`;
+    }
     getDefinitionKey(reference) {
         return `${reference.packageId}::${reference.moduleName}::${reference.name}`;
     }

package/dist/daml-interface/cli/daml-interface-cli-options.d.ts

@@ -1,9 +1,12 @@
+import { type DamlModuleImportStyle } from "../emission/daml-module-import-style.js";
 export declare class DamlInterfaceCliOptions {
     readonly inputPath: string;
     readonly outputDirectory: string;
+    readonly moduleImportStyle: DamlModuleImportStyle;
     constructor(init: {
         inputPath: string;
         outputDirectory: string;
+        moduleImportStyle?: DamlModuleImportStyle;
     });
     /** Parses CLI arguments into strongly typed DAML interface generation options. */
     static parseOrThrow(args: readonly string[]): DamlInterfaceCliOptions;

package/dist/daml-interface/cli/daml-interface-cli-options.js

@@ -1,15 +1,19 @@
 import { DamlInterfaceGenerationException } from "../errors/daml-interface-generation.exception.js";
+import { DamlModuleImportStyles, } from "../emission/daml-module-import-style.js";
 export class DamlInterfaceCliOptions {
     inputPath;
     outputDirectory;
+    moduleImportStyle;
     constructor(init) {
         this.inputPath = init.inputPath;
         this.outputDirectory = init.outputDirectory;
+        this.moduleImportStyle = init.moduleImportStyle ?? DamlModuleImportStyles.esm;
     }
     /** Parses CLI arguments into strongly typed DAML interface generation options. */
     static parseOrThrow(args) {
         let inputPath;
         let outputDirectory;
+        let moduleImportStyle = DamlModuleImportStyles.esm;
         for (let index = 0; index < args.length; index++) {
             const current = args[index];
             const next = args[index + 1];
@@ -21,6 +25,13 @@ export class DamlInterfaceCliOptions {
                 outputDirectory = next;
                 index++;
             }
+            else if (current === "--module-import-style") {
+                if (next !== DamlModuleImportStyles.esm && next !== DamlModuleImportStyles.tsNode) {
+                    throw new DamlInterfaceGenerationException("daml interface cli --module-import-style must be 'esm' or 'ts-node'");
+                }
+                moduleImportStyle = next;
+                index++;
+            }
         }
         if (inputPath === undefined || outputDirectory === undefined) {
             throw new DamlInterfaceGenerationException("daml interface cli requires --input and --output");
@@ -28,6 +39,7 @@ export class DamlInterfaceCliOptions {
         return new DamlInterfaceCliOptions({
             inputPath,
             outputDirectory,
+            moduleImportStyle,
         });
     }
 }

package/dist/daml-interface/cli/daml-interface-cli.d.ts

@@ -1,10 +1,14 @@
 import { DamlInterfaceGenerator } from "../daml-interface-generator.js";
+import { DamlInterfaceGeneratorOptions } from "../daml-interface-generator-options.js";
 import { DamlInterfaceWriter } from "../writing/daml-interface-writer.js";
+type DamlInterfaceGeneratorFactory = (options: DamlInterfaceGeneratorOptions) => DamlInterfaceGenerator;
 export declare class DamlInterfaceCli {
     private readonly generator;
     private readonly writer;
     private readonly readFileAsync;
-    constructor(generator?: DamlInterfaceGenerator, writer?: DamlInterfaceWriter, readFileAsync?: (path: string) => Promise<Uint8Array>);
+    private readonly createGenerator;
+    constructor(generator?: DamlInterfaceGenerator | undefined, writer?: DamlInterfaceWriter, readFileAsync?: (path: string) => Promise<Uint8Array>, createGenerator?: DamlInterfaceGeneratorFactory);
     /** Runs the DAML interface CLI and returns a process exit code. */
     runAsync(args: readonly string[]): Promise<number>;
 }
+export {};

package/dist/daml-interface/cli/daml-interface-cli.js

@@ -1,6 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { extname } from "node:path";
 import { DamlInterfaceGenerator } from "../daml-interface-generator.js";
+import { DamlInterfaceGeneratorOptions } from "../daml-interface-generator-options.js";
 import { DamlInterfaceGenerationException } from "../errors/daml-interface-generation.exception.js";
 import { DamlInterfaceCliOptions } from "./daml-interface-cli-options.js";
 import { DamlInterfaceWriter } from "../writing/daml-interface-writer.js";
@@ -8,23 +9,28 @@ export class DamlInterfaceCli {
     generator;
     writer;
     readFileAsync;
-    constructor(generator = new DamlInterfaceGenerator(), writer = new DamlInterfaceWriter(), readFileAsync = readFile) {
+    createGenerator;
+    constructor(generator = undefined, writer = new DamlInterfaceWriter(), readFileAsync = readFile, createGenerator = (options) => new DamlInterfaceGenerator(options)) {
         this.generator = generator;
         this.writer = writer;
         this.readFileAsync = readFileAsync;
-        void this.generator;
+        this.createGenerator = createGenerator;
         void this.writer;
         void this.readFileAsync;
+        void this.createGenerator;
     }
     /** Runs the DAML interface CLI and returns a process exit code. */
     async runAsync(args) {
         const options = DamlInterfaceCliOptions.parseOrThrow(args);
+        const generator = this.generator ?? this.createGenerator(new DamlInterfaceGeneratorOptions({
+            moduleImportStyle: options.moduleImportStyle,
+        }));
         const bytes = await this.readFileAsync(options.inputPath);
         const extension = extname(options.inputPath).toLowerCase();
         const project = extension === ".dar"
-            ? await this.generator.generateFromDarOrThrowAsync(bytes)
+            ? await generator.generateFromDarOrThrowAsync(bytes)
             : extension === ".dalf"
-                ? await this.generator.generateFromDalfOrThrowAsync(bytes)
+                ? await generator.generateFromDalfOrThrowAsync(bytes)
                 : undefined;
         if (project === undefined) {
             throw new DamlInterfaceGenerationException(`daml interface cli does not support '${extension}' inputs`);

package/dist/daml-interface/daml-interface-generator-options.d.ts

@@ -1,6 +1,9 @@
+import { type DamlModuleImportStyle } from "./emission/daml-module-import-style.js";
 export declare class DamlInterfaceGeneratorOptions {
     readonly generatedDirectory: string;
+    readonly moduleImportStyle: DamlModuleImportStyle;
     constructor(init?: {
         generatedDirectory?: string;
+        moduleImportStyle?: DamlModuleImportStyle;
     });
 }

package/dist/daml-interface/daml-interface-generator-options.js

@@ -1,6 +1,9 @@
+import { DamlModuleImportStyles, } from "./emission/daml-module-import-style.js";
 export class DamlInterfaceGeneratorOptions {
     generatedDirectory;
+    moduleImportStyle;
     constructor(init = {}) {
         this.generatedDirectory = init.generatedDirectory ?? "generated";
+        this.moduleImportStyle = init.moduleImportStyle ?? DamlModuleImportStyles.esm;
     }
 }

package/dist/daml-interface/daml-interface-generator.js

@@ -30,13 +30,13 @@ export class DamlInterfaceGenerator {
     async generateFromDalfOrThrowAsync(archiveBytes) {
         const pkg = this.packageLoader.loadPackageOrThrow(archiveBytes);
         const compilation = DamlLfCompilation.createForTemplateGeneration(new DamlLfWorkspace([pkg]));
-        return this.projectEmitter.emitProject(this.analyzeOrThrow(compilation));
+        return this.projectEmitter.emitProject(this.analyzeOrThrow(compilation), this.options.moduleImportStyle);
     }
     /** Generates an in-memory project from DAR bytes. */
     async generateFromDarOrThrowAsync(archiveBytes) {
         const archive = await this.darArchiveLoader.loadDarOrThrowAsync(archiveBytes);
         const packages = archive.packageEntries.map((entry) => this.packageLoader.loadPackageOrThrow(entry.bytes));
         const compilation = DamlLfCompilation.createForTemplateGeneration(new DamlLfWorkspace(packages));
-        return this.projectEmitter.emitProject(this.analyzeOrThrow(compilation));
+        return this.projectEmitter.emitProject(this.analyzeOrThrow(compilation), this.options.moduleImportStyle);
     }
 }

package/dist/daml-interface/emission/daml-module-import-style.d.ts

@@ -0,0 +1,7 @@
+/** Selects the relative module specifier format emitted for generated DAML projects. */
+export declare class DamlModuleImportStyles {
+    static readonly esm = "esm";
+    static readonly tsNode = "ts-node";
+    private constructor();
+}
+export type DamlModuleImportStyle = "esm" | "ts-node";

package/dist/daml-interface/emission/daml-module-import-style.js

@@ -0,0 +1,6 @@
+/** Selects the relative module specifier format emitted for generated DAML projects. */
+export class DamlModuleImportStyles {
+    static esm = "esm";
+    static tsNode = "ts-node";
+    constructor() { }
+}

package/dist/daml-interface/emission/generated-spec-emitter.d.ts

@@ -0,0 +1,29 @@
+import { DamlInterfaceAnalysisResult } from "../analysis/daml-interface-analyzer.js";
+import { GeneratedDamlInterfaceProject } from "../emission-model/generated-daml-interface-project.js";
+import { GeneratedSpecFile } from "../emission-model/generated-spec-file.js";
+import { type DamlModuleImportStyle } from "./daml-module-import-style.js";
+/** Emits dependency-free Node test modules alongside every generated DAML module. */
+export declare class GeneratedSpecEmitter {
+    private constructor();
+    /** Emits exactly one sibling `.spec.ts` module for every generated production module. */
+    static emitSpecFiles(project: GeneratedDamlInterfaceProject, analysis: DamlInterfaceAnalysisResult, moduleImportStyle?: DamlModuleImportStyle): readonly GeneratedSpecFile[];
+    private static emitTemplateSpec;
+    private static emitNamedTypeSpec;
+    private static emitChoiceSpec;
+    private static emitSupportSpec;
+    private static emitNamespaceSpec;
+    private static emitDescriptorSpec;
+    private static sampleContext;
+    private static emitSampleImports;
+    private static sampleTypeArguments;
+    private static appliedTypeName;
+    private static normalizeType;
+    private static normalizeDefinition;
+    private static nodeImports;
+    private static emitObject;
+    private static identityExpression;
+    private static definitionKey;
+    private static allocateSafeLocalName;
+    private static specPath;
+    private static modulePath;
+}