@reharik/smart-enum 0.2.0 → 0.3.1

package/dist/index.d.cts

@@ -1,3 +1,4 @@
-export { A as AnyEnumLike, D as DatabaseFormat, h as EnumLikeBase, E as Enumeration, F as FieldEnumMapping, c as LogLevel, L as Logger, P as PathEnumMapping, l as RevivePayloadOptions, k as ReviveRowOptions, R as RevivedSmartEnums, f as SerializedSmartEnums, S as SmartApiHelperConfig, g as SmartEnumItemSerialized, j as SmartEnumLike, d as SmartEnumMappingsConfig, n as StandardEnumItem, m as StandardEnumItemBase, e as enumeration, a as isSmartEnum, i as isSmartEnumItem, b as reviveEnumField, r as reviveSmartEnums, s as serializeSmartEnums } from './core-DU5cpej6.cjs';
+export { A as AnyEnumLike, D as DatabaseFormat, h as EnumLikeBase, E as Enumeration, F as FieldEnumMapping, c as LogLevel, L as Logger, P as PathEnumMapping, l as RevivePayloadOptions, k as ReviveRowOptions, R as RevivedSmartEnums, f as SerializedSmartEnums, S as SmartApiHelperConfig, g as SmartEnumItemSerialized, j as SmartEnumLike, d as SmartEnumMappingsConfig, n as StandardEnumItem, m as StandardEnumItemBase, e as enumeration, a as isSmartEnum, i as isSmartEnumItem, b as reviveEnumField, r as reviveSmartEnums, s as serializeSmartEnums } from './transformation-BPyoxZyV.cjs';
+export { getSubsetByProp, subsetByProp } from './core.cjs';
 export { getGlobalEnumRegistry, initializeSmartEnumMappings, reviveAfterTransport, serializeForTransport } from './transport.cjs';
 export { EnumRevivalError, prepareForDatabase, revivePayloadFromDatabase, reviveRowFromDatabase } from './database.cjs';

package/dist/index.d.ts

@@ -1,3 +1,4 @@
-export { A as AnyEnumLike, D as DatabaseFormat, h as EnumLikeBase, E as Enumeration, F as FieldEnumMapping, c as LogLevel, L as Logger, P as PathEnumMapping, l as RevivePayloadOptions, k as ReviveRowOptions, R as RevivedSmartEnums, f as SerializedSmartEnums, S as SmartApiHelperConfig, g as SmartEnumItemSerialized, j as SmartEnumLike, d as SmartEnumMappingsConfig, n as StandardEnumItem, m as StandardEnumItemBase, e as enumeration, a as isSmartEnum, i as isSmartEnumItem, b as reviveEnumField, r as reviveSmartEnums, s as serializeSmartEnums } from './core-DU5cpej6.js';
+export { A as AnyEnumLike, D as DatabaseFormat, h as EnumLikeBase, E as Enumeration, F as FieldEnumMapping, c as LogLevel, L as Logger, P as PathEnumMapping, l as RevivePayloadOptions, k as ReviveRowOptions, R as RevivedSmartEnums, f as SerializedSmartEnums, S as SmartApiHelperConfig, g as SmartEnumItemSerialized, j as SmartEnumLike, d as SmartEnumMappingsConfig, n as StandardEnumItem, m as StandardEnumItemBase, e as enumeration, a as isSmartEnum, i as isSmartEnumItem, b as reviveEnumField, r as reviveSmartEnums, s as serializeSmartEnums } from './transformation-BPyoxZyV.js';
+export { getSubsetByProp, subsetByProp } from './core.js';
 export { getGlobalEnumRegistry, initializeSmartEnumMappings, reviveAfterTransport, serializeForTransport } from './transport.js';
 export { EnumRevivalError, prepareForDatabase, revivePayloadFromDatabase, reviveRowFromDatabase } from './database.js';

package/dist/index.js

