@qikdev/sdk 0.1.211 → 0.1.213

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qikdev/sdk",
-  "version": "0.1.211",
+  "version": "0.1.213",
   "type": "module",
   "description": "Promise based Javascript SDK",
   "main": "./dist/main.js",

package/src/api/qik.content.js

@@ -64,8 +64,141 @@ export default function (qik) {
   ///////////////////////////////////////////////////
 
   const glossaryCache = qik.cache.get("user:glossary");
+  const glossaryIndexCache = qik.cache.get("user:glossary:index");
+  const definitionCache = qik.cache.get("user:glossary:definitions");
 
   let inflightGlossaryRequest;
+  let inflightGlossaryIndexRequest;
+  let inflightDefinitionRequests = {};
+  let indexItemsByKey = {};
+  let hydrationQueue = [];
+  let isHydrating = false;
+
+  const CONCURRENT_HYDRATION_REQUESTS = 3;
+
+  /**
+   * Start background hydration of all definitions
+   * Uses concurrent workers for faster loading
+   * @private
+   */
+  async function startBackgroundHydration(keys) {
+    hydrationQueue = [...keys];
+    if (isHydrating) return;
+    isHydrating = true;
+
+    // Worker function that pulls from the shared queue
+    async function worker() {
+      while (hydrationQueue.length > 0) {
+        const key = hydrationQueue.shift();
+
+        // Skip if already populated or loading
+        if (indexItemsByKey[key]?.populated) continue;
+        if (inflightDefinitionRequests[key]) continue;
+
+        try {
+          await loadDefinition(key);
+        } catch (e) {
+          console.warn(`Failed to hydrate ${key}:`, e);
+        }
+      }
+    }
+
+    // Start concurrent workers
+    const workers = [];
+    for (let i = 0; i < CONCURRENT_HYDRATION_REQUESTS; i++) {
+      workers.push(worker());
+    }
+    await Promise.all(workers);
+
+    isHydrating = false;
+  }
+
+  /**
+   * Load a single definition from the server
+   * @private
+   */
+  async function loadDefinition(key) {
+    inflightDefinitionRequests[key] = qik.api.get(`/glossary/${key}`);
+
+    try {
+      const { data } = await inflightDefinitionRequests[key];
+
+      // Merge full data into existing index item (mutate in place)
+      const indexItem = indexItemsByKey[key];
+      if (indexItem) {
+        Object.assign(indexItem, data, { populated: true });
+      }
+
+      // Also cache separately for getDefinition()
+      const cached = indexItem || { ...data, populated: true };
+      definitionCache.set(key, cached);
+      qik.dispatch("glossary:definition", { key, data: cached });
+      return cached;
+    } finally {
+      inflightDefinitionRequests[key] = null;
+    }
+  }
+
+  /**
+   * Get a full definition for a specific type.
+   * Returns cached if available, otherwise fetches from server.
+   * If background hydration is in progress, prioritizes this key.
+   * @alias content.getDefinition
+   * @param {String} key The type key (e.g., 'article', 'profile')
+   * @param {Object} options Additional options
+   * @param {Boolean} options.reload Force reload from server
+   * @returns {Promise<Object>} The full type definition
+   * @example
+   * const article = await sdk.content.getDefinition('article');
+   * console.log(article.fields);
+   */
+  service.getDefinition = async function (key, options) {
+    options = options || {};
+
+    // Return cached if available and not forcing reload
+    let cached = definitionCache.get(key);
+    if (cached && !options.reload && !options.refresh) {
+      return cached;
+    }
+
+    // If already loading, wait for it
+    if (inflightDefinitionRequests[key]) {
+      await inflightDefinitionRequests[key];
+      return definitionCache.get(key);
+    }
+
+    // Prioritize: move to front of queue
+    const queueIndex = hydrationQueue.indexOf(key);
+    if (queueIndex > 0) {
+      hydrationQueue.splice(queueIndex, 1);
+      hydrationQueue.unshift(key);
+    }
+
+    // Load it now
+    return loadDefinition(key);
+  };
+
+  /**
+   * Start loading all remaining definitions in the background.
+   * Requires glossary({ index: true }) to be called first.
+   * Uses concurrent requests for faster loading.
+   * @alias content.hydrateInBackground
+   * @example
+   * await sdk.content.glossary({ index: true });
+   * sdk.content.hydrateInBackground();
+   */
+  service.hydrateInBackground = function () {
+    const cached = glossaryIndexCache.get("index");
+    if (!cached) {
+      console.warn(
+        "Call glossary({ index: true }) before hydrateInBackground()",
+      );
+      return;
+    }
+
+    const keys = cached.map((item) => item.key);
+    startBackgroundHydration(keys);
+  };
 
   /**
    * Inflate a single value from compressed format
@@ -203,15 +336,62 @@ export default function (qik) {
      * @param  {Boolean} options.reload Force glossary to reload and not be cached.
       If false will retrieve content type data from the in memory cache
      * @param  {Boolean} options.uncompressed Use the uncompressed endpoint
+     * @param  {Boolean} options.index Use lightweight index mode with background hydration
      * @example
      *
      * const { article, profile } = await sdk.content.glossary({hash:true});
      * // Use compressed endpoint for faster loading
      * const glossary = await sdk.content.glossary({compressed:true});
+     * // Use lightweight index with background hydration
+     * const glossary = await sdk.content.glossary({index:true, hash:true});
      */
   service.glossary = async function (options) {
     options = options || {};
 
+    // Index mode: lightweight load with background hydration
+    if (options.index) {
+      let cached = glossaryIndexCache.get("index");
+      const reload = options.reload || options.refresh || !cached;
+
+      if (reload) {
+        if (!inflightGlossaryIndexRequest) {
+          inflightGlossaryIndexRequest = qik.api.get("/glossary/index");
+          inflightGlossaryIndexRequest.then(
+            () => {
+              inflightGlossaryIndexRequest = null;
+            },
+            () => {
+              inflightGlossaryIndexRequest = null;
+            },
+          );
+        }
+
+        const { data } = await inflightGlossaryIndexRequest;
+
+        // Add populated:false to each item and build lookup map
+        data.forEach((item) => {
+          item.populated = false;
+          indexItemsByKey[item.key] = item;
+        });
+
+        glossaryIndexCache.set("index", data);
+        cached = data;
+        qik.dispatch("glossary:index", data);
+        // No auto-hydration - call hydrateInBackground() explicitly if needed
+      }
+
+      if (options.hash) {
+        return qik.utils.hash(cached, "key");
+      }
+
+      if (options.hex) {
+        return qik.utils.hash(cached, "hex");
+      }
+
+      return cached;
+    }
+
+    // Full glossary mode (existing behavior)
     // Check if we already have the glossary cached
     let cached = glossaryCache.get("glossary");
     const uncompressed = !!options.uncompressed;

package/src/version.js

@@ -1 +1 @@
-export const version = "0.1.211";
+export const version = "0.1.213";