辛米尔网页编程工具集·改进型网页存储工具两枚

npm 包

npm 包之名称

@xinmier/enhanced-web-storages 。

npm 包之主页

https://www.npmjs.com/package/@xinmier/enhanced-web-storages。

概述

该软件是一个 npm 包，下称【本软件】。

本软件拟包含一系列程序集，面向网页开发人员，而非最终用户。

本软件包含的两个工具，分别是【改进型网页会话阶段存储器】和【改进型网页本机存储器】。它们分别是 sessionStorage 和 localStorage 的改进型。

符合 W3C 标准的（或者说浏览器原生的） Storage 对象，仅能存放 string 类型的值。若给出其他类型的值，甚至是 function 定义，该值会先自动转换出 string 类型的副本，而后 Storage 对象仅存放该副本。因此，标准的 Storage 对象不够实用。

本软件提供的所谓改进型存储器，则允许存放任意类型的值。凡【值】，凭【键】存取，故而形成【键值对】。

又，本软件提供的所谓改进型存储器，允许为每一个存放的值设定“过期秒数”。

用法（面向网页开发人员）

安装

在命令行环境中，cd 进入你的网页开发项目的文件夹，并执行以下命令：

npm  i  @xinmier/enhanced-web-storages

在代码中使用本工具集

本工具集面向网页开发人员。程序员在编写其代码时，可以采用本工具集。故下方所谓用法均系介绍在编程活动中如何采用本工具集。因此，所谓“用法”亦称“写法”。

简单示例

import {
    enhancedSessionStorage,
    enhancedLocalStorage,
} from '@xinmier/enhanced-web-storages'

enhancedSessionStorage.setItem<string>('姓名', '吴乐川')
enhancedSessionStorage.setItem<number>(
    '年龄',
    45,
    {
        /**
         * 9 秒后该值视为过期。
         * 任何值一旦过期，则无法凭借本工具
         * 提供的 `getItem` 或 `getItemSync` 取得，
         * 故而等同于灰飞烟灭。
         * 
         * 又，毕竟浏览器的 Storage 是公开的。
         * 因此，假如故意绕过本工具集，
         * 直接访问 Storage ，
         * 则仍可能取得所谓过期的值。
         */
        secondsOfExpiration: 9,
    }
)



const {
    value: age,
    succeeded,
} = enhancedSessionStorage.getItemSync('年龄')

/**
 * 应打印：
 * “当下： 45 true”。
 */
console.log('当下：', age, succeeded)

/**
 * 应打印
 * “45”。
 */
enhancedSessionStorage.getItem('年龄').then(console.log)

setTimeout(() => {
    const {
        value: age,
        succeeded,
    } = enhancedSessionStorage.getItemSync('年龄')

    /**
     * 应打印
     * “9 秒后： undefined false”。
     * 因为， 9 秒后，‘年龄’数据已经过期。
     */
    console.log('9 秒后：', age, succeeded)
}, 9 * 1000)



enhancedLocalStorage.setItem('祖国', '中华人民共和国')

enhancedLocalStorage.setItem('不良习惯', '熬夜')
enhancedLocalStorage.removeItem('不良习惯')

编程接口

根导出项

根导出项有两个： enhancedSessionStorage 和 enhancedLocalStorage 。它们的接口完全相同，区别仅在于它们“内部”调用的 Storage 对象不同。顾名思义， enhancedSessionStorage 内部调用的是 Window.sessionStorage ；enhancedLocalStorage 内部调用的是 Window.localStorage 。

TypeScript 接口总览

export interface T_EnhancedWebStorage_SetItemOptions {
    secondsOfExpiration?: null | number;
}



export interface T_EnhancedWebStorage_GetItemOptions {
    shouldTreatNonWrappedValueAsInvalid?: boolean;
}



export type T_EnhancedWebStorage_WrappedValue<T_RawValue = any> = {
    rawValue: T_RawValue;
    creationTimestamp: number;
    creationTimestampHumanReadable: string;
    secondsOfExpiration: null | number;
};



/**
 * 在浏览器中验证过：
 * 以下类型均可在 window.sessionStorage 上成功 setItem 、getItem 。
 * 但 symbol 不行。
 * 顺便指出， setItem() 和 setItem(undefined) 是不同的。前者报错，后者不报错。
 */
export type T_StandardWebStorage_Key = (string | number | null | boolean | undefined | ((...args: unknown[]) => unknown));



/** 经验证，标准的 setItem() 可以接受任何类型的值。 */
export type T_StandardWebStorage_SetItemMethodAcceptableValue = any;



/**
 * 经验证，标准的 getItem() 在 key 确实存在的前提下，返回的永远是文本。
 * 例如：
 *     -   setItem() 存入 null ， getItem() 会得到 'null' 。
 *     -   setItem() 存入函数， getItem() 会得到该函数的源代码全文。
 *
 * 顺便指出：本工具的 getItem() 的返回值可以是任意值。
 */
export type T_StandardWebStorage_GetItemMethodReturnValue = string;



/**
 * 经验证，标准的 key() 在 index 确实存在的前提下，返回的永远是文本。
 * 例如：
 *     -   setItem() 采用 null 作为 key， key() 会得到 'null' 。
 *     -   setItem() 采用函数作为 key， key() 会得到该函数的源代码全文。
 */
export type T_StandardWebStorage_KeyMethodReturnValue = string;



export interface T_EnhancedWebStorage {
    /**
     * 默认值： window.sessionStorage 。
     */
    core: Storage;



    /**
     * 默认值： 'sessionStorage' 。
     */
    coreType: 'localStorage' | 'sessionStorage';



    clear(): void;



    setItem<
        T_RawValue = T_StandardWebStorage_SetItemMethodAcceptableValue
    >(
        key?: T_StandardWebStorage_Key,
        rawValue?: T_RawValue,
        options?: T_EnhancedWebStorage_SetItemOptions
    ): boolean;



    getItemSync<
        T_RawValue = any
    >(
        key?: T_StandardWebStorage_Key,
        options?: T_EnhancedWebStorage_GetItemOptions
    ): {
        succeeded: false;
        value: undefined;
    } | {
        succeeded: true;
        value: T_RawValue;
    };



    getItem<
        T_RawValue = any
    >(
        key?: T_StandardWebStorage_Key,
        options?: T_EnhancedWebStorage_GetItemOptions
    ): Promise<T_RawValue>;



    removeItem(key?: T_StandardWebStorage_Key): void;



    key(index?: number): T_StandardWebStorage_KeyMethodReturnValue | null;
}



export declare const enhancedSessionStorage: T_EnhancedWebStorage;
export declare const enhancedLocalStorage:   T_EnhancedWebStorage;

TypeScript 诸接口详解

1. 属性 core

   core: Storage;

   此乃改进型存储器的所谓“内核”。内核是符合 W3C 标准的 Storage 对象。 参阅上文《根导出项》一节。

   默认值为 window.sessionStorage 。

2. 属性 coreType

   coreType: 'localStorage' | 'sessionStorage';

   此乃改进型存储所谓“内核”的种类记号。

   默认值为 'sessionStorage' 。

3. 方法函数 clear

   用以清除一切已存的数据。

   细则：

   无。

   示例：

   localLocalStorage.clear()

4. 方法函数 setItem

   本方法函数用以保存一枚数据。该数据不但可以是简单类型，例如 number 、 string 、boolean 等，亦可以是复杂类型，例如 object 和 Array 。

   细则：

   • 参数表（依次）：

     1. key?: T_StandardWebStorage_Key 。

        【键值对】的【键】。 key 可以是各色取值，甚至可以是函数，却唯独不可以是 symbol 类型。故而，一旦发现 key 是一个 symbol ，本方法函数本次保存数据将失败，返回 false 。

     2. rawValue?: any 。

        【键值对】的【键】。

     3. options?: T_EnhancedWebStorage_SetItemOptions 。

        此为本次存值的配置项集。

        interface T_EnhancedWebStorage_SetItemOptions {
            secondsOfExpiration?: null | number;
        }

   • 返回值 boolean 。

     若保存过程无误，则返回 true ，反之。

   示例：

   enhancedLocalStorage.setItem<{ 天干: string; 地支: number; }>('某某数据', { 天干: '甲', 地支: 1 })

5. 方法函数 getItemSync

   本方法函数用以查取一枚数据。该数据不但可以是简单类型，例如 number 、 string 、boolean 等，亦可以是复杂类型，例如 object 和 Array 。若该数据不存在，则得到 undefined。若该数据原本存在但已过期，则得到 undefined ，且本次查取向外界返回结果前，该过期数据会被暗中清除，彻底不复存在。总之，数据一旦过期，外界无法取得之。

   本方法函数的返回值并不单纯是欲取得的值本身，而是一个对象，该对象借助 succeeded 字段给出本次取值成功与否的信号。若信号为 true ，则本次取值成功。此时，返回值中的 value 字段给出所取得的值。若信号为 false ，则本次取值识别。此时，返回值中的 value 字段是 undefined 。

   细则：

   • 参数表（依次）：

     1. key?: T_StandardWebStorage_Key 。

        【键值对】的【键】。

     2. options?: T_EnhancedWebStorage_GetItemOptions 。

        此为本次取值的配置项集。

        interface T_EnhancedWebStorage_GetItemOptions {
            shouldTreatNonWrappedValueAsInvalid?: boolean;
        }

   • 返回值：

     type ReturnType1 = {
         succeeded: false;
         value: undefined;
     } | {
         succeeded: true;
         value: T_RawValue; // any
     };

   示例：

   const result = enhancedLocalStorage.getItemSynce<{ 天干: string; 地支: number; }>('某某数据')
   
   const {
       succeeded,
       value,
   } = result
   
   if (succeeded) {
       console.log(value.天干)
       console.log(value.地支)
   }

6. 方法函数 getItem

   本方法函数是上文 getItemSync 的 Promise 变种。本方法函数返回一个 Promise ，而不是借助 succeeded 字段来给出信号。若 Promise 本身【落实】（即 resolved），则代表取值取值成功；反之，若 Promise 本身【落空】（即 rejected），则代表本次取值失败。

   细则：

   • 参数表： 同上文《方法函数 getItemSynce》。

   • 返回值： Promise<any> 。

   示例：

   const value = await enhancedLocalStorage.getItem<{ 天干: string; 地支: number; }>('某某数据')
   console.log(value.天干)
   console.log(value.地支)

7. 方法函数 removeItem

   本方法函数用以删除一枚数据。

   细则：

   • 参数表（依次）：

     1. key?: T_StandardWebStorage_Key

   • 返回值： 无。

   示例：

   enhancedLocalStorage.removeItem('某某数据')

8. 方法函数 key

   本方法函数用以查取某【键值对】的【键】。查取时，以【键】之编号为凭据。这一设计系故意模仿 W3C 标准的 Storage 对象的 key 方法函数。

   细则：

   • 参数表（依次）：

     1. index?: number

   • 返回值： string 或 null 。

     若查得，则返回该【键】，故而类型为 string ；若查不得，则返回 null 。

   示例：

   const theKey = enhancedLocalStorage.key(1)

用法（面向本工具集的设计者和维护者）

暂无。