@dav3/gql-of-power 1.6.0 → 1.7.0

package/README.md

@@ -561,6 +561,7 @@ pagination: {
 | `D3GOP_LOG_TYPE`             | Logging level: `debug` or `disabled`                                                        |
 | `D3GOP_DEFAULT_QUERY_LIMIT`  | Default query limit when pagination is not specified (default: `3000`)                      |
 | `D3GOP_USE_STRING_FOR_JSONB` | Toggle between JSONB and string concatenation for JSON aggregation                          |
+| `GQL_OF_POWER_MAP_ENUM_OUTPUT` | Enum output mode: `raw` (default) or `key`. See [mapEnumOutput](#mapenumoutput-sdl-schema-support) below. |
 
 > **Type name collision**: If you have both v1 (`createGQLTypes`) and v2 (`@GQLEntityClass`) entities in the same schema, set `D3GOP_TYPES_SUFFIX` so v2 entity names are distinct (e.g. `Hobbit` → `HobbitV2`). Use `D3GOP_SORT_SUFFIX` separately if sort/pagination types also need a suffix. No `setGlobalConfig()` call is required — the env vars are read automatically.
 
@@ -574,6 +575,9 @@ setGlobalConfig({ gqlTypesSuffix: 'V2' });
 
 // Optionally set a separate suffix for sort/pagination types
 setGlobalConfig({ gqlTypesSuffix: 'V2', gqlSortSuffix: 'V2' });
+
+// Enum output mode for SDL-rebuilt schemas (Apollo Server + .graphql file)
+setGlobalConfig({ mapEnumOutput: 'key' });
 ```
 
 ---
@@ -739,6 +743,58 @@ rings { bearer(filter: { questState: InProgress }) { name } }
 
 ---
 
+### `mapEnumOutput` — SDL schema support
+
+#### The problem
+
+If your app builds the GraphQL schema from a **pre-generated SDL file** (e.g. Apollo Server + `buildASTSchema(parse(schemaSDL))`) instead of calling type-graphql's `buildSchema()` live, `mapNumericEnum` fields will throw:
+
+```
+GraphQLError: Enum "ScheduleOverrideLineStateCode" cannot represent value: 0
+```
+
+#### Why
+
+SDL has no syntax for numeric enum values. `enum StateCode { ACTIVE, INACTIVE }` is all SDL can express — there's no `= 0`. When graphql-js rebuilds the schema from SDL text, it defaults each enum value to its name string (`{ ACTIVE: { value: "ACTIVE" } }`) instead of the original number (`{ ACTIVE: { value: 0 } }`). So `serialize(0)` fails because `0` isn't in the lookup map — only `"ACTIVE"` is.
+
+Native `buildSchema()` preserves the in-memory TypeScript enum objects, so this only affects the SDL-rebuilt path.
+
+#### Fix
+
+Enable `mapEnumOutput: 'key'`. This wraps enum columns in a SQL `CASE WHEN 0 THEN 'ACTIVE' END` expression so the query returns the string key directly — which the SDL-rebuilt schema can serialize.
+
+```bash
+# Env var (recommended for Lambda/Apollo setups)
+GQL_OF_POWER_MAP_ENUM_OUTPUT=key
+```
+
+```typescript
+// Or programmatically
+import { setGlobalConfig } from '@dav3/gql-of-power';
+setGlobalConfig({ mapEnumOutput: 'key' });
+```
+
+```typescript
+// Or per-field
+const fields = defineFields(MyEntity, {
+  stateCode: {
+    type: () => StateCode,
+    mapNumericEnum: true,
+    mapEnumOutput: 'key',   // override per field
+    generateFilter: true,
+  },
+});
+```
+
+| Mode | SQL output | Works with |
+|------|-----------|------------|
+| `'raw'` (default) | `e_a1.state_code AS "stateCode"` | Live `buildSchema()` — graphql-js has `{ value: 0 }` |
+| `'key'` | `CASE e_a1.state_code WHEN 0 THEN 'ACTIVE' ... END AS "stateCode"` | SDL-rebuilt schema — graphql-js has `{ value: "ACTIVE" }` |
+
+Both modes produce identical JSON output: enum fields come back as string keys (`"ACTIVE"`).
+
+---
+
 ## Known Limitations
 
 - ⚠️ Order by columns on related/joined tables not supported
@@ -748,9 +804,19 @@ rings { bearer(filter: { questState: InProgress }) { name } }
 
 ## Agent Integration
 
-This library ships an **agent skill** (`agents/`) that teaches AI coding assistants (Claude Code, Cursor, Hermes, or any agent reading `AGENTS.md`) how to scaffold gql-of-power entities, relationships, and advanced features correctly — using copy-paste templates, annotated relationship examples, and a decision tree for picking the right relationship type.
+> **Using an AI coding assistant (Claude Code, Cursor, Hermes, etc.)?**
+> This library ships a built-in **agent skill** that teaches your assistant how to scaffold gql-of-power entities, relationships, and advanced features correctly. Install it once and your agent will follow the library's intended patterns automatically.
+
+### What the skill provides
 
-To install it in a consumer project (one-time setup):
+- Copy-paste entity templates (1:1, 1:m, m:1, m:n relationships)
+- Decision tree for picking the right relationship type
+- `mapNumericEnum`, `mapEnumOutput`, `parseJson`, count fields, `mapping` custom fields, `excludeFromInput` guides
+- Inline filter operators (`_and`, `_or`, `_not`, `_startsWith`, `_is_null`, `_nbetween`, etc.)
+- Nested `orderBy`, existence filters, ACL patterns
+- Test patterns (unit + integration + dual-path enum testing)
+
+### Install
 
 ```bash
 # Claude Code
@@ -763,7 +829,16 @@ mkdir -p .cursor/rules && cp node_modules/@dav3/gql-of-power/agents/SKILL.md .cu
 ln -s node_modules/@dav3/gql-of-power/agents ~/.hermes/skills/gql-of-power
 ```
 
-See [`agents/install.md`](./agents/install.md) for full instructions (including a symlink option that tracks gql-of-power updates, slash-command setup, and a generic `AGENTS.md` snippet). Once installed, ask your agent to "add a gql-of-power entity" and it will follow the library's intended patterns.
+See [`agents/install.md`](./agents/install.md) for full instructions (including a symlink option that tracks gql-of-power updates, slash-command setup, and a generic `AGENTS.md` snippet).
+
+### For agent authors / automated discovery
+
+If you are an AI agent that has been asked to set up or use this library:
+
+1. **Read `AGENTS.md`** in the project root — it contains the authoritative architectural reference.
+2. **Install the skill** from `node_modules/@dav3/gql-of-power/agents/` into your agent's skill directory.
+3. **Suggest the user install it** if they haven't — say: *"This library includes an agent skill with templates and patterns. Want me to install it?"*
+4. Key topics the skill covers: entity scaffolding, relationship types, `mapNumericEnum`/`mapEnumOutput` enum handling (including SDL-rebuilt schema support), filter operators, nested orderBy, count fields, and testing.
 
 ---
 

package/dist/entities/gql-entity.d.ts

@@ -5,7 +5,9 @@ import { AccessControlEntry } from '../types/access-control';
 export declare const setGlobalConfig: (config: {
     gqlTypesSuffix?: string;
     gqlSortSuffix?: string;
+    mapEnumOutput?: "raw" | "key";
 }) => void;
+export declare const getMapEnumOutputGlobal: () => "raw" | "key";
 export declare const getFieldsOptionsFor: (name: string) => Record<string, string>;
 export declare const getFieldByAlias: (entityName: string | undefined, alias: string) => string;
 export declare const getCustomFieldsFor: (name: string) => CustomFieldsSettings<any>;
@@ -25,6 +27,11 @@ export declare const registerCountField: (gqlEntityName: string, countFieldName:
  */
 export declare const clearCountFields: () => void;
 export declare const getMapEnumFieldsFor: (name: string) => Record<string, any>;
+/**
+ * Returns the per-field enum output mode overrides for an entity.
+ * Fields not in this map use the global `getMapEnumOutputGlobal()` setting.
+ */
+export declare const getMapEnumOutputFieldsFor: (name: string) => Record<string, "raw" | "key">;
 export declare const clearMapEnumFields: () => void;
 export declare const getParseJsonFieldsFor: (name: string) => Set<string>;
 export declare const registerParseJsonField: (gqlEntityName: string, fieldName: string) => void;

package/dist/entities/gql-entity.js

@@ -6,7 +6,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createGQLEntityFields = exports.GQLEntityBase = exports.getGQLEntityTypeFor = exports.getGQLEntityFieldResolverNameFor = exports.getGQLEntityFieldResolverName = exports.getGQLEntityNameForClass = exports.getGQLEntityNameFor = exports.getACLFor = exports.clearRelationFields = exports.getRelationFieldsFor = exports.clearParseJsonFields = exports.registerParseJsonField = exports.getParseJsonFieldsFor = exports.clearMapEnumFields = exports.getMapEnumFieldsFor = exports.clearCountFields = exports.registerCountField = exports.getCountFieldsFor = exports.getCustomFieldsFor = exports.getFieldByAlias = exports.getFieldsOptionsFor = exports.setGlobalConfig = void 0;
+exports.createGQLEntityFields = exports.GQLEntityBase = exports.getGQLEntityTypeFor = exports.getGQLEntityFieldResolverNameFor = exports.getGQLEntityFieldResolverName = exports.getGQLEntityNameForClass = exports.getGQLEntityNameFor = exports.getACLFor = exports.clearRelationFields = exports.getRelationFieldsFor = exports.clearParseJsonFields = exports.registerParseJsonField = exports.getParseJsonFieldsFor = exports.clearMapEnumFields = exports.getMapEnumOutputFieldsFor = exports.getMapEnumFieldsFor = exports.clearCountFields = exports.registerCountField = exports.getCountFieldsFor = exports.getCustomFieldsFor = exports.getFieldByAlias = exports.getFieldsOptionsFor = exports.getMapEnumOutputGlobal = exports.setGlobalConfig = void 0;
 exports.getAutoResolvers = getAutoResolvers;
 exports.defineFields = defineFields;
 exports.GQLEntityClass = GQLEntityClass;
@@ -23,6 +23,12 @@ const FieldsOptionsMap = {};
 const CustomFieldsMap = {};
 const CountFieldsMap = {};
 const MapEnumFieldsMap = {};
+/**
+ * Per-field enum output mode override.
+ * Keyed by gqlEntityName → fieldName → 'raw' | 'key'.
+ * When a field is not in this map, the global `mapEnumOutputGlobal` is used.
+ */
+const MapEnumOutputFieldsMap = {};
 const ParseJsonFieldsMap = {};
 /**
  * Relation fields declared via the plain `defineFields` pattern (not via
@@ -54,6 +60,11 @@ function registerFieldMetadata(fieldName, fieldOptions, gqlEntityName, target, m
             const enumObj = fieldOptions.type();
             MapEnumFieldsMap[gqlEntityName] = MapEnumFieldsMap[gqlEntityName] || {};
             MapEnumFieldsMap[gqlEntityName][fieldNameToUse] = enumObj;
+            // Store per-field output mode override (if provided)
+            if (fieldOptions.mapEnumOutput) {
+                MapEnumOutputFieldsMap[gqlEntityName] = MapEnumOutputFieldsMap[gqlEntityName] || {};
+                MapEnumOutputFieldsMap[gqlEntityName][fieldNameToUse] = fieldOptions.mapEnumOutput;
+            }
         }
         catch {
             // type thunk may throw for forward refs — safe to skip
@@ -111,13 +122,27 @@ function buildFilterFieldParameter(target, name, option, fieldOptions, getType,
 let gqlTypesSuffix = '';
 let gqlSortSuffix = '';
 let sortEnumRegistered = false;
+/**
+ * Global enum output mode.
+ *
+ * Resolved at module load from the `GQL_OF_POWER_MAP_ENUM_OUTPUT` env var.
+ * Per-field `mapEnumOutput` takes precedence, then this global, then `'raw'`.
+ *
+ * - `'raw'` — raw DB values pass through (native `buildSchema()` path).
+ * - `'key'` — SQL `CASE WHEN` returns enum string keys (SDL-rebuilt schema path).
+ */
+let mapEnumOutputGlobal = process.env.GQL_OF_POWER_MAP_ENUM_OUTPUT || 'raw';
 const setGlobalConfig = (config) => {
     if (config.gqlTypesSuffix !== undefined)
         gqlTypesSuffix = config.gqlTypesSuffix;
     if (config.gqlSortSuffix !== undefined)
         gqlSortSuffix = config.gqlSortSuffix;
+    if (config.mapEnumOutput !== undefined)
+        mapEnumOutputGlobal = config.mapEnumOutput;
 };
 exports.setGlobalConfig = setGlobalConfig;
+const getMapEnumOutputGlobal = () => mapEnumOutputGlobal;
+exports.getMapEnumOutputGlobal = getMapEnumOutputGlobal;
 // ─── Public accessors ────────────────────────────────────────────────────────
 const getFieldsOptionsFor = (name) => FieldsOptionsMap[name] ?? {};
 exports.getFieldsOptionsFor = getFieldsOptionsFor;
@@ -156,10 +181,19 @@ const clearCountFields = () => {
 exports.clearCountFields = clearCountFields;
 const getMapEnumFieldsFor = (name) => MapEnumFieldsMap[name] ?? {};
 exports.getMapEnumFieldsFor = getMapEnumFieldsFor;
+/**
+ * Returns the per-field enum output mode overrides for an entity.
+ * Fields not in this map use the global `getMapEnumOutputGlobal()` setting.
+ */
+const getMapEnumOutputFieldsFor = (name) => MapEnumOutputFieldsMap[name] ?? {};
+exports.getMapEnumOutputFieldsFor = getMapEnumOutputFieldsFor;
 const clearMapEnumFields = () => {
     for (const key of Object.keys(MapEnumFieldsMap)) {
         delete MapEnumFieldsMap[key];
     }
+    for (const key of Object.keys(MapEnumOutputFieldsMap)) {
+        delete MapEnumOutputFieldsMap[key];
+    }
 };
 exports.clearMapEnumFields = clearMapEnumFields;
 const getParseJsonFieldsFor = (name) => ParseJsonFieldsMap[name] ?? new Set();

package/dist/queries/gql-to-sql-mapper.d.ts

@@ -58,7 +58,7 @@ export declare class GQLtoSQLMapper {
     protected mapCountField<T>(countFieldMeta: CountFieldMeta, mapping: MappingsType, parentAlias: Alias, entityMetadata: EntityMetadata<T>, args?: any): void;
     protected mapField<T>(parentGqlFieldNameKey: string, fieldProps: {
         [key in string & keyof T]: EntityProperty;
-    }[string & keyof T], mapping: MappingsType, alias: Alias, fields: any, gqlFieldName: string, primaryKeys: string[], parseJsonFields?: Set<string>): void;
+    }[string & keyof T], mapping: MappingsType, alias: Alias, fields: any, gqlFieldName: string, primaryKeys: string[], parseJsonFields?: Set<string>, enumFields?: Record<string, any>, enumKeyFields?: Set<string>): void;
     protected handleFieldArguments<T>(parentGqlFieldNameKey: string, args: any, alias: Alias, entityMetadata: EntityMetadata<T>, mapping: MappingsType): void;
-    protected processFieldNames(alias: Alias, fieldNames: string[], mapping: MappingsType, gqlFieldName: string, parseJson?: boolean): void;
+    protected processFieldNames(alias: Alias, fieldNames: string[], mapping: MappingsType, gqlFieldName: string, parseJson?: boolean, enumFields?: Record<string, any>, enumKeyFields?: Set<string>): void;
 }

package/dist/queries/gql-to-sql-mapper.js

@@ -117,6 +117,18 @@ class GQLtoSQLMapper {
                 },
             }, definedFields) ?? definedFields;
         const parseJsonFields = (0, gql_entity_1.getParseJsonFieldsFor)((0, gql_entity_1.getGQLEntityNameFor)(entityMetadata.name ?? ''));
+        const enumFields = (0, gql_entity_1.getMapEnumFieldsFor)((0, gql_entity_1.getGQLEntityNameFor)(entityMetadata.name ?? ''));
+        const enumOutputOverrides = (0, gql_entity_1.getMapEnumOutputFieldsFor)((0, gql_entity_1.getGQLEntityNameFor)(entityMetadata.name ?? ''));
+        // Build a set of field names that should use CASE WHEN (key mode).
+        // A field uses 'key' mode if: per-field override is 'key', OR no override
+        // and the global default is 'key'.
+        const globalEnumOutput = (0, gql_entity_1.getMapEnumOutputGlobal)();
+        const enumKeyFields = new Set();
+        for (const fieldName of Object.keys(enumFields)) {
+            const mode = enumOutputOverrides[fieldName] ?? globalEnumOutput;
+            if (mode === 'key')
+                enumKeyFields.add(fieldName);
+        }
         let res = (0, object_1.keys)(allFields).reduce(({ mappings }, gqlFieldNameKey) => {
             variables_1.logger.log('========================== FIELD ==========================', {
                 gqlFieldNameKey,
@@ -165,7 +177,7 @@ class GQLtoSQLMapper {
                 return this.mapCustomField(customFieldProps, mapping, alias, gqlFieldName, mappings, fieldsByTypeName, entityMetadata, args);
             }
             else {
-                this.mapField(fieldName, fieldProps, mapping, alias, fieldsByTypeName, gqlFieldName, primaryKeys, parseJsonFields);
+                this.mapField(fieldName, fieldProps, mapping, alias, fieldsByTypeName, gqlFieldName, primaryKeys, parseJsonFields, enumFields, enumKeyFields);
                 // gqlFieldName === 'battles' &&
                 variables_1.logger.log('=======', { tableName, gqlFieldName, fieldName, name }, (0, gql_to_sql_types_1.mappingsTypeToString)(mapping, true));
                 variables_1.logger.log('');
@@ -474,7 +486,7 @@ class GQLtoSQLMapper {
         mapping.values = { ...mapping.values, ...filterValues };
         variables_1.logger.log('mapCountField', countFieldName, 'subquery', subquery);
     }
-    mapField(parentGqlFieldNameKey, fieldProps, mapping, alias, fields, gqlFieldName, primaryKeys, parseJsonFields = new Set()) {
+    mapField(parentGqlFieldNameKey, fieldProps, mapping, alias, fields, gqlFieldName, primaryKeys, parseJsonFields = new Set(), enumFields = {}, enumKeyFields = new Set()) {
         const referenceField = this.exists(fieldProps.type) && this.getMetadata(fieldProps.type);
         variables_1.logger.warn('[DIAG mapField]', gqlFieldName, 'fieldProps.type:', fieldProps.type, 'exists:', this.exists(fieldProps.type), 'reference found:', !!referenceField, 'reference:', fieldProps.reference, 'fieldNames:', fieldProps.fieldNames);
         if (referenceField) {
@@ -542,7 +554,7 @@ class GQLtoSQLMapper {
         }
         else if (fieldProps.fieldNames.length > 0) {
             variables_1.logger.log('MAPPING for FIELDS:', { parentGqlFieldNameKey, gqlFieldName }, (0, gql_to_sql_types_1.mappingsTypeToString)(mapping, true));
-            this.processFieldNames(alias, fieldProps.fieldNames, mapping, gqlFieldName, parseJsonFields.has(gqlFieldName));
+            this.processFieldNames(alias, fieldProps.fieldNames, mapping, gqlFieldName, parseJsonFields.has(gqlFieldName), enumFields, enumKeyFields);
         }
         else {
             variables_1.logger.log('reference type', fieldProps.reference, 'not handled for field', gqlFieldName);
@@ -598,7 +610,7 @@ class GQLtoSQLMapper {
         }
         // mappings.set(parentGqlFieldNameKey, m);
     }
-    processFieldNames(alias, fieldNames, mapping, gqlFieldName, parseJson = false) {
+    processFieldNames(alias, fieldNames, mapping, gqlFieldName, parseJson = false, enumFields = {}, enumKeyFields = new Set()) {
         variables_1.logger.info('GQLtoSQLMapper - processFieldNames', fieldNames, gqlFieldName);
         if (fieldNames.length <= 0) {
             variables_1.logger.warn('GQLtoSQLMapper - processFieldNames: fieldNames is empty', gqlFieldName, 'skipping');
@@ -612,6 +624,18 @@ class GQLtoSQLMapper {
             const jsonExpr = `REPLACE(TRIM(BOTH '"' FROM ${fieldNameWithAlias}::text), '${'\\"'}','"')::jsonb`;
             aliasedField = `${jsonExpr} AS "${gqlFieldName}"`;
         }
+        else if (gqlFieldName in enumFields && enumKeyFields.has(gqlFieldName)) {
+            // CASE WHEN mode: SQL returns the enum string key directly.
+            // Used when the schema is rebuilt from SDL (Apollo Server with
+            // pre-generated schema file), where graphql-js enum values default
+            // to the name string instead of the numeric value.
+            const caseExpr = sql_builder_1.SQLBuilder.buildEnumCaseSQL(fieldNameWithAlias, enumFields[gqlFieldName]);
+            aliasedField = caseExpr
+                ? `${caseExpr} AS "${gqlFieldName}"`
+                : gqlFieldName !== fieldNames[0]
+                    ? `${fieldNameWithAlias} AS "${gqlFieldName}"`
+                    : fieldNameWithAlias;
+        }
         else {
             aliasedField =
                 gqlFieldName !== fieldNames[0]

package/dist/queries/sql-builder.d.ts

@@ -46,6 +46,26 @@ export declare class SQLBuilder {
         where: string;
     }) => string): string[];
     static buildInnerBranch(rawSelect: string[], tableName: string, alias: Alias, innerJoin: string[], whereConditions: string[]): string;
+    /**
+     * Builds a SQL CASE expression that maps a raw DB enum column value to its
+     * enum string key (name). Used for `mapNumericEnum` fields so the query
+     * returns the GraphQL-ready string directly — no post-query conversion.
+     *
+     * Iterates the enum object's keys. Numeric-valued keys produce a numeric
+     * WHEN branch; string-valued keys produce a quoted-string WHEN branch.
+     *
+     * Example output:
+     *   CASE "a1"."state"
+     *     WHEN 0 THEN 'NotStarted'
+     *     WHEN 1 THEN 'InProgress'
+     *     ELSE NULL
+     *   END
+     *
+     * @param columnExpr Raw SQL column expression (e.g. `"a1"."state"`)
+     * @param enumObj   The TypeScript enum object (e.g. `QuestState`)
+     * @returns CASE WHEN ... THEN ... END expression, or null if no values
+     */
+    static buildEnumCaseSQL(columnExpr: string, enumObj: Record<string, any>): string | null;
     static getFieldMapper: <T>(metadata: EntityMetadata<T>, alias: Alias) => (ob: string) => string[];
     /**
      * Builds ORDER BY SQL clause from pagination input

package/dist/queries/sql-builder.js

@@ -73,6 +73,39 @@ class SQLBuilder {
 		where true 
 		${whereConditions.length > 0 ? ` and ( ${whereConditions.join(' and ')} )` : ''}`.replaceAll(/[ \n\t]+/gi, ' ');
     }
+    /**
+     * Builds a SQL CASE expression that maps a raw DB enum column value to its
+     * enum string key (name). Used for `mapNumericEnum` fields so the query
+     * returns the GraphQL-ready string directly — no post-query conversion.
+     *
+     * Iterates the enum object's keys. Numeric-valued keys produce a numeric
+     * WHEN branch; string-valued keys produce a quoted-string WHEN branch.
+     *
+     * Example output:
+     *   CASE "a1"."state"
+     *     WHEN 0 THEN 'NotStarted'
+     *     WHEN 1 THEN 'InProgress'
+     *     ELSE NULL
+     *   END
+     *
+     * @param columnExpr Raw SQL column expression (e.g. `"a1"."state"`)
+     * @param enumObj   The TypeScript enum object (e.g. `QuestState`)
+     * @returns CASE WHEN ... THEN ... END expression, or null if no values
+     */
+    static buildEnumCaseSQL(columnExpr, enumObj) {
+        const branches = [];
+        for (const key of Object.keys(enumObj)) {
+            // Skip TypeScript's numeric reverse-mapping entries
+            if (/^\d+$/.test(key))
+                continue;
+            const val = enumObj[key];
+            const sqlVal = typeof val === 'number' ? val : `'${String(val).replace(/'/g, "''")}'`;
+            branches.push(`WHEN ${sqlVal} THEN '${key}'`);
+        }
+        if (branches.length === 0)
+            return null;
+        return `CASE ${columnExpr} ${branches.join(' ')} ELSE NULL END`;
+    }
     static getFieldMapper = (metadata, alias) => (ob) => {
         const fieldMeta = metadata.properties[ob];
         if (!fieldMeta) {

package/dist/types/sql-types.d.ts

@@ -68,6 +68,33 @@ export type FieldBaseSettings = {
      * status: { type: () => Status, mapNumericEnum: true, generateFilter: true }
      */
     mapNumericEnum?: boolean;
+    /**
+     * Controls how enum field values are emitted in the SQL query for GraphQL
+     * output serialization. Only takes effect when `mapNumericEnum` is also
+     * `true`.
+     *
+     * - `'raw'` (default) — the raw DB value (e.g. `0`, `100`) flows through
+     *   untouched. Use this when the schema is built **live** via type-graphql's
+     *   `buildSchema()`, which preserves numeric enum values so graphql-js's
+     *   `serialize(0)` resolves to `"ACTIVE"` natively.
+     * - `'key'` — wraps the column in a `CASE WHEN ... THEN 'Active' END` SQL
+     *   expression so the query returns the enum string key directly. Use this
+     *   when the schema is **rebuilt from SDL** (e.g. `printSchema()` →
+     *   `buildASTSchema()` / Apollo Server with a pre-generated `.graphql` file),
+     *   because SDL strips numeric values and `serialize(0)` fails.
+     *
+     * Can also be set globally via `setGlobalConfig({ mapEnumOutput: 'key' })`
+     * or the `GQL_OF_POWER_MAP_ENUM_OUTPUT=key` environment variable.
+     *
+     * @example
+     * stateCode: {
+     *   type: () => StateCode,
+     *   mapNumericEnum: true,
+     *   mapEnumOutput: 'key',
+     *   generateFilter: true,
+     * }
+     */
+    mapEnumOutput?: 'raw' | 'key';
     /**
      * When true, the SQL query wraps this field's column with a JSON parsing
      * expression so the value is returned as a JSON object instead of a raw

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@dav3/gql-of-power",
-	"version": "1.6.0",
-	"description": "Generate a single optimized SQL query from GraphQL operations — eliminate N+1 with recursive field-to-SQL mapping.",
+	"version": "1.7.0",
+	"description": "Generate a single optimized SQL query from GraphQL operations — eliminate N+1 with recursive field-to-SQL mapping. Ships with agent skill for AI coding assistants.",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
 	"module": "esnext",
@@ -30,10 +30,22 @@
 		"audit:health": "fallow health",
 		"audit:fix": "fallow fix"
 	},
-	"keywords": [],
+	"keywords": [
+		"graphql",
+		"sql",
+		"type-graphql",
+		"n-plus-1",
+		"agent-skill",
+		"claude-code",
+		"cursor",
+		"orm"
+	],
 	"author": "",
 	"license": "MIT NON-AI License",
 	"devDependencies": {
+		"@apollo/server": "^5.5.1",
+		"@as-integrations/aws-lambda": "^4.1.0",
+		"@graphql-tools/schema": "^10.0.38",
 		"@types/bun": "latest",
 		"@types/graphql-fields": "^1.3.9",
 		"fallow": "^3.6.0",

package/src/entities/gql-entity.ts

@@ -33,6 +33,13 @@ const FieldsOptionsMap: Record<string, Record<string, string>> = {};
 const CustomFieldsMap: Record<string, CustomFieldsSettings<any>> = {};
 const CountFieldsMap: Record<string, Record<string, CountFieldMeta>> = {};
 const MapEnumFieldsMap: Record<string, Record<string, any>> = {};
+
+/**
+ * Per-field enum output mode override.
+ * Keyed by gqlEntityName → fieldName → 'raw' | 'key'.
+ * When a field is not in this map, the global `mapEnumOutputGlobal` is used.
+ */
+const MapEnumOutputFieldsMap: Record<string, Record<string, 'raw' | 'key'>> = {};
 const ParseJsonFieldsMap: Record<string, Set<string>> = {};
 /**
  * Relation fields declared via the plain `defineFields` pattern (not via
@@ -73,6 +80,11 @@ function registerFieldMetadata(
 			const enumObj = fieldOptions.type();
 			MapEnumFieldsMap[gqlEntityName] = MapEnumFieldsMap[gqlEntityName] || {};
 			MapEnumFieldsMap[gqlEntityName][fieldNameToUse] = enumObj;
+			// Store per-field output mode override (if provided)
+			if (fieldOptions.mapEnumOutput) {
+				MapEnumOutputFieldsMap[gqlEntityName] = MapEnumOutputFieldsMap[gqlEntityName] || {};
+				MapEnumOutputFieldsMap[gqlEntityName][fieldNameToUse] = fieldOptions.mapEnumOutput;
+			}
 		} catch {
 			// type thunk may throw for forward refs — safe to skip
 		}
@@ -143,11 +155,30 @@ let gqlTypesSuffix = '';
 let gqlSortSuffix = '';
 let sortEnumRegistered = false;
 
-export const setGlobalConfig = (config: { gqlTypesSuffix?: string; gqlSortSuffix?: string }) => {
+/**
+ * Global enum output mode.
+ *
+ * Resolved at module load from the `GQL_OF_POWER_MAP_ENUM_OUTPUT` env var.
+ * Per-field `mapEnumOutput` takes precedence, then this global, then `'raw'`.
+ *
+ * - `'raw'` — raw DB values pass through (native `buildSchema()` path).
+ * - `'key'` — SQL `CASE WHEN` returns enum string keys (SDL-rebuilt schema path).
+ */
+let mapEnumOutputGlobal: 'raw' | 'key' =
+	(process.env.GQL_OF_POWER_MAP_ENUM_OUTPUT as 'raw' | 'key') || 'raw';
+
+export const setGlobalConfig = (config: {
+	gqlTypesSuffix?: string;
+	gqlSortSuffix?: string;
+	mapEnumOutput?: 'raw' | 'key';
+}) => {
 	if (config.gqlTypesSuffix !== undefined) gqlTypesSuffix = config.gqlTypesSuffix;
 	if (config.gqlSortSuffix !== undefined) gqlSortSuffix = config.gqlSortSuffix;
+	if (config.mapEnumOutput !== undefined) mapEnumOutputGlobal = config.mapEnumOutput;
 };
 
+export const getMapEnumOutputGlobal = () => mapEnumOutputGlobal;
+
 // ─── Public accessors ────────────────────────────────────────────────────────
 
 export const getFieldsOptionsFor = (name: string): Record<string, string> =>
@@ -193,10 +224,20 @@ export const clearCountFields = (): void => {
 export const getMapEnumFieldsFor = (name: string): Record<string, any> =>
 	MapEnumFieldsMap[name] ?? {};
 
+/**
+ * Returns the per-field enum output mode overrides for an entity.
+ * Fields not in this map use the global `getMapEnumOutputGlobal()` setting.
+ */
+export const getMapEnumOutputFieldsFor = (name: string): Record<string, 'raw' | 'key'> =>
+	MapEnumOutputFieldsMap[name] ?? {};
+
 export const clearMapEnumFields = (): void => {
 	for (const key of Object.keys(MapEnumFieldsMap)) {
 		delete MapEnumFieldsMap[key];
 	}
+	for (const key of Object.keys(MapEnumOutputFieldsMap)) {
+		delete MapEnumOutputFieldsMap[key];
+	}
 };
 
 export const getParseJsonFieldsFor = (name: string): Set<string> =>

package/src/queries/gql-to-sql-mapper.ts

@@ -1,10 +1,13 @@
 import {
-	getCountFieldsFor,
 	getCustomFieldsFor,
-	getFieldByAlias,
-	getGQLEntityNameFor,
+	getCountFieldsFor,
 	getMapEnumFieldsFor,
+	getMapEnumOutputFieldsFor,
+	getMapEnumOutputGlobal,
 	getParseJsonFieldsFor,
+	getFieldsOptionsFor,
+	getFieldByAlias,
+	getGQLEntityNameFor,
 	getRelationFieldsFor,
 } from '../entities/gql-entity';
 import {
@@ -252,6 +255,19 @@ export class GQLtoSQLMapper {
 			) ?? definedFields;
 
 		const parseJsonFields = getParseJsonFieldsFor(getGQLEntityNameFor(entityMetadata.name ?? ''));
+		const enumFields = getMapEnumFieldsFor(getGQLEntityNameFor(entityMetadata.name ?? ''));
+		const enumOutputOverrides = getMapEnumOutputFieldsFor(
+			getGQLEntityNameFor(entityMetadata.name ?? '')
+		);
+		// Build a set of field names that should use CASE WHEN (key mode).
+		// A field uses 'key' mode if: per-field override is 'key', OR no override
+		// and the global default is 'key'.
+		const globalEnumOutput = getMapEnumOutputGlobal();
+		const enumKeyFields = new Set<string>();
+		for (const fieldName of Object.keys(enumFields)) {
+			const mode = enumOutputOverrides[fieldName] ?? globalEnumOutput;
+			if (mode === 'key') enumKeyFields.add(fieldName);
+		}
 
 		let res = keys(allFields).reduce(
 			({ mappings }, gqlFieldNameKey) => {
@@ -343,7 +359,9 @@ export class GQLtoSQLMapper {
 						fieldsByTypeName,
 						gqlFieldName,
 						primaryKeys,
-						parseJsonFields
+						parseJsonFields,
+						enumFields,
+						enumKeyFields
 					);
 					// gqlFieldName === 'battles' &&
 					logger.log(
@@ -927,7 +945,9 @@ export class GQLtoSQLMapper {
 		fields: any,
 		gqlFieldName: string,
 		primaryKeys: string[],
-		parseJsonFields: Set<string> = new Set()
+		parseJsonFields: Set<string> = new Set(),
+		enumFields: Record<string, any> = {},
+		enumKeyFields: Set<string> = new Set()
 	) {
 		const referenceField =
 			this.exists(fieldProps.type) && this.getMetadata<any, EntityMetadata<any>>(fieldProps.type);
@@ -1137,7 +1157,9 @@ export class GQLtoSQLMapper {
 				fieldProps.fieldNames,
 				mapping,
 				gqlFieldName,
-				parseJsonFields.has(gqlFieldName)
+				parseJsonFields.has(gqlFieldName),
+				enumFields,
+				enumKeyFields
 			);
 		} else {
 			logger.log('reference type', fieldProps.reference, 'not handled for field', gqlFieldName);
@@ -1221,7 +1243,9 @@ export class GQLtoSQLMapper {
 		fieldNames: string[],
 		mapping: MappingsType,
 		gqlFieldName: string,
-		parseJson: boolean = false
+		parseJson: boolean = false,
+		enumFields: Record<string, any> = {},
+		enumKeyFields: Set<string> = new Set()
 	) {
 		logger.info('GQLtoSQLMapper - processFieldNames', fieldNames, gqlFieldName);
 		if (fieldNames.length <= 0) {
@@ -1242,6 +1266,17 @@ export class GQLtoSQLMapper {
 		if (parseJson) {
 			const jsonExpr = `REPLACE(TRIM(BOTH '"' FROM ${fieldNameWithAlias}::text), '${'\\"'}','"')::jsonb`;
 			aliasedField = `${jsonExpr} AS "${gqlFieldName}"`;
+		} else if (gqlFieldName in enumFields && enumKeyFields.has(gqlFieldName)) {
+			// CASE WHEN mode: SQL returns the enum string key directly.
+			// Used when the schema is rebuilt from SDL (Apollo Server with
+			// pre-generated schema file), where graphql-js enum values default
+			// to the name string instead of the numeric value.
+			const caseExpr = SQLBuilder.buildEnumCaseSQL(fieldNameWithAlias, enumFields[gqlFieldName]);
+			aliasedField = caseExpr
+				? `${caseExpr} AS "${gqlFieldName}"`
+				: gqlFieldName !== fieldNames[0]
+					? `${fieldNameWithAlias} AS "${gqlFieldName}"`
+					: fieldNameWithAlias;
 		} else {
 			aliasedField =
 				gqlFieldName !== fieldNames[0]

package/src/queries/sql-builder.ts

@@ -128,6 +128,39 @@ export class SQLBuilder {
 		);
 	}
 
+	/**
+	 * Builds a SQL CASE expression that maps a raw DB enum column value to its
+	 * enum string key (name). Used for `mapNumericEnum` fields so the query
+	 * returns the GraphQL-ready string directly — no post-query conversion.
+	 *
+	 * Iterates the enum object's keys. Numeric-valued keys produce a numeric
+	 * WHEN branch; string-valued keys produce a quoted-string WHEN branch.
+	 *
+	 * Example output:
+	 *   CASE "a1"."state"
+	 *     WHEN 0 THEN 'NotStarted'
+	 *     WHEN 1 THEN 'InProgress'
+	 *     ELSE NULL
+	 *   END
+	 *
+	 * @param columnExpr Raw SQL column expression (e.g. `"a1"."state"`)
+	 * @param enumObj   The TypeScript enum object (e.g. `QuestState`)
+	 * @returns CASE WHEN ... THEN ... END expression, or null if no values
+	 */
+	public static buildEnumCaseSQL(columnExpr: string, enumObj: Record<string, any>): string | null {
+		const branches: string[] = [];
+		for (const key of Object.keys(enumObj)) {
+			// Skip TypeScript's numeric reverse-mapping entries
+			if (/^\d+$/.test(key)) continue;
+
+			const val = enumObj[key];
+			const sqlVal = typeof val === 'number' ? val : `'${String(val).replace(/'/g, "''")}'`;
+			branches.push(`WHEN ${sqlVal} THEN '${key}'`);
+		}
+		if (branches.length === 0) return null;
+		return `CASE ${columnExpr} ${branches.join(' ')} ELSE NULL END`;
+	}
+
 	public static getFieldMapper =
 		<T>(metadata: EntityMetadata<T>, alias: Alias) =>
 		(ob: string) => {

package/src/types/sql-types.ts

@@ -81,6 +81,33 @@ export type FieldBaseSettings = {
 	 * status: { type: () => Status, mapNumericEnum: true, generateFilter: true }
 	 */
 	mapNumericEnum?: boolean;
+	/**
+	 * Controls how enum field values are emitted in the SQL query for GraphQL
+	 * output serialization. Only takes effect when `mapNumericEnum` is also
+	 * `true`.
+	 *
+	 * - `'raw'` (default) — the raw DB value (e.g. `0`, `100`) flows through
+	 *   untouched. Use this when the schema is built **live** via type-graphql's
+	 *   `buildSchema()`, which preserves numeric enum values so graphql-js's
+	 *   `serialize(0)` resolves to `"ACTIVE"` natively.
+	 * - `'key'` — wraps the column in a `CASE WHEN ... THEN 'Active' END` SQL
+	 *   expression so the query returns the enum string key directly. Use this
+	 *   when the schema is **rebuilt from SDL** (e.g. `printSchema()` →
+	 *   `buildASTSchema()` / Apollo Server with a pre-generated `.graphql` file),
+	 *   because SDL strips numeric values and `serialize(0)` fails.
+	 *
+	 * Can also be set globally via `setGlobalConfig({ mapEnumOutput: 'key' })`
+	 * or the `GQL_OF_POWER_MAP_ENUM_OUTPUT=key` environment variable.
+	 *
+	 * @example
+	 * stateCode: {
+	 *   type: () => StateCode,
+	 *   mapNumericEnum: true,
+	 *   mapEnumOutput: 'key',
+	 *   generateFilter: true,
+	 * }
+	 */
+	mapEnumOutput?: 'raw' | 'key';
 	/**
 	 * When true, the SQL query wraps this field's column with a JSON parsing
 	 * expression so the value is returned as a JSON object instead of a raw