@dcupl/common 1.11.10 → 2.0.0-beta.0

package/dist/esm/types/query.types.d.ts

@@ -1,80 +1,578 @@
 import { ListItem } from './data.types';
 import { Projection, SortingProjection } from './projection.types';
+/**
+ * Transform options for query values.
+ * - `lowercase`: Convert value to lowercase before comparison
+ * - `trim`: Remove leading/trailing whitespace
+ * - `removeWhitespace`: Remove all whitespace characters
+ */
 export type DcuplQueryTransformOptions = 'lowercase' | 'trim' | 'removeWhitespace';
 export declare const DcuplQueryOperatorsAsArray: readonly ["eq", "find", "gt", "gte", "lt", "lte", "typeof", "isTruthy", "size"];
+/**
+ * Query operators for filtering data.
+ *
+ * Available operators:
+ * - `eq`: Equality check - matches exact values
+ * - `find`: Partial text or object match - searches within strings or objects
+ * - `gt`: Greater than - numeric/date comparison (exclusive)
+ * - `gte`: Greater than or equal - numeric/date comparison (inclusive)
+ * - `lt`: Less than - numeric/date comparison (exclusive)
+ * - `lte`: Less than or equal - numeric/date comparison (inclusive)
+ * - `typeof`: Type check - validates data type
+ * - `isTruthy`: Boolean check - evaluates truthiness
+ * - `size`: Array/string length check - matches collection size
+ *
+ * @example
+ * ```typescript
+ * // Equality
+ * { operator: 'eq', attribute: 'status', value: 'active' }
+ *
+ * // Numeric comparison
+ * { operator: 'gte', attribute: 'price', value: 100 }
+ *
+ * // Text search
+ * { operator: 'find', attribute: 'name', value: 'search term' }
+ * ```
+ */
 export type DcuplQueryOperator = (typeof DcuplQueryOperatorsAsArray)[number];
+/**
+ * Query combination logic.
+ * - `and`: All conditions must match (intersection)
+ * - `or`: At least one condition must match (union)
+ *
+ * @example
+ * ```typescript
+ * // AND logic - both conditions must be true
+ * { groupType: 'and', queries: [condition1, condition2] }
+ *
+ * // OR logic - either condition can be true
+ * { groupType: 'or', queries: [condition1, condition2] }
+ * ```
+ */
 export type DcuplQueryType = 'and' | 'or';
+/**
+ * Base query properties shared by all query types.
+ */
 type DcuplQueryBase = {
+    /**
+     * The attribute/property name to query against.
+     * Can reference nested properties using dot notation (e.g., 'user.email').
+     */
     attribute: string;
+    /**
+     * Optional identifier for this query condition.
+     * Useful for tracking or removing specific queries.
+     */
     queryKey?: any;
+    /**
+     * Optional discriminator for type narrowing.
+     * @internal
+     */
+    __type?: 'query';
+    /**
+     * Query behavior modifiers.
+     */
     options?: {
+        /**
+         * Transform value before comparison.
+         * Applied in order: ['lowercase', 'trim'] applies lowercase first, then trim.
+         */
         transform?: DcuplQueryTransformOptions[];
+        /**
+         * Invert the query result (NOT operation).
+         * @example
+         * ```typescript
+         * // Find items where status is NOT 'active'
+         * { operator: 'eq', attribute: 'status', value: 'active', options: { invert: true } }
+         * ```
+         */
         invert?: boolean;
+        /**
+         * When querying array values, determines match behavior.
+         * - `some`: Match if at least one array element matches (default)
+         * - `every`: Match only if all array elements match
+         *
+         * @example
+         * ```typescript
+         * // Match items where ANY tag equals 'featured'
+         * { operator: 'eq', attribute: 'tags', value: 'featured', options: { arrayValueHandling: 'some' } }
+         *
+         * // Match items where ALL tags equal 'featured'
+         * { operator: 'eq', attribute: 'tags', value: 'featured', options: { arrayValueHandling: 'every' } }
+         * ```
+         */
         arrayValueHandling?: 'some' | 'every';
     };
 };
+/**
+ * Equality query - matches exact values.
+ *
+ * @example
+ * ```typescript
+ * // Match items with status 'active'
+ * { operator: 'eq', attribute: 'status', value: 'active' }
+ *
+ * // Match items with a reference key
+ * { operator: 'eq', attribute: 'categoryId', value: { key: 'cat-123' } }
+ *
+ * // Case-insensitive match
+ * { operator: 'eq', attribute: 'name', value: 'john', options: { transform: ['lowercase'] } }
+ * ```
+ */
 type DcuplQueryEq = DcuplQueryBase & {
     operator: 'eq';
     /**
-     * You may search for any value but
-     * only values of type string and { key:string } may be used for indexed search
+     * Value to match against.
+     * Note: For indexed search optimization, use string or { key: string } values.
      */
     value: any;
 };
