'documentation'

README.md

@@ -1,6 +1,6 @@
-# code template 
+# Code Template 
+![build](https://github.com/aaronp/code-template/actions/workflows/ci.yml/badge.svg)
+[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.github.aaronp/code-template_3/badge.svg?style=flat)](https://maven-badges.herokuapp.com/maven-central/com.github.aaronp/code-template_3)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-An opinionated utility for converting scala scripts into functions which 
-can work with json.
-
-Documentation can be found [here](https://aaronp.github.io/code-template/)
+Check out the [Documentation](https://aaronp.github.io/code-template/)

build.sbt

@@ -2,37 +2,41 @@ import com.typesafe.sbt.pgp
 import sbt.Credentials
 import sbt.Keys.{credentials, publishTo, test}
 import sbtwelcome._
-import sbtrelease._
 
 enablePlugins(GitVersioning)
-enablePlugins(GhpagesPlugin)
-enablePlugins(PamfletPlugin)
-enablePlugins(SiteScaladocPlugin)
 
-Pamflet / sourceDirectory := sourceDirectory.value / "docs"
+logoColor := scala.Console.GREEN
+name := "code-template"
+fork := true
+packageOptions in (Compile, packageBin) += Package.ManifestAttributes("git-sha" -> git.gitHeadCommit.value.getOrElse("unknown"))
+git.remoteRepo := s"git@github.com:aaronp/code-template.git"
+releasePublishArtifactsAction := PgpKeys.publishSigned.value
+libraryDependencies += "org.scalatest"  %% "scalatest"      % "3.2.10" % Test
+libraryDependencies += "org.scala-lang" %% "scala3-staging" % "3.1.0"
+libraryDependencies += "ch.qos.logback" % "logback-core"    % "1.2.10"
+libraryDependencies += ("com.github.aaronp"                                                            %% "eie"    % "1.0.0").cross(CrossVersion.for3Use2_13)
+libraryDependencies ++= List("circe-core", "circe-generic", "circe-parser").map(artifact => "io.circe" %% artifact % "0.14.1")
 autoAPIMappings := true
-SiteScaladoc / siteSubdirName := "api/latest"
-
-ThisBuild / ghpagesNoJekyll := true
-ThisBuild / scalafmtOnCompile := true
-ThisBuild / scalafmtVersion := "1.4.0"
-ThisBuild / versionScheme := Some("early-semver")
-ThisBuild / organization := "com.github.aaronp"
-ThisBuild / scalaVersion  := "3.1.0"
-ThisBuild / resolvers += "Sonatype OSS Snapshots" at "https://oss.sonatype.org/content/repositories/snapshots"
-ThisBuild / credentials += Credentials(Path.userHome / ".sbt" / ".credentials")
-ThisBuild / releasePublishArtifactsAction := PgpKeys.publishSigned.value
-ThisBuild / publishMavenStyle := true
-ThisBuild / exportJars := false
-ThisBuild / pomIncludeRepository := (_ => false)
-ThisBuild / publishTo := {
+ghpagesNoJekyll := true
+scalafmtOnCompile := true
+scalafmtVersion := "1.4.0"
+versionScheme := Some("early-semver")
+organization := "com.github.aaronp"
+scalaVersion := "3.1.0"
+resolvers += "Sonatype OSS Snapshots" at "https://oss.sonatype.org/content/repositories/snapshots"
+credentials += Credentials(Path.userHome / ".sbt" / ".credentials")
+releasePublishArtifactsAction := PgpKeys.publishSigned.value
+publishMavenStyle := true
+exportJars := false
+pomIncludeRepository := (_ => false)
+publishTo := {
   val nexus = "https://oss.sonatype.org/"
   if (isSnapshot.value)
     Some("snapshots" at nexus + "content/repositories/snapshots")
   else
     Some("releases" at nexus + "service/local/staging/deploy/maven2")
 }
-ThisBuild / git.gitTagToVersionNumber := { tag: String =>
+git.gitTagToVersionNumber := { tag: String =>
   if (tag matches "v?[0-9]+\\..*") {
     Some(tag)
   } else None
@@ -54,35 +58,15 @@ logo :=
 
 usefulTasks := Seq(
   UsefulTask("a", "~compile", "Compile with file-watch enabled"),
-  UsefulTask("b", "fmt", "Run scalafmt on the entire project"),
-  UsefulTask("c", "docs/mdoc", "create documentation"),
-  UsefulTask("d", "docs/docusaurusPublishGhpages", "publish documentation"),
-  UsefulTask("e", "publishLocal", "Publish the sbt plugin locally so that you can consume it from a different project"),
-  UsefulTask("f", "startDocusaurus", "Start Docusaurus"),
+  UsefulTask("b", "~test", "Test with file-watch enabled"),
+  UsefulTask("c", "release", "Release a new version (assumes you have ~/.sbt/.credentials set up)")
 )
 
-logoColor := scala.Console.GREEN
-
-lazy val root = project
-  .in(file("."))
-  .settings(
-    name := "code-template",
-    fork := true,
-    packageOptions in (Compile, packageBin) += Package.ManifestAttributes("git-sha" -> git.gitHeadCommit.value.getOrElse("unknown")),
-    git.remoteRepo := s"git@github.com:aaronp/code-template.git",
-    releasePublishArtifactsAction := PgpKeys.publishSigned.value
-  )
-  .settings(libraryDependencies += "org.scalatest"  %% "scalatest" % "3.2.10" % Test)
-  .settings(libraryDependencies += "org.scala-lang" %% "scala3-staging" % "3.1.0")
-  .settings(libraryDependencies += "ch.qos.logback" % "logback-core" % "1.2.10")
-  .settings(libraryDependencies += ("com.github.aaronp" %% "eie" % "1.0.0").cross(CrossVersion.for3Use2_13))
-  .settings(libraryDependencies ++= List("circe-core", "circe-generic", "circe-parser").map(artifact => "io.circe" %% artifact % "0.14.1"))
-
 // see https://leonard.io/blog/2017/01/an-in-depth-guide-to-deploying-to-maven-central/
 
 // To sync with Maven central, you need to supply the following information:
 //Global / pomExtra := {
-ThisBuild / pomExtra := {
+pomExtra := {
   <url>https://github.com/aaronp/code-template</url>
     <licenses>
       <license>
@@ -98,24 +82,3 @@ ThisBuild / pomExtra := {
       </developer>
     </developers>
 }
-
-lazy val docs = project       // new documentation project
-  .in(file("site")) // important: it must not be docs/
-  .dependsOn(root)
-  .enablePlugins(MdocPlugin, DocusaurusPlugin)
-  .settings(
-    mdocVariables := Map("VERSION" -> version.value),
-    moduleName := "site",
-    mdocOut := baseDirectory.value.toPath.resolve("src/pages").toFile
-  )
-
-lazy val startDocusaurus = taskKey[String]("Builds the client").withRank(KeyRanks.APlusTask)
-
-startDocusaurus := {
-  import sys.process._
-  val workDir = new java.io.File("site")
-  val output  = sys.process.Process(Seq("npx", "docusaurus", "start"), workDir).!!
-  java.awt.Desktop.getDesktop.browse(new URI("http://localhost:3000/index.html"))
-  sLog.value.info(output)
-  output
-}

dockerTest.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+
+# This is just a convenience script should anybody want to test locally if they don't have sbt installed
+#
+# See https://hub.docker.com/r/hseeberger/scala-sbt/
+docker run -it --rm -u sbtuser \
+  -w /code \
+  -v $(pwd):/code \
+  -v $HOME/.ivy2:/home/sbtuser/.ivy2 \
+  -v $HOME/.sbt:/home/sbtuser/.sbt \
+  -v $HOME/.m2:/home/sbtuser/.m2 \
+  hseeberger/scala-sbt:8u222_1.3.5_2.13.1 \
+  sbt test

docs/about.md

@@ -1,11 +1,49 @@
-# Code Template
+### The Way Configuration Is Done Hurts
 
-To install my project
-```scala
-libraryDependencies += "com.github.aaronp" % "code-template" % "@VERSION@"
+There is a lot of common ceremony/boilerplate in a lot of projects - setting up REST services, or ETL functions, etc.
+
+This project provides the main components to drive a "black-box" computation - typically which operates on json messages.
+
+This is a typical software component project life-cycle:
+
+```
+1. bootstrap a new project (or copy/clone some exististing project)
+2. hack around with all the usual stuff (configuration parsing, auth, routing, packaging, ...)
+3. finally get to the business logic you wanted to solve
+```
+
+And then the iterations - with a new feature/behavior, you often have to:
+
+```
+1. introduce some new property (e.g., perhaps an `app.properties` has a myApp.newFeature.isEnabled = true)
+2. change the config parsing (the code which knows how to look for myApp.newFeature.isEnabled)
+3. implement some logic based on that configuration
+```
+
+# Usage
+
+Imagine we're writing an application which knows how to do efficient, resource-safe batch processing on a stream of data.
+
+That application might use this library to do something like this:
+```
+val compiler       = CodeTemplate.newCache[Json, Json]()
+```
+
+That compiler is a function which takes a string (e.g. some business logic script) and returns the __business logic__ - a function
+which takes some input _Context_ and returns the result type (e.g. some Json in this case).
+
+```
+     // in practice, this script wouldn't be hard-coded, but come an application configuration, such as a kubernetes config map,
+     // a cloud bucket - whatever.
+     val script : String = """
+           val result = input.content.hello.world // <-- here we would implment our business logic - compute a value, call a service, whatever
+           result.asJson
+      """
+      
+      // at the usage site, that script would be attempted to be compiled (hence the Try) into an Expression, 
+      // which is a function of some 'Context[Input]' into the result type.
+      //
+      // here we have normal Json input and Json output:
+      val compiledResult: Try[Expression[Json, Json]] = compiler(script)
 ```
 
-```scala mdoc
-val x = 1
-List(x, x)
-```

docs/readme.md

@@ -1,6 +1,38 @@
-# Code Template
+![build](https://github.com/aaronp/code-template/actions/workflows/ci.yml/badge.svg)
+[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.github.aaronp/code-template_3/badge.svg?style=flat)](https://maven-badges.herokuapp.com/maven-central/com.github.aaronp/code-template_3)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-To install: 
-```scala
-libraryDependencies += "com.github.aaronp" % "code-template" % "0.1.1"
+# About - the 'why' idea
+
+### TL;DR;
+
+Write [serverless-like](https://en.wikipedia.org/wiki/Serverless_computing) applications which have the ability to actually reach stability.
+
+That is, just drop-in the business logic script within some applications without having to change those applications.
+
+Any time we have to create a new app, such as:
+ * a REST service which can execute some business logic for fixed endpoints
+ * a steams (kafka, rabbit, whatever) app to do some ETL
+ * a batch/cron job which can do all the authentication/context prep and then just run some logic
+
+We have some overhead before we even do anything:
+ * create a repo
+ * put in the CI/CD
+ * documentation
+ * the SDLC stuff (dev/test/release)
+
+We should be able to do better - to offer an "insert here" business-logic in a lof our applications.
+
+To read more, see [here](about.md).
+
+# Building
+
+This project is built using [sbt](https://www.scala-sbt.org/):
+```
+sbt test
+```
+
+Otherwise if you want to play around (and have docker installed) for a container-based experience:
 ```
+./dockerTest.sh
+```