@digitaldefiance/branded-enum 0.0.1 → 0.0.3

package/dist/cjs/lib/advanced.cjs

@@ -0,0 +1,558 @@
+/**
+ * Advanced enum operations for branded enums.
+ *
+ * Provides functions for deriving new enums from existing ones,
+ * including subsetting, exclusion, and transformation operations.
+ */ "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, {
+    clearAllEnumWatchers: function() {
+        return clearAllEnumWatchers;
+    },
+    enumDiff: function() {
+        return enumDiff;
+    },
+    enumExclude: function() {
+        return enumExclude;
+    },
+    enumFromKeys: function() {
+        return enumFromKeys;
+    },
+    enumIntersect: function() {
+        return enumIntersect;
+    },
+    enumMap: function() {
+        return enumMap;
+    },
+    enumSerializer: function() {
+        return enumSerializer;
+    },
+    enumSubset: function() {
+        return enumSubset;
+    },
+    enumToRecord: function() {
+        return enumToRecord;
+    },
+    exhaustive: function() {
+        return exhaustive;
+    },
+    exhaustiveGuard: function() {
+        return exhaustiveGuard;
+    },
+    getEnumWatcherCount: function() {
+        return getEnumWatcherCount;
+    },
+    getGlobalWatcherCount: function() {
+        return getGlobalWatcherCount;
+    },
+    toJsonSchema: function() {
+        return toJsonSchema;
+    },
+    toZodSchema: function() {
+        return toZodSchema;
+    },
+    watchAllEnums: function() {
+        return watchAllEnums;
+    },
+    watchEnum: function() {
+        return watchEnum;
+    }
+});
+const _types = require("./types.js");
+const _factory = require("./factory.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 enumSubset(newId, sourceEnum, keys) {
+    // Validate that sourceEnum is a branded enum
+    if (!isBrandedEnum(sourceEnum)) {
+        throw new Error('enumSubset requires a branded enum as the source');
+    }
+    // Validate that keys array is not empty
+    if (keys.length === 0) {
+        throw new Error('enumSubset requires at least one key');
+    }
+    const sourceEnumId = sourceEnum[_types.ENUM_ID];
+    // Build the subset values object
+    const subsetValues = {};
+    for (const key of keys){
+        // Validate that the key exists in the source enum
+        if (!(key in sourceEnum)) {
+            throw new Error(`Key "${key}" does not exist in enum "${sourceEnumId}"`);
+        }
+        // Copy the key-value pair
+        subsetValues[key] = sourceEnum[key];
+    }
+    // Create and return the new branded enum (this handles registration)
+    return (0, _factory.createBrandedEnum)(newId, subsetValues);
+}
+function enumExclude(newId, sourceEnum, keysToExclude) {
+    // Validate that sourceEnum is a branded enum
+    if (!isBrandedEnum(sourceEnum)) {
+        throw new Error('enumExclude requires a branded enum as the source');
+    }
+    const sourceEnumId = sourceEnum[_types.ENUM_ID];
+    // Validate that all keys to exclude exist in the source enum
+    for (const key of keysToExclude){
+        if (!(key in sourceEnum)) {
+            throw new Error(`Key "${key}" does not exist in enum "${sourceEnumId}"`);
+        }
+    }
+    // Create a Set for O(1) lookup of excluded keys
+    const excludeSet = new Set(keysToExclude);
+    // Get all keys from the source enum (excluding Symbol metadata)
+    const allKeys = Object.keys(sourceEnum);
+    // Build the result values object with non-excluded keys
+    const resultValues = {};
+    for (const key of allKeys){
+        if (!excludeSet.has(key)) {
+            resultValues[key] = sourceEnum[key];
+        }
+    }
+    // Validate that we have at least one key remaining
+    if (Object.keys(resultValues).length === 0) {
+        throw new Error('enumExclude: excluding all keys would result in an empty enum');
+    }
+    // Create and return the new branded enum (this handles registration)
+    return (0, _factory.createBrandedEnum)(newId, resultValues);
+}
+function enumMap(newId, sourceEnum, mapper) {
+    // Validate that sourceEnum is a branded enum
+    if (!isBrandedEnum(sourceEnum)) {
+        throw new Error('enumMap requires a branded enum as the source');
+    }
+    // Get all keys from the source enum (excluding Symbol metadata)
+    const allKeys = Object.keys(sourceEnum);
+    // Build the result values object with transformed values
+    const resultValues = {};
+    for (const key of allKeys){
+        const originalValue = sourceEnum[key];
+        const transformedValue = mapper(originalValue, key);
+        // Validate that the mapper returned a string
+        if (typeof transformedValue !== 'string') {
+            throw new Error('enumMap mapper must return a string');
+        }
+        resultValues[key] = transformedValue;
+    }
+    // Create and return the new branded enum (this handles registration)
+    return (0, _factory.createBrandedEnum)(newId, resultValues);
+}
+function enumFromKeys(enumId, keys) {
+    // Validate that keys array is not empty
+    if (keys.length === 0) {
+        throw new Error('enumFromKeys requires at least one key');
+    }
+    // Track seen keys to detect duplicates
+    const seenKeys = new Set();
+    // Build the values object where each key maps to itself
+    const values = {};
+    for (const key of keys){
+        // Validate that each key is a non-empty string
+        if (typeof key !== 'string' || key.length === 0) {
+            throw new Error('enumFromKeys requires all keys to be non-empty strings');
+        }
+        // Check for duplicate keys
+        if (seenKeys.has(key)) {
+            throw new Error(`enumFromKeys: duplicate key "${key}" found`);
+        }
+        seenKeys.add(key);
+        values[key] = key;
+    }
+    // Create and return the new branded enum (this handles registration)
+    return (0, _factory.createBrandedEnum)(enumId, values);
+}
+function enumDiff(firstEnum, secondEnum) {
+    // Validate that both arguments are branded enums
+    if (!isBrandedEnum(firstEnum) || !isBrandedEnum(secondEnum)) {
+        throw new Error('enumDiff requires branded enums as arguments');
+    }
+    // Get all keys from both enums (excluding Symbol metadata)
+    const firstKeys = new Set(Object.keys(firstEnum));
+    const secondKeys = new Set(Object.keys(secondEnum));
+    const onlyInFirst = [];
+    const onlyInSecond = [];
+    const differentValues = [];
+    const sameValues = [];
+    // Find keys only in first enum and keys in both
+    for (const key of firstKeys){
+        const firstValue = firstEnum[key];
+        if (!secondKeys.has(key)) {
+            // Key only exists in first enum
+            onlyInFirst.push({
+                key,
+                value: firstValue
+            });
+        } else {
+            // Key exists in both - compare values
+            const secondValue = secondEnum[key];
+            if (firstValue === secondValue) {
+                sameValues.push({
+                    key,
+                    value: firstValue
+                });
+            } else {
+                differentValues.push({
+                    key,
+                    firstValue,
+                    secondValue
+                });
+            }
+        }
+    }
+    // Find keys only in second enum
+    for (const key of secondKeys){
+        if (!firstKeys.has(key)) {
+            const secondValue = secondEnum[key];
+            onlyInSecond.push({
+                key,
+                value: secondValue
+            });
+        }
+    }
+    return {
+        onlyInFirst,
+        onlyInSecond,
+        differentValues,
+        sameValues
+    };
+}
+function enumIntersect(...enums) {
+    // Validate that at least two enums are provided
+    if (enums.length < 2) {
+        throw new Error('enumIntersect requires at least two branded enums');
+    }
+    // Validate that all arguments are branded enums
+    for (const enumObj of enums){
+        if (!isBrandedEnum(enumObj)) {
+            throw new Error('enumIntersect requires all arguments to be branded enums');
+        }
+    }
+    // Build a map of value -> Set of enum IDs containing that value
+    const valueToEnumIds = new Map();
+    for (const enumObj of enums){
+        const enumId = enumObj[_types.ENUM_ID];
+        const values = enumObj[_types.ENUM_VALUES];
+        for (const value of values){
+            if (!valueToEnumIds.has(value)) {
+                valueToEnumIds.set(value, new Set());
+            }
+            valueToEnumIds.get(value).add(enumId);
+        }
+    }
+    // Filter to only values that appear in multiple enums
+    const result = [];
+    for (const [value, enumIds] of valueToEnumIds){
+        if (enumIds.size >= 2) {
+            result.push({
+                value,
+                enumIds: Array.from(enumIds).sort()
+            });
+        }
+    }
+    // Sort by value for consistent ordering
+    result.sort((a, b)=>a.value.localeCompare(b.value));
+    return result;
+}
+function enumToRecord(enumObj) {
+    // Validate that enumObj is a branded enum
+    if (!isBrandedEnum(enumObj)) {
+        throw new Error('enumToRecord requires a branded enum');
+    }
+    // Create a new plain object with only the enumerable key-value pairs
+    const result = {};
+    for (const key of Object.keys(enumObj)){
+        result[key] = enumObj[key];
+    }
+    return result;
+}
+/**
+ * The key used to store the enum watcher registry on globalThis.
+ * Namespaced to avoid collisions with other libraries.
+ */ const WATCHER_REGISTRY_KEY = '__brandedEnumWatcherRegistry__';
+/**
+ * Gets or initializes the watcher registry on globalThis.
+ */ function getWatcherRegistry() {
+    const global = globalThis;
+    if (!global[WATCHER_REGISTRY_KEY]) {
+        global[WATCHER_REGISTRY_KEY] = {
+            watchers: new Map(),
+            globalWatchers: new Set()
+        };
+    }
+    return global[WATCHER_REGISTRY_KEY];
+}
+function watchEnum(enumObj, callback) {
+    // Validate that enumObj is a branded enum
+    if (!isBrandedEnum(enumObj)) {
+        throw new Error('watchEnum requires a branded enum');
+    }
+    const enumId = enumObj[_types.ENUM_ID];
+    const registry = getWatcherRegistry();
+    // Add callback to the registry for this enum
+    if (!registry.watchers.has(enumId)) {
+        registry.watchers.set(enumId, new Set());
+    }
+    registry.watchers.get(enumId).add(callback);
+    // Track if this watcher is still active
+    let isActive = true;
+    // Create a Proxy to intercept access
+    const proxy = new Proxy(enumObj, {
+        get (target, prop, receiver) {
+            const value = Reflect.get(target, prop, receiver);
+            // Only trigger callback for active watchers and string keys (not symbols)
+            if (isActive && typeof prop === 'string') {
+                const event = {
+                    enumId,
+                    accessType: 'get',
+                    key: prop,
+                    value: typeof value === 'string' ? value : undefined,
+                    timestamp: Date.now()
+                };
+                // Call the specific callback
+                callback(event);
+                // Also call any global watchers
+                for (const globalCallback of registry.globalWatchers){
+                    globalCallback(event);
+                }
+            }
+            return value;
+        },
+        has (target, prop) {
+            const result = Reflect.has(target, prop);
+            // Only trigger callback for active watchers and string keys
+            if (isActive && typeof prop === 'string') {
+                const event = {
+                    enumId,
+                    accessType: 'has',
+                    key: prop,
+                    timestamp: Date.now()
+                };
+                callback(event);
+                for (const globalCallback of registry.globalWatchers){
+                    globalCallback(event);
+                }
+            }
+            return result;
+        },
+        ownKeys (target) {
+            const keys = Reflect.ownKeys(target);
+            if (isActive) {
+                const event = {
+                    enumId,
+                    accessType: 'keys',
+                    timestamp: Date.now()
+                };
+                callback(event);
+                for (const globalCallback of registry.globalWatchers){
+                    globalCallback(event);
+                }
+            }
+            return keys;
+        },
+        getOwnPropertyDescriptor (target, prop) {
+            return Reflect.getOwnPropertyDescriptor(target, prop);
+        }
+    });
+    // Create unwatch function
+    const unwatch = ()=>{
+        isActive = false;
+        const callbacks = registry.watchers.get(enumId);
+        if (callbacks) {
+            callbacks.delete(callback);
+            if (callbacks.size === 0) {
+                registry.watchers.delete(enumId);
+            }
+        }
+    };
+    return {
+        watched: proxy,
+        unwatch
+    };
+}
+function watchAllEnums(callback) {
+    const registry = getWatcherRegistry();
+    registry.globalWatchers.add(callback);
+    return ()=>{
+        registry.globalWatchers.delete(callback);
+    };
+}
+function clearAllEnumWatchers() {
+    const registry = getWatcherRegistry();
+    registry.watchers.clear();
+    registry.globalWatchers.clear();
+}
+function getEnumWatcherCount(enumId) {
+    const registry = getWatcherRegistry();
+    return registry.watchers.get(enumId)?.size ?? 0;
+}
+function getGlobalWatcherCount() {
+    const registry = getWatcherRegistry();
+    return registry.globalWatchers.size;
+}
+function exhaustive(value, message) {
+    const errorMessage = message ?? `Exhaustive check failed: unexpected value "${String(value)}"`;
+    throw new Error(errorMessage);
+}
+function exhaustiveGuard(enumObj) {
+    // Validate that enumObj is a branded enum
+    if (!isBrandedEnum(enumObj)) {
+        throw new Error('exhaustiveGuard requires a branded enum');
+    }
+    const enumId = enumObj[_types.ENUM_ID];
+    return (value)=>{
+        throw new Error(`Exhaustive check failed for enum "${enumId}": unexpected value "${String(value)}"`);
+    };
+}
+/**
+ * Maps schema version options to their corresponding $schema URIs.
+ */ const SCHEMA_VERSION_URIS = {
+    'draft-04': 'http://json-schema.org/draft-04/schema#',
+    'draft-06': 'http://json-schema.org/draft-06/schema#',
+    'draft-07': 'http://json-schema.org/draft-07/schema#',
+    '2019-09': 'https://json-schema.org/draft/2019-09/schema',
+    '2020-12': 'https://json-schema.org/draft/2020-12/schema'
+};
+function toJsonSchema(enumObj, options = {}) {
+    // Validate that enumObj is a branded enum
+    if (!isBrandedEnum(enumObj)) {
+        throw new Error('toJsonSchema requires a branded enum');
+    }
+    const enumId = enumObj[_types.ENUM_ID];
+    const values = enumObj[_types.ENUM_VALUES];
+    // Extract options with defaults
+    const { title = enumId, description = `Enum values for ${enumId}`, includeSchema = true, schemaVersion = 'draft-07' } = options;
+    // Build the schema object
+    const schema = {
+        title,
+        description,
+        type: 'string',
+        enum: Array.from(values).sort()
+    };
+    // Add $schema if requested
+    if (includeSchema) {
+        return {
+            $schema: SCHEMA_VERSION_URIS[schemaVersion],
+            ...schema
+        };
+    }
+    return schema;
+}
+function toZodSchema(enumObj, options = {}) {
+    // Validate that enumObj is a branded enum
+    if (!isBrandedEnum(enumObj)) {
+        throw new Error('toZodSchema requires a branded enum');
+    }
+    const enumId = enumObj[_types.ENUM_ID];
+    const values = enumObj[_types.ENUM_VALUES];
+    // Convert Set to sorted array
+    const valuesArray = Array.from(values).sort();
+    // Zod's z.enum() requires at least one value
+    if (valuesArray.length === 0) {
+        throw new Error('toZodSchema requires an enum with at least one value');
+    }
+    // Build the schema definition
+    const definition = {
+        typeName: 'ZodEnum',
+        values: valuesArray,
+        enumId
+    };
+    // Add description if provided
+    if (options.description !== undefined) {
+        return {
+            ...definition,
+            description: options.description
+        };
+    }
+    return definition;
+}
+function enumSerializer(enumObj, options = {}) {
+    // Validate that enumObj is a branded enum
+    if (!isBrandedEnum(enumObj)) {
+        throw new Error('enumSerializer requires a branded enum');
+    }
+    const enumId = enumObj[_types.ENUM_ID];
+    const values = enumObj[_types.ENUM_VALUES];
+    const validValues = Array.from(values).sort();
+    const { serialize: serializeTransform, deserialize: deserializeTransform } = options;
+    return {
+        enumObj,
+        enumId,
+        serialize (value) {
+            // Apply custom transform if provided
+            if (serializeTransform) {
+                return serializeTransform(value);
+            }
+            return value;
+        },
+        deserialize (value) {
+            // Check if value is a string
+            if (typeof value !== 'string') {
+                const valueType = value === null ? 'null' : typeof value;
+                return {
+                    success: false,
+                    error: {
+                        message: `Expected a string value, received ${valueType}`,
+                        input: value,
+                        enumId,
+                        validValues
+                    }
+                };
+            }
+            // Apply custom deserialize transform if provided
+            let transformedValue = value;
+            if (deserializeTransform) {
+                try {
+                    transformedValue = deserializeTransform(value);
+                } catch (e) {
+                    return {
+                        success: false,
+                        error: {
+                            message: `Deserialize transform failed: ${e instanceof Error ? e.message : String(e)}`,
+                            input: value,
+                            enumId,
+                            validValues
+                        }
+                    };
+                }
+            }
+            // Validate against the enum
+            if (!values.has(transformedValue)) {
+                return {
+                    success: false,
+                    error: {
+                        message: `Value "${transformedValue}" is not a member of enum "${enumId}"`,
+                        input: value,
+                        enumId,
+                        validValues
+                    }
+                };
+            }
+            return {
+                success: true,
+                value: transformedValue
+            };
+        },
+        deserializeOrThrow (value) {
+            const result = this.deserialize(value);
+            if (!result.success) {
+                throw new Error(result.error.message);
+            }
+            return result.value;
+        }
+    };
+}
+
+//# sourceMappingURL=advanced.cjs.map