Improve syntax

README.md

@@ -23,6 +23,20 @@ Please, drop a ⭐️ if you are interested in this project and you want to supp
 libraryDependencies += "com.github.geirolz" %% "secret" % "0.0.11"
 ```
 
+## Usage
+
+```scala
+import com.geirolz.secret.*
+ import scala.util.Try
+
+ val reusableSecret: Secret[String]  = Secret("password") // reusable secret
+// reusableSecret: Secret[String] = ** SECRET **
+ val oneShotSecret: Secret.OneShot[String] = Secret.oneShot("password") // one shot secret
+// oneShotSecret: OneShotSecret[String] = ** SECRET **
+ val deferredSecret: Secret.Deferred[Try, String] = Secret.deferred(Try("password")) // deferred secret
+// deferredSecret: DeferredSecret[[T >: Nothing <: Any] => Try[T], String] = com.geirolz.secret.DeferredSecret$$anon$1@2ed6f149
+```
+
 ## Obfuscation
 
 By default the value is obfuscated when creating the `Secret` instance using the implicit `SecretStrategy` which, by default, transform the value into a xor-ed
@@ -52,8 +66,8 @@ val database: Either[SecretDestroyed, Database] = secretString.euseAndDestroy(pa
 
 // if you try to access the secret value once used, you'll get an error
 secretString.euse(println(_))
-// res1: Either[SecretDestroyed, Unit] = Left(
-//   value = SecretDestroyed(destructionLocation = README.md:25:113)
+// res2: Either[SecretDestroyed, Unit] = Left(
+//   value = SecretDestroyed(destructionLocation = README.md:50:113)
 // )
 ```
 
@@ -150,7 +164,7 @@ given SecretStrategy[String] = SecretStrategy[String](
 )
 
 Secret("my_password").euse(secret => secret)
-// res9: Either[SecretDestroyed, String] = Right(value = "CUSTOM")
+// res10: Either[SecretDestroyed, String] = Right(value = "CUSTOM")
 ```
 
 ## Custom Obfuscation Strategy algebra
@@ -173,26 +187,25 @@ val myCustomAlgebra = new SecretStrategyAlgebra:
 
     final def deObfuscator[P](f: PlainValueBuffer => P): DeObfuscator[P] =
       DeObfuscator.of { bufferTuple => f(bufferTuple.roObfuscatedBuffer) }
-// myCustomAlgebra: SecretStrategyAlgebra = repl.MdocSession$MdocApp10$$anon$9@55a1c811
+// myCustomAlgebra: SecretStrategyAlgebra = repl.MdocSession$MdocApp11$$anon$12@6512f34b
 
 // build factory based on the algebra
 val myCustomStrategyFactory = myCustomAlgebra.newFactory
-// myCustomStrategyFactory: SecretStrategyFactory = com.geirolz.secret.strategy.SecretStrategyFactory@1ffbad11
-
+// myCustomStrategyFactory: SecretStrategyFactory = com.geirolz.secret.strategy.SecretStrategyFactory@5be15840
 
 // ----------------------------- USAGE -----------------------------
 // implicitly in the scope
 
 import myCustomStrategyFactory.given
 
 Secret("my_password").euse(secret => secret)
-// res11: Either[SecretDestroyed, String] = Right(value = "my_password")
+// res12: Either[SecretDestroyed, String] = Right(value = "my_password")
 
 // or restricted to a specific scope
 myCustomStrategyFactory {
   Secret("my_password").euse(secret => secret)
 }
-// res12: Either[SecretDestroyed, String] = Right(value = "my_password")
+// res13: Either[SecretDestroyed, String] = Right(value = "my_password")
 ```
 
 ## Contributing

core/src/main/scala/com/geirolz/secret/Secret.scala

@@ -9,6 +9,8 @@ import com.geirolz.secret.util.*
 import scala.util.Try
 
 /** Memory-safe and type-safe secret value of type `T`.
+  *
+  * A.K.A. `ReusableSecret`
   *
   * `Secret` does the best to avoid leaking information in memory and in the code BUT an attack is possible and I don't
   * give any certainties or guarantees about security using this class, you use it at your own risk. Code is open
@@ -116,8 +118,12 @@ abstract sealed class Secret[T] private (vault: Vault[T]) extends SecretApi[T](v
     evalUse[Try, Boolean](thisValue => that.use[Try, Boolean](_ === thisValue)).getOrElse(false)
 
 object Secret extends SecretCompanionApi[Secret]:
-  export DeferredSecret.apply as defer
-  export DeferredSecret.fromEnv as deferFromEnv
+
+  type OneShot[T] = OneShotSecret[T]
+  final val oneShot = OneShotSecret
+
+  type Deferred[F[_], T] = DeferredSecret[F, T]
+  final val deferred = DeferredSecret
 
   /** Create a destroyed secret */
   override def destroyed[T](location: Location = Location.unknown): Secret[T] =

core/src/main/scala/com/geirolz/secret/types.scala

@@ -1,21 +1,15 @@
 package com.geirolz.secret
 
-import cats.{MonadError, Show}
-import com.geirolz.secret.util.Location
+import cats.MonadError
+import com.geirolz.secret.strategy.SecretStrategy
+import com.geirolz.secret.util.Hasher
 
 import java.nio.ByteBuffer
-import scala.util.control.NoStackTrace
 
 type PlainValueBuffer      = ByteBuffer
 type ObfuscatedValueBuffer = ByteBuffer
 type KeyBuffer             = ByteBuffer
 
