[{"name":"TaskPort","comment":" This module allows to invoke JavaScript functions using the Elm's Task abstraction,\nwhich is convenient for chaining multiple API calls without introducing the complexity\nin the model of an Elm application.\n\n# Setting up\nBefore TypePort can be used in Elm, it must be set up on JavaScript side.\nRefer to the [README](https://github.com/lobanov/elm-taskport/blob/main/README.md) for comprehensive instructions.\n\n# Usage\n@docs call, callNoArgs\n\n# Error handling\n@docs Error, JSError, JSErrorRecord, InteropError, jsErrorDecoder, interopErrorToString, jsErrorToString, errorToString\n\n# Tests\nWe are exposing tests suite to help test module's implementation details.\n@docs tests\n\n","unions":[{"name":"Error","comment":" A structured error describing exactly how the interop call failed. You can use\nthis to determine the best way to react to and recover from the problem.\n\nCallError prefix is for errors explicitly sent from the JavaScript side. The error information\nwill be specific to the interop use case, and it should be reconsituted from a JSON payload.\n\nInteropError prefix is for the failures of the interop mechanism itself.\n","args":["x"],"cases":[["InteropError",["TaskPort.InteropError"]],["CallError",["x"]]]},{"name":"InteropError","comment":" Subcategory of errors indicating a failure of the interop mechanism itself.\nThese errors are generally not receoverable, but you can use them to allow the application to fail gracefully,\nor at least provide useful context for debugging, for which you can use helper function `interopErrorToString`.\n","args":[],"cases":[["FunctionNotFound",[]],["NotInstalled",[]],["VersionMismatch",[]],["CannotDecodeResponse",["Json.Decode.Error","String.String"]],["CannotDecodeError",["Json.Decode.Error","String.String"]],["RuntimeError",["String.String"]]]},{"name":"JSError","comment":" Generic type representing all possibilities that could be returned from an interop call.\nJavaScript is very lenient regarding its errors. Any value could be thrown, and, if the JS code\nis asynchronous, the `Promise` can reject with any value. TaskPort always attempts to decode erroneous\nresults returned from iterop calls using `ErrorObject` variant and `JSErrorRecord` structure, which\ncontains standard fields for JavaScript `Error` object, but if itsn't possible, it will resorts to\n`ErrorValue` variant followed by the JSON value as-is. \n\nIn most cases you would pass values of this type to `jsErrorToString` to create\na useful diagnostic information, but you might also have a need to handle certain types\nof errors in a particular way. To make that easier, `ErrorObject` variant lifts up the error\nname to aid pattern-match for error types. You may do something like this:\n\n    case error of\n        CallError (ErrorObject \"VerySpecificError\" _) -> -- handle a particular subtype of Error thrown by the JS code\n        _ -> -- respond to the error in a generic way, e.g show a diagnostic message\n","args":[],"cases":[["ErrorObject",["String.String","TaskPort.JSErrorRecord"]],["ErrorValue",["Json.Encode.Value"]]]}],"aliases":[{"name":"JSErrorRecord","comment":" Structure describing an object conforming to JavaScript standard for `Error`.\nUnless you need to handle very specific failure condition in a particular way, you are unlikely\nto use this type.\n\nThe structure contains the following fields:\n* `name` represents the type of the `Error` object, e.g. `ReferenceError`\n* `message` is a free-form string typically passed as a parameter to the error constructor\n* `stackLines` is a platform-specific stack trace for the error\n* `cause` optional nested error object, which is first attempted to be decoded as a `JSErrorRecord`, but\nfalls back to `JSError.ErrorValue` if that's impossible.\n","args":[],"type":"{ name : String.String, message : String.String, stackLines : List.List String.String, cause : Maybe.Maybe TaskPort.JSError }"}],"values":[{"name":"call","comment":" Creates a Task encapsulating an invocation of a particular asyncronous JavaScript function.\nThis function will usually be wrapped into a more specific one, which will partially apply it\nproviding the encoder and the decoders but curry the last parameter, so that it could invoked where necessary\nas a `args -> Task` function.\n\nBecause interop calls can fail, produced task would likely need to be piped into a `Task.attempt` or handled further using `Task.onError`.\n\nHere is a simple example that creates a `Cmd` invoking a registered JavaScript function called `ping`\nand produces a message `GotPong` with a `Result`, containing either an `Ok` variant with a string (determined by the first decoder argument),\nor an `Err`, containing a `TaskPort.Error` describing what went wrong.\n\n    type Msg = GotWidgetName (Result String String)\n\n    TaskPort.call \"getWidgetNameByIndex\" Json.Decode.string TaskPort.jsErrorDecoder Json.Encode.int 0\n        |> Task.attempt GotWidgetName\n\nThe `Task` abstraction allows to effectively compose chains of tasks without creating many intermediate variants in the Msg type, and\ndesigning the model to deal with partially completed call chain. The following example shows how this might be used\nwhen working with a hypothetical 'chatty' JavaScript API, requiring to call `getWidgetsCount` function to obtain a number\nof widgets, and then call `getWidgetName` with each widget's index to obtain its name.\n\n    type Msg = GotWidgets (Result String (List String))\n    \n    TaskPort.callNoArgs \"getWidgetsCount\" Json.Decode.int TaskPort.jsErrorDecoder\n        |> Task.andThen\n            (\\count ->\n                List.range 0 (count - 1)\n                    |> List.map Json.Encode.int\n                    |> List.map (TaskPort.call \"getWidgetNameByIndex\" TaskPort.jsErrorDecoder Json.Decode.string)\n                    |> Task.sequence\n            )\n        |> Task.attempt GotWidgets\n\nThe resulting task has type `Task (TaskPort.Error String) (List String)`, which could be attempted as a single command,\nwhich, if successful, provides a handy `List String` with all widget names.\n","type":"String.String -> Json.Decode.Decoder body -> Json.Decode.Decoder error -> (args -> Json.Encode.Value) -> args -> Task.Task (TaskPort.Error error) body"},{"name":"callNoArgs","comment":" Special version of the `call` that reduces amount of boilerplate code required when calling JavaScript functions\nthat don't take any parameters. It is eqivalent of passing `Json.Encoder.null` into the `call`.\n\n    type Msg = GotWidgetsCount (Result String Int)\n\n    TaskPort.callNoArgs \"getWidgetsCount\" Json.Decode.int Json.Decode.string\n        |> Task.attempt GotWidgetsCount\n","type":"String.String -> Json.Decode.Decoder body -> Json.Decode.Decoder error -> Task.Task (TaskPort.Error error) body"},{"name":"errorToString","comment":" Convenience method for creating a user-presentable string describing an error\nwhich occured during an interop call in case use `jsErrorDecoder` in your interop calls.\n","type":"TaskPort.Error TaskPort.JSError -> String.String"},{"name":"interopErrorToString","comment":" In most cases instances of `InteropError` indicate a catastrophic failure in the\napplication environment and thus cannot be recovered from. This function allows\nElm application to fail gracefully by displaying an error message to the user,\nthat would help application developer to debug the issue.\n\nIt produces multiple lines of output, so you may want to peek at it with\nsomething like this:\n\n    import Html\n\n    errorToHtml : TaskPort.Error -> Html.Html msg\n    errorToHtml error =\n      Html.pre [] [ Html.text (TaskPort.interopErrorToString error) ]\n","type":"TaskPort.InteropError -> String.String"},{"name":"jsErrorDecoder","comment":" JSON decoder that constructs a `JSError` value from erroneous results returned by an interop call.\nYou would pass it to `TaskPort.call` or `TaskPort.callNoArgs`.\n","type":"Json.Decode.Decoder TaskPort.JSError"},{"name":"jsErrorToString","comment":" Generates a human-readable and hopefully helpful string with diagnostic information\ndescribing a `JSError`. It produces multiple lines of output, so you may want to peek at it with\nsomething like this:\n\n    import Html\n\n    errorToHtml : TaskPort.JSError -> Html.Html msg\n    errorToHtml error =\n      Html.pre [] [ Html.text (TaskPort.jsErrorToString error) ]\n","type":"TaskPort.JSError -> String.String"},{"name":"tests","comment":" This is an embedded tests suite allowing to test module-internal logic. No need to use this. ","type":"Test.Test"}],"binops":[]}]