Type definitions

import { Dcupl } from '@dcupl/core';
import type { DcuplQuery, DcuplQueryGroup, ModelDefinition } from '@dcupl/common';

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

// DcuplInitErrorTrackingConfig, DcuplInitErrorAnalyticsConfig and
// DcuplInitReferenceMetadataConfig are all { enabled: boolean }

type DcuplInitScriptingConfig = { enabled?: boolean; compile?: ScriptCompiler };

type ScriptCompiler = (source: string, params: string[]) => (...args: any[]) => any;

// version: 'draft' (default), 'production' or a version name such as 'v1.0.0'
type DcuplInitConfig = { projectId?: string; apiKey?: string; version?: string };

type DcuplInitPerformanceConfig = {
  cache?: {
    enabled: boolean;
    maxSize?: number; // estimated bytes, default 64 MiB; Infinity = no limit
    maxProjectionSize?: number; // estimated bytes per list, default 256 MiB; Infinity = no limit
  };
  clone?: { enabled: boolean };
  partialUpdates?: DcuplPartialUpdateConfig;
  containerBatchSize?: number;
  autoUpdateLists?: { enabled: boolean };
  retainStagedData?: boolean; // default true; false seals the instance after init()
};

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

type DcuplInitQualityConfig = { enabled: boolean; maxErrorsPerGroup?: number };

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

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

type DcuplUpdateOptions = { autoUpdateLists?: boolean };

type ModelDefinition<ModelNames extends string = string> = {
  key: ModelNames;
  keyProperty?: string | readonly string[];
  keyPropertySeparator?: string;
  properties?: Property[];
  references?: Reference[];
  quality?: ModelQualityConfig;
  data?: RawItem[];
  autoGenerateKey?: boolean;
  autoGenerateProperties?: boolean | { deep?: boolean; sampleSize?: number };
  supportsAutoCreation?: boolean;
  valueMappings?: ValueMappingConfig[];
  meta?: ModelMetadata; // { name: string; description?: string; [key: string]: any }
};

type ValueMappingConfig = {
  attributes: string[]; // properties and references the mapping applies to
  values: { from: (string | '$dcupl_falsy')[]; to: any }[];
};

type Property = {
  key: string;
  type: PropertyType;
  quality?: AttributeQualityConfig;
  expression?: string;
  derive?: { localReference: string; remoteProperty: string; separator?: string };
  filter?: boolean | FilterStringSingle | FilterStringArray[]; // object forms: string and Array<string> only
  aggregate?: boolean | Omit<AggregationOptions, 'attribute'>;
  index?: boolean;
  origin?: string; // source field to read the value from, e.g. a CSV column header
  meta?: ModelMetadata;
  separator?: string; // Array<…> types: splits a string value
  fractionDigits?: number; // float, Array<float>
  inputFormat?: string; // date, Array<date>
  UTC?: boolean; // date, Array<date>
};

type FilterStringSingle = { comparisonType?: FilterComparisonType };
type FilterStringArray = { key: string; comparisonType: FilterComparisonType };
type FilterComparisonType =
  | 'equal'
  | 'equalIgnoreCase'
  | 'contains'
  | 'containsIgnoreCase'
  | 'containsIgnoreCaseAndWhitespace';

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

type Reference = {
  key: string;
  model: string;
  type: ReferenceType;
  separator?: string;
  filter?: boolean | ReferenceFilterDefinition;
  aggregate?: boolean | Omit<AggregationOptions, 'attribute'>;
  index?: boolean;
  validity?: ReferenceValidity;
  quality?: AttributeQualityConfig;
  origin?: string; // source field to read the key(s) from
  meta?: ModelMetadata;
  // computed references (one of):
  resolve?: { reference: string; model: string };
  derive?: { localReference: string; remoteReference: string };
  groupBy?: { reference: string; includeSelfInGroup?: boolean };
  query?: DcuplGlobalQueryOptions<any> | DcuplQuery | DcuplQueryGroup | DcuplQuery[] | DcuplQueryGroup[];
};

