saasufy-components 8.3.1 → 8.4.0

package/README.md

@@ -83,7 +83,7 @@ This project does not impose any specific approach to styling components, howeve
 <link href="https://saasufy.com/node_modules/saasufy-components/styles.css" rel="stylesheet" />
 ```
 
-### Utility functions
+### Template utility functions
 
 The following utility functions can be used anywhere inside template `{{expression}}` placeholders:
 
@@ -99,6 +99,65 @@ The following utility functions can be used anywhere inside template `{{expressi
 - Make a string safe by escaping HTML characters: `{{safeString(Product.name)}}`
 - Given an array of objects, extract the values from the specified field and join them together into a single comma-separated string: `{{joinFields(Product, 'name')}}`
 
+### General utility functions
+
+The following utility functions are available for advanced use cases and can be imported from the `saasufy-components` module:
+
+**Import from CDN:**
+```javascript
+import {
+  getRecordIds,
+  getRecord,
+  getRecordCount,
+  generateRecords,
+  getRecords,
+  logAttributeChanges,
+  wait
+} from 'https://saasufy.com/node_modules/saasufy-components/utils.js';
+```
+
+**Import from npm:**
+```javascript
+import {
+  getRecordIds,
+  getRecord,
+  getRecordCount,
+  generateRecords,
+  getRecords,
+  logAttributeChanges,
+  wait
+} from 'saasufy-components/utils.js';
+```
+
+**Available functions:**
+
+- `getRecordIds({ socket, type, viewName, viewParams, startPage, maxPages, pageSize })`: Retrieves record IDs from a collection view across multiple pages. Returns an array of IDs.
+- `getRecord({ socket, type, id, fields })`: Fetches a single record by ID. If fields are specified, only those fields are retrieved; otherwise the entire record is returned.
+- `getRecordCount({ socket, type, viewName, viewParams, offset })`: Gets the total count of records in a view. Returns a number representing the count.
+- `generateRecords({ socket, type, viewName, viewParams, fields, startPage, pageSize, maxAttempts })`: An async generator function that yields records one by one from a collection view. Useful for processing large datasets efficiently.
+
+**Example usage:**
+```javascript
+// Process all products one by one without loading them all into memory at once
+const productGenerator = generateRecords({
+  socket: mySocket,
+  type: 'Product',
+  viewName: 'alphabeticalView',
+  viewParams: { category: 'electronics' },
+  fields: [ 'name', 'price', 'qty' ],
+  pageSize: 50
+});
+
+for await (let product of productGenerator) {
+  console.log(`Processing product: ${product.name}`);
+  // Process each product individually
+}
+```
+- `getRecords({ socket, type, viewName, viewParams, fields, startPage, maxPages, pageSize })`: Retrieves multiple records from a collection view. Returns an array of record objects.
+- `logAttributeChanges(...elementSelectors)`: Logs attribute changes for DOM elements to the console. Useful for debugging. Returns a function to stop observing.
+- `wait(duration)`: Creates a promise that resolves after the specified duration in milliseconds. Useful for adding delays in async operations.
+
+
 ### Special fields
 
 Saasufy supports a number of special metadata fields which are automatically created and updated on each model record.
@@ -120,6 +179,17 @@ You will need to deploy your Saasufy service from the dashboard for the changes
 The `id` field in Saasufy is extra special; you can optionally specify it when you create a new resource, however, if it is not specified, Saasufy will create one for you.
 Saasufy offers utility functions for creating IDs (random and deterministic). See the previous `Utility functions` section.
 
+### Events
+
+The Saasufy `collection-viewer` component dispatches the following events when records are created, updated or removed from an active collection as a result of user interactions with that component:
+
+- `collectionCreate`
+- `collectionUpdate`
+- `collectionDelete`
+
+These events are set to bubble so you can listen to them on any parent element in the DOM.
+The event object passed to the listener function has a `detail` property which is an object with a `type` and `id` property to indicate the type and id of the affected resource within the collection.
+
 ### File hosting
 
 Saasufy provides basic HTTP/HTTPS file hosting functionality with support for client-side caching (with `ETag`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "saasufy-components",
-  "version": "8.3.1",
+  "version": "8.4.0",
   "description": "Components for Saasufy.",
   "main": "index.js",
   "scripts": {

package/utils.js

@@ -510,6 +510,134 @@ export function formatError(error) {
   return error.code === 1009 ? 'Resource exceeded the maximum size' : error.message;
 }
 
+export function getBatches(list, batchSize) {
+  let batches = [];
+  let currentBatch = [];
+  for (let item of list) {
+    if (currentBatch.length >= batchSize) {
+      batches.push(currentBatch);
+      currentBatch = [];
+    }
+    currentBatch.push(item);
+  }
+  if (currentBatch.length) {
+    batches.push(currentBatch);
+  }
+  return batches;
+}
+
+export async function getRecordIds({ socket, type, viewName, viewParams, startPage, maxPages, pageSize }) {
+  if (startPage == null) startPage = 0;
+  if (maxPages == null) maxPages = 10;
+  if (pageSize == null) pageSize = 100;
+  let currentPage = startPage;
+  let lastPage = currentPage + maxPages;
+  let isLastPage = false;
+  let modelIds = [];
+  while (!isLastPage && currentPage < lastPage) {
+    let result = await socket.invoke('crud', {
+      action: 'read',
+      type,
+      offset: currentPage * pageSize,
+      view: viewName,
+      viewParams,
+      pageSize
+    });
+    isLastPage = result.isLastPage;
+    modelIds.push(...result.data);
+    currentPage++;
+  }
+  return modelIds;
+}
+
+export async function getRecord({ socket, type, id, fields }) {
+  if (!fields) {
+    return socket.invoke('crud', {
+      action: 'read',
+      type,
+      id
+    });
+  }
+  let data = await Promise.all(
+    fields.map(async (field) => {
+      return socket.invoke('crud', {
+        action: 'read',
+        type,
+        id,
+        field
+      });
+    })
+  );
+  let fieldCount = fields.length;
+  let record = {};
+  for (let i = 0; i < fieldCount; i++) {
+    record[fields[i]] = data[i];
+  }
+  return record;
+}
+
+export async function getRecordCount({ socket, type, viewName, viewParams, offset }) {
+  let result = await socket.invoke('crud', {
+    action: 'read',
+    type,
+    offset: offset || 0,
+    view: viewName,
+    viewParams,
+    pageSize: 0,
+    getCount: true
+  });
+  return Math.max(result.count - offset, 0);
+}
+
+export async function* generateRecords({ socket, type, viewName, viewParams, fields, startPage, pageSize, maxAttempts }) {
+  if (startPage == null) startPage = 0;
+  if (pageSize == null) pageSize = 100;
+  if (maxAttempts == null) maxAttempts = 10;
+  
+  let currentPage = startPage;
+  let isLastPage = false;
+  let failureCount = 0;
+
+  while (!isLastPage) {
+    try {
+      let result = await socket.invoke('crud', {
+        action: 'read',
+        type,
+        offset: currentPage * pageSize,
+        view: viewName,
+        viewParams,
+        pageSize
+      });
+      let idList = result.data || [];
+      for (let id of idList) {
+        yield await getRecord({ socket, type, id, fields });
+      }
+      isLastPage = result.isLastPage;
+      currentPage++;
+      failureCount = 0;
+    } catch (error) {
+      if (++failureCount > maxAttempts) {
+        throw new Error(`Record generation failed after max consecutive attempts because of error: ${error.message}`);
+      }
+    }
+  }
+}
+
+export async function getRecords({ socket, type, viewName, viewParams, fields, startPage, maxPages, pageSize }) {
+  let recordIds = await getRecordIds({ socket, type, viewName, viewParams, startPage, maxPages, pageSize });
+  let recordIdBatches = getBatches(recordIds, pageSize);
+  let records = [];
+  for (let idBatch of recordIdBatches) {
+    let recordBatch = await Promise.all(
+      idBatch.map(async (id) => {
+        return getRecord({ socket, type, id, fields });
+      })
+    );
+    records.push(...recordBatch);
+  }
+  return records;
+}
+
 export function logAttributeChanges(...elementSelectors) {
   let domObserverCallback = (mutationList) => {
     for (let mutation of mutationList) {
@@ -544,4 +672,4 @@ export function logAttributeChanges(...elementSelectors) {
 
 export function wait(duration) {
   return new Promise((resolve) => setTimeout(resolve, duration));
-}
+}