@celljs/core 4.3.0 → 4.4.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.
Files changed (239) hide show
  1. package/README.md +48 -20
  2. package/cell.schema.json +84 -0
  3. package/cell.yml +13 -12
  4. package/esm/browser/application/frontend-application.d.ts +2 -2
  5. package/esm/browser/application/frontend-application.js +6 -25
  6. package/esm/browser/application/frontend-application.js.map +1 -1
  7. package/esm/common/annotation/component.js +1 -2
  8. package/esm/common/annotation/component.js.map +1 -1
  9. package/esm/common/annotation/service.js +2 -1
  10. package/esm/common/annotation/service.js.map +1 -1
  11. package/esm/common/application/application-entry.js +4 -0
  12. package/esm/common/application/application-entry.js.map +1 -1
  13. package/esm/common/application/application-protocol.d.ts +9 -3
  14. package/esm/common/application/application-protocol.js +19 -7
  15. package/esm/common/application/application-protocol.js.map +1 -1
  16. package/esm/common/application/application.js +1 -1
  17. package/esm/common/application/application.js.map +1 -1
  18. package/esm/common/config/config-util.d.ts +3 -0
  19. package/esm/common/config/config-util.js +6 -1
  20. package/esm/common/config/config-util.js.map +1 -1
  21. package/esm/common/config/dynamic-config.d.ts +3 -0
  22. package/esm/common/config/dynamic-config.js +3 -1
  23. package/esm/common/config/dynamic-config.js.map +1 -1
  24. package/esm/common/config/env-config-util.d.ts +32 -26
  25. package/esm/common/config/env-config-util.js +84 -40
  26. package/esm/common/config/env-config-util.js.map +1 -1
  27. package/esm/common/constants.d.ts +1 -1
  28. package/esm/common/constants.js +1 -1
  29. package/esm/common/constants.js.map +1 -1
  30. package/esm/common/container/auto-bind.js +2 -2
  31. package/esm/common/container/auto-bind.js.map +1 -1
  32. package/esm/common/container/container.js +3 -3
  33. package/esm/common/container/container.js.map +1 -1
  34. package/esm/common/el/core-context-initializer.js +3 -1
  35. package/esm/common/el/core-context-initializer.js.map +1 -1
  36. package/esm/common/el/expression-engine.d.ts +3 -3
  37. package/esm/common/el/expression-engine.js +18 -9
  38. package/esm/common/el/expression-engine.js.map +1 -1
  39. package/esm/common/el/expression-handler.js +2 -1
  40. package/esm/common/el/expression-handler.js.map +1 -1
  41. package/esm/common/el/expression-util.d.ts +17 -4
  42. package/esm/common/el/expression-util.js +28 -9
  43. package/esm/common/el/expression-util.js.map +1 -1
  44. package/esm/common/index.d.ts +1 -0
  45. package/esm/common/index.js +1 -0
  46. package/esm/common/index.js.map +1 -1
  47. package/esm/common/logger/abstract-logger.d.ts +2 -1
  48. package/esm/common/logger/abstract-logger.js +28 -17
  49. package/esm/common/logger/abstract-logger.js.map +1 -1
  50. package/esm/common/logger/logger-protocol.d.ts +2 -2
  51. package/esm/common/logger/logger-protocol.js +1 -1
  52. package/esm/common/logger/logger-protocol.js.map +1 -1
  53. package/esm/common/logger/logger.js +11 -4
  54. package/esm/common/logger/logger.js.map +1 -1
  55. package/esm/common/security-check/index.d.ts +2 -0
  56. package/esm/common/security-check/index.js +3 -0
  57. package/esm/common/security-check/index.js.map +1 -0
  58. package/esm/common/security-check/security-check-protocol.d.ts +40 -0
  59. package/esm/common/security-check/security-check-protocol.js +24 -0
  60. package/esm/common/security-check/security-check-protocol.js.map +1 -0
  61. package/esm/common/security-check/security-checker.d.ts +14 -0
  62. package/esm/common/security-check/security-checker.js +61 -0
  63. package/esm/common/security-check/security-checker.js.map +1 -0
  64. package/esm/common/utils/emitter.d.ts +2 -0
  65. package/esm/common/utils/emitter.js +4 -0
  66. package/esm/common/utils/emitter.js.map +1 -1
  67. package/esm/common/utils/error-util.d.ts +8 -0
  68. package/esm/common/utils/error-util.js +24 -0
  69. package/esm/common/utils/error-util.js.map +1 -1
  70. package/esm/common/utils/event.d.ts +6 -1
  71. package/esm/common/utils/event.js +20 -6
  72. package/esm/common/utils/event.js.map +1 -1
  73. package/esm/common/utils/uuid.d.ts +1 -1
  74. package/esm/common/utils/uuid.js +1 -1
  75. package/esm/common/utils/uuid.js.map +1 -1
  76. package/esm/node/application/backend-application.js +1 -1
  77. package/esm/node/application/backend-application.js.map +1 -1
  78. package/esm/node/context/context.js +3 -3
  79. package/esm/node/context/context.js.map +1 -1
  80. package/lib/browser/application/frontend-application.d.ts +2 -2
  81. package/lib/browser/application/frontend-application.d.ts.map +1 -1
  82. package/lib/browser/application/frontend-application.js +6 -25
  83. package/lib/browser/application/frontend-application.js.map +1 -1
  84. package/lib/common/annotation/component.js +1 -2
  85. package/lib/common/annotation/component.js.map +1 -1
  86. package/lib/common/annotation/service.d.ts.map +1 -1
  87. package/lib/common/annotation/service.js +2 -1
  88. package/lib/common/annotation/service.js.map +1 -1
  89. package/lib/common/annotation/service.spec.d.ts +2 -0
  90. package/lib/common/annotation/service.spec.d.ts.map +1 -0
  91. package/lib/common/annotation/service.spec.js +43 -0
  92. package/lib/common/annotation/service.spec.js.map +1 -0
  93. package/lib/common/aop/aop.spec.js +4 -4
  94. package/lib/common/aop/aop.spec.js.map +1 -1
  95. package/lib/common/application/application-entry.js +4 -0
  96. package/lib/common/application/application-entry.js.map +1 -1
  97. package/lib/common/application/application-protocol.d.ts +9 -3
  98. package/lib/common/application/application-protocol.d.ts.map +1 -1
  99. package/lib/common/application/application-protocol.js +19 -7
  100. package/lib/common/application/application-protocol.js.map +1 -1
  101. package/lib/common/application/application.js +1 -1
  102. package/lib/common/application/application.js.map +1 -1
  103. package/lib/common/application/lifecycle.spec.js +54 -7
  104. package/lib/common/application/lifecycle.spec.js.map +1 -1
  105. package/lib/common/config/config-util.d.ts +3 -0
  106. package/lib/common/config/config-util.d.ts.map +1 -1
  107. package/lib/common/config/config-util.js +5 -0
  108. package/lib/common/config/config-util.js.map +1 -1
  109. package/lib/common/config/dynamic-config.d.ts +3 -0
  110. package/lib/common/config/dynamic-config.d.ts.map +1 -1
  111. package/lib/common/config/dynamic-config.js +4 -2
  112. package/lib/common/config/dynamic-config.js.map +1 -1
  113. package/lib/common/config/env-config-util.d.ts +32 -26
  114. package/lib/common/config/env-config-util.d.ts.map +1 -1
  115. package/lib/common/config/env-config-util.js +84 -40
  116. package/lib/common/config/env-config-util.js.map +1 -1
  117. package/lib/common/config/env-config-util.spec.js +148 -132
  118. package/lib/common/config/env-config-util.spec.js.map +1 -1
  119. package/lib/common/constants.d.ts +1 -1
  120. package/lib/common/constants.d.ts.map +1 -1
  121. package/lib/common/constants.js +1 -1
  122. package/lib/common/constants.js.map +1 -1
  123. package/lib/common/container/auto-bind.js +2 -2
  124. package/lib/common/container/auto-bind.js.map +1 -1
  125. package/lib/common/container/container.js +3 -3
  126. package/lib/common/container/container.js.map +1 -1
  127. package/lib/common/el/core-context-initializer.d.ts.map +1 -1
  128. package/lib/common/el/core-context-initializer.js +3 -1
  129. package/lib/common/el/core-context-initializer.js.map +1 -1
  130. package/lib/common/el/expression-engine.d.ts +3 -3
  131. package/lib/common/el/expression-engine.js +18 -9
  132. package/lib/common/el/expression-engine.js.map +1 -1
  133. package/lib/common/el/expression-engine.spec.js +15 -7
  134. package/lib/common/el/expression-engine.spec.js.map +1 -1
  135. package/lib/common/el/expression-handler.d.ts.map +1 -1
  136. package/lib/common/el/expression-handler.js +2 -1
  137. package/lib/common/el/expression-handler.js.map +1 -1
  138. package/lib/common/el/expression-util.d.ts +17 -4
  139. package/lib/common/el/expression-util.d.ts.map +1 -1
  140. package/lib/common/el/expression-util.js +28 -10
  141. package/lib/common/el/expression-util.js.map +1 -1
  142. package/lib/common/index.d.ts +1 -0
  143. package/lib/common/index.d.ts.map +1 -1
  144. package/lib/common/index.js +1 -0
  145. package/lib/common/index.js.map +1 -1
  146. package/lib/common/logger/abstract-logger.d.ts +2 -1
  147. package/lib/common/logger/abstract-logger.d.ts.map +1 -1
  148. package/lib/common/logger/abstract-logger.js +28 -17
  149. package/lib/common/logger/abstract-logger.js.map +1 -1
  150. package/lib/common/logger/logger-protocol.d.ts +2 -2
  151. package/lib/common/logger/logger-protocol.d.ts.map +1 -1
  152. package/lib/common/logger/logger-protocol.js +1 -1
  153. package/lib/common/logger/logger-protocol.js.map +1 -1
  154. package/lib/common/logger/logger.d.ts.map +1 -1
  155. package/lib/common/logger/logger.js +11 -4
  156. package/lib/common/logger/logger.js.map +1 -1
  157. package/lib/common/logger/logger.spec.js +35 -0
  158. package/lib/common/logger/logger.spec.js.map +1 -1
  159. package/lib/common/security-check/index.d.ts +3 -0
  160. package/lib/common/security-check/index.d.ts.map +1 -0
  161. package/lib/common/security-check/index.js +19 -0
  162. package/lib/common/security-check/index.js.map +1 -0
  163. package/lib/common/security-check/security-check-protocol.d.ts +41 -0
  164. package/lib/common/security-check/security-check-protocol.d.ts.map +1 -0
  165. package/lib/common/security-check/security-check-protocol.js +28 -0
  166. package/lib/common/security-check/security-check-protocol.js.map +1 -0
  167. package/lib/common/security-check/security-checker.d.ts +15 -0
  168. package/lib/common/security-check/security-checker.d.ts.map +1 -0
  169. package/lib/common/security-check/security-checker.js +64 -0
  170. package/lib/common/security-check/security-checker.js.map +1 -0
  171. package/lib/common/security-check/security-checker.spec.d.ts +2 -0
  172. package/lib/common/security-check/security-checker.spec.d.ts.map +1 -0
  173. package/lib/common/security-check/security-checker.spec.js +68 -0
  174. package/lib/common/security-check/security-checker.spec.js.map +1 -0
  175. package/lib/common/utils/emitter.d.ts +2 -0
  176. package/lib/common/utils/emitter.d.ts.map +1 -1
  177. package/lib/common/utils/emitter.js +4 -0
  178. package/lib/common/utils/emitter.js.map +1 -1
  179. package/lib/common/utils/error-util.d.ts +8 -0
  180. package/lib/common/utils/error-util.d.ts.map +1 -1
  181. package/lib/common/utils/error-util.js +24 -0
  182. package/lib/common/utils/error-util.js.map +1 -1
  183. package/lib/common/utils/event.d.ts +6 -1
  184. package/lib/common/utils/event.d.ts.map +1 -1
  185. package/lib/common/utils/event.js +20 -6
  186. package/lib/common/utils/event.js.map +1 -1
  187. package/lib/common/utils/utils-behavior.spec.js +21 -2
  188. package/lib/common/utils/utils-behavior.spec.js.map +1 -1
  189. package/lib/common/utils/uuid.d.ts +1 -1
  190. package/lib/common/utils/uuid.d.ts.map +1 -1
  191. package/lib/common/utils/uuid.js +2 -2
  192. package/lib/common/utils/uuid.js.map +1 -1
  193. package/lib/node/application/backend-application.js +1 -1
  194. package/lib/node/application/backend-application.js.map +1 -1
  195. package/lib/node/context/context.d.ts.map +1 -1
  196. package/lib/node/context/context.js +3 -3
  197. package/lib/node/context/context.js.map +1 -1
  198. package/lib/node/context/context.spec.js +13 -0
  199. package/lib/node/context/context.spec.js.map +1 -1
  200. package/package.json +6 -2
  201. package/src/browser/application/frontend-application.ts +7 -28
  202. package/src/common/annotation/component.ts +1 -1
  203. package/src/common/annotation/service.spec.ts +29 -0
  204. package/src/common/annotation/service.ts +2 -1
  205. package/src/common/aop/aop.spec.ts +4 -4
  206. package/src/common/application/application-entry.ts +4 -0
  207. package/src/common/application/application-protocol.ts +21 -11
  208. package/src/common/application/application.ts +1 -1
  209. package/src/common/application/lifecycle.spec.ts +52 -8
  210. package/src/common/config/config-util.ts +7 -1
  211. package/src/common/config/dynamic-config.ts +6 -1
  212. package/src/common/config/env-config-util.spec.ts +152 -149
  213. package/src/common/config/env-config-util.ts +95 -51
  214. package/src/common/constants.ts +1 -1
  215. package/src/common/container/auto-bind.ts +1 -1
  216. package/src/common/container/container.ts +3 -3
  217. package/src/common/el/core-context-initializer.ts +4 -2
  218. package/src/common/el/expression-engine.spec.ts +17 -8
  219. package/src/common/el/expression-engine.ts +17 -9
  220. package/src/common/el/expression-handler.ts +2 -1
  221. package/src/common/el/expression-util.ts +37 -8
  222. package/src/common/index.ts +1 -0
  223. package/src/common/logger/abstract-logger.ts +30 -17
  224. package/src/common/logger/logger-protocol.ts +1 -1
  225. package/src/common/logger/logger.spec.ts +37 -0
  226. package/src/common/logger/logger.ts +12 -4
  227. package/src/common/security-check/index.ts +2 -0
  228. package/src/common/security-check/security-check-protocol.ts +59 -0
  229. package/src/common/security-check/security-checker.spec.ts +70 -0
  230. package/src/common/security-check/security-checker.ts +48 -0
  231. package/src/common/utils/emitter.ts +5 -0
  232. package/src/common/utils/error-util.ts +27 -1
  233. package/src/common/utils/event.ts +20 -9
  234. package/src/common/utils/utils-behavior.spec.ts +23 -3
  235. package/src/common/utils/uuid.ts +1 -1
  236. package/src/node/application/backend-application.ts +1 -1
  237. package/src/node/context/context.spec.ts +14 -0
  238. package/src/node/context/context.ts +2 -3
  239. package/cell.remote.yml +0 -8
