@reharik/smart-enum 0.4.5 → 0.4.6

package/dist/index.js

@@ -1,29 +1,608 @@
-import {
-  getSubsetByProp,
-  subsetByProp
-} from "./chunk-F65KCMGE.js";
-import {
-  EnumRevivalError,
-  prepareForDatabase,
-  revivePayloadFromDatabase,
-  reviveRowFromDatabase
-} from "./chunk-62LMAE3X.js";
-import {
-  getGlobalEnumRegistry,
-  initializeSmartEnumMappings,
-  reviveAfterTransport,
-  serializeForTransport
-} from "./chunk-QNY5W4SX.js";
-import {
-  enumeration,
-  isSmartEnum,
-  isSmartEnumItem,
-  resetDefaultSerializationMode,
-  reviveEnumField,
-  reviveSmartEnums,
-  serializeSmartEnums,
-  setDefaultSerializationMode
-} from "./chunk-WNCJN5E6.js";
+// src/types.ts
+var SMART_ENUM_ITEM = Symbol("smart-enum-item");
+var SMART_ENUM_ID = Symbol("smart-enum-id");
+var SMART_ENUM = Symbol("smart-enum");
+
+// src/utilities/typeGuards.ts
+var isSmartEnumItem = (x) => {
+  return !!x && typeof x === "object" && Reflect.get(x, SMART_ENUM_ITEM) === true;
+};
+var isSmartEnum = (x) => {
+  return !!x && typeof x === "object" && Reflect.get(x, SMART_ENUM) === true;
+};
+var isSerializedSmartEnumItem = (x) => {
+  return !!x && typeof x === "object" && Reflect.has(x, "__smart_enum_type") && Reflect.has(x, "value");
+};
+
+// src/utilities/enumItemsEqual.ts
+var enumItemsEqual = (a, b) => {
+  if (!isSmartEnumItem(a) || !isSmartEnumItem(b)) {
+    return false;
+  }
+  return Reflect.get(a, SMART_ENUM_ID) === Reflect.get(b, SMART_ENUM_ID) && a.value === b.value;
+};
+
+// src/extensionMethods.ts
+var addExtensionMethods = (enumItems) => {
+  const findBy = (field, target) => enumItems.find((item) => item[field] === target);
+  const requireBy = (field, target, label) => {
+    const item = findBy(field, target);
+    if (!item) {
+      throw new Error(`No enum ${label} found for '${String(target)}'`);
+    }
+    return item;
+  };
+  return {
+    fromValue: (value) => requireBy("value", value, "value"),
+    tryFromValue: (value) => value ? findBy("value", value) : void 0,
+    fromKey: (key) => requireBy("key", key, "key"),
+    tryFromKey: (key) => key ? findBy("key", key) : void 0,
+    equals: enumItemsEqual,
+    items: () => [...enumItems],
+    values: () => enumItems.map((item) => item.value),
+    keys: () => enumItems.map((item) => item.key)
+  };
+};
+
+// src/utilities/getSubsetByProp.ts
+var RESERVED_ENUM_MEMBER_KEYS = /* @__PURE__ */ new Set([
+  "fromValue",
+  "tryFromValue",
+  "fromKey",
+  "tryFromKey",
+  "items",
+  "values",
+  "keys"
+]);
+var getSubsetByProp = (enumInstance, prop, value) => {
+  const matching = [];
+  const memberEntries = {};
+  for (const key of Reflect.ownKeys(enumInstance)) {
+    if (typeof key !== "string" || RESERVED_ENUM_MEMBER_KEYS.has(key)) {
+      continue;
+    }
+    const entry = enumInstance[key];
+    if (!isSmartEnumItem(entry)) {
+      continue;
+    }
+    const item = entry;
+    if (Object.is(item[prop], value)) {
+      memberEntries[key] = item;
+      matching.push(item);
+    }
+  }
+  const methods = addExtensionMethods(
+    matching
+  );
+  return {
+    ...memberEntries,
+    ...methods
+  };
+};
+var subsetByProp = (prop) => (enumInstance, value) => (
+  // `getSubsetByProp` widens `prop` in its return; re-assert to keep curried literal `P` for Pick/Extract.
+  getSubsetByProp(
+    enumInstance,
+    prop,
+    value
+  )
+);
+
+// src/enumerations.ts
+import { capitalCase, constantCase } from "case-anything";
+
+// src/utilities/serializationMode.ts
+var globalDefault;
+var setDefaultSerializationMode = (mode) => {
+  globalDefault = mode;
+};
+var resetDefaultSerializationMode = () => {
+  globalDefault = void 0;
+};
+var resolveSerializationMode = (perEnum) => perEnum ?? globalDefault ?? "wrapped";
+
+// src/enumerations.ts
+function normalizeInput(input) {
+  if (Array.isArray(input)) {
+    return Object.fromEntries(
+      input.map((k) => [k, {}])
+    );
+  }
+  return input;
+}
+var finalizeEnumItem = (item, enumType, enumInstanceId, serializeAs) => {
+  Object.defineProperty(item, SMART_ENUM_ITEM, {
+    value: true,
+    enumerable: false
+  });
+  Object.defineProperty(item, SMART_ENUM_ID, {
+    value: enumInstanceId,
+    enumerable: false
+  });
+  Object.defineProperty(item, "__smart_enum_brand", {
+    value: true,
+    enumerable: false
+  });
+  Object.defineProperty(item, "__smart_enum_type", {
+    value: enumType,
+    enumerable: false
+  });
+  Object.defineProperty(item, "toJSON", {
+    value: () => {
+      const mode = resolveSerializationMode(serializeAs);
+      if (mode === "value") {
+        return item.value;
+      }
+      return { __smart_enum_type: enumType, value: item.value };
+    },
+    enumerable: false
+  });
+  Object.defineProperty(item, "toPostgres", {
+    value: () => item.value,
+    enumerable: false
+  });
+  Object.defineProperty(item, "equals", {
+    value: (other) => enumItemsEqual(item, other),
+    enumerable: false
+  });
+  return item;
+};
+var formatProperties = (k, formatters) => formatters.reduce(
+  (acc, formatter) => {
+    acc[formatter.key] = formatter.format(k);
+    return acc;
+  },
+  {
+    value: constantCase(k),
+    display: capitalCase(k)
+  }
+);
+function buildEnumFromObject(enumType, input, propertyAutoFormatters, serializeAs) {
+  const formattersWithDefaults = [
+    { key: "value", format: constantCase },
+    { key: "display", format: capitalCase },
+    ...propertyAutoFormatters ?? []
+  ];
+  const rawEnumItems = {};
+  const enumInstanceId = Symbol("smart-enum-instance");
+  let index = 0;
+  for (const key in input) {
+    if (Object.prototype.hasOwnProperty.call(input, key)) {
+      const typedKey = key;
+      const value = input[typedKey];
+      const enumItemBase = {
+        index,
+        key: typedKey,
+        ...formatProperties(typedKey, formattersWithDefaults),
+        ...value
+      };
+      const enumItem = finalizeEnumItem(
+        enumItemBase,
+        enumType,
+        enumInstanceId,
+        serializeAs
+      );
+      Object.freeze(enumItem);
+      rawEnumItems[typedKey] = enumItem;
+      index++;
+    }
+  }
+  const extensionMethods = addExtensionMethods(
+    Object.values(rawEnumItems)
+  );
+  const enumObject = {
+    ...rawEnumItems,
+    ...extensionMethods
+  };
+  Object.defineProperty(enumObject, SMART_ENUM, {
+    value: true,
+    enumerable: false
+  });
+  Object.freeze(enumObject);
+  return enumObject;
+}
+function enumeration(enumType, props) {
+  const normalized = normalizeInput(props.input);
+  return buildEnumFromObject(
+    enumType,
+    normalized,
+    props.propertyAutoFormatters,
+    props.serializeAs
+  );
+}
+
+// src/utilities/logger.ts
+var consoleLogger = {
+  debug(message, ...args) {
+    console.debug(`[@reharik/smart-enum:debug] ${message}`, ...args);
+  },
+  info(message, ...args) {
+    console.info(`[@reharik/smart-enum:info] ${message}`, ...args);
+  },
+  warn(message, ...args) {
+    console.warn(`[@reharik/smart-enum:warn] ${message}`, ...args);
+  },
+  error(message, ...args) {
+    console.error(`[@reharik/smart-enum:error] ${message}`, ...args);
+  }
+};
+var globalLogger = consoleLogger;
+function setLogger(logger) {
+  globalLogger = logger;
+}
+function getLogger() {
+  return globalLogger;
+}
+function debug(message, ...args) {
+  globalLogger.debug(message, ...args);
+}
+function info(message, ...args) {
+  globalLogger.info(message, ...args);
+}
+
+// src/utilities/transformation.ts
+var isPlainObject = (x) => typeof x === "object" && x !== null && Object.getPrototypeOf(x) === Object.prototype;
+function serializeSmartEnums(input) {
+  const seen = /* @__PURE__ */ new WeakMap();
+  const walk = (v) => {
+    if (isSmartEnumItem(v)) {
+      return {
+        __smart_enum_type: v.__smart_enum_type,
+        value: v.value
+      };
+    }
+    if (typeof v === "object" && v !== null && seen.has(v)) {
+      return seen.get(v);
+    }
+    if (Array.isArray(v)) {
+      const arr = [];
+      seen.set(v, arr);
+      for (const item of v) {
+        arr.push(walk(item));
+      }
+      return arr;
+    }
+    if (isPlainObject(v)) {
+      const out = {};
+      seen.set(v, out);
+      for (const [k, val] of Object.entries(v)) {
+        out[k] = walk(val);
+      }
+      return out;
+    }
+    return v;
+  };
+  return walk(input);
+}
+function reviveSmartEnums(input, registry) {
+  const seen = /* @__PURE__ */ new WeakMap();
+  const walk = (v) => {
+    if (isSerializedSmartEnumItem(v)) {
+      debug(`Found serialized smartEnum: ${v.__smart_enum_type}`);
+      const enumInstance = registry[v.__smart_enum_type];
+      if (enumInstance) {
+        debug(`Found enumInstance in registry: ${v.__smart_enum_type}`);
+        const enumItem = enumInstance.tryFromValue(v.value);
+        if (enumItem) {
+          debug(`Revived enumItem using value: ${v.value}`);
+          return enumItem;
+        }
+        const key = v.value.toLowerCase();
+        const enumItemFromKey = enumInstance.tryFromKey(key);
+        if (enumItemFromKey) {
+          debug(`Revived enumItem using key: ${key}`);
+          return enumItemFromKey;
+        }
+      }
+      return v;
+    }
+    if (typeof v === "object" && v !== null && seen.has(v)) {
+      return seen.get(v);
+    }
+    if (Array.isArray(v)) {
+      const arr = [];
+      seen.set(v, arr);
+      for (const item of v) arr.push(walk(item));
+      return arr;
+    }
+    if (isPlainObject(v)) {
+      const out = {};
+      seen.set(v, out);
+      for (const [k, val] of Object.entries(v)) {
+        out[k] = walk(val);
+      }
+      return out;
+    }
+    return v;
+  };
+  return walk(input);
+}
+var reviveEnumField = (value, smartEnum, strict = false) => {
+  if (typeof value !== "string") return void 0;
+  const revived = smartEnum.tryFromValue(value);
+  if (revived !== void 0) return revived;
+  if (strict) {
+    throw new Error(`Unknown enum value: ${JSON.stringify(value)}`);
+  }
+  return void 0;
+};
+
+// src/utilities/transport/transportRegistry.ts
+var createLevelFilteredLogger = (logger, level) => {
+  const levels = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3
+  };
+  const currentLevel = levels[level];
+  return {
+    debug: (message, ...args) => {
+      if (currentLevel <= levels.debug) {
+        logger.debug(message, ...args);
+      }
+    },
+    info: (message, ...args) => {
+      if (currentLevel <= levels.info) {
+        logger.info(message, ...args);
+      }
+    },
+    warn: (message, ...args) => {
+      if (currentLevel <= levels.warn) {
+        logger.warn(message, ...args);
+      }
+    },
+    error: (message, ...args) => {
+      if (currentLevel <= levels.error) {
+        logger.error(message, ...args);
+      }
+    }
+  };
+};
+var globalEnumRegistry;
+var initializeSmartEnumMappings = (config) => {
+  globalEnumRegistry = config.enumRegistry;
+  const logLevel = config.logLevel ?? "error";
+  const logger = config.logger ?? getLogger();
+  setLogger(createLevelFilteredLogger(logger, logLevel));
+  info("Initialized smart enum mappings", {
+    enumCount: Object.keys(config.enumRegistry).length,
+    enumTypes: Object.keys(config.enumRegistry),
+    logLevel
+  });
+};
+var getGlobalEnumRegistry = () => globalEnumRegistry;
+
+// src/utilities/transport/reviveAfterTransport.ts
+var reviveAfterTransport = (payload) => {
+  const registry = getGlobalEnumRegistry();
+  if (!registry) {
+    return payload;
+  }
+  return reviveSmartEnums(payload, registry);
+};
+
+// src/utilities/transport/serializeForTransport.ts
+var serializeForTransport = (payload) => serializeSmartEnums(payload);
+
+// src/db/prepareForDatabase.ts
+var isPlainObject2 = (x) => typeof x === "object" && x !== null && Object.getPrototypeOf(x) === Object.prototype;
+var prepareForDatabase = (payload) => {
+  const seen = /* @__PURE__ */ new WeakMap();
+  const walk = (v) => {
+    if (isSmartEnumItem(v)) {
+      return v.value;
+    }
+    if (typeof v === "object" && v !== null && seen.has(v)) {
+      return seen.get(v);
+    }
+    if (Array.isArray(v)) {
+      const arr = [];
+      seen.set(v, arr);
+      for (const item of v) {
+        arr.push(walk(item));
+      }
+      return arr;
+    }
+    if (isPlainObject2(v)) {
+      const out = {};
+      seen.set(v, out);
+      for (const [k, val] of Object.entries(v)) {
+        out[k] = walk(val);
+      }
+      return out;
+    }
+    return v;
+  };
+  return walk(payload);
+};
+
+// src/db/enumRevivalError.ts
+var EnumRevivalError = class extends Error {
+  constructor(message, path, value) {
+    super(message);
+    this.path = path;
+    this.value = value;
+    this.name = "EnumRevivalError";
+  }
+};
+
+// src/db/reviveRowFromDatabase.ts
+var reviveRowFromDatabase = (row, options) => {
+  const { fieldEnumMapping, strict = false } = options;
+  const out = { ...row };
+  for (const [field, smartEnum] of Object.entries(fieldEnumMapping)) {
+    if (!Object.hasOwn(out, field)) {
+      continue;
+    }
+    const raw = out[field];
+    if (typeof raw === "string") {
+      const revived = smartEnum.tryFromValue(raw);
+      if (revived !== void 0) {
+        out[field] = revived;
+      } else if (strict) {
+        throw new EnumRevivalError(
+          `Cannot revive field ${JSON.stringify(field)}: unknown enum value ${JSON.stringify(raw)}`,
+          field,
+          raw
+        );
+      }
+      continue;
+    }
+    if (Array.isArray(raw)) {
+      const revivedItems = [];
+      for (const item of raw) {
+        if (typeof item !== "string") {
+          revivedItems.push(item);
+          continue;
+        }
+        const revived = smartEnum.tryFromValue(item);
+        if (revived !== void 0) {
+          revivedItems.push(revived);
+        } else if (strict) {
+          throw new EnumRevivalError(
+            `Cannot revive field ${JSON.stringify(field)}: unknown enum value ${JSON.stringify(item)} in array`,
+            field,
+            item
+          );
+        } else {
+          revivedItems.push(item);
+        }
+      }
+      out[field] = revivedItems;
+      continue;
+    }
+  }
+  return out;
+};
+
+// src/db/revivePayloadFromDatabase.ts
+var isObjectRecord = (x) => typeof x === "object" && x !== null && !Array.isArray(x);
+var parsePath = (pathStr) => {
+  const tokens = pathStr.split(".").filter(Boolean);
+  const segs = [];
+  for (const token of tokens) {
+    if (token.endsWith("[]")) {
+      const name = token.slice(0, -2);
+      if (name.length === 0) {
+        throw new Error(
+          `Invalid enum revival path "${pathStr}": empty key before []`
+        );
+      }
+      segs.push({ type: "prop", name }, { type: "arrayEach" });
+    } else {
+      segs.push({ type: "prop", name: token });
+    }
+  }
+  const last = segs.at(-1);
+  if (!last || last.type !== "prop") {
+    throw new Error(
+      `Invalid enum revival path "${pathStr}": must end with a property name (not [])`
+    );
+  }
+  return segs;
+};
+var reviveLeaf = (host, key, smartEnum, strict, pathLabel) => {
+  const raw = host[key];
+  if (typeof raw === "string") {
+    const revived = smartEnum.tryFromValue(raw);
+    if (revived !== void 0) {
+      host[key] = revived;
+    } else if (strict) {
+      throw new EnumRevivalError(
+        `Cannot revive path "${pathLabel}": unknown enum value ${JSON.stringify(raw)}`,
+        pathLabel,
+        raw
+      );
+    }
+    return;
+  }
+  if (Array.isArray(raw)) {
+    const revivedItems = [];
+    for (const item of raw) {
+      if (typeof item !== "string") {
+        revivedItems.push(item);
+        continue;
+      }
+      const revived = smartEnum.tryFromValue(item);
+      if (revived !== void 0) {
+        revivedItems.push(revived);
+      } else if (strict) {
+        throw new EnumRevivalError(
+          `Cannot revive path "${pathLabel}": unknown enum value ${JSON.stringify(item)} in array`,
+          pathLabel,
+          item
+        );
+      } else {
+        revivedItems.push(item);
+      }
+    }
+    host[key] = revivedItems;
+    return;
+  }
+};
+var walkPath = (value, segs, segIndex, smartEnum, strict, pathLabel) => {
+  const seg = segs[segIndex];
+  if (seg === void 0) {
+    return;
+  }
+  const isLast = segIndex === segs.length - 1;
+  if (isLast) {
+    if (seg.type !== "prop") {
+      return;
+    }
+    if (!isObjectRecord(value)) {
+      if (strict) {
+        throw new EnumRevivalError(
+          `Cannot revive path "${pathLabel}": expected object at parent of "${seg.name}"`,
+          pathLabel,
+          value
+        );
+      }
+      return;
+    }
+    reviveLeaf(value, seg.name, smartEnum, strict, pathLabel);
+    return;
+  }
+  if (seg.type === "prop") {
+    if (!isObjectRecord(value)) {
+      if (strict) {
+        throw new EnumRevivalError(
+          `Cannot revive path "${pathLabel}": expected object at "${seg.name}"`,
+          pathLabel,
+          value
+        );
+      }
+      return;
+    }
+    walkPath(value[seg.name], segs, segIndex + 1, smartEnum, strict, pathLabel);
+    return;
+  }
+  if (seg.type === "arrayEach") {
+    if (!Array.isArray(value)) {
+      if (strict) {
+        throw new EnumRevivalError(
+          `Cannot revive path "${pathLabel}": expected array before nested path`,
+          pathLabel,
+          value
+        );
+      }
+      return;
+    }
+    for (const el of value) {
+      walkPath(el, segs, segIndex + 1, smartEnum, strict, pathLabel);
+    }
+  }
+};
+var revivePayloadFromDatabase = (payload, options) => {
+  const { pathEnumMapping, strict = false } = options;
+  const root = structuredClone(payload);
+  for (const [pathStr, smartEnum] of Object.entries(pathEnumMapping)) {
+    const segs = parsePath(pathStr);
+    walkPath(root, segs, 0, smartEnum, strict, pathStr);
+  }
+  return root;
+};
 export {
   EnumRevivalError,
   enumeration,