@powerlines/plugin-env 0.16.57 → 0.16.58

package/dist/types/plugin.d.mts

@@ -0,0 +1,168 @@
+import { EnvInterface, SecretsInterface } from "./runtime.mjs";
+import { BabelPluginContext, BabelPluginOptions, BabelPluginResolvedConfig, BabelPluginUserConfig } from "@powerlines/plugin-babel/types";
+import { AutoMDPluginOptions } from "@powerlines/plugin-automd/types/plugin";
+import { AlloyPluginContext, AlloyPluginOptions, AlloyPluginResolvedConfig, AlloyPluginUserConfig } from "@powerlines/plugin-alloy/types";
+import { Reflection } from "@powerlines/deepkit/types";
+import { DotenvParseOutput } from "@stryke/env/types";
+import { Children } from "@alloy-js/core";
+import { DotenvConfiguration, TypeDefinition, TypeDefinitionParameter } from "@stryke/types/configuration";
+
+//#region src/types/plugin.d.ts
+type EnvType = "env" | "secrets";
+type EnvPluginOptions = Omit<DotenvConfiguration, "types"> & {
+  /**
+   * A path to the type definition for the expected env configuration parameters. This value can include both a path to the typescript file and the name of the type definition to use separated by a `":"` or `"#"` character. For example: `"./src/types/env.ts#ConfigConfiguration"`.
+   */
+  types?: TypeDefinitionParameter;
+  /**
+   * A path to the type definition for the expected env secret parameters. This value can include both a path to the typescript file and the name of the type definition to use separated by a `":"` or `"#"` character. For example: `"./src/types/env.ts#ConfigSecrets"`.
+   */
+  secrets?: TypeDefinitionParameter;
+  /**
+   * An additional prefix (or list of additional prefixes) to apply to the environment variables
+   *
+   * @remarks
+   * By default, the plugin will use the `POWERLINES_` prefix. This option is useful for avoiding conflicts with other environment variables.
+   */
+  prefix?: string | string[];
+  /**
+   * Should the plugin inject the env variables in the source code with their values?
+   *
+   * @defaultValue false
+   */
+  inject?: boolean;
+  /**
+   * Should the plugin validate the loaded environment variables against the provided type definitions?
+   *
+   * @defaultValue false
+   */
+  validate?: boolean;
+  /**
+   * The default configuration to use when loading environment variables.
+   *
+   * @remarks
+   * This configuration is used as the base configuration when loading environment variables, and will be overridden by any values found in the `.env` file or the process environment.
+   */
+  defaultConfig?: Children;
+  /**
+   * Babel configuration options to use when injecting environment variables into the source code.
+   *
+   * @remarks
+   * This option allows you to customize the Babel transformation process used to inject environment variables into the source code. If not provided, the plugin will use default Babel settings.
+   */
+  babel?: BabelPluginOptions;
+  /**
+   * AutoMD configuration options to allow injecting environment variables documentation into a markdown file such as a README.md.
+   *
+   * @remarks
+   * The README.md file should contain the `<!-- automd:env --><!-- /automd -->` comment block where the documentation will be injected.
+   */
+  automd?: AutoMDPluginOptions;
+  /**
+   * Alloy configuration options to use when injecting environment variables into the source code.
+   *
+   * @remarks
+   * This option allows you to customize the Alloy transformation process used to inject environment variables into the source code. If not provided, the plugin will use default Alloy settings.
+   */
+  alloy?: AlloyPluginOptions;
+};
+type EnvPluginUserConfig = BabelPluginUserConfig & AlloyPluginUserConfig & {
+  env: EnvPluginOptions;
+};
+type EnvPluginResolvedConfig = BabelPluginResolvedConfig & AlloyPluginResolvedConfig & {
+  env: Required<Pick<DotenvConfiguration, "additionalFiles">> & Required<Pick<EnvPluginOptions, "defaultConfig">> & {
+    /**
+     * The type definition for the expected env variable parameters
+     *
+     * @remarks
+     * This value is parsed from the {@link EnvPluginOptions.types} option.
+     */
+    types: TypeDefinition;
+    /**
+     * The type definition for the expected env secret parameters
+     *
+     * @remarks
+     * This value is parsed from the {@link EnvPluginOptions.secrets} option.
+     */
+    secrets: TypeDefinition;
+    /**
+     * Should the plugin inject the env variables in the source code with their values?
+     *
+     * @remarks
+     * This value is the result of reflecting the {@link EnvPluginOptions.inject} option.
+     */
+    inject: boolean;
+    /**
+     * Should the plugin validate the loaded environment variables against the provided type definitions?
+     *
+     * @remarks
+     * This value is the result of reflecting the {@link EnvPluginOptions.validate} option.
+     */
+    validate: boolean;
+    /**
+     * The prefix used for environment variables
+     *
+     * @remarks
+     * This value is used to filter environment variables that are loaded from the .env file and the process environment.
+     */
+    prefix: string[];
+  };
+};
+interface EnvPluginContext<TResolvedConfig extends EnvPluginResolvedConfig = EnvPluginResolvedConfig> extends BabelPluginContext<TResolvedConfig>, AlloyPluginContext<TResolvedConfig> {
+  env: {
+    /**
+     * The type definitions reflection for the env variables and secrets
+     *
+     * @remarks
+     * These reflections contains the structure of the expected environment variables and secrets as defined by the type definitions provided in the plugin configuration.
+     */
+    types: {
+      /**
+       * The type definitions for the expected env variables
+       */
+      env: Reflection;
+      /**
+       * The type definitions for the expected env secrets
+       */
+      secrets: Reflection;
+    };
+    /**
+     * The current **used** environment variables and secrets reflection
+     *
+     * @remarks
+     * This reflection contains the structure of the current environment variables and secrets as defined during the plugin initialization by extracting the values from the source code.
+     */
+    used: {
+      /**
+       * The current env variables reflection
+       */
+      env: Reflection<EnvInterface>;
+      /**
+       * The current env secrets reflection
+       */
+      secrets: Reflection<SecretsInterface>;
+    };
+    /**
+     * The parsed .env configuration object
+     *
+     * @remarks
+     * This value is the result of loading the .env configuration file found in the project root directory and merging it with the values provided at {@link EnvPluginOptions.values}
+     */
+    parsed: DotenvParseOutput;
+    /**
+     * The injected environment variables and secrets reflection
+     *
+     * @remarks
+     * This reflection contains the structure of the injected environment variables and secrets that were injected into the source code during the build process.
+     */
+    injected: Reflection;
+  };
+}
+declare type __ΩEnvType = any[];
+declare type __ΩEnvPluginOptions = any[];
+declare type __ΩEnvPluginUserConfig = any[];
+declare type __ΩEnvPluginResolvedConfig = any[];
+declare type __ΩEnvPluginContext = any[];
+//#endregion
+export { EnvPluginContext, EnvPluginOptions, EnvPluginResolvedConfig, EnvPluginUserConfig, EnvType, __ΩEnvPluginContext, __ΩEnvPluginOptions, __ΩEnvPluginResolvedConfig, __ΩEnvPluginUserConfig, __ΩEnvType };
+//# sourceMappingURL=plugin.d.mts.map