@@ -1,13 +1,8 @@
1
1
  /** An environment variable that was applied to the configuration. */
2
2
  export interface EnvOverride {
3
3
  variable: string;
4
- /** Dotted path of the overridden key, e.g. `cell.server.port`. */
4
+ /** Dotted path of the overridden key, e.g. `server.port`. */
5
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
6
  }
12
7
 
13
8
  /** An environment variable with the override prefix that could not be applied. */
@@ -21,49 +16,68 @@ export interface EnvOverrideResult {
21
16
  problems: EnvOverrideProblem[];
22
17
  }
23
18
 
19
+ /** Scalar types the configuration schemas give to keys whose value is an expression (`ConfigTypes`). */
20
+ export type ConfigScalarType = 'number' | 'integer' | 'boolean' | 'string';
21
+
22
+ /** Schema types of keys whose value is a `${...}` expression, by dotted path (`server.port`, `typeorm.dataSources.0.port`). */
23
+ export type ConfigTypes = Record<string, ConfigScalarType>;
24
+
24
25
  /**
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`.
26
+ * Overrides configuration keys from environment variables: `CELL_SERVER__PORT=8080` sets
27
+ * `server.port`. Segments are separated by `__` and matched against existing keys ignoring case,
28
+ * `_` and `-` (`ORM_CONFIG` matches `ormConfig`); array items are addressed by canonical index.
31
29
  *
32
30
  * Only existing keys can be overridden, so a misspelled variable is reported instead of silently
33
31
  * ignored. Each key is set by one variable at most: variables that set the same key, or a key and
34
32
  * 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.
33
+ * the type of the key: its schema type when the key holds an expression (`types`), else the type of
34
+ * the value it replaces (a finite number in JSON syntax, `true` / `false`, JSON for objects and
35
+ * arrays, JSON or text where cell.yml has `null`, text for strings); a value that is one `${...}`
36
+ * expression is kept and evaluated like cell.yml. Overrides land before `${...}` expressions are
37
+ * evaluated, so references such as `${server.port}` see the new value. The server applies the
38
+ * variables at startup; the build applies them to the public keys it puts into the frontend.
40
39
  */
