@dcupl/common 2.0.0-beta.3 → 2.0.0-beta.6

package/dist/esm/indices.controller.d.ts

@@ -1,4 +1,4 @@
-import { InverseIndexValuesMap, InverseIndexDataValuesMap, ListItem } from './types';
+import { InverseIndexValuesMap, InverseIndexDataValuesMap, ListItem } from './types/index.js';
 /**
  * Statistics about indices for monitoring
  */

package/dist/esm/logger/index.d.ts

@@ -1,2 +1,2 @@
-export { Logger, logger } from './logger';
-export type { LogLevel, LoggerConfig, LogEntry, TrackedErrorEntry } from './logger';
+export { Logger, logger } from './logger.js';
+export type { LogLevel, LoggerConfig, LogEntry, TrackedErrorEntry } from './logger.js';

package/dist/esm/pivot.d.ts

@@ -1,5 +1,5 @@
-import { IndicesController } from './indices.controller';
-import { ListItem, Aggregation, AggregationOptions } from './types';
+import { IndicesController } from './indices.controller.js';
+import { ListItem, Aggregation, AggregationOptions } from './types/index.js';
 type PivotRowOption = {
     attribute: string;
     calculateTotals?: boolean;

package/dist/esm/property-parser.d.ts

@@ -1,5 +1,30 @@
-import { Property, PropertyType } from './types';
-export declare const getPropertiesForData: (data: any[], deep: boolean) => Property[];
+import { Property, PropertyType } from './types/index.js';
+export declare const coerceStringType: (value: string) => PropertyType;
+export declare const looksDateLike: (value: string) => boolean;
+export type GetPropertiesForDataOptions = {
+    deep?: boolean;
+    sampleSize?: number;
+    /** @deprecated No longer honored — empty values are always skipped for type
+     * inference and counted toward ColumnDiagnostic.emptyRate. */
+    ignoreEmpty?: boolean;
+};
+export type ColumnDiagnostic = {
+    column: string;
+    inferredType: PropertyType;
+    observedTypes: PropertyType[];
+    emptyRate: number;
+    conflict: boolean;
+    hint?: string;
+};
+export type InferModelOptions = GetPropertiesForDataOptions & {
+    coerceStrings?: boolean;
+};
+export type InferModelResult = {
+    properties: Property[];
+    diagnostics: ColumnDiagnostic[];
+};
+export declare const inferModel: (data: any[], options?: InferModelOptions) => InferModelResult;
+export declare const getPropertiesForData: (data: any[], deepOrOptions?: boolean | GetPropertiesForDataOptions) => Property[];
 export declare const isInt: (n: any) => boolean;
 export declare const isFloat: (n: any) => boolean;
 export declare const getDcuplPropertyTypeForNativeType: (value: any) => PropertyType;

package/dist/esm/query-builder.d.ts

@@ -1,5 +1,5 @@
-import { DcuplGlobalQueryOptions, DcuplItemsOptions, DcuplQuery, DcuplQueryGroup } from './types';
-import { DeepQueryService } from './deep-query.service';
+import { DcuplGlobalQueryOptions, DcuplItemsOptions, DcuplQuery, DcuplQueryGroup } from './types/index.js';
+import { DeepQueryService } from './deep-query.service.js';
 export type QueryAttributeEntry = {
     attribute: string;
     reference?: string;

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

@@ -1,4 +1,4 @@
-import { BooleanFilterItem, BooleanFilterOptions, DateFilterItem, DateFilterOptions, DcuplQueryGroup, DcuplQueryStatement, NumberFilterItem, NumberFilterOptions, ReferenceFilterItem, ReferenceFilterOptions, TextFilterItem, TextFilterOptions } from './types';
+import { BooleanFilterItem, BooleanFilterOptions, DateFilterItem, DateFilterOptions, DcuplQueryGroup, DcuplQueryStatement, NumberFilterItem, NumberFilterOptions, ReferenceFilterItem, ReferenceFilterOptions, TextFilterItem, TextFilterOptions } from './types/index.js';
 export declare const generateTextQuery: (options: TextFilterOptions, filterItem?: TextFilterItem) => DcuplQueryGroup;
 export declare const generateBooleanQuery: (options: BooleanFilterOptions, filterItem?: BooleanFilterItem) => DcuplQueryGroup;
 export declare const generateNumberAndDateQuery: (options: NumberFilterOptions | DateFilterOptions, filterItem?: NumberFilterItem | DateFilterItem) => DcuplQueryGroup;

package/dist/esm/queryData.d.ts

@@ -1,5 +1,5 @@
-import { ListItem, InverseIndexReferenceMap, DcuplQueryTransformOptions, CustomOperatorFn, DcuplGlobalQueryOptions } from './types';
-import { ScriptController } from './script.controller';
+import { ListItem, InverseIndexReferenceMap, DcuplQueryTransformOptions, CustomOperatorFn, DcuplGlobalQueryOptions } from './types/index.js';
+import { ScriptController } from './script.controller.js';
 import { ModelParser } from '@dcupl/core/model-parser';
 import { ItemService } from '@dcupl/core/catalog';
 export declare class QueryManager {

package/dist/esm/types/app-loader.types.d.ts

@@ -1,4 +1,5 @@
-import { DataContainerType } from './';
+import { AutoGeneratePropertiesOption, DataContainerType } from './index.js';
+import { KeyPropertySpec } from './key-property.types.js';
 export declare namespace AppLoaderConfiguration {
     /**
      * The base structure for configuration file contains all resources, evnironments and headers
@@ -55,7 +56,7 @@ export declare namespace AppLoaderConfiguration {
         defaultDataContainerUpdateType?: DataContainerType;
         csvParserOptions?: CsvParserOptions;
         missingModelHandling?: {
-            autoGenerateProperties?: boolean;
+            autoGenerateProperties?: AutoGeneratePropertiesOption;
         };
     };
     export type CsvParserOptions = {
@@ -181,9 +182,25 @@ export declare namespace AppLoaderConfiguration {
     };
     export type DataResourceOptions = {
         updateType?: DataContainerType;
-        keyProperty?: string;
+        /**
+         * Property name(s) on each row that uniquely identify it.
+         *
+         * Pass a single string for a simple key (`keyProperty: 'ID'`) or a
+         * non-empty array for a composite key (`keyProperty: ['ID', 'Language']`).
+         * Composite parts are joined into the internal `.key` using
+         * `keyPropertySeparator` (default `::`). Order is preserved literally.
+         *
+         * Each part is stringified via `String(value)`, so `null`, `undefined`,
+         * and `''` produce distinct keys (`'null'`, `'undefined'`, `''`).
+         */
+        keyProperty?: KeyPropertySpec;
+        /**
+         * Separator joining composite `keyProperty` parts. Default `'::'`.
+         * Ignored when `keyProperty` is a string or a single-element array.
+         */
+        keyPropertySeparator?: string;
         autoGenerateKey?: boolean;
-        autoGenerateProperties?: boolean;
+        autoGenerateProperties?: AutoGeneratePropertiesOption;
         csvParserOptions?: CsvParserOptions;
     };
     export type Resource = ModelResource | DataResource | TransformerResource | CustomOperatorResource | CustomScriptResource;

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

@@ -1,3 +1,5 @@
+import { AutoGeneratePropertiesOption } from './model.types.js';
+import { KeyPropertySpec } from './key-property.types.js';
 export type RawItem = any;
 export type ListItem = {
     key: string;
@@ -7,15 +9,17 @@ export type DataContainer<ListType extends RawItem | ListItem = ListItem, ModelN
     model: ModelNames;
     type?: DataContainerType;
     data: ListType[];
-    keyProperty?: string;
+    keyProperty?: KeyPropertySpec;
+    keyPropertySeparator?: string;
     autoGenerateKey?: boolean;
-    autoGenerateProperties?: boolean;
+    autoGenerateProperties?: AutoGeneratePropertiesOption;
     placeholderUid?: string;
 };
 export type DataContainerType = 'upsert' | 'update' | 'set' | 'remove';
 export type ReferenceDataTypes<ListType extends ListItem = ListItem> = string | string[] | ListType | ListType[];
 export type DataOptions<ModelNames extends string = string> = {
     model: ModelNames;
-    keyProperty?: string;
+    keyProperty?: KeyPropertySpec;
+    keyPropertySeparator?: string;
     autoGenerateKey?: boolean;
 };

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

@@ -1,12 +1,12 @@
-import { DcuplUpdateMessage } from '../changeDetection';
-import { PivotOptions } from '../pivot';
-import { AggregationOptions } from './aggregation.types';
-import { DcuplFacetOptions } from './facets.types';
-import { DcuplGroupByOptions } from './group-by.types';
-import { DcuplItemsOptions } from './list.types';
-import { DcuplGlobalQueryOptions } from './query.types';
-import { SuggestionOptions } from './suggestion.types';
-import { LogLevel, LogEntry } from '../logger';
+import { DcuplUpdateMessage } from '../changeDetection.js';
+import { PivotOptions } from '../pivot.js';
+import { AggregationOptions } from './aggregation.types.js';
+import { DcuplFacetOptions } from './facets.types.js';
+import { DcuplGroupByOptions } from './group-by.types.js';
+import { DcuplItemsOptions } from './list.types.js';
+import { DcuplGlobalQueryOptions } from './query.types.js';
+import { SuggestionOptions } from './suggestion.types.js';
+import { LogLevel, LogEntry } from '../logger/index.js';
 export type DcuplInitOptions = {
     config?: DcuplInitConfig;
     /**
@@ -98,6 +98,18 @@ export type DcuplPartialUpdateConfig = {
 };
 export type DcuplInitQualityConfig = {
     enabled: boolean;
+    /**
+     * Maximum number of stored error objects per (model, property, errorType)
+     * group. Quality errors are still counted exactly beyond this limit and are
+     * reachable via `getErrorCounts()`; only the retained error objects (and the
+     * `$DcuplErrorTrackingErrors` model) are bounded. Default: 1000.
+     *
+     * Note: for error groups whose true count exceeds `maxErrorsPerGroup`,
+     * partial-update cleanup may cause `getErrorCounts()` to slightly
+     * over-report, since over-cap occurrences are counted but never stored as
+     * error objects and therefore cannot be decremented on removal.
+     */
+    maxErrorsPerGroup?: number;
 };
 export type DcuplInitErrorTrackingConfig = {
     enabled: boolean;

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

@@ -1,4 +1,4 @@
-import { ListItem } from './data.types';
+import { ListItem } from './data.types.js';
 export type DcuplFacetOptions = {
     attribute: string;
     count?: number;
@@ -6,6 +6,11 @@ export type DcuplFacetOptions = {
     excludeUndefineds?: boolean;
     excludeUnresolved?: boolean;
     calculateResults?: boolean;
+    /**
+     * Opt-in deterministic ordering. See `DcuplFilterOptions.sort` for full semantics.
+     * When omitted the fast (insertion-order) path is preserved.
+     */
+    sort?: 'size-desc' | 'size-asc' | 'value-asc' | 'value-desc';
 };
 export type DcuplFacet = {
     key: string;

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

@@ -1,6 +1,6 @@
-import { DcuplQueryGroup, ListItem } from '.';
-import { CatalogApiOptions } from './list.types';
-import { FilterComparisonType } from './model.types';
+import { DcuplQueryGroup, ListItem } from './index.js';
+import { CatalogApiOptions } from './list.types.js';
+import { FilterComparisonType } from './model.types.js';
 export type NumberConstraintOperators = {
     gt?: number;
     lt?: number;

package/dist/esm/types/group-by.types.d.ts

@@ -1,5 +1,5 @@
-import { AggregationOptions } from './aggregation.types';
-import { DcuplItemsOptions } from './list.types';
+import { AggregationOptions } from './aggregation.types.js';
+import { DcuplItemsOptions } from './list.types.js';
 export type DcuplSectionItemOption<T> = DcuplItemsOptions<T> & {
     key: string;
 };

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

@@ -1,16 +1,17 @@
-export * from './aggregation.types';
-export * from './app-loader.types';
-export * from './data.types';
-export * from './dcupl.types';
-export * from './facets.types';
-export * from './filter.types';
-export * from './group-by.types';
-export * from './internal.types';
-export * from './list.types';
-export * from './model.types';
-export * from './projection.types';
-export * from './quality.types';
-export * from './query.types';
-export * from './section.types';
-export * from './suggestion.types';
-export * from './testing.types';
+export * from './aggregation.types.js';
+export * from './app-loader.types.js';
+export * from './key-property.types.js';
+export * from './data.types.js';
+export * from './dcupl.types.js';
+export * from './facets.types.js';
+export * from './filter.types.js';
+export * from './group-by.types.js';
+export * from './internal.types.js';
+export * from './list.types.js';
+export * from './model.types.js';
+export * from './projection.types.js';
+export * from './quality.types.js';
+export * from './query.types.js';
+export * from './section.types.js';
+export * from './suggestion.types.js';
+export * from './testing.types.js';

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

@@ -1,4 +1,4 @@
-import { ListItem } from './data.types';
+import { ListItem } from './data.types.js';
 export type InverseIndexReferenceMap = Map<string, InverseIndexValuesMap>;
 export type InverseIndexValuesMap = Map<string, Set<string>>;
 export type InverseIndexDataMap = Map<string, InverseIndexDataValuesMap>;

package/dist/esm/types/key-property.types.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Specifies the property (or properties) on a row that uniquely identifies it.
+ *
+ * - A single string names one property: `keyProperty: 'id'`.
+ * - A non-empty array of strings produces a composite key by joining the
+ *   stringified values of each property with the configured separator
+ *   (default `::`): `keyProperty: ['ID', 'Language']` → `.key === 'A1::en'`.
+ *
+ * The order of array entries is significant and preserved verbatim.
+ */
+export type KeyPropertySpec = string | readonly string[];

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

@@ -1,7 +1,7 @@
-import { DcuplGlobalQueryOptions } from './query.types';
-import { ViewDefinition, ModelAttribute } from './model.types';
-import { Projection, SortingProjection } from './projection.types';
-import { ListItem } from './data.types';
+import { DcuplGlobalQueryOptions } from './query.types.js';
+import { ViewDefinition, ModelAttribute } from './model.types.js';
+import { Projection, SortingProjection } from './projection.types.js';
+import { ListItem } from './data.types.js';
 export type DcuplItemsOptions<T> = {
     start?: number;
     count?: number;
@@ -22,6 +22,22 @@ export type DcuplFilterOptions = CatalogApiOptions & {
     excludeUndefineds?: boolean;
     excludeUnresolved?: boolean;
     count?: number;
+    /**
+     * Opt-in deterministic ordering for facet results.
+     *
+     * When omitted (default), results are returned in inverse-index iteration
+     * order and `count` truncation is applied mid-iteration. This is the
+     * fast path and matches all existing call sites.
+     *
+     * When set, `getFacets` walks all facet keys, computes real sizes
+     * (overriding `calculateFacets: false`), applies the chosen sort with
+     * deterministic tie-break, and truncates to `count` after sorting.
+     * This is the slow but correct path — opt in when ordering matters.
+     *
+     * Tie-break for size sorts is always `value` ascending with `undefined`
+     * last. `value-desc` keeps `undefined` last as well.
+     */
+    sort?: 'size-desc' | 'size-asc' | 'value-asc' | 'value-desc';
 };
 export type DcuplFiltersOptions = DcuplFilterOptions & {
     filterKeys?: string[];

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

@@ -1,10 +1,28 @@
-import { AggregationOptions, DcuplGlobalQueryOptions, DcuplQuery, DcuplQueryGroup, RawItem } from '.';
-import { PivotOptions } from '../pivot';
+import { AggregationOptions, DcuplGlobalQueryOptions, DcuplQuery, DcuplQueryGroup, RawItem } from './index.js';
+import { KeyPropertySpec } from './key-property.types.js';
+import { PivotOptions } from '../pivot.js';
 type AggregationOptionsModel = Omit<AggregationOptions, 'attribute'>;
 export type PropertyType = 'any' | 'Array<date>' | 'Array<float>' | 'Array<int>' | 'Array<string>' | 'boolean' | 'date' | 'float' | 'int' | 'json' | 'string';
 export declare const PropertyTypesAsArray: PropertyType[];
 export declare const NumberPropertyTypes: PropertyType[];
 export declare const DatePropertyTypes: PropertyType[];
+/**
+ * Configures how property auto-generation inspects input data.
+ *
+ * - `true` / `false`: enable/disable auto-generation. When enabled with `true`,
+ *   only the first row of input data is inspected (fast, default behavior).
+ * - Object form lets you scan more rows:
+ *   - `deep: true` walks every row and reconciles types across them.
+ *   - `sampleSize: N` walks at most N rows (implies deep). Useful for large datasets
+ *     where row 1 alone may not represent the schema.
+ *
+ * When more than one row is scanned, empty values (`null`, `undefined`, `''`)
+ * are ignored during inference so a single blank cell does not poison a column's type.
+ */
+export type AutoGeneratePropertiesOption = boolean | {
+    deep?: boolean;
+    sampleSize?: number;
+};
 /**
  *  must be singleValued or  multiValued
  * singleValued contains only one key to an object
@@ -355,9 +373,17 @@ export type ModelDefinition<ModelNames extends string = string> = {
     properties?: Property[];
     references?: Reference[];
     data?: RawItem[];
-    keyProperty?: string;
+    /**
+     * Property name(s) on each row that uniquely identify it.
+     * See `KeyPropertySpec` for composite-key behavior.
+     */
+    keyProperty?: KeyPropertySpec;
+    /**
+     * Separator joining composite `keyProperty` parts. Default `'::'`.
+     */
+    keyPropertySeparator?: string;
     autoGenerateKey?: boolean;
-    autoGenerateProperties?: boolean;
+    autoGenerateProperties?: AutoGeneratePropertiesOption;
     supportsAutoCreation?: boolean;
     valueMappings?: ValueMappingConfig[];
     meta?: ModelMetadata;

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

@@ -1,6 +1,60 @@
 export declare namespace QualityAnalyzer {
     type ModelErrorGroup = 'ReferenceDataError' | 'PropertyDataError' | 'DataContainerError' | 'ModelDefinitionError';
-    type ModelErrorType = 'UndefinedAttribute' | 'InvalidValidator' | 'UndefinedValue' | 'NullValue' | 'WrongDataType' | 'NonUniqueKey' | 'MissingModel' | 'MissingProperty' | 'MissingReference' | 'UnknownExpressionVariable' | 'RemoteReferenceKeyNotFound' | 'InvalidModelDefinition';
+    /**
+     * Error types emitted by the quality controller during model registration
+     * and data ingest.
+     *
+     * - `UndefinedAttribute`  — A declared attribute has no corresponding column /
+     *   field in an ingested data container. Fires once per (model, attribute).
+     * - `InvalidValidator`   — A validator on a property could not be parsed or
+     *   evaluated against the data.
+     * - `UndefinedValue`     — A required property has no value on a specific
+     *   data entry (the cell is `undefined`). Fires per-row.
+     * - `NullValue`          — A non-nullable property has an explicit `null` on
+     *   a specific data entry. Fires per-row.
+     * - `WrongDataType`      — A value present on a data entry could not be
+     *   coerced to the declared property type. Fires per-row. Also covers *lossy*
+     *   numeric coercions where coercion succeeds but silently drops information —
+     *   trailing/embedded non-numeric content (e.g. `"1.2 lbs"` → `1.2`) or
+     *   fractional truncation for `int` properties (e.g. `"1.2"` → `1`). Lossy
+     *   records carry `meta.lossy: true` plus `meta.rawValue` and
+     *   `meta.coercedValue`; the coerced value is still kept on the data entry.
+     *   Representation-only differences that preserve the value (leading/trailing
+     *   zeros, surrounding whitespace, `"4.0"` → `4`) are not flagged.
+     *   Aggregation (#197): when one or more cells of a typed column fail to coerce,
+     *   the per-row signals are consolidated into a single `WrongDataType` per
+     *   `(model, attribute)` with `meta.rowCount` = the number of failing rows
+     *   (exact and cap-independent for loader/CSV sources; bounded by
+     *   `maxErrorsPerGroup` for inline data). `getErrorCounts()` reports the stored
+     *   *record* count (1 for an aggregated column), which is intentionally distinct
+     *   from `meta.rowCount`. A column entirely absent from the source still
+     *   produces `UndefinedAttribute`, not `WrongDataType`.
+     * - `NonUniqueKey`       — Two or more data entries share the same key value
+     *   in the same model; later rows are dropped.
+     * - `MissingModel`       — A reference points to a model key that has not
+     *   been registered.
+     * - `MissingProperty`    — Emitted only during model-definition validation
+     *   when a *derived property* declares `derive.remoteProperty` pointing to a
+     *   property that does not exist on the remote model. Not used in any
+     *   CSV/JSON data-ingest path — those are covered by `UndefinedAttribute`,
+     *   `UndefinedValue`, and `WrongDataType`. See model.helper.ts (derived-
+     *   property validator) for the sole emit site.
+     * - `MissingReference`   — A derived property's `derive.localReference` names
+     *   a reference that does not exist on the local model.
+     * - `UnknownExpressionVariable` — An expression property references a
+     *   variable that is neither a property nor a reference on the local model.
+     * - `RemoteReferenceKeyNotFound` — A foreign-key value does not match any
+     *   key in the referenced remote model. Fires per-row.
+     * - `InvalidModelDefinition` — Catch-all for structural problems detected
+     *   when registering a model.
+     * - `UnknownColumn`          — A CSV (or otherwise source-tracked) data
+     *   container contains a column / attribute that is not declared on the
+     *   target model. Values for the column are silently dropped during ingest;
+     *   this error surfaces that data loss without failing the load. Fires once
+     *   per (model, attribute). Only emitted when the loader registers source
+     *   metadata for the container (so inline `model.data` is unaffected).
+     */
+    type ModelErrorType = 'UndefinedAttribute' | 'InvalidValidator' | 'UndefinedValue' | 'NullValue' | 'WrongDataType' | 'NonUniqueKey' | 'MissingModel' | 'MissingProperty' | 'MissingReference' | 'UnknownExpressionVariable' | 'RemoteReferenceKeyNotFound' | 'InvalidModelDefinition' | 'UnknownColumn';
     type DcuplErrorType = 'model' | 'loader';
     type DcuplErrorBase = {
         key?: string;

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

@@ -1,5 +1,5 @@
-import { ListItem } from './data.types';
-import { Projection, SortingProjection } from './projection.types';
+import { ListItem } from './data.types.js';
+import { Projection, SortingProjection } from './projection.types.js';
 /**
  * Transform options for query values.
  * - `lowercase`: Convert value to lowercase before comparison
@@ -13,7 +13,7 @@ export declare const DcuplQueryOperatorsAsArray: readonly ["eq", "find", "gt", "
  *
  * Available operators:
  * - `eq`: Equality check - matches exact values
- * - `find`: Partial text or object match - searches within strings or objects
+ * - `find`: Regex / exact / object match - bare string is exact-equality, `/regex/` for substring/pattern, object for property match
  * - `gt`: Greater than - numeric/date comparison (exclusive)
  * - `gte`: Greater than or equal - numeric/date comparison (inclusive)
  * - `lt`: Less than - numeric/date comparison (exclusive)
@@ -30,8 +30,8 @@ export declare const DcuplQueryOperatorsAsArray: readonly ["eq", "find", "gt", "
  * // Numeric comparison
  * { operator: 'gte', attribute: 'price', value: 100 }
  *
- * // Text search
- * { operator: 'find', attribute: 'name', value: 'search term' }
+ * // Substring search (slash-delimited regex; bare string would be exact-match)
+ * { operator: 'find', attribute: 'name', value: '/search term/' }
  * ```
  */
 export type DcuplQueryOperator = (typeof DcuplQueryOperatorsAsArray)[number];
@@ -128,13 +128,22 @@ type DcuplQueryEq = DcuplQueryBase & {
     value: any;
 };
 /**
- * Find query - partial text or object match.
- * Searches within strings (substring match) or checks object property existence.
+ * Find query - regex / exact / object match.
+ *
+ * Matching depends on the shape of `value`:
+ * - **Bare string** (e.g. `'search'`) — exact-equality against the *whole* field
+ *   value, NOT a substring. `find` with `'Ball'` does not match `'Soccer Ball'`.
+ * - **Slash-delimited regex** (e.g. `'/search/'`, `'/^foo/i'`) — JS regex literal;
+ *   use this for substring and pattern matching.
+ * - **Object** (e.g. `{ key: 'value' }`) — property matching against the field.
  *
  * @example
  * ```typescript
- * // Find items containing 'search' in description
- * { operator: 'find', attribute: 'description', value: 'search' }
+ * // Substring search — slash-delimited regex (bare string would be exact-match)
+ * { operator: 'find', attribute: 'description', value: '/search/' }
+ *
+ * // Exact-match the whole field value
+ * { operator: 'find', attribute: 'status', value: 'active' }
  *
  * // Find items with specific nested property
  * { operator: 'find', attribute: 'metadata', value: { key: 'value' } }
@@ -143,7 +152,7 @@ type DcuplQueryEq = DcuplQueryBase & {
 type DcuplQueryFind = DcuplQueryBase & {
     operator: 'find';
     /**
-     * Text to search for (substring) or object with properties to match.
+     * Bare string (exact-match), `/regex/` (substring/pattern), or object (property match).
      */
     value: Record<string, unknown> | string;
 };

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

@@ -1,5 +1,5 @@
-import { ListItem } from './data.types';
-import { Aggregation } from './aggregation.types';
+import { ListItem } from './data.types.js';
+import { Aggregation } from './aggregation.types.js';
 export type GroupByResponse = {
     _meta: {
         currentSize: number;

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

@@ -1,4 +1,4 @@
-import { DcuplQuery, DcuplQueryGroup, DcuplQueryTransformOptions } from './query.types';
+import { DcuplQuery, DcuplQueryGroup, DcuplQueryTransformOptions } from './query.types.js';
 type SuggestionOptionsBase = {
     attribute: string;
     value: any;