@@ -1,15 +1,19 @@
+import {
+  getSubsetByProp,
+  subsetByProp
+} from "./chunk-YEU2HCVA.js";
 import {
   EnumRevivalError,
   prepareForDatabase,
   revivePayloadFromDatabase,
   reviveRowFromDatabase
-} from "./chunk-XG7XL4T7.js";
+} from "./chunk-3N6NMQCD.js";
 import {
   getGlobalEnumRegistry,
   initializeSmartEnumMappings,
   reviveAfterTransport,
   serializeForTransport
-} from "./chunk-YWKBI354.js";
+} from "./chunk-RO2L7N2F.js";
 import {
   enumeration,
   isSmartEnum,
@@ -17,11 +21,12 @@ import {
   reviveEnumField,
   reviveSmartEnums,
   serializeSmartEnums
-} from "./chunk-PKREHKGD.js";
+} from "./chunk-PUK5FOIE.js";
 export {
   EnumRevivalError,
   enumeration,
   getGlobalEnumRegistry,
+  getSubsetByProp,
   initializeSmartEnumMappings,
   isSmartEnum,
   isSmartEnumItem,
@@ -32,6 +37,7 @@ export {
   reviveRowFromDatabase,
   reviveSmartEnums,
   serializeForTransport,
-  serializeSmartEnums
+  serializeSmartEnums,
+  subsetByProp
 };
 //# sourceMappingURL=index.js.map

package/dist/{core-DU5cpej6.d.cts → transformation-BPyoxZyV.d.cts}

@@ -63,6 +63,7 @@ type SmartEnumMappingsConfig = {
     logLevel?: LogLevel;
     logger?: Logger;
 };
+type BuiltInOverrideKeys = 'key' | 'value' | 'display' | 'deprecated' | 'index' | '__smart_enum_brand' | '__smart_enum_type';
 /**
  * Structural fields shared by every enum member (key, value, display, index, optional deprecated).
  * Does not include smart-enum branding or database helpers; see {@link StandardEnumItem}.
@@ -83,45 +84,12 @@ type StandardEnumItem = StandardEnumItemBase & {
     readonly __smart_enum_type: string;
     readonly toPostgres: () => string;
 };
-/**
- * Structural shape of a smart-style enum object: lookup by value/key, list items/values/keys,
- * plus an index signature so registry and mapping types can treat instances as records.
- * Use {@link SmartEnumLike} when items are full {@link StandardEnumItem}s (the usual case).
- */
-type EnumLikeBase<TItem extends StandardEnumItemBase = StandardEnumItemBase> = {
-    fromValue(value: string): TItem;
-    tryFromValue(value?: string | null): TItem | undefined;
-    fromKey(key: string): TItem;
-    tryFromKey(key?: string | null): TItem | undefined;
-    items(): readonly TItem[];
-    values(): readonly TItem['value'][];
-    keys(): readonly TItem['key'][];
-} & Record<string, unknown>;
-/**
- * A {@link EnumLikeBase} whose items are branded {@link StandardEnumItem}s (typical `enumeration()` result).
- */
-type SmartEnumLike<TItem extends StandardEnumItem = StandardEnumItem> = EnumLikeBase<TItem>;
-type FieldEnumMapping = Record<string, SmartEnumLike>;
-type ReviveRowOptions = {
-    fieldEnumMapping: FieldEnumMapping;
-    strict?: boolean;
-};
-type PathEnumMapping = Record<string, SmartEnumLike>;
-type RevivePayloadOptions = {
-    pathEnumMapping: PathEnumMapping;
-    strict?: boolean;
-};
-type Enumeration<TEnum> = TEnum extends Record<string, infer V> ? V extends {
-    __smart_enum_brand: true;
-} ? V : never : never;
-
-type BuiltInOverrideKeys = 'key' | 'value' | 'display' | 'deprecated' | 'index' | '__smart_enum_brand' | '__smart_enum_type';
 type EnumInputItem = Partial<{
     key: string;
     value: string;
     display: string;
     deprecated: boolean;
-}> & object;
+}> & Record<string, unknown>;
 type ObjectEnumInput = Record<string, EnumInputItem>;
 type EmptyEnumInputItem = Record<never, never>;
 type Separator = '-' | '_' | ' ' | '.';
