@distrohelena/canton-typescript-sdk 0.1.24 → 0.1.26

package/README.md

@@ -1,10 +1,15 @@
 # Canton TypeScript SDK
 
-TypeScript SDK for Canton with a shared `CantonClient`, gRPC and JSON
-transports, gRPC Ledger API-shaped service boundaries, PQS-backed relational
-queries, external-party lifecycle and signing, authenticated and TLS-secured
-channels, and experimental tooling for invariant testing, DAML-LF inspection,
-interface generation, and replay debugging.
+TypeScript SDK for Canton with:
+
+- a shared `CantonClient`
+- gRPC and JSON transports
+- gRPC Ledger API-shaped service boundaries
+- PQS-backed relational queries
+- external-party lifecycle and signing
+- authenticated and TLS-secured channels
+- experimental tooling for invariant testing, DAML-LF inspection, interface
+  generation, and replay debugging
 
 ## Install
 

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

@@ -1,15 +1,15 @@
-import { DamlLfType } from "../../daml-lf/model/daml-lf-type.js";
+import { AnalyzedDamlType } from "./analyzed-daml-type.js";
 export declare class AnalyzedChoice {
     readonly name: string;
     readonly methodName: string;
     readonly parameterName: string;
-    readonly parameterType: DamlLfType;
-    readonly returnType: DamlLfType;
+    readonly parameterType: AnalyzedDamlType;
+    readonly returnType: AnalyzedDamlType;
     constructor(init: {
         name: string;
         methodName: string;
         parameterName: string;
-        parameterType: DamlLfType;
-        returnType: DamlLfType;
+        parameterType: AnalyzedDamlType;
+        returnType: AnalyzedDamlType;
     });
 }

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

@@ -0,0 +1,6 @@
+import { AnalyzedDamlEnumType, AnalyzedDamlRecordType, AnalyzedDamlVariantType } from "./analyzed-daml-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);

package/dist/daml-interface/analysis/analyzed-daml-type-definition.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,54 @@
+import { DamlLfBuiltinType } from "../../daml-lf/model/daml-lf-builtin-type.js";
+import { TypeConReference } from "../../daml-lf/model/type-con-reference.js";
+export type AnalyzedDamlPrimitiveType = {
+    readonly kind: "primitive";
+    readonly builtinType: DamlLfBuiltinType.unit | DamlLfBuiltinType.bool | DamlLfBuiltinType.int64 | DamlLfBuiltinType.date | DamlLfBuiltinType.timestamp | DamlLfBuiltinType.numeric | DamlLfBuiltinType.party | DamlLfBuiltinType.text;
+    readonly numericScale?: number;
+};
+export type AnalyzedDamlContractIdType = {
+    readonly kind: "contractId";
+};
+export type AnalyzedDamlOptionalType = {
+    readonly kind: "optional";
+    readonly element: AnalyzedDamlType;
+};
+export type AnalyzedDamlListType = {
+    readonly kind: "list";
+    readonly element: AnalyzedDamlType;
+};
+export type AnalyzedDamlTextMapType = {
+    readonly kind: "textMap";
+    readonly value: AnalyzedDamlType;
+};
+export type AnalyzedDamlGenMapType = {
+    readonly kind: "genMap";
+    readonly key: AnalyzedDamlType;
+    readonly value: AnalyzedDamlType;
+};
+export type AnalyzedDamlRecordField = {
+    readonly damlLabel: string;
+    readonly propertyName: string;
+    readonly type: AnalyzedDamlType;
+};
+export type AnalyzedDamlRecordType = {
+    readonly kind: "record";
+    readonly fields: readonly AnalyzedDamlRecordField[];
+};
+export type AnalyzedDamlVariantConstructor = {
+    readonly constructor: string;
+    readonly payload: AnalyzedDamlType;
+};
+export type AnalyzedDamlVariantType = {
+    readonly kind: "variant";
+    readonly constructors: readonly AnalyzedDamlVariantConstructor[];
+};
+export type AnalyzedDamlEnumType = {
+    readonly kind: "enum";
+    readonly constructors: readonly string[];
+};
+export type AnalyzedDamlNamedReferenceType = {
+    readonly kind: "namedReference";
+    readonly identity: TypeConReference;
+};
+/** Closed, immutable description of a DAML value serializable by the generator. */
+export type AnalyzedDamlType = AnalyzedDamlPrimitiveType | AnalyzedDamlContractIdType | AnalyzedDamlOptionalType | AnalyzedDamlListType | AnalyzedDamlTextMapType | AnalyzedDamlGenMapType | AnalyzedDamlRecordType | AnalyzedDamlVariantType | AnalyzedDamlEnumType | AnalyzedDamlNamedReferenceType;

package/dist/daml-interface/analysis/analyzed-daml-type.js

@@ -0,0 +1 @@
+export {};

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

@@ -1,14 +1,14 @@
 import { DamlLfTemplateId } from "../../daml-lf/model/daml-lf-template-id.js";
-import { DamlLfType } from "../../daml-lf/model/daml-lf-type.js";
 import { AnalyzedChoice } from "./analyzed-choice.js";
+import { AnalyzedDamlType } from "./analyzed-daml-type.js";
 export declare class AnalyzedTemplateField {
     readonly name: string;
     readonly propertyName: string;
-    readonly type: DamlLfType;
+    readonly type: AnalyzedDamlType;
     constructor(init: {
         name: string;
         propertyName: string;
-        type: DamlLfType;
+        type: AnalyzedDamlType;
     });
 }
 export declare class AnalyzedTemplate {

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

@@ -1,9 +1,12 @@
 import { DamlLfCompilation } from "../../daml-lf/daml-lf-compilation.js";
+import { AnalyzedDamlTypeDefinition } from "./analyzed-daml-type-definition.js";
 import { AnalyzedTemplate } from "./analyzed-template.js";
 export declare class DamlInterfaceAnalysisResult {
     readonly templates: readonly AnalyzedTemplate[];
+    readonly typeDefinitions: readonly AnalyzedDamlTypeDefinition[];
     constructor(init: {
         templates: readonly AnalyzedTemplate[];
+        typeDefinitions: readonly AnalyzedDamlTypeDefinition[];
     });
 }
 export declare class DamlInterfaceAnalyzer {
@@ -12,7 +15,6 @@ export declare class DamlInterfaceAnalyzer {
     private analyzeTemplateOrThrow;
     private analyzeTemplateFieldOrThrow;
     private analyzeChoiceOrThrow;
-    private assertSupportedTypeOrThrow;
     private toCamelCase;
     private toPascalCase;
     private toKebabCase;

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

@@ -1,58 +1,57 @@
 import { DamlLfBuiltinType } from "../../daml-lf/model/daml-lf-builtin-type.js";
+import { TypeConReference } from "../../daml-lf/model/type-con-reference.js";
 import { DamlInterfaceUnsupportedShapeException } from "../errors/daml-interface-unsupported-shape.exception.js";
 import { AnalyzedChoice } from "./analyzed-choice.js";
 import { AnalyzedTemplate, AnalyzedTemplateField } from "./analyzed-template.js";
 export class DamlInterfaceAnalysisResult {
     templates;
+    typeDefinitions;
     constructor(init) {
-        this.templates = init.templates;
+        this.templates = Object.freeze([...init.templates]);
+        this.typeDefinitions = Object.freeze([...init.typeDefinitions]);
     }
 }
 export class DamlInterfaceAnalyzer {
     /** Analyzes compiled DAML-LF templates into generator-facing metadata. */
     analyzeOrThrow(compilation) {
         const semanticModel = compilation.createSemanticModel();
+        const typeBuilder = new AnalyzedDamlTypeBuilder(semanticModel, (value) => this.toCamelCase(value));
         const templates = semanticModel
             .getTemplates()
-            .map((item) => this.analyzeTemplateOrThrow(item));
+            .map((item) => this.analyzeTemplateOrThrow(item, typeBuilder));
         return new DamlInterfaceAnalysisResult({
             templates,
+            typeDefinitions: typeBuilder.getTypeDefinitions(),
         });
     }
-    analyzeTemplateOrThrow(template) {
+    analyzeTemplateOrThrow(template, typeBuilder) {
         return new AnalyzedTemplate({
             templateId: template.templateId,
             className: this.toPascalCase(template.name),
             fileName: `${this.toKebabCase(template.name)}.ts`,
-            createFields: template.fields.map((item) => this.analyzeTemplateFieldOrThrow(item)),
-            choices: template.choices.map((item) => this.analyzeChoiceOrThrow(item)),
+            createFields: template.fields.map((item) => this.analyzeTemplateFieldOrThrow(item, typeBuilder)),
+            choices: template.choices.map((item) => this.analyzeChoiceOrThrow(item, typeBuilder)),
         });
     }
-    analyzeTemplateFieldOrThrow(field) {
-        this.assertSupportedTypeOrThrow(field.type, `template field '${field.name}'`);
+    analyzeTemplateFieldOrThrow(field, typeBuilder) {
+        const type = typeBuilder.buildOrThrow(field.type, `template field '${field.name}'`);
         return new AnalyzedTemplateField({
             name: field.name,
             propertyName: this.toCamelCase(field.name),
-            type: field.type,
+            type,
         });
     }
-    analyzeChoiceOrThrow(choice) {
-        this.assertSupportedTypeOrThrow(choice.parameter.type, `choice parameter '${choice.parameter.name}'`);
-        this.assertSupportedTypeOrThrow(choice.returnType, `choice return type '${choice.name}'`);
+    analyzeChoiceOrThrow(choice, typeBuilder) {
+        const parameterType = typeBuilder.buildOrThrow(choice.parameter.type, `choice parameter '${choice.parameter.name}'`);
+        const returnType = typeBuilder.buildOrThrow(choice.returnType, `choice return type '${choice.name}'`);
         return new AnalyzedChoice({
             name: choice.name,
             methodName: `exercise${this.toPascalCase(choice.name)}`,
             parameterName: this.toCamelCase(choice.parameter.name),
-            parameterType: choice.parameter.type,
-            returnType: choice.returnType,
+            parameterType,
+            returnType,
         });
     }
-    assertSupportedTypeOrThrow(type, context) {
-        if (type.typeConReference !== undefined ||
-            type.builtinType !== DamlLfBuiltinType.text) {
-            throw new DamlInterfaceUnsupportedShapeException(`${context} is not supported yet by the DAML interface generator`);
-        }
-    }
     toCamelCase(value) {
         const pascalCase = this.toPascalCase(value);
         if (pascalCase.length === 0) {
@@ -79,3 +78,168 @@ export class DamlInterfaceAnalyzer {
             .toLowerCase();
     }
 }
+class AnalyzedDamlTypeBuilder {
+    semanticModel;
+    toCamelCase;
+    definitionKeys = [];
+    canonicalIdentities = new Map();
+    definitions = new Map();
+    constructor(semanticModel, toCamelCase) {
+        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");
+            }
+            else if (type.typeArguments.length !== 0) {
+                throw this.unsupported(context, "generic named type applications are not supported");
+            }
+            return this.buildNamedReferenceOrThrow(type.typeConReference, context);
+        }
+        switch (type.builtinType) {
+            case DamlLfBuiltinType.unit:
+            case DamlLfBuiltinType.bool:
+            case DamlLfBuiltinType.int64:
+            case DamlLfBuiltinType.date:
+            case DamlLfBuiltinType.timestamp:
+            case DamlLfBuiltinType.party:
+            case DamlLfBuiltinType.text:
+                this.assertArgumentCountOrThrow(type, 0, context);
+                return Object.freeze({
+                    kind: "primitive",
+                    builtinType: type.builtinType,
+                    ...(type.numericScale === undefined
+                        ? {}
+                        : { numericScale: type.numericScale }),
+                });
+            case DamlLfBuiltinType.numeric:
+                this.assertArgumentCountOrThrow(type, 0, context);
+                if (type.numericScale === undefined ||
+                    !Number.isInteger(type.numericScale) ||
+                    type.numericScale < 0 ||
+                    type.numericScale > 37) {
+                    throw this.unsupported(context, "numeric values require an integer scale from 0 through 37");
+                }
+                return Object.freeze({
+                    kind: "primitive",
+                    builtinType: type.builtinType,
+                    numericScale: type.numericScale,
+                });
+            case DamlLfBuiltinType.contractId:
+                this.assertArgumentCountOrThrow(type, 1, context);
+                return Object.freeze({
+                    kind: "contractId",
+                });
+            case DamlLfBuiltinType.optional:
+                return Object.freeze({
+                    kind: "optional",
+                    element: this.buildUnaryArgumentOrThrow(type, context),
+                });
+            case DamlLfBuiltinType.list:
+                return Object.freeze({
+                    kind: "list",
+                    element: this.buildUnaryArgumentOrThrow(type, context),
+                });
+            case DamlLfBuiltinType.textMap:
+                return Object.freeze({
+                    kind: "textMap",
+                    value: this.buildUnaryArgumentOrThrow(type, context),
+                });
+            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),
+                });
+            case DamlLfBuiltinType.unknown:
+                throw this.unsupported(context, "the type is not serializable");
+        }
+    }
+    getTypeDefinitions() {
+        return Object.freeze(this.definitionKeys.map((key) => {
+            const definition = this.definitions.get(key);
+            if (definition === undefined) {
+                throw new DamlInterfaceUnsupportedShapeException(`could not finish resolving named DAML type '${key}'`);
+            }
+            return definition;
+        }));
+    }
+    buildUnaryArgumentOrThrow(type, context) {
+        this.assertArgumentCountOrThrow(type, 1, context);
+        return this.buildOrThrow(type.typeArguments[0], context);
+    }
+    buildNamedReferenceOrThrow(reference, context) {
+        const key = this.getDefinitionKey(reference);
+        const identity = this.getCanonicalIdentity(reference, key);
+        if (!this.definitions.has(key)) {
+            this.definitionKeys.push(key);
+            this.definitions.set(key, undefined);
+            this.definitions.set(key, this.buildNamedDefinitionOrThrow(reference, identity, context));
+        }
+        return Object.freeze({
+            kind: "namedReference",
+            identity,
+        });
+    }
+    buildNamedDefinitionOrThrow(reference, identity, context) {
+        let dataType;
+        try {
+            dataType = this.semanticModel.getDataTypeOrThrow(reference);
+        }
+        catch (error) {
+            throw this.unsupported(context, `could not resolve named type '${reference.name}'`);
+        }
+        if (dataType.definition.kind === "record") {
+            return Object.freeze({
+                identity,
+                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}'`),
+                }))),
+            });
+        }
+        else if (dataType.definition.kind === "variant") {
+            return Object.freeze({
+                identity,
+                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}'`),
+                }))),
+            });
+        }
+        return Object.freeze({
+            identity,
+            kind: "enum",
+            constructors: Object.freeze([...dataType.definition.constructors]),
+        });
+    }
+    assertArgumentCountOrThrow(type, expectedCount, context) {
+        if (type.typeArguments.length !== expectedCount) {
+            throw this.unsupported(context, `builtin '${type.builtinType}' requires ${expectedCount} type argument${expectedCount === 1 ? "" : "s"}`);
+        }
+    }
+    getDefinitionKey(reference) {
+        return `${reference.packageId}::${reference.moduleName}::${reference.name}`;
+    }
+    getCanonicalIdentity(reference, key) {
+        let identity = this.canonicalIdentities.get(key);
+        if (identity === undefined) {
+            identity = Object.freeze(new TypeConReference({
+                packageId: reference.packageId,
+                moduleName: reference.moduleName,
+                name: reference.name,
+            }));
+            this.canonicalIdentities.set(key, identity);
+        }
+        return identity;
+    }
+    unsupported(context, reason) {
+        return new DamlInterfaceUnsupportedShapeException(`${context} is not supported by the DAML interface generator: ${reason}`);
+    }
+}

package/dist/daml-interface/emission/named-type-emitter.d.ts

@@ -0,0 +1,41 @@
+import { AnalyzedDamlTypeDefinition } from "../analysis/analyzed-daml-type-definition.js";
+import { GeneratedNamedTypeFile } from "../emission-model/generated-named-type-file.js";
+import { GeneratedTemplateBindingFile } from "../emission-model/generated-template-binding-file.js";
+import { TypeScriptNameResolver } from "./type-script-name-resolver.js";
+/** Emits TypeScript declarations for reachable named DAML records, variants, and enums. */
+export declare class NamedTypeEmitter {
+    private readonly nameResolver;
+    constructor(nameResolver?: TypeScriptNameResolver);
+    /** Prepares shared package/module output mappings with template emission. */
+    prepareProjectOrThrow(templates: readonly import("../analysis/analyzed-template.js").AnalyzedTemplate[], definitions: readonly AnalyzedDamlTypeDefinition[]): void;
+    /** Emits one `types.ts` module for every reachable DAML package/module identity. */
+    emitNamedTypeFiles(definitions: readonly AnalyzedDamlTypeDefinition[]): readonly GeneratedNamedTypeFile[];
+    /** Emits named type files from an already prepared shared name resolver. */
+    emitPreparedNamedTypeFiles(definitions: readonly AnalyzedDamlTypeDefinition[], templateFiles?: readonly GeneratedTemplateBindingFile[]): readonly GeneratedNamedTypeFile[];
+    private emitDefinition;
+    private emitImports;
+    private resolveExternalTypeAliases;
+    private getExternalTypeAlias;
+    private getNamedReferences;
+    private getTypeName;
+    private getPrimitiveTypeName;
+    private resolveModulesOrThrow;
+    private resolveDefinitionNamesOrThrow;
+    private resolveCollisionSafeNames;
+    private getReservedModuleExports;
+    private getReservedRuntimeBindings;
+    private mergeReservedNames;
+    private resolveFieldPropertyNames;
+    private getFieldPropertyName;
+    private getFieldKey;
+    private safePropertyName;
+    private getModuleKeyFromTemplateIdentity;
+    private relativeFilePath;
+    private getDefinitionName;
+    private getNamedReferenceTypeName;
+    private getModuleKey;
+    private getDefinitionKey;
+    private safeTypeName;
+    private getRuntimePrimitiveTypes;
+    private shortHash;
+}