+/**
+ * Find query - partial text or object match.
+ * Searches within strings (substring match) or checks object property existence.
+ *
+ * @example
+ * ```typescript
+ * // Find items containing 'search' in description
+ * { operator: 'find', attribute: 'description', value: 'search' }
+ *
+ * // Find items with specific nested property
+ * { operator: 'find', attribute: 'metadata', value: { key: 'value' } }
+ * ```
+ */
 type DcuplQueryFind = DcuplQueryBase & {
     operator: 'find';
+    /**
+     * Text to search for (substring) or object with properties to match.
+     */
     value: Record<string, unknown> | string;
 };
+/**
+ * Numeric/date comparison queries.
+ * Supports greater than, less than, and inclusive variants.
+ *
+ * @example
+ * ```typescript
+ * // Items with price greater than 100
+ * { operator: 'gt', attribute: 'price', value: 100 }
+ *
+ * // Items created after a date
+ * { operator: 'gte', attribute: 'createdAt', value: new Date('2024-01-01') }
+ *
+ * // Items with quantity less than or equal to 10
+ * { operator: 'lte', attribute: 'quantity', value: 10 }
+ * ```
+ */
 type DcuplQueryNumbers = DcuplQueryBase & {
     operator: 'gt' | 'lt' | 'gte' | 'lte';
+    /**
+     * Numeric value, date, or string representation for comparison.
+     */
     value: string | number | Date;
 };
+/**
+ * Type check query - validates data type.
+ *
+ * @example
+ * ```typescript
+ * // Match items where price is a number
+ * { operator: 'typeof', attribute: 'price', value: 'number' }
+ *
+ * // Match items where tags is an array
+ * { operator: 'typeof', attribute: 'tags', value: 'object' }
+ * ```
+ */
 type DcuplQueryTypeOf = DcuplQueryBase & {
     operator: 'typeof';
+    /**
+     * JavaScript type name: 'string', 'number', 'boolean', 'object', 'undefined', 'function', 'symbol'
+     */
     value: string;
 };
+/**
+ * Truthiness check query - evaluates boolean truthiness.
+ *
+ * @example
+ * ```typescript
+ * // Match items where isActive is truthy
+ * { operator: 'isTruthy', attribute: 'isActive', value: true }
+ *
+ * // Match items where isDeleted is falsy
+ * { operator: 'isTruthy', attribute: 'isDeleted', value: false }
+ * ```
+ */
 type DcuplQueryIsTruthy = DcuplQueryBase & {
     operator: 'isTruthy';
+    /**
+     * Expected truthiness: true for truthy values, false for falsy values.
+     */
     value: boolean;
 };
+/**
+ * Size check query - matches array length or string length.
+ *
+ * @example
+ * ```typescript
+ * // Match items with exactly 3 tags
+ * { operator: 'size', attribute: 'tags', value: 3 }
+ *
+ * // Match items with name exactly 10 characters long
+ * { operator: 'size', attribute: 'name', value: 10 }
+ * ```
+ */
 type DcuplQuerySize = DcuplQueryBase & {
     operator: 'size';
+    /**
+     * Expected length/size of the array or string.
+     */
     value: number;
 };
+/**
+ * Query condition - represents a single filter criterion.
+ * Use this to filter items based on attribute values.
+ *
+ * @see QueryCondition - Type alias with clearer naming
+ *
+ * @example
+ * ```typescript
+ * // Simple equality check
+ * const query: DcuplQuery = {
+ *   operator: 'eq',
+ *   attribute: 'status',
+ *   value: 'active'
+ * };
+ *
+ * // Numeric comparison with options
+ * const priceQuery: DcuplQuery = {
+ *   operator: 'gte',
+ *   attribute: 'price',
+ *   value: 100,
+ *   options: { invert: false }
+ * };
+ * ```
+ */
 export type DcuplQuery = DcuplQueryEq | DcuplQueryNumbers | DcuplQueryTypeOf | DcuplQueryIsTruthy | DcuplQuerySize | DcuplQueryFind;
+/**
+ * Query group - combines multiple conditions with AND/OR logic.
+ * Groups can be nested to create complex filter expressions.
+ *
+ * @see QueryConditionGroup - Type alias with clearer naming
+ *
+ * @example
+ * ```typescript
+ * // AND group - all conditions must match
+ * const andGroup: DcuplQueryGroup = {
+ *   groupType: 'and',
+ *   groupKey: 'active-products',
+ *   queries: [
+ *     { operator: 'eq', attribute: 'status', value: 'active' },
+ *     { operator: 'gte', attribute: 'price', value: 100 }
+ *   ]
+ * };
+ *
+ * // OR group - at least one condition must match
+ * const orGroup: DcuplQueryGroup = {
+ *   groupType: 'or',
+ *   queries: [
+ *     { operator: 'eq', attribute: 'category', value: 'electronics' },
+ *     { operator: 'eq', attribute: 'category', value: 'books' }
+ *   ]
+ * };
+ *
+ * // Nested groups
+ * const nestedGroup: DcuplQueryGroup = {
+ *   groupType: 'and',
+ *   queries: [
+ *     { operator: 'eq', attribute: 'status', value: 'active' },
+ *     {
+ *       groupType: 'or',
+ *       queries: [
+ *         { operator: 'eq', attribute: 'featured', value: true },
+ *         { operator: 'gte', attribute: 'rating', value: 4.5 }
+ *       ]
+ *     }
+ *   ]
+ * };
+ * ```
+ */
 export type DcuplQueryGroup<ChildQuery extends DcuplQuery | DcuplQueryGroup = any> = {
+    /**
+     * Optional discriminator for type narrowing.
+     * @internal
+     */
+    __type?: 'group';
+    /**
+     * Combination logic for conditions in this group.
+     * Defaults to 'and' if not specified.
+     */
     groupType?: DcuplQueryType;
+    /**
+     * Optional identifier for this group.
+     * Useful for tracking or removing specific query groups.
+     */
     groupKey?: string;
+    /**
+     * Array of query conditions or nested groups.
+     */
     queries: Array<ChildQuery>;
 };
+/**
+ * Common options for data retrieval operations.
+ * Controls pagination, projection, and sorting.
+ *
+ * @see ItemDataOptions - Type alias with clearer naming
+ */
 type DcuplItemOptions<T> = {
+    /**
+     * Starting index for pagination (0-based).
+     * @example start: 10 // Skip first 10 items
+     */
     start?: number;
+    /**
+     * Maximum number of items to return.
+     * @example count: 20 // Return up to 20 items
+     */
     count?: number;
+    /**
+     * Specify which properties to include/exclude in results.
+     */
     projection?: Projection<T>;
+    /**
+     * Define sorting order for results.
+     */
     sort?: SortingProjection<T>;
 };
+/**
+ * Options for executing queries across the global dcupl instance.
+ * Combines model specification, query conditions, and data retrieval options.
+ *
+ * @see QueryExecutionContext - Type alias with clearer naming
+ *
+ * @example
+ * ```typescript
+ * const options: DcuplGlobalQueryOptions<Product> = {
+ *   modelKey: 'Product',
+ *   queries: [
+ *     { operator: 'eq', attribute: 'status', value: 'active' }
+ *   ],
+ *   start: 0,
+ *   count: 20,
+ *   sort: { price: 'asc' }
+ * };
+ * ```
+ */
 export type DcuplGlobalQueryOptions<T> = {
+    /**
+     * Model identifier to query against.
+     */
     modelKey: string;
 } & DcuplItemOptions<T> & DcuplQueryGroup;
+/**
+ * Options for retrieving a single item from the global dcupl instance.
+ */
 export type DcuplGlobalItemOptions<T> = {
+    /**
+     * Model identifier.
+     */
     modelKey: string;
+    /**
+     * Item identifier.
+     */
     itemKey: string;
+    /**
+     * Optional projection to control returned properties.
+     */
     projection?: Projection<T>;
 };
+/**
+ * Options for retrieving multiple specific items from the global dcupl instance.
+ */
 export type DcuplGlobalManyItemOptions<T> = {
+    /**
+     * Model identifier.
+     */
     modelKey: string;
+    /**
+     * Array of item identifiers.
+     */
     itemKeys: string[];
+    /**
+     * Optional projection to control returned properties.
+     */
     projection?: Projection<T>;
 };
+/**
+ * Options for executing queries on a list instance.
+ * Combines query conditions with data retrieval options.
+ *
+ * @see ListQueryOptions - Type alias with clearer naming
+ *
+ * @example
+ * ```typescript
+ * const options: DcuplListQueryOptions<Product> = {
+ *   queries: [
+ *     { operator: 'gte', attribute: 'price', value: 50 }
+ *   ],
+ *   groupType: 'and',
+ *   count: 10
+ * };
+ * const results = list.catalog.query.execute(options);
+ * ```
+ */
 export type DcuplListQueryOptions<T> = DcuplItemOptions<T> & DcuplQueryGroup;
+/**
+ * Options for retrieving a specific item from a list instance.
+ */
 export type DcuplListItemOptions<T> = DcuplItemOptions<T> & {
+    /**
+     * Item identifier.
+     */
     itemKey: string;
 };
