create-enum-es 1.0.3 → 3.0.0

package/README.md

@@ -1,82 +1,333 @@
+# create-enum-es
+
+> 零依赖、类型安全的前端枚举工具，为 TypeScript 项目提供完整的枚举管理方案。
+
+## 安装
+
+```bash
+npm install create-enum-es
 ```
-import { createEnum } from '../dist/emun-create.es.js';
 
-const enum1 = createEnum({
-  On: [1, '开启'],
-  Off: [0, '关闭'],
-})
+## 快速开始
 
-console.log(enum1.getVal('On')) // 1
-console.log(enum1.getValList('On', 'Off')) // [1, 0]
-console.log(enum1.getValList('On')) // [1]
-console.log(enum1.getValList()) // [1, 0]
+```ts
+import createEnum from "create-enum-es";
 
+const Status = createEnum({
+  ACTIVE:   [1, "激活", { color: "green" }],
+  INACTIVE: [0, "未激活", { color: "gray" }],
+  PENDING:  [2, "待审核", { color: "orange" }],
+} as const);
 
-console.log(enum1.getValMap('On', 'Off')) // {On: 1, Off: 0}
-console.log(enum1.getValMap('Off')) // {Off: 0}
-console.log(enum1.getValMap()) // {On: 1, Off: 0}
+Status.ACTIVE;          // 1（直接属性访问）
+Status.label("ACTIVE"); // '激活'
+Status.label(1);        // '激活'（通过 value 查 label）
+Status.extra("ACTIVE"); // { color: 'green' }
+```
 
+> **重要：** 定义时需要在对象末尾加上 `as const` 以获得完整的类型推导。
 
-console.log(enum1.getName('On')) // 开启
-console.log(enum1.getNameByValue(enum1.Off)) // 关闭
-console.log(enum1.getName(enum1.On, { arguType: 'value' })) // 开启
+## API
 
+### `createEnum(enumMap)`
 
