@dav3/gql-of-power 1.5.0 → 1.7.0

package/README.md

@@ -380,19 +380,32 @@ filter: {
 
 ### Filter operations
 
-| Operation      | Meaning                                                |
-| -------------- | ------------------------------------------------------ |
-| `_eq`          | Equal                                                  |
-| `_ne`          | Not equal                                              |
-| `_in`          | In array                                               |
-| `_nin`         | Not in array                                           |
-| `_like`        | ILIKE (case-insensitive contains)                      |
-| `_gt` / `_gte` | Greater than / greater than or equal                   |
-| `_lt` / `_lte` | Less than / less than or equal                         |
-| `_and`         | Logical AND                                            |
-| `_or`          | Logical OR (generates UNION ALL)                       |
-| `_exists`      | Check related entities exist (AND-combined per key)    |
-| `_not_exists`  | Check no related entities exist (AND-combined per key) |
+| Operation      | Meaning                                                 |
+| -------------- | ------------------------------------------------------- |
+| `_eq`          | Equal                                                   |
+| `_ne`          | Not equal                                               |
+| `_in`          | In array                                                |
+| `_nin`         | Not in array                                            |
+| `_like`        | LIKE (case-sensitive contains)                          |
+| `_nlike`       | NOT LIKE                                                |
+| `_ilike`       | ILIKE (case-insensitive contains)                       |
+| `_nilike`      | NOT ILIKE                                               |
+| `_startsWith`  | LIKE prefix (case-sensitive)                            |
+| `_istartsWith` | ILIKE prefix (case-insensitive)                         |
+| `_endsWith`    | LIKE suffix (case-sensitive)                            |
+| `_iendsWith`   | ILIKE suffix (case-insensitive)                         |
+| `_re`          | Regex match (`~`)                                       |
+| `_nre`         | Regex non-match (`!~`)                                  |
+| `_gt` / `_gte` | Greater than / greater than or equal                    |
+| `_lt` / `_lte` | Less than / less than or equal                          |
+| `_between`     | BETWEEN low AND high                                    |
+| `_nbetween`    | NOT BETWEEN low AND high                                |
+| `_is_null`     | IS NULL (true) / IS NOT NULL (false)                    |
+| `_and`         | Logical AND                                             |
+| `_or`          | Logical OR (generates UNION ALL)                        |
+| `_not`         | Negates a conjunction of conditions (NOT (...) wrapper) |
+| `_exists`      | Check related entities exist (AND-combined per key)     |
+| `_not_exists`  | Check no related entities exist (AND-combined per key)  |
 
 ### Existence Filters (`_exists` / `_not_exists`)
 
@@ -425,6 +438,28 @@ filter: {
 
 `_exists` generates `EXISTS (SELECT 1 FROM ... WHERE ...)` subqueries. `_not_exists` generates `NOT EXISTS (...)`. Multiple keys within one `_exists`/`_not_exists` each produce a separate `EXISTS`/`NOT EXISTS` clause, AND-combined in the WHERE. OR across exists conditions is achieved via `_or`.
 
+### Negation Filter (`_not`)
+
+Negate a set of conditions. `_not` takes an array of filter objects, AND-combines them, and wraps the result in `NOT (...)`.
+
+```graphql
+# Persons whose name is NOT "Sauron" AND race is NOT "Maiar"
+filter: {
+  _not: [
+    { name: "Sauron" }
+    { race: "Maiar" }
+  ]
+}
+
+# Combine _not with other filters
+filter: {
+  age_gt: 50
+  _not: [{ race: "Orc" }]
+}
+```
+
+Generates `NOT (cond1 AND cond2)` in the WHERE clause. For simple field-level negation, the negated operators (`_ne`, `_nin`) are more direct — `_not` is for negating compound expressions. Note: nesting `_or` inside `_not` is not fully negated (the UNION ALL path is not invertible); use De Morgan's law (`_and` of negated conditions) instead.
+
 ---
 
 ## Count Fields
@@ -526,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.
 
@@ -539,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' });
 ```
 
 ---
@@ -704,9 +743,60 @@ 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
 
-- ⚠️ Class-level `_not` conditions not yet supported
 - ⚠️ Order by columns on related/joined tables not supported
 - ⚠️ ACL pending async refactoring
 
@@ -714,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.
 
-To install it in a consumer project (one-time setup):
+### What the skill provides
+
+- 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
@@ -729,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();
@@ -452,40 +486,6 @@ function _buildInputType(gqlEntityName, fields, opts, metadata, customFields) {
     return GQLEntityInput;
 }
 // ─── Shared resolver builder ─────────────────────────────────────────────────
-/**
- * Phase 2: attach @FieldResolver methods for fields with `mapNumericEnum`.
- *
- * The resolver returns the raw DB value unchanged. graphql-js's
- * `GraphQLEnumType.serialize()` performs the value→name conversion itself
- * (e.g. 100 → "Forged") using the internal values registered by
- * `registerEnumType`. Returning the string key here would cause
- * "Enum cannot represent value" errors at serialization time.
- */
-function _registerMapNumericEnumResolvers(rawFields, FieldsResolver) {
-    for (const fieldName of Object.keys(rawFields)) {
-        const fieldOpts = rawFields[fieldName];
-        if (!fieldOpts?.mapNumericEnum)
-            continue;
-        const fieldNameToUse = fieldOpts.alias ?? fieldName;
-        const enumTypeThunk = fieldOpts.type;
-        const resolveFn = (root) => {
-            const value = root[fieldNameToUse];
-            if (value === null || value === undefined)
-                return null;
-            return value;
-        };
-        Object.defineProperty(FieldsResolver.prototype, fieldNameToUse, {
-            value: resolveFn,
-            writable: true,
-            configurable: true,
-        });
-        (0, type_graphql_1.FieldResolver)(enumTypeThunk, {
-            ...fieldOpts.options,
-            name: fieldNameToUse,
-        })(FieldsResolver.prototype, fieldNameToUse, Object.getOwnPropertyDescriptor(FieldsResolver.prototype, fieldNameToUse));
-        (0, type_graphql_1.Root)()(FieldsResolver.prototype, fieldNameToUse, 0);
-    }
-}
 /** Phase 3: process custom fields — alias registration, metadata, resolve/mapping/requiresRelations strategies. */
 function _processCustomFields(customFields, gqlEntityName, GQLEntity, GQLEntityFilterInput, FieldsResolver, opts, metadata) {
     CustomFieldsMap[gqlEntityName] = customFields;
@@ -877,10 +877,7 @@ function _buildResolversForEntity(GQLEntity, gqlEntityName, fields, opts, metada
     FieldsResolver = __decorate([
         (0, type_graphql_1.Resolver)(() => GQLEntity)
     ], FieldsResolver);
-    // ─── Phases 2-6: delegate to focused helpers ────────────────────────────
-    if (rawFields) {
-        _registerMapNumericEnumResolvers(rawFields, FieldsResolver);
-    }
+    // ─── Phases 3-6: delegate to focused helpers ────────────────────────────
     if (customFields) {
         _processCustomFields(customFields, gqlEntityName, GQLEntity, GQLEntityFilterInput, FieldsResolver, opts, metadata);
     }

package/dist/field-operations.d.ts

@@ -19,13 +19,22 @@ export declare abstract class FieldOperationsClass<T> {
     abstract _lt: T;
     abstract _lte: T;
     abstract _like: T;
-    abstract _re: T;
+    abstract _nlike: T;
     abstract _ilike: T;
+    abstract _nilike: T;
+    abstract _startsWith: T;
+    abstract _istartsWith: T;
+    abstract _endsWith: T;
+    abstract _iendsWith: T;
+    abstract _re: T;
+    abstract _nre: T;
     abstract _fulltext: T;
     abstract _overlap: T[];
     abstract _contains: T;
     abstract _contained: T;
     abstract _between: T[];
+    abstract _nbetween: T[];
+    abstract _is_null: T;
     abstract _exists: T;
 }
 type Scalar = string | number | boolean | bigint | null;
@@ -69,7 +78,7 @@ export declare const FieldOperations: {
         where: string;
         value: undefined;
     };
-    _re: ([l, r]: string[], []: Scalar[]) => {
+    _nlike: ([l, r]: string[], []: Scalar[]) => {
         where: string;
         value: undefined;
     };
@@ -77,6 +86,34 @@ export declare const FieldOperations: {
         where: string;
         value: undefined;
     };
+    _nilike: ([l, r]: string[], []: Scalar[]) => {
+        where: string;
+        value: undefined;
+    };
+    _startsWith: ([l, r]: string[], []: Scalar[]) => {
+        where: string;
+        value: undefined;
+    };
+    _istartsWith: ([l, r]: string[], []: Scalar[]) => {
+        where: string;
+        value: undefined;
+    };
+    _endsWith: ([l, r]: string[], []: Scalar[]) => {
+        where: string;
+        value: undefined;
+    };
+    _iendsWith: ([l, r]: string[], []: Scalar[]) => {
+        where: string;
+        value: undefined;
+    };
+    _re: ([l, r]: string[], []: Scalar[]) => {
+        where: string;
+        value: undefined;
+    };
+    _nre: ([l, r]: string[], []: Scalar[]) => {
+        where: string;
+        value: undefined;
+    };
     _fulltext: ([l, r]: string[], []: Scalar[]) => {
         where: string;
         value: undefined;
@@ -93,6 +130,14 @@ export declare const FieldOperations: {
         where: string;
         value: undefined;
     };
+    _nbetween: ([l, r1, r2]: string[], []: Scalar[]) => {
+        where: string;
+        value: undefined;
+    };
+    _is_null: ([l]: string[], [_l, rv]: Scalar[]) => {
+        where: string;
+        value: undefined;
+    };
     _exists: ([l]: string[], []: Scalar[]) => {
         where: string;
         value: undefined;

package/dist/field-operations.js

@@ -64,14 +64,42 @@ exports.FieldOperations = {
         where: `${l} like ${r}`,
         value: undefined,
     }),
-    _re: ([l, r], []) => ({
-        where: `${l} ~ ${r}`,
+    _nlike: ([l, r], []) => ({
+        where: `${l} not like ${r}`,
         value: undefined,
     }),
     _ilike: ([l, r], []) => ({
         where: `${l} ilike ${r}`,
         value: undefined,
     }),
+    _nilike: ([l, r], []) => ({
+        where: `${l} not ilike ${r}`,
+        value: undefined,
+    }),
+    _startsWith: ([l, r], []) => ({
+        where: `${l} like ${r} || '%'`,
+        value: undefined,
+    }),
+    _istartsWith: ([l, r], []) => ({
+        where: `${l} ilike ${r} || '%'`,
+        value: undefined,
+    }),
+    _endsWith: ([l, r], []) => ({
+        where: `${l} like '%' || ${r}`,
+        value: undefined,
+    }),
+    _iendsWith: ([l, r], []) => ({
+        where: `${l} ilike '%' || ${r}`,
+        value: undefined,
+    }),
+    _re: ([l, r], []) => ({
+        where: `${l} ~ ${r}`,
+        value: undefined,
+    }),
+    _nre: ([l, r], []) => ({
+        where: `${l} !~ ${r}`,
+        value: undefined,
+    }),
     _fulltext: ([l, r], []) => ({
         where: `${l}::tsvector @@ ${r}::tsquery`,
         value: undefined,
@@ -88,6 +116,14 @@ exports.FieldOperations = {
         where: `${l} between ${r1} and ${r2}`,
         value: undefined,
     }),
+    _nbetween: ([l, r1, r2], []) => ({
+        where: `${l} not between ${r1} and ${r2}`,
+        value: undefined,
+    }),
+    _is_null: ([l], [_l, rv]) => ({
+        where: rv ? `${l} is null` : `${l} is not null`,
+        value: undefined,
+    }),
     _exists: ([l], []) => ({
         where: `exists ${l}`,
         value: undefined,

package/dist/queries/filter-processor.d.ts

@@ -66,9 +66,28 @@ export declare class FilterProcessor extends ClassOperations {
      */
     _and<T>({ entityMetadata, gqlFilters, parentAlias, alias, fieldName, mapping, mappings, customFields, }: ClassOperationInputType<T>): void;
     /**
-     * Handles _not operations (placeholder implementation)
+     * Handles _not operations.
+     *
+     * Negates the conjunction of all filter conditions in the array.
+     * `_not: [{ a: 1 }, { b: 2 }]` produces `NOT (a = 1 AND b = 2)`.
+     *
+     * Each filter in the array is mapped via recursiveMap (same as _and),
+     * the resulting WHERE clauses are combined with AND, and the whole
+     * expression is wrapped in `NOT (...)`. Required JOINs and bound values
+     * are forwarded so relationship-based conditions resolve correctly.
+     *
+     * @example
+     * ```graphql
+     * filter: {
+     *   _not: [{ name: "Sauron" }, { race: "Maiar" }]
+     * }
+     * ```
+     * Generates:
+     * ```sql
+     * WHERE ... AND NOT (person_name = :val AND person_race = :val2)
+     * ```
      */
-    _not<T>({ entityMetadata, gqlFilters, alias, fieldName, mapping, mappings, }: ClassOperationInputType<T>): void;
+    _not<T>({ entityMetadata, gqlFilters, parentAlias, alias, fieldName, mapping, mappings, customFields, }: ClassOperationInputType<T>): void;
     /**
      * Handles _exists operations.
      *

package/dist/queries/filter-processor.js

@@ -250,11 +250,63 @@ class FilterProcessor extends operations_1.ClassOperations {
         });
     }
     /**
-     * Handles _not operations (placeholder implementation)
+     * Handles _not operations.
+     *
+     * Negates the conjunction of all filter conditions in the array.
+     * `_not: [{ a: 1 }, { b: 2 }]` produces `NOT (a = 1 AND b = 2)`.
+     *
+     * Each filter in the array is mapped via recursiveMap (same as _and),
+     * the resulting WHERE clauses are combined with AND, and the whole
+     * expression is wrapped in `NOT (...)`. Required JOINs and bound values
+     * are forwarded so relationship-based conditions resolve correctly.
+     *
+     * @example
+     * ```graphql
+     * filter: {
+     *   _not: [{ name: "Sauron" }, { race: "Maiar" }]
+     * }
+     * ```
+     * Generates:
+     * ```sql
+     * WHERE ... AND NOT (person_name = :val AND person_race = :val2)
+     * ```
      */
-    _not({ entityMetadata, gqlFilters, alias, fieldName, mapping, mappings, }) {
-        // TODO: Implement _not operation
-        variables_1.logger.warn('FilterProcessor - _not operation not yet implemented');
+    _not({ entityMetadata, gqlFilters, parentAlias, alias, fieldName, mapping, mappings, customFields, }) {
+        const filters = Array.isArray(gqlFilters) ? gqlFilters : [gqlFilters];
+        const combined = filters.reduce((acc, f) => {
+            const mapped = this.recursiveMapFunction({
+                entityMetadata,
+                gqlFilters: [f],
+                parentAlias,
+                alias,
+                customFields,
+            });
+            // Nested _or/_and inside _not cannot be negated via a simple NOT(...)
+            // wrapper because they rely on the UNION ALL path. Warn so callers
+            // know those branches aren't fully negated.
+            const orEntry = mapped.get('_or');
+            if (orEntry && orEntry._or.length > 0) {
+                variables_1.logger.warn("FilterProcessor - _not: nested _or inside _not is not fully negated; use De Morgan's (_and of negated conditions) instead");
+            }
+            mapped.delete('_or');
+            mapped.delete('_and');
+            const reduced = utils_1.QueriesUtils.mappingsReducer(mapped);
+            acc.where.push(...reduced.where);
+            acc.innerJoin.push(...reduced.innerJoin);
+            acc.values = { ...acc.values, ...reduced.values };
+            return acc;
+        }, {
+            where: [],
+            innerJoin: [],
+            values: {},
+        });
+        if (combined.where.length > 0) {
+            const negatedWhere = `not (${combined.where.join(' and ')})`;
+            mapping.where.push(negatedWhere);
+            mapping.innerJoin.push(...combined.innerJoin);
+            mapping.values = { ...mapping.values, ...combined.values };
+        }
+        variables_1.logger.log('FilterProcessor - _not - negated where', mapping.where);
     }
     /**
      * Handles _exists operations.

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;
 }