simple-scaffold 0.7.5 → 1.0.0-alpha.12

package/README.md

@@ -2,6 +2,16 @@
 
 Simple Scaffold allows you to create your structured files based on templates.
 
+Simply organize your commonly-created files in their original structure, and replace any variable
+values (such as component or app name) inside the paths or contents of the files with tokens to be
+populated upon scaffolding.
+
+Then, run Simple Scaffold and it will generate your files for you in the desired structure,
+with file names and contents that contain your dynamic information.
+
+It's a simple way to easily create reusable components, common class files to start writing from,
+or even entire app structures.
+
 ## Install
 
 You can either use it as a command line tool or import into your own code and run from there.
@@ -11,6 +21,8 @@ You can either use it as a command line tool or import into your own code and ru
 npm install [-g] simple-scaffold
 # yarn
 yarn [global] add simple-scaffold
+# run without installing
+npx simple-scaffold <...args>
 ```
 
 ## Use as a command line tool
@@ -18,62 +30,71 @@ yarn [global] add simple-scaffold
 ### Command Line Options
 
 ```plaintext
-Scaffold Generator
-
-  Generate scaffolds for your project based on file templates.
-  Usage: simple-scaffold scaffold-name [options]
-
-Options
-
-  -n, --name string                 Component output name                                                         
-  -t, --templates File[]            A glob pattern of template files to load.                                     
-                                    A template file may be of any type and extension, and supports Handlebars as  
-                                    a parsing engine for the file names and contents, so you may customize both   
-                                    with variables from your configuration.                                       
-  -o, --output File                 The output directory to put the new files in. They will attempt to maintain   
-                                    their regular structure as they are found, if possible.                       
-  -l, --locals JSON string          A JSON string for the template to use in parsing.                             
-  -w, --overwrite Boolean           Whether to overwrite files when they are found to already exist. Default=true 
-  -q, --quiet Boolean               When set to true, logs will not output (including warnings and errors).       
-                                    Default=false                                                                 
-  -S, --create-sub-folder Boolean   Whether to create a subdirectory with {{Name}} in the output directory.       
-                                    Default=true                                                                  
-  -h, --help                        Display this help message      
+Usage: simple-scaffold [options]
+
+Create structured files based on templates.
+
+Options:
+
+  --help|-h                 Display help information
+
+  --name|-n                 Name to be passed to the generated files. {{name}} and
+                            {{Name}} inside contents and file names will be replaced
+                            accordingly.
+
+  --output|-o               Path to output to. If --create-sub-folder is enabled, the
+                            subfolder will be created inside this path.
+
+  --templates|-t            Template files to use as input. You may provide multiple
+                            files, each of which can be a relative or absolute path, or a glob
+                            pattern for multiple file matching easily. (default:
+                            )
+
+  --overwrite|-w            Enable to override output files, even if they already exist.
+                            (default: false)
+
+  --data|-d                 Add custom data to the templates. By default, only your app
+                            name is included.
+
+  --create-sub-folder|-s    Create subfolder with the input name (default:
+                            false)
+
+  --quiet|-q                Suppress output logs (Same as --verbose 0)
+                            (default: false)
+
+  --verbose|-v              Determine amount of logs to display. The values are: 0
+                            (none) | 1 (debug) | 2 (info) | 3 (warn) | 4 (error). The
+                            provided level will display messages of the same level or higher.
+                            (default: 2)
+
+  --dry-run|-dr             Don't emit files. This is good for testing your scaffolds and
+                            making sure they don't fail, without having to write actual file
+                            contents or create directories. (default:
+                            false)
 ```
 
-You can add this as a script in your `package.json`:
+You can also add this as a script in your `package.json`:
 
 ```json
 {
+  ...
   "scripts": {
-    "scaffold": "yarn simple-scaffold --template scaffolds/component/**/* --output src/components --locals myProp=\"propname\",myVal=123"
+    ...
+    "scaffold": "yarn simple-scaffold --templates scaffolds/component/**/* --output src/components --data '{\"myProp\": \"propName\", \"myVal\": \"123\"}'"
   }
 }
 ```
 
-## Scaffolding
-
-Scaffolding will replace {{vars}} in both the file name and its contents and put the transformed files
-in `<output>/<{{Name}}>`, as per the Handlebars formatting rules.
-
-Your context will be pre-populated with the following:
-
-- `{{Name}}`: CapitalizedName of the component
-- `{{name}}`: camelCasedName of the component
-
-Any `locals` you add in the config will populate with their names wrapped in `{{` and `}}`.
-They are all stringified, so be sure to parse them accordingly by creating a script, if necessary.
-
-### Use in Node.js
+## Use in Node.js
 
 You can also build the scaffold yourself, if you want to create more complex arguments or scaffold groups.
 Simply pass a config object to the constructor, and invoke `run()` when you are ready to start.
 The config takes similar arguments to the command line:
 
-```javascript
-const SimpleScaffold = require("simple-scaffold").default
+```typescript
+import Scaffold from "simple-scaffold"
 
-const scaffold = new SimpleScaffold({
+const scaffold = SimpleScaffold({
   name: "component",
   templates: [path.join(__dirname, "scaffolds", "component")],
   output: path.join(__dirname, "src", "components"),
@@ -81,84 +102,159 @@ const scaffold = new SimpleScaffold({
   locals: {
     property: "value",
   },
-}).run()
+})
 ```
 
 The exception in the config is that `output`, when used in Node directly, may also be passed a
 function for each input file to output into a dynamic path:
 