-console.log(enum1.getOptions())
-// [
-//     {
-//         "value": 1,
-//         "label": "开启"
-//     },
-//     {
-//         "value": 0,
-//         "label": "关闭"
-//     }
-// ]
-console.log(enum1.getOptions({ labelKey: 'name', valueKey: 'key' }))
-// [
-//     {
-//         "key": 1,
-//         "name": "开启"
-//     },
-//     {
-//         "key": 0,
-//         "name": "关闭"
-//     }
-// ]
-console.log(enum1.getOptions('On'))
-// [
-//     {
-//         "value": 1,
-//         "label": "开启"
-//     }
-// ]
-console.log(enum1.getOptions(enum1.On, { arguType: 'value' }))
-// [
-//     {
-//         "value": 1,
-//         "label": "开启"
-//     }
-// ]
-console.log(enum1.getOptionsByValues())
+创建一个冻结的枚举实例。参数格式：
+
+```ts
+{
+  KEY: [value, label, extra?] // extra 可选
+} as const
+```
+
+---
+
+### 属性访问
+
+```ts
+Status.ACTIVE   // 1
+Status.INACTIVE // 0
+```
+
+直接通过 Key 获取 Value，享受完整的类型提示。
+
+---
+
+### `value(key)`
+
+通过 Key 获取 Value。
+
+```ts
+Status.value("ACTIVE"); // 1
+```
+
+---
+
+### `values(...keys?)`
+
+获取多个枚举值。不传参返回所有值。
+
+```ts
+Status.values();                   // [1, 0, 2]
+Status.values("ACTIVE", "PENDING"); // [1, 2]
+```
+
+---
+
+### `keys()`
+
+获取所有枚举 Key。
+
+```ts
+Status.keys(); // ['ACTIVE', 'INACTIVE', 'PENDING']
+```
+
+---
+
+### `label(keyOrValue)`
+
+通过 Key 或 Value 获取 Label，支持双向查找。
+
+```ts
+Status.label("ACTIVE"); // '激活'
+Status.label(1);        // '激活'
+```
+
+---
+
+### `extra(keyOrValue)`
+
+通过 Key 或 Value 获取附加数据。
+
+```ts
+Status.extra("ACTIVE"); // { color: 'green' }
+Status.extra(1);        // { color: 'green' }
+```
+
+---
+
+### `keyOf(value)`
+
+通过 Value 反查 Key。
+
+```ts
+Status.keyOf(1); // 'ACTIVE'
+Status.keyOf(0); // 'INACTIVE'
+```
+
+---
+
+### `check(val, key)`
+
+检测一个值是否等于指定 Key 对应的枚举值。
+
+```ts
+Status.check(1, "ACTIVE");   // true
+Status.check(1, "INACTIVE"); // false
+```
+
+---
+
+### `has(val)`
+
+判断一个值是否属于该枚举（类型守卫）。
+
+```ts
+Status.has(1);  // true
+Status.has(99); // false
+
+// 类型守卫：
+const val: unknown = 1;
+if (Status.has(val)) {
+  // val 在此分支中被收窄为 TEValue<typeof Status>
+}
+```
+
+---
+
+### `size`
+
+获取枚举项数量。
+
+```ts
+Status.size; // 3
+```
+
+---
+
+### `options(...keys?)`
+
+获取枚举选项列表，适配 Select/Radio/Checkbox 等 UI 组件。不传参返回所有。
+
+```ts
+Status.options();
 // [
-//     {
-//         "value": 1,
-//         "label": "开启"
-//     },
-//     {
-//         "value": 0,
-//         "label": "关闭"
-//     }
+//   { value: 1, label: '激活', extra: { color: 'green' } },
+//   { value: 0, label: '未激活', extra: { color: 'gray' } },
+//   { value: 2, label: '待审核', extra: { color: 'orange' } },
 // ]
-console.log(enum1.getOptionsByValues(enum1.On, { labelKey: 'name', valueKey: 'key' }))
+
+Status.options("ACTIVE", "PENDING");
+// 只返回指定项
+```
+
+---
+
+### `pick(...keys)`
+
+选取指定 Key，生成新的枚举实例。
+
+```ts
+const ActiveOnly = Status.pick("ACTIVE", "PENDING");
+ActiveOnly.ACTIVE;  // 1
+ActiveOnly.PENDING; // 2
+// ActiveOnly.INACTIVE  ← 类型错误，不存在
+```
+
+---
+
+### `omit(...keys)`
+
+排除指定 Key，生成新的枚举实例。
+
+```ts
+const WithoutPending = Status.omit("PENDING");
+WithoutPending.ACTIVE;   // 1
+WithoutPending.INACTIVE; // 0
+// WithoutPending.PENDING  ← 类型错误，不存在
+```
+
+---
+
+### `filter(predicate)`
+
+按条件过滤枚举项，返回满足条件的 options 数组。
+
+```ts
+// 过滤掉 INACTIVE
+Status.filter((value) => value !== 0);
 // [
-//     {
-//         "key": 1,
-//         "name": "开启"
-//     }
+//   { value: 1, label: '激活', extra: { color: 'green' } },
+//   { value: 2, label: '待审核', extra: { color: 'orange' } },
 // ]
 
-console.log(enum1.check(enum1.On, 'On')) // true
+// 根据 extra 过滤
+Status.filter((_v, _l, _k, extra) => extra?.color === "green");
+```
+
+回调参数：`(value, label, key, extra) => boolean`
+
+---
+
+### `forEach(callback)`
+
+遍历所有枚举项。
+
+```ts
+Status.forEach((value, label, key, extra) => {
+  console.log(`${key}: ${value} - ${label}`, extra);
+});
+```
+
+---
+
+### `for...of` 迭代
+
+枚举实例实现了 `Symbol.iterator`，支持 `for...of` 和展开运算符。
+
+```ts
+for (const { key, value, label, extra } of Status) {
+  console.log(key, value, label, extra);
+}
+
+const items = [...Status]; // 展开为数组
 ```
 
