@imqueue/pg-sequelize 4.2.0

package/README.md

@@ -0,0 +1,94 @@
+# @imqueue/pg-sequelize
+
+[![Build Status](https://img.shields.io/github/actions/workflow/status/imqueue/pg-sequelize/build.yml)](https://github.com/imqueue/pg-sequelize)
+[![Known Vulnerabilities](https://snyk.io/test/github/imqueue/pg-sequelize/badge.svg?targetFile=package.json)](https://snyk.io/test/github/imqueue/pg-sequelize?targetFile=package.json)
+[![License](https://img.shields.io/badge/license-GPL-blue.svg)](https://github.com/imqueue/pg-sequelize/blob/master/LICENSE)
+
+Turns a query described as data — a filter, a page, an order and the fields the caller
+actually needs — into one efficient Sequelize statement. Plus database views as models,
+the Postgres index options Sequelize cannot express, and a single import surface for the
+whole ORM stack.
+
+# Sequelize v6, and the alternative
+
+This targets Sequelize v6 — a mature line, proven in production, and the one this
+package is actively developed against. Sequelize v7 is still in alpha upstream, so v6 is
+what there is to build on today; if v7 lands, this follows it.
+
+If you would rather build on Prisma,
+[@imqueue/pg-prisma](https://github.com/imqueue/pg-prisma) covers the same ground for
+that stack. Both are supported — pick the ORM you want to live with.
+
+# Renamed
+
+This package was called `@imqueue/sequelize` up to and including 4.1.3. The old
+name is deprecated on npm and receives no further releases; there is no
+compatibility shim. To migrate, change the dependency and every import specifier
+— no export changed name or signature, and the `pg-` prefix only states what was
+always true: this targets Postgres specifically, not every Sequelize dialect.
+
+# Install
+
+~~~bash
+npm i --save @imqueue/pg-sequelize
+~~~
+
+# Usage
+
+Connect once, anywhere in the service. Every later call hands back the same instance, so
+only the first one needs the configuration:
+
+~~~typescript
+import { database, query } from '@imqueue/pg-sequelize';
+
+const sequelize = database({
+    logger: console,
+    modelsPath: './src/orm/models',
+    sequelize: {
+        benchmark: true,
+        dialect: 'postgres',
+        storage: 'sequelize',
+        pool: {
+            max: 250,
+            min: 2,
+            idle: 30000,
+            acquire: 30000,
+        },
+    },
+});
+~~~
+
+Then let the caller's own arguments build the query. `autoQuery` reads the requested
+field map, so a column nobody asked for is not selected and a relation nobody reached
+into is not joined:
+
+~~~typescript
+const where = query.toWhereOptions(query.withRangeFilters(filter));
+const rows = await LeadModel.findAll(query.autoQuery<FindOptions>(
+    LeadModel,
+    fields,
+    where,
+    query.toLimitOptions(pageOptions),
+    query.toOrderOptions(orderBy),
+));
+const total = await LeadModel.count(query.autoCountQuery(LeadModel, fields, where));
+~~~
+
+`filter`, `fields`, `pageOptions` and `orderBy` are plain JSON — `FilterInput`,
+`FieldsInput`, `PaginationInput` and `OrderByInput` describe them — because Sequelize
+writes its operators as ES symbols, and a symbol cannot survive a wire format. A GraphQL
+resolver is the case this was written against, passing its arguments and its selected
+field set straight through; an RPC method taking a filter object is the same problem.
+
+# Docs
+
+Every exported symbol carries its own documentation, so an editor is the fastest
+reference. The same content is published, symbol by symbol, as the
+[API reference](https://imqueue.org/api/pg-sequelize/latest/) — searchable, and linkable
+when you need to point someone at one thing. The wider ecosystem documentation is at
+[imqueue.org](https://imqueue.org/docs/).
+
+## License
+
+This project is licensed under the GNU General Public License v3.0.
+See the [LICENSE](LICENSE)

package/SECURITY.md

@@ -0,0 +1,41 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+If you believe you have found a security vulnerability in this `@imqueue` project (or
+any `@imqueue/*` package), please report it **privately** — do not open a public
+issue, pull request, or discussion for it.
+
+Two private channels:
+
+- **GitHub** — use *Security → Report a vulnerability* on this repository to open a
+  private advisory (preferred; it keeps the report and the fix coordinated in one
+  place).
+- **Email** — <support@imqueue.com> with the details below.
+
+Please include:
+
+- the affected package or repository and version(s);
+- a description of the issue and its impact;
+- steps to reproduce, or a proof of concept, where possible.
+
+## What to expect
+
+- We aim to acknowledge a report within a few business days.
+- We'll confirm the issue, keep you updated on progress, and coordinate a fix and a
+  disclosure timeline with you.
+- Once a fix is released we'll credit the reporter in the advisory unless you prefer
+  to remain anonymous.
+
+## Supported versions
+
+Security fixes land on the latest published release line of each `@imqueue/*`
+package on npm. Please make sure you can reproduce an issue against the current
+release before reporting.
+
+## Scope
+
+The `@imqueue` framework is open source under GPL-3.0. This policy covers the code
+in the `@imqueue/*` packages and the project repositories. Vulnerabilities in
+third-party dependencies should be reported to those projects, though we're glad to
+help coordinate an upgrade.

package/index.d.ts

@@ -0,0 +1,86 @@
+/*!
+ * @imqueue/pg-sequelize - Sequelize ORM refines for @imqueue
+ *
+ * I'm Queue Software Project
+ * Copyright (C) 2025  imqueue.com <support@imqueue.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ *
+ * If you want to use this code in a closed source (commercial) project, you can
+ * purchase a proprietary commercial license. Please contact us at
+ * <support@imqueue.com> to get commercial licensing options.
+ */
+/**
+ * Sequelize and `sequelize-typescript`, refined for `@imqueue` services.
+ *
+ * The problem it was built for: a caller describes the query it wants as DATA — a
+ * filter, a page, an order, and the fields it actually needs — and the service has to
+ * turn that into one efficient statement, without trusting any of it and without
+ * knowing in advance which shape will arrive. Anything can hand you a query described
+ * that way; a GraphQL API is the case this was written against, where a resolver passes
+ * the arguments and the selected field set through almost untouched and gets back a
+ * query that selects the columns asked for, joins only the relations the selection
+ * reaches into, and filters on values that arrived as JSON. An RPC method taking a
+ * filter object, or a REST endpoint with query parameters, is the same problem with
+ * different packaging.
+ *
+ * Which version, and which package. This targets Sequelize v6 — mature, proven in
+ * production, and what this package is actively developed against. Sequelize v7 is
+ * still in alpha upstream, so v6 is the line to build on for now, and if v7 lands this
+ * follows it. If you would rather build on Prisma, `@imqueue/pg-prisma` covers the same
+ * ground for that stack. Both are supported: pick the ORM you want to live with.
+ *
+ * The `query` namespace and the serializable input types are what do it. Sequelize
+ * writes a filter with ES symbols as its operators, and a symbol cannot survive a JSON
+ * payload, so {@link FilterInput}, {@link FieldsInput}, {@link PaginationInput} and
+ * {@link OrderByInput} give the wire an equivalent that can. `query.autoQuery` turns
+ * them back into Sequelize options, and builds the `include` tree the requested fields
+ * imply — which is where the efficiency comes from: a field nobody asked for is not
+ * selected, and a relation nobody reached into is not joined.
+ *
+ * {@link database} builds and caches the connection and discovers your compiled model
+ * files. It is a process-wide singleton: the first call configures it, every later one
+ * hands back the same instance, and SQL logging that can prettify and colourise
+ * statements is installed along the way.
+ *
+ * It is also the single import surface for the ORM stack, which is what most files in
+ * a service touch it for. Everything `sequelize` and `sequelize-typescript` export is
+ * re-exported here — `Table`, `Column`, `DataType`, `AllowNull`, `ForeignKey`,
+ * `BelongsTo`, `HasMany`, `QueryInterface` and the rest — so a model imports from one
+ * place rather than three, and several option types are widened on the way through
+ * (see {@link ReturningOptions}). A migration usually needs nothing but
+ * `QueryInterface`.
+ *
+ * The decorators are the smallest part and the most opinionated: {@link CreatedBy},
+ * {@link UpdatedBy} and {@link DeletedBy} stamp the acting user from the RPC request
+ * context, {@link AssociatedWith} declares a relation the query helpers can walk, and
+ * `View` and `DynamicView` let a model be a database view — a parameterised one, whose
+ * placeholders are filled in per query.
+ *
+ * @example
+ * ```typescript
+ * // the shape every paginated read method in a service ends up with
+ * const where = query.toWhereOptions(query.withRangeFilters(filter));
+ * const rows = await LeadModel.findAll(query.autoQuery<FindOptions>(
+ *     LeadModel,
+ *     fields,
+ *     where,
+ *     query.toLimitOptions(pageOptions),
+ *     query.toOrderOptions(orderBy),
+ * ));
+ * ```
+ *
+ * @packageDocumentation
+ */
+export * from './src/index.js';

package/index.js

@@ -0,0 +1,87 @@
+/*!
+ * @imqueue/pg-sequelize - Sequelize ORM refines for @imqueue
+ *
+ * I'm Queue Software Project
+ * Copyright (C) 2025  imqueue.com <support@imqueue.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ *
+ * If you want to use this code in a closed source (commercial) project, you can
+ * purchase a proprietary commercial license. Please contact us at
+ * <support@imqueue.com> to get commercial licensing options.
+ */
+/**
+ * Sequelize and `sequelize-typescript`, refined for `@imqueue` services.
+ *
+ * The problem it was built for: a caller describes the query it wants as DATA — a
+ * filter, a page, an order, and the fields it actually needs — and the service has to
+ * turn that into one efficient statement, without trusting any of it and without
+ * knowing in advance which shape will arrive. Anything can hand you a query described
+ * that way; a GraphQL API is the case this was written against, where a resolver passes
+ * the arguments and the selected field set through almost untouched and gets back a
+ * query that selects the columns asked for, joins only the relations the selection
+ * reaches into, and filters on values that arrived as JSON. An RPC method taking a
+ * filter object, or a REST endpoint with query parameters, is the same problem with
+ * different packaging.
+ *
+ * Which version, and which package. This targets Sequelize v6 — mature, proven in
+ * production, and what this package is actively developed against. Sequelize v7 is
+ * still in alpha upstream, so v6 is the line to build on for now, and if v7 lands this
+ * follows it. If you would rather build on Prisma, `@imqueue/pg-prisma` covers the same
+ * ground for that stack. Both are supported: pick the ORM you want to live with.
+ *
+ * The `query` namespace and the serializable input types are what do it. Sequelize
+ * writes a filter with ES symbols as its operators, and a symbol cannot survive a JSON
+ * payload, so {@link FilterInput}, {@link FieldsInput}, {@link PaginationInput} and
+ * {@link OrderByInput} give the wire an equivalent that can. `query.autoQuery` turns
+ * them back into Sequelize options, and builds the `include` tree the requested fields
+ * imply — which is where the efficiency comes from: a field nobody asked for is not
+ * selected, and a relation nobody reached into is not joined.
+ *
+ * {@link database} builds and caches the connection and discovers your compiled model
+ * files. It is a process-wide singleton: the first call configures it, every later one
+ * hands back the same instance, and SQL logging that can prettify and colourise
+ * statements is installed along the way.
+ *
+ * It is also the single import surface for the ORM stack, which is what most files in
+ * a service touch it for. Everything `sequelize` and `sequelize-typescript` export is
+ * re-exported here — `Table`, `Column`, `DataType`, `AllowNull`, `ForeignKey`,
+ * `BelongsTo`, `HasMany`, `QueryInterface` and the rest — so a model imports from one
+ * place rather than three, and several option types are widened on the way through
+ * (see {@link ReturningOptions}). A migration usually needs nothing but
+ * `QueryInterface`.
+ *
+ * The decorators are the smallest part and the most opinionated: {@link CreatedBy},
+ * {@link UpdatedBy} and {@link DeletedBy} stamp the acting user from the RPC request
+ * context, {@link AssociatedWith} declares a relation the query helpers can walk, and
+ * `View` and `DynamicView` let a model be a database view — a parameterised one, whose
+ * placeholders are filled in per query.
+ *
+ * @example
+ * ```typescript
+ * // the shape every paginated read method in a service ends up with
+ * const where = query.toWhereOptions(query.withRangeFilters(filter));
+ * const rows = await LeadModel.findAll(query.autoQuery<FindOptions>(
+ *     LeadModel,
+ *     fields,
+ *     where,
+ *     query.toLimitOptions(pageOptions),
+ *     query.toOrderOptions(orderBy),
+ * ));
+ * ```
+ *
+ * @packageDocumentation
+ */
+export * from './src/index.js';
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@imqueue/pg-sequelize",
+  "version": "4.2.0",
+  "description": "Sequelize/Postgres toolkit for @imqueue microservices — turns a query described as data (filters, paging, ordering, fields) into one efficient statement, plus database views as models and the Postgres index options Sequelize cannot express",
+  "keywords": [
+    "imqueue",
+    "imq",
+    "sequelize",
+    "postgres",
+    "postgresql",
+    "pg",
+    "orm",
+    "typescript",
+    "graphql",
+    "microservices"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean-compiled": "npm run clean-js && npm run clean-typedefs && npm run clean-maps",
+    "build": "npm run clean-compiled && tsc",
+    "prepare": "npm run build",
+    "lint": "oxlint",
+    "format": "oxfmt \"index.ts\" \"src/**/*.ts\" \"test/**/*.ts\"",
+    "format:check": "oxfmt --check \"index.ts\" \"src/**/*.ts\" \"test/**/*.ts\"",
+    "test": "npm run build && node --test --test-timeout=15000 $(find test -name '*.spec.js')",
+    "test-coverage": "npm run build && node --enable-source-maps --test --experimental-test-coverage --test-timeout=15000 $(find test -name '*.spec.js')",
+    "test-lcov": "npm run build && mkdir -p coverage && node --enable-source-maps --test --experimental-test-coverage --test-reporter=lcov --test-reporter-destination=coverage/lcov.info --test-timeout=15000 $(find test -name '*.spec.js'); node scripts/strip-comment-coverage.mjs coverage/lcov.info",
+    "test-coverage-html": "npm run test-lcov; genhtml coverage/lcov.info --output-directory coverage/html --ignore-errors inconsistent,corrupt,format,mismatch && echo \"Coverage report: file://$(pwd)/coverage/html/index.html\"",
+    "test-dev": "npm run test && npm run clean-js && npm run clean-typedefs && npm run clean-maps",
+    "clean-typedefs": "find . -name '*.d.ts' -not -wholename '*node_modules*' -type f -delete",
+    "clean-maps": "find . -name '*.js.map' -not -wholename '*node_modules*' -type f -delete",
+    "clean-js": "find . -name '*.js' -not -wholename '*node_modules*' -type f -delete",
+    "clean-tests": "rm -rf .nyc_output coverage",
+    "clean": "npm run clean-tests && npm run clean-typedefs && npm run clean-maps && npm run clean-js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/imqueue/pg-sequelize.git"
+  },
+  "bugs": {
+    "url": "https://github.com/imqueue/pg-sequelize/issues"
+  },
+  "homepage": "https://imqueue.org/",
+  "author": "imqueue.com <support@imqueue.com>",
+  "license": "GPL-3.0-only",
+  "dependencies": {
+    "@imqueue/rpc": "^3.4.1",
+    "pg": "^8.22.0",
+    "reflect-metadata": "^0.2.2",
+    "sequelize": "^6.37.8",
+    "sequelize-typescript": "^2.1.6",
+    "sql-formatter": "^15.8.2"
+  },
+  "devDependencies": {
+    "@types/node": "^24.9.1",
+    "oxfmt": "0.57.0",
+    "oxlint": "1.72.0",
+    "typescript": "^7.0.2"
+  },
+  "main": "index.js",
+  "types": "index.d.ts",
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./package.json": "./package.json"
+  }
+}