@imqueue/pg-sequelize 4.2.0

package/src/helpers/query.d.ts

@@ -0,0 +1,445 @@
+import { type CountOptions, Transaction } from 'sequelize';
+import { type FindOptions, type IncludeOptions, type ModelAttributes } from 'sequelize';
+import { Model } from 'sequelize-typescript';
+import type { Literal } from 'sequelize/types/utils';
+import type { BaseModel } from '../BaseModel.js';
+import { FieldsInput, OrderByInput, PaginationInput } from '../types/index.js';
+/**
+ * Turns a caller's serialized query into Sequelize options, and back out as SQL.
+ *
+ * @remarks
+ * The reason this package exists. A GraphQL API receives a filter, a page, an order
+ * and the set of fields the query selected — all of it plain JSON, none of it in a
+ * shape Sequelize accepts. These helpers translate: `autoQuery` is the one that
+ * composes the others, `toWhereOptions` turns a serialized filter into a `where` with
+ * the joins its nested parts imply, and `toLimitOptions` and `toOrderOptions` cover
+ * paging and ordering.
+ *
+ * The efficiency comes from the fields map. A column nobody asked for is not selected
+ * and a relation nobody reached into is not joined, so the statement narrows as the
+ * caller's selection narrows rather than being fixed by the resolver.
+ *
+ * Below that sit the escape hatches — `sql`, `L` and `E` — for the cases no option
+ * object can express.
+ */
+export declare namespace query {
+    /**
+     * The two shapes {@link query.pureData} accepts: one record, or many.
+     *
+     * @remarks
+     * An overloaded call signature rather than a union, so the return type follows the
+     * argument — pass an array and an array comes back.
+     */
+    interface PureDataFunction {
+        <_M extends Model<_M>, T>(model: typeof Model, input: T, attributes?: string[]): ModelAttributes;
+        <_M extends Model<_M>, T>(model: typeof Model, input: T[], attributes?: string[]): ModelAttributes[];
+    }
+    /**
+     * Collapses whitespace outside quoted literals, so a statement fits on one line.
+     *
+     * @remarks
+     * Walks the string tracking whether a single quote is open, so runs of
+     * whitespace inside a literal are preserved and only structural whitespace is
+     * collapsed. Quote tracking is a simple toggle: it does not understand escaped
+     * or doubled quotes, so a literal containing one can throw the parity off.
+     *
+     * @param input - Statement to normalise.
+     * @returns The statement with structural whitespace collapsed to single spaces.
+     */
+    export function safeSqlSpaceCleanup(input: string): string;
+    /**
+     * Normalises a SQL string: one-lined, whitespace collapsed, ending in a single
+     * semicolon.
+     *
+     * @remarks
+     * Usable as a plain function or as a template tag, the tag form being there so
+     * an editor highlights the SQL. It does NOT interpolate: a tag carrying
+     * substitutions throws, because the substituted values cannot be reached from
+     * here and the statement would come out mangled: tagging
+     * `SELECT ... WHERE id = ${id}` used to yield `... id = ,`. Bind parameters are
+     * the answer, and they are also the only safe one.
+     *
+     * Whitespace inside single-quoted literals is preserved; only whitespace
+     * outside them is collapsed.
+     *
+     * @param sqlQuery - A complete statement, or a template with no substitutions.
+     * @param values - Template substitutions, which are not supported.
+     * @returns The statement on one line, terminated with exactly one `;`.
+     * @throws TypeError when used as a template tag with substitutions.
+     * @example
+     * ```typescript
+     * const statement = sql`
+     *     SELECT id, name
+     *       FROM "Lead"
+     *      WHERE status = $1
+     * `;
+     * // SELECT id, name FROM "Lead" WHERE status = $1;
+     * await database().query(statement, { bind: [status] });
+     * ```
+     */
+    export function sql(sqlQuery: string | TemplateStringsArray, ...values: any[]): string;
+    /**
+     * Keeps only the properties a model actually declares.
+     *
+     * @remarks
+     * The filter for input arriving from outside: anything the model does not declare
+     * as an attribute is dropped rather than passed to Sequelize, so a caller cannot
+     * set a column by sending an unexpected property. Arrays are mapped element by
+     * element, and relations are dropped along with everything else — this looks at
+     * `rawAttributes` only.
+     *
+     * @param model - Model whose attributes define what survives.
+     * @param input - One object, or an array of them.
+     * @param attributes - Attribute names to allow, defaulting to all the model's.
+     * @returns A new object (or array) carrying only the allowed properties.
+     */
+    export const pureData: PureDataFunction;
+    /**
+     * Narrows a requested fields map to the model's own columns.
+     *
+     * @remarks
+     * Relations and unknown names are dropped, and the primary keys are then added
+     * back whether or not they were asked for — a deliberate trade so domain logic
+     * always has a key to work with, at the cost of returning a column the caller
+     * did not request.
+     *
+     * @param model - Model to narrow against.
+     * @param fields - Requested fields map, or a falsy value for "everything".
+     * @returns The surviving column names, or `true` meaning no restriction.
+     */
+    export function pureFields(model: typeof BaseModel, fields: any): string[] | true;
+    /**
+     * Whether a fields map asks for any of the model's relations.
+     *
+     * @remarks
+     * The cheap test for "does this query need joins at all", used to avoid building
+     * an `include` when the caller only wants columns.
+     *
+     * @param model - Model whose associations to check against.
+     * @param fields - Requested fields map.
+     * @returns `true` when at least one key names an association.
+     */
+    export function needNesting(model: typeof Model, fields: any): boolean;
+    /**
+     * Intersects a set of attributes with the names a caller asked for.
+     *
+     * @remarks
+     * With a `model` given, an empty intersection falls back to that model's primary
+     * keys rather than to nothing — so a fields list that matches no column selects
+     * the keys instead of every column, which is the safer failure but is not what
+     * "no matches" might suggest. Without a `model`, an empty result stays empty.
+     *
+     * @param attributes - Object whose keys are the available names.
+     * @param fields - Names the caller asked for.
+     * @param model - Model to take primary keys from when nothing matched.
+     * @returns The matching names, or the primary keys, or an empty array.
+     */
+    export function filtered(attributes: any, fields: string[], model?: typeof BaseModel): string[];
+    /**
+     * Foreign-key column names on a model for the given relations.
+     *
+     * @remarks
+     * These have to be selected even when the caller did not ask for them, or
+     * Sequelize cannot attach the joined rows — which is why `autoQuery` merges them
+     * into the attribute list.
+     *
+     * @param model - Model holding the foreign keys.
+     * @param relations - Association names to collect keys for.
+     * @returns The foreign-key column names.
+     */
+    export function foreignKeys(model: typeof BaseModel, relations: string[]): string[];
+    /**
+     * Merges query-option fragments into one options object.
+     *
+     * @remarks
+     * Per property: an absent property is taken as-is, arrays are unioned with
+     * duplicates dropped, objects are shallow-assigned, and anything else is
+     * overwritten by the later value. A fragment whose property type disagrees with
+     * what is already there — a scalar where an array sits, say — throws rather than
+     * guessing.
+     *
+     * MUTATES and returns `queryOptions`, so pass a fresh object unless sharing is
+     * what you want.
+     *
+     * @param queryOptions - Target, mutated in place.
+     * @param merge - Fragments to merge, in order; falsy ones are skipped.
+     * @returns The same `queryOptions` object.
+     * @throws TypeError when a fragment's property type conflicts with the target's.
+     */
+    export function mergeQuery(queryOptions?: any, ...merge: any[]): any;
+    /**
+     * Builds Sequelize find options from a requested fields map, joins included.
+     *
+     * @remarks
+     * The helper the others compose into. It turns a {@link FieldsInput} into
+     * `attributes` plus a nested `include` for every relation the map mentions,
+     * recursing into each level, and adds the foreign keys a join needs whether or
+     * not they were requested. Its rest parameter then merges the fragments the
+     * sibling helpers return, which is the intended shape of a paginated read.
+     *
+     * A value in the map that is not `false` doubles as a filter for that column, so
+     * a fields map can carry a where clause; see {@link FieldsInput} for why presence
+     * rather than value is what selects.
+     *
+     * Two things to know. It MUTATES the `fields` map, adding any column named in a
+     * merged `order` that the map omits, so ordering cannot break selection. And
+     * `fields` may also be a plain array of names, which selects those columns and
+     * builds no joins at all.
+     *
+     * @param model - Model to build the query for.
+     * @param fields - Requested fields map, or an array of column names.
+     * @param merge - Option fragments to merge in, typically from the helpers below.
+     * @returns Find options, typed as the caller asks.
+     * @example
+     * ```typescript
+     * const where = toWhereOptions(withRangeFilters(filter));
+     * const rows = await LeadModel.findAll(autoQuery<FindOptions>(
+     *     LeadModel,
+     *     fields,
+     *     where,
+     *     toLimitOptions(pageOptions),
+     *     toOrderOptions(orderBy),
+     * ));
+     * ```
+     */
+    export function autoQuery<T>(model: any, fields?: any, ...merge: (Partial<T> | undefined)[]): T;
+    /**
+     * Return names of primary key fields for a given model.
+     *
+     * @param model - Model to read the keys of.
+     * @returns The primary key attribute names, in declaration order.
+     */
+    export function primaryKeys(model: typeof BaseModel): string[];
+    /**
+     * Foreign key map representation, where related property name references
+     * parent property name.
+     */
+    interface ForeignKeyMap {
+        [property: string]: string;
+    }
+    /**
+     * Returns foreign key map for a given pair of parent model and related
+     * model.
+     *
+     * @param parent - Model on the referenced side.
+     * @param model - Model whose foreign keys are wanted.
+     */
+    export function foreignKeysMap(parent: typeof BaseModel, model: typeof BaseModel): ForeignKeyMap | null;
+    /**
+     * Recursively creates entity and all it's relations from a given input
+     * using a given model.
+     *
+     * @param model - model class to map entity to
+     * @param input - data input object related to a given model
+     * @param fields - fields map to return on created entity
+     * @param transaction - transaction
+     */
+    export function createEntity<T extends BaseModel<T>, I>(model: typeof BaseModel, input: I, fields?: FieldsInput, transaction?: Transaction): Promise<Partial<T>>;
+    /**
+     * The counting counterpart of {@link query.autoQuery}, for the same fields and filter.
+     *
+     * @remarks
+     * Builds the same query, then drops `attributes` and counts distinct primary keys
+     * instead — `distinct` matters because the joins `autoQuery` adds would otherwise
+     * multiply a row once per joined record and inflate the total.
+     *
+     * Pass it the same `fields` and filter as the data query, or the two disagree.
+     *
+     * @param model - Model to count rows of.
+     * @param fields - The same fields map used for the data query.
+     * @param merge - The same filter fragments, minus limit and order.
+     * @returns Count options ready for `Model.count()`.
+     */
+    export function autoCountQuery(model: any, fields?: any, ...merge: (Partial<CountOptions> | undefined)[]): CountOptions;
+    /**
+     * Builds proper paging options query part
+     *
+     * @param pageOptions - obtained pagination input
+     *                                          from remote
+     * @returns pagination part of the query
+     */
+    export function toLimitOptions<_T>(pageOptions?: PaginationInput): FindOptions;
+    /**
+     * Turns a serialized order into Sequelize's `order` option.
+     *
+     * @remarks
+     * One entry per property, in the order the object lists them, so the caller
+     * controls precedence. Directions are normalised rather than trusted — anything
+     * that does not read as descending becomes ascending, which is what keeps a value
+     * off the wire out of the statement. An empty or absent order yields no `order`
+     * at all rather than an empty one.
+     *
+     * @param orderBy - Property-to-direction map from the caller.
+     * @returns Options carrying `order`, or empty options.
+     */
+    export function toOrderOptions<_T>(orderBy?: OrderByInput): FindOptions;
+    /**
+     * Matches a value, or no value at all.
+     *
+     * @remarks
+     * For the filter that means "these, and the rows where it is not set": the result
+     * is an `OR` over `null` and what you pass. Without it a `null` in a where clause
+     * compares rather than tests, and matches nothing.
+     *
+     * @param value - Value, or values, to accept alongside `null`.
+     * @returns A where fragment for one column.
+     */
+    export function orNull(value: string | string[]): Partial<FindOptions>;
+    /**
+     * Turns a serializable filter into Sequelize `where` options.
+     *
+     * @remarks
+     * Each property is dispatched on its shape: a `$`-prefixed key becomes the
+     * matching Sequelize operator (see {@link FILTER_OPS}), an object with `start`
+     * and `end` becomes a `BETWEEN`, any other object is walked recursively as a
+     * nested filter, an array becomes an OR of its values, and a scalar is compared
+     * directly.
+     *
+     * A STRING value is inspected before it is compared, which is convenient and
+     * occasionally surprising. A `%` anywhere in it makes the comparison a
+     * case-insensitive `ILIKE`, and a leading `<=`, `>=`, `<`, `>` or `=` becomes
+     * that operator with the rest as the value, coerced to a number or a `Date` when
+     * it parses as one. So `'>=10'` and `'%abc%'` work with no operator key — and a
+     * literal value that happens to contain `%`, such as `'50% off'`, becomes a
+     * pattern match rather than an equality test. Use an explicit `$eq` where that
+     * matters.
+     *
+     * Empty is treated as absent, not as a contradiction: an empty array is skipped
+     * and a single-element array is unwrapped to the value. Given a falsy filter it
+     * returns `{}`, which means "no restriction" — so a caller cannot accidentally
+     * filter everything out by passing nothing.
+     *
+     * With `inputType`, a property matching one of that type's own properties is
+     * turned into a required `include` on the related model rather than a column
+     * comparison, which is how a filter reaches across a relation.
+     *
+     * @param filter - Filter from a caller. Modified in place as empties are cleared.
+     * @param inputType - Constructor describing which properties are relations.
+     * @returns Options carrying `where` and, where relations were filtered, `include`.
+     */
+    export function toWhereOptions<T>(filter?: T, inputType?: new () => T): any;
+    /**
+     * ORs an array of filter values into one condition.
+     *
+     * @remarks
+     * Plain values are gathered into a single `IN`, while values carrying their own
+     * operator prefix become separate conditions, and the two groups are then ORed —
+     * so `['a', 'b', '>=10']` becomes `IN (a, b) OR >= 10` rather than three
+     * unrelated comparisons.
+     *
+     * @param data - Values to combine.
+     * @returns A `where` fragment for one column.
+     */
+    export function buildWhereFromArray(data: any[]): any;
+    /**
+     * Rewrites `<column>Range` filter properties onto the columns they belong to.
+     *
+     * @remarks
+     * The convention that lets a range be filtered over RPC: a caller sends
+     * `durationRange: { start, end }` and this moves it to `duration`, where
+     * {@link query.toWhereOptions} turns it into a `BETWEEN`. Recognition is strict — the
+     * property name must end in `Range` and the value must have exactly the keys
+     * `start` and `end`, in either order. Anything else is left untouched and
+     * filtered as an ordinary value, and nested objects are walked so a range on a
+     * related model works too.
+     *
+     * Sending both `duration` and `durationRange` throws rather than choosing one.
+     *
+     * MUTATES and returns the filter it is given.
+     *
+     * @param filter - Filter to rewrite in place.
+     * @returns The same filter, with ranges moved onto their columns.
+     */
+    export function withRangeFilters(filter: any): any;
+    /**
+     * Finds the include options for a model reached through a chain of includes.
+     *
+     * @remarks
+     * The way to reach into a query that is already built — to add a where clause to a
+     * join, say, without rebuilding the whole thing. The path is walked one model at a
+     * time, and it is CONSUMED as that happens, so pass a copy if the caller still
+     * needs it.
+     *
+     * @param queryOptions - Query to search.
+     * @param path - Models to follow, outermost first.
+     * @returns The matching include options, or `null` when the path does not resolve.
+     */
+    export function getInclude(queryOptions: FindOptions, path: (typeof Model)[]): IncludeOptions | null;
+    /**
+     * Builds a Sequelize literal from a string or a template — the escape hatch for
+     * SQL that no query option can express.
+     *
+     * @remarks
+     * A literal is spliced into the statement exactly as given, so nothing about it
+     * is parsed, checked or escaped. That is the whole point of it, and the reason to
+     * keep each one as small as the job allows: a correlated subquery in a `where`, a
+     * window function in an `order`, an operator Sequelize has no name for. Runtime
+     * values belong in {@link query.E} rather than in the text.
+     *
+     * Used as a template tag, the substitutions used to be dropped and the literal
+     * parts joined with commas, so the example below produced
+     * `(SELECT COUNT(*) FROM "SomeTable" WHERE owner = ,) = 0` — accepted by the
+     * template, rejected by Postgres. They are now interpolated in order.
+     *
+     * {@link query.sql} refuses substitutions rather than interpolating them, and the
+     * difference is deliberate: a complete statement can carry bind parameters, so
+     * interpolating into one is a choice to avoid. A fragment handed to Sequelize as
+     * a literal has no bind channel, which leaves escaping as the only option.
+     *
+     * @param str - The SQL text, or the literal parts when used as a template tag.
+     * @param values - The substitutions, when used as a template tag.
+     * @returns The text as a Sequelize literal, ready to use as a query option value.
+     * @example
+     * ```typescript
+     * const owner = 3;
+     * const query = {
+     *     where: L`(SELECT COUNT(*) FROM "SomeTable" WHERE owner = ${E(owner)}) = 0`,
+     * };
+     * ```
+     */
+    export function L(str: TemplateStringsArray | string, ...values: any[]): Literal;
+    /**
+     * Renders a value as a SQL constant: a number as itself, a string quoted and
+     * escaped, anything else as `NULL`.
+     *
+     * @remarks
+     * The companion to {@link query.L} and the only safe way to get a runtime value
+     * into a literal. Single quotes inside a string are doubled, which is what
+     * Postgres requires — and what this did not do: a value of `O'Brien` came out as
+     * a broken string constant, and a value chosen deliberately came out as SQL. The
+     * same path escapes a dynamic view's parameters, so a view selected with
+     * caller-supplied `viewParams` was open the same way.
+     *
+     * Only numbers and strings render as values. Booleans, dates, objects, `null` and
+     * `undefined` all become `NULL` — so format a date as a string before passing it,
+     * and do not reach for this to render a boolean.
+     *
+     * @param input - Value to render.
+     * @returns The number itself, a quoted and escaped string, or `NULL`.
+     */
+    export function E(input: any): string | number;
+    /**
+     * Deletes properties from an object.
+     *
+     * @remarks
+     * MUTATES what it is given and hands it back, so it composes into a call chain.
+     * A falsy argument is returned untouched, which makes it safe on an optional
+     * value.
+     *
+     * @param obj - Object to strip.
+     * @param props - Property names to delete.
+     * @returns The same object.
+     */
+    export function skip(obj: any, ...props: string[]): any;
+    /**
+     * Traverses given query object, lookups for includes matching
+     * the given arguments of include options and overrides those are matching
+     * by model and alias with the provided option.
+     *
+     * @param queryOptions - Query whose includes are to be overridden.
+     * @param options - Include options to apply, matched by model and alias.
+     * @returns The same query options.
+     */
+    export function overrideJoin(queryOptions: FindOptions | CountOptions, ...options: IncludeOptions[]): FindOptions | CountOptions;
+    export {};
+}