Migrate to static templates (#30)

feat(schematic): prompts * remove filebuilder * update/improve scripts * dasherize all import paths * handle entity name input for camelcase and dasherize * update readme * rename collection description * rename schematic name to add * remove schematic-src * update test script * add np package * bump schematic versions * upgrade sandbox-app to latest packages * fix sandbox-app styles path for ng-test builder v7 * add v7 prompts * update readme for prompts * modify tests to skip prompts with inline options
briebug · Oct 23, 2018 · e50e3b0 · e50e3b0
1 parent af3bd45
commit e50e3b0
Show file tree

Hide file tree

Showing 83 changed files with 3,363 additions and 12,877 deletions.
diff --git a/README.md b/README.md
@@ -1,17 +1,50 @@
-# NgRx Entity Generator
+# NgRx Entity Schematic
 
-An Angular schematic for generating NgRx files.
+An Angular schematic for quickly scaffolding NgRx Entities with actions, effects, reducer, model, service, and passing specs.
 
-- [What it generates](#generated)
 - [How to use](#how-to-use)
-- [Schematic development](#development)
-- [Schematic architecture](#architecture)
+- [What it generates](#generated)
+- [Local development](#development)
+- [Schematic project architecture](#architecture)
+
+## How to Use <a name="how-to-use"></a>
+
+### Install the necessary NgRx Entity libraries in your project
+
+    yarn add @ngrx/{effects,entity,router-store,store,store-devtools} ngrx-store-freeze
+
+### Run the schematic
+
+    ng add @briebug/ngrx-entity-schematic
+
+This will add the schematic as a project dependency if not already and provide prompts for configuration.
+
+#### Entity name
+
+The `ENTITY` name provided should either be camel case or dasherized (`customerOrder` || `customer-order`)
+
+### Optional - run the schematic with inline options
+
+    ng add @briebug/ngrx-entity-schematic ENTITY
+
+#### Generate Entity files at a specific relative path: `--path`
+
+    ng add @briebug/ngrx-entity-schematic ENTITY --path PATH/TO/WRITE
+
+#### Generate Entity files with NgRx setup files: `--init`
+
+    ng add @briebug/ngrx-entity-schematic ENTITY --init --path PATH/TO/WRITE
+
+- `ENTITY`, `--path`, and `--init` flags can be used together.
+- `ENTITY` is **required** as the first argument after the schematic name
 
 ## What it generates <a name="generated"></a>
 
-This schematic creates a basic implementation of NgRx files in your project. For example, if you run the schematic for the entity "customer", the schematic will generate a `state` folder (if it doesn't already exist), and you'll end up with the following:
+This schematic accepts an entity name and scaffolds all the necessary files for utilizing the NgRx Entity Library. For example, if you run the schematic for the entity `customer`, you'll end up with the following:
 
-```
+    ng add @briebug/ngrx-entity-schematic customer --path app/state
+
+```text
 app/
 ├── state/
 │   └── customer
@@ -24,159 +57,109 @@ app/
 │       ├── customer.service.ts
 │       ├── index.ts
 ```
-with the --init option you also get:
-```
+
+the `--init` option provides 4 additional files
+
+    ng add @briebug/ngrx-entity-schematic customer --init --path app/state
+
+```text
 app/
 ├── state/
-│   ├── app.interfaces.ts
-│   ├── app.reducer.ts
-│   ├── state-utils.ts
-│   ├── state.module.ts
+│   └── customer
+│       ├── customer.actions.ts
+│       ├── customer.effects.spec.ts
+│       ├── customer.effects.ts
+│       ├── customer.model.ts
+│       ├── customer.reducer.spec.ts
+│       ├── customer.reducer.ts
+│       ├── customer.service.ts
+│       ├── index.ts
+│   ├── app.interfaces.ts          *
+│   ├── app.reducer.ts             *
+│   ├── state-utils.ts             *
+│   ├── state.module.ts            *
 ```
 
-Continuing the example of "customer", the following are included:
+Continuing the example of `customer`, the following are included:
 
 | action | effect | reducer |
 | ------ | ------ | ------- |
-| InsertCustomer | ✔ | ✔ |
-| InsertCustomerSuccess |  | ✔ |
-| InsertCustomerFail | | ✔ |
-| SearchAllCustomerEntities | ✔ |  ✔ |
-| SearchAllCustomerEntitiesSuccess | | ✔ |
-| SearchAllCustomerEntitiesFail |  | ✔ |
-| LoadCustomerById | ✔ | ✔ |
-| LoadCustomerByIdSuccess | | ✔ |
-| LoadCustomerByIdFail |  | ✔ |
-| UpdateCustomer | ✔ | ✔ |
-| UpdateCustomerSuccess |  | ✔ |
-| UpdateCustomerFail |  | ✔ |
-| DeleteCustomerById | ✔ | ✔ |
-| DeleteCustomerByIdSuccess |  | ✔ |
-| DeleteCustomerByIdFail |  | ✔ |
-| SetSearchQuery | ✔ | ✔ |
-| SelectCustomerById | ✔ | ✔ |
+| `InsertCustomer` | ✅ | ✅ |
+| `InsertCustomerSuccess` |  | ✅ |
+| `InsertCustomerFail` | | ✅ |
+| `SearchAllCustomerEntities` | ✅ |  ✅ |
+| `SearchAllCustomerEntitiesSuccess` | | ✅ |
+| `SearchAllCustomerEntitiesFail` |  | ✅ |
+| `LoadCustomerById` | ✅ | ✅ |
+| `LoadCustomerByIdSuccess` | | ✅ |
+| `LoadCustomerByIdFail` |  | ✅ |
+| `UpdateCustomer` | ✅ | ✅ |
+| `UpdateCustomerSuccess` |  | ✅ |
+| `UpdateCustomerFail` |  | ✅ |
+| `DeleteCustomerById` | ✅ | ✅ |
+| `DeleteCustomerByIdSuccess` |  | ✅ |
+| `DeleteCustomerByIdFail` |  | ✅ |
+| `SetSearchQuery` | ✅ | ✅ |
+| `SelectCustomerById` | ✅ | ✅ |
 
 ### Other files:
 
-- `index.ts` exports all the selectors. 
-- `customer.service.ts` is a client for your api - it works with the sandbox app, but you will likely replace this with your own service. Just be aware that the effects expect the methods in this file.
-- `customer.model.ts` - you can safely replace this but the generated spec files use methods in this file to generate mocks.
-
-Be sure to go through the files to remove what you don't need and tailor them to your project.
-
-## How to Use <a name="how-to-use"></a>
-
-### Install the schematic globally
-
-```shell
-yarn global add @briebug/ngrx-entity-schematic
-```
-
-### Install NgRx in your project
+- `index.ts` exports all the selectors.
+- `customer.service.ts` is a provider for your entities - you will need to modify this service to make CRUD calls for your entity. Be aware that the effects expect the methods in this file.
+- `customer.model.ts` - you can safely replace this but the generated spec files uses exported methods to generate mocks.
 
-```shell
-yarn add @ngrx/{effects,entity,router-store,store,store-devtools} ngrx-store-freeze
-```
-
-### Run schematic
+*Be sure to audit the files and tailor them to your project*
 
-Generate Entity files, where `ENTITY_NAME` is an all-lowercase string name for your entity.
+## Install and use globally
 
-```shell
-ng g @briebug/ngrx-entity-schematic:ngrx-entity-schematic ENTITY_NAME
-```
+Optionally, you can install the package globally
 
-Generate Entity files at a specific relative path. Without the path option, a `state` folder is created in the root of the `app` folder.
+    yarn global add @briebug/ngrx-entity-schematic
 
-```shell
-ng g @briebug/ngrx-entity-schematic:ngrx-entity-schematic ENTITY_NAME --path RELATIVE/PATH
-```
+Then run the schematic in any project, assuming the angular/cli is installed and available.
 
-Generate Entity files with NgRx setup files
+    ng g @briebug/ngrx-entity-schematic:add
 
-```shell
-ng g @briebug/ngrx-entity-schematic:ngrx-entity-schematic ENTITY_NAME --init
-```
+## Local Development
 
-- `ENTITY_NAME`, `--path`, and `--init` flags can be used together.
-- `ENTITY_NAME` is **required** as the first argument after the schematic name
+### Link the schematic to the `sandbox-app`
 
-## Schematic development <a name="development"></a>
+This will create a symlink in your global packages so that when this schematic package is requested in the sandbox-app, it executes this local directory.
 
-Link the schematic to the `sandbox-app`, then build
+Effectively executing the `./src/ngrx-entity/index.ts` every time the schematic is run inside the `./sandbox-app`.
 
-```shell
-yarn link:schematic
-yarn build:schematic
-```
+    yarn link:schematic
 
 ### Run schematic locally
 
-You can run or re-run schematic against `sandbox-app` and pass options
+The most robust way to test schematic changes against the sandbox-app is to reset the sandbox to its version-controlled state, build the schematic code, and execute the schematic against the sandbox-app. Make changes and repeat.
 
-```shell
-yarn launch ENTITY_NAME --init
-```
+    yarn clean:build:launch
 
-Reset the `sandbox-app` to it's version controlled state, then execute the schematic locally against the `sandbox-app`.
+You can pass optionally pass arguments to this command
 
-```shell
-yarn clean:launch ENTITY_NAME
-```
+    yarn clean:build:launch customerOrders --init --path src/app/state
 
-Compile the schematic code if changes have been made to `./src/*`
+There are more specific commands that allow for individually running the above workflow. Those scripts can be found in the `./package.json`.
 
-```shell
-yarn build:schematic
-```
-
-### Copy `schematic-src` files into schematic template files
-
-Read the blueprint app, `/schematic-src`, and copy all the necessary files into the schematic folder, `/src/__files__`. During the copy, replace all "entity" placeholders with their respective template placeholder. Run this if changes to the `schematic-src` app have been made.
-
-```shell
-yarn build:run:fileBuilder
-```
-
-#### Entity string mapping
+### Test the schematic prompts
 
-| Entity | Template variable | Before | After |
-| ------ | ----------------- |--|--|
-|Briebug|`<%= classify(name) %>` |`class InsertBriebug`|`class Insert<%= classify(name) %>` |
-|briebug|`<%= name %>` |`import {} from './briebug.model'`|`import {} from './<%= name %>.model'`|
+run the launch command with any inline options
 
-#### About
+    yarn launch
 
-This schematic uses a template project that acts as the working blueprint for what the schematic will eventually generate. This pattern was chosen to provide a faster and easier development cycle when testing the blueprint app as a standalone application providing the typical dev feedback by the Angular  CLI and other devtools. The alternative would involve developing against the template files (which include template variables like `<%= classify(name) %>`) and having to run the schematic locally on every change.
+### Test commands
 
-### Developing the `buildFiles` script
+The test command expects and entity name of `briebug` to test how the schematic runs inside the sandbox-app. Changing this script should require changes to the sandbox-app and understanding of the consequences.
 
-This script copies and modifies the blueprint Entity files into the schematic `__files__` directory. The following commands allow for quick dev feedback and debugging.
+    "test:ci": "yarn clean:build:launch briebug --init && yarn test:sandbox && yarn clean"
 
-Compile the `buildFiles` script into `/tmp` in one shell
-
-```shell
-build:fileBuilder
-```
-
-In another shell, run the following script which will watch the `/tmp` dir for changes. Allows for attaching a debugger on port `9222`. See the attached `.vscode/launch.json` file for debugging with VSCode. Run the `Attach Schematic` debugger.
-
-```shell
-run:fileBuilder
-```
-
-Once both of these are run, changes to `./buildFiles.ts` should recompile and trigger an update to nodemon. Then trigger the VSCode debugger `f5` and that will land a breakpoint on line:1 of the app. Step over that to get to your breakpoint.
-
-## Schematic architecture <a name="architecture"></a>
+## Schematic Project Architecture <a name="architecture"></a>
 
 ### ./src
 
-This is the schematic code that's executed when running `ng g @briebug/ngrx-entity-schematic:ngrx-entity-schematic`.
-
-### ./schematic-src
-
-This is the blueprint app used for generating the schematic, specifically the template files in `./src/ngrx-entity/__files__`. This is a working application that defines the final form of the schematic.
+This is the schematic code that's executed when running `ng add @briebug/ngrx-entity-schematic`.
 
 ### ./sandbox-app
 
-This is an application that's used for testing the schematic locally during development.
+This is an application that's used for testing the schematic locally during development. This provides E2E like feedback.
diff --git a/buildFiles.ts b/buildFiles.ts