-```javascript
+```typescript
 config.output = (fullPath, baseDir, baseName) => {
   console.log({ fullPath, baseDir, baseName })
-  return [baseDir, baseName].join(path.sep)
+  return path.resolve(baseDir, baseName)
 }
 ```
 
-## Example Scaffold Input
+## Preparing files
+
+### Template files
+
+Put your template files anywhere, and fill them with tokens for replacement.
+
+### Variable/token replacement
+
+Scaffolding will replace `{{ varName }}` in both the file name and its contents and put the
+transformed files in the output directory.
+
+The data available for the template parser is the data you pass to the `data` config option (or
+`--data` argument in CLI).
+
+Your `data` will be pre-populated with the following:
+
+- `{{Name}}`: PascalCase of the component name
+- `{{name}}`: raw name of the component
+
+> Simple-Scaffold uses [Handlebars.js](https://handlebarsjs.com/) for outputting the file contents,
+> see their documentation for more information on syntax.
+> Any `data` you add in the config will be available for use with their names wrapped in
+> `{{` and `}}`.
+
+#### Helpers
+
+Simple-Scaffold provides some built-in text transformation filters usable by handleBars.
 
-### Input directory structure
+For example, you may use `{{ snakeCase name }}` inside a template file or filename, and it will
+replace `My Name` with `my_name` when producing the final value.
+
+Here are the built-in helpers available for use:
+
+| Helper name | Example code            | Example output |
+| ----------- | ----------------------- | -------------- |
+| camelCase   | `{{ camelCase name }}`  | myName         |
+| snakeCase   | `{{ snakeCase name }}`  | my_name        |
+| startCase   | `{{ startCase name }}`  | My Name        |
+| kebabCase   | `{{ kebabCase name }}`  | my-name        |
+| hyphenCase  | `{{ hyphenCase name }}` | my-name        |
+| pascalCase  | `{{ pascalCase name }}` | MyName         |
+
+> These helpers are available for any data property, not exclusive to `name`.
+
+## Examples
+
+### Command Example
+
+```bash
+simple-scaffold MyComponent \
+    -t project/scaffold/**/* \
+    -o src/components \
+    -d '{"className": "myClassName"}'
+    MyComponent
+```
+
+### Example Scaffold Input
+
+#### Input Directory structure
 
 ```plaintext
 - project
-    - scaffold
-        - {{Name}}.js
-    - src
-        - components
-        - ...
+  - scaffold
+    - {{Name}}.js
+  - src
+    - components
+    - ...
 ```
 
-#### project/scaffold/{{Name}}.js
+#### Contents of `project/scaffold/{{Name}}.jsx`
 
 ```js
 const React = require('react')
 
-module.exports = class {{Name}} extends React.Component {
-  render() {
+module.exports = function {{Name}}(props) {
+  return (
     <div className="{{className}}">{{Name}} Component</div>
-  }
+  )
 }
 ```
 
-### Run Example
-
-```bash
-simple-scaffold MyComponent \
-    -t project/scaffold/**/* \
-    -o src/components \
-    -l className=my-component
-```
-
-## Example Scaffold Output
+### Example Scaffold Output
 
 ### Output directory structure
 
 ```plaintext
 - project
-    - src
-        - components
-            - MyComponent
-                - MyComponent.js
-        - ...
+  - src
+    - components
+      - MyComponent
+        - MyComponent.js
+    - ...
 ```
 
-With `createSubfolder = false`:
+With `createSubFolder = false`:
 
 ```plaintext
 - project
-    - src
-        - components
-            - MyComponent.js
-        - ...
+  - src
+    - components
+      - MyComponent.js
+    - ...
 ```
 
-#### project/scaffold/MyComponent/MyComponent.js
+#### Contents of `project/scaffold/MyComponent/MyComponent.jsx`
 
 ```js
 const React = require("react")
 
-module.exports = class MyComponent extends React.Component {
-  render() {
-    <div className="my-component">MyComponent Component</div>
-  }
+module.exports = function MyComponent(props) {
+  return (
+    <div className="myClassName">MyComponent Component</div>
+  )
 }
 ```
+
+## Contributing
+
+I welcome any issues or pull requests on GitHub. If you find a bug, or would like a new feature,
+don't hesitate to open an appropriate issue and I will do my best to reply promptly.
+
+If you are a developer and want to contribute code, here are some starting tips:
+
+1. Fork this repository
+2. Run `yarn install`
+3. Run `yarn dev` to start file watch mode
+4. Make any changes you would like
+5. Create tests for your changes
+6. Update the relevant documentation (readme, code comments, type comments)
+7. Create a PR on upstream
+
+Some tips on getting around the code:
+
+- Use `yarn dev` for development - it runs TypeScript compile in watch mode, allowing you to make
+  changes and immediately be able to try them using `yarn cmd`.
+- Use `yarn build` to build the output
+- Use `yarn test` to run tests
+- Use `yarn cmd` to use the CLI feature of Simple Scaffold from within the root directory,
+  enabling you to test different behaviors. See `yarn cmd -h` for more information.
+
+  > This requires an updated build, and does not trigger one itself. Either use `yarn dev` or
+  > `yarn build` before running this, or use `yarn build-cmd` instead, which triggers a build right
+  > before running the command with the rest of the given arguments.

package/cmd.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const cmd_util_1 = require("./cmd_util");
+cmd_util_1.parseCliArgs();
+//# sourceMappingURL=cmd.js.map

package/cmd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cmd.js","sourceRoot":"","sources":["../src/cmd.ts"],"names":[],"mappings":";;AAAA,yCAAyC;AACzC,uBAAY,EAAE,CAAA"}

package/cmd_util.d.ts

@@ -0,0 +1 @@
+export declare function parseCliArgs(args?: string[]): void;

package/cmd_util.js

@@ -0,0 +1,92 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCliArgs = void 0;
+const massarg_1 = __importDefault(require("massarg"));
+const chalk_1 = __importDefault(require("chalk"));
+const types_1 = require("./types");
+const scaffold_1 = require("./scaffold");
+function parseCliArgs(args = process.argv.slice(2)) {
+    return (massarg_1.default()
+        .main(scaffold_1.Scaffold)
+        .option({
+        name: "name",
+        aliases: ["n"],
+        description: "Name to be passed to the generated files. {{name}} and {{Name}} inside contents and file names will be replaced accordingly.",
+        isDefault: true,
+        required: true,
+    })
+        .option({
+        name: "output",
+        aliases: ["o"],
+        description: "Path to output to. If --create-sub-folder is enabled, the subfolder will be created inside this path.",
+        required: true,
+    })
+        .option({
+        name: "templates",
+        aliases: ["t"],
+        array: true,
+        description: "Template files to use as input. You may provide multiple files, each of which can be a relative or absolute path, " +
+            "or a glob pattern for multiple file matching easily.",
+        required: true,
+    })
+        .option({
+        name: "overwrite",
+        aliases: ["w"],
+        boolean: true,
+        defaultValue: false,
+        description: "Enable to override output files, even if they already exist.",
+    })
+        .option({
+        name: "data",
+        aliases: ["d"],
+        description: "Add custom data to the templates. By default, only your app name is included.",
+        parse: (v) => JSON.parse(v),
+    })
+        .option({
+        name: "create-sub-folder",
+        aliases: ["s"],
+        boolean: true,
+        defaultValue: false,
+        description: "Create subfolder with the input name",
+    })
+        .option({
+        name: "quiet",
+        aliases: ["q"],
+        boolean: true,
+        defaultValue: false,
+        description: "Suppress output logs (Same as --verbose 0)",
+    })
+        .option({
+        name: "verbose",
+        aliases: ["v"],
+        defaultValue: types_1.LogLevel.Info,
+        description: `Determine amount of logs to display. The values are: ${chalk_1.default.bold `0 (none) | 1 (debug) | 2 (info) | 3 (warn) | 4 (error)`}. The provided level will display messages of the same level or higher.`,
+        parse: Number,
+    })
+        .option({
+        name: "dry-run",
+        aliases: ["dr"],
+        boolean: true,
+        defaultValue: false,
+        description: "Don't emit files. This is good for testing your scaffolds and making sure they " +
+            "don't fail, without having to write actual file contents or create directories.",
+    })
+        // .example({
+        //   input: `yarn cmd -t examples/test-input/Component -o examples/test-output -d '{"property":"myProp","value":"10"}'`,
+        //   description: "Usage",
+        //   output: "",
+        // })
+        .help({
+        binName: "simple-scaffold",
+        useGlobalColumns: true,
+        usageExample: "[options]",
+        header: "Create structured files based on templates.",
+        footer: `Copyright © Chen Asraf 2021\nNPM: ${chalk_1.default.underline `https://npmjs.com/package/massarg`}\nGitHub: ${chalk_1.default.underline `https://github.com/chenasraf/massarg`}`,
+    })
+        .parse(args));
+}
+exports.parseCliArgs = parseCliArgs;
+//# sourceMappingURL=cmd_util.js.map

package/cmd_util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cmd_util.js","sourceRoot":"","sources":["../src/cmd_util.ts"],"names":[],"mappings":";;;;;;AAAA,sDAA6B;AAC7B,kDAAyB;AACzB,mCAAqD;AACrD,yCAAqC;AAErC,SAAgB,YAAY,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACvD,OAAO,CACL,iBAAO,EAA2D;SAC/D,IAAI,CAAC,mBAAQ,CAAC;SACd,MAAM,CAAC;QACN,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,CAAC,GAAG,CAAC;QACd,WAAW,EACT,8HAA8H;QAChI,SAAS,EAAE,IAAI;QACf,QAAQ,EAAE,IAAI;KACf,CAAC;SACD,MAAM,CAAC;QACN,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,CAAC,GAAG,CAAC;QACd,WAAW,EACT,uGAAuG;QACzG,QAAQ,EAAE,IAAI;KACf,CAAC;SACD,MAAM,CAAC;QACN,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,CAAC,GAAG,CAAC;QACd,KAAK,EAAE,IAAI;QACX,WAAW,EACT,oHAAoH;YACpH,sDAAsD;QACxD,QAAQ,EAAE,IAAI;KACf,CAAC;SACD,MAAM,CAAC;QACN,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,CAAC,GAAG,CAAC;QACd,OAAO,EAAE,IAAI;QACb,YAAY,EAAE,KAAK;QACnB,WAAW,EAAE,8DAA8D;KAC5E,CAAC;SACD,MAAM,CAAC;QACN,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,CAAC,GAAG,CAAC;QACd,WAAW,EAAE,+EAA+E;QAC5F,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;KAC5B,CAAC;SACD,MAAM,CAAC;QACN,IAAI,EAAE,mBAAmB;QACzB,OAAO,EAAE,CAAC,GAAG,CAAC;QACd,OAAO,EAAE,IAAI;QACb,YAAY,EAAE,KAAK;QACnB,WAAW,EAAE,sCAAsC;KACpD,CAAC;SACD,MAAM,CAAC;QACN,IAAI,EAAE,OAAO;QACb,OAAO,EAAE,CAAC,GAAG,CAAC;QACd,OAAO,EAAE,IAAI;QACb,YAAY,EAAE,KAAK;QACnB,WAAW,EAAE,4CAA4C;KAC1D,CAAC;SACD,MAAM,CAAC;QACN,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,CAAC,GAAG,CAAC;QACd,YAAY,EAAE,gBAAQ,CAAC,IAAI;QAC3B,WAAW,EAAE,wDAAwD,eAAK,CAAC,IAAI,CAAA,wDAAwD,yEAAyE;QAChN,KAAK,EAAE,MAAM;KACd,CAAC;SACD,MAAM,CAAC;QACN,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,CAAC,IAAI,CAAC;QACf,OAAO,EAAE,IAAI;QACb,YAAY,EAAE,KAAK;QACnB,WAAW,EACT,iFAAiF;YACjF,iFAAiF;KACpF,CAAC;QACF,aAAa;QACb,wHAAwH;QACxH,0BAA0B;QAC1B,gBAAgB;QAChB,KAAK;SACJ,IAAI,CAAC;QACJ,OAAO,EAAE,iBAAiB;QAC1B,gBAAgB,EAAE,IAAI;QACtB,YAAY,EAAE,WAAW;QACzB,MAAM,EAAE,6CAA6C;QACrD,MAAM,EAAE,qCAAqC,eAAK,CAAC,SAAS,CAAA,mCAAmC,aAAa,eAAK,CAAC,SAAS,CAAA,sCAAsC,EAAE;KACpK,CAAC;SACD,KAAK,CAAC,IAAI,CAAC,CACf,CAAA;AACH,CAAC;AArFD,oCAqFC"}

package/index.d.ts

@@ -1,30 +1,4 @@
-declare namespace IScaffold {
-  class SimpleScaffold {
-    constructor(config: Config)
-    run(): void
-  }
-
-  export interface Config {
-    name?: string
-    templates: string[]
-    output:
-      | string
-      | ((fullPath: string, basedir: string, basename: string) => string)
-    locals?: Locals
-    createSubfolder?: boolean
-    overwrite?: boolean | ((path: string) => boolean)
-    quiet?: boolean
-  }
-
-  export interface Locals {
-    [k: string]: string
-  }
-
-  export interface FileRepr {
-    base: string
-    file: string
-  }
-}
-
-export default IScaffold.SimpleScaffold
-export { IScaffold }
+export * from "./scaffold";
+export * from "./types";
+import Scaffold from "./scaffold";
+export default Scaffold;

package/index.js

@@ -1,2 +1,20 @@
-const SimpleScaffold = require('./dist')
-module.exports = SimpleScaffold
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./scaffold"), exports);
+__exportStar(require("./types"), exports);
+const scaffold_1 = __importDefault(require("./scaffold"));
+exports.default = scaffold_1.default;
+//# sourceMappingURL=index.js.map

package/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,6CAA0B;AAC1B,0CAAuB;AACvB,0DAAiC;AACjC,kBAAe,kBAAQ,CAAA"}

package/package.json

@@ -1,47 +1,42 @@
 {
   "name": "simple-scaffold",
-  "version": "0.7.5",
+  "version": "1.0.0-alpha.12",
   "description": "Create files based on templates",
   "repository": "https://github.com/chenasraf/simple-scaffold.git",
   "author": "Chen Asraf <inbox@casraf.com>",
   "license": "MIT",
-  "main": "dist/index.js",
-  "bin": "dist/cmd.js",
-  "types": "index.d.ts",
+  "main": "index.js",
+  "bin": "cmd.js",
   "scripts": {
-    "build": "NODE_ENV=${NODE_ENV:-production} webpack && chmod -R +x ./dist",
-    "prepublishOnly": "yarn build",
-    "dev": "webpack --watch",
+    "clean": "rm -rf dist/",
+    "build": "yarn clean && tsc && chmod -R +x ./dist && cp ./package.json ./dist/ && cp ./README.md ./dist/",
+    "dev": "tsc --watch",
     "start": "node dist/scaffold.js",
-    "test": "node dist/test.js",
-    "cmd": "dist/cmd.js",
+    "test": "jest --verbose",
+    "cmd": "node --trace-warnings dist/cmd.js",
     "build-test": "yarn build && yarn test",
     "build-cmd": "yarn build && yarn cmd"
   },
   "dependencies": {
-    "command-line-args": "^5.0.2",
-    "command-line-usage": "^6.1.1",
+    "args": "^5.0.1",
+    "chalk": "^4.1.2",
     "glob": "^7.1.3",
-    "handlebars": "^4.1.0"
+    "handlebars": "^4.7.7",
+    "lodash": "^4.17.21",
+    "massarg": "^1.0.4",
+    "util.promisify": "^1.1.1"
   },
   "devDependencies": {
-    "@types/command-line-args": "^5.0.0",
-    "@types/command-line-usage": "^5.0.1",
+    "@types/args": "^3.0.1",
     "@types/glob": "^7.1.1",
+    "@types/jest": "^26.0.24",
+    "@types/lodash": "^4.14.171",
+    "@types/mock-fs": "^4.13.1",
     "@types/node": "^14.14.22",
-    "copy-webpack-plugin": "^7.0.0",
-    "jest": "^26.6.3",
-    "ts-loader": "^8.0.14",
-    "typescript": "^4.1.3",
-    "webpack": "^5.19.0",
-    "webpack-cli": "^4.4.0",
-    "webpack-dev-server": "^3.2.1",
-    "webpack-node-externals": "^2.5.2"
-  },
-  "jest": {
-    "testPathIgnorePatterns": [
-      "node_modules",
-      "dist"
-    ]
+    "jest": "^27.0.6",
+    "mock-fs": "^5.0.0",
+    "ts-jest": "^27.0.3",
+    "ts-node": "^10.1.0",
+    "typescript": "^4.3.5"
   }
-}
+}

package/scaffold.d.ts

@@ -0,0 +1,3 @@
+import { ScaffoldConfig } from "./types";
+export declare function Scaffold(config: ScaffoldConfig): Promise<void>;
+export default Scaffold;