package/dist/types/plugin.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.mts","names":[],"sources":["../../src/types/plugin.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;KAyCY,OAAA;KAEA,gBAAA,GAAmB,KAAK;EAFxB;AAEZ;;EAA+B,KAAA,CAAA,EAIrB,uBAJqB;EAIrB;;;EA2CA,OAAA,CAAA,EAtCE,uBAsCF;EAQC;;;AAWX;;;EAES,MAAA,CAAA,EAAA,MAAA,GAAA,MAAA,EAAA;EAAgB;AAGzB;;;;EAEkB,MAAA,CAAA,EAAA,OAAA;EAAT;;;;;EAgBQ,QAAA,CAAA,EAAA,OAAA;EAAc;AA4B/B;;;;;EAiBW,aAAA,CAAA,EA/FO,QA+FP;EAKI;;;;;;EAmCD,KAAA,CAAA,EA/HJ,kBA+HI;EArDV;;;;;;WAlEO;;;;;;;UAQD;;KAGE,mBAAA,GAAsB,wBAChC;OACO;;KAGG,uBAAA,GAA0B,4BACpC;OACO,SAAS,KAAK,2CACjB,SAAS,KAAK;;;;;;;WAOL;;;;;;;aAQE;;;;;;;;;;;;;;;;;;;;;;;;UA4BA,yCACS,0BAA0B,iCAGhD,mBAAmB,kBACnB,mBAAmB;;;;;;;;;;;;WAYZ;;;;eAKI;;;;;;;;;;;;WAaJ,WAAW;;;;eAKP,WAAW;;;;;;;;YASd;;;;;;;cAQE"}

package/dist/types/plugin.mjs

@@ -128,4 +128,5 @@ const __ΩEnvPluginContext = [
 ];
 
 //#endregion
-export { __ΩEnvPluginContext, __ΩEnvPluginOptions, __ΩEnvPluginResolvedConfig, __ΩEnvPluginUserConfig, __ΩEnvType };
+export { __ΩEnvPluginContext, __ΩEnvPluginOptions, __ΩEnvPluginResolvedConfig, __ΩEnvPluginUserConfig, __ΩEnvType };
+//# sourceMappingURL=plugin.mjs.map