+/**
+ * Custom operator function for extending query capabilities.
+ * Receives a query condition and list item, returns whether the item matches.
+ *
+ * @example
+ * ```typescript
+ * const customOperator: CustomOperatorFn = (query, listItem) => {
+ *   const value = listItem.data[query.attribute];
+ *   return value !== undefined;
+ * };
+ * ```
+ */
 export type CustomOperatorFn = (query: DcuplQuery, listItem: ListItem) => boolean;
+/**
+ * Map of custom operator names to their implementation functions.
+ */
 export type CustomOperatorFnMap = Map<string, CustomOperatorFn>;
+/**
+ * Internal query statement representation.
+ * Used for query execution and optimization.
+ *
+ * @internal
+ */
 export type DcuplQueryStatement<T = any> = DcuplItemOptions<T> & {
     modelKey: string;
     groupType?: DcuplQueryType;
     queries: DcuplQuery[] | DcuplQueryGroup<DcuplQuery>[] | DcuplQueryGroup<DcuplQueryGroup<DcuplQuery>>[];
 };
+/**
+ * Query condition - represents a single filter criterion.
+ * Alias for {@link DcuplQuery} with clearer naming.
+ *
+ * Use this to filter items based on attribute values using various operators.
+ *
+ * @example
+ * ```typescript
+ * // Equality check
+ * const condition: QueryCondition = {
+ *   operator: 'eq',
+ *   attribute: 'status',
+ *   value: 'active'
+ * };
+ *
+ * // Numeric comparison
+ * const priceCondition: QueryCondition = {
+ *   operator: 'gte',
+ *   attribute: 'price',
+ *   value: 100
+ * };
+ * ```
+ */
+export type QueryCondition = DcuplQuery;
+/**
+ * Query group - combines multiple conditions with AND/OR logic.
+ * Alias for {@link DcuplQueryGroup} with clearer naming.
+ *
+ * Groups can be nested to create complex filter expressions.
+ *
+ * @example
+ * ```typescript
+ * // AND group
+ * const group: QueryConditionGroup = {
+ *   groupType: 'and',
+ *   queries: [
+ *     { operator: 'eq', attribute: 'status', value: 'active' },
+ *     { operator: 'gte', attribute: 'price', value: 100 }
+ *   ]
+ * };
+ *
+ * // Nested groups
+ * const nested: QueryConditionGroup = {
+ *   groupType: 'and',
+ *   queries: [
+ *     { operator: 'eq', attribute: 'status', value: 'active' },
+ *     {
+ *       groupType: 'or',
+ *       queries: [
+ *         { operator: 'eq', attribute: 'featured', value: true },
+ *         { operator: 'gte', attribute: 'rating', value: 4.5 }
+ *       ]
+ *     }
+ *   ]
+ * };
+ * ```
+ */
+export type QueryConditionGroup<ChildQuery extends DcuplQuery | DcuplQueryGroup = any> = DcuplQueryGroup<ChildQuery>;
+/**
+ * Query execution context for global dcupl operations.
+ * Alias for {@link DcuplGlobalQueryOptions} with clearer naming.
+ *
+ * Combines model specification, query conditions, and data retrieval options.
+ *
+ * @example
+ * ```typescript
+ * const context: QueryExecutionContext<Product> = {
+ *   modelKey: 'Product',
+ *   queries: [
+ *     { operator: 'eq', attribute: 'status', value: 'active' }
+ *   ],
+ *   groupType: 'and',
+ *   start: 0,
+ *   count: 20,
+ *   sort: { price: 'asc' }
+ * };
+ * const results = dcupl.data.query(context);
+ * ```
+ */
+export type QueryExecutionContext<T> = DcuplGlobalQueryOptions<T>;
+/**
+ * Options for executing queries on a list instance.
+ * Alias for {@link DcuplListQueryOptions} with clearer naming.
+ *
+ * Combines query conditions with pagination, projection, and sorting options.
+ *
+ * @example
+ * ```typescript
+ * const options: ListQueryOptions<Product> = {
+ *   queries: [
+ *     { operator: 'gte', attribute: 'price', value: 50 }
+ *   ],
+ *   groupType: 'and',
+ *   start: 0,
+ *   count: 10,
+ *   sort: { name: 'asc' }
+ * };
+ * const results = list.catalog.query.execute(options);
+ * ```
+ */
+export type ListQueryOptions<T> = DcuplListQueryOptions<T>;
+/**
+ * Common data retrieval options.
+ * Alias for {@link DcuplItemOptions} with clearer naming.
+ *
+ * Controls pagination, projection, and sorting for data operations.
+ *
+ * @example
+ * ```typescript
+ * const options: ItemDataOptions<Product> = {
+ *   start: 0,
+ *   count: 20,
+ *   projection: { name: true, price: true },
+ *   sort: { price: 'desc' }
+ * };
+ * ```
+ */
+export type ItemDataOptions<T> = DcuplItemOptions<T>;
 export {};