@imqueue/pg-sequelize 4.2.0

package/src/Graph.d.ts

@@ -0,0 +1,215 @@
+/*!
+ * @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.
+ */
+/**
+ * A graph as adjacency lists: each vertex mapped to the vertices it points at.
+ */
+export type GraphMap<T> = Map<T, T[]>;
+/**
+ * Called once per vertex during a traversal.
+ *
+ * @remarks
+ * Returning `false` prunes the walk at that vertex — its own edges are not
+ * followed — rather than ending the traversal. Anything else, `undefined`
+ * included, carries on. The second argument is the live visited map, so a
+ * callback can see what has already been reached, and add to it to steer the
+ * walk away from a vertex it does not want visited.
+ */
+export type GraphForeachCallback<T> = (vertex: T, visited: Map<T, boolean>) => false | void;
+/**
+ * A directed, unweighted graph with depth-first traversal and cycle detection.
+ *
+ * @remarks
+ * Small on purpose. It exists so model associations can be walked as a graph —
+ * `BaseModel.toGraph()` builds one — and the question worth asking of that graph is
+ * whether it has a cycle, because a cycle is a chain of `include`s that can be asked
+ * to include itself.
+ *
+ * Directed, despite what this said for a long time: an edge is recorded only on the
+ * vertex it starts from, so `addEdge(a, b)` does not make `hasEdge(b, a)` true. The
+ * cycle detection is the standard directed-graph one, with a recursion stack
+ * alongside the visited set, and it would be wrong for an undirected graph.
+ *
+ * Vertices are used as `Map` keys, so identity is what distinguishes them — model
+ * classes work, structurally equal objects do not.
+ *
+ * @example
+ * ```typescript
+ * const graph = Lead.toGraph();
+ *
+ * if (graph.isCycled()) {
+ *     // some association path leads back to where it started
+ * }
+ * ```
+ */
+export declare class Graph<T> {
+    /** The adjacency lists backing this graph. */
+    private list;
+    /**
+     * Adds vertices with no edges.
+     *
+     * @remarks
+     * Not idempotent: a vertex that is already present has its edges RESET, so guard
+     * with {@link Graph.hasVertex} when a vertex may already be there. Adding an edge
+     * from an unknown vertex adds it for you, which is the usual way one appears.
+     *
+     * @param vertex - Vertices to add.
+     * @returns This graph, for chaining.
+     */
+    addVertex(...vertex: T[]): Graph<T>;
+    /**
+     * Removes vertices along with the edges leading out of them.
+     *
+     * @remarks
+     * Edges pointing AT a removed vertex are left behind, so other vertices can go on
+     * naming one that is gone — and a walk that follows such an edge simply finds no
+     * further edges rather than failing.
+     *
+     * @param vertex - Vertices to remove.
+     * @returns This graph, for chaining.
+     */
+    delVertex(...vertex: T[]): Graph<T>;
+    /**
+     * Adds edges from one vertex to others.
+     *
+     * @remarks
+     * Directed: only `fromVertex` records them. It is added to the graph first if it
+     * is not there yet, while the targets are not — an edge may point at a vertex the
+     * graph does not otherwise know. Duplicate edges are kept as duplicates.
+     *
+     * @param fromVertex - Vertex the edges start from.
+     * @param toVertex - Vertices they point at.
+     * @returns This graph, for chaining.
+     */
+    addEdge(fromVertex: T, ...toVertex: T[]): Graph<T>;
+    /**
+     * Removes edges from one vertex to others.
+     *
+     * @remarks
+     * Every occurrence of each target is removed, so a duplicated edge goes entirely.
+     * A vertex with no edges, or one that is not in the graph, is left alone.
+     *
+     * @param fromVertex - Vertex to remove edges from.
+     * @param toVertex - Vertices to stop pointing at.
+     * @returns This graph, for chaining.
+     */
+    delEdge(fromVertex: T, ...toVertex: T[]): Graph<T>;
+    /**
+     * Whether one vertex points at another.
+     *
+     * @remarks
+     * Directed, so the order of the arguments matters: this asks about an edge from
+     * `vertex` to `edge` and says nothing about the other direction.
+     *
+     * @param vertex - Vertex the edge would start from.
+     * @param edge - Vertex it would point at.
+     * @returns `true` when that edge is present.
+     */
+    hasEdge(vertex: T, edge: T): boolean;
+    /**
+     * Whether a vertex is in this graph.
+     *
+     * @remarks
+     * By identity, since vertices are `Map` keys. A vertex that is only pointed at by
+     * an edge and never added is not in the graph.
+     *
+     * @param vertex - Vertex to look for.
+     * @returns `true` when the graph holds it.
+     */
+    hasVertex(vertex: T): boolean;
+    /**
+     * Visits every vertex once, depth first.
+     *
+     * @remarks
+     * Walks from each vertex in turn, sharing one visited set across all of them — so
+     * the callback sees each vertex exactly once no matter how many paths reach it,
+     * and a disconnected part of the graph is covered too. A callback returning
+     * `false` prunes that branch; the traversal moves on to the next vertex rather
+     * than stopping.
+     *
+     * @param callback - Called once per vertex.
+     * @returns This graph, for chaining.
+     */
+    forEach(callback: GraphForeachCallback<T>): Graph<T>;
+    /**
+     * Walks depth first from one vertex.
+     *
+     * @remarks
+     * Follows edges as far as they go, marking each vertex as it arrives and never
+     * arriving twice, which is what makes it safe on a cyclic graph. Passing a visited
+     * map of your own both continues an earlier walk and lets you exclude vertices by
+     * marking them before starting.
+     *
+     * @param vertex - Vertex to start from.
+     * @param callback - Called once per vertex reached; returning `false` prunes.
+     * @param visited - Vertices already reached. A fresh map by default.
+     * @returns This graph, for chaining.
+     */
+    walk(vertex: T, callback?: GraphForeachCallback<T>, visited?: Map<T, boolean>): Graph<T>;
+    /**
+     * Every vertex reachable from one vertex, in the order a depth-first walk finds
+     * them.
+     *
+     * @remarks
+     * The reachable SET, not the longest path — each vertex appears once however many
+     * routes lead to it, and the starting vertex is the first entry. Reading it as a
+     * path is what makes a cyclic graph look as though it terminates.
+     *
+     * @param vertex - Vertex to start from.
+     * @returns An iterator over the reachable vertices.
+     */
+    path(vertex: T): IterableIterator<T>;
+    /**
+     * Whether any path in this graph leads back to where it started.
+     *
+     * @remarks
+     * Checks from every vertex, so a cycle in a part of the graph nothing else reaches
+     * is still found. A self-edge counts. For model associations this is the question
+     * that matters: a cycle is an `include` chain that can be asked to include itself.
+     *
+     * @returns `true` when the graph contains a cycle.
+     */
+    isCycled(): boolean;
+    /**
+     * The vertices in this graph, in insertion order.
+     *
+     * @returns An iterator over the vertices.
+     */
+    vertices(): IterableIterator<T>;
+    /**
+     * Looks for a cycle reachable from one vertex.
+     *
+     * @remarks
+     * Depth-first with a recursion stack beside the visited set: reaching a vertex
+     * that is still on the stack means the path has come back on itself, whereas
+     * reaching one that is merely visited means it was explored already and holds no
+     * cycle. The stack entry is cleared on the way out, which is what keeps two
+     * separate paths through one vertex from reading as a cycle.
+     *
+     * @param vertex - Vertex to search from.
+     * @param visited - Vertices explored in this run, added to as it goes.
+     * @param stack - Vertices on the current path.
+     * @returns `true` when a cycle is reachable from `vertex`.
+     */
+    private detectCycle;
+}

