@libs-ui/utils 0.2.282 → 0.2.284

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

@@ -1,23 +1,34 @@
-/**
- * Hàm có thể trả về lỗi nếu:
- * - maxData < 0 và acceptNegative là false
- * - minNegative là undefined và acceptNegative là true
- * - maxData < minNegative (chỉ xảy ra khi acceptNegative là true)
- * - minNegative > 0 (chỉ xảy ra khi acceptNegative là true)
- * @throws {Error}
- * @required luôn đặt hàm này trong try catch và xử lý ngoại lệ
- * @hint Truyền 3 tham số: min,max và tick
- */
-export declare const getSmartAxisScale: (maxData: number, options?: {
+interface AxisScaleOptions {
     minTickCount?: number;
     maxTickCount?: number;
-    stepCandidates?: Array<number>;
+    stepCandidates?: number[];
     acceptNegative?: boolean;
     minNegative?: number;
     acceptStepIsTypeFloat?: boolean;
-}) => {
+}
+interface AxisScaleResult {
     stepSize: number;
     max: number;
     min: number;
     tickAmount: number;
-};
+}
+/**
+ * Tính toán smart axis scale cho biểu đồ
+ *
+ * @param maxData - Giá trị tối đa của dữ liệu
+ * @param options - Các tùy chọn cấu hình axis scale
+ * @returns Cấu hình axis scale bao gồm stepSize, max, min, tickAmount
+ *
+ * @throws {Error} INVALID_NEGATIVE_DATA - khi maxData < 0 mà acceptNegative = false
+ * @throws {Error} MISSING_MIN_NEGATIVE - khi acceptNegative = true nhưng thiếu minNegative
+ * @throws {Error} INVALID_RANGE - khi maxData < minNegative
+ * @throws {Error} INVALID_MIN_NEGATIVE - khi minNegative >= 0
+ *
+ * @example
+ * ```typescript
+ * const result = getSmartAxisScale(100, { minTickCount: 5, maxTickCount: 10 });
+ * // returns { stepSize: 20, max: 120, min: 0, tickAmount: 6 }
+ * ```
+ */
+export declare const getSmartAxisScale: (originalMaxData: 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.282",
+  "version": "0.2.284",
   "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.282",
+    "@libs-ui/interfaces-types": "0.2.284",
     "rxjs": "~7.8.0"
   },
   "sideEffects": false,