@libs-ui/utils 0.2.281 → 0.2.283

package/get-smart-axis-scale.d.ts

@@ -1,9 +1,31 @@
-export declare const getSmartAxisScale: (maxData: number, options?: {
+interface AxisScaleOptions {
     minTickCount?: number;
     maxTickCount?: number;
-    stepCandidates?: Array<number>;
-}) => {
-    step: number;
-    maxY: number;
-    ticks: number;
-};
+    stepCandidates?: number[];
+    acceptNegative?: boolean;
+    minNegative?: number;
+    acceptStepIsTypeFloat?: boolean;
+}
+interface AxisScaleResult {
+    stepSize: number;
+    max: number;
+    min: number;
+    tickAmount: number;
+}
+/**
+ * Calculates smart axis scale for charts
+ *
+ * @description This function can throw errors if:
+ * - maxData < 0 and acceptNegative is false
+ * - minNegative is undefined and acceptNegative is true
+ * - maxData < minNegative (only when acceptNegative is true)
+ * - minNegative > 0 (only when acceptNegative is true)
+ *
+ * @throws {Error} Validation errors for invalid input combinations
+ * @required Always wrap this function in try-catch and handle exceptions
+ * @param maxData - Maximum data value
+ * @param options - Configuration options for axis scaling
+ * @returns Axis scale configuration
+ */
+export declare const getSmartAxisScale: (maxData: number, options?: AxisScaleOptions) => AxisScaleResult;
+export {};

package/helpers.d.ts

@@ -35,6 +35,70 @@ export declare const isEmpty: (value: unknown) => boolean;
  * omitBy(obj, isNil); // { a: 1, c: 3 }
  */
 export declare const omitBy: <T>(objData: Record<string, any>, predicate: (val: any) => boolean) => T;
+/**
+ * Lấy giá trị từ đối tượng theo đường dẫn chỉ định
+ *
+ * Hàm này giúp bạn truy cập vào các thuộc tính sâu bên trong một đối tượng một cách an toàn,
+ * tránh lỗi khi thuộc tính không tồn tại.
+ *
+ * @param obj Đối tượng nguồn cần lấy giá trị
+ * @param path Đường dẫn đến thuộc tính cần lấy. Có thể là:
+ *   - Chuỗi: 'user.profile.name' hoặc 'items[0].title'
+ *   - Mảng: ['user', 'profile', 'name'] hoặc ['items', '0', 'title']
+ *   - Chuỗi rỗng '': trả về chính đối tượng gốc
+ * @param defaultValue Giá trị mặc định trả về khi không tìm thấy thuộc tính (mặc định: undefined)
+ * @param keepLastValueIfSignal Có giữ nguyên signal cuối cùng hay không (mặc định: false - sẽ gọi signal())
+ * @returns Giá trị tìm được hoặc giá trị mặc định
+ *
+ * @example
+ * // Ví dụ cơ bản
+ * const user = { name: 'John', age: 30 };
+ * get(user, 'name'); // 'John'
+ * get(user, 'email'); // undefined
+ * get(user, 'email', 'no-email'); // 'no-email'
+ *
+ * @example
+ * // Truyền path rỗng - trả về chính đối tượng gốc
+ * const data = { name: 'Alice', age: 25 };
+ * get(data, ''); // { name: 'Alice', age: 25 } (chính đối tượng data)
+ * get(data, '', 'default'); // { name: 'Alice', age: 25 } (bỏ qua defaultValue)
+ *
+ * @example
+ * // Truy cập thuộc tính sâu
+ * const data = {
+ *   user: {
+ *     profile: {
+ *       name: 'Alice',
+ *       settings: { theme: 'dark' }
+ *     }
+ *   }
+ * };
+ * get(data, 'user.profile.name'); // 'Alice'
+ * get(data, 'user.profile.settings.theme'); // 'dark'
+ * get(data, 'user.profile.avatar', 'default.jpg'); // 'default.jpg'
+ *
+ * @example
+ * // Truy cập mảng
+ * const items = [
+ *   { name: 'Item 1', price: 100 },
+ *   { name: 'Item 2', price: 200 }
+ * ];
+ * get(items, '[0].name'); // 'Item 1'
+ * get(items, '0.price'); // 100
+ * get(items, '[1].name'); // 'Item 2'
+ * get(items, '[2].name', 'Not found'); // 'Not found'
+ *
+ * @example
+ * // Sử dụng với mảng path
+ * const nested = { a: { b: { c: 'deep value' } } };
+ * get(nested, ['a', 'b', 'c']); // 'deep value'
+ * get(nested, ['a', 'b', 'd'], 'default'); // 'default'
+ *
+ * @example
+ * // Trường hợp đặc biệt
+ * get(null, 'any.path'); // undefined
+ * get(undefined, 'any.path', 'fallback'); // 'fallback'
+ */
 export declare const get: <T = any>(obj: any, path: string | string[], defaultValue?: any, keepLastValueIfSignal?: boolean) => T;
 /**
  * Thiết lập giá trị cho một thuộc tính trong đối tượng theo đường dẫn chỉ định

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@libs-ui/utils",
-  "version": "0.2.281",
+  "version": "0.2.283",
   "peerDependencies": {
     "@angular/common": "^18.2.0",
     "@angular/core": "^18.2.0",
     "crypto-es": "^2.1.0",
     "dayjs": "1.11.5",
-    "@libs-ui/interfaces-types": "0.2.281",
+    "@libs-ui/interfaces-types": "0.2.283",
     "rxjs": "~7.8.0"
   },
   "sideEffects": false,