elrh-cosca 0.2.0 → 0.2.2

package/README.md

@@ -7,11 +7,13 @@ The **"COSCA"** abbreviation stands for **CO**de **SCA**ffolding which points ou
 
 ## How to use
 
+**NOTE:** The library is **ESM only** and it is advised to use with at least **Node 18**.
+
 `npm install elrh-cosca` to include into your project.
 
-**List of available functions:**
+### List of file-manipulation functions
 
-### `createFileFromTemplate`
+#### `createFileFromTemplate`
 
 ```ts
 async function createFileFromTemplate(
@@ -27,15 +29,23 @@ Path to `targetFile` is relative to `process.cwd()` which allows consumers to ru
 
 By default the function asks for confirmation before attempting to create the file and if the file with the same name as `targetFile` is detected. Setting the last optional parameter `force` to `true` will suppress manual confirmation prompts.
 
-### `promptUser`
+#### `createFileFromWebTemplate`
 
 ```ts
-export async function promptUser(question: string): Promise<boolean>
+async function createFileWebFromTemplate(
+  url: string, targetFile: string, force: boolean = false
+): Promise<void>
 ```
 
-Prints out a `question` to the console and waits for the input. Returns `true` when `y` is pressed and `false` otherwise.
+Gets a file definition from given `url` and will create a fresh copy in target project when invoked. 
+
+Contents of `url` must be accessible via `node:https.get` function and will be fetched as raw string data.
+
+Path to `targetFile` is relative to `process.cwd()` which allows consumers to run `npx your-script` in their project roots during development.
+
+By default the function asks for confirmation before attempting to create the file and if the file with the same name as `targetFile` is detected. Setting the last optional parameter `force` to `true` will suppress manual confirmation prompts.
 
-### `updateConfigFile`
+#### `updateConfigFile`
 
 ```ts
 async function updateConfigFile(
@@ -45,7 +55,7 @@ async function updateConfigFile(
 
 Prints out a `question` to the console and waits for the input. Returns `true` when `y` is pressed and `false` otherwise.
 
-### `updateConfigFile`
+#### `updateConfigFile`
 
 ```ts
 async function updateConfigFile(
@@ -67,7 +77,7 @@ Please [report](https://github.com/AloisSeckar/elrh-cosca/issues) any logical fl
 
 By default the function asks for confirmation before attempting to alter the `targetFile`. Setting the last optional parameter `force` to `true` will suppress manual confirmation prompts.
 
-### `updateJsonFile`
+#### `updateJsonFile`
 
 ```ts
 async function updateJsonFile(
@@ -83,10 +93,10 @@ Currently it only allows adding new values under top-level keys. If the `jsonKey
 
 By default the function asks for confirmation before attempting to alter the `targetFile`. Setting the last optional parameter `force` to `true` will suppress manual confirmation prompts.
 
-### `updateTextFile`
+#### `updateTextFile`
 
 ```ts
-export async function updateTextFile(
+async function updateTextFile(
     pathToFile: string, rowsToAdd: string[], force: boolean = false
 ): Promise<void>
 ```
@@ -95,6 +105,34 @@ Takes a path to a plain text file and injects `rowsToAdd` at the end of the file
 
 By default the function asks for confirmation before attempting to alter the `targetFile`. Setting the last optional parameter `force` to `true` will suppress manual confirmation prompts.
 
+### List of terminal helpers
+
+#### `promptUser`
+
+```ts
+async function promptUser(question: string): Promise<boolean>
+```
+
+Prints out a `question` to the console and waits for the input. Returns `true` when `y` is pressed and `false` otherwise.
+
+### List of other utils
+
+#### `parseQualifiedPath`
+
+```ts
+function parseQualifiedPath(path: string): { pkg: string; file: string }
+```
+
+Expects path to file in `"package:relative/path/to/file"` format and splits it into `{ pkg, file }`. The package name can be scoped (e.g. `@scope/package`).
+
+#### `resolvePackagePath`
+
+```ts
+function resolvePackagePath(pkg: string): string
+```
+
+Resolve a package's installed root directory *from the target app* - which can be either from within itself during development or from corresponding package dir inside *node_modules*. The package name can be scoped (e.g. `@scope/package`).
+
 ## Tech stack
 
 - Developed with [TypeScript](https://www.typescriptlang.org/) in mind
@@ -102,6 +140,8 @@ By default the function asks for confirmation before attempting to alter the `ta
 - Build with [Vite](https://vitejs.dev/)
 - Tested with [Vitest](https://vitest.dev/)
 
+See [Changelog](https://github.com/AloisSeckar/elrh-cosca/blob/main/CHANGELOG.md) for project history and development.
+
 ## Report bugs & contact
 
 Use GitHub issues to report bugs / propose enhancements / give feedback: