@helios-lang/contract-utils 0.2.61 → 0.2.63

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helios-lang/contract-utils",
-  "version": "0.2.61",
+  "version": "0.2.63",
   "description": "Convenience and type-safety utilities for using Helios validators from within Typescript",
   "main": "src/index.js",
   "types": "types/index.d.ts",
@@ -28,17 +28,20 @@
     "@helios-lang/cli-utils": "^0.1.6",
     "@helios-lang/codec-utils": "^0.1.35",
     "@helios-lang/compiler-utils": "^0.1.25",
-    "@helios-lang/ledger": "^0.4.11",
+    "@helios-lang/ledger": "^0.5.1",
     "@helios-lang/type-utils": "^0.1.21",
-    "@helios-lang/uplc": "^0.3.6"
+    "@helios-lang/uplc": "^0.3.8"
   },
   "scripts": {
     "build": "pnpm run prettify && pnpm run build:types && pnpm run test:suite",
     "build:types": "tsc -p jsconfig.json --noEmit false --emitDeclarationOnly",
+    "lockfile:sync": "pnpm install --ignore-workspace",
     "prettify": "prettier . --write",
     "test": "pnpm run test:pretty && pnpm run test:types && pnpm run test:suite",
     "test:pretty": "prettier . --check",
     "test:suite": "node --test",
+    "testing": "node --test --watch",
+    "testing:debug": "node --inspect-brk --test --watch",
     "test:types": "pnpm run build:types"
   }
 }

package/src/cast/Cast.js

@@ -94,11 +94,20 @@ export class Cast {
     }
 
     /**
+     * converts javascript object to UPLC data, according to the schema.
+     * @remarks
+     * The optional `dataPath` parameter can provide a contextual cue for the
+     * data-conversion process, and will be displayed as part of any error messages
+     * thrown during the data transformation
+     *
      * @param {TPermissive} x
+     * @param {string} dataPath
      * @returns {UplcData}
      */
-    toUplcData(x) {
-        return schemaToUplc(this.schema, x)
+    toUplcData(x, dataPath = "") {
+        const t = schemaToUplcWithDataPath(this.schema, x, {}, dataPath)
+        t.rawData = x
+        return t
     }
 }
 
@@ -106,15 +115,42 @@ export class Cast {
  * @param {TypeSchema} schema
  * @param {any} x
  * @param {Record<string, TypeSchema>} defs
+ * @param {string} dataPath
  * @returns {UplcData}
  */
-function schemaToUplc(schema, x, defs = {}) {
-    const kind = schema.kind
+function schemaToUplcWithDataPath(schema, x, defs = {}, dataPath = "") {
+    try {
+        const t = schemaToUplc(schema, x, defs, dataPath)
+        t.dataPath = dataPath
+        return t
+    } catch (e) {
+        if (!e.uplcDataPath) {
+            e.message = `${e.message}\n ... at ${dataPath}`
+            e.uplcDataPath = dataPath
+        }
+        debugger
+        throw e
+    }
+}
 
+/**
+ * @param {TypeSchema} schema
+ * @param {any} x
+ * @param {Record<string, TypeSchema>} defs
+ * @param {string} dataPath
+ * @returns {UplcData}
+ */
+function schemaToUplc(schema, x, defs = {}, dataPath = "") {
+    const kind = schema.kind
     switch (kind) {
         case "reference": {
             const def = expectSome(defs[schema.id])
-            return schemaToUplc(def, x, defs)
+            return schemaToUplcWithDataPath(
+                def,
+                x,
+                defs,
+                `${dataPath}::ref{${schema.id}}`
+            )
         }
         case "internal": {
             const name = schema.name
@@ -184,43 +220,88 @@ function schemaToUplc(schema, x, defs = {}) {
                 case "Value":
                     return Value.new(x).toUplcData()
                 default:
-                    throw new Error(`not yet implemented for ${name}`)
+                    throw new Error(
+                        `schemaToUplc not yet implemented for ${name}`
+                    )
             }
         }
         case "list":
             return new ListData(
-                x.map((x) => schemaToUplc(schema.itemType, x, defs))
+                x.map((x, i) =>
+                    schemaToUplcWithDataPath(
+                        schema.itemType,
+                        x,
+                        defs,
+                        `${dataPath}.list[${i}]`
+                    )
+                )
             )
         case "map": {
-            const entries = x instanceof Map ? x.entries() : x
+            const entries =
+                x instanceof Map
+                    ? [...x.entries()]
+                    : Array.isArray(x)
+                      ? x
+                      : Object.entries(x)
             return new MapData(
                 entries.map(([k, v]) => [
-                    schemaToUplc(schema.keyType, k, defs),
-                    schemaToUplc(schema.valueType, v, defs)
+                    schemaToUplcWithDataPath(
+                        schema.keyType,
+                        k,
+                        defs,
+                        `${dataPath}[mapKey '${k}']`
+                    ),
+                    schemaToUplcWithDataPath(
+                        schema.valueType,
+                        v,
+                        defs,
+                        `${dataPath}[map].${k}`
+                    )
                 ])
             )
         }
         case "tuple":
             return new ListData(
-                x.map((x, i) => schemaToUplc(schema.itemTypes[i], x, defs))
+                x.map((x, i) =>
+                    schemaToUplcWithDataPath(
+                        schema.itemTypes[i],
+                        x,
+                        defs,
+                        `${dataPath}[tuple@${i}]`
+                    )
+                )
             )
         case "option":
             return encodeOptionData(
-                x ? schemaToUplc(schema.someType, x, defs) : None
+                x
+                    ? schemaToUplcWithDataPath(
+                          schema.someType,
+                          x,
+                          defs,
+                          `${dataPath}::Some`
+                      )
+                    : None
             )
         case "struct": {
             defs[schema.id] = schema
             switch (schema.format) {
                 case "singleton":
-                    return schemaToUplc(
+                    const singleFieldName = schema.fieldTypes[0].name
+                    return schemaToUplcWithDataPath(
                         schema.fieldTypes[0].type,
-                        x[schema.fieldTypes[0].name],
-                        defs
+                        x[singleFieldName],
+                        defs,
+                        `${dataPath}[sStruct.${singleFieldName}]`
                     )
                 case "list":
                     return new ListData(
                         schema.fieldTypes.map(({ name, type }) =>
-                            schemaToUplc(type, x[name])
+                            schemaToUplcWithDataPath(
+                                type,
+                                x[name],
+                                {},
+                                `${dataPath}[fStruct].${name}`
+                            )
                         )
                     )
                 case "map": {
@@ -243,8 +324,18 @@ function schemaToUplc(schema, x, defs = {}) {
                         )
 
                         if (ft) {
-                            const keyData = new ByteArrayData(encodeUtf8(key))
-                            const valueData = schemaToUplc(ft.type, value, defs)
+                            debugger
+                            // const rawKey = ft.key || ft.name
+                            const rawKey = ft.name
+                            const keyData = new ByteArrayData(
+                                encodeUtf8(rawKey)
+                            )
+                            const valueData = schemaToUplcWithDataPath(
+                                ft.type,
+                                value,
+                                defs,
+                                `${dataPath}[mStruct][${key}]`
+                            )
 
                             pairs.push([keyData, valueData])
                         }
@@ -276,16 +367,27 @@ function schemaToUplc(schema, x, defs = {}) {
             return new ConstrData(
                 tag,
                 schema.variantTypes[tag].fieldTypes.map((f) =>
-                    schemaToUplc(f.type, variantFields[f.name], defs)
+                    schemaToUplcWithDataPath(
+                        f.type,
+                        variantFields[f.name],
+                        defs,
+                        `${dataPath}[${schema.name}::${variantName}].${f.name}`
+                    )
                 )
             )
         }
         case "variant":
             defs[schema.id] = schema
+
             return new ConstrData(
                 schema.tag,
                 schema.fieldTypes.map(({ name, type }) =>
-                    schemaToUplc(type, x[name])
+                    schemaToUplcWithDataPath(
+                        type,
+                        x[name],
+                        {},
+                        `${dataPath}.${name}`
+                    )
                 )
             )
         default:

package/src/cast/UserFunc.js

@@ -2,11 +2,13 @@ import { bytesToHex } from "@helios-lang/codec-utils"
 import { expectSome, isLeft, isString } from "@helios-lang/type-utils"
 import { ConstrData, IntData, UplcDataValue } from "@helios-lang/uplc"
 import { Cast } from "./Cast.js"
+import { BasicUplcLogger } from "@helios-lang/uplc"
 
 /**
  * @typedef {import("@helios-lang/type-utils").TypeSchema} TypeSchema
  * @typedef {import("@helios-lang/uplc").CekResult} CekResult
  * @typedef {import("@helios-lang/uplc").UplcData} UplcData
+ * @typedef {import("@helios-lang/uplc").UplcLoggingI} UplcLoggingI
  * @typedef {import("@helios-lang/uplc").UplcProgram} UplcProgram
  * @typedef {import("@helios-lang/uplc").UplcValue} UplcValue
  * @typedef {import("./Cast.js").CastConfig} CastConfig
@@ -70,9 +72,10 @@ export class UserFunc {
 
     /**
      * @param {ArgsT} namedArgs
+     * @param {UplcLoggingI} [logOptions]
      * @returns {RetT}
      */
-    eval(namedArgs) {
+    eval(namedArgs, logOptions) {
         /**
          * @type {{[argName: string]: any}}
          */
@@ -100,7 +103,8 @@ export class UserFunc {
         })
 
         const result = this.evalUnsafe(
-            /** @type {UnsafeArgsT<ArgsT>} */ (unsafeNamedArgs)
+            /** @type {UnsafeArgsT<ArgsT>} */ (unsafeNamedArgs),
+            logOptions
         )
 
         if (this.props.returns) {
@@ -115,10 +119,11 @@ export class UserFunc {
 
     /**
      * @param {UnsafeArgsT<ArgsT>} namedArgs
+     * @param {UplcLoggingI} [logOptions]
      * @returns {RetT extends void ? void : UplcData}
      */
-    evalUnsafe(namedArgs) {
-        const result = this.profile(namedArgs).result
+    evalUnsafe(namedArgs, logOptions) {
+        const result = this.profile(namedArgs, logOptions).result
 
         if (isLeft(result)) {
             throw new Error(result.left.error)
@@ -133,9 +138,10 @@ export class UserFunc {
 
     /**
      * @param {UnsafeArgsT<ArgsT>} namedArgs
+     * @param {UplcLoggingI} [logOptions] - optional, passed to UplcProgram.eval if provided
      * @returns {CekResult}
      */
-    profile(namedArgs) {
+    profile(namedArgs, logOptions) {
         const isMain = this.name == "main"
 
         /**
@@ -184,10 +190,12 @@ export class UserFunc {
 
         const argValues = args.map((a) => new UplcDataValue(a))
 
-        const cekResult = this.uplc.eval(argValues)
+        const cekResult = this.uplc.eval(argValues, { logOptions })
 
         if (this.uplc.alt?.plutusVersion == "PlutusScriptV2") {
-            const cekResultUnoptim = this.uplc.alt.eval(argValues)
+            const cekResultUnoptim = this.uplc.alt.eval(argValues, {
+                logOptions
+            })
             const resultUnoptim = cekResultUnoptim.result
             const resultUnoptimStr = evalResultToString(resultUnoptim)
             const resultStr = evalResultToString(cekResult.result)

package/types/cast/Cast.d.ts

@@ -52,10 +52,17 @@ export class Cast<TStrict, TPermissive> {
      */
     fromUplcData(data: UplcData): TStrict;
     /**
+     * converts javascript object to UPLC data, according to the schema.
+     * @remarks
+     * The optional `dataPath` parameter can provide a contextual cue for the
+     * data-conversion process, and will be displayed as part of any error messages
+     * thrown during the data transformation
+     *
      * @param {TPermissive} x
+     * @param {string} dataPath
      * @returns {UplcData}
      */
-    toUplcData(x: TPermissive): UplcData;
+    toUplcData(x: TPermissive, dataPath?: string): UplcData;
 }
 export type UplcData = import("@helios-lang/uplc").UplcData;
 export type TypeSchema = import("../codegen/index.js").TypeSchema;

package/types/cast/Cast.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Cast.d.ts","sourceRoot":"","sources":["../../src/cast/Cast.js"],"names":[],"mappings":"AAmhBA;;;;;;GAMG;AACH,8BANa,OAAO,EACP,WAAW,QACb,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,UAC9B,UAAU,GACR,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,CAQtC;AA3fD;;;GAGG;AAEH;;;;GAIG;AAEH;;;;GAIG;AAEH;;;;;GAKG;AAEH;;;GAGG;AACH,kBAHa,OAAO,EACP,WAAW;IAepB;;;OAGG;IACH,oBAHW,UAAU,UACV,UAAU,EAKpB;IAnBD;;;OAGG;IACH,iBAFU,UAAU,CAEd;IAEN;;;OAGG;IACH,iBAFU,UAAU,CAEd;IAWN;;;OAGG;IACH,mBAHW,QAAQ,GACN,OAAO,CAInB;IAED;;;OAGG;IACH,cAHW,WAAW,GACT,QAAQ,CAIpB;CACJ;uBAhEY,OAAO,mBAAmB,EAAE,QAAQ;yBACpC,OAAO,qBAAqB,EAAE,UAAU;yBAIxC;IACZ,SAAa,EAAE,OAAO,CAAA;CACnB;6BAIS,OAAO,EACP,WAAW,IACX,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC;;;;qBAKlD,OAAO,EACP,WAAW,IACX,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,GAAG,gBAAgB,CAAC,OAAO,EAAE,WAAW,CAAC"}
+{"version":3,"file":"Cast.d.ts","sourceRoot":"","sources":["../../src/cast/Cast.js"],"names":[],"mappings":"AAynBA;;;;;;GAMG;AACH,8BANa,OAAO,EACP,WAAW,QACb,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,UAC9B,UAAU,GACR,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,CAQtC;AAjmBD;;;GAGG;AAEH;;;;GAIG;AAEH;;;;GAIG;AAEH;;;;;GAKG;AAEH;;;GAGG;AACH,kBAHa,OAAO,EACP,WAAW;IAepB;;;OAGG;IACH,oBAHW,UAAU,UACV,UAAU,EAKpB;IAnBD;;;OAGG;IACH,iBAFU,UAAU,CAEd;IAEN;;;OAGG;IACH,iBAFU,UAAU,CAEd;IAWN;;;OAGG;IACH,mBAHW,QAAQ,GACN,OAAO,CAInB;IAED;;;;;;;;;;OAUG;IACH,cAJW,WAAW,aACX,MAAM,GACJ,QAAQ,CAMpB;CACJ;uBAzEY,OAAO,mBAAmB,EAAE,QAAQ;yBACpC,OAAO,qBAAqB,EAAE,UAAU;yBAIxC;IACZ,SAAa,EAAE,OAAO,CAAA;CACnB;6BAIS,OAAO,EACP,WAAW,IACX,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC;;;;qBAKlD,OAAO,EACP,WAAW,IACX,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,GAAG,gBAAgB,CAAC,OAAO,EAAE,WAAW,CAAC"}

package/types/cast/UserFunc.d.ts

@@ -2,6 +2,7 @@
  * @typedef {import("@helios-lang/type-utils").TypeSchema} TypeSchema
  * @typedef {import("@helios-lang/uplc").CekResult} CekResult
  * @typedef {import("@helios-lang/uplc").UplcData} UplcData
+ * @typedef {import("@helios-lang/uplc").UplcLoggingI} UplcLoggingI
  * @typedef {import("@helios-lang/uplc").UplcProgram} UplcProgram
  * @typedef {import("@helios-lang/uplc").UplcValue} UplcValue
  * @typedef {import("./Cast.js").CastConfig} CastConfig
@@ -55,23 +56,27 @@ export class UserFunc<ArgsT extends {
     get name(): string;
     /**
      * @param {ArgsT} namedArgs
+     * @param {UplcLoggingI} [logOptions]
      * @returns {RetT}
      */
-    eval(namedArgs: ArgsT): RetT;
+    eval(namedArgs: ArgsT, logOptions?: import("@helios-lang/uplc/types/logging/UplcLoggingI.js").UplcLoggingI | undefined): RetT;
     /**
      * @param {UnsafeArgsT<ArgsT>} namedArgs
+     * @param {UplcLoggingI} [logOptions]
      * @returns {RetT extends void ? void : UplcData}
      */
-    evalUnsafe(namedArgs: UnsafeArgsT<ArgsT>): RetT extends void ? void : UplcData;
+    evalUnsafe(namedArgs: UnsafeArgsT<ArgsT>, logOptions?: import("@helios-lang/uplc/types/logging/UplcLoggingI.js").UplcLoggingI | undefined): RetT extends void ? void : UplcData;
     /**
      * @param {UnsafeArgsT<ArgsT>} namedArgs
+     * @param {UplcLoggingI} [logOptions] - optional, passed to UplcProgram.eval if provided
      * @returns {CekResult}
      */
-    profile(namedArgs: UnsafeArgsT<ArgsT>): CekResult;
+    profile(namedArgs: UnsafeArgsT<ArgsT>, logOptions?: import("@helios-lang/uplc/types/logging/UplcLoggingI.js").UplcLoggingI | undefined): CekResult;
 }
 export type TypeSchema = import("@helios-lang/type-utils").TypeSchema;
 export type CekResult = import("@helios-lang/uplc").CekResult;
 export type UplcData = import("@helios-lang/uplc").UplcData;
+export type UplcLoggingI = import("@helios-lang/uplc").UplcLoggingI;
 export type UplcProgram = import("@helios-lang/uplc").UplcProgram;
 export type UplcValue = import("@helios-lang/uplc").UplcValue;
 export type CastConfig = import("./Cast.js").CastConfig;

package/types/cast/UserFunc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"UserFunc.d.ts","sourceRoot":"","sources":["../../src/cast/UserFunc.js"],"names":[],"mappings":"AAKA;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;GAeG;AAEH;;;GAGG;AAEH;;;GAGG;AACH,sBAHwC,KAAK,SAAhC;IAAE,CAAC,OAAO,EAAE,MAAM,GAAG,GAAG,CAAA;CAAE,EAC1B,IAAI;IAgBb;;;OAGG;IACH,kBAHW,WAAW,SACX,aAAa,EAKvB;IApBD;;;OAGG;IACH,eAFU,WAAW,CAEjB;IAEJ;;;;OAIG;IACH,uBAAK;IAWL;;OAEG;IACH,mBAEC;IAED;;;OAGG;IACH,gBAHW,KAAK,GACH,IAAI,CAyChB;IAED;;;OAGG;IACH,sBAHW,WAAW,CAAC,KAAK,CAAC,GAChB,IAAI,SAAS,IAAI,GAAG,IAAI,GAAG,QAAQ,CAc/C;IAED;;;OAGG;IACH,mBAHW,WAAW,CAAC,KAAK,CAAC,GAChB,SAAS,CAiGrB;CACJ;yBAnOY,OAAO,yBAAyB,EAAE,UAAU;wBAC5C,OAAO,mBAAmB,EAAE,SAAS;uBACrC,OAAO,mBAAmB,EAAE,QAAQ;0BACpC,OAAO,mBAAmB,EAAE,WAAW;wBACvC,OAAO,mBAAmB,EAAE,SAAS;yBACrC,OAAO,WAAW,EAAE,UAAU;;;;4BAK9B;IACZ,IAAQ,EAAE,MAAM,CAAA;IAChB,qBAAyB,EAAE,OAAO,CAAA;IAClC,qBAAyB,EAAE,OAAO,CAAA;IAClC,SAAa,EAAE;QACf,IAAU,EAAE,MAAM,CAAA;QAClB,IAAU,EAAE,UAAU,CAAA;QACtB,UAAgB,EAAE,OAAO,CAAA;KACpB,EAAE,CAAA;IACP,OAAW,CAAC,EAAE,UAAU,CAAA;IACxB,gBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7C,UAAc,EAAE,UAAU,CAAA;CACvB;wBAIS,KAAK,IACL,GAAE,CAAgB,IAAX,MAAM,KAAK,GAAG,CAAC,SAAS,gBAAgB,GAAG,MAAM,GAAG,QAAQ,GAAC"}
+{"version":3,"file":"UserFunc.d.ts","sourceRoot":"","sources":["../../src/cast/UserFunc.js"],"names":[],"mappings":"AAMA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;GAeG;AAEH;;;GAGG;AAEH;;;GAGG;AACH,sBAHwC,KAAK,SAAhC;IAAE,CAAC,OAAO,EAAE,MAAM,GAAG,GAAG,CAAA;CAAE,EAC1B,IAAI;IAgBb;;;OAGG;IACH,kBAHW,WAAW,SACX,aAAa,EAKvB;IApBD;;;OAGG;IACH,eAFU,WAAW,CAEjB;IAEJ;;;;OAIG;IACH,uBAAK;IAWL;;OAEG;IACH,mBAEC;IAED;;;;OAIG;IACH,gBAJW,KAAK,oGAEH,IAAI,CA0ChB;IAED;;;;OAIG;IACH,sBAJW,WAAW,CAAC,KAAK,CAAC,oGAEhB,IAAI,SAAS,IAAI,GAAG,IAAI,GAAG,QAAQ,CAc/C;IAED;;;;OAIG;IACH,mBAJW,WAAW,CAAC,KAAK,CAAC,oGAEhB,SAAS,CAmGrB;CACJ;yBA1OY,OAAO,yBAAyB,EAAE,UAAU;wBAC5C,OAAO,mBAAmB,EAAE,SAAS;uBACrC,OAAO,mBAAmB,EAAE,QAAQ;2BACpC,OAAO,mBAAmB,EAAE,YAAY;0BACxC,OAAO,mBAAmB,EAAE,WAAW;wBACvC,OAAO,mBAAmB,EAAE,SAAS;yBACrC,OAAO,WAAW,EAAE,UAAU;;;;4BAK9B;IACZ,IAAQ,EAAE,MAAM,CAAA;IAChB,qBAAyB,EAAE,OAAO,CAAA;IAClC,qBAAyB,EAAE,OAAO,CAAA;IAClC,SAAa,EAAE;QACf,IAAU,EAAE,MAAM,CAAA;QAClB,IAAU,EAAE,UAAU,CAAA;QACtB,UAAgB,EAAE,OAAO,CAAA;KACpB,EAAE,CAAA;IACP,OAAW,CAAC,EAAE,UAAU,CAAA;IACxB,gBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7C,UAAc,EAAE,UAAU,CAAA;CACvB;wBAIS,KAAK,IACL,GAAE,CAAgB,IAAX,MAAM,KAAK,GAAG,CAAC,SAAS,gBAAgB,GAAG,MAAM,GAAG,QAAQ,GAAC"}