@xxkatt/utils 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xxkatt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,68 @@
-# Temporary Holding Version
+# @xxkatt/utils
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+常用的 JavaScript / TypeScript 工具函数，提供 ESM 导出和 TypeScript 类型声明，无运行时依赖。
+
+## 安装
+
+```sh
+pnpm add @xxkatt/utils
+```
+
+## 使用
+
+```ts
+import { randomId, uuid } from '@xxkatt/utils'
+
+uuid() // 32 位 UUID v4，不带横杠
+uuid('', true) // 标准 UUID v4：xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+uuid('user_') // 添加前缀：user_…
+uuid('user_', true) // 添加前缀并保留横杠
+
+randomId() // 32 个随机的小写十六进制字符
+randomId(8, 10) // 8 位随机数字，可能以 0 开头
+randomId(21, 62) // 21 个随机字符，字符来自 0–9、a–z、A–Z
+```
+
+## API
+
+### uuid(prefix?, hyphens?)
+
+生成 UUID v4，返回 `string`。
+
+| 参数      | 类型      | 默认值  | 说明                                 |
+| --------- | --------- | ------- | ------------------------------------ |
+| `prefix`  | `string`  | `''`    | 原样拼接在 UUID 前，分隔符需自行提供 |
+| `hyphens` | `boolean` | `false` | 是否保留标准 UUID 中的横杠           |
+
+不计前缀时，默认返回 32 个小写十六进制字符；保留横杠时长度为 36。
+
+### randomId(length?, radix?)
+
+使用加密安全随机数生成自定义 ID，返回 `string`。
+
+| 参数     | 类型     | 默认值 | 说明                                           |
+| -------- | -------- | ------ | ---------------------------------------------- |
+| `length` | `number` | `32`   | 字符数量，必须为非负安全整数；`0` 返回空字符串 |
+| `radix`  | `number` | `16`   | 基数，必须为 `2` 至 `62` 的整数（含边界）      |
+
+字符表为 `0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ`，使用其中前 `radix` 个字符。参数不符合要求时抛出 `RangeError`；`length` 为 `0` 时仍会校验 `radix`。
+
+自定义 ID 不遵循 UUID 格式，随机结果可能重复。需要标准 UUID v4 时请使用 `uuid`。
+
+## 运行环境
+
+支持 Node.js 24+，以及支持 Web Crypto API 和 ES2022 的现代浏览器。
+
+- `uuid` 依赖 `globalThis.crypto.randomUUID()`；浏览器中需要 HTTPS 或 localhost 等安全上下文。
+- `randomId` 依赖 `globalThis.crypto.getRandomValues()`。
+- 通过 ESM `import` 使用。
+
+## 文档与反馈
+
+- [完整 API 文档](https://github.com/xxkatt/xxkatt-utils/tree/master/apps/docs/js/utils)
+- [源码仓库](https://github.com/xxkatt/xxkatt-utils)
+- [问题反馈](https://github.com/xxkatt/xxkatt-utils/issues)
+
+## 许可证
+
+[MIT](./LICENSE) © 2026 xxkatt

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 生成 UUID v4，默认返回 32 个小写十六进制字符。
+ *
+ * @param prefix 原样拼接在 UUID 前的前缀，分隔符需自行提供。
+ * @param hyphens 是否保留标准 UUID 中的横杠，默认 false。
+ * @example
+ * uuid()
+ * uuid('', true)
+ * uuid('user_')
+ * uuid('user_', true)
+ */
+export declare function uuid(prefix?: string, hyphens?: boolean): string;
+/**
+ * 使用加密安全随机数生成 ID；自定义长度的 ID 不遵循 UUID 格式。
+ * 字符表依次为 0–9、a–z、A–Z，使用前 radix 个字符。
+ *
+ * @param length 字符数量，必须为非负安全整数，默认 32；0 返回空字符串。
+ * @param radix 基数，必须为 2–62 的整数，默认 16。
+ * @example
+ * randomId(8, 10)
+ * randomId(21, 62)
+ */
+export declare function randomId(length?: number, radix?: number): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,47 @@
+// src/uuid/index.ts
+const ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
+/**
+* 生成 UUID v4，默认返回 32 个小写十六进制字符。
+*
+* @param prefix 原样拼接在 UUID 前的前缀，分隔符需自行提供。
+* @param hyphens 是否保留标准 UUID 中的横杠，默认 false。
+* @example
+* uuid()
+* uuid('', true)
+* uuid('user_')
+* uuid('user_', true)
+*/
+function uuid(prefix = "", hyphens = false) {
+	const value = globalThis.crypto.randomUUID();
+	return prefix + (hyphens ? value : value.replaceAll("-", ""));
+}
+/**
+* 使用加密安全随机数生成 ID；自定义长度的 ID 不遵循 UUID 格式。
+* 字符表依次为 0–9、a–z、A–Z，使用前 radix 个字符。
+*
+* @param length 字符数量，必须为非负安全整数，默认 32；0 返回空字符串。
+* @param radix 基数，必须为 2–62 的整数，默认 16。
+* @example
+* randomId(8, 10)
+* randomId(21, 62)
+*/
+function randomId(length = 32, radix = 16) {
+	if (!Number.isSafeInteger(length) || length < 0) throw new RangeError("length must be a non-negative safe integer");
+	if (!Number.isInteger(radix) || radix < 2 || radix > 62) throw new RangeError("radix must be an integer between 2 and 62");
+	if (length === 0) return "";
+	const bytes = new Uint8Array(Math.min(length, 65536));
+	const limit = 256 - 256 % radix;
+	let value = "";
+	while (value.length < length) {
+		globalThis.crypto.getRandomValues(bytes);
+		for (const byte of bytes) {
+			if (byte >= limit) continue;
+			value += ALPHABET.charAt(byte % radix);
+			if (value.length === length) break;
+		}
+	}
+	return value;
+}
+export { randomId, uuid };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/uuid/index.ts"],"sourcesContent":["const ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'\n\n/**\n * 生成 UUID v4，默认返回 32 个小写十六进制字符。\n *\n * @param prefix 原样拼接在 UUID 前的前缀，分隔符需自行提供。\n * @param hyphens 是否保留标准 UUID 中的横杠，默认 false。\n * @example\n * uuid()\n * uuid('', true)\n * uuid('user_')\n * uuid('user_', true)\n */\nexport function uuid(prefix: string = '', hyphens: boolean = false): string {\n  const value = globalThis.crypto.randomUUID()\n  return prefix + (hyphens ? value : value.replaceAll('-', ''))\n}\n\n/**\n * 使用加密安全随机数生成 ID；自定义长度的 ID 不遵循 UUID 格式。\n * 字符表依次为 0–9、a–z、A–Z，使用前 radix 个字符。\n *\n * @param length 字符数量，必须为非负安全整数，默认 32；0 返回空字符串。\n * @param radix 基数，必须为 2–62 的整数，默认 16。\n * @example\n * randomId(8, 10)\n * randomId(21, 62)\n */\nexport function randomId(length: number = 32, radix: number = 16): string {\n  if (!Number.isSafeInteger(length) || length < 0) {\n    throw new RangeError('length must be a non-negative safe integer')\n  }\n  if (!Number.isInteger(radix) || radix < 2 || radix > ALPHABET.length) {\n    throw new RangeError('radix must be an integer between 2 and 62')\n  }\n  if (length === 0) return ''\n\n  const bytes = new Uint8Array(Math.min(length, 65_536))\n  const limit = 256 - (256 % radix)\n  let value = ''\n\n  while (value.length < length) {\n    globalThis.crypto.getRandomValues(bytes)\n    for (const byte of bytes) {\n      // 丢弃无法均分到字符表的尾部区间，避免取模导致分布偏差。\n      if (byte >= limit) continue\n      value += ALPHABET.charAt(byte % radix)\n      if (value.length === length) break\n    }\n  }\n\n  return value\n}\n"],"mappings":";AAAA,MAAM,WAAW;;;;;;;;;;;;AAajB,SAAgB,KAAK,SAAiB,IAAI,UAAmB,OAAe;CAC1E,MAAM,QAAQ,WAAW,OAAO,WAAW;CAC3C,OAAO,UAAU,UAAU,QAAQ,MAAM,WAAW,KAAK,EAAE;AAC7D;;;;;;;;;;;AAYA,SAAgB,SAAS,SAAiB,IAAI,QAAgB,IAAY;CACxE,IAAI,CAAC,OAAO,cAAc,MAAM,KAAK,SAAS,GAC5C,MAAM,IAAI,WAAW,4CAA4C;CAEnE,IAAI,CAAC,OAAO,UAAU,KAAK,KAAK,QAAQ,KAAK,QAAQ,IACnD,MAAM,IAAI,WAAW,2CAA2C;CAElE,IAAI,WAAW,GAAG,OAAO;CAEzB,MAAM,QAAQ,IAAI,WAAW,KAAK,IAAI,QAAQ,KAAM,CAAC;CACrD,MAAM,QAAQ,MAAO,MAAM;CAC3B,IAAI,QAAQ;CAEZ,OAAO,MAAM,SAAS,QAAQ;EAC5B,WAAW,OAAO,gBAAgB,KAAK;EACvC,KAAK,MAAM,QAAQ,OAAO;GAExB,IAAI,QAAQ,OAAO;GACnB,SAAS,SAAS,OAAO,OAAO,KAAK;GACrC,IAAI,MAAM,WAAW,QAAQ;EAC/B;CACF;CAEA,OAAO;AACT"}

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@xxkatt/utils",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "description": "常用的 JavaScript / TypeScript 工具函数",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xxkatt/xxkatt-utils.git",
+    "directory": "packages/js/utils"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\""
+  }
 }