From ed500c612e88daaa60ae212677a5c86d873a4b29 Mon Sep 17 00:00:00 2001 From: Kononnable Date: Mon, 9 Sep 2019 21:36:22 +0200 Subject: [PATCH 1/7] unfinished docs --- .env.dist | 44 ++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.MD | 52 ++++++++++++++++++++++++++++++++++++++++++++++++ DEVELOPER.MD | 30 ++++++++++++++++++++++++++++ USECASES.MD | 53 +++++++++++++++++++++++++++++++++++++++++++++++++ package.json | 2 +- tsconfig.json | 2 +- 6 files changed, 181 insertions(+), 2 deletions(-) create mode 100644 .env.dist create mode 100644 CONTRIBUTING.MD create mode 100644 DEVELOPER.MD create mode 100644 USECASES.MD diff --git a/.env.dist b/.env.dist new file mode 100644 index 0000000..ba50d93 --- /dev/null +++ b/.env.dist @@ -0,0 +1,44 @@ +MSSQL_Skip=0 +MSSQL_Host=localhost +MSSQL_Port=1433 +MSSQL_Username=sa +MSSQL_Password=Admin12345 +MSSQL_Database=typeorm_mg +MSSQL_SSL=0 + +POSTGRES_Skip=0 +POSTGRES_Host=localhost +POSTGRES_Port=5432 +POSTGRES_Username=test +POSTGRES_Password=test +POSTGRES_Database=test +POSTGRES_SSL=0 + +MYSQL_Skip=0 +MYSQL_Host=localhost +MYSQL_Port=3306 +MYSQL_Username=root +MYSQL_Password=admin +MYSQL_Database=test +MYSQL_SSL=0 + +MARIADB_Skip=0 +MARIADB_Host=localhost +MARIADB_Port=3307 +MARIADB_Username=root +MARIADB_Password=admin +MARIADB_Database=test +MARIADB_SSL=0 + +ORACLE_Skip=0 +ORACLE_Host=localhost +ORACLE_Port=1521 +ORACLE_SSL=0 +ORACLE_UsernameSys=sys +ORACLE_PasswordSys=Oradoc_db1 +ORACLE_Database=orclpdb1.localdomain +ORACLE_Username=typeorm_mg +ORACLE_Password=Passw0rd + +SQLITE_Skip=0 +SQLITE_Database=./sqlitedb.db diff --git a/CONTRIBUTING.MD b/CONTRIBUTING.MD new file mode 100644 index 0000000..14ed5ac --- /dev/null +++ b/CONTRIBUTING.MD @@ -0,0 +1,52 @@ +# Contributing to typeorm-model-generator + + + - [Question or Problem?](#question) + - [Submission Guidelines](#submit) + - [Commit Message Format](#commit) + + + +## Got a Question or Problem? +* You can create issue on [github](https://github.com/Kononnable/typeorm-model-generator/issues) +* While this tool doesn't have separate separate chat you can use [typeorm slack workspace](https://join.slack.com/t/typeorm/shared_invite/enQtNDQ1MzA3MDA5MTExLTFiNDEyOGUxZGQyYWIwOTA0NDQxODdkOGQ0OTUxNzFjYjUwY2E0ZmFlODc5OTYyYzAzNGM3MGZjYzhjYTBiZTY) since everyone using this tool will also use typeorm. + + + +## Submission Guidelines + +### Submitting an Issue + +Before you submitting new issue, please check the issue tracker, maybe your problem is already described and the discussion might inform you of available workarounds. + +Before fixing a bug we need to reproduce and confirm it. In order to reproduce bugs, we will ask you to provide a minimal reproduction. Having a minimal reproducible scenario gives us a wealth of important information without going back & forth to you with additional questions. A minimal reproduction allows us to quickly confirm a bug (or point out a coding problem) as well as confirm that we are fixing the right problem. + +### Submitting a Pull Request (PR) +Before you submit your Pull Request (PR) consider the following guidelines: + +1. Search [GitHub](https://github.com/Kononnable/typeorm-model-generator/pulls) for an open or closed PR that relates to your submission. You don't want to duplicate effort. +1. Make your changes in a new git branch: + + ```shell + git checkout -b my-fix-branch master + ``` + +1. Create your patch. +1. Run test suite and ensure that all tests pass. +1. Commit your changes using a descriptive commit message. + +1. Push your branch to GitHub: + + ```shell + git push origin my-fix-branch + ``` + +1. In GitHub, send a pull request to `typeorm-model-generator:master`. +* If we suggest changes then: + * Make the required updates. + * Re-run test suites to ensure tests are still passing. + * Push to your GitHub repository (this will update your Pull Request) + +Note: if you don't want to run tests on your own for some reason you can rely on tests run on CI. + +That's it! Thank you for your contribution! diff --git a/DEVELOPER.MD b/DEVELOPER.MD new file mode 100644 index 0000000..cfd8243 --- /dev/null +++ b/DEVELOPER.MD @@ -0,0 +1,30 @@ +# Setting up environment +## Building +After cloning the repository you can check your changes made to source code without compiling whole library. Just run `npm start` to run this tool through ts-node. It helps with development speed and avoids problem with setting correct sourcemaps when debugging. + +However if you want to build typeorm-model-generator you can do this by running +``` +npm run build +``` +this might come handy if you want to build full pipeline workflow with typeorm-model-generator and install it through `npm link`. +## Running Tests Locally +To run tests you need to have docker and docker-compose installed. You may also use non-dockerized database servers but it's not recommended - they might use non-default settings. +### Oracle Database +If you want to run oracle tests locally you must have *oracle client* configured for your machine and accepted oracle license on *DockerHub*. Because of oracle client limitations i.e. it's not distributed for 32bit environments you have to install oracledb manually +``` +npm install oracledb --no-save +``` +### Configuration +Tests use environment values to connect to multiple database engines. For developer convenience there is already prepared env file with default connection settings for connecting to dockerized db engines. This is also the place you can disable testing on specific db engine. You just need to rename the env file +``` +cp .env.dit .env +``` +### Database engines +Next you have to start db engines. If you want to test all of the drivers and have configured oracle correctly you can just +``` +docker-compose up -d +``` +You can also start just specific database engines e.g. +``` +docker-compose up -d mysql postgres mariadb +``` diff --git a/USECASES.MD b/USECASES.MD new file mode 100644 index 0000000..34ccea0 --- /dev/null +++ b/USECASES.MD @@ -0,0 +1,53 @@ +# Common use cases +Typeorm-model-generator can be used in multiple ways. Here are some workflows you can use. +## Use directly from npm +You can use typeorm-model-generator directly from npm +``` +npx typeorm-model-generator +``` +Please remember using `npx typeorm-model-generator` will download latest available version. To avoid it you can specify version each time `npx typeorm-model-generator@0.3.0` or install a package locally - npx will use locally installed version then. +### command line parameters +You can customize generated output by specifying multiple parameters. Full list of parameters are available through `npx typeorm-model-generator --help` +### config file +If you execute `npx typeorm-model-generator` without specifying any parameters you will enter a wizard mode which will guide you through specifying connection settings and allow to customize generated model. At the end of this process you can save your choices, so the process will run automatically next time. +## clone repo and make manual changes +If you need more power over how models are generated you can fork the repo and make changes to the code specific to your use case there. +- fork the repo +- clone forked repo locally +- create branch for your changes +``` +git checkout -b my-branch master +``` +- add remote repository +``` +git remote add upstream https://github.com/Kononnable/typeorm-model-generator.git +``` +You can run model generation tool by running `npm run start` after installing dependencies. + +When you want to download changes made on main typeorm-model-generator repo just +- checkout `master` branch +- download changes from main repository +``` +git pull --ff upstream master +``` +- checkout branch with your changes +``` +git checkout my-branch +``` +- merge changes onto your branch +``` +git merge master +``` + +## git repo with dependency and entire pipeline +Similar to last workflow, but this time we don't have to worry about manually merging changes from main repository. +- Init new package +``` +npm init -y +``` +- Install typeorm-model-generator as a dependency +``` +npm install typeorm-model-generator +``` +- Write code which loads generated entities files and change its content +- Run typeorm-model-generator, then your code which customizes it(you may add this to `package.json` scripts section) diff --git a/package.json b/package.json index 69278d3..52324d8 100644 --- a/package.json +++ b/package.json @@ -5,7 +5,7 @@ "bin": "bin/typeorm-model-generator", "scripts": { "start": "ts-node ./src/index.ts", - "build": "tsc && ncp src/entity.mst dist/src/entity.mst", + "build": "npm run clean && tsc && ncp src/entity.mst dist/src/entity.mst", "prepare": "npm run build", "pretest": "tsc --noEmit", "test": "nyc --reporter=lcov ts-node ./node_modules/mocha/bin/_mocha test/**/*.test.ts -- -R spec --bail", diff --git a/tsconfig.json b/tsconfig.json index bcc555a..7172bbc 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -1,4 +1,4 @@ -{ +Watc{ "compilerOptions": { "module": "commonjs", "target": "es6", From 8fdac8153914ffaa1a07b3c94bc634607714bd7f Mon Sep 17 00:00:00 2001 From: Kononnable Date: Mon, 9 Sep 2019 22:16:28 +0200 Subject: [PATCH 2/7] fix typo --- tsconfig.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tsconfig.json b/tsconfig.json index 7172bbc..bcc555a 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -1,4 +1,4 @@ -Watc{ +{ "compilerOptions": { "module": "commonjs", "target": "es6", From e58a448788cee87410542c8fd6e6383d50082599 Mon Sep 17 00:00:00 2001 From: Kononnable Date: Sun, 15 Sep 2019 23:44:55 +0200 Subject: [PATCH 3/7] docs changes --- CONTRIBUTING.MD | 6 +++--- DEVELOPER.MD | 18 +++++++++--------- USECASES.MD | 28 ++++++++++++++-------------- 3 files changed, 26 insertions(+), 26 deletions(-) diff --git a/CONTRIBUTING.MD b/CONTRIBUTING.MD index 14ed5ac..45fc965 100644 --- a/CONTRIBUTING.MD +++ b/CONTRIBUTING.MD @@ -9,7 +9,7 @@ ## Got a Question or Problem? * You can create issue on [github](https://github.com/Kononnable/typeorm-model-generator/issues) -* While this tool doesn't have separate separate chat you can use [typeorm slack workspace](https://join.slack.com/t/typeorm/shared_invite/enQtNDQ1MzA3MDA5MTExLTFiNDEyOGUxZGQyYWIwOTA0NDQxODdkOGQ0OTUxNzFjYjUwY2E0ZmFlODc5OTYyYzAzNGM3MGZjYzhjYTBiZTY) since everyone using this tool will also use typeorm. +* While this tool doesn't have separate separate chat room you can use [typeorm slack workspace](https://join.slack.com/t/typeorm/shared_invite/enQtNDQ1MzA3MDA5MTExLTFiNDEyOGUxZGQyYWIwOTA0NDQxODdkOGQ0OTUxNzFjYjUwY2E0ZmFlODc5OTYyYzAzNGM3MGZjYzhjYTBiZTY) since everyone using typeorm-model-generator will also use typeorm. @@ -17,7 +17,7 @@ ### Submitting an Issue -Before you submitting new issue, please check the issue tracker, maybe your problem is already described and the discussion might inform you of available workarounds. +Before submitting new issue, please check the issue tracker, maybe your problem is already described and the discussion might inform you of available workarounds. Before fixing a bug we need to reproduce and confirm it. In order to reproduce bugs, we will ask you to provide a minimal reproduction. Having a minimal reproducible scenario gives us a wealth of important information without going back & forth to you with additional questions. A minimal reproduction allows us to quickly confirm a bug (or point out a coding problem) as well as confirm that we are fixing the right problem. @@ -47,6 +47,6 @@ Before you submit your Pull Request (PR) consider the following guidelines: * Re-run test suites to ensure tests are still passing. * Push to your GitHub repository (this will update your Pull Request) -Note: if you don't want to run tests on your own for some reason you can rely on tests run on CI. +Note: if you don't want to run tests on your machine you can rely on tests run on CI(unless you're changing something oracledb specific). That's it! Thank you for your contribution! diff --git a/DEVELOPER.MD b/DEVELOPER.MD index cfd8243..090b173 100644 --- a/DEVELOPER.MD +++ b/DEVELOPER.MD @@ -1,30 +1,30 @@ # Setting up environment ## Building -After cloning the repository you can check your changes made to source code without compiling whole library. Just run `npm start` to run this tool through ts-node. It helps with development speed and avoids problem with setting correct sourcemaps when debugging. +After cloning the repository you can check your changes made to source code without compiling whole library. Just run `npm start` to run typeorm-model-generator through ts-node. It helps with development speed and avoids problem with setting correct sourcemaps when debugging. -However if you want to build typeorm-model-generator you can do this by running +However if you want to build typeorm-model-generator you can do this by running: ``` npm run build ``` -this might come handy if you want to build full pipeline workflow with typeorm-model-generator and install it through `npm link`. +It might come handy if you want to build full pipeline workflow with model generator and install it through `npm link`. ## Running Tests Locally -To run tests you need to have docker and docker-compose installed. You may also use non-dockerized database servers but it's not recommended - they might use non-default settings. +To run tests you need to have docker and docker-compose installed. You may also use non-dockerized database servers but it's not recommended - they might use non-default database engine settings. ### Oracle Database -If you want to run oracle tests locally you must have *oracle client* configured for your machine and accepted oracle license on *DockerHub*. Because of oracle client limitations i.e. it's not distributed for 32bit environments you have to install oracledb manually +If you want to run oracle tests locally you must have [oracle client](https://oracle.github.io/node-oracledb/INSTALL.html#quickstart) configured for your machine and accepted oracle license on [DockerHub](https://hub.docker.com/_/oracle-database-enterprise-edition). Because of oracle client limitations i.e. it's not distributed for 32bit environments you have to install oracledb manually: ``` npm install oracledb --no-save ``` ### Configuration -Tests use environment values to connect to multiple database engines. For developer convenience there is already prepared env file with default connection settings for connecting to dockerized db engines. This is also the place you can disable testing on specific db engine. You just need to rename the env file +Tests use environment values to provide credentials for connecting to multiple database engines. For developer convenience there is prepared env file with default connection settings(for connecting to dockerized db engines). After cloning the repo you just need to rename the env file: ``` -cp .env.dit .env +cp .env.dist .env ``` ### Database engines -Next you have to start db engines. If you want to test all of the drivers and have configured oracle correctly you can just +Next you have to start db engines. If you want to test all of the drivers and have configured oracle correctly you can just: ``` docker-compose up -d ``` -You can also start just specific database engines e.g. +You can also start just specific database engines e.g.: ``` docker-compose up -d mysql postgres mariadb ``` diff --git a/USECASES.MD b/USECASES.MD index 34ccea0..2af9621 100644 --- a/USECASES.MD +++ b/USECASES.MD @@ -1,24 +1,24 @@ # Common use cases -Typeorm-model-generator can be used in multiple ways. Here are some workflows you can use. +Typeorm-model-generator can be used in multiple workflows. Here are described few recommended ones. ## Use directly from npm -You can use typeorm-model-generator directly from npm +You can use typeorm-model-generator directly from npm: ``` npx typeorm-model-generator ``` -Please remember using `npx typeorm-model-generator` will download latest available version. To avoid it you can specify version each time `npx typeorm-model-generator@0.3.0` or install a package locally - npx will use locally installed version then. +Please remember that by using `npx typeorm-model-generator` you will download latest available version. To avoid it you can specify version each time `npx typeorm-model-generator@0.3.0` or install a package locally - npx will use locally installed version then. ### command line parameters You can customize generated output by specifying multiple parameters. Full list of parameters are available through `npx typeorm-model-generator --help` ### config file -If you execute `npx typeorm-model-generator` without specifying any parameters you will enter a wizard mode which will guide you through specifying connection settings and allow to customize generated model. At the end of this process you can save your choices, so the process will run automatically next time. +If you execute `npx typeorm-model-generator` without specifying any parameters you will enter a wizard mode which will guide you through specifying connection settings and allow to customize generated models. At the end of this process you will be able to save your settings, so the process will run automatically next time. ## clone repo and make manual changes -If you need more power over how models are generated you can fork the repo and make changes to the code specific to your use case there. +If you need more power over how models are generated you can fork the repo and make changes to the code which are specific to your use case. - fork the repo - clone forked repo locally -- create branch for your changes +- create branch for your changes: ``` git checkout -b my-branch master ``` -- add remote repository +- add remote repository: ``` git remote add upstream https://github.com/Kononnable/typeorm-model-generator.git ``` @@ -26,28 +26,28 @@ You can run model generation tool by running `npm run start` after installing de When you want to download changes made on main typeorm-model-generator repo just - checkout `master` branch -- download changes from main repository +- download changes from main repository: ``` git pull --ff upstream master ``` -- checkout branch with your changes +- checkout branch with your changes: ``` git checkout my-branch ``` -- merge changes onto your branch +- merge changes onto your branch: ``` git merge master ``` ## git repo with dependency and entire pipeline Similar to last workflow, but this time we don't have to worry about manually merging changes from main repository. -- Init new package +- Init new package: ``` npm init -y ``` -- Install typeorm-model-generator as a dependency +- Install typeorm-model-generator as a dependency: ``` npm install typeorm-model-generator ``` -- Write code which loads generated entities files and change its content -- Run typeorm-model-generator, then your code which customizes it(you may add this to `package.json` scripts section) +- Write code which loads generated entity files and change its content +- Run typeorm-model-generator, then your code which customizes it (you may add this step to `package.json` scripts section) From 8f17bd96c60f07ba90f43e3a8efa30e340a4f66d Mon Sep 17 00:00:00 2001 From: Kononnable Date: Mon, 16 Sep 2019 11:36:17 +0200 Subject: [PATCH 4/7] Update CONTRIBUTING.MD --- CONTRIBUTING.MD | 1 - 1 file changed, 1 deletion(-) diff --git a/CONTRIBUTING.MD b/CONTRIBUTING.MD index 45fc965..16ae4e9 100644 --- a/CONTRIBUTING.MD +++ b/CONTRIBUTING.MD @@ -3,7 +3,6 @@ - [Question or Problem?](#question) - [Submission Guidelines](#submit) - - [Commit Message Format](#commit) From 061eca6c00faa119ef30f5afd87c79db0236e70a Mon Sep 17 00:00:00 2001 From: Kononnable Date: Mon, 16 Sep 2019 20:43:13 +0200 Subject: [PATCH 5/7] docs --- CONTRIBUTING.MD | 2 +- USECASES.MD | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.MD b/CONTRIBUTING.MD index 16ae4e9..ecd80ac 100644 --- a/CONTRIBUTING.MD +++ b/CONTRIBUTING.MD @@ -46,6 +46,6 @@ Before you submit your Pull Request (PR) consider the following guidelines: * Re-run test suites to ensure tests are still passing. * Push to your GitHub repository (this will update your Pull Request) -Note: if you don't want to run tests on your machine you can rely on tests run on CI(unless you're changing something oracledb specific). +Note: if you don't want to run tests on your machine you can rely on tests run on CI (unless you're changing something oracledb specific). That's it! Thank you for your contribution! diff --git a/USECASES.MD b/USECASES.MD index 2af9621..b01c7e4 100644 --- a/USECASES.MD +++ b/USECASES.MD @@ -40,7 +40,7 @@ git merge master ``` ## git repo with dependency and entire pipeline -Similar to last workflow, but this time we don't have to worry about manually merging changes from main repository. +Similar to previous workflow, but this time we don't have to worry about manually merging changes from main repository. - Init new package: ``` npm init -y From 66b00d11f47aa9a7f63588762573eb607ac5c93d Mon Sep 17 00:00:00 2001 From: Kononnable Date: Tue, 17 Sep 2019 20:54:28 +0200 Subject: [PATCH 6/7] readme link to use cases --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index f7eb48d..80bddc0 100644 --- a/README.md +++ b/README.md @@ -82,6 +82,8 @@ Options: ``` npx typeorm-model-generator -d "Z:\sqlite.db" -e sqlite -o . ```` +## Use Cases +Please take a look at [few workflows](USECASES.md) which might help you with deciding how you're gonna use typeorm-model-generator. ## Naming strategy If you want to generate custom names for properties in generated entities you need to use custom naming strategy. You need to create your own version of [NamingStrategy](https://github.com/Kononnable/typeorm-model-generator/blob/master/src/NamingStrategy.ts) and pass it as command parameter. From 8f7486cc28e63e5285f8663ec4fa62f5b2cccb61 Mon Sep 17 00:00:00 2001 From: Kononnable Date: Tue, 17 Sep 2019 21:02:02 +0200 Subject: [PATCH 7/7] file casing changes --- CONTRIBUTING.MD => CONTRIBUTING.md | 0 DEVELOPER.MD => DEVELOPER.md | 0 USECASES.MD => USECASES.md | 0 3 files changed, 0 insertions(+), 0 deletions(-) rename CONTRIBUTING.MD => CONTRIBUTING.md (100%) rename DEVELOPER.MD => DEVELOPER.md (100%) rename USECASES.MD => USECASES.md (100%) diff --git a/CONTRIBUTING.MD b/CONTRIBUTING.md similarity index 100% rename from CONTRIBUTING.MD rename to CONTRIBUTING.md diff --git a/DEVELOPER.MD b/DEVELOPER.md similarity index 100% rename from DEVELOPER.MD rename to DEVELOPER.md diff --git a/USECASES.MD b/USECASES.md similarity index 100% rename from USECASES.MD rename to USECASES.md