Renamed toMetadata and fromMetadata

examples/nodejs/src/marlowe-object-flow.ts

@@ -186,7 +186,7 @@ async function createContractMenu(
     depositDeadline,
     releaseDeadline,
   };
-  const metadata = delayPaymentTemplate.encode(scheme);
+  const metadata = delayPaymentTemplate.toMetadata(scheme);
   const sourceMap = await mkSourceMap(lifecycle, mkDelayPayment(scheme));
   const [contractId, txId] = await sourceMap.createContract({
     stakeAddress: rewardAddress,
@@ -601,7 +601,7 @@ async function validateExistingContract(
     contractId,
   });
 
-  const scheme = delayPaymentTemplate.decode(contractDetails.metadata);
+  const scheme = delayPaymentTemplate.fromMetadata(contractDetails.metadata);
 
   if (!scheme) {
     return "InvalidMarloweTemplate";

packages/marlowe-template/src/index.ts

@@ -2,9 +2,10 @@
  * This is an `experimental` package that helps with the definition and sharing of the parameters of
  * a Marlowe contract template.
  *
- * We call a contract template to a function that receives a set of parameters and returns a Marlowe contract.
- * Manually sharing the contract parameters can be challenging, so this package aims to solve that by {@link MarloweTemplate.encode | encoding}
- * and {@link MarloweTemplate.decode | decoding}  the parameters as {@link @marlowe.io/runtime-core!index.Metadata}.
+ * We call a contract template to a function (e.g. `mkContract`) that receives a set of parameters and returns a Marlowe contract.
+ * Manually sharing the contract parameters can be challenging, so this package aims to solve that by
+ * serializing the parameters {@link MarloweTemplate.toMetadata | to} and
+ * {@link MarloweTemplate.fromMetadata | from} {@link @marlowe.io/runtime-core!index.Metadata}.
  *
  * ```
  * import { mkMarloweTemplate, TemplateParametersOf } from "@marlowe.io/marlowe-template";
@@ -48,7 +49,7 @@
  *
  * runtime.contracts.create({
  *   contract: mkContract(contractParameters),
- *   metadata: myTemplate.encode(contractParameters)
+ *   metadata: myTemplate.toMetadata(contractParameters)
  * })
  * ```
  * @packageDocumentation

packages/marlowe-template/src/template.ts

@@ -27,8 +27,8 @@ export class DecodingTemplateError extends Error {
 
 /**
  * This class holds information on the parameters required to create a Marlowe contract and
- * a way to {@link MarloweTemplate.encode} and {@link MarloweTemplate.decode} the contract parameters as {@link @marlowe.io/runtime-core!index.Metadata}.
- * The order of the parameters is important as it is used by the codec to encode and decode.
+ * a way to serialize them {@link MarloweTemplate.toMetadata | to} and {@link MarloweTemplate.fromMetadata | from}  {@link @marlowe.io/runtime-core!index.Metadata}.
+ * The order of the parameters is important as they drive the serialization.
  *
  * The Metadata encoding is as following:
  * A top level entry with key `9041` and value with an object with two fields:
@@ -43,6 +43,11 @@ export class MarloweTemplate<ObjectParams extends object> {
   private templateCodec: t.Type<ObjectParams, Metadata, unknown>;
   name: string;
   description?: string;
+  /**
+   * Manual constructor for the MarloweTemplate class, you should use {@link mkMarloweTemplate} instead.
+   * @typeParam ObjectParams - The inferred type of the `options.params` as an object.
+   * @param options - The {@link MkTemplateOptions | options} to create a new MarloweTemplate.
+   */
   constructor(options: MkTemplateOptions<readonly TemplateParam<any>[]>) {
     const templateParams = options.params;
     this.name = options.name;
@@ -145,27 +150,22 @@ export class MarloweTemplate<ObjectParams extends object> {
    * @returns the decoded ObjectParams.
    * @throws {@link DecodingTemplateError} - if the value is not a valid Metadata.
    */
-  decode(value: Metadata): ObjectParams {
+  fromMetadata(value: Metadata): ObjectParams {
     const decoded = this.templateCodec.decode(value);
     if (decoded._tag === "Right") {
       return decoded.right;
     } else {
       throw new DecodingTemplateError(this, decoded.left);
     }
   }
-  // NOTE: The output of the encode is the output of the Metadata codec,
-  //       which is compatible with its inputs, but it doesn't have the
-  //       branded types. Here we cast to the Metadata type to allow easier
-  //       usability with the rest of the runtime, that expects the Branded
-  //       types.
   /**
    * Encodes the given value into a Metadata object.
    *
    * @param value The value to be encoded.
    * @returns The encoded Metadata object.
    */
-  encode(value: ObjectParams): Metadata {
-    return this.templateCodec.encode(value) as Metadata;
+  toMetadata(value: ObjectParams) {
+    return this.templateCodec.encode(value);
   }
 }
 

packages/marlowe-template/test/basic-types-template.spec.ts

@@ -44,7 +44,7 @@ describe("Template basic types", () => {
 
   it("should encode a valid value", () => {
     const a: BasicParams = { str: "hello", num: 42, dte: aDate };
-    expect(basicTemplate.encode(a)).toEqual({
+    expect(basicTemplate.toMetadata(a)).toEqual({
       "9041": {
         v: 1n,
         params: [["hello"], 42n, aDateMS],
@@ -60,7 +60,7 @@ describe("Template basic types", () => {
       },
     };
 
-    expect(basicTemplate.decode(metadata)).toEqual({
+    expect(basicTemplate.fromMetadata(metadata)).toEqual({
       str: "hello",
       num: 42n,
       dte: aDate,
@@ -73,7 +73,7 @@ describe("Template basic types", () => {
       num: 42n,
       dte: aDate,
     };
-    expect(basicTemplate.encode(a)).toEqual({
+    expect(basicTemplate.toMetadata(a)).toEqual({
       "9041": {
         v: 1n,
         params: [["a".repeat(64), "a"], 42n, aDateMS],
@@ -88,7 +88,7 @@ describe("Template basic types", () => {
         params: [["a".repeat(64), "a"], 42n, aDateMS],
       },
     };
-    expect(basicTemplate.decode(metadata)).toEqual({
+    expect(basicTemplate.fromMetadata(metadata)).toEqual({
       str: "a".repeat(65),
       num: 42n,
       dte: aDate,

packages/marlowe-template/test/delayed-payment-template.spec.ts

@@ -95,7 +95,7 @@ describe("Delayed payment Template", () => {
       depositDeadline: aDepositDate,
       releaseDeadline: aReleaseDate,
     };
-    expect(delayPaymentTemplate.encode(a)).toEqual({
+    expect(delayPaymentTemplate.toMetadata(a)).toEqual({
       "9041": {
         v: 1n,
         params: [
@@ -134,7 +134,7 @@ describe("Delayed payment Template", () => {
       },
     };
 
-    expect(delayPaymentTemplate.decode(metadata)).toEqual({
+    expect(delayPaymentTemplate.fromMetadata(metadata)).toEqual({
       payer: addressBech32(
         "addr_test1qpcucug827nlrmsv7n66hwdfpemwqtv8nxnjc4azacuu807w6l6hgelwsph7clqmauq7h3y9qhhgs0rwu3mu8uf7m4kqckxkry"
       ),
@@ -164,6 +164,6 @@ describe("Delayed payment Template", () => {
       },
     };
     // FIXME: Improve the error message checking
-    expect(() => delayPaymentTemplate.decode(metadata)).toThrow();
+    expect(() => delayPaymentTemplate.fromMetadata(metadata)).toThrow();
   });
 });