+---
+
+### `toMap()`
+
+转为 `Map<value, label>`。
+
+```ts
+Status.toMap();
+// Map { 1 => '激活', 0 => '未激活', 2 => '待审核' }
+```
+
+---
+
+### `toRecord()`
+
+转为 `{ [value]: label }` 对象。
+
+```ts
+Status.toRecord();
+// { 1: '激活', 0: '未激活', 2: '待审核' }
+```
+
+---
+
+## TypeScript 类型支持
+
+所有 API 均提供完整的类型推导：
+
+```ts
+const Status = createEnum({
+  ACTIVE:   [1, "激活", { color: "green" }],
+  INACTIVE: [0, "未激活", { color: "gray" }],
+} as const);
+
+Status.ACTIVE;          // 类型为 1（字面量）
+Status.value("ACTIVE"); // 类型为 number
+Status.label("ACTIVE"); // 类型为 string
+Status.extra("ACTIVE"); // 类型为 { readonly color: "green" }
+
+// pick/omit 返回类型正确收窄
+const picked = Status.pick("ACTIVE");
+picked.ACTIVE;   // ✅
+picked.INACTIVE; // ❌ 类型错误
+```
+
+## 典型场景
+
+### 配合 Select 组件
+
+```tsx
+const Status = createEnum({ ... } as const);
+
+// React / Vue
+<Select options={Status.options()} />
+
+// 只展示部分选项
+<Select options={Status.options("ACTIVE", "PENDING")} />
+
+// 动态过滤
+<Select options={Status.filter((v) => v !== 0)} />
+```
+
+### 表格列渲染
+
+```tsx
+const columns = [
+  {
+    title: "状态",
+    render: (val) => Status.label(val),
+  },
+];
+```
+
+### 条件判断
+
+```ts
+if (Status.check(row.status, "ACTIVE")) {
+  // ...
+}
+
+// 或者
+if (row.status === Status.ACTIVE) {
+  // ...
+}
+```
+
+## License
+
+ISC

package/dist/create-enum.cjs.js

@@ -1,241 +1 @@
-'use strict';
-
-/**
- * 数据类型
- * @param {*} data
- * @param {String} type
- * @returns {Boolean}
- */
-function isType(data, type) {
-    const dataType = Object.prototype.toString.call(data).slice(8, -1).toLowerCase();
-    return type === dataType;
-}
-/**
- * 数据是否为空
- * @param {*} data
- * @returns
- */
-function isEmpty(data) {
-    if (isType(data, "array") || isType(data, "string")) {
-        return data.length === 0;
-    }
-    if (data instanceof Map || data instanceof Set) {
-        return data.size === 0;
-    }
-    if (isType(data, "object")) {
-        return Object.keys(data).length === 0;
-    }
-    return Boolean(data);
-}
-/**
- * 深度拷贝
- * @param {Object|Array} obj
- * @return {Object|Array}
- */
-function deepClone(obj) {
-    let objClone = Array.isArray(obj) ? [] : {};
-    if (obj && typeof obj === "object") {
-        for (let key in obj) {
-            if (obj.hasOwnProperty(key)) {
-                //判断ojb子元素是否为对象，如果是，递归复制
-                if (obj[key] && typeof obj[key] === "object") {
-                    objClone[key] = deepClone(obj[key]);
-                }
-                else {
-                    //如果不是，简单复制
-                    objClone[key] = obj[key];
-                }
-            }
-        }
-    }
-    return objClone;
-}
-
-/**
- * 获取配置参数
- * @param {*} args
- * @returns
- */
-function getConfigParams(args) {
-    let config = { labelKey: "label", valueKey: "value", arguType: "key" }; // 选项参数配置
-    const lastArgu = args[args.length - 1];
-    if (isType(lastArgu, "object")) {
-        config = { ...config, ...lastArgu };
-        args = args.slice(0, args.length - 1);
-    }
-    return [config, args];
-}
-/**
- * 判断枚举key列表是否有效
- * @param {*} args
- * @returns {Boolean}
- */
-function judgEnumKeys(keys) {
-    return !isEmpty(keys) && keys.every((key) => typeof key === "string");
-}
-/**
- * 枚举类
- * @param {Object} enumMap 枚举对象
- * 枚举格式：
- * {
- *    枚举key1: [枚举值1，枚举描述1],
- *    枚举key2: [枚举值2，枚举描述2]
- * }
- */
-class Enum {
-    __enumMap__;
-    __enumValueMap__;
-    __enumNameMap__;
-    __valueNameMap__;
-    /**
-     * @param {Object} enumMap 枚举map
-     */
-    constructor(enumMap) {
-        if (!isType(enumMap, "object")) {
-            throw new TypeError("初始化参数值必须是一个object！");
-        }
-        this.#init(deepClone(enumMap));
-    }
-    /**
-     * 初始化
-     * @param {Object} enumMap 枚举对象
-     * @private
-     */
-    #init(enumMap) {
-        this.#setEnumMap(enumMap); //处理映射关系
-    }
-    /**
-     * 设置枚举间的映射
-     * @param {Object} enumMap
-     * @private
-     */
-    #setEnumMap(enumMap) {
-        const enumValueMap = {};
-        const enumNameMap = {};
-        const valueNameMap = {};
-        Object.keys(enumMap).forEach((key) => {
-            const item = enumMap[key];
-            if (!Array.isArray(item)) {
-                throw new TypeError("初始化参数对象字段的值必是一个array！");
-            }
-            enumValueMap[key] = item[0];
-            enumNameMap[key] = item[1];
-            valueNameMap[item[0]] = item[1];
-        });
-        this.__enumMap__ = Object.freeze(enumMap);
-        this.__enumValueMap__ = Object.freeze(enumValueMap);
-        this.__enumNameMap__ = Object.freeze(enumNameMap);
-        this.__valueNameMap__ = Object.freeze(valueNameMap);
-    }
-    /**
-     * 获取枚举值
-     * @param {String} key 枚举KEY
-     * @return {Number} 枚举值
-     */
-    getVal(key) {
-        return this.__enumValueMap__[key];
-    }
-    /**
-     * 获取多个枚举值
-     * @param {Array} param 多个枚举KEY
-     * @return {Array} {[枚举值]}
-     */
-    getValList(...args) {
-        let keys = Object.keys(this.__enumMap__); // 不传递返回所有
-        if (judgEnumKeys(args)) {
-            keys = Array.from(args);
-        }
-        return keys.map((key) => this.getVal(key));
-    }
-    /**
-     * 获取多个枚举值Map
-     * @param {Array} param 多个枚举KEY，如果不传递则返回所有
-     * @return {Object} {[枚举key]:枚举值}
-     */
-    getValMap(...args) {
-        let keys = Object.keys(this.__enumMap__); // 不传递返回所有
-        if (judgEnumKeys(args)) {
-            keys = Array.from(args);
-        }
-        return keys.reduce((wrap, key) => {
-            wrap[key] = this.getVal(key);
-            return wrap;
-        }, {});
-    }
-    getName(keyOrVal, _config) {
-        const [config] = getConfigParams([_config]);
-        if (config.arguType === "key") {
-            return this.__enumNameMap__[keyOrVal];
-        }
-        else if (config.arguType === "value") {
-            return this.getNameByValue(keyOrVal);
-        }
-        else {
-            throw new TypeError("参数arguType的值类型不为 key|value ！");
-        }
-    }
-    /**
-     * 通过枚举值获取枚举名称
-     * @param {String|Nunber} val
-     * @return {String|Null}
-     */
-    getNameByValue(val) {
-        return this.__valueNameMap__[val];
-    }
-    getOptions(..._args) {
-        const [config, args] = getConfigParams(_args);
-        if (config.arguType === "key") {
-            let keys = Object.keys(this.__enumMap__); // 不传递返回所有
-            if (judgEnumKeys(args)) {
-                keys = Array.from(args);
-            }
-            return keys.map((key) => {
-                const value = this.getVal(key);
-                const name = this.getName(key);
-                return { [config.valueKey]: value, [config.labelKey]: name };
-            });
-        }
-        else if (config.arguType === "value") {
-            return this.getOptionsByValues(..._args);
-        }
-        else {
-            throw new TypeError("参数arguType的值类型不为 key | value ！");
-        }
-    }
-    getOptionsByValues(..._args) {
-        const [config, args] = getConfigParams(_args);
-        let values = Object.values(this.__enumValueMap__); // 不传递返回所有
-        if (!isEmpty(args)) {
-            values = Array.from(args);
-        }
-        return values.map((value) => {
-            const name = this.getNameByValue(value);
-            return { [config.valueKey]: value, [config.labelKey]: name };
-        });
-    }
-    /**
-     * 检测字段类型
-     * @param {Number} typeVal 类型
-     * @param {String} typeKey 类型key
-     * @return {Boolean}
-     */
-    check(typeVal, typeKey) {
-        return this.getVal(typeKey) === typeVal;
-    }
-}
-/**
- * 创建枚举
- * @param {Object} enumMap
- * @param {String} description
- * @returns
- */
-const createEnum = (enumMap) => {
-    const enumInstance = new Enum(enumMap); // 返回实例
-    const e = Object.create(enumInstance);
-    for (const key in enumMap) {
-        e[key] = enumMap[key]?.[0];
-    }
-    return Object.freeze(e);
-};
-
-exports.createEnum = createEnum;
+"use strict";class e{__enumMap__;__enumLabelMap__;__enumExtraMap__;__valueKeyMap__;constructor(e){if(null===e||"object"!=typeof e||Array.isArray(e))throw new TypeError("初始化参数值必须是一个 object！");const t={},_={},r={},n=Object.keys(e);for(let a=0;a<n.length;a++){const s=n[a],u=e[s];if(!Array.isArray(u))throw new TypeError(`初始化参数对象字段 "${s}" 的值必须是一个 array！`);this[s]=u[0],t[s]=u[1],t[u[0]]=u[1],_[s]=u[2],_[u[0]]=u[2],r[u[0]]=s}this.__enumMap__=Object.freeze(e),this.__enumLabelMap__=Object.freeze(t),this.__enumExtraMap__=Object.freeze(_),this.__valueKeyMap__=Object.freeze(r)}keys(){return Object.keys(this.__enumMap__)}value(e){return this[e]}values(...e){return(e.length>0?e:this.keys()).map(e=>this.value(e))}options(...e){return(e.length>0?e:this.keys()).map(e=>({value:this.value(e),label:this.label(e),extra:this.extra(e)}))}label(e){return this.__enumLabelMap__[e]}extra(e){return this.__enumExtraMap__[e]}keyOf(e){return this.__valueKeyMap__[e]}check(e,t){return this.value(t)===e}has(e){return this.__valueKeyMap__.hasOwnProperty(e)}get size(){return Object.keys(this.__enumMap__).length}omit(...e){const _={},r=new Set(e),n=Object.keys(this.__enumMap__);for(let e=0;e<n.length;e++){const t=n[e];r.has(t)||(_[t]=this.__enumMap__[t])}return t(_)}pick(...e){const _={};for(let t=0;t<e.length;t++){const r=e[t];this.__enumMap__.hasOwnProperty(r)&&(_[r]=this.__enumMap__[r])}return t(_)}forEach(e){const t=Object.keys(this.__enumMap__);for(let _=0;_<t.length;_++){const r=t[_];e(this.value(r),this.__enumLabelMap__[r],r,this.__enumExtraMap__[r])}}toMap(){const e=new Map,t=Object.keys(this.__enumMap__);for(let _=0;_<t.length;_++){const r=t[_],n=this.__enumMap__[r];e.set(n[0],n[1])}return e}toRecord(){const e={},t=Object.keys(this.__enumMap__);for(let _=0;_<t.length;_++){const r=t[_],n=this.__enumMap__[r];e[n[0]]=n[1]}return e}filter(e){const t=[],_=Object.keys(this.__enumMap__);for(let r=0;r<_.length;r++){const n=_[r],a=this.value(n),s=this.__enumLabelMap__[n],u=this.__enumExtraMap__[n];e(a,s,n,u)&&t.push({value:a,label:s,extra:u})}return t}[Symbol.iterator](){const e=Object.keys(this.__enumMap__);let t=0;const _=this;return{next(){if(t<e.length){const r=e[t++];return{done:!1,value:{key:r,value:_.value(r),label:_.__enumLabelMap__[r],extra:_.__enumExtraMap__[r]}}}return{done:!0,value:void 0}}}}}const t=t=>{const _=new e(t);return Object.freeze(_)};module.exports=t;