Appframe Data for modern browsers and Node.js

An implementation of afDataObject using modern browser APIs and syntax. The bundle also includes the Api, DataProviderHandler, MemoryStorage and Procedure classes.

Testing

Run Node.js tests:

pnpm test:node

Run browser tests:

pnpm test:browser

Add --headed to run browser tests with a visible browser window:

pnpm test:browser -- --headed

API changes

This project provides 2 versions of the data object. One version that should have the same API as afDataObject (but might not be compatible), and one slightly more lightweight version.

The light version removes some of the less used methods:

• getAllPrimKeys
• getAllRows
• getByID
• getDataHandler (dataHandler field on DataObject is public)
• getDataSourceArticleID (options field on DataObject is public)
• getDirtyData
• getMaxRecords
• getEventHandler (eventHandler field on DataObject is public)
• getSystemFieldNames
• getGroupBy / setGroupBy
• hasIITrig
• hasIUTrig
• hasIDTrig
• saveToLocal
• saveToIndexedDB
• setFieldFormat

The following methods have been removed from both versions:

• beginEdit
• isEditing
• isStrict
• setErrorHandler

Other differences

• These properties are public on the data object:
  • Options (dataObject.options)
  • Data handler (dataObject.dataHandler)
  • Event handler (dataObject.eventHandler)
  • storageEngine (dataObject.storageEngine)
  • masterDataObject (dataObject.masterDataObject)

Breaking changes

• Strict mode has been removed (not enabled by Appframe in static scripts anyway)
• All callback parameters have been removed. Instead they return promises that you can await, and will throw errors.
• errorHandler is no longer a method or option. Instead you should subscribe to error events
• XML fields not supported. Will be handled as strings
• save, setCurrentIndex and endEdit no longer support running synchronously by passing a synchronous boolean parameter. setCurrentIndex still supports a second boolean parameter, but this will not cause it to run synchronously, but will return a promise if it is set to true.
• The argument passed in onParameterUpdated changed from an object with the parameter name as the key, to an object with this shape: { name: 'parameterName', value: 'parameterValue' }

Event handler changes

To reduce dependency size, the EventHandler class from @olenbetong/appframe-core has been replaced with mitt. Events emitted are CustomEvent instances, and instead of returning false to abort an event, we have to call event.preventDefault() instead. The arguments for the event are now found in event.detail.

Another consequence of using mitt is that all event handlers will be called even if one of them calls event.preventDefault(). This shouldn't be a problem, since relying on the event handler to stop executing is unsafe, because you don't know if a handler after yours will abort the event.

The Paging component used another EvenHandler type, but this has also been replaced with mitt. This means you no longer have an on, before or afterstring as the first argument to attach and detach. To replace the after events for abortable events, afterPageRefresh and afterPageChange have been added.

Browser support

The data object is only tested in modern browsers (Chromium, Firefox and Safari). A legacy bundle with IE11 target is created, but no longer tested.

The following APIs need to be polyfilled in order to use this project with older browsers:

• fetch + AbortController
• Promise
• Array.prototype.includes
• Object.assign
• Object.values
• String.prototype.includes

polyfill.io

https://polyfill.io/v3/polyfill.min.js?flags=gated&rum=true&features=fetch%2CAbortController%2Cdefault%2CArray.prototype.includes%2CObject.values

Preloading data from server scripts

Data for one or more data objects can be embedded directly in the HTML before the client script runs. Expose the data on af.article.preloadedData using a standard <script> tag:

<script>
  window.af = window.af || {};
  af.article = af.article || {};
  af.article.preloadedData = {
    dsExample: [
      { id: 1, name: "Alice" },
      { id: 2, name: "Bob" }
    ]
  };
</script>

When a DataObject is created with dataSourceId: "dsExample", it picks up these rows automatically and skips the initial network request.

If the preloaded rows should not remain available after the data has been consumed, remove them:

delete af.article.preloadedData.dsExample;
// or clear all preloaded data
af.article.preloadedData = {};

Client class for cross-domain support

There is a new Client class that can be used to access data objects and procedures on other origins (assuming CORS has been set up correctly). Data handlers and procedures take a client option that can be set to override the default client (current origin).

If the user is not already authenticated on the origin, you need to run the login method.

import { Client, ProcedureAPI } from "@olenbetong/appframe-data";

const devClient = new Client("dev.example.com");
await devClient.login("admin", "1234");

const procSomething = new ProcedureAPI({ procedureId: "astp_Namespace_ProcedureName", client: devClient });

NB! When running in a Node.js environment, no default client is set. You can set it using the setDefaultClient export. If any operation that performs network requests is executed before the default client is set, an exception will be thrown.

import { Client, setDefaultClient } from "@olenbetong/appframe-data";

const devClient = new Client("dev.example.com");
await devClient.login("admin", "1234");

setDefaultClient(devClient);