@achs/env 2.0.0 → 3.1.0

package/src/utils/command.util.ts

@@ -0,0 +1,223 @@
+import chalk from 'chalk';
+import merge from 'merge-deep';
+import { Arguments } from 'yargs';
+import { CommandArguments } from 'arguments';
+import { EnvCommandArguments } from 'commands/env.command';
+import { EnvProviderConfig, EnvProviderResult } from '../interfaces';
+import {
+    createValidators,
+    interpolate,
+    logger,
+    readJson,
+    schemaFrom,
+    writeJson
+} from '../utils';
+
+/**
+ * Injects config to command arguments from file.
+ *
+ * @param {Record<string, unknown>} argv
+ * @param {[string, string]} delimiters
+ */
+export async function loadConfigFile(
+    argv: Record<string, unknown>,
+    delimiters: [string, string]
+): Promise<void> {
+    if (typeof argv.configFile === 'string') {
+        const path = interpolate(argv.configFile, argv, delimiters);
+        const [config, success] = await readJson(path);
+
+        if (success) for (const key in config) argv[key] ??= config[key];
+    }
+}
+
+/**
+ * Extracts subcommand from command line parameters.
+ *
+ * @export
+ * @param {string[]} rawArgv process.argv.slice(2)
+ * @param {[string, string]} delimiters
+ *
+ * @returns {string[]} subcommand for wrap if exists
+ */
+export function getSubcommand(rawArgv: string[], delimiters: [string, string]) {
+    let subcommand: string[] = [];
+
+    // subcommand delimiter indexes
+    const begin = rawArgv.indexOf(delimiters[0]);
+    const count = rawArgv.lastIndexOf(delimiters[1]) - begin;
+
+    // calculates subcommand surrounded by delimiters
+    if (begin > 0) {
+        subcommand =
+            count > 0
+                ? rawArgv.splice(begin, count + 1).slice(1, -1)
+                : rawArgv.splice(begin).slice(1);
+    }
+
+    return subcommand;
+}
+
+/**
+ * Loads providers JSON schema from file.
+ *
+ * @param {Record<string, unknown>} argv
+ * @param {[string, string]} delimiters
+ *
+ * @returns {Promise<Record<string, unknown>>}
+ */
+export async function loadSchemaFile(
+    argv: Record<string, unknown>,
+    delimiters: [string, string]
+): Promise<Record<string, unknown> | undefined> {
+    if (typeof argv.schemaFile === 'string') {
+        const path = interpolate(argv.schemaFile, argv, delimiters);
+        const [schema, success] = await readJson(path);
+
+        return success ? schema : undefined;
+    }
+
+    return undefined;
+}
+
+/**
+ * Reads project package.json.
+ *
+ * @export
+ * @returns {Promise<Record<string, unknown>> | never}
+ */
+export async function loadProjectInfo(): Promise<
+    Record<string, unknown> | undefined
+> {
+    try {
+        return await import(`${process.cwd()}/package.json`);
+    } catch {
+        logger.warn(
+            `project file ${chalk.underline.yellow('package.json')} not found`
+        );
+
+        return undefined;
+    }
+}
+
+/**
+ * Executes load functions from provider handlers.
+ *
+ * @param {EnvProviderConfig[]} providers
+ * @param {Partial<Arguments<EnvCommandArguments>>} argv
+ *
+ * @returns {EnvProviderResult[]}
+ */
+export function loadVariablesFromProviders(
+    providers: EnvProviderConfig[],
+    argv: Partial<Arguments<EnvCommandArguments>>
+): Promise<EnvProviderResult[]> {
+    if (!providers) return Promise.resolve([]) as Promise<EnvProviderResult[]>;
+
+    return Promise.all(
+        providers.map(({ handler: { key, load }, config }) => {
+            logger.silly(`executing ${chalk.yellow(key)} provider`);
+
+            const value = load(argv, config);
+
+            if (value instanceof Promise) {
+                return value.then((value) => ({
+                    key,
+                    config,
+                    value
+                }));
+            } else {
+                return { key, config, value };
+            }
+        })
+    );
+}
+
+/**
+ * Flattern environment provider results.
+ *
+ * @param {EnvProviderResult[]} results
+ * @param {Partial<Arguments<EnvCommandArguments>>} argv
+ *
+ * @throws {Error} on schema validation failed
+ *
+ * @returns {EnvProviderResult[]} flatten results
+ */
+export function flatResults(
+    results: EnvProviderResult[]
+): EnvProviderResult[] | never {
+    return results.flatMap(({ value }) => {
+        if (Array.isArray(value)) value = merge({}, ...value);
+
+        return value;
+    });
+}
+
+/**
+ * Flattern and validates environment provider results.
+ *
+ * @param {EnvProviderResult[]} results
+ * @param {Partial<Arguments<EnvCommandArguments>>} argv
+ *
+ * @throws {Error} on schema validation failed
+ *
+ * @returns {EnvProviderResult[]}
+ */
+export function flatAndValidateResults(
+    results: EnvProviderResult[],
+    argv: Partial<Arguments<EnvCommandArguments>>
+): EnvProviderResult[] | never {
+    if (!argv.schemaValidate) return flatResults(results);
+
+    const validators = createValidators(argv.schema!, argv.detectFormat);
+
+    return results.flatMap(({ key, value }) => {
+        if (Array.isArray(value)) value = merge({}, ...value);
+
+        const validator = validators![key];
+
+        if (validator(value)) return value;
+
+        logger.error(
+            `schema validation failed for ${chalk.yellow(key)}`,
+            validator.errors
+        );
+
+        throw new Error(`schema validation failed for ${key}`);
+    });
+}
+
+/**
+ * Creates or updates JSON schema from
+ * environment variables grouped by provider key.
+ *
+ * @export
+ * @param {EnvProviderResult[]} env
+ * @param {Arguments<EnvCommandArguments>} argv
+ *
+ * @returns {Promise<object>} JSON schema grouped by provider key.
+ */
+export async function generateSchemaFrom(
+    env: EnvProviderResult[],
+    argv: Arguments<CommandArguments>
+): Promise<object> {
+    const { resolve, nullable, detectFormat, schemaFile } = argv;
+
+    // generates schemas from proviers results
+    let schema = env.reduce((schema, { key, value }) => {
+        const env = Array.isArray(value) ? merge({}, ...value) : value;
+
+        schema[key] = schemaFrom(env, {
+            nullable,
+            strings: { detectFormat }
+        });
+
+        return schema;
+    }, {} as Record<string, unknown>);
+
+    if (resolve === 'merge') schema = merge(argv.schema, schema);
+
+    await writeJson(schemaFile, schema, true);
+
+    return schema;
+}