-// alias
-type SPassword = Secret[String]
-object SPassword:
-  type OneShot = OneShotSecret[String]
-  def apply(value: String): SPassword = Secret(value)
-
 // private
 private[secret] type MonadSecretError[F[_]] = MonadError[F, ? >: SecretDestroyed]
 private[secret] val vaultTag: String     = "** VAULT **"

core/src/test/scala/com/geirolz/secret/SecretSuite.scala

@@ -47,10 +47,10 @@ abstract class SecretSuite(using SecretStrategyFactory) extends munit.ScalaCheck
       )
   }
 
-  test("Secret.deferredFromEnv") {
+  test("Secret.deferred.fromEnv") {
     given SysEnv[Try] = SysEnv.fromMap[Try](Map("TEST" -> "VALUE"))
-    Secret
-      .deferFromEnv[Try]("TEST")
+    Secret.deferred
+      .fromEnv[Try]("TEST")
       .use(value =>
         assertEquals(
           obtained = value,

docs/compiled/README.md

@@ -23,6 +23,20 @@ Please, drop a ⭐️ if you are interested in this project and you want to supp
 libraryDependencies += "com.github.geirolz" %% "secret" % "0.0.11"
 ```
 
+## Usage
+
+```scala
+import com.geirolz.secret.*
+ import scala.util.Try
+
+ val reusableSecret: Secret[String]  = Secret("password") // reusable secret
+// reusableSecret: Secret[String] = ** SECRET **
+ val oneShotSecret: Secret.OneShot[String] = Secret.oneShot("password") // one shot secret
+// oneShotSecret: OneShotSecret[String] = ** SECRET **
+ val deferredSecret: Secret.Deferred[Try, String] = Secret.deferred(Try("password")) // deferred secret
+// deferredSecret: DeferredSecret[[T >: Nothing <: Any] => Try[T], String] = com.geirolz.secret.DeferredSecret$$anon$1@2ed6f149
+```
+
 ## Obfuscation
 
 By default the value is obfuscated when creating the `Secret` instance using the implicit `SecretStrategy` which, by default, transform the value into a xor-ed
@@ -52,8 +66,8 @@ val database: Either[SecretDestroyed, Database] = secretString.euseAndDestroy(pa
 
 // if you try to access the secret value once used, you'll get an error
 secretString.euse(println(_))
-// res1: Either[SecretDestroyed, Unit] = Left(
-//   value = SecretDestroyed(destructionLocation = README.md:25:113)
+// res2: Either[SecretDestroyed, Unit] = Left(
+//   value = SecretDestroyed(destructionLocation = README.md:50:113)
 // )
 ```
 
@@ -150,7 +164,7 @@ given SecretStrategy[String] = SecretStrategy[String](
 )
 
 Secret("my_password").euse(secret => secret)
-// res9: Either[SecretDestroyed, String] = Right(value = "CUSTOM")
+// res10: Either[SecretDestroyed, String] = Right(value = "CUSTOM")
 ```
 
 ## Custom Obfuscation Strategy algebra
@@ -173,26 +187,25 @@ val myCustomAlgebra = new SecretStrategyAlgebra:
 
     final def deObfuscator[P](f: PlainValueBuffer => P): DeObfuscator[P] =
       DeObfuscator.of { bufferTuple => f(bufferTuple.roObfuscatedBuffer) }
-// myCustomAlgebra: SecretStrategyAlgebra = repl.MdocSession$MdocApp10$$anon$9@55a1c811
+// myCustomAlgebra: SecretStrategyAlgebra = repl.MdocSession$MdocApp11$$anon$12@6512f34b
 
 // build factory based on the algebra
 val myCustomStrategyFactory = myCustomAlgebra.newFactory
-// myCustomStrategyFactory: SecretStrategyFactory = com.geirolz.secret.strategy.SecretStrategyFactory@1ffbad11
-
+// myCustomStrategyFactory: SecretStrategyFactory = com.geirolz.secret.strategy.SecretStrategyFactory@5be15840
 
 // ----------------------------- USAGE -----------------------------
 // implicitly in the scope
 
 import myCustomStrategyFactory.given
 
 Secret("my_password").euse(secret => secret)
-// res11: Either[SecretDestroyed, String] = Right(value = "my_password")
+// res12: Either[SecretDestroyed, String] = Right(value = "my_password")
 
 // or restricted to a specific scope
 myCustomStrategyFactory {
   Secret("my_password").euse(secret => secret)
 }
-// res12: Either[SecretDestroyed, String] = Right(value = "my_password")
+// res13: Either[SecretDestroyed, String] = Right(value = "my_password")
 ```
 
 ## Contributing

docs/source/README.md

@@ -23,6 +23,17 @@ Please, drop a ⭐️ if you are interested in this project and you want to supp
 libraryDependencies += "com.github.geirolz" %% "secret" % "@VERSION@"
 ```
 
+## Usage
+
+```scala mdoc:reset
+ import com.geirolz.secret.*
+ import scala.util.Try
+
+ val reusableSecret: Secret[String]  = Secret("password") // reusable secret
+ val oneShotSecret: Secret.OneShot[String] = Secret.oneShot("password") // one shot secret
+ val deferredSecret: Secret.Deferred[Try, String] = Secret.deferred(Try("password")) // deferred secret
+```
+
 ## Obfuscation
 
 By default the value is obfuscated when creating the `Secret` instance using the implicit `SecretStrategy` which, by default, transform the value into a xor-ed