@fast-china/utils 1.0.38 → 2.0.2

package/dist/object/index.d.mts

@@ -0,0 +1,76 @@
+//#region src/object/index.d.ts
+/** URL 查询参数支持的单值类型。 */
+type QueryPrimitive = bigint | boolean | number | string | null | undefined;
+/** URL 查询参数值；数组使用重复键表示。 */
+type QueryValue = QueryPrimitive | readonly QueryPrimitive[];
+/** {@link toQueryString} 的序列化选项。 */
+interface QueryStringOptions {
+  /** 返回非空结果时是否添加 `?`；默认 `false`。 */
+  prefixQuestionMark?: boolean;
+  /** 是否按键的 UTF-16 码元顺序稳定排序；默认保留对象枚举顺序。 */
+  sort?: boolean;
+  /** 空格编码方式；默认遵循表单编码并输出 `+`。 */
+  space?: "percent" | "plus";
+}
+/**
+ * 判断值是否是普通对象。
+ *
+ * @param value - 任意待检查值。
+ * @returns 原型为 `Object.prototype` 或 `null` 时返回 `true`。
+ */
+declare function isPlainObject(value: unknown): value is Record<PropertyKey, unknown>;
+/**
+ * 安全判断对象是否拥有自己的属性。
+ *
+ * @remarks 不调用可能被对象覆盖的 `hasOwnProperty`。
+ * @param value - 待检查对象。
+ * @param key - 字符串、数字或 Symbol 属性键。
+ * @returns 属性为对象自有属性时返回 `true`，并收窄键类型。
+ */
+declare function hasOwn<ObjectType extends object, Key extends PropertyKey>(value: ObjectType, key: Key): key is Key & keyof ObjectType;
+/**
+ * 从对象中选择指定自有可枚举属性。
+ *
+ * @param source - 不会被修改的源对象。
+ * @param keys - 需要保留的键；不存在的键被忽略。
+ * @returns 新对象，保持 `keys` 的遍历顺序。
+ */
+declare function pick<Source extends object, Keys extends readonly (keyof Source)[]>(source: Source, keys: Keys): Pick<Source, Keys[number]>;
+/**
+ * 浅复制对象并删除指定属性。
+ *
+ * @param source - 不会被修改的源对象。
+ * @param keys - 需要排除的键。
+ * @returns 包含其余自有可枚举字符串与 Symbol 属性的新对象。
+ */
+declare function omit<Source extends object, Keys extends readonly (keyof Source)[]>(source: Source, keys: Keys): Omit<Source, Keys[number]>;
+/**
+ * 映射对象的自有可枚举属性值。
+ *
+ * @param source - 不会被修改的源对象。
+ * @param mapper - 接收值、键和源对象的映射函数。
+ * @returns 保留原键的新对象。
+ */
+declare function mapValues<Source extends object, Result>(source: Source, mapper: (value: Source[keyof Source], key: keyof Source, source: Source) => Result): { [Key in keyof Source]: Result; };
+/**
+ * 对自有可枚举属性执行 SameValue 浅比较。
+ *
+ * @remarks 嵌套对象只比较引用；`NaN` 相等，`0` 与 `-0` 不相等。
+ * @param left - 第一对象。
+ * @param right - 第二对象。
+ * @returns 自有可枚举键集合与对应值均满足 SameValue 时返回 `true`。
+ */
+declare function shallowEqual(left: object, right: object): boolean;
+/**
+ * 将对象序列化为标准 URL 查询字符串。
+ *
+ * @remarks `null` 与 `undefined` 被跳过；数组使用重复键；返回值不会修改输入。
+ * @param value - 查询参数对象。
+ * @param options - 排序、空格和问号前缀选项。
+ * @returns URL 编码后的查询字符串；没有参数时始终返回空字符串。
+ * @throws `RangeError` 当参数包含 `NaN` 或无穷数字。
+ */
+declare function toQueryString(value: Readonly<Record<string, QueryValue>>, options?: QueryStringOptions): string;
+//#endregion
+export { QueryPrimitive, QueryStringOptions, QueryValue, hasOwn, isPlainObject, mapValues, omit, pick, shallowEqual, toQueryString };
+//# sourceMappingURL=index.d.mts.map

package/dist/object/index.mjs

@@ -0,0 +1,134 @@
+//#region src/object/index.ts
+/**
+* 判断 Query Value 是否为重复参数数组。
+*
+* @param value - 单值或数组形式的 Query Value。
+* @returns 是只读原始值数组时返回 `true`。
+*/
+const isQueryPrimitiveArray = (value) => Array.isArray(value);
+/**
+* 安全写入结果对象的自有可枚举属性。
+*
+* @remarks 使用 `defineProperty` 避免 `__proto__` 触发 Setter，并显式拒绝三个原型污染键。
+* @param target - 要写入的结果对象。
+* @param key - 自有属性键。
+* @param value - 属性值。
+* @throws `TypeError` 当键为 `__proto__`、`prototype` 或 `constructor`。
+*/
+const defineEnumerableProperty = (target, key, value) => {
+	Object.defineProperty(target, key, {
+		configurable: true,
+		enumerable: true,
+		value,
+		writable: true
+	});
+};
+/**
+* 判断值是否是普通对象。
+*
+* @param value - 任意待检查值。
+* @returns 原型为 `Object.prototype` 或 `null` 时返回 `true`。
+*/
+function isPlainObject(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === null || prototype === Object.prototype;
+}
+/**
+* 安全判断对象是否拥有自己的属性。
+*
+* @remarks 不调用可能被对象覆盖的 `hasOwnProperty`。
+* @param value - 待检查对象。
+* @param key - 字符串、数字或 Symbol 属性键。
+* @returns 属性为对象自有属性时返回 `true`，并收窄键类型。
+*/
+function hasOwn(value, key) {
+	return Object.hasOwn(value, key);
+}
+/**
+* 从对象中选择指定自有可枚举属性。
+*
+* @param source - 不会被修改的源对象。
+* @param keys - 需要保留的键；不存在的键被忽略。
+* @returns 新对象，保持 `keys` 的遍历顺序。
+*/
+function pick(source, keys) {
+	const result = {};
+	for (const key of keys) if (Object.prototype.propertyIsEnumerable.call(source, key)) defineEnumerableProperty(result, key, source[key]);
+	return result;
+}
+/**
+* 浅复制对象并删除指定属性。
+*
+* @param source - 不会被修改的源对象。
+* @param keys - 需要排除的键。
+* @returns 包含其余自有可枚举字符串与 Symbol 属性的新对象。
+*/
+function omit(source, keys) {
+	const result = { ...source };
+	for (const key of keys) Reflect.deleteProperty(result, key);
+	return result;
+}
+/**
+* 映射对象的自有可枚举属性值。
+*
+* @param source - 不会被修改的源对象。
+* @param mapper - 接收值、键和源对象的映射函数。
+* @returns 保留原键的新对象。
+*/
+function mapValues(source, mapper) {
+	const result = {};
+	for (const key of Reflect.ownKeys(source)) if (Object.prototype.propertyIsEnumerable.call(source, key)) defineEnumerableProperty(result, key, mapper(source[key], key, source));
+	return result;
+}
+/**
+* 对自有可枚举属性执行 SameValue 浅比较。
+*
+* @remarks 嵌套对象只比较引用；`NaN` 相等，`0` 与 `-0` 不相等。
+* @param left - 第一对象。
+* @param right - 第二对象。
+* @returns 自有可枚举键集合与对应值均满足 SameValue 时返回 `true`。
+*/
+function shallowEqual(left, right) {
+	if (Object.is(left, right)) return true;
+	const leftKeys = Reflect.ownKeys(left).filter((key) => Object.prototype.propertyIsEnumerable.call(left, key));
+	const rightKeys = Reflect.ownKeys(right).filter((key) => Object.prototype.propertyIsEnumerable.call(right, key));
+	if (leftKeys.length !== rightKeys.length) return false;
+	return leftKeys.every((key) => Object.hasOwn(right, key) && Object.is(Reflect.get(left, key), Reflect.get(right, key)));
+}
+/**
+* 把 Query 原始值规范化为文本。
+*
+* @param value - 已排除空值的字符串、数字、布尔值或 BigInt。
+* @returns 与 URLSearchParams 兼容的文本值。
+* @throws `RangeError` 当数字不是有限值。
+*/
+const serializeQueryValue = (value) => {
+	if (typeof value === "number" && !Number.isFinite(value)) throw new RangeError("Query parameter numbers must be finite.");
+	return String(value);
+};
+/**
+* 将对象序列化为标准 URL 查询字符串。
+*
+* @remarks `null` 与 `undefined` 被跳过；数组使用重复键；返回值不会修改输入。
+* @param value - 查询参数对象。
+* @param options - 排序、空格和问号前缀选项。
+* @returns URL 编码后的查询字符串；没有参数时始终返回空字符串。
+* @throws `RangeError` 当参数包含 `NaN` 或无穷数字。
+*/
+function toQueryString(value, options = {}) {
+	const entries = Object.entries(value);
+	if (options.sort) entries.sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0);
+	const parameters = new URLSearchParams();
+	for (const [key, rawValue] of entries) {
+		const values = isQueryPrimitiveArray(rawValue) ? rawValue : [rawValue];
+		for (const item of values) if (item !== null && item !== void 0) parameters.append(key, serializeQueryValue(item));
+	}
+	let result = parameters.toString();
+	if (options.space === "percent") result = result.replace(/\+/gu, "%20");
+	return result && options.prefixQuestionMark ? `?${result}` : result;
+}
+//#endregion
+export { hasOwn, isPlainObject, mapValues, omit, pick, shallowEqual, toQueryString };
+
+//# sourceMappingURL=index.mjs.map