package/dist/types/plugin.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.mjs","names":[],"sources":["../../src/types/plugin.ts"],"sourcesContent":["/* -------------------------------------------------------------------\n\n                   ⚡ Storm Software - Powerlines\n\n This code was released as part of the Powerlines project. Powerlines\n is maintained by Storm Software under the Apache-2.0 license, and is\n free for commercial and private use. For more information, please visit\n our licensing page at https://stormsoftware.com/licenses/projects/powerlines.\n\n Website:                  https://stormsoftware.com\n Repository:               https://github.com/storm-software/powerlines\n Documentation:            https://docs.stormsoftware.com/projects/powerlines\n Contact:                  https://stormsoftware.com/contact\n\n SPDX-License-Identifier:  Apache-2.0\n\n ------------------------------------------------------------------- */\n\nimport { Children } from \"@alloy-js/core\";\nimport { Reflection } from \"@powerlines/deepkit/types\";\nimport {\n  AlloyPluginContext,\n  AlloyPluginOptions,\n  AlloyPluginResolvedConfig,\n  AlloyPluginUserConfig\n} from \"@powerlines/plugin-alloy/types\";\nimport { AutoMDPluginOptions } from \"@powerlines/plugin-automd/types/plugin\";\nimport {\n  BabelPluginContext,\n  BabelPluginOptions,\n  BabelPluginResolvedConfig,\n  BabelPluginUserConfig\n} from \"@powerlines/plugin-babel/types\";\nimport type { DotenvParseOutput } from \"@stryke/env/types\";\nimport {\n  DotenvConfiguration,\n  TypeDefinition,\n  TypeDefinitionParameter\n} from \"@stryke/types/configuration\";\nimport { EnvInterface, SecretsInterface } from \"./runtime\";\n\nexport type EnvType = \"env\" | \"secrets\";\n\nexport type EnvPluginOptions = Omit<DotenvConfiguration, \"types\"> & {\n  /**\n   * A path to the type definition for the expected env configuration parameters. This value can include both a path to the typescript file and the name of the type definition to use separated by a `\":\"` or `\"#\"` character. For example: `\"./src/types/env.ts#ConfigConfiguration\"`.\n   */\n  types?: TypeDefinitionParameter;\n\n  /**\n   * A path to the type definition for the expected env secret parameters. This value can include both a path to the typescript file and the name of the type definition to use separated by a `\":\"` or `\"#\"` character. For example: `\"./src/types/env.ts#ConfigSecrets\"`.\n   */\n  secrets?: TypeDefinitionParameter;\n\n  /**\n   * An additional prefix (or list of additional prefixes) to apply to the environment variables\n   *\n   * @remarks\n   * By default, the plugin will use the `POWERLINES_` prefix. This option is useful for avoiding conflicts with other environment variables.\n   */\n  prefix?: string | string[];\n\n  /**\n   * Should the plugin inject the env variables in the source code with their values?\n   *\n   * @defaultValue false\n   */\n  inject?: boolean;\n\n  /**\n   * Should the plugin validate the loaded environment variables against the provided type definitions?\n   *\n   * @defaultValue false\n   */\n  validate?: boolean;\n\n  /**\n   * The default configuration to use when loading environment variables.\n   *\n   * @remarks\n   * This configuration is used as the base configuration when loading environment variables, and will be overridden by any values found in the `.env` file or the process environment.\n   */\n  defaultConfig?: Children;\n\n  /**\n   * Babel configuration options to use when injecting environment variables into the source code.\n   *\n   * @remarks\n   * This option allows you to customize the Babel transformation process used to inject environment variables into the source code. If not provided, the plugin will use default Babel settings.\n   */\n  babel?: BabelPluginOptions;\n\n  /**\n   * AutoMD configuration options to allow injecting environment variables documentation into a markdown file such as a README.md.\n   *\n   * @remarks\n   * The README.md file should contain the `<!-- automd:env --><!-- /automd -->` comment block where the documentation will be injected.\n   */\n  automd?: AutoMDPluginOptions;\n\n  /**\n   * Alloy configuration options to use when injecting environment variables into the source code.\n   *\n   * @remarks\n   * This option allows you to customize the Alloy transformation process used to inject environment variables into the source code. If not provided, the plugin will use default Alloy settings.\n   */\n  alloy?: AlloyPluginOptions;\n};\n\nexport type EnvPluginUserConfig = BabelPluginUserConfig &\n  AlloyPluginUserConfig & {\n    env: EnvPluginOptions;\n  };\n\nexport type EnvPluginResolvedConfig = BabelPluginResolvedConfig &\n  AlloyPluginResolvedConfig & {\n    env: Required<Pick<DotenvConfiguration, \"additionalFiles\">> &\n      Required<Pick<EnvPluginOptions, \"defaultConfig\">> & {\n        /**\n         * The type definition for the expected env variable parameters\n         *\n         * @remarks\n         * This value is parsed from the {@link EnvPluginOptions.types} option.\n         */\n        types: TypeDefinition;\n\n        /**\n         * The type definition for the expected env secret parameters\n         *\n         * @remarks\n         * This value is parsed from the {@link EnvPluginOptions.secrets} option.\n         */\n        secrets: TypeDefinition;\n\n        /**\n         * Should the plugin inject the env variables in the source code with their values?\n         *\n         * @remarks\n         * This value is the result of reflecting the {@link EnvPluginOptions.inject} option.\n         */\n        inject: boolean;\n\n        /**\n         * Should the plugin validate the loaded environment variables against the provided type definitions?\n         *\n         * @remarks\n         * This value is the result of reflecting the {@link EnvPluginOptions.validate} option.\n         */\n        validate: boolean;\n\n        /**\n         * The prefix used for environment variables\n         *\n         * @remarks\n         * This value is used to filter environment variables that are loaded from the .env file and the process environment.\n         */\n        prefix: string[];\n      };\n  };\n\nexport interface EnvPluginContext<\n  TResolvedConfig extends EnvPluginResolvedConfig = EnvPluginResolvedConfig\n>\n  extends\n    BabelPluginContext<TResolvedConfig>,\n    AlloyPluginContext<TResolvedConfig> {\n  env: {\n    /**\n     * The type definitions reflection for the env variables and secrets\n     *\n     * @remarks\n     * These reflections contains the structure of the expected environment variables and secrets as defined by the type definitions provided in the plugin configuration.\n     */\n    types: {\n      /**\n       * The type definitions for the expected env variables\n       */\n      env: Reflection;\n\n      /**\n       * The type definitions for the expected env secrets\n       */\n      secrets: Reflection;\n    };\n\n    /**\n     * The current **used** environment variables and secrets reflection\n     *\n     * @remarks\n     * This reflection contains the structure of the current environment variables and secrets as defined during the plugin initialization by extracting the values from the source code.\n     */\n    used: {\n      /**\n       * The current env variables reflection\n       */\n      env: Reflection<EnvInterface>;\n\n      /**\n       * The current env secrets reflection\n       */\n      secrets: Reflection<SecretsInterface>;\n    };\n\n    /**\n     * The parsed .env configuration object\n     *\n     * @remarks\n     * This value is the result of loading the .env configuration file found in the project root directory and merging it with the values provided at {@link EnvPluginOptions.values}\n     */\n    parsed: DotenvParseOutput;\n\n    /**\n     * The injected environment variables and secrets reflection\n     *\n     * @remarks\n     * This reflection contains the structure of the injected environment variables and secrets that were injected into the source code during the build process.\n     */\n    injected: Reflection;\n  };\n}\n"],"mappings":";;;;;;;AAAA,MAAM,UAAU;CAAC;CAAK;OAAW;OAAe;CAAY;CAAQ;CAAC;;;;;;AAErE,MAAM,UAAU;CAAC;CAAK;CAAK;CAAQ;CAAY;;;;;;;AA0B/C,MAAM,aAAa;CAAC;CAAA;CAAA;CAAA;CAAA;AAEpB,MAAM,sBAAqB;OAAA;CAAA;CAAA;CAAA;CAAA;CAAA;CAAA;CAAA;CAAA;CAAA;CAAA;CAAA;CAAA;CAAA;CAAA;CAAA;OAAA;CAAA;CAAA;OAAA;CAAA;CAAA;OAAA;CAAA;CAAA;CAAA;CAAA;CAAA;AAE3B,MAAM,yBAAyB;OAAO;OAAC;OAAA;CAAA;CAAA;CAAA;CAAA;AAEvC,MAAM,6BAAC;OAAA;OAAA;OAAA;OAAA;CAAA;OAAA;OAAA;OAAA;CAAA;CAAA;CAAA;CAAA;CAAA;CAAA;CAAA;CAAA;CAAA;CAAA;CAAA;CAAA;CAAA;CAAA;CAAA;AAEP,MAAM,sBAAU;OAAA;CAAA;OAAA;OAAA;OAAA;CAAA;CAAA;OAAA;CAAA;CAAA;CAAA;CAAA;OAAA;OAAA;CAAA;OAAA;OAAA;CAAA;CAAA;CAAA;CAAA;CAAA;OAAA;CAAA;CAAA;CAAA;CAAA;CAAA"}