@digitaldefiance/branded-enum 0.0.1 → 0.0.3

package/dist/cjs/index.cjs

@@ -0,0 +1,149 @@
+/**
+ * branded-enum - Runtime-identifiable enum-like types for TypeScript
+ *
+ * This library provides enum-like objects with embedded metadata for runtime
+ * identification, enabling you to determine which enum a string value belongs to.
+ *
+ * @packageDocumentation
+ */ // =============================================================================
+// Types
+// =============================================================================
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: all[name]
+    });
+}
+_export(exports, {
+    EnumClass: function() {
+        return _decorators.EnumClass;
+    },
+    EnumValue: function() {
+        return _decorators.EnumValue;
+    },
+    assertFromEnum: function() {
+        return _guards.assertFromEnum;
+    },
+    clearAllEnumWatchers: function() {
+        return _advanced.clearAllEnumWatchers;
+    },
+    createBrandedEnum: function() {
+        return _factory.createBrandedEnum;
+    },
+    enumDiff: function() {
+        return _advanced.enumDiff;
+    },
+    enumEntries: function() {
+        return _utils.enumEntries;
+    },
+    enumExclude: function() {
+        return _advanced.enumExclude;
+    },
+    enumFromKeys: function() {
+        return _advanced.enumFromKeys;
+    },
+    enumIntersect: function() {
+        return _advanced.enumIntersect;
+    },
+    enumMap: function() {
+        return _advanced.enumMap;
+    },
+    enumSerializer: function() {
+        return _advanced.enumSerializer;
+    },
+    enumSize: function() {
+        return _accessors.enumSize;
+    },
+    enumSubset: function() {
+        return _advanced.enumSubset;
+    },
+    enumToRecord: function() {
+        return _advanced.enumToRecord;
+    },
+    exhaustive: function() {
+        return _advanced.exhaustive;
+    },
+    exhaustiveGuard: function() {
+        return _advanced.exhaustiveGuard;
+    },
+    findEnumSources: function() {
+        return _registry.findEnumSources;
+    },
+    getAllEnumConsumers: function() {
+        return _decorators.getAllEnumConsumers;
+    },
+    getAllEnumIds: function() {
+        return _registry.getAllEnumIds;
+    },
+    getConsumedEnums: function() {
+        return _decorators.getConsumedEnums;
+    },
+    getEnumById: function() {
+        return _registry.getEnumById;
+    },
+    getEnumConsumers: function() {
+        return _decorators.getEnumConsumers;
+    },
+    getEnumId: function() {
+        return _accessors.getEnumId;
+    },
+    getEnumValues: function() {
+        return _accessors.getEnumValues;
+    },
+    getEnumWatcherCount: function() {
+        return _advanced.getEnumWatcherCount;
+    },
+    getGlobalWatcherCount: function() {
+        return _advanced.getGlobalWatcherCount;
+    },
+    getKeyForValue: function() {
+        return _utils.getKeyForValue;
+    },
+    getRegistry: function() {
+        return _registry.getRegistry;
+    },
+    hasValue: function() {
+        return _utils.hasValue;
+    },
+    isFromEnum: function() {
+        return _guards.isFromEnum;
+    },
+    isValidKey: function() {
+        return _utils.isValidKey;
+    },
+    mergeEnums: function() {
+        return _merge.mergeEnums;
+    },
+    parseEnum: function() {
+        return _guards.parseEnum;
+    },
+    safeParseEnum: function() {
+        return _guards.safeParseEnum;
+    },
+    toJsonSchema: function() {
+        return _advanced.toJsonSchema;
+    },
+    toZodSchema: function() {
+        return _advanced.toZodSchema;
+    },
+    watchAllEnums: function() {
+        return _advanced.watchAllEnums;
+    },
+    watchEnum: function() {
+        return _advanced.watchEnum;
+    }
+});
+const _factory = require("./lib/factory.js");
+const _registry = require("./lib/registry.js");
+const _guards = require("./lib/guards.js");
+const _accessors = require("./lib/accessors.js");
+const _utils = require("./lib/utils.js");
+const _merge = require("./lib/merge.js");
+const _advanced = require("./lib/advanced.js");
+const _decorators = require("./lib/decorators.js");
+
+//# sourceMappingURL=index.cjs.map