package/{utils/index.d.ts → src/utils/index.ts}

@@ -4,4 +4,3 @@ export * from './json.util';
 export * from './logger';
 export * from './normalize.util';
 export * from './schema.util';
-//# sourceMappingURL=index.d.ts.map

package/src/utils/interpolate.util.ts

@@ -0,0 +1,65 @@
+import subslate from 'subslate';
+
+/**
+ * Validates value must be a record.
+ *
+ * @export
+ * @param {unknown} obj
+ * @returns {*}  {obj is Record<string, unknown>}
+ */
+export function isRecord(obj: unknown): obj is Record<string, unknown> {
+    if (!obj || typeof obj !== 'object') return false;
+
+    return Object.keys(obj).length > 0;
+}
+
+/**
+ * Replaces string arguments with regex interpolation.
+ *
+ * @export
+ * @template T
+ * @param {T} value
+ * @param {Record<string, unknown>} args
+ * @param {[string, string]} [delimiters=['[[', ']]']]
+ *
+ * @returns {T} mutated value
+ */
+export function interpolate<T extends string | unknown>(
+    value: T,
+    args: Record<string, unknown>,
+    delimiters: [string, string] = ['[[', ']]']
+): T {
+    if (typeof value === 'string') {
+        return subslate(value, args, {
+            startStopPairs: delimiters
+        }) as T;
+    }
+
+    if (Array.isArray(value))
+        return value.map((a) => interpolate(a, args, delimiters)) as T;
+
+    if (isRecord(value)) return interpolateJson(value, args, delimiters) as T;
+
+    return value;
+}
+
+/**
+ * Replaces JSON string arguments with regex interpolation.
+ *
+ * @export
+ * @param {Record<string, unknown>} args
+ * @param {Record<string, unknown>} values
+ * @param {[string, string]} [delimiters=['[[', ']]']]
+ *
+ * @returns {Record<string, unknown>} mutated args
+ */
+export function interpolateJson(
+    values: Record<string, unknown>,
+    args: Record<string, unknown>,
+    delimiters: [string, string] = ['[[', ']]']
+): Record<string, unknown> {
+    for (const key in values)
+        values[key] = interpolate(values[key], args, delimiters);
+
+    return values;
+}