@@ -132,49 +100,107 @@ type TrimUnderscore<S extends string> = S extends `_${infer R}` ? TrimUnderscore
 type CollapseUnderscores<S extends string> = S extends `${infer A}__${infer B}` ? CollapseUnderscores<`${A}_${B}`> : S;
 type ConstantCaseInternal<S extends string, Prev extends string = '', Out extends string = ''> = S extends `${infer C}${infer Rest}` ? C extends Separator ? ConstantCaseInternal<Rest, C, PushUnderscore<Out>> : IsUpperChar<C> extends true ? IsLowerChar<Prev> extends true ? ConstantCaseInternal<Rest, C, `${PushUnderscore<Out>}${Uppercase<C>}`> : ConstantCaseInternal<Rest, C, `${Out}${Uppercase<C>}`> : ConstantCaseInternal<Rest, C, `${Out}${Uppercase<C>}`> : CollapseUnderscores<TrimUnderscore<Out>>;
 type ConstantCase<S extends string> = string extends S ? string : ConstantCaseInternal<S>;
+/** Segments of a `ConstantCase` string (underscore-separated ALL CAPS words). */
+type SplitConstantCaseSegments<S extends string> = S extends `${infer A}_${infer B}` ? [A, ...SplitConstantCaseSegments<B>] : [S];
+/** First character upper, remainder lower (for ALL-CAPS words from `ConstantCase`). */
+type TitleCaseAllCapsWord<W extends string> = W extends '' ? '' : W extends `${infer F}${infer R}` ? `${Uppercase<F>}${Lowercase<R>}` : W;
+type JoinDisplaySegments<T extends readonly string[]> = T extends readonly [
+    infer A extends string,
+    ...infer Rest extends readonly string[]
+] ? Rest extends readonly [] ? TitleCaseAllCapsWord<A> : `${TitleCaseAllCapsWord<A>} ${JoinDisplaySegments<Rest>}` : '';
+/**
+ * Display string derived from the enum member key: `ConstantCase` → split → title-case words → join with spaces.
+ * Matches default runtime `capitalCase(key)` for typical PascalCase / camelCase keys. Member keys that already
+ * contain separators may differ from `capitalCase` at runtime; custom `propertyAutoFormatters` for `display`
+ * are not reflected in this type.
+ */
+type DisplayCaseFromEnumKey<K extends string> = string extends K ? string : JoinDisplaySegments<SplitConstantCaseSegments<ConstantCase<K>>>;
 type ArrayToObjectType<T extends readonly string[]> = {
     [K in T[number]]: EmptyEnumInputItem & {
         readonly value?: ConstantCase<K>;
     };
 };
 type NormalizedInputType<TInput> = TInput extends readonly string[] ? ArrayToObjectType<TInput> : TInput extends ObjectEnumInput ? TInput : never;
-type UnionKeys<T> = T extends T ? keyof T : never;
-type MergeUnionToObject<T> = {
-    [K in UnionKeys<T>]: T extends Record<K, infer V> ? V : undefined;
-};
-type ExtraShapeUnion<TObj extends ObjectEnumInput> = {
-    [K in keyof TObj]: Omit<TObj[K], BuiltInOverrideKeys>;
-}[keyof TObj];
-type InferredExtraFields<TObj extends ObjectEnumInput> = MergeUnionToObject<ExtraShapeUnion<TObj>>;
-type EnumItemFromNormalizedObject<TObj extends ObjectEnumInput, K extends keyof TObj = keyof TObj> = Omit<StandardEnumItem, 'key' | 'value'> & InferredExtraFields<TObj> & {
+/** Input-derived fields for one member key (excludes built-ins filled by `enumeration()`). */
+type EnumMemberExtra<TObj extends ObjectEnumInput, K extends keyof TObj> = Omit<TObj[K], BuiltInOverrideKeys>;
+type EnumItemFromNormalizedObject<TObj extends ObjectEnumInput, K extends keyof TObj = keyof TObj> = Omit<StandardEnumItem, 'key' | 'value' | 'display'> & EnumMemberExtra<TObj, K> & {
     readonly key: Extract<K, string>;
     readonly value: TObj[K] extends {
         value?: infer V;
-    } ? Extract<V, string> extends never ? string : Extract<V, string> : string;
+    } ? [Extract<V, string>] extends [never] ? ConstantCase<Extract<K, string>> : Extract<V, string> : ConstantCase<Extract<K, string>>;
+    readonly display: TObj[K] extends {
+        display?: infer D;
+    } ? [Extract<D, string>] extends [never] ? DisplayCaseFromEnumKey<Extract<K, string>> : Extract<D, string> : DisplayCaseFromEnumKey<Extract<K, string>>;
 };
 type EnumMemberUnionFromNormalizedObject<TObj extends ObjectEnumInput> = {
     [K in keyof TObj]: EnumItemFromNormalizedObject<TObj, K>;
 }[keyof TObj];