package/src/Graph.js

@@ -0,0 +1,257 @@
+/**
+ * A directed, unweighted graph with depth-first traversal and cycle detection.
+ *
+ * @remarks
+ * Small on purpose. It exists so model associations can be walked as a graph —
+ * `BaseModel.toGraph()` builds one — and the question worth asking of that graph is
+ * whether it has a cycle, because a cycle is a chain of `include`s that can be asked
+ * to include itself.
+ *
+ * Directed, despite what this said for a long time: an edge is recorded only on the
+ * vertex it starts from, so `addEdge(a, b)` does not make `hasEdge(b, a)` true. The
+ * cycle detection is the standard directed-graph one, with a recursion stack
+ * alongside the visited set, and it would be wrong for an undirected graph.
+ *
+ * Vertices are used as `Map` keys, so identity is what distinguishes them — model
+ * classes work, structurally equal objects do not.
+ *
+ * @example
+ * ```typescript
+ * const graph = Lead.toGraph();
+ *
+ * if (graph.isCycled()) {
+ *     // some association path leads back to where it started
+ * }
+ * ```
+ */
+export class Graph {
+    /** The adjacency lists backing this graph. */
+    list = new Map();
+    /**
+     * Adds vertices with no edges.
+     *
+     * @remarks
+     * Not idempotent: a vertex that is already present has its edges RESET, so guard
+     * with {@link Graph.hasVertex} when a vertex may already be there. Adding an edge
+     * from an unknown vertex adds it for you, which is the usual way one appears.
+     *
+     * @param vertex - Vertices to add.
+     * @returns This graph, for chaining.
+     */
+    addVertex(...vertex) {
+        for (const v of vertex) {
+            this.list.set(v, []);
+        }
+        return this;
+    }
+    /**
+     * Removes vertices along with the edges leading out of them.
+     *
+     * @remarks
+     * Edges pointing AT a removed vertex are left behind, so other vertices can go on
+     * naming one that is gone — and a walk that follows such an edge simply finds no
+     * further edges rather than failing.
+     *
+     * @param vertex - Vertices to remove.
+     * @returns This graph, for chaining.
+     */
+    delVertex(...vertex) {
+        for (const v of vertex) {
+            this.list.delete(v);
+        }
+        return this;
+    }
+    /**
+     * Adds edges from one vertex to others.
+     *
+     * @remarks
+     * Directed: only `fromVertex` records them. It is added to the graph first if it
+     * is not there yet, while the targets are not — an edge may point at a vertex the
+     * graph does not otherwise know. Duplicate edges are kept as duplicates.
+     *
+     * @param fromVertex - Vertex the edges start from.
+     * @param toVertex - Vertices they point at.
+     * @returns This graph, for chaining.
+     */
+    addEdge(fromVertex, ...toVertex) {
+        let edges = this.list.get(fromVertex);
+        if (!edges) {
+            this.addVertex(fromVertex);
+            edges = this.list.get(fromVertex);
+        }
+        edges.push(...toVertex);
+        return this;
+    }
+    /**
+     * Removes edges from one vertex to others.
+     *
+     * @remarks
+     * Every occurrence of each target is removed, so a duplicated edge goes entirely.
+     * A vertex with no edges, or one that is not in the graph, is left alone.
+     *
+     * @param fromVertex - Vertex to remove edges from.
+     * @param toVertex - Vertices to stop pointing at.
+     * @returns This graph, for chaining.
+     */
+    delEdge(fromVertex, ...toVertex) {
+        const edges = this.list.get(fromVertex);
+        if (!(edges && edges.length)) {
+            return this;
+        }
+        for (const vertex of toVertex) {
+            while (~edges.indexOf(vertex)) {
+                edges.splice(edges.indexOf(vertex), 1);
+            }
+        }
+        return this;
+    }
+    /**
+     * Whether one vertex points at another.
+     *
+     * @remarks
+     * Directed, so the order of the arguments matters: this asks about an edge from
+     * `vertex` to `edge` and says nothing about the other direction.
+     *
+     * @param vertex - Vertex the edge would start from.
+     * @param edge - Vertex it would point at.
+     * @returns `true` when that edge is present.
+     */
+    hasEdge(vertex, edge) {
+        return !!~(this.list.get(vertex) || []).indexOf(edge);
+    }
+    /**
+     * Whether a vertex is in this graph.
+     *
+     * @remarks
+     * By identity, since vertices are `Map` keys. A vertex that is only pointed at by
+     * an edge and never added is not in the graph.
+     *
+     * @param vertex - Vertex to look for.
+     * @returns `true` when the graph holds it.
+     */
+    hasVertex(vertex) {
+        return this.list.has(vertex);
+    }
+    /**
+     * Visits every vertex once, depth first.
+     *
+     * @remarks
+     * Walks from each vertex in turn, sharing one visited set across all of them — so
+     * the callback sees each vertex exactly once no matter how many paths reach it,
+     * and a disconnected part of the graph is covered too. A callback returning
+     * `false` prunes that branch; the traversal moves on to the next vertex rather
+     * than stopping.
+     *
+     * @param callback - Called once per vertex.
+     * @returns This graph, for chaining.
+     */
+    forEach(callback) {
+        const visited = new Map();
+        for (const node of this.list.keys()) {
+            this.walk(node, callback, visited);
+        }
+        return this;
+    }
+    /**
+     * Walks depth first from one vertex.
+     *
+     * @remarks
+     * Follows edges as far as they go, marking each vertex as it arrives and never
+     * arriving twice, which is what makes it safe on a cyclic graph. Passing a visited
+     * map of your own both continues an earlier walk and lets you exclude vertices by
+     * marking them before starting.
+     *
+     * @param vertex - Vertex to start from.
+     * @param callback - Called once per vertex reached; returning `false` prunes.
+     * @param visited - Vertices already reached. A fresh map by default.
+     * @returns This graph, for chaining.
+     */
+    walk(vertex, callback, visited = new Map()) {
+        if (!visited.get(vertex)) {
+            visited.set(vertex, true);
+            if (callback && callback(vertex, visited) === false) {
+                return this;
+            }
+            for (const neighbor of this.list.get(vertex) || []) {
+                this.walk(neighbor, callback, visited);
+            }
+        }
+        return this;
+    }
+    /**
+     * Every vertex reachable from one vertex, in the order a depth-first walk finds
+     * them.
+     *
+     * @remarks
+     * The reachable SET, not the longest path — each vertex appears once however many
+     * routes lead to it, and the starting vertex is the first entry. Reading it as a
+     * path is what makes a cyclic graph look as though it terminates.
+     *
+     * @param vertex - Vertex to start from.
+     * @returns An iterator over the reachable vertices.
+     */
+    path(vertex) {
+        const visited = new Map();
+        this.walk(vertex, undefined, visited);
+        return visited.keys();
+    }
+    /**
+     * Whether any path in this graph leads back to where it started.
+     *
+     * @remarks
+     * Checks from every vertex, so a cycle in a part of the graph nothing else reaches
+     * is still found. A self-edge counts. For model associations this is the question
+     * that matters: a cycle is an `include` chain that can be asked to include itself.
+     *
+     * @returns `true` when the graph contains a cycle.
+     */
+    isCycled() {
+        const visited = new Map();
+        const stack = new Map();
+        for (const node of this.list.keys()) {
+            if (this.detectCycle(node, visited, stack)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * The vertices in this graph, in insertion order.
+     *
+     * @returns An iterator over the vertices.
+     */
+    vertices() {
+        return this.list.keys();
+    }
+    /**
+     * Looks for a cycle reachable from one vertex.
+     *
+     * @remarks
+     * Depth-first with a recursion stack beside the visited set: reaching a vertex
+     * that is still on the stack means the path has come back on itself, whereas
+     * reaching one that is merely visited means it was explored already and holds no
+     * cycle. The stack entry is cleared on the way out, which is what keeps two
+     * separate paths through one vertex from reading as a cycle.
+     *
+     * @param vertex - Vertex to search from.
+     * @param visited - Vertices explored in this run, added to as it goes.
+     * @param stack - Vertices on the current path.
+     * @returns `true` when a cycle is reachable from `vertex`.
+     */
+    detectCycle(vertex, visited, stack) {
+        if (!visited.get(vertex)) {
+            visited.set(vertex, true);
+            stack.set(vertex, true);
+            for (const currentNode of this.list.get(vertex) || []) {
+                if ((!visited.get(currentNode) &&
+                    this.detectCycle(currentNode, visited, stack)) ||
+                    stack.get(currentNode)) {
+                    return true;
+                }
+            }
+        }
+        stack.set(vertex, false);
+        return false;
+    }
+}
+//# sourceMappingURL=Graph.js.map

package/src/decorators/AssociatedWith.d.ts

@@ -0,0 +1,94 @@
+/*!
+ * @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.
+ */
+/**
+ * Describes the association a filter field stands for.
+ */
+export interface IAssociated {
+    /** The model on the other side of the association. */
+    model: any;
+    /**
+     * The input class describing that model's own filter fields.
+     *
+     * @remarks
+     * Read recursively, so a filter can nest as deep as the input classes do.
+     */
+    input: any;
+    /**
+     * Association name on the model, when it differs from the field name.
+     *
+     * @remarks
+     * Recorded and then never read: nothing in this package consumes it today, so
+     * the field name and the association name have to match. Left in place because
+     * removing it from the public type would break callers that set it.
+     */
+    modelFieldName?: string;
+}
+/**
+ * Marks a field of a filter input as standing for an association rather than for a
+ * column.
+ *
+ * @remarks
+ * This is what lets a caller's filter reach through a relation. `query.toWhereOptions`
+ * instantiates the input class, and any property it finds carrying one of these
+ * descriptors becomes a required `include` on the associated model, with the nested
+ * filter resolved against that model's own input class — recursively, so the nesting
+ * can go as deep as the input classes do. Without it the nested object would be
+ * treated as a column filter and produce a where clause on a column that does not
+ * exist.
+ *
+ * Declare the field with `declare`, and do not instantiate the input class yourself.
+ * The descriptor lives on the prototype as a read-only, non-enumerable property, so a
+ * real field declaration would shadow it with `undefined` under
+ * `useDefineForClassFields` and the association would be silently ignored — and an
+ * assignment to it throws in strict mode. These classes are descriptions of a wire
+ * shape, not containers for one.
+ *
+ * The thunk is resolved on first read rather than at decoration time, which is what
+ * makes it worth being a thunk: input classes and models routinely import each other,
+ * and a decorator body runs while those modules are still initialising, so resolving
+ * eagerly could capture `undefined` as the model. First read happens on the first
+ * query, by which point every module is loaded.
+ *
+ * @param cb - Returns the association descriptor.
+ * @returns A property decorator.
+ * @example
+ * ```typescript
+ * export class PaymentListInput {
+ *     @property(() => `number[] | ${FilterInput.name}`, true)
+ *     declare public amount?: number[] | FilterInput;
+ *
+ *     @property('PaymentTypeListInput', true)
+ *     @AssociatedWith(() => ({
+ *         model: PaymentType,
+ *         input: PaymentTypeListInput,
+ *     }))
+ *     declare public paymentType?: PaymentTypeListInput;
+ * }
+ *
+ * // A filter of { paymentType: { name: 'card' } } now becomes a required join on
+ * // PaymentType with the name filter applied there.
+ * const options = query.toWhereOptions(filter, PaymentListInput);
+ * ```
+ */
+export declare function AssociatedWith(cb: () => IAssociated): (target: any, key: string) => any;

package/src/decorators/AssociatedWith.js

@@ -0,0 +1,71 @@
+/**
+ * Marks a field of a filter input as standing for an association rather than for a
+ * column.
+ *
+ * @remarks
+ * This is what lets a caller's filter reach through a relation. `query.toWhereOptions`
+ * instantiates the input class, and any property it finds carrying one of these
+ * descriptors becomes a required `include` on the associated model, with the nested
+ * filter resolved against that model's own input class — recursively, so the nesting
+ * can go as deep as the input classes do. Without it the nested object would be
+ * treated as a column filter and produce a where clause on a column that does not
+ * exist.
+ *
+ * Declare the field with `declare`, and do not instantiate the input class yourself.
+ * The descriptor lives on the prototype as a read-only, non-enumerable property, so a
+ * real field declaration would shadow it with `undefined` under
+ * `useDefineForClassFields` and the association would be silently ignored — and an
+ * assignment to it throws in strict mode. These classes are descriptions of a wire
+ * shape, not containers for one.
+ *
+ * The thunk is resolved on first read rather than at decoration time, which is what
+ * makes it worth being a thunk: input classes and models routinely import each other,
+ * and a decorator body runs while those modules are still initialising, so resolving
+ * eagerly could capture `undefined` as the model. First read happens on the first
+ * query, by which point every module is loaded.
+ *
+ * @param cb - Returns the association descriptor.
+ * @returns A property decorator.
+ * @example
+ * ```typescript
+ * export class PaymentListInput {
+ *     @property(() => `number[] | ${FilterInput.name}`, true)
+ *     declare public amount?: number[] | FilterInput;
+ *
+ *     @property('PaymentTypeListInput', true)
+ *     @AssociatedWith(() => ({
+ *         model: PaymentType,
+ *         input: PaymentTypeListInput,
+ *     }))
+ *     declare public paymentType?: PaymentTypeListInput;
+ * }
+ *
+ * // A filter of { paymentType: { name: 'card' } } now becomes a required join on
+ * // PaymentType with the name filter applied there.
+ * const options = query.toWhereOptions(filter, PaymentListInput);
+ * ```
+ */
+export function AssociatedWith(cb) {
+    return (target, key) => {
+        let resolved;
+        let done = false;
+        Object.defineProperty(target, key, {
+            get() {
+                if (!done) {
+                    done = true;
+                    const association = cb();
+                    if (association) {
+                        resolved = {
+                            model: association.model,
+                            input: association.input,
+                            key: association.modelFieldName || key,
+                        };
+                    }
+                }
+                return resolved;
+            },
+        });
+        return target;
+    };
+}
+//# sourceMappingURL=AssociatedWith.js.map