{"id":30464954,"url":"https://github.com/dwtechs/antity-pgsql.js","last_synced_at":"2026-04-18T16:11:54.598Z","repository":{"id":310215410,"uuid":"917935152","full_name":"DWTechs/Antity-pgsql.js","owner":"DWTechs","description":"Open source library to add PostgreSQL support to @dwtechs/Antity entities","archived":false,"fork":false,"pushed_at":"2026-04-10T09:01:48.000Z","size":508,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-10T10:39:07.289Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DWTechs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-01-16T23:20:01.000Z","updated_at":"2026-04-10T09:01:57.000Z","dependencies_parsed_at":"2025-09-26T17:02:30.683Z","dependency_job_id":"fc9e05eb-a7c1-4590-9f3c-7227537e1bca","html_url":"https://github.com/DWTechs/Antity-pgsql.js","commit_stats":null,"previous_names":["dwtechs/antity-pgsql.js"],"tags_count":31,"template":false,"template_full_name":null,"purl":"pkg:github/DWTechs/Antity-pgsql.js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DWTechs%2FAntity-pgsql.js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DWTechs%2FAntity-pgsql.js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DWTechs%2FAntity-pgsql.js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DWTechs%2FAntity-pgsql.js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DWTechs","download_url":"https://codeload.github.com/DWTechs/Antity-pgsql.js/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DWTechs%2FAntity-pgsql.js/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31975037,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"online","status_checked_at":"2026-04-18T02:00:07.018Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-24T02:44:10.528Z","updated_at":"2026-04-18T16:11:54.587Z","avatar_url":"https://github.com/DWTechs.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n[![License: MIT](https://img.shields.io/npm/l/@dwtechs/antity-pgsql.svg?color=brightgreen)](https://opensource.org/licenses/MIT)\n[![npm version](https://badge.fury.io/js/%40dwtechs%2Fantity-pgsql.svg)](https://www.npmjs.com/package/@dwtechs/antity-pgsql)\n[![last version release date](https://img.shields.io/github/release-date/DWTechs/Antity-pgsql.js)](https://www.npmjs.com/package/@dwtechs/antity-pgsql)\n![Jest:coverage](https://img.shields.io/badge/Jest:coverage-87%25-brightgreen.svg)\n\n- [Synopsis](#synopsis)\n- [Support](#support)\n- [Installation](#installation)\n- [Usage](#usage)\n- [API Reference](#api-reference)\n- [Contributors](#contributors)\n- [Stack](#stack)\n\n\n## Synopsis\n\n**[Antity-pgsql.js](https://github.com/DWTechs/Antity-pgsql.js)** adds PostgreSQL features to **Antity.js** library.\n\n- 🪶 Very lightweight\n- 🧪 Thoroughly tested\n- 🚚 Shipped as EcmaScrypt module\n- 📝 Written in Typescript\n\n## Installation\n\n```bash\n$ npm i @dwtechs/antity-pgsql\n```\n\n## Usage\n\n```javascript\n\nimport { SQLEntity } from \"@dwtechs/antity-pgsql\";\nimport { normalizeName, normalizeNickname } from \"@dwtechs/checkard\";\n\n// Create entity with default 'public' schema\nconst entity = new SQLEntity(\"consumers\", [\n  // properties...\n]);\n\n// Or specify a custom schema\nconst customEntity = new SQLEntity(\"consumers\", [\n  // properties...\n], \"myschema\");\n\n// Example with all properties\nconst entity = new SQLEntity(\"consumers\", [\n  {\n    key: \"id\",\n    type: \"integer\",\n    min: 0,\n    max: 120,\n    isTypeChecked: true,\n    isFilterable: true,\n    requiredFor: [\"PUT\"],\n    operations: [\"SELECT\", \"UPDATE\"],\n    isPrivate: false,\n    sanitizer: null,\n    normalizer: null,\n    validator: null,\n  },\n  {\n    key: \"firstName\",\n    type: \"string\",\n    min: 0,\n    max: 255,\n    isTypeChecked: true,\n    isFilterable: false,\n    requiredFor: [\"POST\", \"PUT\"],\n    operations: [\"SELECT\", \"UPDATE\"],\n    isPrivate: false,\n    sanitizer: null,\n    normalizer: normalizeName,\n    validator: null,\n  },\n  {\n    key: \"lastName\",\n    type: \"string\",\n    min: 0,\n    max: 255,\n    isTypeChecked: true,\n    isFilterable: false,\n    requiredFor: [\"POST\", \"PUT\"],\n    operations: [\"SELECT\", \"UPDATE\"],\n    isPrivate: false,\n    sanitizer: null,\n    normalizer: normalizeName,\n    validator: null,\n  },\n  {\n    key: \"nickname\",\n    type: \"string\",\n    min: 0,\n    max: 255,\n    isTypeChecked: true,\n    isFilterable: true,\n    requiredFor: [\"POST\", \"PUT\"],\n    operations: [\"SELECT\", \"UPDATE\"],\n    isPrivate: false,\n    sanitizer: null,\n    normalizer: normalizeNickname,\n    validator: null,\n  },\n]);\n\nrouter.get(\"/\", ..., entity.get);\n\n// Using substacks (recommended) - combines normalize, validate, and database operation\nrouter.post(\"/\", ...entity.addArraySubstack);\nrouter.put(\"/\", ...entity.updateArraySubstack);\nrouter.put(\"/preferences\", ...entity.syncArraySubstack);\n\n// Or manually chain middlewares\nrouter.post(\"/manual\", entity.normalizeArray, entity.validateArray, ..., entity.add);\nrouter.put(\"/manual\", entity.normalizeArray, entity.validateArray, ..., entity.update);\n\nrouter.patch(\"/archive\", ..., entity.archive);\nrouter.delete(\"/\", ..., entity.delete);\nrouter.delete(\"/archived\", ..., entity.deleteArchive);\nrouter.get(\"/:id/history\", ..., entity.getHistory);\n\n```\n\n### Expected table structure\n\n```sql\nCREATE TABLE IF NOT EXISTS \"service\" (\n  id SERIAL PRIMARY KEY,\n  name varchar(20) NOT NULL,\n  pattern TEXT,\n  archived BOOLEAN DEFAULT FALSE,\n  \"archivedAt\" TIMESTAMP,\n  \"creatorId\" INT,\n  \"creatorName\" TEXT,\n  \"updaterId\" INT,\n  \"updaterName\" TEXT,\n  \"createdAt\" TIMESTAMP DEFAULT NOW(),\n  \"updatedAt\" TIMESTAMP NULL\n);\n```\n\n## API Reference\n\n\n```javascript\n\ntype Operation = \"SELECT\" | \"INSERT\" | \"UPDATE\";\n\ntype Row = Record\u003cstring, string | number | boolean | Date | number[]\u003e;\n\ntype MatchMode =  \n  \"startsWith\" | \n  \"endsWith\" |\n  \"contains\" |\n  \"notContains\" |\n  \"equals\" |\n  \"notEquals\" |\n  \"between\" |\n  \"in\" |\n  \"notIn\" |\n  \"lt\" |\n  \"lte\" |\n  \"gt\" |\n  \"gte\" |\n  \"is\" |\n  \"isNot\" |\n  \"before\" |\n  \"after\" |\n  \"st_contains\" |\n  \"st_dwithin\";\n\n\ntype Filters = {\n  [key: string]: Filter | Filter[]; // Supports both simple (object) and complex (array) formats\n}\n\ntype Filter = {\n  value: string | number | boolean | Date | number[];\n  matchMode?: MatchMode;\n  operator?: string; // 'and' | 'or' - Used when multiple filters apply to the same property\n}\n\ntype PGClient = {\n  query(text: string, values?: unknown[]): Promise\u003cPGResponse\u003e;\n};\n\ntype PGResponse = {\n  rows: Record\u003cstring, unknown\u003e[];\n  rowCount: number | null;\n  total?: number;\n};\n\ntype SelectResponse = {\n  rows: Record\u003cstring, unknown\u003e[];\n  total?: number;\n};\n\ntype ExpressMiddleware = (req: Request, res: Response, next: NextFunction) =\u003e void;\ntype ExpressMiddlewareAsync = (req: Request, res: Response, next: NextFunction) =\u003e Promise\u003cvoid\u003e;\ntype SubstackTuple = [ExpressMiddleware, ExpressMiddleware, ExpressMiddlewareAsync];\n\nclass SQLEntity {\n  constructor(name: string, properties: Property[], schema?: string);\n  get name(): string;\n  get table(): string;\n  get schema(): string;\n  get privateProps(): string[];\n  get properties(): Property[];\n  set name(name: string);\n  set table(table: string);\n  set schema(schema: string);\n\n  // Middleware substacks (combine normalize, validate, and operation)\n  get addArraySubstack(): SubstackTuple;\n  get addOneSubstack(): SubstackTuple;\n  get updateArraySubstack(): SubstackTuple;\n  get updateOneSubstack(): SubstackTuple;\n  get upsertArraySubstack(): SubstackTuple;\n  get upsertOneSubstack(): SubstackTuple;\n  get syncArraySubstack(): SubstackTuple;\n\n  query: {\n    select: (\n      first?: number,\n      rows?: number | null,\n      sortField?: string | null,\n      sortOrder?: \"ASC\" | \"DESC\" | null,\n      filters?: Filters | null) =\u003e {\n        query: string;\n        args: (Filter[\"value\"])[];\n      };\n    update: (\n      rows: Row[],\n      consumer?: { id?: number | string, nickname?: string }) =\u003e {\n        query: string;\n        args: unknown[];\n    };\n    archive: (\n      rows: Row[],\n      consumer?: { id?: number | string, nickname?: string }) =\u003e {\n        query: string;\n        args: unknown[];\n    };\n    insert: (\n      rows: Row[],\n      consumer?: { id?: number | string, nickname?: string },\n      rtn?: string) =\u003e {\n        query: string;\n          args: unknown[];\n      };\n    upsert: (\n      rows: Row[],\n      conflictTarget: string | string[],\n      consumer?: { id?: number | string, nickname?: string },\n      rtn?: string) =\u003e {\n        query: string;\n        args: unknown[];\n      };\n    delete: (ids: number[]) =\u003e {\n      query: string;\n      args: number[];\n    };\n    deleteArchive: () =\u003e string;\n    return: (prop: string) =\u003e string;\n  };\n  get: (req: Request, res: Response, next: NextFunction) =\u003e void;\n  add: (req: Request, res: Response, next: NextFunction) =\u003e Promise\u003cvoid\u003e;\n  update: (req: Request, res: Response, next: NextFunction) =\u003e Promise\u003cvoid\u003e;\n  upsert: (req: Request, res: Response, next: NextFunction) =\u003e Promise\u003cvoid\u003e;\n  sync: (req: Request, res: Response, next: NextFunction) =\u003e Promise\u003cvoid\u003e;\n  archive: (req: Request, res: Response, next: NextFunction) =\u003e Promise\u003cvoid\u003e;\n  delete: (req: Request, res: Response, next: NextFunction) =\u003e Promise\u003cvoid\u003e;\n  deleteArchive: (req: Request, res: Response, next: NextFunction) =\u003e void;\n  getHistory: (req: Request, res: Response, next: NextFunction) =\u003e Promise\u003cvoid\u003e;\n\n}\n\nfunction filter(\n  first: number,\n  rows: number | null,\n  sortField: string | null,\n  sortOrder: Sort | null,\n  filters: Filters | null,\n): { filterClause: string, args: (Filter[\"value\"])[] };\n\nfunction execute(\n  query: string, \n  args: (string | number | boolean | Date | number[])[], \n  client: PGClient | null,\n): Promise\u003cPGResponse\u003e;\n\n\n```\n\n### Middleware Methods for Express.js\n\nget(), add(), update(), upsert(), sync(), archive(), delete(), deleteArchive() and getHistory() methods are made to be used as Express.js middlewares.\nEach method will look for data to work on in the **req.body.rows** parameter.\n\nThe upsert() method additionally requires **req.body.conflictTarget** to specify which column(s) define uniqueness.\n\nThe sync() method accepts an optional **req.body.idField** (defaults to `'id'`) and optional **req.body.filters** to scope which existing rows are considered part of the managed set.\n\n### Schema Qualification\n\nAll SQL queries generated by Antity-pgsql use schema-qualified table names (e.g., `schema.table`). This provides:\n- **Security**: Protection against search_path manipulation attacks, especially important when using SECURITY DEFINER functions\n- **Clarity**: Explicit schema references make queries more readable and maintainable\n- **Flexibility**: Easy multi-schema support within the same application\n\nThe default schema is `'public'` but can be customized via the constructor's third parameter or the `schema` setter.\n\n### Middleware Substacks\n\nSubstacks are pre-composed middleware chains that combine normalization, validation, and database operations:\n\n- **addArraySubstack**: Combines `normalizeArray`, `validateArray`, and `add`. Use this for POST routes with `req.body.rows` containing multiple objects.\n- **addOneSubstack**: Combines `normalizeOne`, `validateOne`, and `add`. Use this for POST routes with `req.body` containing a single object.\n- **updateArraySubstack**: Combines `normalizeArray`, `validateArray`, and `update`. Use this for PUT routes with `req.body.rows` containing multiple objects.\n- **updateOneSubstack**: Combines `normalizeOne`, `validateOne`, and `update`. Use this for PUT routes with `req.body` containing a single object.\n- **upsertArraySubstack**: Combines `normalizeArray`, `validateArray`, and `upsert`. Use this for upsert routes with `req.body.rows` containing multiple objects. Requires `req.body.conflictTarget`.\n- **upsertOneSubstack**: Combines `normalizeOne`, `validateOne`, and `upsert`. Use this for upsert routes with `req.body` containing a single object. Requires `req.body.conflictTarget`.\n- **syncArraySubstack**: Combines `normalizeArray`, `validateArray`, and `sync`. Use this for bulk-sync routes with `req.body.rows` containing the full desired state. Rows are inserted, updated, or deleted as needed. Accepts optional `req.body.idField` and `req.body.filters`.\n\nUsing substacks simplifies your route definitions and ensures consistent data processing.\n\n### Query Methods\n\n- **query.select()**: Generates a SELECT query. When the `rows` parameter is provided (not null), pagination is automatically enabled and the query includes `COUNT(*) OVER () AS total` to return the total number of rows. The total count is extracted from results and returned separately from the row data.\n- **query.insert()**: Generates an INSERT query. Accepts an array of `Row` objects with properties matching the entity definition. Consumer fields are appended directly to the query arguments — row objects are **not mutated**. Optionally appends `consumer.id` as `creatorId` and `consumer.nickname` as `creatorName` for audit tracking. Supports `RETURNING` clause via the `rtn` parameter.\n- **query.update()**: Generates an UPDATE query using CASE statements. Accepts an array of `Row` objects with `id` property. Optionally appends `consumer.id` as `updaterId` and `consumer.nickname` as `updaterName` for audit tracking.\n- **query.upsert()**: Generates an INSERT ... ON CONFLICT ... DO UPDATE query. (See [Upsert](#upsert-insert-or-update) section below.) Accepts an array of `Row` objects and a `conflictTarget` (single column name or array of column names) that defines uniqueness. If a conflict occurs on the specified column(s), the row is updated; otherwise, it is inserted. Properties are automatically included if they have both INSERT and UPDATE operations. Consumer fields are appended directly to the query arguments — row objects are **not mutated**. Optionally appends `consumer.id` as `creatorId` and `consumer.nickname` as `creatorName` for audit tracking. Supports `RETURNING` clause via the `rtn` parameter.\n- **query.archive()**: Generates a simplified `UPDATE ... SET archived = true WHERE id IN (...)` query. Accepts an array of `Row` objects with `id` property. Optionally appends `consumer.id` as `updaterId` and `consumer.nickname` as `updaterName` for audit tracking. Does not require an `archived` field in the rows — it is set directly in the SQL.\n- **sync()**: Atomically synchronises the table with the provided rows inside a single PostgreSQL transaction. Missing rows are inserted, existing rows are updated, and rows absent from the list are deleted. Accepts optional `idField` (default `'id'`) and `filters` to restrict the scope of managed rows. Stores the result in `res.locals.rows` and a summary `{ inserted, updated, deleted }` in `res.locals.sync`.\n- **delete()**: Deletes rows by their IDs. Expects `req.body.rows` to be an array of objects with `id` property: `[{id: 1}, {id: 2}]`\n- **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.\n- **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.\n\n### Bulk Sync\n\nThe sync functionality atomically replaces the managed set of rows in a table with the supplied list. It combines insert, update, and delete in a single PostgreSQL **transaction** — either all changes succeed or none do.\n\n#### How It Works\n\n1. **Fetch existing IDs**: A `SELECT id FROM table` is issued, optionally scoped by `filters`.\n2. **Diff**: Incoming rows without an ID (or with an unknown ID) are inserted; rows with a known ID are updated; existing IDs absent from the incoming list are deleted — all within the same filter scope.\n3. **Transaction**: All three operations run inside `BEGIN` / `COMMIT`. A failure at any step triggers `ROLLBACK`.\n4. **Result**: `res.locals.rows` contains the full synced list (with generated IDs filled in for inserts). `res.locals.sync` contains `{ inserted, updated, deleted }` counts.\n\n#### Usage Examples\n\n**Using the middleware:**\n\n```javascript\n// Route definition\nrouter.put('/users/sync', ...entity.syncArraySubstack);\n\n// Request body — send the entire desired state\n{\n  rows: [\n    { id: 1, name: 'John Updated', email: 'john@example.com', age: 31 }, // update\n    { name: 'Jane New', email: 'jane@example.com', age: 25 }             // insert\n    // id: 2 is absent → will be deleted\n  ],\n  idField: 'id' // optional, defaults to 'id'\n}\n```\n\n**Scoping with filters (only manage a subset of rows):**\n\n```javascript\n// Only sync rows where age \u003e= 18 — rows outside this filter are left untouched\n{\n  rows: [\n    { id: 1, name: 'John', email: 'john@example.com', age: 30 }\n  ],\n  filters: {\n    age: { value: 18, matchMode: 'gte' }\n  }\n}\n```\n\n**Response locals after sync:**\n\n```javascript\nres.locals.rows  // full list of synced rows (inserts have their new id)\nres.locals.sync  // { inserted: 1, updated: 1, deleted: 1 }\n```\n\n#### Important Notes\n\n- **Atomic**: All insert / update / delete operations are wrapped in a single transaction.\n- **Filter scope**: When `filters` are provided, only rows matching the filter are considered \"managed\". Rows outside the filter are never touched.\n- **Property selection**: Insert uses `INSERT` properties; update uses `UPDATE` properties — same as the standalone `add` and `update` middlewares.\n- **Consumer tracking**: `consumer.id` and `consumer.nickname` from `res.locals.consumer` are forwarded to inserts as `creatorId`/`creatorName` and to updates as `updaterId`/`updaterName` for audit tracking.\n\n### Upsert (Insert or Update)\n\nThe upsert functionality uses PostgreSQL's `INSERT ... ON CONFLICT ... DO UPDATE` syntax to insert rows or update them if they already exist based on a unique constraint.\n\n#### How It Works\n\n1. **Conflict Target**: You specify which column(s) define uniqueness (e.g., `'id'`, `'email'`, or `['name', 'email']`)\n2. **Property Selection**: Properties are automatically included if they have **both** `INSERT` and `UPDATE` in their `operations` array\n3. **On Conflict**: When a conflict occurs, all columns except the conflict target are updated\n\n#### Usage Examples\n\n**Using the middleware with a single conflict target:**\n\n```javascript\n// Route definition\nrouter.post('/users/upsert', ...entity.upsertArraySubstack);\n\n// Request body\n{\n  rows: [\n    { id: 1, name: 'John Updated', email: 'john@example.com' },\n    { name: 'Jane New', email: 'jane@example.com' }\n  ],\n  conflictTarget: 'id'\n}\n```\n\n**Using email as conflict target:**\n\n```javascript\n// If a user with this email exists, update their name; otherwise, insert\n{\n  rows: [\n    { name: 'John', email: 'john@example.com', age: 30 }\n  ],\n  conflictTarget: 'email'\n}\n```\n\n**Using multiple columns as conflict target:**\n\n```javascript\n// Unique constraint on combination of name and email\n{\n  rows: [\n    { name: 'John', email: 'john@example.com', age: 30 }\n  ],\n  conflictTarget: ['name', 'email']\n}\n```\n\n**Using the query generator directly:**\n\n```javascript\nconst { query, args } = entity.query.upsert(\n  [{ id: 1, name: 'John', email: 'john@example.com' }],\n  'id',\n  { id: 1, nickname: 'admin' }, // consumer (optional)\n  'RETURNING id' // return clause (optional)\n);\n// Generates:\n// INSERT INTO public.users (name, email, creatorId, name)\n// VALUES ($1, $2, $3, $4)\n// ON CONFLICT (id) DO UPDATE SET \n//   name = EXCLUDED.name,\n//   email = EXCLUDED.email,\n//   creatorId = EXCLUDED.creatorId,\n//   name = EXCLUDED.name\n// RETURNING id\n```\n\n#### Property Configuration for Upsert\n\nProperties are automatically included in upsert if they have both INSERT and UPDATE operations:\n\n```javascript\n{\n  key: 'name',\n  operations: ['SELECT', 'INSERT', 'UPDATE'] // Included in upsert\n}\n\n{\n  key: 'id',\n  operations: ['SELECT', 'UPDATE'] // NOT included (no INSERT)\n}\n\n{\n  key: 'createdAt',\n  operations: ['SELECT', 'INSERT'] // NOT included (no UPDATE)\n}\n```\n\n#### Important Notes\n\n- **Conflict Target Required**: The `conflictTarget` parameter must specify an existing unique constraint or primary key\n- **Mixed Rows**: You can upsert rows with and without IDs in the same request if your conflict target handles it (e.g., using `SERIAL` primary key)\n- **Atomic Operation**: Unlike separate insert/update calls, upsert is a single atomic database operation\n- **Concurrent Safety**: Prevents race conditions when multiple requests try to create the same record\n\n### Filters\n\nFilters support two formats for maximum flexibility:\n\n#### Simple Format (Single Filter per Property)\n\nBackward-compatible format using a single filter object:\n\n```javascript\nconst filters = {\n  name: { value: 'John', matchMode: 'contains' },\n  age: { value: 30, matchMode: 'equals' },\n  archived: { value: false, matchMode: 'equals' }\n};\n```\n\n#### Complex Format (Multiple Filters per Property)\n\nArray-based format supporting multiple filters with logical operators:\n\n```javascript\nconst filters = {\n  // Multiple filters on the same property with OR operator\n  name: [\n    { value: 'John', matchMode: 'contains', operator: 'or' },\n    { value: 'Jane', matchMode: 'contains', operator: 'or' }\n  ],\n  // Age range with AND operator\n  age: [\n    { value: 18, matchMode: 'gte', operator: 'and' },\n    { value: 65, matchMode: 'lte', operator: 'and' }\n  ],\n  // Single filter in array format\n  archived: [{ value: false, matchMode: 'equals' }]\n};\n```\n\nThis generates SQL like:\n```sql\nWHERE (name LIKE '%John%' OR name LIKE '%Jane%') \n  AND (age \u003e= 18 AND age \u003c= 65) \n  AND archived = false\n```\n\n**Notes:**\n- Both formats can be mixed in the same filters object\n- When using arrays with a single filter, the operator is optional\n- Default operator is 'AND' if not specified\n- The operator field is case-insensitive\n\n\n## Match modes\n\nList of possible match modes :  \n\n| Name        | alias | types                   | Description |\n| :---------- | :---- | :---------------------- | :-------------------------------------------------------- |\n| startsWith  |       | string                  | Whether the value starts with the filter value |\n| contains\t  |       | string                  | Whether the value contains the filter value |\n| endsWith    |       | string                  | Whether the value ends with the filter value |\n| notContains |       | string                  | Whether the value does not contain filter value |\n| equals\t  |       | string \\| number        | Whether the value equals the filter value |\n| notEquals\t  |       | string \\| number        | Whether the value does not equal the filter value |\n| in\t      |       | string[] \\| number[]    | Whether the value is included in the list |\n| notIn\t      |       | string[] \\| number[]    | Whether the value is not included in the list |\n| lt\t      |       | string \\| number        | Whether the value is less than the filter value |\n| lte\t      |       | string \\| number        | Whether the value is less than or equals to the filter value |\n| gt\t      |       | string \\| number        | Whether the value is greater than the filter value |\n| gte\t      |       | string \\| number        | Whether the value is greater than or equals to the filter value |\n| is\t      |       | date \\| boolean \\| null | Whether the value equals the filter value, alias to equals |\n| isNot\t      |       | date \\| boolean \\| null | Whether the value does not equal the filter value, alias to notEquals |\n| before      |       | date                    | Whether the date value is before the filter date |\n| after\t      |       | date                    | Whether the date value is after the filter date |\n| between     |       | date[2] \\| number[2]    | Whether the value is between the filter values | \n| st_contains |       | geometry                | Whether the geometry completely contains other geometries |\n| st_dwithin  |       | geometry                | Whether geometries are within a specified distance from another geometry |\n\n## Types\n\nList of compatible match modes for each property types\n\n| Name        | Match modes             |\n| :---------- | :---------------------- | \n| string      | startsWith,\u003cbr\u003econtains,\u003cbr\u003eendsWith,\u003cbr\u003enotContains,\u003cbr\u003eequals,\u003cbr\u003enotEquals,\u003cbr\u003ein,\u003cbr\u003enotIn,\u003cbr\u003elt,\u003cbr\u003elte,\u003cbr\u003egt,\u003cbr\u003egte |\n| number      | equals,\u003cbr\u003enotEquals,\u003cbr\u003ein,\u003cbr\u003enotIn,\u003cbr\u003elt,\u003cbr\u003elte,\u003cbr\u003egt,\u003cbr\u003egte |\n| date        | is,\u003cbr\u003eisNot,\u003cbr\u003ebefore,\u003cbr\u003eafter |\n| boolean     | is,\u003cbr\u003eisNot            |\n| string[]    | in                      |\n| number[]    | in,\u003cbr\u003ebetween          |\n| date[]      | between                 |\n| geometry    | st_contains,\u003cbr\u003est_dwithin |\n\nList of secondary types : \n\n| Name               | equivalent |\n| :----------------- | :--------- | \n| integer            | number     |\n| float              | number     |\n| even               | number     |\n| odd                | number     |\n| positive           | number     |\n| negative           | number     |\n| powerOfTwo         | number     |\n| ascii              | number     |\n| array              | any[]      |\n| jwt                | string     |\n| symbol             | string     |\n| email              | string     |\n| password           | string     |\n| regex              | string     |\n| ipAddress          | string     |\n| slug               | string     |\n| hexadecimal        | string     |\n| date               | date       |\n| timestamp          | date       |\n| function           | string     |\n| htmlElement        | string     |\n| htmlEventAttribute | string     |\n| node               | string     |\n| json               | object     |\n| object             | object     |\n\n\n## Available options for a property\n\nAny of these can be passed into the options object for each function.\n\n| Name            | Type                      |               Description                         |  Default value  |  \n| :-------------- | :------------------------ | :------------------------------------------------ | :-------------- |\n| key             |  string                   | Name of the property                              |\n| type            |  Type                     | Type of the property                              |\n| min             |  number \\| Date           | Minimum value                                     | 0 \\| 1900-01-01\n| max             |  number \\| Date           | Maximum value                                     | 999999999 \\| 2200-12-31\n| requiredFor     |  Method[]                 | property is required for the listed methods only  | [\"PATCH\", \"PUT\", \"POST\"]\n| isPrivate       |  boolean                  | Property is unsafe to send in the response        | true\n| isTypeChecked   |  boolean                  | Type is checked during validation                 | false\n| isFilterable    |  boolean                  | property is filterable in a SELECT operation      | true\n| operations      |  Operation[]              | Property is used for the DML operations only      | [\"SELECT\", \"INSERT\", \"UPDATE\"]\n| sanitizer       |  ((v: unknown) =\u003e unknown) \\| null | Custom sanitizer function if sanitize is true     | null\n| normalizer      |  ((v: unknown) =\u003e unknown) \\| null | Custom Normalizer function if normalize is true   | null\n| validator       |  ((v: unknown) =\u003e unknown) \\| null | validator function if validate is true | null\n\n\n* *Min and max parameters are not used for boolean type*\n* *TypeCheck Parameter is not used for boolean, string and array types*\n\n## Support\n\n| Environment | Version |\n| :---------- | :-----: |\n| Node.js     |  \u003e= 22  |\n\n## Contributors\n\nAntity.js is still in development and we would be glad to get all the help you can provide.\nTo contribute please read **[contributor.md](https://github.com/DWTechs/Antity.js/blob/main/contributor.md)** for detailed installation guide.\n\n## Stack\n\n| Purpose         |                    Choice                    |                                                     Motivation |\n| :-------------- | :------------------------------------------: | -------------------------------------------------------------: |\n| repository      |        [Github](https://github.com/)         |     hosting for software development version control using Git |\n| package manager |     [npm](https://www.npmjs.com/get-npm)     |                                default node.js package manager |\n| language        | [TypeScript](https://www.typescriptlang.org) | static type checking along with the latest ECMAScript features |\n| module bundler  |      [Rollup](https://rollupjs.org)          |                        advanced module bundler for ES6 modules |\n| unit testing    |          [Jest](https://jestjs.io/)          |                  delightful testing with a focus on simplicity |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdwtechs%2Fantity-pgsql.js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdwtechs%2Fantity-pgsql.js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdwtechs%2Fantity-pgsql.js/lists"}