@agnostack/env 2.0.0-beta.1 → 2.0.0-canary.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/dist/env.d.ts +9 -9
  2. package/dist/env.js +53 -4
  3. package/dist/esm/env.js +53 -4
  4. package/package.json +17 -20
package/dist/env.d.ts CHANGED
@@ -10,21 +10,21 @@ export function lowerKeyValidator(envKey: string): boolean;
10
10
  export function publicKeyValidator(envKey: string): boolean;
11
11
  export function cleanLowerEnv(_env: Record<string, string | undefined> | undefined, keyValidator?: (envKey: string) => boolean): Record<string, string | undefined>;
12
12
  export function cleanPublicEnv(_env: Record<string, string | undefined> | undefined, keyValidator?: (envKey: string) => boolean): Record<string, string | undefined>;
13
- export function parseEnvData(_env?: NodeJS.ProcessEnv): {
13
+ export function parseEnvData(_env?: Record<string, string | undefined>): {
14
+ args: string[];
14
15
  env: Record<string, string> & {
15
16
  ENVIRONMENT: string;
16
17
  };
17
18
  nextEnv: Record<string, string | undefined>;
18
19
  publicEnv: Record<string, string | undefined>;
19
20
  stringifiedEnv: Record<string, string>;
20
- argParams: {
21
- [x: string]: string | undefined;
22
- };
23
- params: {
24
- [x: string]: string | undefined;
25
- ENVIRONMENT: string;
26
- };
27
- args: string[];
21
+ argEntries: {
22
+ arg: string;
23
+ param: string;
24
+ value: string | undefined;
25
+ }[];
26
+ argParams: Record<string, string | undefined>;
27
+ params: Record<string, string | undefined>;
28
28
  };
29
29
  export function getPublicEnvValue(publicEnv: Record<string, string | undefined> | undefined, key: string): string | undefined;
30
30
  export function replaceEnvTemplate(replaceable: unknown, { env: _env, template, callback, }?: {
package/dist/env.js CHANGED
@@ -52,7 +52,7 @@ const cleanEnv = (_env, keyValidator = exports.nextKeyValidator) => (Object.entr
52
52
  * @param {(envKey: string) => boolean} [keyValidator]
53
53
  * @returns {Record<string, string | undefined>}
54
54
  */
55
- const cleanLowerEnv = (_env, keyValidator = exports.lowerKeyValidator) => (cleanEnv(process.env, keyValidator));
55
+ const cleanLowerEnv = (_env, keyValidator = exports.lowerKeyValidator) => (cleanEnv(_env, keyValidator));
56
56
  exports.cleanLowerEnv = cleanLowerEnv;
57
57
  /**
58
58
  * @param {Record<string, string | undefined> | undefined} _env
@@ -61,6 +61,39 @@ exports.cleanLowerEnv = cleanLowerEnv;
61
61
  */
62
62
  const cleanPublicEnv = (_env, keyValidator = exports.publicKeyValidator) => (cleanEnv(_env, keyValidator));
63
63
  exports.cleanPublicEnv = cleanPublicEnv;
64
+ /**
65
+ * The one place argv and the ambient env are read together, so a caller gets both from a single
66
+ * call rather than parsing argv itself.
67
+ *
68
+ * ENVIRONMENT is resolved rather than trusted: an explicit `ENVIRONMENT` wins, otherwise the first
69
+ * non-empty of SITE_ENV, BUILD_ENV, NODE_ENV, falling back to 'development'.
70
+ *
71
+ * ⚠️ The argv split is by FORM, not by meaning. `--key=value` becomes an `argParams` entry; a
72
+ * valueless `--flag` stays a string in `args`, which also still holds `process.argv[0]` (the node
73
+ * binary) and `[1]` (the script path). A caller reading positionals must skip those two, and one
74
+ * reading bare flags must look in `args` rather than `argParams`.
75
+ *
76
+ * `argEntries` is the third view: every argument in order — `arg` as typed, `param` and `value`
77
+ * already split out — so a
78
+ * caller can forward what it did not consume without re-deriving it. An ARRAY rather than a map
79
+ * because repeats are meaningful — `--context=a=1 --context=b=2` is two entries, and keying them
80
+ * would silently keep only the last.
81
+ *
82
+ * `stringifiedEnv` is a MAP, not a string — each value JSON-stringified, which is the shape
83
+ * webpack's DefinePlugin wants.
84
+ *
85
+ * @param {Record<string, string | undefined>} [_env] defaults to process.env
86
+ * @returns {{
87
+ * args: string[],
88
+ * env: Record<string, string> & { ENVIRONMENT: string },
89
+ * nextEnv: Record<string, string | undefined>,
90
+ * publicEnv: Record<string, string | undefined>,
91
+ * stringifiedEnv: Record<string, string>,
92
+ * argEntries: { arg: string, param: string, value: string | undefined }[],
93
+ * argParams: Record<string, string | undefined>,
94
+ * params: Record<string, string | undefined>,
95
+ * }}
96
+ */
64
97
  const parseEnvData = (_env = process.env) => {
65
98
  var _a;
66
99
  const { ENVIRONMENT, SITE_ENV, BUILD_ENV, NODE_ENV } = _env;
@@ -73,7 +106,10 @@ const parseEnvData = (_env = process.env) => {
73
106
  const mergedEnv = Object.assign(Object.assign({}, _env), {
74
107
  // NOTE: intentionally giving precedence to ENVIRONMENT
75
108
  ENVIRONMENT: ENVIRONMENT || _environment });
76
- const _b = process.argv.reduce(({ args: _args, argParams: _argParams, }, arg) => {
109
+ // NOTE: One pass over argv building both halves of the split — `args` collects every entry that
110
+ // carried no value (bare flags, positionals, and argv[0]/[1]), `argParams` every `key=value` one
111
+ // with its leading `--` stripped. An entry is never in both.
112
+ const _b = process.argv.reduce(({ args: _args, argParams: _argParams, argEntries: _argEntries, }, arg, index) => {
77
113
  var _a, _b, _c, _d, _e;
78
114
  // NOTE: split on the FIRST '=' only — everything after it is the value, verbatim.
79
115
  // Splitting on every '=' truncated any value that contained one, so `--context=env=prod`
@@ -82,11 +118,14 @@ const parseEnvData = (_env = process.env) => {
82
118
  const [__param, _value] = (separatorIndex === -1)
83
119
  ? [arg, undefined]
84
120
  : [arg.slice(0, separatorIndex), arg.slice(separatorIndex + 1)];
85
- const _param = (_c = __param === null || __param === void 0 ? void 0 : __param.replace) === null || _c === void 0 ? void 0 : _c.call(__param, '--', '');
121
+ // NOTE: anchored. A bare `.replace('--', '')` strips the first `--` ANYWHERE, so
122
+ // `my--param=x` arrived as `myparam`. Only a leading `--` is a flag marker.
123
+ const _param = (_c = __param === null || __param === void 0 ? void 0 : __param.replace) === null || _c === void 0 ? void 0 : _c.call(__param, /^--/, '');
86
124
  if ((0, display_js_1.stringEmptyOnly)(_param)) {
87
125
  return {
88
126
  args: _args,
89
127
  argParams: _argParams,
128
+ argEntries: _argEntries,
90
129
  };
91
130
  }
92
131
  /** @type {[string, string | undefined]} */
@@ -108,10 +147,20 @@ const parseEnvData = (_env = process.env) => {
108
147
  argParams: Object.assign(Object.assign({}, _argParams), (0, display_js_1.stringNotEmptyOnly)(value) && {
109
148
  [param]: value,
110
149
  }),
150
+ // NOTE: index 0 is the node binary and 1 the script path — never arguments, so neither
151
+ // reaches argEntries. That is what lets a caller forward `arg` without re-deriving which
152
+ // entries were real arguments.
153
+ argEntries: [
154
+ ..._argEntries,
155
+ ...(index >= 2) ? [{ arg, param, value }] : []
156
+ ],
111
157
  };
112
158
  }, {
113
159
  args: /** @type {string[]} */ ([]),
114
- argParams: /** @type {Record<string, string>} */ ({}),
160
+ // NOTE: `string | undefined` because the conditional spread below can widen it — seeding it
161
+ // as `Record<string, string>` made the accumulator and the callback's return disagree.
162
+ argParams: /** @type {Record<string, string | undefined>} */ ({}),
163
+ argEntries: /** @type {{ arg: string, param: string, value: string | undefined }[]} */ ([]),
115
164
  }), { argParams } = _b, output = __rest(_b, ["argParams"]);
116
165
  const nextEnv = cleanEnv(mergedEnv);
117
166
  const publicEnv = (0, exports.cleanPublicEnv)(mergedEnv);
package/dist/esm/env.js CHANGED
@@ -46,13 +46,46 @@ const cleanEnv = (_env, keyValidator = nextKeyValidator) => (Object.entries(_env
46
46
  * @param {(envKey: string) => boolean} [keyValidator]
47
47
  * @returns {Record<string, string | undefined>}
48
48
  */
49
- export const cleanLowerEnv = (_env, keyValidator = lowerKeyValidator) => (cleanEnv(process.env, keyValidator));
49
+ export const cleanLowerEnv = (_env, keyValidator = lowerKeyValidator) => (cleanEnv(_env, keyValidator));
50
50
  /**
51
51
  * @param {Record<string, string | undefined> | undefined} _env
52
52
  * @param {(envKey: string) => boolean} [keyValidator]
53
53
  * @returns {Record<string, string | undefined>}
54
54
  */
55
55
  export const cleanPublicEnv = (_env, keyValidator = publicKeyValidator) => (cleanEnv(_env, keyValidator));
56
+ /**
57
+ * The one place argv and the ambient env are read together, so a caller gets both from a single
58
+ * call rather than parsing argv itself.
59
+ *
60
+ * ENVIRONMENT is resolved rather than trusted: an explicit `ENVIRONMENT` wins, otherwise the first
61
+ * non-empty of SITE_ENV, BUILD_ENV, NODE_ENV, falling back to 'development'.
62
+ *
63
+ * ⚠️ The argv split is by FORM, not by meaning. `--key=value` becomes an `argParams` entry; a
64
+ * valueless `--flag` stays a string in `args`, which also still holds `process.argv[0]` (the node
65
+ * binary) and `[1]` (the script path). A caller reading positionals must skip those two, and one
66
+ * reading bare flags must look in `args` rather than `argParams`.
67
+ *
68
+ * `argEntries` is the third view: every argument in order — `arg` as typed, `param` and `value`
69
+ * already split out — so a
70
+ * caller can forward what it did not consume without re-deriving it. An ARRAY rather than a map
71
+ * because repeats are meaningful — `--context=a=1 --context=b=2` is two entries, and keying them
72
+ * would silently keep only the last.
73
+ *
74
+ * `stringifiedEnv` is a MAP, not a string — each value JSON-stringified, which is the shape
75
+ * webpack's DefinePlugin wants.
76
+ *
77
+ * @param {Record<string, string | undefined>} [_env] defaults to process.env
78
+ * @returns {{
79
+ * args: string[],
80
+ * env: Record<string, string> & { ENVIRONMENT: string },
81
+ * nextEnv: Record<string, string | undefined>,
82
+ * publicEnv: Record<string, string | undefined>,
83
+ * stringifiedEnv: Record<string, string>,
84
+ * argEntries: { arg: string, param: string, value: string | undefined }[],
85
+ * argParams: Record<string, string | undefined>,
86
+ * params: Record<string, string | undefined>,
87
+ * }}
88
+ */
56
89
  export const parseEnvData = (_env = process.env) => {
57
90
  var _a;
58
91
  const { ENVIRONMENT, SITE_ENV, BUILD_ENV, NODE_ENV } = _env;
@@ -65,7 +98,10 @@ export const parseEnvData = (_env = process.env) => {
65
98
  const mergedEnv = Object.assign(Object.assign({}, _env), {
66
99
  // NOTE: intentionally giving precedence to ENVIRONMENT
67
100
  ENVIRONMENT: ENVIRONMENT || _environment });
68
- const _b = process.argv.reduce(({ args: _args, argParams: _argParams, }, arg) => {
101
+ // NOTE: One pass over argv building both halves of the split — `args` collects every entry that
102
+ // carried no value (bare flags, positionals, and argv[0]/[1]), `argParams` every `key=value` one
103
+ // with its leading `--` stripped. An entry is never in both.
104
+ const _b = process.argv.reduce(({ args: _args, argParams: _argParams, argEntries: _argEntries, }, arg, index) => {
69
105
  var _a, _b, _c, _d, _e;
70
106
  // NOTE: split on the FIRST '=' only — everything after it is the value, verbatim.
71
107
  // Splitting on every '=' truncated any value that contained one, so `--context=env=prod`
@@ -74,11 +110,14 @@ export const parseEnvData = (_env = process.env) => {
74
110
  const [__param, _value] = (separatorIndex === -1)
75
111
  ? [arg, undefined]
76
112
  : [arg.slice(0, separatorIndex), arg.slice(separatorIndex + 1)];
77
- const _param = (_c = __param === null || __param === void 0 ? void 0 : __param.replace) === null || _c === void 0 ? void 0 : _c.call(__param, '--', '');
113
+ // NOTE: anchored. A bare `.replace('--', '')` strips the first `--` ANYWHERE, so
114
+ // `my--param=x` arrived as `myparam`. Only a leading `--` is a flag marker.
115
+ const _param = (_c = __param === null || __param === void 0 ? void 0 : __param.replace) === null || _c === void 0 ? void 0 : _c.call(__param, /^--/, '');
78
116
  if (stringEmptyOnly(_param)) {
79
117
  return {
80
118
  args: _args,
81
119
  argParams: _argParams,
120
+ argEntries: _argEntries,
82
121
  };
83
122
  }
84
123
  /** @type {[string, string | undefined]} */
@@ -100,10 +139,20 @@ export const parseEnvData = (_env = process.env) => {
100
139
  argParams: Object.assign(Object.assign({}, _argParams), stringNotEmptyOnly(value) && {
101
140
  [param]: value,
102
141
  }),
142
+ // NOTE: index 0 is the node binary and 1 the script path — never arguments, so neither
143
+ // reaches argEntries. That is what lets a caller forward `arg` without re-deriving which
144
+ // entries were real arguments.
145
+ argEntries: [
146
+ ..._argEntries,
147
+ ...(index >= 2) ? [{ arg, param, value }] : []
148
+ ],
103
149
  };
104
150
  }, {
105
151
  args: /** @type {string[]} */ ([]),
106
- argParams: /** @type {Record<string, string>} */ ({}),
152
+ // NOTE: `string | undefined` because the conditional spread below can widen it — seeding it
153
+ // as `Record<string, string>` made the accumulator and the callback's return disagree.
154
+ argParams: /** @type {Record<string, string | undefined>} */ ({}),
155
+ argEntries: /** @type {{ arg: string, param: string, value: string | undefined }[]} */ ([]),
107
156
  }), { argParams } = _b, output = __rest(_b, ["argParams"]);
108
157
  const nextEnv = cleanEnv(mergedEnv);
109
158
  const publicEnv = cleanPublicEnv(mergedEnv);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@agnostack/env",
3
- "version": "2.0.0-beta.1",
3
+ "version": "2.0.0-canary.10",
4
4
  "author": "agnoStack Dev <developers@agnostack.com> (https://agnostack.com)",
5
5
  "owner": "agnoStack",
6
6
  "description": "Please contact agnoStack via info@agnostack.com for any questions",
@@ -39,21 +39,20 @@
39
39
  "node": ">=22.x"
40
40
  },
41
41
  "scripts": {
42
- "tsc": "npx -p typescript tsc",
43
- "watch": "yarn tsc -p tsconfig.build.json -w",
44
- "prebuild": "yarn tsc -b tsconfig.build.json --clean && node scripts/clean.mjs dist _storage",
45
- "build": "yarn tsc -p tsconfig.build.json && yarn tsc -p tsconfig.esm.json && node scripts/write-esm-pkg.mjs",
42
+ "watch": "tsc -p tsconfig.build.json -w",
43
+ "prebuild": "tsc -b tsconfig.build.json --clean && node scripts/clean.mjs dist _storage",
44
+ "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.esm.json && node scripts/write-esm-pkg.mjs",
46
45
  "clean": "node scripts/clean.mjs dist node_modules _storage",
47
- "clean:install": "yarn clean && yarn install --force",
46
+ "clean:install": "pnpm clean && pnpm install --force",
48
47
  "lint:fix": "eslint . --fix",
49
48
  "lint": "eslint .",
50
- "typecheck": "yarn tsc",
49
+ "typecheck": "tsc --noEmit",
51
50
  "verify:dist": "node scripts/verify-dist.mjs",
52
51
  "test:watch": "vitest",
53
52
  "test": "vitest run",
54
53
  "release": "semantic-release",
55
- "release:debug": "yarn release --debug",
56
- "prepublishOnly": "yarn verify:dist",
54
+ "release:debug": "pnpm release --debug",
55
+ "prepublishOnly": "node scripts/verify-dist.mjs",
57
56
  "prepare": "husky"
58
57
  },
59
58
  "lint-staged": {
@@ -63,14 +62,11 @@
63
62
  },
64
63
  "sideEffects": false,
65
64
  "devDependencies": {
66
- "@commitlint/cli": "19.x",
67
- "@commitlint/config-conventional": "19.x",
65
+ "@commitlint/cli": "21.x",
66
+ "@commitlint/config-conventional": "21.x",
68
67
  "@eslint/js": "9.x",
69
- "@semantic-release/changelog": "6.0.3",
70
- "@semantic-release/git": "10.0.1",
71
- "@semantic-release/github": "11.x",
72
- "@semantic-release/npm": "12.x",
73
- "@semantic-release/release-notes-generator": "14.x",
68
+ "@semantic-release/changelog": "7.x",
69
+ "@semantic-release/git": "11.x",
74
70
  "@types/node": "22.x",
75
71
  "@typescript-eslint/eslint-plugin": "8.x",
76
72
  "@typescript-eslint/parser": "8.x",
@@ -78,13 +74,14 @@
78
74
  "eslint-plugin-import": "2.x",
79
75
  "globals": "16.x",
80
76
  "husky": "9.x",
81
- "lint-staged": "15.x",
77
+ "lint-staged": "17.x",
82
78
  "semantic-release": "25.x",
83
- "typescript": "5.9.3",
84
- "vitest": "3.x"
79
+ "semantic-release-export-data": "1.x",
80
+ "typescript": "5.x",
81
+ "vitest": "4.x"
85
82
  },
86
83
  "publishConfig": {
87
84
  "access": "public"
88
85
  },
89
- "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
86
+ "packageManager": "pnpm@9.15.4"
90
87
  }