dyna-record 0.0.1

package/dist/src/operations/FindById/FindById.js

@@ -0,0 +1,244 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const metadata_1 = __importDefault(require("../../metadata"));
+const dynamo_utils_1 = require("../../dynamo-utils");
+const query_utils_1 = require("../../query-utils");
+const Filters_1 = require("../../query-utils/Filters");
+const dynamo_utils_2 = require("../../dynamo-utils");
+const utils_1 = require("../../utils");
+const OperationBase_1 = __importDefault(require("../OperationBase"));
+const utils_2 = require("../utils");
+const utils_3 = require("../../metadata/utils");
+const Logger_1 = __importDefault(require("../../Logger"));
+/**
+ * Facilitates the retrieval of an entity by its identifier (ID) from the database, potentially including its associated entities based on specified relationships.
+ *
+ * It supports fetching an entity solely by its ID or along with its related entities through specified associations, allowing for flexible retrieval of complex entity graphs in a single operation.
+ *
+ * @template T - The type of the entity being retrieved, extending `DynaRecord`.
+ */
+class FindById extends OperationBase_1.default {
+    #transactionBuilder;
+    constructor(Entity) {
+        super(Entity);
+        this.#transactionBuilder = new dynamo_utils_2.TransactGetBuilder();
+    }
+    /**
+     * Find an entity by Id and optionally include associations
+     * @param {string} id - Entity Id
+     * @param {Object} options - FindById options
+     * @param {Object[]=} options.include - The associations to include in the query
+     * @param {string} options.include[].association - The name of the association to include. Must be defined on the model
+     * @returns An entity with optional included associations serialized
+     */
+    async run(id, options) {
+        if (options?.include === undefined) {
+            return await this.findByIdOnly(id);
+        }
+        else {
+            return await this.findByIdWithIncludes(id, options.include);
+        }
+    }
+    /**
+     * Find an Entity by id without associations
+     * @param {string} id - Entity Id
+     * @returns An entity object or undefined
+     */
+    async findByIdOnly(id) {
+        const { name: tableName } = this.tableMetadata;
+        const res = await dynamo_utils_1.DynamoClient.getItem({
+            TableName: tableName,
+            Key: {
+                [this.partitionKeyAlias]: this.EntityClass.partitionKeyValue(id),
+                [this.sortKeyAlias]: this.EntityClass.name
+            },
+            ConsistentRead: true
+        });
+        if (res === undefined) {
+            return undefined;
+        }
+        else {
+            return (0, utils_1.tableItemToEntity)(this.EntityClass, res);
+        }
+    }
+    /**
+     * Find an entity with included associations
+     * @param {string} id - Entity Id
+     * @param {Object[]=} includedAssociations - The associations to include in the query
+     * @param {string} includedAssociations[].association - The name of the association to include. Must be defined on the model
+     * @returns An entity with included associations serialized
+     */
+    async findByIdWithIncludes(id, includedAssociations) {
+        const includedRels = this.getIncludedRelationships(includedAssociations);
+        const params = this.buildFindByIdIncludesQuery(id, includedRels);
+        const queryResults = await dynamo_utils_1.DynamoClient.query({
+            ...params,
+            ConsistentRead: true
+        });
+        if (queryResults.length === 0) {
+            return undefined;
+        }
+        const sortedQueryResults = this.filterQueryResults(queryResults);
+        const relationsObj = (0, utils_2.buildEntityRelationshipMetaObj)(includedRels);
+        this.buildGetIncludedRelationshipsTransaction(sortedQueryResults, relationsObj);
+        const transactionRes = await this.#transactionBuilder.executeTransaction();
+        return this.resolveFindByIdIncludesResults(sortedQueryResults.item, transactionRes, relationsObj.relationsLookup);
+    }
+    /**
+     * Build the query to find the entity, and any of the BelongsToLinks for the included models
+     * @param id
+     * @param includedRelationships
+     * @returns
+     */
+    buildFindByIdIncludesQuery(id, includedRelationships) {
+        const modelPartitionKey = this.tableMetadata.partitionKeyAttribute.name;
+        const partitionFilter = (0, Filters_1.includedRelationshipsFilter)(this.EntityClass.name, includedRelationships);
+        return new query_utils_1.QueryBuilder({
+            entityClassName: this.EntityClass.name,
+            key: { [modelPartitionKey]: this.EntityClass.partitionKeyValue(id) },
+            options: { filter: partitionFilter }
+        }).build();
+    }
+    /**
+     * Sort query results into an object containing:
+     *  - item: The FindById DynamoItem
+     *  - belongsToLinks: BelongsToLinkDynamoItem records for each of the included relationships
+     * @param queryResults
+     * @returns
+     */
+    filterQueryResults(queryResults) {
+        return queryResults.reduce((acc, res) => {
+            const typeAlias = this.tableMetadata.defaultAttributes.type.alias;
+            if (res[typeAlias] === this.EntityClass.name)
+                acc.item = res;
+            if ((0, utils_1.isBelongsToLinkDynamoItem)(res, this.tableMetadata))
+                acc.belongsToLinks.push(res);
+            return acc;
+        }, { item: {}, belongsToLinks: [] });
+    }
+    buildGetIncludedRelationshipsTransaction(sortedQueryResults, relationsObj) {
+        this.buildGetRelationshipsThroughLinksTransaction(sortedQueryResults.belongsToLinks, relationsObj.relationsLookup);
+        this.buildGetRelationshipsThroughForeignKeyTransaction(sortedQueryResults.item, relationsObj.belongsToRelationships);
+    }
+    /**
+     * Builds transactions to get an associated entity via a BelongsToLink (HasOne or HasMany)
+     * @param belongsToLinks
+     * @param relationsLookup
+     */
+    buildGetRelationshipsThroughLinksTransaction(belongsToLinks, relationsLookup) {
+        const { name: tableName, defaultAttributes } = this.tableMetadata;
+        belongsToLinks.forEach(link => {
+            const foreignKey = link[defaultAttributes.foreignKey.alias];
+            const foreignEntityType = link[defaultAttributes.foreignEntityType.alias];
+            if ((0, utils_1.isPropertyKey)(foreignEntityType) && (0, utils_1.isString)(foreignKey)) {
+                const rel = relationsLookup[foreignEntityType];
+                this.#transactionBuilder.addGet({
+                    TableName: tableName,
+                    Key: {
+                        [this.partitionKeyAlias]: rel.target.partitionKeyValue(foreignKey),
+                        [this.sortKeyAlias]: rel.target.name
+                    }
+                });
+            }
+            else {
+                Logger_1.default.error(
+                // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
+                `Corrupted foreign key value. Invalid type. ${foreignEntityType} - ${foreignKey}`);
+            }
+        });
+    }
+    /**
+     * Builds transactions to get an associated entity using a foreign key on the parent model (BelongsTo)
+     * @param belongsToLinks
+     * @param relationsLookup
+     */
+    buildGetRelationshipsThroughForeignKeyTransaction(item, belongsToRelationships) {
+        if (belongsToRelationships.length > 0) {
+            const { name: tableName } = this.tableMetadata;
+            const attributes = metadata_1.default.getEntityAttributes(this.EntityClass.name);
+            belongsToRelationships.forEach(rel => {
+                const foreignKeyTableAlias = attributes[rel.foreignKey].alias;
+                const foreignKeyVal = item[foreignKeyTableAlias];
+                if (foreignKeyVal === undefined)
+                    return;
+                this.#transactionBuilder.addGet({
+                    TableName: tableName,
+                    Key: {
+                        [this.partitionKeyAlias]: rel.target.partitionKeyValue(foreignKeyVal),
+                        [this.sortKeyAlias]: rel.target.name
+                    }
+                });
+            });
+        }
+    }
+    /**
+     * Get relationship metadata for the associations included in the query
+     * @param includedAssociations
+     * @returns
+     */
+    getIncludedRelationships(includedAssociations) {
+        return includedAssociations.reduce((acc, includedRel) => {
+            const key = includedRel.association;
+            const included = this.entityMetadata.relationships[key];
+            if (included !== undefined)
+                acc.push(included);
+            return acc;
+        }, []);
+    }
+    /**
+     * Serialize the FindById item to its class, serialize results from included relationships query onto the entity
+     * @param entityTableItem
+     * @param transactionResults
+     * @param relationsLookup
+     * @returns
+     */
+    resolveFindByIdIncludesResults(entityTableItem, transactionResults, relationsLookup) {
+        const parentEntity = (0, utils_1.tableItemToEntity)(this.EntityClass, entityTableItem);
+        const typeAlias = this.tableMetadata.defaultAttributes.type.alias;
+        this.setIncludedRelationshipDefaults(parentEntity, relationsLookup);
+        transactionResults.forEach(res => {
+            const tableItem = res.Item;
+            if (tableItem !== undefined) {
+                const rel = relationsLookup[tableItem[typeAlias]];
+                if ((0, utils_1.isKeyOfEntity)(parentEntity, rel.propertyName)) {
+                    if (rel.type === "HasMany" || rel.type === "HasAndBelongsToMany") {
+                        const entity = (0, utils_1.tableItemToEntity)(rel.target, tableItem);
+                        const entities = parentEntity[rel.propertyName] ?? [];
+                        if (Array.isArray(entities)) {
+                            entities.push(entity);
+                        }
+                        Object.assign(parentEntity, { [rel.propertyName]: entities });
+                    }
+                    else {
+                        Object.assign(parentEntity, {
+                            [rel.propertyName]: (0, utils_1.tableItemToEntity)(rel.target, tableItem)
+                        });
+                    }
+                }
+            }
+        });
+        return parentEntity;
+    }
+    /**
+     * Initializes default values for included relationships on a parent entity. It assigns
+     * an empty array to each relationship property for HasMany and HasAndBelongsToMany specified in `relationsLookup` if the property exists on `parentEntity`.
+     *
+     * @param parentEntity - The parent entity to initialize relationship properties on.
+     * @param relationsLookup - A mapping of relationship identifiers to their descriptions, including the relationship
+     * type and the property name on the parent entity.
+     */
+    setIncludedRelationshipDefaults(parentEntity, relationsLookup) {
+        Object.values(relationsLookup).forEach(rel => {
+            if (!(0, utils_1.isKeyOfEntity)(parentEntity, rel.propertyName))
+                return;
+            if ((0, utils_3.isHasManyRelationship)(rel) ||
+                (0, utils_3.isHasAndBelongsToManyRelationship)(rel)) {
+                (0, utils_1.safeAssign)(parentEntity, rel.propertyName, []);
+            }
+        });
+    }
+}
+exports.default = FindById;

