Type Definitions

type DcuplInitOptions = {
  config?: DcuplInitConfig;
  quality?: DcuplInitQualityConfig;
  performance?: DcuplInitPerformanceConfig;
  analytics?: DcuplInitErrorAnalyticsConfig;
  referenceMetadata?: DcuplInitReferenceMetadataConfig;
  logging?: DcuplInitLoggingConfig;
};

type DcuplInitConfig = {
  projectId?: string;
  apiKey?: string;
  version?: string;
};

type DcuplInitPerformanceConfig = {
  cache?: {
    enabled: boolean;
  };
  clone?: {
    enabled: boolean;
  };
  partialUpdates?: DcuplPartialUpdateConfig;
  containerBatchSize?: number;
  autoUpdateLists?: {
    enabled: boolean;
  };
};

type DcuplPartialUpdateConfig = {
  modelRatioThreshold?: number;
  itemRatioThreshold?: number;
  cacheInvalidationThreshold?: number;
  enableDetailedLogging?: boolean;
};

type DcuplInitQualityConfig = {
  enabled: boolean;
};

type DcuplInitLoggingConfig = {
  level?: LogLevel;
  format?: 'json' | 'pretty';
  onLog?: (entry: LogEntry) => void;
  modules?: Record<string, LogLevel>;
};

type LogLevel = 'debug' | 'info' | 'warn' | 'error';

type DcuplUpdateOptions = {
  autoUpdateLists?: boolean;
};

type ModelDefinition = {
  key: string;
  keyProperty?: string;
  properties?: PropertyDefinition[];
  references?: ReferenceDefinition[];
  quality?: ModelQualityConfig;
  data?: RawItem[];
  autoGenerateKey?: boolean;
  autoGenerateProperties?: boolean;
  supportsAutoCreation?: boolean;
  valueMappings?: ValueMappingConfig[];
  meta?: ModelMetadata;
};

type PropertyDefinition = {
  key: string;
  type: PropertyType;
  displayKey?: string;
  quality?: PropertyQualityConfig;
  expression?: string;
  derive?: {
    localReference: string;
    remoteProperty: string;
    separator?: string;
  };
  filter?: boolean | FilterConfig;
  aggregate?: boolean | AggregationOptionsModel;
  index?: boolean;
};

type PropertyType =
  | 'string'
  | 'int'
  | 'float'
  | 'boolean'
  | 'date'
  | 'json'
  | 'any'
  | 'Array<string>'
  | 'Array<int>'
  | 'Array<float>'
  | 'Array<date>';

type ReferenceDefinition = {
  key: string;
  model: string;
  type: ReferenceType;
  separator?: string;
  filter?: boolean | FilterConfig;
  aggregate?: boolean | AggregationOptionsModel;
  index?: boolean;
  validity?: ValidityConfig;
};

type ReferenceType = 'singleValued' | 'multiValued';

type RawItem = {
  key?: string;
  [property: string]: any;
};

type DataOptions = {
  model: string;
  keyProperty?: string;
  autoGenerateKey?: boolean;
};

type DataContainer = {
  model: string;
  type?: DataContainerType;
  data: RawItem[];
  keyProperty?: string;
  autoGenerateKey?: boolean;
  autoGenerateProperties?: boolean;
  placeholderUid?: string;
};

type DataContainerType = 'upsert' | 'update' | 'set' | 'remove';

type DcuplQuery =
  | DcuplQueryEq
  | DcuplQueryNumbers
  | DcuplQueryTypeOf
  | DcuplQueryIsTruthy
  | DcuplQuerySize
  | DcuplQueryFind;

type DcuplQueryBase = {
  attribute: string;
  queryKey?: any;
  options?: DcuplQueryOptions;
};

// Equality check
const statusQuery: DcuplQuery = {
  operator: 'eq',
  attribute: 'status',
  value: 'active'
};

// Numeric comparison with options
const priceQuery: DcuplQuery = {
  operator: 'gte',
  attribute: 'price',
  value: 100,
  options: { invert: false }
};

