@onecx/accelerator 7.3.0 → 7.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onecx/accelerator",
-  "version": "7.3.0",
+  "version": "7.4.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -11,7 +11,7 @@
     "rxjs": "^7.8.1",
     "@nx/devkit": "^22.0.2",
     "@nx/module-federation": "22.0.2",
-    "@onecx/nx-migration-utils": "^7.3.0"
+    "@onecx/nx-migration-utils": "^7.4.0"
   },
   "type": "commonjs",
   "main": "./src/index.js",

package/src/lib/utils/ensure-property.utils.d.ts

@@ -18,41 +18,72 @@ type SetPathTuple<T, Path extends ReadonlyArray<string | number>, Value> = Path
  * about intermediate objects being missing. It will not overwrite existing values - only
  * null or undefined values are replaced.
  *
+ * **Returns the typed object** - you should use the return value to access the properties
+ * with full type safety.
+ *
+ * Supports property names with special characters that can only be accessed via bracket notation.
+ *
  * @template T - The object type
  * @template Path - The path as a tuple of keys
  * @template Value - The type of the value to set
  * @param obj - The object to modify
  * @param path - An array representing the path to the property (e.g., ['user', 'profile', 'name'])
  * @param initialValue - The value to set if the property is currently null or undefined
+ * @returns The same object with updated type information including the new property
  *
  * @example
- * // Ensure a global debug flag exists
- * ensureProperty(globalThis, ['myApp', 'config', 'debug'], false);
- * // Access it safely:
- * if (globalThis.myApp.config.debug) {
+ * // Recommended: Use the return value for full type safety
+ * const g = ensureProperty(globalThis, ['myApp', 'config', 'debug'], false);
+ * if (g.myApp.config.debug) {
  *   console.log('Debug mode enabled');
  * }
  *
  * @example
- * // Initialize nested configuration
- * const config = {};
- * ensureProperty(config, ['database', 'host'], 'localhost');
- * ensureProperty(config, ['database', 'port'], 5432);
- * // config is now { database: { host: 'localhost', port: 5432 } }
+ * // For regular property names (no special chars), both ways work:
+ * // 1. Using return value (recommended for consistency)
+ * let config = {};
+ * config = ensureProperty(config, ['database', 'host'], 'localhost');
+ * console.log(config.database.host); // TypeScript knows about this
+ *
+ * // 2. Without using return value (works for non-special chars)
+ * const settings = {};
+ * ensureProperty(settings, ['server', 'port'], 3000);
+ * console.log(settings.server.port); // Also works, but less type-safe
+ *
+ * @example
+ * // For globalThis with regular names, you can declare it globally:
+ * declare global {
+ *   var myApp: { config: { debug: boolean } };
+ * }
+ * ensureProperty(globalThis, ['myApp', 'config', 'debug'], false);
+ * if (globalThis.myApp.config.debug) { // Works without using return value
+ *   console.log('Debug enabled');
+ * }
+ *
+ * @example
+ * // For special characters, MUST use return value:
+ * const g = ensureProperty(globalThis, ['@onecx/accelerator', 'version'], '1.0.0');
+ * console.log(g['@onecx/accelerator'].version); // TypeScript knows this exists
+ * // globalThis['@onecx/accelerator'].version won't work without the return value
  *
  * @example
  * // Won't overwrite existing values
- * const obj = { name: 'John' };
- * ensureProperty(obj, ['name'], 'Jane');
- * // obj.name remains 'John'
+ * let obj = { name: 'John' };
+ * obj = ensureProperty(obj, ['name'], 'Jane');
+ * console.log(obj.name); // Still 'John'
  *
  * @example
  * // Replaces null values
- * const obj = { name: null };
- * ensureProperty(obj, ['name'], 'Default');
- * // obj.name is now 'Default'
+ * let obj = { name: null };
+ * obj = ensureProperty(obj, ['name'], 'Default');
+ * console.log(obj.name); // Now 'Default'
+ *
+ * @example
+ * // Nested paths with special characters
+ * const g = ensureProperty(globalThis, ['@myapp/config', 'feature-flags', 'enabled'], true);
+ * console.log(g['@myapp/config']['feature-flags'].enabled);
  */
-export declare function ensureProperty<const Path extends ReadonlyArray<string | number>, Value>(obj: typeof globalThis, path: Path, initialValue: Value): asserts obj is typeof globalThis & SetPathTuple<typeof globalThis, Path, Value>;
-export declare function ensureProperty<T extends object, const Path extends ValidPaths<T>, Value>(obj: T, path: Path, initialValue: Value): asserts obj is T & SetPathTuple<T, Path, Value>;
-export declare function ensureProperty<T extends object, const Path extends ReadonlyArray<string | number>, Value>(obj: T, path: Path, initialValue: Value): asserts obj is T & SetPathTuple<T, Path, Value>;
+export declare function ensureProperty<const Path extends ReadonlyArray<string | number>, Value>(obj: typeof globalThis, path: Path, initialValue: Value): typeof globalThis & SetPathTuple<typeof globalThis, Path, Value>;
+export declare function ensureProperty<T extends object, const Path extends ValidPaths<T>, Value>(obj: T, path: Path, initialValue: Value): T & SetPathTuple<T, Path, Value>;
+export declare function ensureProperty<T extends object, const Path extends ReadonlyArray<string | number>, Value>(obj: T, path: Path, initialValue: Value): T & SetPathTuple<T, Path, Value>;
 export {};

package/src/lib/utils/ensure-property.utils.js

@@ -12,8 +12,9 @@ function ensureProperty(obj, path, initialValue) {
     }
     const lastKey = path.at(-1);
     if (lastKey === undefined) {
-        return;
+        return obj;
     }
     current[lastKey] ??= initialValue;
+    return obj;
 }
 //# sourceMappingURL=ensure-property.utils.js.map

package/src/lib/utils/ensure-property.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"ensure-property.utils.js","sourceRoot":"","sources":["../../../../../../libs/accelerator/src/lib/utils/ensure-property.utils.ts"],"names":[],"mappings":";;AAoHA,wCAoBC;AApBD,SAAgB,cAAc,CAC1B,GAAM,EACN,IAAU,EACV,YAAmB;IAEnB,IAAI,OAAO,GAAQ,GAAG,CAAC;IAEvB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,IAAI,OAAO,OAAO,CAAC,GAAG,CAAC,KAAK,QAAQ,EAAE,CAAC;YAC3D,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC;QACtB,CAAC;QACD,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5B,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO;IACX,CAAC;IACD,OAAO,CAAC,OAAO,CAAC,KAAK,YAAY,CAAC;AACtC,CAAC"}
+{"version":3,"file":"ensure-property.utils.js","sourceRoot":"","sources":["../../../../../../libs/accelerator/src/lib/utils/ensure-property.utils.ts"],"names":[],"mappings":";;AAmJA,wCAqBC;AArBD,SAAgB,cAAc,CAC1B,GAAM,EACN,IAAU,EACV,YAAmB;IAEnB,IAAI,OAAO,GAAQ,GAAG,CAAC;IAEvB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,IAAI,OAAO,OAAO,CAAC,GAAG,CAAC,KAAK,QAAQ,EAAE,CAAC;YAC3D,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC;QACtB,CAAC;QACD,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5B,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,GAAuC,CAAC;IACnD,CAAC;IACD,OAAO,CAAC,OAAO,CAAC,KAAK,YAAY,CAAC;IAClC,OAAO,GAAuC,CAAC;AACnD,CAAC"}