package/src/utils/json.util.ts

@@ -0,0 +1,116 @@
+import os from 'os';
+import path from 'path';
+import { existsSync } from 'fs';
+import { readFile, writeFile } from 'fs/promises';
+
+/**
+ * Replaces undefined by null in JSON.stringify()
+ *
+ * @param {string} _ property key
+ * @param {any} value property value
+ *
+ * @returns {any} value
+ */
+const replacer = (_: string, value: any): typeof value | null =>
+    value === undefined ? null : value;
+
+/**
+ * Resolve a relative path for os.
+ *
+ * @export
+ * @param {string} filePath relative path from project root
+ *
+ * @returns {string} path
+ */
+export function resolvePath(filePath: string): string {
+    const home = os.homedir();
+
+    if (home !== undefined)
+        filePath = filePath.replace(/^~($|\/|\\)/, `${home}$1`);
+
+    return path.resolve(process.cwd(), filePath);
+}
+
+/**
+ * Reads and parses a JSON file.
+ *
+ * @export
+ * @template T
+ * @param {string} path
+ *
+ * @returns {Promise<[Record<string, any>, boolean]>}
+ */
+export async function readJson<T = Record<string, any>>(
+    path: string
+): Promise<[T | Record<string, any>, boolean] | never> {
+    if (!existsSync(path)) return [{}, false];
+
+    return [JSON.parse(await readFile(path, 'utf8')), true];
+}
+
+/**
+ * Saves a JSON into a file.
+ *
+ * @export
+ * @param {string} path
+ * @param {unknown} content
+ * @param {false} overwrite
+ * @param {false} undefinedAsNull replaces undefined by null
+ *
+ * @returns {Promise<boolean>}
+ */
+export async function writeJson(
+    path: string,
+    content: Record<string, unknown>,
+    overwrite = false,
+    undefinedAsNull = false
+): Promise<boolean | never> {
+    const exists = existsSync(path);
+
+    if (exists && !overwrite) return false;
+
+    await writeFile(
+        path,
+        `${JSON.stringify(
+            content,
+            undefinedAsNull ? replacer : undefined,
+            4
+        )}\n`,
+        'utf8'
+    );
+
+    return true;
+}
+
+/**
+ * Saves a JSON into a file as dotenv.
+ *
+ * @export
+ * @param {string} path
+ * @param {unknown} content
+ * @param {false} overwrite
+ *
+ * @returns {Promise<boolean>}
+ */
+export async function writeEnvFromJson(
+    path: string,
+    content: Record<string, unknown>,
+    overwrite = false
+): Promise<boolean | never> {
+    const exists = existsSync(path);
+
+    if (exists && !overwrite) return false;
+
+    let data = '';
+
+    for (const key in content) {
+        let value = content[key];
+        if (typeof value === 'string') value = `"${value}"`;
+
+        data += `${key}=${value}\n`;
+    }
+
+    await writeFile(path, data, 'utf8');
+
+    return true;
+}

package/{utils/logger.js → src/utils/logger.ts}