package/dist/cjs/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/index.ts"],"sourcesContent":["/**\n * branded-enum - Runtime-identifiable enum-like types for TypeScript\n *\n * This library provides enum-like objects with embedded metadata for runtime\n * identification, enabling you to determine which enum a string value belongs to.\n *\n * @packageDocumentation\n */\n\n// =============================================================================\n// Types\n// =============================================================================\n\nexport type {\n  BrandedEnumMetadata,\n  BrandedEnum,\n  BrandedEnumValue,\n  RegistryEntry,\n  BrandedEnumRegistry,\n  EnumConsumerEntry,\n  EnumConsumerRegistry,\n  AnyBrandedEnum,\n  EnumKeys,\n  EnumValues,\n  ValidEnumValue,\n  StrictEnumParam,\n} from './lib/types.js';\n\n// =============================================================================\n// Factory\n// =============================================================================\n\nexport { createBrandedEnum } from './lib/factory.js';\n\n// =============================================================================\n// Registry\n// =============================================================================\n\nexport {\n  getRegistry,\n  getAllEnumIds,\n  getEnumById,\n  findEnumSources,\n} from './lib/registry.js';\n\n// =============================================================================\n// Type Guards\n// =============================================================================\n\nexport { isFromEnum, assertFromEnum, parseEnum, safeParseEnum } from './lib/guards.js';\nexport type { SafeParseSuccess, SafeParseFailure, SafeParseError, SafeParseErrorCode, SafeParseResult } from './lib/guards.js';\n\n// =============================================================================\n// Metadata Accessors\n// =============================================================================\n\nexport { getEnumId, getEnumValues, enumSize } from './lib/accessors.js';\n\n// =============================================================================\n// Utility Functions\n// =============================================================================\n\nexport {\n  hasValue,\n  getKeyForValue,\n  isValidKey,\n  enumEntries,\n} from './lib/utils.js';\n\n// =============================================================================\n// Composition\n// =============================================================================\n\nexport { mergeEnums } from './lib/merge.js';\n\n// =============================================================================\n// Advanced Operations\n// =============================================================================\n\nexport { enumSubset, enumExclude, enumMap, enumFromKeys, enumDiff, enumIntersect, enumToRecord, watchEnum, watchAllEnums, clearAllEnumWatchers, getEnumWatcherCount, getGlobalWatcherCount, exhaustive, exhaustiveGuard, toJsonSchema, toZodSchema, enumSerializer } from './lib/advanced.js';\nexport type { EnumDiffResult, EnumIntersectEntry, EnumAccessType, EnumAccessEvent, EnumWatchCallback, WatchEnumResult, ToJsonSchemaOptions, EnumJsonSchema, ToZodSchemaOptions, ZodEnumSchemaDefinition, EnumSerializerOptions, DeserializeSuccess, DeserializeFailure, DeserializeResult, EnumSerializer } from './lib/advanced.js';\n\n// =============================================================================\n// Decorators\n// =============================================================================\n\nexport {\n  EnumValue,\n  EnumClass,\n  getEnumConsumers,\n  getConsumedEnums,\n  getAllEnumConsumers,\n} from './lib/decorators.js';\nexport type { EnumValueOptions } from './lib/decorators.js';\n"],"names":["EnumClass","EnumValue","assertFromEnum","clearAllEnumWatchers","createBrandedEnum","enumDiff","enumEntries","enumExclude","enumFromKeys","enumIntersect","enumMap","enumSerializer","enumSize","enumSubset","enumToRecord","exhaustive","exhaustiveGuard","findEnumSources","getAllEnumConsumers","getAllEnumIds","getConsumedEnums","getEnumById","getEnumConsumers","getEnumId","getEnumValues","getEnumWatcherCount","getGlobalWatcherCount","getKeyForValue","getRegistry","hasValue","isFromEnum","isValidKey","mergeEnums","parseEnum","safeParseEnum","toJsonSchema","toZodSchema","watchAllEnums","watchEnum"],"rangeMappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;","mappings":"AAAA;;;;;;;CAOC,GAED,gFAAgF;AAChF,QAAQ;AACR,gFAAgF;;;;;;;;;;;;IA6E9EA,SAAS;eAATA,qBAAS;;IADTC,SAAS;eAATA,qBAAS;;IAtCUC,cAAc;eAAdA,sBAAc;;IA8BuFC,oBAAoB;eAApBA,8BAAoB;;IA/CrIC,iBAAiB;eAAjBA,0BAAiB;;IA+C+BC,QAAQ;eAARA,kBAAQ;;IAb/DC,WAAW;eAAXA,kBAAW;;IAaQC,WAAW;eAAXA,qBAAW;;IAAWC,YAAY;eAAZA,sBAAY;;IAAYC,aAAa;eAAbA,uBAAa;;IAA9CC,OAAO;eAAPA,iBAAO;;IAA2MC,cAAc;eAAdA,wBAAc;;IAvB/NC,QAAQ;eAARA,mBAAQ;;IAuBlCC,UAAU;eAAVA,oBAAU;;IAA+DC,YAAY;eAAZA,sBAAY;;IAA8FC,UAAU;eAAVA,oBAAU;;IAAEC,eAAe;eAAfA,yBAAe;;IArCrNC,eAAe;eAAfA,yBAAe;;IAiDfC,mBAAmB;eAAnBA,+BAAmB;;IAnDnBC,aAAa;eAAbA,uBAAa;;IAkDbC,gBAAgB;eAAhBA,4BAAgB;;IAjDhBC,WAAW;eAAXA,qBAAW;;IAgDXC,gBAAgB;eAAhBA,4BAAgB;;IAjCTC,SAAS;eAATA,oBAAS;;IAAEC,aAAa;eAAbA,wBAAa;;IAuB+GC,mBAAmB;eAAnBA,6BAAmB;;IAAEC,qBAAqB;eAArBA,+BAAqB;;IAfxLC,cAAc;eAAdA,qBAAc;;IAzBdC,WAAW;eAAXA,qBAAW;;IAwBXC,QAAQ;eAARA,eAAQ;;IAdDC,UAAU;eAAVA,kBAAU;;IAgBjBC,UAAU;eAAVA,iBAAU;;IAQHC,UAAU;eAAVA,iBAAU;;IAxBkBC,SAAS;eAATA,iBAAS;;IAAEC,aAAa;eAAbA,qBAAa;;IA8B4JC,YAAY;eAAZA,sBAAY;;IAAEC,WAAW;eAAXA,qBAAW;;IAAvIC,aAAa;eAAbA,uBAAa;;IAAxBC,SAAS;eAATA,mBAAS;;;yBA/CvE;0BAW3B;wBAM8D;2BAOlB;uBAW5C;uBAMoB;0BAM+O;4BAanQ"}

