Source: smart-collections/collection.js

  1. import { CollectionItem } from './collection_item.js';
  2. import { deep_merge } from './helpers.js';
  3. import {render as render_settings_component} from "./components/settings.js";
  5. const AsyncFunction = Object.getPrototypeOf(async function(){}).constructor; // for checking if function is async
  7. /**
  8.  * Base class representing a collection of items with various methods to manipulate and retrieve these items.
  9.  */
  10. export class Collection {
  11.   /**
  12.    * Constructs a new Collection instance.
  13.    * @param {Object} env - The environment context containing configurations and adapters.
  14.    */
  15.   constructor(env, opts = {}) {
  16.     this.env = env;
  17.     this.opts = opts;
  18.     if(opts.custom_collection_key) this.collection_key = opts.custom_collection_key;
  19.     this.env[this.collection_key] = this;
  20.     this.config = this.env.config;
  21.     this.items = {};
  22.     this.merge_defaults();
  23.     this.loaded = null;
  24.     this._loading = false;
  25.     this.load_time_ms = null;
  26.     this.settings_container = null;
  27.   }
  28.   static async init(env, opts = {}) {
  29.     env[this.collection_key] = new this(env, opts);
  30.     await env[this.collection_key].init();
  31.     env.collections[this.collection_key] = 'init';
  32.   }
  34.   /**
  35.    * Gets the collection name derived from the class name.
  36.    * @return {String} The collection name.
  37.    */
  38.   static get collection_key() { return this.name.replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase(); }
  40.   // INSTANCE METHODS
  41.   async init() {}
  43.   /**
  44.    * Creates or updates an item in the collection based on the provided data.
  45.    * @param {Object} data - The data to create or update an item.
  46.    * @returns {Promise<CollectionItem>|CollectionItem} The newly created or updated item.
  47.    */
  48.   create_or_update(data = {}) {
  49.     const existing = this.find_by(data);
  50.     const item = existing ? existing : new this.item_type(this.env);
  51.     item._queue_save = !!!existing;
  52.     const changed = item.update_data(data); // handles this.data
  53.     if (!existing) {
  54.       if (item.validate_save()) this.set(item); // make it available in collection (if valid)
  55.       else {
  56.         console.warn("Invalid item, skipping adding to collection: ", item);
  57.         return item;
  58.       }
  59.     }
  60.     if (existing && !changed) return existing; // if existing item and no changes, return existing item (no need to save)
  61.     // dynamically handle async init functions
  62.     if (item.init instanceof AsyncFunction) return new Promise((resolve, reject) => { item.init(data).then(() => resolve(item)); });
  63.     item.init(data); // handles functions that involve other items
  64.     return item;
  65.   }
  67.   /**
  68.    * Finds an item in the collection that matches the given data.
  69.    * @param {Object} data - The criteria used to find the item.
  70.    * @returns {CollectionItem|null} The found item or null if not found.
  71.    */
  72.   find_by(data) {
  73.     if(data.key) return this.get(data.key);
  74.     const temp = new this.item_type(this.env);
  75.     const temp_data = JSON.parse(JSON.stringify(data, temp.sanitize_data(data)));
  76.     deep_merge(temp.data, temp_data); // deep merge data
  77.     return temp.key ? this.get(temp.key) : null;
  78.   }
  79.   // READ
  80.   /**
  81.    * Filters the items in the collection based on the provided options.
  82.    * @param {Object} filter_opts - The options used to filter the items.
  83.    * @return {CollectionItem[]} The filtered items.
  84.    */
  85.   filter(filter_opts={}) {
  86.     this.filter_opts = this.prepare_filter(filter_opts);
  87.     const results = [];
  88.     const { limit } = this.filter_opts;
  89.     for (const item of Object.values(this.items)) {
  90.       if (limit && results.length >= limit) break;
  91.       if (item.filter(filter_opts)) {
  92.         results.push(item);
  93.       }
  94.     }
  95.     return results;
  96.   }
  97.   // alias for filter
  98.   list(filter_opts) { return this.filter(filter_opts); }
  100.   /**
  101.    * Prepares filter options for use in the filter implementation.
  102.    * Used by sub-classes to convert simplified filter options into filter_opts compatible with the filter implementation.
  103.    * @param {Object} filter_opts - The original filter options provided.
  104.    * @returns {Object} The prepared filter options compatible with the filter implementation.
  105.    */
  106.   prepare_filter(filter_opts) { return filter_opts; }
  107.   /**
  108.    * Retrieves a single item from the collection based on the provided strategy and options.
  109.    * @param {String} key - The key of the item to retrieve.
  110.    * @return {CollectionItem} The retrieved item.
  111.    */
  112.   get(key) { return this.items[key]; }
  113.   /**
  114.    * Retrieves multiple items from the collection based on the provided keys.
  115.    * @param {String[]} keys - The keys of the items to retrieve.
  116.    * @return {CollectionItem[]} The retrieved items.
  117.    */
  118.   get_many(keys = []) {
  119.     if (Array.isArray(keys)) return keys.map((key) => this.get(key)).filter(Boolean);
  120.     console.error("get_many called with non-array keys: ", keys);
  121.   }
  122.   /**
  123.    * Retrieves a random item from the collection based on the provided options.
  124.    * @param {Object} opts - The options used to retrieve the item.
  125.    * @return {CollectionItem} The retrieved item.
  126.    */
  127.   get_rand(opts = null) {
  128.     if (opts) {
  129.       const filtered = this.filter(opts);
  130.       return filtered[Math.floor(Math.random() * filtered.length)];
  131.     }
  132.     return this.items[this.keys[Math.floor(Math.random() * this.keys.length)]];
  133.   }
  134.   // UPDATE
  135.   /**
  136.    * Adds or updates an item in the collection.
  137.    * @param {CollectionItem} item - The item to add or update.
  138.    */
  139.   set(item) {
  140.     if (!item.key) throw new Error("Item must have key property");
  141.     this.items[item.key] = item;
  142.   }
  143.   /**
  144.    * Updates multiple items in the collection based on the provided keys and data.
  145.    * @param {String[]} keys - The keys of the items to update.
  146.    * @param {Object} data - The data to update the items with.
  147.    */
  148.   update_many(keys = [], data = {}) { this.get_many(keys).forEach((item) => item.update_data(data)); }
  149.   // DESTROY
  150.   /**
  151.    * Clears all items from the collection.
  152.    */
  153.   clear() {
  154.     this.items = {};
  155.   }
  156.   /**
  157.    * Deletes an item from the collection based on its key.
  158.    * Does not trigger save or delete from adapter data.
  159.    * @param {String} key - The key of the item to delete.
  160.    */
  161.   delete_item(key) {
  162.     delete this.items[key];
  163.   }
  164.   /**
  165.    * Deletes multiple items from the collection based on their keys.
  166.    * @param {String[]} keys - The keys of the items to delete.
  167.    */
  168.   delete_many(keys = []) {
  169.     // keys.forEach((key) => delete this.items[key]);
  170.     keys.forEach((key) => {
  171.       this.items[key].delete();
  172.     });
  173.   }
  174.   // CONVENIENCE METHODS (namespace getters)
  175.   /**
  176.    * Gets or sets the collection name. If a name is set, it overrides the default name.
  177.    * @param {String} name - The new collection name.
  178.    */
  179.   get collection_key() { return (this._collection_key) ? this._collection_key : this.constructor.collection_key; }
  180.   set collection_key(name) { this._collection_key = name; }
  182.   // DATA ADAPTER
  183.   get data_adapter() {
  184.     if(!this._data_adapter){
  185.       const config = this.env.opts.collections?.[this.collection_key];
  186.       const data_adapter_class = config?.data_adapter
  187.         ?? this.env.opts.collections?.smart_collections?.data_adapter
  188.       ;
  189.       if(!data_adapter_class) throw new Error("No data adapter class found for " + this.collection_key + " or smart_collections");
  190.       this._data_adapter = new data_adapter_class(this);
  191.     }
  192.     return this._data_adapter;
  193.   }
  194.   get data_dir() { return 'multi'; }
  195.   get data_fs() { return this.env.data_fs; }
  196.   /**
  197.    * Gets the class name of the item type the collection manages.
  198.    * @return {String} The item class name.
  199.    */
  200.   get item_class_name() {
  201.     const name = this.constructor.name;
  202.     if (name.endsWith('ies')) return name.slice(0, -3) + 'y'; // Entities -> Entity
  203.     else if (name.endsWith('s')) return name.slice(0, -1); // Sources -> Source
  204.     else return name + "Item"; // Collection -> CollectionItem
  205.   }
  206.   /**
  207.    * Gets the name of the item type the collection manages, derived from the class name.
  208.    * @return {String} The item name.
  209.    */
  210.   get item_name() { return this.item_class_name.replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase(); }
  211.   /**
  212.    * Gets the constructor of the item type the collection manages.
  213.    * @return {Function} The item type constructor.
  214.    */
  215.   get item_type() { return this.env.item_types[this.item_class_name]; }
  216.   /**
  217.    * Gets the keys of the items in the collection.
  218.    * @return {String[]} The keys of the items.
  219.    */
  220.   get keys() { return Object.keys(this.items); }
  222.   /**
  223.    * @deprecated use data_adapter instead (2024-09-14)
  224.    */
  225.   get adapter(){ return this.data_adapter; }
  226.   /**
  227.    * Gets the data path from the environment.
  228.    * @deprecated use env.env_data_dir
  229.    * @returns {string} The data path.
  230.    */
  231.   get data_path() { return this.env.data_path; } // DEPRECATED
  232.   // ADAPTER METHODS
  233.   /**
  234.    * Saves the current state of the collection.
  235.    */
  236.   async save() { await this.data_adapter.save(); }
  237.   async save_queue() { await this.process_save_queue(); }
  239.   // UTILITY METHODS
  240.   /**
  241.    * Merges default configurations from all classes in the inheritance chain for Collection types; 
  242.    * e.g. EntityCollection, NoteCollection, etc.
  243.    */
  244.   merge_defaults() {
  245.     let current_class = this.constructor;
  246.     while (current_class) { // merge collection config into item config
  247.       const col_conf = this.config?.collections?.[current_class.collection_key];
  248.       Object.entries((typeof col_conf === 'object') ? col_conf : {})
  249.         .forEach(([key, value]) => this[key] = value)
  250.       ;
  251.       current_class = Object.getPrototypeOf(current_class);
  252.     }
  253.   }
  254.   async process_save_queue() {
  255.     this.notices?.show('saving', "Saving " + this.collection_key + "...", { timeout: 0 });
  256.     if(this._saving) return console.log("Already saving");
  257.     this._saving = true;
  258.     setTimeout(() => { this._saving = false; }, 10000); // set _saving to false after 10 seconds
  259.     const save_queue = Object.values(this.items).filter(item => item._queue_save);
  260.     console.log("Saving " + this.collection_key + ": ", save_queue.length + " items");
  261.     const time_start = Date.now();
  262.     await Promise.all(save_queue.map(item => item.save()));
  263.     console.log("Saved " + this.collection_key + " in " + (Date.now() - time_start) + "ms");
  264.     this._saving = false;
  265.     this.notices?.remove('saving');
  266.   }
  267.   async process_load_queue() {
  268.     this.notices?.show('loading', "Loading " + this.collection_key + "...", { timeout: 0 });
  269.     if(this._loading) return console.log("Already loading");
  270.     this._loading = true;
  271.     setTimeout(() => { this._loading = false; }, 10000); // set _loading to false after 10 seconds
  272.     const load_queue = Object.values(this.items).filter(item => item._queue_load);
  273.     console.log("Loading " + this.collection_key + ": ", load_queue.length + " items");
  274.     const time_start = Date.now();
  275.     const batch_size = 100;
  276.     for (let i = 0; i < load_queue.length; i += batch_size) {
  277.       const batch = load_queue.slice(i, i + batch_size);
  278.       await Promise.all(batch.map(item => item.load()));
  279.     }
  280.     this.env.collections[this.collection_key] = 'loaded';
  281.     this.load_time_ms = Date.now() - time_start;
  282.     console.log("Loaded " + this.collection_key + " in " + this.load_time_ms + "ms");
  283.     this._loading = false;
  284.     this.loaded = load_queue.length;
  285.     this.notices?.remove('loading');
  286.   }
  287.   get settings_config() { return this.process_settings_config({}); }
  288.   process_settings_config(_settings_config, prefix = '') {
  289.     const add_prefix = (key) =>
  290.       prefix && !key.includes(`${prefix}.`) ? `${prefix}.${key}` : key;
  292.     return Object.entries(_settings_config).reduce((acc, [key, val]) => {
  293.       // Create a shallow copy to avoid mutating the original _settings_config
  294.       let new_val = { ...val };
  296.       if (new_val.conditional) {
  297.         if (!new_val.conditional(this)) return acc;
  298.         delete new_val.conditional; // Remove conditional to prevent re-checking downstream
  299.       }
  301.       if (new_val.callback) {
  302.         new_val.callback = add_prefix(new_val.callback);
  303.       }
  305.       if (new_val.btn_callback) {
  306.         new_val.btn_callback = add_prefix(new_val.btn_callback);
  307.       }
  309.       if (new_val.options_callback) {
  310.         new_val.options_callback = add_prefix(new_val.options_callback);
  311.       }
  313.       const new_key = add_prefix(this.process_setting_key(key));
  314.       acc[new_key] = new_val;
  315.       return acc;
  316.     }, {});
  317.   }
  318.   process_setting_key(key) { return key; } // override in sub-class if needed for prefixes and variable replacements
  319.   get default_settings() { return {}; }
  320.   get settings() {
  321.     if(!this.env.settings[this.collection_key]){
  322.       this.env.settings[this.collection_key] = this.default_settings;
  323.     }
  324.     return this.env.settings[this.collection_key];
  325.   }
  326.   get render_settings_component() {
  327.     return (typeof this.opts.components?.settings === 'function'
  328.       ? this.opts.components.settings
  329.       : render_settings_component
  330.     ).bind(this.smart_view);
  331.   }
  332.   get smart_view() {
  333.     if(!this._smart_view) this._smart_view = this.env.init_module('smart_view');
  334.     return this._smart_view;
  335.   }
  336.   /**
  337.    * Renders the settings for the collection.
  338.    * @param {HTMLElement} container - The container element to render the settings into.
  339.    * @param {Object} opts - Additional options for rendering.
  340.    * @param {Object} opts.settings_keys - An array of keys to render.
  341.    */
  342.   async render_settings(container=this.settings_container, opts = {}) {
  343.     if(!this.settings_container || container !== this.settings_container) this.settings_container = container;
  344.     if(!container) throw new Error("Container is required");
  345.     container.innerHTML = '';
  346.     container.innerHTML = '<div class="sc-loading">Loading ' + this.collection_key + ' settings...</div>';
  347.     const frag = await this.render_settings_component(this, opts);
  348.     container.innerHTML = '';
  349.     container.appendChild(frag);
  350.     this.smart_view.on_open_overlay(container);
  351.     return container;
  352.   }
  354.   unload() {
  355.     this.clear();
  356.   }
  357.   async run_load() {
  358.     this.loaded = null;
  359.     this.load_time_ms = null;
  360.     Object.values(this.items).forEach((item) => item.queue_load());
  361.     this.notices?.show(`loading ${this.collection_key}`, `Loading ${this.collection_key}...`, { timeout: 0 });
  362.     await this.process_load_queue();
  363.     this.notices?.remove(`loading ${this.collection_key}`);
  364.     this.notices?.show('done loading', `${this.collection_key} loaded`, { timeout: 3000 });
  365.     this.render_settings(); // re-render settings
  366.   }
  368. }