@celljs/core 3.9.0 → 4.0.0
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.
- package/cell.remote.yml +8 -0
- package/cell.yml +0 -3
- package/esm/common/application/application-entry.js +21 -3
- package/esm/common/application/application-entry.js.map +1 -1
- package/esm/common/application/application-host.d.ts +38 -0
- package/esm/common/application/application-host.js +17 -0
- package/esm/common/application/application-host.js.map +1 -0
- package/esm/common/application/index.d.ts +1 -0
- package/esm/common/application/index.js +1 -0
- package/esm/common/application/index.js.map +1 -1
- package/esm/common/config/env-config-util.d.ts +48 -0
- package/esm/common/config/env-config-util.js +185 -0
- package/esm/common/config/env-config-util.js.map +1 -0
- package/esm/common/config/index.d.ts +1 -0
- package/esm/common/config/index.js +1 -0
- package/esm/common/config/index.js.map +1 -1
- package/lib/common/application/application-entry.d.ts.map +1 -1
- package/lib/common/application/application-entry.js +21 -3
- package/lib/common/application/application-entry.js.map +1 -1
- package/lib/common/application/application-host.d.ts +39 -0
- package/lib/common/application/application-host.d.ts.map +1 -0
- package/lib/common/application/application-host.js +20 -0
- package/lib/common/application/application-host.js.map +1 -0
- package/lib/common/application/index.d.ts +1 -0
- package/lib/common/application/index.d.ts.map +1 -1
- package/lib/common/application/index.js +1 -0
- package/lib/common/application/index.js.map +1 -1
- package/lib/common/config/env-config-util.d.ts +49 -0
- package/lib/common/config/env-config-util.d.ts.map +1 -0
- package/lib/common/config/env-config-util.js +188 -0
- package/lib/common/config/env-config-util.js.map +1 -0
- package/lib/common/config/env-config-util.spec.d.ts +2 -0
- package/lib/common/config/env-config-util.spec.d.ts.map +1 -0
- package/lib/common/config/env-config-util.spec.js +314 -0
- package/lib/common/config/env-config-util.spec.js.map +1 -0
- package/lib/common/config/index.d.ts +1 -0
- package/lib/common/config/index.d.ts.map +1 -1
- package/lib/common/config/index.js +1 -0
- package/lib/common/config/index.js.map +1 -1
- package/package.json +14 -25
- package/src/common/application/application-entry.ts +20 -4
- package/src/common/application/application-host.ts +46 -0
- package/src/common/application/index.ts +1 -0
- package/src/common/config/env-config-util.spec.ts +341 -0
- package/src/common/config/env-config-util.ts +225 -0
- package/src/common/config/index.ts +1 -0
- package/cell-remote.yml +0 -3
|
@@ -0,0 +1,225 @@
|
|
|
1
|
+
/** An environment variable that was applied to the configuration. */
|
|
2
|
+
export interface EnvOverride {
|
|
3
|
+
variable: string;
|
|
4
|
+
/** Dotted path of the overridden key, e.g. `cell.server.port`. */
|
|
5
|
+
path: string;
|
|
6
|
+
/**
|
|
7
|
+
* Set when the first key also exists under `cell`: the top-level key wins, and this is the path
|
|
8
|
+
* under `cell` that the variable does not set (reach it with `CELL_<TARGET>__CELL__...`).
|
|
9
|
+
*/
|
|
10
|
+
shadows?: string;
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
/** An environment variable with the override prefix that could not be applied. */
|
|
14
|
+
export interface EnvOverrideProblem {
|
|
15
|
+
variable: string;
|
|
16
|
+
message: string;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
export interface EnvOverrideResult {
|
|
20
|
+
applied: EnvOverride[];
|
|
21
|
+
problems: EnvOverrideProblem[];
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* Overrides configuration keys from environment variables: `CELL_BACKEND__SERVER__PORT=8080` sets
|
|
26
|
+
* `cell.server.port` of the backend. Segments are separated by `__` and matched against existing
|
|
27
|
+
* keys ignoring case, `_` and `-` (`ORM_CONFIG` matches `ormConfig`, `SERVE_STATIC` matches
|
|
28
|
+
* `serve-static`); array items are addressed by canonical index. The first key is looked up at the
|
|
29
|
+
* top level, then under `cell`, so `SERVER__PORT` is short for `CELL__SERVER__PORT` unless the
|
|
30
|
+
* project has a top-level `server` of its own; `CELL__...` always means `cell`.
|
|
31
|
+
*
|
|
32
|
+
* Only existing keys can be overridden, so a misspelled variable is reported instead of silently
|
|
33
|
+
* ignored. Each key is set by one variable at most: variables that set the same key, or a key and
|
|
34
|
+
* one inside it, are all reported and none applies, whatever their order. The value is converted to
|
|
35
|
+
* the type of the value it replaces (a finite number in JSON syntax, `true` / `false`, JSON for
|
|
36
|
+
* objects and arrays, JSON or text where cell.yml has `null`, text for strings); a value that is one
|
|
37
|
+
* `${...}` expression is kept and evaluated like cell.yml. Overrides land before `${...}`
|
|
38
|
+
* expressions are evaluated, so references such as `${cell.server.port}` see the new value. The
|
|
39
|
+
* backend applies its variables at startup; the frontend applies them when it is built.
|
|
40
|
+
*/
|
|
41
|
+
export namespace EnvConfigUtil {
|
|
42
|
+
|
|
43
|
+
export const PREFIXES = { backend: 'CELL_BACKEND__', frontend: 'CELL_FRONTEND__' } as const;
|
|
44
|
+
|
|
45
|
+
export type Target = keyof typeof PREFIXES;
|
|
46
|
+
|
|
47
|
+
interface Resolved {
|
|
48
|
+
variable: string;
|
|
49
|
+
value: string;
|
|
50
|
+
/** Keys from the root, as written in the configuration. */
|
|
51
|
+
keys: string[];
|
|
52
|
+
shadows?: string;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/** Applies the variables of `target` in `env` to `config` in place. */
|
|
56
|
+
export function apply(config: Record<string, any>, env: Record<string, string | undefined>, target: Target): EnvOverrideResult {
|
|
57
|
+
const result: EnvOverrideResult = { applied: [], problems: [] };
|
|
58
|
+
const prefix = PREFIXES[target];
|
|
59
|
+
const resolved: Resolved[] = [];
|
|
60
|
+
for (const variable of Object.keys(env).filter(name => name.startsWith(prefix)).sort()) {
|
|
61
|
+
const value = env[variable];
|
|
62
|
+
if (value === undefined) {
|
|
63
|
+
continue;
|
|
64
|
+
}
|
|
65
|
+
try {
|
|
66
|
+
resolved.push({ variable, value, ...resolve(config, variable.slice(prefix.length).split('__')) });
|
|
67
|
+
} catch (error) {
|
|
68
|
+
result.problems.push({ variable, message: (error as Error).message });
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
// Paths are resolved against cell.yml before anything changes, so the outcome never depends on the order of the variables.
|
|
72
|
+
for (const entry of resolved) {
|
|
73
|
+
const path = entry.keys.join('.');
|
|
74
|
+
const others = resolved.filter(other => other !== entry && overlaps(entry.keys, other.keys));
|
|
75
|
+
if (others.length > 0) {
|
|
76
|
+
const list = others.map(other => `${other.variable} (${other.keys.join('.')})`).join(', ');
|
|
77
|
+
result.problems.push({ variable: entry.variable, message: `sets ${path}, which ${list} also set${others.length === 1 ? 's' : ''}. Set each key with one variable; to change items of an object or array you replace, write them into its JSON.` });
|
|
78
|
+
continue;
|
|
79
|
+
}
|
|
80
|
+
try {
|
|
81
|
+
assign(config, entry.keys, entry.value);
|
|
82
|
+
result.applied.push({ variable: entry.variable, path, ...(entry.shadows ? { shadows: entry.shadows } : {}) });
|
|
83
|
+
} catch (error) {
|
|
84
|
+
result.problems.push({ variable: entry.variable, message: (error as Error).message });
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
result.problems.sort((x, y) => (x.variable < y.variable ? -1 : x.variable > y.variable ? 1 : 0));
|
|
88
|
+
return result;
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
/** Applies the backend variables of `process.env` and warns about the ones that do not apply. */
|
|
92
|
+
export function applyProcessEnv(config: Record<string, any>): EnvOverrideResult {
|
|
93
|
+
const result = apply(config, process.env, 'backend');
|
|
94
|
+
for (const problem of result.problems) {
|
|
95
|
+
console.warn(`[cell] ${problem.variable} is ignored: ${problem.message}`);
|
|
96
|
+
}
|
|
97
|
+
return result;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/** The same key, or one inside the other. */
|
|
101
|
+
function overlaps(a: string[], b: string[]): boolean {
|
|
102
|
+
const length = Math.min(a.length, b.length);
|
|
103
|
+
return a.slice(0, length).every((key, i) => key === b[i]);
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
function resolve(config: Record<string, any>, segments: string[]): Pick<Resolved, 'keys' | 'shadows'> {
|
|
107
|
+
if (segments.some(segment => !segment)) {
|
|
108
|
+
throw new Error('empty segment; separate keys with exactly two underscores.');
|
|
109
|
+
}
|
|
110
|
+
const cell = config.cell && typeof config.cell === 'object' ? config.cell : undefined;
|
|
111
|
+
const top = find(config, segments[0]);
|
|
112
|
+
const inCell = cell ? find(cell, segments[0]) : undefined;
|
|
113
|
+
if (top === undefined && inCell === undefined) {
|
|
114
|
+
const cellKeys = cell ? ` or under cell (keys: ${Object.keys(cell).join(', ') || '(none)'})` : '';
|
|
115
|
+
throw new Error(
|
|
116
|
+
`no key '${segments[0]}' at the top level (keys: ${Object.keys(config).join(', ') || '(none)'})${cellKeys}. Only keys present in cell.yml can be overridden.`,
|
|
117
|
+
);
|
|
118
|
+
}
|
|
119
|
+
const keys: string[] = top === undefined ? ['cell'] : [];
|
|
120
|
+
const shadows = top !== undefined && inCell !== undefined && top !== 'cell' ? `cell.${inCell}` : undefined;
|
|
121
|
+
let node: any = top === undefined ? cell : config;
|
|
122
|
+
for (let i = 0; i < segments.length; i++) {
|
|
123
|
+
const key = find(node, segments[i]);
|
|
124
|
+
if (key === undefined) {
|
|
125
|
+
const where = keys.length > 0 ? keys.join('.') : 'the top level';
|
|
126
|
+
const available = Array.isArray(node) ? `indexes 0-${node.length - 1}` : `keys: ${Object.keys(node).join(', ') || '(none)'}`;
|
|
127
|
+
throw new Error(`no key '${segments[i]}' under ${where} (${available}). Only keys present in cell.yml can be overridden.`);
|
|
128
|
+
}
|
|
129
|
+
keys.push(key);
|
|
130
|
+
if (i < segments.length - 1) {
|
|
131
|
+
if (!node[key] || typeof node[key] !== 'object') {
|
|
132
|
+
throw new Error(`${keys.join('.')} is not an object, so it has no key '${segments[i + 1]}'.`);
|
|
133
|
+
}
|
|
134
|
+
node = node[key];
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
return { keys, ...(shadows ? { shadows } : {}) };
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
function assign(config: Record<string, any>, keys: string[], value: string): void {
|
|
141
|
+
const parent = keys.slice(0, -1).reduce((node, key) => node[key], config);
|
|
142
|
+
const last = keys[keys.length - 1];
|
|
143
|
+
parent[last] = convert(parent[last], value, keys.join('.'));
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
function find(node: any, segment: string): string | undefined {
|
|
147
|
+
if (Array.isArray(node)) {
|
|
148
|
+
// Canonical indexes only: '08' would set a property named '08', not item 8.
|
|
149
|
+
return /^(0|[1-9]\d*)$/.test(segment) && Number(segment) < node.length ? segment : undefined;
|
|
150
|
+
}
|
|
151
|
+
const wanted = normalize(segment);
|
|
152
|
+
const keys = Object.keys(node);
|
|
153
|
+
return keys.find(key => key === segment) ?? keys.find(key => normalize(key) === wanted);
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
function normalize(key: string): string {
|
|
157
|
+
return key.replace(/[-_]/g, '').toLowerCase();
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
/** JSON number syntax: `Number()` would also take '', 'Infinity', '0x10' and ' 8 '. */
|
|
161
|
+
const NUMBER = /^-?(0|[1-9]\d*)(\.\d+)?([eE][+-]?\d+)?$/;
|
|
162
|
+
|
|
163
|
+
/** A value that is one `${...}` expression and nothing else. */
|
|
164
|
+
function isExpression(value: string): boolean {
|
|
165
|
+
return value.startsWith('${') && value.endsWith('}') && value.indexOf('${', 2) === -1;
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
/**
|
|
169
|
+
* Converts `value` to the type of `current`, the value in cell.yml. A value that is one `${...}`
|
|
170
|
+
* expression is kept for evaluation, as if written in cell.yml, so its result decides the type:
|
|
171
|
+
* `CELL_BACKEND__SERVER__PORT='${env.PORT}'` works although the port is a number.
|
|
172
|
+
*/
|
|
173
|
+
function convert(current: unknown, value: string, path: string): unknown {
|
|
174
|
+
if (isExpression(value)) {
|
|
175
|
+
return value;
|
|
176
|
+
}
|
|
177
|
+
switch (typeof current) {
|
|
178
|
+
case 'number':
|
|
179
|
+
return number(value, path);
|
|
180
|
+
case 'boolean':
|
|
181
|
+
if (!/^(true|false)$/i.test(value)) {
|
|
182
|
+
throw new Error(`${path} is a boolean, got '${value}'. Use true or false.`);
|
|
183
|
+
}
|
|
184
|
+
return value.toLowerCase() === 'true';
|
|
185
|
+
case 'object':
|
|
186
|
+
if (current === null) {
|
|
187
|
+
// No type to follow: JSON when it is JSON (null, 5, true, "x", [], {}), else the text.
|
|
188
|
+
const parsed = parse(value);
|
|
189
|
+
return parsed ? parsed.value : value;
|
|
190
|
+
}
|
|
191
|
+
return json(current, value, path);
|
|
192
|
+
default:
|
|
193
|
+
return value;
|
|
194
|
+
}
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
function number(value: string, path: string): number {
|
|
198
|
+
const result = NUMBER.test(value) ? Number(value) : NaN;
|
|
199
|
+
if (!Number.isFinite(result)) {
|
|
200
|
+
throw new Error(`${path} is a number, got '${value}'. Use a decimal number such as 8080, -1 or 0.5.`);
|
|
201
|
+
}
|
|
202
|
+
// An integer literal past 2^53 would silently become a different number.
|
|
203
|
+
if (/^-?\d+$/.test(value) && !Number.isSafeInteger(result)) {
|
|
204
|
+
throw new Error(`${path} is a number, got '${value}', which is too large to keep exactly. Use a string in cell.yml for such values.`);
|
|
205
|
+
}
|
|
206
|
+
return result;
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
function json(current: object, value: string, path: string): unknown {
|
|
210
|
+
const kind = Array.isArray(current) ? 'an array' : 'an object';
|
|
211
|
+
const parsed = parse(value)?.value;
|
|
212
|
+
if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed) !== Array.isArray(current)) {
|
|
213
|
+
throw new Error(`${path} is ${kind}; pass it as JSON, or override its keys one by one.`);
|
|
214
|
+
}
|
|
215
|
+
return parsed;
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
function parse(value: string): { value: unknown } | undefined {
|
|
219
|
+
try {
|
|
220
|
+
return { value: JSON.parse(value) };
|
|
221
|
+
} catch {
|
|
222
|
+
return undefined;
|
|
223
|
+
}
|
|
224
|
+
}
|
|
225
|
+
}
|
package/cell-remote.yml
DELETED