rf: rename type and fn (#79)

* refactor: rename and enhance string validation functions

- Renamed `isSafeString` to `isStrictSafeString` and updated its implementation to enforce stricter validation criteria for strings.
- Renamed `genSafeString` to `genStrictSafeString` to reflect the stricter generation of safe strings.
- Updated corresponding unit tests to match the new function names and ensure they validate the expected behavior for strict safety checks.

* feat: enhance isStrictSafeString validation and add test cases

- Updated the isStrictSafeString function to use a regular expression for improved string validation, ensuring only alphanumeric characters are accepted.
- Added new test cases to validate the function against various inputs, including numeric strings and disallowed characters.
- This change enhances the robustness of string validation in the codebase.

* feat: enhance string type definitions and documentation

- Added detailed JSDoc comments for the StrictSafeString type and isStrictSafeString function, including descriptions in both English and Chinese.
- Improved the documentation for the fromUnicodeStr and textWithBOM functions, clarifying parameter types and return values.
- Enhanced overall code readability and maintainability through better documentation practices.

* refactor: move isStrictSafeString function and tests to appropriate files

- Removed the isStrictSafeString function and its tests from str.ts and str.test.ts, respectively.
- Added the isStrictSafeString function and its corresponding test cases to string.ts and string.test.ts for better organization and clarity.
- This change improves the structure of the codebase by ensuring that string validation functions and tests are located together.

js/str.test.ts

@@ -1,37 +1,21 @@
 import {
   fromUnicodeStr,
   genRandomString,
-  genSafeString,
-  isSafeString,
+  genStrictSafeString,
   textWithBOM,
 } from './str.ts';
-import { assert, assertEquals } from '@std/assert';
-
-Deno.test('isSafeString', () => {
-  assert(isSafeString('9'));
-  assert(isSafeString('0'));
-  assert(isSafeString('a'));
-  assert(isSafeString('z'));
-  assert(isSafeString('A'));
-  assert(isSafeString('Z'));
-  assert(!isSafeString('.'));
-  assert(!isSafeString('a🥳'));
-  assert(
-    !isSafeString(`
-`),
-  );
-});
+import { assertEquals } from '@std/assert';
 
-Deno.test('genSafeString', () => {
+Deno.test('genStrictSafeString', () => {
   const len = 65536;
 
-  console.time('genSafeString');
-  genSafeString(len);
-  console.timeEnd('genSafeString');
+  console.time('genStrictSafeString');
+  genStrictSafeString(len);
+  console.timeEnd('genStrictSafeString');
 
-  assertEquals(genSafeString(5).length, 5);
-  assertEquals(typeof genSafeString(5)[4], 'string');
-  console.log('genSafeString(5)', genSafeString(5));
+  assertEquals(genStrictSafeString(5).length, 5);
+  assertEquals(typeof genStrictSafeString(5)[4], 'string');
+  console.log('genStrictSafeString(5)', genStrictSafeString(5));
 });
 
 Deno.test('genRandomString', () => {

js/str.ts

@@ -1,32 +1,9 @@
-type SafeString = string;
-/**
- * check str in [az09AZ]
- */
-export function isSafeString(str: string): str is SafeString {
-  for (let i = 0; i < str.length; i++) {
-    const u = str.codePointAt(i);
-    if (!u) {
-      return false;
-    }
-    if (u > 122 || u < 48) { // z=122, 0=48
-      return false;
-    }
-    if (u > 57 && u < 65) { // 9=57, A=65
-      return false;
-    }
-    if (u > 90 && u < 97) { // Z=90, a=97
-      return false;
-    }
-  }
-  return true;
-}
-
 /**
  * not a ramdom string (but faster)
  * @param len
  * @returns
  */
-export function genSafeString(len: number): string {
+export function genStrictSafeString(len: number): string {
   return new TextDecoder().decode(
     crypto.getRandomValues(new Uint8Array(len)).map((u) => {
       if (u > 122 || u < 48) { // z=122, 0=48
@@ -62,8 +39,9 @@ export function genRandomString(
 }
 
 /**
+ * Decode string from Unicode encoding to UTF-8
  * 编码字符串为 UTF-8
- * @param str 16 位的 Unicode 编码的 ASCII 字符串, 比如 `\u8fd9a` 表示 `这a`
+ * @param str 16-bit Unicode encoded ASCII string, e.g. `\u8fd9a` represents `这a`
  */
 export function fromUnicodeStr(str: string): string {
   let encoded = '';
@@ -92,11 +70,12 @@ export function fromUnicodeStr(str: string): string {
 }
 
 /**
+ * Add UTF-8 BOM to text (for Windows...)
  * 为文本添加 UTF-8 BOM (for Windows...)
  * - [Magic Number](https://en.wikipedia.org/wiki/Magic_number_(programming))
  * - [Byte Order Mark](https://en.wikipedia.org/wiki/Byte_order_mark)
- * @param v 需要增加 BOM 的文本
- * @returns
+ * @param v Text that needs BOM added
+ * @returns Text with BOM header
  */
 export function textWithBOM(v: Uint8Array | string): Uint8Array {
   let data: Uint8Array;

ts/string.test.ts

@@ -1,6 +1,24 @@
-import { isSafeString } from './string.ts';
+import { isSafeString, isStrictSafeString } from './string.ts';
 import { assert } from '@std/assert';
 
+Deno.test('isStrictSafeString', () => {
+  assert(isStrictSafeString('9'));
+  assert(isStrictSafeString('0'));
+  assert(isStrictSafeString('a'));
+  assert(isStrictSafeString('z'));
+  assert(isStrictSafeString('A'));
+  assert(isStrictSafeString('Z'));
+  assert(isStrictSafeString('1234567890'));
+  assert(!isStrictSafeString('Z_'));
+  assert(!isStrictSafeString('_Z'));
+  assert(!isStrictSafeString('.'));
+  assert(!isStrictSafeString('a🥳'));
+  assert(
+    !isStrictSafeString(`
+`),
+  );
+});
+
 Deno.test('isSafeString', () => {
   assert(isSafeString(''));
   assert(isSafeString('1 2'));

ts/string.ts

@@ -10,6 +10,25 @@ export type JWTString = string;
 /** 手机号码 */
 export type PhoneNum = string;
 
+/**
+ * [Type] Strict safe string (only contains a-z, A-Z, 0-9)
+ * [类型] 严格安全的字符串 (仅包含 a-z, A-Z, 0-9)
+ *
+ * @author iugo <[email protected]>
+ */
+export type StrictSafeString = string;
+
+/**
+ * Check if a string is strictly safe (only contains a-z, A-Z, 0-9)
+ * 检查字符串是否为严格安全的字符串 (仅包含 a-z, A-Z, 0-9)
+ *
+ * @param str String to check
+ * @returns Whether the string is strictly safe
+ */
+export function isStrictSafeString(str: string): str is StrictSafeString {
+  return /^[a-zA-Z0-9]+$/.test(str);
+}
+
 /**
  * [类型] 不包含英文特殊字符 (ASCII 范围内除了字母, 数字, 下划线和空格以外的字符)
  * @author iugo <[email protected]>