Scala Webapp Utilities

This library was initially extracted (with permission) from the closed-source ShipReq where it when through many evolutions, and was battled-tested on a real-world, large and complex project. It was ported without git commit history, so please understand that in this case, the low commit count is not an indication of immaturity.

val WebappUtilVer = "<version>"

// Minimal
"com.github.japgolly.webapp-util" %%% "core"             % WebappUtilVer
"com.github.japgolly.webapp-util" %%% "test"             % WebappUtilVer % Test

// Node-specific additional testing support
"com.github.japgolly.webapp-util" %%% "test-node"        % WebappUtilVer % Test

// Requiring Boopickle
"com.github.japgolly.webapp-util" %%% "core-boopickle"   % WebappUtilVer
"com.github.japgolly.webapp-util" %%% "test-boopickle"   % WebappUtilVer % Test

// Cats Effect support
"com.github.japgolly.webapp-util" %%% "core-cats-effect" % WebappUtilVer
"com.github.japgolly.webapp-util" %%% "test-cats-effect" % WebappUtilVer % Test

// Circe JSON support
"com.github.japgolly.webapp-util" %%% "core-circe"       % WebappUtilVer
"com.github.japgolly.webapp-util" %%% "test-circe"       % WebappUtilVer % Test

// HttpClient implementation using okhttp4
"com.github.japgolly.webapp-util"  %% "core-okhttp4"     % WebappUtilVer

// Postgres support via Doobie and Cats Effect
"com.github.japgolly.webapp-util"  %% "db-postgres"      % WebappUtilVer
"com.github.japgolly.webapp-util"  %% "test-db-postgres" % WebappUtilVer % Test

Included

The core module:

• japgolly.webapputil.general

  • AsyncFunction - an async, failable function (JS only)
  • Enabled - type-safe union of Enabled | Disabled
  • ErrorMsg - typed error message, with some util and predefined cases
  • JsExt - JS-only implicit extensions (JS only)
  • LazyVal - lightweight lazy val as a portable value
  • LoggerJs - simple logger (JS only)
  • Permission - type-safe union of Allow | Deny
  • Protocol - abstract definitions of protocols
  • Retries - immutable retry policy
  • ThreadUtils - thread groups, thread pools, ExecutionContext util, shutdown hooks (JVM only)
  • TimersJs - API over JS timers (JS only)
  • Url - types for URLs
  • VarJs - immutable reference to a potentially abstract, potentially mutable variable (JS only)
  • Version - types for a version with a major and minor component

• japgolly.webapputil.ajax

  • AjaxProtocol - protocol for an AJAX endpoint
  • AjaxClient - means for a client to perform AJAX calls (JS only)

• japgolly.webapputil.binary

  • BinaryData - immutable representation of BinaryData
  • BinaryFormat - converts a type to a binary format and back (JS only)
  • BinaryJs - functions for conversion between various JS binary data types (JS only)
  • BinaryString - binary data efficiently encoded as a UTF-16 string (JS only)
  • CodecEngine - capability to encode and decode binary data given a codec typeclass
  • Compression - binary compression and decompression (JS only)
  • Encryption - binary encryption and decryption (JS only)
  • Pako - facade for the JS pako library with provides zlib compression & decompression (JS only)

• japgolly.webapputil.browser

  • WindowConfirm - abstraction over window.confirm (JS only)
  • WindowLocation - abstraction over window.location (JS only)
  • WindowPrompt - abstraction over window.prompt (JS only)

• japgolly.webapputil.entrypoint

  • EntrypointDef - definition of a JS app entrypoint
  • Entrypoint - abstract class for a JS app entrypoint (JS only)
  • EntrypointInvoker - generate JS to invoke an entrypoint (JVM only)
  • Html - HTML content (JVM only)
  • Js - typed text representing JavaScript code (plus some util) (JVM only)
  • LoadJs - define a bundle of JS assets to be loaded via loadjs before entrypoint invocation (JVM only)

• japgolly.webapputil.http

  • Cookie - abstract HTTP cookie and associated util
  • HttpClient - abstract HTTP (invocation) client
  • UrlEncoder - cross-platform URL encoding and decoding

• japgolly.webapputil.indexeddb (JS only)

  • IndexedDb - monadic API over IndexedDb that enforces transaction rules at compile-time, and provides higher-level ops such as atomic async modification (JS only)
  • IndexedDbKey - typed key for use in IndexedDb (JS only)
  • KeyCodec - codec between an arbitrary type and a IndexedDb key (JS only)
  • ObjectStoreDef - IndexedDb store and codecs (JS only)
  • ValueCodec - codec between an arbitrary type and a IndexedDb value (JS only)

• japgolly.webapputil.locks

  • LockMechanism - means of implicitly specifying how to acquire locks (JVM only)
  • LockUtils - helpers around Java locks (JVM only)
  • GenericSharedLock.Safe - shared lock APIs that are FP-safe (consistent between JVM and JS)
  • GenericSharedLock.Unsafe - shared lock APIs that are FP-unsafe, in that not effect type is used (consistent between JVM and JS)
  • SharedLock - lock that can be safely shared between threads (different API between JVM & JS)
  • SharedLock.ReadWrite - read/write lock that can be safely shared between threads (different API between JVM & JS)

• japgolly.webapputil.websocket

  • WebSocket - abstract API over a websocket connection (JS only)
  • WebSocketClient - high-level, managed websocket connection from client to server, supporting things like authorisation, auto-reconnection, retries, session expiry (TLA+ spec) (JS only)
  • WebSocketServerUtil - util for writing server-side websockets (JVM only)
  • WebSocketShared - definitions and util shared between websocket client and server

• japgolly.webapputil.webstorage (JS only)

  • AbstractWebStorage - API over webstorage with some impls
  • KeyCodec - codec between an arbitrary type and a webstorage key
  • ValueCodec - codec between an arbitrary type and a webstorage value
  • WebStorageKey - high-level interface to data in webstorage

• japgolly.webapputil.webworker (JS only)

  • AbstractWebWorker - web worker client & server API
  • ManagedWebWorker - web worker client & server implementations that handle all the low-level work
  • OnError - web worker error handler
  • WebWorkerProtocol - protocol API for communication between web worker client and server

The test module:

• japgolly.webapputil.test
  • BinaryTestUtil - util for testing binary data
  • TestAjaxClient - AjaxClient instance for use in tests (JS only)
  • TestHttpClient - HttpClient instance for use in tests
  • TestTimersJs - TimersJs instance for use in tests (JS only)
  • TestWebSocket - WebSocket instance for use in tests (JS only)
  • TestWebWorker - in-memory instances of AbstractWebWorker client and server API for use in tests (JS only)
  • TestWindowConfirm - WindowConfirm instance for use in tests (JS only)
  • TestWindowLocation - WindowLocation instance for use in tests (JS only)
  • TestWindowPrompt - WindowPrompt instance for use in tests (JS only)

The test-node module:

• japgolly.webapputil.test.node (JS only)
  • TestNode - util for testing using Node

The core-boopickle module:

• japgolly.webapputil.boopickle
  • BinaryFormatExt - additional functionality around BinaryFormat (JS only)
  • BinaryWebWorkerProtocol - implementation of WebWorkerProtocol that uses boopickle for message encoding (JS only)
  • BoopickleCodecEngine - implementation of CodecEngine for boopickle
  • BoopickleWebSocketClient - implementation of WebSocketClient that uses boopickle for message encoding (JS only)
  • EncryptionEngine - implementation of Encryption.Engine (JS only)
  • EntrypointDefExt - additional functionality around EntrypointDef
  • IndexedDbExt - additional functionality around IndexedDb (JS only)
  • PicklerUtil - util around, and implementations of, Boopickle Picklers
  • SafePickler - safer version of a Boopickle Pickler with versioning support
  • SafePicklerUtil - util for working with SafePickler versions during (de)serialisation

The test-boopickle module:

• japgolly.webapputil.boopickle.test
  • TestEncryption - util for testing encryption (JS only)
  • TestIndexedDb - util for testing IndexedDb code (JS only)
  • WebSocketTestUtil - util for testing WebSocket code (JS only)

The core-cats-effect module:

• japgolly.webapputil.cats.effect
  • Implicits so that IO is recognised as an effect type usable by the rest of the this library.
    • Effect.Async[IO]
    • Effect.Sync[IO] (JVM only)
  • ThreadUtilsIO - thread pools, scheduling, shutdown hooks, IO runtimes (JVM only)

The test-cats-effect module:

• japgolly.webapputil.cats.effect.test
  • TestHttpClientIO (JVM only)

The core-circe module:

• japgolly.webapputil.circe
  • JsonAjaxClient - implementation of AjaxClient that uses JSON and JsonCodec (JS only)
  • JsonCodec - composition of Circe's Encoder and Decoder into a single typeclass
  • JsonEntrypointCodec - creates instances of EntrypointDef.Codec using Circe codecs
  • JsonUtil - util to supplement Circe
  • Extension methods available via import japgolly.webapputil.circe._
    • HttpClient.Body.json to create response bodies as JSON
    • HttpClient.Body#parseJsonBody to parse request bodies as JSON

The test-circe module:

• japgolly.webapputil.circe.test
  • JsonTestUtil - util to test JSON codecs
  • TestJsonAjaxClient - implementation of TestAjaxClient that uses JSON and JsonCodec (JS only)

The core-okhttp4 module: (JVM only)

• japgolly.webapputil.okhttp4
  • OkHttp4Client - implementation of HttpClient using okhttp4

The db-postgres module: (JVM only)

• japgolly.webapputil.db
  • Db - connection to the database
  • DbConfig - DB config definitions, i.e. to load DB details at runtime on app startup
  • DbMigration - manages DB schema migrations (via Flyway)
  • DoobieCodecs - a few generic codecs for Doobie
  • DoobieHelpers - helpers for Doobie
  • JdbcLogging - times and logs JDBC calls
  • SqlTracer - modularised behaviour around JDBC calls
  • XA - wrapper around Transactor[IO] (used to be more and may again)

The test-db-postgres module: (JVM only)

• japgolly.webapputil.db.test
  • DbTable - util around DB tables and row counting
  • DelegateConnection - java.sql.Connection instance that routes all calls to a delegated connection
  • TestDb - provides access to a test DB, manages things like migration, and util
  • TestDbConfig - easily load DB config from tests
  • TestDbHelpers - DB util helpful during testing
  • TestXA - a live connection to the DB, and util to make testing as easy as possible

TODO:

• Add examples
• Add ScalaDoc and proper doc

Support

If you like what I do —my OSS libraries, my contributions to other OSS libs, my programming blog— and you'd like to support me, more content, more lib maintenance, please become a patron! I do all my OSS work unpaid so showing your support will make a big difference.