# @unicef-polymer/etools-dexie-caching

> Handles IndexedDb caching

Latest version **1.1.0** (published 2022-09-30) · BSD-3-Clause license · 0 weekly downloads

## Install

```sh
npm install @unicef-polymer/etools-dexie-caching
pnpm add @unicef-polymer/etools-dexie-caching
yarn add @unicef-polymer/etools-dexie-caching
bun add @unicef-polymer/etools-dexie-caching
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.0 |
| Published | 2022-09-30 |
| First published | 2019-11-27 |
| Weekly downloads | 0 |
| License | BSD-3-Clause |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 28.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Maintainers | insightfeatures, adriana.trif, adrian-hangan, dci_npm, andrei.laza |

## Links

- npm: https://www.npmjs.com/package/@unicef-polymer/etools-dexie-caching
- Repository: https://github.com/unicef-polymer/etools-dexie-caching
- Homepage: https://github.com/unicef-polymer/etools-dexie-caching#readme
- Issues: https://github.com/unicef-polymer/etools-dexie-caching/issues
- npm.io page: https://npm.io/package/@unicef-polymer/etools-dexie-caching

## Dependencies (2)

- [dexie](https://npm.io/package/dexie.md) ^3.2.2
- [@unicef-polymer/etools-behaviors](https://npm.io/package/@unicef-polymer/etools-behaviors.md) ^3.1.1

## Recent versions

- 1.1.0 (latest) — 2022-09-30
- 1.1.0-rc.1 — 2022-09-29
- 1.0.4 — 2022-08-23
- 1.0.3 — 2022-06-02
- 1.0.2 — 2020-06-16
- 1.0.1 — 2020-06-15
- 1.0.0 — 2020-04-21
- 1.0.0-rc.6 — 2020-01-13
- 1.0.0-rc.2 — 2019-11-27
- 1.0.0-rc.1 — 2019-11-27

## README

# \<etools-dexie-caching\>

* Handles caching in IndexedDb.
* To use you have to define your Dexie db(s) and endpoints in your app.
* Ability to cache in your app's specific db: `window.EtoolsRequestCacheDb`
* Ability to cache in a db that is shared between etools apps and holds the data that is common to all these apps: `window.EtoolsSharedDb`.

## Data caching requirement

Example of defining the `window.EtoolsRequestCacheDb`:

```javascript
  var appDexieDb = new Dexie('[insert name]');
  appDexieDb.version(1).stores({
    countries: "id, name"
    listsExpireMapTable: "&name, expire",
    ajaxDefaultDataTable: "&cacheKey, data, expire"
  });

  window.EtoolsRequestCacheDb = appDexieDb;
```

Example of defining the `window.EtoolsSharedDb`:
```javascript
  var sharedDexieDb = new Dexie('EtoolsSharedDb');
  sharedDexieDb.version(1).stores({
    collections: "&cacheKey, data, expire"
  });

  window.EtoolsSharedDb = sharedDexieDb;
```


In your app you will configure your cacheable endpoints:
```javascript
const endpoints = {
  {
    url: 'your/api/route',
    exp: 300000, // if exp = 0 no caching will be made
    cachingKey: 'stringIdentifier'
  },
   {
    url: 'your/api/route',
    exp: 300000, // if exp is missing no caching will be made
    sharedDbCachingKey: 'stringIdentifier'
  },
   {
    url: 'your/api/route',
    exp: 300000, // milliseconds expected
    cacheTableName: 'stringIdentifier'
  }
};
```

To mark an endpoint as cacheable you have to set the `exp` property and one of `cachingKey`, `cacheTableName` or `sharedDbCachingKey`. If just `exp` property is provided, `cachingKey` will automatically be set to the url of the endpoint.

 Set the `cachingKey` property if you want to cache the endpoint response in the default table `ajaxDefaultDataTable` and 'cachingKey' will be the row identifier used to retrieve the data.
The cached data will have the following format:
```javascript
{
  // cacheKey can have request params stringified in the end if params were provided in sendRequest options
  cacheKey: '[provided cachingKey value]',
  // Date.now() + endpoint.exp
  expire: 1491306589975,
  // request response data
  data: [endpoint response]
}
```
Set the `cacheTableName` property if you do not want to cache in the `ajaxDefaultDataTable` table, but in a separate table with the provided name.
This is recommended if you need to do queries on this table later, like showing a list with pagination and filtering only on frontend side.
The expiration of the data in these tables is stored in the `listsExpireMapTable` table, under the following format, with `name` column being the row identifier:
```javascript
{
  name: '[provided cacheTableName value]',
  // Date.now() + endpoint.exp
  expire: 1491306589975
}
```

Set the  `sharedDbCachingKey` if you want to cache the data in the EtoolsSharedDb, in the default table called `collections` and 'sharedDbCachingKey' will be the row identifier used to retrieve the data.


For info about Dexie.js databases check the [documentation](http://dexie.org/).

### Disable caching

Just set this in your app: `window.EtoolsRequestCacheDisabled = true`


## Install

```bash
$ npm i --save @unicef-polymer/etools-dexie-caching
```

## Usage example
```javascript
if (requestIsCacheable(method, endpoint)) {
    return getFromCache(endpoint)
      .catch(() => { // Data not found in cache or is expired
        return `do http request...`
          .then(response => cacheEndpointResponse(response, endpoint));
      });
  }

  return `do http request...`; // When request is not cacheable, just do the http request
```

## Demo

```
See etools-ajax component (https://github.com/unicef-polymer/etools-ajax) for an example.
```

---
_Source: https://npm.io/package/@unicef-polymer/etools-dexie-caching · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._