// Text search
const searchQuery: DcuplQuery = {
  operator: 'find',
  attribute: 'description',
  value: 'search term'
};

type DcuplQueryOperator =
  | 'eq'       // Equality check - matches exact values
  | 'find'     // Partial text or object match
  | 'gt'       // Greater than (exclusive)
  | 'gte'      // Greater than or equal (inclusive)
  | 'lt'       // Less than (exclusive)
  | 'lte'      // Less than or equal (inclusive)
  | 'typeof'   // Type check - validates data type
  | 'isTruthy' // Boolean check - evaluates truthiness
  | 'size';    // Array/string length check

// Equality
{ operator: 'eq', attribute: 'status', value: 'active' }

// Numeric comparison
{ operator: 'gte', attribute: 'price', value: 100 }

// Text search
{ operator: 'find', attribute: 'name', value: 'search term' }

// Type check
{ operator: 'typeof', attribute: 'price', value: 'number' }

// Truthiness
{ operator: 'isTruthy', attribute: 'isActive', value: true }

// Array size
{ operator: 'size', attribute: 'tags', value: 3 }

type DcuplQueryOptions = {
  transform?: DcuplQueryTransformOptions[];
  invert?: boolean;
  arrayValueHandling?: 'some' | 'every';
};

type DcuplQueryTransformOptions = 'lowercase' | 'trim' | 'removeWhitespace';

// Case-insensitive search
{
  operator: 'eq',
  attribute: 'name',
  value: 'john',
  options: { transform: ['lowercase', 'trim'] }
}

// Find items where status is NOT 'active'
{
  operator: 'eq',
  attribute: 'status',
  value: 'active',
  options: { invert: true }
}

// Match items where ALL tags equal 'featured'
{
  operator: 'eq',
  attribute: 'tags',
  value: 'featured',
  options: { arrayValueHandling: 'every' }
}

type DcuplQueryGroup<ChildQuery = DcuplQuery | DcuplQueryGroup> = {
  groupType?: 'and' | 'or';
  groupKey?: string;
  queries: Array<ChildQuery>;
};

// 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 for complex logic
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 }
      ]
    }
  ]
};

type DcuplListQueryOptions<T> = {
  // Query group properties
  groupType?: 'and' | 'or';
  groupKey?: string;
  queries: Array<DcuplQuery | DcuplQueryGroup>;

  // Pagination
  start?: number;
  count?: number;

  // Projection and sorting
  projection?: Projection<T>;
  sort?: SortingProjection<T>;
};

const options: DcuplListQueryOptions<Product> = {
  groupType: 'and',
  queries: [
    { operator: 'eq', attribute: 'status', value: 'active' },
    { operator: 'gte', attribute: 'price', value: 50 }
  ],
  start: 0,
  count: 10,
  sort: {
    attributes: ['price'],
    order: ['ASC']
  }
};

const results = list.catalog.query.execute(options);

type DcuplGlobalQueryOptions<T> = {
  modelKey: string;

  // Query group properties
  groupType?: 'and' | 'or';
  groupKey?: string;
  queries: Array<DcuplQuery | DcuplQueryGroup>;

  // Pagination
  start?: number;
  count?: number;

  // Projection and sorting
  projection?: Projection<T>;
  sort?: SortingProjection<T>;
};

const options: DcuplGlobalQueryOptions<Product> = {
  modelKey: 'Product',
  groupType: 'and',
  queries: [
    { operator: 'eq', attribute: 'status', value: 'active' }
  ],
  start: 0,
  count: 20,
  sort: {
    attributes: ['price'],
    order: ['ASC']
  }
};

const results = dcupl.query.execute(options);

type SortingProjection<T> = {
  attributes: Array<keyof T>;
  order: Array<'ASC' | 'DESC'>;
  script?: {
    key: string;
    options: any;
  };
};

// Sort by price ascending, then by name descending
const sort: SortingProjection<Product> = {
  attributes: ['price', 'name'],
  order: ['ASC', 'DESC']
};

type DcuplListOptions = {
  modelKey: string;
  listKey?: string;
  listItemKeys?: string[];
  query?: DcuplGlobalQueryOptions;
  autoUpdate?: boolean;
};