@@ -1,8 +1,9 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.logger = void 0;
-const tslog_1 = require("tslog");
-exports.logger = new tslog_1.LoggerWithoutCallSite({
+import { LoggerWithoutCallSite as Logger } from 'tslog';
+
+/**
+ * Global stdout wrap.
+ */
+export const logger = new Logger({
     displayDateTime: true,
     displayLoggerName: false,
     displayInstanceName: false,
@@ -15,4 +16,3 @@ exports.logger = new tslog_1.LoggerWithoutCallSite({
     dateTimePattern: 'hour:minute:second.millisecond',
     maskPlaceholder: '***'
 });
-//# sourceMappingURL=logger.js.map

package/src/utils/normalize.util.ts

@@ -0,0 +1,142 @@
+/**
+ * Flatten a object keeping depth path
+ * in key using __ as level separator.
+ *
+ * @param {Record<string, any>} obj
+ * @param {string} nestingDelimiter char for delimit nesting levels
+ * @param {boolean} arrayDescomposition serialize or break down arrays
+ * @param {boolean} clearNull if null should removed from object
+ * @param {string} pkey first level key
+ *
+ * @returns {Record<string, string>} flattended object
+ */
+export function flatten(
+    obj: Record<string, any>,
+    nestingDelimiter = '__',
+    pkey = ''
+): Record<string, string> {
+    const flattened: Record<string, string> = {};
+
+    for (let key in obj) {
+        const value = obj[key];
+        const type = typeof value;
+
+        if (value === undefined || type === 'function') continue;
+
+        // skipped property
+        if (key[0] === '#') continue;
+        key = pkey + key;
+
+        if (value === null || type !== 'object' || Array.isArray(value)) {
+            flattened[key] = value;
+
+            continue;
+        }
+
+        Object.assign(
+            flattened,
+            flatten(value, nestingDelimiter, `${key}${nestingDelimiter}`)
+        );
+    }
+
+    return flattened;
+}
+
+/**
+ * Normalizes env object, converts arrays in list strings,
+ * only primitives types array,
+ * and removes $ global character from keys.
+ *
+ * @param {Record<string, any>} obj
+ * @param {string} nestingDelimiter char for delimit nesting levels
+ * @param {boolean} arrayDescomposition serialize or break down arrays
+ * @param {string} pkey first level key
+ *
+ * @returns {Record<string, string>} normalized object
+ */
+export function normalize(
+    obj: Record<string, any>,
+    nestingDelimiter = '__',
+    arrayDescomposition = false,
+    pkey = ''
+): Record<string, string> {
+    const flattened: Record<string, string> = {};
+
+    for (let key in obj) {
+        const value = obj[key];
+        const type = typeof value;
+
+        if (value === null || value === undefined || type === 'function')
+            continue;
+
+        // global property, but prefix removed for injection
+        key = pkey + key.replace('$', '');
+
+        if (type !== 'object') {
+            flattened[key] = value;
+
+            continue;
+        }
+
+        if (Array.isArray(value)) {
+            normalizeArray(
+                flattened,
+                key,
+                value,
+                nestingDelimiter,
+                arrayDescomposition
+            );
+        } else {
+            Object.assign(
+                flattened,
+                normalize(
+                    value,
+                    nestingDelimiter,
+                    arrayDescomposition,
+                    `${key}${nestingDelimiter}`
+                )
+            );
+        }
+    }
+
+    return flattened;
+}
+
+/**
+ * Flatten and normalizes an array.
+ *
+ * @param {Record<string, string>} flattened
+ * @param {string} key
+ * @param {any[]} value
+ * @param {string} [nestingDelimiter='__']
+ * @param {boolean} [arrayDescomposition=false]
+ */
+function normalizeArray(
+    flattened: Record<string, string>,
+    key: string,
+    value: any[],
+    nestingDelimiter = '__',
+    arrayDescomposition = false
+): void {
+    if (arrayDescomposition) {
+        key = `${key}${nestingDelimiter}`;
+
+        for (let i = 0; i < value.length; i++) {
+            if (typeof value[i] === 'object') {
+                Object.assign(
+                    flattened,
+                    normalize(
+                        value[i],
+                        nestingDelimiter,
+                        arrayDescomposition,
+                        `${key}${i}${nestingDelimiter}`
+                    )
+                );
+            } else {
+                flattened[`${key}${i}`] = value[i];
+            }
+        }
+    } else {
+        flattened[key] = value.filter((v) => typeof v !== 'object').join(',');
+    }
+}