type ReferenceType = 'singleValued' | 'multiValued';
type ReferenceValidity = 'loose' | 'strict';
type ReferenceFilterDefinition = { calculateFacets?: boolean; excludeZeros?: boolean; excludeUndefineds?: boolean };

type RawItem = any;

type ListItem = { key: string; [id: string]: any };

type DataOptions<ModelNames extends string = string> = {
  model: ModelNames;
  keyProperty?: string | readonly string[];
  keyPropertySeparator?: string;
  autoGenerateKey?: boolean;
};

type DataContainer = {
  model: string;
  type?: DataContainerType;
  data: RawItem[];
  keyProperty?: string | readonly string[];
  keyPropertySeparator?: string;
  autoGenerateKey?: boolean;
  autoGenerateProperties?: boolean | { deep?: boolean; sampleSize?: number };
  placeholderUid?: string;
};

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

type DcuplQuery =
  | DcuplQueryEq // operator: 'eq'; value: any
  | DcuplQueryIn // operator: 'in'; value: unknown[]
  | DcuplQueryNumbers // operator: 'gt' | 'lt' | 'gte' | 'lte'; value: string | number | Date
  | DcuplQueryTypeOf // operator: 'typeof'; value: string
  | DcuplQueryIsTruthy // operator: 'isTruthy'; value: boolean
  | DcuplQuerySize // operator: 'size'; value: number
  | DcuplQueryFind; // operator: 'find'; value: string | Record<string, unknown>

// Shared by every variant; not exported
type DcuplQueryBase = {
  attribute: string; // dot notation for nested values, e.g. 'user.email'
  queryKey?: any;
  options?: DcuplQueryOptions;
};

type DcuplQueryOperator = 'eq' | 'in' | 'find' | 'gt' | 'gte' | 'lt' | 'lte' | 'typeof' | 'isTruthy' | 'size';

type DcuplQueryOptions = {
  transform?: DcuplQueryTransformOptions[];
  invert?: boolean;
  arrayValueHandling?: 'some' | 'every';
  regexFlags?: string; // find only
};

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

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

type DcuplListQueryOptions<T> = DcuplItemsOptions<T> & Partial<DcuplQueryGroup>;

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

type DcuplGlobalQueryOptions<T> = { modelKey: string } & DcuplItemsOptions<T> & DcuplQueryGroup;

type DcuplGlobalItemOptions<T> = { modelKey: string; itemKey: string; projection?: Projection<T> };
type DcuplGlobalManyItemOptions<T> = { modelKey: string; itemKeys: string[]; projection?: Projection<T> };

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

type Projection<T> = WildCard | ProjectionAdvanced<T>;

type WildCard = { $?: boolean; $$?: boolean }; // not exported

type ProjectionAdvanced<T> = {
  [P in keyof T]?: boolean | WildCard | ProjectionAdvanced<T[P]>;
};

type DcuplListOptions<ModelNames extends string = string> = {
  modelKey: ModelNames;
  listKey?: string;
  listItemKeys?: string[];
  query?: DcuplGlobalQueryOptions<ListItem>;
  autoUpdate?: boolean;
};

class DcuplList<ListType = any> {
  key: string;
  modelKey: string;
  catalog: Catalog<ListType & ListItem>;

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

type ListMetadata = {
  key: string;
  currentSize: number;
  initialSize: number;
  appliedQuery: DcuplGlobalQueryOptions<any>;
  attributes: ModelAttribute[]; // ModelAttribute = Property | Reference
  views: ViewDefinition[];
};

type DcuplGlobalFacetOptions = { modelKey: string; options: DcuplFacetOptions; query?: DcuplGlobalQueryOptions<any> };
// Same shape: DcuplGlobalAggregateOptions (AggregationOptions), DcuplGlobalSuggestionOptions (SuggestionOptions),
// DcuplGlobalGroupByOptions (DcuplGroupByOptions<any>), DcuplGlobalPivotOptions (PivotOptions)
type DcuplGlobalMetadataOptions = { modelKey: string; query?: DcuplGlobalQueryOptions<any> };

type DcuplFacetOptions = {
  attribute: string;
  count?: number;
  excludeZeros?: boolean;
  excludeUndefineds?: boolean;
  excludeUnresolved?: boolean;
  calculateResults?: boolean;
  sort?: 'size-desc' | 'size-asc' | 'value-asc' | 'value-desc';
  excludeGroup?: string;
};

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

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

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

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

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[] };

// Only SuggestionOptions is exported; narrow it with
// Extract<SuggestionOptions, { relevantData: 'excludeQuery' }> if you need one variant
type SuggestionOptions = SuggestionOptionsFiltered | SuggestionOptionsAll | SuggestionOptionsExcludeQuery;

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

type SuggestionOptionsFiltered = SuggestionOptionsBase & { relevantData?: 'filtered'; excludeQuery?: never };
type SuggestionOptionsAll = SuggestionOptionsBase & { relevantData?: 'all'; excludeQuery?: never };
type SuggestionOptionsExcludeQuery = SuggestionOptionsBase & {
  relevantData: 'excludeQuery';
  excludeQuery: Partial<DcuplQuery | DcuplQueryGroup>;
};

type Suggestion = {
  value: string; // typed string; at runtime numbers and booleans keep their type, a date (or Array<date>) value comes back as its ISO string
  keys: string[];
};

type DcuplGroupByOptions<T> = DcuplItemsOptions<T> & {
  attribute: string;
  aggregates?: AggregationOptions[];
  items?: DcuplSectionItemOption<T>[];
};

type DcuplSectionItemOption<T> = DcuplItemsOptions<T> & {
  key: string; // a group key, or '*' for every group
};

type GroupByResponse = {
  _meta: { currentSize: number; initialSize: number };
  items: SectionItem[];
};

type SectionItem = ListItem & {
  _meta: { size: number }; // items in this group
  _aggregates: Aggregation[]; // one per entry of options.aggregates
  _items: ListItem[]; // filled only for groups named in options.items
};

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;

type PivotResponse = PivotResponseItem;

// Not exported; same shape as PivotResponse
type PivotResponseItem = {
  key: string;
  value?: any;
  values?: Aggregation[];
  columns?: Omit<PivotResponseItem, 'rows'>[];
  rows?: PivotResponseItem[];
};

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

type DcuplUpdateMessage = {
  type: DcuplUpdateType;
  scope: 'all' | 'global' | 'list' | 'list$';
  action?: 'update';
  origin?: 'user' | 'loader';
  listKey?: string;
  modelKey?: string;
  method?: string; // the operation that triggered the event, as the SDK names it
  args?: any;
  result?: any;
  start?: number;
  end?: number;
  duration?: number;
  key?: number;
};

type DcuplUpdateType =
  | 'data_change'
  | 'dcupl_destroyed'
  | 'dcupl_handle_datacontainer'
  | 'dcupl_initialized'
  | 'dcupl_updated_manually'
  | 'dcupl_partial_update'
  | 'filter_many'
  | 'filter_one'
  | 'fn_aggregate'
  | 'fn_facets'
  | 'fn_groupBy'
  | 'fn_metadata'
  | 'fn_pivot'
  | 'fn_suggest'
  | 'list_created'
  | 'list_destroyed'
  | 'list_updated'
  | 'loader_added'
  | 'loader_config_fetched'
  | 'loader_data_fetched'
  | 'loader_models_fetched'
  | 'loader_scripts_fetched'
  | 'loader_processed'
  | 'loader_removed'
  | 'model_add'
  | 'query_apply_options'
  | 'query_apply'
  | 'query_execute'
  | 'query_get'
  | 'query_has'
  | 'query_many'
  | 'query_one'
  | 'query_remove'
  | 'query_reset'
  | 'result_updated'
  | 'view_add';

type ViewDefinition = ViewDefinitionSection | ViewDefinitionPivot;

type ViewDefinitionSection = {
  key: string;
  model: string;
  type: 'section';
  primaryAttribute: string;
  aggregates: AggregationOptions[];
  meta?: ModelMetadata;
};

type ViewDefinitionPivot = {
  key: string;
  model: string;
  type: 'pivot';
  options: PivotOptions;
  meta?: ModelMetadata;
};

type AttributeQualityConfig = {
  required?: boolean; // default true
  nullable?: boolean; // default false
  forceStrictDataType?: boolean; // default false
  validators?: {
    email?: { value?: any };
    endsWith?: { value?: any };
    enum?: { value?: any };
    includes?: { value?: any };
    max?: { value?: any };
    maxLength?: { value?: any };
    min?: { value?: any };
    minLength?: { value?: any };
    pattern?: { value?: any };
    unique?: { value?: any };
    startsWith?: { value?: any };
  };
  validatorHandling?: 'loose' | 'strict'; // default 'loose'
};

type ModelQualityConfig = {
  enabled?: boolean; // default true
  attributes?: Omit<AttributeQualityConfig, 'validators'>;
};

type ErrorGroupSummary = {
  key: string; // `model::attribute::errorType`
  model?: string;
  attribute?: string;
  errorGroup: string;
  errorType: string; // QualityAnalyzer.ModelErrorType | QualityAnalyzer.LoaderErrorType
  type: 'model' | 'loader';
  totalCount: number; // also counts beyond maxErrorsPerGroup
  storedCount: number; // records kept (<= maxErrorsPerGroup)
  truncated: boolean; // totalCount > storedCount
};

type ModelErrorType =
  | 'UndefinedAttribute'
  | 'InvalidValidator'
  | 'UndefinedValue'
  | 'NullValue'
  | 'WrongDataType'
  | 'NonUniqueKey'
  | 'MissingKey'
  | 'DuplicatePropertyKey'
  | 'MissingModel'
  | 'MissingProperty'
  | 'MissingReference'
  | 'UnknownExpressionVariable'
  | 'RemoteReferenceKeyNotFound'
  | 'InvalidModelDefinition'
  | 'UnknownColumn';

type LoaderErrorType =
  | 'InvalidConfig'
  | 'InvalidResource'
  | 'ScriptingDisabled'
  | 'TransformerError'
  | 'EndpointScriptMissing'
  | 'EndpointDuplicate';

type ScriptType = 'script' | 'async_script' | 'sort' | 'operator' | 'validator' | 'endpoint';

type EndpointScriptMethod = 'GET' | 'POST';

type EndpointScriptRequest = {
  method: EndpointScriptMethod;
  path: string;
  params: Record<string, string>;
  query: Record<string, string | string[]>;
  body: unknown;
  headers: Record<string, string>;
};

type EndpointScriptContext = { dcupl: ReadOnlyDcupl; request: EndpointScriptRequest; options: Record<string, unknown> };

type ReadOnlyDcupl = {
  query: {
    one: <T extends ListItem = ListItem>(options: DcuplGlobalItemOptions<T>) => T | null;
    many: <T extends ListItem = ListItem>(options: DcuplGlobalManyItemOptions<T>) => T[];
    execute: <T extends ListItem = ListItem>(options: DcuplGlobalQueryOptions<T>) => T[];
    generate: (
      modelKey: string,
      query: DcuplQueryGroup | DcuplQuery | DcuplQuery[] | DcuplQueryGroup[],
    ) => DcuplGlobalQueryOptions<any>;
  };
  fn: {
    pivot: (options: DcuplGlobalPivotOptions) => PivotResponse;
    aggregate: (options: DcuplGlobalAggregateOptions) => Aggregation;
    suggest: (options: DcuplGlobalSuggestionOptions) => Suggestion[];
    groupBy: (options: DcuplGlobalGroupByOptions) => GroupByResponse;
    facets: (options: DcuplGlobalFacetOptions) => FilterItemEntry[];
    metadata: (options: DcuplGlobalMetadataOptions) => ListMetadata;
  };
  models: { get: (modelKey: string) => ModelDefinition | undefined; keys: () => string[] };
  views: { get: (viewKey: string) => ViewDefinition | undefined; keys: (options?: { modelKey: string }) => string[] };
  scripts: { keys: () => string[] };
};

class ScriptNotFoundError extends Error {
  readonly name = 'ScriptNotFound';
  readonly key: string;
  // message: `Script ${key} not found`
}

type TemplateEndpoint = { path: string; method: 'GET' | 'POST'; scriptKey: string; description?: string };

// on RestApi.Template
endpoints?: TemplateEndpoint[];

class Dcupl {
  constructor(options?: DcuplInitOptions);

  models: {
    get(modelKey: string): ModelDefinition | undefined;
    set(model: ModelDefinition): void;
    update(model: ModelDefinition): void;
    remove(modelKey: string): void;
    keys(): string[];
  };
  data: {
    // Staged; applied by the next dcupl.update() (or init())
    set(data: RawItem[], options: DataOptions): void;
    update(data: RawItem[], options: DataOptions): void;
    upsert(data: RawItem[], options: DataOptions): void;
    remove(data: RawItem[], options: DataOptions): void;
    reset(options: { model: string }): void;
    apply(container: DataContainer): void;
  };
  lists: {
    create<T extends RawItem = RawItem>(options: {
      modelKey: string;
      listKey?: string;
      listItemKeys?: string[];
      query?: DcuplGlobalQueryOptions<ListItem>;
    }): DcuplList<T>;
    get(listKey: string): DcuplList | undefined;
    getAll(options?: { modelKey: string }): DcuplList[];
    destroy(options?: { listKey?: string; modelKey?: string }): void;
  };
  query: {
    one<T extends ListItem = ListItem>(options: DcuplGlobalItemOptions<T>): T | null;
    many<T extends ListItem = ListItem>(options: DcuplGlobalManyItemOptions<T>): T[];
    execute<T extends ListItem = ListItem>(options: DcuplGlobalQueryOptions<T>): T[];
    generate(
      modelKey: string,
      query: DcuplQueryGroup | DcuplQuery | DcuplQuery[] | DcuplQueryGroup[],
    ): DcuplGlobalQueryOptions<any>;
    registerCustomOperator(operator: string, fn: CustomOperatorFn): void; // deprecated: use a custom script
  };
  fn: {
    pivot(options: DcuplGlobalPivotOptions): PivotResponse;
    aggregate(options: DcuplGlobalAggregateOptions): Aggregation;
    suggest(options: DcuplGlobalSuggestionOptions): Suggestion[];
    groupBy(options: DcuplGlobalGroupByOptions): GroupByResponse;
    facets(options: DcuplGlobalFacetOptions): FilterItemEntry[];
    metadata(options: DcuplGlobalMetadataOptions): ListMetadata;
  };
  views: {
    get(viewKey: string): ViewDefinition | undefined;
    keys(options?: { modelKey: string }): string[];
    set(view: ViewDefinition): void;
    remove(viewKey: string): void;
  };
  scripts: {
    set(key: string, script: string): void;
    remove(key: string): void;
    get(key: string): string | undefined;
    keys(): string[];
    execute(key: string, options?: any): any;
    executeAsync(key: string, options?: any): any;
    executeEndpoint(key: string, request: EndpointScriptRequest, options?: Record<string, unknown>): Promise<unknown>;
  };
  loaders: {
    add(loader: any, key?: string): void; // a DcuplAppLoader from @dcupl/loader
    remove(key: string): void;
    get(key: string): any;
  };
  quality: { errors: { summary(): QualityAnalyzer.ErrorGroupSummary[] } };
  initOptions: DcuplInitOptions;
  version: string; // the installed @dcupl/core version
  readonly sealed: boolean;

  init(): Promise<boolean>;
  update(options?: { autoUpdateLists?: boolean }): Promise<boolean>;
  seal(): void;
  destroy(): void;
  on(callback: CallbackFunction): () => void;
}