saasufy-components 8.3.1 → 8.4.1

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/WEBSOCKET_API.md

@@ -0,0 +1,181 @@
+# WebSocket API
+
+## Overview
+
+Saasufy exposes a powerful WebSocket API which allows you to integrate with your Saasufy service in complex ways; it supports CRUD operations and subscriptions for data changes. This API can be used to build custom components which interact with Saasufy data or to integrate with third-party services.
+
+The Saasufy WebSocket CRUD API and Subscribe API are implemented on top of the SocketCluster protocol.
+It is recommended to use the `socketcluster-client` library: http://npmjs.org/socketcluster-client
+
+You can connect a SocketCluster client socket to your Saasufy service like this:
+```js
+// The the script URL/path may differ depending on your setup
+import {
+  create as createSocket
+} from 'https://saasufy.com/node_modules/socketcluster-client/socketcluster-client.min.js';
+
+// Change the path with that of your own service
+let clientSocket = createSocket({
+  hostname: 'saasufy.com',
+  port: 443,
+  secure: true,
+  path: '/sid8001/socketcluster/'
+});
+```
+
+## CRUD API
+
+All CRUD operations can be invoked on a client socket like this:
+
+```js
+await clientSocket.invoke('crud', queryObject);
+```
+
+The format of the `queryObject` for various operations is shown below.
+
+### Read collection view
+```json
+{
+    "action": "read",
+    "type": "Product",
+    "offset": 0,
+    "view": "categoryView",
+    "viewParams": {
+        "categoryName": "Electronics"
+    },
+    "pageSize": 10
+}
+```
+This API returns a response object with `data` and `isLastPage` properties. The `data` property holds an array of IDs - The recommended approach is to load the list of IDs and then fetch individual properties on demand. The Saasufy service uses lightweight WebSocket frames and caches resources on the back end so it's acceptable to make a relatively large number of requests for individual fields.
+
+If `getCount` is true, the operation will return the total number of records which exist in the specified view via a `count` property. Note that this can become computationally expensive if the view has a large number of records.
+
+### Create model instance
+```json
+{
+    "action": "create",
+    "type": "Product",
+    "value": {
+        "name": "Pixel 7",
+        "brand": "Google",
+        "categoryName": "Electronics"
+    }
+}
+```
+An optional `id` field can be specified as part of the `value` object. If it is not specified, then the `id` will be created automatically by Saasufy.
+
+### Update model instance
+```json
+{
+    "action": "update",
+    "type": "Product",
+    "id": "2201ec45-1c7c-4a5f-8432-1015b7fc4b92",
+    "value": {
+        "name": "Pixel 7"
+    }
+}
+```
+By default, for efficiency reasons, change notifications related to a specific CRUD action are not sent to the socket which initiated the action. In order to receive such notifications, you should add a top level `publisherId` property to the object. It should be a string of length between 1 and 50 characters. The `publisherId` will be sent to the origin client socket alongside the change notification. It can be used to identify where the action originated.
+
+### Delete model instance
+```json
+{
+    "action": "delete",
+    "type": "Product",
+    "id": "2201ec45-1c7c-4a5f-8432-1015b7fc4b92"
+}
+```
+In order to receive change notifications back from the client socket which initiated an action, you should add a top level `publisherId` property to the object above. It should be a string of length between 1 and 50 characters. The `publisherId` will be sent to the origin client socket alongside the change notification.
+
+### Read model field
+```json
+{
+    "action": "read",
+    "type": "Product",
+    "id": "2201ec45-1c7c-4a5f-8432-1015b7fc4b92",
+    "field": "name"
+}
+```
+The `field` property can be omitted to read the entire resource object with all available fields.
+
+### Update model field
+```json
+{
+    "action": "update",
+    "type": "Product",
+    "id": "2201ec45-1c7c-4a5f-8432-1015b7fc4b92",
+    "field": "name",
+    "value": "Pixel 7"
+}
+```
+In order to receive change notifications back from the client socket which initiated an action, you should add a top level `publisherId` property to the object above. It should be a string of length between 1 and 50 characters. The `publisherId` will be sent to the origin client socket alongside the change notification.
+
+### Update multiple model fields
+```json
+{
+    "action": "update",
+    "type": "Product",
+    "id": "2201ec45-1c7c-4a5f-8432-1015b7fc4b92",
+    "value": {
+      "name": "Pixel 7",
+      "qty": 3
+    }
+}
+```
+
+### Delete model field
+```json
+{
+    "action": "delete",
+    "type": "Product",
+    "id": "2201ec45-1c7c-4a5f-8432-1015b7fc4b92",
+    "field": "qty"
+}
+```
+
+## Subscribe API
+
+All subscribe operations can be invoked on a client socket like this:
+
+```js
+let channel = clientSocket.subscribe(channelName);
+```
+
+Changes can be consumed like this:
+
+```js
+for await (let data of channel) {
+  // data represents the change object.
+}
+```
+
+### View changes
+
+The format of the `channelName` is this:
+
+```js
+`crud>${viewName}(${viewPrimaryParamsString}):${modelType}`
+```
+
+For example, to subscribe to changes to the `categoryView` of the `Product` collection, with the view params `{ categoryName: 'Electronics' }`, the `channelName` to use would be:
+
+```js
+'crud>categoryView({"categoryName":"Electronics"}):Product'
+```
+
+If there are multiple view params, they must be specified in alphabetical order based on the property name.
+
+### Field changes
+
+The format of the `channelName` is this:
+
+```js
+`crud>${modelType}/${modelId}/${modelField}`
+```
+
+For example, to subscribe to changes to the `name` field of a `Product` with ID `a3647d32-1aa2-4332-b8bb-8f3c84648cfa`, the `channelName` to use would be:
+
+```js
+'crud>Product/a3647d32-1aa2-4332-b8bb-8f3c84648cfa/name'
+```
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "saasufy-components",
-  "version": "8.3.1",
+  "version": "8.4.1",
   "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));
-}
+}