+type EnumFromNormalizedObject<TObj extends ObjectEnumInput> = {
+    [K in keyof TObj]: EnumItemFromNormalizedObject<TObj, K>;
+} & CoreEnumMethods<EnumMemberUnionFromNormalizedObject<TObj>>;
+type PropertyAutoFormatter = {
+    /** The property name to generate */
+    key: string;
+    /** Function to transform the key into the property value */
+    format: (k: string) => string;
+};
 type CoreEnumMethods<TItem extends StandardEnumItem> = {
     fromValue(value: string): TItem;
     tryFromValue(value?: string | null): TItem | undefined;
     fromKey(key: string): TItem;
     tryFromKey(key?: string | null): TItem | undefined;
     items(): readonly TItem[];
-    values(): readonly string[];
-    keys(): readonly string[];
+    /** Matches runtime: `items.map(i => i.value)` (see {@link EnumLikeBase}). */
+    values(): readonly TItem['value'][];
+    /** Matches runtime: `items.map(i => i.key)` (see {@link EnumLikeBase}). */
+    keys(): readonly TItem['key'][];
+};
+/**
+ * Structural shape of a smart-style enum object: lookup by value/key, list items/values/keys,
+ * plus an index signature so registry and mapping types can treat instances as records.
+ * Use {@link SmartEnumLike} when items are full {@link StandardEnumItem}s (the usual case).
+ */
+type EnumLikeBase<TItem extends StandardEnumItemBase = StandardEnumItemBase> = {
+    fromValue(value: string): TItem;
+    tryFromValue(value?: string | null): TItem | undefined;
+    fromKey(key: string): TItem;
+    tryFromKey(key?: string | null): TItem | undefined;
+    items(): readonly TItem[];
+    values(): readonly TItem['value'][];
+    keys(): readonly TItem['key'][];
+} & Record<string, unknown>;
+/**
+ * A {@link EnumLikeBase} whose items are branded {@link StandardEnumItem}s (typical `enumeration()` result).
+ */
+type SmartEnumLike<TItem extends StandardEnumItem = StandardEnumItem> = EnumLikeBase<TItem>;
+/** Union of branded enum member values on an enum object `T`. */
+type SmartEnumMemberUnion<T extends Record<string, unknown>> = {
+    [K in keyof T]: T[K] extends StandardEnumItem ? T[K] : never;
+}[keyof T];
+/** Keys on `TEnum` whose member matches `Record<P, V>` within `ItemUnion`. */
+type SmartEnumSubsetKeys<TEnum extends Record<string, unknown>, ItemUnion extends StandardEnumItem, P extends keyof ItemUnion & string, V extends ItemUnion[P]> = {
+    [K in keyof TEnum]: TEnum[K] extends Extract<ItemUnion, Record<P, V>> ? K : never;
+}[keyof TEnum];
+type SmartEnumSubsetItemUnion<ItemUnion extends StandardEnumItem, P extends keyof ItemUnion & string, V extends ItemUnion[P]> = Extract<ItemUnion, Record<P, V>>;
+type SmartEnumSubsetView<TEnum extends Record<string, unknown>, ItemUnion extends StandardEnumItem, P extends keyof ItemUnion & string, V extends ItemUnion[P]> = Pick<TEnum, SmartEnumSubsetKeys<TEnum, ItemUnion, P, V>> & CoreEnumMethods<SmartEnumSubsetItemUnion<ItemUnion, P, V>>;
+type FieldEnumMapping = Record<string, SmartEnumLike>;
+type ReviveRowOptions = {
+    fieldEnumMapping: FieldEnumMapping;
+    strict?: boolean;
+};
+type PathEnumMapping = Record<string, SmartEnumLike>;
+type RevivePayloadOptions = {
+    pathEnumMapping: PathEnumMapping;
+    strict?: boolean;
 };
-type EnumFromNormalizedObject<TObj extends ObjectEnumInput> = {
-    [K in keyof TObj]: EnumItemFromNormalizedObject<TObj, K>;
-} & CoreEnumMethods<EnumMemberUnionFromNormalizedObject<TObj>>;
 type EnumerationProps<TInput> = {
     input: TInput;
     propertyAutoFormatters?: PropertyAutoFormatter[];
 };
-type PropertyAutoFormatter = {
-    key: string;
-    format: (k: string) => string;
-};
+type Enumeration<TEnum> = TEnum extends Record<string, infer V> ? V extends {
+    __smart_enum_brand: true;
+} ? V : never : never;
+
 declare function enumeration<const TArr extends readonly string[]>(enumType: string, props: EnumerationProps<TArr>): EnumFromNormalizedObject<NormalizedInputType<TArr>>;
 declare function enumeration<const TObj extends ObjectEnumInput>(enumType: string, props: EnumerationProps<TObj>): EnumFromNormalizedObject<NormalizedInputType<TObj>>;
 
@@ -266,4 +292,4 @@ declare function reviveSmartEnums<R>(input: unknown, registry: Record<string, An
  */
 declare const reviveEnumField: <TItem>(value: unknown, smartEnum: AnyEnumLike<TItem>, strict?: boolean) => TItem | undefined;
 
-export { type AnyEnumLike as A, type DatabaseFormat as D, type Enumeration as E, type FieldEnumMapping as F, type Logger as L, type PathEnumMapping as P, type RevivedSmartEnums as R, type SmartApiHelperConfig as S, isSmartEnum as a, reviveEnumField as b, type LogLevel as c, type SmartEnumMappingsConfig as d, enumeration as e, type SerializedSmartEnums as f, type SmartEnumItemSerialized as g, type EnumLikeBase as h, isSmartEnumItem as i, type SmartEnumLike as j, type ReviveRowOptions as k, type RevivePayloadOptions as l, type StandardEnumItemBase as m, type StandardEnumItem as n, reviveSmartEnums as r, serializeSmartEnums as s };
+export { type AnyEnumLike as A, type DatabaseFormat as D, type Enumeration as E, type FieldEnumMapping as F, type Logger as L, type PathEnumMapping as P, type RevivedSmartEnums as R, type SmartApiHelperConfig as S, isSmartEnum as a, reviveEnumField as b, type LogLevel as c, type SmartEnumMappingsConfig as d, enumeration as e, type SerializedSmartEnums as f, type SmartEnumItemSerialized as g, type EnumLikeBase as h, isSmartEnumItem as i, type SmartEnumLike as j, type ReviveRowOptions as k, type RevivePayloadOptions as l, type StandardEnumItemBase as m, type StandardEnumItem as n, type SmartEnumMemberUnion as o, type SmartEnumSubsetView as p, reviveSmartEnums as r, serializeSmartEnums as s };

package/dist/{core-DU5cpej6.d.ts → transformation-BPyoxZyV.d.ts}

@@ -63,6 +63,7 @@ type SmartEnumMappingsConfig = {
     logLevel?: LogLevel;
     logger?: Logger;
 };
+type BuiltInOverrideKeys = 'key' | 'value' | 'display' | 'deprecated' | 'index' | '__smart_enum_brand' | '__smart_enum_type';
 /**
  * Structural fields shared by every enum member (key, value, display, index, optional deprecated).
  * Does not include smart-enum branding or database helpers; see {@link StandardEnumItem}.
@@ -83,45 +84,12 @@ type StandardEnumItem = StandardEnumItemBase & {
     readonly __smart_enum_type: string;
     readonly toPostgres: () => string;
 };
-/**
- * Structural shape of a smart-style enum object: lookup by value/key, list items/values/keys,
- * plus an index signature so registry and mapping types can treat instances as records.
- * Use {@link SmartEnumLike} when items are full {@link StandardEnumItem}s (the usual case).
- */
-type EnumLikeBase<TItem extends StandardEnumItemBase = StandardEnumItemBase> = {
-    fromValue(value: string): TItem;
-    tryFromValue(value?: string | null): TItem | undefined;
-    fromKey(key: string): TItem;
-    tryFromKey(key?: string | null): TItem | undefined;
-    items(): readonly TItem[];
-    values(): readonly TItem['value'][];
-    keys(): readonly TItem['key'][];
-} & Record<string, unknown>;
-/**
- * A {@link EnumLikeBase} whose items are branded {@link StandardEnumItem}s (typical `enumeration()` result).
- */
-type SmartEnumLike<TItem extends StandardEnumItem = StandardEnumItem> = EnumLikeBase<TItem>;
-type FieldEnumMapping = Record<string, SmartEnumLike>;
-type ReviveRowOptions = {
-    fieldEnumMapping: FieldEnumMapping;
-    strict?: boolean;
-};
-type PathEnumMapping = Record<string, SmartEnumLike>;
-type RevivePayloadOptions = {
-    pathEnumMapping: PathEnumMapping;
-    strict?: boolean;
-};
-type Enumeration<TEnum> = TEnum extends Record<string, infer V> ? V extends {
-    __smart_enum_brand: true;
-} ? V : never : never;
-
-type BuiltInOverrideKeys = 'key' | 'value' | 'display' | 'deprecated' | 'index' | '__smart_enum_brand' | '__smart_enum_type';
 type EnumInputItem = Partial<{
     key: string;
     value: string;
     display: string;
     deprecated: boolean;
-}> & object;
+}> & Record<string, unknown>;
 type ObjectEnumInput = Record<string, EnumInputItem>;
 type EmptyEnumInputItem = Record<never, never>;
 type Separator = '-' | '_' | ' ' | '.';
