npm package: @olenbetong/appframe-data
Description: Implementation of Appframe data objects and procedures for modern browsers
Author: Bjørnar Vister Hansen
Latest version: 1.4.1

# 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:

```sh
pnpm test:node
```

Run browser tests:

```sh
pnpm test:browser
```

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

```sh
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 `after`string 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:

```html
<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:

```js
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.

```js
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.

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

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

setDefaultClient(devClient);
```