interface DcuplList<T = any> {
  key: string;
  modelKey: string;
  catalog: Catalog<T>;

  update(options?: { reprocessData?: boolean }): void;
  destroy(): void;
  on(callback: CallbackFunction): () => void;
}

type DcuplFacetOptions = {
  attribute: string;
  count?: number;
  excludeZeros?: boolean;
  excludeUndefineds?: boolean;
  excludeUnresolved?: boolean;
  calculateResults?: boolean;
};

const facetOptions: DcuplFacetOptions = {
  attribute: 'category',
  count: 10,
  excludeZeros: true,
  calculateResults: true
};

const facets = list.catalog.fn.facet(facetOptions);

type DcuplFacet = {
  key: string;
  enabled: boolean;
  selected: boolean;
  size: number;
  value: boolean | string | null | undefined;
  entry: ListItem;
  resultKeys: string[];
  children?: Array<DcuplFacet>;
};

type AggregationOptions = {
  attribute: string;
  types: AggregationType[];
  distinctOptions?: {
    limit?: number;
    skipKeys?: boolean;
  };
  groupOptions?: {
    limit?: number;
    calculateNotFound?: boolean;
    groups?: AggregationGroupOption[];
  };
  excludeZeros?: boolean;
  excludeUndefineds?: boolean;
  excludeUnresolved?: boolean;
};

type AggregationType = 'sum' | 'avg' | 'count' | 'min' | 'max' | 'distinct' | 'group';

type AggregationGroupOption = {
  from?: any;
  to?: any;
  value?: any[];
};

// Basic aggregation
const basicOptions: AggregationOptions = {
  attribute: 'price',
  types: ['sum', 'avg', 'min', 'max', 'count']
};

// With distinct values
const distinctOptions: AggregationOptions = {
  attribute: 'category',
  types: ['distinct'],
  distinctOptions: {
    limit: 20,
    skipKeys: false
  }
};

// With custom grouping (price ranges)
const groupOptions: AggregationOptions = {
  attribute: 'price',
  types: ['group'],
  groupOptions: {
    groups: [
      { from: 0, to: 50 },
      { from: 50, to: 100 },
      { from: 100, to: 500 }
    ]
  }
};

const result = list.catalog.fn.aggregate(basicOptions);

type Aggregation = {
  attribute: string;
  types: AggregationType[];
  sum?: number;
  avg?: number;
  count?: number;
  min?: number;
  max?: number;
  distinct?: AggregationDistinctValue[];
  group?: AggregationGroupValue[];
};

type AggregationDistinctValue = {
  value: string;
  count: number;
  keys?: string[];
};

type AggregationGroupValue = {
  option: AggregationGroupOption;
  count: number;
  keys: string[];
};

type SuggestionOptions =
  | SuggestionOptionsFiltered
  | SuggestionOptionsAll
  | SuggestionOptionsExcludeQuery;

type SuggestionOptionsBase = {
  attribute: string;
  value: any;
  max?: number;
  calculateResultKeys?: boolean;
  excludeUndefineds?: boolean;
  excludeNulls?: boolean;
  transform?: DcuplQueryTransformOptions[];
};

// Use filtered data (respects current query state)
type SuggestionOptionsFiltered = SuggestionOptionsBase & {
  relevantData?: 'filtered';
};

// Use all data (ignores current query state)
type SuggestionOptionsAll = SuggestionOptionsBase & {
  relevantData?: 'all';
};

// Use data excluding specific query
type SuggestionOptionsExcludeQuery = SuggestionOptionsBase & {
  relevantData: 'excludeQuery';
  excludeQuery: Partial<DcuplQuery | DcuplQueryGroup>;
};

// Basic suggestions
const options: SuggestionOptions = {
  attribute: 'name',
  value: 'app',
  max: 10,
  transform: ['lowercase']
};

// Suggestions from all data (ignoring filters)
const allOptions: SuggestionOptions = {
  attribute: 'name',
  value: 'app',
  relevantData: 'all',
  max: 10
};

// Suggestions excluding a specific query
const excludeOptions: SuggestionOptions = {
  attribute: 'category',
  value: 'elec',
  relevantData: 'excludeQuery',
  excludeQuery: {
    operator: 'eq',
    attribute: 'category',
    queryKey: 'category-filter'
  }
};

const suggestions = list.catalog.fn.suggest(options);

type Suggestion = {
  value: string;
  keys: string[];
};

type DcuplGroupByOptions<T> = {
  attribute: string;
  aggregates?: AggregationOptions[];
  items?: DcuplSectionItemOption<T>[];
  excludeZeros?: boolean;
  excludeUndefineds?: boolean;
  excludeUnresolved?: boolean;

  // Pagination options inherited
  start?: number;
  count?: number;
  projection?: Projection<T>;
  sort?: SortingProjection<T>;
};

type DcuplSectionItemOption<T> = {
  key: string;
  start?: number;
  count?: number;
  projection?: Projection<T>;
  sort?: SortingProjection<T>;
};

const groupByOptions: DcuplGroupByOptions<Product> = {
  attribute: 'category',
  aggregates: [
    { attribute: 'price', types: ['avg', 'min', 'max'] }
  ],
  excludeZeros: true,
  count: 10,
  sort: {
    attributes: ['name'],
    order: ['ASC']
  }
};

const grouped = list.catalog.fn.groupBy(groupByOptions);

type PivotOptions = {
  rows: PivotRowOption[];
  columns: PivotColumnOption[];
  values: PivotValueOption[];
  options?: {
    calculateTotals?: boolean;
  };
};

type PivotRowOption = {
  attribute: string;
  calculateTotals?: boolean;
};

type PivotColumnOption = {
  attribute: string;
  calculateTotals?: boolean;
};

type PivotValueOption = AggregationOptions;

const pivotOptions: PivotOptions = {
  rows: [
    { attribute: 'category', calculateTotals: true },
    { attribute: 'brand' }
  ],
  columns: [
    { attribute: 'year' }
  ],
  values: [
    { attribute: 'revenue', types: ['sum'] },
    { attribute: 'quantity', types: ['count', 'avg'] }
  ],
  options: {
    calculateTotals: true
  }
};

const pivotResult = dcupl.fn.pivot({
  modelKey: 'Sales',
  options: pivotOptions
});

type PivotResponse = {
  key: string;
  value?: any;
  values?: Aggregation[];
  columns?: PivotResponseItem[];
  rows?: PivotResponseItem[];
};

type PivotResponseItem = {
  key: string;
  value?: any;
  values?: Aggregation[];
  columns?: PivotResponseItem[];
  rows?: PivotResponseItem[];
};

type CallbackFunction = (message: DcuplMessage) => void;

type DcuplMessage = {
  type: DcuplMessageType;
  scope: string;
  args?: any[];
};

type DcuplMessageType =
  | 'dcupl_init_completed'
  | 'dcupl_updated_manually'
  | 'dcupl_partial_update'
  | 'list_updated'
  | 'query_apply'
  | 'query_reset';

type ViewDefinition = {
  key: string;
  modelKey: string;
  query?: DcuplGlobalQueryOptions;
};

type PropertyQualityConfig = {
  required?: boolean;
  validators?: {
    min?: { value: number };
    max?: { value: number };
    minLength?: { value: number };
    maxLength?: { value: number };
    pattern?: { value: string };
  };
};

type ModelQualityConfig = {
  enabled?: boolean;
};

interface Dcupl {
  // Properties
  models: ModelsAPI;
  lists: ListsAPI;
  data: DataAPI;
  query: QueryAPI;
  fn: FunctionsAPI;
  views: ViewsAPI;
  scripts: ScriptsAPI;
  loaders: LoadersAPI;
  initOptions: DcuplInitOptions;
  version: string;

  // Methods
  init(): Promise<boolean>;
  update(options?: DcuplUpdateOptions): Promise<boolean>;
  destroy(): void;
  on(callback: CallbackFunction): () => void;
}