@olenbetong/data-object

ES6+ implementation of af.DataObject and af.Procedure

Usage no npm install needed!

<script type="module">
  import olenbetongDataObject from 'https://cdn.skypack.dev/@olenbetong/data-object';
</script>

README

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.

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
  • getEventHandler (eventHandler field on DataObject is public)
  • getSystemFieldNames
  • getGroupBy / setGroupBy
  • hasIITrig
  • hasIUTrig
  • hasIDTrig
  • saveToLocal
  • saveToIndexedDB
  • setErrorHandler

Async

Functions that takes callbacks are now simple wrappers around equivalent async functions. The async functions are preferred over functions with callbacks, and the callback functions might be deprecated/removed in the future. The async versions do not use the errorHandler, but will isntead throw errors.

As of version 0.8, both the non-async methods have been made async. Both versions will throw exceptions on failure, but the methods ending with Async will not use the data objects' error handler first.

Async methods in DataObject:

  • deleteCurrentRowAsync
  • deleteRowAsync
  • endEditAsync
  • getAllPrimKeysAsync (compat version only)
  • refreshCurrentRowAsync
  • refreshDataSourceAsync
  • refreshRowAsync
  • retrievePartialAsync
  • saveAsync

Async methods in DataHandler:

  • createAsync
  • destroyAsync
  • retrieveAsync
  • updateAsync

Async methods in Procedure

  • executeAsync
  • execute2Async

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

  • 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/common 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

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/data-object";

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. This needs to be done before anything that uses the default client is initialized.

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

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

setDefaultClient(devClient);