@distrohelena/canton-typescript-sdk 0.1.28 → 0.1.30

package/dist/daml-interface/emission/generated-test-sample-emitter.js

@@ -0,0 +1,459 @@
+import { DamlLfBuiltinType } from "../../daml-lf/model/daml-lf-builtin-type.js";
+import { DamlInterfaceUnsupportedShapeException } from "../errors/daml-interface-unsupported-shape.exception.js";
+/** Collects generated-test dependencies while assigning deterministic collision-safe local names. */
+class GeneratedTestSampleImportCollector {
+    importsByKey = new Map();
+    localNames = new Set();
+    constructor(imports = []) {
+        for (const entry of imports) {
+            this.importsByKey.set(`${entry.modulePath}\u0000${entry.exportedName}\u0000${entry.typeOnly ? "type" : "value"}`, entry);
+            this.localNames.add(entry.localName);
+        }
+    }
+    get imports() {
+        return [...this.importsByKey.values()].sort((left, right) => left.modulePath.localeCompare(right.modulePath)
+            || left.exportedName.localeCompare(right.exportedName));
+    }
+    /** Reserves local identifiers already declared by the generated spec module. */
+    reserveLocalNames(names) {
+        for (const name of names) {
+            this.localNames.add(name);
+        }
+    }
+    addRuntime(exportedName) {
+        return this.add("@distrohelena/canton-typescript-sdk/daml-interface", exportedName, exportedName, false);
+    }
+    addNamedType(file, exportedName) {
+        return this.add(file.path, exportedName, exportedName, true, file.namespaceAlias);
+    }
+    add(modulePath, exportedName, preferredLocalName, typeOnly, namespaceAlias = "GeneratedType") {
+        const key = `${modulePath}\u0000${exportedName}\u0000${typeOnly ? "type" : "value"}`;
+        const existing = this.importsByKey.get(key);
+        if (existing !== undefined) {
+            return existing.localName;
+        }
+        let localName = preferredLocalName;
+        let suffix = 2;
+        if (this.localNames.has(localName)) {
+            localName = `${namespaceAlias}${exportedName}`;
+        }
+        while (this.localNames.has(localName)) {
+            localName = `${namespaceAlias}${exportedName}_${suffix}`;
+            suffix += 1;
+        }
+        this.localNames.add(localName);
+        this.importsByKey.set(key, {
+            modulePath,
+            exportedName,
+            localName,
+            typeOnly,
+        });
+        return localName;
+    }
+}
+/** Emits deterministic, finite TypeScript and ledger JSON source expressions for analyzed DAML values. */
+export class GeneratedTestSampleEmitter {
+    static defaultMaximumDepth = 2;
+    constructor() { }
+    static emitTypeScriptExpressionOrThrow(type, context) {
+        return this.emitOrThrow(type, context, "typeScript");
+    }
+    static emitLedgerExpressionOrThrow(type, context) {
+        return this.emitOrThrow(type, context, "ledger");
+    }
+    /** Emits a TypeScript sample with its immutable, collision-safe import requirements. */
+    static emitTypeScriptExpressionWithImportsOrThrow(type, context, options = {}) {
+        const imports = new GeneratedTestSampleImportCollector(options.imports);
+        imports.reserveLocalNames(options.reservedLocalNames ?? []);
+        return {
+            expression: this.emitOrThrow(type, context, "typeScript", imports),
+            imports: imports.imports,
+        };
+    }
+    static emitOrThrow(type, context, representation, imports) {
+        const bindings = context.typeVariableBindings ?? new Map();
+        return this.emit(type, {
+            representation,
+            definitionIndex: this.createDefinitionIndex(context.definitions),
+            namedTypeFiles: context.namedTypeFiles,
+            imports,
+            path: context.path ?? ["value"],
+            depth: context.maximumDepth ?? this.defaultMaximumDepth,
+            bindings,
+            activeReferences: new Set(),
+        });
+    }
+    static emit(type, state) {
+        if (state.depth <= 0) {
+            const finite = this.emitFinite(type, state, new Set());
+            if (finite !== undefined) {
+                return finite;
+            }
+            throw this.uninhabitable(state.path, type);
+        }
+        switch (type.kind) {
+            case "primitive":
+                return this.emitPrimitive(type.builtinType, type.numericScale, state);
+            case "contractId":
+                return '"#sample-contract-id"';
+            case "optional":
+                return state.representation === "ledger" ? "null" : "undefined";
+            case "list":
+                return `[${this.emit(type.element, this.descend(state, "[0]"))}]`;
+            case "textMap":
+                return state.representation === "ledger"
+                    ? `{ "sample-key": ${this.emit(type.value, this.descend(state, "sample-key"))} }`
+                    : `new Map([["sample-key", ${this.emit(type.value, this.descend(state, "sample-key"))}]])`;
+            case "genMap": {
+                const entry = `[${this.emit(type.key, this.descend(state, "[0].key"))}, ${this.emit(type.value, this.descend(state, "[0].value"))}]`;
+                return state.representation === "ledger" ? `[${entry}]` : `new Map([${entry}])`;
+            }
+            case "record":
+                return this.emitRecord(type.fields, state);
+            case "variant":
+                return this.emitVariant(type.constructors, state);
+            case "enum":
+                return JSON.stringify(type.constructors[0]);
+            case "typeVariable":
+                return this.emitTypeVariable(type, state);
+            case "namedReference":
+                return this.emitNamedReference(type, state);
+        }
+    }
+    static emitFinite(type, state, visitedReferences) {
+        switch (type.kind) {
+            case "primitive":
+                return this.emitPrimitive(type.builtinType, type.numericScale, state);
+            case "contractId":
+                return '"#sample-contract-id"';
+            case "optional":
+                return state.representation === "ledger" ? "null" : "undefined";
+            case "list":
+                return "[]";
+            case "textMap":
+                return state.representation === "ledger" ? "{}" : "new Map()";
+            case "genMap":
+                return state.representation === "ledger" ? "[]" : "new Map()";
+            case "record": {
+                const fields = [];
+                for (const field of type.fields) {
+                    const value = this.emitFinite(field.type, this.descend(state, field.propertyName), visitedReferences);
+                    if (value === undefined) {
+                        return undefined;
+                    }
+                    fields.push(this.emitObjectProperty(state.representation === "ledger" ? field.damlLabel : field.propertyName, value));
+                }
+                return `{ ${fields.join(", ")} }`;
+            }
+            case "variant": {
+                for (const constructor of type.constructors) {
+                    const payload = this.emitFinite(constructor.payload, this.descend(state, constructor.constructor), visitedReferences);
+                    if (payload !== undefined) {
+                        return `{ tag: ${JSON.stringify(constructor.constructor)}, value: ${payload} }`;
+                    }
+                }
+                return undefined;
+            }
+            case "enum":
+                return type.constructors.length === 0 ? undefined : JSON.stringify(type.constructors[0]);
+            case "typeVariable": {
+                const binding = state.bindings.get(this.typeVariableKey(type));
+                return binding === undefined ? undefined : this.emitFinite(binding, state, visitedReferences);
+            }
+            case "namedReference": {
+                const referenceKey = this.referenceKey(type.identity, type.typeArguments, state.bindings);
+                if (visitedReferences.has(referenceKey)) {
+                    return undefined;
+                }
+                const definition = state.definitionIndex.get(this.identityKey(type.identity));
+                if (definition === undefined) {
+                    return '"#sample-contract-id"';
+                }
+                const namedState = this.withDefinitionBindings(definition, type.typeArguments, state);
+                const nextVisited = new Set(visitedReferences);
+                nextVisited.add(referenceKey);
+                const structural = this.emitFiniteDefinition(definition, namedState, nextVisited);
+                if (structural === undefined || state.representation === "ledger") {
+                    return structural;
+                }
+                return this.wrapNamedTypeSample(type.identity, type.typeArguments, structural, namedState);
+            }
+        }
+    }
+    static emitPrimitive(builtinType, numericScale, state) {
+        switch (builtinType) {
+            case DamlLfBuiltinType.unit:
+                if (state.representation === "ledger") {
+                    return "{}";
+                }
+                return `new ${state.imports?.addRuntime("DamlUnit") ?? "DamlUnit"}()`;
+            case DamlLfBuiltinType.bool:
+                return "true";
+            case DamlLfBuiltinType.int64:
+                return state.representation === "ledger" ? '"1"' : "1n";
+            case DamlLfBuiltinType.date:
+                if (state.representation === "ledger") {
+                    return "1";
+                }
+                return `new ${state.imports?.addRuntime("DamlDate") ?? "DamlDate"}(1)`;
+            case DamlLfBuiltinType.timestamp:
+                if (state.representation === "ledger") {
+                    return '"1000000"';
+                }
+                return `new ${state.imports?.addRuntime("DamlTimestamp") ?? "DamlTimestamp"}("1000000")`;
+            case DamlLfBuiltinType.numeric: {
+                const numeric = numericScale === undefined || numericScale === 0
+                    ? "1"
+                    : `1.${"0".repeat(numericScale)}`;
+                if (state.representation === "ledger") {
+                    return JSON.stringify(numeric);
+                }
+                return `new ${state.imports?.addRuntime("DamlNumeric") ?? "DamlNumeric"}(${JSON.stringify(numeric)})`;
+            }
+            case DamlLfBuiltinType.party:
+                if (state.representation === "ledger") {
+                    return '"Alice"';
+                }
+                return `new ${state.imports?.addRuntime("DamlParty") ?? "DamlParty"}("Alice")`;
+            case DamlLfBuiltinType.text:
+                return '"sample text"';
+            default:
+                throw new DamlInterfaceUnsupportedShapeException(`Cannot synthesize a generated test sample for unsupported primitive '${builtinType}' at ${state.path.join(".")}`);
+        }
+    }
+    static emitRecord(fields, state) {
+        return `{ ${fields.map((field) => this.emitObjectProperty(state.representation === "ledger" ? field.damlLabel : field.propertyName, this.emit(field.type, this.descend(state, field.propertyName)))).join(", ")} }`;
+    }
+    static emitVariant(constructors, state) {
+        const constructor = constructors[0];
+        if (constructor === undefined) {
+            throw this.uninhabitable(state.path, { kind: "variant", constructors });
+        }
+        return `{ tag: ${JSON.stringify(constructor.constructor)}, value: ${this.emit(constructor.payload, this.descend(state, constructor.constructor))} }`;
+    }
+    static emitTypeVariable(type, state) {
+        const binding = state.bindings.get(this.typeVariableKey(type));
+        if (binding === undefined) {
+            throw new DamlInterfaceUnsupportedShapeException(`Cannot synthesize a generated test sample for unbound type variable '${type.name ?? type.internedStringIndex}' at ${state.path.join(".")}`);
+        }
+        return this.emit(binding, state);
+    }
+    static emitNamedReference(type, state) {
+        const referenceKey = this.referenceKey(type.identity, type.typeArguments, state.bindings);
+        if (state.activeReferences.has(referenceKey)) {
+            const finite = this.emitFinite(type, state, new Set());
+            if (finite !== undefined) {
+                return finite;
+            }
+            throw this.uninhabitable(state.path, type);
+        }
+        const definition = state.definitionIndex.get(this.identityKey(type.identity));
+        if (definition === undefined) {
+            return '"#sample-contract-id"';
+        }
+        const namedState = this.withDefinitionBindings(definition, type.typeArguments, {
+            ...state,
+            depth: state.depth - 1,
+            activeReferences: new Set([...state.activeReferences, referenceKey]),
+        });
+        if (namedState.depth <= 0) {
+            const finite = this.emitFinite(type, state, new Set());
+            if (finite === undefined) {
+                throw this.uninhabitable(state.path, type);
+            }
+            return finite;
+        }
+        const structural = this.emitDefinition(definition, namedState);
+        return state.representation === "ledger"
+            ? structural
+            : this.wrapNamedTypeSample(type.identity, type.typeArguments, structural, namedState);
+    }
+    static wrapNamedTypeSample(identity, typeArguments, structural, state) {
+        const file = state.namedTypeFiles.find((candidate) => candidate.packageId === identity.packageId && candidate.moduleName === identity.moduleName);
+        const exportedName = file?.exportedTypeNamesByIdentity.get(this.identityKey(identity));
+        if (file === undefined || exportedName === undefined) {
+            return structural;
+        }
+        const localName = state.imports?.addNamedType(file, exportedName) ?? exportedName;
+        const parameters = typeArguments.map((argument) => this.emitTypeName(argument, state));
+        const appliedName = parameters.length === 0 ? localName : `${localName}<${parameters.join(", ")}>`;
+        return `(${structural} satisfies ${appliedName})`;
+    }
+    static emitDefinition(definition, state) {
+        if (definition.kind === "record") {
+            return `{ ${definition.fields.map((field, index) => this.emitObjectProperty(state.representation === "ledger"
+                ? field.damlLabel
+                : this.getRecordPropertyName(definition, index, field.propertyName, state), this.emit(field.type, this.descend(state, field.propertyName)))).join(", ")} }`;
+        }
+        else if (definition.kind === "variant") {
+            return this.emitVariant(definition.constructors, state);
+        }
+        return JSON.stringify(definition.constructors[0]);
+    }
+    static emitFiniteDefinition(definition, state, visitedReferences) {
+        if (definition.kind !== "record") {
+            return this.emitFinite(definition, state, visitedReferences);
+        }
+        const fields = [];
+        for (const [index, field] of definition.fields.entries()) {
+            const value = this.emitFinite(field.type, this.descend(state, field.propertyName), visitedReferences);
+            if (value === undefined) {
+                return undefined;
+            }
+            fields.push(this.emitObjectProperty(state.representation === "ledger"
+                ? field.damlLabel
+                : this.getRecordPropertyName(definition, index, field.propertyName, state), value));
+        }
+        return `{ ${fields.join(", ")} }`;
+    }
+    static emitTypeName(type, state) {
+        switch (type.kind) {
+            case "primitive":
+                switch (type.builtinType) {
+                    case DamlLfBuiltinType.unit:
+                        return state.imports?.addRuntime("DamlUnit") ?? "DamlUnit";
+                    case DamlLfBuiltinType.bool: return "boolean";
+                    case DamlLfBuiltinType.int64: return "bigint";
+                    case DamlLfBuiltinType.date:
+                        return state.imports?.addRuntime("DamlDate") ?? "DamlDate";
+                    case DamlLfBuiltinType.timestamp:
+                        return state.imports?.addRuntime("DamlTimestamp") ?? "DamlTimestamp";
+                    case DamlLfBuiltinType.numeric:
+                        return state.imports?.addRuntime("DamlNumeric") ?? "DamlNumeric";
+                    case DamlLfBuiltinType.party:
+                        return state.imports?.addRuntime("DamlParty") ?? "DamlParty";
+                    case DamlLfBuiltinType.text: return "string";
+                    default: throw this.uninhabitable(state.path, type);
+                }
+            case "contractId": return "string";
+            case "optional": return `${this.emitTypeName(type.element, state)} | undefined`;
+            case "list": return `readonly ${this.emitTypeName(type.element, state)}[]`;
+            case "textMap": return `ReadonlyMap<string, ${this.emitTypeName(type.value, state)}>`;
+            case "genMap": return `ReadonlyMap<${this.emitTypeName(type.key, state)}, ${this.emitTypeName(type.value, state)}>`;
+            case "typeVariable": {
+                const binding = state.bindings.get(this.typeVariableKey(type));
+                return binding === undefined ? "unknown" : this.emitTypeName(binding, state);
+            }
+            case "namedReference": {
+                const definition = state.definitionIndex.get(this.identityKey(type.identity));
+                const definitionState = definition === undefined
+                    ? state
+                    : this.withDefinitionBindings(definition, type.typeArguments, state);
+                const file = state.namedTypeFiles.find((candidate) => candidate.packageId === type.identity.packageId && candidate.moduleName === type.identity.moduleName);
+                const exportedName = file?.exportedTypeNamesByIdentity.get(this.identityKey(type.identity));
+                if (file === undefined || exportedName === undefined) {
+                    return "string";
+                }
+                const localName = state.imports?.addNamedType(file, exportedName) ?? exportedName;
+                const argumentsText = type.typeArguments.map((argument) => this.emitTypeName(argument, definitionState));
+                return argumentsText.length === 0 ? localName : `${localName}<${argumentsText.join(", ")}>`;
+            }
+            case "record":
+            case "variant":
+            case "enum":
+                return "unknown";
+        }
+    }
+    static withDefinitionBindings(definition, typeArguments, state) {
+        const parameters = "typeParameters" in definition ? definition.typeParameters : [];
+        if (parameters.length !== typeArguments.length) {
+            throw new DamlInterfaceUnsupportedShapeException(`Cannot synthesize a generated test sample for ${this.describeIdentity(definition.identity)}: expected ${parameters.length} type arguments but received ${typeArguments.length} at ${state.path.join(".")}`);
+        }
+        const bindings = new Map(state.bindings);
+        parameters.forEach((parameter, index) => bindings.set(this.typeVariableKey(parameter), this.resolveTypeVariables(typeArguments[index], state.bindings)));
+        return { ...state, bindings };
+    }
+    static resolveTypeVariables(type, bindings) {
+        if (type.kind === "typeVariable") {
+            return bindings.get(this.typeVariableKey(type)) ?? type;
+        }
+        switch (type.kind) {
+            case "optional":
+                return { ...type, element: this.resolveTypeVariables(type.element, bindings) };
+            case "list":
+                return { ...type, element: this.resolveTypeVariables(type.element, bindings) };
+            case "textMap":
+                return { ...type, value: this.resolveTypeVariables(type.value, bindings) };
+            case "genMap":
+                return {
+                    ...type,
+                    key: this.resolveTypeVariables(type.key, bindings),
+                    value: this.resolveTypeVariables(type.value, bindings),
+                };
+            case "record":
+                return {
+                    ...type,
+                    fields: type.fields.map((field) => ({
+                        ...field,
+                        type: this.resolveTypeVariables(field.type, bindings),
+                    })),
+                };
+            case "variant":
+                return {
+                    ...type,
+                    constructors: type.constructors.map((constructor) => ({
+                        ...constructor,
+                        payload: this.resolveTypeVariables(constructor.payload, bindings),
+                    })),
+                };
+            case "namedReference":
+                return {
+                    ...type,
+                    typeArguments: type.typeArguments.map((argument) => this.resolveTypeVariables(argument, bindings)),
+                };
+            case "primitive":
+            case "contractId":
+            case "enum":
+                return type;
+        }
+    }
+    static descend(state, segment) {
+        return {
+            ...state,
+            path: [...state.path, segment],
+            depth: state.depth - 1,
+        };
+    }
+    static createDefinitionIndex(definitions) {
+        return new Map(definitions.map((definition) => [this.identityKey(definition.identity), definition]));
+    }
+    static getRecordPropertyName(definition, index, fallback, state) {
+        const file = state.namedTypeFiles.find((candidate) => candidate.packageId === definition.identity.packageId && candidate.moduleName === definition.identity.moduleName);
+        const key = `${this.identityKey(definition.identity)}\u0000field\u0000${index}`;
+        return file?.fieldPropertyNames.get(key) ?? fallback;
+    }
+    static emitObjectProperty(name, value) {
+        const propertyName = /^[A-Za-z_$][A-Za-z0-9_$]*$/u.test(name)
+            ? name
+            : JSON.stringify(name);
+        return `${propertyName}: ${value}`;
+    }
+    static typeVariableKey(type) {
+        return type.name === undefined ? `#${type.internedStringIndex}` : `${type.name}\u0000${type.internedStringIndex}`;
+    }
+    static identityKey(identity) {
+        return `${identity.packageId}\u0000${identity.moduleName}\u0000${identity.name}`;
+    }
+    static referenceKey(identity, typeArguments, bindings) {
+        return `${this.identityKey(identity)}<${typeArguments.map((argument) => this.typeFingerprint(argument, bindings)).join(",")}>`;
+    }
+    static typeFingerprint(type, bindings) {
+        if (type.kind === "typeVariable") {
+            const resolved = bindings.get(this.typeVariableKey(type));
+            return resolved === undefined ? this.typeVariableKey(type) : this.typeFingerprint(resolved, bindings);
+        }
+        else if (type.kind === "namedReference") {
+            return `${this.identityKey(type.identity)}<${type.typeArguments.map((argument) => this.typeFingerprint(argument, bindings)).join(",")}>`;
+        }
+        return type.kind === "primitive"
+            ? `${type.kind}:${type.builtinType}:${type.numericScale ?? ""}`
+            : type.kind;
+    }
+    static uninhabitable(path, type) {
+        const identity = type.kind === "namedReference" ? this.describeIdentity(type.identity) : "the reachable DAML value";
+        return new DamlInterfaceUnsupportedShapeException(`Cannot synthesize a finite generated test sample for ${identity} at ${path.join(".")}`);
+    }
+    static describeIdentity(identity) {
+        return `${identity.packageId}:${identity.moduleName}:${identity.name}`;
+    }
+}

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