package/dist/object/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/object/index.ts"],"sourcesContent":["/** URL 查询参数支持的单值类型。 */\nexport type QueryPrimitive = bigint | boolean | number | string | null | undefined;\n\n/** URL 查询参数值；数组使用重复键表示。 */\nexport type QueryValue = QueryPrimitive | readonly QueryPrimitive[];\n\n/**\n * 判断 Query Value 是否为重复参数数组。\n *\n * @param value - 单值或数组形式的 Query Value。\n * @returns 是只读原始值数组时返回 `true`。\n */\nconst isQueryPrimitiveArray = (value: QueryValue): value is readonly QueryPrimitive[] => Array.isArray(value);\n\n/** {@link toQueryString} 的序列化选项。 */\nexport interface QueryStringOptions {\n\t/** 返回非空结果时是否添加 `?`；默认 `false`。 */\n\tprefixQuestionMark?: boolean;\n\t/** 是否按键的 UTF-16 码元顺序稳定排序；默认保留对象枚举顺序。 */\n\tsort?: boolean;\n\t/** 空格编码方式；默认遵循表单编码并输出 `+`。 */\n\tspace?: \"percent\" | \"plus\";\n}\n\n/**\n * 安全写入结果对象的自有可枚举属性。\n *\n * @remarks 使用 `defineProperty` 避免 `__proto__` 触发 Setter，并显式拒绝三个原型污染键。\n * @param target - 要写入的结果对象。\n * @param key - 自有属性键。\n * @param value - 属性值。\n * @throws `TypeError` 当键为 `__proto__`、`prototype` 或 `constructor`。\n */\nconst defineEnumerableProperty = (target: object, key: PropertyKey, value: unknown): void => {\n\tObject.defineProperty(target, key, { configurable: true, enumerable: true, value, writable: true });\n};\n\n/**\n * 判断值是否是普通对象。\n *\n * @param value - 任意待检查值。\n * @returns 原型为 `Object.prototype` 或 `null` 时返回 `true`。\n */\nexport function isPlainObject(value: unknown): value is Record<PropertyKey, unknown> {\n\tif (typeof value !== \"object\" || value === null) return false;\n\tconst prototype = Object.getPrototypeOf(value) as object | null;\n\treturn prototype === null || prototype === Object.prototype;\n}\n\n/**\n * 安全判断对象是否拥有自己的属性。\n *\n * @remarks 不调用可能被对象覆盖的 `hasOwnProperty`。\n * @param value - 待检查对象。\n * @param key - 字符串、数字或 Symbol 属性键。\n * @returns 属性为对象自有属性时返回 `true`，并收窄键类型。\n */\nexport function hasOwn<ObjectType extends object, Key extends PropertyKey>(value: ObjectType, key: Key): key is Key & keyof ObjectType {\n\treturn Object.hasOwn(value, key);\n}\n\n/**\n * 从对象中选择指定自有可枚举属性。\n *\n * @param source - 不会被修改的源对象。\n * @param keys - 需要保留的键；不存在的键被忽略。\n * @returns 新对象，保持 `keys` 的遍历顺序。\n */\nexport function pick<Source extends object, Keys extends readonly (keyof Source)[]>(source: Source, keys: Keys): Pick<Source, Keys[number]> {\n\tconst result = {} as Pick<Source, Keys[number]>;\n\tfor (const key of keys) {\n\t\tif (Object.prototype.propertyIsEnumerable.call(source, key)) defineEnumerableProperty(result, key, source[key]);\n\t}\n\treturn result;\n}\n\n/**\n * 浅复制对象并删除指定属性。\n *\n * @param source - 不会被修改的源对象。\n * @param keys - 需要排除的键。\n * @returns 包含其余自有可枚举字符串与 Symbol 属性的新对象。\n */\nexport function omit<Source extends object, Keys extends readonly (keyof Source)[]>(source: Source, keys: Keys): Omit<Source, Keys[number]> {\n\tconst result = { ...source };\n\tfor (const key of keys) Reflect.deleteProperty(result, key);\n\treturn result;\n}\n\n/**\n * 映射对象的自有可枚举属性值。\n *\n * @param source - 不会被修改的源对象。\n * @param mapper - 接收值、键和源对象的映射函数。\n * @returns 保留原键的新对象。\n */\nexport function mapValues<Source extends object, Result>(\n\tsource: Source,\n\tmapper: (value: Source[keyof Source], key: keyof Source, source: Source) => Result\n): { [Key in keyof Source]: Result } {\n\tconst result = {} as { [Key in keyof Source]: Result };\n\tfor (const key of Reflect.ownKeys(source) as (keyof Source)[]) {\n\t\tif (Object.prototype.propertyIsEnumerable.call(source, key)) defineEnumerableProperty(result, key, mapper(source[key], key, source));\n\t}\n\treturn result;\n}\n\n/**\n * 对自有可枚举属性执行 SameValue 浅比较。\n *\n * @remarks 嵌套对象只比较引用；`NaN` 相等，`0` 与 `-0` 不相等。\n * @param left - 第一对象。\n * @param right - 第二对象。\n * @returns 自有可枚举键集合与对应值均满足 SameValue 时返回 `true`。\n */\nexport function shallowEqual(left: object, right: object): boolean {\n\tif (Object.is(left, right)) return true;\n\tconst leftKeys = Reflect.ownKeys(left).filter((key) => Object.prototype.propertyIsEnumerable.call(left, key));\n\tconst rightKeys = Reflect.ownKeys(right).filter((key) => Object.prototype.propertyIsEnumerable.call(right, key));\n\tif (leftKeys.length !== rightKeys.length) return false;\n\treturn leftKeys.every((key) => Object.hasOwn(right, key) && Object.is(Reflect.get(left, key), Reflect.get(right, key)));\n}\n\n/**\n * 把 Query 原始值规范化为文本。\n *\n * @param value - 已排除空值的字符串、数字、布尔值或 BigInt。\n * @returns 与 URLSearchParams 兼容的文本值。\n * @throws `RangeError` 当数字不是有限值。\n */\nconst serializeQueryValue = (value: Exclude<QueryPrimitive, null | undefined>): string => {\n\tif (typeof value === \"number\" && !Number.isFinite(value)) {\n\t\tthrow new RangeError(\"Query parameter numbers must be finite.\");\n\t}\n\treturn String(value);\n};\n\n/**\n * 将对象序列化为标准 URL 查询字符串。\n *\n * @remarks `null` 与 `undefined` 被跳过；数组使用重复键；返回值不会修改输入。\n * @param value - 查询参数对象。\n * @param options - 排序、空格和问号前缀选项。\n * @returns URL 编码后的查询字符串；没有参数时始终返回空字符串。\n * @throws `RangeError` 当参数包含 `NaN` 或无穷数字。\n */\nexport function toQueryString(value: Readonly<Record<string, QueryValue>>, options: QueryStringOptions = {}): string {\n\tconst entries = Object.entries(value);\n\tif (options.sort) entries.sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));\n\tconst parameters = new URLSearchParams();\n\tfor (const [key, rawValue] of entries) {\n\t\tconst values = isQueryPrimitiveArray(rawValue) ? rawValue : [rawValue];\n\t\tfor (const item of values) {\n\t\t\tif (item !== null && item !== undefined) parameters.append(key, serializeQueryValue(item));\n\t\t}\n\t}\n\tlet result = parameters.toString();\n\tif (options.space === \"percent\") result = result.replace(/\\+/gu, \"%20\");\n\treturn result && options.prefixQuestionMark ? `?${result}` : result;\n}\n"],"mappings":";;;;;;;AAYA,MAAM,yBAAyB,UAA0D,MAAM,QAAQ,KAAK;;;;;;;;;;AAqB5G,MAAM,4BAA4B,QAAgB,KAAkB,UAAyB;CAC5F,OAAO,eAAe,QAAQ,KAAK;EAAE,cAAc;EAAM,YAAY;EAAM;EAAO,UAAU;CAAK,CAAC;AACnG;;;;;;;AAQA,SAAgB,cAAc,OAAuD;CACpF,IAAI,OAAO,UAAU,YAAY,UAAU,MAAM,OAAO;CACxD,MAAM,YAAY,OAAO,eAAe,KAAK;CAC7C,OAAO,cAAc,QAAQ,cAAc,OAAO;AACnD;;;;;;;;;AAUA,SAAgB,OAA2D,OAAmB,KAAyC;CACtI,OAAO,OAAO,OAAO,OAAO,GAAG;AAChC;;;;;;;;AASA,SAAgB,KAAoE,QAAgB,MAAwC;CAC3I,MAAM,SAAS,CAAC;CAChB,KAAK,MAAM,OAAO,MACjB,IAAI,OAAO,UAAU,qBAAqB,KAAK,QAAQ,GAAG,GAAG,yBAAyB,QAAQ,KAAK,OAAO,IAAI;CAE/G,OAAO;AACR;;;;;;;;AASA,SAAgB,KAAoE,QAAgB,MAAwC;CAC3I,MAAM,SAAS,EAAE,GAAG,OAAO;CAC3B,KAAK,MAAM,OAAO,MAAM,QAAQ,eAAe,QAAQ,GAAG;CAC1D,OAAO;AACR;;;;;;;;AASA,SAAgB,UACf,QACA,QACoC;CACpC,MAAM,SAAS,CAAC;CAChB,KAAK,MAAM,OAAO,QAAQ,QAAQ,MAAM,GACvC,IAAI,OAAO,UAAU,qBAAqB,KAAK,QAAQ,GAAG,GAAG,yBAAyB,QAAQ,KAAK,OAAO,OAAO,MAAM,KAAK,MAAM,CAAC;CAEpI,OAAO;AACR;;;;;;;;;AAUA,SAAgB,aAAa,MAAc,OAAwB;CAClE,IAAI,OAAO,GAAG,MAAM,KAAK,GAAG,OAAO;CACnC,MAAM,WAAW,QAAQ,QAAQ,IAAI,CAAC,CAAC,QAAQ,QAAQ,OAAO,UAAU,qBAAqB,KAAK,MAAM,GAAG,CAAC;CAC5G,MAAM,YAAY,QAAQ,QAAQ,KAAK,CAAC,CAAC,QAAQ,QAAQ,OAAO,UAAU,qBAAqB,KAAK,OAAO,GAAG,CAAC;CAC/G,IAAI,SAAS,WAAW,UAAU,QAAQ,OAAO;CACjD,OAAO,SAAS,OAAO,QAAQ,OAAO,OAAO,OAAO,GAAG,KAAK,OAAO,GAAG,QAAQ,IAAI,MAAM,GAAG,GAAG,QAAQ,IAAI,OAAO,GAAG,CAAC,CAAC;AACvH;;;;;;;;AASA,MAAM,uBAAuB,UAA6D;CACzF,IAAI,OAAO,UAAU,YAAY,CAAC,OAAO,SAAS,KAAK,GACtD,MAAM,IAAI,WAAW,yCAAyC;CAE/D,OAAO,OAAO,KAAK;AACpB;;;;;;;;;;AAWA,SAAgB,cAAc,OAA6C,UAA8B,CAAC,GAAW;CACpH,MAAM,UAAU,OAAO,QAAQ,KAAK;CACpC,IAAI,QAAQ,MAAM,QAAQ,MAAM,CAAC,OAAO,CAAC,WAAY,OAAO,QAAQ,KAAK,OAAO,QAAQ,IAAI,CAAE;CAC9F,MAAM,aAAa,IAAI,gBAAgB;CACvC,KAAK,MAAM,CAAC,KAAK,aAAa,SAAS;EACtC,MAAM,SAAS,sBAAsB,QAAQ,IAAI,WAAW,CAAC,QAAQ;EACrE,KAAK,MAAM,QAAQ,QAClB,IAAI,SAAS,QAAQ,SAAS,KAAA,GAAW,WAAW,OAAO,KAAK,oBAAoB,IAAI,CAAC;CAE3F;CACA,IAAI,SAAS,WAAW,SAAS;CACjC,IAAI,QAAQ,UAAU,WAAW,SAAS,OAAO,QAAQ,QAAQ,KAAK;CACtE,OAAO,UAAU,QAAQ,qBAAqB,IAAI,WAAW;AAC9D"}

package/dist/storage/index.d.mts

@@ -0,0 +1,107 @@
+//#region src/storage/index.d.ts
+/** Storage 业务值编码器。 */
+interface StorageCodec {
+  /**
+   * 把已编码文本恢复为业务值。
+   * @param value - 由同一 Codec 的 `encode` 生成并持久化的文本。
+   * @returns 解码后的业务值。
+   * @throws 当文本损坏、格式不受支持或无法反序列化时应抛出错误。
+   */
+  decode: (value: string) => unknown;
+  /**
+   * 把业务值编码为可持久化字符串。
+   * @param value - 调用方传入的业务值。
+   * @returns 可由同一 Codec 的 `decode` 无损恢复的文本。
+   * @throws 当值不受支持或无法序列化时应抛出错误。
+   */
+  encode: (value: unknown) => string;
+}
+/** 程序入口调用 {@link configureStorage} 时使用的全局配置。 */
+interface StorageConfiguration {
+  /** 自定义值编码器；默认使用严格 JSON Codec，同一应用生命周期内必须保持同一引用。 */
+  codec?: StorageCodec;
+  /** 启用 Base64 可逆混淆；不提供加密、完整性或认证，不能与 `codec` 同时使用。 */
+  crypto?: boolean;
+  /** 返回 Unix 毫秒时间戳的时钟；默认使用 `Date.now`，主要用于 TTL 测试与受控时间源。 */
+  now?: () => number;
+  /** 所有物理键使用的非空命名空间前缀； */
+  prefix?: string;
+}
+/** 单次 Storage 写入配置。 */
+interface StorageWriteOptions {
+  /** 从写入时刻开始的有效毫秒数；必须是大于 0 的有限数，省略时永久有效。 */
+  ttlMs?: number;
+}
+/** `Local` 与 `Session` 的统一操作接口。 */
+interface StorageArea {
+  /** 当前全局 Storage 配置的物理键前缀；首次读取会激活默认配置。 */
+  readonly prefix: string;
+  /**
+   * 删除当前命名空间内的全部键，不影响同一后端中的其他应用键。
+   * @throws `Error` 当当前平台后端不可用。
+   */
+  clear: () => void;
+  /**
+   * 获取并解码业务值；已过期记录会在读取时删除。
+   * @param key - 不含全局前缀的非空业务键。
+   * @returns 解码后的值；键缺失或过期时返回 `undefined`。
+   * @throws 当键非法、包络损坏、Codec 解码失败或后端不可用时抛出错误。
+   */
+  get: <Value = unknown>(key: string) => Value | undefined;
+  /**
+   * 判断一个可成功读取且未过期的业务键是否存在。
+   * @param key - 不含全局前缀的非空业务键。
+   * @returns 键存在且包络有效时返回 `true`。
+   */
+  has: (key: string) => boolean;
+  /**
+   * 返回当前命名空间内的业务键快照。
+   * @returns 已移除全局前缀并按字典序排列的新数组；不会自动清理过期项。
+   */
+  keys: () => string[];
+  /**
+   * 扫描当前命名空间并删除全部过期记录。
+   * @returns 本次实际删除的记录数量。
+   * @throws 当发现损坏包络或后端不可用时抛出错误。
+   */
+  pruneExpired: () => number;
+  /**
+   * 删除单个业务键；键不存在时保持幂等。
+   * @param key - 不含全局前缀的非空业务键。
+   */
+  remove: (key: string) => void;
+  /**
+   * 删除业务键以指定文本开头的全部条目，范围仍受全局命名空间限制。
+   * @param keyPrefix - 不含全局前缀的非空业务键前缀。
+   */
+  removeByPrefix: (keyPrefix: string) => void;
+  /**
+   * 编码并写入业务值，可附加惰性清理的 TTL。
+   * @param key - 不含全局前缀的非空业务键。
+   * @param value - 必须受当前 Codec 支持的业务值。
+   * @param options - 可选的单次写入 TTL。
+   * @throws 当键、TTL、业务值或后端写入无效时抛出错误。
+   */
+  set: <Value>(key: string, value: Value, options?: StorageWriteOptions) => void;
+}
+/** Base64 混淆 Codec；只隐藏明文外观，不提供加密、完整性或认证。 */
+declare const base64StorageCodec: StorageCodec;
+/** 浏览器 localStorage 或自动检测的 uni-app Storage 全局业务入口。 */
+declare const Local: StorageArea;
+/** 浏览器 sessionStorage 的全局业务入口；uni-app 不提供会话存储。 */
+declare const Session: StorageArea;
+/**
+ * 在首次 Storage 操作前可选配置 `Local` 与 `Session`。
+ *
+ * @remarks 不调用时在首次操作上使用 `fast__`、JSON Codec 与 `Date.now`。首次激活后只允许以完全相同的值和引用重复调用。若检测到
+ * 全局 `uni`，则自动使用其同步 Storage 且只启用 `Local`，否则使用浏览器 `localStorage` 与 `sessionStorage`。
+ * `crypto: true` 仅恢复旧版 Base64 混淆行为，不能保护敏感数据。
+ * @param options - 可选的全局键前缀、Codec、旧版混淆选项与时钟。
+ * @throws 配置非法、重复配置冲突或目标平台 Storage 不可用时抛出错误。
+ */
+declare function configureStorage(options?: StorageConfiguration): void;
+/** 返回全局 Storage 是否已经由应用入口配置。 */
+declare function isStorageConfigured(): boolean;
+//#endregion
+export { Local, Session, StorageArea, StorageCodec, StorageConfiguration, StorageWriteOptions, base64StorageCodec, configureStorage, isStorageConfigured };
+//# sourceMappingURL=index.d.mts.map

package/dist/storage/index.mjs

@@ -0,0 +1,327 @@
+import { decodeSecureBase64, encodeSecureBase64 } from "../base64/index.mjs";
+//#region src/storage/index.ts
+const runtimeStorageGlobals = globalThis;
+/**
+* 读取并校验当前运行时的全局 uni-app 同步 Storage。
+*
+* @returns 检测到 uni-app 时返回同步 Storage；普通浏览器环境返回 `undefined`。
+* @throws `TypeError` 当全局 `uni` 存在但缺少本库需要的同步 Storage 方法。
+*/
+const getGlobalUniStorage = () => {
+	const value = runtimeStorageGlobals.uni;
+	if (value === void 0) return void 0;
+	if (typeof value !== "object" && typeof value !== "function" || value === null) throw new TypeError("The global uni object does not provide synchronous Storage APIs.");
+	const storage = value;
+	if (typeof storage.getStorageSync !== "function" || typeof storage.getStorageInfoSync !== "function" || typeof storage.removeStorageSync !== "function" || typeof storage.setStorageSync !== "function") throw new TypeError("The global uni object does not provide synchronous Storage APIs.");
+	return storage;
+};
+/** 默认 JSON Codec；显式拒绝会被 JSON.stringify 静默丢弃的顶层值。 */
+const jsonCodec = {
+	decode: (value) => JSON.parse(value),
+	encode: (value) => {
+		const encoded = JSON.stringify(value);
+		if (typeof encoded !== "string") throw new TypeError("The storage value is not JSON-serializable.");
+		return encoded;
+	}
+};
+/** Base64 混淆 Codec；只隐藏明文外观，不提供加密、完整性或认证。 */
+const base64StorageCodec = {
+	decode: (value) => JSON.parse(decodeSecureBase64(value)),
+	encode: (value) => {
+		const encoded = JSON.stringify(value);
+		if (typeof encoded !== "string") throw new TypeError("The storage value is not JSON-serializable.");
+		return encodeSecureBase64(encoded);
+	}
+};
+/** 页面级唯一配置；只允许幂等重复配置，避免模块加载顺序改变行为。 */
+let activeConfiguration;
+/**
+* 判断未知值是否为非数组对象记录。
+*
+* @param value - JSON.parse 返回的未知值。
+* @returns 值为非空、非数组对象时返回 `true`。
+*/
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+* 校验 Storage 业务键。
+*
+* @param key - 不含全局 Prefix 的业务键或业务键前缀。
+* @throws `TypeError` 当值不是非空字符串。
+*/
+const assertKey = (key) => {
+	if (typeof key !== "string" || key.length === 0) throw new TypeError("Storage keys must be non-empty strings.");
+};
+/**
+* 创建浏览器 Storage 后端。
+*
+* @remarks 平台对象在调用阶段读取，因此导入模块不会访问浏览器全局对象。
+* @param kind - 选择 `localStorage` 或 `sessionStorage`。
+* @returns 统一的内部同步后端。
+* @throws `Error` 当所选 Storage 在当前环境不可用。
+*/
+const createWebStorageBackend = (kind) => {
+	const storage = kind === "local" ? runtimeStorageGlobals.localStorage : runtimeStorageGlobals.sessionStorage;
+	if (storage === void 0) throw new Error(`${kind}Storage is unavailable in the current runtime.`);
+	return {
+		getItem: (key) => storage.getItem(key),
+		keys: () => {
+			const keys = [];
+			for (let index = 0; index < storage.length; index += 1) {
+				const key = storage.key(index);
+				if (key !== null) keys.push(key);
+			}
+			return keys;
+		},
+		removeItem: (key) => {
+			storage.removeItem(key);
+		},
+		setItem: (key, value) => {
+			storage.setItem(key, value);
+		}
+	};
+};
+/**
+* 把 uni-app 同步 Storage 适配为内部后端。
+*
+* @remarks uni-app 以空字符串同时表示“键缺失”和“真实空值”，因此空字符串需要结合键清单消除歧义。
+* @param storage - 已从全局 `uni` 读取并校验的同步 API。
+* @returns 统一的内部同步后端。
+*/
+const createUniStorageBackend = (storage) => ({
+	getItem: (key) => {
+		const value = storage.getStorageSync(key);
+		if (value !== "") return value;
+		return storage.getStorageInfoSync().keys.includes(key) ? value : void 0;
+	},
+	keys: () => [...storage.getStorageInfoSync().keys],
+	removeItem: (key) => {
+		storage.removeStorageSync(key);
+	},
+	setItem: (key, value) => {
+		storage.setStorageSync(key, value);
+	}
+});
+/**
+* 解析并校验版本化 Storage 包络。
+*
+* @param rawValue - 后端返回的原始值。
+* @param key - 用于错误定位的完整物理键。
+* @returns 当前 v3 包络。
+* @throws `TypeError` 当原始值不是字符串、JSON 损坏、版本不支持或字段类型非法。
+*/
+const parseStoredEnvelope = (rawValue, key) => {
+	if (typeof rawValue !== "string") throw new TypeError(`Storage entry "${key}" is not a string.`);
+	try {
+		const parsed = JSON.parse(rawValue);
+		if (!isRecord(parsed) || parsed["version"] !== 3 || typeof parsed["data"] !== "string" || !(parsed["expiresAt"] === null || typeof parsed["expiresAt"] === "number" && Number.isFinite(parsed["expiresAt"]))) throw new TypeError("Unsupported storage envelope.");
+		return {
+			data: parsed["data"],
+			expiresAt: parsed["expiresAt"],
+			version: 3
+		};
+	} catch (cause) {
+		throw new TypeError(`Storage entry "${key}" is corrupted or unsupported.`, { cause });
+	}
+};
+/**
+* 创建绑定命名空间、Codec 与时钟的 Storage Area。
+*
+* @param backendFactory - 每次操作时解析平台后端的工厂，保证导入安全并反映平台可用性。
+* @param prefix - 已校验的全局物理键前缀。
+* @param codec - 业务值与包络文本之间的 Codec。
+* @param now - TTL 计算使用的可注入时钟。
+* @returns 完整的命名空间 Storage 操作集合。
+*/
+const createStorageArea = (backendFactory, prefix, codec, now) => {
+	/**
+	* 拼接物理键。
+	*
+	* @param key - 已校验业务键。
+	* @returns 带当前命名空间前缀的物理键。
+	*/
+	const toStorageKey = (key) => `${prefix}${key}`;
+	/**
+	* 枚举当前命名空间中的业务键。
+	*
+	* @param backend - 本次操作使用的后端。
+	* @returns 已移除物理前缀、去重并排序的业务键。
+	* @throws `TypeError` 当后端返回非字符串键。
+	*/
+	const listBusinessKeys = (backend) => {
+		const keys = backend.keys();
+		if (!Array.isArray(keys) || !keys.every((key) => typeof key === "string")) throw new TypeError("Storage backend keys must be strings.");
+		return [...new Set(keys.filter((key) => key.startsWith(prefix)).map((key) => key.slice(prefix.length)))].sort();
+	};
+	/**
+	* 读取并处理单个包络。
+	*
+	* @param backend - 本次操作使用的后端。
+	* @param key - 业务键。
+	* @returns 未过期包络；键缺失或已经过期时返回 `undefined`。
+	* @throws `TypeError` 当键或包络非法。
+	* @throws `RangeError` 当注入时钟返回非有限时间戳。
+	*/
+	const readStoredEnvelope = (backend, key) => {
+		assertKey(key);
+		const storageKey = toStorageKey(key);
+		const rawValue = backend.getItem(storageKey);
+		if (rawValue === null || rawValue === void 0) return void 0;
+		const envelope = parseStoredEnvelope(rawValue, storageKey);
+		if (envelope.expiresAt === null) return envelope;
+		const timestamp = now();
+		if (!Number.isFinite(timestamp)) throw new RangeError("Storage clock must return a finite timestamp.");
+		if (timestamp < envelope.expiresAt) return envelope;
+		backend.removeItem(storageKey);
+	};
+	return {
+		prefix,
+		clear() {
+			const backend = backendFactory();
+			for (const key of listBusinessKeys(backend)) backend.removeItem(toStorageKey(key));
+		},
+		get(key) {
+			const envelope = readStoredEnvelope(backendFactory(), key);
+			if (envelope === void 0) return void 0;
+			try {
+				return codec.decode(envelope.data);
+			} catch (cause) {
+				throw new TypeError(`Storage entry "${toStorageKey(key)}" could not be decoded.`, { cause });
+			}
+		},
+		has: (key) => readStoredEnvelope(backendFactory(), key) !== void 0,
+		keys: () => listBusinessKeys(backendFactory()),
+		pruneExpired() {
+			const backend = backendFactory();
+			let removed = 0;
+			for (const key of listBusinessKeys(backend)) {
+				const before = backend.getItem(toStorageKey(key));
+				if (before !== null && before !== void 0 && readStoredEnvelope(backend, key) === void 0) removed += 1;
+			}
+			return removed;
+		},
+		remove(key) {
+			assertKey(key);
+			backendFactory().removeItem(toStorageKey(key));
+		},
+		removeByPrefix(keyPrefix) {
+			assertKey(keyPrefix);
+			const backend = backendFactory();
+			for (const key of listBusinessKeys(backend)) if (key.startsWith(keyPrefix)) backend.removeItem(toStorageKey(key));
+		},
+		set(key, value, options = {}) {
+			assertKey(key);
+			if (value === void 0) throw new TypeError("Top-level undefined cannot be stored; remove the key instead.");
+			let expiresAt = null;
+			if (options.ttlMs !== void 0) {
+				if (!Number.isFinite(options.ttlMs) || options.ttlMs <= 0) throw new RangeError("ttlMs must be a positive finite number.");
+				const timestamp = now();
+				if (!Number.isFinite(timestamp) || !Number.isFinite(timestamp + options.ttlMs)) throw new RangeError("Storage expiry exceeds the supported timestamp range.");
+				expiresAt = timestamp + options.ttlMs;
+			}
+			let data;
+			try {
+				data = codec.encode(value);
+				if (typeof data !== "string") throw new TypeError("Storage codecs must return strings.");
+			} catch (cause) {
+				throw new TypeError("The storage value could not be encoded.", { cause });
+			}
+			backendFactory().setItem(toStorageKey(key), JSON.stringify({
+				data,
+				expiresAt,
+				version: 3
+			}));
+		}
+	};
+};
+/**
+* 获取已激活的全局 Storage 配置。
+*
+* @returns 显式配置或首次 Storage 操作创建的默认配置。
+*/
+const requireStorageConfiguration = () => {
+	if (activeConfiguration === void 0) configureStorage();
+	if (activeConfiguration === void 0) throw new Error("Storage configuration could not be initialized.");
+	return activeConfiguration;
+};
+/**
+* 创建稳定的公开 Storage 门面。
+*
+* @param select - 从激活配置选择 Local 或 Session 的函数。
+* @param name - 用于不可用错误的公开门面名称。
+* @returns 可安全导入、并在首次调用时解析默认或显式配置的稳定对象。
+*/
+const createStorageAreaProxy = (select, name) => {
+	/**
+	* 解析当前实际 Area。
+	*
+	* @returns 配置中的 Local 或 Session Area。
+	* @throws `Error` 当 uni-app 模式请求 Session。
+	*/
+	const getArea = () => {
+		const area = select(requireStorageConfiguration());
+		if (area === void 0) throw new Error(`${name} is unavailable in uni-app.`);
+		return area;
+	};
+	return {
+		get prefix() {
+			return getArea().prefix;
+		},
+		clear: () => {
+			getArea().clear();
+		},
+		get: (key) => getArea().get(key),
+		has: (key) => getArea().has(key),
+		keys: () => getArea().keys(),
+		pruneExpired: () => getArea().pruneExpired(),
+		remove: (key) => {
+			getArea().remove(key);
+		},
+		removeByPrefix: (keyPrefix) => {
+			getArea().removeByPrefix(keyPrefix);
+		},
+		set: (key, value, options) => {
+			getArea().set(key, value, options);
+		}
+	};
+};
+/** 浏览器 localStorage 或自动检测的 uni-app Storage 全局业务入口。 */
+const Local = createStorageAreaProxy((configuration) => configuration.local, "Local");
+/** 浏览器 sessionStorage 的全局业务入口；uni-app 不提供会话存储。 */
+const Session = createStorageAreaProxy((configuration) => configuration.session, "Session");
+/**
+* 在首次 Storage 操作前可选配置 `Local` 与 `Session`。
+*
+* @remarks 不调用时在首次操作上使用 `fast__`、JSON Codec 与 `Date.now`。首次激活后只允许以完全相同的值和引用重复调用。若检测到
+* 全局 `uni`，则自动使用其同步 Storage 且只启用 `Local`，否则使用浏览器 `localStorage` 与 `sessionStorage`。
+* `crypto: true` 仅恢复旧版 Base64 混淆行为，不能保护敏感数据。
+* @param options - 可选的全局键前缀、Codec、旧版混淆选项与时钟。
+* @throws 配置非法、重复配置冲突或目标平台 Storage 不可用时抛出错误。
+*/
+function configureStorage(options = {}) {
+	const prefix = options.prefix ?? "fast__";
+	if (typeof prefix !== "string" || prefix.length === 0) throw new TypeError("Storage prefix must be a non-empty string.");
+	if (options.codec !== void 0 && options.crypto === true) throw new TypeError("Storage codec and crypto options cannot be used together.");
+	const codec = options.codec ?? (options.crypto === true ? base64StorageCodec : jsonCodec);
+	const now = options.now ?? Date.now;
+	if (activeConfiguration !== void 0) {
+		if (activeConfiguration.prefix === prefix && activeConfiguration.codec === codec && activeConfiguration.now === now) return;
+		throw new Error("Storage has already been configured with different options.");
+	}
+	const uni = getGlobalUniStorage();
+	const configuration = {
+		codec,
+		local: createStorageArea(uni === void 0 ? () => createWebStorageBackend("local") : () => createUniStorageBackend(uni), prefix, codec, now),
+		now,
+		prefix
+	};
+	if (uni === void 0) configuration.session = createStorageArea(() => createWebStorageBackend("session"), prefix, codec, now);
+	activeConfiguration = configuration;
+}
+/** 返回全局 Storage 是否已经由应用入口配置。 */
+function isStorageConfigured() {
+	return activeConfiguration !== void 0;
+}
+//#endregion
+export { Local, Session, base64StorageCodec, configureStorage, isStorageConfigured };
+
+//# sourceMappingURL=index.mjs.map