@nest-boot/graphql-connection 7.6.1 → 7.6.2

package/dist/graphql-connection.constants.js

@@ -1,5 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GRAPHQL_CONNECTION_METADATA = void 0;
+/**
+ * Symbol used as a metadata key for storing connection metadata on connection classes.
+ *
+ * This symbol is used internally by the connection builder to attach metadata
+ * (entity class, field options, filter schema) to generated connection classes.
+ * The metadata is then used by the ConnectionQueryBuilder to construct queries.
+ *
+ * @internal
+ */
 exports.GRAPHQL_CONNECTION_METADATA = Symbol("GRAPHQL_CONNECTION_METADATA");
 //# sourceMappingURL=graphql-connection.constants.js.map

package/dist/graphql-connection.constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"graphql-connection.constants.js","sourceRoot":"","sources":["../src/graphql-connection.constants.ts"],"names":[],"mappings":";;;AAAa,QAAA,2BAA2B,GAAG,MAAM,CAC/C,6BAA6B,CAC9B,CAAC"}
+{"version":3,"file":"graphql-connection.constants.js","sourceRoot":"","sources":["../src/graphql-connection.constants.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;GAQG;AACU,QAAA,2BAA2B,GAAG,MAAM,CAC/C,6BAA6B,CAC9B,CAAC"}

package/dist/graphql-connection.module.d.ts

@@ -1,3 +1,23 @@
 import { ConfigurableModuleClass } from "./graphql-connection.module-definition";
+/**
+ * NestJS module that provides GraphQL connection-based pagination functionality.
+ *
+ * This module is global and provides the {@link ConnectionManager} service for
+ * executing paginated queries following the Relay connection specification.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { Module } from "@nestjs/common";
+ * import { GraphQLConnectionModule } from "@nest-boot/graphql-connection";
+ *
+ * @Module({
+ *   imports: [GraphQLConnectionModule.register()],
+ * })
+ * export class AppModule {}
+ * ```
+ *
+ * @see {@link ConnectionManager} for executing paginated queries
+ * @see {@link ConnectionBuilder} for building connection types
+ */
 export declare class GraphQLConnectionModule extends ConfigurableModuleClass {
 }

package/dist/graphql-connection.module.js

@@ -10,6 +10,26 @@ exports.GraphQLConnectionModule = void 0;
 const common_1 = require("@nestjs/common");
 const connection_manager_1 = require("./connection.manager");
 const graphql_connection_module_definition_1 = require("./graphql-connection.module-definition");
+/**
+ * NestJS module that provides GraphQL connection-based pagination functionality.
+ *
+ * This module is global and provides the {@link ConnectionManager} service for
+ * executing paginated queries following the Relay connection specification.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { Module } from "@nestjs/common";
+ * import { GraphQLConnectionModule } from "@nest-boot/graphql-connection";
+ *
+ * @Module({
+ *   imports: [GraphQLConnectionModule.register()],
+ * })
+ * export class AppModule {}
+ * ```
+ *
+ * @see {@link ConnectionManager} for executing paginated queries
+ * @see {@link ConnectionBuilder} for building connection types
+ */
 let GraphQLConnectionModule = class GraphQLConnectionModule extends graphql_connection_module_definition_1.ConfigurableModuleClass {
 };
 exports.GraphQLConnectionModule = GraphQLConnectionModule;

package/dist/graphql-connection.module.js.map

@@ -1 +1 @@
-{"version":3,"file":"graphql-connection.module.js","sourceRoot":"","sources":["../src/graphql-connection.module.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAAgD;AAEhD,6DAAyD;AACzD,iGAAiF;AAO1E,IAAM,uBAAuB,GAA7B,MAAM,uBAAwB,SAAQ,8DAAuB;CAAG,CAAA;AAA1D,0DAAuB;kCAAvB,uBAAuB;IALnC,IAAA,eAAM,GAAE;IACR,IAAA,eAAM,EAAC;QACN,SAAS,EAAE,CAAC,sCAAiB,CAAC;QAC9B,OAAO,EAAE,CAAC,sCAAiB,CAAC;KAC7B,CAAC;GACW,uBAAuB,CAAmC"}
+{"version":3,"file":"graphql-connection.module.js","sourceRoot":"","sources":["../src/graphql-connection.module.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAAgD;AAEhD,6DAAyD;AACzD,iGAAiF;AAEjF;;;;;;;;;;;;;;;;;;;GAmBG;AAMI,IAAM,uBAAuB,GAA7B,MAAM,uBAAwB,SAAQ,8DAAuB;CAAG,CAAA;AAA1D,0DAAuB;kCAAvB,uBAAuB;IALnC,IAAA,eAAM,GAAE;IACR,IAAA,eAAM,EAAC;QACN,SAAS,EAAE,CAAC,sCAAiB,CAAC;QAC9B,OAAO,EAAE,CAAC,sCAAiB,CAAC;KAC7B,CAAC;GACW,uBAAuB,CAAmC"}

package/dist/interfaces/connection-args.interface.d.ts

@@ -1,11 +1,58 @@
 import { FilterQuery } from "@mikro-orm/core";
 import { OrderInterface } from "./order.interface";
+/**
+ * Arguments for querying a paginated connection.
+ *
+ * Supports both forward pagination (first/after) and backward pagination (last/before),
+ * as well as filtering, ordering, and search query functionality.
+ *
+ * @typeParam Entity - The entity type being queried
+ *
+ * @example Forward pagination
+ * ```typescript
+ * const args: ConnectionArgsInterface<User> = {
+ *   first: 10,
+ *   after: "cursor123",
+ *   orderBy: { field: "CREATED_AT", direction: OrderDirection.DESC },
+ * };
+ * ```
+ *
+ * @example Backward pagination
+ * ```typescript
+ * const args: ConnectionArgsInterface<User> = {
+ *   last: 10,
+ *   before: "cursor456",
+ * };
+ * ```
+ */
 export interface ConnectionArgsInterface<Entity extends object> {
+    /**
+     * Returns elements after this cursor (for forward pagination).
+     */
     after?: string;
+    /**
+     * Returns elements before this cursor (for backward pagination).
+     */
     before?: string;
+    /**
+     * Returns up to the first n elements (for forward pagination).
+     */
     first?: number;
+    /**
+     * Returns up to the last n elements (for backward pagination).
+     */
     last?: number;
+    /**
+     * A search query string to filter results.
+     * Parsed using search-syntax and applied to searchable fields.
+     */
     query?: string;
+    /**
+     * A MongoDB-style filter query to apply to the results.
+     */
     filter?: FilterQuery<Entity>;
+    /**
+     * Ordering options for the returned results.
+     */
     orderBy?: OrderInterface<Entity>;
 }

package/dist/interfaces/connection-builder-options.interface.d.ts

@@ -1,4 +1,23 @@
 import type { FilterOptions } from "mikro-orm-filter-query-schema";
+/**
+ * Configuration options for the ConnectionBuilder.
+ *
+ * @example
+ * ```typescript
+ * const options: ConnectionBuilderOptions = {
+ *   filter: {
+ *     maxDepth: 3,
+ *     maxConditions: 10,
+ *     maxOrBranches: 3,
+ *     maxArrayLength: 50,
+ *   },
+ * };
+ * ```
+ */
 export interface ConnectionBuilderOptions {
+    /**
+     * Options for the filter query schema builder.
+     * Controls limits on filter complexity to prevent abuse.
+     */
     filter?: FilterOptions;
 }

package/dist/interfaces/connection-metadata.interface.d.ts

@@ -2,8 +2,27 @@ import { EntityClass, FilterQuery } from "@mikro-orm/core";
 import type { FieldType } from "mikro-orm-filter-query-schema";
 import type { ZodType } from "zod";
 import { FieldOptions } from "../types/field-options.type";
+/**
+ * Metadata stored on connection classes for query building.
+ *
+ * This metadata is attached to connection classes using the
+ * GRAPHQL_CONNECTION_METADATA symbol and is used by the
+ * ConnectionQueryBuilder to construct queries.
+ *
+ * @typeParam Entity - The entity type for the connection
+ * @internal
+ */
 export interface ConnectionMetadata<Entity extends object> {
+    /**
+     * The MikroORM entity class.
+     */
     entityClass: EntityClass<Entity>;
+    /**
+     * Map of field names to their configuration options.
+     */
     fieldOptionsMap: Map<string, FieldOptions<Entity, FieldType, string>>;
+    /**
+     * Zod schema for validating and parsing filter queries.
+     */
     filterQuerySchema: ZodType<FilterQuery<Entity>>;
 }

package/dist/interfaces/connection.interface.d.ts

@@ -1,7 +1,26 @@
 import { type PageInfo } from "../objects";
 import { type EdgeInterface } from "./edge.interface";
+/**
+ * Represents a paginated connection following the Relay specification.
+ *
+ * A connection contains a list of edges (items with cursors), pagination info,
+ * and the total count of items matching the query.
+ *
+ * @typeParam T - The type of entities in the connection
+ *
+ * @see {@link https://relay.dev/graphql/connections.htm Relay Connection Specification}
+ */
 export interface ConnectionInterface<T> {
+    /**
+     * A list of edges, each containing a node and its cursor.
+     */
     edges: EdgeInterface<T>[];
+    /**
+     * Information about the current page for pagination.
+     */
     pageInfo: PageInfo;
+    /**
+     * The total number of items matching the query (before pagination).
+     */
     totalCount: number;
 }

package/dist/interfaces/edge.interface.d.ts

@@ -1,4 +1,21 @@
+/**
+ * Represents an edge in a GraphQL connection.
+ *
+ * An edge contains a single item (node) and a cursor that can be used
+ * for pagination to fetch items before or after this position.
+ *
+ * @typeParam T - The type of the node (entity) in the edge
+ *
+ * @see {@link https://relay.dev/graphql/connections.htm#sec-Edge-Types Relay Edge Type Specification}
+ */
 export interface EdgeInterface<T> {
+    /**
+     * The item at the end of this edge.
+     */
     node: T;
+    /**
+     * A cursor for use in pagination.
+     * Can be passed to `after` or `before` arguments.
+     */
     cursor: string;
 }

package/dist/interfaces/order-field.type.d.ts

@@ -1,6 +1,31 @@
 import { AutoPath } from "@mikro-orm/core/typings";
+/**
+ * Utility type that converts dot notation to underscore notation.
+ * For example: "user.profile.name" becomes "user_profile_name"
+ * @internal
+ */
 type DotToUnderscore<S extends string> = S extends `${infer Prefix}.${infer Rest}` ? `${Prefix}_${DotToUnderscore<Rest>}` : S;
+/**
+ * The key type for order fields.
+ *
+ * Converts entity field paths to uppercase with underscores.
+ * For example, "createdAt" becomes "CREATED_AT", and "user.name" becomes "USER_NAME".
+ *
+ * @typeParam T - The entity type
+ */
 export type OrderFieldKey<T> = Uppercase<DotToUnderscore<AutoPath<T, string>>>;
+/**
+ * The value type for order fields (the actual field path in the entity).
+ *
+ * @typeParam T - The entity type
+ */
 export type OrderFieldValue<T> = AutoPath<T, string>;
+/**
+ * A record mapping order field keys to their actual field paths.
+ *
+ * Used to create the GraphQL enum for sortable fields.
+ *
+ * @typeParam T - The entity type
+ */
 export type OrderFieldType<T> = Record<OrderFieldKey<T>, OrderFieldValue<T>>;
 export {};

package/dist/interfaces/order.interface.d.ts

@@ -1,6 +1,25 @@
 import { type OrderDirection } from "../enums";
 import { OrderFieldKey } from "./order-field.type";
+/**
+ * Specifies the ordering for a connection query.
+ *
+ * @typeParam T - The entity type being ordered
+ *
+ * @example
+ * ```typescript
+ * const order: OrderInterface<User> = {
+ *   field: "CREATED_AT",
+ *   direction: OrderDirection.DESC,
+ * };
+ * ```
+ */
 export interface OrderInterface<T> {
+    /**
+     * The field to order by (uppercase with underscores, e.g., "CREATED_AT").
+     */
     field: OrderFieldKey<T>;
+    /**
+     * The direction to order (ASC or DESC).
+     */
     direction: OrderDirection;
 }

package/dist/objects/page-info.object.d.ts

@@ -1,6 +1,41 @@
+/**
+ * Provides information about pagination in a connection.
+ *
+ * PageInfo is used to determine whether more pages exist and to fetch
+ * additional pages using cursor-based pagination.
+ *
+ * @see {@link https://relay.dev/graphql/connections.htm#sec-undefined.PageInfo Relay PageInfo Specification}
+ *
+ * @example Using pageInfo for pagination
+ * ```typescript
+ * const result = await connectionManager.find(UserConnection, { first: 10 });
+ *
+ * if (result.pageInfo.hasNextPage) {
+ *   // Fetch next page using endCursor
+ *   const nextPage = await connectionManager.find(UserConnection, {
+ *     first: 10,
+ *     after: result.pageInfo.endCursor,
+ *   });
+ * }
+ * ```
+ */
 export declare class PageInfo {
+    /**
+     * Whether there are more pages to fetch following the current page.
+     */
     hasNextPage: boolean;
+    /**
+     * Whether there are any pages prior to the current page.
+     */
     hasPreviousPage: boolean;
+    /**
+     * The cursor of the first edge in the current page.
+     * Can be used with `before` for backward pagination.
+     */
     startCursor: string | null;
+    /**
+     * The cursor of the last edge in the current page.
+     * Can be used with `after` for forward pagination.
+     */
     endCursor: string | null;
 }

package/dist/objects/page-info.object.js

@@ -11,6 +11,27 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PageInfo = void 0;
 const graphql_1 = require("@nest-boot/graphql");
+/**
+ * Provides information about pagination in a connection.
+ *
+ * PageInfo is used to determine whether more pages exist and to fetch
+ * additional pages using cursor-based pagination.
+ *
+ * @see {@link https://relay.dev/graphql/connections.htm#sec-undefined.PageInfo Relay PageInfo Specification}
+ *
+ * @example Using pageInfo for pagination
+ * ```typescript
+ * const result = await connectionManager.find(UserConnection, { first: 10 });
+ *
+ * if (result.pageInfo.hasNextPage) {
+ *   // Fetch next page using endCursor
+ *   const nextPage = await connectionManager.find(UserConnection, {
+ *     first: 10,
+ *     after: result.pageInfo.endCursor,
+ *   });
+ * }
+ * ```
+ */
 let PageInfo = class PageInfo {
 };
 exports.PageInfo = PageInfo;

package/dist/objects/page-info.object.js.map

@@ -1 +1 @@
-{"version":3,"file":"page-info.object.js","sourceRoot":"","sources":["../../src/objects/page-info.object.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,gDAAuD;AAKhD,IAAM,QAAQ,GAAd,MAAM,QAAQ;CAkBpB,CAAA;AAlBY,4BAAQ;AAKnB;IAJC,IAAA,eAAK,EAAC,GAAG,EAAE,CAAC,OAAO,EAAE;QACpB,UAAU,EAAE,CAAC;QACb,WAAW,EAAE,mEAAmE;KACjF,CAAC;;6CACoB;AAMtB;IAJC,IAAA,eAAK,EAAC,GAAG,EAAE,CAAC,OAAO,EAAE;QACpB,UAAU,EAAE,CAAC;QACb,WAAW,EAAE,wDAAwD;KACtE,CAAC;;iDACwB;AAG1B;IADC,IAAA,eAAK,EAAC,GAAG,EAAE,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;6CACZ;AAG5B;IADC,IAAA,eAAK,EAAC,GAAG,EAAE,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;2CACd;mBAjBf,QAAQ;IAHpB,IAAA,oBAAU,EAAC;QACV,WAAW,EAAE,uKAAuK;KACrL,CAAC;GACW,QAAQ,CAkBpB"}
+{"version":3,"file":"page-info.object.js","sourceRoot":"","sources":["../../src/objects/page-info.object.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,gDAAuD;AAEvD;;;;;;;;;;;;;;;;;;;;GAoBG;AAII,IAAM,QAAQ,GAAd,MAAM,QAAQ;CAgCpB,CAAA;AAhCY,4BAAQ;AAQnB;IAJC,IAAA,eAAK,EAAC,GAAG,EAAE,CAAC,OAAO,EAAE;QACpB,UAAU,EAAE,CAAC;QACb,WAAW,EAAE,mEAAmE;KACjF,CAAC;;6CACoB;AAStB;IAJC,IAAA,eAAK,EAAC,GAAG,EAAE,CAAC,OAAO,EAAE;QACpB,UAAU,EAAE,CAAC;QACb,WAAW,EAAE,wDAAwD;KACtE,CAAC;;iDACwB;AAO1B;IADC,IAAA,eAAK,EAAC,GAAG,EAAE,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;6CACZ;AAO5B;IADC,IAAA,eAAK,EAAC,GAAG,EAAE,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;2CACd;mBA/Bf,QAAQ;IAHpB,IAAA,oBAAU,EAAC;QACV,WAAW,EAAE,uKAAuK;KACrL,CAAC;GACW,QAAQ,CAgCpB"}