@@ -132,49 +100,107 @@ type TrimUnderscore<S extends string> = S extends `_${infer R}` ? TrimUnderscore
 type CollapseUnderscores<S extends string> = S extends `${infer A}__${infer B}` ? CollapseUnderscores<`${A}_${B}`> : S;
 type ConstantCaseInternal<S extends string, Prev extends string = '', Out extends string = ''> = S extends `${infer C}${infer Rest}` ? C extends Separator ? ConstantCaseInternal<Rest, C, PushUnderscore<Out>> : IsUpperChar<C> extends true ? IsLowerChar<Prev> extends true ? ConstantCaseInternal<Rest, C, `${PushUnderscore<Out>}${Uppercase<C>}`> : ConstantCaseInternal<Rest, C, `${Out}${Uppercase<C>}`> : ConstantCaseInternal<Rest, C, `${Out}${Uppercase<C>}`> : CollapseUnderscores<TrimUnderscore<Out>>;
 type ConstantCase<S extends string> = string extends S ? string : ConstantCaseInternal<S>;
+/** Segments of a `ConstantCase` string (underscore-separated ALL CAPS words). */
+type SplitConstantCaseSegments<S extends string> = S extends `${infer A}_${infer B}` ? [A, ...SplitConstantCaseSegments<B>] : [S];
+/** First character upper, remainder lower (for ALL-CAPS words from `ConstantCase`). */
+type TitleCaseAllCapsWord<W extends string> = W extends '' ? '' : W extends `${infer F}${infer R}` ? `${Uppercase<F>}${Lowercase<R>}` : W;
+type JoinDisplaySegments<T extends readonly string[]> = T extends readonly [
+    infer A extends string,
+    ...infer Rest extends readonly string[]
+] ? Rest extends readonly [] ? TitleCaseAllCapsWord<A> : `${TitleCaseAllCapsWord<A>} ${JoinDisplaySegments<Rest>}` : '';
+/**
+ * Display string derived from the enum member key: `ConstantCase` → split → title-case words → join with spaces.
+ * Matches default runtime `capitalCase(key)` for typical PascalCase / camelCase keys. Member keys that already
+ * contain separators may differ from `capitalCase` at runtime; custom `propertyAutoFormatters` for `display`
+ * are not reflected in this type.
+ */
+type DisplayCaseFromEnumKey<K extends string> = string extends K ? string : JoinDisplaySegments<SplitConstantCaseSegments<ConstantCase<K>>>;
 type ArrayToObjectType<T extends readonly string[]> = {
     [K in T[number]]: EmptyEnumInputItem & {
         readonly value?: ConstantCase<K>;
     };
 };
 type NormalizedInputType<TInput> = TInput extends readonly string[] ? ArrayToObjectType<TInput> : TInput extends ObjectEnumInput ? TInput : never;
-type UnionKeys<T> = T extends T ? keyof T : never;
-type MergeUnionToObject<T> = {
-    [K in UnionKeys<T>]: T extends Record<K, infer V> ? V : undefined;
-};
-type ExtraShapeUnion<TObj extends ObjectEnumInput> = {
-    [K in keyof TObj]: Omit<TObj[K], BuiltInOverrideKeys>;
-}[keyof TObj];
-type InferredExtraFields<TObj extends ObjectEnumInput> = MergeUnionToObject<ExtraShapeUnion<TObj>>;
-type EnumItemFromNormalizedObject<TObj extends ObjectEnumInput, K extends keyof TObj = keyof TObj> = Omit<StandardEnumItem, 'key' | 'value'> & InferredExtraFields<TObj> & {
+/** Input-derived fields for one member key (excludes built-ins filled by `enumeration()`). */
+type EnumMemberExtra<TObj extends ObjectEnumInput, K extends keyof TObj> = Omit<TObj[K], BuiltInOverrideKeys>;
+type EnumItemFromNormalizedObject<TObj extends ObjectEnumInput, K extends keyof TObj = keyof TObj> = Omit<StandardEnumItem, 'key' | 'value' | 'display'> & EnumMemberExtra<TObj, K> & {
     readonly key: Extract<K, string>;
     readonly value: TObj[K] extends {
         value?: infer V;
-    } ? Extract<V, string> extends never ? string : Extract<V, string> : string;
+    } ? [Extract<V, string>] extends [never] ? ConstantCase<Extract<K, string>> : Extract<V, string> : ConstantCase<Extract<K, string>>;
+    readonly display: TObj[K] extends {
+        display?: infer D;
+    } ? [Extract<D, string>] extends [never] ? DisplayCaseFromEnumKey<Extract<K, string>> : Extract<D, string> : DisplayCaseFromEnumKey<Extract<K, string>>;
 };
 type EnumMemberUnionFromNormalizedObject<TObj extends ObjectEnumInput> = {
     [K in keyof TObj]: EnumItemFromNormalizedObject<TObj, K>;
 }[keyof TObj];
+type EnumFromNormalizedObject<TObj extends ObjectEnumInput> = {
+    [K in keyof TObj]: EnumItemFromNormalizedObject<TObj, K>;
+} & CoreEnumMethods<EnumMemberUnionFromNormalizedObject<TObj>>;
+type PropertyAutoFormatter = {
+    /** The property name to generate */
+    key: string;
+    /** Function to transform the key into the property value */
+    format: (k: string) => string;
+};
 type CoreEnumMethods<TItem extends StandardEnumItem> = {
     fromValue(value: string): TItem;
     tryFromValue(value?: string | null): TItem | undefined;
     fromKey(key: string): TItem;
     tryFromKey(key?: string | null): TItem | undefined;
     items(): readonly TItem[];
-    values(): readonly string[];
-    keys(): readonly string[];
+    /** Matches runtime: `items.map(i => i.value)` (see {@link EnumLikeBase}). */
+    values(): readonly TItem['value'][];
+    /** Matches runtime: `items.map(i => i.key)` (see {@link EnumLikeBase}). */
+    keys(): readonly TItem['key'][];
+};
+/**
+ * Structural shape of a smart-style enum object: lookup by value/key, list items/values/keys,
+ * plus an index signature so registry and mapping types can treat instances as records.
+ * Use {@link SmartEnumLike} when items are full {@link StandardEnumItem}s (the usual case).
+ */
+type EnumLikeBase<TItem extends StandardEnumItemBase = StandardEnumItemBase> = {
+    fromValue(value: string): TItem;
+    tryFromValue(value?: string | null): TItem | undefined;
+    fromKey(key: string): TItem;
+    tryFromKey(key?: string | null): TItem | undefined;
+    items(): readonly TItem[];
+    values(): readonly TItem['value'][];
+    keys(): readonly TItem['key'][];
+} & Record<string, unknown>;
+/**
+ * A {@link EnumLikeBase} whose items are branded {@link StandardEnumItem}s (typical `enumeration()` result).
+ */
+type SmartEnumLike<TItem extends StandardEnumItem = StandardEnumItem> = EnumLikeBase<TItem>;
+/** Union of branded enum member values on an enum object `T`. */
+type SmartEnumMemberUnion<T extends Record<string, unknown>> = {
+    [K in keyof T]: T[K] extends StandardEnumItem ? T[K] : never;
+}[keyof T];
+/** Keys on `TEnum` whose member matches `Record<P, V>` within `ItemUnion`. */
+type SmartEnumSubsetKeys<TEnum extends Record<string, unknown>, ItemUnion extends StandardEnumItem, P extends keyof ItemUnion & string, V extends ItemUnion[P]> = {
+    [K in keyof TEnum]: TEnum[K] extends Extract<ItemUnion, Record<P, V>> ? K : never;
+}[keyof TEnum];
+type SmartEnumSubsetItemUnion<ItemUnion extends StandardEnumItem, P extends keyof ItemUnion & string, V extends ItemUnion[P]> = Extract<ItemUnion, Record<P, V>>;
+type SmartEnumSubsetView<TEnum extends Record<string, unknown>, ItemUnion extends StandardEnumItem, P extends keyof ItemUnion & string, V extends ItemUnion[P]> = Pick<TEnum, SmartEnumSubsetKeys<TEnum, ItemUnion, P, V>> & CoreEnumMethods<SmartEnumSubsetItemUnion<ItemUnion, P, V>>;
+type FieldEnumMapping = Record<string, SmartEnumLike>;
+type ReviveRowOptions = {
+    fieldEnumMapping: FieldEnumMapping;
+    strict?: boolean;
+};
+type PathEnumMapping = Record<string, SmartEnumLike>;
+type RevivePayloadOptions = {
+    pathEnumMapping: PathEnumMapping;
+    strict?: boolean;
 };