package/dist/src/operations/FindById/index.d.ts

@@ -0,0 +1,3 @@
+export { default as FindById } from "./FindById";
+export * from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/operations/FindById/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/operations/FindById/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,YAAY,CAAC;AACjD,cAAc,SAAS,CAAC"}

package/dist/src/operations/FindById/index.js

@@ -0,0 +1,23 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FindById = void 0;
+var FindById_1 = require("./FindById");
+Object.defineProperty(exports, "FindById", { enumerable: true, get: function () { return __importDefault(FindById_1).default; } });
+__exportStar(require("./types"), exports);

package/dist/src/operations/FindById/types.d.ts

@@ -0,0 +1,57 @@
+import type { QueryItems } from "../../dynamo-utils";
+import type DynaRecord from "../../DynaRecord";
+import type { EntityAttributes, RelationshipAttributeNames } from "../types";
+import type { BelongsToLinkDynamoItem } from "../../types";
+/**
+ * Defines options for the `FindById` operation, allowing specification of additional associations to include in the query result.
+ *
+ * @template T - The type of the entity being queried, extending `DynaRecord`.
+ *
+ * @property {Array<{ association: RelationshipAttributeNames<T> }>} [include] - An array of association names to be included in the result of the query. Each association name must be a valid relationship attribute name for the entity `T`.
+ */
+export interface FindByIdOptions<T extends DynaRecord> {
+    include?: Array<{
+        association: RelationshipAttributeNames<T>;
+    }>;
+}
+/**
+ * Represents a list of associations to be included in the query result, derived from the `FindByIdOptions`.
+ *
+ * @template T - The type of the entity being queried, extending `DynaRecord`.
+ */
+export type IncludedAssociations<T extends DynaRecord> = NonNullable<FindByIdOptions<T>["include"]>;
+/**
+ * Describes the structure of query results, sorting them into the main entity item and any associated `BelongsToLink` items. Used during processing
+ *
+ * @property {QueryItems[number]} item - The main entity item retrieved from the query.
+ * @property {BelongsToLinkDynamoItem[]} belongsToLinks - An array of `BelongsToLinkDynamoItem` instances associated with the main entity item.
+ */
+export interface SortedQueryResults {
+    item: QueryItems[number];
+    belongsToLinks: BelongsToLinkDynamoItem[];
+}
+/**
+ * Derives the keys of included associations from `FindByIdOptions`, representing the names of relationships specified to be included in the query result.
+ *
+ * @template T - The type of the entity being queried, extending `DynaRecord`.
+ * @template Opts - The options for the `FindById` operation.
+ */
+type IncludedKeys<T extends DynaRecord, Opts extends FindByIdOptions<T>> = Opts extends Required<FindByIdOptions<T>> ? [...NonNullable<Opts>["include"]][number]["association"] : never;
+/**
+ * Describes the entity attributes, extending them with any specified included associations for comprehensive query results.
+ *
+ * @template T - The type of the entity being queried, extending `DynaRecord`.
+ * @template P - The properties of the entity `T`.
+ */
+type EntityKeysWithIncludedAssociations<T extends DynaRecord, P extends keyof T> = {
+    [K in P]: T[K] extends DynaRecord ? EntityAttributes<T> : T[K] extends DynaRecord[] ? Array<EntityAttributes<T>> : T[K];
+};
+/**
+ * Represents the result of a `FindById` operation, including the main entity and any specified associated entities.
+ *
+ * @template T - The type of the main entity, extending `DynaRecord`.
+ * @template Opts - The options for the `FindById` operation, specifying included associations.
+ */
+export type FindByIdIncludesRes<T extends DynaRecord, Opts extends FindByIdOptions<T>> = EntityKeysWithIncludedAssociations<T, keyof EntityAttributes<T> | IncludedKeys<T, Opts>>;
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/src/operations/FindById/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/operations/FindById/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAC;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,0BAA0B,EAAE,MAAM,UAAU,CAAC;AAC7E,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAE3D;;;;;;GAMG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,UAAU;IACnD,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,WAAW,EAAE,0BAA0B,CAAC,CAAC,CAAC,CAAA;KAAE,CAAC,CAAC;CACjE;AAED;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,SAAS,UAAU,IAAI,WAAW,CAClE,eAAe,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAC9B,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IACzB,cAAc,EAAE,uBAAuB,EAAE,CAAC;CAC3C;AAED;;;;;GAKG;AACH,KAAK,YAAY,CAAC,CAAC,SAAS,UAAU,EAAE,IAAI,SAAS,eAAe,CAAC,CAAC,CAAC,IACrE,IAAI,SAAS,QAAQ,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,GACrC,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,aAAa,CAAC,GACxD,KAAK,CAAC;AAEZ;;;;;GAKG;AACH,KAAK,kCAAkC,CACrC,CAAC,SAAS,UAAU,EACpB,CAAC,SAAS,MAAM,CAAC,IACf;KACD,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,UAAU,GAC7B,gBAAgB,CAAC,CAAC,CAAC,GACnB,CAAC,CAAC,CAAC,CAAC,SAAS,UAAU,EAAE,GACvB,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,GAC1B,CAAC,CAAC,CAAC,CAAC;CACX,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,CAC7B,CAAC,SAAS,UAAU,EACpB,IAAI,SAAS,eAAe,CAAC,CAAC,CAAC,IAC7B,kCAAkC,CACpC,CAAC,EACD,MAAM,gBAAgB,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,EAAE,IAAI,CAAC,CAClD,CAAC"}

