elrh-cosca 0.2.4 → 0.2.6

package/dist/types/functions/create-file-from-template.d.ts

@@ -1 +1,11 @@
-export declare function createFileFromTemplate(templateFile: string, targetFile: string, force?: boolean): Promise<void>;
+/**
+ * Creates a new copy of given file from a local template.
+ *
+ * @param {string} templateFile - The path to the template file (prefixed with package name).
+ * @param {string} targetFile - The path to the target file to create (relative to CWD). Can overwrite existing files if confirmed.
+ * @param {boolean} force - Whether to force creation without prompting.
+ * @param {string} prompt - Custom prompt message displayed in terminal.
+ * @returns {Promise<void>} An empty promise that resolves when the file is created.
+ * @throws Will throw an error if the template file cannot be found or the target file failed to be created.
+ */
+export declare function createFileFromTemplate(templateFile: string, targetFile: string, force?: boolean, prompt?: string): Promise<void>;

package/dist/types/functions/create-file-from-web-template.d.ts

@@ -1 +1,11 @@
-export declare function createFileFromWebTemplate(url: string, targetFile: string, force?: boolean): Promise<void>;
+/**
+ * Creates a new copy of given file from a web template.
+ *
+ * @param {string} url - The URL to the template file (must be accessible via `node:https.get` and return raw text data).
+ * @param {string} targetFile - The path to the target file to create (relative to CWD). Can overwrite existing files if confirmed.
+ * @param {boolean} force - Whether to force creation without prompting.
+ * @param {string} prompt - Custom prompt message displayed in terminal.
+ * @returns {Promise<void>} An empty promise that resolves when the file is created.
+ * @throws Will throw an error if the remote template cannot be fetched or the target file failed to be created.
+ */
+export declare function createFileFromWebTemplate(url: string, targetFile: string, force?: boolean, prompt?: string): Promise<void>;

package/dist/types/functions/update-config-file.d.ts

@@ -8,6 +8,7 @@
  *
  * @param {string} pathToFile - Path to file, relative to project root (process.cwd()).
  * @param {object} newConfig - Config to merge in (takes precedence).
- * @returns {Promise<void>}
+ * @returns {Promise<void>} An empty promise that resolves when the file is updated.
+ * @throws Will throw an error if no config export is found or it cannot be processed.
  */
-export declare function updateConfigFile(pathToFile: string, newConfig: Record<string | number | symbol, any>, force?: boolean): Promise<void>;
+export declare function updateConfigFile(pathToFile: string, newConfig: Record<string | number | symbol, any>, force?: boolean, prompt?: string): Promise<void>;

package/dist/types/functions/update-json-file.d.ts

@@ -1 +1,12 @@
-export declare function updateJsonFile(pathToFile: string, jsonKey: string, newValues: Record<string | number | symbol, any>, force?: boolean): Promise<void>;
+/**
+ * Updates a JSON file by modifying a specific key with new values.
+ *
+ * @param {string} pathToFile - The path to the JSON file to update (relative to CWD).
+ * @param {string} jsonKey - The key in the JSON file to update (can be new or existing).
+ * @param {Record<string | number | symbol, any>} newValues - The new values to set for the specified key.
+ * @param {boolean} force - Whether to force the update without prompting.
+ * @param {string} prompt - Custom prompt message displayed in terminal.
+ * @returns {Promise<void>} An empty promise that resolves when the file is updated.
+ * @throws Will throw an error if the file does not exist or cannot be parsed as JSON.
+ */
+export declare function updateJsonFile(pathToFile: string, jsonKey: string, newValues: Record<string | number | symbol, any>, force?: boolean, prompt?: string): Promise<void>;

package/dist/types/functions/update-text-file.d.ts

@@ -1 +1,11 @@
-export declare function updateTextFile(pathToFile: string, rowsToAdd: string[], force?: boolean): Promise<void>;
+/**
+ * Updates a text file by adding new rows.
+ *
+ * @param {string} pathToFile - The path to the text file to update (relative to CWD).
+ * @param {string[]} rowsToAdd - New rows to be added at the end of the file.
+ * @param {boolean} force - Whether to force the update without prompting.
+ * @param {string} prompt - Custom prompt message displayed in terminal.
+ * @returns {Promise<void>} An empty promise that resolves when the file is updated.
+ * @throws Will throw an error if the file does not exist.
+ */
+export declare function updateTextFile(pathToFile: string, rowsToAdd: string[], force?: boolean, prompt?: string): Promise<void>;

package/dist/types/main.d.ts

