@dwtechs/antity-pgsql 0.9.1 → 0.11.0

package/README.md

@@ -62,11 +62,11 @@ const entity = new SQLEntity("consumers", [
     type: "integer",
     min: 0,
     max: 120,
-    typeCheck: true,
-    filter: true,
-    need: ["PUT"],
+    isTypeChecked: true,
+    isFilterable: true,
+    requiredFor: ["PUT"],
     operations: ["SELECT", "UPDATE"],
-    send: true,
+    isPrivate: false,
     sanitizer: null,
     normalizer: null,
     validator: null,
@@ -76,11 +76,11 @@ const entity = new SQLEntity("consumers", [
     type: "string",
     min: 0,
     max: 255,
-    typeCheck: true,
-    filter: false,
-    need: ["POST", "PUT"],
+    isTypeChecked: true,
+    isFilterable: false,
+    requiredFor: ["POST", "PUT"],
     operations: ["SELECT", "UPDATE"],
-    send: true,
+    isPrivate: false,
     sanitizer: null,
     normalizer: normalizeName,
     validator: null,
@@ -90,11 +90,11 @@ const entity = new SQLEntity("consumers", [
     type: "string",
     min: 0,
     max: 255,
-    typeCheck: true,
-    filter: false,
-    need: ["POST", "PUT"],
+    isTypeChecked: true,
+    isFilterable: false,
+    requiredFor: ["POST", "PUT"],
     operations: ["SELECT", "UPDATE"],
-    send: true,
+    isPrivate: false,
     sanitizer: null,
     normalizer: normalizeName,
     validator: null,
@@ -104,11 +104,11 @@ const entity = new SQLEntity("consumers", [
     type: "string",
     min: 0,
     max: 255,
-    typeCheck: true,
-    filter: true,
-    need: ["POST", "PUT"],
+    isTypeChecked: true,
+    isFilterable: true,
+    requiredFor: ["POST", "PUT"],
     operations: ["SELECT", "UPDATE"],
-    send: true,
+    isPrivate: false,
     sanitizer: null,
     normalizer: normalizeNickname,
     validator: null,
@@ -125,10 +125,10 @@ router.put("/", ...entity.updateArraySubstack);
 router.post("/manual", entity.normalizeArray, entity.validateArray, ..., entity.add);
 router.put("/manual", entity.normalizeArray, entity.validateArray, ..., entity.update);
 
-router.put("/archive", ..., entity.archive);
+router.patch("/archive", ..., entity.archive);
 router.delete("/", ..., entity.delete);
 router.delete("/archived", ..., entity.deleteArchive);
-router.get("/history", ..., entity.getHistory);
+router.get("/:id/history", ..., entity.getHistory);
 
 ```
 
@@ -160,10 +160,14 @@ type MatchMode =
   "st_dwithin";
 
 
+type Filters = {
+  [key: string]: Filter | Filter[]; // Supports both simple (object) and complex (array) formats
+}
+
 type Filter = {
   value: string | number | boolean | Date | number[];
-  subProps?: string[];
   matchMode?: MatchMode;
+  operator?: string; // 'and' | 'or' - Used when multiple filters apply to the same property
 }
 
 type ExpressMiddleware = (req: Request, res: Response, next: NextFunction) => void;
@@ -175,7 +179,7 @@ class SQLEntity {
   get name(): string;
   get table(): string;
   get schema(): string;
-  get unsafeProps(): string[];
+  get privateProps(): string[];
   get properties(): Property[];
   set name(name: string);
   set table(table: string);
@@ -278,6 +282,56 @@ Using substacks simplifies your route definitions and ensures consistent data pr
 - **deleteArchive()**: Deletes archived rows that were archived before a specific date using a PostgreSQL SECURITY DEFINER function. Expects `req.body.date` to be a Date object.
 - **getHistory()**: Retrieves modification history for rows from the `log.history` table. Expects `req.body.rows` to be an array of objects with `id` property. Returns all historical records for the specified entity IDs.
 
+### Filters
+
+Filters support two formats for maximum flexibility:
+
+#### Simple Format (Single Filter per Property)
+
+Backward-compatible format using a single filter object:
+
+```javascript
+const filters = {
+  name: { value: 'John', matchMode: 'contains' },
+  age: { value: 30, matchMode: 'equals' },
+  archived: { value: false, matchMode: 'equals' }
+};
+```
+
+#### Complex Format (Multiple Filters per Property)
+
+Array-based format supporting multiple filters with logical operators:
+
+```javascript
+const filters = {
+  // Multiple filters on the same property with OR operator
+  name: [
+    { value: 'John', matchMode: 'contains', operator: 'or' },
+    { value: 'Jane', matchMode: 'contains', operator: 'or' }
+  ],
+  // Age range with AND operator
+  age: [
+    { value: 18, matchMode: 'gte', operator: 'and' },
+    { value: 65, matchMode: 'lte', operator: 'and' }
+  ],
+  // Single filter in array format
+  archived: [{ value: false, matchMode: 'equals' }]
+};
+```
+
+This generates SQL like:
+```sql
+WHERE (name LIKE '%John%' OR name LIKE '%Jane%') 
+  AND (age >= 18 AND age <= 65) 
+  AND archived = false
+```
+
+**Notes:**
+- Both formats can be mixed in the same filters object
+- When using arrays with a single filter, the operator is optional
+- Default operator is 'AND' if not specified
+- The operator field is case-insensitive
+
 
 ## Match modes
 
@@ -360,10 +414,10 @@ Any of these can be passed into the options object for each function.
 | type            |  Type                     | Type of the property                              |
 | min             |  number \| Date           | Minimum value                                     | 0 \| 1900-01-01
 | max             |  number \| Date           | Maximum value                                     | 999999999 \| 2200-12-31
-| need            |  Method[]                 | property is validated for the listed methods only | ["PATCH", "PUT", "POST"]
-| send            |  boolean                  | Property is sent in the response                  | true
-| typeCheck       |  boolean                  | Type is checked during validation                 | false
-| filter          |  boolean                  | property is filterable in a SELECT operation      | true
+| requiredFor     |  Method[]                 | property is required for the listed methods only  | ["PATCH", "PUT", "POST"]
+| isPrivate       |  boolean                  | Property is unsafe to send in the response        | true
+| isTypeChecked   |  boolean                  | Type is checked during validation                 | false
+| isFilterable    |  boolean                  | property is filterable in a SELECT operation      | true
 | operations      |  Operation[]              | Property is used for the DML operations only      | ["SELECT", "INSERT", "UPDATE"]
 | sanitizer       |  ((v:any) => any) \| null | Custom sanitizer function if sanitize is true     | null
 | normalizer      |  ((v:any) => any) \| null | Custom Normalizer function if normalize is true   | null

package/dist/antity-pgsql.d.ts

@@ -36,23 +36,23 @@ export type Filters = {
 };
 export type Filter = {
   value: string | number | boolean | Date | number[];
-  subProps?: string[];
   matchMode?: MatchMode;
+  operator?: string;
 };
 export type { Type };
 
 export declare class Property extends BaseProperty {
-  filter: boolean;
+  isFilterable: boolean;
   operations: Operation[];
   constructor(
     key: string,
     type: Type,
     min: number | Date | null,
     max: number | Date | null,
-    need: Method[],
-    send: boolean,
-    typeCheck: boolean,
-    filter: boolean,
+    requiredFor: Method[],
+    isPrivate: boolean,
+    isTypeChecked: boolean,
+    isFilterable: boolean,
     operations: Operation[] | undefined,
     sanitizer: ((v: unknown) => unknown) | null,
     normalizer: ((v: unknown) => unknown) | null,

package/dist/antity-pgsql.js

@@ -160,20 +160,33 @@ function comparator(matchMode) {
 }
 
 function add(filters) {
+    var _a, _b;
     const conditions = [];
     const args = [];
     if (filters) {
         let i = 1;
         for (const k in filters) {
-            const { value, matchMode } = filters[k];
-            const indexes = isArray(value) ? value.map(() => i++) : [i++];
-            const cond = addOne(k, indexes, matchMode);
-            if (cond) {
-                conditions.push(cond);
-                if (isArray(value))
-                    args.push(...value);
-                else
-                    args.push(value);
+            const filterValue = filters[k];
+            const filterArray = isArray(filterValue) ? filterValue : [filterValue];
+            const groupConditions = [];
+            for (const filter of filterArray) {
+                const { value, matchMode } = filter;
+                const indexes = isArray(value) ? value.map(() => i++) : [i++];
+                const cond = addOne(k, indexes, matchMode);
+                if (cond) {
+                    groupConditions.push(cond);
+                    if (isArray(value))
+                        args.push(...value);
+                    else
+                        args.push(value);
+                }
+            }
+            if (groupConditions.length > 0) {
+                const operator = ((_b = (_a = filterArray[0]) === null || _a === void 0 ? void 0 : _a.operator) === null || _b === void 0 ? void 0 : _b.toUpperCase()) || 'AND';
+                const combined = groupConditions.length > 1
+                    ? `(${groupConditions.join(` ${operator} `)})`
+                    : groupConditions[0];
+                conditions.push(combined);
             }
         }
     }
@@ -459,18 +472,26 @@ function cleanFilters(filters, properties) {
                 delete filters[k];
                 continue;
             }
-            if (!prop.filter) {
+            if (!prop.isFilterable) {
                 log.warn(`${LOGS_PREFIX}Filters: skipping unfilterable property: ${k}`);
                 delete filters[k];
                 continue;
             }
             const type$1 = type(prop.type);
-            const { matchMode: matchMode$1 } = filters[k];
-            if (!matchMode$1 || !matchMode(type$1, matchMode$1)) {
-                log.warn(`${LOGS_PREFIX}Filters: skipping invalid match mode: "${matchMode$1}" for type: "${type$1}" at property: "${k}"`);
+            const filterValue = filters[k];
+            const filterArray = isArray(filterValue) ? filterValue : [filterValue];
+            const validFilters = filterArray.filter((f) => {
+                const { matchMode: matchMode$1 } = f;
+                if (!matchMode$1 || !matchMode(type$1, matchMode$1)) {
+                    log.warn(`${LOGS_PREFIX}Filters: skipping invalid match mode: "${matchMode$1}" for type: "${type$1}" at property: "${k}"`);
+                    return false;
+                }
+                return true;
+            });
+            if (!validFilters.length)
                 delete filters[k];
-                continue;
-            }
+            else
+                filters[k] = validFilters;
         }
     }
     return filters;
@@ -497,10 +518,10 @@ function generateSummary(name, table, properties) {
         lines.push(`│ │ ├─ Type: ${p.type}`);
         lines.push(`│ │ ├─ Min: ${p.min}`);
         lines.push(`│ │ ├─ Max: ${p.max}`);
-        lines.push(`│ │ ├─ need: ${p.need}`);
-        lines.push(`│ │ ├─ Safe: ${p.safe}`);
-        lines.push(`│ │ ├─ TypeCheck: ${p.typeCheck}`);
-        lines.push(`│ │ ├─ Filter: ${p.filter}`);
+        lines.push(`│ │ ├─ RequiredFor: ${p.requiredFor}`);
+        lines.push(`│ │ ├─ IsPrivate: ${p.isPrivate}`);
+        lines.push(`│ │ ├─ IsTypeChecked: ${p.isTypeChecked}`);
+        lines.push(`│ │ ├─ IsFilterable: ${p.isFilterable}`);
         lines.push(`│ │ ├─ Operations: [${p.operations.join(', ')}]`);
         lines.push(`│ │ ├─ Sanitize: ${p.sanitize}`);
         lines.push(`│ │ ├─ Normalize: ${p.normalize}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dwtechs/antity-pgsql",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "Open source library to add PostgreSQL support to @dwtechs/Antity entities.",
   "keywords": [
     "entities"
@@ -38,7 +38,7 @@
   "dependencies": {
     "@dwtechs/checkard": "3.6.0",
     "@dwtechs/winstan": "0.5.0",
-    "@dwtechs/antity": "0.15.0",
+    "@dwtechs/antity": "0.16.0",
     "@dwtechs/sparray": "0.2.1",
     "pg": "8.13.1"
   },