sgerp-frontend-lib 0.1.1 → 0.1.3

package/dist/sgerp/collection.js

@@ -0,0 +1,756 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Collection = void 0;
+const underscore_1 = __importDefault(require("underscore"));
+/**
+ * Base Collection class inspired by Backbone.js
+ * Provides indexing, pagination, and utility methods for model arrays
+ * Uses underscore.js for collection operations
+ * Supports React integration via change listeners
+ */
+class Collection {
+    constructor(fetchFn, models, meta) {
+        this._models = [];
+        this._index = new Map();
+        this._meta = {
+            has_more: false,
+            next: null,
+            next_offset: null,
+        };
+        this._offset = 0;
+        this._limit = 20;
+        this.lastParams = {};
+        this._listeners = new Set();
+        this._dependentCalls = [];
+        // Batched getAsync state
+        this._batchQueue = new Map();
+        this._batchTimeout = null;
+        this._isBatchFetching = false;
+        this._cacheHits = new Set();
+        this.fetchFn = fetchFn;
+        if (models) {
+            this.reset(models, meta);
+        }
+    }
+    /**
+     * Register a dependent call configuration
+     * This will automatically fetch related data after the main collection is loaded
+     */
+    registerDependentCall(config) {
+        this._dependentCalls.push(config);
+    }
+    /**
+     * Subscribe to collection changes (for React integration)
+     */
+    onChange(listener) {
+        this._listeners.add(listener);
+        // Return unsubscribe function
+        return () => {
+            this._listeners.delete(listener);
+        };
+    }
+    /**
+     * Notify all listeners of changes
+     */
+    _notifyChange() {
+        this._listeners.forEach(listener => listener());
+    }
+    /**
+     * Get all models in the collection
+     */
+    get models() {
+        return this._models;
+    }
+    /**
+     * Get the number of models in the collection
+     */
+    get length() {
+        return this._models.length;
+    }
+    /**
+     * Get pagination metadata
+     */
+    get meta() {
+        return this._meta;
+    }
+    /**
+     * Check if there are more pages to fetch
+     */
+    get hasMore() {
+        return this._meta.has_more;
+    }
+    /**
+     * Get a model by ID from the index
+     */
+    get(id) {
+        return this._index.get(id);
+    }
+    /**
+     * Asynchronously get a model by ID with automatic batched fetching
+     * If the model is not in the collection, it will be fetched along with other requested IDs
+     * All getAsync calls within 50ms are batched into a single API request
+     *
+     * @param id - The ID of the model to fetch
+     * @returns Promise that resolves to the model or null if not found
+     *
+     * @example
+     * const project = await api.collections.project.getAsync(123);
+     * if (project) {
+     *   console.log(project.name);
+     * }
+     */
+    async getAsync(id, forceFresh = false) {
+        // Check if already in collection (skip if forceFresh is true)
+        const existing = this._index.get(id);
+        if (existing && !forceFresh) {
+            this._cacheHits.add(id);
+            // Ensure batch will be processed to log cache hits
+            if (!this._batchTimeout) {
+                this._batchTimeout = setTimeout(() => {
+                    this._processBatch();
+                }, 50);
+            }
+            return existing;
+        }
+        // Return a promise that will be resolved when batch fetch completes
+        return new Promise((resolve) => {
+            // Add to batch queue
+            if (!this._batchQueue.has(id)) {
+                this._batchQueue.set(id, []);
+            }
+            this._batchQueue.get(id).push(resolve);
+            // Clear existing timeout and set new one (debounce)
+            if (this._batchTimeout) {
+                clearTimeout(this._batchTimeout);
+            }
+            this._batchTimeout = setTimeout(() => {
+                this._processBatch();
+            }, 50); // 50ms debounce
+        });
+    }
+    /**
+     * Process the batched getAsync requests
+     * @private
+     */
+    async _processBatch() {
+        if (this._isBatchFetching) {
+            return;
+        }
+        const idsToFetch = Array.from(this._batchQueue.keys());
+        const cacheHits = Array.from(this._cacheHits);
+        const resolvers = new Map(this._batchQueue);
+        this._batchQueue.clear();
+        this._cacheHits.clear();
+        this._isBatchFetching = true;
+        // Log summary
+        if (cacheHits.length > 0 || idsToFetch.length > 0) {
+            const parts = [];
+            if (cacheHits.length > 0) {
+                parts.push(`${cacheHits.length} from cache: [${cacheHits.join(', ')}]`);
+            }
+            if (idsToFetch.length > 0) {
+                parts.push(`${idsToFetch.length} to fetch: [${idsToFetch.join(', ')}]`);
+            }
+            console.log(`[Collection._processBatch] ${parts.join(' | ')}`);
+        }
+        if (idsToFetch.length === 0) {
+            this._isBatchFetching = false;
+            return;
+        }
+        try {
+            // Fetch all IDs in one request (using fetchFn directly to avoid reset)
+            const response = await this.fetchFn({
+                id__in: idsToFetch.join(','),
+                limit: idsToFetch.length,
+            });
+            // Add fetched models to collection without clearing existing ones
+            if (response.objects && response.objects.length > 0) {
+                this.add(response.objects);
+            }
+            // Resolve all promises with the fetched models
+            idsToFetch.forEach(id => {
+                const model = this._index.get(id) || null;
+                const callbacks = resolvers.get(id);
+                if (callbacks) {
+                    callbacks.forEach(callback => callback(model));
+                }
+            });
+        }
+        catch (error) {
+            console.error('[Collection._processBatch] Failed to fetch batched models:', error);
+            // Resolve all promises with null on error
+            idsToFetch.forEach(id => {
+                const callbacks = resolvers.get(id);
+                if (callbacks) {
+                    callbacks.forEach(callback => callback(null));
+                }
+            });
+        }
+        finally {
+            this._isBatchFetching = false;
+        }
+    }
+    /**
+     * Get a model at a specific position
+     */
+    at(index) {
+        return this._models[index];
+    }
+    /**
+     * Add models to the collection and update the index
+     * Creates a new array reference for React compatibility
+     * Only triggers change notification if data actually changed
+     */
+    add(models) {
+        const modelsArray = Array.isArray(models) ? models : [models];
+        const newModels = [...this._models];
+        let hasChanges = false;
+        modelsArray.forEach(model => {
+            // Update or add to models array
+            const existingIndex = newModels.findIndex(m => m.id === model.id);
+            if (existingIndex >= 0) {
+                // Always update existing items (backend may not update modified_at)
+                newModels[existingIndex] = model;
+                this._index.set(model.id, model);
+                hasChanges = true;
+            }
+            else {
+                newModels.push(model);
+                this._index.set(model.id, model);
+                hasChanges = true;
+            }
+        });
+        // Only update and notify if something actually changed
+        if (hasChanges) {
+            // Create new array reference for React to detect changes
+            this._models = newModels;
+            this._notifyChange();
+        }
+    }
+    /**
+     * Prepend models to the beginning of the collection
+     * Useful for adding newly created items to the top of a list
+     */
+    prepend(models) {
+        const modelsArray = Array.isArray(models) ? models : [models];
+        const newModels = [...this._models];
+        modelsArray.forEach(model => {
+            // Remove if already exists
+            const existingIndex = newModels.findIndex(m => m.id === model.id);
+            if (existingIndex >= 0) {
+                newModels.splice(existingIndex, 1);
+            }
+            // Add to the beginning
+            newModels.unshift(model);
+            // Update index
+            this._index.set(model.id, model);
+        });
+        // Create new array reference for React to detect changes
+        this._models = newModels;
+        this._notifyChange();
+    }
+    /**
+     * Prepend models to the beginning of the collection and fetch their related data
+     * This is useful when adding newly created items without refetching the entire collection
+     * @param models - Model(s) to prepend
+     * @param config - Optional request configuration
+     */
+    async prependWithRelations(models, config) {
+        // First prepend the model(s) to the collection
+        this.prepend(models);
+        // Then execute dependent calls to fetch and attach related data
+        // executeDependentCalls processes all models in _models, so it will enrich the prepended models
+        await this.executeDependentCalls(config);
+    }
+    /**
+     * Remove a model by ID
+     */
+    remove(id) {
+        this._models = this._models.filter(m => m.id !== id);
+        this._index.delete(id);
+        this._notifyChange();
+    }
+    /**
+     * Reset the collection with new models
+     */
+    reset(models, meta) {
+        this._models = [];
+        this._index.clear();
+        if (meta) {
+            this._meta = meta;
+        }
+        this.add(models);
+        // No need to call _notifyChange here since add() calls it
+    }
+    /**
+     * Get the maximum modified_at value from the collection
+     * Useful for incremental updates
+     */
+    getMaxModifiedAt() {
+        if (this._models.length === 0)
+            return null;
+        const modifiedAtValues = this._models
+            .map(m => m.modified_at)
+            .filter(Boolean);
+        if (modifiedAtValues.length === 0)
+            return null;
+        // String comparison works for ISO timestamps
+        return modifiedAtValues.reduce((max, current) => (current > max ? current : max), modifiedAtValues[0]);
+    }
+    /**
+     * Fetch and merge updates since the last modified_at timestamp
+     * Returns true if new data was fetched, false otherwise
+     */
+    async fetchUpdates(additionalParams = {}, useGte = false) {
+        let maxModifiedAt = this.getMaxModifiedAt();
+        // If collection is empty, use Unix epoch (1970-01-01) to fetch all data
+        if (!maxModifiedAt) {
+            maxModifiedAt = '1970-01-01T00:00:00Z';
+        }
+        const filterKey = useGte ? 'modified_at__gte' : 'modified_at__gt';
+        const params = Object.assign(Object.assign({}, additionalParams), { [filterKey]: maxModifiedAt });
+        // Use fetchFn which already knows the collection name
+        const response = await this.fetchFn(params);
+        const updates = response.objects || [];
+        if (updates.length > 0) {
+            // Merge updates into existing collection
+            this.add(updates);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Clear all models from the collection
+     */
+    clear() {
+        this._models = [];
+        this._index.clear();
+        this._meta = {
+            has_more: false,
+            next: null,
+            next_offset: null,
+        };
+        this._notifyChange();
+    }
+    /**
+     * Iterate over each model
+     */
+    forEach(callback) {
+        this._models.forEach(callback);
+    }
+    /**
+     * Map over models
+     */
+    map(callback) {
+        return this._models.map(callback);
+    }
+    /**
+     * Filter models
+     */
+    filter(callback) {
+        return this._models.filter(callback);
+    }
+    /**
+     * Find a model
+     */
+    find(callback) {
+        return this._models.find(callback);
+    }
+    /**
+     * Check if collection contains a model with the given ID
+     */
+    has(id) {
+        return this._index.has(id);
+    }
+    /**
+     * Convert to plain array
+     */
+    toArray() {
+        return [...this._models];
+    }
+    /**
+     * Convert to JSON
+     */
+    toJSON() {
+        return this._models;
+    }
+    // ============================================
+    // Underscore.js Collection Methods
+    // ============================================
+    /**
+     * Extract a single property from each model
+     * @example projects.pluck('name') // ['Project 1', 'Project 2']
+     */
+    pluck(key) {
+        return underscore_1.default.pluck(this._models, key);
+    }
+    /**
+     * Filter models that match all the given properties
+     * @example projects.where({ timezone: 'UTC' })
+     */
+    where(properties) {
+        return underscore_1.default.where(this._models, properties);
+    }
+    /**
+     * Find the first model that matches all the given properties
+     * @example projects.findWhere({ timezone: 'UTC' })
+     */
+    findWhere(properties) {
+        return underscore_1.default.findWhere(this._models, properties);
+    }
+    /**
+     * Sort models by a property or function
+     * @example projects.sortBy('name')
+     * @example projects.sortBy(p => p.name.toLowerCase())
+     */
+    sortBy(iteratee) {
+        return underscore_1.default.sortBy(this._models, iteratee);
+    }
+    /**
+     * Group models by a property or function
+     * @example projects.groupBy('timezone')
+     * @example projects.groupBy(p => p.name[0]) // Group by first letter
+     */
+    groupBy(iteratee) {
+        return underscore_1.default.groupBy(this._models, iteratee);
+    }
+    /**
+     * Count models by a property or function
+     * @example projects.countBy('timezone')
+     */
+    countBy(iteratee) {
+        return underscore_1.default.countBy(this._models, iteratee);
+    }
+    /**
+     * Index models by a property or function (returns a map)
+     * @example projects.indexBy('name')
+     */
+    indexBy(iteratee) {
+        return underscore_1.default.indexBy(this._models, iteratee);
+    }
+    /**
+     * Split collection into two arrays: [matches, non-matches]
+     * @example const [active, inactive] = projects.partition(p => !p.is_invalidated)
+     */
+    partition(predicate) {
+        return underscore_1.default.partition(this._models, predicate);
+    }
+    /**
+     * Get n random models from the collection
+     * @example projects.sample(3) // Get 3 random projects
+     */
+    sample(n) {
+        if (n === undefined) {
+            return underscore_1.default.sample(this._models);
+        }
+        return underscore_1.default.sample(this._models, n);
+    }
+    /**
+     * Shuffle the models (returns new array)
+     * @example projects.shuffle()
+     */
+    shuffle() {
+        return underscore_1.default.shuffle(this._models);
+    }
+    /**
+     * Get the first n models (or first model if n not specified)
+     * @example projects.first() // First project
+     * @example projects.first(5) // First 5 projects
+     */
+    first(n) {
+        if (n === undefined) {
+            return underscore_1.default.first(this._models);
+        }
+        return underscore_1.default.first(this._models, n);
+    }
+    /**
+     * Get the last n models (or last model if n not specified)
+     * @example projects.last() // Last project
+     * @example projects.last(5) // Last 5 projects
+     */
+    last(n) {
+        if (n === undefined) {
+            return underscore_1.default.last(this._models);
+        }
+        return underscore_1.default.last(this._models, n);
+    }
+    /**
+     * Get all models except the last n
+     * @example projects.initial(2) // All except last 2
+     */
+    initial(n = 1) {
+        return underscore_1.default.initial(this._models, n);
+    }
+    /**
+     * Get all models except the first n
+     * @example projects.rest(2) // All except first 2
+     */
+    rest(n = 1) {
+        return underscore_1.default.rest(this._models, n);
+    }
+    /**
+     * Exclude models with the given IDs
+     * @example projects.without(1, 2, 3)
+     */
+    without(...ids) {
+        return underscore_1.default.reject(this._models, model => ids.includes(model.id));
+    }
+    /**
+     * Check if collection is empty
+     * @example projects.isEmpty()
+     */
+    isEmpty() {
+        return underscore_1.default.isEmpty(this._models);
+    }
+    /**
+     * Get the size of the collection (alias for length)
+     * @example projects.size()
+     */
+    size() {
+        return underscore_1.default.size(this._models);
+    }
+    /**
+     * Test if all models pass the predicate
+     * @example projects.every(p => !p.is_invalidated)
+     */
+    every(predicate) {
+        return underscore_1.default.every(this._models, predicate);
+    }
+    /**
+     * Test if any model passes the predicate
+     * @example projects.some(p => p.timezone === 'UTC')
+     */
+    some(predicate) {
+        return underscore_1.default.some(this._models, predicate);
+    }
+    /**
+     * Opposite of filter - returns models that don't match
+     * @example projects.reject(p => p.is_invalidated)
+     */
+    reject(predicate) {
+        return underscore_1.default.reject(this._models, predicate);
+    }
+    /**
+     * Find the maximum value by a property or function
+     * @example projects.max('created_at')
+     * @example projects.max(p => p.name.length)
+     */
+    max(iteratee) {
+        return underscore_1.default.max(this._models, iteratee);
+    }
+    /**
+     * Find the minimum value by a property or function
+     * @example projects.min('created_at')
+     * @example projects.min(p => p.name.length)
+     */
+    min(iteratee) {
+        return underscore_1.default.min(this._models, iteratee);
+    }
+    /**
+     * Reduce the collection to a single value
+     * @example projects.reduce((sum, p) => sum + 1, 0)
+     */
+    reduce(callback, initialValue) {
+        return underscore_1.default.reduce(this._models, callback, initialValue);
+    }
+    /**
+     * Get unique models (removes duplicates by ID)
+     * @example projects.uniq()
+     */
+    uniq() {
+        return underscore_1.default.uniq(this._models, model => model.id);
+    }
+    /**
+     * Check if the collection contains a model matching the predicate
+     * @example projects.contains(p => p.name === 'Test')
+     */
+    contains(predicate) {
+        return underscore_1.default.some(this._models, predicate);
+    }
+    /**
+     * Invoke a method on each model (if models have methods)
+     * @example projects.invoke('toString')
+     */
+    invoke(methodName, ...args) {
+        return underscore_1.default.invoke(this._models, methodName, ...args);
+    }
+    /**
+     * Execute all dependent calls after the main collection is loaded
+     */
+    async executeDependentCalls(config) {
+        if (this._dependentCalls.length === 0 || this._models.length === 0) {
+            return;
+        }
+        for (const dependentCall of this._dependentCalls) {
+            // Extract all IDs from current models
+            const ids = this._models
+                .map(model => dependentCall.extractIds(model))
+                .filter((id) => id !== null && id !== undefined);
+            // Remove duplicates
+            const uniqueIds = Array.from(new Set(ids));
+            if (uniqueIds.length === 0) {
+                continue;
+            }
+            // Build params for dependent API call
+            const idParam = dependentCall.idParam || 'id__in';
+            const dependentParams = {
+                [idParam]: uniqueIds.join(','),
+            };
+            if (dependentCall.onlyFields && dependentCall.onlyFields.length > 0) {
+                dependentParams.only_fields = dependentCall.onlyFields.join(',');
+            }
+            // Add extra filter parameters if provided
+            if (dependentCall.extraParams) {
+                Object.assign(dependentParams, dependentCall.extraParams);
+            }
+            try {
+                // Fetch related data
+                const dependentResponse = await dependentCall.fetchFn(dependentParams, config);
+                if (dependentCall.isArray) {
+                    // One-to-many relationship: group related objects by match field
+                    const matchField = dependentCall.matchField || 'id';
+                    const relatedArrayMap = new Map();
+                    dependentResponse.objects.forEach(obj => {
+                        const matchValue = obj[matchField];
+                        if (matchValue !== null && matchValue !== undefined) {
+                            if (!relatedArrayMap.has(matchValue)) {
+                                relatedArrayMap.set(matchValue, new Map());
+                            }
+                            // Use Map to deduplicate by ID
+                            relatedArrayMap.get(matchValue).set(obj.id, obj);
+                        }
+                    });
+                    // Merge related arrays back into models
+                    this._models = this._models.map(model => {
+                        const relatedId = dependentCall.extractIds(model);
+                        if (relatedId !== null && relatedId !== undefined) {
+                            const relatedMap = relatedArrayMap.get(relatedId);
+                            const relatedArray = relatedMap ? Array.from(relatedMap.values()) : [];
+                            return Object.assign(Object.assign({}, model), { [dependentCall.targetField]: relatedArray });
+                        }
+                        return Object.assign(Object.assign({}, model), { [dependentCall.targetField]: [] });
+                    });
+                }
+                else {
+                    // One-to-one relationship: map by ID
+                    const relatedMap = new Map(dependentResponse.objects.map(obj => [obj.id, obj]));
+                    // Merge related data back into models
+                    this._models = this._models.map(model => {
+                        const relatedId = dependentCall.extractIds(model);
+                        if (relatedId !== null && relatedId !== undefined) {
+                            const relatedObj = relatedMap.get(relatedId);
+                            if (relatedObj) {
+                                return Object.assign(Object.assign({}, model), { [dependentCall.targetField]: relatedObj });
+                            }
+                        }
+                        return model;
+                    });
+                }
+                // Update the index with merged models
+                this._models.forEach(model => {
+                    this._index.set(model.id, model);
+                });
+            }
+            catch (error) {
+                console.error(`Failed to fetch dependent data for ${dependentCall.collectionName}:`, error);
+                // Continue with other dependent calls even if one fails
+            }
+        }
+        // Notify listeners of the changes
+        this._notifyChange();
+    }
+    /**
+     * Fetch the first page of models
+     */
+    async fetch(params, config) {
+        const paramsObj = (params && typeof params === 'object' ? params : {});
+        this.lastParams = paramsObj;
+        this._limit = paramsObj.limit || 20;
+        this._offset = paramsObj.offset || 0;
+        const response = await this.fetchFn(Object.assign(Object.assign({}, paramsObj), { limit: this._limit, offset: this._offset }), config);
+        this.reset(response.objects, response.meta);
+        // Execute dependent calls to fetch related data
+        await this.executeDependentCalls(config);
+    }
+    /**
+     * Fetch the next page and append to the collection
+     */
+    async fetchNext(config) {
+        if (!this._meta.has_more) {
+            return;
+        }
+        // Calculate next offset
+        this._offset += this._limit;
+        // Use lastParams to preserve filters, just update offset
+        const response = await this.fetchFn(Object.assign(Object.assign({}, this.lastParams), { limit: this._limit, offset: this._offset }), config);
+        this.add(response.objects);
+        this._meta = response.meta;
+        // Execute dependent calls for the newly loaded page
+        await this.executeDependentCalls(config);
+    }
+    /**
+     * Fetch all pages and populate the collection
+     */
+    async fetchAll(params, config) {
+        // Fetch first page with provided params
+        const paramsObj = (params && typeof params === 'object' ? params : {});
+        await this.fetch(Object.assign(Object.assign({}, paramsObj), { limit: 1000 }), config);
+        // Fetch remaining pages
+        while (this._meta.has_more) {
+            await this.fetchNext(config);
+        }
+    }
+    /**
+     * Convert collection models to GeoJSON FeatureCollection
+     *
+     * @param toFeature - Optional function to convert a model to a GeoJSON Feature.
+     *                    If not provided, subclasses should override this method.
+     * @returns GeoJSON FeatureCollection or null if conversion is not supported
+     *
+     * @example
+     * // With callback
+     * const geojson = collection.toGeoJSON((location) => ({
+     *   type: 'Feature',
+     *   geometry: location.point,
+     *   properties: {
+     *     name: location.name,
+     *     code: location.code
+     *   },
+     *   id: location.id
+     * }));
+     *
+     * @example
+     * // Override in subclass
+     * class MyCollection extends Collection<MyModel> {
+     *   toGeoJSON(): GeoJSONFeatureCollection {
+     *     return {
+     *       type: 'FeatureCollection',
+     *       features: this.models.map(model => ({
+     *         type: 'Feature',
+     *         geometry: model.geometry,
+     *         properties: { name: model.name },
+     *         id: model.id
+     *       }))
+     *     };
+     *   }
+     * }
+     */
+    toGeoJSON(toFeature) {
+        if (!toFeature) {
+            // No conversion function provided and not overridden in subclass
+            console.warn('toGeoJSON: No conversion function provided. Pass a toFeature callback or override this method in a subclass.');
+            return null;
+        }
+        const features = this._models
+            .map(model => toFeature(model))
+            .filter((feature) => feature !== null);
+        return {
+            type: 'FeatureCollection',
+            features
+        };
+    }
+}
+exports.Collection = Collection;