@@ -6,6 +6,7 @@ import { updateTextFile } from './functions/update-text-file';
 import { promptUser } from './terminal/prompt-user';
 import { showError } from './terminal/show-error';
 import { showMessage } from './terminal/show-message';
+import { getEnvValue } from './utils/get-env-value';
 import { parseQualifiedPath } from './utils/parse-qualified-path';
 import { resolvePackagePath } from './utils/resolve-package-path';
-export { createFileFromTemplate, createFileFromWebTemplate, updateConfigFile, updateJsonFile, updateTextFile, promptUser, showError, showMessage, parseQualifiedPath, resolvePackagePath, };
+export { createFileFromTemplate, createFileFromWebTemplate, updateConfigFile, updateJsonFile, updateTextFile, promptUser, showError, showMessage, getEnvValue, parseQualifiedPath, resolvePackagePath, };

package/dist/types/terminal/prompt-user.d.ts

@@ -1 +1,11 @@
-export declare function promptUser(question: string): Promise<boolean>;
+/**
+ * Prompts the user with a question and returns their response.
+ *
+ * @param {string} question - Question to ask the user
+ * @param {{ input?: NodeJS.ReadableStream; output?: NodeJS.WritableStream }} options - Optional setting of custom input/output stream
+ * @returns {Promise<boolean>} - true if the user answered yes (`y`, `Y`, `yes`, `YES`), false otherwise
+ */
+export declare function promptUser(question: string, options?: {
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream;
+}): Promise<boolean>;

package/dist/types/terminal/show-error.d.ts

@@ -1 +1,7 @@
+/**
+ * Prints error message into stderr with specified number of newlines after it.
+ *
+ * @param {string} message - The error message text to display.
+ * @param {number} linesAfter - The number of newlines to print after the message (default is 1).
+ */
 export declare function showError(message: string, linesAfter?: number): void;

package/dist/types/terminal/show-message.d.ts

@@ -1 +1,7 @@
+/**
+ * Prints message into stdout with specified number of newlines after it.
+ *
+ * @param {string} message - The message text to display.
+ * @param {number} linesAfter - The number of newlines to print after the message (default is 1).
+ */
 export declare function showMessage(message: string, linesAfter?: number): void;

package/dist/types/utils/get-env-value.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Retrieves the value of an environment variable from a .env file.
+ *
+ * @param {string} key - The name of the environment variable to retrieve.
+ * @param {string} envFilePath - The path to the .env file (default is the .env file in the project root).
+ * @returns {string | undefined} - The value of the environment variable, or undefined if not found.
+ */
+export declare function getEnvValue(key: string, envFilePath?: string): string | undefined;

package/dist/types/utils/parse-qualified-path.d.ts

@@ -1,6 +1,10 @@
 /**
  * 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`). Throws error on invalid input.
+ * The package name can be scoped (e.g. `@scope/package`).
+ *
+ * @param {string} path - The qualified path string to parse.
+ * @returns {{ pkg: string; file: string }} An object containing the package name and the relative file path.
+ * @throws Will throw an error if the input format is invalid.
  */
 export declare function parseQualifiedPath(path: string): {
     pkg: string;

package/dist/types/utils/resolve-package-path.d.ts

@@ -2,5 +2,9 @@
  * Resolve a package's installed root directory *from the target app*.
  * Package name can be scoped (e.g. `@scope/package`).
  * Works with npm/yarn/pnpm, hoisting or not.
+ *
+ * @param {string} packageName - The name of the package to resolve.
+ * @returns {string} The absolute path to the package's root directory.
+ * @throws Will throw an error if the package cannot be found or accessed.
  */
 export declare function resolvePackagePath(packageName: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "elrh-cosca",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "type": "module",
   "files": [
     "dist"

package/test/cosca-test.js

@@ -4,7 +4,7 @@
 
 import {
   createFileFromTemplate, createFileFromWebTemplate, promptUser, showError, showMessage,
-  updateConfigFile, updateJsonFile, updateTextFile
+  updateConfigFile, getEnvValue, updateJsonFile, updateTextFile
 } from '../dist/elrh-cosca.mjs'
 
 async function main() {
@@ -13,6 +13,14 @@ async function main() {
   console.log('Test showMessage')
   showError('ERROR!')
 
+  console.log('Test getEnvValue')
+  const a = getEnvValue('A')
+  const b = getEnvValue('B')
+  const c = getEnvValue('C')
+  const d = getEnvValue('D')
+  const e = getEnvValue('E')
+  console.log(a, b, c, d, e)
+
   console.log('Test promptUser')
   const input = await promptUser('Is it today?')
   console.log('User input:', input)