@sincpro/mobile 0.1.0

package/dist/domain/entity/entity_collection.d.ts

@@ -0,0 +1,396 @@
+import { DomainEvent, type DomainEventClass } from "../../domain/event_sourcing/domain_event";
+import { type Entity, type RemoteEntity } from "./entity";
+import { ValueObject } from "./value_object";
+export type CriteriaOperator = "=" | "!=" | "in" | "not_in" | "like" | ">" | "<" | ">=" | "<=";
+export interface ICriteria<T = any> {
+    field: keyof T;
+    operator: CriteriaOperator;
+    value: any;
+}
+/**
+ * Type-safe, immutable collection for Entity aggregates with event sourcing support.
+ * Implements IEventSourced for domain event publishing and provides functional operations.
+ *
+ * @example
+ * const collection = new EntityCollection([priceList1, priceList2]);
+ *
+ * // Functional operations (immutable)
+ * const active = collection.filter(pl => pl.isActive).sortBy(pl => pl.name);
+ *
+ * // Aggregations
+ * const total = collection.sumBy(pl => pl.price);
+ * const cheapest = collection.minBy(pl => pl.price);
+ *
+ * // Set operations
+ * const union = collection1.union(collection2);
+ * const common = collection1.intersect(collection2);
+ *
+ * // Event sourcing
+ * await collection.publishEventWith(PRICE_LISTS_SYNCED, pl => ({ id: pl.remoteId, name: pl.name }));
+ */
+export declare class EntityCollection<T extends Entity> extends ValueObject {
+    uuid: string;
+    eventIds: string[];
+    private entities;
+    private _domainEventsV2;
+    private _correlationIdV2;
+    constructor(entities?: T[]);
+    /** Factory method for creating instances - override in subclasses */
+    protected createInstance(entities: T[]): this;
+    /** Creates collection from array of entities - polymorphic, works with subclasses */
+    static from<T extends Entity>(this: new (entities: T[]) => EntityCollection<T>, entities: T[]): EntityCollection<T>;
+    /**
+     * Converts entity, array, or collection to plain array.
+     * Useful for repository save methods that accept multiple input types.
+     * Supports: single entity, arrays, Set, EntityCollection
+     *
+     * @example
+     * const entities = EntityCollection.toArrayFrom(entity);
+     * // Works with: single entity, array, Set, or EntityCollection
+     */
+    static toArrayFrom<T extends Entity>(entity: T | T[] | EntityCollection<T>): T[];
+    /** Returns total number of entities in collection */
+    get length(): number;
+    /** Checks if collection has no entities */
+    get isEmpty(): boolean;
+    /** Checks if collection has at least one entity */
+    get isNotEmpty(): boolean;
+    /**
+     * Enables native JavaScript/TypeScript boolean evaluation.
+     * Collection behaves like primitives in conditional contexts.
+     *
+     * Compatible with language keywords:
+     * - if (collection) { } // true if has entities
+     * - !collection // true if empty
+     * - collection && doSomething() // executes if not empty
+     * - collection || defaultValue // uses collection if not empty
+     * - collection ? a : b // ternary operator
+     * - while (collection) { } // loops while not empty
+     * - Boolean(collection) // explicit boolean conversion
+     * - +collection // converts to number (length)
+     * - String(collection) // converts to "EntityCollection(n)"
+     *
+     * @example
+     * if (priceLists) { console.log("Has items"); }
+     * const items = priceLists || new EntityCollection();
+     * !emptyCollection // true
+     */
+    [Symbol.toPrimitive](hint: string): boolean | number | string;
+    /**
+     * Returns numeric value for collection (length).
+     * Enables: +collection, Number(collection)
+     */
+    valueOf(): number;
+    /** Converts collection to plain array (creates new copy) */
+    toArray(): T[];
+    /** Gets entity at specific index (0-based) */
+    at(index: number): T | undefined;
+    /** Gets entity at specific index (0-based) */
+    get(index: number): T | undefined;
+    /** Checks if collection contains entity (uses Entity.equals) */
+    includes(entity: T): boolean;
+    /** Finds index of entity in collection (uses Entity.equals) */
+    indexOf(entity: T): number;
+    /** Concatenates multiple collections into new collection */
+    concat(...collections: EntityCollection<T>[]): this;
+    /** Returns subset of collection from start to end index */
+    slice(start?: number, end?: number): this;
+    /** Returns first entity in collection */
+    first(): T | undefined;
+    /** Returns last entity in collection */
+    last(): T | undefined;
+    /** Adds entity to collection (mutates) */
+    add(entity: T): this;
+    /** Adds multiple entities to collection (mutates) */
+    addAll(entities: T[]): this;
+    /** Removes entity from collection (mutates, uses Entity.equals) */
+    remove(entity: T): this;
+    /** Removes all entities from collection (mutates) */
+    clear(): this;
+    /** Makes collection iterable (use with for...of loops) */
+    [Symbol.iterator](): Iterator<T>;
+    /**
+     * Splits collection into chunks of specified size
+     * @example
+     * const pages = collection.chunk(10); // [[...10], [...10], ...]
+     * pages.forEach((page, i) => console.log(`Page ${i}: ${page.length} items`));
+     */
+    chunk(size: number): this[];
+    /** Counts entities matching predicate (returns length if no predicate) */
+    count(predicate?: (entity: T) => boolean): number;
+    /** Finds entity with minimum value from selector */
+    minBy(selector: (entity: T) => number): T | undefined;
+    /** Finds entity with maximum value from selector */
+    maxBy(selector: (entity: T) => number): T | undefined;
+    /** Sums numeric values from selector across all entities */
+    sumBy(selector: (entity: T) => number): number;
+    /** Calculates average of numeric values from selector */
+    averageBy(selector: (entity: T) => number): number;
+    /** Finds last entity matching predicate (searches from end) */
+    findLast(predicate: (entity: T) => boolean): T | undefined;
+    /**
+     * Converts collection to Map using key selector (for fast lookups)
+     * @example
+     * const priceListMap = collection.toMap(pl => pl.remoteId!);
+     * const priceList = priceListMap.get(123); // O(1) lookup
+     */
+    toMap<K>(keySelector: (entity: T) => K): Map<K, T>;
+    /**
+     * Converts collection to plain object using key and value selectors
+     * @example
+     * const names = collection.toRecord(pl => pl.remoteId!, pl => pl.name);
+     * // { 1: "Premium", 2: "Basic" }
+     */
+    toRecord<K extends string | number, V>(keySelector: (entity: T) => K, valueSelector: (entity: T) => V): Record<K, V>;
+    /** Checks if collection contains any of provided entities */
+    containsAny(entities: T[]): boolean;
+    /** Checks if collection contains all provided entities */
+    containsAll(entities: T[]): boolean;
+    /** Returns new collection with entities matching predicate */
+    filter(predicate: (entity: T, index: number) => boolean): this;
+    /** Transforms entities to new type, returns new collection */
+    map<R extends Entity>(mapper: (entity: T, index: number) => R): EntityCollection<R>;
+    /** Transforms entities to any type, returns plain array */
+    mapToArray<R>(mapper: (entity: T, index: number) => R): R[];
+    /** Maps and flattens results into new collection */
+    flatMap<R extends Entity>(mapper: (entity: T, index: number) => R[]): EntityCollection<R>;
+    /** Maps and flattens results into plain array */
+    flatMapToArray<R>(mapper: (entity: T, index: number) => R[]): R[];
+    /** Finds first entity matching predicate */
+    find(predicate: (entity: T) => boolean): T | undefined;
+    /** Finds index of first entity matching predicate */
+    findIndex(predicate: (entity: T) => boolean): number;
+    /** Checks if at least one entity matches predicate */
+    some(predicate: (entity: T) => boolean): boolean;
+    /** Checks if all entities match predicate */
+    every(predicate: (entity: T) => boolean): boolean;
+    /** Executes callback for each entity */
+    forEach(callback: (entity: T, index: number) => void): void;
+    /** Reduces collection to single value using reducer function */
+    reduce<R>(reducer: (acc: R, entity: T, index: number) => R, initialValue: R): R;
+    /** Sorts collection using compare function, returns new collection */
+    sort(compareFn: (a: T, b: T) => number): this;
+    /** Sorts collection by key selector, returns new collection */
+    sortBy(keySelector: (entity: T) => any): this;
+    /**
+     * Groups entities by key into Map of collections
+     * @example
+     * const byTyp = collection.groupBy(pl => pl.currencyId);
+     * // Map<number, EntityCollection<PriceList>>
+     * byType.get(1)?.forEach(pl => console.log(pl.name));
+     */
+    groupBy<K>(keySelector: (entity: T) => K): Map<K, this>;
+    /**
+     * Splits collection into [matching, non-matching] tuple
+     * @example
+     * const [active, inactive] = collection.partition(pl => pl.isActive);
+     */
+    partition(predicate: (entity: T) => boolean): [this, this];
+    /** Returns collection with unique entities (uses UUID by default or custom key selector) */
+    distinct(keySelector?: (entity: T) => any): this;
+    /** Returns first N entities from collection */
+    take(count: number): this;
+    /** Skips first N entities, returns rest */
+    skip(count: number): this;
+    /** Returns union of collections (no duplicates by uuid) */
+    union(other: this): this;
+    /** Returns entities present in both collections */
+    intersect(other: this): this;
+    /** Returns entities in this collection but not in other */
+    except(other: this): this;
+    /**
+     * Returns entities in this collection but not in other using custom selector
+     * @example
+     * const different = collection1.exceptBy(collection2, e => e.name);
+     */
+    exceptBy<K>(other: this, keySelector: (entity: T) => K): this;
+    /**
+     * Finds entity by UUID
+     * @example
+     * const entity = collection.findByUuid("abc-123-def");
+     */
+    findByUuid(uuid: string): T | undefined;
+    /**
+     * Finds entities by multiple UUIDs
+     * @example
+     * const entities = collection.findByUuids(["uuid1", "uuid2", "uuid3"]);
+     */
+    findByUuids(uuids: string[]): this;
+    /**
+     * Checks if collection contains entity with given UUID
+     * @example
+     * if (collection.hasUuid("abc-123")) { ... }
+     */
+    hasUuid(uuid: string): boolean;
+    /**
+     * Extracts all UUIDs as plain array
+     * @example
+     * const uuids = collection.getUuids();
+     * await deleteByUuids(uuids);
+     */
+    getUuids(): string[];
+    /**
+     * Creates a Map indexed by UUID for O(1) lookups
+     * @example
+     * const byUuid = collection.toMapByUuid();
+     * const entity = byUuid.get("abc-123"); // Fast lookup
+     */
+    toMapByUuid(): Map<string, T>;
+    addDomainEvent<E extends DomainEvent>(EventClass: DomainEventClass<E>, payload: Partial<E>): string;
+    addDomainEventWithEntities<E extends DomainEvent>(EventClass: DomainEventClass<E>): string;
+    getDomainEvents(): readonly DomainEvent[];
+    clearDomainEvents(): void;
+    publishAllDomainEvents(): Promise<void>;
+    publishAllDomainEventsSync(): Promise<void>;
+    publishDomainEvent<E extends DomainEvent>(EventClass: DomainEventClass<E>, payload: Partial<E>): Promise<void>;
+    publishDomainEventSync<E extends DomainEvent>(EventClass: DomainEventClass<E>, payload: Partial<E>): Promise<void>;
+    publishDomainEventWithEntities<E extends DomainEvent>(EventClass: DomainEventClass<E>): Promise<void>;
+    publishDomainEventWithEntitiesSync<E extends DomainEvent>(EventClass: DomainEventClass<E>): Promise<void>;
+    /**
+     * Serializes collection as array of entity JSONs.
+     * Collection is a manager, not an entity, so it serializes as pure entity list.
+     * @example
+     * const json = collection.asJSON();
+     * await saveToDatabase(json);
+     */
+    asJSON(pretty?: boolean): string;
+    /**
+     * Filters entities using criteria array. All criteria must match (AND).
+     * @example
+     * const filtered = collection.findByCriteria([
+     *   { field: 'customerId', operator: '=', value: 123 },
+     *   { field: 'state', operator: 'in', value: ['draft', 'posted'] }
+     * ]);
+     */
+    findByCriteria(criteria: ICriteria<T>[]): this;
+    /**
+     * Deserializes collection from array of entity JSONs.
+     * Collection is a manager, not an entity, so it deserializes from pure entity list.
+     * @example
+     * const collection = EntityCollection.fromJSON<PriceList>(json, PriceList);
+     */
+    static fromJSON<T extends Entity>(json: string | any, EntityClass?: new () => T): any;
+}
+/**
+ * Collection for RemoteEntity aggregates with DTO mapping support.
+ * Extends EntityCollection with fromRemoteDTO for batch entity creation.
+ *
+ * @example
+ * const collection = RemoteEntityCollection.fromRemoteDTO(
+ *   remoteDTOs,
+ *   PriceList
+ * );
+ * await collection.publishIds(PRICE_LISTS_SYNCED);
+ */
+export declare class RemoteEntityCollection<T extends RemoteEntity> extends EntityCollection<T> {
+    /**
+     * Creates collection from remote DTOs using entity's fromRemoteDTO method
+     * @example
+     * const priceLists = RemoteEntityCollection.fromRemoteDTO(
+     *   apiResponse.records,
+     *   PriceList
+     * );
+     */
+    static fromRemoteDTO<T extends RemoteEntity>(dtos: any[], EntityClass: {
+        fromRemoteDTO: (dto: any) => T;
+    }): RemoteEntityCollection<T>;
+    /** Factory method override to create RemoteEntityCollection instances */
+    protected createInstance(entities: T[]): this;
+    /**
+     * Finds entity by remoteId
+     * Returns undefined if entity doesn't have remoteId or not found
+     * @example
+     * const customer = customers.findByRemoteId(123);
+     */
+    findByRemoteId(remoteId: number): T | undefined;
+    /**
+     * Finds entities by multiple remoteIds
+     * @example
+     * const products = collection.findByRemoteIds([1, 2, 3, 4, 5]);
+     */
+    findByRemoteIds(remoteIds: number[]): RemoteEntityCollection<T>;
+    /**
+     * Checks if collection contains entity with given remoteId
+     * @example
+     * if (customers.hasRemoteId(123)) { ... }
+     */
+    hasRemoteId(remoteId: number): boolean;
+    /**
+     * Returns entities that have remoteId set (synced with backend)
+     * @example
+     * const syncedEntities = collection.withRemoteId();
+     */
+    withRemoteId(): RemoteEntityCollection<T>;
+    /**
+     * Returns entities without remoteId (local-only, not synced)
+     * @example
+     * const localOnlyEntities = collection.withoutRemoteId();
+     */
+    withoutRemoteId(): RemoteEntityCollection<T>;
+    /**
+     * Extracts all remoteIds as plain array (filters out null/undefined)
+     * @example
+     * const remoteIds = collection.getRemoteIds();
+     * await syncWithBackend(remoteIds);
+     */
+    getRemoteIds(): number[];
+    /**
+     * Creates a Map indexed by remoteId for O(1) lookups
+     * Filters out entities without remoteId
+     * @example
+     * const byRemoteId = collection.toMapByRemoteId();
+     * const customer = byRemoteId.get(123); // Fast lookup
+     */
+    toMapByRemoteId(): Map<number, T>;
+    /**
+     * Returns entities in this collection but not in other, comparing by remoteId
+     * Useful for finding entities that exist locally but not in backend response
+     * @example
+     * const localOnly = localCollection.exceptByRemoteId(backendCollection);
+     */
+    exceptByRemoteId(other: RemoteEntityCollection<T>): RemoteEntityCollection<T>;
+    /**
+     * Returns entities present in both collections, comparing by remoteId
+     * Useful for finding entities that exist in both local and backend
+     * @example
+     * const inBoth = localCollection.intersectByRemoteId(backendCollection);
+     */
+    intersectByRemoteId(other: RemoteEntityCollection<T>): RemoteEntityCollection<T>;
+    /**
+     * Removes duplicates by remoteId (keeps first occurrence)
+     * Entities without remoteId are kept and deduplicated by uuid
+     * @example
+     * const unique = collection.distinctByRemoteId();
+     */
+    distinctByRemoteId(): RemoteEntityCollection<T>;
+    /**
+     * Filters entities pending synchronization with backend
+     * @example
+     * const pending = collection.findPendingSync();
+     * for (const entity of pending) {
+     *   await pushToBackend(entity);
+     * }
+     */
+    findPendingSync(): RemoteEntityCollection<T>;
+    /**
+     * Filters entities successfully synced with backend
+     * @example
+     * const synced = collection.findSynced();
+     * console.log(`${synced.length} entities synced`);
+     */
+    findSynced(): RemoteEntityCollection<T>;
+    /**
+     * Filters entities that failed synchronization
+     * @example
+     * const failed = collection.findFailed();
+     * failed.forEach(e => logger.error(`Failed to sync: ${e.uuid}`));
+     */
+    findFailed(): RemoteEntityCollection<T>;
+    /**
+     * Groups entities by remote state
+     * @example
+     * const byState = collection.groupByRemoteState();
+     * console.log(`Pending: ${byState.get('PENDING')?.length}`);
+     */
+    groupByRemoteState(): Map<string, RemoteEntityCollection<T>>;
+}