package/dist/cjs/lib/accessors.cjs

@@ -0,0 +1,55 @@
+/**
+ * Metadata accessors for branded enums.
+ *
+ * Provides functions to retrieve metadata from branded enum objects,
+ * including enum ID, values array, and size.
+ */ "use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: all[name]
+    });
+}
+_export(exports, {
+    enumSize: function() {
+        return enumSize;
+    },
+    getEnumId: function() {
+        return getEnumId;
+    },
+    getEnumValues: function() {
+        return getEnumValues;
+    }
+});
+const _types = require("./types.js");
+/**
+ * Checks if an object is a branded enum (has Symbol metadata).
+ *
+ * @param obj - The object to check
+ * @returns true if obj is a branded enum
+ */ function isBrandedEnum(obj) {
+    return obj !== null && typeof obj === 'object' && _types.ENUM_ID in obj && _types.ENUM_VALUES in obj && typeof obj[_types.ENUM_ID] === 'string' && obj[_types.ENUM_VALUES] instanceof Set;
+}
+function getEnumId(enumObj) {
+    if (!isBrandedEnum(enumObj)) {
+        return undefined;
+    }
+    return enumObj[_types.ENUM_ID];
+}
+function getEnumValues(enumObj) {
+    if (!isBrandedEnum(enumObj)) {
+        return undefined;
+    }
+    return Array.from(enumObj[_types.ENUM_VALUES]);
+}
+function enumSize(enumObj) {
+    if (!isBrandedEnum(enumObj)) {
+        return undefined;
+    }
+    return enumObj[_types.ENUM_VALUES].size;
+}
+
+//# sourceMappingURL=accessors.cjs.map

package/dist/cjs/lib/accessors.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/lib/accessors.ts"],"sourcesContent":["/**\n * Metadata accessors for branded enums.\n *\n * Provides functions to retrieve metadata from branded enum objects,\n * including enum ID, values array, and size.\n */\n\nimport {\n  AnyBrandedEnum,\n  BrandedEnum,\n  BrandedEnumValue,\n  ENUM_ID,\n  ENUM_VALUES,\n  EnumValues,\n} from './types.js';\n\n/**\n * Checks if an object is a branded enum (has Symbol metadata).\n *\n * @param obj - The object to check\n * @returns true if obj is a branded enum\n */\nfunction isBrandedEnum(obj: unknown): obj is AnyBrandedEnum {\n  return (\n    obj !== null &&\n    typeof obj === 'object' &&\n    ENUM_ID in obj &&\n    ENUM_VALUES in obj &&\n    typeof (obj as AnyBrandedEnum)[ENUM_ID] === 'string' &&\n    (obj as AnyBrandedEnum)[ENUM_VALUES] instanceof Set\n  );\n}\n\n/**\n * Gets the enum ID from a branded enum.\n *\n * Retrieves the unique identifier that was assigned when the enum was created.\n * Returns undefined for objects that are not branded enums.\n *\n * @param enumObj - The object to get the enum ID from. Can be any type.\n * @returns The enum ID string if enumObj is a branded enum, `undefined` otherwise.\n *\n * @example\n * // Get ID from branded enum\n * const Status = createBrandedEnum('status', { Active: 'active' } as const);\n * getEnumId(Status); // 'status'\n *\n * @example\n * // Returns undefined for non-branded objects\n * getEnumId({}); // undefined\n * getEnumId({ Active: 'active' }); // undefined\n * getEnumId(null); // undefined\n */\nexport function getEnumId(enumObj: unknown): string | undefined {\n  if (!isBrandedEnum(enumObj)) {\n    return undefined;\n  }\n  return enumObj[ENUM_ID];\n}\n\n/**\n * Gets all values from a branded enum as an array.\n *\n * Returns an array containing all the string values in the enum.\n * The order of values is not guaranteed.\n *\n * @template E - The branded enum type\n * @param enumObj - The object to get values from. Can be any type.\n * @returns Array of all enum values if enumObj is a branded enum,\n *   `undefined` otherwise.\n *\n * @example\n * // Get values from branded enum\n * const Status = createBrandedEnum('status', {\n *   Active: 'active',\n *   Inactive: 'inactive'\n * } as const);\n * getEnumValues(Status); // ['active', 'inactive']\n *\n * @example\n * // Returns undefined for non-branded objects\n * getEnumValues({}); // undefined\n * getEnumValues({ Active: 'active' }); // undefined\n */\nexport function getEnumValues<E extends AnyBrandedEnum>(\n  enumObj: E\n): EnumValues<E>[] | undefined;\nexport function getEnumValues(enumObj: unknown): string[] | undefined;\nexport function getEnumValues(enumObj: unknown): string[] | undefined {\n  if (!isBrandedEnum(enumObj)) {\n    return undefined;\n  }\n  return Array.from(enumObj[ENUM_VALUES]);\n}\n\n/**\n * Gets the number of values in a branded enum.\n *\n * Returns the count of unique values in the enum. This is equivalent to\n * the number of key-value pairs defined when the enum was created.\n *\n * @param enumObj - The object to get the size of. Can be any type.\n * @returns The number of values in the enum if enumObj is a branded enum,\n *   `undefined` otherwise.\n *\n * @example\n * // Get size of branded enum\n * const Status = createBrandedEnum('status', {\n *   Active: 'active',\n *   Inactive: 'inactive'\n * } as const);\n * enumSize(Status); // 2\n *\n * @example\n * // Returns undefined for non-branded objects\n * enumSize({}); // undefined\n * enumSize({ Active: 'active' }); // undefined\n */\nexport function enumSize(enumObj: unknown): number | undefined {\n  if (!isBrandedEnum(enumObj)) {\n    return undefined;\n  }\n  return enumObj[ENUM_VALUES].size;\n}\n"],"names":["enumSize","getEnumId","getEnumValues","isBrandedEnum","obj","ENUM_ID","ENUM_VALUES","Set","enumObj","undefined","Array","from","size"],"rangeMappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;","mappings":"AAAA;;;;;CAKC;;;;;;;;;;;IAiHeA,QAAQ;eAARA;;IAjEAC,SAAS;eAATA;;IAmCAC,aAAa;eAAbA;;;uBA1ET;AAEP;;;;;CAKC,GACD,SAASC,cAAcC,GAAY;IACjC,OACEA,QAAQ,QACR,OAAOA,QAAQ,YACfC,cAAO,IAAID,OACXE,kBAAW,IAAIF,OACf,OAAO,AAACA,GAAsB,CAACC,cAAO,CAAC,KAAK,YAC5C,AAACD,GAAsB,CAACE,kBAAW,CAAC,YAAYC;AAEpD;AAsBO,SAASN,UAAUO,OAAgB;IACxC,IAAI,CAACL,cAAcK,UAAU;QAC3B,OAAOC;IACT;IACA,OAAOD,OAAO,CAACH,cAAO,CAAC;AACzB;AA8BO,SAASH,cAAcM,OAAgB;IAC5C,IAAI,CAACL,cAAcK,UAAU;QAC3B,OAAOC;IACT;IACA,OAAOC,MAAMC,IAAI,CAACH,OAAO,CAACF,kBAAW,CAAC;AACxC;AAyBO,SAASN,SAASQ,OAAgB;IACvC,IAAI,CAACL,cAAcK,UAAU;QAC3B,OAAOC;IACT;IACA,OAAOD,OAAO,CAACF,kBAAW,CAAC,CAACM,IAAI;AAClC"}