@@ -1,24 +1,32 @@
 import { AnalyzedDamlTypeDefinition } from "../analysis/analyzed-daml-type-definition.js";
+import { DamlInterfacePackageMetadata } from "../analysis/daml-interface-analyzer.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";
+import { type DamlModuleImportStyle } from "./daml-module-import-style.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;
+    prepareProjectOrThrow(templates: readonly import("../analysis/analyzed-template.js").AnalyzedTemplate[], definitions: readonly AnalyzedDamlTypeDefinition[], packageMetadata?: ReadonlyMap<string, DamlInterfacePackageMetadata>): void;
     /** Emits one `types.ts` module for every reachable DAML package/module identity. */
-    emitNamedTypeFiles(definitions: readonly AnalyzedDamlTypeDefinition[]): readonly GeneratedNamedTypeFile[];
+    emitNamedTypeFiles(definitions: readonly AnalyzedDamlTypeDefinition[], moduleImportStyle?: DamlModuleImportStyle): readonly GeneratedNamedTypeFile[];
     /** Emits named type files from an already prepared shared name resolver. */
-    emitPreparedNamedTypeFiles(definitions: readonly AnalyzedDamlTypeDefinition[], templateFiles?: readonly GeneratedTemplateBindingFile[]): readonly GeneratedNamedTypeFile[];
+    emitPreparedNamedTypeFiles(definitions: readonly AnalyzedDamlTypeDefinition[], templateFiles?: readonly GeneratedTemplateBindingFile[], moduleImportStyle?: DamlModuleImportStyle): readonly GeneratedNamedTypeFile[];
     private emitDefinition;
     private emitImports;
     private resolveExternalTypeAliases;
     private getExternalTypeAlias;
     private getNamedReferences;
     private getTypeName;
+    private getArrayElementTypeName;
     private getPrimitiveTypeName;
+    private resolveTypeParameterNames;
+    private getDefinitionTypeParameters;
+    private getTypeParameterName;
+    private getTypeParameters;
+    private getTypeParameterKey;
     private resolveModulesOrThrow;
     private resolveDefinitionNamesOrThrow;
     private resolveCollisionSafeNames;