41
40
  export namespace EnvConfigUtil {
42
41
 
43
- export const PREFIXES = { backend: 'CELL_BACKEND__', frontend: 'CELL_FRONTEND__' } as const;
42
+ export const PREFIX = 'CELL_';
44
43
 
45
- export type Target = keyof typeof PREFIXES;
44
+ /** Variables of the toolchain that share the prefix and are never configuration (`CELL_MODE` would hit the key `mode`). */
45
+ export const RESERVED: readonly string[] = ['CELL_PRESET', 'CELL_MODE', 'CELL_EVENT', 'CELL_OUT_DIR', 'CELL_DEBUG'];
46
+
47
+ /** Variables that apply: the prefix, not reserved. */
48
+ export function isOverride(name: string): boolean {
49
+ return name.startsWith(PREFIX) && !RESERVED.includes(name);
50
+ }
46
51
 
47
52
  interface Resolved {
48
53
  variable: string;
49
54
  value: string;
50
55
  /** Keys from the root, as written in the configuration. */
51
56
  keys: string[];
52
- shadows?: string;
57
+ /** `typeof` the value in the configuration before any variable applies. */
58
+ type: string;
53
59
  }
54
60
 
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 {
61
+ /**
62
+ * Applies the `CELL_*` variables of `env` to `config` in place. A variable of one segment whose
63
+ * name is no top-level key (`CELL_REGION`, a variable of another tool) is not configuration and is
64
+ * left alone; with `__` in it, a name that matches no key is reported.
65
+ */
66
+ export function apply(config: Record<string, any>, env: Record<string, string | undefined>, types: ConfigTypes = {}): EnvOverrideResult {
57
67
  const result: EnvOverrideResult = { applied: [], problems: [] };
58
- const prefix = PREFIXES[target];
68
+ const prefix = PREFIX;
59
69
  const resolved: Resolved[] = [];
60
- for (const variable of Object.keys(env).filter(name => name.startsWith(prefix)).sort()) {
70
+ for (const variable of Object.keys(env).filter(isOverride).sort()) {
61
71
  const value = env[variable];
62
72
  if (value === undefined) {
63
73
  continue;
64
74
  }
75
+ const segments = variable.slice(prefix.length).split('__');
76
+ if (segments.length === 1 && find(config, segments[0]) === undefined) {
77
+ continue;
78
+ }
65
79
  try {
66
- resolved.push({ variable, value, ...resolve(config, variable.slice(prefix.length).split('__')) });
80
+ resolved.push({ variable, value, ...resolve(config, segments) });
67
81
  } catch (error) {
68
82
  result.problems.push({ variable, message: (error as Error).message });
69
83
  }
@@ -78,8 +92,12 @@ export namespace EnvConfigUtil {
78
92
  continue;
79
93
  }
80
94
  try {
81
- assign(config, entry.keys, entry.value);
82
- result.applied.push({ variable: entry.variable, path, ...(entry.shadows ? { shadows: entry.shadows } : {}) });
95
+ assign(config, entry.keys, entry.value, types[path]);
96
+ // An expression set on a number or boolean key converts to that type when it is evaluated.
97
+ if (types[path] === undefined && isExpression(entry.value) && (entry.type === 'number' || entry.type === 'boolean')) {
98
+ types[path] = entry.type;
99
+ }
100
+ result.applied.push({ variable: entry.variable, path });
83
101
  } catch (error) {
84
102
  result.problems.push({ variable: entry.variable, message: (error as Error).message });
85
103
  }
@@ -88,9 +106,9 @@ export namespace EnvConfigUtil {
88
106
  return result;
89
107
  }
90
108
 
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');
109
+ /** Applies the `CELL_*` variables of `process.env` and warns about the ones that do not apply. */
110
+ export function applyProcessEnv(config: Record<string, any>, types: ConfigTypes = {}): EnvOverrideResult {
111
+ const result = apply(config, process.env, types);
94
112
  for (const problem of result.problems) {
95
113
  console.warn(`[cell] ${problem.variable} is ignored: ${problem.message}`);
96
114
  }
@@ -103,22 +121,18 @@ export namespace EnvConfigUtil {
103
121
  return a.slice(0, length).every((key, i) => key === b[i]);
104
122
  }
105
123
 
106
- function resolve(config: Record<string, any>, segments: string[]): Pick<Resolved, 'keys' | 'shadows'> {
124
+ function resolve(config: Record<string, any>, segments: string[]): Pick<Resolved, 'keys' | 'type'> {
125
+ if (segments[0].startsWith('_')) {
126
+ throw new Error(`one underscore after CELL, then \`__\` between keys: CELL_${segments[0].replace(/^_+/, '')}${segments.length > 1 ? '__' + segments.slice(1).join('__') : ''}.`);
127
+ }
128
+ if (/^(BACKEND|FRONTEND)$/i.test(segments[0]) && find(config, segments[0]) === undefined) {
129
+ throw new Error(`the CELL_BACKEND__ / CELL_FRONTEND__ prefixes are gone: the same variable serves both sides, e.g. CELL_${segments.slice(1).join('__') || 'SERVER__PORT'}.`);
130
+ }
107
131
  if (segments.some(segment => !segment)) {
108
132
  throw new Error('empty segment; separate keys with exactly two underscores.');
109
133
  }
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;
134
+ const keys: string[] = [];
135
+ let node: any = config;
122
136
  for (let i = 0; i < segments.length; i++) {
123
137
  const key = find(node, segments[i]);
124
138
  if (key === undefined) {
@@ -134,13 +148,46 @@ export namespace EnvConfigUtil {
134
148
  node = node[key];
135
149
  }
136
150
  }
137
- return { keys, ...(shadows ? { shadows } : {}) };
151
+ return { keys, type: typeof node[keys[keys.length - 1]] };
138
152
  }
139
153
 
140
- function assign(config: Record<string, any>, keys: string[], value: string): void {
154
+ function assign(config: Record<string, any>, keys: string[], value: string, type: ConfigScalarType | undefined): void {
141
155
  const parent = keys.slice(0, -1).reduce((node, key) => node[key], config);
142
156
  const last = keys[keys.length - 1];
143
- parent[last] = convert(parent[last], value, keys.join('.'));
157
+ const path = keys.join('.');
158
+ parent[last] = type && !isExpression(value) ? toType(type, value, path) : convert(parent[last], value, path);
159
+ }
160
+
161
+ /**
162
+ * Converts the text an expression or a variable gave to the scalar type of the key's schema:
163
+ * `${env.PORT ?? 3000}` is a number when `PORT` is set. Values that are not text are kept.
164
+ */
165
+ export function toType(type: ConfigScalarType, value: unknown, path: string): unknown {
166
+ if (typeof value !== 'string') {
167
+ return value;
168
+ }
169
+ switch (type) {
170
+ case 'number':
171
+ return number(value, path);
172
+ case 'integer': {
173
+ const result = number(value, path);
174
+ if (!Number.isInteger(result)) {
175
+ throw new Error(`${path} is an integer, got '${value}'.`);
176
+ }
177
+ return result;
178
+ }
179
+ case 'boolean':
180
+ return boolean(value, path);
181
+ default:
182
+ return value;
183
+ }
184
+ }
185
+
186
+ function boolean(value: string, path: string): boolean {
187
+ if (!/^(true|false)$/i.test(value)) {
188
+ throw new Error(`${path} is a boolean, got '${value}'. Use true or false.`);
189
+ }
190
+ return value.toLowerCase() === 'true';
144
191
  }
145
192
 
146
193
  function find(node: any, segment: string): string | undefined {
@@ -168,7 +215,7 @@ export namespace EnvConfigUtil {
168
215
  /**
169
216
  * Converts `value` to the type of `current`, the value in cell.yml. A value that is one `${...}`
170
217
  * 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.
218
+ * `CELL_SERVER__PORT='${env.PORT}'` works although the port is a number.
172
219
  */
173
220
  function convert(current: unknown, value: string, path: string): unknown {
174
221
  if (isExpression(value)) {
@@ -178,10 +225,7 @@ export namespace EnvConfigUtil {
178
225
  case 'number':
179
226
  return number(value, path);
180
227
  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';
228
+ return boolean(value, path);
185
229
  case 'object':
186
230
  if (current === null) {
187
231
  // No type to follow: JSON when it is JSON (null, 5, true, "x", [], {}), else the text.
@@ -3,4 +3,4 @@ export const METADATA_KEY = {
3
3
  component: 'cell:component'
4
4
  };
5
5
 
6
- export const TENANT_ENABLED = 'cell.tenant.enabled';
6
+ export const TENANT_ENABLED = 'tenant.enabled';
@@ -29,7 +29,7 @@ export function autoBind(registry?: ContainerModuleRegistry): ContainerModule {
29
29
  }
30
30
 
31
31
  function proxyIfNeeded(container: Container, metadata: ComponentMetadata, instance: any) {
32
- if (ConfigUtil.getRaw().cell?.aop?.enabled && instance?.constructor) {
32
+ if (ConfigUtil.getRaw().aop?.enabled && instance?.constructor) {
33
33
  if (container.get<ClassFilter>(ClassFilter).matches(instance.constructor, metadata)) {
34
34
  return container.get<AopProxyFactory>(AopProxyFactory).create({ target: instance, metadata }).getProxy();
35
35
  }
@@ -238,12 +238,12 @@ export class Container {
238
238
  this.resolving.push(binding);
239
239
  this.requests.push(target);
240
240
  try {
241
- const context: ResolveContext = { container: this, target };
242
241
  let value: T;
242
+ // Classes, the most common bindings, need no ResolveContext: it is only created for a factory or an activation.
243
243
  if (binding.type === 'class') {
244
244
  value = this.construct(binding.implementation!);
245
245
  } else if (binding.factory) {
246
- value = binding.factory(context);
246
+ value = binding.factory({ container: this, target });
247
247
  } else {
248
248
  throw new ContainerError({
249
249
  code: 'CELL_DI_INCOMPLETE_BINDING',
@@ -253,7 +253,7 @@ export class Container {
253
253
  });
254
254
  }
255
255
  if (binding.activation) {
256
- value = binding.activation(context, value);
256
+ value = binding.activation({ container: this, target }, value);
257
257
  }
258
258
  if (binding.scope === Scope.Singleton) {
259
259
  binding.value = value;
@@ -2,6 +2,7 @@ import { Component, Autowired } from '../annotation';
2
2
  import { ContainerUtil } from '../container';
3
3
  import { ContextInitializer, ExpressionContext, ExpressionHandler } from './expression-protocol';
4
4
  import { ExpressionEngine } from './expression-engine';
5
+ import { ExpressionUtil } from './expression-util';
5
6
 
6
7
  @Component(ContextInitializer)
7
8
  export class CoreContextInitializer implements ContextInitializer {
@@ -11,7 +12,8 @@ export class CoreContextInitializer implements ContextInitializer {
11
12
 
12
13
  initialize(ctx: ExpressionContext): void {
13
14
  if (typeof process !== 'undefined') {
14
- ctx.env = { ...process.env, _ignoreEl: true };
15
+ // An empty variable counts as unset, so `${env.PORT ?? 3000}` takes the default.
16
+ ctx.env = { ...ExpressionUtil.definedEnv(process.env), _ignoreEl: true };
15
17
  }
16
18
  const expressionHandler = ContainerUtil.get<ExpressionHandler>(ExpressionHandler);
17
19
  this.engine.addTransforms({
@@ -23,4 +25,4 @@ export class CoreContextInitializer implements ContextInitializer {
23
25
 
24
26
  priority = 500;
25
27
 
26
- }
28
+ }
@@ -17,15 +17,15 @@ describe('ExpressionEngine', () => {
17
17
  const evaluate = (source: string, context: object = {}) => engine.evaluate(source, context);
18
18
  const context = {
19
19
  env: { PORT: '8080', EMPTY: '' },
20
- cell: { server: { port: 3000 } },
20
+ server: { port: 3000 },
21
21
  user: { name: 'tom', roles: ['admin', 'dev'] },
22
22
  users: [{ name: 'a', age: 10 }, { name: 'b', age: 20 }, { name: 'c', age: 30 }],
23
23
  n: 5
24
24
  };
25
25
 
26
26
  it('reads names; a missing one is undefined, never an error', () => {
27
- expect(evaluate('cell.server.port', context)).to.equal(3000);
28
- expect(evaluate('cell.missing.deep', context)).to.equal(undefined);
27
+ expect(evaluate('server.port', context)).to.equal(3000);
28
+ expect(evaluate('server.missing.deep', context)).to.equal(undefined);
29
29
  expect(evaluate('missing', context)).to.equal(undefined);
30
30
  expect(evaluate("user['name']", context)).to.equal('tom');
31
31
  expect(evaluate('users[1].name', context)).to.equal('b');
@@ -54,14 +54,23 @@ describe('ExpressionEngine', () => {
54
54
  expect(evaluate('-n + 1', context)).to.equal(-4);
55
55
  });
56
56
 
57
- it('a ? b : c, and a ?: b for defaults', () => {
58
- expect(evaluate("env.MISSING ?: 'nobody'", context)).to.equal('nobody');
59
- expect(evaluate("env.EMPTY ?: 'fallback'", context)).to.equal('fallback');
60
- expect(evaluate('(env.PORT ?: 3306) * 1', context)).to.equal(8080);
57
+ it('a ? b : c, and a ?? b for defaults as in JavaScript', () => {
58
+ expect(evaluate("env.MISSING ?? 'nobody'", context)).to.equal('nobody');
59
+ expect(evaluate("env.EMPTY ?? 'fallback'", context)).to.equal('');
60
+ expect(evaluate("env.EMPTY || 'fallback'", context)).to.equal('fallback');
61
+ expect(evaluate('env.PORT ?? 3306', context)).to.equal('8080');
62
+ expect(evaluate('0 ?? 1')).to.equal(0);
63
+ expect(evaluate("env.MISSING ?? env.OTHER ?? 'last'", context)).to.equal('last');
61
64
  expect(evaluate("n > 9 ? 'big' : n > 3 ? 'mid' : 'small'", context)).to.equal('mid');
62
65
  expect(evaluate('true ? false ? 1 : 2 : 3')).to.equal(2);
63
66
  });
64
67
 
68
+ it('rejects ?: and points to ??', () => {
69
+ const error = errorOf(() => engine.compile("env.PORT ?: 3000"));
70
+ expect(error.message).to.contain("'?:' is not an operator");
71
+ expect(error.hint).to.contain('??');
72
+ });
73
+
65
74
  it('filters keep the elements that .name expressions are true for', () => {
66
75
  expect(evaluate('users[.age > 15].name', context)).to.equal('b');
67
76
  expect(evaluate('users[.age > n * 3]', context)).to.deep.equal([{ name: 'b', age: 20 }, { name: 'c', age: 30 }]);
@@ -104,4 +113,4 @@ describe('ExpressionEngine', () => {
104
113
  expect(own.compile('n + 1')).to.equal(own.compile('n + 1'));
105
114
  expect(own.compile('n + 1').evaluate({ n: 1 })).to.equal(2);
106
115
  });
107
- });
116
+ });
@@ -3,11 +3,11 @@
3
3
  * policies evaluate. Its grammar is the one of jexl 2, which Cell used before:
4
4
  *
5
5
  * - literals: `'text'`, `"text"`, `42`, `1.5`, `true`, `false`, `[a, b]`, `{ key: value }`;
6
- * - names: `cell.server.port`, `list[0]`, `map['key']`, filters `users[.age > 18]` (`.age` is a
6
+ * - names: `server.port`, `list[0]`, `map['key']`, filters `users[.age > 18]` (`.age` is a
7
7
  * property of each element); a missing property is `undefined`, never an error; a property of an
8
8
  * array is the property of its first element;
9
- * - operators, loosest first: `a ? b : c` and `a ?: b` (`b` when `a` is falsy), `||` and `&&` (same
10
- * precedence, left to right), `== != > >= < <= in`, `+ -`, `* / //` (`//` rounds down), `% ^`
9
+ * - operators, loosest first: `a ? b : c`, `??` `||` and `&&` (same precedence, left to right; `a ?? b`
10
+ * is `b` when `a` is `null` or `undefined`, as in JavaScript), `== != > >= < <= in`, `+ -`, `* / //` (`//` rounds down), `% ^`
11
11
  * (`^` is power), then `!` and `-` in front;
12
12
  * - transforms `value|name(args)` and functions `name(args)`: only the ones added to the engine.
13
13
  *
@@ -120,10 +120,10 @@ interface Token {
120
120
  }
121
121
 
122
122
  /** Longest first, so that `//` is not `/`. */
123
- const OPERATORS = ['//', '==', '!=', '>=', '<=', '&&', '||', '+', '-', '*', '/', '%', '^', '>', '<', '!'];
123
+ const OPERATORS = ['??', '//', '==', '!=', '>=', '<=', '&&', '||', '+', '-', '*', '/', '%', '^', '>', '<', '!'];
124
124
  const PUNCTUATION = '.[]|{}:,()?';
125
125
  const PRECEDENCE: Record<string, number> = {
126
- '||': 10, '&&': 10,
126
+ '??': 10, '||': 10, '&&': 10,
127
127
  '==': 20, '!=': 20, '>': 20, '>=': 20, '<': 20, '<=': 20, in: 20,
128
128
  '+': 30, '-': 30,
129
129
  '*': 40, '/': 40, '//': 40,
@@ -177,11 +177,17 @@ class ExpressionParser {
177
177
  if (!this.accept('?')) {
178
178
  return test;
179
179
  }
180
- const consequent = this.accept(':') ? undefined : this.ternaryThen();
181
- const alternate = this.ternary();
182
- if (!consequent) {
183
- return (c, e) => test(c, e) || alternate(c, e);
180
+ if (this.peek().type === 'punctuation' && this.peek().value === ':') {
181
+ throw new ExpressionSyntaxError({
182
+ code: 'CELL_EL_SYNTAX',
183
+ message: `'?:' is not an operator at position ${this.peek().start - 1} of: ${this.source}`,
184
+ hint: "Write a default with ??, e.g. ${env.PORT ?? 3000}; || takes the right side for any falsy value.",
185
+ expression: this.source,
186
+ position: this.peek().start - 1
187
+ });
184
188
  }
189
+ const consequent = this.ternaryThen();
190
+ const alternate = this.ternary();
185
191
  return (c, e) => test(c, e) ? consequent(c, e) : alternate(c, e);
186
192
  }
187
193
 
@@ -207,6 +213,8 @@ class ExpressionParser {
207
213
  left = (c, e) => l(c, e) && r(c, e);
208
214
  } else if (token.value === '||') {
209
215
  left = (c, e) => l(c, e) || r(c, e);
216
+ } else if (token.value === '??') {
217
+ left = (c, e) => l(c, e) ?? r(c, e);
210
218
  } else {
211
219
  const apply = BINARY[token.value];
212
220
  left = (c, e) => apply(l(c, e), r(c, e));
@@ -1,6 +1,7 @@
1
1
  import { Component, Autowired } from '../annotation';
2
2
  import { ExpressionHandler, ExpressionContextProvider, ExpressionCompiler, ExpressionContext, ExpressionCompilerOptions } from './expression-protocol';
3
3
  import { ExpressionUtil } from './expression-util';
4
+ import { ConfigUtil } from '../config/config-util';
4
5
 
5
6
  /**
6
7
  * Evaluates `${...}` expressions with {@link ExpressionUtil}: the result of an expression is never
@@ -23,7 +24,7 @@ export class ExpressionHandlerImpl implements ExpressionHandler {
23
24
 
24
25
  if (!ctx && c !== this._ctx && !expressionCompilerOptions?.ignoreContextExpression) {
25
26
  this._ctx = c;
26
- ExpressionUtil.evaluateConfiguration(c, this.options(expressionCompilerOptions));
27
+ ExpressionUtil.evaluateConfiguration(c, { ...this.options(expressionCompilerOptions), types: ConfigUtil.getTypes() });
27
28
  }
28
29
  return c;
29
30
  }
@@ -1,5 +1,9 @@
1
1
  import { ExpressionCompiler, ExpressionCompilerOptions, ExpressionContext } from './expression-protocol';
2
2
  import { Expression, ExpressionEngine } from './expression-engine';
3
+ import { EnvConfigUtil, type ConfigTypes } from '../config/env-config-util';
4
+
5
+ // The build (@celljs/vite) applies CELL_* variables with the same code as the server.
6
+ export { EnvConfigUtil };
3
7
 
4
8
  interface MiddleExpression {
5
9
  expression: string | Expression;
@@ -22,18 +26,18 @@ export class ExpressionSectionCompiler implements ExpressionCompiler {
22
26
  private BRACKET_BEGIN = '{';
23
27
  private BRACKET_END = '}';
24
28
 
25
- protected getSpecialChar(opitons: Required<ExpressionCompilerOptions>): string {
26
- if (opitons.ignoreSpecialChar) {
29
+ protected getSpecialChar(options: Required<ExpressionCompilerOptions>): string {
30
+ if (options.ignoreSpecialChar) {
27
31
  return '';
28
32
  }
29
- return opitons.specialChar;
33
+ return options.specialChar;
30
34
  }
31
35
 
32
- protected equalsSpecialChar(opitons: Required<ExpressionCompilerOptions>, char: string): boolean {
33
- if (opitons.ignoreSpecialChar) {
36
+ protected equalsSpecialChar(options: Required<ExpressionCompilerOptions>, char: string): boolean {
37
+ if (options.ignoreSpecialChar) {
34
38
  return false;
35
39
  }
36
- return char === opitons.specialChar;
40
+ return char === options.specialChar;
37
41
  }
38
42
 
39
43
  compileSections(text: string, options: ExpressionCompilerOptions): (string | Expression)[] {
@@ -181,7 +185,7 @@ export class ExpressionSectionCompiler implements ExpressionCompiler {
181
185
 
182
186
  }
183
187
 
184
- /** An expression of the configuration that cannot be evaluated; `path` is its key, e.g. `cell.db.url`. */
188
+ /** An expression of the configuration that cannot be evaluated; `path` is its key, e.g. `db.url`. */
185
189
  export class ExpressionError extends Error {
186
190
 
187
191
  override readonly name = 'ExpressionError';
@@ -204,10 +208,31 @@ export namespace ExpressionUtil {
204
208
  /** Defaults to an {@link ExpressionSectionCompiler} on a plain {@link ExpressionEngine} (no transforms). */
205
209
  compiler?: ExpressionCompiler;
206
210
  compilerOptions?: ExpressionCompilerOptions;
211
+ /**
212
+ * Schema types by dotted path, for {@link evaluateConfiguration}: the text an expression of such a
213
+ * key gives is converted (`server.port: ${env.PORT ?? 3000}` is a number when `PORT` is set).
214
+ */
215
+ types?: ConfigTypes;
216
+ /**
217
+ * For {@link evaluateConfiguration}: evaluates only the keys whose dotted path it accepts; the keys
218
+ * they refer to are still evaluated. The build uses it for the frontend keys.
219
+ */
220
+ include?: (path: string) => boolean;
207
221
  }
208
222
 
209
223
  let defaultCompiler: ExpressionCompiler | undefined;
210
224
 
225
+ /** The environment as expressions see it: an empty variable counts as unset (`${env.X ?? 'default'}`). */
226
+ export function definedEnv(env: Record<string, string | undefined>): Record<string, string> {
227
+ const result: Record<string, string> = {};
228
+ for (const [name, value] of Object.entries(env)) {
229
+ if (value !== undefined && value !== '') {
230
+ result[name] = value;
231
+ }
232
+ }
233
+ return result;
234
+ }
235
+
211
236
  function compilerOf(options: Options): ExpressionCompiler {
212
237
  return options.compiler ?? (defaultCompiler ??= new ExpressionSectionCompiler());
213
238
  }
@@ -311,6 +336,10 @@ export namespace ExpressionUtil {
311
336
  let value: unknown;
312
337
  try {
313
338
  value = unwrap(evaluateText(template, () => view(root), options));
339
+ const type = options.types?.[path];
340
+ if (type) {
341
+ value = EnvConfigUtil.toType(type, value, path);
342
+ }
314
343
  } catch (error) {
315
344
  if (error instanceof ExpressionError) {
316
345
  throw error;
@@ -353,7 +382,7 @@ export namespace ExpressionUtil {
353
382
  return proxy;
354
383
  };
355
384
 
356
- walk(root, (text, owner, key) => valueOf(owner, key), (child, owner, key) => {
385
+ walk(root, (text, owner, key) => (options.include && !options.include(pathOf(owner, key)) ? text : valueOf(owner, key)), (child, owner, key) => {
357
386
  if (!paths.has(child)) {
358
387
  paths.set(child, pathOf(owner, key));
359
388
  }
@@ -10,3 +10,4 @@ export * from './config';
10
10
  export * from './error';
11
11
  export * from './el';
12
12
  export * from './provider';
13
+ export * from './security-check';
@@ -1,17 +1,22 @@
1
1
  import { Autowired, Optional, Value } from '../annotation';
2
+ import { ErrorUtil } from '../utils/error-util';
2
3
  import { Logger, LOGGER_LEVEL, LOG_LEVELS, LogLevel, onLogEmitter, TraceIdProvider } from './logger-protocol';
3
4
 
5
+ /** Position of each level in LOG_LEVELS, looked up on every message. */
6
+ const RANK: Record<string, number> = Object.fromEntries(LOG_LEVELS.map((level, index) => [level, index]));
7
+
4
8
  export abstract class AbstractLogger implements Logger {
5
9
  protected instance: Logger;
6
10
  protected context?: string;
7
11
 
8
- @Value(`${LOGGER_LEVEL} ?: 'info'`)
12
+ @Value(`${LOGGER_LEVEL} ?? 'info'`)
9
13
  level: LogLevel;
10
14
 
11
15
  @Autowired(TraceIdProvider) @Optional()
12
16
  protected readonly traceIdProvider?: TraceIdProvider;
13
17
 
14
- protected timeRecords: Map<string, number> = new Map();
18
+ /** Created by the first `time()`: most loggers never time anything. */
19
+ protected timeRecords?: Map<string, number>;
15
20
 
16
21
  setContext(context?: string): void {
17
22
  this.context = context;
@@ -25,8 +30,7 @@ export abstract class AbstractLogger implements Logger {
25
30
  }
26
31
 
27
32
  isEnabled(level: LogLevel): boolean {
28
- const configured = LOG_LEVELS.indexOf(this.level);
29
- return LOG_LEVELS.indexOf(level) >= (configured < 0 ? LOG_LEVELS.indexOf('info') : configured);
33
+ return RANK[level] >= (RANK[this.level] ?? RANK.info);
30
34
  }
31
35
 
32
36
  /** `level` is the level of the message, not the configured one. */
@@ -37,27 +41,36 @@ export abstract class AbstractLogger implements Logger {
37
41
 
38
42
  protected log(message: any, context?: string, logFn: (...args: any[]) => void = console.info, level: LogLevel = 'info'): void {
39
43
  const traceId = this.traceIdProvider?.provide();
40
- const traceStr = traceId ? ` [trace: ${traceId}]` : '';
41
44
  const contextStr = this.resolveContextString(context);
42
- logFn(`${this.resolvePrefix(level)}${traceStr}${contextStr}${message}`);
43
- onLogEmitter.fire({
44
- level,
45
- traceId,
46
- rootContext: this.context,
47
- context,
48
- message
49
- });
45
+ // An error is written with its stack and causes, not only `Error: message`.
46
+ const text = message instanceof Error ? ErrorUtil.describe(message) : message;
47
+ // `time [level] [trace: id] [context] message`, without the parts that are empty (winston writes its own prefix).
48
+ let head = this.resolvePrefix(level);
49
+ if (traceId) {
50
+ head = head ? `${head} [trace: ${traceId}]` : `[trace: ${traceId}]`;
51
+ }
52
+ logFn(`${head ? `${head} ` : ''}${contextStr}${text}`);
53
+ // Most applications have no LoggerService listener: no message object per line then.
54
+ if (onLogEmitter.hasListeners) {
55
+ onLogEmitter.fire({
56
+ level,
57
+ traceId,
58
+ rootContext: this.context,
59
+ context,
60
+ message
61
+ });
62
+ }
50
63
  }
51
64
 
52
65
  time(label: string): void {
53
- this.timeRecords.set(label, Date.now());
66
+ (this.timeRecords ??= new Map()).set(label, Date.now());
54
67
  }
55
68
 
56
69
  timeEnd(label: string, context?: string): number | undefined {
57
- const start = this.timeRecords.get(label);
70
+ const start = this.timeRecords?.get(label);
58
71
  if (start !== undefined) {
59
72
  const duration = Date.now() - start;
60
- this.timeRecords.delete(label);
73
+ this.timeRecords!.delete(label);
61
74
  this.log(`${label} [${duration}ms]`, context);
62
75
  return duration;
63
76
  } else {
@@ -70,4 +83,4 @@ export abstract class AbstractLogger implements Logger {
70
83
  abstract error(message: any, context?: string | undefined): void;
71
84
  abstract warn(message: any, context?: string | undefined): void;
72
85
  abstract debug(message: any, context?: string | undefined): void;
73
- }
86
+ }
@@ -1,5 +1,5 @@
1
1
  import { Emitter, Event } from '../utils';
2
- export const LOGGER_CONFIG = 'cell.logger';
2
+ export const LOGGER_CONFIG = 'logger';
3
3
  export const LOGGER_LEVEL = `${LOGGER_CONFIG}.level`;
4
4
 
5
5
  export const Logger = Symbol('Logger');