package/dist/src/operations/FindById/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/operations/OperationBase.d.ts

@@ -0,0 +1,37 @@
+import type DynaRecord from "../DynaRecord";
+import { type EntityMetadata, type TableMetadata } from "../metadata";
+import type { EntityClass } from "../types";
+/**
+ * Serves as an abstract base class for various operation classes within the ORM system that perform actions on entities, such as creating, updating, querying, or deleting. This class provides shared properties and functionality that are common across different types of operations, centralizing the handling of entity and table metadata.
+ *
+ * @template T - The type of the entity that the operation will be performed on, extending `DynaRecord`.
+ *
+ * @method run
+ * An abstract method that must be implemented by subclasses to execute the specific operation. The parameters and return type of this method can vary depending on the operation being performed.
+ */
+declare abstract class OperationBase<T extends DynaRecord> {
+    /**
+     * The class of the entity on which the operation is performed, providing static methods and properties related to the entity.
+     */
+    protected readonly EntityClass: EntityClass<T>;
+    /**
+     * Metadata for the entity, including information about its attributes and relationships.
+     */
+    protected readonly entityMetadata: EntityMetadata;
+    /**
+     *  Metadata for the table associated with the entity, including details about the table's structure and how the entity's attributes map to table columns.
+     */
+    protected readonly tableMetadata: TableMetadata;
+    /**
+     * The alias used for the entity's partition key attribute in the database table, derived from the table metadata.
+     */
+    protected readonly partitionKeyAlias: string;
+    /**
+     * The alias used for the entity's sort key attribute in the database table, if applicable, derived from the table metadata.
+     */
+    protected readonly sortKeyAlias: string;
+    constructor(Entity: EntityClass<T>);
+    abstract run(...params: unknown[]): unknown;
+}
+export default OperationBase;
+//# sourceMappingURL=OperationBase.d.ts.map

package/dist/src/operations/OperationBase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OperationBase.d.ts","sourceRoot":"","sources":["../../../src/operations/OperationBase.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,UAAU,MAAM,eAAe,CAAC;AAC5C,OAAiB,EAAE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C;;;;;;;GAOG;AACH,uBAAe,aAAa,CAAC,CAAC,SAAS,UAAU;IAC/C;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;IAE/C;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IAElD;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IAEhD;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IAE7C;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;gBAE5B,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;aAQlB,GAAG,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO;CACnD;AAED,eAAe,aAAa,CAAC"}

package/dist/src/operations/OperationBase.js

@@ -0,0 +1,44 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const metadata_1 = __importDefault(require("../metadata"));
+/**
+ * Serves as an abstract base class for various operation classes within the ORM system that perform actions on entities, such as creating, updating, querying, or deleting. This class provides shared properties and functionality that are common across different types of operations, centralizing the handling of entity and table metadata.
+ *
+ * @template T - The type of the entity that the operation will be performed on, extending `DynaRecord`.
+ *
+ * @method run
+ * An abstract method that must be implemented by subclasses to execute the specific operation. The parameters and return type of this method can vary depending on the operation being performed.
+ */
+class OperationBase {
+    /**
+     * The class of the entity on which the operation is performed, providing static methods and properties related to the entity.
+     */
+    EntityClass;
+    /**
+     * Metadata for the entity, including information about its attributes and relationships.
+     */
+    entityMetadata;
+    /**
+     *  Metadata for the table associated with the entity, including details about the table's structure and how the entity's attributes map to table columns.
+     */
+    tableMetadata;
+    /**
+     * The alias used for the entity's partition key attribute in the database table, derived from the table metadata.
+     */
+    partitionKeyAlias;
+    /**
+     * The alias used for the entity's sort key attribute in the database table, if applicable, derived from the table metadata.
+     */
+    sortKeyAlias;
+    constructor(Entity) {
+        this.EntityClass = Entity;
+        this.entityMetadata = metadata_1.default.getEntity(Entity.name);
+        this.tableMetadata = metadata_1.default.getTable(this.entityMetadata.tableClassName);
+        this.partitionKeyAlias = this.tableMetadata.partitionKeyAttribute.alias;
+        this.sortKeyAlias = this.tableMetadata.sortKeyAttribute.alias;
+    }
+}
+exports.default = OperationBase;

package/dist/src/operations/Query/Query.d.ts

@@ -0,0 +1,45 @@
+import type DynaRecord from "../../DynaRecord";
+import { type QueryOptions as QueryBuilderOptions } from "../../query-utils";
+import OperationBase from "../OperationBase";
+import type { EntityKeyConditions, QueryOptions, QueryResults } from "./types";
+/**
+ * Provides functionality to query entities from the database based on partition key, sort key, and optional filter conditions.
+ *
+ * The `Query` operation supports two main query patterns: querying by a simple entity ID or by more complex key conditions that include partition key, optional sort key, and filters. It can handle querying for both entities and their relationships, like "BelongsTo" links, based on the provided conditions.
+ *
+ * @template T - The type of the entity being queried, extending `DynaRecord`.
+ */
+declare class Query<T extends DynaRecord> extends OperationBase<T> {
+    /**
+     * Run the query operation
+     * @param key EntityId or object with PartitionKey and optional SortKey conditions
+     * @param options Filter conditions, indexName, or SortKey conditions if querying by keys
+     * @returns Array of Entity or BelongsToLinks
+     */
+    run(key: string | EntityKeyConditions<T>, options?: QueryBuilderOptions | Omit<QueryOptions, "indexName">): Promise<QueryResults<T>>;
+    /**
+     * Query by PartitionKey and optional SortKey/Filter/Index conditions
+     * @param {Object} key - PartitionKey value and optional SortKey condition. Keys must be attributes defined on the model
+     * @param {Object=} options - QueryBuilderOptions. Supports filter and indexName
+     * @param {Object=} options.filter - Filter conditions object. Keys must be attributes defined on the model. Value can be exact value for Equality. Array for "IN" or $beginsWith
+     * @param {string=} options.indexName - The name of the index to filter on
+     */
+    private queryByKey;
+    /**
+     * Query an EntityPartition by EntityId and optional SortKey/Filter conditions.
+     * QueryByIndex not supported. Use Query with keys if indexName is needed
+     * @param {string} id - Entity Id
+     * @param {Object=} options - QueryOptions. Supports filter and skCondition
+     * @param {Object=} options.skCondition - Sort Key condition. Can be an exact value or { $beginsWith: "val" }
+     * @param {Object=} options.filter - Filter conditions object. Keys must be attributes defined on the model. Value can be exact value for Equality. Array for "IN" or $beginsWith
+     */
+    private queryEntity;
+    /**
+     * Resolve dynamo query results to the entity class
+     * @param queryResults
+     * @returns
+     */
+    private resolveQueryResults;
+}
+export default Query;
+//# sourceMappingURL=Query.d.ts.map

package/dist/src/operations/Query/Query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Query.d.ts","sourceRoot":"","sources":["../../../../src/operations/Query/Query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAEL,KAAK,YAAY,IAAI,mBAAmB,EACzC,MAAM,mBAAmB,CAAC;AAQ3B,OAAO,aAAa,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,mBAAmB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE/E;;;;;;GAMG;AACH,cAAM,KAAK,CAAC,CAAC,SAAS,UAAU,CAAE,SAAQ,aAAa,CAAC,CAAC,CAAC;IACxD;;;;;OAKG;IACU,GAAG,CACd,GAAG,EAAE,MAAM,GAAG,mBAAmB,CAAC,CAAC,CAAC,EACpC,OAAO,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,GAC9D,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAQ3B;;;;;;OAMG;YACW,UAAU;IAexB;;;;;;;OAOG;YACW,WAAW;IAyBzB;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;CAS5B;AAED,eAAe,KAAK,CAAC"}

package/dist/src/operations/Query/Query.js

@@ -0,0 +1,84 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const query_utils_1 = require("../../query-utils");
+const DynamoClient_1 = __importDefault(require("../../dynamo-utils/DynamoClient"));
+const utils_1 = require("../../utils");
+const OperationBase_1 = __importDefault(require("../OperationBase"));
+/**
+ * Provides functionality to query entities from the database based on partition key, sort key, and optional filter conditions.
+ *
+ * The `Query` operation supports two main query patterns: querying by a simple entity ID or by more complex key conditions that include partition key, optional sort key, and filters. It can handle querying for both entities and their relationships, like "BelongsTo" links, based on the provided conditions.
+ *
+ * @template T - The type of the entity being queried, extending `DynaRecord`.
+ */
+class Query extends OperationBase_1.default {
+    /**
+     * Run the query operation
+     * @param key EntityId or object with PartitionKey and optional SortKey conditions
+     * @param options Filter conditions, indexName, or SortKey conditions if querying by keys
+     * @returns Array of Entity or BelongsToLinks
+     */
+    async run(key, options) {
+        if (typeof key === "string") {
+            return await this.queryEntity(key, options);
+        }
+        else {
+            return await this.queryByKey(key, options);
+        }
+    }
+    /**
+     * Query by PartitionKey and optional SortKey/Filter/Index conditions
+     * @param {Object} key - PartitionKey value and optional SortKey condition. Keys must be attributes defined on the model
+     * @param {Object=} options - QueryBuilderOptions. Supports filter and indexName
+     * @param {Object=} options.filter - Filter conditions object. Keys must be attributes defined on the model. Value can be exact value for Equality. Array for "IN" or $beginsWith
+     * @param {string=} options.indexName - The name of the index to filter on
+     */
+    async queryByKey(key, options) {
+        const params = new query_utils_1.QueryBuilder({
+            entityClassName: this.EntityClass.name,
+            key,
+            options
+        }).build();
+        const queryResults = await DynamoClient_1.default.query(params);
+        return this.resolveQueryResults(queryResults);
+    }
+    /**
+     * Query an EntityPartition by EntityId and optional SortKey/Filter conditions.
+     * QueryByIndex not supported. Use Query with keys if indexName is needed
+     * @param {string} id - Entity Id
+     * @param {Object=} options - QueryOptions. Supports filter and skCondition
+     * @param {Object=} options.skCondition - Sort Key condition. Can be an exact value or { $beginsWith: "val" }
+     * @param {Object=} options.filter - Filter conditions object. Keys must be attributes defined on the model. Value can be exact value for Equality. Array for "IN" or $beginsWith
+     */
+    async queryEntity(id, options) {
+        const modelPk = this.tableMetadata.partitionKeyAttribute.name;
+        const modelSk = this.tableMetadata.sortKeyAttribute.name;
+        const keyCondition = {
+            [modelPk]: this.EntityClass.partitionKeyValue(id),
+            ...(options?.skCondition !== undefined && {
+                [modelSk]: options?.skCondition
+            })
+        };
+        const params = new query_utils_1.QueryBuilder({
+            entityClassName: this.EntityClass.name,
+            key: keyCondition,
+            options
+        }).build();
+        const queryResults = await DynamoClient_1.default.query(params);
+        return this.resolveQueryResults(queryResults);
+    }
+    /**
+     * Resolve dynamo query results to the entity class
+     * @param queryResults
+     * @returns
+     */
+    resolveQueryResults(queryResults) {
+        return queryResults.map(res => (0, utils_1.isBelongsToLinkDynamoItem)(res, this.tableMetadata)
+            ? (0, utils_1.tableItemToBelongsToLink)(this.tableMetadata, res)
+            : (0, utils_1.tableItemToEntity)(this.EntityClass, res));
+    }
+}
+exports.default = Query;

package/dist/src/operations/Query/index.d.ts

@@ -0,0 +1,3 @@
+export { default as Query } from "./Query";
+export * from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/operations/Query/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/operations/Query/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,KAAK,EAAE,MAAM,SAAS,CAAC;AAC3C,cAAc,SAAS,CAAC"}

package/dist/src/operations/Query/index.js

@@ -0,0 +1,23 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Query = void 0;
+var Query_1 = require("./Query");
+Object.defineProperty(exports, "Query", { enumerable: true, get: function () { return __importDefault(Query_1).default; } });
+__exportStar(require("./types"), exports);

package/dist/src/operations/Query/types.d.ts

@@ -0,0 +1,38 @@
+import type DynaRecord from "../../DynaRecord";
+import type { KeyConditions, QueryOptions as QueryBuilderOptions, SortKeyCondition } from "../../query-utils";
+import type { BelongsToLink } from "../../relationships";
+import type { EntityAttributes } from "../types";
+/**
+ * Extends the basic query builder options by adding an optional sort key condition for more precise querying capabilities.
+ *
+ * @extends QueryBuilderOptions - Base query options provided by the query utilities.
+ * @property {SortKeyCondition?} skCondition - An optional condition for the sort key to further refine the query. This can be an exact match condition or a condition specifying a range or beginning match for the sort key.
+ */
+export interface QueryOptions extends QueryBuilderOptions {
+    /**
+     * Condition to query sort key by
+     */
+    skCondition?: SortKeyCondition;
+}
+/**
+ * Defines partition key conditions for querying entities based on their keys. This type is used to specify the conditions under which an entity or a set of entities can be queried from the database.
+ *
+ * @template T - The type of the entity being queried, extending `DynaRecord`.
+ * @property {KeyConditions} - Conditions applied to entity keys. Each key in the entity can have conditions such as equality, range conditions, or begins with conditions.
+ */
+export type EntityKeyConditions<T> = {
+    [K in keyof T]?: KeyConditions;
+};
+/**
+ * Represents the results of a query operation, which can include both entity attributes and associated `BelongsToLink` objects.
+ *
+ * @template T - The type of the entity being queried, extending `DynaRecord`.
+ */
+export type QueryResults<T extends DynaRecord> = Array<EntityAttributes<T> | BelongsToLink>;
+/**
+ * A utility type that represents a single item in the query results, which can be either an entity or a `BelongsToLink`. This type is derived from the `QueryResults` array type, providing a convenient way to refer to individual results from a query.
+ *
+ * @template T - The type of the entity being queried, extending `DynaRecord`.
+ */
+export type QueryResult<T extends DynaRecord> = QueryResults<T>[number];
+//# sourceMappingURL=types.d.ts.map

package/dist/src/operations/Query/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/operations/Query/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAC;AAC/C,OAAO,KAAK,EACV,aAAa,EACb,YAAY,IAAI,mBAAmB,EACnC,gBAAgB,EACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,WAAW,YAAa,SAAQ,mBAAmB;IACvD;;OAEG;IACH,WAAW,CAAC,EAAE,gBAAgB,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI;KAClC,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,aAAa;CAC/B,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,UAAU,IAAI,KAAK,CACpD,gBAAgB,CAAC,CAAC,CAAC,GAAG,aAAa,CACpC,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,UAAU,IAAI,YAAY,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/src/operations/Query/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });