Skip to content

Latest commit

 

History

History
232 lines (183 loc) · 19.3 KB

README.md

File metadata and controls

232 lines (183 loc) · 19.3 KB
Raw

Scala Webapp Utilities

Build Status Latest Version

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

  • 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)

The test module:

The test-node module:

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

The core-boopickle module:

  • japgolly.webapputil.boopickle

The test-boopickle module:

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:

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

The core-okhttp4 module: (JVM only)

  • japgolly.webapputil.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.