aws-service-stack 0.18.421 → 0.18.424

package/dist/service/crud.service.interface.d.ts

@@ -1,11 +1,17 @@
-import { BaseEntity, CognitoUser, DynamoIndexMap, Filter, List } from "../index";
+import { BaseEntity, CognitoUser, DynamoIndexMap, ErrorReason, Filter, HttpStatus, List } from "../index";
 import { EntityConfig } from "../model/index.js";
 /**
- * Defines a generic base service interface for working with entities in both
- * DynamoDB and OpenSearch.
+ * Entity service facade for DynamoDB writes, DynamoDB indexed reads, DynamoDB scans,
+ * and OpenSearch reads.
  */
 export interface CrudService<T extends BaseEntity> {
+    /**
+     * Applies table, index, ownership, trace, and OpenSearch configuration to the service.
+     */
     setConfig(config: EntityConfig): void;
+    /**
+     * Returns the configured DynamoDB table name.
+     */
     getTableName(): string;
     /**
      * Creates a new entity for the given user.
@@ -81,17 +87,41 @@ export interface CrudService<T extends BaseEntity> {
      */
     findByIds(entityIds: string[], requestUser?: CognitoUser): Promise<T[]>;
     /**
-     * Retrieves a paginated and filtered list of entities from DynamoDB.
+     * Executes a DynamoDB Query through a configured index.
      *
-     * @param filter - Filtering and sorting options.
-     * @returns A promise resolving to a paginated list of entities.
+     * `find` never falls back to Scan. The filter must resolve to `indexName` and
+     * `indexValue`, either explicitly or through the entity `DynamoIndexMap`.
+     * Sort-key fields defined in the selected index map entry are used as
+     * DynamoDB key conditions by the repository.
+     *
+     * @param filter - Query-string or filter object that resolves to a DynamoDB index query.
+     * @param debug - When true, logs the generated DynamoDB command.
+     * @returns One DynamoDB query page and an optional pagination `lastKey`.
+     * @throws ErrorHttp or ErrorDynamoDB when the filter cannot resolve to an indexed query.
      */
-    find(filter: Filter | string): Promise<List<Partial<T>>>;
+    find(filter: Filter | string, debug?: boolean): Promise<List<Partial<T>>>;
     /**
-     * Scans the table with non-index filters. Expensive; avoid it for hot paths.
+     * Executes a DynamoDB Scan for non-indexed/ad-hoc filters.
+     *
+     * Scans are expensive and should not be used in hot paths. The filter must
+     * include `queryCountLimit` with a value from 1 to 500. That value limits the
+     * number of internal DynamoDB Scan requests issued by one service call.
+     *
+     * @param filter - Query-string or filter object. Must include `queryCountLimit`.
+     * @param debug - When true, logs each generated DynamoDB Scan command.
+     * @returns Matching items collected before `size`, `queryCountLimit`, or table end is reached.
+     */
+    scan(filter: Filter | string, debug?: boolean): Promise<List<Partial<T>>>;
+    /**
+     * Parses a query string and executes it through `find`.
      */
-    scan(filter: Filter): Promise<List<Partial<T>>>;
     findQuery(queryParams: string): Promise<List<Partial<T>>>;
+    /**
+     * Builds and executes an OpenSearch query DSL request from query-string/filter input.
+     *
+     * @param queryParams - OpenSearch query parser input.
+     * @param debug - When true, logs the generated OpenSearch query.
+     */
     searchQuery(queryParams: any, debug?: boolean): Promise<{
         items: Partial<T>[];
         total: number;
@@ -119,20 +149,31 @@ export interface CrudService<T extends BaseEntity> {
     findByField(fieldName: string, fieldValue: any): Promise<List<T>>;
     findFirst(fieldName: string, fieldValue: string | boolean | number | Date): Promise<T>;
     throwError(code: number, message: string, errorContent?: any): void;
+    throwHttpError(status: HttpStatus, message: string, errorContent?: any, reason?: ErrorReason): void;
+    /**
+     * @deprecated use throwHttpError instead
+     * */
     throwErrorHttp(error: {
         message: string;
         code: number;
     }, message: string, errorContent?: any): void;
+    /**
+     * @deprecated use throwHttpError instead
+     * */
     throwErrorsHttp(code: number, message: string, errorContent?: any): void;
     throwErrorDatabase(tableName: string, command: any, errorContent?: any): void;
     throwErrorValidation(entityName: string, validation: Map<string, any>, errorContent?: any): void;
     /**
-     * Retrieves a filtered and sorted list of entities from OpenSearch.
+     * Executes an OpenSearch read.
+     *
+     * Use `search` for full-text, flexible filtering, aggregations, and views that
+     * are backed by OpenSearch rather than DynamoDB.
      *
-     * @param filter - Filtering and sorting options.
-     * @returns A promise resolving to the list of matching entities.
+     * @param filter - Query-string or filter object for OpenSearch.
+     * @param debug - When true, logs the generated OpenSearch query.
+     * @returns One OpenSearch page.
      */
-    search(filter: Filter | string): Promise<List<Partial<T>>>;
+    search(filter: Filter | string, debug?: boolean): Promise<List<Partial<T>>>;
     searchFieldNotExist(fieldName: string, from: number, size: number): Promise<Partial<T>[]>;
     /**
      * Changes the owner of an entity.
@@ -149,3 +190,4 @@ export interface CrudService<T extends BaseEntity> {
     incrementValueByField(entityId: string, fieldName: string, value?: number): Promise<T>;
     decrementValueByField(entityId: string, fieldName: string, value?: number): Promise<T>;
 }
+//# sourceMappingURL=crud.service.interface.d.ts.map

package/dist/service/crud.service.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crud.service.interface.d.ts","sourceRoot":"","sources":["../../src/service/crud.service.interface.ts"],"names":[],"mappings":"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"}

package/dist/service/crud.service.interface.js.map

@@ -1 +1 @@
-{"version":3,"file":"crud.service.interface.js","sourceRoot":"","sources":["../../src/service/crud.service.interface.ts"],"names":[],"mappings":"","sourcesContent":["import { BaseEntity, CognitoUser, DynamoIndexMap, Filter, List } from \"../index\";\nimport { EntityConfig } from \"@chinggis/types\";\n\n/**\n * Defines a generic base service interface for working with entities in both\n * DynamoDB and OpenSearch.\n */\nexport interface CrudService<T extends BaseEntity> {\n  setConfig(config: EntityConfig): void;\n\n  getTableName(): string;\n  /**\n   * Creates a new entity for the given user.\n   * @param ownerId - The ID of the user who owns the entity.\n   * @param entity - The entity to be created.\n   * @param parentId\n   * @param createdByUser - The created user.\n   * @returns The created entity.\n   */\n  save(entity: Partial<T>, ownerId: string, parentId?: string, createdByUser?: CognitoUser): Promise<T>;\n\n  /**\n   * Creates multiple new entities for the given user.\n   * @param ownerId - The ID of the user who owns the entities.\n   * @param entity - An array of entities to be created.\n   * @param parentId\n   * @param createdByUser - The created user.\n   * @param isTransactional - Whether to perform the operation in a transaction.\n   * @returns An array of created entities.\n   */\n  saveAll(\n    entity: Partial<T>[],\n    ownerId: string,\n    parentId?: string,\n    createdByUser?: CognitoUser,\n    isTransactional?: boolean,\n  ): Promise<Partial<T>[]>;\n\n  /**\n   * Applies partial updates to an entity for the given user.\n   * Only the specified fields will be updated.\n   * @param requestUser - Cognito user, system if not exist\n   * @param entity - The entity with updated fields.\n   * @returns The updated entity.\n   */\n  update(entity: Partial<T>, requestUser?: CognitoUser, fields?: string[]): Promise<T>;\n\n  /**\n   * Applies partial updates to multiple entities for the given user.\n   * Only the specified fields will be updated for each entity.\n   * @param requestUser - Cognito user, system if not exist\n   * @param entity - An array of entities with updated fields.\n   * @param fields - The list of field names to update in each entity. Supports dot paths (e.g. `author.name`).\n   * @param isTransactional - Whether to perform the operation in a transaction.\n   * @returns True if all entities were successfully updated.\n   */\n  updateAll(entity: T[], fields: string[], requestUser?: CognitoUser, isTransactional?: boolean): Promise<boolean>;\n\n  /**\n   * Updates selected fields for one entity. The entity object provides both the\n   * partition-key value (to identify the item) and the new field values to write.\n   * Supports dot paths (e.g. `author.name`).\n   */\n  updateFields(entity: Partial<T>, fields: string[], requestUser?: CognitoUser): Promise<Partial<T>>;\n\n  /**\n   * Deletes an entity by ID for the given user.\n   * @param requestUser - Cognito user, system if not exist\n   * @param entityId - The ID of the entity to delete.\n   * @returns True if the entity was successfully deleted.\n   */\n  remove(entityId: string, requestUser?: CognitoUser): Promise<boolean>;\n\n  deleteFields(entityId: string, fields: string[]): Promise<Partial<T>>;\n\n  /**\n   * Deletes multiple entities by their IDs for the given user.\n   * @param requestUser - Cognito user, system if not exist\n   * @param entityIds - An array of entity IDs to delete.\n   * @returns True if all entities were successfully deleted.\n   */\n  removeAll(entityIds: string[], requestUser?: CognitoUser): Promise<boolean>;\n\n  removeMatch(filter: Filter | string, requestUser?: CognitoUser): Promise<boolean>;\n\n  /**\n   * Retrieves an entity by its ID for the given user.\n   * @param requestUser - Cognito user, system if not exist\n   * @param entityId - The ID of the entity to retrieve.\n   * @returns The requested entity.\n   */\n  findById(entityId: string, requestUser?: CognitoUser): Promise<T>;\n\n  /**\n   * Retrieves multiple entities by their IDs for the given user.\n   * @param requestUser - Cognito user, system if not exist\n   * @param entityIds - An array of entity IDs to retrieve.\n   * @returns An array of found entities.\n   */\n  findByIds(entityIds: string[], requestUser?: CognitoUser): Promise<T[]>;\n\n  /**\n   * Retrieves a paginated and filtered list of entities from DynamoDB.\n   *\n   * @param filter - Filtering and sorting options.\n   * @returns A promise resolving to a paginated list of entities.\n   */\n  find(filter: Filter | string): Promise<List<Partial<T>>>;\n\n  /**\n   * Scans the table with non-index filters. Expensive; avoid it for hot paths.\n   */\n  scan(filter: Filter): Promise<List<Partial<T>>>;\n\n  findQuery(queryParams: string): Promise<List<Partial<T>>>;\n\n  searchQuery(\n    queryParams: any,\n    debug?: boolean,\n  ): Promise<{ items: Partial<T>[]; total: number; aggs?: Record<string, any> }>;\n\n  /**\n   * Returns a lazy async iterator over paginated DynamoDB query results.\n   * Each `next()` call loads the next page only when the current buffer is empty.\n   */\n  findStream(filter: string, size?: number): AsyncGenerator<T>;\n\n  /**\n   * Returns a lazy async iterator over paginated OpenSearch query results.\n   * Each `next()` call loads the next page only when the current buffer is empty.\n   */\n  searchStream(filter: string, size?: number): AsyncGenerator<T>;\n\n  searchStreamAggr(\n    filter: Filter | string,\n    size?: number,\n  ): AsyncGenerator<{ items: Partial<T>[]; total: number; aggs?: Record<string, any> }>;\n\n  searchQueryTotalCount(queryParams: any): Promise<number>;\n\n  findAll(): Promise<T[]>;\n\n  findAllMatch(filter: Filter | string): Promise<T[]>;\n\n  findAllByIndex(indexName: string, indexValue: any): Promise<T[]>;\n\n  findByField(fieldName: string, fieldValue: any): Promise<List<T>>;\n\n  findFirst(fieldName: string, fieldValue: string | boolean | number | Date): Promise<T>;\n\n  throwError(code: number, message: string, errorContent?: any): void;\n\n  throwErrorHttp(error: { message: string; code: number }, message: string, errorContent?: any): void;\n\n  throwErrorsHttp(code: number, message: string, errorContent?: any): void;\n\n  throwErrorDatabase(tableName: string, command: any, errorContent?: any): void;\n\n  throwErrorValidation(entityName: string, validation: Map<string, any>, errorContent?: any): void;\n\n  // throwError(httpStatus: number, message: string): void;\n  /**\n   * Retrieves a filtered and sorted list of entities from OpenSearch.\n   *\n   * @param filter - Filtering and sorting options.\n   * @returns A promise resolving to the list of matching entities.\n   */\n  search(filter: Filter | string): Promise<List<Partial<T>>>;\n\n  searchFieldNotExist(fieldName: string, from: number, size: number): Promise<Partial<T>[]>;\n\n  /**\n   * Changes the owner of an entity.\n   * @param ownerId - The new owner's ID.\n   * @param entityId - The ID of the entity to transfer.\n   * @returns The updated entity with the new owner.\n   */\n  changeOwner(entityId: string, ownerId: string): Promise<T>;\n\n  setTable(tableName: string, dynamoIndexMap: DynamoIndexMap): boolean;\n\n  setOpensearch(indexName: string, opensearchEndpoint: string): boolean;\n\n  getIndexES(): string;\n\n  getIndexMapDB(): DynamoIndexMap;\n\n  setIndexMapDB(indexMap: DynamoIndexMap): boolean;\n\n  incrementValueByField(entityId: string, fieldName: string, value?: number): Promise<T>;\n\n  decrementValueByField(entityId: string, fieldName: string, value?: number): Promise<T>;\n}\n"]}
+{"version":3,"file":"crud.service.interface.js","sourceRoot":"","sources":["../../src/service/crud.service.interface.ts"],"names":[],"mappings":"","sourcesContent":["import { BaseEntity, CognitoUser, DynamoIndexMap, ErrorReason, Filter, HttpStatus, List } from \"../index\";\nimport { EntityConfig } from \"@chinggis/types\";\n\n/**\n * Entity service facade for DynamoDB writes, DynamoDB indexed reads, DynamoDB scans,\n * and OpenSearch reads.\n */\nexport interface CrudService<T extends BaseEntity> {\n  /**\n   * Applies table, index, ownership, trace, and OpenSearch configuration to the service.\n   */\n  setConfig(config: EntityConfig): void;\n\n  /**\n   * Returns the configured DynamoDB table name.\n   */\n  getTableName(): string;\n  /**\n   * Creates a new entity for the given user.\n   * @param ownerId - The ID of the user who owns the entity.\n   * @param entity - The entity to be created.\n   * @param parentId\n   * @param createdByUser - The created user.\n   * @returns The created entity.\n   */\n  save(entity: Partial<T>, ownerId: string, parentId?: string, createdByUser?: CognitoUser): Promise<T>;\n\n  /**\n   * Creates multiple new entities for the given user.\n   * @param ownerId - The ID of the user who owns the entities.\n   * @param entity - An array of entities to be created.\n   * @param parentId\n   * @param createdByUser - The created user.\n   * @param isTransactional - Whether to perform the operation in a transaction.\n   * @returns An array of created entities.\n   */\n  saveAll(\n    entity: Partial<T>[],\n    ownerId: string,\n    parentId?: string,\n    createdByUser?: CognitoUser,\n    isTransactional?: boolean,\n  ): Promise<Partial<T>[]>;\n\n  /**\n   * Applies partial updates to an entity for the given user.\n   * Only the specified fields will be updated.\n   * @param requestUser - Cognito user, system if not exist\n   * @param entity - The entity with updated fields.\n   * @returns The updated entity.\n   */\n  update(entity: Partial<T>, requestUser?: CognitoUser, fields?: string[]): Promise<T>;\n\n  /**\n   * Applies partial updates to multiple entities for the given user.\n   * Only the specified fields will be updated for each entity.\n   * @param requestUser - Cognito user, system if not exist\n   * @param entity - An array of entities with updated fields.\n   * @param fields - The list of field names to update in each entity. Supports dot paths (e.g. `author.name`).\n   * @param isTransactional - Whether to perform the operation in a transaction.\n   * @returns True if all entities were successfully updated.\n   */\n  updateAll(entity: T[], fields: string[], requestUser?: CognitoUser, isTransactional?: boolean): Promise<boolean>;\n\n  /**\n   * Updates selected fields for one entity. The entity object provides both the\n   * partition-key value (to identify the item) and the new field values to write.\n   * Supports dot paths (e.g. `author.name`).\n   */\n  updateFields(entity: Partial<T>, fields: string[], requestUser?: CognitoUser): Promise<Partial<T>>;\n\n  /**\n   * Deletes an entity by ID for the given user.\n   * @param requestUser - Cognito user, system if not exist\n   * @param entityId - The ID of the entity to delete.\n   * @returns True if the entity was successfully deleted.\n   */\n  remove(entityId: string, requestUser?: CognitoUser): Promise<boolean>;\n\n  deleteFields(entityId: string, fields: string[]): Promise<Partial<T>>;\n\n  /**\n   * Deletes multiple entities by their IDs for the given user.\n   * @param requestUser - Cognito user, system if not exist\n   * @param entityIds - An array of entity IDs to delete.\n   * @returns True if all entities were successfully deleted.\n   */\n  removeAll(entityIds: string[], requestUser?: CognitoUser): Promise<boolean>;\n\n  removeMatch(filter: Filter | string, requestUser?: CognitoUser): Promise<boolean>;\n\n  /**\n   * Retrieves an entity by its ID for the given user.\n   * @param requestUser - Cognito user, system if not exist\n   * @param entityId - The ID of the entity to retrieve.\n   * @returns The requested entity.\n   */\n  findById(entityId: string, requestUser?: CognitoUser): Promise<T>;\n\n  /**\n   * Retrieves multiple entities by their IDs for the given user.\n   * @param requestUser - Cognito user, system if not exist\n   * @param entityIds - An array of entity IDs to retrieve.\n   * @returns An array of found entities.\n   */\n  findByIds(entityIds: string[], requestUser?: CognitoUser): Promise<T[]>;\n\n  /**\n   * Executes a DynamoDB Query through a configured index.\n   *\n   * `find` never falls back to Scan. The filter must resolve to `indexName` and\n   * `indexValue`, either explicitly or through the entity `DynamoIndexMap`.\n   * Sort-key fields defined in the selected index map entry are used as\n   * DynamoDB key conditions by the repository.\n   *\n   * @param filter - Query-string or filter object that resolves to a DynamoDB index query.\n   * @param debug - When true, logs the generated DynamoDB command.\n   * @returns One DynamoDB query page and an optional pagination `lastKey`.\n   * @throws ErrorHttp or ErrorDynamoDB when the filter cannot resolve to an indexed query.\n   */\n  find(filter: Filter | string, debug?: boolean): Promise<List<Partial<T>>>;\n\n  /**\n   * Executes a DynamoDB Scan for non-indexed/ad-hoc filters.\n   *\n   * Scans are expensive and should not be used in hot paths. The filter must\n   * include `queryCountLimit` with a value from 1 to 500. That value limits the\n   * number of internal DynamoDB Scan requests issued by one service call.\n   *\n   * @param filter - Query-string or filter object. Must include `queryCountLimit`.\n   * @param debug - When true, logs each generated DynamoDB Scan command.\n   * @returns Matching items collected before `size`, `queryCountLimit`, or table end is reached.\n   */\n  scan(filter: Filter | string, debug?: boolean): Promise<List<Partial<T>>>;\n\n  /**\n   * Parses a query string and executes it through `find`.\n   */\n  findQuery(queryParams: string): Promise<List<Partial<T>>>;\n\n  /**\n   * Builds and executes an OpenSearch query DSL request from query-string/filter input.\n   *\n   * @param queryParams - OpenSearch query parser input.\n   * @param debug - When true, logs the generated OpenSearch query.\n   */\n  searchQuery(\n    queryParams: any,\n    debug?: boolean,\n  ): Promise<{ items: Partial<T>[]; total: number; aggs?: Record<string, any> }>;\n\n  /**\n   * Returns a lazy async iterator over paginated DynamoDB query results.\n   * Each `next()` call loads the next page only when the current buffer is empty.\n   */\n  findStream(filter: string, size?: number): AsyncGenerator<T>;\n\n  /**\n   * Returns a lazy async iterator over paginated OpenSearch query results.\n   * Each `next()` call loads the next page only when the current buffer is empty.\n   */\n  searchStream(filter: string, size?: number): AsyncGenerator<T>;\n\n  searchStreamAggr(\n    filter: Filter | string,\n    size?: number,\n  ): AsyncGenerator<{ items: Partial<T>[]; total: number; aggs?: Record<string, any> }>;\n\n  searchQueryTotalCount(queryParams: any): Promise<number>;\n\n  findAll(): Promise<T[]>;\n\n  findAllMatch(filter: Filter | string): Promise<T[]>;\n\n  findAllByIndex(indexName: string, indexValue: any): Promise<T[]>;\n\n  findByField(fieldName: string, fieldValue: any): Promise<List<T>>;\n\n  findFirst(fieldName: string, fieldValue: string | boolean | number | Date): Promise<T>;\n\n  throwError(code: number, message: string, errorContent?: any): void;\n\n  throwHttpError(status: HttpStatus, message: string, errorContent?: any, reason?: ErrorReason): void;\n\n  /**\n   * @deprecated use throwHttpError instead\n   * */\n  throwErrorHttp(error: { message: string; code: number }, message: string, errorContent?: any): void;\n\n  /**\n   * @deprecated use throwHttpError instead\n   * */\n  throwErrorsHttp(code: number, message: string, errorContent?: any): void;\n\n  throwErrorDatabase(tableName: string, command: any, errorContent?: any): void;\n\n  throwErrorValidation(entityName: string, validation: Map<string, any>, errorContent?: any): void;\n\n  // throwError(httpStatus: number, message: string): void;\n  /**\n   * Executes an OpenSearch read.\n   *\n   * Use `search` for full-text, flexible filtering, aggregations, and views that\n   * are backed by OpenSearch rather than DynamoDB.\n   *\n   * @param filter - Query-string or filter object for OpenSearch.\n   * @param debug - When true, logs the generated OpenSearch query.\n   * @returns One OpenSearch page.\n   */\n  search(filter: Filter | string, debug?: boolean): Promise<List<Partial<T>>>;\n\n  searchFieldNotExist(fieldName: string, from: number, size: number): Promise<Partial<T>[]>;\n\n  /**\n   * Changes the owner of an entity.\n   * @param ownerId - The new owner's ID.\n   * @param entityId - The ID of the entity to transfer.\n   * @returns The updated entity with the new owner.\n   */\n  changeOwner(entityId: string, ownerId: string): Promise<T>;\n\n  setTable(tableName: string, dynamoIndexMap: DynamoIndexMap): boolean;\n\n  setOpensearch(indexName: string, opensearchEndpoint: string): boolean;\n\n  getIndexES(): string;\n\n  getIndexMapDB(): DynamoIndexMap;\n\n  setIndexMapDB(indexMap: DynamoIndexMap): boolean;\n\n  incrementValueByField(entityId: string, fieldName: string, value?: number): Promise<T>;\n\n  decrementValueByField(entityId: string, fieldName: string, value?: number): Promise<T>;\n}\n"]}