elrh-cosca 0.1.5 → 0.2.1

package/README.md

@@ -7,20 +7,125 @@ 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:
-- `createFileFromTemplate`
-- `promptUser`
-- `updateJsonFile`
-- `updateTextFile`
+### List of file-manipulation functions
+
+#### `createFileFromTemplate`
+
+```ts
+async function createFileFromTemplate(
+  templateFile: string, targetFile: string, force: boolean = false
+): Promise<void>
+```
+
+Takes a path to a template file from your project and will create a fresh copy in target project when invoked. 
+
+Path to `templateFile` must be prefixed with the package name to allow proper resolution, e.g. `your-package:path/to/template`. The package name can be scoped.
+
+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`
+
+```ts
+async function updateConfigFile(
+  pathToFile: string, newConfig: Record<string | number | symbol, any>, 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.
+
+#### `updateConfigFile`
+
+```ts
+async function updateConfigFile(
+  pathToFile: string, newConfig: Record<string | number | symbol, any>, force: boolean = false
+): Promise<void>
+```
+
+Takes a path to a configuration file and updates it with the provided `newConfig` object. 
+
+Path to `targetFile` is relative to `process.cwd()`. The file currently must use ESM format with either `default` or named export of **exactly one** configuration object or function call with a configuration object as its argument.
+
+The merger is performed using [unjs/magicast](https://github.com/unjs/magicast). It should:
+- preserve comments
+- work recursively to allow deep-merge
+- extend existing object with new keys from `newConfig`
+- overwrite keys with same name with values from `newConfig`
+- create a unique-union in case of arrays
+Please [report](https://github.com/AloisSeckar/elrh-cosca/issues) any logical flaws and issues of the process.
+
+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`
+
+```ts
+async function updateJsonFile(
+  pathToFile: string, jsonKey: string, newValues: Record<string | number | symbol, any>, force: boolean = false
+): Promise<void>
+```
+
+Takes a path to a JSON file and injects `newValues` under `jsonKey` key.
+
+Path to `targetFile` is relative to `process.cwd()`. The file must be a valid JSON file. It is parsed using plain `JSON.parse`.
+
+Currently it only allows adding new values under top-level keys. If the `jsonKey` exists, new values are merged into existing ones. Otherwise, new key is added. The function tracks if any real change was made and notifies the user if not.
+
+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`
+
+```ts
+async function updateTextFile(
+    pathToFile: string, rowsToAdd: string[], force: boolean = false
+): Promise<void>
+```
+
+Takes a path to a plain text file and injects `rowsToAdd` at the end of the file, **providing they are not already present in the file**. The function tracks if any real change was made and notifies the user if not.
+
+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/)
+- Developed with [TypeScript](https://www.typescriptlang.org/) in mind
+- Using [magicast](https://github.com/unjs/magicast) for parsing files
 - 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: