helpers fix

.github/workflows/alpha.yml

@@ -13,6 +13,7 @@ jobs:
         with:
           node-version: "12.x"
       - run: yarn install --frozen-lockfile
+      - run: yarn test
       - run: yarn build
       - run: cd ./dist && yarn pack --filename=../package.tgz
         if: "!contains(github.event.head_commit.message, '[skip publish]')"

.github/workflows/main.yml

@@ -13,6 +13,7 @@ jobs:
         with:
           node-version: "12.x"
       - run: yarn install --frozen-lockfile
+      - run: yarn test
       - run: yarn build
       - run: cd ./dist && yarn pack --filename=../package.tgz
         if: "!contains(github.event.head_commit.message, '[skip publish]')"

MIGRATION.md

@@ -0,0 +1,20 @@
+# Migrating from 0.x to 1.0
+
+In Simple Scaffold v1.0, the entire codebase was overhauled, yet usage remains mostly the same
+between versions. With these notable exceptions:
+
+- Some of the argument names have changed
+- Template syntax has been improved
+
+## Argument changes
+
+- `locals` has been renamed to `data`. The appropriate command line args have been updated as
+  well to `--data` | `-d`.
+
+## Template syntax changes
+
+Simple Scaffold still uses Handlebars.js to handle template content and file names. However, helpers
+have been added to remove the need for you to pre-process the template data on simple use-cases such
+as case type manipulation (converting to camel case, snake case, etc)
+
+See the readme for the full information on how to use these helpers and which are available.

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.
@@ -81,8 +91,8 @@ You can also build the scaffold yourself, if you want to create more complex arg
 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 = SimpleScaffold({
   name: "component",
@@ -92,18 +102,30 @@ const scaffold = SimpleScaffold({
   locals: {
     property: "value",
   },
+  helpers: {
+    twice: (text) => [text, text].join(" ")
+  }
 })
 ```
 
-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:
+### Additional Node.js options
 
-```javascript
-config.output = (fullPath, baseDir, baseName) => {
-  console.log({ fullPath, baseDir, baseName })
-  return path.resolve(baseDir, baseName)
-}
-```
+In addition to all the options available in the command line, there are some JS-specific options
+available:
+
+1. When `output` is used in Node directly, it may also be passed a function for each input file to
+   output into a dynamic path:
+
+    ```typescript
+    config.output = (fullPath, baseDir, baseName) => {
+      console.log({ fullPath, baseDir, baseName })
+      return path.resolve(baseDir, baseName)
+    }
+    ```
+
+2. You may add custom `helpers` to your scaffolds. Helpers are simple `(string) => string` functions
+   that transform your `data` variables into other values. See [Helpers](#helpers) for the list of
+   default helpers, or add your own to be loaded into the template parser.
 
 ## Preparing files
 
@@ -146,8 +168,20 @@ Here are the built-in helpers available for use:
 | kebabCase   | `{{ kebabCase name }}`  | my-name        |
 | hyphenCase  | `{{ hyphenCase name }}` | my-name        |
 | pascalCase  | `{{ pascalCase name }}` | MyName         |
+| upperCase   | `{{ upperCase name }}`  | MYNAME         |
+| lowerCase   | `{{ lowerCase name }}`  | myname         |
 
-**Note:** These helpers are available for any data property, not exclusive to `name`.
+> These helpers are available for any data property, not exclusive to `name`.
+
+You may also add your own custom helpers using the `helpers` options when using the JS API (rather
+than the CLI). The `helpers` option takes an object whose keys are helper names, and values are
+the transformation functions. For example, `upperCase` is implemented like so:
+
+```typescript
+config.helpers = {
+  upperCase: (text) => text.toUpperCase(),
+}
+```
 
 ## Examples
 
@@ -174,15 +208,15 @@ simple-scaffold MyComponent \
     - ...
 ```
 
-#### Contents of `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>
-  }
+  )
 }
 ```
 
@@ -209,14 +243,42 @@ With `createSubFolder = false`:
     - ...
 ```
 
-#### Contents of `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() {
+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.json

@@ -1,6 +1,6 @@
 {
   "name": "simple-scaffold",
-  "version": "1.0.0-alpha.10",
+  "version": "1.0.0-alpha.15",
   "description": "Create files based on templates",
   "repository": "https://github.com/chenasraf/simple-scaffold.git",
   "author": "Chen Asraf <inbox@casraf.com>",
@@ -23,7 +23,7 @@
     "glob": "^7.1.3",
     "handlebars": "^4.7.7",
     "lodash": "^4.17.21",
-    "massarg": "^1.0.3",
+    "massarg": "^1.0.5",
     "util.promisify": "^1.1.1"
   },
   "devDependencies": {

src/cmd_util.ts

@@ -10,67 +10,69 @@ export function parseCliArgs(args = process.argv.slice(2)) {
       .option({
         name: "name",
         aliases: ["n"],
-        isDefault: true,
         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.",
-        defaultValue: [],
-        array: true,
+        required: true,
       })
       .option({
-        aliases: ["w"],
         name: "overwrite",
-        description: "Enable to override output files, even if they already exist.",
-        defaultValue: false,
+        aliases: ["w"],
         boolean: true,
+        defaultValue: false,
+        description: "Enable to override output files, even if they already exist.",
       })
       .option({
-        aliases: ["d"],
         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({
-        aliases: ["s"],
         name: "create-sub-folder",
+        aliases: ["s"],
+        boolean: true,
+        defaultValue: false,
         description: "Create subfolder with the input name",
-        defaultValue: false,
-        boolean: true,
       })
       .option({
-        aliases: ["q"],
         name: "quiet",
-        description: "Suppress output logs (Same as --verbose 0)",
-        defaultValue: false,
+        aliases: ["q"],
         boolean: true,
+        defaultValue: false,
+        description: "Suppress output logs (Same as --verbose 0)",
       })
       .option({
-        aliases: ["v"],
         name: "verbose",
-        description: `Determine amount of logs to display. The values are: ${chalk.bold`0 (none) | 1 (debug) | 2 (info) | 3 (warn) | 4 (error)`}. The provided level will display messages of the same level or higher.`,
+        aliases: ["v"],
         defaultValue: LogLevel.Info,
+        description: `Determine amount of logs to display. The values are: ${chalk.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({
-        aliases: ["dr"],
         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.",
-        defaultValue: false,
-        boolean: true,
       })
       // .example({
       //   input: `yarn cmd -t examples/test-input/Component -o examples/test-output -d '{"property":"myProp","value":"10"}'`,
@@ -82,7 +84,11 @@ export function parseCliArgs(args = process.argv.slice(2)) {
         useGlobalColumns: true,
         usageExample: "[options]",
         header: "Create structured files based on templates.",
-        footer: `Copyright © Chen Asraf 2021\nNPM: ${chalk.underline`https://npmjs.com/package/massarg`}\nGitHub: ${chalk.underline`https://github.com/chenasraf/massarg`}`,
+        footer: [
+          `Copyright © Chen Asraf 2021`,
+          `NPM: ${chalk.underline`https://npmjs.com/package/simple-scaffold`}`,
+          `GitHub: ${chalk.underline`https://github.com/chenasraf/simple-scaffold`}`,
+        ].join("\n"),
       })
       .parse(args)
   )

src/scaffold.ts

@@ -14,11 +14,13 @@ import {
   pascalCase,
   isDir,
   removeGlob,
+  makeRelativePath,
+  registerHelpers,
 } from "./utils"
 import { LogLevel, ScaffoldConfig } from "./types"
 
-export async function Scaffold(config: ScaffoldConfig) {
-  const options = { ...config }
+export async function Scaffold({ ...options }: ScaffoldConfig) {
+  registerHelpers(options)
   try {
     const data = { name: options.name, Name: pascalCase(options.name), ...options.data }
     log(options, LogLevel.Debug, "Full config:", {
@@ -29,12 +31,13 @@ export async function Scaffold(config: ScaffoldConfig) {
       data: options.data,
       overwrite: options.overwrite,
       quiet: options.quiet,
+      helpers: Object.keys(options.helpers ?? {}),
       verbose: `${options.verbose} (${Object.keys(LogLevel).find(
         (k) => (LogLevel[k as any] as unknown as number) === options.verbose!
       )})`,
     })
     log(options, LogLevel.Info, "Data:", data)
-    for (let template of config.templates) {
+    for (let template of options.templates) {
       try {
         const _isGlob = template.includes("*")
         if (!_isGlob && !(await pathExists(template))) {
@@ -66,8 +69,9 @@ export async function Scaffold(config: ScaffoldConfig) {
         log(options, LogLevel.Debug, "after glob")
         for (const inputFilePath of files) {
           if (!(await isDir(inputFilePath))) {
+            const relPath = makeRelativePath(path.dirname(removeGlob(inputFilePath).replace(_nonGlobTemplate, "")))
             const basePath = path
-              .resolve(process.cwd(), path.dirname(removeGlob(inputFilePath).replace(_nonGlobTemplate, "")).slice(1))
+              .resolve(process.cwd(), relPath)
               .replace(process.cwd() + "/", "")
               .replace(process.cwd(), "")
             log(
@@ -75,13 +79,11 @@ export async function Scaffold(config: ScaffoldConfig) {
               LogLevel.Debug,
               `\nprocess.cwd(): ${process.cwd()}`,
               `\norigTemplate: ${origTemplate}`,
-              `\nremoveGlob(inputFilePath).replace(_nonGlobTemplate, "").slice(1): ${removeGlob(inputFilePath)
-                .replace(_nonGlobTemplate, "")
-                .slice(1)}`,
+              `\nrelPath: ${relPath}`,
               `\ntemplate: ${template}`,
               `\ninputFilePath: ${inputFilePath}`,
               `\nnonGlobTemplate: ${_nonGlobTemplate}`,
-              `\nbase path: ${basePath}`,
+              `\nbasePath: ${basePath}`,
               `\nisDir: ${_isDir}`,
               `\nisGlob: ${_isGlob}`,
               `\n`

src/types.ts

@@ -11,18 +11,76 @@ export type FileResponseFn<T> = (fullPath: string, basedir: string, basename: st
 export type FileResponse<T> = T | FileResponseFn<T>
 
 export interface ScaffoldConfig {
-  /** The name supplied for the output templates */
+  /**
+   * Name to be passed to the generated files. `{{name}}` and `{{Name}}` inside contents and file names will be replaced
+   * accordingly.
+   */
   name: string
-  /** Template input files/dirs/glob patterns to use as template input. These will be copied to the output directory. */
+
+  /**
+   * 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: current working directory)
+   */
   templates: string[]
-  /** Output directory to put scaffolded files in. */
+
+  /** Path to output to. If `createSubFolder` is `true`, the subfolder will be created inside this path. */
   output: FileResponse<string>
+
+  /**
+   * Create subfolder with the input name (default: `false`)
+   */
   createSubFolder?: boolean
+
+  /**
+   * Add custom data to the templates. By default, only your app name is included as `{{name}}` and `{{Name}}`.
+   */
   data?: Record<string, string>
+
+  /**
+   * Enable to override output files, even if they already exist. (default: `false`)
+   *
+   * You may supply a function to this option, which can take the arguments `(fullPath, baseDir, baseName)` and returns
+   * a string, to return a dynamic path for each file.
+   */
   overwrite?: FileResponse<boolean>
+
+  /** Suppress output logs (Same as `verbose: 0` or `verbose: LogLevel.None`) */
   quiet?: boolean
+
+  /**
+   * 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 (info)`)
+   * @see LogLevel
+   */
   verbose?: LogLevel
+
+  /**
+   * 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`)
+   */
   dryRun?: boolean
+
+  /**
+   * Additional helpers to add to the template parser. Provide an object whose keys are the name of the function to add,
+   * and the value is the helper function itself. The signature of helpers is as follows:
+   * ```typescript
+   * (text: string) => string
+   * ```
+   *
+   * A full example might be:
+   *
+   * ```typescript
+   * Scaffold({
+   *   //...
+   *   helpers: {
+   *     upperCamelCase: (text) => camelCase(text).toUpperCase()
+   *   }
+   * })
+   * ```
+   */
+  helpers?: Record<string, (text: string) => string>
 }
 export interface ScaffoldCmdConfig {
   name: string
@@ -32,5 +90,6 @@ export interface ScaffoldCmdConfig {
   data?: Record<string, string>
   overwrite: boolean
   quiet: boolean
+  verbose: LogLevel
   dryRun: boolean
 }

src/utils.ts

@@ -10,17 +10,23 @@ import { promises as fsPromises } from "fs"
 import chalk from "chalk"
 const { stat, access, mkdir } = fsPromises
 
-const helpers = {
+export const defaultHelpers: Exclude<ScaffoldConfig["helpers"], undefined> = {
   camelCase,
   snakeCase,
   startCase,
   kebabCase,
   hyphenCase: kebabCase,
   pascalCase,
+  lowerCase: (text) => text.toLowerCase(),
+  upperCase: (text) => text.toUpperCase(),
 }
 
-for (const helperName in helpers) {
-  Handlebars.registerHelper(helperName, helpers[helperName as keyof typeof helpers])
+export function registerHelpers(options: ScaffoldConfig) {
+  const _helpers = { ...defaultHelpers, ...options.helpers }
+  for (const helperName in _helpers) {
+    log(options, LogLevel.Debug, `Registering helper: ${helperName}`)
+    Handlebars.registerHelper(helperName, _helpers[helperName as keyof typeof _helpers])
+  }
 }
 
 export function handleErr(err: NodeJS.ErrnoException | null) {
@@ -119,3 +125,7 @@ export async function isDir(path: string): Promise<boolean> {
 export function removeGlob(template: string) {
   return template.replace(/\*/g, "").replace(/\/\//g, "/")
 }
+
+export function makeRelativePath(str: string): string {
+  return str.startsWith("/") ? str.slice(1) : str
+}

tests/scaffold.test.ts

@@ -3,6 +3,7 @@ import FileSystem from "mock-fs/lib/filesystem"
 import Scaffold from "../src/scaffold"
 import { readdirSync, readFileSync } from "fs"
 import { Console } from "console"
+import { defaultHelpers } from "../src/utils"
 
 const fileStructNormal = {
   input: {
@@ -30,6 +31,20 @@ const fileStructNested = {
   },
   output: {},
 }
+
+const defaultHelperNames = Object.keys(defaultHelpers)
+const fileStructHelpers = {
+  input: {
+    defaults: defaultHelperNames.reduce<Record<string, string>>(
+      (all, cur) => ({ ...all, [cur + ".txt"]: `{{ ${cur} name }}` }),
+      {}
+    ),
+    custom: {
+      "add1.txt": "{{ add1 name }}",
+    },
+  },
+  output: {},
+}
 // let logsTemp: any = []
 // let logMock: any
 function withMock(fileStruct: FileSystem.DirectoryItems, testFn: jest.EmptyFunction): jest.EmptyFunction {
@@ -202,4 +217,59 @@ describe("Scaffold", () => {
       })
     })
   )
+
+  describe(
+    "helpers",
+    withMock(fileStructHelpers, () => {
+      const _helpers: Record<string, (text: string) => string> = {
+        add1: (text) => text + " 1",
+      }
+
+      describe("default helpers", () => {
+        test("should work", async () => {
+          await Scaffold({
+            name: "app_name",
+            output: "output",
+            templates: ["input"],
+            verbose: 0,
+            helpers: _helpers,
+          })
+
+          const results = {
+            camelCase: "appName",
+            snakeCase: "app_name",
+            startCase: "App Name",
+            kebabCase: "app-name",
+            hyphenCase: "app-name",
+            pascalCase: "AppName",
+            lowerCase: "app_name",
+            upperCase: "APP_NAME",
+          }
+          for (const key in results) {
+            const file = readFileSync(process.cwd() + `/output/defaults/${key}.txt`)
+            expect(file.toString()).toEqual(results[key as keyof typeof results])
+          }
+        })
+      })
+      describe("custom helpers", () => {
+        test("should work", async () => {
+          await Scaffold({
+            name: "app_name",
+            output: "output",
+            templates: ["input"],
+            verbose: 0,
+            helpers: _helpers,
+          })
+
+          const results = {
+            add1: "app_name 1",
+          }
+          for (const key in results) {
+            const file = readFileSync(process.cwd() + `/output/custom/${key}.txt`)
+            expect(file.toString()).toEqual(results[key as keyof typeof results])
+          }
+        })
+      })
+    })
+  )
 })

yarn.lock

@@ -932,7 +932,7 @@ chalk@2.4.2, chalk@^2.0.0:
     escape-string-regexp "^1.0.5"
     supports-color "^5.3.0"
 
-chalk@^4.0.0, chalk@^4.1.1:
+chalk@^4.0.0:
   version "4.1.1"
   resolved "https://registry.yarnpkg.com/chalk/-/chalk-4.1.1.tgz#c80b3fab28bf6371e6863325eee67e618b77e6ad"
   integrity sha512-diHzdDKxcU+bAsUboHLPEDQiw0qEe0qd7SYUn3HgcFlWgbDcfLGswOHYeGrHKzG9z6UYf01d9VFMfZxPM1xZSg==
@@ -2161,12 +2161,12 @@ makeerror@1.0.x:
   dependencies:
     tmpl "1.0.x"
 
-massarg@^1.0.3:
-  version "1.0.3"
-  resolved "https://registry.yarnpkg.com/massarg/-/massarg-1.0.3.tgz#228cf2d84896924b6b12021ea23ed9a9077e15b7"
-  integrity sha512-LYb4XvAQ+PbBClyfkn9B4JtfwycfpnOnGIznALt9YLnrmQaCcXXJBQsG5SA/2w+bmLOeYRoR9GqqFLyaniCn9g==
+massarg@^1.0.5:
+  version "1.0.5"
+  resolved "https://registry.yarnpkg.com/massarg/-/massarg-1.0.5.tgz#3dfd49bb63bfca4b0371a2f0ffc7580a9a6cc7a0"
+  integrity sha512-gkJHZsNfeMurpVPKojCiT2lnG2cSxHPAXZSg+gCLIgCf5bGn7pKOsoeu4qVAc5mlBxV2l/hA1yojt+ZsJd8SDg==
   dependencies:
-    chalk "^4.1.1"
+    chalk "^4.1.2"
     lodash "^4.17.21"
 
 merge-stream@^2.0.0: