Merge pull request #69 from oracle/release_1.2.0

chore(release): v1.2.0, README.md documentation updated

Author: dbtools-antcampo

README.md

@@ -4,239 +4,132 @@
 
 - [Overview](#overview)
 - [Prerequisites](#prerequisites)
+- [Installation](#installation)
 - [Getting Started](#getting-started)
-    - [Examples](#examples)
-        - [Create a React Database App](#create-a-react-database-app)
-        - [Create a Todo Database App](#create-a-todo-database-app)
+- [Templates](#templates)
+- [Options](#options)
+- [Examples](#examples)
+  - [Usage](#usage)
+  - [Simple React app](#simple-react-app)
+  - [React todo app](#react-todo-app)
+  - [Application without interactive prompts](#application-without-interactive-prompts)
 - [Contributing](#contributing)
 - [Security](#security)
 - [License](#license)
 
 ## Overview
-<!-- toc -->
-* [Database Create App](#database-create-app)
-<!-- tocstop -->
 
-<!-- installation -->
-## Installation
-
-1. Install the package globally using npm
-
-```properties
-npm install -g @dbtools/create-database-app
-```
-
-## Project Name:
-
-2. Enter a desired name for your application
-
-```properties
-? What would you like your application's name to be?
-```
-
-## Template Selection:
-
-1. Select node-vanilla
-
-```properties
-? Which template would you like to use for your project? (Use arrow keys)
-> node-vanilla
-> node-react
-> node-vue
-> node-react-todo
-```
-## Database Connection Type:
-
-1. Select the preferred database connection method
-
-```properties
-? Which database connection type would you like to choose? (Use arrow keys)
-> Cloud Wallet Path
-> Basic Connection (Protocol, Hostname, Port, Service Name / SID)
-```
+Create an Oracle Database Application from a template.
 
-## Basic Connection Configuration:
+NOTE: The applications generated by this package should not be deployed using privileged database accounts. In turn, Oracle recommends for them to be deployed using the least privileged account possible.
 
-1. Provide database connection details when promted by the terminal
+## Prerequisites
 
-- Protocol: (defaults to TCP)
-```properties
-? What is your database protocol? (TCP)
-```
+- An Oracle Database, either on-prem or an [Autonomous Database](https://www.oracle.com/autonomous-database/) instance
+- Node.js 18 (Recommendation is to use nvm)
 
-- Hostname: (defaults to localhost)
-```properties
-? What is your database protocol? (TCP)
-```
+## Installation
 
-- Protocol: (defaults to TCP)
-```properties
-? What is your database port? (1521)
-```
+Install the package globally using npm
 
-- Service Type:
-```properties
-? Which service type would you like to use? (Use arrow keys)
-> SID
-> Service name
+```sh
+npm install -g @oracle/create-database-app
 ```
 
-- SID:
-```properties
-? Please input your database SID:
-```
+## Getting Started
 
-- Service Name:
-```properties
-? Please input your database service name:
-```
+The main application usage is through the @oracle/create-database-app NPM package, which will scaffold an application that will be connected to your Oracle Database.
 
-- Database Username
-```properties
-? What's your database username?
+```sh
+npm create @oracle/database-app
 ```
+This will temporarily install the package in your computer and prompt you for details like the name of the application, the template, and the database connection, from which it will create a git folder named as the given application name in your current directory, and install its dependencies.
 
-- Database Password
-```properties
-? What's your database password?
-```
+Next, you will be able to open the project in your favorite IDE or Code Editor and read the provided documentation to get started creating a database application using your favorite framework. We ship configuration files with recommended settings and extensions for Visual Studio Code.
 
-# Database Environment
-Within this .env file, you'll find details regarding the connection to the database used in the application.
+## Templates
 
-```properties
-# Database User
-DB_USER= username
-# Database User
-DB_PASSWORD= password
-# Connection string to your ADB instance
-CONNECT_STRING= connection_string
-```
+The package offers the following templates, which connect to the database using the [oracledb database driver](https://github.com/oracle/node-oracledb):
 
-# Cloud Wallet Path (if selected)
-If you selected the option of Cloud Wallet path yo will need
-to establish an Oracle Wallet, you'll require the Oracle Public Key Infrastructure (PKI) command line tool, known as orapki.
+- `node-vanilla`: A starter template that uses Node.js, vanilla JavaScript, HTML and CSS. It is built by [vite](https://vitejs.dev/).
+- `node-jet`: A starter template that uses Node.js and [Oracle JET](https://www.oracle.com/webfolder/technetwork/jet/index.html). It is built using the [ojet-cli](https://www.npmjs.com/package/@oracle/ojet-cli).
+- `node-react`: A starter template that uses Node.js and [React](https://react.dev/). It is built by [vite](https://vitejs.dev/).
+- `node-vue`: A starter template that uses Node.js and [Vue.js](https://vuejs.org/). It is built by [vite](https://vitejs.dev/).
+- `node-angular`: A starter template that uses Node.js and [Angular](https://angular.dev/). It is built by [Angular CLI](https://github.com/angular/angular-cli). (New in `v1.2.0`)
+- `node-react-todo`: A simple task manager template that uses Node.js and [React](https://react.dev/). It demonstrates the use of the database for Create, Read, Update and Delete (CRUD) operations. It is built by [vite](https://vitejs.dev/).
 
-```properties
-WALLETPATH <Domain Root>/<Domain Name>/config/fmwconfig/essconfig/essbase/walletssl
-```
+Each of the templates include documentation for you to get started with them, as well as NPM scripts for you to use right after generating the application.
 
-Next you will then provide the path of your Cloud Wallet
-```properties
-? Please input your Cloud Wallet Path:
-```
+## Options
 
-# Cloud Wallet Environment
-Within this configuration file, you'll find details regarding the connection to the cloud Wallet used in the application.
+You can provide the following options directly to the command:
 
-```properties
-# Oracle Wallet Password (If using a cloud wallet)
-WALLET_PASSWORD= password
-# Path to your Oracle Wallet directory (If using a cloud wallet)
-WALLET_LOCATION= <Domain Root>/<Domain Name>/config/fmwconfig/essconfig/essbase/walletssl
-```
-<!-- installationstop -->
-
-## Usage
-<!-- usage -->
-```sh-session
-$ npm install -g @dbtools/create-database-app
-$ create-database-app COMMAND
-running command...
-$ create-database-app (--version)
-@dbtools/create-database-app/1.1.3 darwin-arm64 node-v18.18.2
-$ create-database-app --help [COMMAND]
-USAGE
-  $ create-database-app COMMAND
+- `template`: Name of the template to use ([See options above](#templates))
+- `connection-type`: Options listed below:
+  - `basic`: Requires additional information like `db-protocol`, `db-hostname`, etc.
+  - `walletPath`: Requires a path to the wallet via the `wallet-path` flag.
+- `wallet-path`: Path to the zip file (or folder if uncompressed) containing the wallet and network configuration files.
+- `db-username`: Database username to connect. **Note**: For [Autonomous Databases](https://www.oracle.com/autonomous-database/) we do not recommend using the ADMIN user.
+- `db-protocol`: For details consult [Connecting to Oracle Database](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html).
+- `db-hostname`: For details consult [Connecting to Oracle Database](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html).
+- `db-port`: For details consult [Connecting to Oracle Database](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html).
+- `db-service-type`: Options listed below. For details consult [Connecting to Oracle Database](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html).
+  - `serviceName`
+  - `sid`
+- `db-service-name`: For details consult [Connecting to Oracle Database](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html).
+- `db-sid`: For details consult [Connecting to Oracle Database](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html).
+
+## Database Environment
+When an application is generated, you'll find a `.env` file with details regarding the connection to the database used in the application.
+
+```properties
+# Database user
+DB_USER=<my-username>
+# Database password
+DB_PASSWORD=<my-password>
 ...
 ```
-<!-- usagestop -->
-## Commands
-
-Create an Oracle Database Application from a template.
-
-NOTE: The applications generated by this package should not be deployed using
-privileged database accounts. In turn, Oracle recommends for them to be deployed
-using the least privileged account possible.
 
-## Prerequisites
-
-- An Oracle Database, either on-prem or an
-    [Autonomous Database](https://www.oracle.com/autonomous-database/) instance
-- Node.js 18 (Recommendation is to use [nvm](https://github.com/nvm-sh/nvm))
-
-## Getting Started
+## Examples
 
-The main application usage is through the `@oracle/create-database-app` NPM
-package, which will scaffold an application that will be connected to your
-Oracle Database.
+### Usage
 
+The simplest example on how to use the generator is via:
 ```sh
 npm create @oracle/database-app
 ```
+This opens an interactive prompt where information regarding the application and connection details can be provided.
 
-This will temporarily install the package in your computer and prompt
-you for details like the name of the application, the template, and the database
-connection, from which it will create a git folder named as the given
-application name in your current directory, and install its dependencies.
-
-Next, you will be able to open the project in your favorite IDE or Code Editor
-and read the provided documentation to get started creating a database
-application using your favorite framework. We ship configuration files with
-recommended settings and extensions for Visual Studio Code.
-
-The package offers the following templates, which connect to the database
-using the the [`oracledb` database driver](https://github.com/oracle/node-oracledb):
-
-- `node-vanilla`: A starter template that uses Node.js, vanilla JavaScript, HTML
-    and CSS. It is built by [`vite`](https://vitejs.dev/)
-- `node-jet`: A starter template that uses Node.js and
-    [Oracle JET](https://www.oracle.com/webfolder/technetwork/jet/index.html).
-    It is built using the `ojet-cli`
-- `node-react`: A starter template that uses Node.js and
-    [React](https://react.dev/). It is built by [`vite`](https://vitejs.dev/)
-- `node-vue`: A starter template that uses Node.js and
-    [Vue.js](https://vuejs.org/). It is built by [`vite`](https://vitejs.dev/)
-- `node-react-todo`: A simple task manager template that uses Node.js and
-    [React](https://react.dev/). It demonstrates the use of the database for
-    Create, Read, Update and Delete (CRUD) operations. It is built by
-    [`vite`](https://vitejs.dev/)
-
-Each of the templates include documentation for you to get started with them, as
-well as NPM scripts for you to use right after generating the application.
+### Simple React app
 
-You can provide the following options directly to the command:
-
-- `--name`: followed by the name of your application
-- `--template`: followed by the name of the template to use (See above)
-
-If none or only a few options are provided to the command, it will prompt for
-the missing details.
-
-### Examples
+```sh
+npm create @oracle/database-app -- "my-react-app" --template "node-react"
+```
 
-#### Create a React Database App
+### React todo app
 
-If you want to generate an application named `my-app` with the `node-react`
-template, you can execute:
+You can generate an example of a fully functional application. The example below creates an app named `my-todo` with the `node-react-todo` template.
 
 ```sh
-npm create @oracle/database-app -- \
-    --name 'my-app' \
-    --template 'node-react'
+npm create @oracle/database-app -- "my-todo" --template "node-react-todo"
 ```
 
-#### Create a Todo Database App
+### Application without interactive prompts
 
-If you want to generate an application named `my-todo` with the `node-todo`
-template, you can execute:
+Any combination of parameters defined via the interactive prompt can be defined using a flag as part of the command.*
 
 ```sh
-npm create @oracle/database-app -- \
-    --name 'my-todo' \
-    --template 'node-react-todo'
+npm create @oracle/database-app -- "my-app" \
+    --template "node-react" \
+    --connection-type "walletPath" \
+    --db-username "<my-db-user>" \
+    --wallet-path "<path>.zip"
 ```
 
+The example above shows how to connect to an [Autonomous Database](https://www.oracle.com/autonomous-database/) using a wallet.
+
+Note: passwords still need to be provided using the prompt.
+
 ## Contributing
 
 This project welcomes contributions from the community. Before submitting a pull

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@oracle/create-database-app",
-  "version": "1.1.11",
+  "version": "1.2.0",
   "description": "Create an Oracle Database Application from a Template",
   "author": "Oracle Corporation",
   "keywords": [