Merge pull request #1 from thought2/dev2

dev -> main

Author: m-bock

README.md

@@ -2,7 +2,7 @@
 
 ![example workflow](https://github.com/thought2/purescript-ts-bridge/actions/workflows/ci.yml/badge.svg)
 
-A **PureScript** library for type class based **TypeScript** type generation (`.d.ts` files).
+Call your PureScript code from TypeScript.
 
 ## Documentation
 
@@ -28,13 +28,17 @@ spago install ts-bridge
 - Polymorphic types optimized for best type inference in TS
 - Tried and tested in production
 
+## How it works
+
+Via type classes a set of types are defined that you'd like to support to export to TypeScript.
+The library creates an extra CLI entry point to your app, which generates types for given values of those types. They get written to the file system in the form of TypeScript type declaration (`.d.ts`) files.
 
 ## Similar Projects
 
 - [purescript-tsd-gen](https://github.com/minoki/purescript-tsd-gen)
   This project follows a different approach for type generation. It extracts TypeScript types from the PureScript CST. As such the process is more automated but less customizable.
 
-# Support
+## Support
 
 If you find a bug or have a feature idea feel free to make a PR or file an issue.
 

docs/getting-started.md

@@ -36,6 +36,7 @@ And add the following imports are needed for this example:
 ```hs
 import Prelude
 
+import DTS as DTS
 import Data.Either (Either)
 import Effect (Effect)
 import TsBridge as TSB
@@ -47,7 +48,7 @@ Then you should define a typeclass that looks like this:
 
 ```hs
 class TsBridge (a :: Type) where
-  tsBridge :: Proxy a -> TSB.StandaloneTsType
+  tsBridge :: Proxy a -> TSB.TsBridgeM DTS.TsType
 ```
 </li>
 <li>
@@ -125,7 +126,7 @@ The same for the values that we want to expose. However, we're making use of
 record puns to eliminate the risk of spelling mistakes:
 
 ```hs
-myTsProgram :: Either TSB.Error TSB.TsProgram
+myTsProgram :: Either TSB.AppError DTS.TsProgram
 myTsProgram =
   TSB.tsProgram
     [ TSB.tsModuleFile "Sample"

justfile

@@ -1,10 +1,15 @@
 set shell := ["bash", "-c"]
 
+allowed_warnings := "ImplicitQualifiedImport"
+
 build:
-    spago build --purs-args '--stash --censor-lib --censor-codes=ImplicitQualifiedImport'
+    spago build --purs-args '--stash --censor-lib --censor-codes={{allowed_warnings}}'
 
 build-strict:
-    spago build --purs-args '--stash --censor-lib --strict --censor-codes=ImplicitQualifiedImport'
+    spago build --purs-args '--stash --censor-lib --strict --censor-codes={{allowed_warnings}}'
+
+clean:
+    rm -rf .spago output .psa-stash
 
 format:
     purs-tidy format-in-place 'src/**/*.purs'
@@ -26,7 +31,7 @@ check-spell:
     yarn run cspell "docs/**/*.md" || true
     yarn run cspell "README.md" || true
 
-ci: check-format gen-docs check-git-clean build-strict test
+ci: clean check-format gen-docs build-strict test check-git-clean
 
 check-git-clean:
     [ -z "$(git status --porcelain)" ]

packages.dhall

@@ -2,4 +2,22 @@ let upstream =
       https://github.com/purescript/package-sets/releases/download/psc-0.15.4-20220901/packages.dhall
         sha256:f1531b29c21ac437ffe5666c1b6cc76f0a9c29d3c9d107ff047aa2567744994f
 
-in  upstream
+in  upstream
+
+
+  with dts =
+    { dependencies =
+  [ "arrays"
+  , "console"
+  , "effect"
+  , "maybe"
+  , "newtype"
+  , "ordered-collections"
+  , "ordered-set"
+  , "prelude"
+  , "tuples"
+  ]
+    , repo = "https://github.com/thought2/purescript-dts.git"
+    , version = "ea900ff5108f6dec7c7fbab14cb6c09d036c0d63"
+    }
+  

spago.dhall

@@ -4,6 +4,7 @@
   , "aff-promise"
   , "arrays"
   , "console"
+  , "dts"
   , "effect"
   , "either"
   , "foldable-traversable"

src/TsBridge.purs

@@ -4,7 +4,6 @@ module TsBridge
 
 import TsBridge.Cli as Exp
 import TsBridge.Core as Exp
-import TsBridge.DTS as Exp
 import TsBridge.Monad as Exp
-import TsBridge.Print as Exp
-import TsBridge.DefaultImpls as Exp
+import TsBridge.DefaultImpls as Exp
+import TsBridge.Types as Exp

src/TsBridge/Cli.purs

@@ -5,6 +5,8 @@ module TsBridge.Cli (mkTypeGenCli) where
 
 import Prelude
 
+import DTS (TsProgram)
+import DTS.Print (Path(..), TsSource(..), printTsProgram)
 import Data.Either (Either(..))
 import Data.Foldable (fold, for_)
 import Data.Map as Map
@@ -21,8 +23,7 @@ import Node.Path (dirname)
 import Node.Process as Process
 import Options.Applicative (help, helper, info, long, metavar, strOption, value, (<**>))
 import Options.Applicative as O
-import TsBridge.DTS (TsProgram, Error, printError)
-import TsBridge.Print (Path(..), TsSource(..), printTsProgram)
+import TsBridge.Types (AppError, printError)
 
 -------------------------------------------------------------------------------
 -- Types
@@ -58,14 +59,18 @@ parserInfoTsBridgeCliOpts = info (parserTsBridgeCliOpts <**> helper)
 -------------------------------------------------------------------------------
 -- App
 -------------------------------------------------------------------------------
-mkTypeGenCliAff :: Either Error TsProgram -> Aff Unit
+mkTypeGenCliAff :: Either AppError TsProgram -> Aff Unit
 mkTypeGenCliAff eitherTsProg = do
   cliOpts <- liftEffect $ O.execParser parserInfoTsBridgeCliOpts
 
   case eitherTsProg of
     Left err -> do
-      log $ printError err
-      liftEffect $ Process.exit 0
+      log ""
+      log "Cannot generate TypeScript Code. The following error happened:"
+      log ""
+      log $ show $ printError err
+      log ""
+      liftEffect $ Process.exit 1
     Right tsProg -> writeTsProgramToDisk cliOpts tsProg
 
 writeTsProgramToDisk :: TsBridgeCliOpts -> TsProgram -> Aff Unit
@@ -86,6 +91,6 @@ writeTsProgramToDisk cliOpts tsProg = do
 
 -- | Given a `TsProgram` returns an effectful CLI that can be used as an entry
 -- | point for a type generator.
-mkTypeGenCli :: Either Error TsProgram -> Effect Unit
+mkTypeGenCli :: Either AppError TsProgram -> Effect Unit
 mkTypeGenCli tsProg = launchAff_ $ mkTypeGenCliAff tsProg
 

src/TsBridge/Core.purs

@@ -1,6 +1,5 @@
 module TsBridge.Core
-  ( StandaloneTsType
-  , class TsBridgeBy
+  ( class TsBridgeBy
   , class TsValues
   , class TsValuesRL
   , tsBridgeBy
@@ -15,8 +14,9 @@ module TsBridge.Core
 
 import Prelude
 
-import Control.Monad.Error.Class (class MonadError, catchError, throwError)
+import Control.Monad.Error.Class (throwError)
 import Control.Monad.Writer (listens, tell)
+import DTS as DTS
 import Data.Array as A
 import Data.Array as Array
 import Data.Either (Either)
@@ -32,16 +32,15 @@ import Prim.Row as Row
 import Prim.RowList (class RowToList, RowList)
 import Prim.RowList as RL
 import Safe.Coerce (coerce)
-import TsBridge.DTS (TsNameDraft)
-import TsBridge.DTS as DTS
 import TsBridge.Monad (Scope(..), TsBridgeAccum(..), TsBridgeM, runTsBridgeM)
+import TsBridge.Types (AppError(..), mapErr, mkName, mkPursModuleName, toTsName)
 import Type.Proxy (Proxy(..))
 
 -- | A `StandaloneTsType` represents a TypeScript type with everything it needs
 -- | to be placed inside complete TS program: If the type references nominal
 -- | types from other modules, all information is contained that is needed to
 -- | render those references.
-type StandaloneTsType = TsBridgeM DTS.TsType
+--type StandaloneTsType = TsBridgeM DTS.TsType
 
 -- | Type Class that is used by the type generator to recursively traverse
 -- | types.
@@ -64,16 +63,19 @@ type StandaloneTsType = TsBridgeM DTS.TsType
 
 class TsBridgeBy :: Type -> Type -> Constraint
 class TsBridgeBy tok a where
-  tsBridgeBy :: tok -> Proxy a -> StandaloneTsType
+  tsBridgeBy :: tok -> Proxy a -> TsBridgeM DTS.TsType
 
-tsModuleFile :: String -> Array (TsBridgeM (Array DTS.TsDeclaration)) -> Either DTS.Error (Array DTS.TsModuleFile)
-tsModuleFile n xs = do
-  (xs' /\ TsBridgeAccum { typeDefs }) <- runTsBridgeM $ mapErr (DTS.AtModule n) $ join <$> sequence xs
+tsModuleFile :: String -> Array (TsBridgeM (Array DTS.TsDeclaration)) -> Either AppError (Array DTS.TsModuleFile)
+tsModuleFile n xs =
+  mapErr (AtModule n)
+    do
+      -- TODO: check for duplicate identifiers
 
-  pure (typeDefs <> [ DTS.TsModuleFile (DTS.TsFilePath (n <> "/index.d.ts")) (DTS.TsModule xs') ])
+      _ <- mkPursModuleName n
 
-mapErr :: forall e m a. MonadError e m => (e -> e) -> m a -> m a
-mapErr f ma = catchError ma (f >>> throwError)
+      (xs' /\ TsBridgeAccum { typeDefs }) <- runTsBridgeM $ join <$> sequence xs
+
+      pure (typeDefs <> [ DTS.TsModuleFile (DTS.TsFilePath (n <> "/index.d.ts")) (DTS.TsModule xs') ])
 
 mergeModules :: Array DTS.TsModuleFile -> DTS.TsProgram
 mergeModules xs =
@@ -87,17 +89,19 @@ mergeModule (DTS.TsModule ds1) (DTS.TsModule ds2) =
   DTS.TsModule
     (Array.nub (ds1 <> ds2))
 
-tsProgram :: Array (Either DTS.Error (Array DTS.TsModuleFile)) -> Either DTS.Error DTS.TsProgram
-tsProgram xs = xs # sequence <#> join >>> mergeModules
+tsProgram :: Array (Either AppError (Array DTS.TsModuleFile)) -> Either AppError DTS.TsProgram
+tsProgram xs =
+  -- TODO: check for duplicate modules
+  xs # sequence <#> join >>> mergeModules
 
 -- | For rare cases where you want to export a type alias. References to this type
 -- | alias will be fully resolved in the generated code. So it is more practical
 -- | to use a newtype instead, which can be references by name.
-tsTypeAlias :: forall tok a. TsBridgeBy tok a => tok -> TsNameDraft -> Proxy a -> TsBridgeM (Array DTS.TsDeclaration)
-tsTypeAlias tok n x = ado
+tsTypeAlias :: forall tok a. TsBridgeBy tok a => tok -> String -> Proxy a -> TsBridgeM (Array DTS.TsDeclaration)
+tsTypeAlias tok aliasName x = ado
   x /\ scope <- listens (un TsBridgeAccum >>> _.scope >>> un Scope) t
-  name <- DTS.mkTsName n
-  in [ DTS.TsDeclTypeDef name DTS.Public (coerce scope.floating) x ]
+  name <- mkName aliasName
+  in [ DTS.TsDeclTypeDef (toTsName name) DTS.Public (coerce scope.floating) x ]
   where
   t = tsBridgeBy tok x
 
@@ -117,23 +121,26 @@ tsOpaqueType tok x = do
     _ -> pure []
 
 -- | Exports a single PureScript value to TypeScript. `tsValues` may be better choice. 
-tsValue :: forall tok a. TsBridgeBy tok a => tok -> TsNameDraft -> a -> TsBridgeM (Array DTS.TsDeclaration)
+tsValue :: forall tok a. TsBridgeBy tok a => tok -> String -> a -> TsBridgeM (Array DTS.TsDeclaration)
 tsValue tok n _ = tsValue' tok n (Proxy :: _ a)
 
-tsValue' :: forall tok a. TsBridgeBy tok a => tok -> TsNameDraft -> Proxy a -> TsBridgeM (Array DTS.TsDeclaration)
-tsValue' tok n _ = do
-  let t = tsBridgeBy tok (Proxy :: _ a)
-  x /\ scope <- listens (un TsBridgeAccum >>> _.scope >>> un Scope) t
+tsValue' :: forall tok a. TsBridgeBy tok a => tok -> String -> Proxy a -> TsBridgeM (Array DTS.TsDeclaration)
+tsValue' tok n _ =
+  mapErr (AtValue n)
+    do
+      let t = tsBridgeBy tok (Proxy :: _ a)
+      x /\ scope <- listens (un TsBridgeAccum >>> _.scope >>> un Scope) t
 
-  name <- DTS.mkTsName n
+      name <- mkName n
 
-  when (OSet.length scope.floating /= 0)
-    $ throwError
-    $ DTS.ErrUnquantifiedTypeVariables
-    $ (Set.fromFoldable :: Array _ -> _)
-    $ OSet.toUnfoldable scope.floating
+      when (OSet.length scope.floating /= 0)
+        ( throwError
+            $ ErrUnquantifiedTypeVariables
+            $ (Set.fromFoldable :: Array _ -> _)
+            $ OSet.toUnfoldable scope.floating
+        )
 
-  pure [ DTS.TsDeclValueDef name DTS.Public x ]
+      pure [ DTS.TsDeclValueDef (toTsName name) DTS.Public x ]
 
 --------------------------------------------------------------------------------
 -- class TsValues
@@ -169,4 +176,4 @@ instance
   tsValuesRL tok r _ = (<>) <$> head <*> tail
     where
     tail = tsValuesRL tok r (Proxy :: _ rl)
-    head = tsValue' tok (DTS.TsName $ reflectSymbol (Proxy :: _ sym)) (Proxy :: _ a)
+    head = tsValue' tok (reflectSymbol (Proxy :: _ sym)) (Proxy :: _ a)