From 4031a7c242f49671549bda00dea0754afd6e4896 Mon Sep 17 00:00:00 2001
From: Kenji <120051456+KenjiGinjo@users.noreply.github.com>
Date: Wed, 21 Aug 2024 17:33:32 +0800
Subject: [PATCH] =?UTF-8?q?[=E5=B7=B2=E5=AE=8C=E6=88=90]=20chore=20example?=
 =?UTF-8?q?=20&=20jsdoc=20(#10)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat: ask

* fix: small fix

* fix: small fix

* fix: small fix

* fix(test): oid

* docs: tidy up

---------

Co-authored-by: bingtsingw <10382462+bingtsingw@users.noreply.github.com>
---
 .../src/_internal/pathToSegments.spec.ts      |  1 +
 packages/utility/src/array/rank.spec.ts       | 32 ++++++++++++++
 packages/utility/src/format/bytes.spec.ts     |  7 +++-
 packages/utility/src/format/bytes.ts          | 14 +++++++
 packages/utility/src/format/currency.spec.ts  | 14 ++++++-
 packages/utility/src/format/currency.ts       | 11 +++++
 packages/utility/src/format/starlize.spec.ts  | 10 +++--
 packages/utility/src/format/starlize.ts       | 22 ++++++++++
 packages/utility/src/generator/oid.spec.ts    |  2 +
 packages/utility/src/generator/oid.ts         |  2 +-
 packages/utility/src/misc/get-distance.ts     |  8 +---
 packages/utility/src/misc/get-district.ts     |  8 ++++
 packages/utility/src/misc/stringify.spec.ts   |  1 +
 packages/utility/src/misc/stringify.ts        |  7 ++++
 packages/utility/src/string/template.spec.ts  | 13 ++++++
 packages/utility/src/string/trim.spec.ts      | 42 +++++++++----------
 16 files changed, 158 insertions(+), 36 deletions(-)

diff --git a/packages/utility/src/_internal/pathToSegments.spec.ts b/packages/utility/src/_internal/pathToSegments.spec.ts
index 2aceff4..21ab5c2 100644
--- a/packages/utility/src/_internal/pathToSegments.spec.ts
+++ b/packages/utility/src/_internal/pathToSegments.spec.ts
@@ -7,6 +7,7 @@ describe('pathToSegments', () => {
     expect(pathToSegments('a[b][c]')).toEqual(['a', 'b', 'c']);
     expect(pathToSegments('a[b].c')).toEqual(['a', 'b', 'c']);
     expect(pathToSegments('a["b.c"].d')).toEqual(['a', 'b.c', 'd']);
+    expect(pathToSegments('a[b.c].d')).toEqual(['a', 'b.c', 'd']);
     expect(pathToSegments('.a.b.c')).toEqual(['', 'a', 'b', 'c']);
   });
 
diff --git a/packages/utility/src/array/rank.spec.ts b/packages/utility/src/array/rank.spec.ts
index 2d9ae26..74c8212 100644
--- a/packages/utility/src/array/rank.spec.ts
+++ b/packages/utility/src/array/rank.spec.ts
@@ -29,4 +29,36 @@ describe('rankByPath', () => {
   test('array with one element', () => {
     expect(rankByPath([{ score: 59 }], 'score')).toEqual([{ _rank: 1, score: 59 }]);
   });
+
+  test('array with complex element', () => {
+    expect(
+      rankByPath(
+        [
+          { a: 3, b: '' },
+          { a: 1, c: false },
+          { a: 2, c: 0 },
+        ],
+        'a',
+      ),
+    ).toEqual([
+      { _rank: 1, a: 3, b: '' },
+      { _rank: 2, a: 2, c: 0 },
+      { _rank: 3, a: 1, c: false },
+    ]);
+
+    expect(
+      rankByPath(
+        [
+          { a: '3', b: '' },
+          { a: '1', c: false },
+          { a: 2, c: 0 },
+        ],
+        'a',
+      ),
+    ).toEqual([
+      { _rank: 1, a: '3', b: '' },
+      { _rank: 2, a: 2, c: 0 },
+      { _rank: 3, a: '1', c: false },
+    ]);
+  });
 });
diff --git a/packages/utility/src/format/bytes.spec.ts b/packages/utility/src/format/bytes.spec.ts
index 2cda8b6..462d5e5 100644
--- a/packages/utility/src/format/bytes.spec.ts
+++ b/packages/utility/src/format/bytes.spec.ts
@@ -1,8 +1,8 @@
 import { describe, expect, test } from 'bun:test';
 import { formatBytes } from './bytes';
 
-describe('format', () => {
-  test('formatBytes', () => {
+describe('formatBytes', () => {
+  test('normal usage', () => {
     expect(formatBytes(0)).toEqual('0 B');
     expect(formatBytes(1)).toEqual('1 B');
     expect(formatBytes(1000)).toEqual('1000 B');
@@ -10,6 +10,9 @@ describe('format', () => {
     expect(formatBytes(2048)).toEqual('2 KB');
     expect(formatBytes(2560)).toEqual('2.5 KB');
     expect(formatBytes(1111)).toEqual('1.08 KB');
+    expect(formatBytes(1111, 1)).toEqual('1.1 KB');
+    expect(formatBytes(1111, 2)).toEqual('1.08 KB');
+    expect(formatBytes(1111, 3)).toEqual('1.085 KB');
 
     expect(formatBytes(2560000)).toEqual('2.44 MB');
     expect(formatBytes(Math.pow(1024, 3))).toEqual('1 GB');
diff --git a/packages/utility/src/format/bytes.ts b/packages/utility/src/format/bytes.ts
index 4e46b0d..a49525e 100644
--- a/packages/utility/src/format/bytes.ts
+++ b/packages/utility/src/format/bytes.ts
@@ -1,3 +1,17 @@
+/**
+ * Format bytes to human readable string.
+ *
+ * @example
+ * formatBytes(1024) // => '1 KB'
+ * formatBytes(2048) // => '2 KB'
+ * formatBytes(2560) // => '2.5 KB'
+ * formatBytes(2560000)) // => '2.44 MB'
+ *
+ * formatBytes(1111) // => '1.08 KB'
+ * formatBytes(1111, 1) // => '1.1 KB'
+ * formatBytes(1111, 2) // => '1.08 KB'
+ * formatBytes(1111, 3) // => '1.085 KB'
+ */
 export const formatBytes = (bytes: number, decimals = 2): string => {
   if (bytes === 0) return '0 B';
 
diff --git a/packages/utility/src/format/currency.spec.ts b/packages/utility/src/format/currency.spec.ts
index 13ca5ec..f2272d1 100644
--- a/packages/utility/src/format/currency.spec.ts
+++ b/packages/utility/src/format/currency.spec.ts
@@ -8,17 +8,27 @@ describe('format', () => {
     expect(formatCurrency(999)).toEqual('¥ 9.99');
 
     expect(formatCurrency(2, { decimals: 0 })).toEqual('¥ 0');
+    expect(formatCurrency(2, { decimals: 1 })).toEqual('¥ 0.0');
+    expect(formatCurrency(2, { decimals: 2 })).toEqual('¥ 0.02');
+
     expect(formatCurrency(100, { decimals: 0 })).toEqual('¥ 1');
+    expect(formatCurrency(100, { decimals: 1 })).toEqual('¥ 1.0');
     expect(formatCurrency(999, { decimals: 0 })).toEqual('¥ 10');
+    expect(formatCurrency(999, { decimals: 1 })).toEqual('¥ 10.0');
+    expect(formatCurrency(999, { decimals: 2 })).toEqual('¥ 9.99');
+    expect(formatCurrency(999, { decimals: 3 })).toEqual('¥ 9.990');
 
     expect(formatCurrency(2, { symbol: '' })).toEqual('0.02');
-    expect(formatCurrency(100, { symbol: '' })).toEqual('1.00');
-    expect(formatCurrency(999, { symbol: '' })).toEqual('9.99');
+    expect(formatCurrency(100, { symbol: '$' })).toEqual('$ 1.00');
+    expect(formatCurrency(999, { symbol: 'Є' })).toEqual('Є 9.99');
 
     expect(formatCurrency(2, { sign: true })).toEqual('¥ +0.02');
+    expect(formatCurrency(2, { sign: false })).toEqual('¥ 0.02');
     expect(formatCurrency(100, { sign: true })).toEqual('¥ +1.00');
+    expect(formatCurrency(100, { sign: false })).toEqual('¥ 1.00');
     expect(formatCurrency(999, { sign: true })).toEqual('¥ +9.99');
 
+    expect(formatCurrency(-2, { sign: false })).toEqual('¥ -0.02');
     expect(formatCurrency(-2, { sign: true })).toEqual('¥ -0.02');
     expect(formatCurrency(-100, { sign: true })).toEqual('¥ -1.00');
     expect(formatCurrency(-999, { sign: true })).toEqual('¥ -9.99');
diff --git a/packages/utility/src/format/currency.ts b/packages/utility/src/format/currency.ts
index 4f71987..bbebed2 100644
--- a/packages/utility/src/format/currency.ts
+++ b/packages/utility/src/format/currency.ts
@@ -1,3 +1,14 @@
+/**
+ * Format currency
+ *
+ * @example
+ * formatCurrency(2) // => '¥ 0.02'
+ * formatCurrency(2, { decimals: 0 })) // => '¥ 0.02'
+ * formatCurrency(2, { sign: true })) // => '¥ +0.02'
+ * formatCurrency(2, { symbol: '$' })) // => '$ 0.02'
+ */
+
+// TODO: F2Y 并没有使用
 export const formatCurrency = (
   currency: number,
   options?: { decimals?: number; symbol?: string; sign?: boolean; F2Y?: boolean },
diff --git a/packages/utility/src/format/starlize.spec.ts b/packages/utility/src/format/starlize.spec.ts
index 79eed0c..040d95f 100644
--- a/packages/utility/src/format/starlize.spec.ts
+++ b/packages/utility/src/format/starlize.spec.ts
@@ -4,14 +4,16 @@ import { starlizeCard, starlizeName } from './starlize';
 describe('starlize', () => {
   test('starlizeName', () => {
     expect(starlizeName('')).toEqual('');
-    expect(starlizeName('张')).toEndWith('张');
-    expect(starlizeName('张三')).toEndWith('*三');
-    expect(starlizeName('张三李')).toEndWith('张*李');
-    expect(starlizeName('张三李四')).toEndWith('张**四');
+    expect(starlizeName('张')).toEqual('张');
+    expect(starlizeName('张三')).toEqual('*三');
+    expect(starlizeName('张三李')).toEqual('张*李');
+    expect(starlizeName('张三李四')).toEqual('张**四');
   });
 
   test('starlizeCard', () => {
     expect(starlizeCard('', 0, 0)).toEqual('');
+    expect(starlizeCard('0000', 1, 1)).toEqual('0**0');
+    expect(starlizeCard('0000', 2, 1)).toEqual('00*0');
     expect(starlizeCard('0000000000000000', 0, 0)).toEqual('****************');
     expect(starlizeCard('0', 4, 3)).toEqual('*');
     expect(starlizeCard('00', 4, 3)).toEqual('**');
diff --git a/packages/utility/src/format/starlize.ts b/packages/utility/src/format/starlize.ts
index a481ac8..f943a5a 100644
--- a/packages/utility/src/format/starlize.ts
+++ b/packages/utility/src/format/starlize.ts
@@ -1,3 +1,11 @@
+/**
+ * The middle of the name will be replaced with *. (string length > 2)
+ *
+ * @example
+ * starlizeName('张三') // => '张*'
+ * starlizeName('张三李') // => '张*李'
+ * starlizeName('张三李四') // => '张**四'
+ */
 export const starlizeName = (name: string): string => {
   const length = name.length;
 
@@ -12,6 +20,20 @@ export const starlizeName = (name: string): string => {
   return `${name[0]}${'*'.repeat(length - 2)}${name[length - 1]}`;
 };
 
+/**
+ * The middle of the card number will be replaced with *.
+ *
+ * @param {string} card The card number.
+ * @param {number} front The number of characters to keep at the beginning.
+ * @param {number} after The number of characters to keep at the end.
+ *
+ * @example
+ * starlizeCard('000', 1, 1) // => '0*0'
+ * starlizeCard('0000', 1, 1) // => '0**0'
+ * starlizeCard('0000', 2, 1) // => '00*0'
+ * starlizeCard('0000000000000000', 0, 0) // => '****************'
+ * starlizeCard('0000000000000000', 4, 4) // => '0000********0000'
+ */
 export const starlizeCard = (card: string, front: number, after: number): string => {
   const length = card.length;
 
diff --git a/packages/utility/src/generator/oid.spec.ts b/packages/utility/src/generator/oid.spec.ts
index b189ef0..462c939 100644
--- a/packages/utility/src/generator/oid.spec.ts
+++ b/packages/utility/src/generator/oid.spec.ts
@@ -1,10 +1,12 @@
 import { describe, expect, test } from 'bun:test';
+import { format } from 'date-fns';
 import { oid } from './oid';
 
 describe('oid', () => {
   test('normal usage', () => {
     const _oid = oid();
 
+    expect(_oid).toStartWith(format(new Date(), 'yyMMdd'));
     expect(_oid.length).toEqual(20);
   });
 });
diff --git a/packages/utility/src/generator/oid.ts b/packages/utility/src/generator/oid.ts
index ce32b78..139883d 100644
--- a/packages/utility/src/generator/oid.ts
+++ b/packages/utility/src/generator/oid.ts
@@ -5,7 +5,7 @@
  * oid() // => 24123141323885749088
  */
 export const oid = (): string => {
-  const now = new Date('2024-12-31T00:00:00.000Z');
+  const now = new Date();
   const date = now.toISOString().slice(2, 10).replace(/-/g, ''); // 24-12-31 -> 241231
   const time = now.getMilliseconds().toString() + now.getTime().toString();
   const timeRand = (parseInt(time, 10) / 42).toString(10).slice(0, 8);
diff --git a/packages/utility/src/misc/get-distance.ts b/packages/utility/src/misc/get-distance.ts
index 4a1bce9..36f92b1 100644
--- a/packages/utility/src/misc/get-distance.ts
+++ b/packages/utility/src/misc/get-distance.ts
@@ -14,12 +14,8 @@ const validatePoint = ({ longitude, latitude }: { longitude: number; latitude: n
  * 计算两个坐标点之间距离（单位M）
  * https://mixbit.xyz/post/javascript-calculates-the-distance-between-two-points-of-coordinates.html
  *
- * @param {object} point1 坐标点1
- * @param {string} point1.longitude 经度
- * @param {string} point1.latitude 纬度
- * @param {object} point2 坐标点2
- * @param {string} point2.longitude 经度
- * @param {string} point2.latitude 纬度
+ * @example
+ * getDistance({ latitude: 39.916668, longitude: 116.383331 }, { latitude: 31.150681, longitude: 121.124176 }) // => 1065706.56
  */
 export const getDistance = (
   point1: { latitude: number; longitude: number },
diff --git a/packages/utility/src/misc/get-district.ts b/packages/utility/src/misc/get-district.ts
index ddf01a7..035c7d9 100644
--- a/packages/utility/src/misc/get-district.ts
+++ b/packages/utility/src/misc/get-district.ts
@@ -35,6 +35,14 @@ export const districtStartWith = ({ title, district }: { title: string; district
   return true;
 };
 
+/**
+ * 获取地址中的区域
+ * - 如果 title 中从第 0 到第 3 个字符开始的子串与 district 或去掉“区”后的 district 相匹配，则认为无效。
+ *
+ * @example
+ * getDistance({ address: "广东省深圳市罗湖区科技园路0号" }) // => 罗湖区
+ * getDistance({ address: "广东省深圳市罗湖区科技园路0号", title: "罗湖星巴克" }) // => ""
+ */
 export const getDistrict = ({ title = '', address }: { title?: string; address?: string }): string => {
   if (!address) {
     return '';
diff --git a/packages/utility/src/misc/stringify.spec.ts b/packages/utility/src/misc/stringify.spec.ts
index 93a6eef..a51bf44 100644
--- a/packages/utility/src/misc/stringify.spec.ts
+++ b/packages/utility/src/misc/stringify.spec.ts
@@ -5,6 +5,7 @@ describe('misc', () => {
   test('stringify', () => {
     expect(stringify({ a: '1' })).toEqual('{"a":"1"}');
     expect(stringify('{"a":"1"}')).toEqual('{"a":"1"}');
+    expect(() => stringify('asd')).toThrow('Not Valid JSON');
     expect(() => stringify(true)).toThrow('Not Valid JSON');
   });
 });
diff --git a/packages/utility/src/misc/stringify.ts b/packages/utility/src/misc/stringify.ts
index a69eac6..494df9d 100644
--- a/packages/utility/src/misc/stringify.ts
+++ b/packages/utility/src/misc/stringify.ts
@@ -12,6 +12,13 @@ const isJson = (value: any): boolean => {
   }
 };
 
+/**
+ * Stringify JSON
+ *
+ * @example
+ * stringify({ a: '1' }) // => '{"a":"1"}'
+ * stringify('{"a":"1"}') // => '{"a":"1"}'
+ */
 export const stringify = (value: any): string => {
   if (!isJson(value)) {
     throw new InternalErrorException('Not Valid JSON');
diff --git a/packages/utility/src/string/template.spec.ts b/packages/utility/src/string/template.spec.ts
index 2bffd2a..66cdca9 100644
--- a/packages/utility/src/string/template.spec.ts
+++ b/packages/utility/src/string/template.spec.ts
@@ -9,4 +9,17 @@ describe('template', () => {
     expect(template('hello, {{name}}', { age: 1 })).toBe('hello, ');
     expect(template('hello, {{name}}{{!}}', { '!': '！' })).toBe('hello, ！');
   });
+
+  test('empty', () => {
+    expect(template('', { name: 'world' })).toBe('');
+    expect(template('', {})).toBe('');
+    expect(template('hello', {})).toBe('hello');
+
+    expect(template('hello {{ }}', {})).toBe('hello ');
+    expect(template('hello {{ name }}', {})).toBe('hello ');
+  });
+
+  test('do not support {}', () => {
+    expect(template('hello { name }', {})).toBe('hello { name }');
+  });
 });
diff --git a/packages/utility/src/string/trim.spec.ts b/packages/utility/src/string/trim.spec.ts
index c574ae3..1cc9d37 100644
--- a/packages/utility/src/string/trim.spec.ts
+++ b/packages/utility/src/string/trim.spec.ts
@@ -3,6 +3,13 @@ import { WHITESPACE } from '../constants';
 import { trim, trimEnd, trimStart } from './trim';
 
 describe('trim', () => {
+  test('normal usage', () => {
+    expect(trim('  a b c  ', ' ')).toBe('a b c');
+    expect(trim('-_-a-b-c-_-', '_-')).toBe('a-b-c');
+    expect(trim('/repos/:owner/:repo/', '/')).toBe('repos/:owner/:repo');
+    expect(trim('222222__hello__1111111', '12_')).toBe('hello');
+  });
+
   test('should work for empty string', () => {
     expect(trim(null, '_')).toBe('');
     expect(trim('', '_')).toBe('');
@@ -26,16 +33,16 @@ describe('trim', () => {
 
     expect(trim(str)).toBe(exp);
   });
-
-  test('should remove chars', () => {
-    expect(trim('  a b c  ', ' ')).toBe('a b c');
-    expect(trim('-_-a-b-c-_-', '_-')).toBe('a-b-c');
-    expect(trim('/repos/:owner/:repo/', '/')).toBe('repos/:owner/:repo');
-    expect(trim('222222__hello__1111111', '12_')).toBe('hello');
-  });
 });
 
 describe('trimStart', () => {
+  test('normal usage', () => {
+    expect(trimStart('  a b c  ', ' ')).toBe('a b c  ');
+    expect(trimStart('-_-a-b-c-_-', '_-')).toBe('a-b-c-_-');
+    expect(trimStart('/repos/:owner/:repo/', '/')).toBe('repos/:owner/:repo/');
+    expect(trimStart('222222__hello__1111111', '12_')).toBe('hello__1111111');
+  });
+
   test('should work for empty string', () => {
     expect(trimStart(null, '_')).toBe('');
     expect(trimStart('', '_')).toBe('');
@@ -59,16 +66,16 @@ describe('trimStart', () => {
 
     expect(trimStart(str)).toBe(exp);
   });
-
-  test('should remove chars', () => {
-    expect(trimStart('  a b c  ', ' ')).toBe('a b c  ');
-    expect(trimStart('-_-a-b-c-_-', '_-')).toBe('a-b-c-_-');
-    expect(trimStart('/repos/:owner/:repo/', '/')).toBe('repos/:owner/:repo/');
-    expect(trimStart('222222__hello__1111111', '12_')).toBe('hello__1111111');
-  });
 });
 
 describe('trimEnd', () => {
+  test('normal usage', () => {
+    expect(trimEnd('  a b c  ', ' ')).toBe('  a b c');
+    expect(trimEnd('-_-a-b-c-_-', '_-')).toBe('-_-a-b-c');
+    expect(trimEnd('/repos/:owner/:repo/', '/')).toBe('/repos/:owner/:repo');
+    expect(trimEnd('222222__hello__1111111', '12_')).toBe('222222__hello');
+  });
+
   test('should work for empty string', () => {
     expect(trimEnd(null, '_')).toBe('');
     expect(trimEnd('', '_')).toBe('');
@@ -92,11 +99,4 @@ describe('trimEnd', () => {
 
     expect(trimEnd(str)).toBe(exp);
   });
-
-  test('should remove chars', () => {
-    expect(trimEnd('  a b c  ', ' ')).toBe('  a b c');
-    expect(trimEnd('-_-a-b-c-_-', '_-')).toBe('-_-a-b-c');
-    expect(trimEnd('/repos/:owner/:repo/', '/')).toBe('/repos/:owner/:repo');
-    expect(trimEnd('222222__hello__1111111', '12_')).toBe('222222__hello');
-  });
 });