-type EnumFromNormalizedObject<TObj extends ObjectEnumInput> = {
-    [K in keyof TObj]: EnumItemFromNormalizedObject<TObj, K>;
-} & CoreEnumMethods<EnumMemberUnionFromNormalizedObject<TObj>>;
 type EnumerationProps<TInput> = {
     input: TInput;
     propertyAutoFormatters?: PropertyAutoFormatter[];
 };
-type PropertyAutoFormatter = {
-    key: string;
-    format: (k: string) => string;
-};
+type Enumeration<TEnum> = TEnum extends Record<string, infer V> ? V extends {
+    __smart_enum_brand: true;
+} ? V : never : never;
+
 declare function enumeration<const TArr extends readonly string[]>(enumType: string, props: EnumerationProps<TArr>): EnumFromNormalizedObject<NormalizedInputType<TArr>>;
 declare function enumeration<const TObj extends ObjectEnumInput>(enumType: string, props: EnumerationProps<TObj>): EnumFromNormalizedObject<NormalizedInputType<TObj>>;
 
@@ -266,4 +292,4 @@ declare function reviveSmartEnums<R>(input: unknown, registry: Record<string, An
  */
 declare const reviveEnumField: <TItem>(value: unknown, smartEnum: AnyEnumLike<TItem>, strict?: boolean) => TItem | undefined;
 
-export { type AnyEnumLike as A, type DatabaseFormat as D, type Enumeration as E, type FieldEnumMapping as F, type Logger as L, type PathEnumMapping as P, type RevivedSmartEnums as R, type SmartApiHelperConfig as S, isSmartEnum as a, reviveEnumField as b, type LogLevel as c, type SmartEnumMappingsConfig as d, enumeration as e, type SerializedSmartEnums as f, type SmartEnumItemSerialized as g, type EnumLikeBase as h, isSmartEnumItem as i, type SmartEnumLike as j, type ReviveRowOptions as k, type RevivePayloadOptions as l, type StandardEnumItemBase as m, type StandardEnumItem as n, reviveSmartEnums as r, serializeSmartEnums as s };
+export { type AnyEnumLike as A, type DatabaseFormat as D, type Enumeration as E, type FieldEnumMapping as F, type Logger as L, type PathEnumMapping as P, type RevivedSmartEnums as R, type SmartApiHelperConfig as S, isSmartEnum as a, reviveEnumField as b, type LogLevel as c, type SmartEnumMappingsConfig as d, enumeration as e, type SerializedSmartEnums as f, type SmartEnumItemSerialized as g, type EnumLikeBase as h, isSmartEnumItem as i, type SmartEnumLike as j, type ReviveRowOptions as k, type RevivePayloadOptions as l, type StandardEnumItemBase as m, type StandardEnumItem as n, type SmartEnumMemberUnion as o, type SmartEnumSubsetView as p, reviveSmartEnums as r, serializeSmartEnums as s };